Protocol Reference v7

This is the current normative boundary for AgentXchain protocol v7. It exists because the repo already had two adjacent but different surfaces:

• Protocol v7 explains the constitutional model.
• Protocol Implementor Guide explains how to prove conformance.

Neither one was clean enough to answer the narrower question: what is actually part of protocol v7 right now, and what is merely a reference-runner or integration detail?

The canonical versioned repo-native source is PROTOCOL-v7.md.

The governed config schema is also shipped as a machine-readable package artifact at agentxchain/schemas/agentxchain-config. The connector capabilities handshake output schema is at agentxchain/schemas/connector-capabilities-output.

Versioning Model

Do not flatten these into one number:

Axis	Current value	Meaning
Protocol version	v7	Constitutional contract
Governed config schema	1.0	agentxchain.json governed config shape
Turn result schema	1.0	staged result payload contract
Governed state schema	1.1	.agentxchain/state.json shape
Coordinator config/state/context schema	0.1	multi-repo config and coordinator artifacts
Conformance tiers	1, 2, 3	executable proof packaging, not protocol versions

If someone says "AgentXchain is on schema 1.1" or "Tier 3 means protocol v3," that is wrong.

Normative Repo-Local Contract

These repo-local concepts are protocol v7, not UI sugar:

Governed run statuses

• idle
• active
• paused
• blocked
• completed
• failed

Write authorities

• authoritative
• proposed
• review_only

Artifact and lifecycle rules

• Governed config is repo-native in agentxchain.json.
• Raw governed role bindings use roles.<role>.runtime. The reference runner normalizes that field to runtime_id in memory and in turn/state artifacts, but runtime_id is not the canonical raw config field.
• Accepted turn history is append-only in .agentxchain/history.jsonl.
• Accepted decisions and selected governance events are append-only in .agentxchain/decision-ledger.jsonl.
• Run lifecycle events are append-only in .agentxchain/events.jsonl (run_started, turn_dispatched, turn_accepted, blocking/escalation, run_completed).
• Terminal run summaries are append-only in .agentxchain/run-history.jsonl, with inherited continuity from parent runs kept under separate parent_context metadata rather than mixed into the current run's own counters.
• Turn dispatch is turn-scoped under .agentxchain/dispatch/turns/<turn_id>/.
• Staged results are turn-scoped under .agentxchain/staging/<turn_id>/turn-result.json.
• Gate requests are queued first and only become human-approvable when they materialize as pending_phase_transition or pending_run_completion.
• review_only turns must raise at least one objection. That is a protocol rule, not a documentation preference.

Decision durability and overrides

Decision carryover in v7 is explicit:

• durability: "run" is the default decision scope. Run-scoped decisions do not escape the current run.
• durability: "repo" promotes a decision into repo-level continuity so continuation runs still inherit it.
• overrides: "DEC-..." is the repo-decision replacement hook. The v7 fixture set (DC-003, DC-004) proves that a valid override targets an existing active repo decision, and self-override is invalid.

These semantics are proven by the decision_carryover conformance surface (DC-001 through DC-005).

Run event lifecycle

Run events in .agentxchain/events.jsonl follow a strict ordering contract:

• The first event must be run_started.
• turn_accepted must be preceded by turn_dispatched for the same turn.
• run_completed must be the last event.
• Timestamps must not regress (no backwards timestamps).
• Turn events must include turn.turn_id.

These rules are proven by the event_lifecycle conformance surface (EL-001 through EL-008).

Governed config schema artifact

• Package export: agentxchain/schemas/agentxchain-config
• Source file: cli/src/lib/schemas/agentxchain-config.schema.json
• Current purpose: freeze the raw governed config shape for project, roles, runtimes, and the raw role-to-runtime binding contract so non-reference runners do not have to infer it from normalized reference-runner state.
• The published schema also documents the runner-owned watchdog knobs run_loop.startup_watchdog_ms and run_loop.stale_turn_threshold_ms, plus the local-CLI-specific override runtimes.<id>.startup_watchdog_ms, so BUG-51/BUG-47/BUG-54 tuning is part of the machine-readable config contract instead of an implementation-only detail.
• Runtime capability declarations live under runtimes.<id>.capabilities in raw config. Those declarations affect the runtime capability contract and the connector capabilities handshake, but they do not rename the raw role binding field.

Connector capabilities output schema artifact

• Package export: agentxchain/schemas/connector-capabilities-output
• Source file: cli/src/lib/schemas/connector-capabilities-output.schema.json
• Current purpose: freeze the connector capabilities --json output shape so third-party tooling can validate the handshake response without parsing prose or inferring shapes from tests. Covers single-runtime, multi-runtime (--all), and error responses.

Workflow kit output schema artifact

• Package export: agentxchain/schemas/workflow-kit-output
• Source file: cli/src/lib/schemas/workflow-kit-output.schema.json
• Current purpose: freeze the workflow-kit describe --json output shape so third-party tooling can validate the workflow kit contract response. Covers phase templates, per-phase artifacts, semantic validators, and gate artifact coverage.

Connector validate schema continuity proof

• connector validate --json emits schema_contract
• Current purpose: prove that the selected runtime+role binding is coherent across the published raw config schema artifact and the generated connector capability handshake before synthetic dispatch claims success
• Scope: runtime+role continuity proof only; not a standalone schema artifact yet

Normative Coordinator Contract

These multi-repo concepts are part of protocol v7:

• super_run_id
• workstreams
• acceptance_projection
• COORDINATOR_CONTEXT.json
• coordinator pending_gate

Current barrier types are:

• all_repos_accepted
• interface_alignment (requires explicit interface_alignment.decision_ids_by_repo; satisfied only when each repo has accepted its declared decision IDs)
• named_decisions (requires explicit named_decisions.decision_ids_by_repo; satisfied only when each repo has accepted its declared decision IDs)
• ordered_repo_sequence
• shared_human_gate

The coordinator is not allowed to invent repo-local truth. Repo-local accepted history remains authoritative. Coordinator projections, barriers, and gates are derived from repo-local state, not the other way around.

Current Executable Proof Set

Protocol v7 is currently proven by the shipped conformance corpus under .agentxchain-conformance/fixtures/.

Current surfaces:

• Tier 1: state_machine, turn_result_validation, gate_semantics, decision_ledger, history, config_schema, delegation, decision_carryover, parallel_turns, event_lifecycle
• Tier 2: dispatch_manifest, hook_audit
• Tier 3: coordinator

That list is the current executable proof set. It is not a claim that every shipped product feature is part of protocol v7.

Why This Is Still v7

The reference CLI ships workflow surfaces beyond the v7 conformance corpus. That does not automatically make them protocol-v8 requirements.

These surfaces are still reference-runner or operator workflow features today:

• mission hierarchy and mission plans under .agentxchain/missions/
• dashboard APIs, ports, view names, and browser UX
• export, report, and release operator surfaces

A non-reference runner can truthfully claim protocol-v7 conformance without implementing those features. The current bar is the shipped fixture corpus plus the normative artifact contracts documented here.

A future protocol-v8 cut needs durable promotion work: promoted fixtures or a new normative artifact/state contract, plus the matching versioned docs and capabilities updates. A changelog line is not enough.

Not Normative In v7

These are real product surfaces, but they are not part of protocol v7 conformance today:

• CLI command names such as step, resume, or multi approve-gate
• mission hierarchy, mission plans, and .agentxchain/missions/ workflow artifacts
• dashboard ports, view names, and browser UX
• provider-specific adapter behavior such as Anthropic or OpenAI request wiring
• notifications.webhooks delivery behavior and event transport
• export artifact schema and verify export report semantics, which are stable operator contracts but not protocol-v7 proof surfaces. See Export Schema Reference

Those surfaces matter, but treating them as constitutional truth before they are promoted into the conformance boundary would be sloppy.

How To Read The Docs Stack

• Start with Protocol v7 for the constitutional overview.
• Use this page when you need the current normative boundary.
• Use Protocol Implementor Guide when you are building or validating another runner.