docs(contracts): capture Milestone 1 event and persistence contracts (Step 0) #31

Merged

clawdie merged 1 commit from docs/milestone-1-contract-capture into main

2026-10-03 06:26:31 +02:00

clawdie commented

2026-10-03 06:26:15 +02:00

Owner

Freeze the Protocol 22 event and on-disk persistence contracts before any
Milestone 1 implementation, in a v2 pack separate from the frozen Phase 0 v1
fixtures.

Captured from herdr api schema --json and read-only probes of the live
herdr 0.9.3 socket:

Event naming is genuinely two-tier: events.subscribe filters are dotted
(pane.agent_status_changed) while push data.type and events.wait match use
underscores (pane_agent_status_changed). Two push envelopes exist (event,
subscription_event); neither carries a sequence number; timeout is
timeout_ms.
events.subscribe with [] is a valid no-op (subscription_started), not an
error; pane-scoped filters require pane_id; unknown kinds are rejected.
The on-disk session.json is a different contract from session.snapshot
(internal integer ids, public_*_numbers maps, a tagged layout tree).

Records the four design decisions (event envelopes, full-duplex transport,
ordering, persistence scope) and the open items, and adopts the narrow
persistence scope: exact split-tree restoration is out until a Split layout
variant is captured. No code changes; docs/fixtures only.

Freeze the Protocol 22 event and on-disk persistence contracts before any Milestone 1 implementation, in a v2 pack separate from the frozen Phase 0 v1 fixtures. Captured from `herdr api schema --json` and read-only probes of the live herdr 0.9.3 socket: - Event naming is genuinely two-tier: events.subscribe filters are dotted (pane.agent_status_changed) while push data.type and events.wait match use underscores (pane_agent_status_changed). Two push envelopes exist (event, subscription_event); neither carries a sequence number; timeout is timeout_ms. - events.subscribe with [] is a valid no-op (subscription_started), not an error; pane-scoped filters require pane_id; unknown kinds are rejected. - The on-disk session.json is a different contract from session.snapshot (internal integer ids, public_*_numbers maps, a tagged layout tree). Records the four design decisions (event envelopes, full-duplex transport, ordering, persistence scope) and the open items, and adopts the narrow persistence scope: exact split-tree restoration is out until a Split layout variant is captured. No code changes; docs/fixtures only.

clawdie added 1 commit

2026-10-03 06:26:15 +02:00

docs(contracts): capture Milestone 1 event and persistence contracts (Step 0)

verify-evidence / verify evidence reports (pull_request) Successful in 2s

Details

c56666b181

Freeze the Protocol 22 event and on-disk persistence contracts before any
Milestone 1 implementation, in a v2 pack separate from the frozen Phase 0 v1
fixtures.

Captured from `herdr api schema --json` and read-only probes of the live
herdr 0.9.3 socket:

- Event naming is genuinely two-tier: events.subscribe filters are dotted
  (pane.agent_status_changed) while push data.type and events.wait match use
  underscores (pane_agent_status_changed). Two push envelopes exist (event,
  subscription_event); neither carries a sequence number; timeout is
  timeout_ms.
- events.subscribe with [] is a valid no-op (subscription_started), not an
  error; pane-scoped filters require pane_id; unknown kinds are rejected.
- The on-disk session.json is a different contract from session.snapshot
  (internal integer ids, public_*_numbers maps, a tagged layout tree).

Records the four design decisions (event envelopes, full-duplex transport,
ordering, persistence scope) and the open items, and adopts the narrow
persistence scope: exact split-tree restoration is out until a Split layout
variant is captured. No code changes; docs/fixtures only.

clawdie merged commit cae9c8e7ec into main

2026-10-03 06:26:31 +02:00

clawdie deleted branch docs/milestone-1-contract-capture

2026-10-03 06:26:31 +02:00

clawdie referenced this pull request from a commit

2026-10-03 06:26:32 +02:00

Merge pull request 'docs(contracts): capture Milestone 1 event and persistence contracts (Step 0)' (#31) from docs/milestone-1-contract-capture into main