@tpsdev-ai/agent 0.7.0 → 0.9.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 (134) hide show
  1. package/bun.lock +27 -15
  2. package/bunfig.toml +17 -0
  3. package/dist/bin.js +4 -3
  4. package/dist/bin.js.map +1 -1
  5. package/dist/config.d.ts +8 -1
  6. package/dist/config.d.ts.map +1 -1
  7. package/dist/config.js +38 -3
  8. package/dist/config.js.map +1 -1
  9. package/dist/home.d.ts +3 -0
  10. package/dist/home.d.ts.map +1 -0
  11. package/dist/home.js +18 -0
  12. package/dist/home.js.map +1 -0
  13. package/dist/index.d.ts +16 -3
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +12 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/io/flair.d.ts +1 -10
  18. package/dist/io/flair.d.ts.map +1 -1
  19. package/dist/io/flair.js +29 -28
  20. package/dist/io/flair.js.map +1 -1
  21. package/dist/io/mail.d.ts +184 -30
  22. package/dist/io/mail.d.ts.map +1 -1
  23. package/dist/io/mail.js +944 -185
  24. package/dist/io/mail.js.map +1 -1
  25. package/dist/lib/agent-keys.d.ts +106 -0
  26. package/dist/lib/agent-keys.d.ts.map +1 -0
  27. package/dist/lib/agent-keys.js +298 -0
  28. package/dist/lib/agent-keys.js.map +1 -0
  29. package/dist/lib/bridge-identity.d.ts +10 -0
  30. package/dist/lib/bridge-identity.d.ts.map +1 -0
  31. package/dist/lib/bridge-identity.js +56 -0
  32. package/dist/lib/bridge-identity.js.map +1 -0
  33. package/dist/lib/mail-lock-namespace.d.ts +19 -0
  34. package/dist/lib/mail-lock-namespace.d.ts.map +1 -0
  35. package/dist/lib/mail-lock-namespace.js +58 -0
  36. package/dist/lib/mail-lock-namespace.js.map +1 -0
  37. package/dist/lib/mail-lock.d.ts +81 -0
  38. package/dist/lib/mail-lock.d.ts.map +1 -0
  39. package/dist/lib/mail-lock.js +319 -0
  40. package/dist/lib/mail-lock.js.map +1 -0
  41. package/dist/lib/mailbox-filename.d.ts +2 -0
  42. package/dist/lib/mailbox-filename.d.ts.map +1 -0
  43. package/dist/lib/mailbox-filename.js +4 -0
  44. package/dist/lib/mailbox-filename.js.map +1 -0
  45. package/dist/lib/mailbox-policy.d.ts +245 -0
  46. package/dist/lib/mailbox-policy.d.ts.map +1 -0
  47. package/dist/lib/mailbox-policy.js +949 -0
  48. package/dist/lib/mailbox-policy.js.map +1 -0
  49. package/dist/lib/public-key.d.ts +6 -0
  50. package/dist/lib/public-key.d.ts.map +1 -0
  51. package/dist/lib/public-key.js +45 -0
  52. package/dist/lib/public-key.js.map +1 -0
  53. package/dist/lib/registry-key.d.ts +2 -0
  54. package/dist/lib/registry-key.d.ts.map +1 -0
  55. package/dist/lib/registry-key.js +10 -0
  56. package/dist/lib/registry-key.js.map +1 -0
  57. package/dist/lib/relay-lock.d.ts +7 -0
  58. package/dist/lib/relay-lock.d.ts.map +1 -0
  59. package/dist/lib/relay-lock.js +19 -0
  60. package/dist/lib/relay-lock.js.map +1 -0
  61. package/dist/lib/signEnvelope.d.ts +12 -0
  62. package/dist/lib/signEnvelope.d.ts.map +1 -1
  63. package/dist/lib/signEnvelope.js.map +1 -1
  64. package/dist/lib/signing-key.d.ts +2 -0
  65. package/dist/lib/signing-key.d.ts.map +1 -0
  66. package/dist/lib/signing-key.js +9 -0
  67. package/dist/lib/signing-key.js.map +1 -0
  68. package/dist/lib/topic-recipient.d.ts +2 -0
  69. package/dist/lib/topic-recipient.d.ts.map +1 -0
  70. package/dist/lib/topic-recipient.js +2 -0
  71. package/dist/lib/topic-recipient.js.map +1 -0
  72. package/dist/llm/provider.d.ts.map +1 -1
  73. package/dist/llm/provider.js +9 -7
  74. package/dist/llm/provider.js.map +1 -1
  75. package/dist/runtime/agent.d.ts.map +1 -1
  76. package/dist/runtime/agent.js +32 -25
  77. package/dist/runtime/agent.js.map +1 -1
  78. package/dist/runtime/event-loop.d.ts +21 -2
  79. package/dist/runtime/event-loop.d.ts.map +1 -1
  80. package/dist/runtime/event-loop.js +199 -54
  81. package/dist/runtime/event-loop.js.map +1 -1
  82. package/dist/runtime/types.d.ts +11 -0
  83. package/dist/runtime/types.d.ts.map +1 -1
  84. package/dist/runtime/types.js +13 -1
  85. package/dist/runtime/types.js.map +1 -1
  86. package/package.json +3 -4
  87. package/src/bin.ts +4 -3
  88. package/src/config.ts +46 -3
  89. package/src/home.ts +18 -0
  90. package/src/index.ts +33 -2
  91. package/src/io/flair.ts +23 -28
  92. package/src/io/mail.ts +1007 -200
  93. package/src/lib/agent-keys.ts +308 -0
  94. package/src/lib/bridge-identity.ts +49 -0
  95. package/src/lib/mail-lock-namespace.ts +64 -0
  96. package/src/lib/mail-lock.ts +337 -0
  97. package/src/lib/mailbox-filename.ts +3 -0
  98. package/src/lib/mailbox-policy.ts +1085 -0
  99. package/src/lib/public-key.ts +49 -0
  100. package/src/lib/registry-key.ts +8 -0
  101. package/src/lib/relay-lock.ts +20 -0
  102. package/src/lib/signEnvelope.ts +12 -0
  103. package/src/lib/signing-key.ts +8 -0
  104. package/src/lib/topic-recipient.ts +1 -0
  105. package/src/llm/provider.ts +9 -7
  106. package/src/runtime/agent.ts +30 -27
  107. package/src/runtime/event-loop.ts +221 -68
  108. package/src/runtime/types.ts +14 -0
  109. package/test/config.test.ts +85 -2
  110. package/test/core-loop.test.ts +6 -4
  111. package/test/governance.test.ts +4 -1
  112. package/test/helpers/event-loop-child.mjs +50 -0
  113. package/test/helpers/mail-delivery-worker.mjs +16 -0
  114. package/test/helpers/mail-kill-child.mjs +104 -0
  115. package/test/helpers/signed-relay-record.ts +31 -0
  116. package/test/home-per-call.test.ts +72 -0
  117. package/test/io.test.ts +81 -14
  118. package/test/mail-client-lock-namespace.test.ts +155 -0
  119. package/test/mail-client-repoint-root.test.ts +368 -0
  120. package/test/mail-delivery-at-least-once.test.ts +1238 -0
  121. package/test/mail-event-loop-delivery.test.ts +769 -0
  122. package/test/mail-intent-phases.test.ts +304 -0
  123. package/test/mail-interrupted-recovery.test.ts +393 -0
  124. package/test/mail-lock-pid-state.test.ts +238 -0
  125. package/test/mail-lock.test.ts +96 -0
  126. package/test/mail-partial-flair.test.ts +102 -0
  127. package/test/mail-placement-replay.test.ts +116 -0
  128. package/test/mail-promote-guard.test.ts +305 -21
  129. package/test/mail-relay-reservation.test.ts +60 -0
  130. package/test/mailbox-filename.test.ts +16 -0
  131. package/test/public-key.test.ts +108 -0
  132. package/test/runtime-key-encoding.test.ts +105 -0
  133. package/test/runtime-pending-key.test.ts +117 -0
  134. package/test/security/mail-trust.test.ts +406 -109
@@ -0,0 +1,1085 @@
1
+ /**
2
+ * Shared mailbox policy and consumed-id replay store for both first-delivery
3
+ * paths: the CLI's `promote()` and this package's `MailClient`.
4
+ */
5
+ import { appendFileSync, type BigIntStats, closeSync, type Dirent, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
6
+ import { createHash, randomUUID } from "node:crypto";
7
+ import { homedir } from "node:os";
8
+ import { join } from "node:path";
9
+ import { type Envelope, type FlairClient, verifyEnvelope } from "./signEnvelope.js";
10
+
11
+ // ─── Envelope id shape (cli#429) ─────────────────────────────────────────────
12
+ //
13
+ // signOutboundBody validates replyToId before signing. The mailbox policy
14
+ // validates messageId and any replyToId on receipt; signEnvelope itself does not.
15
+
16
+ /** 1-128 chars of `[A-Za-z0-9._-]`. Anchored; no flags. */
17
+ export const ENVELOPE_ID_SHAPE = /^[A-Za-z0-9._-]{1,128}$/;
18
+
19
+ /** A human-readable statement of ENVELOPE_ID_SHAPE, for error messages. */
20
+ export const ENVELOPE_ID_SHAPE_TEXT = "letters, digits, dot, underscore or hyphen, 1-128 chars";
21
+
22
+ /** True only for a string that satisfies ENVELOPE_ID_SHAPE. */
23
+ export function isValidEnvelopeId(id: unknown): id is string {
24
+ return typeof id === "string" && ENVELOPE_ID_SHAPE.test(id);
25
+ }
26
+
27
+ /** Describe a rejected id without echoing it: its type, and its length for a string. */
28
+ function describeIdValue(value: unknown): string {
29
+ if (typeof value === "string") return value.length === 0 ? "an empty string" : `a ${value.length}-char string outside the rule`;
30
+ return value === null ? "null" : typeof value;
31
+ }
32
+
33
+ // ─── Envelope parsing ────────────────────────────────────────────────────────
34
+
35
+ /**
36
+ * Try to parse a message body as an envelope-shaped record.
37
+ *
38
+ * Returns the envelope object, or the string "json-parse-error" (not JSON) or
39
+ * "missing-fields" (JSON but not envelope-shaped).
40
+ */
41
+ export function tryParseEnvelope(body: string): Record<string, unknown> | "json-parse-error" | "missing-fields" {
42
+ let parsed: unknown;
43
+ try {
44
+ parsed = JSON.parse(body);
45
+ } catch {
46
+ return "json-parse-error";
47
+ }
48
+
49
+ if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
50
+ return "missing-fields";
51
+ }
52
+
53
+ const obj = parsed as Record<string, unknown>;
54
+ if (
55
+ typeof obj.v !== "number" ||
56
+ !Array.isArray(obj.delegationChain) ||
57
+ typeof obj.signature !== "string"
58
+ ) {
59
+ return "missing-fields";
60
+ }
61
+
62
+ return obj;
63
+ }
64
+
65
+ /** Parse an envelope-shaped record with a string body. */
66
+ export function parseSignedEnvelope(body: string): { ok: true; envelope: Envelope } | { ok: false; class: "invalid"; reason: string } {
67
+ const parsed = tryParseEnvelope(body);
68
+ if (parsed === "json-parse-error") {
69
+ return { ok: false, class: "invalid", reason: "body is not JSON (signed envelope required)" };
70
+ }
71
+ if (parsed === "missing-fields") {
72
+ return { ok: false, class: "invalid", reason: "body is not envelope-shaped" };
73
+ }
74
+ if (typeof parsed.body !== "string") {
75
+ return { ok: false, class: "invalid", reason: "envelope body is not a string" };
76
+ }
77
+ if (typeof parsed.from !== "string" || !(parsed.delegationChain as unknown[]).every((hop) => {
78
+ if (!hop || typeof hop !== "object") return false;
79
+ const entry = hop as Record<string, unknown>;
80
+ return typeof entry.agent === "string" && (entry.kind === "agent" || entry.kind === "human")
81
+ && (entry.signature === null || typeof entry.signature === "string");
82
+ })) {
83
+ return { ok: false, class: "invalid", reason: "invalid envelope sender or delegation chain" };
84
+ }
85
+ return { ok: true, envelope: parsed as unknown as Envelope };
86
+ }
87
+
88
+ export function isTopicRecipient(address: unknown, agentId: string, from: string): boolean {
89
+ if (typeof address !== "string" || !address.startsWith("topic:")) return false;
90
+ const topic = address.slice("topic:".length);
91
+ if (!/^[a-z0-9][a-z0-9-]*$/.test(topic) || topic.length > 64) return false;
92
+ try {
93
+ const root = process.env.TPS_HOME || join(process.env.HOME || homedir(), ".tps");
94
+ const meta = JSON.parse(readFileSync(join(root, "topics", topic, "meta.json"), "utf8"));
95
+ return Array.isArray(meta.subscribers) && meta.subscribers.includes(agentId)
96
+ && (meta.allowedPublishers === undefined || (Array.isArray(meta.allowedPublishers)
97
+ && (meta.allowedPublishers.length === 0 || meta.allowedPublishers.includes(from))));
98
+ } catch {
99
+ return false;
100
+ }
101
+ }
102
+
103
+ // ─── The mailbox decision ────────────────────────────────────────────────────
104
+
105
+ /** The reject classes the mailbox policy and the replay gate emit. */
106
+ export type MailboxPolicyRejectClass = "invalid" | "unresolvable-principal" | "wrong-recipient" | "replay";
107
+
108
+ export type MailboxPolicyResult =
109
+ | { ok: true; envelope: Envelope }
110
+ | { ok: false; class: MailboxPolicyRejectClass; reason: string };
111
+
112
+ /**
113
+ * The stable reason string `verifyEnvelope` returns when an agent-kind chain
114
+ * entry or `envelope.from` cannot be resolved from the LOCAL Flair. It is a
115
+ * presence failure, not a signature failure: the principal is simply not
116
+ * registered here.
117
+ */
118
+ const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
119
+
120
+ /**
121
+ * The ONE mailbox decision for an enveloped record.
122
+ *
123
+ * The checks, in order:
124
+ * 1. signature, through the caller's Flair client;
125
+ * 2. wrapper/envelope `from` binding;
126
+ * 3. recipient binding;
127
+ * 4. `messageId` shape, and `replyToId` shape when present;
128
+ * 5. `timestamp` shape.
129
+ *
130
+ * The replay gate (first delivery only) is the ReplayStore below.
131
+ */
132
+ export async function decideEnvelopeForMailbox(
133
+ agent: string,
134
+ envelope: Envelope,
135
+ wrapperFrom: unknown,
136
+ client: FlairClient,
137
+ ): Promise<MailboxPolicyResult> {
138
+ // 1. Signature.
139
+ const verified = await verifyEnvelope(envelope, client);
140
+ if (!verified.ok) {
141
+ // Unresolved-principal presence failure.
142
+ // CLI promotion attempts verify-unavailable dead-lettering on verifier throws;
143
+ // MailClient leaves the record in new/ for retry.
144
+ const missing = UNRESOLVABLE_PRINCIPAL_REASON_RE.exec(verified.reason);
145
+ if (missing) {
146
+ const entry = missing[1]!;
147
+ const reason =
148
+ `unresolvable-principal: ${entry} is not registered in the local Flair ` +
149
+ `(agent-kind delegation-chain entry or sender this mailbox cannot resolve). ` +
150
+ `Possible spoke-topology cause: a spoke holds only its own principal and hub ` +
151
+ `principals are not distributed downward (see cli#383). Not a signature or ` +
152
+ `forgery verdict. Terminal — delivery refused.`;
153
+ return { ok: false, class: "unresolvable-principal", reason };
154
+ }
155
+ return { ok: false, class: "invalid", reason: `signature verification failed: ${verified.reason}` };
156
+ }
157
+
158
+ // 2. The wrapper `from` is what consumers route by, and it is unverified; a
159
+ // wrapper/envelope mismatch is itself a reject.
160
+ if (typeof wrapperFrom !== "string" || wrapperFrom !== envelope.from) {
161
+ return {
162
+ ok: false,
163
+ class: "invalid",
164
+ reason: `wrapper/envelope from mismatch (wrapper.from=${String(wrapperFrom)}, envelope.from=${envelope.from})`,
165
+ };
166
+ }
167
+
168
+ if (envelope.to !== agent && !isTopicRecipient(envelope.to, agent, envelope.from)) {
169
+ return {
170
+ ok: false,
171
+ class: "wrong-recipient",
172
+ reason: `wrong-recipient (envelope.to=${envelope.to}, mailbox=${agent})`,
173
+ };
174
+ }
175
+
176
+ // 4. `messageId` shape — the replay gate keys on it, a reply threads on it,
177
+ // and verifyEnvelope does not enforce it. A malformed id is a terminal
178
+ // reject, not an undefined key that silently never matches. The reason
179
+ // never echoes the value (it may carry control characters); it names only
180
+ // the type/length.
181
+ if (!isValidEnvelopeId(envelope.messageId)) {
182
+ return {
183
+ ok: false,
184
+ class: "invalid",
185
+ reason: `invalid messageId (must be ${ENVELOPE_ID_SHAPE_TEXT}; got ${describeIdValue(envelope.messageId)})`,
186
+ };
187
+ }
188
+
189
+ // 4b. `replyToId` shape (cli#429): optional, but when the envelope carries
190
+ // the field it must satisfy the same rule — a signed value outside it is
191
+ // never presented, whoever signed it.
192
+ if ((envelope as { replyToId?: unknown }).replyToId !== undefined && !isValidEnvelopeId(envelope.replyToId)) {
193
+ return {
194
+ ok: false,
195
+ class: "invalid",
196
+ reason: `invalid replyToId (must be ${ENVELOPE_ID_SHAPE_TEXT}; got ${describeIdValue(envelope.replyToId)})`,
197
+ };
198
+ }
199
+
200
+ // 5. `timestamp` shape — a malformed/absent timestamp is rejected, never
201
+ // silently replaced by the wrapper's unsigned value (that fallback would
202
+ // let an unsigned field stand in for a signed one).
203
+ if (typeof envelope.timestamp !== "string" || Number.isNaN(Date.parse(envelope.timestamp))) {
204
+ const shown = typeof envelope.timestamp === "string" ? JSON.stringify(envelope.timestamp) : String(envelope.timestamp);
205
+ return {
206
+ ok: false,
207
+ class: "invalid",
208
+ reason: `invalid timestamp (must be a parseable timestamp, got ${shown})`,
209
+ };
210
+ }
211
+
212
+ return { ok: true, envelope };
213
+ }
214
+
215
+ // ─── Durable consumed-id ledger (replay gate that survives maildir GC) ───────
216
+ const CONSUMED_LEDGER_FILE = "consumed.jsonl";
217
+ const CONSUMED_LEDGER_RETENTION_MS = 180 * 24 * 60 * 60 * 1000;
218
+
219
+ /** Bounds checked on later deliverNext() calls for unclaimed in_progress work; the deadline precedes re-verification. */
220
+ export const MAX_DELIVERY_PRESENTATIONS = 5;
221
+ export const DELIVERY_PRESENTATION_TTL_MS = 24 * 60 * 60 * 1000;
222
+
223
+ /**
224
+ * cli#617 slice (b): the presenter that holds an `in_progress` intent. `token`
225
+ * is a per-presentation nonce: completion must present it, so a stale or
226
+ * foreign presentation cannot finalize the current one. `pid` and `start` (the
227
+ * process start token mail-lock records for lock owners) say which process
228
+ * holds it. `moduleNonce` identifies the module copy whose token set tracks it;
229
+ * other copies in the same process are treated as live until process exit or lease expiry.
230
+ */
231
+ export interface PresentationClaim {
232
+ token: string;
233
+ pid: number;
234
+ start: string | null;
235
+ moduleNonce: string;
236
+ }
237
+
238
+ /** What a placement intent records (cli#617), as the ReplayStore reads it. */
239
+ export interface PlacementState {
240
+ messageId: string;
241
+ phase: PlacementPhase;
242
+ presentations?: number;
243
+ firstPresentedAt?: string;
244
+ claim?: PresentationClaim;
245
+ }
246
+
247
+ /** The result of a completion attempt against the intent (cli#617 slice b). */
248
+ export type PlacementCompletion = "completed" | "absent" | "stale" | "identity";
249
+
250
+ /**
251
+ * The replay gate and placement intents for one mailbox. Call while holding
252
+ * that mailbox's lock (acquireMailLock on the same root).
253
+ */
254
+ export interface ReplayStore {
255
+ isConsumed(messageId: string, pendingFile?: string): boolean;
256
+ /**
257
+ * Write a `placing` intent. Refuses to replace an intent in any other phase,
258
+ * with one exception (cli#617). A `failed` marker for a different message,
259
+ * whose payload has left cur/, moves to its tombstone when that name is
260
+ * unoccupied, or is the marker's own inode (treated as an interrupted move).
261
+ * An occupied tombstone refuses the placement by name.
262
+ */
263
+ beginPlacement(messageId: string, file: string, sourcePath?: string | number): void;
264
+ ownsPendingPlacement(messageId: string, file: string): boolean;
265
+ /** A live (not `failed`) intent for this messageId names `file`. */
266
+ hasPendingPlacement(messageId: string, file: string): boolean;
267
+ /** The per-file gate: a quarantined or live (not `failed`) intent names `file`. */
268
+ hasPendingFile(file: string): boolean;
269
+ /**
270
+ * The phase of `file`'s placement intent, or null when it has none (cli#617).
271
+ * Throws MalformedPlacementIntentError on a quarantined or malformed intent.
272
+ */
273
+ placementPhase(file: string): PlacementPhase | null;
274
+ /** Delete a `placing` intent for this messageId. An intent in any other phase is kept. */
275
+ finishPlacement(messageId: string, file: string): void;
276
+ /**
277
+ * Record a consumed messageId. Call ONLY after the record is in cur/; THROWS
278
+ * on failure, and the caller must then roll the move back.
279
+ */
280
+ recordConsumed(messageId: string): void;
281
+ /**
282
+ * cli#617 slice (b): what `file`'s intent records, or null when it has none.
283
+ * Throws MalformedPlacementIntentError on a quarantined or malformed intent.
284
+ */
285
+ placementState(file: string): PlacementState | null;
286
+ /**
287
+ * cli#617 slice (b): advance a live (`placing` or `in_progress`) intent for
288
+ * this message to its next presentation, recording `claim` as its holder. A
289
+ * `placing` intent becomes `in_progress` at presentation 1; an `in_progress`
290
+ * intent's count increments. Returns `absent` when no live intent for this
291
+ * message is present (missing, another message, or a `failed`/`unknown`
292
+ * phase), `presented` with the new count, or terminal `failed` before a sixth
293
+ * presentation or when the deadline is exceeded. The count check permits the fifth.
294
+ * The caller must not present a failed intent and first checks claim liveness.
295
+ * Call under the mailbox lock.
296
+ */
297
+ advancePresentation(messageId: string, file: string, nowIso: string, claim: PresentationClaim): PresentationAdvance;
298
+ /**
299
+ * cli#617 slice (b): the deadline alone. An `in_progress` intent for this
300
+ * message whose first presentation is more than DELIVERY_PRESENTATION_TTL_MS
301
+ * before `nowIso` goes terminal `failed` (`failed`); otherwise it is unchanged
302
+ * (`live`), or there is no `in_progress` intent for this message (`absent`).
303
+ * It never presents. The caller first checks claim liveness. Call under the mailbox lock.
304
+ */
305
+ expireOverdue(messageId: string, file: string, nowIso: string): { status: "failed"; presentations: number } | { status: "live" } | { status: "absent" };
306
+ /**
307
+ * cli#617 slice (b): completion-only finalize, bound to one presentation.
308
+ * Deletes the intent only when it is `in_progress` for this message, its
309
+ * claim carries `token`, and `cur/<file>` is still the file the intent
310
+ * recorded (device, inode, size and SHA-256). These results leave it unchanged: `absent` (no intent
311
+ * for this message), `stale` (phase is not `in_progress` or claim token does not match),
312
+ * or `identity` (recorded cur/ identity absent or mismatched).
313
+ */
314
+ completePlacement(messageId: string, file: string, token: string): PlacementCompletion;
315
+ releasePlacement(messageId: string, file: string, token: string): boolean;
316
+ }
317
+
318
+ /** The result of advancing a placement intent to its next presentation (cli#617 slice b). */
319
+ export type PresentationAdvance =
320
+ | { status: "absent" }
321
+ | { status: "presented"; presentations: number }
322
+ | { status: "failed"; presentations: number };
323
+
324
+ /** The durable ReplayStore for the mailbox rooted at `root` (`<mailDir>/<agent>`). */
325
+ export function mailboxReplayStore(root: string): ReplayStore {
326
+ return {
327
+ isConsumed: (messageId, pendingFile) => isConsumedMessageId(root, messageId, pendingFile),
328
+ beginPlacement: (messageId, file, sourcePath) => writePlacementIntent(root, messageId, file, sourcePath),
329
+ ownsPendingPlacement: (messageId, file) => {
330
+ const intent = readPlacementIntent(root, file);
331
+ if (intent?.messageId !== messageId || !intent.identity) return false;
332
+ try {
333
+ const stat = lstatSync(join(root, "cur", file), { bigint: true });
334
+ return stat.isFile() && matchesFileIdentity(stat, intent.identity, readFileSync(join(root, "cur", file)));
335
+ } catch (err) {
336
+ if (isMissing(err)) return false;
337
+ throw err;
338
+ }
339
+ },
340
+ hasPendingFile: (file) => existsSync(`${placementIntentPath(root, file)}.quarantined`) || isLivePlacement(readPlacementIntent(root, file)),
341
+ hasPendingPlacement: (messageId, file) => {
342
+ const intent = readPlacementIntent(root, file);
343
+ return intent?.messageId === messageId && isLivePlacement(intent);
344
+ },
345
+ placementPhase: (file) => readPlacementIntent(root, file)?.phase ?? null,
346
+ finishPlacement: (messageId, file) => {
347
+ const intent = readPlacementIntent(root, file);
348
+ if (intent?.messageId !== messageId || intent.phase !== "placing") return;
349
+ unlinkSync(placementIntentPath(root, file));
350
+ syncDirectory(root);
351
+ },
352
+ recordConsumed: (messageId) => recordConsumedMessageId(root, messageId),
353
+ placementState: (file) => {
354
+ const intent = readPlacementIntent(root, file);
355
+ if (!intent) return null;
356
+ return {
357
+ messageId: intent.messageId, phase: intent.phase,
358
+ ...(intent.presentations === undefined ? {} : { presentations: intent.presentations }),
359
+ ...(intent.firstPresentedAt === undefined ? {} : { firstPresentedAt: intent.firstPresentedAt }),
360
+ ...(intent.claim === undefined ? {} : { claim: { ...intent.claim } }),
361
+ };
362
+ },
363
+ advancePresentation: (messageId, file, nowIso, claim) => advancePlacementPresentation(root, messageId, file, nowIso, claim),
364
+ expireOverdue: (messageId, file, nowIso) => expireOverduePlacement(root, messageId, file, nowIso),
365
+ completePlacement: (messageId, file, token) => completeInProgressPlacement(root, messageId, file, token),
366
+ releasePlacement: (messageId, file, token) => releaseInProgressPlacement(root, messageId, file, token),
367
+ };
368
+ }
369
+
370
+ /**
371
+ * List well-formed pending intents with their phase; quarantine malformed ones
372
+ * and omit them. An intent whose phase resolves to `failed` is not pending and
373
+ * is omitted.
374
+ * Call under the mailbox lock and re-read each intent before acting on it.
375
+ */
376
+ export function pendingPlacementEntries(root: string): Array<{ messageId: string; file: string; phase: PlacementPhase }> {
377
+ const entries: Array<{ messageId: string; file: string; phase: PlacementPhase }> = [];
378
+ let names: string[];
379
+ try {
380
+ names = readdirSync(root);
381
+ } catch (err) {
382
+ if (isMissing(err)) return entries;
383
+ throw err;
384
+ }
385
+ for (const name of names) {
386
+ if (!/^\.placement-[a-f0-9]{64}\.json$/.test(name)) continue;
387
+ const path = join(root, name);
388
+ let raw: string;
389
+ try {
390
+ raw = readFileSync(path, "utf8");
391
+ } catch (err) {
392
+ if (isMissing(err)) continue; // removed after the listing
393
+ throw err;
394
+ }
395
+ const intent = parsePlacement(raw, path);
396
+ if (!intent) {
397
+ quarantinePlacement(path);
398
+ continue;
399
+ }
400
+ if (!isLivePlacement(intent)) continue;
401
+ entries.push({ messageId: intent.messageId, file: intent.file, phase: intent.phase });
402
+ }
403
+ return entries;
404
+ }
405
+
406
+ function placementIntentPath(root: string, file: string): string {
407
+ return join(root, `.placement-${createHash("sha256").update(file).digest("hex")}.json`);
408
+ }
409
+
410
+ function malformedPlacement(path: string): Error {
411
+ const err = new Error(`malformed placement intent at ${path}`);
412
+ err.name = "MalformedPlacementIntentError";
413
+ return err;
414
+ }
415
+
416
+ function quarantinePlacement(path: string): void {
417
+ const err = malformedPlacement(path);
418
+ writeFileSync(`${path}.quarantined.reason`, `${err.name}: ${err.message}\n`, { mode: 0o600 });
419
+ renameSync(path, `${path}.quarantined`);
420
+ syncDirectory(join(path, ".."));
421
+ console.warn(`${err.name}: ${err.message}`);
422
+ }
423
+
424
+ /**
425
+ * The phase phaseOf RESOLVES for a placement intent (cli#617 design rev 2).
426
+ * Every rule keys on this resolved result, not on the raw `phase` field.
427
+ * phaseOf checks `version`, `presentations` and `firstPresentedAt` before
428
+ * `phase`. An unsupported value in any of them resolves to `unknown` whatever
429
+ * `phase` says: `version: 2` with no `phase`, and `version: 2` with
430
+ * `phase: "failed"`, both resolve to `unknown`. The result reflects what the
431
+ * intent declares; it does not prove the state behind it.
432
+ *
433
+ * - `placing`: a commit in flight. An intent resolves to `placing` when it has
434
+ * no `phase` (or `phase: "placing"`), a recognized `version` (absent or 1) and
435
+ * valid liveness values (absent or well-formed). So an otherwise-valid intent
436
+ * written before phases existed, whose `file` is a plain basename, reads as
437
+ * before. The one exception: an older intent whose `file` is not a plain
438
+ * basename, which the old parser accepted when its hashed name matched, is
439
+ * now malformed and quarantined.
440
+ * - `in_progress`: `phase: "in_progress"` under the same `version` and liveness
441
+ * conditions; it declares a committed message whose handler has not completed.
442
+ * - `failed`: `phase: "failed"` under the same conditions; it declares a
443
+ * terminal message (its liveness bound was reached). It is not pending: it
444
+ * never closes the per-file (filename) gate and is never listed for
445
+ * recovery, while its message ID stays refused by the consumed-ID (replay)
446
+ * gate. A different message may need the same basename once the old payload
447
+ * has left cur/. If the tombstone name (failedTombstonePath) is unoccupied,
448
+ * or is the marker's own inode (treated as an interrupted move), the marker
449
+ * moves there and the new placement proceeds. An occupied tombstone refuses
450
+ * the placement by name. While the payload is in cur/, the marker stays and
451
+ * the new placement is refused. The record is kept until an operator
452
+ * removes it.
453
+ * - `unknown`: an unsupported value in a recognized field (`phase`, `version`,
454
+ * `presentations`, `firstPresentedAt` or `claim`, where `presentations` must
455
+ * be a non-negative safe integer and a `claim` is valid only on an
456
+ * `in_progress` intent); other extra fields are ignored. The store never
457
+ * finishes or replaces it; MailClient recovery, the CLI lease sweep and CLI
458
+ * promotion never present it; and it is not quarantined solely for that
459
+ * value. It keeps its own per-file gate closed.
460
+ *
461
+ * Slice (b) adds the writers: MailClient.deliverNext() writes `in_progress`
462
+ * (with its presentation claim) and the liveness bound writes `failed`. Nothing
463
+ * in the agent runtime calls deliverNext() until slice (c).
464
+ */
465
+ export type PlacementPhase = "placing" | "in_progress" | "failed" | "unknown";
466
+
467
+ /** The placement intent schema version this reader understands; an intent without one is this version. */
468
+ const PLACEMENT_INTENT_VERSION = 1;
469
+
470
+ export interface FileIdentity {
471
+ dev: string;
472
+ ino: string;
473
+ size?: string;
474
+ sha256?: string;
475
+ }
476
+
477
+ // Link changes preserve this identity. The same device, inode and bytes are accepted as the same message.
478
+ export function fileIdentity(stat: BigIntStats, bytes: Buffer): FileIdentity {
479
+ return { dev: stat.dev.toString(), ino: stat.ino.toString(), size: stat.size.toString(), sha256: createHash("sha256").update(bytes).digest("hex") };
480
+ }
481
+
482
+ export function matchesFileIdentity(stat: BigIntStats, identity: FileIdentity, bytes: Buffer): boolean {
483
+ const current = fileIdentity(stat, bytes);
484
+ return stat.isFile() && current.dev === identity.dev && current.ino === identity.ino
485
+ && current.size === identity.size && current.sha256 === identity.sha256;
486
+ }
487
+
488
+ interface PlacementIntent {
489
+ messageId: string;
490
+ file: string;
491
+ identity?: FileIdentity;
492
+ phase: PlacementPhase;
493
+ /** Hand-overs so far (rev 2 liveness bound). */
494
+ presentations?: number;
495
+ /** When the first hand-over happened (rev 2 liveness bound). */
496
+ firstPresentedAt?: string;
497
+ /** The presentation holding an `in_progress` intent (slice b). */
498
+ claim?: PresentationClaim;
499
+ }
500
+
501
+ /** A plain basename: non-empty, not `.` or `..`, with no path separator or NUL. */
502
+ function isPlainBasename(file: string): boolean {
503
+ return file !== "" && file !== "." && file !== ".." && !/[/\\\0]/.test(file);
504
+ }
505
+
506
+ const CLAIM_TOKEN_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
507
+
508
+ /** A presentation claim has UUID token/module nonces, a positive pid and a start token string or null. */
509
+ function isPresentationClaim(value: unknown): value is PresentationClaim {
510
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
511
+ const claim = value as Record<string, unknown>;
512
+ return typeof claim.token === "string" && CLAIM_TOKEN_SHAPE.test(claim.token)
513
+ && typeof claim.moduleNonce === "string" && CLAIM_TOKEN_SHAPE.test(claim.moduleNonce)
514
+ && Number.isSafeInteger(claim.pid) && (claim.pid as number) > 0
515
+ && (claim.start === null || (typeof claim.start === "string" && claim.start.length > 0 && claim.start.length <= 256));
516
+ }
517
+
518
+ /**
519
+ * Resolve the phase of a parsed intent. `version`, `presentations` and
520
+ * `firstPresentedAt` are checked first, and an unsupported value in any of them
521
+ * resolves to `unknown` whatever `phase` says. Then `phase` resolves: absent or
522
+ * `placing`, `in_progress`, `failed`, and anything else is `unknown`. `unknown`
523
+ * is not malformed, and other extra fields are ignored. A malformed identity or
524
+ * basename is still malformed (parsePlacement).
525
+ */
526
+ function phaseOf(intent: Record<string, unknown>): PlacementPhase {
527
+ if (intent.version !== undefined && intent.version !== PLACEMENT_INTENT_VERSION) return "unknown";
528
+ const presentations = intent.presentations;
529
+ if (presentations !== undefined && !(Number.isSafeInteger(presentations) && (presentations as number) >= 0)) return "unknown";
530
+ const firstPresentedAt = intent.firstPresentedAt;
531
+ if (firstPresentedAt !== undefined && (typeof firstPresentedAt !== "string" || Number.isNaN(Date.parse(firstPresentedAt)))) {
532
+ return "unknown";
533
+ }
534
+ const claim = intent.claim;
535
+ if (claim !== undefined && !isPresentationClaim(claim)) return "unknown";
536
+ const phase = intent.phase;
537
+ let resolved: PlacementPhase;
538
+ if (phase === undefined || phase === "placing") resolved = "placing";
539
+ else if (phase === "in_progress" || phase === "failed") resolved = phase;
540
+ else return "unknown";
541
+ // A claim is valid only on an in_progress intent.
542
+ if (claim !== undefined && resolved !== "in_progress") return "unknown";
543
+ return resolved;
544
+ }
545
+
546
+ /** A pending intent: any resolved phase but `failed`. */
547
+ function isLivePlacement(intent: PlacementIntent | null): boolean {
548
+ return intent !== null && intent.phase !== "failed";
549
+ }
550
+
551
+ /**
552
+ * Parse an intent, or null when it is malformed: the name, messageId and
553
+ * identity must hold; an in_progress claim requires firstPresentedAt.
554
+ * An unsupported value in `phase`, `version` or a liveness field alone never
555
+ * makes an intent malformed (see phaseOf).
556
+ */
557
+ function parsePlacement(raw: string, path: string): PlacementIntent | null {
558
+ try {
559
+ const intent = JSON.parse(raw);
560
+ if (typeof intent?.file === "string" && isPlainBasename(intent.file)
561
+ && placementIntentPath(join(path, ".."), intent.file) === path
562
+ && isValidEnvelopeId(intent?.messageId)
563
+ && (intent.identity === undefined || (typeof intent.identity?.dev === "string"
564
+ && typeof intent.identity?.ino === "string" && /^(0|[1-9][0-9]*)$/.test(intent.identity.dev)
565
+ && /^[1-9][0-9]*$/.test(intent.identity.ino)
566
+ && (intent.identity.sha256 === undefined || (typeof intent.identity.sha256 === "string" && /^[a-f0-9]{64}$/.test(intent.identity.sha256)))
567
+ && (intent.identity.size === undefined || (typeof intent.identity.size === "string" && /^(0|[1-9][0-9]*)$/.test(intent.identity.size)))))) {
568
+ if (intent.phase === "in_progress" && intent.claim !== undefined && intent.firstPresentedAt === undefined) return null;
569
+ const phase = phaseOf(intent);
570
+ return {
571
+ messageId: intent.messageId, file: intent.file, identity: intent.identity, phase,
572
+ ...(phase === "unknown" ? {} : {
573
+ presentations: intent.presentations,
574
+ firstPresentedAt: intent.firstPresentedAt,
575
+ ...(intent.claim === undefined ? {} : { claim: { token: intent.claim.token, pid: intent.claim.pid, start: intent.claim.start, moduleNonce: intent.claim.moduleNonce } }),
576
+ }),
577
+ };
578
+ }
579
+ } catch {}
580
+ return null;
581
+ }
582
+
583
+ function readPlacementIntent(root: string, file: string): PlacementIntent | null {
584
+ const path = placementIntentPath(root, file);
585
+ if (existsSync(`${path}.quarantined`)) throw malformedPlacement(path);
586
+ let raw: string;
587
+ try { raw = readFileSync(path, "utf8"); } catch (err) {
588
+ if (isMissing(err)) return null;
589
+ throw err;
590
+ }
591
+ const intent = parsePlacement(raw, path);
592
+ if (!intent) {
593
+ quarantinePlacement(path);
594
+ throw malformedPlacement(path);
595
+ }
596
+ return intent;
597
+ }
598
+
599
+ /**
600
+ * Where a retired `failed` marker for `file` is kept (cli#617):
601
+ * `.placement-<sha256(file)>.failed-<messageId>.json`. A tombstone leaves the
602
+ * per-file (filename) gate open and is never listed for recovery. It keeps its
603
+ * message ID retained in the consumed ledger (pendingPlacementIds), so the
604
+ * consumed-ID (replay) gate still refuses that message. It stays until an
605
+ * operator removes it.
606
+ */
607
+ function failedTombstonePath(root: string, file: string, messageId: string): string {
608
+ return `${placementIntentPath(root, file).slice(0, -".json".length)}.failed-${messageId}.json`;
609
+ }
610
+
611
+ const FAILED_TOMBSTONE_NAME = /^\.placement-[a-f0-9]{64}\.failed-(.+)\.json$/;
612
+
613
+ /**
614
+ * Move a `failed` marker to its tombstone without ever replacing one: the link
615
+ * fails if the tombstone name is taken. A tombstone that is the marker's own
616
+ * inode is treated as an interrupted earlier move, which this finishes. Any
617
+ * other occupant is refused by name, and the marker and the tombstone are both
618
+ * kept.
619
+ */
620
+ function retireFailedMarker(root: string, path: string, file: string, messageId: string): void {
621
+ const tombstone = failedTombstonePath(root, file, messageId);
622
+ try {
623
+ linkSync(path, tombstone);
624
+ } catch (err) {
625
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
626
+ const marker = lstatSync(path, { bigint: true });
627
+ const kept = lstatSync(tombstone, { bigint: true });
628
+ if (!marker.isFile() || !kept.isFile() || !matchesFileIdentity(marker, fileIdentity(kept, readFileSync(tombstone)), readFileSync(path))) {
629
+ const refusal = new Error(`failed tombstone occupied for ${file} (message ${messageId}); marker and tombstone kept`);
630
+ refusal.name = "FailedTombstoneOccupiedError";
631
+ throw refusal;
632
+ }
633
+ }
634
+ unlinkSync(path);
635
+ syncDirectory(root);
636
+ }
637
+
638
+ function isAbsent(path: string): boolean {
639
+ try {
640
+ lstatSync(path);
641
+ return false;
642
+ } catch (err) {
643
+ if (isMissing(err)) return true;
644
+ throw err;
645
+ }
646
+ }
647
+
648
+ function syncDirectory(root: string): void {
649
+ const fd = openSync(root, "r");
650
+ try { fsyncSync(fd); } finally { closeSync(fd); }
651
+ }
652
+
653
+ function writePlacementIntent(root: string, messageId: string, file: string, sourcePath?: string | number): void {
654
+ if (!isValidEnvelopeId(messageId)) throw new Error("invalid placement messageId");
655
+ if (!isPlainBasename(file)) throw new Error("placement file is not a plain basename");
656
+ const path = placementIntentPath(root, file);
657
+ const existing = readPlacementIntent(root, file);
658
+ if (existing && existing.messageId !== messageId) {
659
+ // cli#617: once its payload has left cur/, a `failed` marker yields its
660
+ // basename to a different message. It moves to its tombstone, keeping the
661
+ // operator's record and the old consumed ID, and this placement proceeds.
662
+ // The exception is an occupied tombstone, which refuses by name
663
+ // (retireFailedMarker).
664
+ if (existing.phase !== "failed" || !isAbsent(join(root, "cur", file))) {
665
+ throw new Error(`placement intent for ${file} names another message`);
666
+ }
667
+ retireFailedMarker(root, path, file, existing.messageId);
668
+ } else if (existing && existing.phase !== "placing") {
669
+ // cli#617: only a `placing` intent is rewritten; any other phase is kept.
670
+ throw new Error(`placement intent for ${file} is ${existing.phase}; not replaced`);
671
+ }
672
+ let identity: PlacementIntent["identity"];
673
+ if (sourcePath !== undefined) {
674
+ const stat = typeof sourcePath === "number" ? fstatSync(sourcePath, { bigint: true }) : lstatSync(sourcePath, { bigint: true });
675
+ if (!stat.isFile()) throw new Error("placement source is not a regular file");
676
+ identity = fileIdentity(stat, readFileSync(sourcePath));
677
+ }
678
+ const tmp = `${path}.${randomUUID()}.tmp`;
679
+ const fd = openSync(tmp, "wx", 0o600);
680
+ try {
681
+ try {
682
+ writeFileSync(fd, JSON.stringify({ messageId, file, identity }));
683
+ fsyncSync(fd);
684
+ } finally { closeSync(fd); }
685
+ renameSync(tmp, path);
686
+ syncDirectory(root);
687
+ } finally {
688
+ rmSync(tmp, { force: true });
689
+ }
690
+ }
691
+
692
+ /**
693
+ * cli#617 slice (b): rewrite the live intent for `file` in place, keeping its
694
+ * messageId and recorded identity. Refuses (returns false) unless a `placing`
695
+ * or `in_progress` intent for this message is present; a `failed` or `unknown`
696
+ * intent, or another message's intent, is never replaced. The write is the
697
+ * temp-file, fsync, rename, directory-fsync sequence. A
698
+ * `.phase.tmp` suffix marks the phase transition for the crash-boundary
699
+ * fixture (mail-kill-child).
700
+ */
701
+ function writePlacementPhase(root: string, messageId: string, file: string, fields: Record<string, unknown>): boolean {
702
+ const path = placementIntentPath(root, file);
703
+ const existing = readPlacementIntent(root, file);
704
+ if (!existing || existing.messageId !== messageId) return false;
705
+ if (existing.phase !== "placing" && existing.phase !== "in_progress") return false;
706
+ const next: Record<string, unknown> = {
707
+ messageId,
708
+ file,
709
+ ...(existing.identity ? { identity: existing.identity } : {}),
710
+ ...fields,
711
+ };
712
+ const tmp = `${path}.${randomUUID()}.phase.tmp`;
713
+ const fd = openSync(tmp, "wx", 0o600);
714
+ try {
715
+ try {
716
+ writeFileSync(fd, JSON.stringify(next));
717
+ fsyncSync(fd);
718
+ } finally { closeSync(fd); }
719
+ renameSync(tmp, path);
720
+ syncDirectory(root);
721
+ } finally {
722
+ rmSync(tmp, { force: true });
723
+ }
724
+ return true;
725
+ }
726
+
727
+ /** Is an `in_progress` intent past the deadline at `nowIso`? An intent without a first presentation never is. */
728
+ function pastDeliveryDeadline(intent: PlacementIntent, nowIso: string): boolean {
729
+ if (intent.firstPresentedAt === undefined) return false;
730
+ return Date.parse(nowIso) - Date.parse(intent.firstPresentedAt) > DELIVERY_PRESENTATION_TTL_MS;
731
+ }
732
+
733
+ /** Write the terminal `failed` phase over a live intent, dropping its claim. */
734
+ function failPlacement(root: string, messageId: string, file: string, presentations: number, firstPresentedAt: string): boolean {
735
+ return writePlacementPhase(root, messageId, file, {
736
+ version: PLACEMENT_INTENT_VERSION, phase: "failed", presentations, firstPresentedAt,
737
+ });
738
+ }
739
+
740
+ /**
741
+ * cli#617 slice (b): advance a live intent to its next presentation, or to the
742
+ * terminal `failed` phase before a sixth presentation or when the deadline is
743
+ * exceeded. The count check permits the fifth. A `placing`
744
+ * intent becomes `in_progress` at presentation 1 (the first hand-over, counted
745
+ * before it); an `in_progress` intent's count increments. Either way the new
746
+ * presentation's claim replaces any earlier one, so an earlier presentation can
747
+ * no longer complete it. `failed` and `unknown` are not live, so they advance
748
+ * to `absent`.
749
+ */
750
+ function advancePlacementPresentation(
751
+ root: string, messageId: string, file: string, nowIso: string, claim: PresentationClaim,
752
+ ): PresentationAdvance {
753
+ if (!isPresentationClaim(claim)) throw new Error("invalid presentation claim");
754
+ const intent = readPlacementIntent(root, file);
755
+ if (!intent || intent.messageId !== messageId) return { status: "absent" };
756
+ if (intent.phase === "placing") {
757
+ const written = writePlacementPhase(root, messageId, file, {
758
+ version: PLACEMENT_INTENT_VERSION, phase: "in_progress", presentations: 1, firstPresentedAt: nowIso, claim,
759
+ });
760
+ return written ? { status: "presented", presentations: 1 } : { status: "absent" };
761
+ }
762
+ if (intent.phase !== "in_progress") return { status: "absent" };
763
+ const previous = intent.presentations ?? 0;
764
+ const firstPresentedAt = intent.firstPresentedAt ?? nowIso;
765
+ const next = previous + 1;
766
+ if (next > MAX_DELIVERY_PRESENTATIONS || pastDeliveryDeadline(intent, nowIso)) {
767
+ return failPlacement(root, messageId, file, previous, firstPresentedAt)
768
+ ? { status: "failed", presentations: previous }
769
+ : { status: "absent" };
770
+ }
771
+ const written = writePlacementPhase(root, messageId, file, {
772
+ version: PLACEMENT_INTENT_VERSION, phase: "in_progress", presentations: next, firstPresentedAt, claim,
773
+ });
774
+ return written ? { status: "presented", presentations: next } : { status: "absent" };
775
+ }
776
+
777
+ /** cli#617 slice (b): the deadline alone, never a presentation (see ReplayStore.expireOverdue). */
778
+ function expireOverduePlacement(
779
+ root: string, messageId: string, file: string, nowIso: string,
780
+ ): { status: "failed"; presentations: number } | { status: "live" } | { status: "absent" } {
781
+ const intent = readPlacementIntent(root, file);
782
+ if (!intent || intent.messageId !== messageId || intent.phase !== "in_progress") return { status: "absent" };
783
+ if (!pastDeliveryDeadline(intent, nowIso)) return { status: "live" };
784
+ const presentations = intent.presentations ?? 0;
785
+ return failPlacement(root, messageId, file, presentations, intent.firstPresentedAt!)
786
+ ? { status: "failed", presentations }
787
+ : { status: "absent" };
788
+ }
789
+
790
+ function releaseInProgressPlacement(root: string, messageId: string, file: string, token: string): boolean {
791
+ const intent = readPlacementIntent(root, file);
792
+ if (!intent || intent.messageId !== messageId || intent.phase !== "in_progress" || intent.claim?.token !== token) return false;
793
+ return writePlacementPhase(root, messageId, file, {
794
+ version: PLACEMENT_INTENT_VERSION,
795
+ phase: "in_progress",
796
+ presentations: intent.presentations,
797
+ firstPresentedAt: intent.firstPresentedAt,
798
+ });
799
+ }
800
+
801
+ export class PlacementDurabilityError extends Error {}
802
+
803
+ /**
804
+ * cli#617 slice (b): completion-only finalize, bound to one presentation: the
805
+ * intent must be `in_progress` for this message, carry `token` in its claim,
806
+ * and still name the cur/ file at its recorded identity.
807
+ */
808
+ function completeInProgressPlacement(root: string, messageId: string, file: string, token: string): PlacementCompletion {
809
+ const intent = readPlacementIntent(root, file);
810
+ if (!intent || intent.messageId !== messageId) return "absent";
811
+ if (intent.phase !== "in_progress" || intent.claim?.token !== token) return "stale";
812
+ if (!intent.identity) return "identity";
813
+ let stat: BigIntStats;
814
+ try {
815
+ stat = lstatSync(join(root, "cur", file), { bigint: true });
816
+ if (!stat.isFile() || !matchesFileIdentity(stat, intent.identity, readFileSync(join(root, "cur", file)))) return "identity";
817
+ } catch (err) {
818
+ if (isMissing(err)) return "identity";
819
+ throw err;
820
+ }
821
+ unlinkSync(placementIntentPath(root, file));
822
+ try { syncDirectory(root); } catch (cause) {
823
+ throw new PlacementDurabilityError("intent unlinked; directory sync failed, durability uncertain", { cause });
824
+ }
825
+ return "completed";
826
+ }
827
+
828
+ function pendingPlacementIds(root: string, quarantine = false): { ids: Set<string>; blocked: Set<string>; retainAll: boolean } {
829
+ const ids = new Set<string>();
830
+ const blocked = new Set<string>();
831
+ let retainAll = false;
832
+ for (const name of readdirSync(root)) {
833
+ // A retired `failed` marker keeps its message ID retained, by its name alone.
834
+ const tombstone = FAILED_TOMBSTONE_NAME.exec(name);
835
+ if (tombstone) {
836
+ if (isValidEnvelopeId(tombstone[1])) ids.add(tombstone[1]);
837
+ continue;
838
+ }
839
+ if (!/^\.placement-[a-f0-9]{64}\.json(?:\.quarantined)?$/.test(name)) continue;
840
+ const path = join(root, name.replace(/\.quarantined$/, ""));
841
+ const raw = readFileSync(join(root, name), "utf8");
842
+ const intent = name.endsWith(".quarantined") ? null : parsePlacement(raw, path);
843
+ if (intent) {
844
+ ids.add(intent.messageId);
845
+ continue;
846
+ }
847
+ const matches = [...raw.matchAll(/"messageId"\s*:\s*("(?:[^"\\]|\\.)*")/g)];
848
+ if (matches.length === 0 || matches.length !== [...raw.matchAll(/"messageId"\s*:/g)].length) retainAll = true;
849
+ for (const match of matches) {
850
+ try {
851
+ const id = JSON.parse(match[1]!);
852
+ if (isValidEnvelopeId(id)) { ids.add(id); blocked.add(id); }
853
+ else retainAll = true;
854
+ } catch { retainAll = true; }
855
+ }
856
+ if (quarantine && !name.endsWith(".quarantined")) quarantinePlacement(path);
857
+ }
858
+ return { ids, blocked, retainAll };
859
+ }
860
+
861
+ function consumedLedgerPath(root: string): string {
862
+ return join(root, CONSUMED_LEDGER_FILE);
863
+ }
864
+
865
+ /**
866
+ * Append after writing cur/. A successful append commits the promotion.
867
+ */
868
+ function recordConsumedMessageId(root: string, messageId: string): void {
869
+ mkdirSync(root, { recursive: true });
870
+ const path = consumedLedgerPath(root);
871
+ const raw = readLedgerText(root);
872
+ if (raw === null) writeFileSync(path, "", { flag: "wx" });
873
+ try {
874
+ writeFileSync(join(root, ".consumed-initialized"), "", { flag: "wx" });
875
+ } catch (err) {
876
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
877
+ }
878
+ appendFileSync(path, `${raw !== null && raw !== "" && !raw.endsWith("\n") ? "\n" : ""}${JSON.stringify({ id: messageId, at: new Date().toISOString() })}\n`, "utf-8");
879
+ }
880
+
881
+ function parseConsumedLedger(raw: string, cutoff: number, pendingIds: Set<string>, retainAll = false): { ids: Set<string>; kept: string[]; pruned: number } {
882
+ const ids = new Set<string>();
883
+ const kept: string[] = [];
884
+ let pruned = 0;
885
+ for (const line of raw.split("\n")) {
886
+ if (!line) continue;
887
+ let entry: { id?: unknown; at?: unknown };
888
+ try {
889
+ entry = JSON.parse(line);
890
+ } catch {
891
+ // Retain intact IDs; a line without one blocks delivery.
892
+ const matches = [...line.matchAll(/"id"\s*:\s*("(?:[^"\\]|\\.)*")/g)];
893
+ if (matches.length === 0 || matches.length !== [...line.matchAll(/"id"\s*:/g)].length) {
894
+ throw new Error("consumed history has an unrecoverable ID");
895
+ }
896
+ for (const match of matches) {
897
+ const id = JSON.parse(match[1]!);
898
+ if (!isValidEnvelopeId(id)) throw new Error("consumed history has an invalid ID");
899
+ ids.add(id);
900
+ }
901
+ kept.push(line);
902
+ continue;
903
+ }
904
+ const id = entry?.id;
905
+ if (!isValidEnvelopeId(id)) throw new Error("consumed history has an invalid ID");
906
+ const at = typeof entry.at === "string" ? Date.parse(entry.at) : Number.NaN;
907
+ if (Number.isNaN(at)) {
908
+ ids.add(id);
909
+ kept.push(line);
910
+ continue;
911
+ }
912
+ if (at < cutoff && !retainAll && !pendingIds.has(id)) {
913
+ pruned++;
914
+ continue;
915
+ }
916
+ ids.add(id);
917
+ kept.push(line);
918
+ }
919
+ return { ids, kept, pruned };
920
+ }
921
+
922
+ /**
923
+ * The replace drops any line appended between the read and the rename, so call
924
+ * this only while holding the mailbox lock. A reader that does not hold the
925
+ * lock uses peekConsumedLedger.
926
+ */
927
+ function readConsumedLedger(root: string): Set<string> {
928
+ const path = consumedLedgerPath(root);
929
+
930
+ const raw = readLedgerText(root);
931
+ const pending = pendingPlacementIds(root, true);
932
+ if (raw === null) return pending.blocked;
933
+
934
+ const { ids, kept, pruned } = parseConsumedLedger(raw, Date.now() - CONSUMED_LEDGER_RETENTION_MS, pending.ids, pending.retainAll);
935
+ if (pruned > 0) {
936
+ try {
937
+ const tmp = `${path}.tmp`;
938
+ writeFileSync(tmp, kept.length > 0 ? `${kept.join("\n")}\n` : "", "utf-8");
939
+ renameSync(tmp, path);
940
+ } catch {
941
+ // Pruning is housekeeping — non-fatal, retried on the next read.
942
+ }
943
+ }
944
+ for (const id of pending.blocked) ids.add(id);
945
+ return ids;
946
+ }
947
+
948
+ /** A read error on consumed history, naming the path that could not be read. */
949
+ function unreadableHistory(path: string, err: unknown): Error {
950
+ const code = (err as NodeJS.ErrnoException | undefined)?.code;
951
+ const detail = code ?? (err instanceof Error ? err.message : String(err));
952
+ return new Error(`consumed history at ${path} is unreadable (${detail})`);
953
+ }
954
+
955
+ function isMissing(err: unknown): boolean {
956
+ return (err as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
957
+ }
958
+
959
+ /**
960
+ * Read the ledger without changing it: the live id set readConsumedLedger would
961
+ * return, or null for an uninitialized missing ledger. It never writes,
962
+ * renames or prunes.
963
+ */
964
+ function peekConsumedLedger(root: string): Set<string> | null {
965
+ const raw = readLedgerText(root);
966
+ if (raw === null) return null;
967
+ const pending = pendingPlacementIds(root);
968
+ return parseConsumedLedger(raw, Date.now() - CONSUMED_LEDGER_RETENTION_MS, pending.ids, pending.retainAll).ids;
969
+ }
970
+
971
+ /**
972
+ * Does this maildir record carry the envelope messageId? Counts both the
973
+ * persisted `envelopeId` and, for legacy records, a body that is itself a
974
+ * signed envelope.
975
+ */
976
+ function recordCarriesMessageId(msg: { envelopeId?: unknown; body?: unknown }, messageId: string): boolean {
977
+ if (msg.envelopeId !== undefined) {
978
+ if (!isValidEnvelopeId(msg.envelopeId)) throw new Error("consumed record has an invalid envelope ID");
979
+ return msg.envelopeId === messageId;
980
+ }
981
+ if (typeof msg.body !== "string") throw new Error("consumed record has no envelope ID");
982
+ const parsed = tryParseEnvelope(msg.body);
983
+ if (parsed === "json-parse-error" || parsed === "missing-fields" || !isValidEnvelopeId(parsed.messageId)) {
984
+ throw new Error("consumed record has no recoverable envelope ID");
985
+ }
986
+ return parsed.messageId === messageId;
987
+ }
988
+
989
+ /**
990
+ * Has this envelope messageId already been consumed?
991
+ *
992
+ * The durable ledger is the authority (it survives maildir GC). The maildir
993
+ * scan (cur/ + archive/, recursively) is kept as a MIGRATION fallback for
994
+ * records consumed before this ledger existed — or by an older build — so an
995
+ * upgrade does not open a window for records already on disk. Counts both the
996
+ * persisted `envelopeId` and, for legacy records, a body that is itself a
997
+ * signed envelope. This is the gate on replay of consumed history.
998
+ *
999
+ * It reads the ledger through readConsumedLedger, which may rewrite the ledger:
1000
+ * call it only while holding the mailbox lock.
1001
+ */
1002
+ function isConsumedMessageId(root: string, messageId: string, pendingFile?: string): boolean {
1003
+ if (readConsumedLedger(root).has(messageId)) return true;
1004
+
1005
+ return maildirHistoryHasMessageId(root, messageId, pendingFile === undefined ? undefined : join(root, "cur", pendingFile));
1006
+ }
1007
+
1008
+ function maildirHistoryHasMessageId(root: string, messageId: string, pendingPath?: string): boolean {
1009
+ const stack = [join(root, "cur"), join(root, "archive")];
1010
+ for (let dir = stack.pop(); dir !== undefined; dir = stack.pop()) {
1011
+ let entries: Dirent[];
1012
+ try {
1013
+ entries = readdirSync(dir, { withFileTypes: true });
1014
+ } catch (err) {
1015
+ if (isMissing(err)) continue;
1016
+ throw unreadableHistory(dir, err);
1017
+ }
1018
+ for (const entry of entries) {
1019
+ const full = join(dir, entry.name);
1020
+ if (full === pendingPath) continue;
1021
+ if (entry.isDirectory()) {
1022
+ stack.push(full);
1023
+ continue;
1024
+ }
1025
+ if (!entry.name.endsWith(".json")) continue;
1026
+ let raw: string;
1027
+ try {
1028
+ raw = readFileSync(full, "utf-8");
1029
+ } catch (err) {
1030
+ if (isMissing(err)) continue; // removed after the listing
1031
+ throw unreadableHistory(full, err);
1032
+ }
1033
+ let record;
1034
+ try { record = JSON.parse(raw); } catch { throw new Error(`consumed history at ${full} is corrupt`); }
1035
+ if (record == null || typeof record !== "object") throw new Error(`consumed history at ${full} is corrupt`);
1036
+ if (recordCarriesMessageId(record, messageId)) return true;
1037
+ }
1038
+ }
1039
+ return false;
1040
+ }
1041
+
1042
+ /**
1043
+ * Replay lookup for a reader that does not hold the mailbox lock: true when
1044
+ * this envelope messageId is in the consumed ledger or, failing that, in the
1045
+ * maildir fallback — the history isConsumedMessageId consults. It writes,
1046
+ * renames, prunes and creates nothing. Unavailable history throws; the caller
1047
+ * must withhold the record.
1048
+ */
1049
+ export function peekConsumedForMailboxRoot(root: string, messageId: string): boolean {
1050
+ if (peekConsumedLedger(root)?.has(messageId)) return true;
1051
+ return maildirHistoryHasMessageId(root, messageId);
1052
+ }
1053
+
1054
+ function readLedgerText(root: string): string | null {
1055
+ const path = consumedLedgerPath(root);
1056
+ try { return readFileSync(path, "utf-8"); } catch (err) {
1057
+ if (!isMissing(err)) throw unreadableHistory(path, err);
1058
+ try { readFileSync(join(root, ".consumed-initialized")); } catch (markerErr) {
1059
+ if (isMissing(markerErr)) return null;
1060
+ throw unreadableHistory(path, markerErr);
1061
+ }
1062
+ throw new Error(`consumed history at ${path} is missing after initialization`);
1063
+ }
1064
+ }
1065
+
1066
+ export function hasCommittedMessageId(root: string, messageId: string): boolean {
1067
+ const ids = peekConsumedLedger(root);
1068
+ if (ids === null) return false;
1069
+ return ids.has(messageId);
1070
+ }
1071
+
1072
+ // ─── First delivery into cur/ (cli#482) ──────────────────────────────────────
1073
+ //
1074
+ /** The result of a first-delivery placement. */
1075
+ export type FirstDelivery = { status: "placed" } | { status: "exists" };
1076
+
1077
+ export function placeCurRecord(sourcePath: string, curPath: string): FirstDelivery {
1078
+ try {
1079
+ linkSync(sourcePath, curPath);
1080
+ return { status: "placed" };
1081
+ } catch (err) {
1082
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
1083
+ return { status: "exists" };
1084
+ }
1085
+ }