beadboard/docs/protocols/2026-02-28-bd-audit-coordination-schema.md

BD Audit Coordination Schema (Draft)

Date: 2026-02-28
Status: Draft for skill migration planning
Scope: Replace bb coordination semantics with bd-native event/audit contracts

Related protocol baseline:

• docs/protocols/operative-protocol-v1.md

Intent

Use bd as the only required system in agent work repos. Keep coordination state in append-only audit events, and keep human context in bead comments.

Primary storage:

• protocol state: bd audit record --stdin
• lifecycle state: bd update, bd close, bd agent state, bd agent heartbeat
• narrative context: bd comments add

Why Audit-First

1. Append-only event log fits protocol timelines.
2. Dolt history gives immutable version snapshots and diffability across event evolution.
3. Frontend projections (inbox, reservation map, takeover eligibility) can be derived deterministically from event history.

Event Envelope (v1)

Every coordination event SHOULD use this envelope (JSON sent through bd audit record --stdin):

{
  "version": "coord.v1",
  "kind": "coord_event",
  "issue_id": "bb-123",
  "actor": "amber-otter",
  "timestamp": "2026-02-28T18:00:00.000Z",
  "data": {
    "event_type": "RESERVE",
    "event_id": "evt_01JN6Y1Q7R80E8P6K1Q5",
    "project_root": "/abs/path/to/repo",
    "to_agent": "cobalt-harbor",
    "scope": "src/lib/*",
    "state": "unread",
    "takeover_mode": "none",
    "reason": "",
    "payload": {}
  }
}

Notes:

• kind remains compatible with bd audit entry typing.
• protocol-specific fields live under data.
• event_id MUST be globally unique and stable for dedupe.

Canonical Event Types

Required for parity with current bb behavior:

1. SEND: directed message created (to_agent required, state=unread)
2. READ: message seen (event_ref to prior SEND)
3. ACK: message accepted (event_ref to prior SEND)
4. RESERVE: scope reservation created
5. RELEASE: scope reservation released
6. TAKEOVER: stale/evicted reservation force-acquired
7. RESUME: identity adoption event
8. BLOCKED: explicit blocker signal
9. HANDOFF: explicit transfer signal
10. INCURSION: overlap warning signal

Required Fields by Event

Shared required fields:

• event_type
• event_id
• project_root
• issue_id
• actor
• timestamp

Extra required fields:

• SEND: to_agent, payload.subject, payload.body
• READ: event_ref
• ACK: event_ref
• RESERVE: scope, payload.ttl_minutes
• RELEASE: scope
• TAKEOVER: scope, takeover_mode (stale | evicted), reason
• RESUME: payload.prior_agent, reason (uncommitted_scope | in_progress_ownership)
• BLOCKED: to_agent, payload.blocker, payload.requested_action
• HANDOFF: to_agent, payload.summary, payload.next_action
• INCURSION: scope, payload.incursion_kind (exact | partial), payload.owner_liveness

Derivation Rules (Frontend/API)

Inbox projection:

• unread: SEND with no later READ/ACK on same event_id
• read: READ exists, no later ACK
• acked: ACK exists

Reservation projection:

• active reservation = latest event for (project_root, scope) is RESERVE or TAKEOVER and not superseded by RELEASE
• owner liveness from bd agent heartbeat/state

Takeover policy:

• owner active: deny takeover
• owner stale: allow only explicit stale takeover mode
• owner evicted: allow takeover and mark prior reservation expired in projection

Dolt Considerations

1. Never rewrite prior protocol events; only append.
2. Treat projections as computed views, never source of truth.
3. Use Dolt history for postmortems (bd history/bd diff) against protocol incidents.
4. Keep schema versioned (coord.v1 -> future upgrades by additive fields and new event types).

Skill Migration Guidance (Later Work)

When updating skills/beadboard-driver, use this contract:

1. Replace bb agent send/inbox/read/ack with bd audit event writes + API-derived inbox reads.
2. Replace bb reserve/release/status with bd audit reservation events + API overlap/liveness checks.
3. Keep bd lifecycle commands unchanged.
4. Keep human summaries in bd comments for operator readability.