typeclaw 0.48.12 → 0.49.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 (213) hide show
  1. package/package.json +6 -3
  2. package/scripts/dump-system-prompt.ts +52 -110
  3. package/src/agent/attention-escalation.ts +8 -5
  4. package/src/agent/auth-reloadable.ts +2 -3
  5. package/src/agent/auth.ts +59 -79
  6. package/src/agent/compaction.ts +2 -2
  7. package/src/agent/index.ts +173 -85
  8. package/src/agent/live-sessions.ts +2 -2
  9. package/src/agent/live-subagents.ts +1 -0
  10. package/src/agent/llm-replay-sanitizer.ts +1 -1
  11. package/src/agent/model-overrides.ts +1 -1
  12. package/src/agent/multimodal/look-at.ts +3 -3
  13. package/src/agent/multimodal/read-redirect.ts +1 -1
  14. package/src/agent/plugin-tools.ts +76 -39
  15. package/src/agent/prompt-cache-key.ts +42 -0
  16. package/src/agent/provider-error.ts +179 -10
  17. package/src/agent/reload-tool.ts +1 -1
  18. package/src/agent/restart-handoff/index.ts +7 -14
  19. package/src/agent/reviewer-activity.ts +68 -0
  20. package/src/agent/session-origin.ts +33 -0
  21. package/src/agent/subagents.ts +14 -2
  22. package/src/agent/system-prompt.ts +68 -202
  23. package/src/agent/todo/continuation-policy.ts +12 -4
  24. package/src/agent/tool-error-remediation.ts +1 -1
  25. package/src/agent/tool-file-safety.ts +113 -14
  26. package/src/agent/tool-not-found-nudge.ts +1 -1
  27. package/src/agent/tool-result-budget.ts +2 -2
  28. package/src/agent/tools/channel-disengage.ts +2 -2
  29. package/src/agent/tools/channel-edit.ts +2 -2
  30. package/src/agent/tools/channel-fetch-attachment.ts +2 -2
  31. package/src/agent/tools/channel-history-render.ts +2 -1
  32. package/src/agent/tools/channel-history.ts +2 -2
  33. package/src/agent/tools/channel-react.ts +2 -2
  34. package/src/agent/tools/channel-read.ts +2 -2
  35. package/src/agent/tools/channel-reply.ts +25 -7
  36. package/src/agent/tools/channel-send.ts +51 -9
  37. package/src/agent/tools/curl-impersonate.ts +11 -2
  38. package/src/agent/tools/grant-role.ts +2 -2
  39. package/src/agent/tools/post-github-review.ts +79 -17
  40. package/src/agent/tools/restart.ts +2 -2
  41. package/src/agent/tools/skip-response.ts +4 -4
  42. package/src/agent/tools/spawn-subagent.ts +165 -14
  43. package/src/agent/tools/stream-snapshot.ts +2 -2
  44. package/src/agent/tools/subagent-cancel.ts +2 -2
  45. package/src/agent/tools/subagent-output.ts +10 -2
  46. package/src/agent/tools/todo/index.ts +2 -2
  47. package/src/agent/tools/webfetch/tool.ts +2 -2
  48. package/src/agent/tools/websearch.ts +2 -2
  49. package/src/bundled-plugins/backup/README.md +10 -9
  50. package/src/bundled-plugins/backup/runner.ts +140 -58
  51. package/src/bundled-plugins/backup/subagents.ts +58 -26
  52. package/src/bundled-plugins/github-cli-auth/gh-command.ts +34 -2
  53. package/src/bundled-plugins/github-cli-auth/granted-push.ts +135 -0
  54. package/src/bundled-plugins/github-cli-auth/index.ts +83 -11
  55. package/src/bundled-plugins/github-cli-auth/review-account.ts +23 -0
  56. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -2
  57. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +45 -7
  58. package/src/bundled-plugins/operator/operator.ts +15 -4
  59. package/src/bundled-plugins/reviewer/skills/code-review.ts +1 -1
  60. package/src/bundled-plugins/security/index.ts +50 -2
  61. package/src/bundled-plugins/security/policies/git-exfil.ts +24 -12
  62. package/src/channels/adapters/discord-bot-reactions.ts +18 -0
  63. package/src/channels/adapters/discord-bot.ts +122 -67
  64. package/src/channels/adapters/discord-reactions.ts +18 -0
  65. package/src/channels/adapters/discord.ts +114 -8
  66. package/src/channels/adapters/github/inbound.ts +103 -8
  67. package/src/channels/adapters/github/index.ts +251 -19
  68. package/src/channels/adapters/github/last-alive.ts +27 -0
  69. package/src/channels/adapters/github/outbound.ts +54 -18
  70. package/src/channels/adapters/github/pending-review-store.ts +141 -0
  71. package/src/channels/adapters/github/permission-guidance.ts +1 -0
  72. package/src/channels/adapters/github/reactions.ts +100 -0
  73. package/src/channels/adapters/github/reconcile-cooldown-store.ts +197 -67
  74. package/src/channels/adapters/github/reconcile-open-prs.ts +418 -33
  75. package/src/channels/adapters/github/recovery.ts +106 -0
  76. package/src/channels/adapters/github/review-check.ts +510 -0
  77. package/src/channels/adapters/github/review-submitter.ts +34 -2
  78. package/src/channels/adapters/instagram.ts +32 -14
  79. package/src/channels/adapters/kakaotalk.ts +22 -7
  80. package/src/channels/adapters/line.ts +18 -3
  81. package/src/channels/adapters/outbound-account.ts +20 -0
  82. package/src/channels/adapters/own-reactions.ts +66 -0
  83. package/src/channels/adapters/recovery-correlation.ts +214 -0
  84. package/src/channels/adapters/slack-bot-classify.ts +18 -11
  85. package/src/channels/adapters/slack-bot-dedupe.ts +111 -28
  86. package/src/channels/adapters/slack-bot-reactions.ts +18 -0
  87. package/src/channels/adapters/slack-bot.ts +125 -57
  88. package/src/channels/adapters/slack-classify.ts +25 -4
  89. package/src/channels/adapters/slack-inbound-revision.ts +96 -0
  90. package/src/channels/adapters/slack-reactions.ts +18 -0
  91. package/src/channels/adapters/slack-thread-ts.ts +6 -0
  92. package/src/channels/adapters/slack.ts +48 -3
  93. package/src/channels/adapters/teams.ts +14 -4
  94. package/src/channels/adapters/telegram-bot.ts +56 -10
  95. package/src/channels/adapters/webex-bot.ts +12 -2
  96. package/src/channels/adapters/webex.ts +12 -2
  97. package/src/channels/background-handoff.ts +434 -0
  98. package/src/channels/background-obligations.ts +893 -0
  99. package/src/channels/continuity-types.ts +271 -0
  100. package/src/channels/github-review-check.ts +598 -0
  101. package/src/channels/github-review-turn-ledger.ts +102 -28
  102. package/src/channels/github-review-verdict-coordinator.ts +96 -13
  103. package/src/channels/github-token-bridge.ts +11 -5
  104. package/src/channels/inbound-journal.ts +1738 -0
  105. package/src/channels/index.ts +6 -1
  106. package/src/channels/manager.ts +17 -7
  107. package/src/channels/recovery-dispatcher.ts +264 -0
  108. package/src/channels/recovery-notice.ts +94 -0
  109. package/src/channels/recovery-outbox.ts +459 -0
  110. package/src/channels/router.ts +2582 -633
  111. package/src/channels/schema.ts +8 -1
  112. package/src/channels/subagent-completion-bridge.ts +17 -14
  113. package/src/channels/types.ts +121 -16
  114. package/src/channels/waiting-reactions.ts +664 -0
  115. package/src/cli/compose.ts +7 -4
  116. package/src/cli/hostd.ts +49 -3
  117. package/src/cli/inspect.ts +11 -14
  118. package/src/cli/model.ts +7 -5
  119. package/src/cli/oauth-callbacks.ts +38 -23
  120. package/src/coding-agent/broker-body.ts +38 -0
  121. package/src/coding-agent/broker.ts +290 -0
  122. package/src/coding-agent/claude.ts +95 -0
  123. package/src/coding-agent/codex.ts +104 -0
  124. package/src/coding-agent/index.ts +506 -0
  125. package/src/coding-agent/omo-state.ts +69 -0
  126. package/src/coding-agent/omo-stream.ts +98 -0
  127. package/src/coding-agent/omo.ts +192 -0
  128. package/src/coding-agent/runner.ts +263 -0
  129. package/src/coding-agent/tool.ts +62 -0
  130. package/src/coding-agent/worktree.ts +355 -0
  131. package/src/compose/restart.ts +10 -3
  132. package/src/compose/start.ts +20 -3
  133. package/src/config/config.ts +70 -26
  134. package/src/config/providers.ts +278 -50
  135. package/src/container/exit-reason.ts +44 -0
  136. package/src/container/index.ts +5 -0
  137. package/src/container/log-archive.ts +51 -13
  138. package/src/container/memory-limit.ts +1 -1
  139. package/src/container/memory-oversubscription.ts +36 -6
  140. package/src/container/oom-events.ts +86 -0
  141. package/src/container/restart.ts +2 -0
  142. package/src/container/shared.ts +8 -1
  143. package/src/container/start.ts +25 -13
  144. package/src/container/stop.ts +6 -2
  145. package/src/container/tool-oom-priority.ts +32 -0
  146. package/src/cron/consumer.ts +10 -4
  147. package/src/cron/reloadable.ts +23 -2
  148. package/src/doctor/checks.ts +14 -2
  149. package/src/hostd/daemon.ts +20 -10
  150. package/src/hostd/spawn.ts +106 -5
  151. package/src/hostd/version.ts +20 -0
  152. package/src/hostd/watchdog.ts +241 -0
  153. package/src/init/dockerfile.ts +57 -592
  154. package/src/init/index.ts +6 -7
  155. package/src/init/oauth-login.ts +57 -17
  156. package/src/inspect/transcript-view.ts +6 -3
  157. package/src/mcp/client.ts +3 -1
  158. package/src/operations/classify-tool-outcome.ts +45 -1
  159. package/src/operations/incidents.ts +10 -5
  160. package/src/plugin/core-tool-names.ts +1 -1
  161. package/src/plugin/define.ts +1 -0
  162. package/src/plugin/index.ts +1 -0
  163. package/src/plugin/types.ts +6 -1
  164. package/src/run/background-handoff-boot.ts +86 -0
  165. package/src/run/channel-session-factory.ts +5 -4
  166. package/src/run/index.ts +93 -93
  167. package/src/run/resource-sample.ts +19 -0
  168. package/src/sandbox/build.ts +4 -0
  169. package/src/sandbox/coding-agent.ts +214 -0
  170. package/src/sandbox/policy.ts +1 -0
  171. package/src/sandbox/runtime-private.ts +4 -1
  172. package/src/secrets/coding-agent-auth.ts +97 -0
  173. package/src/secrets/index.ts +0 -16
  174. package/src/secrets/refresh-provider-oauth.ts +30 -76
  175. package/src/secrets/schema.ts +3 -4
  176. package/src/secrets/storage.ts +133 -234
  177. package/src/server/command-runner.ts +6 -2
  178. package/src/server/index.ts +102 -41
  179. package/src/sessions/index.ts +1 -1
  180. package/src/skills/typeclaw-channel-github/SKILL.md +7 -5
  181. package/src/skills/typeclaw-claude-code/SKILL.md +25 -260
  182. package/src/skills/typeclaw-claude-code/references/auth-flow.md +7 -23
  183. package/src/skills/typeclaw-claude-code/references/headless-sessions.md +11 -0
  184. package/src/skills/typeclaw-claude-code/references/results-and-worktrees.md +13 -0
  185. package/src/skills/typeclaw-codex-cli/SKILL.md +35 -270
  186. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +13 -20
  187. package/src/skills/typeclaw-codex-cli/references/headless-sessions.md +26 -0
  188. package/src/skills/typeclaw-codex-cli/references/results-and-worktrees.md +28 -0
  189. package/src/skills/typeclaw-config/SKILL.md +24 -24
  190. package/src/skills/typeclaw-config/references/dockerfile.md +14 -13
  191. package/src/skills/typeclaw-cron/SKILL.md +1 -1
  192. package/src/skills/typeclaw-github-contributing/SKILL.md +2 -2
  193. package/src/skills/typeclaw-memory/SKILL.md +3 -3
  194. package/src/skills/typeclaw-omo-cli/SKILL.md +52 -0
  195. package/src/skills/typeclaw-omo-cli/references/auth-flow.md +11 -0
  196. package/src/skills/typeclaw-omo-cli/references/headless-sessions.md +11 -0
  197. package/src/skills/typeclaw-omo-cli/references/results-and-worktrees.md +23 -0
  198. package/src/skills/typeclaw-plugins/SKILL.md +20 -20
  199. package/src/skills/typeclaw-skills/SKILL.md +19 -2
  200. package/src/skills/typeclaw-troubleshooting/SKILL.md +15 -2
  201. package/src/tui/index.ts +5 -3
  202. package/src/tui/theme.ts +1 -1
  203. package/typeclaw.schema.json +44 -2
  204. package/src/agent/adaptive-thinking-compat.ts +0 -79
  205. package/src/secrets/claude-credentials-json.ts +0 -129
  206. package/src/secrets/codex-auth-json.ts +0 -102
  207. package/src/secrets/export-claude-credentials-file.ts +0 -270
  208. package/src/secrets/export-codex-auth-file.ts +0 -250
  209. package/src/secrets/oauth-xai.ts +0 -348
  210. package/src/skills/typeclaw-claude-code/references/stop-hook.md +0 -101
  211. package/src/skills/typeclaw-claude-code/references/tmux-driving.md +0 -243
  212. package/src/skills/typeclaw-codex-cli/references/stop-hook.md +0 -92
  213. package/src/skills/typeclaw-codex-cli/references/tmux-driving.md +0 -239
@@ -0,0 +1,1738 @@
1
+ import { createHash, randomUUID } from 'node:crypto'
2
+ import { mkdir, open, rename, unlink } from 'node:fs/promises'
3
+ import type { FileHandle } from 'node:fs/promises'
4
+ import { dirname, resolve } from 'node:path'
5
+
6
+ import { z } from 'zod'
7
+
8
+ import type { MatchableOrigin } from '../permissions/resolve'
9
+ import type { BackgroundObligation, BackgroundObligationRef, BackgroundObligationStore } from './background-obligations'
10
+ import { parseBackgroundObligation } from './background-obligations'
11
+ import { parseRecoveryRecord, recoveryPayload } from './continuity-types'
12
+ import type { RecoveryNoticeCause, RecoveryRecord } from './continuity-types'
13
+ import { createRecoveryNotice, recoveryNoticePartitionKey } from './recovery-notice'
14
+ import type { RecoveryOutbox } from './recovery-outbox'
15
+ import { channelKeyId } from './types'
16
+ import type { ChannelKey } from './types'
17
+
18
+ export type InboundRef = { inputId: string; generation: number }
19
+ export type InboundOutcome = {
20
+ kind: 'delivered' | 'intentionally-suppressed'
21
+ decisionId: string
22
+ reason?: string
23
+ deliveryId?: string
24
+ }
25
+ type InboundReference = { messageId?: string; receiptId?: string }
26
+ /** An input that still owes a response or a notice keeps its full admission provenance. */
27
+ export type OpenInboundRecord = InboundRef & {
28
+ schemaVersion: 1
29
+ identity: string
30
+ accountIdentity: string
31
+ target: ChannelKey
32
+ principal: MatchableOrigin
33
+ epoch: string
34
+ acceptedAt: number
35
+ reference?: InboundReference
36
+ sourceParentSessionId?: string
37
+ phase: 'admitted' | 'turn-owned' | 'notice-prepared' | 'notice-owned'
38
+ claim?: { turnId: string; ownerSessionId?: string; epoch: string; generation: number }
39
+ transfer?: RecoveryRecord
40
+ }
41
+ /**
42
+ * Closed authority, kept indefinitely because no adapter replay floor is proven. It holds only what a
43
+ * later delivery or stale callback is judged against: the exact identity (`inputId`), the terminal
44
+ * generation and outcome, the frozen author fence, the Slack message representative (`messageKey`,
45
+ * ordered by `acceptedAt`), the platform reference, and the delivery of the frozen notice that
46
+ * covered it (whose payload the journal keeps once per delivery).
47
+ */
48
+ export type ClosedInboundRecord = InboundRef & {
49
+ phase: 'closed'
50
+ acceptedAt: number
51
+ reference?: InboundReference
52
+ principalDigest: string
53
+ messageKey?: string
54
+ outcome: InboundOutcome
55
+ noticeDeliveryId?: string
56
+ }
57
+ export type InboundRecord = OpenInboundRecord | ClosedInboundRecord
58
+ export type InboundAdmission = {
59
+ accountIdentity: string
60
+ target: ChannelKey
61
+ principal: MatchableOrigin
62
+ messageId?: string
63
+ eventKind: string
64
+ revision: string
65
+ receiptId?: string
66
+ reference?: { messageId?: string; receiptId?: string }
67
+ ownerSessionId?: string
68
+ }
69
+ /** The schema-1 row every decision line carries in full, closed rows included. */
70
+ type JournalRow = Omit<OpenInboundRecord, 'phase'> & { phase: InboundRecord['phase']; outcome?: InboundOutcome }
71
+ type Owner = { turnId: string; ownerSessionId?: string; target: ChannelKey; fromTurnId?: string }
72
+ type Change = { expected: InboundRef; row: JournalRow }
73
+ type BackgroundChange = { expected: BackgroundObligationRef; row: BackgroundObligation }
74
+ type Decision = {
75
+ schemaVersion: 1
76
+ seq: number
77
+ transitionId: string
78
+ epoch: string
79
+ type: string
80
+ changes: Change[]
81
+ backgroundChanges: BackgroundChange[]
82
+ requestDigest?: string
83
+ }
84
+ type Applied = {
85
+ schemaVersion: 1
86
+ seq: number
87
+ transitionId: string
88
+ epoch: string
89
+ type: 'mixed-applied'
90
+ decisionId: string
91
+ decisionDigest: string
92
+ }
93
+ type DecisionReceipt = {
94
+ transitionId: string
95
+ seq: number
96
+ /** Absent only on receipts carried over from a schema-1 snapshot. */
97
+ epoch?: string
98
+ type: string
99
+ decisionDigest: string
100
+ payloadDigest: string
101
+ requestDigest?: string
102
+ inboundRefs: InboundRef[]
103
+ backgroundRefs: BackgroundObligationRef[]
104
+ }
105
+ /** Snapshot written before tombstones: every row in full. Read-only compatibility. */
106
+ type LegacySnapshot = {
107
+ schemaVersion: 1
108
+ seq: number
109
+ type: 'snapshot'
110
+ rows: JournalRow[]
111
+ decisions: Decision[]
112
+ receipts: DecisionReceipt[]
113
+ }
114
+ type SnapshotOpenRow = Omit<OpenInboundRecord, 'transfer'> & { notice?: string }
115
+ type Snapshot = {
116
+ schemaVersion: 2
117
+ seq: number
118
+ type: 'snapshot'
119
+ /** Frozen transfer payloads, once per delivery; rows refer to them by deliveryId. */
120
+ notices: RecoveryRecord[]
121
+ open: SnapshotOpenRow[]
122
+ closed: ClosedInboundRecord[]
123
+ /** Mixed decisions whose background application is not yet recorded, in full. */
124
+ decisions: Decision[]
125
+ receipts: DecisionReceipt[]
126
+ }
127
+ type Line = Decision | Applied | LegacySnapshot | Snapshot
128
+ const canonical = (value: unknown): string => {
129
+ if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
130
+ if (value && typeof value === 'object')
131
+ return `{${Object.entries(value)
132
+ .filter(([, v]) => v !== undefined)
133
+ .sort(([a], [b]) => a.localeCompare(b))
134
+ .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`)
135
+ .join(',')}}`
136
+ return JSON.stringify(value) ?? 'null'
137
+ }
138
+ const digest = (value: unknown) => createHash('sha256').update(canonical(value)).digest('hex')
139
+ const copy = <T>(value: T): T => JSON.parse(JSON.stringify(value))
140
+ const integer = (n: unknown) => Number.isSafeInteger(n) && Number(n) > 0
141
+ const id = (value: unknown) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
142
+ const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
143
+ const principalDigest = (principal: MatchableOrigin) => digest(['principal', principal])
144
+ /** Below this much growth the journal is never rewritten; above it, once growth reaches the last snapshot's size. */
145
+ const COMPACTION_FLOOR_BYTES = 1024 * 1024
146
+ const READ_CHUNK_BYTES = 64 * 1024
147
+ const activeWriters = new Map<string, InboundJournal>()
148
+ async function syncDirectory(path: string) {
149
+ let fd: FileHandle
150
+ try {
151
+ fd = await open(path, 'r')
152
+ } catch (error) {
153
+ if (
154
+ process.platform === 'win32' &&
155
+ ['EPERM', 'EINVAL', 'EISDIR'].includes((error as NodeJS.ErrnoException).code ?? '')
156
+ )
157
+ return
158
+ throw error
159
+ }
160
+ try {
161
+ await fd.sync()
162
+ } catch (error) {
163
+ if (
164
+ process.platform !== 'win32' ||
165
+ !['EPERM', 'EINVAL', 'EISDIR'].includes((error as NodeJS.ErrnoException).code ?? '')
166
+ )
167
+ throw error
168
+ } finally {
169
+ await fd.close()
170
+ }
171
+ }
172
+ const positive = z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
173
+ const nonempty = z.string().min(1)
174
+ const hex = z.string().regex(/^[a-f0-9]{64}$/)
175
+ const referenceSchema = z.object({ messageId: nonempty.optional(), receiptId: nonempty.optional() }).strict()
176
+ const outcomeSchema = z
177
+ .object({
178
+ kind: z.enum(['delivered', 'intentionally-suppressed']),
179
+ decisionId: nonempty,
180
+ reason: z.string().optional(),
181
+ deliveryId: nonempty.optional(),
182
+ })
183
+ .strict()
184
+ const rowSchema = z
185
+ .object({
186
+ schemaVersion: z.literal(1),
187
+ inputId: hex,
188
+ generation: positive,
189
+ identity: nonempty,
190
+ accountIdentity: nonempty,
191
+ epoch: nonempty,
192
+ acceptedAt: z.number().finite().nonnegative(),
193
+ target: z.unknown(),
194
+ principal: z.unknown(),
195
+ reference: referenceSchema.optional(),
196
+ sourceParentSessionId: nonempty.optional(),
197
+ phase: z.enum(['admitted', 'turn-owned', 'notice-prepared', 'notice-owned', 'closed']),
198
+ claim: z
199
+ .object({ turnId: nonempty, ownerSessionId: nonempty.optional(), epoch: nonempty, generation: positive })
200
+ .strict()
201
+ .optional(),
202
+ transfer: z.unknown().optional(),
203
+ outcome: outcomeSchema.optional(),
204
+ })
205
+ .strict()
206
+ const closedSchema = z
207
+ .object({
208
+ inputId: hex,
209
+ generation: positive,
210
+ phase: z.literal('closed'),
211
+ acceptedAt: z.number().finite().nonnegative(),
212
+ reference: referenceSchema.optional(),
213
+ principalDigest: hex,
214
+ messageKey: hex.optional(),
215
+ outcome: outcomeSchema,
216
+ noticeDeliveryId: hex.optional(),
217
+ })
218
+ .strict()
219
+ const inboundExpectedSchema = z
220
+ .object({
221
+ inputId: hex,
222
+ generation: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
223
+ })
224
+ .strict()
225
+ const backgroundExpectedSchema = z.object({ obligationId: hex, generation: positive }).strict()
226
+ const decisionSchema = z
227
+ .object({
228
+ schemaVersion: z.literal(1),
229
+ seq: positive,
230
+ transitionId: nonempty,
231
+ epoch: nonempty,
232
+ type: z.enum(['admitted', 'turn-claimed', 'ownership-moved', 'outcome-decided', 'notice-prepared', 'notice-owned']),
233
+ changes: z.array(z.object({ expected: inboundExpectedSchema, row: z.unknown() }).strict()),
234
+ backgroundChanges: z.array(z.object({ expected: backgroundExpectedSchema, row: z.unknown() }).strict()),
235
+ requestDigest: hex.optional(),
236
+ })
237
+ .strict()
238
+ const legacyReceiptSchema = z
239
+ .object({
240
+ transitionId: nonempty,
241
+ seq: positive,
242
+ type: decisionSchema.shape.type,
243
+ decisionDigest: hex,
244
+ payloadDigest: hex,
245
+ requestDigest: hex.optional(),
246
+ inboundRefs: z.array(inboundExpectedSchema),
247
+ backgroundRefs: z.array(backgroundExpectedSchema),
248
+ })
249
+ .strict()
250
+ const receiptSchema = legacyReceiptSchema.extend({ epoch: nonempty.optional() }).strict()
251
+ const legacySnapshotSchema = z
252
+ .object({
253
+ schemaVersion: z.literal(1),
254
+ seq: positive,
255
+ type: z.literal('snapshot'),
256
+ rows: z.array(z.unknown()),
257
+ decisions: z.array(z.unknown()),
258
+ receipts: z.array(legacyReceiptSchema),
259
+ })
260
+ .strict()
261
+ const snapshotSchema = z
262
+ .object({
263
+ schemaVersion: z.literal(2),
264
+ seq: positive,
265
+ type: z.literal('snapshot'),
266
+ notices: z.array(z.unknown()),
267
+ open: z.array(z.unknown()),
268
+ closed: z.array(closedSchema),
269
+ decisions: z.array(z.unknown()),
270
+ receipts: z.array(receiptSchema),
271
+ })
272
+ .strict()
273
+ const appliedSchema = z
274
+ .object({
275
+ schemaVersion: z.literal(1),
276
+ seq: positive,
277
+ transitionId: nonempty,
278
+ epoch: nonempty,
279
+ type: z.literal('mixed-applied'),
280
+ decisionId: nonempty,
281
+ decisionDigest: hex,
282
+ })
283
+ .strict()
284
+ function validateRow(row: JournalRow) {
285
+ rowSchema.parse(row)
286
+ if (digest(['inbound', row.identity]) !== row.inputId) throw new Error('Invalid inbound journal identity')
287
+ createRecoveryNotice({
288
+ target: row.target,
289
+ accountIdentity: row.accountIdentity,
290
+ principal: row.principal,
291
+ covers: [{ store: 'inbound', id: row.inputId, generation: row.generation }],
292
+ transferId: row.inputId,
293
+ recoveryGeneration: row.inputId,
294
+ createdAt: row.acceptedAt,
295
+ })
296
+ if (
297
+ (row.phase === 'closed') !== !!row.outcome ||
298
+ (row.claim && (row.phase !== 'turn-owned' || row.claim.generation !== row.generation))
299
+ )
300
+ throw new Error('Invalid inbound state fields')
301
+ if (!['admitted', 'turn-owned', 'notice-prepared', 'notice-owned', 'closed'].includes(row.phase))
302
+ throw new Error('Invalid inbound phase')
303
+ if (
304
+ row.phase === 'turn-owned' &&
305
+ (!row.claim || !row.claim.turnId || !row.claim.epoch || row.claim.generation !== row.generation)
306
+ )
307
+ throw new Error('Invalid inbound claim generation')
308
+ if (
309
+ row.phase === 'closed' &&
310
+ (!row.outcome || !['delivered', 'intentionally-suppressed'].includes(row.outcome.kind) || !row.outcome.decisionId)
311
+ )
312
+ throw new Error('Invalid inbound outcome')
313
+ if (row.phase.startsWith('notice-') && !row.transfer) throw new Error('Missing inbound transfer')
314
+ if (row.transfer) {
315
+ parseRecoveryRecord(row.transfer)
316
+ if (
317
+ row.transfer.accountIdentity !== row.accountIdentity ||
318
+ channelKeyId(row.transfer.target) !== channelKeyId(row.target) ||
319
+ canonical(row.transfer.principal) !== canonical(row.principal) ||
320
+ !row.transfer.covers.some((c) => c.store === 'inbound' && c.id === row.inputId && c.generation <= row.generation)
321
+ )
322
+ throw new Error('Invalid inbound transfer coverage')
323
+ }
324
+ }
325
+ // Boot has no live owner: the captured claim owner supersedes the immutable admission/launch parent.
326
+ const inboundPartition = (row: OpenInboundRecord) =>
327
+ recoveryNoticePartitionKey({
328
+ target: row.target,
329
+ accountIdentity: row.accountIdentity,
330
+ principal: row.principal,
331
+ parentSessionId: row.claim?.ownerSessionId ?? row.sourceParentSessionId,
332
+ })
333
+ const backgroundPartition = (row: BackgroundObligation) =>
334
+ recoveryNoticePartitionKey({
335
+ target: row.target,
336
+ accountIdentity: row.accountIdentity,
337
+ principal: row.principal,
338
+ parentSessionId: row.claim?.ownerSessionId ?? row.parentSessionId,
339
+ })
340
+ /**
341
+ * A Slack message is its ts within the authenticated account's workspace/chat. Routing thread and
342
+ * edit revision are delivery shapes of that one message, so a single admission answers all of them.
343
+ * The key is a digest so a closed tombstone can keep it without the identity it was derived from.
344
+ */
345
+ const slackMessageKey = (input: {
346
+ root: string
347
+ accountIdentity: string
348
+ target: ChannelKey
349
+ messageId?: string
350
+ eventKind: string
351
+ }) =>
352
+ (input.target.adapter === 'slack' || input.target.adapter === 'slack-bot') && input.messageId
353
+ ? digest([
354
+ 'slack-message',
355
+ input.root,
356
+ input.accountIdentity,
357
+ input.target.adapter,
358
+ input.target.workspace,
359
+ input.target.chat,
360
+ input.messageId,
361
+ input.eventKind,
362
+ ])
363
+ : undefined
364
+ /** Derived from the stored identity tuple; rows that cannot be decoded keep exact-identity dedupe only. */
365
+ function storedSlackMessageKey(row: JournalRow) {
366
+ const messageId = row.reference?.messageId
367
+ if (!messageId || (row.target.adapter !== 'slack' && row.target.adapter !== 'slack-bot')) return undefined
368
+ let tuple: unknown
369
+ try {
370
+ tuple = JSON.parse(row.identity)
371
+ } catch {
372
+ return undefined
373
+ }
374
+ if (
375
+ !Array.isArray(tuple) ||
376
+ tuple.length !== 6 ||
377
+ typeof tuple[0] !== 'string' ||
378
+ typeof tuple[4] !== 'string' ||
379
+ !tuple[4] ||
380
+ tuple[1] !== row.accountIdentity ||
381
+ tuple[2] !== channelKeyId(row.target) ||
382
+ tuple[3] !== messageId
383
+ )
384
+ return undefined
385
+ return slackMessageKey({
386
+ root: tuple[0],
387
+ accountIdentity: row.accountIdentity,
388
+ target: row.target,
389
+ messageId,
390
+ eventKind: tuple[4],
391
+ })
392
+ }
393
+ function storedEventKind(identity: string): string | undefined {
394
+ let tuple: unknown
395
+ try {
396
+ tuple = JSON.parse(identity)
397
+ } catch {
398
+ return undefined
399
+ }
400
+ return Array.isArray(tuple) && tuple.length === 6 && typeof tuple[4] === 'string' && tuple[4] ? tuple[4] : undefined
401
+ }
402
+ /** The closed form of a full row: identity, terminal state and fences only. */
403
+ function tombstone(row: JournalRow): ClosedInboundRecord {
404
+ const messageKey = storedSlackMessageKey(row)
405
+ return {
406
+ inputId: row.inputId,
407
+ generation: row.generation,
408
+ phase: 'closed',
409
+ acceptedAt: row.acceptedAt,
410
+ ...(row.reference ? { reference: row.reference } : {}),
411
+ principalDigest: principalDigest(row.principal),
412
+ ...(messageKey ? { messageKey } : {}),
413
+ outcome: row.outcome!,
414
+ ...(row.transfer ? { noticeDeliveryId: row.transfer.deliveryId } : {}),
415
+ }
416
+ }
417
+
418
+ /** Single-runtime writer. Callers hold the background target lane through coverage reads and cache publication. */
419
+ export class InboundJournal {
420
+ readonly epoch: string
421
+ readonly path: string
422
+ private fd?: FileHandle
423
+ private sequence = 0
424
+ /** Open rows in full, closed rows as tombstones. Never pruned: no replay floor is proven. */
425
+ private rows = new Map<string, InboundRecord>()
426
+ /** Slack message key → representative inputId; rebuilt from durable rows, never persisted. */
427
+ private slackMessages = new Map<string, string>()
428
+ /** Frozen transfer payload, once per delivery; rows refer to it by deliveryId. */
429
+ private notices = new Map<string, RecoveryRecord>()
430
+ /** Mixed decisions not yet recorded as applied: the only decision bodies kept. */
431
+ private decisions = new Map<string, Decision>()
432
+ /** Idempotency fences a caller can still present; see `retainsReceipt`. */
433
+ private receipts = new Map<string, DecisionReceipt>()
434
+ /** Transition IDs this writer minted itself and never handed to any caller. */
435
+ private minted = new Set<string>()
436
+ private snapshotBytes = 0
437
+ private growthBytes = 0
438
+ private maintaining = false
439
+ private compactionQueued = false
440
+ /**
441
+ * True only while a healthy compaction swaps the closed handle for the installed file's reopened
442
+ * one. The writer queue is held for the whole swap, so in-memory state stays authoritative and
443
+ * readable; no write can run until the replacement handle exists.
444
+ */
445
+ private swapping = false
446
+ private queue: Promise<void> = Promise.resolve()
447
+ private initializing?: Promise<void>
448
+ private initialized = false
449
+ private initializationCancelled = false
450
+ private closing?: Promise<void>
451
+ private frozen?: unknown
452
+ private readonly background?: BackgroundObligationStore
453
+ private readonly failureListeners = new Set<(error: unknown) => void>()
454
+ constructor(
455
+ agentDir: string,
456
+ private readonly options: {
457
+ epoch?: string
458
+ backgroundObligations?: BackgroundObligationStore
459
+ onError?: (error: unknown) => void
460
+ now?: () => number
461
+ onDurability?: (
462
+ phase:
463
+ | 'initialization-directory-created'
464
+ | 'initialization-read'
465
+ | 'append-written'
466
+ | 'append-synced'
467
+ | 'mixed-json-applied'
468
+ | 'compaction-started'
469
+ | 'temp-synced'
470
+ | 'handle-closed'
471
+ | 'replaced'
472
+ | 'directory-synced'
473
+ | 'reopened',
474
+ record?: unknown,
475
+ ) => void | Promise<void>
476
+ onSync?: (milliseconds: number) => void
477
+ /** Internal: growth below which maintenance never rewrites. Not operator configuration. */
478
+ compactionFloorBytes?: number
479
+ } = {},
480
+ ) {
481
+ this.path = resolve(agentDir, 'channels', 'inbound-continuity.jsonl')
482
+ this.background = options.backgroundObligations
483
+ this.epoch = this.background?.epoch ?? options.epoch ?? randomUUID()
484
+ if (options.epoch && options.epoch !== this.epoch) throw new Error('Continuity epoch mismatch')
485
+ this.frozen = new Error('Inbound journal initialization pending')
486
+ this.background?.setFrozen(this.frozen)
487
+ }
488
+ private fail(error: unknown) {
489
+ // Canceled startup has no runtime owner to fence or replay.
490
+ if (this.initializationCancelled) return
491
+ this.frozen = error
492
+ this.background?.setFrozen(error)
493
+ for (const listener of this.failureListeners) listener(error)
494
+ this.options.onError?.(error)
495
+ }
496
+ subscribeFailure(listener: (error: unknown) => void): () => void {
497
+ this.failureListeners.add(listener)
498
+ return () => {
499
+ this.failureListeners.delete(listener)
500
+ }
501
+ }
502
+ /** Operational: initialized writer, not cancelled, frozen or closed, holding a handle or mid-swap. */
503
+ assertAvailable() {
504
+ if (this.initializationCancelled || this.frozen !== undefined || !(this.fd || this.swapping))
505
+ throw new Error('Inbound continuity frozen pending repair', { cause: this.frozen })
506
+ }
507
+ health() {
508
+ return {
509
+ available: !this.initializationCancelled && this.frozen === undefined && !!(this.fd || this.swapping),
510
+ error: this.frozen,
511
+ sequence: this.sequence,
512
+ }
513
+ }
514
+ private serialized<T>(action: () => Promise<T>): Promise<T> {
515
+ const result = this.queue.then(action)
516
+ this.queue = result.then(
517
+ () => {},
518
+ () => {},
519
+ )
520
+ return result
521
+ }
522
+ /** Stop startup before teardown; an operational writer remains available for durable closeout. */
523
+ cancelInitialization() {
524
+ if (!this.initialized) this.initializationCancelled = true
525
+ }
526
+ initialize() {
527
+ return (this.initializing ??= this.serialized(async () => {
528
+ if (this.initializationCancelled) return
529
+ try {
530
+ if (activeWriters.has(this.path) && activeWriters.get(this.path) !== this)
531
+ throw new Error('Inbound journal already has a writer')
532
+ activeWriters.set(this.path, this)
533
+ await mkdir(dirname(this.path), { recursive: true })
534
+ await this.options.onDurability?.('initialization-directory-created')
535
+ if (this.initializationCancelled) return
536
+ await syncDirectory(dirname(dirname(this.path)))
537
+ if (this.initializationCancelled) return
538
+ const { end, size } = await this.load()
539
+ await this.options.onDurability?.('initialization-read')
540
+ if (this.initializationCancelled) return
541
+ if (end !== size) {
542
+ // Windows append handles cannot truncate; repair durably before opening the writer.
543
+ const repair = await open(this.path, 'r+')
544
+ if (this.initializationCancelled) {
545
+ await repair.close()
546
+ return
547
+ }
548
+ try {
549
+ await repair.truncate(end)
550
+ await repair.sync()
551
+ } finally {
552
+ await repair.close()
553
+ }
554
+ }
555
+ if (this.initializationCancelled) return
556
+ this.fd = await open(this.path, 'a+', 0o600)
557
+ if (this.initializationCancelled) return
558
+ await syncDirectory(dirname(this.path))
559
+ if (this.initializationCancelled) return
560
+ await this.repairInternal()
561
+ if (this.initializationCancelled) return
562
+ this.initialized = true
563
+ } catch (error) {
564
+ if (this.initializationCancelled) return
565
+ this.fail(error)
566
+ throw error
567
+ } finally {
568
+ if (this.initializationCancelled) {
569
+ try {
570
+ await this.fd?.close()
571
+ } finally {
572
+ this.fd = undefined
573
+ if (activeWriters.get(this.path) === this) activeWriters.delete(this.path)
574
+ }
575
+ }
576
+ }
577
+ }))
578
+ }
579
+ /**
580
+ * One strict pass over the durable journal: each LF-terminated line is decoded as fatal UTF-8,
581
+ * parsed and folded as it is read, so only normalized state is retained. Bytes after the last LF
582
+ * are a torn append and are reported for truncation; any complete line that fails throws and
583
+ * leaves the file untouched.
584
+ */
585
+ private async load(): Promise<{ end: number; size: number }> {
586
+ let handle: FileHandle
587
+ try {
588
+ handle = await open(this.path, 'r')
589
+ } catch (error) {
590
+ if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
591
+ return { end: 0, size: 0 }
592
+ }
593
+ try {
594
+ const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true })
595
+ const chunk = Buffer.allocUnsafe(READ_CHUNK_BYTES)
596
+ let partial: Buffer[] = []
597
+ let size = 0
598
+ let end = 0
599
+ for (;;) {
600
+ const { bytesRead } = await handle.read(chunk, 0, chunk.length, null)
601
+ if (!bytesRead) break
602
+ const view = chunk.subarray(0, bytesRead)
603
+ let start = 0
604
+ for (let lf = view.indexOf(10); lf !== -1; lf = view.indexOf(10, start)) {
605
+ const line = partial.length ? Buffer.concat([...partial, view.subarray(start, lf)]) : view.subarray(start, lf)
606
+ partial = []
607
+ let text = decoder.decode(line)
608
+ // A whole-file decode skipped one leading byte-order mark; per-line decoding keeps that rule.
609
+ if (end === 0 && text.charCodeAt(0) === 0xfeff) text = text.slice(1)
610
+ this.fold(JSON.parse(text) as Line, line.length + 1)
611
+ start = lf + 1
612
+ end = size + start
613
+ }
614
+ if (start < bytesRead) partial.push(Buffer.from(view.subarray(start)))
615
+ size += bytesRead
616
+ }
617
+ return { end, size }
618
+ } finally {
619
+ await handle.close()
620
+ }
621
+ }
622
+ private fold(line: Line, bytes: number) {
623
+ if (!line || !integer(line.seq)) throw new Error('Invalid journal version or sequence')
624
+ if (line.type === 'snapshot') {
625
+ if (line.schemaVersion !== 1 && line.schemaVersion !== 2) throw new Error('Invalid journal version or sequence')
626
+ if (this.sequence) throw new Error('Invalid journal snapshot position')
627
+ if (line.schemaVersion === 2) this.foldSnapshot(line)
628
+ else this.foldLegacySnapshot(line as LegacySnapshot)
629
+ this.snapshotBytes = bytes
630
+ this.growthBytes = 0
631
+ } else {
632
+ if (line.schemaVersion !== 1) throw new Error('Invalid journal version or sequence')
633
+ if (line.seq !== this.sequence + 1) throw new Error('Noncontiguous journal sequence')
634
+ if (line.type === 'mixed-applied') this.foldApplied(line as Applied)
635
+ else this.foldDecision(line as Decision)
636
+ this.growthBytes += bytes
637
+ }
638
+ this.sequence = line.seq
639
+ }
640
+ private foldLegacySnapshot(snap: LegacySnapshot) {
641
+ legacySnapshotSchema.parse(snap)
642
+ for (const row of snap.rows) {
643
+ validateRow(row)
644
+ if (this.rows.has(row.inputId)) throw new Error('Duplicate snapshot input')
645
+ this.install(row)
646
+ this.indexSlackMessage(this.rows.get(row.inputId)!)
647
+ }
648
+ this.foldSnapshotHistory(snap.seq, snap.receipts, snap.decisions)
649
+ }
650
+ private foldSnapshot(snap: Snapshot) {
651
+ snapshotSchema.parse(snap)
652
+ for (const value of snap.notices) {
653
+ const notice = parseRecoveryRecord(value)
654
+ if (this.notices.has(notice.deliveryId)) throw new Error('Duplicate snapshot notice')
655
+ this.notices.set(notice.deliveryId, notice)
656
+ }
657
+ const referenced = new Set<string>()
658
+ for (const value of snap.open) {
659
+ const { notice, ...fields } = value as SnapshotOpenRow & { transfer?: unknown }
660
+ if (fields.transfer !== undefined) throw new Error('Inline transfer in compact snapshot')
661
+ const transfer = notice === undefined ? undefined : this.notices.get(notice)
662
+ if (notice !== undefined && !transfer) throw new Error('Unknown snapshot notice')
663
+ const row = (transfer ? { ...fields, transfer } : fields) as JournalRow
664
+ validateRow(row)
665
+ if (row.phase === 'closed') throw new Error('Closed row in open snapshot section')
666
+ if (this.rows.has(row.inputId)) throw new Error('Duplicate snapshot input')
667
+ this.rows.set(row.inputId, row as OpenInboundRecord)
668
+ this.indexSlackMessage(row as OpenInboundRecord)
669
+ if (transfer) referenced.add(transfer.deliveryId)
670
+ }
671
+ for (const row of snap.closed) {
672
+ if (this.rows.has(row.inputId)) throw new Error('Duplicate snapshot input')
673
+ if (row.noticeDeliveryId !== undefined) {
674
+ const transfer = this.notices.get(row.noticeDeliveryId)
675
+ if (
676
+ !transfer ||
677
+ principalDigest(transfer.principal) !== row.principalDigest ||
678
+ !transfer.covers.some((c) => c.store === 'inbound' && c.id === row.inputId && c.generation <= row.generation)
679
+ )
680
+ throw new Error('Invalid closed notice coverage')
681
+ referenced.add(transfer.deliveryId)
682
+ }
683
+ this.rows.set(row.inputId, row)
684
+ this.indexSlackMessage(row)
685
+ }
686
+ if (referenced.size !== this.notices.size) throw new Error('Unreferenced snapshot notice')
687
+ this.foldSnapshotHistory(snap.seq, snap.receipts, snap.decisions)
688
+ }
689
+ private foldSnapshotHistory(seq: number, receipts: DecisionReceipt[], decisions: Decision[]) {
690
+ const sequences = new Set<number>()
691
+ const transitions = new Set<string>()
692
+ for (const receipt of receipts) {
693
+ if (receipt.seq > seq || sequences.has(receipt.seq) || transitions.has(receipt.transitionId))
694
+ throw new Error('Invalid snapshot receipt sequence')
695
+ sequences.add(receipt.seq)
696
+ transitions.add(receipt.transitionId)
697
+ for (const ref of receipt.inboundRefs) {
698
+ const row = this.rows.get(ref.inputId)
699
+ if (!row || ref.generation < 1 || ref.generation > row.generation)
700
+ throw new Error('Snapshot receipt has invalid generation')
701
+ }
702
+ if (this.retainsReceipt(receipt.transitionId, receipt.epoch)) this.receipts.set(receipt.transitionId, receipt)
703
+ }
704
+ for (const decision of decisions) {
705
+ this.validateDecision(decision)
706
+ if (
707
+ decision.seq > seq ||
708
+ sequences.has(decision.seq) ||
709
+ transitions.has(decision.transitionId) ||
710
+ !decision.backgroundChanges.length
711
+ )
712
+ throw new Error('Invalid pending snapshot decision')
713
+ sequences.add(decision.seq)
714
+ transitions.add(decision.transitionId)
715
+ for (const change of decision.changes) {
716
+ const current = this.rows.get(change.row.inputId)
717
+ const expected = change.row.phase === 'closed' ? tombstone(change.row) : change.row
718
+ if (canonical(current) !== canonical(expected))
719
+ throw new Error('Snapshot pending decision conflicts with source')
720
+ }
721
+ this.decisions.set(decision.transitionId, decision)
722
+ }
723
+ }
724
+ private foldDecision(decision: Decision) {
725
+ this.validateDecision(decision)
726
+ const pending = this.decisions.get(decision.transitionId)
727
+ const receipt = this.receipts.get(decision.transitionId)
728
+ if (receipt && receipt.decisionDigest !== digest(decision))
729
+ throw new Error('Conflicting compacted transition identity')
730
+ if (pending) {
731
+ if (canonical(pending) !== canonical(decision)) throw new Error('Conflicting duplicate journal transition')
732
+ return
733
+ }
734
+ if (receipt) return
735
+ for (const change of decision.changes) this.validateChange(change, decision.type)
736
+ for (const change of decision.changes) {
737
+ this.install(change.row)
738
+ // Only admission creates a row; later transitions keep its immutable identity.
739
+ if (decision.type === 'admitted') this.indexSlackMessage(this.rows.get(change.row.inputId)!)
740
+ }
741
+ // A mixed decision stays in full until its background application is recorded.
742
+ if (decision.backgroundChanges.length) this.decisions.set(decision.transitionId, decision)
743
+ else this.remember(decision)
744
+ }
745
+ private foldApplied(receipt: Applied) {
746
+ appliedSchema.parse(receipt)
747
+ const decision = this.decisions.get(receipt.decisionId)
748
+ if (
749
+ !decision ||
750
+ digest(decision) !== receipt.decisionDigest ||
751
+ receipt.transitionId !== `applied:${receipt.decisionId}`
752
+ )
753
+ throw new Error('Invalid mixed application receipt')
754
+ this.decisions.delete(receipt.decisionId)
755
+ this.remember(decision)
756
+ }
757
+ /** Applied history is normalized at once: a full decision body never outlives its application. */
758
+ private remember(decision: Decision) {
759
+ if (this.minted.delete(decision.transitionId) || !this.retainsReceipt(decision.transitionId, decision.epoch)) return
760
+ this.receipts.set(decision.transitionId, {
761
+ transitionId: decision.transitionId,
762
+ seq: decision.seq,
763
+ epoch: decision.epoch,
764
+ type: decision.type,
765
+ decisionDigest: digest(decision),
766
+ payloadDigest: digest([decision.type, decision.changes, decision.backgroundChanges]),
767
+ ...(decision.requestDigest !== undefined ? { requestDigest: decision.requestDigest } : {}),
768
+ ...this.result(
769
+ decision.changes.map((c) => c.row),
770
+ decision.backgroundChanges.map((c) => c.row),
771
+ ),
772
+ })
773
+ }
774
+ /**
775
+ * A receipt only matters to a caller that can still present its transition ID. Admission IDs are
776
+ * answered by the permanent row itself. A bare UUID is a runtime-local handle: once the epoch that
777
+ * minted or received it has ended, no live caller holds it and no durable record re-issues one.
778
+ * Derived and caller-named IDs (`prepare:`, `owned:`, `recovery:`, stop IDs, …) stay indefinitely.
779
+ */
780
+ private retainsReceipt(transitionId: string, epoch: string | undefined) {
781
+ if (transitionId.startsWith('admit:')) return false
782
+ return !(uuid.test(transitionId) && epoch !== this.epoch)
783
+ }
784
+ /** Keeps open rows in full and closed rows as tombstones; the frozen transfer is stored once per delivery. */
785
+ private install(row: JournalRow) {
786
+ let transfer = row.transfer
787
+ if (transfer) {
788
+ const frozen = this.notices.get(transfer.deliveryId)
789
+ if (frozen && canonical(frozen) !== canonical(transfer)) throw new Error('Conflicting frozen transfer payload')
790
+ if (frozen) transfer = frozen
791
+ else this.notices.set(transfer.deliveryId, transfer)
792
+ }
793
+ this.rows.set(
794
+ row.inputId,
795
+ row.phase === 'closed' ? tombstone(row) : ((transfer ? { ...row, transfer } : row) as OpenInboundRecord),
796
+ )
797
+ }
798
+ private frozenNotice(row: InboundRecord | undefined): RecoveryRecord | undefined {
799
+ if (!row) return undefined
800
+ if (row.phase !== 'closed') return row.transfer
801
+ return row.noticeDeliveryId === undefined ? undefined : this.notices.get(row.noticeDeliveryId)
802
+ }
803
+ private indexSlackMessage(row: InboundRecord) {
804
+ const key = row.phase === 'closed' ? row.messageKey : storedSlackMessageKey(row)
805
+ if (!key) return
806
+ const current = this.rows.get(this.slackMessages.get(key) ?? '')
807
+ // Historical per-revision rows all stay; the earliest admission deterministically represents the message.
808
+ if (
809
+ current &&
810
+ current.inputId !== row.inputId &&
811
+ (current.acceptedAt < row.acceptedAt || (current.acceptedAt === row.acceptedAt && current.inputId < row.inputId))
812
+ )
813
+ return
814
+ this.slackMessages.set(key, row.inputId)
815
+ }
816
+ private validateDecision(decision: Decision) {
817
+ decisionSchema.parse(decision)
818
+ if (!decision.changes.length && !decision.backgroundChanges.length) throw new Error('Empty journal decision')
819
+ if (decision.type === 'admitted' && (decision.changes.length !== 1 || decision.backgroundChanges.length))
820
+ throw new Error('Admission must cover exactly one input')
821
+ const seen = new Set<string>()
822
+ for (const c of decision.changes) {
823
+ validateRow(c.row)
824
+ if (!c.expected || c.expected.inputId !== c.row.inputId || seen.has(c.row.inputId))
825
+ throw new Error('Invalid or duplicate inbound coverage')
826
+ seen.add(c.row.inputId)
827
+ }
828
+ for (const c of decision.backgroundChanges) {
829
+ parseBackgroundObligation(c.row)
830
+ if (
831
+ !id(c.expected.obligationId) ||
832
+ !integer(c.expected.generation) ||
833
+ c.row.obligationId !== c.expected.obligationId ||
834
+ c.row.generation !== c.expected.generation + 1 ||
835
+ seen.has(c.row.obligationId)
836
+ )
837
+ throw new Error('Invalid background decision coverage')
838
+ seen.add(c.row.obligationId)
839
+ }
840
+ const coverage = [...decision.changes.map((c) => c.row), ...decision.backgroundChanges.map((c) => c.row)]
841
+ const first = coverage[0]!
842
+ const phases: Record<string, string> = {
843
+ admitted: 'admitted',
844
+ 'turn-claimed': 'turn-owned',
845
+ 'ownership-moved': 'turn-owned',
846
+ 'outcome-decided': 'closed',
847
+ 'notice-prepared': 'notice-prepared',
848
+ 'notice-owned': 'notice-owned',
849
+ }
850
+ for (const row of coverage) {
851
+ if (
852
+ row.phase !== phases[decision.type] ||
853
+ row.accountIdentity !== first.accountIdentity ||
854
+ channelKeyId(row.target) !== channelKeyId(first.target)
855
+ )
856
+ throw new Error('Conflicting journal decision scope')
857
+ if (decision.type === 'outcome-decided' && canonical(row.outcome) !== canonical(first.outcome))
858
+ throw new Error('Conflicting journal outcome coverage')
859
+ if (decision.type === 'notice-prepared' && canonical(row.transfer) !== canonical(first.transfer))
860
+ throw new Error('Conflicting frozen transfer coverage')
861
+ if (decision.type === 'notice-prepared' && canonical(row.principal) !== canonical(first.principal))
862
+ throw new Error('Notice coverage must be partitioned by principal')
863
+ }
864
+ }
865
+ private validateChange(change: Change, type: string) {
866
+ const before = this.rows.get(change.expected.inputId)
867
+ const after = change.row
868
+ if (type === 'admitted') {
869
+ if (before || change.expected.generation !== 0 || after.generation !== 1 || after.phase !== 'admitted')
870
+ throw new Error('Invalid journal admission')
871
+ return
872
+ }
873
+ if (
874
+ !before ||
875
+ before.generation !== change.expected.generation ||
876
+ before.phase === 'closed' ||
877
+ after.generation !== before.generation + (type === 'notice-owned' ? 0 : 1) ||
878
+ before.identity !== after.identity ||
879
+ before.epoch !== after.epoch ||
880
+ before.accountIdentity !== after.accountIdentity ||
881
+ canonical(before.target) !== canonical(after.target) ||
882
+ canonical(before.principal) !== canonical(after.principal)
883
+ )
884
+ throw new Error('Stale or conflicting journal generation')
885
+ if (
886
+ canonical([before.acceptedAt, before.reference, before.sourceParentSessionId]) !==
887
+ canonical([after.acceptedAt, after.reference, after.sourceParentSessionId])
888
+ )
889
+ throw new Error('Inbound transition changes immutable reference metadata')
890
+ if (
891
+ type === 'turn-claimed' &&
892
+ (!['admitted', 'turn-owned'].includes(before.phase) ||
893
+ after.phase !== 'turn-owned' ||
894
+ (before.claim && (before.claim.turnId !== after.claim?.turnId || before.claim.epoch !== after.claim?.epoch)))
895
+ )
896
+ throw new Error('Invalid journal claim')
897
+ if (type === 'ownership-moved' && (before.phase !== 'turn-owned' || after.phase !== 'turn-owned'))
898
+ throw new Error('Invalid journal move')
899
+ if (type === 'outcome-decided' && after.phase !== 'closed') throw new Error('Invalid journal outcome')
900
+ if (type === 'notice-prepared' && (before.transfer || after.phase !== 'notice-prepared'))
901
+ throw new Error('Invalid notice preparation')
902
+ if (
903
+ type === 'notice-owned' &&
904
+ (before.phase !== 'notice-prepared' ||
905
+ after.phase !== 'notice-owned' ||
906
+ canonical(before.transfer) !== canonical(after.transfer))
907
+ )
908
+ throw new Error('Invalid notice ownership')
909
+ }
910
+ private async append(line: Line, repair = false) {
911
+ if (!repair) this.assertAvailable()
912
+ // Appends run on the writer queue, never inside a compaction swap: only a real open handle is written.
913
+ const fd = this.fd
914
+ if (!fd) throw new Error('Journal append has no open handle')
915
+ try {
916
+ const start = performance.now()
917
+ const text = `${JSON.stringify(line)}\n`
918
+ await fd.writeFile(text)
919
+ await this.options.onDurability?.('append-written', line)
920
+ await fd.sync()
921
+ this.options.onSync?.(performance.now() - start)
922
+ await this.options.onDurability?.('append-synced', line)
923
+ this.fold(line, Buffer.byteLength(text))
924
+ } catch (error) {
925
+ this.fail(error)
926
+ throw error
927
+ }
928
+ this.scheduleCompaction()
929
+ }
930
+ private async applyBackground(decision: Decision, repair = false) {
931
+ if (!decision.backgroundChanges.length || !this.decisions.has(decision.transitionId)) return
932
+ if (!this.background) throw new Error('Mixed decision requires background store')
933
+ const identity = { transitionId: decision.transitionId, decisionDigest: digest(decision) }
934
+ for (const change of decision.backgroundChanges) {
935
+ if (this.initializationCancelled) return
936
+ const apply = (current: Readonly<BackgroundObligation>) => {
937
+ const next = change.row
938
+ if (
939
+ canonical([
940
+ current.taskId,
941
+ current.parentSessionId,
942
+ current.parentSessionFile,
943
+ current.accountIdentity,
944
+ current.target,
945
+ current.principal,
946
+ current.epoch,
947
+ current.acceptedAt,
948
+ ]) !==
949
+ canonical([
950
+ next.taskId,
951
+ next.parentSessionId,
952
+ next.parentSessionFile,
953
+ next.accountIdentity,
954
+ next.target,
955
+ next.principal,
956
+ next.epoch,
957
+ next.acceptedAt,
958
+ ])
959
+ )
960
+ throw new Error('Mixed decision changes immutable background provenance')
961
+ if (
962
+ decision.type === 'turn-claimed' &&
963
+ (current.transfer ||
964
+ !['result-ready', 'turn-owned'].includes(current.phase) ||
965
+ (current.claim &&
966
+ (current.claim.turnId !== next.claim?.turnId ||
967
+ current.claim.epoch !== next.claim?.epoch ||
968
+ current.claim.ownerSessionId !== next.claim?.ownerSessionId)))
969
+ )
970
+ throw new Error('Mixed claim changes background owner')
971
+ if (decision.type === 'ownership-moved' && current.phase !== 'turn-owned')
972
+ throw new Error('Mixed move has no prior background owner')
973
+ if (decision.type === 'notice-prepared' && current.transfer) throw new Error('Mixed transfer already prepared')
974
+ return copy(next)
975
+ }
976
+ const row = repair
977
+ ? await this.background.applyJournalDecision(change.expected, identity, apply)
978
+ : await this.background.apply(change.expected, identity, apply)
979
+ const receipt = row?.applications.find((r) => r.transitionId === identity.transitionId)
980
+ if (
981
+ !receipt ||
982
+ receipt.decisionDigest !== identity.decisionDigest ||
983
+ receipt.expectedGeneration !== change.expected.generation ||
984
+ receipt.resultingGeneration !== change.row.generation
985
+ )
986
+ throw new Error('Mixed application conflict')
987
+ }
988
+ await this.options.onDurability?.('mixed-json-applied', decision)
989
+ if (this.initializationCancelled) return
990
+ await this.append(
991
+ {
992
+ schemaVersion: 1,
993
+ seq: this.sequence + 1,
994
+ transitionId: `applied:${decision.transitionId}`,
995
+ epoch: this.epoch,
996
+ type: 'mixed-applied',
997
+ decisionId: decision.transitionId,
998
+ decisionDigest: digest(decision),
999
+ },
1000
+ repair,
1001
+ )
1002
+ }
1003
+ private async repairInternal() {
1004
+ this.background?.setFrozen(new Error('Inbound journal repair pending'))
1005
+ try {
1006
+ for (const decision of [...this.decisions.values()].sort((a, b) => a.seq - b.seq)) {
1007
+ if (this.initializationCancelled) return
1008
+ const target = decision.backgroundChanges[0]!.row.target
1009
+ await this.background!.withTargetLane(target, () => this.applyBackground(decision, true))
1010
+ }
1011
+ if (this.initializationCancelled) return
1012
+ this.frozen = undefined
1013
+ this.background?.setFrozen(undefined)
1014
+ } catch (error) {
1015
+ this.fail(error)
1016
+ throw error
1017
+ }
1018
+ }
1019
+ repair() {
1020
+ return this.serialized(async () => {
1021
+ this.assertAvailable()
1022
+ await this.repairInternal()
1023
+ })
1024
+ }
1025
+ private async commit(
1026
+ type: string,
1027
+ changes: Change[],
1028
+ backgroundChanges: BackgroundChange[],
1029
+ requestedTransitionId?: string,
1030
+ requestDigest?: string,
1031
+ ) {
1032
+ this.assertAvailable()
1033
+ const transitionId = requestedTransitionId ?? randomUUID()
1034
+ const receipt = this.receipts.get(transitionId)
1035
+ if (receipt) {
1036
+ if (receipt.payloadDigest !== digest([type, changes, backgroundChanges]))
1037
+ throw new Error('Conflicting duplicate transition identity')
1038
+ return receipt
1039
+ }
1040
+ const previous = this.decisions.get(transitionId)
1041
+ if (previous) {
1042
+ if (
1043
+ canonical([previous.type, previous.changes, previous.backgroundChanges]) !==
1044
+ canonical([type, changes, backgroundChanges])
1045
+ )
1046
+ throw new Error('Conflicting duplicate transition identity')
1047
+ await this.applyBackground(previous)
1048
+ return previous
1049
+ }
1050
+ const decision: Decision = {
1051
+ schemaVersion: 1,
1052
+ seq: this.sequence + 1,
1053
+ epoch: this.epoch,
1054
+ transitionId,
1055
+ type,
1056
+ changes,
1057
+ backgroundChanges,
1058
+ requestDigest,
1059
+ }
1060
+ this.validateDecision(decision)
1061
+ for (const change of changes) this.validateChange(change, type)
1062
+ if (backgroundChanges.length) {
1063
+ // A known background freeze rejects a mixed decision before it is durable; once written, only
1064
+ // journal repair may apply it, so a write the store cannot follow would poison every admission.
1065
+ if (!this.background) throw new Error('Mixed decision requires background store')
1066
+ this.background.assertAvailable()
1067
+ }
1068
+ if (requestedTransitionId === undefined) this.minted.add(transitionId)
1069
+ try {
1070
+ await this.append(decision)
1071
+ } catch (error) {
1072
+ this.minted.delete(transitionId)
1073
+ throw error
1074
+ }
1075
+ try {
1076
+ await this.applyBackground(decision)
1077
+ } catch (error) {
1078
+ this.fail(error)
1079
+ throw error
1080
+ }
1081
+ return decision
1082
+ }
1083
+ /**
1084
+ * The one duplicate authority for admission and pre-routing lookup. A Slack message resolves to its
1085
+ * representative row whatever revision or thread shape arrives; only identities outside the message
1086
+ * index (other adapters, receipt-only, undecodable rows) use exact identity. A duplicate returns the
1087
+ * existing row untouched (its debt never follows a new routing thread), and a different author is a
1088
+ * conflict, never a fresh slot — closed or open.
1089
+ */
1090
+ private existingAdmission(input: InboundAdmission) {
1091
+ const root = dirname(dirname(this.path))
1092
+ const identity = canonical([
1093
+ root,
1094
+ input.accountIdentity,
1095
+ channelKeyId(input.target),
1096
+ input.messageId ?? input.receiptId,
1097
+ input.eventKind,
1098
+ input.revision,
1099
+ ])
1100
+ const inputId = digest(['inbound', identity])
1101
+ const message = slackMessageKey({ root, ...input })
1102
+ const representative = message ? this.slackMessages.get(message) : undefined
1103
+ const existing = this.rows.get(representative ?? inputId)
1104
+ if (
1105
+ existing &&
1106
+ (existing.phase === 'closed' ? existing.principalDigest : principalDigest(existing.principal)) !==
1107
+ principalDigest(input.principal)
1108
+ )
1109
+ throw new Error('Conflicting duplicate admission principal')
1110
+ return { identity, inputId, existing }
1111
+ }
1112
+ async admit(
1113
+ input: InboundAdmission,
1114
+ ): Promise<
1115
+ | { kind: 'accepted'; inputId: string; generation: number }
1116
+ | { kind: 'duplicate'; inputId: string; outcome?: InboundOutcome }
1117
+ > {
1118
+ await this.initialize()
1119
+ return this.serialized(async () => {
1120
+ this.assertAvailable()
1121
+ if (
1122
+ !input.accountIdentity ||
1123
+ !input.eventKind ||
1124
+ typeof input.revision !== 'string' ||
1125
+ !(input.messageId || input.receiptId)
1126
+ )
1127
+ throw new Error('Missing inbound continuity identity')
1128
+ const { identity, inputId, existing } = this.existingAdmission(input)
1129
+ if (existing)
1130
+ return {
1131
+ kind: 'duplicate' as const,
1132
+ inputId: existing.inputId,
1133
+ outcome: existing.phase === 'closed' ? copy(existing.outcome) : undefined,
1134
+ }
1135
+ const row: OpenInboundRecord = {
1136
+ schemaVersion: 1,
1137
+ inputId,
1138
+ identity,
1139
+ generation: 1,
1140
+ accountIdentity: input.accountIdentity,
1141
+ target: copy(input.target),
1142
+ principal: copy(input.principal),
1143
+ epoch: this.epoch,
1144
+ acceptedAt: (this.options.now ?? Date.now)(),
1145
+ phase: 'admitted',
1146
+ reference: { messageId: input.messageId, receiptId: input.receiptId },
1147
+ sourceParentSessionId: input.ownerSessionId,
1148
+ }
1149
+ await this.commit('admitted', [{ expected: { inputId, generation: 0 }, row }], [], `admit:${inputId}`)
1150
+ return { kind: 'accepted' as const, inputId, generation: 1 }
1151
+ })
1152
+ }
1153
+ get(inputId: string): InboundRecord | undefined {
1154
+ this.assertAvailable()
1155
+ const row = this.rows.get(inputId)
1156
+ return row ? copy(row) : undefined
1157
+ }
1158
+ list(): InboundRecord[] {
1159
+ this.assertAvailable()
1160
+ return [...this.rows.values()].map(copy)
1161
+ }
1162
+ resolve(ids: readonly string[]): InboundRef[] {
1163
+ this.assertAvailable()
1164
+ return ids.map((inputId) => {
1165
+ const row = this.rows.get(inputId)
1166
+ if (!row) throw new Error('Unknown inbound ID')
1167
+ return { inputId, generation: row.generation }
1168
+ })
1169
+ }
1170
+ private coverage(refs: InboundRef[], target: ChannelKey): OpenInboundRecord[] {
1171
+ const seen = new Set<string>()
1172
+ return refs.map((ref) => {
1173
+ const row = this.rows.get(ref.inputId)
1174
+ if (
1175
+ !row ||
1176
+ seen.has(ref.inputId) ||
1177
+ row.generation !== ref.generation ||
1178
+ row.phase === 'closed' ||
1179
+ channelKeyId(row.target) !== channelKeyId(target)
1180
+ )
1181
+ throw new Error('Invalid inbound coverage')
1182
+ seen.add(ref.inputId)
1183
+ return row
1184
+ })
1185
+ }
1186
+ private async backgroundCoverage(refs: BackgroundObligationRef[], target: ChannelKey, inbound: OpenInboundRecord[]) {
1187
+ if (refs.length && !this.background) throw new Error('Missing background store')
1188
+ const seen = new Set<string>()
1189
+ const rows: BackgroundObligation[] = []
1190
+ for (const ref of refs) {
1191
+ const row = await this.background!.get(ref.obligationId)
1192
+ if (
1193
+ !row ||
1194
+ seen.has(ref.obligationId) ||
1195
+ row.generation !== ref.generation ||
1196
+ row.phase === 'closed' ||
1197
+ channelKeyId(row.target) !== channelKeyId(target) ||
1198
+ (inbound.length && row.accountIdentity !== inbound[0]!.accountIdentity)
1199
+ )
1200
+ throw new Error('Invalid mixed background coverage')
1201
+ seen.add(ref.obligationId)
1202
+ rows.push(row)
1203
+ }
1204
+ return rows
1205
+ }
1206
+ private result(
1207
+ rows: ReadonlyArray<{ inputId: string; generation: number }>,
1208
+ background: ReadonlyArray<{ obligationId: string; generation: number }>,
1209
+ ) {
1210
+ return {
1211
+ inboundRefs: rows.map((r) => ({ inputId: r.inputId, generation: r.generation })),
1212
+ backgroundRefs: background.map((r) => ({ obligationId: r.obligationId, generation: r.generation })),
1213
+ }
1214
+ }
1215
+ claim(refs: InboundRef[], owner: Owner, backgroundRefs: BackgroundObligationRef[] = [], decisionId?: string) {
1216
+ return this.changeOwner('turn-claimed', refs, owner, backgroundRefs, decisionId)
1217
+ }
1218
+ move(
1219
+ refs: InboundRef[],
1220
+ owner: Owner & { fromTurnId: string },
1221
+ backgroundRefs: BackgroundObligationRef[] = [],
1222
+ decisionId?: string,
1223
+ ) {
1224
+ return this.changeOwner('ownership-moved', refs, owner, backgroundRefs, decisionId)
1225
+ }
1226
+ private async repeated(transitionId: string | undefined, requestDigest: string) {
1227
+ this.assertAvailable()
1228
+ const receipt = transitionId ? this.receipts.get(transitionId) : undefined
1229
+ const previous = transitionId ? this.decisions.get(transitionId) : undefined
1230
+ const identity = receipt ?? previous
1231
+ if (!identity) return undefined
1232
+ if (identity.requestDigest !== requestDigest) throw new Error('Conflicting duplicate transition identity')
1233
+ if (previous) await this.applyBackground(previous)
1234
+ const result = receipt
1235
+ ? copy({ inboundRefs: receipt.inboundRefs, backgroundRefs: receipt.backgroundRefs })
1236
+ : this.result(
1237
+ previous!.changes.map((c) => c.row),
1238
+ previous!.backgroundChanges.map((c) => c.row),
1239
+ )
1240
+ if (identity.type === 'turn-claimed' || identity.type === 'ownership-moved') {
1241
+ for (const ref of result.inboundRefs) {
1242
+ const row = this.rows.get(ref.inputId)
1243
+ if (!row || row.generation !== ref.generation || row.phase !== 'turn-owned' || row.claim?.epoch !== this.epoch)
1244
+ throw new Error('Journal ownership decision superseded')
1245
+ }
1246
+ for (const ref of result.backgroundRefs) {
1247
+ const row = await this.background?.get(ref.obligationId)
1248
+ if (!row || row.generation !== ref.generation || row.phase !== 'turn-owned' || row.claim?.epoch !== this.epoch)
1249
+ throw new Error('Background ownership decision superseded')
1250
+ }
1251
+ }
1252
+ return result
1253
+ }
1254
+ private changeOwner(
1255
+ type: string,
1256
+ refs: InboundRef[],
1257
+ owner: Owner,
1258
+ brefs: BackgroundObligationRef[],
1259
+ decisionId?: string,
1260
+ ) {
1261
+ return this.serialized(async () => {
1262
+ const requestDigest = digest([type, refs, owner, brefs])
1263
+ const repeated = await this.repeated(decisionId, requestDigest)
1264
+ if (repeated) return repeated
1265
+ const rows = this.coverage(refs, owner.target)
1266
+ const bg = await this.backgroundCoverage(brefs, owner.target, rows)
1267
+ for (const row of [...rows, ...bg]) {
1268
+ if (
1269
+ row.transfer ||
1270
+ (type === 'ownership-moved'
1271
+ ? row.claim?.turnId !== owner.fromTurnId
1272
+ : row.claim &&
1273
+ (row.claim.turnId !== owner.turnId ||
1274
+ row.claim.epoch !== this.epoch ||
1275
+ row.claim.ownerSessionId !== owner.ownerSessionId)) ||
1276
+ ('obligationId' in row && type === 'turn-claimed' && !['result-ready', 'turn-owned'].includes(row.phase))
1277
+ )
1278
+ throw new Error('Invalid claim owner')
1279
+ }
1280
+ const next = rows.map((row) => ({
1281
+ ...row,
1282
+ generation: row.generation + 1,
1283
+ phase: 'turn-owned' as const,
1284
+ claim: {
1285
+ turnId: owner.turnId,
1286
+ ownerSessionId: owner.ownerSessionId,
1287
+ epoch: this.epoch,
1288
+ generation: row.generation + 1,
1289
+ },
1290
+ }))
1291
+ const nextBg = bg.map((row) => ({
1292
+ ...row,
1293
+ generation: row.generation + 1,
1294
+ phase: 'turn-owned' as const,
1295
+ claim: {
1296
+ turnId: owner.turnId,
1297
+ ownerSessionId: owner.ownerSessionId,
1298
+ epoch: this.epoch,
1299
+ generation: row.generation + 1,
1300
+ },
1301
+ }))
1302
+ await this.commit(
1303
+ type,
1304
+ next.map((row, i) => ({ expected: refs[i]!, row })),
1305
+ nextBg.map((row, i) => ({ expected: brefs[i]!, row })),
1306
+ decisionId,
1307
+ requestDigest,
1308
+ )
1309
+ return this.result(next, nextBg)
1310
+ })
1311
+ }
1312
+ settle(refs: InboundRef[], outcome: InboundOutcome, brefs: BackgroundObligationRef[] = [], target?: ChannelKey) {
1313
+ return this.serialized(async () => {
1314
+ const requestDigest = digest(['outcome-decided', refs, outcome, brefs, target])
1315
+ const repeated = await this.repeated(outcome.decisionId, requestDigest)
1316
+ if (repeated) return repeated
1317
+ const first = this.rows.get(refs[0]?.inputId ?? '')
1318
+ if (first?.phase === 'closed') throw new Error('Invalid inbound coverage')
1319
+ const destination =
1320
+ target ?? first?.target ?? (brefs[0] ? (await this.background?.get(brefs[0].obligationId))?.target : undefined)
1321
+ if (!destination) {
1322
+ if (!refs.length && !brefs.length) return this.result([], [])
1323
+ throw new Error('Missing outcome target')
1324
+ }
1325
+ const rows = this.coverage(refs, destination)
1326
+ const bg = await this.backgroundCoverage(brefs, destination, rows)
1327
+ const next = rows.map((row) => ({
1328
+ ...row,
1329
+ generation: row.generation + 1,
1330
+ phase: 'closed' as const,
1331
+ outcome,
1332
+ claim: undefined,
1333
+ }))
1334
+ const nextBg = bg.map((row) => ({
1335
+ ...row,
1336
+ generation: row.generation + 1,
1337
+ phase: 'closed' as const,
1338
+ outcome,
1339
+ claim: undefined,
1340
+ }))
1341
+ await this.commit(
1342
+ 'outcome-decided',
1343
+ next.map((row, i) => ({ expected: refs[i]!, row })),
1344
+ nextBg.map((row, i) => ({ expected: brefs[i]!, row })),
1345
+ outcome.decisionId,
1346
+ requestDigest,
1347
+ )
1348
+ return this.result(next, nextBg)
1349
+ })
1350
+ }
1351
+ /**
1352
+ * Freezes a notice over owed coverage. `cause` picks the template: `restart` (the default) is the
1353
+ * RFC boot-recovery notice with its original request digest; `live-turn-ended` is a same-process
1354
+ * turn that ended unanswered and is frozen as its own distinct record.
1355
+ */
1356
+ prepareNotice(
1357
+ refs: InboundRef[],
1358
+ target: ChannelKey,
1359
+ brefs: BackgroundObligationRef[] = [],
1360
+ ownerSessionId?: string,
1361
+ cause: RecoveryNoticeCause = 'restart',
1362
+ ) {
1363
+ return this.serialized(async () => {
1364
+ this.assertAvailable()
1365
+ // Restart keeps the pre-cause request digest so earlier preparation receipts still match.
1366
+ const requestDigest = digest(
1367
+ cause === 'restart'
1368
+ ? ['notice-prepared', refs, target, brefs, ownerSessionId]
1369
+ : ['notice-prepared', refs, target, brefs, ownerSessionId, cause],
1370
+ )
1371
+ const transitionId = `prepare:${digest(['inbound-transfer', refs, brefs])}`
1372
+ const prior = this.decisions.get(transitionId)
1373
+ const receipt = this.receipts.get(transitionId)
1374
+ if (prior || receipt) {
1375
+ if ((prior ?? receipt)!.requestDigest !== requestDigest)
1376
+ throw new Error('Conflicting duplicate notice preparation')
1377
+ const transfer =
1378
+ prior?.changes[0]?.row.transfer ?? this.frozenNotice(this.rows.get(receipt!.inboundRefs[0]!.inputId))
1379
+ if (!transfer || channelKeyId(transfer.target) !== channelKeyId(target))
1380
+ throw new Error('Conflicting duplicate notice preparation')
1381
+ return copy(transfer)
1382
+ }
1383
+ const rows = this.coverage(refs, target)
1384
+ const bg = await this.backgroundCoverage(brefs, target, rows)
1385
+ if (!rows.length) throw new Error('Inbound notice requires inbound coverage')
1386
+ if ([...rows, ...bg].some((row) => canonical(row.principal) !== canonical(rows[0]!.principal)))
1387
+ throw new Error('Notice coverage must be partitioned by principal')
1388
+ if ([...rows, ...bg].some((row) => row.transfer)) throw new Error('Already transferred coverage')
1389
+ const transferId = digest(['inbound-transfer', refs, brefs])
1390
+ const parents = rows.map((row) => row.claim?.ownerSessionId ?? ownerSessionId ?? row.sourceParentSessionId)
1391
+ // A covered child must share the notice's stop authority, not only its destination.
1392
+ const backgroundParents = bg.map((row) => row.claim?.ownerSessionId ?? ownerSessionId ?? row.parentSessionId)
1393
+ if (new Set([...parents, ...backgroundParents]).size !== 1)
1394
+ throw new Error('Notice coverage must be partitioned by owner')
1395
+ const transfer = createRecoveryNotice({
1396
+ target,
1397
+ accountIdentity: rows[0]!.accountIdentity,
1398
+ principal: rows[0]!.principal,
1399
+ transferId,
1400
+ recoveryGeneration: transferId,
1401
+ sourceParentSessionId: parents[0],
1402
+ cause,
1403
+ covers: [
1404
+ ...refs.map((r, i) => ({
1405
+ store: 'inbound' as const,
1406
+ id: r.inputId,
1407
+ generation: r.generation + 1,
1408
+ ...(parents[i] ? { parentSessionId: parents[i] } : {}),
1409
+ })),
1410
+ ...brefs.map((r, i) => ({
1411
+ store: 'background' as const,
1412
+ id: r.obligationId,
1413
+ generation: r.generation + 1,
1414
+ parentSessionId: bg[i]!.parentSessionId,
1415
+ })),
1416
+ ],
1417
+ })
1418
+ const next = rows.map((row) => ({
1419
+ ...row,
1420
+ generation: row.generation + 1,
1421
+ phase: 'notice-prepared' as const,
1422
+ transfer,
1423
+ claim: undefined,
1424
+ }))
1425
+ const nextBg = bg.map((row) => ({
1426
+ ...row,
1427
+ generation: row.generation + 1,
1428
+ phase: 'notice-prepared' as const,
1429
+ transfer,
1430
+ claim: undefined,
1431
+ }))
1432
+ await this.commit(
1433
+ 'notice-prepared',
1434
+ next.map((row, i) => ({ expected: refs[i]!, row })),
1435
+ nextBg.map((row, i) => ({ expected: brefs[i]!, row })),
1436
+ `prepare:${transferId}`,
1437
+ requestDigest,
1438
+ )
1439
+ return transfer
1440
+ })
1441
+ }
1442
+ async importPrepared(outbox: RecoveryOutbox, transfer: RecoveryRecord) {
1443
+ this.assertAvailable()
1444
+ parseRecoveryRecord(transfer)
1445
+ for (const cover of transfer.covers.filter((c) => c.store === 'inbound')) {
1446
+ const frozen = this.frozenNotice(this.rows.get(cover.id))
1447
+ if (!frozen || recoveryPayload(frozen) !== recoveryPayload(transfer))
1448
+ throw new Error('Prepared frozen payload mismatch')
1449
+ }
1450
+ const imported = await outbox.import(transfer)
1451
+ await this.serialized(async () => {
1452
+ this.assertAvailable()
1453
+ const rows = transfer.covers.filter((c) => c.store === 'inbound').map((c) => this.rows.get(c.id))
1454
+ if (rows.some((row) => this.frozenNotice(row)?.deliveryId !== transfer.deliveryId))
1455
+ throw new Error('Prepared transfer mismatch')
1456
+ for (const c of transfer.covers.filter((c) => c.store === 'background')) {
1457
+ const row = await this.background?.ownNotice(c.id, c.generation, transfer.deliveryId)
1458
+ if (!row && imported.state !== 'delivered' && imported.state !== 'suppressed')
1459
+ throw new Error('Background notice ownership conflict')
1460
+ }
1461
+ const pending = rows.filter((row): row is OpenInboundRecord => !!row && row.phase === 'notice-prepared')
1462
+ if (pending.length)
1463
+ await this.commit(
1464
+ 'notice-owned',
1465
+ pending.map((row) => ({
1466
+ expected: { inputId: row.inputId, generation: row.generation },
1467
+ row: { ...row, phase: 'notice-owned' },
1468
+ })),
1469
+ [],
1470
+ `owned:${transfer.transferId}`,
1471
+ )
1472
+ })
1473
+ await this.acknowledgeNotice(imported)
1474
+ return imported
1475
+ }
1476
+ /** Pre-routing duplicate check; the same resolver and author fence as admission. */
1477
+ lookupAdmission(input: InboundAdmission): InboundRecord | undefined {
1478
+ this.assertAvailable()
1479
+ const { existing } = this.existingAdmission(input)
1480
+ return existing ? copy(existing) : undefined
1481
+ }
1482
+ /**
1483
+ * Boot transfer of inbound authority no live turn can still answer. Issued transfers re-import
1484
+ * unchanged first, so a late matching row forms its own notice instead of mutating one. Remaining
1485
+ * old-epoch rows become one mixed notice per recovery partition, joined by compatible old-epoch
1486
+ * children; unmatched children keep the background store's singleton fallback.
1487
+ */
1488
+ async importOldEpoch(outbox: RecoveryOutbox) {
1489
+ await this.initialize()
1490
+ this.assertAvailable()
1491
+ const background = this.background
1492
+ const issued = new Map<string, { target: ChannelKey; inputIds: string[] }>()
1493
+ for (const row of this.rows.values()) {
1494
+ if (row.phase === 'closed' || !row.transfer) continue
1495
+ const transfer = issued.get(row.transfer.deliveryId)
1496
+ if (transfer) transfer.inputIds.push(row.inputId)
1497
+ else issued.set(row.transfer.deliveryId, { target: row.target, inputIds: [row.inputId] })
1498
+ }
1499
+ for (const { target, inputIds } of issued.values()) {
1500
+ const reimport = async () => {
1501
+ this.assertAvailable()
1502
+ for (const inputId of inputIds) {
1503
+ const row = this.rows.get(inputId)
1504
+ if (row?.phase === 'closed' || !row?.transfer) continue
1505
+ await this.importPrepared(outbox, row.transfer)
1506
+ return
1507
+ }
1508
+ }
1509
+ await (background ? background.withTargetLane(target, reimport) : reimport())
1510
+ }
1511
+ const owedInbound = (row: InboundRecord | undefined): row is OpenInboundRecord =>
1512
+ !!row && row.phase !== 'closed' && !row.transfer && row.epoch !== this.epoch
1513
+ const owedBackground = (row: BackgroundObligation | undefined): row is BackgroundObligation =>
1514
+ !!row && row.phase !== 'closed' && !row.transfer && row.epoch !== this.epoch
1515
+ const partitions = new Map<string, { target: ChannelKey; inputIds: string[]; backgroundIds: string[] }>()
1516
+ for (const row of this.rows.values()) {
1517
+ if (!owedInbound(row)) continue
1518
+ const key = inboundPartition(row)
1519
+ const partition = partitions.get(key) ?? { target: row.target, inputIds: [], backgroundIds: [] }
1520
+ partitions.set(key, partition)
1521
+ partition.inputIds.push(row.inputId)
1522
+ }
1523
+ if (background && partitions.size) {
1524
+ for (const row of await background.list())
1525
+ if (owedBackground(row)) partitions.get(backgroundPartition(row))?.backgroundIds.push(row.obligationId)
1526
+ }
1527
+ for (const [key, partition] of partitions) {
1528
+ const transfer = async () => {
1529
+ this.assertAvailable()
1530
+ // The boot snapshot is not authority: cover only rows still open in this exact partition.
1531
+ const rows = partition.inputIds
1532
+ .map((id) => this.rows.get(id))
1533
+ .filter((row): row is OpenInboundRecord => owedInbound(row) && inboundPartition(row) === key)
1534
+ if (!rows.length) return
1535
+ const children: BackgroundObligation[] = []
1536
+ for (const id of partition.backgroundIds) {
1537
+ const row = await background!.get(id)
1538
+ if (owedBackground(row) && backgroundPartition(row) === key) children.push(row)
1539
+ }
1540
+ const prepared = await this.prepareNotice(
1541
+ rows
1542
+ .sort((a, b) => a.acceptedAt - b.acceptedAt || a.inputId.localeCompare(b.inputId))
1543
+ .map((row) => ({ inputId: row.inputId, generation: row.generation })),
1544
+ partition.target,
1545
+ children
1546
+ .sort((a, b) => a.acceptedAt - b.acceptedAt || a.obligationId.localeCompare(b.obligationId))
1547
+ .map((row) => ({ obligationId: row.obligationId, generation: row.generation })),
1548
+ )
1549
+ await this.importPrepared(outbox, prepared)
1550
+ }
1551
+ await (background ? background.withTargetLane(partition.target, transfer) : transfer())
1552
+ }
1553
+ }
1554
+ async validateNotice(record: RecoveryRecord): Promise<'open' | 'resolved'> {
1555
+ this.assertAvailable()
1556
+ let open = false
1557
+ parseRecoveryRecord(record)
1558
+ for (const cover of record.covers.filter((c) => c.store === 'inbound')) {
1559
+ const row = this.rows.get(cover.id)
1560
+ const frozen = this.frozenNotice(row)
1561
+ if (!row || !frozen || recoveryPayload(frozen) !== recoveryPayload(record))
1562
+ throw new Error('Invalid inbound notice authority')
1563
+ if (row.phase === 'closed') continue
1564
+ if (row.phase !== 'notice-owned' || row.generation !== cover.generation)
1565
+ throw new Error('Inbound notice not owned')
1566
+ open = true
1567
+ }
1568
+ if (record.covers.some((c) => c.store === 'background')) {
1569
+ if (!this.background) throw new Error('Missing background authority')
1570
+ if ((await this.background.validateNotice(record)) === 'open') open = true
1571
+ }
1572
+ return open ? 'open' : 'resolved'
1573
+ }
1574
+ /** Admission event kinds of a notice covering only open inbound rows; undefined for any other coverage. */
1575
+ noticeEventKinds(record: RecoveryRecord): string[] | undefined {
1576
+ const kinds: string[] = []
1577
+ for (const cover of record.covers) {
1578
+ const row = cover.store === 'inbound' ? this.rows.get(cover.id) : undefined
1579
+ if (!row || row.phase === 'closed') return undefined
1580
+ const kind = storedEventKind(row.identity)
1581
+ if (kind === undefined) return undefined
1582
+ kinds.push(kind)
1583
+ }
1584
+ return kinds.length ? kinds : undefined
1585
+ }
1586
+ async acknowledgeNotice(record: RecoveryRecord) {
1587
+ if (!['delivered', 'suppressed'].includes(record.state)) return
1588
+ await this.closeNotice(record, {
1589
+ kind: record.state === 'delivered' ? 'delivered' : 'intentionally-suppressed',
1590
+ decisionId: record.suppression?.decisionId ?? `recovery:${record.deliveryId}`,
1591
+ deliveryId: record.deliveryId,
1592
+ reason: record.suppression?.reason,
1593
+ })
1594
+ }
1595
+ suppressNoticeCoverage(record: RecoveryRecord, decision: { decisionId: string; reason: string }) {
1596
+ return this.closeNotice(record, { kind: 'intentionally-suppressed', ...decision, deliveryId: record.deliveryId })
1597
+ }
1598
+ private async closeNotice(record: RecoveryRecord, outcome: InboundOutcome) {
1599
+ this.assertAvailable()
1600
+ parseRecoveryRecord(record)
1601
+ const refs: InboundRef[] = []
1602
+ const bg: BackgroundObligationRef[] = []
1603
+ for (const c of record.covers) {
1604
+ if (c.store === 'inbound') {
1605
+ const row = this.rows.get(c.id)
1606
+ const frozen = this.frozenNotice(row)
1607
+ if (!row || !frozen || recoveryPayload(frozen) !== recoveryPayload(record))
1608
+ throw new Error('Inbound receipt mismatch')
1609
+ if (row.phase !== 'closed') refs.push({ inputId: c.id, generation: c.generation })
1610
+ }
1611
+ if (c.store === 'background') {
1612
+ const row = await this.background?.get(c.id)
1613
+ if (!row?.transfer || recoveryPayload(row.transfer) !== recoveryPayload(record))
1614
+ throw new Error('Background receipt mismatch')
1615
+ if (row.phase !== 'closed') bg.push({ obligationId: c.id, generation: c.generation })
1616
+ }
1617
+ }
1618
+ if (refs.length || bg.length) await this.settle(refs, outcome, bg, record.target)
1619
+ }
1620
+ /**
1621
+ * Starts growth-driven compaction once boot recovery has finished. A compaction is queued on the
1622
+ * writer's own queue when the bytes appended since the last snapshot reach the larger of a fixed
1623
+ * floor and that snapshot's size, so rewrite work stays proportional to new growth (tombstones kept
1624
+ * forever never cause repeated rewrites) and a journal that is not growing is never rewritten.
1625
+ * Checked here and after each append; `close()` stops it.
1626
+ */
1627
+ startMaintenance() {
1628
+ if (this.closing || this.initializationCancelled) return
1629
+ this.maintaining = true
1630
+ this.scheduleCompaction()
1631
+ }
1632
+ private scheduleCompaction() {
1633
+ if (
1634
+ !this.maintaining ||
1635
+ this.compactionQueued ||
1636
+ this.growthBytes < Math.max(this.options.compactionFloorBytes ?? COMPACTION_FLOOR_BYTES, this.snapshotBytes)
1637
+ )
1638
+ return
1639
+ this.compactionQueued = true
1640
+ void this.serialized(async () => {
1641
+ this.compactionQueued = false
1642
+ // Shutdown or a freeze after scheduling leaves the growth for the next boot to compact.
1643
+ if (!this.maintaining || this.frozen !== undefined || !this.fd) return
1644
+ await this.compactInternal()
1645
+ }).catch(() => {
1646
+ // compactInternal froze the journal and reported the failure through fail().
1647
+ })
1648
+ }
1649
+ compact() {
1650
+ return this.serialized(() => this.compactInternal())
1651
+ }
1652
+ /**
1653
+ * Rewrites the journal as one compact snapshot of the already-normalized state: temp sync, close the
1654
+ * old handle, replace, directory sync, reopen. Any failure freezes the writer; it never appends
1655
+ * through a handle to an unlinked file.
1656
+ */
1657
+ private async compactInternal() {
1658
+ this.assertAvailable()
1659
+ // The writer stall starts here, before the snapshot is materialized and written.
1660
+ await this.options.onDurability?.('compaction-started')
1661
+ const snapshot = this.snapshot()
1662
+ const text = `${JSON.stringify(snapshot)}\n`
1663
+ const temp = `${this.path}.${randomUUID()}.tmp`
1664
+ let ownsTemp = false
1665
+ try {
1666
+ const fd = await open(temp, 'wx', 0o600)
1667
+ ownsTemp = true
1668
+ try {
1669
+ await fd.writeFile(text)
1670
+ await fd.sync()
1671
+ } finally {
1672
+ await fd.close()
1673
+ }
1674
+ await this.options.onDurability?.('temp-synced', snapshot)
1675
+ const previous = this.fd!
1676
+ this.swapping = true
1677
+ this.fd = undefined
1678
+ await previous.close()
1679
+ await this.options.onDurability?.('handle-closed', snapshot)
1680
+ await rename(temp, this.path)
1681
+ ownsTemp = false
1682
+ await this.options.onDurability?.('replaced', snapshot)
1683
+ await syncDirectory(dirname(this.path))
1684
+ await this.options.onDurability?.('directory-synced', snapshot)
1685
+ this.fd = await open(this.path, 'a+', 0o600)
1686
+ this.swapping = false
1687
+ this.sequence = snapshot.seq
1688
+ this.snapshotBytes = Buffer.byteLength(text)
1689
+ this.growthBytes = 0
1690
+ await this.options.onDurability?.('reopened', snapshot)
1691
+ } catch (error) {
1692
+ // A failed swap freezes before the swap flag clears, so no instant reports a healthy journal.
1693
+ this.fail(error)
1694
+ this.swapping = false
1695
+ // Only this compaction's own never-installed temp file is removed.
1696
+ if (ownsTemp) await unlink(temp).catch(() => {})
1697
+ throw error
1698
+ }
1699
+ }
1700
+ private snapshot(): Snapshot {
1701
+ const open: SnapshotOpenRow[] = []
1702
+ const closed: ClosedInboundRecord[] = []
1703
+ for (const row of this.rows.values()) {
1704
+ if (row.phase === 'closed') {
1705
+ closed.push(row)
1706
+ continue
1707
+ }
1708
+ const { transfer, ...fields } = row
1709
+ open.push(transfer ? { ...fields, notice: transfer.deliveryId } : fields)
1710
+ }
1711
+ return {
1712
+ schemaVersion: 2,
1713
+ seq: Math.max(1, this.sequence),
1714
+ type: 'snapshot',
1715
+ notices: [...this.notices.values()],
1716
+ open,
1717
+ closed,
1718
+ decisions: [...this.decisions.values()],
1719
+ receipts: [...this.receipts.values()],
1720
+ }
1721
+ }
1722
+ async flush() {
1723
+ await this.queue
1724
+ }
1725
+ close() {
1726
+ this.cancelInitialization()
1727
+ // A queued compaction that has not started is skipped; one in progress finishes before the handle closes.
1728
+ this.maintaining = false
1729
+ return (this.closing ??= this.serialized(async () => {
1730
+ try {
1731
+ await this.fd?.close()
1732
+ } finally {
1733
+ this.fd = undefined
1734
+ if (activeWriters.get(this.path) === this) activeWriters.delete(this.path)
1735
+ }
1736
+ }))
1737
+ }
1738
+ }