@byok-sdk/bot-collaboration 0.0.0-stage → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2058 -2
  3. package/dist/adapter-steps.d.ts +49 -0
  4. package/dist/channel.d.ts +111 -0
  5. package/dist/chunk-33YA66U7.js +7 -0
  6. package/dist/chunk-33YA66U7.js.map +1 -0
  7. package/dist/chunk-5J5SOWWI.js +12 -0
  8. package/dist/chunk-5J5SOWWI.js.map +1 -0
  9. package/dist/chunk-XTZUCECQ.js +12 -0
  10. package/dist/chunk-XTZUCECQ.js.map +1 -0
  11. package/dist/chunk-ZUFZCROA.js +27 -0
  12. package/dist/chunk-ZUFZCROA.js.map +1 -0
  13. package/dist/coalesce.d.ts +18 -0
  14. package/dist/commit-vectors.test-support.d.ts +173 -0
  15. package/dist/commit.d.ts +52 -0
  16. package/dist/compaction.d.ts +13 -0
  17. package/dist/delegation.d.ts +12 -0
  18. package/dist/delivery-routing.d.ts +63 -0
  19. package/dist/delivery-vectors.test-support.d.ts +78 -0
  20. package/dist/delivery.d.ts +20 -0
  21. package/dist/dream.d.ts +88 -0
  22. package/dist/home-projections.d.ts +5 -0
  23. package/dist/host-kit.d.ts +40 -0
  24. package/dist/host-kit.js +6 -0
  25. package/dist/host-kit.js.map +1 -0
  26. package/dist/host.d.ts +433 -0
  27. package/dist/inbound.d.ts +17 -0
  28. package/dist/index.d.ts +5 -0
  29. package/dist/index.js +16 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/k4-fixtures.test-support.d.ts +10 -0
  32. package/dist/l-test-host.test-support.d.ts +72 -0
  33. package/dist/migration.d.ts +251 -0
  34. package/dist/model.d.ts +83 -0
  35. package/dist/persona.d.ts +2 -0
  36. package/dist/retention-vectors.test-support.d.ts +17 -0
  37. package/dist/retention.d.ts +61 -0
  38. package/dist/rooms.d.ts +22 -0
  39. package/dist/routine-vectors.test-support.d.ts +81 -0
  40. package/dist/routines.d.ts +110 -0
  41. package/dist/rules/autonomy.d.ts +67 -0
  42. package/dist/rules/cards.d.ts +31 -0
  43. package/dist/rules/coalesce.d.ts +111 -0
  44. package/dist/rules/commands.d.ts +306 -0
  45. package/dist/rules/commit.d.ts +82 -0
  46. package/dist/rules/compaction.d.ts +33 -0
  47. package/dist/rules/context.d.ts +484 -0
  48. package/dist/rules/delegation.d.ts +353 -0
  49. package/dist/rules/due.d.ts +15 -0
  50. package/dist/rules/frame.d.ts +4 -0
  51. package/dist/rules/history.d.ts +34 -0
  52. package/dist/rules/inbound.d.ts +53 -0
  53. package/dist/rules/index.d.ts +13 -0
  54. package/dist/rules/index.js +4 -0
  55. package/dist/rules/index.js.map +1 -0
  56. package/dist/rules/message.d.ts +31 -0
  57. package/dist/rules/outcome.d.ts +45 -0
  58. package/dist/rules/priority.d.ts +52 -0
  59. package/dist/rules/rooms.d.ts +187 -0
  60. package/dist/rules/schema.d.ts +110 -0
  61. package/dist/rules/sync.d.ts +157 -0
  62. package/dist/rules/team.d.ts +119 -0
  63. package/dist/rules/turn.d.ts +129 -0
  64. package/dist/schema.d.ts +154 -0
  65. package/dist/switch.d.ts +53 -0
  66. package/dist/team-model.d.ts +54 -0
  67. package/dist/team.d.ts +56 -0
  68. package/dist/testing.d.ts +6 -0
  69. package/dist/testing.js +20 -0
  70. package/dist/testing.js.map +1 -0
  71. package/dist/toolset-policy.d.ts +2 -0
  72. package/dist/topology.d.ts +49 -0
  73. package/package.json +80 -4
package/README.md CHANGED
@@ -1,3 +1,2059 @@
1
- # Temporary Holding Version
1
+ # Bot collaboration
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@byok-sdk/bot-collaboration` implements K8a and K8b in the Bot PRD. A Host
4
+ installs it with the other SDK packages of the same version. It uses the K4
5
+ Host execution core (`@byok-sdk/server/execution-core`) and the K8-S public
6
+ schema and calendar APIs. It has no paid runtime call. Tests use a synthetic
7
+ adapter with the real SDK, daemon, HTTP transport, SQLite stores, and
8
+ `submit_result` helper.
9
+
10
+ ## Entries
11
+
12
+ Each symbol has one entry (#1845). K4 needs Node 24.22.1 or later, because its ledger uses `node:sqlite`.
13
+
14
+ | Entry | Contents | Loads where |
15
+ | --- | --- | --- |
16
+ | `.` | `BotCollaboration` and its option types, `botCompactVeto`, `createBotPersonaProjection`, `teamSnapshot` and its errors | Node only. It loads the L Host and `@byok-sdk/client`. |
17
+ | `./host-kit` | The L modules a Host adapter composes: model, channel, delivery, routines, team, migration, retention, dreaming, adapter steps | Node or a Worker. It loads the K4 root entry, but not the L Host or `@byok-sdk/client`. The hosted Worker example bundles it. |
18
+ | `./rules` | The pure rules that the two entries above do not export | Anywhere. It loads only `@byok-sdk/protocol` and `@byok-sdk/server/execution-core/canonical`, so no `node:sqlite`. |
19
+ | `./testing` | The shared vectors, the L test Host, and the K4 test data `policy` and `template` | Tests on Node. It needs the optional peers `vitest` and `@hono/node-server`. |
20
+
21
+ `openLTestHost` requires a `deviceCredentials` backend from the caller. In tests,
22
+ import `InMemoryDeviceCredentialBackend` from `@byok-sdk/client/testing` and pass
23
+ `deviceCredentials: new InMemoryDeviceCredentialBackend()` along with `consume`.
24
+ The fixture passes that backend to its daemon; it supplies no default.
25
+
26
+ ## Run
27
+
28
+ Use Node 24.15 or later and Bun. From the repository root:
29
+
30
+ ```sh
31
+ bun install --frozen-lockfile
32
+ bun run build
33
+ bun run --cwd packages/bot-collaboration typecheck
34
+ bun run --cwd packages/bot-collaboration test
35
+ ```
36
+
37
+ `src/host.test.ts` shows the embedded setup. Create one `BotCollaboration`
38
+ per tenant and ledger. Open that ledger with the K8 compact veto:
39
+ `new HostLedger(file, tenant, { compactVeto: botCompactVeto })`. The
40
+ constructor refuses a ledger without it ([Compaction](#compaction)). Give it a valid Agent execution template and a Host
41
+ connector. Route the embedded server's `wake.consume` to `bot.consume`.
42
+ Route its `agentMessage.consume` to `bot.consumeMessage`.
43
+ Call `bot.recover()` after startup. Call `bot.close()` before closing the SDK
44
+ server or the ledger. Do not call the K4 core's mutation methods directly.
45
+ Use `input`, `answer`, `decide`, `cancelTurn`, `enqueueHostIntent`, `cancelHostIntent`, `updateRoutine`, `setRoutineLifecycle`, `endRoutine`, `cancelDelegation`, and `abandonDelegation`.
46
+ Use `receive` for IM messages ([IM channel input](#im-channel-input)).
47
+ Use `autonomy`, `wouldDoRecords` and `setBotAutonomy` for the owner's observe/auto switch
48
+ ([Bot autonomy](#bot-autonomy-observe-and-auto-1229)).
49
+ Read `inboundDispositions` for the destination of every inbound human message
50
+ ([Inbound disposition](#inbound-disposition-1229)).
51
+ Read `snapshot` or upload K4 projections with `core.flushProjections`.
52
+ Read `inputRoot` to learn whether an `input` committed ([Input root](#input-root-1407)).
53
+
54
+ The execution template selects this Bot's Agent. It must use a runtime profile
55
+ without external-effect connector tools or ambient credentials. Required MCP
56
+ toolsets are refused by default. A Host may explicitly declare logical IDs with
57
+ `readOnlyToolsets: ['market.read']` when it controls the local tool server and
58
+ enforces read-only behavior there. The execution's `requiredToolsets` still
59
+ selects those IDs through the ordinary daemon admission path. This declaration
60
+ is not inferred from model output or MCP annotations and is not proof that a
61
+ tool has no effects. The Host connector stays outside the Agent. This example does not
62
+ provide a runtime sandbox. The deployment owns that boundary.
63
+
64
+ The constructor owns copies of execution/model templates and the allowlist;
65
+ mutating the caller's configuration later cannot widen admission. Every model, restored non-archived Bot execution and outstanding frozen intent/execution
66
+ must satisfy the policy, as must Bot creation,
67
+ updates and turn enqueue. A restart with a narrower policy fails closed when
68
+ persisted Bot templates or pending execution inputs require removed IDs. The
69
+ check covers the current Bot template, so it skips archived Bots. An archived
70
+ Bot never runs a new Turn. Its outstanding frozen work still must satisfy the
71
+ policy. Settled historical execution records remain readable. Change those
72
+ templates through an authorized Host migration before reopening; this slice adds
73
+ no migration API.
74
+ Effectful actions still use `confirmable_action` and owner confirmation.
75
+ This is the same-device read-only toolset slice of #606; external-authority
76
+ storage and two-process relay remain separate.
77
+
78
+ `bot.core` is public, but the rule to avoid direct K4 mutation calls still
79
+ holds. To run the Host's own work on this tenant's core, register a handler in
80
+ `hostIntents` and call `enqueueHostIntent(input, handler)` (#882). One ledger
81
+ transaction enqueues the K4 intent and stores the handler name, so the owner of
82
+ the intent survives a restart. A restart refuses an open Host intent whose
83
+ handler is not registered. At a `task.complete` terminal, the handler runs
84
+ synchronously in the terminal transaction with the result document. Bot output
85
+ never reaches it. The call uses the Host's own authority and bypasses Bot
86
+ policy. Its execution still passes the read-only toolset admission, because a
87
+ restart admits every open intent. A Host intent shares the FIFO of its Agent: on
88
+ a Bot's agentRef, that Bot's later Turns wait until it settles. An exact replay
89
+ returns the same intent while K4 keeps it.
90
+
91
+ An Agent message of a Host intent goes to the message handler of the same name
92
+ in `hostIntentMessages` (#1356). The handler runs synchronously in the K4
93
+ message transaction and returns the `MessageDisposition` that K4 records:
94
+ `{ outcome: 'accepted' }` or `{ outcome: 'refused', reasonCode }`. K8 does not
95
+ deliver the body; the handler delivers it with `tx.publish` or the Host's own
96
+ channel. A handler that throws rolls the transaction back, so neither K8 nor K4
97
+ writes anything, and a handler that returns a promise or another shape throws
98
+ too. An accepted message is recorded in `replies` under its task id, with the
99
+ intent key as `turnId` and no body, so a replay is accepted without the
100
+ handler. A refused message keeps its command record, so a replay gets the same
101
+ refusal without the handler and other content for the same message id gets
102
+ `message_conflict`. A Host intent whose name has no message handler refuses its
103
+ messages with `binding_mismatch`. A name in `hostIntentMessages` needs a
104
+ `hostIntents` handler. `enqueueHostIntent` refuses an execution with
105
+ `messageEgress` whose name has no message handler, and a restart refuses an
106
+ open such intent whose message handler is not registered. The pass that removes
107
+ a compacted Host intent's record also removes its replies.
108
+
109
+ Cancel a Host intent with the owner call `cancelHostIntent(key)` (#1320), not
110
+ with `bot.core.cancel`. K4 records the cancel on the intent row, so a restart
111
+ reads the same fact. An intent that was not submitted settles as `cancelled`
112
+ inside the call, which returns `{ result: 'cancelled' }`: its handler does not
113
+ run, and its FIFO moves on. A submitted or running intent gets an SDK cancel, and
114
+ the call returns `{ result: 'cancel_pending' }` at once. K4 then settles it: a
115
+ cancelled terminal runs no handler, but a `task.complete` that arrived before the
116
+ cancel still runs the handler once. Read the final conclusion with
117
+ `bot.core.intent(key)`. A settled intent returns `{ result: 'already_settled' }`
118
+ with its conclusion and sends nothing, so a replay does not fail. The call throws
119
+ `HostIntentError` with `unknown_intent` for a key that is not a Host intent and
120
+ `not_host_intent` for a Bot Turn key; cancel a Bot Turn with `cancelTurn`. A
121
+ cancel does not release a `handler_failed` intent, because K4 applies its
122
+ terminal again; `failStuckIntent` below is the way out.
123
+
124
+ A K4 terminal that K8 cannot apply leaves its intent open: a key that is neither
125
+ a Bot Turn nor a Host intent, for example from a direct `bot.core.enqueue`
126
+ (`unknown_intent`), a Host handler that throws or returns a promise
127
+ (`handler_failed`), or a Bot Turn whose outcome commit throws, for example a
128
+ document outside its frozen schema (`outcome_failed`). After the owner call, the
129
+ next sync settles such a Bot Turn as `failed` and reports it. Then `drain()` rejects with
130
+ `IntentOutcomeError`, and so does every API that runs a pass, including `input`
131
+ and the `wake.consume` hook. The audit gets one row for each key and reason. The
132
+ intent stays at the head of its FIFO until its outcome applies, for example
133
+ after a restart with a fixed handler, or until the owner calls
134
+ `failStuckIntent(key)`. That call runs a K4 drain first, so it also works right
135
+ after a restart. If that drain refuses the intent's terminal again, one
136
+ transaction settles the intent as `failed` with the K4 `settle` transition and
137
+ adds the audit row `Intent failed by owner <code>: <key> <reason>`. The settle
138
+ runs no handler, and the intent records no terminal; the server task keeps it.
139
+ The drain before the settle applies the terminal once more, so a `handler_failed`
140
+ handler runs once inside the call. If that drain applies the outcome, the call
141
+ refuses with `already_settled`. If that drain rejects and the intent has
142
+ no refusal of its own, the call throws the drain error. Later drains move past
143
+ the intent. The call settles the key first. Its closing pass, like every API
144
+ that runs a pass, rejects if another intent is stuck, and a retry for this key
145
+ then refuses with `already_settled`. A Host intent keeps its `hostIntents` record until K4 compacts it,
146
+ so an exact replay of `enqueueHostIntent` returns the failed intent. The call
147
+ refuses with `HostIntentError`: `unknown_intent` for a key with no K4 intent,
148
+ `already_settled` for a settled intent, and `not_stuck` for an intent whose
149
+ terminal K8 did not refuse, such as one still running. The settle of a Bot Turn
150
+ also writes the refusal code to the Turn as `settleCode: 'outcome_failed'`, in
151
+ the ledger and in its `bot-turn:<id>` projection, so a reader does not match the
152
+ audit row (#1405). A Host intent and a key that K8 did not write keep the code
153
+ only in the audit row. `BotOptions` passes `reconcileMs` (default 100) and
154
+ `onOutbox` to the K4 core.
155
+
156
+ ### Idempotent owner cancels (#1405)
157
+
158
+ `cancelTurn(id)` and `cancelDelegation(id)` return a result in the shape of
159
+ `cancelHostIntent`, read from the ledger, so a replay and a restart give the
160
+ same answer: `TurnCancelResult` `{ turnId, result, conclusion? }` and
161
+ `DelegationCancelResult` `{ delegationId, result, verdict? }`.
162
+
163
+ - `cancelled`: this call committed the cancel.
164
+ - `cancel_pending`: an earlier cancel has no terminal yet: the Turn's K4 intent
165
+ has a `cancelReason`, or the delegation has a cancel fact and no verdict. The
166
+ call writes nothing and does not call `core.cancel`. A cancel fact that is not
167
+ delivered yet still goes out with the next pass.
168
+ - `already_settled`: the target had ended, and the call writes nothing. A Turn
169
+ gives its earlier `conclusion` (its K4 intent's when it has one), a
170
+ delegation its `verdict`.
171
+
172
+ `cancelTurn` on B's chain Turn whose delegation has no verdict answers as
173
+ `cancelDelegation` does; once the verdict is in, it answers from the Turn. An
174
+ input batch id or a member input id names the batch Turn, and an open batch
175
+ commits its seal, so it gives `cancelled`. A Turn id that is not in the state
176
+ still throws `Turn not found`.
177
+
178
+ `cancelDelegation` refuses with `DelegationError`, whose `key` is the
179
+ delegation id: `unknown_delegation`, and `not_cancellable` for a `reply_held`
180
+ or `uncertain` delegation; end those with `abandonDelegation`. Both error
181
+ classes extend `Error`, so an `instanceof Error` check still holds, and the
182
+ messages are the same as before.
183
+
184
+ ### Input root (#1407)
185
+
186
+ `input` commits first and then runs a pass, so it can reject with a drain error
187
+ after the input committed, and the Turn still runs. `inputRoot(key, botId)` is
188
+ read-only: it returns the id that `input` returns for that key and Bot, from the
189
+ input's command record, or `undefined` when no input with that key committed.
190
+ It runs no pass, writes nothing and does not change the K8 revision, so it
191
+ gives the same answer after a restart. A record that retention moved still
192
+ answers until its row expires; the key then reads as not committed. The call
193
+ checks no principal and does not compare the request text: a replay of `input`
194
+ does both.
195
+
196
+ ## Reply visibility
197
+
198
+ A Bot reply is visible iff its Turn's intent concluded `succeeded` with that
199
+ reply's task id (#1762). The SDK accepts the reply while the Turn still runs, so
200
+ an accepted reply is not yet a Turn that happened: the Turn can still fail, for
201
+ example when the daemon stops before its outcome commits.
202
+
203
+ - K8's channel outbox follows this itself. An accepted reply's delivery is
204
+ `staged`, and no sender takes it. The outcome transaction that concludes the
205
+ intent `succeeded` promotes it to `pending`. A staged delivery whose intent
206
+ concludes otherwise becomes `rejected` with code `outcome_not_applied` at the
207
+ next sync, and its reply stays only as an audit fact.
208
+ - `replies` records every accepted reply, including withheld ones. A Host that
209
+ shows or uploads replies from `replies` checks the conclusion first: skip a
210
+ reply unless `core.intent(turnId)` has `conclusion === 'succeeded'` and
211
+ `taskId` equal to the reply's task id. For example, AiphaBee adds this check
212
+ to its `k8RootUploads` before it returns a body. A failed Turn then shows its
213
+ failure, never its reply.
214
+ - The conclusion check covers replies that K8 accepted while the Turn was
215
+ running. K4 `consumeMessage` has no conclusion check, so a message that
216
+ arrives after its intent concluded is still accepted and recorded in
217
+ `replies`, and the check passes it when the intent concluded `succeeded`.
218
+ K8 stages any delivery it queues for that message, and the next sync
219
+ withholds it as `outcome_not_applied`. The SDK daemon is not expected to
220
+ publish such a message, but a Host with a channel takes K8's delivery state
221
+ as the authority: it shows a reply only when its delivery was promoted, not
222
+ `staged` and not rejected `outcome_not_applied`. A Host without a channel has
223
+ only the conclusion check.
224
+ - A Turn that outlives its reply route token cannot answer on that route. If
225
+ the token has expired at acceptance, K8 queues the reply on the conversation's
226
+ active push route, or records `reply_route_expired` and queues nothing. If it
227
+ expires after acceptance, the promoted delivery is rejected
228
+ `reply_route_expired`, and an active push route gets a new delivery with its
229
+ own id.
230
+ - A send is at-least-once from the durable outbox. The receiver deduplicates by
231
+ the delivery id, which stays the same across resends of one row; a Host
232
+ upload deduplicates by task id, and only the task that concluded the intent
233
+ can pass the check above.
234
+
235
+ ## Would-do rows
236
+
237
+ Each would-do row names the Turn whose outcome proposed it, in `turnId`
238
+ (#1756). Retention moves the row with that Turn's root into the `wouldDo`
239
+ application rows, so `wouldDoRecords` lists only the rows of roots that are
240
+ still in the state. A Host that keeps the would-do feed longer copies the rows
241
+ before it acknowledges the root.
242
+
243
+ A ledger written by an earlier version has rows without `turnId`. Run
244
+ `migrateWouldDo(ledger)` from `./host-kit` once per ledger, before the new version
245
+ serves. It fills `turnId` from the K4 task id of each live Turn intent, over
246
+ every generation, and moves each row whose intent K4 already compacted, or
247
+ whose Turn left the state, to the `wouldDo` application rows. It returns
248
+ `{ backfilled, archived }`. `archived` counts rows that leave the feed early;
249
+ they are history of settled Turns, so no Turn reads them. A second run returns
250
+ zeros. A switch export or import refuses a would-do row without `turnId`, so
251
+ migrate the source before a switch. For example, AiphaBee runs it on each
252
+ device ledger in its runtime update.
253
+
254
+ ## Actions and context
255
+
256
+ The Host applies management actions, Main Bot delegation cancels, routine
257
+ actions, confirmation cards, questions, then delegations. Each turn freezes
258
+ the ordinary Bot schema and its ContextPack
259
+ when its K4 intent is enqueued. Waiting turns and retries reuse that frozen
260
+ input. The wait limit is five minutes before execution starts. For a routine
261
+ Turn, it counts from the occurrence record. A started
262
+ execution waits for canonical device terminal evidence.
263
+ The schema offers delegation, `ask_user`, `confirmable_action`, and the
264
+ three routine actions. It offers all current routine ids, up to eight.
265
+ It never offers a `target` field. A user input starts one
266
+ root budget. Self delegation permits four continuations for that root. A
267
+ continuation keeps the hop, authority, and open delegation of its parent.
268
+ It does not consume the Bot budget. A refused action
269
+ enters only its originating Bot's `ContextPack.rejectedActions`. Other accepted actions still apply.
270
+ A Bot in `observe` records `create_routine`, a cross-Bot `delegate` and
271
+ `room_call` instead of applying them; every other action applies as above
272
+ ([Bot autonomy](#bot-autonomy-observe-and-auto-1229)).
273
+
274
+ `BotOptions.outcome` narrows that offer (#881). `actions.turn` lists the
275
+ actions of a Bot Turn outside a room, from `delegate`, `ask_user`,
276
+ `confirmable_action` and the three routine actions. `actions.main` lists the
277
+ extra actions of an owner Main Bot Turn, from the Bot and room management
278
+ actions, `team_note` and `cancel_delegation`. A list only removes actions, and
279
+ an empty list removes all of that kind. `timeZones` holds 1 to 8 IANA zones for
280
+ `create_routine` and `update_routine`, checked by the `@byok-sdk/protocol` routine
281
+ calendar. The default is `UTC` and `America/New_York`. `confirmable` holds 1 to
282
+ 16 `confirmable_action` branches, each an action name and its draft schema. The
283
+ default is `send_message`, and the connector receives only the offered names.
284
+ Sixteen branches with the `send_message` draft and 64-byte names fit both
285
+ bounds with eight long time zones at the eight-routine limit, with room for
286
+ heavier drafts (`CONFIRMABLE_MAX`).
287
+ The constructor checks the offer and composes one schema with it. Turns that
288
+ froze before keep their schema. A room seat always gets `speech`. A schema
289
+ that is over budget blocks its Turn. The H
290
+ sync takes the same offer as `SyncOptions.offer`, a value from `outcomeOffer`.
291
+ An offer with `actions.turn` also narrows the system
292
+ prompt of a Bot Turn: it keeps only the sentences for every Bot Turn and for the
293
+ actions in that Turn's frozen schema (`systemPrompt`, `promptActions`). With only
294
+ `delegate`, the prompt names no `ask_user`, `confirmable_action` or routine.
295
+ A narrowed prompt never names `speech` or `room_call`, which only a room seat
296
+ gets. An offer without `actions.turn` keeps
297
+ `SYSTEM_PROMPT`. A narrowed prompt is shorter, so the
298
+ `minimumInstructionBytes(SYSTEM_PROMPT)` check still bounds it.
299
+
300
+ Questions support text and single choice. An answer creates an `answer` turn.
301
+ It is a new user input with its own stable budget root. Replaying the same
302
+ answer does not reset that budget. The rules that read only the outcome are
303
+ `bot-turn-outcome.v1` contract rules (#1374, #1375): blank model text after
304
+ `trim()`, a repeated option id, delegate target, `create_bot` localId,
305
+ cancel id, room member or weekday, a `create_room` admin outside its members,
306
+ an update that changes nothing, and an invalid schedule. The device refuses
307
+ such an outcome on `submit_result`, and the Host refuses it whole.
308
+ An expired card can appear in the recent ContextPack window. It creates no model turn.
309
+ A confirmation card starts as `pending`. The owner can choose `confirmed` or
310
+ `rejected`. A card becomes `expired` after 24 hours. Only a committed
311
+ `confirmed` card calls the Host connector. Confirmation results and explicit
312
+ rejection return as an `action_result` turn. Passive expiry creates no turn.
313
+ Connector success, error, and external id enter that turn.
314
+ Late and conflicting decisions return an error. Replaying the same completed
315
+ decision is idempotent. Decision projections are committed once, so uploading
316
+ them does not cause later syncs to publish them again.
317
+
318
+ The connector receives an AbortSignal and must deduplicate by the card id.
319
+ The Host enforces `connectorTimeoutMs` (default 30 seconds), even if the
320
+ connector ignores cancellation. A timeout releases the serial chain and
321
+ commits a failed action_result with an unknown external outcome. A late connector
322
+ result cannot overwrite that committed result. The Host calls the connector at
323
+ most once per card (#958): one transaction claims the call before it runs, and
324
+ the transaction that commits its result or error drops the claim. A claim found
325
+ with no result at a later pass (a crash after the call, or a failed result
326
+ commit) ends the card the same way as a timeout, with no second call. No
327
+ exactly-once external effect is claimed.
328
+
329
+ The system rules are in `src/rules/schema.ts`. K4 carries them in the instruction.
330
+ They require an acknowledgement and self delegation for long work. Final text
331
+ uses messageEgress. Progress uses messageDraft or typed activity. A failed,
332
+ cancelled, or missing-outcome continuation has a failed owner projection.
333
+ The Host publishes final turns with `owner`, source, status, and conclusion.
334
+ It does not turn an outcome document into a second chat message. K8 stores no
335
+ reply text that the user saw. In history mode the external authority gives it
336
+ as a row's `reply` (see External history authority).
337
+
338
+ `src/rules/` holds the collaboration rules as pure functions (#606, #739 D1):
339
+ room seats, input coalescing, Turns, delegation, the result schema, the
340
+ ContextPack and the order of outcome actions. They take rows and K4 intent
341
+ facts, do no I/O and import no ledger type. The ContextPack functions take the
342
+ Bot's history as an argument. This example reads that history from the device
343
+ ledger. The other `src/` files are the K8 adapter around these rules.
344
+
345
+ From K4, the rules import only `hash` and `canonical`, from the
346
+ `@byok-sdk/server/execution-core/canonical` entry (#884). That entry
347
+ imports only `node:crypto`. The K4 root entry also loads `node:sqlite` and
348
+ `node:async_hooks`, so the rules never import it. `src/rules-boundary.test.ts`
349
+ holds both rules. The rules still need `node:crypto` and the global `Buffer`.
350
+ Workers with `nodejs_compat` have both.
351
+
352
+ ## Bot autonomy: observe and auto (#1229)
353
+
354
+ A Bot's autonomous actions start in `observe`. The owner sees what the
355
+ Bot would do, then switches the Bot to `auto` per Bot. This is the
356
+ owner ruling of 2026-10-31 on #1229. It is Host policy over the same
357
+ frozen schema. K4, K8-S, the SDK wire and the protocol do not change.
358
+
359
+ | Action | observe | auto |
360
+ | --- | --- | --- |
361
+ | `create_routine` | Recorded as would-do. No K4 routine, occurrence or wake. | Applied. |
362
+ | `delegate` to another Bot | Recorded as would-do. No delegation row, `bot_request` Turn or budget unit. | Applied. |
363
+ | `room_call` of a seat | Recorded as would-do. No new round or seat. The seat's speech still applies. | Applied. |
364
+ | Self `delegate` (continuation) | Applied, as in auto. | Applied. |
365
+ | `messageEgress`, `confirmable_action`, `ask_user` | Applied, as in auto. | Applied. |
366
+
367
+ An outcome is still checked against its frozen schema in observe, and a
368
+ would-do row is keyed by `hash([taskId, 'would-do', action, index])`. So
369
+ applying the same outcome twice records one row. The row holds the frozen
370
+ action itself, never a model summary. Rows live in
371
+ `snapshot().wouldDo` and are published once as `would-do:<id>`, so a
372
+ Host UI reads either the ledger or that projection. They are Host UI
373
+ history: never in a ContextPack and never on the wire. Each row names its
374
+ Turn in `turnId`, and retention moves it with that Turn's root (#1756), so
375
+ `wouldDoRecords` lists only the rows of roots still in the state.
376
+
377
+ The default of a new Bot is `observe`. A Bot profile without the field
378
+ (an older ledger) reads as `observe` too. Only the owner principal
379
+ switches it:
380
+
381
+ ```ts
382
+ // The Host UI: the would-do feed and one switch per Bot.
383
+ const records = bot.wouldDoRecords(reviewerId); // oldest first; omit the id for every Bot
384
+ const current = bot.autonomy(reviewerId); // 'observe' | 'auto'
385
+ await bot.setBotAutonomy(reviewerId, 'auto', principal); // owner only
386
+ ```
387
+
388
+ `setBotAutonomy` writes `bot-autonomy:<botId>:<revision>` for the Host
389
+ UI. It applies to outcomes recorded after the switch. It does not replay
390
+ a would-do row. A non-owner fails with `not_owner`; an unverified caller
391
+ fails with `unverified_sender`. Both write an audit row first. The team
392
+ authority's profile does not own this field, so a team snapshot cannot
393
+ change it.
394
+
395
+ Coalesced input is a policy before enqueue: see
396
+ [User input priority](#user-input-priority-1229) for how it interacts
397
+ with queued autonomous work.
398
+
399
+ ## Routine invariants
400
+
401
+ Bot routines are K4 routines. Each one is a `hostOccurrence` definition with
402
+ the `bot-routine` hook. The K4 ledger stores the definition, the pending
403
+ version, the reserved slot, the occurrences and the wake outbox. K8 keeps no
404
+ routine state. The Host core uses `nextRoutineOccurrence` as its calendar: a
405
+ routine rule is a `RoutineSchedule` whose `tz` is the definition time zone.
406
+ K4, K8-S and the SDK all use the 368-day wake horizon.
407
+
408
+ K8 keeps the Bot policy. A Bot creates routines only for itself. Each owner
409
+ has at most eight routines that are not completed. The routine id is
410
+ `hash([taskId, 'create_routine', index])`. The hook input holds `owner`,
411
+ `authority` and `prompt`, and a new version keeps the owner and the authority.
412
+ An update must change the schedule or the prompt, and a schedule repeats no
413
+ weekday. The contract checks an outcome's routine actions; the owner
414
+ `updateRoutine` and the sealed create and reseal check the same at their entry.
415
+ The routine actions run as K4 routine commands in the outcome
416
+ commit. A refused action changes no routine.
417
+
418
+ The hook writes the routine Turn in the occurrence commit. The Turn id is the
419
+ K4 intent key `occurrence:<occurrence key>`. The next sync promotes the Turn
420
+ with `promoteOccurrence` and its frozen schema and ContextPack. Its wait limit
421
+ is five minutes from the occurrence record, not from the promotion. A routine
422
+ Turn that ends before promotion, for example on cancel or for an archived
423
+ owner, concludes its occurrence as `cancelled`. Redelivery reads the stored
424
+ occurrence and does not call the hook again.
425
+
426
+ K4 keeps a running occurrence and only the latest queued one. A new slot
427
+ settles an older queued routine Turn as `superseded`. On update, the new
428
+ version stays `pending` while an occurrence is unsettled or an old slot is
429
+ due. The old chain gets no new slot, and the version switches when that work
430
+ settles. K4 stores only the current and the pending definition; the Host
431
+ service keeps the version history. Pause cancels the reserved slot. Resume
432
+ keeps the current version while work is unsettled. Cancel marks the routine
433
+ completed and stops new occurrences. Accepted work finishes with its old
434
+ version. To stop an execution too, use K4 cancellation explicitly. Routine
435
+ results are owner turns with source `routine`.
436
+
437
+ `updateRoutine` and `setRoutineLifecycle` change only the routines of this
438
+ Host's Bot. `endRoutine(id)` runs the keyless `end_routine` command (§55c): the
439
+ Main Bot completes any open Bot routine, an archived owner's too, as cancel
440
+ does. Without it, the routine of an archived Bot would fire at every slot. The
441
+ command needs the Main Bot role and gets the K4 rows through the
442
+ `CommandPorts.routines` port.
443
+
444
+ ### Sealed Bot routines
445
+
446
+ A sealed Bot routine (#953, #654 E3d-4) is a `bot-routine` whose Turn
447
+ instruction only a member and the device can read. The owner's member endpoint
448
+ seals the whole instruction once per routine version with K4
449
+ `sealRoutineTemplate`. The instruction is `sealedRoutineInstruction(prompt)`:
450
+ the K8 Turn frame with every action, `Request:` and the prompt, and no
451
+ ContextPack, because v1 has no plaintext field for Host content next to a
452
+ sealed instruction. The Turn's frozen outcome schema stays the authority on
453
+ which actions the Bot may take.
454
+
455
+ - `sealedDefinition` makes version 1. The member picks the routine id, a fresh
456
+ UUID, because the template binds it, and an id that any routine row already
457
+ has is refused. `resealDefinition` stages the next version of a sealed
458
+ routine only. A template sealed for another version throws
459
+ `SealedRoutineVersionError`, and nothing is written. Both check that
460
+ `sealing.categories` is exactly `['task-input']`, that the template is
461
+ sealed for the Bot's current Agent revision, and that the occurrence offer
462
+ parses. A sealed routine counts toward the limit of eight.
463
+ - The authority is `owner`, and a routine stays sealed. `update_routine`, from
464
+ a Bot or the owner, is refused on a sealed routine, and the outcome schema
465
+ offers no sealed id for it. Cancel and `end_routine` complete it as any
466
+ routine.
467
+ - The view in each ContextPack shows `sealed: true` and nothing of the
468
+ template.
469
+ - The hook writes the occurrence Turn with an empty `request` and
470
+ `sealedRoutine: { routineId, definitionVersion }`. The sync freezes it from
471
+ the Host's `sealedTemplate` lookup: the Bot's execution template with
472
+ `sealing`, the template byte for byte as `sealed`, and `routineRef`, with no
473
+ `instruction`, no history and the plaintext `bot-turn-outcome.v1` contract.
474
+ K4 then promotes it as a sealed occurrence intent.
475
+ - A Turn whose template is missing (`sealed_routine_template_missing`), or
476
+ whose Bot Agent revision differs from the one the template is sealed for
477
+ (`sealed_routine_agent_changed`), ends `failed` with the projection
478
+ `sealed-routine-failed:<turnId>`. It never blocks: a blocked routine Turn
479
+ keeps its occurrence open, and that stops the version switch a reseal needs.
480
+ An outcome schema over budget depends on the state, not on the version, so
481
+ it blocks a sealed Turn as a plain one until the state shrinks.
482
+ - The outcome and every projection stay plaintext, even when they carry
483
+ content derived from the sealed instruction.
484
+
485
+ L has no sealed dispatch. Its embedded server declares no `e2ee.member`, so
486
+ no daemon paired to it advertises `sealed-payload-v1`, and its K4 port has no
487
+ `submitSealed`: L has no command that creates a sealed routine, and a sealed
488
+ intent would fail with `sealed_dispatch_unavailable` before any submit. H
489
+ runs sealed routines on a cloud tenant.
490
+
491
+ `compact` removes settled routine rows: a promoted
492
+ occurrence through its intent key, and a concluded occurrence through its
493
+ occurrence key. `botRoutines` reads the Bot routine views from the K4 rows.
494
+ Other K4 routines of the Host, for example Host jobs from `BotOptions.hostJobs`,
495
+ are not Bot routines. A Host job may return only a summary: L sets K4
496
+ `hostJobExecution: 'fail'`, so a result with `execution` concludes its
497
+ occurrence `failed` and promotes nothing, as H does, because no K8 Turn could
498
+ settle that intent. K4 alone promotes it by default.
499
+
500
+ K8 owns only Turn intents, Host intents (#882) and dream intents (#1475), so L
501
+ also sets K4 `executionRoutines: 'refuse'`; H refuses them too (#954). An
502
+ `execution` routine is refused at creation, from `bot.core.addRoutine`,
503
+ `bot.core.updateRoutine` or a Host intent handler's `tx.routines`, and no routine
504
+ row is written. The constructor refuses a ledger that still holds one that is
505
+ not completed. Only K8's own hooks promote an occurrence: the routine Turn and
506
+ `bot-dream`. Host code that needs Agent work for an occurrence calls
507
+ `enqueueHostIntent` itself, outside a Host job handler, with its own key.
508
+ `enqueueHostIntent` refuses `occurrence:<key>`.
509
+
510
+ ### Dreaming (#1475)
511
+
512
+ Each unarchived Bot with a usable model template has a dream routine: a daily
513
+ task that checks and tidies its memory against the Host's history, built with
514
+ `buildDreamInstruction`. Dreaming is on by default.
515
+
516
+ **Cost.** The default is one run per Bot per day that had a new completed Turn,
517
+ on the Bot's own model. Set `dreaming.models` to cheap templates, or pass
518
+ `dreaming: false` to turn it off for the whole Host.
519
+
520
+ ```ts
521
+ new BotCollaboration(server, ledger, { ...options,
522
+ dreaming: { timeZone: 'Asia/Hong_Kong', models: ['cheap', 'fast'], maxDurationMs: 900_000 } });
523
+ ```
524
+
525
+ - **Lifecycle.** Every sync adds the routine of a new Bot, ends the routine of an
526
+ archived Bot, and with `dreaming: false` ends them all. `recover()` is a sync,
527
+ so it does both. A routine whose template goes away later stays and records
528
+ `model_unavailable`. `dreaming: false` ends routines for good, so turning it
529
+ back on creates a new routine id with the same record. Default-on needs
530
+ `wake.consume` routed to `bot.consume` even with no Bot routines, and a Host clock
531
+ outside the years 2000 to 2200 throws in sync unless `dreaming: false`.
532
+ - **Time.** 03:00 daily, in `dreaming.timeZone`. Without it, the routine takes this
533
+ process's local zone when it is created and stores it in its definition, so a
534
+ later restart in another zone does not move it. A Host on a server should set
535
+ `dreaming.timeZone`: server clocks are usually UTC, and 03:00 UTC may be the
536
+ middle of the user's day.
537
+ - **Model.** A dream always runs on the Bot's own device, because its memory home
538
+ is there. It takes the first name in `dreaming.models` that exists in the current
539
+ `models` and is on that device. Otherwise it falls back to the Bot's own template,
540
+ with or without a list. Only the list decides what is cheap: K8 infers nothing
541
+ from a runtime name.
542
+ - **Task.** A fresh writer with `agentMemory: 'none'` and no `agentMemoryCommit`, on
543
+ every platform, and `terminalProjection: { mode: 'none' }`. The offer always sets
544
+ `agentMemory: 'none'`: with it unset, a daemon could attach the memory MCP, and a
545
+ `MEMORY.md` over its limit would then fail the dream before it starts, though the
546
+ dream is what repairs it. There is no rollback, so the instruction orders every
547
+ step to leave usable memory. It carries no message egress and no toolsets, and
548
+ drops the template's `homeAccess`, `preparation` and `agentMemoryCommit`.
549
+ - **Memory paths.** The task is not `homeAccess`, so its cwd is the Bot's home. In
550
+ `none` mode the device injects no `MEMORY.md` and no memory guidance.
551
+ `MEMORY.md` and `notes/` in the instruction resolve from the cwd, and the runtime
552
+ uses its own file tools.
553
+ - **Input.** The Bot's completed Turns after the last successful dream's mark, up
554
+ to the first Turn that is still queued or processing, so a Turn that user input
555
+ overtook is covered by a later dream. A blocked Turn does not stop the run; if it
556
+ later completes, no dream covers it. With `BotOptions.history`, K8 reads the rows
557
+ there with `turnId` set to the dream's intent key. The mark advances only through
558
+ the settled rows that history returned. A failed read skips that day; no completed
559
+ row read after the mark skips it with `no_new_turns`, leaving the mark unchanged,
560
+ just as in K8-state mode. A Bot whose history authority never returns completed
561
+ rows never dreams. The pack fills what `instructionMaxBytes` leaves after the fixed text.
562
+ The first dream window starts when dreaming was set up for the Bot; older Turns
563
+ of an upgraded ledger still go into its pack.
564
+ - **Native sessions.** `dreaming.nativeSessions` defaults to `true` and requests
565
+ native session input for the same window when the device advertises support.
566
+ Set it to `false` to omit the request. The device switch is off by default;
567
+ see [Native session input](../../docs/security.md#native-session-input) for
568
+ what it sends to the configured model provider.
569
+ - **Queue.** A dream joins the Bot's FIFO behind the Turns of its sync, and user
570
+ input goes ahead of a dream that has not started (#1229). A running dream is not
571
+ interrupted, so user input waits for it, at most `maxDurationMs` (default 15
572
+ minutes). A queued dream waits at most an hour, and a newer slot supersedes it.
573
+ - **Record.** `snapshot().dreams.bots[botId]` holds `since`, `throughTurn` and `last`:
574
+ the occurrence's outcome, its reason, the template and whether it was a fallback.
575
+ A dream that does not succeed leaves `since` and `throughTurn`, so the next one
576
+ covers the same Turns. A skip concludes its occurrence `cancelled`, with one of
577
+ `no_new_turns`, `model_unavailable`, `history_unavailable`, `bot_not_ready`,
578
+ `bot_archived`, `bot_suspended`, `device_unavailable`, `dreaming_off` or
579
+ `superseded` (concluded `superseded`).
580
+ - **Owner.** `dreams.open` owns each dream intent, so its terminal never reaches a
581
+ Host intent handler. `cancelHostIntent` and `failStuckIntent` refuse it.
582
+ - **On H.** H does not run dreams yet. An owner switch moves the routines and the
583
+ record, and H concludes each `bot-dream` occurrence `cancelled` with no task,
584
+ recording `H does not support dreaming yet`. A dream queued or running at export
585
+ blocks it like other open work, until it settles.
586
+
587
+ ### Compaction
588
+
589
+ A Turn id is its K4 intent key. K8 reads the intent of a Turn after K4 settles
590
+ it: the next pass copies the conclusion into the Turn, and delegation, room and
591
+ reply checks read it later. So `botCompactVeto` refuses an acknowledged key
592
+ while one of these holds:
593
+
594
+ - its Turn is not concluded, or the Turn still has its K4 intent and its
595
+ conclusion is not reported;
596
+ - a delegation without a verdict has the Turn in `chainTurnIds` or as
597
+ `cancel.targetTurnId`, or any delegation has it as `lateTurnId`;
598
+ - its room seat is not released;
599
+ - one of its reply receipts is not settled: K4 does not hold the receipt for
600
+ message replay, or a delegated reply body has no verdict yet;
601
+ - it is the intent of a dream that the sync has not closed (`dreams.open`), so
602
+ the dream's result is not in K8 yet.
603
+
604
+ K4 runs the veto inside `compact`'s own transaction. A refusal throws
605
+ `CompactVetoError` and changes nothing. Retry the key after a later pass.
606
+ Any other key without a Turn, for example a Host job, is not a K8 key.
607
+
608
+ The veto guards each `HostLedger` instance that has it. Another instance on
609
+ the same file without the veto can still compact a Turn intent early. Then the
610
+ next pass fails that Turn with conclusion `failed`, because K8 did not see the
611
+ K4 result. It writes an audit line and reports the Turn once, with
612
+ `reason: 'result_retired'`. The Turn fails even when K4 already applied its
613
+ outcome, because K8 does not read the K4 application tombstone. A routine
614
+ Turn's intent tombstone expires with its slot. K4 removes the occurrence with
615
+ the intent, so the pass also fails a routine Turn whose occurrence is gone,
616
+ after its tombstone expired. The check runs before the archived Bot check, so a
617
+ retired Turn of an archived Bot also fails with `result_retired`. The archived
618
+ Bot check cancels only a Turn that has no conclusion. A retired room seat Turn
619
+ also releases its seat as `failed`, with reason `result_retired`, so its round
620
+ moves on. At Host start, a business reply receipt of a compacted Turn stays,
621
+ also for a routine Turn after its tombstone expired. A due reply check of a compacted chain intent takes
622
+ the failed readback path. The Host keeps processing other work.
623
+
624
+ ### Retention
625
+
626
+ Every transaction reads and rewrites the collaboration state, so settled
627
+ history must leave it. `bot.retain({ acknowledgedRoots, now, retentionMs })`
628
+ does that on the Host's explicit acknowledgement. It never runs on its own.
629
+
630
+ - A root is the `root` field of a Turn projection, the round root that
631
+ `roomInput` and a room `receive` return, or the `root` field of a
632
+ `room-seat:` or `room-root:` projection. One root holds its Turns,
633
+ budget, delegations and their batches and units, replies, schemas, cards,
634
+ questions, the rejections that its Turns consumed, its input batch and
635
+ inputs, its rounds with their seats, seat Turns and `team.roots` row, its
636
+ inbounds, and the deliveries that its Turns queued (each delivery stores
637
+ its `turnId`). A seat Turn belongs to its round's root, but
638
+ its projection shows its seat id as `root`. Acknowledging a seat id throws
639
+ `RetentionRefused` with code `seat_root` and the round's root in
640
+ `roundRoot`. Acknowledge that root instead.
641
+ - One ledger transaction moves every row of each acknowledged root into K4
642
+ application rows by map name and id (the K4 row port). It retires the
643
+ root's Turn, input and round ids for good.
644
+ - `RetentionRefused` with code `protected_root` rolls back the whole call while a
645
+ root is still in use: a Turn that is not concluded, or that still has its
646
+ K4 intent and is not reported; an unresolved delegation, an unreleased
647
+ batch or a reserved unit; an open card or question; an open input batch; an
648
+ open round or seat; an open delivery or a live reply route; an open routine
649
+ occurrence; or a Turn, card or question in the ContextPack window of its
650
+ Bot (the Turns from the oldest turn of its handoff pack to its newest, and
651
+ the last 12 cards and questions, bounded by `contextTurnLimit`).
652
+ Unconsumed rejections stay in the state.
653
+ - An unknown root throws. A root that is already archived counts as
654
+ `alreadyArchivedRoots`.
655
+ - Each call also moves the command records of archived roots and the records
656
+ with no root. They answer replays for at least `retentionMs`, which must be
657
+ seven days or more; a later call removes them after that. A retry after the
658
+ window decides again, and an archived Turn, input or round id makes the
659
+ commit throw `RetiredIdentityError` and change nothing. A store makes that
660
+ check itself: `commitCommand` hands the ids that `decide` added to
661
+ `CommandStore.admitted`, and the store calls `refuseRetired` before it
662
+ commits. Sync fails a Turn with a retired id instead of running it. A Turn
663
+ id and an input id are one identity space (`retiredIdentity`): an input
664
+ that does not coalesce becomes a Turn with its own id, and the coalescing
665
+ policy can change between retention and a retry.
666
+ - The handoff pack of the window leaves out the Bot's Turns that can still
667
+ freeze (queued or blocked), and its total is at least `recentBytes +
668
+ earlyBytes` plus the pack frame, so `earlier` always gets all of `earlyBytes`.
669
+ A freeze has no more than that, a Cross-Bot Turn often less, and the Turns it
670
+ adds only start `earlier` at a newer turn, so no freeze reads a turn older
671
+ than the window. `Host.retain` uses the `handoff` budgets of a freeze, and
672
+ `RetentionLimits.handoff` is required, so a store that calls `retainRoots`
673
+ passes the budgets it freezes with. Room messages and rejections still go by
674
+ `contextTurnLimit`.
675
+ - Each call moves the audit lines, revoked push routes that no delivery uses,
676
+ and settled persona deliveries: applied ones except the newest of each Bot,
677
+ and failures of an older profile revision. These archived rows stay.
678
+ - `historyWindow.omitted*` counts only rows still in the state.
679
+ - Each call moves the room messages of archived roots to application rows in
680
+ namespace `roomMessages`, by message id, with or without `roomHistory`. The
681
+ last `contextTurnLimit` messages of each room stay, because a seat
682
+ ContextPack reads at most that many. A message of a root that is still in
683
+ the state stays too. The same call recomputes `visibleFrom`: it is an offset
684
+ in the kept list, so each member sees the same kept messages as before. The
685
+ state, and so a snapshot, no longer holds the whole room history.
686
+ `historyWindow.omittedMessages` and `notice` of a seat ContextPack count only
687
+ messages still in the state, as `history.omittedTurns` does; a count over moved
688
+ messages would need a stored count for each Bot.
689
+
690
+ After retention, a late message for an archived Turn gets `binding_mismatch`,
691
+ and an echo can no longer match an archived delivery. Back up the whole SQLite
692
+ database: a JSON-only restore loses the archived rows and tombstones.
693
+
694
+ `CollaborationState.version` is 3. Version 1 kept the routines in K8 state.
695
+ The Host refuses a version 1 ledger and changes nothing. Restore a ledger
696
+ backup made before this change, or start a new ledger.
697
+
698
+ The Host drains application commands until all new turns have a K4 intent.
699
+ An immediate terminal cannot leave a continuation without a wake.
700
+ K4 schedules and cancels routine wakes through its outbox. A resume of the
701
+ same key replaces a pending cancel with the schedule, so the SDK holds one
702
+ wake. A failed SDK wake call rejects the K4 drain, and the Host call that
703
+ started it rejects after its commit. The K4 outbox keeps the row with
704
+ `lastError`. The K4 retry timer retries it with backoff from 1 s to 60 s, for
705
+ at most about 5 min, and each later drain, wake delivery or `recover()` also
706
+ retries it. A failed K4 drain does
707
+ not stop the rest of its process pass, and the pass arms the timer, so card
708
+ expiry, delivery retries, reply checks, seat deadlines and input batch seals
709
+ keep their times. The pass then rethrows the drain error. Startup schedules a reserved wake that the SDK
710
+ no longer holds. K4 rejects a wake whose time differs from its reservation,
711
+ and the SDK delivers it again. K4 records an unknown, inactive or superseded
712
+ wake in `ignoredWakes`. Calendar errors stop the chain, record an audit, and
713
+ let the accepted occurrence finish. Pause and resume retry the calendar.
714
+
715
+ ## Boundaries
716
+
717
+ The collaboration state has version 3. The Host rejects version 2, unsupported
718
+ and unversioned stored state. It does not reset or migrate that state. A
719
+ version 2 ledger cannot hold archived rows, so restore a ledger backup made
720
+ before this change, or start a new ledger.
721
+
722
+ This example has one team and one owner per ledger. Paid Pi success-rate
723
+ measurement belongs to [WO-10b](../../docs/submit-result-measurement.md); the method defines per-runtime/model/platform cells and does not supply live data. Retention of the
724
+ collaboration history is explicit ([Retention](#retention)). K4 routine
725
+ versions have no retention policy in this small example.
726
+
727
+ ## Commit contract
728
+
729
+ Each collaboration command goes through one commit (#739 D1,
730
+ `src/rules/commit.ts`). A commit takes a scope, a command id, an optional
731
+ expected revision and the command. It returns the new revision, the
732
+ disposition and the outbox rows that it wrote. One store transaction holds
733
+ the state change, the command record and the outbox rows.
734
+
735
+ - A replay of a command id with the same evidence returns the first result
736
+ and changes nothing. The evidence is the hash of the fields that decide the
737
+ command's effect.
738
+ - The same command id with other evidence is an `identity_conflict`. The Host
739
+ keeps the existing error text, for example `Input identity conflict`.
740
+ - Without an expected revision, the commit decides on the head. An explicit
741
+ revision that is not the head is a `stale_revision` conflict. A replay is
742
+ checked first, so a retry with its original revision gets its first result.
743
+ - The revision counts committed commands only (#739 6b). Each new commit adds
744
+ 1, also for a refused disposition. A command that throws commits nothing.
745
+ Host passes that only apply evidence (sync, reconcile, reply checks,
746
+ deliveries, device refresh) do not change the revision.
747
+ - A keyless command has no record (#739 6a). Each call applies and adds 1 to
748
+ the revision, so its command id is not a dedup key. Only an explicit expected
749
+ revision protects a retry: the first commit moved the head, so the retry is a
750
+ `stale_revision` conflict.
751
+
752
+ The keyed commands are owner input, received IM input, room input, answers,
753
+ card decisions, team snapshots, and three K4 callbacks: a terminal outcome, an Agent message
754
+ and a Bot routine occurrence. The keyless commands are `setMainBot`,
755
+ `updateRoom`, `retryPersona`, `personaReady`, `enablePushRoute`, `revokePushRoute`,
756
+ `resendDelivery`, `cancelDelegation`, `abandonDelegation`, `cancelTurn` and `endRoutine`.
757
+ A `cancelTurn` or `cancelDelegation` that answers `cancel_pending` or
758
+ `already_settled` commits nothing ([idempotent owner cancels](#idempotent-owner-cancels-1405)).
759
+ `src/rules/commands.ts` decides all of them. The Host checks the principal
760
+ and the channel before the commit, and it calls K4 cancel and delivers cancel
761
+ facts after the commit. `updateRoutine` and `setRoutineLifecycle` are K4
762
+ commands on K4 rows and do not commit here; `endRoutine` commits `end_routine`,
763
+ whose port runs K4 `setLifecycle`.
764
+
765
+ In this L example the scope is the ledger tenant. Owner APIs pass no expected
766
+ revision. K4 already deduplicates terminals (`applied`) and accepted messages (the
767
+ message receipt), so L stores no record for those callbacks. K4 writes no
768
+ receipt for a refused message, so L keeps a record for it: a retry gets the
769
+ same refusal and does not change the revision. When retention moves that
770
+ record, the message hook reads it from the K4 rows of its own transaction. Other content for the same
771
+ message id is refused with `message_conflict`. The D1 vectors in
772
+ `src/commit-vectors.test-support.ts` run against a pure in-memory store and
773
+ against the L ledger; the D2 H adapter runs the same vectors.
774
+
775
+ ### Sync step
776
+
777
+ A sync step freezes the offer of a Turn without an intent, and settles the
778
+ Turn of a concluded intent (#793 D2b). `syncTurn` in `src/rules/sync.ts`
779
+ decides it for one Turn. `src/rules/commands.ts` exports it with the
780
+ commands. The rule changes the state, publishes projections and returns the
781
+ write for the store:
782
+
783
+ - `freeze`: store this intent input (`key`, `source`, `waitUntil`,
784
+ `execution`). The rule sets `waitUntil` to `now` plus 5 minutes.
785
+ - `routine`: a routine Turn joins the FIFO as its occurrence intent.
786
+ - `cancel`: the Bot is archived. Cancel the intent, which has not started.
787
+ - `ended`: the Turn has no intent and is concluded. A routine Turn concludes
788
+ its open occurrence.
789
+
790
+ A Host that binds devices gives the step the optional fact
791
+ `deviceRefusal(botId)` (#956, §55a): `unbound`, `revoked`, `mode` or
792
+ `switching` for the device of the Bot's current execution template, which a
793
+ freeze would use. The step then holds that Bot's Turns that have no intent: it
794
+ returns no write, sets `held` on the Turn, publishes the hold once, and adds an
795
+ audit row with the reason. `unbound`, `revoked` and `mode` hold with
796
+ `device_not_bound` and publish `held:<turnId>`; `switching` (#957) holds with
797
+ `device_switching` and publishes `held-switching:<turnId>`. Each body is
798
+ `{ owner, turnId, code }`. The rest of the scope syncs. The hold comes before
799
+ the profile check, since a refused device may never apply a profile. The next
800
+ sync with no refusal (the device is bound, or a `team_snapshot` moved the Bot)
801
+ clears `held` and freezes the Turn with the current template. A held room
802
+ seat Turn waits for its seat deadline, as any seat that does not start. Each
803
+ hold code has its own projection id with one body, so a changed reason never
804
+ conflicts. L sets the fact from its topology records (see "Topology switch").
805
+ `DEVICE_NOT_BOUND` is H's `DeviceBindingError` code.
806
+
807
+ A store runs the step for each stored Turn, in insertion order, in one
808
+ transaction under the same scope lock as a commit. It reads the facts inside
809
+ that transaction. The projections that the step publishes reach the store's
810
+ outbox in the same transaction. A projection with the same id and the same
811
+ body adds nothing. Another body for that id throws `Projection identity
812
+ conflict`. The step is a Host pass that only applies evidence, so it writes
813
+ no command record and keeps the revision. A client's expected revision does
814
+ not go stale because of a sync. If one Turn throws, the store writes nothing.
815
+ L runs the step in its sync transaction through `syncTurnInLedger`
816
+ (`src/commit.ts`), which keeps the K4 writes: `enqueue`, `promoteOccurrence`,
817
+ the intent cancel and the occurrence conclusion. The L sync transaction also
818
+ runs other Host steps before and after the per-Turn steps. Before them, it
819
+ seals due input batches, expires pending cards and advances rooms. After
820
+ them, it settles delegations, reports card decisions and adds their action
821
+ result Turns, cleans reply tokens and projects input batches. The card steps
822
+ are the K8 rule `src/rules/cards.ts` (`expireCards`, `reportCardDecisions`),
823
+ which the `cardVectors` hold for L and H. This contract
824
+ defines only the per-Turn step. The `syncVectors` in
825
+ `src/commit-vectors.test-support.ts` hold these rules for the in-memory store
826
+ and for L. The `coalesceVectors` there hold the batch seal before the
827
+ per-Turn steps and the batch projection after them, for L and H.
828
+
829
+ `collaborationDue(state, timers)` in `src/rules/due.ts` lists the times when a
830
+ sync has collaboration work to do: each open input batch's seal, each pending
831
+ card's expiry, each unreleased seat's deadline, and the delegation times
832
+ (`delegationDue`). `src/rules/commands.ts` exports it. L arms its timer with
833
+ these times and its own L-only ones. H stores their minimum as the scope's due
834
+ time (#793 S4). Routine slots are K4's, so they are not in the list.
835
+
836
+ The room step of a Host sync is `advanceRoomSeats(state, facts, now, add, publish)`
837
+ in `src/rules/rooms.ts` (#793 S6). It runs `advanceRooms` on the seat facts,
838
+ fails a seat Turn whose work was not admitted, queues each new seat Turn
839
+ through `add` (`seatTurn` gives its fields), publishes the room projections
840
+ of the seats that became terminal through `publish`, and returns the seats
841
+ whose admitted work the Host cancels. `src/rules/commands.ts` exports both. L builds
842
+ the facts from its K4 intents; H builds them from its intent rows. A Turn
843
+ step can release a seat (a blocked or retired seat Turn). Both Hosts then run
844
+ the room step and the Turn steps again in the same sync, so the next seat gets
845
+ its Turn: L in `advanceRoomsAndTurns` (`src/rooms.ts`), H in its sync loop.
846
+ The `roomVectors` run on both.
847
+
848
+ `checkReply(state, d, check, now, emit, uncertainAfterMs)` in
849
+ `src/rules/delegation.ts` decides one reply check of a `reply_pending`
850
+ delegation: a reply body that the Host holds answers it, a failed read
851
+ retries with backoff, and otherwise the SDK readback decides.
852
+ `replyCheckDue(d, now)` selects the due checks. `src/rules/commands.ts`
853
+ exports both. L's `flushReplies` runs them with its own SDK read, and H runs
854
+ them in `HostedReplyChecker` (#793 S7). The `replyVectors` hold the decision
855
+ for L and H.
856
+
857
+ Known L limit: K4 stores the whole Host ledger, with the collaboration state,
858
+ in one JSON row per tenant. Turns, replies, audit rows and command records
859
+ make that row grow. Command records are dedup evidence; retention must not
860
+ delete a record while a retry of its command can still arrive. Per-entity L
861
+ storage and K8 retention are #798.
862
+
863
+ ## External history authority
864
+
865
+ With the `history` option, the ContextPack history of a Bot Turn comes from an
866
+ external authority, not from this ledger (#739 D1, #606). Before a Bot Turn
867
+ freezes its offer, the Host reads the Bot's earlier history outside the ledger
868
+ transaction. Then one transaction freezes the offer with those rows. The
869
+ transaction freezes only a Turn that still has no offer.
870
+
871
+ - The authority returns rows in the ContextPack row shape: `id`, `root`,
872
+ `source`, `request`, `hop`, `status`, optional `conclusion`,
873
+ `outcomeSummary`, and optional `reply`, the reply text that the user saw for
874
+ that Turn (#1318). Rows in another shape are refused, as is a `reply` that
875
+ is not a string.
876
+ - `historyRowFromTurn` builds one row from a `bot-turn:<id>` projection value
877
+ and the caller's `reply`, so the authority does not derive `outcomeSummary`
878
+ itself. `contextTurns` checks rows in this shape and returns them as
879
+ `ContextTurn[]`. The K8 entry exports both and the `ContextTurn` type
880
+ (#1356).
881
+ - A row's `request` and `reply` become the lines of its turn in `history`, and
882
+ the handoff budgets bound them as for stored Turns (see
883
+ [Group chat and Main Bot](#group-chat-and-main-bot)).
884
+ - The rows replace the stored Turns in that ContextPack. The current Turn
885
+ always comes from this ledger.
886
+ - The collaboration state does not store the rows. The Turn keeps their hash
887
+ in `historyDigest`, which covers `reply`. K4 keeps the frozen instruction
888
+ of the offer, as for every offer.
889
+ - Cards, questions and rejected actions stay Host state. Room seats read room
890
+ messages, so they read no history.
891
+ - A read that throws or returns another shape leaves the Turn queued. The
892
+ timer reads again after about one second.
893
+ - A read still open after `historyTimeoutMs` (default 10 seconds) counts as
894
+ failed, so a stalled authority cannot hold the Host queue. The Host does
895
+ not abort the read. Reads run one after another, so a pass waits at most
896
+ `historyTimeoutMs` for each Turn that reads.
897
+
898
+ With the `roomHistory` option, the room messages of a seat ContextPack come
899
+ from an external authority too (#883). Before a seat Turn freezes its offer,
900
+ the Host calls `roomHistory({ roomId, botId, turnId })` outside the ledger
901
+ transaction, in the same phase as `history`.
902
+
903
+ - The authority returns the messages that this seat's Bot can see, oldest
904
+ first, as `{ id, from, text, late }` rows. The authority selects them for
905
+ that Bot, so K8 applies no `visibleFrom` of its own. Rows in another shape
906
+ are refused.
907
+ - The rows replace `room.messages` in that ContextPack, in the same message
908
+ window. The state does not store them. The seat Turn keeps their hash in
909
+ `historyDigest`.
910
+ - K8 still writes `room.messages`. Round counts, mention seats and the seat
911
+ request text read it.
912
+ - A read that throws or returns another shape leaves the seat queued, and the
913
+ timer reads again. A read still open after `historyTimeoutMs` or at the
914
+ seat deadline counts as failed.
915
+ The seat deadline still applies, so a seat whose read never succeeds is
916
+ released as `busy` and its Turn expires.
917
+ - Each accepted seat post also publishes the projection
918
+ `room-message:<roomId>:<messageId>` with `{ roomId, id, from, text, late }`,
919
+ the row that `room.messages` stores. The message id is the seat id, so a
920
+ replay has the same id and body; the uploader delivers it at least once, and
921
+ the Host deduplicates by id. A `pass` and a refused post publish no
922
+ `room-message:` projection; their seats have `room-seat:` projections.
923
+ Without the option, no `room-message:` projection exists.
924
+ - The next seat of a room is not read while that room has an undelivered
925
+ `room-message:` projection. K4 drops a projection only after the Host
926
+ uploader's `deliver` resolved, so the Host's `deliver` must resolve only
927
+ after its write can be read back from the authority. The held seat waits
928
+ like a failed read, and its deadline still applies: a projection that never
929
+ delivers releases each later seat of its room as `busy` at its deadline.
930
+ - Room input that the Host gives K8 (`roomInput`, or `receive` for a group
931
+ message) is not projected. The Host writes it to its authority first, then
932
+ calls K8, so the next seat reads it.
933
+ - The ledger does not store the mode. Each time a Host turns the option on, it
934
+ first writes the posts made while it was off to its authority, deduplicated
935
+ by id. Turn the option on before the first retention: retention moves the
936
+ room messages of archived roots out of `snapshot().team.rooms` (see
937
+ Retention). After a retention, the backfill also reads the archived rows of
938
+ namespace `roomMessages`, which the owner switch export carries in its
939
+ `archived` section.
940
+
941
+ The team comes from this ledger, unless the `team: 'external'` option is set.
942
+
943
+ ## External team authority
944
+
945
+ With `team: 'external'`, an external authority owns the Bots (#739 Q4c). The
946
+ constructor creates no Main Bot. The authority sends team snapshots with
947
+ `applyTeam({ revision, bots })`. Each Bot has `id`, `name`, `role`,
948
+ `persona`, `model` and `mainBot`. The Host maps `model` to its own execution
949
+ template.
950
+
951
+ - The team revision is the authority's revision. It is not the collaboration
952
+ commit revision. It must be a safe integer of 1 or more, and each new
953
+ snapshot must have a higher revision.
954
+ - A newer snapshot archives each Bot that it does not list, as `delete_bot`
955
+ does. A new Bot gets its first persona projection. A changed name, role,
956
+ persona or model queues the same projection as `update_bot`. A change of the
957
+ Main Bot flag only sets the flag.
958
+ - An archived Bot cannot come back. A snapshot that lists one is refused, and
959
+ nothing changes.
960
+ - The command id is the team revision. The same revision with the same Bots
961
+ replays, in any Bot order. The same revision with other Bots is an
962
+ `identity_conflict`. The replay check comes first, so an exact retry of an
963
+ applied older snapshot gets its first result.
964
+ - A revision that is not newer and was not applied before refuses with
965
+ `stale_team`. The refusal is a commit, so it adds 1 to the collaboration
966
+ revision.
967
+ - The snapshot covers the Bots only. `setMainBot`, `create_bot`, `update_bot`
968
+ and `delete_bot` refuse with `external_team`, and the Main Bot schema does
969
+ not offer those three actions. Team notes and persona retries stay local.
970
+ Rooms stay local too, unless the external rooms mode below is on.
971
+ - The ledger stores the mode. A ledger with a local team cannot open in
972
+ external mode, and an external ledger cannot open without the option.
973
+
974
+ A snapshot Bot can carry `participation: 'suspended'` (#1319). The Bot stays in
975
+ the team, its rooms and its routines, but takes no new K8 work. `participation`
976
+ is `'suspended'` or absent; any other value refuses the whole snapshot as
977
+ `Invalid team snapshot Bot`, and nothing changes. A suspended Bot:
978
+
979
+ - leaves the `delegate.to` and `room_call` member lists of every schema frozen
980
+ after the snapshot, and gets no room seat, even when a message names it;
981
+ - ends its open work as an archived Bot's does: a Turn that has not frozen
982
+ concludes `cancelled`, a frozen intent that has not started is cancelled, and
983
+ work that started runs on with its outcome kept as audit only. An open
984
+ delegation to it resolves `refused` with reason `target_suspended`; a verdict
985
+ for a delegation that it started gets no reply Turn
986
+ (`undelivered: 'initiator_suspended'`);
987
+ - refuses `input`, an owner `receive`, `answer` of its question and `decide` of
988
+ its card with `TeamModeError` code `bot_suspended`
989
+ (`bot_suspended: Bot <id> is not participating`), and the commit writes
990
+ nothing. `setAutonomy`, `persona_ready` and push routes stay available.
991
+
992
+ A later snapshot without the field restores the Bot as it was: its profile
993
+ revision, `readyRevision`, autonomy, room memberships and routines are kept.
994
+ Work cancelled or refused while it was suspended, and routine slots that it
995
+ missed, do not come back. Archive stays for a deleted Bot: a suspended Bot that
996
+ a snapshot no longer lists is archived.
997
+
998
+ With `persona: 'external'` as well, the Host owns the persona projection of
999
+ each Bot (#879). The Host projects the Agent home with its own daemon hook, so
1000
+ there is one projection writer and one revision for each agentRef.
1001
+
1002
+ - Each snapshot Bot carries the Host's `profileRevision`, a decimal string.
1003
+ K8 uses it as the Bot revision and as the agentRef `profileRevision` of its
1004
+ execution. K8 queues no projection and counts no revision of its own.
1005
+ - The revision never goes back. A changed name, role, persona or model needs a
1006
+ newer revision. A snapshot that breaks either rule is refused, and nothing
1007
+ changes. Without the option, a snapshot with `profileRevision` is refused.
1008
+ - `personaReady(botId, revision)` reports that the Host applied this revision.
1009
+ The current revision readies the Bot, an older one changes nothing, and a
1010
+ newer one refuses. A Bot's Turns freeze their offers only when it is ready,
1011
+ as before. After a newer revision, the Bot keeps its last ready revision, so
1012
+ it stays a delegate target while its Turns wait. The Host reports
1013
+ `personaReady` only after the snapshot that introduces that revision
1014
+ resolves: an earlier report is refused, not stored.
1015
+ - `retryPersona` refuses with `external_persona`.
1016
+ - The ledger stores this mode too, so a restart cannot change it. The mode is
1017
+ fixed once stored, with no migration. The option needs `team: 'external'`.
1018
+
1019
+ With `rooms: 'external'` as well, the team snapshot also owns the rooms
1020
+ (#1321). Each snapshot carries `rooms`, the authority's whole room list, and
1021
+ `applyTeam({ revision, bots, rooms })` writes it after the Bots. Without the
1022
+ mode, a snapshot with `rooms` is refused; with it, a snapshot without `rooms`
1023
+ is refused, and nothing changes.
1024
+
1025
+ - A room has `id`, `name`, `members`, and optionally `admin`, `mode`,
1026
+ `announcement` and `memberMentions`. The id matches
1027
+ `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` and is not an `Object.prototype` key.
1028
+ The rules are those of `create_room`, with one difference: a room can have
1029
+ no member. Its members are Bots of the same snapshot, 0 to 12 and distinct,
1030
+ and its admin is a member. `mode` is `mention` or omitted, `memberMentions`
1031
+ is `execute`, `ignore` or omitted. A snapshot holds at most
1032
+ `TEAM_ROOM_LIMIT` (64) rooms, and room order is not content.
1033
+ - A new room starts with no visible history for its members. A listed room
1034
+ takes the snapshot's fields as a whole: an omitted admin, announcement or
1035
+ `memberMentions` is cleared, and `memberMentions` returns to `execute`. A
1036
+ member that stays keeps its visibility, a new member sees messages from now
1037
+ on, and a member that left and came back starts again from now.
1038
+ - A room that the snapshot no longer lists is archived for good: it shows
1039
+ `archived: true`, with no member, no visibility and no admin. At the next
1040
+ pass its seats are removed as for a member that left: a seat that has not
1041
+ started is cancelled, a seat that started runs on and its speech is kept as
1042
+ audit only, and the round closes once every seat is released. `roomInput`,
1043
+ a room `receive` and a `room_call` round in it throw `Room is archived`, so
1044
+ the Host stops giving K8 its inbound messages first. A snapshot that lists
1045
+ an archived room is refused, and nothing changes.
1046
+ - `createRoom`, `updateRoom` and `setMemberMentions` refuse with
1047
+ `external_rooms`. The Main Bot schema offers neither `create_room` nor
1048
+ `update_room`, and an outcome that has one is refused with `external_rooms`.
1049
+ - A suspended Bot (#1319) can be a room member, under the suspension rules
1050
+ above.
1051
+ - The ledger stores this mode too, so a restart cannot change it. The mode is
1052
+ fixed once stored, with no migration. The option needs `team: 'external'`.
1053
+
1054
+ With `history` and `team: 'external'` together, the device ledger holds
1055
+ neither the history nor the team authority.
1056
+
1057
+ ## Group chat and Main Bot
1058
+
1059
+ The supplied Agent template is the initial Main Bot. A team can have multiple
1060
+ Main Bots. `setMainBot(botId, value)` is an owner API. The Host must authenticate
1061
+ its owner APIs before calling them, unless it passes a verified principal
1062
+ ([IM channel input](#im-channel-input)). `input(key, request, botId)` selects a Bot.
1063
+ The default is the initial Main Bot. Ordinary turns keep the K8a actions.
1064
+
1065
+ Give the Host the real server home projection API. Install
1066
+ `createBotPersonaProjection()` as the daemon's `agentHome.projection` consumer.
1067
+ It validates the opaque profile digest. It writes persona text to the Bot's
1068
+ own `AGENTS.md` with the SDK `writeHomeFile`, under the SDK writer lease. New
1069
+ profiles and updates wait for an exact `applied` or `idempotent` readback.
1070
+ The readback must match device,
1071
+ AgentRef, request id, and digest. New execution input then uses that revision.
1072
+ Already frozen executions keep their old input. A pending projection does not
1073
+ permit dispatch. All management actions participate in the K4 outcome commit.
1074
+
1075
+ Main Bot schemas offer six actions: `create_bot`, `update_bot`, `delete_bot`,
1076
+ `create_room`, `update_room`, and `team_note`. The Host checks the current role
1077
+ again when applying each action. Creation offers three local Bot slots and one
1078
+ local room slot. A room can use those Bot slots in the same outcome. Model ids
1079
+ come from `BotOptions.models`. The default model id is `default`. Each model
1080
+ has a Host-owned execution template. A Bot update cannot move its device.
1081
+ The Host can replace the templates at run time with `setModels(models)`, for
1082
+ example after a device key changed (#1357). Construction and `setModels` apply
1083
+ each template by model name to every unarchived Bot, a suspended one too. The
1084
+ Bot keeps its device and its profile; its agentRef follows its profile
1085
+ revision. No profile revision, readiness or persona projection changes. A Turn
1086
+ that froze before keeps the execution it froze with, also while it waits in
1087
+ the K4 FIFO. A template outside `readOnlyToolsets` refuses the call, which then
1088
+ changes nothing. A Bot whose model has no template keeps its stored template,
1089
+ and each of its Turns, a sealed routine Turn too, blocks with
1090
+ `Unavailable model: <name>` before it freezes (`blocked:<turnId>`). It freezes
1091
+ once a later `setModels` or restart provides the template. No write entry
1092
+ refuses a missing template of an existing Bot: a snapshot or `update_bot` that
1093
+ names such a model stores the profile and keeps the stored template. A new Bot
1094
+ still needs a template, since its device comes from it. A sealed routine's
1095
+ template is the sealed copy and is not re-projected.
1096
+ Profiles cap the active team at 24 Bots. Team notes cap at 20 entries of 300
1097
+ characters. Every team Bot receives these notes. Other Bots' private turns and
1098
+ persona text do not enter its ContextPack. No cross-home memory read occurs.
1099
+ `delete_bot` archives the profile and cancels unstarted work. Running results
1100
+ become audit only. Delegated work for the archived Bot is also cancelled when
1101
+ it runs (see Cross-Bot delegation). It does not delete the Agent home.
1102
+
1103
+ Profile deliveries share the Host serial consumer. The consumer waits for known
1104
+ old intents to settle. Device terminal readback can precede writer cleanup.
1105
+ A projection can therefore stay pending after it hits that lease. The Host
1106
+ reads every prior delivery before retry. It stores a new delivery id before
1107
+ sending the same revision and digest. Delay starts at one second and caps at
1108
+ 60 seconds. Recovery reuses stored ids. Old duplicate controls cannot replace
1109
+ a newer revision. Each revision remains gated on an exact accepted readback.
1110
+
1111
+ Use `roomInput(key, roomId, text, mentions, principal)` for a user message. `mentions` is
1112
+ an ordered Bot id list or the structured value `all`. The default is empty.
1113
+ The optional `principal` is the verified sender ([IM channel input](#im-channel-input)).
1114
+ The Host never scans text for names or `[PASS]`. Rooms support mention mode.
1115
+ An admin identity grants a larger budget. It does not create an implicit seat.
1116
+ A room has no admin mode, so the outcome fragment offers only `mention`. `updateRoom` is an authenticated owner API
1117
+ for membership, admin, name, and announcement changes.
1118
+
1119
+ `createRoom(roomId, fields)` is an authenticated owner API that creates a room
1120
+ with a Host room id and no model run (#1321). The id follows the snapshot room
1121
+ id rule ([External team authority](#external-team-authority)), and the fields
1122
+ follow `create_room`: 1 to 12 distinct active members, an admin that is a
1123
+ member, and mention mode only. The command id comes from the room id. The same
1124
+ id with the same name, members, admin and announcement replays the first
1125
+ result, and other fields are an `identity_conflict` (`Room identity conflict`).
1126
+ An id that already has a room, also one that a Main Bot outcome created, throws
1127
+ `Room already exists`. A new room starts with no visible history for its
1128
+ members. Later membership changes follow `updateRoom`. A local room cannot be
1129
+ deleted. In the external rooms mode, `createRoom` refuses with
1130
+ `external_rooms`.
1131
+
1132
+ `setMemberMentions(roomId, value, principal)` is an owner API for the
1133
+ `memberMentions` setting of a room (#1230). The value is `execute` or `ignore`;
1134
+ the default is `execute`. With `execute`, a structured mention from any verified
1135
+ human opens a seat. With `ignore`, a structured mention from a human who is not
1136
+ the owner opens no seat: the message stays room background, with no device work
1137
+ and no BYOK key. The owner's own mention still opens seats. Only the owner
1138
+ changes the setting, and only inbound messages that arrive after it see the new
1139
+ value; an open root and an established seat keep their admission
1140
+ ([R6](../../docs/host-im-adapter.md#r6-structured-mentions)).
1141
+
1142
+ A room turn is a fresh member Agent execution. It uses `bot-turn-outcome.v1`
1143
+ with required `speech`, plus optional `room_call`. It has no messageEgress.
1144
+ `{ speech: { kind: 'post', text: 'Evidence' } }` writes shared history.
1145
+ `{ speech: { kind: 'pass' } }` is an explicit pass. Empty or blank speech,
1146
+ missing outcome, and execution failure are visible seat failures. A textual
1147
+ mention in a post cannot create a seat. Main Bot room seats have the same speech-only authority as other members.
1148
+ Management actions are available only outside room seats. Only structured `room_call.members` can add seats after a Bot speaks.
1149
+
1150
+ Seats run in reservation order within a round. Each seat enters the same K4
1151
+ FIFO as that Bot's own turns. The waiting grace is 240 seconds. First observed claim starts a separate
1152
+ 240-second running grace. This persisted deadline does not reset on later
1153
+ scans or recovery. The K4 fallback
1154
+ waiting bound stays at 300 seconds. Room admission cancels waiting work first.
1155
+ If the member is still waiting at grace, the seat becomes `busy`. If it has
1156
+ started, the round can proceed while its writer stays held in K4. A later post
1157
+ uses its seat id and enters history once. Removed waiting seats are invalid.
1158
+ Removed running members can produce audit evidence, but cannot post or call.
1159
+ Already completed post, pass, and failure states remain unchanged.
1160
+
1161
+ A round permits initial seats + 4, plus 4 when it has an admin. Each member
1162
+ gets at most two seats; the round admin gets at most four. A reservation spends
1163
+ budget even if it fails, passes, or times out. Batch room calls are atomic.
1164
+ A late room_call after a round closes can open a new round. At most three such
1165
+ rounds share one user root. At most ten late posts share that root. A new user
1166
+ message starts a new root. ContextPack selects up to the most recent 100
1167
+ eligible messages. The 32 KiB budget counts the UTF-8 bytes of the frozen
1168
+ Request plus the serialized ContextPack. `historyWindow.currentRequestBytes`
1169
+ records the exact Request size, including the room request wrapper. The Host
1170
+ drops oldest whole rows until that budget fits. `historyWindow.notice` reports
1171
+ omitted messages and refusals.
1172
+ History overflow does not block a seat. The frozen Request section keeps the
1173
+ complete accepted request. Only a Request that alone exceeds 32 KiB blocks
1174
+ the turn. The seat reason and blocked projection report its byte count, the
1175
+ limit, and a request to shorten the input.
1176
+ For room_call seats, the visible caller post is the current request and its
1177
+ author id is retained. A pass inherits the earlier visible trigger. This
1178
+ request is preserved even if it has left the recent message window.
1179
+ The ledger retains its full audit history. No Summary is generated. Authority
1180
+ enums and required control metadata are not silently truncated. If non-history
1181
+ metadata plus the accepted Request exceeds the budget after history is removed,
1182
+ the notice reports that separate condition. That condition does not block.
1183
+ A Bot Turn outside a room carries its history in `history`, the
1184
+ `@byok-sdk/protocol` `buildHandoffPack` result (#1446). A row becomes a turn:
1185
+ `lines` is `{ speaker: source, text: request }`, then
1186
+ `{ speaker: 'bot', text: reply }` when the row has a reply, and `meta` is
1187
+ `{ id, root, hop, status, conclusion?, outcomeSummary }`. `history.recent`
1188
+ holds the newest whole turns, `history.earlier` holds excerpts of the turns
1189
+ before them, and `history.omittedTurns` counts the rest. The `handoff` option
1190
+ sets `recentBytes`, `earlyBytes` and `totalBytes`, by default 40 KiB, 6 KiB and
1191
+ 46 KiB (`DEFAULT_HANDOFF_BUDGETS`), and construction refuses a value that
1192
+ `buildHandoffPack` refuses. A snapshot view from `contextPack` has the
1193
+ candidate as the newest turn of `recent`, which may be cut; an empty `recent`
1194
+ with turns in the input means the candidate did not fit, and the last turn of
1195
+ `earlier` is not the candidate. `contextMaxBytes` covers the Request and the
1196
+ ContextPack without `history`. `contextTurnLimit` selects no history; it still
1197
+ bounds refusals, cards, questions and the room messages that retention keeps.
1198
+ A room seat keeps `room.messages`, as above.
1199
+
1200
+ Cards and questions each retain at most 12 items. Pending work takes priority.
1201
+ The Host removes old refusals, settled items, old messages, then pending items.
1202
+ `historyWindow.turnLimit` names the message or item count limit. Both room and
1203
+ private context also report `omittedMessages`, `omittedCards`,
1204
+ `omittedQuestions`, `omittedPendingCards`, `omittedPendingQuestions`, and
1205
+ `omittedRejections`, and a room seat reports `omittedTurns`. Zero counts remain
1206
+ explicit. `historyWindow.notice` also reports turns that `history` omits. Full
1207
+ outcomes stay in the ledger. Context includes action names and the current
1208
+ routine definition.
1209
+
1210
+ Rejected feedback is private to its Bot. The next frozen input reserves it.
1211
+ An execution that fails before it starts releases that reservation.
1212
+ A turn that cannot pass Request or schema admission has status `blocked` and
1213
+ `blockedReason`. It creates no intent. `cancelTurn` can cancel it before admission.
1214
+ Other schema composition errors propagate as Host defects.
1215
+
1216
+ Unmentioned messages are stored as background. They do not create a seat, but
1217
+ a later selected member can see eligible background messages. Each member has
1218
+ a persisted offset into `room.messages` in `visibleFrom`. New members see only
1219
+ messages appended after joining. Retained members keep their offset; retention
1220
+ lowers it by the messages that it moves from before it, so the member sees the
1221
+ same kept messages. Leaving and
1222
+ rejoining resets it. Both owner edits and Main Bot room edits use this rule.
1223
+ A pre-join root request is also excluded from a new member's Request section.
1224
+ A delayed post appended after joining is visible. Already frozen offers keep
1225
+ their selected window. A room without an earlier offset starts at the next
1226
+ user input; its older history is not disclosed.
1227
+
1228
+ A room Turn never gets `memory_save` (#1446): other users' and Bots' text
1229
+ reaches it, and what a Turn saves comes back in every later Turn of that Bot.
1230
+ `syncTurn` freezes a `room_slot` Turn with a lower `payload.agentMemory`:
1231
+ `read-write` becomes `read`, `read-write-if-admitted` becomes
1232
+ `read-if-admitted`, and a template without the field freezes as
1233
+ `read-if-admitted`. `none`, `read` and `read-if-admitted` stay. The mode only
1234
+ goes down. Every other source keeps the template value, a sealed routine Turn
1235
+ too, and the frozen execution stores the mode that the offer carries, so replay
1236
+ does not change. `read-if-admitted` needs a device that advertises
1237
+ `agent-memory-selection` and `agent-memory-read-if-admitted`; a daemon with an
1238
+ Agent home advertises both.
1239
+
1240
+ Read-only here means no `memory_save` and no memory-writing guidance. The SDK
1241
+ does not make memory files read-only ([protocol](../../docs/protocol.md)
1242
+ §2.2): a Bot whose toolset can write files can still change `MEMORY.md` from a
1243
+ room Turn. A Host that needs to stop that narrows the toolset or the file scope
1244
+ of the Bot's template.
1245
+
1246
+ `src/group-chat.test.ts` uses a real embedded SDK, daemon, HTTP transport,
1247
+ SQLite reopen, persona writes, and submit_result helper. `src/rooms.test.ts`
1248
+ checks budgets, authority, atomic refusal, and context limits as state rules.
1249
+ `roomInput` and all other mutations use the same serial Host consumer. Do not
1250
+ call K4 mutation APIs directly. Upload projections with `core.flushProjections`
1251
+ or read `snapshot().team` for seats, profile delivery state and the room
1252
+ messages that retention has not moved.
1253
+
1254
+ ### Room seat projections
1255
+
1256
+ K8 publishes how each seat of a room round ended, and when a round root has
1257
+ ended, in every mode, with or without `roomHistory` (#1393). The state does
1258
+ not store them; each is published once, in the transaction that makes it
1259
+ true.
1260
+
1261
+ - `room-seat:<roomId>:<seatId>` with `{ roomId, root, roundId, seatId, botId,
1262
+ status, late, reason?, triggerMessageId? }`, when the seat becomes terminal: `post`, `pass`,
1263
+ `failed`, `busy`, `removed` or `blocked`. `late` is not terminal; a late
1264
+ seat is published when its Turn ends. `reason` is the conclusion or block
1265
+ reason that the seat stores. A seat with no admitted Turn, such as a
1266
+ waiting seat whose Bot left the room, is published too, though it has no
1267
+ `bot-turn:` projection. Only a seat that a `room_call` opened has
1268
+ `triggerMessageId`, the message the seat answers: the caller's post (its
1269
+ seat id), or, when the caller passed, the message the caller answered (its
1270
+ own `triggerMessageId`, else the root). A Host tells a mentioned seat from a
1271
+ `room_call` seat by this field and does not derive it from the seat id. A
1272
+ seat opened before the release that added the field is not backfilled.
1273
+ - `room-root:<roomId>:<root>` with `{ roomId, root, seats }`, when every seat
1274
+ of every round of the root is terminal, the seats that a `room_call` added
1275
+ included. `seats` lists their ids in reservation order; each has its
1276
+ `room-seat:` projection in the same or an earlier transaction. A root that
1277
+ opens no seat is published in its `room_input` or `receive` transaction,
1278
+ with `seats: []`. The root is the id that `retain` acknowledges.
1279
+ - A Host must handle both prefixes before it upgrades to the release that
1280
+ adds them: a Host that refuses an unknown projection prefix fails its flush
1281
+ on the first one.
1282
+
1283
+ ## Persona delivery failures
1284
+
1285
+ A stale or conflicting persona completion stays in the owner ledger. It emits
1286
+ an owner projection with the Bot id, revision, reason, and recoverable status.
1287
+ Waiting turns expose `profileFailure`. They remain queued and cannot execute
1288
+ with an unconfirmed persona. The authenticated owner can call
1289
+ `retryPersona(botId)` after resolving the device-side problem. This creates
1290
+ the same desired persona at the next profile revision. It retains the failed
1291
+ operation for audit. An exact accepted readback still gates dispatch. Retry
1292
+ also survives a Host restart. It does not bypass schema or persona admission.
1293
+ A stale device may need profile-state reconciliation before retry can succeed.
1294
+ Transient delivery errors remain pending and use the existing automatic retry.
1295
+
1296
+ The supplied `createBotPersonaProjection` consumer writes `AGENTS.md` with
1297
+ the SDK `writeHomeFile` (#738). It runs on Windows, Linux and macOS. After a
1298
+ process crash, `AGENTS.md` has its old or its new persona. On POSIX, an
1299
+ `applied` readback means that the file and its directory are flushed. On
1300
+ Windows, it means that the file only is flushed. There, an OS crash or a power
1301
+ loss after the readback can bring back the old persona while the SDK record
1302
+ keeps the new revision. This Host does not deliver an acknowledged revision
1303
+ again, so the old file stays until the next persona update writes it. A process
1304
+ crash can leave an `AGENTS.md.<pid>-<n>.tmp` file in the home. The next
1305
+ `writeHomeFile` call for `AGENTS.md` removes it when that process has ended.
1306
+ The Host failure and retry API does not change these limits.
1307
+
1308
+
1309
+ ## Deferred Main Bot routine target
1310
+
1311
+ Main Bot `create_routine.target` for another Bot is not implemented. Routine
1312
+ creation remains self-only in this example. Aimpact did not approve that
1313
+ extension for this PR. A later K8b work order must add it. Cross-Bot delegation
1314
+ also stays outside this history-window change.
1315
+
1316
+ ## Cross-Bot delegation
1317
+
1318
+ This section covers slices X1–X6 and X2M of the
1319
+ [approved plan](../../docs/adr/ADR-041-k8b-cross-bot.md).
1320
+ See the [acceptance matrix](VALIDATION.md) for evidence and open rows.
1321
+ A Bot can delegate requests to other Bots of the same team. The `to` enum
1322
+ lists this Bot first, then each active team Bot after its first persona
1323
+ readback. It lists Bot ids only. A room seat has no `delegate` fragment.
1324
+
1325
+ One outcome can hold two cross-Bot items. The Host refuses an item with
1326
+ a delegation verdict and a reason: `room_seat`,
1327
+ `target_archived`, `hop_limit`, or `budget_exhausted`.
1328
+ A refusal also enters the initiator's `rejectedActions`.
1329
+ An accepted item creates a `bot_request` Turn for the target. Its id is
1330
+ `H(taskId, 'delegate', index)`. Its hop is the initiator's hop plus one, at
1331
+ most four. B's ContextPack holds B's own history and a `delegation` block.
1332
+ B's reply cap is `BOT_REPLY_MAX_BYTES` (8 192 UTF-8 bytes).
1333
+
1334
+ Each Turn stores `authority`: `owner` for user input and answers, `bot` for a
1335
+ `bot_request`. Continuations, replies, action results, and routine Turns
1336
+ inherit it. Management needs a Main Bot and `owner` authority, both in the
1337
+ schema and at apply time.
1338
+
1339
+ `consumeMessage` checks the exact task, device, AgentRef, and destination
1340
+ binding in one ledger transaction. It stores an accepted delegated reply by
1341
+ task id. That record is the only reply body authority. At the chain end, the
1342
+ verdict is `answered` when the record exists. Otherwise the delegation is
1343
+ `reply_pending`. The Host timer reads `tasks.agentMessage` with a backoff from
1344
+ 1 to 60 seconds. It does not wait for a K4 scan. No message gives `failed`
1345
+ (`no_reply`). Held gives `reply_held`; `abandonDelegation` then sets
1346
+ `abandoned`. After `uncertainAfterMs` (default 30 minutes) without a result,
1347
+ the delegation is `uncertain`.
1348
+
1349
+ Other chain ends map to verdicts as follows. `failed` gives `failed`.
1350
+ `declined` gives `failed` with `busy` or the decline code. `expired` gives
1351
+ `expired`. A Host cancel with reason `expired` gives `expired`
1352
+ (`claim_raced_deadline`). A user cancel gives `cancelled` (`user_cancelled`).
1353
+
1354
+ `cancelDelegation(id)` works while the delegation is queued, `waiting_device`,
1355
+ running, or `reply_pending`. `cancelTurn` on a chain Turn calls it. One transaction
1356
+ freezes `cancel = { requestedAt, targetTurnId, delivered }` on the current
1357
+ chain Turn. That Turn then accepts no first message and applies no outcome.
1358
+ Without a K4 intent, the transaction closes the Turn and sets `cancelled`.
1359
+ It does not call `core.cancel`. With an intent, the Host calls `core.cancel`
1360
+ after the commit and then sets `delivered`. Each `process` pass delivers an
1361
+ undelivered cancel to its frozen target, so a restart completes it. When
1362
+ `core.cancel` fails, `cancelDelegation` rejects, but the cancel stays
1363
+ committed and the timer delivers it. A repeat gives `cancel_pending` until the
1364
+ verdict and `already_settled` with the verdict after it; neither writes or calls
1365
+ `core.cancel` ([idempotent owner cancels](#idempotent-owner-cancels-1405)).
1366
+
1367
+ A message accepted before the cancel stays. The verdict is then `cancelled`
1368
+ with that reply marked `partial`. A message after the cancel is refused
1369
+ (`delegation_cancelled`). A cancel with no terminal after `cancelGraceMs`
1370
+ (default 60 seconds) shows `uncertain`. A claimed chain Turn with no terminal
1371
+ after `uncertainAfterMs` also shows `uncertain`. The Host never resubmits and
1372
+ never starts a new generation. A later terminal gives the normal verdict.
1373
+
1374
+ A Main Bot cancels through the `cancel_delegation` outcome fragment. Only a
1375
+ Main Bot Turn with `authority = owner` outside a room seat gets it. Its
1376
+ `delegationId` enum lists open delegations: no verdict, no cancel yet, and
1377
+ status `queued`, `waiting_device`, `running`, or `reply_pending`. The list is
1378
+ newest first and has at most 24 ids. The ContextPack `openDelegations` block shows each listed
1379
+ id with its Bots, status, and the first 80 code points of the request. It
1380
+ also counts the omitted delegations and shows a notice. The owner cancels
1381
+ those with `cancelDelegation`. Apply runs after the management actions and
1382
+ before the routine actions. It checks room seat, owner authority, and the
1383
+ Main Bot role again. Then it runs the same arbitration transaction. The cancel fact records
1384
+ `reason: 'main_bot_cancelled'`, and the verdict keeps that reason. A resolved
1385
+ delegation gives the rejected action `already_resolved` and no second
1386
+ verdict. The Main Bot sees it in its next ContextPack.
1387
+
1388
+ `abandonDelegation(id)` ends a `reply_held` or `uncertain` delegation with
1389
+ `abandoned`. When the attempt can still run, it also writes a K4 cancel. A
1390
+ terminal after the verdict goes to `audit` only.
1391
+
1392
+ When the target Bot is archived, the next `process` pass cancels its open
1393
+ delegations. It uses the same arbitration transaction, with the cancel reason
1394
+ `target_archived`. This applies in every open state: queued, `waiting_device`, running,
1395
+ `reply_pending`, `reply_held`, and `uncertain`. A Turn without a K4 intent
1396
+ closes at once. A queued intent settles as `cancelled`. A submitted attempt
1397
+ gets `tasks.cancel` and an attempt readback. A claimed attempt gets
1398
+ `tasks.cancel`, and the Host waits for its terminal. The verdict is `refused`
1399
+ (`target_archived`). A reply accepted before the archive does not go to the
1400
+ initiator. The Host writes an `audit` note for it. A cancel with no terminal
1401
+ follows the `uncertain` rules above. Archived Bots leave the `to` enum and the
1402
+ roster at the next schema build. A delegation cancelled by the archive leaves
1403
+ the `cancel_delegation` enum.
1404
+
1405
+ When the initiator is archived, the target's work continues. The verdict is
1406
+ still written, but the Host creates no `bot_reply` Turn and releases the free
1407
+ reply slots. The delegation row and its projection show
1408
+ `undelivered: 'initiator_archived'`.
1409
+
1410
+ Every verdict reaches the initiator once, in a `bot_reply` Turn. The accepted
1411
+ items of one outcome form a batch. The first report waits until each accepted
1412
+ item has a verdict or is `uncertain`. It holds every verdict of the batch so
1413
+ far, refusals included. Its id is `H('bot_reply', taskId)` for two accepted
1414
+ items and `H('bot_reply', delegationId)` for one. When every accepted item is
1415
+ `uncertain`, there is no batch Turn. A verdict after the first report, or
1416
+ after that state, reports in its own Turn `H('bot_reply', delegationId)`.
1417
+ When an outcome has no accepted item, one refusal report Turn
1418
+ `H('bot_reply', taskId)` holds all its refusals. That
1419
+ report has no `delegate` fragment. Status changes publish
1420
+ `delegation:<id>:<revision>` projections with `id`, `revision`, `root`,
1421
+ `fromBotId`, `toBotId`, `request`, `status`, and `verdict`, `reason`,
1422
+ `replyTurnId` and `undelivered` once set. `root` is the delegation's root, so a
1423
+ Host can place a cross-Bot delegation under the conversation of its root
1424
+ (#1356).
1425
+
1426
+ The root Bot budget is 12 units. An outcome with `n` accepted items reserves
1427
+ `n + max(n, 1)` units: one B unit and one A reply slot for each item.
1428
+ Admission counts every open reservation on the root. When the units are not
1429
+ free, the Host refuses accepted items from the last index
1430
+ (`budget_exhausted`) and checks again. After each report, the batch releases
1431
+ its free slots above the number of unreported items. A refusal report
1432
+ reserves one slot when one is free. Otherwise
1433
+ it is delivery only: it does not start a model, and it enters the next
1434
+ ContextPack. A unit is spent at the first observed claim and released when it
1435
+ can no longer be needed. `spent + reserved <= 12` holds after each transaction.
1436
+
1437
+ A `bot_request` or `bot_reply` instruction puts request text and reply bodies
1438
+ once, as raw UTF-8 in length-framed blocks. Team notes, rooms, and routines
1439
+ are trimmed oldest first, and background has priority: `history` gets only the
1440
+ bytes left after it, up to `handoff.totalBytes`. A larger
1441
+ `instructionMaxBytes` can therefore leave less history, because more background
1442
+ stays. `instructionMaxBytes` (default 65 536) bounds the whole instruction.
1443
+ Construction refuses a value below
1444
+ `minimumInstructionBytes(SYSTEM_PROMPT)`. The minimum includes the
1445
+ `openDelegations` block of a Main Bot reply Turn.
1446
+
1447
+ A Main Bot with 24 Bots, 8 routines, and a room exceeds the outcome schema cap
1448
+ of 16 384 bytes. The Host blocks such a Turn with a visible reason. It does
1449
+ not cut an enum. Without the room, 24 open delegations in the
1450
+ `cancel_delegation` enum still fit (15 949 bytes).
1451
+
1452
+ ### Topology switch (§4.1)
1453
+
1454
+ L is the old owner when a device moves from L to H (#957). L keeps one owner
1455
+ record per device in its ledger, as §4.1 records the mode per device: one L
1456
+ Host can own Bots on two devices (see "Second-device placement"). A device with
1457
+ no record is `{ mode: 'L', revision: 0 }`. `topology(deviceId)` reads it.
1458
+ The product runs the switch with these calls, each on the revision it expects.
1459
+ A stale revision throws `CommitConflict` with `stale_revision`, and each step
1460
+ except the export raises the revision:
1461
+
1462
+ 1. `freezeForSwitch(deviceId, revision)` writes `{ mode: 'L', switching: 'H' }`
1463
+ and returns the record read back from the ledger.
1464
+ 2. `drainForSwitch(deviceId, { cancel })` returns the device's open work:
1465
+ - open K4 intents whose execution names the device;
1466
+ - Turns of its Bots with no conclusion and no intent;
1467
+ - open input batches;
1468
+ - Agent home writes that were sent and have no terminal readback. A write
1469
+ is marked sent in the transaction before the send, so a crash or a
1470
+ failed send still counts it.
1471
+
1472
+ With `cancel`, it cancels the intents, Turns and batches first, then runs a
1473
+ pass. A tried intent concludes only from its SDK terminal, so it stays
1474
+ listed until the reconciler reads one. The drain waits for nothing: no
1475
+ timeout counts as stop evidence.
1476
+ 3. `exportForSwitch(devices, exportedAt?)` seals the whole domain into a
1477
+ switch export once every device in `devices` is frozen at its revision and
1478
+ drained (see "Owner switch on L" below).
1479
+ 4. After the new owner imported and verified the export,
1480
+ `commitSwitch(deviceId, revision, receipt)` writes `{ mode: 'H' }` for every
1481
+ device of the export in one transaction, when `receipt` is the export's
1482
+ digest and `deviceId` at `revision` is one of its devices. It refuses while
1483
+ the same transaction finds open work. `abortSwitch(deviceId, revision)`
1484
+ instead writes `{ mode: 'L' }`, so L owns the device again and its held
1485
+ Turns run.
1486
+
1487
+ While the device is frozen, each entry that can create execution for it throws
1488
+ `DeviceSwitchingError` (`code: 'device_switching'`) and writes nothing:
1489
+
1490
+ - `input`, and `receive` owner input, for a Bot on the device;
1491
+ - `roomInput`, and `receive` room input or bot background, when any Bot member
1492
+ of the room is on the device;
1493
+ - `answer`, when the question's Bot is on the device, and `decide` (either
1494
+ decision), when the card's Bot is on the device, since each adds a Turn for
1495
+ that Bot;
1496
+ - `enqueueHostIntent` on the device.
1497
+
1498
+ The check runs after the replay lookup (the new `CommandPorts.admit` port), so
1499
+ an exact replay of a command or Host intent that L accepted before the freeze
1500
+ still returns its first result.
1501
+
1502
+ The Bots each command reaches are a pure rule, `commandBots(state, command)` from
1503
+ `./rules/commands` (#975). L refuses a command when one of those Bots' devices
1504
+ refuses work. H passes the same rule to its `CommandPorts.admit`, so both Hosts
1505
+ refuse the same commands during a freeze. A frozen domain then starts no new
1506
+ Turn and no new card connector call.
1507
+
1508
+ After the commit these entries throw `DeviceModeError` (`code:
1509
+ 'device_not_bound'`, `reason: 'mode'`, as H's refusal of a device in the other
1510
+ mode), for good.
1511
+
1512
+ Other refusals and holds:
1513
+
1514
+ - **Routine slot:** a slot of a routine whose Bot is on the device throws from
1515
+ the routine hook. K4 then records neither the slot nor a Turn, and the SDK
1516
+ delivers the wake again later, so a slot is never dropped. It runs after an
1517
+ abort. From the export on every slot refuses, also after the commit, and the
1518
+ new owner schedules the routine's wakes on its own SDK.
1519
+ - **Sync:** any other path that adds a Turn for a Bot on the device is held.
1520
+ This covers a Bot outcome that delegates, a room round, and a batch that
1521
+ seals.
1522
+ - **Agent home:** a home write for the device's Bots is not sent, so one Agent
1523
+ home never has two writers. A sent write is still read back. A write that
1524
+ was never sent is not read back and arms no timer, so after a commit nothing
1525
+ polls it.
1526
+ - **K4 submit:** L gives K4 `admitSubmit`, which reads the same record. K4 then
1527
+ sends nothing to the device, in the transaction that begins a submit and in
1528
+ the readback right before the SDK call. That holds for a queued intent from
1529
+ before the freeze, a `backoff` intent (it keeps its generation), the K4 timer
1530
+ drain and an intent added through `bot.core` directly. A held intent is sent
1531
+ after an abort; the drain with `cancel` settles it.
1532
+
1533
+ Commands that add no execution still run, since the drain needs some of them:
1534
+ cancels, team and routine lifecycle changes, `consumeMessage` and retention.
1535
+
1536
+ Each check reads the record in the transaction that would write the work. The
1537
+ constructor reads every record first and refuses a malformed one, so a restart
1538
+ admits nothing before it knows the freeze.
1539
+
1540
+ Once a device is in mode H, every step on this ledger refuses. A domain moves
1541
+ back to L by an import into a new L tenant (below).
1542
+
1543
+ ### Owner switch on L (#975)
1544
+
1545
+ `src/switch.ts` reads an L ledger into the switch format and writes the format
1546
+ into an L tenant. One function, `switchContent`, serves both the old owner's
1547
+ export and the new owner's read-back, so one function states what an L ledger
1548
+ holds. The whole coordination domain moves together.
1549
+
1550
+ **Old owner (L → H).** `exportForSwitch(devices, exportedAt?)` runs in one
1551
+ synchronous step: it dumps the ledger (K4 `dumpForSwitch`), checks it, seals it
1552
+ (`sealSwitchExport`) and records the export mark. It refuses:
1553
+
1554
+ - a device that is not switching at its revision, or still has open work;
1555
+ - a live Bot on a device it does not name, and every other state the format
1556
+ refuses (`SwitchExportError`);
1557
+ - Agent memory state, which binds the tenant inside its digests;
1558
+ - a pending projection: upload them with `core.flushProjections` first;
1559
+ - a pending submit or Host job, which K4 would run while the export waits;
1560
+ - a stored copy that differs from the value it is derived from, with
1561
+ `reference`: an intent's `agent` (K4 `agentKey`), task id (K4 `taskId`) and
1562
+ frozen input of each generation, K4 `applied` (the current task of each
1563
+ succeeded intent), each occurrence's wake key (K4 `parseRoutineWakeKey`), its
1564
+ slot, intent id and conclusion, a routine's next wake key, and the
1565
+ `attempts` of intents and occurrences;
1566
+ - a K4 or K8 record with a field the format does not name, which would be
1567
+ dropped.
1568
+
1569
+ From the mark on, also after a restart, this Host writes nothing to the
1570
+ ledger. Each K8 write refuses with `SwitchExportedError` (`code:
1571
+ 'switch_exported'`) after the write runs, so a new command on a frozen or
1572
+ H-owned device still gets its device refusal. A refusal the write raises first
1573
+ also comes before the export's: a replayed command id (also on a frozen
1574
+ device), an id conflict, `stale_revision` and `RetentionRefused`. Each refusal
1575
+ writes nothing. That holds for the root entries a product calls directly too: `commitInLedger`, `retainInLedger`,
1576
+ `callCardsInLedger` (before the connector runs) and `syncTurnInLedger`. The
1577
+ passes and the timer run nothing, the K4 hooks and the routine lifecycle and
1578
+ update entries refuse, and the compact veto (`botCompactVeto`) refuses every
1579
+ intent with `switch_exported`. The mark stays after the commit, so the old
1580
+ ledger keeps the exported state.
1581
+
1582
+ Do not compact an exported ledger. `ledger.compact` with no acknowledged
1583
+ intent still deletes expired tombstones, which the veto does not see. Before
1584
+ the commit that makes the commit refuse, so the switch is aborted and exported
1585
+ again; after the commit it does no harm.
1586
+
1587
+ `commitSwitch` checks the receipt against the mark, then seals the ledger
1588
+ again under the export's header and refuses a different digest. That check
1589
+ covers the K4 core, which writes on its own timers: a routine that is pacing a
1590
+ schedule retry, or that switches to a pending version, can change between the
1591
+ export and the commit. The commit then refuses, and the switch is aborted and
1592
+ exported again. The commit moves every device of the export at once, so a
1593
+ domain is never split between the owners. An abort of a device of the export
1594
+ ends the export, and the new owner discards its import; after the commit no
1595
+ device of it aborts.
1596
+
1597
+ **New owner (H → L).** On a new, empty ledger tenant (a switch back to L opens
1598
+ a new tenant), and with no `BotCollaboration` on it:
1599
+
1600
+ 1. `importForSwitch(ledger, document)` verifies the H export and writes it
1601
+ with each device owned by H and an import record, in one transaction (K4
1602
+ `loadForSwitch`). Before that transaction commits, K4 reads the tenant's
1603
+ rows back, and they must seal to the document's digest under its header;
1604
+ otherwise it throws `SwitchExportError` with `manifest` and writes nothing.
1605
+ So an import is either verified or not there. It returns the receipt
1606
+ `{ digest, devices }` that the old owner commits away on.
1607
+ 2. After the old owner committed, `commitImport(ledger, digest)` gives L each
1608
+ device of the import and deletes the import record.
1609
+ 3. `discardImport(ledger)` deletes an import that is not to be committed (K4
1610
+ `discard`). It first marks the import as being discarded, so a commit
1611
+ refuses it from then on.
1612
+
1613
+ A `BotCollaboration` refuses to open a ledger with an import record, and the
1614
+ root entries (`commitInLedger`, `retainInLedger`, `callCardsInLedger`,
1615
+ `syncTurnInLedger`) refuse it the same way before they run. So no work runs on
1616
+ an import before its commit, and a committed tenant has no record to discard. The import writes each derived value from the format: `agent` for the
1617
+ new tenant, the task ids and inputs of every generation, `applied`, slots, wake
1618
+ keys, intent ids, `attempts` and the Host intent handlers. A concluded intent
1619
+ gets K4's cursors of a new row (`phase: 'settled'`, `notBefore: 0`). Routines
1620
+ and occurrences go in the order of their ordinals, which the format makes their
1621
+ positions.
1622
+
1623
+ **Ordering.** The receipt is the export's digest, and nothing between the two
1624
+ Hosts proves that the target imported it: there is no authentication between
1625
+ them. The product runs the steps in order and keeps the document:
1626
+
1627
+ - The old owner commits away only after the target reported its import
1628
+ verified.
1629
+ - The export document is kept until the target committed toward its owner.
1630
+ - If an import is lost after the old owner committed away, the kept document
1631
+ is imported into a new tenant.
1632
+ - Only one import of a digest is committed; every other one is discarded. The
1633
+ receipt names no tenant, so one document can be imported into two tenants.
1634
+ - From the export on the old owner refuses all work, so two owners never run
1635
+ the domain at the same time.
1636
+
1637
+ Not moved: the source SDK's wakes, that is the `schedule` and `cancel-wake`
1638
+ rows and the scan wake. The new owner's `recover()` schedules each routine's
1639
+ next wake on its own SDK. K4 `ignoredWakes` does not move either. It is an
1640
+ optional audit of wake deliveries that the source SDK made and K4 ignored, at
1641
+ most `IGNORED_WAKE_AUDIT_LIMIT` rows, and no rule reads it. A target starts
1642
+ without it, as a new ledger does, and an export is not refused for it.
1643
+
1644
+ ### Owner switch export format (#975)
1645
+
1646
+ The `./migration` entry (`src/migration.ts`) is the one form in which a whole
1647
+ coordination domain moves between owners: an L ledger tenant or an H scope.
1648
+ Neither Host's storage is the format. The old owner builds a `SwitchContent`
1649
+ once every device of the domain is frozen and drained, and
1650
+ `sealSwitchExport` checks it, orders each section by its identity and adds a
1651
+ manifest. The manifest has the count and the `hash(canonical(section))` of
1652
+ each list section, and one digest over them and the header (source, domain,
1653
+ frozen device revisions, export time). The collaboration digest is the hash
1654
+ of its JSON text, because the insertion order of its maps is state: K8 reads
1655
+ Turns in that order for context and retention, so a target must keep it. The new owner runs `verifySwitchExport` on
1656
+ the document before it writes anything, and again on its own rows read back
1657
+ into this form, so the digest it records in its receipt is the source's. The
1658
+ digest covers the header, and `domain` is the source's tenant or scope id (a
1659
+ switch back to L opens a new tenant). So the read-back copies the document's
1660
+ header as it is and rebuilds only the sections from the target's rows. Devices
1661
+ are in JS string order of their id, and each section in JS string order of
1662
+ `canonical(identity)`, so a read-back sorts that way in JS or reseals; a
1663
+ database `ORDER BY` may give `unsorted`.
1664
+
1665
+ A record holds what a target needs to rebuild the row, with values the source
1666
+ stores, never a default. Routines and occurrences carry their ordinal, which is
1667
+ their position in their section, exactly 0 to n - 1: what moves is their order,
1668
+ which is all K4 stores, and H stores the position in its column. An intent
1669
+ carries K4 `sequence` or H `ordinal` as it is, gaps included, and its frozen
1670
+ input (a sealed one stays sealed). H stores only part of this
1671
+ today: the K4-only fields get H columns in the H slice that imports them.
1672
+ Every object has an exact set of keys.
1673
+
1674
+ A value that a Host derives from others is not in a record, and the target
1675
+ derives its own. The format never sees the source's stored copies, so each
1676
+ Host's export builder checks them against these rules and refuses to build an
1677
+ export where one differs:
1678
+ - an intent's FIFO key, K4 `agentKey(domain, execution)`, from the target's
1679
+ own tenant or scope and the device and Agent of the frozen input;
1680
+ - the execution input of each earlier generation (`input` with that
1681
+ generation's task id), and K4 `intent.execution` (`input` without
1682
+ `taskId`), which hold while K4 runs without its memory option, as K8 does;
1683
+ - K4 `applied`: the current task id exactly when the intent `succeeded`;
1684
+ - a K4 occurrence's wake key and slot (K4 `routineWakeKey`). Each occurrence
1685
+ has exactly one slot on both Hosts, so the format has no slot section;
1686
+ - an occurrence's intent id (K4 `occurrenceIntentKey`), and K4 `attempts`,
1687
+ which `switchAttempts` derives for both Hosts.
1688
+
1689
+ An intent carries the K4 execution of each earlier generation (submission,
1690
+ start, attempt, terminal and message receipt), because K4 compacts an intent
1691
+ only with the execution of every generation. A message for an earlier task is
1692
+ answered from its execution: by its receipt, or else `stale_generation`.
1693
+ Nothing relies on a replay after the switch getting `accepted`: the target's
1694
+ SDK passes an Agent message to the Host only when its own stores hold the
1695
+ device's task and offer binding, which this export does not carry.
1696
+
1697
+ The format refuses, with `SwitchExportError` and a `reason`:
1698
+ - the source's owner records (L `topology`, and L `hostIntents`, whose handler
1699
+ each intent carries);
1700
+ - a K4 message receipt, of the current generation or an earlier one, that is
1701
+ not the K8 accepted reply of the same task id, or a reply with no receipt
1702
+ (`receipt_mismatch`);
1703
+ - a record that names one the export does not hold (`reference`): an
1704
+ occurrence intent (K4's `occurrence:<sha-256>` key) or Host job outbox row
1705
+ without its occurrence, an occurrence without its routine, an occurrence key
1706
+ that is not K4's hash of its routine slot and trigger, or a task id that is
1707
+ not `hash([key, generation])`;
1708
+ - state that K4 cannot produce (`invalid`): a retry policy outside K4's
1709
+ `validateRetry` bounds, on an intent or a routine definition; a generation at
1710
+ or past `maxAttempts`; a `reserved` intent past generation 0 or with
1711
+ anything from a submission; an earlier generation without its terminal and
1712
+ attempt, or that was not begun; an occurrence that does not match its
1713
+ routine's run kind (a Host job routine's occurrence has a job, is never
1714
+ promoted, since L runs K4 with `hostJobExecution: 'fail'` and H concludes a
1715
+ job result with an execution `failed`, and has a pending job exactly while it
1716
+ is open; a hook routine's has no job); a routine
1717
+ or occurrence ordinal that is not its position; and two occurrences of one
1718
+ slot (`duplicate`);
1719
+ - an execution routine (`execution_routine`): a K8 domain holds only Turn and
1720
+ Host intents (#954), L refuses execution routines and H refuses them at
1721
+ create, and K8 Bot routines are occurrence hooks;
1722
+ - a live Bot on a device the export does not move;
1723
+ - open work: an open Turn or input batch, an intent with no conclusion, or a
1724
+ card call in flight;
1725
+ - a pending Agent home write that is `sent` or has a `retryAt`, because it may
1726
+ have reached the device. An unsent one moves and is sent by the new owner;
1727
+ - a pending projection (`projection_pending`): H's receiver deduplicates by
1728
+ `(scope, id)`, and L does not record whether it was sent (H raises `tries`
1729
+ before the send), so the source flushes its projections first;
1730
+ - rows out of identity order, a repeated identity or ordinal, a key outside the
1731
+ format, malformed fields, a value that is not JSON by K4's `validateJson`
1732
+ (`NaN`, `undefined`, a class instance, checked before the seal clones the
1733
+ content), and a manifest that does not match the content.
1734
+
1735
+ A channel delivery moves under its id,
1736
+ `hash([taskId, messageId, routeKey, nonce?])`, which names no Host domain, so
1737
+ the target's readback or resend of a `sending` or `unknown` delivery uses the
1738
+ source's idempotency key. Whether a platform honors that key is its adapter's
1739
+ concern (`docs/host-im-adapter.md`); the switch does not change it.
1740
+
1741
+ This entry has no I/O. L's export, import and commit are in "Owner switch on L";
1742
+ H's are in the hosted example README, "Owner switch export (#975)" and "Owner switch
1743
+ import (#975)".
1744
+
1745
+ ### Second-device placement and device wait
1746
+
1747
+ One embedded server and one Host ledger can serve Bots on two enrolled
1748
+ devices. Supply `BotOptions.models` with Host-owned templates for each device:
1749
+
1750
+ ```ts
1751
+ const models = {
1752
+ local: localExecution,
1753
+ remote: { ...remoteExecution, deviceId: enrolledSecondDeviceId },
1754
+ };
1755
+ ```
1756
+
1757
+ A `create_bot` action selects `model: 'remote'`. The Host copies that
1758
+ execution template's device into the Bot profile. A model update keeps the
1759
+ Bot's device. This is creation placement, not home migration. A changed
1760
+ `remote` template, passed to `setModels` or at a restart, is re-projected onto
1761
+ each Bot of that model on its own device; it does not move a Bot either.
1762
+ Install `createBotPersonaProjection()` on both daemons. Wait for exact persona
1763
+ readback before dispatch. Device B needs SDK daemon and runtime code, with
1764
+ its own credential store and Agent homes. It needs no collaboration Host.
1765
+
1766
+ Supply `server.machines.list` for wait display. A delivered, unclaimed offer
1767
+ shows `waiting_device` only when that device's presence has expired. Persona
1768
+ and FIFO waits remain queued. Missing or failed discovery, including the
1769
+ one-second I/O bound, supplies no new offline fact. Presence does not control
1770
+ dispatch or verdicts. K4 keeps the original five-minute deadline. Reconnect
1771
+ can claim the same frozen task. Expiry cancels and reads the attempt before
1772
+ reporting `expired` once to A. A claim race still needs terminal evidence.
1773
+
1774
+ See [Second device and relay contract](SECOND-DEVICE.md). Its two-process
1775
+ Topology L relay is a contract only. The synthetic two-daemon test proves
1776
+ the embedded-server path. Hosted `submitAgentExecution`, two physical
1777
+ computers, two Host processes, and paid Pi behavior remain outside that proof.
1778
+
1779
+ ## Input coalescing
1780
+
1781
+ This section covers slice I1 of the Octop plan for issue #551.
1782
+ Input coalescing is an optional Host policy. It runs before K4 enqueue.
1783
+ K4, the SDK, and the wire do not change.
1784
+
1785
+ `BotOptions.coalesce` turns it on. Without it, `input` makes the same state
1786
+ change as before: one Turn, one K4 intent, and one execution for each input.
1787
+ A field that you do not give takes its default. Construction refuses a value
1788
+ that is not an integer or is out of range.
1789
+
1790
+ | Field | Default | Range |
1791
+ | --- | --- | --- |
1792
+ | `windowMs` | 10 000 | 1 000 to 60 000 |
1793
+ | `maxItems` | 8 | 2 to 16 |
1794
+ | `maxBytes` | 8 192 | 1 024 to `contextMaxBytes / 4` |
1795
+
1796
+ A Bot is busy when it has a Turn that is not concluded and not blocked.
1797
+ An input to an idle Bot seals at once as a one-input batch. Its Turn id,
1798
+ Request, intent key, and frozen instruction are the same as without the policy.
1799
+ An input to a busy Bot opens a batch or joins the open batch of that Bot.
1800
+ A Bot has at most one open batch. Inputs join one batch only when the Bot,
1801
+ conversation, sender principal id, authority, Bot revision, and Bot model are
1802
+ the same. In this example, each Bot has one 1:1 conversation, so the Bot id
1803
+ also identifies the conversation. Room input never coalesces.
1804
+
1805
+ A sealed batch becomes one `user` Turn. Its id is the id of the first input.
1806
+ `input` returns this id for each member. The K4 intent key is this Turn id, so
1807
+ task identity, FIFO order, generation, and cancel readback do not change. The
1808
+ batch Turn is the budget root. Continuation and delegation budgets count once
1809
+ for the whole batch, not once for each input. Neither the batch nor its Turn
1810
+ changes after the seal. The Host never changes an enqueued intent.
1811
+
1812
+ A one-input batch keeps the raw text as its Request. A batch with more inputs
1813
+ has one notice line, then each input in arrival order. Each input is framed
1814
+ once as raw UTF-8, with the frame of Cross-Bot replies. The metadata line holds
1815
+ `inputId` and `receivedAt`. The Host renders the merged Request before each
1816
+ join. If it is larger than `maxBytes`, the Host seals the batch and opens a new
1817
+ batch for the input. So a merged Request always fits the ContextPack budget.
1818
+ A long single input stays alone and unframed. An input over the ContextPack
1819
+ budget blocks with a visible reason, as before.
1820
+
1821
+ | Seal reason | Condition |
1822
+ | --- | --- |
1823
+ | `idle` | The Bot is idle. |
1824
+ | `window` | `windowMs` passed after the first input. Later inputs do not extend it. |
1825
+ | `items` | The batch has `maxItems` inputs. |
1826
+ | `bytes` | The next input makes the merged Request larger than `maxBytes`. |
1827
+ | `boundary` | Another new Turn of this Bot arrives. |
1828
+ | `key_changed` | The sender, authority, or Bot configuration changed. |
1829
+ | `cancel` | `cancelTurn` names the batch or a member input. |
1830
+ | `policy_off` | The Host restarted without `coalesce`. |
1831
+ | `archived` | The Bot is archived. |
1832
+
1833
+ Every other new Turn of the Bot seals its open batch first: `answer`,
1834
+ `action_result`, `routine`, `room_slot`, `bot_request`, `bot_reply`, and
1835
+ `continuation`. So the queue keeps arrival order. A replayed Turn does not
1836
+ seal. The seal check runs at the start of each Host sync and before each new
1837
+ input. `recover()` runs a sync first, so a due batch seals after a restart.
1838
+
1839
+ `cancelTurn` takes a batch id or a member input id. It cancels the whole batch.
1840
+ A replay of `input` with the same key and text returns the batch Turn id and
1841
+ does not join again. A replay with a changed text throws
1842
+ `Input identity conflict`. Each input has a durable record in
1843
+ `snapshot().inputs` with its `batchId`. `snapshot().inputBatches` holds the
1844
+ batches. The `bot-turn:<id>` projection carries `inputIds` in arrival order.
1845
+ Show the one reply once, and mark each member message from `inputIds`.
1846
+
1847
+ From the second input, a reply can wait up to `windowMs` plus the running
1848
+ execution. A batch Turn freezes its ContextPack at enqueue, as every waiting
1849
+ Turn does. The Host does not read message text for meaning, so a later input
1850
+ such as "never mind" does not withdraw an earlier input. The model reads all
1851
+ inputs in order and answers them together.
1852
+
1853
+ This example does not yet arm a timer at the window end, or publish
1854
+ `input-batch` projections (slice I2). Until then, a batch of a busy Bot seals
1855
+ at the next Host call or when the Bot becomes idle.
1856
+
1857
+ ## User input priority (#1229)
1858
+
1859
+ The K4 FIFO stays one queue per `(tenant, deviceId, agentId)`, ordered by
1860
+ the ledger's `sequence` (`docs/host-execution-core.md` §3). The reference Host
1861
+ adds one explicit rule on top of it. A **user-source** intent goes ahead of
1862
+ the queued, never-submitted `routine` and `bot_request` intents of the same
1863
+ Agent FIFO. "User-source" is the K4 `source: 'user'`: an owner input, and
1864
+ an `answer` Turn. The rule runs in the same ledger transaction that enqueues
1865
+ the user intent, so it is durable and survives a restart.
1866
+
1867
+ - Only intents with `phase: 'queued'` and `attempts: 0` move. A submitted or
1868
+ in-flight execution keeps its `sequence`, its `taskId` and its generation,
1869
+ and a cancel is not issued to make room.
1870
+ - The user intents and the autonomous intents keep their own arrival order.
1871
+ A self continuation, an `action_result` or a Bot reply keeps its position.
1872
+ - `setBotAutonomy` and the observe mode never reorder anything.
1873
+ - A standalone K4 reader sees a plain ledger: the order is just `sequence`
1874
+ values. No memory state and no second queue.
1875
+
1876
+ The Host also reserves **one slot per device** for user work. The limit is
1877
+ `BotOptions.deviceConcurrency` (default 8, the SDK daemon's
1878
+ `maxConcurrentTasks` default). An intent occupies a slot once it is submitted
1879
+ or has attempt evidence. Autonomous work may fill `limit - 1` slots;
1880
+ user-source work may fill all of them. A limit of 1 has no spare slot, so the
1881
+ reservation is off there. A refused begin stays queued and is retried when a
1882
+ slot frees; a submitted execution is never cancelled.
1883
+
1884
+ ```ts
1885
+ const bot = new BotCollaboration(server, ledger, { ...options, deviceConcurrency: 8 });
1886
+ ```
1887
+
1888
+ The rule has no effect on the SDK wire, the protocol or the K4 FIFO contract.
1889
+ It changes only the `sequence` of intents that never reached the SDK.
1890
+
1891
+ `coalesce` is a policy before enqueue, so an open batch has no intent yet.
1892
+ A batch seals when its Bot is idle (`idle`) or at its other seal reasons. A
1893
+ queued `bot_request` keeps the Bot busy, so with coalescing on, an open batch
1894
+ waits behind that work and its Turn joins the FIFO after the seal. Without
1895
+ coalescing, the user input becomes the next submitted intent. A Host that
1896
+ needs the strict order with coalescing must seal its batch sooner or leave
1897
+ coalescing off. This is the remaining interaction of #1229 item 1.
1898
+
1899
+ ## Inbound disposition (#1229)
1900
+
1901
+ Every inbound human message gets one deterministic destination, derived from
1902
+ the rows the Host already writes. There is no second disposition table:
1903
+ `inboundDispositions()` reads the inbound, input-batch and Turn rows.
1904
+
1905
+ | Destination | Meaning |
1906
+ | --- | --- |
1907
+ | `filtered(code)` | Refused before a Turn: `unverified_sender` or `not_owner`. The audit row stays. |
1908
+ | `coalesced(turnId)` | In the Turn `turnId`, including a merged input whose batch is still open. |
1909
+ | `answered(turnId)` | The Turn succeeded. |
1910
+ | `failed(turnId)` | The Turn failed, expired or was superseded. |
1911
+ | `cancelled(turnId)` | The owner cancelled the Turn or its batch. |
1912
+
1913
+ A 1:1 input names the batch Turn that answers it. A room input names its round
1914
+ id; the round's seat Turns decide the destination. A recorded message whose
1915
+ Turn was retained away reads `failed`, never nothing, so the Host UI cannot
1916
+ show a message with no destination.
1917
+
1918
+ ```ts
1919
+ const rows = bot.inboundDispositions(); // oldest first, from the ledger
1920
+ ```
1921
+
1922
+ Each transition is published once as
1923
+ `inbound:<id>:<destination>:<turnId>` (or `inbound:<id>:filtered:<code>`).
1924
+ The id names the destination, so a projection value never changes. The rows
1925
+ are Host UI history: never in a ContextPack and never on the wire.
1926
+
1927
+ `echo`, a direct bot message (`bot_audit`) and a group bot message
1928
+ (`bot_background`) keep their delivery, audit and round rows; this projection
1929
+ covers every inbound human message.
1930
+
1931
+ ## IM channel input
1932
+
1933
+ This section covers slices M2 and M3 of the Octop plan for issue #552.
1934
+ The rules are in the [Host IM adapter guide](../../docs/host-im-adapter.md).
1935
+ A channel adapter takes the sender from authenticated platform data and gives
1936
+ a `Principal` with an `id` and the `kind` `human` or `bot`. Give principal ids
1937
+ a namespace that no Bot id uses, for example `im:<platform user id>`. Room
1938
+ history shows both kinds of id in `from`. The adapter maps the platform chat
1939
+ to a Bot id (`direct`) or a room id (`group`). It maps mention entities to Bot
1940
+ ids.
1941
+
1942
+ `receive(message)` classifies one `InboundMessage` with `classifyInbound`, in
1943
+ the order of the guide's §3. The first match wins.
1944
+
1945
+ | Sender and conversation | Result |
1946
+ | --- | --- |
1947
+ | No verified principal | `unverified_sender`. Audit only. |
1948
+ | Own bot account, listed in `channel.self` | `echo`. Exact delivery reconciliation only. No Turn or seat. |
1949
+ | Bot, 1:1 | `bot_audit`. Audit only. No Turn. |
1950
+ | Bot, group | `bot_background`. A room message without a seat, also with mention entities. |
1951
+ | Owner, 1:1 | `owner_input`. `input` with the principal. |
1952
+ | Other human, 1:1 | `not_owner`. Audit only. |
1953
+ | Human, group | `room_input`. `roomInput` with the principal. Mention entities select seats. |
1954
+
1955
+ The input key is `inboundKey(message)`, the hash of channel, conversation id,
1956
+ and platform message id. A redelivered event returns the same id. The Host
1957
+ never scans text for mentions.
1958
+
1959
+ `BotOptions.owner` is the owner principal id. The default is `owner`. Only the
1960
+ human principal with this id passes the owner check. These owner APIs take an
1961
+ optional last `principal`: `input`, `answer`, `decide`, `cancelTurn`,
1962
+ `cancelDelegation`, and `abandonDelegation`. The check runs first. Without a
1963
+ principal argument, the call acts as the owner, so the Host must authenticate
1964
+ the caller. A given `undefined`, `null`, or malformed principal is refused with
1965
+ `unverified_sender`. Any other principal that is not the owner is refused with
1966
+ `not_owner`. Each refusal writes an audit row before the call rejects. For an
1967
+ IM action, pass the principal that the adapter verified. Accept an approval
1968
+ only from a verified button callback, never from a text command.
1969
+
1970
+ `roomInput` takes the same optional `principal`, with the same
1971
+ `unverified_sender` rule. Any verified human can post. The room message
1972
+ records the principal id in `from`, and a seat request records it in
1973
+ `requestFrom`. Without a principal, `from` is `user`. A bot principal's
1974
+ mentions select no seat. The delivery owner APIs below use the same principal rule.
1975
+
1976
+ ### Delivery outbox
1977
+
1978
+ Set `BotOptions.channel` to enable the Host outbox:
1979
+
1980
+ ```ts
1981
+ channel: {
1982
+ port: channelPort,
1983
+ self: { slack: ['im:our-bot-account'] },
1984
+ sendTimeoutMs: 15_000,
1985
+ }
1986
+ ```
1987
+
1988
+ `ChannelPort` sends final text and can read back a delivery id. Its `send`
1989
+ result is `accepted` with a platform message id, or an explicit `rejected`
1990
+ result with a code, retryability and optional `retryAfterMs`. The port owns
1991
+ platform authentication and keeps bot tokens in the Host credential broker.
1992
+ The Host never puts the port or a channel secret in a Bot toolset.
1993
+
1994
+ Add a `replyRoute` to an authenticated `InboundMessage`. Its channel must
1995
+ match the message, and its `inboundId` must equal `platformMessageId`.
1996
+ The Host saves it with input admission, before it can process a reply.
1997
+ An input batch uses its newest member's route. The route reference in a
1998
+ Delivery is the Host's `inboundKey`; the port receives the original platform
1999
+ inbound id and credential. Reply tokens stay in Host-only ledger state.
2000
+ Do not publish or log the raw ledger or `snapshot()` as an IM view.
2001
+
2002
+ Push is off by default. These owner APIs operate on a direct Bot conversation
2003
+ or a group room:
2004
+
2005
+ ```ts
2006
+ const routeId = await bot.enablePushRoute(
2007
+ { kind: 'direct', id: 'main' }, 'slack', 'platform-conversation-id', principal,
2008
+ );
2009
+ await bot.revokePushRoute(routeId, principal);
2010
+ const newDeliveryId = await bot.resendDelivery(unknownDeliveryId, principal);
2011
+ ```
2012
+
2013
+ Enabling a replacement revokes the old push route of that conversation.
2014
+ A push target is a non-secret platform target, never a reply credential.
2015
+ Only the owner can enable, revoke or resend. As with the other owner APIs,
2016
+ an omitted principal means that the Host already authenticated the owner.
2017
+ A manual resend requires a usable reply route or an active push route. It
2018
+ creates a new id and preserves the old unknown row. It can show a duplicate
2019
+ message if the original send arrived.
2020
+
2021
+ `consumeMessage` records first acceptance and its pending Delivery in the
2022
+ same SQLite transaction. Exact redelivery creates no second row. Applied
2023
+ room posts, confirmation summaries and questions also create deliveries in
2024
+ their acceptance transaction. Drafts and typed activity create no delivery.
2025
+ Routine output uses only its own conversation's opted-in push route.
2026
+ Without a route, the Host keeps the content in its UI and audits
2027
+ `no_push_route` or `reply_route_expired`.
2028
+
2029
+ Each process pass calls `flushDeliveries`. It commits `sending` and an
2030
+ attempt increment before calling the port. The default business deadline is
2031
+ 15 seconds. A timeout, exception or lost connection gives `unknown` and no
2032
+ automatic resend. An explicit retryable rejection waits for the larger of
2033
+ Retry-After and exponential backoff. At most three sends run. A required
2034
+ wait above 60 seconds is final rejection; it is never shortened.
2035
+
2036
+ Call `recover()` before serving work after restart. It maps persisted
2037
+ `sending` to `unknown`. A port's optional readback can confirm `accepted`,
2038
+ prove `absent`, or return `unsupported`. Only proven absence permits a
2039
+ bounded retry. Readback must complete within the adapter's own I/O budget.
2040
+ Unknown rows have no automatic retry timer. A Host drain can check readback;
2041
+ an authenticated echo can reconcile them without a drain.
2042
+
2043
+ An echo must come from a verified bot principal listed in `channel.self`
2044
+ for that channel. Match its conversation and either `deliveryId` from native
2045
+ platform data or an already-known `platformMessageId`. Never take an echo id
2046
+ from message text. A different bot, human, channel or conversation cannot
2047
+ confirm a delivery. Echoes can arrive while `send` is pending; they do not
2048
+ wait behind the send operation.
2049
+
2050
+ Reply tokens are removed at expiry. They are also removed after the root
2051
+ has no open Turn or seat and no pending/sending delivery on that route.
2052
+ Metadata and delivery audit remain. All delivery state is Host state; it
2053
+ does not change K4, K7, the SDK message disposition or wire messages.
2054
+
2055
+ The ledger is a single-owner reference. Use one Host instance per tenant.
2056
+ The reusable fake-channel test factory is `channelContract` in
2057
+ `src/channel-contract.ts`. Its harness lets downstream adapters run the same
2058
+ Host delivery cases with controlled platform results. A real platform adapter
2059
+ still needs the downstream acceptance in M4.