# INTERFACE REGISTRY

## Canonical Contracts

- `MODULES/schemas/HANDOFF.agent-state.schema.json`
- `MODULES/schemas/STATUS_EVENT.schema.json`
- `MODULES/schemas/ARTIFACT_MANIFEST.schema.json`
- `MODULES/schemas/SWARM_HANDOFF.schema.json`
- `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`
- `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`
- `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`
- `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`
- `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`
- `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`
- `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`

## Runtime Contract

- `ACE_WORKFLOW.md` is the canonical workspace runtime profile artifact.
- Its YAML front matter must validate against `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`.
- The markdown body after the closing front matter boundary is the active runtime prompt template.
- The optional `continuity` block only budgets derived packet content; it must not redefine canonical ACE truth outside the existing state artifacts and sidecar-native stores.

## Workspace Session Contract

- `runtime-workspaces.json` is the canonical managed workspace/session registry.
- It must validate against `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`.
- Removal only applies to registry-backed managed workspace paths under the configured runtime root.

## Runtime Tool Contract

- `runtime-tool-specs.json` is the canonical runtime-configured external tool registry.
- It must validate against `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`.
- Unattended executor and direct runtime-tool execution must validate input/output payloads against the declared tool schemas.

## Runtime Executor Contract

- `runtime-executor-sessions.json` is the canonical unattended execution session registry.
- It must validate against `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`.
- Session turns must record request/response paths, summaries, and tool-call outcomes without mutating existing HANDOFF or STATUS_EVENT schema versions.

## Tracker Snapshot Contract

- `tracker-snapshot.json` is the canonical normalized tracker snapshot artifact.
- It must validate against `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`.
- Scheduler and future executor consumers must use normalized item/comment fields only; provider-specific detail belongs under `metadata`.

## Vericify Sidecar Contract

- `vericify/ace-bridge.json` is an optional sidecar bridge snapshot for Vericify-style read-model consumers.
- It must validate against `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`.
- `vericify/process-posts.json` is an optional structured process-post log and must validate against `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`.
- Vericify remains optional; ACE must not require the Vericify package to read or write these artifacts.

## Public Surface Gate

- `audit_public_surface` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
- `PUBLIC_SURFACE_REPORT.md` is the durable audit artifact written by that gate.
- `MODULES/gates/gate-typescript-public-surface.json` is the executable gate manifest for CI or operator use.

## Provenance Contract

- `ARTIFACT_MANIFEST.json` is mandatory and must be schema-valid.
- Each artifact entry must include `artifact_id`, `artifact_path`, `producer_module`, `spec_version`, `req_ids`, `checksum`, `confidence_level`, `evidence_ref`, and `timestamp`.
- `PROVENANCE_LOG.md` must mirror manifest entries with append-only evidence-linked records.

## Versioning Rules

- additive changes: `minor`
- breaking changes: `major`
- bugfix/clarification: `patch`

## Compatibility Requirement

Producer and consumer compatibility must be documented before release.