VAPA & The Five SPEC Layers

grace beginner 5 min read

ELI5

GRACE is a building code for AI prompts. Five chapters cover what a prompt looks like, how to seal it tamper-proof, how prompts depend on each other, how humans approve risky changes, and how every run is logged. STRATT is the contractor that actually builds to that code.

Technical Deep Dive

GRACE defines Verifiable Agentic Prompt Architecture (VAPA): prompts as typed, fingerprinted, dependency-tracked, gate-checked, trace-audited units. STRATT is the reference implementation.

The Five Layers

SPEC	Concern	Reference Package
SPEC-01	Typed contracts, 5 unit types, 9-state lifecycle	`@stratt/schema`
SPEC-02	Blake3 canonical fingerprint + tamper detection	`@stratt/fingerprint`
SPEC-03	Import DAG, blast radius, cross-namespace resolution	`@stratt/graph`
SPEC-04	Hard-sync gate checkpoints (APPROVED/REJECTED/TIMEOUT/ESCALATED)	`@stratt/graph` + `@stratt/cli` + `councils/`
SPEC-05	Execution traces, quality scoring, regression detection	`@stratt/cli` (Block I)

Concern Routing

flowchart LR
    A[New requirement] --> B{Concern?}
    B -->|Output shape / type| C[SPEC-01<br/>schema]
    B -->|Tamper proofing| D[SPEC-02<br/>fingerprint]
    B -->|Import / blast radius| E[SPEC-03<br/>graph]
    B -->|Human approval| F[SPEC-04<br/>graph + cli]
    B -->|Audit / quality| G[SPEC-05<br/>cli]
    C --> H[Zod validator + contract.ts]
    D --> I[5-stage canonicalise → Blake3]
    E --> J[Kahn DAG + ChocoBridgeResolver]
    F --> K[Gate authority agent]
    G --> L[trace.yaml + Veritas gate]

Cross-Spec Bridges

FM-06 bridges SPEC-01 (contracts) ↔ versioning.
FM-07 bridges SPEC-01 (lifecycle) ↔ SPEC-03 (imports).
Gate-required lifecycle transitions bridge SPEC-01 ↔ SPEC-04.

Key Terms

VAPA → Verifiable Agentic Prompt Architecture; the category GRACE defines.
STRATT → Reference implementation of GRACE across packages L0–L5.
SPEC layer → One of five mandatory specifications, each owning a distinct concern.

Q&A

Q: Which SPEC owns the rule that publishing the same version with different content is forbidden? A: SPEC-02. Identical version with different content produces a different Blake3 digest, breaking the composition fingerprint of every dependent chain.

Q: Where does FM-04 (protected agent missing) live in the SPEC layout? A: SPEC-04. It is enforced by packages/graph/src/protect.ts against council configs in councils/{name}/council.yaml.

Q: Why is SPEC-05 the most recently implemented? A: It depends on every other spec (it audits chain executions, which reference units, fingerprints, imports, and gate resolutions). Block I delivered trace.ts, regression.ts, and veritas.ts.

Examples

A change request “remove the target_branch input from the boot-review task” routes:

SPEC-01: contract change classification → breaking → major bump.
SPEC-02: new fingerprint required.
SPEC-03: blast radius enumerates all chains importing boot-review.
SPEC-04: approval-gated transition (active→deprecated for the old version).
SPEC-05: regression check after publish — if quality score drops > 0.05, Veritas fires.

neighbors on the map

Layer Architecture L0–L6 deciding which package a new feature belongs in
Nine Councils & Agent Roster routing a chain to the right gate authority
IRIS Ecosystem Overview explaining IRIS to a new teammate