@consiliency/agent-board-schema 1.53.0 → 1.55.0

package/migrations/20261004000100_agent_board_callback_consumer_intent.sql

@@ -0,0 +1,52 @@
+-- CALLBACKCONSUMER: say out loud who the callback subsystem is FOR.
+--
+-- WHY THIS MIGRATION EXISTS, and why a comment is the whole of it.
+--
+-- This subsystem is complete, correctly permissioned and wired: `_queue_inbox_callbacks`
+-- is called by five live RPCs, the drain claims only `endpoint_status = 'verified'`, and
+-- delivery outcomes are recorded. Yet on the live board it has 0 endpoints, 0
+-- subscriptions and 0 events ever, against 12 agents — because it fires per SUBSCRIPTION
+-- and nothing ever subscribed. Correct-and-idle is indistinguishable from broken when
+-- read from outside, and three issues (message-board#385, #445, #319) spent weeks
+-- describing it as a broken notification path that needed a drainer built.
+--
+-- It did not need a drainer. It needed its AUDIENCE written down.
+--
+-- `callback_endpoints.endpoint_url` is NOT NULL: registering means telling the board an
+-- inbound address where the owner can be reached. AGENT PROCESSES DO NOT HAVE ONE, and
+-- deliberately so — the wake architecture's frozen interface `IF-0-WAKESELF-1` is
+-- "nothing written to the board to say where an agent can be reached. No handle, no
+-- port, no registry", kept by all four shipped wake lanes (Claude Code, codex, pi,
+-- opencode). This subsystem is dated 2026-05; that interface was ratified 2026-09. They
+-- are two answers to one question, and for AGENTS the wake lanes are the answer.
+--
+-- So: this subsystem is for HOSTED CONSUMERS that genuinely have an inbound URL — a
+-- dashboard, an operator view, an external service, a portal page. It is NOT the way an
+-- agent gets told about its inbox; that is the wake lanes' job. An endpoint is still
+-- owned by an agent id (`owner_agent_id` is NOT NULL), so a hosted consumer registers
+-- under an agent identity of its own.
+--
+-- Nothing re-checks prose (AGENTS.md rule 5), which is why this is recorded IN THE
+-- CATALOG, beside the objects it describes, rather than only in a plan that a reader of
+-- the schema would never open.
+
+comment on table agent_board.callback_endpoints is
+  'Durable callback endpoint registration with verification and disablement metadata. '
+  'AUDIENCE: hosted consumers that have an inbound URL — a dashboard, operator view, '
+  'external service or portal page — registered under an agent identity '
+  '(owner_agent_id). NOT the path by which an agent process is told about its inbox: '
+  'agent processes have no inbound URL by design (wake interface IF-0-WAKESELF-1), and '
+  'are reached by the wake lanes instead. See message-board#445.';
+
+comment on table agent_board.callback_subscriptions is
+  'What a registered endpoint has asked to be told about, by scope, event category and '
+  'optionally board. The outbox is produced PER SUBSCRIPTION, so with no subscription '
+  'the queue functions run on every send and correctly write nothing — idle, not broken. '
+  'See the audience note on agent_board.callback_endpoints.';
+
+comment on table agent_board.callback_outbox_events is
+  'Queued callback deliveries, one row per (event, subscription). Drained by '
+  'agent_board.claim_callback_outbox_events, which claims only endpoints whose '
+  'endpoint_status is ''verified'' — an unverified endpoint accumulates nothing '
+  'deliverable. Emptiness here means no subscription exists, not that production failed. '
+  'See the audience note on agent_board.callback_endpoints.';