@sema-agent/core 7.63.0 → 7.65.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 (239) hide show
  1. package/CHANGELOG.md +725 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent.js +25 -5
  23. package/dist/core/allow-entry.d.ts +4 -0
  24. package/dist/core/ask-origin.d.ts +1 -1
  25. package/dist/core/ask-origin.js +2 -2
  26. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  27. package/dist/core/ask-unresolvable-notice.js +10 -3
  28. package/dist/core/auto-compaction.d.ts +7 -5
  29. package/dist/core/auto-promote.d.ts +3 -2
  30. package/dist/core/background-agent-store.d.ts +14 -0
  31. package/dist/core/background-agent-store.js +3 -0
  32. package/dist/core/checkpoint-queries.d.ts +9 -6
  33. package/dist/core/checkpoint-queries.js +8 -3
  34. package/dist/core/checkpoint-store.d.ts +7 -4
  35. package/dist/core/context-settings.d.ts +39 -9
  36. package/dist/core/context-settings.js +32 -10
  37. package/dist/core/engine-attestation.d.ts +26 -6
  38. package/dist/core/engine-attestation.js +5 -1
  39. package/dist/core/engine-notice.d.ts +37 -2
  40. package/dist/core/engine-notice.js +3 -1
  41. package/dist/core/extension-requester.d.ts +9 -0
  42. package/dist/core/extension-requester.js +7 -0
  43. package/dist/core/file-history-store.d.ts +30 -2
  44. package/dist/core/file-history-store.js +48 -9
  45. package/dist/core/fs-write-gate-policy.js +1 -1
  46. package/dist/core/gate-fold.js +5 -1
  47. package/dist/core/gate-lanes.js +2 -0
  48. package/dist/core/gate-outcome.d.ts +39 -2
  49. package/dist/core/gate-outcome.js +20 -1
  50. package/dist/core/governance-codes.d.ts +8 -4
  51. package/dist/core/governance-codes.js +8 -3
  52. package/dist/core/leg-identity.d.ts +35 -1
  53. package/dist/core/leg-identity.js +10 -0
  54. package/dist/core/mailbox-store.d.ts +39 -4
  55. package/dist/core/mailbox-store.js +14 -2
  56. package/dist/core/memory-engine/consolidation.d.ts +13 -6
  57. package/dist/core/memory-engine/consolidation.js +26 -0
  58. package/dist/core/memory-engine/control-objects.d.ts +58 -0
  59. package/dist/core/memory-engine/control-objects.js +273 -0
  60. package/dist/core/memory-engine/control-plane-adoption.d.ts +51 -0
  61. package/dist/core/memory-engine/control-plane-adoption.js +161 -0
  62. package/dist/core/memory-engine/delegation-settlement.d.ts +73 -40
  63. package/dist/core/memory-engine/delegation-settlement.js +271 -107
  64. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  65. package/dist/core/memory-engine/dual-root.js +7 -3
  66. package/dist/core/memory-engine/engine.d.ts +54 -33
  67. package/dist/core/memory-engine/engine.js +150 -157
  68. package/dist/core/memory-engine/file-backend.d.ts +58 -76
  69. package/dist/core/memory-engine/file-backend.js +111 -268
  70. package/dist/core/memory-engine/index.d.ts +3 -2
  71. package/dist/core/memory-engine/index.js +2 -1
  72. package/dist/core/memory-engine/layout.d.ts +135 -50
  73. package/dist/core/memory-engine/layout.js +214 -89
  74. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  75. package/dist/core/memory-engine/memory-age.js +17 -0
  76. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  77. package/dist/core/memory-engine/memory-backend-contract.js +159 -2
  78. package/dist/core/memory-engine/memory-deployment.d.ts +12 -4
  79. package/dist/core/memory-engine/memory-deployment.js +31 -6
  80. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  81. package/dist/core/memory-engine/origin-clearance.js +64 -9
  82. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  83. package/dist/core/memory-engine/session-write-home.js +37 -10
  84. package/dist/core/memory-engine/tools.d.ts +2 -2
  85. package/dist/core/memory-engine/tools.js +7 -7
  86. package/dist/core/memory-engine/types.d.ts +55 -12
  87. package/dist/core/memory-engine/types.js +2 -1
  88. package/dist/core/memory-vector.d.ts +6 -14
  89. package/dist/core/memory.d.ts +0 -462
  90. package/dist/core/memory.js +0 -333
  91. package/dist/core/mode-policy.js +3 -3
  92. package/dist/core/mods/agent-stations.d.ts +18 -0
  93. package/dist/core/mods/agent-stations.js +8 -6
  94. package/dist/core/mods/extension-call.d.ts +4 -0
  95. package/dist/core/mods/extension-call.js +8 -0
  96. package/dist/core/mods/tool-call.js +3 -4
  97. package/dist/core/parent-spec-seat.d.ts +2 -2
  98. package/dist/core/peer-channel.d.ts +5 -0
  99. package/dist/core/permission-rule-consent.d.ts +64 -22
  100. package/dist/core/permission-rule-consent.js +106 -58
  101. package/dist/core/permission-rule-store.d.ts +56 -21
  102. package/dist/core/permission-rule-store.js +2 -0
  103. package/dist/core/refusal-echo.d.ts +20 -0
  104. package/dist/core/refusal-echo.js +33 -0
  105. package/dist/core/retention.d.ts +175 -10
  106. package/dist/core/retention.js +44 -0
  107. package/dist/core/retired-keys.d.ts +5 -0
  108. package/dist/core/retired-keys.js +3 -0
  109. package/dist/core/rule-offer-read.d.ts +0 -4
  110. package/dist/core/rule-offer-read.js +2 -18
  111. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  112. package/dist/core/runner/classifier-ladder.js +4 -2
  113. package/dist/core/runner/compact-session.js +10 -7
  114. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  115. package/dist/core/runner/compaction-call-options.js +3 -2
  116. package/dist/core/runner/contracts.d.ts +28 -9
  117. package/dist/core/runner/delegation-owner.d.ts +2 -3
  118. package/dist/core/runner/delegation-owner.js +2 -1
  119. package/dist/core/runner/gate-exit.d.ts +6 -0
  120. package/dist/core/runner/gate-exit.js +11 -2
  121. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  122. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  123. package/dist/core/runner/prepare-ask-lane.js +3 -3
  124. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  125. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  126. package/dist/core/runner/prepare-config-doors.js +4 -0
  127. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  128. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  129. package/dist/core/runner/prepare-gate-stations.d.ts +8 -0
  130. package/dist/core/runner/prepare-gate-stations.js +15 -7
  131. package/dist/core/runner/prepare-hands-readface.js +1 -1
  132. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  133. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  134. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  135. package/dist/core/runner/prepare-memory.d.ts +4 -0
  136. package/dist/core/runner/prepare-memory.js +22 -28
  137. package/dist/core/runner/prepare-policy-chain.js +18 -10
  138. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  139. package/dist/core/runner/prepare-task.d.ts +5 -1
  140. package/dist/core/runner/prepare-task.js +16 -11
  141. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  142. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  143. package/dist/core/runner/resume-admission.d.ts +2 -2
  144. package/dist/core/runner/resume-admission.js +2 -23
  145. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  146. package/dist/core/runner/role-resolution-table.js +62 -0
  147. package/dist/core/runner/run-compaction-machinery.js +2 -2
  148. package/dist/core/runner/run-identity-wiring.js +12 -9
  149. package/dist/core/runner/run-leg.js +8 -4
  150. package/dist/core/runner/run-notification-lane.js +23 -23
  151. package/dist/core/runner/run-recovery-lanes.js +3 -3
  152. package/dist/core/runner/run-terminal-adoption.js +1 -1
  153. package/dist/core/runner/run-turn-boundary.js +14 -15
  154. package/dist/core/runner/runtask.js +1 -1
  155. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  156. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  157. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  158. package/dist/core/runner/tool-occurrence.js +2 -2
  159. package/dist/core/runner-deps.d.ts +1 -1
  160. package/dist/core/secret-env.d.ts +2 -2
  161. package/dist/core/secret-env.js +6 -20
  162. package/dist/core/session-checkout.d.ts +63 -3
  163. package/dist/core/session-checkout.js +152 -58
  164. package/dist/core/session-store.d.ts +6 -6
  165. package/dist/core/session-store.js +3 -3
  166. package/dist/core/shell-read-silence.js +8 -0
  167. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  168. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  169. package/dist/core/task-event.d.ts +9 -5
  170. package/dist/core/task-notification.d.ts +137 -31
  171. package/dist/core/task-notification.js +198 -100
  172. package/dist/core/task-registry-agent.d.ts +11 -0
  173. package/dist/core/task-registry-agent.js +12 -3
  174. package/dist/core/task-registry-shared.d.ts +11 -0
  175. package/dist/core/task-registry.d.ts +18 -0
  176. package/dist/core/task-registry.js +27 -8
  177. package/dist/core/task-spec.d.ts +7 -2
  178. package/dist/core/tool-errors.d.ts +17 -9
  179. package/dist/core/tool-errors.js +1 -1
  180. package/dist/core/tool-policy.d.ts +18 -1
  181. package/dist/core/tool-policy.js +16 -7
  182. package/dist/core/tool-result-store.d.ts +20 -0
  183. package/dist/core/tool-spec.d.ts +10 -6
  184. package/dist/core/trace.d.ts +3 -2
  185. package/dist/core/workflow-journal-store.d.ts +11 -0
  186. package/dist/core/workflow-journal-store.js +7 -0
  187. package/dist/core/workflow-run-store.d.ts +9 -0
  188. package/dist/core/workflow-run-store.js +6 -0
  189. package/dist/core/write-protect.d.ts +16 -0
  190. package/dist/core/write-protect.js +10 -0
  191. package/dist/engine/compaction/compaction.d.ts +2 -1
  192. package/dist/engine/harness/types.d.ts +1 -0
  193. package/dist/engine/session/repo-utils.d.ts +14 -4
  194. package/dist/engine/session/repo-utils.js +5 -4
  195. package/dist/engine/session/session.d.ts +7 -1
  196. package/dist/engine/session/session.js +5 -2
  197. package/dist/index.d.ts +13 -11
  198. package/dist/index.js +13 -11
  199. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  200. package/dist/orchestration/run-workflow-tool.js +7 -0
  201. package/dist/orchestration/workflow-types.d.ts +2 -1
  202. package/dist/orchestration/workflow.d.ts +3 -0
  203. package/dist/orchestration/workflow.js +2 -1
  204. package/dist/prompts/default.d.ts +1 -2
  205. package/dist/scenarios/full-body.d.ts +1 -1
  206. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  207. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  208. package/dist/stores/file/checkpoint-store.js +4 -1
  209. package/dist/stores/file/file-history-store.d.ts +13 -0
  210. package/dist/stores/file/file-history-store.js +75 -13
  211. package/dist/stores/file/index.d.ts +12 -16
  212. package/dist/stores/file/index.js +7 -25
  213. package/dist/stores/file/permission-rule-store.d.ts +34 -0
  214. package/dist/stores/file/permission-rule-store.js +104 -9
  215. package/dist/stores/file/session-store.js +1 -1
  216. package/dist/stores/file/tool-result-store.d.ts +14 -0
  217. package/dist/stores/file/tool-result-store.js +39 -2
  218. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  219. package/dist/stores/file/workflow-journal-store.js +17 -0
  220. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  221. package/dist/stores/file/workflow-run-store.js +15 -0
  222. package/dist/tools/fs/read-deny.d.ts +15 -2
  223. package/dist/tools/fs/read-deny.js +10 -2
  224. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  225. package/dist/tools/fs/shell-read-check.js +7 -7
  226. package/package.json +2 -2
  227. package/test/export-surface.snapshot.json +71 -73
  228. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  229. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  230. package/wire-changes/core@7.64.0.json +2653 -0
  231. package/wire-changes/core@7.65.0.json +1650 -0
  232. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  233. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  234. package/wire-changes/primitives@7.64.0.json +30 -0
  235. package/wire-changes/primitives@7.65.0.json +337 -0
  236. package/dist/core/memory-recall.d.ts +0 -208
  237. package/dist/core/memory-recall.js +0 -136
  238. package/dist/stores/file/memory-store.d.ts +0 -124
  239. package/dist/stores/file/memory-store.js +0 -353
@@ -99,9 +99,22 @@ export interface MailboxPeerMeta {
99
99
  * ahead of the non-urgent ones of the same pass and counts it on the inbox notice; it never changes
100
100
  * WHEN the recipient reads (the recipient's setting decides that, never the sender). */
101
101
  urgent?: boolean;
102
+ /**
103
+ * WHO the record is for: the occupant (`SessionMetadata.incarnation`) of the session the writer addressed, as the writer
104
+ * resolved that address — a park seat from its leg's address, a sender from the recipient's directory row, a notice from the
105
+ * reply address it answers. A session box outlives its occupant (the id can be deleted and created again, the box stays), so a
106
+ * drain hands a record only to the occupant it names ({@link import("../engine/session/repo-utils.js").sameOccupant}: absent on
107
+ * both sides is one occupant — a deployment whose store mints no tokens; absent on one side only is another occupant). A
108
+ * record for another occupant is discarded with an account, never delivered. An addressing fact, not a secret and not a
109
+ * credential: it proves nothing about who wrote the record.
110
+ */
111
+ occupant?: string;
112
+ /** The occupant of the SENDING session, beside `fromSession`: what a notice answering this record (a receipt, an idle notice)
113
+ * is addressed to ({@link occupant} of that notice). Absent = the sender stated none. */
114
+ fromOccupant?: string;
102
115
  }
103
116
  /** design/385 — the typed body of a notice-kind record. `state` is drawn from the receipt states on a
104
- * `delivery_notice` (`held|denied|expired|delivered|refused|dropped`) and from the idle kinds on an
117
+ * `delivery_notice` (`held|denied|expired|delivered|refused|dropped|held_by_policy`) and from the idle kinds on an
105
118
  * `idle_notice` (`idle|exited|unavailable|expired`); the validator admits the union, the drain checks
106
119
  * the pairing (a state that does not fit its kind is settled `notice_unrouted`, never rendered). */
107
120
  export interface MailboxPeerNoticeMeta {
@@ -142,8 +155,9 @@ export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_
142
155
  export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
143
156
  /** The `notice.state` vocabulary the validator admits (the union of both notice families; the drain
144
157
  * checks the kind↔state pairing). Spelled here, beside the record kinds, so the store contract is
145
- * self-contained — the lane's own closed sets re-derive from these. */
146
- export declare const MAILBOX_PEER_NOTICE_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"];
158
+ * self-contained — the lane's two closed sets (`PEER_DELIVERY_RECEIPT_STATES`, `PEER_IDLE_NOTICE_KINDS`)
159
+ * are spelled beside their renderers and together equal this one (a pin holds the two spellings together). */
160
+ export declare const MAILBOX_PEER_NOTICE_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable", "held_by_policy"];
147
161
  export type MailboxPeerNoticeState = (typeof MAILBOX_PEER_NOTICE_STATES)[number];
148
162
  /** The `append` refusal code for a malformed `peerMeta` (design/385): a garbage record is refused up
149
163
  * front with this code, never silently stripped or stored — a drain that reads a half-typed record
@@ -383,7 +397,15 @@ export interface MailboxStore {
383
397
  releaseLease(scope: string, handle: string, owner: string): Promise<void>;
384
398
  /** Observation face (the "N pending" receipt figure) — count of currently-visible messages. */
385
399
  peekCount(scope: string, handle: string): Promise<number>;
386
- /** Drop the WHOLE mailbox for (scope, handle) — the row-deletion companion (F-13). */
400
+ /**
401
+ * Drop the WHOLE mailbox for (scope, handle) — the row-deletion companion (F-13).
402
+ *
403
+ * @contract mailbox.session_box_outlives_its_occupant — deleting a session's row does not remove its box
404
+ * `(scope, session.<id>)`: a deployment's deletion cascade clears it with this verb (retention is the deployment's). What
405
+ * stays behind is never delivered to another occupant: every session-box record names the occupant it is for
406
+ * ({@link MailboxPeerMeta.occupant}), and a drain hands a record only to that occupant — a record for an earlier occupant
407
+ * of the id is discarded with an account (`delegation.delivery_discarded`) by the next occupant's drain.
408
+ */
387
409
  drop(scope: string, handle: string): Promise<void>;
388
410
  /** Age out mailboxes whose newest message BY `sentAt` (not by array/insertion order — RB-250②)
389
411
  * is older than maxAgeMs. Returns mailboxes dropped. */
@@ -444,6 +466,19 @@ export type MailboxCrossProcessVerdict = {
444
466
  * value of the wrong type (a malformed declaration is refused, not read as "probably fine").
445
467
  */
446
468
  export declare function mailboxCrossProcessMountVerdict(store: MailboxStore): MailboxCrossProcessVerdict;
469
+ /**
470
+ * THE mount verdict of the SESSION-BOX lane — a session's own `session.<id>` box, the drain that consumes it and every seat that
471
+ * appends to it: the mailbox's cross-process declaration ({@link mailboxCrossProcessMountVerdict}) AND a session store that reads a
472
+ * session's row by id (`SessionStore.headOf`). A box outlives its session's occupant (the id can be deleted and created again), and
473
+ * a drain discards a record addressed to another occupant only after it has read, by id, that its run's session still holds the
474
+ * occupant it acquired; over a store that cannot be read by id every such record is undecidable and the box would jam, so the lane
475
+ * does not mount, and the reason names the missing read. One judgment, read by the drain mount, the peer-lane mount and the send
476
+ * face, so where a record is parked and where it is drained cannot disagree. `sessions` absent = no session store at all: the same
477
+ * refusal.
478
+ */
479
+ export declare function sessionBoxMountVerdict(mailbox: MailboxStore, sessions: {
480
+ readonly headOf?: unknown;
481
+ } | undefined): MailboxCrossProcessVerdict;
447
482
  /** RB-250② (2026-07-28) class fix — the box age for `reap` is the MAX `sentAt`, not the
448
483
  * last array element: `sentAt` is caller-supplied, so append order need not be time order, and taking
449
484
  * the tail let a box whose freshest message was mid-array be swept — both bundled backends discarded
@@ -52,10 +52,10 @@ export function assertMailboxDecisionMove(seq, expect, next) {
52
52
  }
53
53
  export const MAILBOX_PEER_FROM_MODES = Object.freeze(["bypass", "prompting"]);
54
54
  export const MAILBOX_PEER_RECORD_KINDS = Object.freeze(["peer_message", "idle_notice", "delivery_notice", "idle_subscription", "engine_frame"]);
55
- export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"]);
55
+ export const MAILBOX_PEER_NOTICE_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable", "held_by_policy"]);
56
56
  export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
57
57
  export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
58
- const PEER_META_STRING_KEYS = ["fromSession", "fromRoot", "senderKey", "fromScope", "gateReceiptId"];
58
+ const PEER_META_STRING_KEYS = ["fromSession", "fromRoot", "senderKey", "fromScope", "gateReceiptId", "occupant", "fromOccupant"];
59
59
  export function readMailboxPeerMeta(raw) {
60
60
  if (raw === undefined)
61
61
  return undefined;
@@ -228,6 +228,18 @@ export function mailboxCrossProcessMountVerdict(store) {
228
228
  : `the mailbox backend's crossProcessSafe declaration is malformed (${typeof declared}, expected a boolean)`;
229
229
  return { ok: false, code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE, reason };
230
230
  }
231
+ export function sessionBoxMountVerdict(mailbox, sessions) {
232
+ const store = mailboxCrossProcessMountVerdict(mailbox);
233
+ if (!store.ok)
234
+ return store;
235
+ if (typeof sessions?.headOf === "function")
236
+ return { ok: true };
237
+ return {
238
+ ok: false,
239
+ code: MAILBOX_CROSS_PROCESS_UNSAFE_CODE,
240
+ reason: "the session store has no by-id read (SessionStore.headOf): a session box outlives its session's occupant, and without that read a drain cannot confirm that its run's session still holds the occupant it acquired before it discards a record addressed to another, so a box shared across runs would hand one occupant's records to another on luck",
241
+ };
242
+ }
231
243
  export function newestSentAt(messages) {
232
244
  let newest;
233
245
  for (const m of messages) {
@@ -8,7 +8,7 @@
8
8
  * they land) — a second implementation would be a drift seam, exactly the class the challenge
9
9
  * exclusion view closed.
10
10
  */
11
- import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryGovernanceStore, NotePatch } from "./types.js";
11
+ import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryGovernanceObjects, MemoryGovernanceStore, NotePatch } from "./types.js";
12
12
  import type { ConsolidationDriverRunRow } from "./consolidation-driver.js";
13
13
  /**
14
14
  * Derive the SUPERSEDED set from a committed header listing: superseded entry id → the standing
@@ -547,9 +547,9 @@ export type MemoryGovernanceDurability = "backend" | "replica-local";
547
547
  * `"backend"` ⇔ the backend publishes its own control plane (`controlPlaneRoot`, a non-empty string — the File backend:
548
548
  * every control-plane record, the consolidation store and the governance ledgers alike, sits in its directory). A
549
549
  * backend that carries `MemoryBackend.governance` but no control plane still answers `"replica-local"`: the
550
- * consolidation state and the governance documents (lineage, challenges, settlements, session accounts and the
551
- * announcement queue a consolidation writes) ride its store, but the instruction holds (each beside its captured bytes)
552
- * are still kept in the replica's control plane, and the answer changes only when they ride the store too. Eligibility also reads the capture opt-out records
550
+ * consolidation state, the governance documents (lineage, challenges, settlements, session accounts and the
551
+ * announcement queue a consolidation writes) and the instruction holds with their captured bytes (#3485) ride its
552
+ * store, and the answer stays `"replica-local"` there: eligibility also reads the capture opt-out records
553
553
  * (`MemoryEngineOptions.captureRecordStore`: a carrier the host injects is its declaration of a store every replica
554
554
  * reads; the default is a file in the engine's control plane — the store's own directory on the File backend): an
555
555
  * answer that turns `"backend"` for a backend without a control plane must hold for the default carrier as well.
@@ -557,11 +557,18 @@ export type MemoryGovernanceDurability = "backend" | "replica-local";
557
557
  export declare function memoryGovernanceDurability(backend: MemoryBackend): MemoryGovernanceDurability;
558
558
  /** The control plane a File governance store keeps its documents in; `undefined` for any other store. */
559
559
  export declare function fileGovernanceStoreDir(store: MemoryGovernanceStore): string | undefined;
560
+ /** A store's control objects as a reader that must see damage rather than be spared it reads them — an erasure's count,
561
+ * an export's roster: for a File store the listing names every entry standing in the kind's directory
562
+ * (`standingFileControlObjectNames`) — a subdirectory, a dangling link, a name no writer could have used — so the verbs
563
+ * that meet it refuse it by name and the reader counts it; any other store's listing is its own (KL-3466-c). The other
564
+ * verbs are the store's. */
565
+ export declare function standingControlObjectsOf(store: MemoryGovernanceStore): MemoryGovernanceObjects;
560
566
  /**
561
567
  * The consolidation state's File store over one control plane — the gate file, the plan workbook, the intent
562
568
  * credentials, the run account and the mint archive exactly as they have always been laid out (same names, same
563
- * bytes, same locks). The File backend carries it over its own control plane; an engine whose backend carries no
564
- * store keeps its state with this over the replica's control plane.
569
+ * bytes, same locks), each governance document in its own file ({@link fileGovernanceDocOf}) and each control object
570
+ * in its kind's directory (`control-objects.ts`). The File backend carries it over its own control plane; an engine
571
+ * whose backend carries no store keeps its state with this over the replica's control plane.
565
572
  */
566
573
  export declare function fileGovernanceStore(controlDir: string): MemoryGovernanceStore;
567
574
  /** Derive a product's slug from its proposed name (memory filename charset; collisions are the
@@ -2,6 +2,7 @@ import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:
2
2
  import { join } from "node:path";
3
3
  import { uuidv7 } from "../../engine/session/uuid.js";
4
4
  import { atomicWriteFileSync, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
5
+ import { deleteFileControlObject, getFileControlObject, listFileControlObjects, moveFileControlObject, putFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
5
6
  import { thrownText } from "../thrown-value.js";
6
7
  import { optionKeys, receiveMembers } from "../own-property-receipt.js";
7
8
  export function deriveSupersededSet(headers, opts = {}) {
@@ -407,6 +408,16 @@ const FILE_GOVERNANCE_DIRS = new WeakMap();
407
408
  export function fileGovernanceStoreDir(store) {
408
409
  return FILE_GOVERNANCE_DIRS.get(store);
409
410
  }
411
+ export function standingControlObjectsOf(store) {
412
+ const dir = fileGovernanceStoreDir(store);
413
+ return {
414
+ putObject: (kind, name, bytes, meta) => store.putObject(kind, name, bytes, meta),
415
+ getObject: (kind, name) => store.getObject(kind, name),
416
+ listObjects: dir === undefined ? (kind) => store.listObjects(kind) : async (kind) => standingFileControlObjectNames(dir, kind),
417
+ moveObject: (from, to) => store.moveObject(from, to),
418
+ deleteObject: (kind, name) => store.deleteObject(kind, name),
419
+ };
420
+ }
410
421
  function isMintArchive(value) {
411
422
  return typeof value === "object" && value !== null && Reflect.get(value, "kind") === "llm-consolidation-plan";
412
423
  }
@@ -514,6 +525,21 @@ export function fileGovernanceStore(controlDir) {
514
525
  rmSync(path, { force: true });
515
526
  return true;
516
527
  },
528
+ async putObject(kind, name, bytes) {
529
+ return putFileControlObject(controlDir, kind, name, bytes);
530
+ },
531
+ async getObject(kind, name) {
532
+ return getFileControlObject(controlDir, kind, name);
533
+ },
534
+ async listObjects(kind) {
535
+ return listFileControlObjects(controlDir, kind);
536
+ },
537
+ async moveObject(from, to) {
538
+ return moveFileControlObject(controlDir, from, to);
539
+ },
540
+ async deleteObject(kind, name) {
541
+ return deleteFileControlObject(controlDir, kind, name);
542
+ },
517
543
  });
518
544
  FILE_GOVERNANCE_DIRS.set(store, controlDir);
519
545
  return store;
@@ -0,0 +1,58 @@
1
+ import { type MemoryControlObjectKind } from "./types.js";
2
+ import { type QuarantineCapture } from "./layout.js";
3
+ /** Where a File store stages an object's bytes before publishing them under the object's name. Never a kind's
4
+ * directory: a listing of a kind answers published names only. */
5
+ export declare const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
6
+ /** A control-object kind's directory under a File store's control plane. A kind outside
7
+ * {@link MEMORY_CONTROL_OBJECT_KINDS} is refused (`memory.control_object_unknown`) — never given a directory of its own. */
8
+ export declare function fileControlObjectDirOf(kind: MemoryControlObjectKind): string;
9
+ /** A name a store keeps an object under: one opaque, non-empty segment of at most 255 UTF-8 bytes — never `.` / `..`, never a
10
+ * separator or a NUL. */
11
+ export declare function isControlObjectName(name: unknown): name is string;
12
+ /** The filesystem code behind a File control-object refusal: the refusal's own `code` when it is the filesystem's, else
13
+ * the code of the filesystem error it was raised over (`cause`) — `undefined` when neither names one. */
14
+ export declare function fileControlObjectFaultCode(err: unknown): string | undefined;
15
+ /**
16
+ * The open judge of a File governance store over `controlDir` (#3512): the store publishes every object with `link`
17
+ * ({@link putFileControlObject}, {@link moveFileControlObject}), so on a file system that cannot make a hard link every
18
+ * object write would fail — and a containment whose copy fails still takes the suspect off the plane (its copy is
19
+ * lost, not kept). One link is tried, at the open, between two files at the control plane's top level (named with
20
+ * `LINK_PROBE_PREFIX`), and both are removed; a link the file system refuses is refused here
21
+ * (`memory.control_plane_links_unsupported`, `controlPlaneLinksRefusal`, `detail.path` = `controlDir`). Not judged — the
22
+ * open proceeds as before — when the first file cannot be created (a control plane that is read-only, full or not
23
+ * writable: what was not tried is not claimed) or when the link's name already stands. Asked at each open, never
24
+ * cached. The callers are the two holders of a File store: the File backend's construction and an engine whose backend
25
+ * carries no store of its own. `controlDir` stands when it is asked.
26
+ */
27
+ export declare function probeControlPlaneLinks(controlDir: string): void;
28
+ /** Write `(kind, name)` once ({@link import("./types.js").MemoryGovernanceStore.putObject}): `"existed"` only when the name already
29
+ * holds these same bytes; a name holding other bytes is refused, never answered as written. */
30
+ export declare function putFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string, bytes: Uint8Array): "created" | "existed";
31
+ /** A control object's bytes ({@link import("./types.js").MemoryGovernanceStore.getObject}). */
32
+ export declare function getFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string): Uint8Array | undefined;
33
+ /** Every name standing in a kind's directory, sorted — the objects and whatever else stands there (a subdirectory, a dangling link,
34
+ * a name no writer could have used). For the readers that must see damage rather than be spared it: the adoption of a replica
35
+ * refuses each such entry by name and withholds the documents behind it, and the strays reader counts them — an entry standing
36
+ * where an object's record belongs is a fact, never an absence. {@link listFileControlObjects} is the store's verb: objects only. */
37
+ export declare function standingFileControlObjectNames(controlDir: string, kind: MemoryControlObjectKind): string[];
38
+ /** Every name of `kind`, sorted ({@link import("./types.js").MemoryGovernanceStore.listObjects}): the regular files under a legal
39
+ * name — the entries {@link getFileControlObject} reads. A subdirectory or a dangling link in a kind's directory is no object and
40
+ * is not named here; the verbs that meet it refuse it, and {@link standingFileControlObjectNames} still names it. */
41
+ export declare function listFileControlObjects(controlDir: string, kind: MemoryControlObjectKind): string[];
42
+ /** Move one object, never overwriting ({@link import("./types.js").MemoryGovernanceStore.moveObject}). */
43
+ export declare function moveFileControlObject(controlDir: string, from: {
44
+ readonly kind: MemoryControlObjectKind;
45
+ readonly name: string;
46
+ }, to: {
47
+ readonly kind: MemoryControlObjectKind;
48
+ readonly name: string;
49
+ }): "moved" | "already-moved";
50
+ /** {@link putFileControlObject} for a writer whose record is the first one under the name — the synchronous twin of
51
+ * `putControlObjectOnce` (`layout.ts`), one law: `"existed"` ⇔ an object stands there that reads back (the same bytes,
52
+ * or other bytes the put refused); a refusal no readable object explains is the put's own and is thrown. */
53
+ export declare function putFileControlObjectOnce(controlDir: string, kind: MemoryControlObjectKind, name: string, bytes: Uint8Array): "created" | "existed";
54
+ /** The File store's capture of one suspect file's copy into its `quarantine` objects — the synchronous twin of
55
+ * `captureIntoQuarantine` (`layout.ts`) for the File backend's own synchronous read paths, under the same names. */
56
+ export declare function captureIntoFileQuarantine(controlDir: string, path: string, content: string, now: () => number): QuarantineCapture;
57
+ /** Delete one object ({@link import("./types.js").MemoryGovernanceStore.deleteObject}). */
58
+ export declare function deleteFileControlObject(controlDir: string, kind: MemoryControlObjectKind, name: string): boolean;
@@ -0,0 +1,273 @@
1
+ import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeSync } from "node:fs";
2
+ import { randomUUID } from "node:crypto";
3
+ import { join } from "node:path";
4
+ import { MEMORY_CONTROL_OBJECT_KINDS } from "./types.js";
5
+ import { ControlPlaneCorruptError, IMPORT_RECEIPTS_DIR, LINK_PROBE_PREFIX, QUARANTINE_DIR, SESSION_CAPTURE_OPTOUT_DIR, SESSION_POLLUTION_DIR, controlPlaneLinksRefusal, ensureDirExists, quarantineCaptureBase, quarantineCaptureName } from "./layout.js";
6
+ import { thrownText } from "../thrown-value.js";
7
+ const FILE_CONTROL_OBJECT_DIRS = Object.freeze({
8
+ pollution: SESSION_POLLUTION_DIR,
9
+ "import-receipt": IMPORT_RECEIPTS_DIR,
10
+ quarantine: QUARANTINE_DIR,
11
+ hold: "hold",
12
+ "clearance-custody": "origin-clearance-custody",
13
+ capture: SESSION_CAPTURE_OPTOUT_DIR,
14
+ });
15
+ export const CONTROL_OBJECT_STAGE_DIR = ".control-object-stage";
16
+ function unknownObject(what) {
17
+ const e = new Error(`memory governance store: ${what} (a control object is one of ${MEMORY_CONTROL_OBJECT_KINDS.join(", ")}, named by one opaque segment)`);
18
+ e.code = "memory.control_object_unknown";
19
+ return e;
20
+ }
21
+ export function fileControlObjectDirOf(kind) {
22
+ if (typeof kind !== "string" || !Object.prototype.hasOwnProperty.call(FILE_CONTROL_OBJECT_DIRS, kind))
23
+ throw unknownObject(`${JSON.stringify(String(kind))} is not a control-object kind`);
24
+ return FILE_CONTROL_OBJECT_DIRS[kind];
25
+ }
26
+ const CONTROL_OBJECT_NAME_MAX_BYTES = 255;
27
+ export function isControlObjectName(name) {
28
+ return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name) && Buffer.byteLength(name, "utf8") <= CONTROL_OBJECT_NAME_MAX_BYTES;
29
+ }
30
+ function objectPath(controlDir, kind, name) {
31
+ const dir = fileControlObjectDirOf(kind);
32
+ if (!isControlObjectName(name))
33
+ throw unknownObject(`${JSON.stringify(String(name))} is not a control-object name`);
34
+ return join(controlDir, dir, name);
35
+ }
36
+ function errnoOf(err) {
37
+ return typeof err === "object" && err !== null ? Reflect.get(err, "code") : undefined;
38
+ }
39
+ export function fileControlObjectFaultCode(err) {
40
+ if (err instanceof ControlPlaneCorruptError)
41
+ return errnoOf(err.cause);
42
+ return errnoOf(err);
43
+ }
44
+ function unprobeable(path, err) {
45
+ return new ControlPlaneCorruptError(`memory control object at ${path} could not be probed (${errnoOf(err) ?? "io error"}) — whether it stands is unknown (fail-closed)`, { cause: err });
46
+ }
47
+ function entryAt(path) {
48
+ let found;
49
+ try {
50
+ found = lstatSync(path);
51
+ }
52
+ catch (err) {
53
+ if (errnoOf(err) === "ENOENT")
54
+ return "absent";
55
+ throw unprobeable(path, err);
56
+ }
57
+ if (found.isFile())
58
+ return "object";
59
+ if (!found.isSymbolicLink())
60
+ return "other";
61
+ try {
62
+ return statSync(path).isFile() ? "object" : "other";
63
+ }
64
+ catch (err) {
65
+ const code = errnoOf(err);
66
+ if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
67
+ return "other";
68
+ throw unprobeable(path, err);
69
+ }
70
+ }
71
+ function stands(path) {
72
+ return entryAt(path) !== "absent";
73
+ }
74
+ function notAnObject(kind, name, refusal) {
75
+ return new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but is not a control object (a regular file under a legal name) — ${refusal} (fail-closed)`);
76
+ }
77
+ function otherBytesStand(kind, name) {
78
+ return new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name already stands with different bytes — refusing to overwrite it (fail-closed)`);
79
+ }
80
+ function standingHolds(controlDir, kind, name, bytes) {
81
+ const standing = getFileControlObject(controlDir, kind, name);
82
+ return standing === undefined ? undefined : Buffer.from(standing).equals(bytes);
83
+ }
84
+ export function probeControlPlaneLinks(controlDir) {
85
+ const source = join(controlDir, `${LINK_PROBE_PREFIX}${randomUUID()}`);
86
+ const linked = `${source}.link`;
87
+ try {
88
+ closeSync(openSync(source, "wx", 0o600));
89
+ }
90
+ catch {
91
+ return;
92
+ }
93
+ let made = false;
94
+ try {
95
+ linkSync(source, linked);
96
+ made = true;
97
+ }
98
+ catch (err) {
99
+ const fault = errnoOf(err);
100
+ if (fault !== "EEXIST")
101
+ throw controlPlaneLinksRefusal(controlDir, fault);
102
+ }
103
+ finally {
104
+ for (const path of made ? [linked, source] : [source]) {
105
+ try {
106
+ rmSync(path, { force: true });
107
+ }
108
+ catch {
109
+ }
110
+ }
111
+ }
112
+ }
113
+ export function putFileControlObject(controlDir, kind, name, bytes) {
114
+ const path = objectPath(controlDir, kind, name);
115
+ const held = standingHolds(controlDir, kind, name, bytes);
116
+ if (held === true)
117
+ return "existed";
118
+ if (held === false)
119
+ throw otherBytesStand(kind, name);
120
+ ensureDirExists(join(controlDir, fileControlObjectDirOf(kind)));
121
+ const stageDir = join(controlDir, CONTROL_OBJECT_STAGE_DIR);
122
+ ensureDirExists(stageDir);
123
+ const staged = join(stageDir, randomUUID());
124
+ const fd = openSync(staged, "wx", 0o600);
125
+ try {
126
+ let written = 0;
127
+ while (written < bytes.byteLength) {
128
+ const n = writeSync(fd, bytes, written, bytes.byteLength - written);
129
+ if (n <= 0)
130
+ throw new Error(`memory control object ${kind}/${name}: write made no progress (${written}/${bytes.byteLength} bytes)`);
131
+ written += n;
132
+ }
133
+ fsyncSync(fd);
134
+ }
135
+ finally {
136
+ closeSync(fd);
137
+ }
138
+ try {
139
+ linkSync(staged, path);
140
+ return "created";
141
+ }
142
+ catch (err) {
143
+ if (errnoOf(err) === "EEXIST") {
144
+ const held = standingHolds(controlDir, kind, name, bytes);
145
+ if (held === true)
146
+ return "existed";
147
+ if (held === false)
148
+ throw otherBytesStand(kind, name);
149
+ throw new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name stood when the object was published and was gone when its bytes were compared — nothing was written (fail-closed)`);
150
+ }
151
+ throw err;
152
+ }
153
+ finally {
154
+ rmSync(staged, { force: true });
155
+ }
156
+ }
157
+ export function getFileControlObject(controlDir, kind, name) {
158
+ const path = objectPath(controlDir, kind, name);
159
+ const state = entryAt(path);
160
+ if (state === "absent")
161
+ return undefined;
162
+ if (state === "other")
163
+ throw notAnObject(kind, name, "it is never read as missing");
164
+ try {
165
+ return new Uint8Array(readFileSync(path));
166
+ }
167
+ catch (err) {
168
+ if ((errnoOf(err) === "ENOENT" || errnoOf(err) === "ENOTDIR") && !stands(path))
169
+ return undefined;
170
+ throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but cannot be read (${errnoOf(err) ?? "io error"}) — it is never read as missing (fail-closed)`, { cause: err });
171
+ }
172
+ }
173
+ export function standingFileControlObjectNames(controlDir, kind) {
174
+ const dir = join(controlDir, fileControlObjectDirOf(kind));
175
+ try {
176
+ return readdirSync(dir).sort();
177
+ }
178
+ catch (err) {
179
+ if (errnoOf(err) === "ENOENT" && !stands(dir))
180
+ return [];
181
+ throw new ControlPlaneCorruptError(`memory control objects of kind ${kind} could not be enumerated (${errnoOf(err) ?? "io error"}) at ${dir} — an enumeration failure is not an empty kind (fail-closed)`, { cause: err });
182
+ }
183
+ }
184
+ export function listFileControlObjects(controlDir, kind) {
185
+ const dir = join(controlDir, fileControlObjectDirOf(kind));
186
+ return standingFileControlObjectNames(controlDir, kind).filter((name) => isControlObjectName(name) && entryAt(join(dir, name)) === "object");
187
+ }
188
+ function sameBytes(a, b) {
189
+ const sa = statSync(a);
190
+ const sb = statSync(b);
191
+ if (sa.dev === sb.dev && sa.ino === sb.ino)
192
+ return true;
193
+ return readFileSync(a).equals(readFileSync(b));
194
+ }
195
+ export function moveFileControlObject(controlDir, from, to) {
196
+ const src = objectPath(controlDir, from.kind, from.name);
197
+ const dst = objectPath(controlDir, to.kind, to.name);
198
+ const neither = () => new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: neither the source nor the target stands — nothing to move or to resume (fail-closed)`);
199
+ if (src === dst) {
200
+ if (stands(src))
201
+ return "already-moved";
202
+ throw neither();
203
+ }
204
+ ensureDirExists(join(controlDir, fileControlObjectDirOf(to.kind)));
205
+ try {
206
+ linkSync(src, dst);
207
+ }
208
+ catch (err) {
209
+ const code = errnoOf(err);
210
+ if (code === "ENOENT" && !stands(src)) {
211
+ if (stands(dst))
212
+ return "already-moved";
213
+ throw neither();
214
+ }
215
+ if (code !== "EEXIST")
216
+ throw err;
217
+ if (!lstatSync(dst).isFile())
218
+ throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands but is not a file of its own (a link, or no file) — refusing to drop the source onto it (fail-closed)`);
219
+ if (!sameBytes(src, dst))
220
+ throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands with different bytes — refusing to overwrite it (fail-closed)`);
221
+ }
222
+ unlinkSync(src);
223
+ return "moved";
224
+ }
225
+ export function putFileControlObjectOnce(controlDir, kind, name, bytes) {
226
+ try {
227
+ return putFileControlObject(controlDir, kind, name, bytes);
228
+ }
229
+ catch (err) {
230
+ let standing;
231
+ try {
232
+ standing = getFileControlObject(controlDir, kind, name);
233
+ }
234
+ catch {
235
+ throw err;
236
+ }
237
+ if (standing === undefined)
238
+ throw err;
239
+ return "existed";
240
+ }
241
+ }
242
+ export function captureIntoFileQuarantine(controlDir, path, content, now) {
243
+ const bytes = new TextEncoder().encode(content);
244
+ const base = quarantineCaptureBase(path, now);
245
+ try {
246
+ for (let attempt = 0; attempt <= 10; attempt++) {
247
+ const name = quarantineCaptureName(base, attempt);
248
+ if (putFileControlObjectOnce(controlDir, "quarantine", name, bytes) === "created")
249
+ return { name };
250
+ }
251
+ return { failed: "quarantine copy failed: every capture name already stands" };
252
+ }
253
+ catch (err) {
254
+ return { failed: `quarantine copy failed: ${thrownText(err)}` };
255
+ }
256
+ }
257
+ export function deleteFileControlObject(controlDir, kind, name) {
258
+ const path = objectPath(controlDir, kind, name);
259
+ const state = entryAt(path);
260
+ if (state === "absent")
261
+ return false;
262
+ if (state === "other")
263
+ throw notAnObject(kind, name, "refusing to delete it");
264
+ try {
265
+ unlinkSync(path);
266
+ return true;
267
+ }
268
+ catch (err) {
269
+ if ((errnoOf(err) === "ENOENT" || errnoOf(err) === "ENOTDIR") && !stands(path))
270
+ return false;
271
+ throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but could not be deleted (${errnoOf(err) ?? "io error"}) (fail-closed)`, { cause: err });
272
+ }
273
+ }
@@ -0,0 +1,51 @@
1
+ import { type MemoryControlObjectKind, type MemoryGovernanceDocName, type MemoryGovernanceStore } from "./types.js";
2
+ /** The carrier records a replica control plane still holds. */
3
+ export interface ReplicaControlPlaneStrays {
4
+ /** The governance documents with a file (or a journal) in the replica. */
5
+ readonly docs: readonly MemoryGovernanceDocName[];
6
+ /** How many entries stand in each kind's directory of the replica (kinds with none are absent): the control objects, and whatever
7
+ * else stands where an object's record belongs — adoption refuses each of those by name, never skips it. */
8
+ readonly objects: Readonly<Partial<Record<MemoryControlObjectKind, number>>>;
9
+ }
10
+ /** One record adoption handled: a document (`doc:<name>`) or an object (`<kind>/<name>`). */
11
+ export interface AdoptedControlRecord {
12
+ readonly record: string;
13
+ /** What the carrier holds now, never what became of the replica's copy (which stays): `"written"` ⇔ the carrier
14
+ * lacked the record and now holds the same value; `"converged"` ⇔ it already held the same value. */
15
+ readonly outcome: "written" | "converged";
16
+ /** sha-256 of the record as the replica held it: an object's bytes, a document's committed JSON value. */
17
+ readonly digest: string;
18
+ }
19
+ /** {@link adoptReplicaControlPlane}'s answer. */
20
+ export interface ControlPlaneAdoptionReport {
21
+ /** Records the carrier now holds with the replica's value (the replica keeps its copy). */
22
+ readonly adopted: readonly AdoptedControlRecord[];
23
+ /** Records whose adoption did not complete, each with why — a different value already in the carrier, a record that
24
+ * could not be read or verified, or a receipt row that could not be written (then the carrier may already hold the
25
+ * value, and a re-run converges it). */
26
+ readonly refused: readonly {
27
+ readonly record: string;
28
+ readonly reason: string;
29
+ }[];
30
+ }
31
+ /** The replica's body-less record of which of its records the carrier holds with the same value (one row per record and digest). */
32
+ export declare const CONTROL_PLANE_ADOPTION_FILE = "control-plane-adoption.json";
33
+ /** The carrier records `controlDir` holds — documents with a file or journal, objects by kind. An enumeration that
34
+ * fails throws `ControlPlaneCorruptError` (never an empty answer). */
35
+ export declare function replicaControlPlaneStrays(controlDir: string): ReplicaControlPlaneStrays;
36
+ /**
37
+ * Copy the replica control plane's carrier records into `carrier` (see the module note). Answers what the carrier now
38
+ * holds with the replica's value and what was refused; the replica's records are not removed either way. When `carrier`
39
+ * is the File store over `controlDir` itself there is nothing to hand over and the answer is empty. A `controlDir` that does
40
+ * not exist is refused (`ControlPlaneCorruptError`): the call is an operator's, over a path they named, and a wrong path must
41
+ * not read as "nothing to adopt".
42
+ */
43
+ export declare function adoptReplicaControlPlane(controlDir: string, carrier: MemoryGovernanceStore, opts?: {
44
+ readonly now?: () => number;
45
+ }): Promise<ControlPlaneAdoptionReport>;
46
+ /** The replica's adoption receipt: one body-less row per adopted record (what, the digest of its bytes, when). */
47
+ export declare function readControlPlaneAdoptionReceipt(controlDir: string): ReadonlyArray<{
48
+ readonly record: string;
49
+ readonly digest: string;
50
+ readonly at: number;
51
+ }>;