Chains

A Chain is an executable workflow. It either executes admitted instructions directly, or composes ordered and conditional Bits. A Bit is an executable atomic task. Merely storing checklist items does not execute a Chain and cannot produce a successful run.

Runtime invariant

Every run is denied unless the current instructions have a valid admission decision whose digest matches the current Chain revision. Missing or stale decisions are revalidated before execution. If classification is unavailable, the Chain remains unexecuted. Historical records are never silently grandfathered.

Core endpoints

Method	Path	Purpose
GET	/chains	List Chains
GET	/chains/:id	Read one Chain
POST	/chains	Create an instruction-backed executable Chain
PATCH	/chains/:id	Update a Chain and revalidate changed instructions
POST	/chains/from-bit-dag	Create a Chain from executable Bits and Agent bindings
PATCH	/chains/:id/execution-source	Replace the executable source atomically
POST	/chains/:id/trigger-run	Request an idempotent run
GET	/chains/:id/runs	List execution runs
GET	/chains/:id/runs/:runId	Inspect a run
POST	/chains/:id/runs/:runId/cancel	Cancel a run
GET	/chains/:id/bit-tree	Read the composed Bit graph
GET	/chains/:id/artifacts	List produced artifacts
GET	/chains/:id/provenance	Trace runs, Bits, Agents and artifacts

Create an instruction-backed Chain

curl -X POST "$BASE_URL/chains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly customer update",
    "instructions": "Collect this week’s approved customer changes, produce a concise update, and save it as a workspace artifact.",
    "assistantAgentInstanceId": "00000000-0000-4000-8000-000000000001"
  }'

instructions is required and must describe work the runtime can execute. A human practice, passive reminder, or source-less record is rejected. description is explanatory text and never substitutes for instructions.

Compose Bits

Use /chains/from-bit-dag when the workflow has multiple atomic units. Each Bit must have an executable source, such as an active Agent execution profile. The API owns graph validation, admission, grants, revisioning and persistence as one domain operation.

Templates

Executable templates expose ordered Bit slots. Installation requires exactly one accessible Agent binding for every slot and creates the matching execution grant. Use GET /chains-templates, GET /chains-templates/:id, and POST /chains-templates/:id/fork.

Admission failures

Non-executable requests, stale decisions, unavailable classifiers, missing Bit execution sources, invalid graphs, or insufficient grants fail closed. Responses contain stable error codes; instruction text is not emitted in admission telemetry.