Protocol Layers

The GRACE Protocol is organized into five specification layers, each addressing a distinct category of problems in agentic prompt architecture. These layers are implemented in STRATT packages and stacked vertically with strict dependency rules: lower layers have zero knowledge of higher layers.

The Five Layers

SPEC-01: Prompt Contract Specification

Problem: Silent contract drift — units change their output shapes without detection, causing downstream cascades of failures.

Defines:

• Five unit types: role, rule, task, chain, supply
• Typed contracts: Input/output contracts with declared types (string, integer, float, boolean, document, array, object)
• Failure modes: Four strategies per unit (gate, retry, abort, fallback)
• Change classification: Breaking (major version bump), additive (minor), patch (bug fix only)
• CI enforcement: Automatic version bump validation — if you change a contract, CI rejects it unless the version number reflects the breaking change

Implemented in:

Component	Package	Path
Unit type validators	@stratt/schema	packages/schema/src/types/
Contract schema	@stratt/schema	packages/schema/src/types/contract.ts
Change classification	@stratt/cli	packages/cli/src/commands/diff.ts
CI enforcement (FM-06)	@stratt/graph	packages/graph/src/protect.ts

Example contract:

unit:
  type: task
  inputs:
    - name: document
      type: document
      required: true
    - name: style_guide
      type: document
      required: false
  outputs:
    - name: formatted_document
      type: document
    - name: confidence
      type: float
  failure_modes:
    - gate: EDITOR-04  # block until human approval
    - retry: 3         # retry up to 3 times
    - fallback: null   # no fallback; fail hard

SPEC-02: Blake3 Fingerprint & Tamper Detection

Problem: No way to verify that the prompt executing in production is the one that was authored, reviewed, and approved. A unit could be silently modified after publishing.

Defines:

• Canonical serialization: A 5-stage pipeline that normalizes YAML into a deterministic byte sequence
• Blake3 hashing: Hash the canonical sequence → 64-character hex digest
• Fingerprint format: blake3:{64 hex chars} (lowercase)
• Four verification states: unpublished, verified, drift (changed locally), tampered (changed in registry)
• Chain fingerprints as Merkle trees: A chain’s fingerprint is the root hash of all its steps’ fingerprints
• Atomic publishing: Fingerprint is committed to the registry; if the R2 write fails, the entire publish is rolled back

Implemented in:

Component	Package	Path
Canonical serialization	@stratt/fingerprint	packages/fingerprint/src/canonicalise.ts
Blake3 hashing	@stratt/fingerprint	packages/fingerprint/src/hash.ts
Verification	@stratt/fingerprint	packages/fingerprint/src/verify.ts
14 test vectors	@stratt/fingerprint	packages/fingerprint/tests/vectors.ts
CI check (FM-01)	@stratt/graph	packages/graph/src/ci.ts
SPUH binary encoding	@stratt/schema	packages/schema/src/spuh.ts

Critical constraint: The blake3-wasm library is pinned to version 2.1.5 exactly. Version 3.0.0 introduced an async API break and is incompatible.

Failure mode FM-01: Fingerprint tamper detected (Blake3 digest mismatch).

SPEC-03: Dependency Graph Specification

Problem: Modifying a core unit without knowing it’s imported by dozens of other units causes cascade failures across the ecosystem.

Defines:

• DAG (Directed Acyclic Graph) model: Every unit imports explicitly; no implicit references
• Cycle detection (Kahn’s algorithm): The graph must be acyclic; any import cycle is rejected immediately
• Blast radius computation: When you modify a unit, the system computes which other units (transitively) depend on it
• Domain isolation: Cross-domain imports are only allowed via core/ and shared/ domains
• Protected unit enforcement: Certain units cannot be changed without a version bump or gate approval

Implemented in:

Component	Package	Path
DAG construction	@stratt/graph	packages/graph/src/dag.ts
Blast radius computation	@stratt/graph	packages/graph/src/blast.ts
Import resolution	@stratt/graph	packages/graph/src/resolve.ts
Cycle detection (FM-03)	@stratt/graph	packages/graph/src/dag.ts
Domain isolation (FM-07)	@stratt/graph	packages/graph/src/protect.ts
Cross-namespace resolution	@stratt/graph	packages/graph/src/namespace.ts
Choco bridge resolver	@stratt/graph	packages/graph/src/choco-resolver.ts

Failure modes:

• FM-03: Circular dependency detected (import cycle)
• FM-07: Draft isolation failure (stable unit importing a draft unit)

SPEC-04: Gate Checkpoint Protocol

Problem: Autonomous chains producing plausible-looking output that is subtly wrong, with no detection mechanism. A chain executes 100% autonomously and produces garbage — detected only after it breaks downstream systems.

Defines:

• Hard synchronization primitives: Chain halts completely; human must approve before continuing
• Four terminal states:
  • APPROVED — human approves, chain continues
  • REJECTED — human rejects, chain fails (no fallback)
  • TIMEOUT (24h default) — if no human response in 24 hours, escalate to superior council
  • ESCALATED — routed to higher authority
• Gate authority agents (one per council): LEWIS-06 (Pathfinder), RETRO-04 (Hermes), EDITOR-04 (Athena), etc.
• Protected agents (cannot be bypassed): BECK-02, EECOM-02, CURATOR-02, and others
• Audit records: Every gate resolution is logged with timestamp, approver, reason, and affected unit
• Veritas gate (for DSPy-optimized unit promotion): Automatic gate that triggers when regression score exceeds threshold

Implemented in:

Component	Package	Path
Gate approval workflow	@stratt/cli	packages/cli/src/commands/gate.ts
Protected agent checks (FM-04)	@stratt/graph	packages/graph/src/protect.ts
Gate removal detection (FM-05)	@stratt/graph	packages/graph/src/protect.ts
Council configurations	—	councils/{pathfinder,hermes,athena}/council.yaml

Failure modes:

• FM-04: Protected agent missing (chain lacks required protected agent for domain)
• FM-05: Gate removal (gate step removed without major version bump)

Example gate in a chain:

steps:
  - name: draft-proposal
    unit: stratt://docs/task/draft-proposal@1.0.0
  - name: human-review-gate
    unit: stratt://core/gate/editorial-review@1.0.0
    config:
      authority: EDITOR-04
      timeout_hours: 24
      escalate_to: CURATOR-02
  - name: publish
    unit: stratt://docs/task/publish@1.0.0

SPEC-05: Execution Trace & Audit Specification

Problem: No way to answer which units improved, which degraded, which gates fired most often — after months of running chains in production.

Defines:

• Mandatory trace creation: Every chain execution produces a structured trace (no opt-out)
• Chain-level trace fields:
  • trace_id, chain_address, version, fingerprint
  • session_id, created_at, completed_at, status
  • quality_score, token_count_in, token_count_out
• Step-level trace entries:
  • Unit address, agent assignment, input prompts, responses
  • Token counts per step, status transitions
  • Timing information (queued, started, completed)
• Pluggable quality scorer:
  • Heuristic default: conformance + completeness + token efficiency
  • Custom scorers can be registered
• DSPy JSONL export:
  • Export filtered traces for DSPy fine-tuning
  • Filtering: min score, date range, version range
• Automated regression detection:
  • Quality score delta ≥ 0.05 triggers Veritas gate
  • Veritas evaluates units against last 3 successful runs

Implementation status: Implemented in Block I. Core components in @stratt/cli:

Component	Package	Path
Trace reading	@stratt/cli	lib/trace.ts
Run log merging	@stratt/cli	lib/run-log-reader.ts
Regression detection	@stratt/cli	lib/regression.ts
Veritas gate	@stratt/cli	lib/veritas.ts
DSPy export	@stratt/cli	commands/export-dspy.ts
Regression command	@stratt/cli	commands/regression.ts
Gate integration	@stratt/cli	commands/gate.ts

Example trace output (JSONL format):

{
  "trace_id": "tr_01aryz6s41tsqt0yp91qsydysq",
  "chain_address": "stratt://ops/chain/incident-response@2.1.0",
  "version": "2.1.0",
  "fingerprint": "blake3:a1b2c3d4e5f6...",
  "created_at": "2026-04-07T14:23:00Z",
  "completed_at": "2026-04-07T14:28:15Z",
  "status": "success",
  "quality_score": 0.87,
  "token_count_in": 2340,
  "token_count_out": 1840,
  "steps": [
    {
      "step_index": 0,
      "unit_address": "stratt://ops/task/assess-severity@1.0.0",
      "agent": "RETRO-04",
      "status": "success",
      "started_at": "2026-04-07T14:23:00Z",
      "completed_at": "2026-04-07T14:24:10Z",
      "token_in": 1200,
      "token_out": 340
    }
  ]
}

The Layer Stack

L6    MERIDIAN              ← Astro documentation site (public-facing)
L5    @stratt/cli           ← 24 commands, all orchestration
L4    @stratt/ir            ← Execution IR, portable compilation (n8n, TypeScript, LangChain)
L3.5  @stratt/n8n-exporter  ← Chain → n8n workflow compiler (FORGE pattern)
L3    @stratt/graph         ← DAG, blast radius, CI pipeline (FM-01 through FM-08)
L2    @stratt/crdt          ← Yjs-based CRDT, 7 merge strategies
L1    @stratt/schema        ← Zod validators, URI parsing, SPUH binary encoding
L0    @stratt/fingerprint   ← Canonical serialization → Blake3 hash

Dependency rule: Lower layers depend only on lower layers. Layer 5 can depend on Layers 0-4, but Layer 0 has zero dependencies on anything else.

Cross-Implementation Map

SPEC	Provides	Depends on	Primary Package
SPEC-01	Contracts	L1 validators	@stratt/schema + @stratt/cli
SPEC-02	Fingerprints	L0 hashing	@stratt/fingerprint + @stratt/schema
SPEC-03	Dependencies	L1 URIs	@stratt/graph
SPEC-04	Gates	L3 DAG	@stratt/graph + @stratt/cli
SPEC-05	Traces	L5 commands	@stratt/cli

Failure Modes

Each SPEC defines one or more failure modes (FM), detectable during CI or runtime:

FM Code	SPEC	Name	Condition
FM-01	SPEC-02	Fingerprint tamper	Blake3 digest mismatch
FM-02	SPEC-03	Broken imports	Unresolvable stratt:// or choco:// reference
FM-03	SPEC-03	DAG cycles	Circular dependency detected
FM-04	SPEC-04	Protected agent missing	Chain lacks required protected agent
FM-05	SPEC-04	Gate removal	Gate step removed without major version bump
FM-06	SPEC-01	Contract breaking change	Required input removed or type changed without major bump
FM-07	SPEC-03	Draft isolation	Stable unit importing a draft unit
FM-08	—	R2 infrastructure failure	Registry unavailable
FM-09	SPEC-04	Capability check	Agent assigned to step lacks required capability

What Remains

Gap	SPEC	Target
R2 atomic publish pipeline	SPEC-02	Production registry writes (currently local-only)
HTTP mode for ChocoBridgeResolver	SPEC-03	choco:// resolution via API endpoint
MIPROv2 optimization loop	SPEC-05	Automated prompt refinement via DSPy
Veritas auto-trigger automation	SPEC-05	Event-driven regression detection

See Also

• Primer — Horizontal Domain Scaling
• Namespace Resolution
• GRACE Protocol Overview