Pactia specification

The intent language for the AI era

You write what must stay true. AI writes how it works.

Pactia is an AI-native intent language — compiled by pactiac to AI-neutral JSON IR; BSC renders for any model or coding platform. Packages publish as git repos with semver tags (Go-style); official libraries live on GitHub (kernel, pactia-io).

Current version: 1.2
Status: Specification

---

The intent line

┌─────────────────────────────────────────────┐
│  ABOVE THE LINE — Intent                    │
│  Entities · APIs · Roles · Policy · Stack   │
│  Prose · Tags · Packages · Provenance       │
└─────────────────────────────────────────────┘
────────────── conformance gate ───────────────
┌─────────────────────────────────────────────┐
│  BELOW THE LINE — Implementation            │
│  Logic · indexes · edge cases · tuning      │
│  Owned by AI and engineers. Free.           │
└─────────────────────────────────────────────┘

Above the line: what every session must inherit — regardless of model, engineer, or sprint.
Below the line: how it works today. Pactia never owns it.

See overview.md for philosophy, three altitudes, and architecture coverage.

---

Hello world (altitude 0)

pactia 1.0

product MyApp {
  > A mobile app for tracking personal fitness goals and sharing progress with friends.
  > Never commit secrets. Map errors to our envelope before returning.
  > List endpoints use cursor pagination.
}

No tags. No module. At least one > line should describe the product. See overview.md — three altitudes.

---

See it

Fleet management in Pactia 1.0 — mostly prose, with tags only where structure matters (56 lines):

Almost pure prose — same product, @stack only, no model or API tags (37 lines):

Relay fixture (1.2 canonical) · Language spec

Legacy fleet mini/prose/full fixtures were removed from this repo; see pactiac test/fixtures for 1.2 copies.

---

Documents

Full index: docs/README.md

Document	Role
overview.md	Philosophy, three altitudes, intent line
language-spec.md	Language only — grammar, def, blocks
macros.md	Unified def for tags and macros
grammar-reference.md	BNF and implementer error codes
registry.md	Symbol resolution mechanics
packages.md	Packages, pactia.toml, publish
platform.md	Stack packages
compilation.md	Compiler pipeline, JSON IR
editor-support.md	VS Code / Cursor highlighting
schemas/	JSON Schema — pactia.toml, pactia.lock only

Tooling

Pactia spec	Language declaration	pactiac	pactia
1.2	pactia 1.0 on the version line	>=0.3.0	>=0.3.0

Spec 1.2 documents syntax and IR for products that declare pactia 1.0 in source. Highlights: package constants (export def name = value), CONSTANT_DEF_REQUIRED diagnostic, context keyword, import + attach workspace assembly.

The stack

*.pactia  ──pactiac──▶  workspace.json + slice IR  ──▶  agent context + specifications
              ▲
         pactia — vendor git deps, lockfile, build

	Repo	Role
Language	spec (this repo)	Pactia 1.2 — grammar, JSON IR, packages
Compiler	pactiac	Deterministic compile to module-scoped IR
Package manager	pactia	pactia init, add, install, update, build
Kernel packages	kernel	@pactia/kernel, @pactia/kernel-*
Stack / surface	pactia-io	Platform packages
Editor	vscode-pactia	Syntax, tags, diagnostics
Examples	examples	Canonical workspaces

Model-agnostic by design. Switch Cursor, Claude Code, or Copilot — your .pactia files and lockfile stay the same.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.