Envelope Specification — Cosmonapse Protocol

The envelope

signal.json

{
  "v":         "1",
  "id":        "evt_01JVBCDEF1234567890ABCDEF",
  "trace_id":  "trc_01JVBCDEF0000000000000000",
  "parent_id": "evt_01JVBCDEF0000000000000001",
  "type":      "THOUGHT_DELTA",
  "neuron":    "claude-debug",
  "ts":        "2026-05-16T14:22:01.391Z",
  "payload": {
    "delta": "reading the traceback...",
    "seq":   1
  },
  "meta": {
    "model":  "claude-sonnet-4-6",
    "tokens": { "out": 12 }
  }
}

Field reference

v●

Envelope version. Always “1” for this revision.

id●

Unique event ID — prefixed ULID. Consumers dedupe by this within a 60s window.

trace_id●

Root workflow ID. Stable across the entire delegation tree.

parent_id

ID of the event that caused this one. Absent only on the root TASK or TASK_OFFER.

type●

Message type. One of the values catalogued below.

neuron

Emitting Neuron ID. Omitted for client-originated events (e.g. a root TASK dispatched by an external workflow trigger).

ts●

RFC 3339 UTC timestamp with millisecond precision.

payload

Type-specific shape. Open object; consumers ignore unknown keys.

Three layers. Non-overlapping responsibilities.

The envelope flows top to bottom; agent output flows bottom to top. Each layer has exactly one job.

Dendrite — synapse-side connector + orchestration
The only component that touches the Synapse. Hosts Axons; owns routing decisions; exposes the aggregate of its Axons’ capabilities; emits REGISTER / HEARTBEAT / DEREGISTER; routes inbound TASKs (addressed by neuron_id or by capabilities); opens Pathways. A Dendrite has a role: "orchestrator" (full dispatch / emit surface) or "worker" (hosts Axons and bids in capability routing, but cannot emit TASK or any cognition signal). The role guard sits on emit() itself — every cognition emitter funnels through it. Every orchestrator-role Dendrite can drive workflows; there is no separate Cortex class.

↕

Axon — agent-side tool

Unwraps TASK → calls Neuron. Wraps Neuron output → AGENT_OUTPUT / CLARIFICATION / ERROR → returns to Dendrite. Never touches the Synapse directly.

↕

Neuron — pure function

async fn(input, context) → output. No protocol knowledge. Fully testable in isolation.

Identifiers

All identifiers are prefixed ULIDs: a short lowercase type prefix, an underscore, and a 26-character canonical ULID. Globally unique without coordination; lexicographically sortable by creation time.

Prefix	Used for	Example
evt_	Any envelope id	`evt_01JVBCDEF1234567890ABCDEF`
trc_	Any trace_id	`trc_01JVBCDEF0000000000000000`
call_	TOOL_CALL / TOOL_RESULT pairs	`call_01JVBCDEF0000000000000002`
prop_	CONSENSUS proposal IDs	`prop_01JVXAMPLE0000000000000001`

Subjects & delivery

Two TASK subjects. Two delivery modes.

The protocol exposes two transport-level routing modes for TASKs. The mode is chosen at dispatch time; both ride the same envelope.

Mode	Subject	Delivery	Selected when
Addressed	`cosmonapse.<ns>.TASK`	Broadcast (every Dendrite subscribes, only the named host acts)	TASK carries a `neuron` field
Capability-routed	`cosmonapse.<ns>.TASK.routed`	Queue group `caps:<sorted-aggregate>` — broker delivers exactly once per matching cap profile	TASK omits `neuron` and sets `payload.capabilities`

The split exists because a single queue group on a shared subject would break addressed routing (the broker could deliver an addressed TASK to a Dendrite that doesn’t host the target Axon, which would silently drop it). With two subjects, addressed broadcast and capability load-balancing coexist cleanly. Heterogeneous deployments — Dendrites with different but overlapping cap profiles — still get at-least-once across profiles; for atomic claim use TASK_OFFER / BID / TASK_AWARDED instead.

Cosmonapse CoreActive Development

Message types — Lifecycle

The mandatory types. Any compliant implementation must handle all of them.

TASKDendrite · external

Assigns a unit of work. Root TASK has no parent_id; delegated TASK points to the triggering event. Payload: { intent, input, context_ref?, deadline?, budget_usd? }

AGENT_OUTPUTDendrite (Axon data)

The Axon’s only output envelope for normal agent work. Neutral — workflow-semantic-free. The orchestrating Dendrite decides what it becomes. Payload: { output }

FINALDendrite

Successful completion of a task. Produced by the orchestrating Dendrite, never the Axon. Exactly one per task. Payload: { result }

ERRORAxon · Dendrite

Task failure — agent exception, timeout, no-capable-agent, budget exceeded. First terminal event wins. Payload: { kind, message, retriable? }

TASK_OFFERDendrite

Broadcast to candidates capable of handling an intent. Agents respond with BID or stay silent. Payload: includes required_caps, bid_window_ms.

BIDDendrite

An agent’s self-assessment in response to a TASK_OFFER. Payload: { offer_id, confidence, cost_estimate_usd?, eta_ms? }

TASK_AWARDEDDendrite

Sent to the winning agent after bid evaluation. Payload: { offer_id }

TASK_DECLINEDDendrite

Sent to the losers — signal to discard any speculative work.

Cosmonapse CoreActive Development

Message types — Cognition

Produced by the Dendrite, not the Axon or Neuron. Optional — a Dendrite that simply forwards TASK → FINAL with no intermediate events is fully compliant.

THOUGHT_DELTADendrite

A chunk of streaming reasoning. meta.seq must be monotonic per (trace_id, agent). Payload: { delta, final? }

PLANDendrite

Structured plan the agent has decided to follow. Supervisors may interrupt before execution. Payload: { steps, revision }

TOOL_CALLDendrite

The agent is invoking a tool. A matching TOOL_RESULT is expected. Payload: { tool, args, call_id }

TOOL_RESULTDendrite

Tool response, parent_id pointing to the corresponding TOOL_CALL. Payload: { call_id, ok, value?, error? }

ESCALATIONDendrite

Agent cannot complete and is requesting re-dispatch to a more capable agent. Caller is excluded from the new candidate set. Payload: { reason, hints? }

CONSENSUSDendrite

Publishes the outcome of a multi-agent vote. Payload: { proposal_id, outcome, votes, threshold? }

CRITIQUEDendrite

A review of another envelope’s output, pinned via target_event_id. Payload: { target_event_id, severity, note }

CLARIFICATIONDendrite (Axon data)

The Axon recognises a clarification signal in the agent’s raw output and emits this directly. The Dendrite never has to inspect AGENT_OUTPUT for it. Payload: { questions, context? }

DISCOVERDendrite

Capability discovery probe. Peers that match respond on the discovery subject; the originator aggregates them into a registry snapshot.

Cosmonapse CoreActive Development

Message types — Agent management

Emitted by the Dendrite on behalf of each attached Axon. The Axon owns the metadata (neuron_id, capabilities, version); the Dendrite publishes these Signals onto the Synapse.

REGISTERDendrite (Axon data)

An agent announces its capabilities and constraints. Re-emit with updated fields is valid (upsert). Payload: { capabilities, cost_hint?, max_concurrent?, max_latency_ms? }

DEREGISTERDendrite (Axon data)

Graceful exit. Nuclei stop routing to this agent. Payload: { reason }

HEARTBEATDendrite (Axon data)

Periodic liveness. Missing N (default 3) consecutive heartbeats = treated as dead. Payload: { status, load?, in_flight? }

Cosmonapse EngramActive Development

Message types — Engram (shared memory)

The Engram surface is request/reply: an Axon asks for context with RECALL or commits a write with IMPRINT, and the bound backend replies with RECALLED or IMPRINTED. Identifiers use the eng_ ULID prefix. The Neuron never writes to the memory fabric directly — EngramClient is the in-Neuron API.

Engram primitives → Recall · Imprint | Echo (next)

RECALLAxon (via EngramClient)

Asks the bound Engram to return relevant context for a Neuron. Payload: { engram_id, query, mode?, k?, deadline_ms? } where mode is first | merge | all.

RECALLEDEngram backend

Reply to a RECALL, parent_id pointing at the original request. Payload: { hits, partial? } where each Hit carries { id, content, score?, tags? }.

IMPRINTAxon (via EngramClient)

Commits a write to the bound Engram. Payload: { engram_id, op, entry, deadline_ms? } where op is add | append | merge | upsert | delete.

IMPRINTEDEngram backend

Reply to an IMPRINT. Payload: { id, ok, error? }.

Cosmonapse DopplerActive Development

Observability surface

Doppler is a non-competing, read-only consumer of the Synapse. It does not define its own Signal types — it taps every Signal emitted by Core and Engram. Pulse streams the raw telemetry; Prism renders it as dashboards and trace graphs. cosmo doppler in the CLI is the baseline implementation.

Pulse — real-time Signal metrics: latency, throughput, error rates, cost per Neuron. Prism — the visualization layer: trace graphs, audit logs, dashboard views. Both build on the existing Synapse subscription model — no new envelope types required.

Cosmonapse ImmuneNot Planned

Future signal extensions

These signal types are reserved for future Cosmonapse products. They are not part of the current envelope spec but are documented here for planning purposes.

Immune — Genome · Myelin · Reflex · AntiBody

Planned signal types include IDENTITY_ASSERT (Genome — neuron identity proof), KEY_ROTATE (Myelin — in-band key refresh), and THREAT_SIGNAL (Reflex/AntiBody — anomaly broadcast). These will extend the envelope spec in a future revision and remain backwards-compatible with v1 consumers.

Cloud — Membrane

Membrane isolation signals are infrastructure-layer only and will not appear on the application Synapse. They operate below the envelope boundary.

Validation

An envelope is valid if and only if…

It is well-formed JSON.
v is present and equals "1".
id is present and matches ^evt_[0-9A-Z]{26}$.
trace_id is present and matches ^trc_[0-9A-Z]{26}$.
parent_id, if present, matches the event pattern.
type is present and is one of the catalogued values.
ts is a valid RFC 3339 UTC timestamp ending in Z.
payload and meta, if present, are JSON objects.
Required payload fields for the given type are present and correctly typed.

cosmo validate checks these rules against a stream of envelopes. Validity is purely structural — Cosmonapse does not enforce sequencing or lifecycle rules. What constitutes a completed task, what happens after an error, and how envelopes flow over time are decisions you make in your Dendrite.