FMVISION / WEAVEPROTOCOL REFERENCE

THE SYSTEM, END TO END

Weave protocol

Events carry the work.
Every transition keeps its evidence.

A practical reference for the event system, its executable local tool and the contracts that connect each step.

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.

RequestDurable receiptConsumer resultNext stepClaim → verification

People keep ownership of their applications, authored worlds and judgments. Recording an event does not grant permission to act.

LayerResponsibility
EventWhat happened, who sent it, who receives it, and its cause.
ContractThe immutable version and permitted next steps.
JournalDurable inbox, outbox, evidence and recovery state.
ConsumerA registered executable handler with bounded inputs and a terminal outcome.
WireThe versioned representation used by a particular transport.

What works today

ComponentScope
Core event runtimeDurable 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 / 1Implemented and locally qualified. Finite DAG, fanout/join, immutable hash and deterministic successor IDs. Production flow activation remains separate.
Local system toolFive executable commands, one complete file-integrity consumer. 70 passing tests in the retained local suite.
Reference binary layouts40-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.

CommandBehavior
catalogList implemented commands, consumer limits and pinned contract.
submit FILE --sha256 EXPECTEDPersist a new UUID job and root request; return queued job ID. Expected digest must come from the caller.
run IDRecover 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 IDRead durable received outcome and evidence without running the job.
events IDRead 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.

ExitMeaning
0Command succeeded; inspect state for queued/pending/verified.
1Job has a recorded failed outcome.
2Invalid 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

EventOwnerMeaning
event_createdsource daemonPersist a source observation with its canonical reference.
delivery_ackreceiving daemonExact recipient context received the event. No agent action or task completion implied.
action_resultrecipientReport actual handler disposition using crew.event-return/1.
replyaddressed recipientOne optional substantive bounded reply to the original initiator.
completion_claimtask ownerA claim with evidence, separate from verification.
independently_verifiedindependent verifierAcceptance 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

FieldContract
schemaweave.event/1
idImmutable occurrence identity. Duplicate identity with different content is rejected.
kindRegistered event type; never a permission grant.
sender / recipientExact crew, native session, account and server binding. The local tool uses isolated local service endpoints.
sourceBounded canonical source reference.
parentCausal/correlation event ID, or null for a root.
bodyTyped object defined by the event kind.
replyAllowedExplicit 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.

CodeStatusHandling
0pendingnonterminal
1runningnonterminal
2handledterminal
3already_resumedterminal
4completion_verifiedterminal
5blockedterminal
6operator_decisionterminal
7staleterminal
8duplicateterminal
9no_actionterminal
10failedterminal
11partialnonterminal
12unsupportedterminal
13invalid_inputterminal
14cancelledterminal
15deferrednonterminal
CodeResponse instruction
0No optional response
1continue
2complete
3report
4verify
5inspect
6reconcile-without-replay
7hold
8escalate
9checkpoint
10resume-within-authorization
11stop
12provide-source
13review-assignment
14independent-review
15inspect-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) → 0x20

S 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.

All format layouts · Kanji vocabulary · Binary comparison

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.

FieldRule
schemaweave.continuation/1
id / versionNamed contract; positive integer version.
nodes1–64 nodes; complete contract at most 32 KiB.
kindRegistered non-control application event.
recipientExact endpoint binding.
afterPredecessor name → explicit allowed terminal status codes. All selected predecessors must satisfy their predicates.
inputNonempty immutable reference, at most 1,000 UTF-8 bytes.
completionaction_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 / situationBehavior
pending → sendingCommit the dispatch attempt before transport.
deliveredRequires a durable receiver receipt, not a successful socket write.
blockedCurrent authorization or receiver rejection prevents delivery.
sending at crash → uncertainNo automatic external replay. Preserve the original identity.
uncertain → delivered / pendingExplicit exact evidence proves delivered or not delivered before reconciliation.
Local tool recoveryExclusive ownership of all local journals permits exact inbox presence/absence proof. This does not generalize to remote effects.
Cross-store projection crashReconcile the original persisted successor IDs into the central view; do not create replacements.
Rejected flowRetain 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
OperationRoute
submitPOST /events
receiptGET /events/{id}
inboxGET /inbox?crew={id}&session={nativeSessionId}&after={sequence}
returnPOST /events/{id}/result
subscribeGET /stream?crew={id}&session={nativeSessionId}; SSE Last-Event-ID reconnect cursor
learningGET/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.

GlyphDisposition
済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

SourcePurpose
Protocols/events/weave.jsonWeave descriptor
Protocols/events/crew-event-system-v1.jsonLifecycle and reply contract
Protocols/events/weave-runtime-v1.jsonRuntime API and native presentation
tools/coordination/weave/edrin/design.jsonContinuation architecture and limits
tools/coordination/weave/edrin/tool-guide.jsonExecutable local tool guide
tools/coordination/weave/edrin/tool-tests.jsonRetained 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.