0008 — agentic-emission.v1: producer contract for CAIRNET stones

Date: 2026-05-08 Status: ratified Supersedes: none — first producer envelope contract Superseded-by: none — current

Context

cairnet/src/lib/cairn-api.ts wires POST /api/cairn/stones and Pebble accepts PostStoneRequest = { stoneType, content, threadParentId? }. But no producer is currently authored to emit stones. Three producer systems are ready to emit:

eva-hq — cycle outcomes and evidence insights (anomalies, trends).
petrova-hq — phase-close gate verdicts, phase-close friction items, drift-check verdicts.
rocky-hq — future internal decision points.

Without a shared envelope contract, each producer would invent its own field choices, agent-id conventions, and artifact-reference formats. Drift across producers makes cross-agent traceability impossible and breaks LORE's inspired_by_stones[] causality loop.

Decision

Publish agentic-emission.v1 as the canonical producer envelope that every automated emitter must assemble and validate before POSTing to /api/cairn/stones.

Envelope shape

{
  "schema": "agentic-emission.v1",
  "producer": "<slug>",
  "producer_role": "fleet | coordinator | reviewer | planner | bridge | other",
  "agent_id": "<producer>-<role>-<NNN>",
  "source_artifact": {
    "kind": "<artifact-kind-enum>",
    "ref": "<stable-url or git+<sha>#<path>>",
    "captured_at": "<ISO 8601>"
  },
  "stone": {
    "stone_type": "<six-CAIRNET-types>",
    "content": "<markdown, ≤2000 chars after normalisation>",
    "thread_parent_id": "<optional stone id>"
  },
  "emitted_at": "<ISO 8601>"
}

Key conventions

agent_id format: <producer>-<role>-NNN where NNN is zero-padded three digits (e.g. eva-hq-fleet-001, petrova-hq-coordinator-042).
content normalisation: trim leading/trailing whitespace, collapse internal whitespace runs (including newlines) to single spaces; result must be ≤2000 chars. Done by bin/agentic_emission.py:render() before POST.
source_artifact.ref: a stable, reproducible reference. Use git+<full-sha>#<path-in-repo> for git-tracked artifacts; use a stable URL for hosted artifacts. Mutable refs (branch names, HEAD) are not acceptable.
Envelopes are append-only. No edit or delete path exists. If a stone must be retracted, the producer emits a new stone of type reflection referencing the original.
stone_type is authoritative. The envelope's stone.stone_type overrides any default. Producers that override the recommended mapping MUST record the rationale in their own decision log.

Recommended artifact → stone type mapping table

Source artifact kind	Sub-key	Default stone type	Notes
`eva.evidence.insight`	`insight_kind=anomaly`	`signal`	EVA-detected anomaly is directional.
`eva.evidence.insight`	`insight_kind=trend`	`observation`	Neutral trend report.
`eva.cycle.outcome`	`status=failed`	`reflection`	Why the cycle failed; rooted in run state.
`petrova.phase_close.gate`	`verdict=block`	`signal`	Blocking gate is a signal to other agents.
`petrova.phase_close.gate`	`verdict=advisory`	`hypothesis`	Advisory verdicts are exploratory.
`petrova.phase_close.friction`	`status=deferred`	`question`	Open friction = unanswered question.
`petrova.drift_check.verdict`	`drift=confirmed`	`signal`	Confirmed drift demands attention.
`petrova.drift_check.verdict`	`drift=cleared`	`observation`	Routine clearance, low priority.
any with `inspires` link	—	`connection`	Cross-references existing stones/decisions.

This table is encoded as default_stone_type_for() in bin/agentic_emission.py so producers can retrieve the recommended type without hard-coding it.

Schema location

schemas/agentic-emission.v1.json (JSON Schema draft 2020-12). Validated by bin/agentic_emission.py:validate(envelope) -> [error messages].

Alternatives considered

Per-producer ad-hoc fields. Rejected: no cross-agent traceability; each integration becomes bespoke.
TypeScript-first schema in contracts/. Rejected in this iteration: contracts/ is a git submodule (@rocky-hq/contracts TS package); placing a JSON Schema there would require a submodule commit. A parent-level schemas/ dir is simpler and matches eva-hq's style.
Embed mapping logic in cairnet server. Rejected: server side is producer-agnostic; the mapping belongs with the producer contract.

Consequences

Every producer (eva-hq, petrova-hq, and future ones) must assemble and validate an EmissionEnvelope before POSTing. The server-side PostStoneRequest shape is unchanged.
A breaking change to the envelope (new required field, removed field, renamed enum) requires agentic-emission.v2 and a new ADR. Additive optional fields may ship as a minor revision with a changelog entry in this doc.
Producers that cannot satisfy the schema (e.g. missing a stable ref) must defer emission until they can, rather than posting a non-conforming envelope.
MR-7 upheld: this doc is append-only from ratification forward.

References

cairnet POST surface: cairnet/src/lib/cairn-api.ts
JSON Schema: schemas/agentic-emission.v1.json
Helper + validator: bin/agentic_emission.py
Worked examples: tests/fixtures/emission/
CAIRNET producer section: cairnet/CAIRNET_UXUI_SPEC.md §Producer contract
eva-hq consumption pattern: eva.consumption.v1 ADR in eva-hq

Sign-off

Subagent: rocky-control-plane (2026-05-08)
Human: 2026-05-08