Protocol Overview

What is GRACE?

GRACE defines the discipline of constructing, versioning, fingerprinting, and auditing prompt units for autonomous AI agent systems such that every execution is cryptographically traceable to an approved, immutable specification.

Official Category: Verifiable Agentic Prompt Architecture (VAPA)
Protocol: GRACE
Reference Implementation: STRATT v2.0+

---

The Core Problem

Autonomous chains operating with prompt units face three classes of silent failure:

1. Silent Contract Drift — Units change output shapes without detection, causing downstream failures
2. Unverifiable Execution — No way to verify that the prompt executing is the one that was authored and approved
3. Undetectable Degradation — Chains produce plausible-looking output that is subtly wrong, with no mechanism to surface when quality drops

GRACE solves these through five normative specification layers.

---

Five Specification Layers

SPEC-01: Prompt Contract Specification

Problem: Silent contract drift when units change outputs without bumping versions.

Solution: Five unit types with typed input/output contracts, explicit change classification, and CI enforcement:

• 5 Unit Types: role, rule, task, chain, supply
• Typed Contracts: 7 input types (string, integer, float, boolean, document, array, object) + outputs + failure handlers
• Change Classification: Breaking (major), additive (minor), patch — enforced by CI
• Lifecycle: 9-state machine (draft → review → approved → published → active → deprecated → archived → tombstoned)
• Council Stewardship: 7 councils govern unit approval and gates

Learn more: GRACE Spec SPEC-01

SPEC-02: Blake3 Fingerprint & Tamper Detection

Problem: No way to verify that production prompts match approved specifications.

Solution: Cryptographic fingerprinting via Blake3 over canonical YAML serialisation:

• 5-Stage Pipeline: YAML parse → object transform (null removal, NFC) → canonical JSON → UTF-8 → Blake3 hash
• Deterministic: Any canonical YAML produces identical 64-char hex hash
• Tamper Detection: Stored vs. computed comparison reveals fingerprint mismatches
• Test Vectors: 14 normative vectors ensure implementation conformance
• RFC 8785 Analysis: 4 intentional divergences from JCS standard, documented

Learn more: GRACE Spec SPEC-02

SPEC-03: Dependency Graph Specification

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

Solution: Directed acyclic graph (DAG) model for unit imports:

• Explicit Imports: All dependencies declared as stratt:// or choco:// URIs
• Cycle Detection: Kahn’s algorithm prevents circular dependencies
• Blast Radius: Transitive reverse dependencies computed to assess change impact
• Domain Isolation: Cross-domain imports restricted to core/ and shared/
• Cross-Namespace: choco:// scheme enables imports from external documentation systems

Learn more: GRACE Spec SPEC-03

SPEC-04: Gate Checkpoint Protocol

Problem: Autonomous chains produce plausible-looking but subtly wrong output with no synchronisation mechanism.

Solution: Hard synchronisation primitives that halt execution until resolved:

• Gate States: PENDING → APPROVED, REJECTED, TIMEOUT (24h), ESCALATED
• Gate Authority: One agent per council with approval power (e.g., LEWIS-06 for Pathfinder)
• Protected Agents: Some agents cannot be bypassed (e.g., BECK-02, EECOM-02)
• Gate-Required Transitions: 4 lifecycle transitions require explicit approval
• Audit Records: Every gate resolution recorded with timestamp and resolver

Learn more: GRACE Spec SPEC-04

SPEC-05: Execution Trace & Audit Specification

Problem: After months of running chains, no way to answer which units improved, which degraded, which gates fired most.

Solution: Mandatory trace creation with quality scoring and regression detection:

• Chain Traces: trace_id, version, fingerprint, quality_score, token counts
• Step Traces: Unit address, agent, prompts, responses, status, gate resolutions
• Quality Scoring: Conformance (contract match) + completeness (required fields) + efficiency (tokens/output)
• DSPy Export: JSONL format for model optimization with filtering by score/date/version
• Regression Detection: Auto-trigger gate when quality drops > 5%

Status: Design phase. Implementation roadmap in next release.

Learn more: GRACE Spec SPEC-05

---

7 Active Councils

Each council governs one domain and stewards units within it:

Council	Domain	Gate Authority	Protected Agent
Pathfinder	dev	LEWIS-06	BECK-02
Hermes	ops	RETRO-04	EECOM-02
Athena	docs	EDITOR-04	CURATOR-02
Bastion	security	COMMANDER-05	ANALYST-03
Compass	product	COURSE-05	MERIDIAN-03
Herald	marketing	CROWN-05	GAZETTE-03
Terra	data	MANTLE-05	SPRING-03

---

15 Domains

Units are segmented into 15 domains:

Core Domains: dev, ops, docs, shared
Professional Domains: neuro, finance, nutrition, legal, film, artist, security, product, data, marketing, core

Cross-domain imports restricted to prevent tight coupling. Non-core domains can only import from their own domain, core/, or shared/.

---

Design Principles

1. Determinism

All cryptographic operations must be deterministic. Identical inputs produce identical outputs. The 5-stage fingerprint pipeline enforces this.

2. Immutability

Published units (status ≥ published) are immutable. Modification requires publishing a new version. Enables reliable dependency tracking.

3. Auditability

Every mutation, gate resolution, and state transition is recorded with timestamp and resolver. No silent changes.

4. Fail Secure

When in doubt, reject. All 9 failure modes result in explicit rejection with clear error messages, never silent acceptance.

5. Layering

Implementation is strictly layered. Lower layers (fingerprint, schema) have zero knowledge of higher layers (CLI, IR). Enables independent development and testing.

---

9 Failure Modes (FM-01 through FM-09)

All failure modes are enumerated and traceable to implementation:

Code	Name	Trigger	Handler
FM-01	Fingerprint Tamper	Stored ≠ computed hash	Reject execution, alert
FM-02	Broken Imports	Unit doesn’t exist	Validation error
FM-03	DAG Cycles	Circular dependency	Validation error
FM-04	Protected Agent Missing	Agent not in council	Validation error
FM-05	Gate Removal	Gate-required transition without approval	Validation error
FM-06	Contract Breaking Change	Required input removed	Validation error
FM-07	Draft Isolation	Draft imports non-draft	Validation error
FM-08	R2 Infrastructure Failure	Registry unavailable	Publish fails, rollback
FM-09	Capability Check	Agent lacks capability	Validation error

---

Conformance Levels

Level 1: Core (Minimum)

• SPEC-01 unit types and contracts
• SPEC-02 fingerprinting
• SPEC-03 DAG cycle detection
• 6-step validation pipeline

Reference: @stratt/schema + @stratt/fingerprint + basic @stratt/graph

Level 2: Production (Recommended)

• All of Level 1
• SPEC-04 gate checkpoint protocol
• Blast radius computation
• Domain isolation enforcement
• Audit record creation

Reference: Full STRATT implementation

Level 3: Advanced (Optional)

• All of Level 1 + 2
• SPEC-05 execution traces
• Quality scoring
• DSPy export pipeline
• Automated regression detection

---

Key Concepts

URI Format

All units are identified by canonical URIs: stratt://{domain}/{type}/{slug}@{version}

Examples:

• stratt://dev/role/code-reviewer@1.2.3
• stratt://ops/task/health-check@2.1.0
• stratt://shared/supply/policies@1.0.0

Cross-namespace imports use choco:// scheme:

• choco://security/standards/data-handling@2.1.0

Lifecycle State Machine

Units progress through 9 states with explicit transitions:

draft → review → approved → published → active → deprecated → archived → tombstoned

Some transitions require gate approval (frozen transitions). Status determines what can be imported.

Contract Model

Tasks and chains define typed input/output contracts:

contract:
  inputs:
    - name: code
      type: string
      required: true
  outputs:
    - name: review
      type: string
  failure_modes:
    - code: TIMEOUT
      handler: retry

Modifications that add outputs or make inputs optional are non-breaking. Removals or type changes require major version bump.

Draft Isolation Rule

A unit in draft status can only import units also in draft status. This prevents immature work from polluting approved chains.

---

Next Steps

• Getting Started: Quick-start guide — Create your first unit in 5 minutes
• Full Specification: GRACE Protocol v1.0 — Complete normative reference
• Architecture: System architecture — Package layers and data flow
• CLI Reference: 21 Commands — All commands with examples