One event, an explicit next step
Weave carries information through typed, durable events. A request, a delivery receipt, a result and a verification are separate facts. Registered consumers do the mechanical work; a versioned continuation describes which result permits the next step.
People keep ownership of their applications, authored worlds and judgments. Recording an event does not grant permission to act.
| Layer | Responsibility |
|---|---|
| Event | What happened, who sent it, who receives it, and its cause. |
| Contract | The immutable version and permitted next steps. |
| Journal | Durable inbox, outbox, evidence and recovery state. |
| Consumer | A registered executable handler with bounded inputs and a terminal outcome. |
| Wire | The versioned representation used by a particular transport. |
What works today
| Component | Scope |
|---|---|
| Core event runtime | Durable journals, correlated receipts, bounded replies and evidence-gated recovery are implemented. Runtime contracts describe deployed native/relay adapters; this page does not probe their live health. |
| Continuation / 1 | Implemented and locally qualified. Finite DAG, fanout/join, immutable hash and deterministic successor IDs. Production flow activation remains separate. |
| Local system tool | Five executable commands, one complete file-integrity consumer. 70 passing tests in the retained local suite. |
| Reference binary layouts | 40-byte send, 4-byte receipt and 16-byte member layout have their own draft/reference status. They are not a universal encoding for every event. |
Browse the source-generated event and wire catalog. Catalog labels describe evidence scope; they are not a live service check.
Use the complete local tool
The first consumer verifies a regular file, up to 16 MiB, against a caller-supplied SHA-256. A worker reads the file; a separate deterministic verifier reads it again. A received verification records success. It is a machine acceptance check, not independent human review.
| Command | Behavior |
|---|---|
| catalog | List implemented commands, consumer limits and pinned contract. |
| submit FILE --sha256 EXPECTED | Persist a new UUID job and root request; return queued job ID. Expected digest must come from the caller. |
| run ID | Recover local delivery from exact inbox evidence, drain the finite event queue, inspect the file, claim the measured result and check it with a second read against the expected digest. |
| status ID | Read durable received outcome and evidence without running the job. |
| events ID | Read immutable event envelopes, including causal IDs, without running the job. |
python3 -B tools/crew/weave_tool.py catalog
python3 -B tools/crew/weave_tool.py submit /absolute/path/to/file --sha256 <expected-64-hex-digest>
python3 -B tools/crew/weave_tool.py run <returned-job-id>
python3 -B tools/crew/weave_tool.py status <returned-job-id>
python3 -B tools/crew/weave_tool.py events <returned-job-id>Place --state PATH before the command to choose a state directory. The default is ~/.local/share/weave-local. Save the returned job ID. A repeated run retains the same events; changed inputs require a new submission.
| Exit | Meaning |
|---|---|
| 0 | Command succeeded; inspect state for queued/pending/verified. |
| 1 | Job has a recorded failed outcome. |
| 2 | Invalid request, missing job, conflicting inputs or execution/storage error; original records retained. |
Verification describes the bytes at the recorded reads, not future contents, authorship or safety. The tool does not contact crew, invoke models or execute arbitrary shell commands.
Event lifecycle
| Event | Owner | Meaning |
|---|---|---|
| event_created | source daemon | Persist a source observation with its canonical reference. |
| delivery_ack | receiving daemon | Exact recipient context received the event. No agent action or task completion implied. |
| action_result | recipient | Report actual handler disposition using crew.event-return/1. |
| reply | addressed recipient | One optional substantive bounded reply to the original initiator. |
| completion_claim | task owner | A claim with evidence, separate from verification. |
| independently_verified | independent verifier | Acceptance criteria checked against independent evidence. |
Progress may continue after an initial action disposition. The disposition is immutable: a worker that reports RUNNING uses a separately registered completion event later. A settled graph is not automatically a completed or verified job.
The event envelope
| Field | Contract |
|---|---|
| schema | weave.event/1 |
| id | Immutable occurrence identity. Duplicate identity with different content is rejected. |
| kind | Registered event type; never a permission grant. |
| sender / recipient | Exact crew, native session, account and server binding. The local tool uses isolated local service endpoints. |
| source | Bounded canonical source reference. |
| parent | Causal/correlation event ID, or null for a root. |
| body | Typed object defined by the event kind. |
| replyAllowed | Explicit boolean; control events never grant replies. |
The reference JSON envelope is limited to 65,536 bytes. Identity, kind and source are bounded strings; each endpoint component is at most 256 UTF-8 bytes. Payloads use references where content belongs elsewhere.
Statuses and response instructions
A status is a handler disposition. An optional response instruction is data for an authorized consumer; naming it does not execute it.
| Code | Status | Handling |
|---|---|---|
| 0 | pending | nonterminal |
| 1 | running | nonterminal |
| 2 | handled | terminal |
| 3 | already_resumed | terminal |
| 4 | completion_verified | terminal |
| 5 | blocked | terminal |
| 6 | operator_decision | terminal |
| 7 | stale | terminal |
| 8 | duplicate | terminal |
| 9 | no_action | terminal |
| 10 | failed | terminal |
| 11 | partial | nonterminal |
| 12 | unsupported | terminal |
| 13 | invalid_input | terminal |
| 14 | cancelled | terminal |
| 15 | deferred | nonterminal |
| Code | Response instruction |
|---|---|
| 0 | No optional response |
| 1 | continue |
| 2 | complete |
| 3 | report |
| 4 | verify |
| 5 | inspect |
| 6 | reconcile-without-replay |
| 7 | hold |
| 8 | escalate |
| 9 | checkpoint |
| 10 | resume-within-authorization |
| 11 | stop |
| 12 | provide-source |
| 13 | review-assignment |
| 14 | independent-review |
| 15 | inspect-full-record |
Codes 16–255 are available only with an explicitly registered extended response catalog. The generic event adapter accepts the initial 0–15 selections. Even COMPLETION_VERIFIED as a disposition does not create an independent verification event.
Bytes and framing
The result body has two versioned forms. Transport framing, authentication and correlation are counted separately.
Compact: SSSS RRRR 1 byte
Full: SSSS 0000 RRRRRRRR 2 bytes
ACK: 00000001 1 byte
Example: HANDLED (2), no response (0) → 0x20S is the four-bit status. R is the response selection. Reserved full-format bits must be zero. Native text uses exactly two or four hexadecimal characters; those characters are not binary wire bytes. ACK and result can share a byte value: their typed envelope distinguishes them.
Codebooks are versioned within their protocol families. Numeric IDs are not allocated from row order. Kanji presentation is separate from wire IDs and does not promise single-token encoding.
One bounded substantive reply
An initiating message may explicitly permit one optional reply from its exact addressed recipient back to its exact initiator. The reply allowance is consumed atomically with persistence.
- Optional UTF-8 text: at most 32 bytes, rejected on overflow without truncation.
- Compact result/instruction body: one or two bytes; envelope overhead is separate.
- Duplicate submissions retain the same receipt and do not consume another allowance.
- A reply grants no further reply. Control events never generate ACK chains.
- Silence is valid for optional correspondence. Required handler status remains separate.
Versioned continuation graphs
A root pins the canonical SHA-256 of its contract. Each node declares its registered event kind, exact recipient, predecessor outcomes, input reference and terminal completion kind.
| Field | Rule |
|---|---|
| schema | weave.continuation/1 |
| id / version | Named contract; positive integer version. |
| nodes | 1–64 nodes; complete contract at most 32 KiB. |
| kind | Registered non-control application event. |
| recipient | Exact endpoint binding. |
| after | Predecessor name → explicit allowed terminal status codes. All selected predecessors must satisfy their predicates. |
| input | Nonempty immutable reference, at most 1,000 UTF-8 bytes. |
| completion | action_result, or a registered non-control completion kind returning canonical terminal result and output reference. |
Successor IDs derive from the root, contract hash and node name. The root remains the parent; causes reference actual predecessor completion events. Input consumption and successor emission commit in the existing transaction. Fanout is atomic; joins wait for all required results.
A disallowed terminal result skips dependent branches. Skipping is derived graph state, not evidence that an action ran. Cycles are rejected. Cancellation, timeouts and migration need explicit semantics rather than implicit retries.
Complete local consumer contract
{
"schema": "weave.continuation/1",
"id": "local-file-verification",
"version": 1,
"nodes": {
"inspect": {
"kind": "file.inspect",
"completion": "file.finished",
"recipient": {
"crew": "weave-local-worker",
"session": "local-v1",
"account": "local-tool",
"server": "localhost"
},
"after": {},
"input": "job:input-file"
}
}
}Delivery, failure and recovery
| State / situation | Behavior |
|---|---|
| pending → sending | Commit the dispatch attempt before transport. |
| delivered | Requires a durable receiver receipt, not a successful socket write. |
| blocked | Current authorization or receiver rejection prevents delivery. |
| sending at crash → uncertain | No automatic external replay. Preserve the original identity. |
| uncertain → delivered / pending | Explicit exact evidence proves delivered or not delivered before reconciliation. |
| Local tool recovery | Exclusive ownership of all local journals permits exact inbox presence/absence proof. This does not generalize to remote effects. |
| Cross-store projection crash | Reconcile the original persisted successor IDs into the central view; do not create replacements. |
| Rejected flow | Retain the route issue and expose recordedIssue in status. A recorded issue is historical evidence, not an inferred job outcome. |
External effects need consumer-specific receipts. No universal exactly-once guarantee is claimed. A failed file job retains its evidence and remains failed; submit a new job for a new attempt.
Runtime and authorization
The existing daemon wakes on events and filesystem/native publisher notifications. Subscriptions use SSE with a reconnect cursor. Heartbeats check authorization; they do not poll worker status.
/v1/vmfactory/infrastructure/protocols/weave/runtime| Operation | Route |
|---|---|
| submit | POST /events |
| receipt | GET /events/{id} |
| inbox | GET /inbox?crew={id}&session={nativeSessionId}&after={sequence} |
| return | POST /events/{id}/result |
| subscribe | GET /stream?crew={id}&session={nativeSessionId}; SSE Last-Event-ID reconnect cursor |
| learning | GET/POST /learning; owner-authenticated practice receipts and actual adoption summary |
These routes belong to the authenticated relay, not this read-only documentation app. Submission requires current central authorization and exact endpoint bindings. Replies retain their original return allowance. Local replicas and contract registrations cannot grant crew permissions.
For a production continuation, the existing central records table holds weave_continuation:<sha256> with {contract, scheduler}. An inbox root body is exactly {continuation: sha256}. The scheduler must match its current binding. Native instruction mapping needs a separately qualified adapter.
The native bridge accepts one of the explicit status glyphs below and an optional second line of at most 32 UTF-8 bytes. Invalid status produces no inferred result; an oversized optional line does not erase a valid status.
| Glyph | Disposition |
|---|---|
| 済 | handled |
| 障 | blocked |
| 中 | running |
| 待 | deferred |
| 否 | failed |
| 疑 | operator_decision |
Change without rewriting history
Changed semantics require a new immutable contract version and hash. Existing roots keep their original pins and endpoint bindings. Stop admitting new roots when rolling back; retain journals and reconcile in-flight effects. Never retarget old roots or delete uncertain evidence.
To add a consumer, define bounded input, an executable handler, explicit terminal/output events, a recovery contract and an acceptance check. Register its event kinds and authority through the existing owning system. Qualify its real success, failure and restart paths before expanding adoption.
Sources and verification
This page is generated from the structured contracts and executable codecs. It is a reference, not a new policy authority. Runtime availability and local qualification are stated separately.
Download contracts, codec definitions and source hashes · Current event catalog
| Source | Purpose |
|---|---|
| Protocols/events/weave.json | Weave descriptor |
| Protocols/events/crew-event-system-v1.json | Lifecycle and reply contract |
| Protocols/events/weave-runtime-v1.json | Runtime API and native presentation |
| tools/coordination/weave/edrin/design.json | Continuation architecture and limits |
| tools/coordination/weave/edrin/tool-guide.json | Executable local tool guide |
| tools/coordination/weave/edrin/tool-tests.json | Retained regression evidence |
Regenerate this page with python3 -B tools/binary-messaging/playground/protocol_build.py. No image inspection was used; Jay judges the visual result.