Export Schema Reference

This page documents the stable machine contract produced by agentxchain export and checked by agentxchain verify export.

This is not protocol v7 conformance. Export artifacts are an operator-facing audit and automation surface. They matter, but they are not part of the current protocol-v7 proof set. For the constitutional boundary, see Protocol Reference v7.

Choose The Right Surface

Do not treat the export artifact as self-explanatory transport data. AgentXchain has four adjacent operator surfaces here, and they are not interchangeable:

• agentxchain export writes the raw portable artifact documented on this page.
• agentxchain audit reads the live current repo/workspace, builds a fresh artifact, verifies it, and renders the derived governance summary.
• agentxchain report --input <file> reads an existing export artifact and renders that derived summary without touching live repo state.
• agentxchain replay export <file> reads an existing export artifact into a temporary read-only dashboard workspace for interactive inspection.

That distinction matters even more for coordinator artifacts. Partial coordinator exports where repos.<repo_id>.ok === false are still valid report/replay inputs: report keeps repo_ok_count / repo_error_count plus the failed repo row and error, while replay export restores a minimal placeholder governed repo instead of inventing a missing child export. audit only applies to a live workspace you are standing in, not a saved artifact.

Version And Kinds

Current export artifact schema:

Field	Value
schema_version	0.3
Run artifact export_kind	agentxchain_run_export
Coordinator artifact export_kind	agentxchain_coordinator_export

File Entry Contract

Every entry under files is keyed by its repo-relative path and carries the same shape:

Field	Meaning
format	Parsed view type: json, jsonl, or text
bytes	Original file byte length
sha256	SHA-256 digest of the original file bytes
content_base64	Original raw bytes, base64-encoded
data	Parsed JSON/JSONL value or raw UTF-8 text

content_base64 is the important part. verify export decodes it, re-derives bytes, re-derives sha256, and then proves that data still matches the decoded JSON, JSONL, or text payload. Without content_base64, the digest fields would just be self-reported metadata.

Run Export Shape

agentxchain export produces this top-level shape when run from a governed project:

Key	Meaning
schema_version	Export artifact schema version
export_kind	Always agentxchain_run_export for this shape
exported_at	ISO timestamp for artifact creation
project_root	Relative path from the current working directory to the governed project root
project	Project identity and normalized governed metadata
summary	Derived run summary for quick inspection
files	Repo-native audit files keyed by relative path
config	Raw agentxchain.json content
state	Parsed .agentxchain/state.json content
workspace	Source checkout metadata used for cross-machine continuity restore decisions

project

Field	Meaning
id	config.project.id
name	config.project.name
goal	Optional config.project.goal, or null when unset
template	Configured template or implicit generic
protocol_mode	Exported run protocol mode
schema_version	Governed config schema version

summary

Field	Meaning
run_id	Current governed run id or null
status	Current run status or null
phase	Current phase or null
workflow_phase_order	Ordered array of unique phase names from the project's routing config, or null when no routing is defined. When present it must be non-empty and include summary.phase. Used by diff --export for phase-aware regression detection and phase-order drift warnings
project_goal	Optional project goal copied from project.goal, or null when unset
active_turn_ids	Sorted keys from state.active_turns
retained_turn_ids	Sorted keys from state.retained_turns
history_entries	Count of .agentxchain/history.jsonl records
decision_entries	Count of .agentxchain/decision-ledger.jsonl records
hook_audit_entries	Count of .agentxchain/hook-audit.jsonl records
notification_audit_entries	Count of .agentxchain/notification-audit.jsonl records
dispatch_artifact_files	Number of files under .agentxchain/dispatch/
staging_artifact_files	Number of files under .agentxchain/staging/
intake_present	Whether any .agentxchain/intake/ file exists
coordinator_present	Whether any .agentxchain/multirepo/ file exists inside the governed repo
provenance	Run provenance metadata (trigger, parent_run_id, created_by) — null when absent
inherited_context	Read-only summary inherited from a parent run via --inherit-context — null when absent
dashboard_session	Snapshot of local dashboard-daemon status at export time
delegation_summary	Delegation chain summary derived from accepted history — null when history is unavailable
repo_decisions	Cross-run repo-level decisions — null when no repo decisions exist
export_files_truncated	true when maxExportFiles cap was applied and some collected files were omitted from the export
total_collected_files	Total number of files found before any maxExportFiles cap
included_files	Number of files actually included in the export files object

summary.repo_decisions

When present (non-null), provides a structured view of repo-level decisions that persist across runs:

Field	Meaning
total	Total number of repo decisions (active + overridden)
active_count	Number of currently active repo decisions
overridden_count	Number of overridden repo decisions
active	Array of active decisions (id, category, statement, role, run_id, overrides, durability, authority_level, authority_source)
overridden	Array of overridden decisions (id, overridden_by, statement, overrides, durability, role, authority_level, authority_source)
operator_summary	Compact first-glance significance block for operator surfaces

summary.repo_decisions.operator_summary

Field	Meaning
active_categories	Sorted unique categories from active repo decisions
highest_active_authority_level	Highest active decision authority level, or null when authority is not configured
highest_active_authority_role	Role holding the highest active authority, or null
highest_active_authority_source	Authority source (configured, human_default, unknown_role) or null
superseding_active_count	Number of active repo decisions that explicitly supersede earlier decisions
overridden_with_successor_count	Number of overridden repo decisions with a recorded overridden_by successor

summary.dashboard_session

Every current run export includes a dashboard-session snapshot object:

Field	Meaning
status	"running", "pid_only", "stale", or "not_running"
pid	Live/stale PID when known, else null
url	Dashboard URL when session metadata exists, else null
started_at	Session start timestamp when known, else null

This is an export-time operator snapshot, not protocol state. It is derived at export time using the same dashboard-session logic used by doctor and status --json.

This field is intentionally local and machine-specific:

• it records what the exporting workspace observed at export time
• verify export validates only the stored object shape and status-consistent invariants
• verifier-clean artifacts do not prove a live dashboard is still running on some later machine
• downstream surfaces such as agentxchain report may render this snapshot, but they must treat it as artifact metadata rather than re-probing live daemon state through the export contract

summary.delegation_summary

When present (non-null), provides a structured view of delegation chains:

Field	Meaning
total_delegations_issued	Total number of delegations across all parent turns
delegation_chains	Array of delegation chain objects

Each delegation chain object:

Field	Meaning
parent_turn_id	Turn that issued the delegations
parent_role	Role that delegated
delegations	Array of individual delegation entries
review_turn_id	Turn that reviewed the delegation results, or null if pending
outcome	"completed", "failed", "mixed", or "pending"

Each delegation entry:

Field	Meaning
delegation_id	Unique delegation identifier
to_role	Role the sub-task was delegated to
charter	Description of the delegated work
status	"completed", "failed", or "pending"
child_turn_id	Turn that executed the delegation, or null if not yet executed

This is a derived export summary, not an independent authority ledger:

• it is reconstructed from embedded .agentxchain/history.jsonl delegation records
• verify export fails closed when the summary disagrees with that embedded history
• operator-facing surfaces may render the summary for convenience, but the underlying history remains the authority inside the artifact

Included governed roots

When present, the run export collects:

• agentxchain.json
• TALK.md
• .agentxchain-dashboard.pid
• .agentxchain-dashboard.json
• .agentxchain/state.json
• .agentxchain/session.json
• .agentxchain/history.jsonl
• .agentxchain/decision-ledger.jsonl
• .agentxchain/repo-decisions.jsonl
• .agentxchain/lock.json
• .agentxchain/hook-audit.jsonl
• .agentxchain/hook-annotations.jsonl
• .agentxchain/run-history.jsonl
• .agentxchain/events.jsonl
• .agentxchain/notification-audit.jsonl
• .agentxchain/schedule-state.json
• .agentxchain/schedule-daemon.json
• .agentxchain/continuous-session.json
• .agentxchain/human-escalations.jsonl
• .agentxchain/sla-reminders.json
• .agentxchain/dispatch/**
• .agentxchain/staging/**
• .agentxchain/transactions/accept/**
• .agentxchain/intake/**
• .agentxchain/missions/**
• .agentxchain/multirepo/**
• .agentxchain/reviews/**
• .agentxchain/proposed/**
• .agentxchain/reports/**
• .planning/**

Missing optional roots are skipped. The exporter snapshots repo-native audit evidence; it does not sweep arbitrary source files into the artifact.

workspace.git

Run exports now include a source-checkout portability block:

Field	Meaning
is_repo	Whether the source export came from a git-backed checkout
head_sha	Source HEAD commit SHA or null
dirty_paths	All dirty tracked/staged/untracked paths in the source checkout
restore_supported	true only when the export is safe to restore into another checkout in this slice
restore_blockers	Exact reasons restore is unsafe, typically dirty product files outside the governed continuity roots

This metadata is for agentxchain restore, not protocol conformance. A run export can still be a valid audit artifact when restore_supported is false.

Coordinator Export Shape

When run from a coordinator workspace rooted by agentxchain-multi.json, the exporter emits:

Key	Meaning
schema_version	Export artifact schema version
export_kind	Always agentxchain_coordinator_export for this shape
exported_at	ISO timestamp for artifact creation
workspace_root	Relative path from the current working directory to the coordinator root
coordinator	Coordinator project metadata
summary	Derived coordinator summary
files	Coordinator-level audit files keyed by relative path
config	Raw agentxchain-multi.json content
repos	Per-repo export status and nested governed exports

coordinator

Field	Meaning
project_id	config.project.id or null
project_name	config.project.name or null
schema_version	Coordinator config schema version
repo_count	Number of entries in config.repos
workstream_count	Number of entries in config.workstreams

summary

Field	Meaning
super_run_id	Current coordinator run id or null
status	Current coordinator status or null
phase	Current coordinator phase or null
workflow_phase_order	Ordered array of unique phase names from the coordinator's routing config, or null when no routing is defined. When present it must be non-empty and include summary.phase
repo_run_statuses	Raw coordinator repo status snapshot derived from .agentxchain/multirepo/state.json
barrier_count	Number of barrier objects in .agentxchain/multirepo/barriers.json
history_entries	Count of .agentxchain/multirepo/history.jsonl records
decision_entries	Count of .agentxchain/multirepo/decision-ledger.jsonl records
aggregated_events	Merged child-repo lifecycle events: total_events, repos_with_events, event_type_counts, and time-sorted events array with repo_id on each entry

summary.repo_run_statuses is coordinator-state metadata. It records what the coordinator workspace believed about each child repo at export time, even when those labels are coarse linkage states like linked or initialized.

Operator-facing comparison and reporting surfaces use a stricter boundary. When a nested child export is readable, agentxchain diff --export, agentxchain report, and agentxchain audit derive child repo status from that nested repo authority first. Those commands may still preserve summary.repo_run_statuses as coordinator metadata, but they must not treat it as the primary repo-status truth when child authority exists.

repos

Each repos.<repo_id> entry has this contract:

Field	Meaning
ok	true when the child repo exported successfully, else false
path	Child repo path from agentxchain-multi.json
export	Full nested agentxchain_run_export when ok is true
error	Non-empty failure message when ok is false

The coordinator export does not fail just because one child repo export fails. Instead it records the bad repo as ok: false with an error string and still emits the coordinator artifact. That keeps coordinator-level evidence inspectable even when one repo is broken or missing.

That partial-export shape is intentional. Downstream commands degrade on purpose instead of inventing a nested repo export that is not there:

• agentxchain verify export recursively verifies only ok: true child exports and rejects summary.aggregated_events claims that depend on a failed child repo with no embedded export proof.
• agentxchain report and agentxchain audit still render coordinator-level evidence and per-repo export health, but drill-down fields for the failed child repo stay absent because there is no nested run export to summarize.
• agentxchain replay export still starts by restoring successful child repos and a minimal placeholder governed repo for the failed path so coordinator views stay readable without pretending the missing child export was embedded.

Included coordinator roots

When present, the coordinator export collects:

• agentxchain-multi.json
• .agentxchain/multirepo/state.json
• .agentxchain/multirepo/history.jsonl
• .agentxchain/multirepo/barriers.json
• .agentxchain/multirepo/decision-ledger.jsonl
• .agentxchain/multirepo/barrier-ledger.jsonl

Each successful child repo entry then embeds the full governed run export for that repo under repos.<repo_id>.export.

Verification Contract

agentxchain verify export currently accepts schema_version: "0.2" and "0.3" artifacts and checks:

• file-entry integrity by recomputing bytes and sha256 from content_base64
• data truth for json, jsonl, and text
• run-export summary fields against exported state and files
• summary.delegation_summary reconstructed from embedded .agentxchain/history.jsonl — verifies total_delegations_issued and delegation_chains match the history entries
• summary.repo_decisions reconstructed from embedded .agentxchain/repo-decisions.jsonl — verifies total, active_count, overridden_count, and decision arrays match the file
• summary.dashboard_session schema validation — verifies status enum, PID/URL/started_at types, and status-consistent invariants (e.g., running requires a PID, not_running requires all-null fields), but does not probe live dashboard state
• coordinator-export summary fields against exported multirepo state and barriers
• coordinator summary.aggregated_events consistency against embedded child-repo events.jsonl data when that summary is present
• recursive verification of each nested child export when repos.<repo_id>.ok === true

Verification Report Shape (--format json)

When verification completes (exit code 0 or 1), the JSON report has this shape:

Field	Type	Meaning
overall	"pass" or "fail"	"pass" when errors is empty, "fail" otherwise
schema_version	string or null	Schema version from the artifact, or null if missing
export_kind	string or null	Export kind from the artifact, or null if missing
file_count	number	Count of keys in the artifact files map
repo_count	number	Count of keys in repos (coordinator exports), or 0 for run exports
errors	string[]	Structured error strings, each formatted as "<path>: <message>"
input	string	Resolved file path or "stdin"

Command Error Shape (exit code 2)

When the input cannot be read or is not valid JSON, the report has a different shape:

Field	Type	Meaning
overall	"error"	Always "error" for command-level failures
input	string	Resolved file path or "stdin"
message	string	Human-readable error description

If you need CLI usage and exit codes, see the verify export command reference. If you need a human-readable summary derived from a verifier-clean artifact, use Governance Report Reference. If you need the constitutional boundary, go back to Protocol Reference v7.