Skip to main content

Task Contract Pack (MVP)

last updated: 2026-03-01

This page defines the machine-checkable I/O contracts used by the Protocol Factory MVP.

These contracts serve three purposes:

  1. Step Functions integration (structured outputs; no scraping logs)
  2. Determinism boundaries (LLMs propose; tools verify; outputs are typed)
  3. Auditability (every artifact and event is hash-addressed)

Files in this pack​

Schemas (JSON Schema 2020-12):

  • contracts/planner_task_io.schema.json
  • contracts/builder_task_io.schema.json
  • contracts/verifier_task_io.schema.json
  • contracts/ledger_event.schema.json
  • contracts/evidence_bundle_manifest.schema.json

Examples:

  • contracts/examples/planner.success.json
  • contracts/examples/builder.success.json
  • contracts/examples/verifier.success.json
  • contracts/examples/ledger.event.plan_generated.json
  • contracts/examples/evidence.manifest.json

Contract design principles​

  • Opaque large payloads: prompts and full logs go to S3; Step Functions receives references + hashes.
  • Hashes everywhere: anything used in dispute workflows is content-addressed (SHA-256).
  • Stable IDs: use run_id + phase + step and ULIDs for sub-objects.
  • No secrets: schemas never include tokens, keys, or internal endpoints.

Where these are used​

  • PlannerAgent emits a PlannerResult to the state machine.
  • BuilderAgent emits a BuilderResult (including the created git refs).
  • VerifierAgent emits a VerifierResult and sets the gate outcome.
  • Every significant transition writes a LedgerEvent record.
  • PRs link to an EvidenceBundleManifest stored in S3.

Public vs private note​

These contracts are safe to publish because they describe interfaces and invariants, not your private:

  • credentials/secrets,
  • internal network topology,
  • proprietary prompts,
  • partner integrations,
  • cost/rate-limits,
  • security thresholds.

If you later decide to keep the factory proprietary, you can keep these schemas public while moving:

  • concrete prompt templates
  • policy thresholds
  • infra wiring (exact ARNs, IAM roles, subnet IDs) into a private repo.
Last updated on