@sema-agent/core 7.62.0 → 7.64.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 (320) hide show
  1. package/CHANGELOG.md +936 -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-transcript-placement.d.ts +23 -0
  23. package/dist/agents/subagent-transcript-placement.js +14 -0
  24. package/dist/agents/subagent.js +102 -54
  25. package/dist/brain/route-adjudicator.js +9 -4
  26. package/dist/core/allow-entry.d.ts +4 -0
  27. package/dist/core/approval-object.js +1 -1
  28. package/dist/core/arg-summary.js +1 -1
  29. package/dist/core/ask-origin.d.ts +1 -1
  30. package/dist/core/ask-origin.js +2 -2
  31. package/dist/core/ask-question.d.ts +2 -2
  32. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  33. package/dist/core/ask-unresolvable-notice.js +10 -3
  34. package/dist/core/auto-compaction.d.ts +7 -5
  35. package/dist/core/background-agent-store.d.ts +7 -0
  36. package/dist/core/background-agent-store.js +3 -0
  37. package/dist/core/canonical-json.d.ts +23 -13
  38. package/dist/core/canonical-json.js +4 -4
  39. package/dist/core/checkpoint-queries.d.ts +50 -4
  40. package/dist/core/checkpoint-queries.js +42 -17
  41. package/dist/core/checkpoint-requirements.d.ts +3 -3
  42. package/dist/core/checkpoint-requirements.js +2 -1
  43. package/dist/core/checkpoint-row-verdict.d.ts +15 -4
  44. package/dist/core/checkpoint-row-verdict.js +22 -2
  45. package/dist/core/checkpoint-store.d.ts +28 -11
  46. package/dist/core/checkpoint-store.js +45 -4
  47. package/dist/core/compliance.d.ts +6 -2
  48. package/dist/core/compliance.js +3 -3
  49. package/dist/core/context-settings.d.ts +40 -9
  50. package/dist/core/context-settings.js +32 -10
  51. package/dist/core/engine-attestation.d.ts +27 -7
  52. package/dist/core/engine-attestation.js +5 -1
  53. package/dist/core/engine-notice.d.ts +43 -5
  54. package/dist/core/extension-requester.d.ts +9 -0
  55. package/dist/core/extension-requester.js +7 -0
  56. package/dist/core/file-history-store.d.ts +28 -0
  57. package/dist/core/file-history-store.js +48 -5
  58. package/dist/core/fs-write-gate-policy.js +1 -1
  59. package/dist/core/gate-fold.js +2 -0
  60. package/dist/core/gate-lanes.js +2 -0
  61. package/dist/core/gate-outcome.d.ts +39 -2
  62. package/dist/core/gate-outcome.js +20 -1
  63. package/dist/core/git-worktree-env.d.ts +62 -3
  64. package/dist/core/git-worktree-env.js +91 -30
  65. package/dist/core/governance-codes.d.ts +9 -3
  66. package/dist/core/governance-codes.js +17 -3
  67. package/dist/core/leg-identity.d.ts +19 -1
  68. package/dist/core/leg-identity.js +12 -0
  69. package/dist/core/mailbox-store.d.ts +39 -4
  70. package/dist/core/mailbox-store.js +14 -2
  71. package/dist/core/memory-engine/consolidation-driver.d.ts +32 -17
  72. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  73. package/dist/core/memory-engine/consolidation.d.ts +74 -10
  74. package/dist/core/memory-engine/consolidation.js +183 -11
  75. package/dist/core/memory-engine/control-objects.d.ts +25 -0
  76. package/dist/core/memory-engine/control-objects.js +151 -0
  77. package/dist/core/memory-engine/control-plane-adoption.d.ts +48 -0
  78. package/dist/core/memory-engine/control-plane-adoption.js +159 -0
  79. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  80. package/dist/core/memory-engine/data-plane.js +11 -6
  81. package/dist/core/memory-engine/delegation-settlement.d.ts +58 -40
  82. package/dist/core/memory-engine/delegation-settlement.js +270 -85
  83. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  84. package/dist/core/memory-engine/dual-root.js +11 -7
  85. package/dist/core/memory-engine/engine.d.ts +136 -58
  86. package/dist/core/memory-engine/engine.js +491 -394
  87. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  88. package/dist/core/memory-engine/entry-scan.js +3 -0
  89. package/dist/core/memory-engine/file-backend.d.ts +62 -60
  90. package/dist/core/memory-engine/file-backend.js +122 -198
  91. package/dist/core/memory-engine/index.d.ts +8 -7
  92. package/dist/core/memory-engine/index.js +7 -6
  93. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  94. package/dist/core/memory-engine/landing-admission.js +3 -3
  95. package/dist/core/memory-engine/layout.d.ts +127 -46
  96. package/dist/core/memory-engine/layout.js +264 -109
  97. package/dist/core/memory-engine/memory-backend-contract.d.ts +26 -1
  98. package/dist/core/memory-engine/memory-backend-contract.js +476 -0
  99. package/dist/core/memory-engine/memory-deployment.d.ts +42 -11
  100. package/dist/core/memory-engine/memory-deployment.js +54 -15
  101. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  102. package/dist/core/memory-engine/origin-clearance.js +68 -9
  103. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  104. package/dist/core/memory-engine/scope-contract.js +68 -19
  105. package/dist/core/memory-engine/session-write-home.d.ts +37 -2
  106. package/dist/core/memory-engine/session-write-home.js +38 -11
  107. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  108. package/dist/core/memory-engine/sync-client.js +7 -0
  109. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  110. package/dist/core/memory-engine/sync-report.js +6 -2
  111. package/dist/core/memory-engine/tools.d.ts +2 -2
  112. package/dist/core/memory-engine/tools.js +10 -10
  113. package/dist/core/memory-engine/types.d.ts +155 -19
  114. package/dist/core/memory-engine/types.js +2 -0
  115. package/dist/core/memory.js +15 -6
  116. package/dist/core/mode-policy.js +3 -3
  117. package/dist/core/mods/agent-stations.d.ts +18 -0
  118. package/dist/core/mods/agent-stations.js +8 -6
  119. package/dist/core/mods/extension-call.d.ts +4 -0
  120. package/dist/core/mods/extension-call.js +8 -0
  121. package/dist/core/mods/stations.d.ts +20 -1
  122. package/dist/core/mods/stations.js +21 -2
  123. package/dist/core/mods/tool-call.js +3 -4
  124. package/dist/core/parent-spec-seat.d.ts +2 -2
  125. package/dist/core/park-selfcheck.js +2 -2
  126. package/dist/core/pause-registry.d.ts +2 -0
  127. package/dist/core/pause-registry.js +3 -0
  128. package/dist/core/peer-channel.d.ts +5 -0
  129. package/dist/core/permission-rule-consent.d.ts +26 -8
  130. package/dist/core/permission-rule-consent.js +76 -36
  131. package/dist/core/permission-rule-store.d.ts +72 -13
  132. package/dist/core/permission-rule-store.js +29 -8
  133. package/dist/core/read-only-shell.js +3 -2
  134. package/dist/core/redaction-marks.d.ts +8 -0
  135. package/dist/core/redaction-marks.js +6 -0
  136. package/dist/core/refusal-echo.d.ts +20 -0
  137. package/dist/core/refusal-echo.js +33 -0
  138. package/dist/core/remote-env.d.ts +12 -1
  139. package/dist/core/remote-env.js +3 -0
  140. package/dist/core/retention.d.ts +180 -10
  141. package/dist/core/retention.js +45 -0
  142. package/dist/core/retired-keys.d.ts +5 -0
  143. package/dist/core/retired-keys.js +3 -0
  144. package/dist/core/rule-offer-read.d.ts +0 -4
  145. package/dist/core/rule-offer-read.js +2 -18
  146. package/dist/core/runner/child-tree.d.ts +29 -3
  147. package/dist/core/runner/child-tree.js +39 -16
  148. package/dist/core/runner/classifier-ladder.d.ts +7 -1
  149. package/dist/core/runner/classifier-ladder.js +4 -2
  150. package/dist/core/runner/compact-session.js +10 -7
  151. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  152. package/dist/core/runner/compaction-call-options.js +3 -2
  153. package/dist/core/runner/contracts.d.ts +39 -11
  154. package/dist/core/runner/delegation-owner.d.ts +10 -3
  155. package/dist/core/runner/delegation-owner.js +4 -1
  156. package/dist/core/runner/gate-exit.d.ts +6 -0
  157. package/dist/core/runner/gate-exit.js +13 -4
  158. package/dist/core/runner/inherited-ask-grants.js +1 -1
  159. package/dist/core/runner/memory-consolidation-driver.d.ts +10 -5
  160. package/dist/core/runner/memory-consolidation-driver.js +12 -9
  161. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  162. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  163. package/dist/core/runner/person-path-rows.d.ts +8 -3
  164. package/dist/core/runner/person-path-rows.js +5 -1
  165. package/dist/core/runner/placement-fence.d.ts +12 -0
  166. package/dist/core/runner/placement-fence.js +20 -6
  167. package/dist/core/runner/prepare-ask-lane.js +5 -5
  168. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -2
  169. package/dist/core/runner/prepare-caps-and-workflow.js +7 -4
  170. package/dist/core/runner/prepare-config-doors.js +4 -0
  171. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  172. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  173. package/dist/core/runner/prepare-execution-env.js +17 -6
  174. package/dist/core/runner/prepare-gate-stations.d.ts +5 -0
  175. package/dist/core/runner/prepare-gate-stations.js +5 -5
  176. package/dist/core/runner/prepare-hands-readface.d.ts +2 -1
  177. package/dist/core/runner/prepare-hands-readface.js +5 -4
  178. package/dist/core/runner/prepare-inherited-gate.d.ts +13 -9
  179. package/dist/core/runner/prepare-inherited-gate.js +12 -6
  180. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  181. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  182. package/dist/core/runner/prepare-memory.d.ts +7 -2
  183. package/dist/core/runner/prepare-memory.js +41 -39
  184. package/dist/core/runner/prepare-park-ask.js +4 -3
  185. package/dist/core/runner/prepare-policy-chain.js +7 -7
  186. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  187. package/dist/core/runner/prepare-task.js +26 -18
  188. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  189. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  190. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  191. package/dist/core/runner/resume-admission.d.ts +2 -2
  192. package/dist/core/runner/resume-admission.js +2 -23
  193. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  194. package/dist/core/runner/role-resolution-table.js +62 -0
  195. package/dist/core/runner/run-compaction-machinery.js +2 -2
  196. package/dist/core/runner/run-identity-wiring.js +12 -9
  197. package/dist/core/runner/run-leg.js +9 -5
  198. package/dist/core/runner/run-notification-lane.js +22 -22
  199. package/dist/core/runner/run-recovery-lanes.js +3 -3
  200. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  201. package/dist/core/runner/run-terminal-adoption.js +1 -1
  202. package/dist/core/runner/run-turn-boundary.js +14 -15
  203. package/dist/core/runner/runtask.js +1 -1
  204. package/dist/core/runner/terminal-account.js +1 -1
  205. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  206. package/dist/core/runner/tool-occurrence.js +2 -2
  207. package/dist/core/runner-deps.d.ts +7 -3
  208. package/dist/core/secret-env.d.ts +1 -1
  209. package/dist/core/secret-env.js +4 -4
  210. package/dist/core/session-checkout.d.ts +168 -0
  211. package/dist/core/session-checkout.js +579 -0
  212. package/dist/core/session-store.d.ts +12 -4
  213. package/dist/core/session-store.js +23 -3
  214. package/dist/core/session.d.ts +16 -2
  215. package/dist/core/session.js +3 -0
  216. package/dist/core/shell-read-silence.js +8 -0
  217. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +0 -12
  218. package/dist/core/store-contracts/checkpoint-store-contract.js +6 -7
  219. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  220. package/dist/core/store-contracts/session-store-contract.js +39 -0
  221. package/dist/core/task-event.d.ts +30 -5
  222. package/dist/core/task-notification.d.ts +119 -32
  223. package/dist/core/task-notification.js +186 -100
  224. package/dist/core/task-registry-agent.d.ts +25 -2
  225. package/dist/core/task-registry-agent.js +56 -22
  226. package/dist/core/task-registry-shared.d.ts +33 -11
  227. package/dist/core/task-registry.d.ts +33 -9
  228. package/dist/core/task-registry.js +36 -18
  229. package/dist/core/task-spec-members.js +1 -1
  230. package/dist/core/task-spec.d.ts +27 -2
  231. package/dist/core/tool-errors.d.ts +14 -6
  232. package/dist/core/tool-errors.js +1 -1
  233. package/dist/core/tool-policy.d.ts +32 -13
  234. package/dist/core/tool-policy.js +27 -17
  235. package/dist/core/tool-result-store.d.ts +20 -0
  236. package/dist/core/tool-spec.d.ts +42 -19
  237. package/dist/core/trace.d.ts +3 -2
  238. package/dist/core/types.d.ts +1 -1
  239. package/dist/core/untrusted-egress.d.ts +15 -4
  240. package/dist/core/untrusted-egress.js +23 -22
  241. package/dist/core/workflow-journal-store.d.ts +11 -0
  242. package/dist/core/workflow-journal-store.js +7 -0
  243. package/dist/core/workflow-run-store.d.ts +9 -0
  244. package/dist/core/workflow-run-store.js +6 -0
  245. package/dist/core/workspace-snapshot.d.ts +3 -1
  246. package/dist/core/workspace-snapshot.js +1 -0
  247. package/dist/engine/compaction/compaction.d.ts +2 -1
  248. package/dist/engine/harness/types.d.ts +67 -1
  249. package/dist/engine/harness/types.js +108 -0
  250. package/dist/engine/session/import-validate.js +6 -1
  251. package/dist/engine/session/session.d.ts +30 -1
  252. package/dist/engine/session/session.js +48 -1
  253. package/dist/index.d.ts +12 -7
  254. package/dist/index.js +12 -7
  255. package/dist/internal/harness-types.d.ts +1 -1
  256. package/dist/orchestration/run-workflow-tool.d.ts +8 -1
  257. package/dist/orchestration/run-workflow-tool.js +8 -0
  258. package/dist/orchestration/workflow-types.d.ts +2 -1
  259. package/dist/orchestration/workflow.d.ts +6 -0
  260. package/dist/orchestration/workflow.js +5 -2
  261. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  262. package/dist/stores/file/checkpoint-store.js +4 -1
  263. package/dist/stores/file/file-history-store.d.ts +13 -0
  264. package/dist/stores/file/file-history-store.js +75 -13
  265. package/dist/stores/file/index.d.ts +11 -1
  266. package/dist/stores/file/index.js +7 -11
  267. package/dist/stores/file/permission-rule-store.d.ts +23 -0
  268. package/dist/stores/file/permission-rule-store.js +75 -7
  269. package/dist/stores/file/session-store.js +2 -1
  270. package/dist/stores/file/tool-result-store.d.ts +14 -0
  271. package/dist/stores/file/tool-result-store.js +39 -2
  272. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  273. package/dist/stores/file/workflow-journal-store.js +17 -0
  274. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  275. package/dist/stores/file/workflow-run-store.js +15 -0
  276. package/dist/tools/fs/bash-program-position.js +3 -3
  277. package/dist/tools/fs/program-read-model.d.ts +34 -10
  278. package/dist/tools/fs/program-read-model.js +37 -7
  279. package/dist/tools/fs/program-read-model.rows.js +13 -2
  280. package/dist/tools/fs/read-deny.d.ts +28 -3
  281. package/dist/tools/fs/read-deny.js +18 -2
  282. package/dist/tools/fs/removal-targets.js +3 -3
  283. package/dist/tools/fs/safety.d.ts +2 -0
  284. package/dist/tools/fs/safety.js +1 -1
  285. package/dist/tools/fs/shell-read-argv.d.ts +8 -1
  286. package/dist/tools/fs/shell-read-argv.js +34 -29
  287. package/dist/tools/fs/shell-read-bindings.d.ts +2 -0
  288. package/dist/tools/fs/shell-read-bindings.js +5 -1
  289. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  290. package/dist/tools/fs/shell-read-brace.js +79 -0
  291. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  292. package/dist/tools/fs/shell-read-check.js +16 -14
  293. package/dist/tools/fs/shell-read-establish.js +23 -16
  294. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  295. package/dist/tools/fs/shell-read-judge.js +3 -3
  296. package/dist/tools/fs/shell-read-plan.d.ts +10 -0
  297. package/dist/tools/fs/shell-read-plan.js +189 -93
  298. package/dist/tools/fs/shell-read-start.d.ts +19 -9
  299. package/dist/tools/fs/shell-read-start.js +20 -12
  300. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  301. package/dist/tools/fs/shell-read-word.js +9 -5
  302. package/dist/tools/fs/shell-read-workdir.d.ts +26 -7
  303. package/dist/tools/fs/shell-read-workdir.js +73 -12
  304. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  305. package/dist/tools/worktree.d.ts +3 -2
  306. package/dist/tools/worktree.js +7 -35
  307. package/package.json +3 -2
  308. package/test/export-surface.snapshot.json +135 -11
  309. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  310. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  311. package/wire-changes/core@7.63.0.json +3523 -0
  312. package/wire-changes/core@7.64.0.json +2653 -0
  313. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  314. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  315. package/wire-changes/primitives@7.63.0.json +445 -0
  316. package/wire-changes/primitives@7.64.0.json +30 -0
  317. package/dist/core/credential-vocabulary.d.ts +0 -176
  318. package/dist/core/credential-vocabulary.js +0 -190
  319. package/dist/core/redaction-passes.d.ts +0 -82
  320. package/dist/core/redaction-passes.js +0 -377
@@ -3,7 +3,7 @@ const { O_WRONLY, O_RDONLY, O_CREAT, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConsta
3
3
  import { homedir } from "node:os";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
6
- import { MEMORY_ORIGIN_CAUSES } from "./types.js";
6
+ import { MEMORY_GOVERNANCE_DOC_NAMES, MEMORY_ORIGIN_CAUSES } from "./types.js";
7
7
  import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
8
8
  import { thrownLabel, thrownText } from "../thrown-value.js";
9
9
  import { egressText } from "../untrusted-egress.js";
@@ -214,6 +214,9 @@ export function scopeDirName(scope) {
214
214
  }
215
215
  const caseFoldByDirIdentity = new Map();
216
216
  let caseFoldProbeSeq = 0;
217
+ export function forgetCaseFoldVerdicts() {
218
+ caseFoldByDirIdentity.clear();
219
+ }
217
220
  function lstatOrAbsent(p) {
218
221
  try {
219
222
  return lstatSync(p);
@@ -736,7 +739,7 @@ function moveLooseContent(root, controlDir, rec, owner, label, renew, sink, resu
736
739
  rmSync(join(root, p), { force: true });
737
740
  }
738
741
  renew();
739
- writeIndexRevs(controlDir, {});
742
+ clearIndexRevs(controlDir);
740
743
  discloseLayoutIncident(sink, "memory.layout_migrated", `memory layout adopted at ${root}: ${moved} loose entr${moved === 1 ? "y" : "ies"} moved into the home of ${JSON.stringify(owner)} (${label})${resumed ? " — an interrupted move was finished" : ""}`);
741
744
  }
742
745
  export const canonicalize = physicalPathOfExisting;
@@ -970,7 +973,7 @@ export function tryStoreTxnLock(controlDir, opts) {
970
973
  }
971
974
  }
972
975
  if (tokenPresent) {
973
- const tomb = join(controlDir, `${STORE_TXN_LOCK_DIR}.stale-${randomUUID()}`);
976
+ const tomb = join(controlDir, `${STORE_TXN_LOCK_DIR}${LOCK_TOMB_INFIX}${randomUUID()}`);
974
977
  let stolen = false;
975
978
  try {
976
979
  renameSync(lockDir, tomb);
@@ -1361,6 +1364,112 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
1361
1364
  ...(detail !== undefined ? { detail } : {}),
1362
1365
  };
1363
1366
  }
1367
+ export const ATOMIC_WRITE_TMP_PREFIX = ".tmp-";
1368
+ export const LOCK_TOMB_INFIX = ".stale-";
1369
+ export const STORE_OPEN_ARTIFACTS = Object.freeze({
1370
+ files: Object.freeze([ROOT_ANCHOR_FILE, SCOPES_FILE, `${SCOPES_FILE}.journal`]),
1371
+ filePrefixes: Object.freeze([ATOMIC_WRITE_TMP_PREFIX]),
1372
+ lockDirs: Object.freeze([`${ROOT_ANCHOR_FILE}.lock`, `${SCOPES_FILE}.lock`, STORE_TXN_LOCK_DIR]),
1373
+ memoryFilePrefixes: Object.freeze([CASEFOLD_PROBE_PREFIX]),
1374
+ });
1375
+ export function isStoreOpenArtifact(where, rel) {
1376
+ const [top] = rel;
1377
+ if (top === undefined)
1378
+ return false;
1379
+ const starts = (prefixes) => prefixes.some((p) => top.startsWith(p));
1380
+ if (where === "memory")
1381
+ return rel.length === 1 && starts(STORE_OPEN_ARTIFACTS.memoryFilePrefixes);
1382
+ if (rel.length === 1)
1383
+ return STORE_OPEN_ARTIFACTS.files.includes(top) || starts(STORE_OPEN_ARTIFACTS.filePrefixes);
1384
+ return isLockTreeName(top);
1385
+ }
1386
+ function isLockTreeName(name) {
1387
+ return STORE_OPEN_ARTIFACTS.lockDirs.some((lock) => name === lock || name.startsWith(`${lock}${LOCK_TOMB_INFIX}`));
1388
+ }
1389
+ export function storeHoldsRecord(memoryDir, controlDir) {
1390
+ return treeHoldsRecord(controlDir, "control", (name) => namedArtifactDamaged(memoryDir, controlDir, name)) || treeHoldsRecord(memoryDir, "memory");
1391
+ }
1392
+ function namedArtifactDamaged(memoryDir, controlDir, name) {
1393
+ try {
1394
+ if (name === ROOT_ANCHOR_FILE)
1395
+ readStoreRootAnchor(controlDir, memoryDir);
1396
+ else if (name === SCOPES_FILE || name === `${SCOPES_FILE}.journal`) {
1397
+ for (const file of [`${SCOPES_FILE}.journal`, SCOPES_FILE])
1398
+ if (!absentOrRegularFile(join(controlDir, file)))
1399
+ return true;
1400
+ readScopesRecord(controlDir);
1401
+ }
1402
+ return false;
1403
+ }
1404
+ catch {
1405
+ return true;
1406
+ }
1407
+ }
1408
+ function absentOrRegularFile(path) {
1409
+ const entry = lstatOrAbsent(path);
1410
+ if (entry === undefined)
1411
+ return true;
1412
+ return entry.isSymbolicLink() ? statSync(path).isFile() : entry.isFile();
1413
+ }
1414
+ const STORE_CENSUS_WALKS = 4;
1415
+ function treeHoldsRecord(dir, where, damaged) {
1416
+ const walk = (path, rel) => {
1417
+ let items;
1418
+ try {
1419
+ items = readdirSync(path, { withFileTypes: true });
1420
+ }
1421
+ catch (err) {
1422
+ if (err.code !== "ENOENT")
1423
+ return true;
1424
+ return rel.length === 0 ? absentDirReading(path) : "moved";
1425
+ }
1426
+ for (const item of items) {
1427
+ const at = [...rel, item.name];
1428
+ if (rel.length === 0 && damaged?.(item.name) === true)
1429
+ return true;
1430
+ const reading = !item.isDirectory() ? !isStoreOpenArtifact(where, at) : where === "control" && rel.length === 0 && isLockTreeName(item.name) ? false : walk(join(path, item.name), at);
1431
+ if (reading !== false)
1432
+ return reading;
1433
+ }
1434
+ return false;
1435
+ };
1436
+ let quiet = 0;
1437
+ for (let n = 0; n < STORE_CENSUS_WALKS; n += 1) {
1438
+ const reading = walk(dir, []);
1439
+ if (reading === true)
1440
+ return true;
1441
+ quiet = reading === false ? quiet + 1 : 0;
1442
+ if (quiet === 2)
1443
+ return false;
1444
+ }
1445
+ return true;
1446
+ }
1447
+ function absentDirReading(dir) {
1448
+ for (let at = dir;; at = dirname(at)) {
1449
+ let item;
1450
+ try {
1451
+ item = lstatSync(at, { throwIfNoEntry: false });
1452
+ }
1453
+ catch {
1454
+ return true;
1455
+ }
1456
+ if (item === undefined) {
1457
+ if (dirname(at) === at)
1458
+ return false;
1459
+ continue;
1460
+ }
1461
+ if (item.isSymbolicLink()) {
1462
+ try {
1463
+ if (statSync(at, { throwIfNoEntry: false }) === undefined)
1464
+ return true;
1465
+ }
1466
+ catch {
1467
+ return true;
1468
+ }
1469
+ }
1470
+ return at === dir ? "moved" : false;
1471
+ }
1472
+ }
1364
1473
  export const ANNOUNCEMENTS_FILE = "announcements.json";
1365
1474
  export const MEMORY_ANNOUNCEMENTS_MAX = 20;
1366
1475
  export const SCAN_FUSE_FILE = "scan-fuse.json";
@@ -1378,7 +1487,7 @@ export function acquireSidecarLock(lockDir, opts = {}) {
1378
1487
  const mintToken = () => `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
1379
1488
  let deadlineRounds = 0;
1380
1489
  const stealOnce = () => {
1381
- const tomb = `${lockDir}.stale-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
1490
+ const tomb = `${lockDir}${LOCK_TOMB_INFIX}${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
1382
1491
  try {
1383
1492
  renameSync(lockDir, tomb);
1384
1493
  }
@@ -1514,7 +1623,7 @@ function readSidecarJson(controlDir, fileName) {
1514
1623
  }
1515
1624
  const ANNOUNCEMENTS_FORM = 2;
1516
1625
  function emptyAnnouncements() {
1517
- return { scopes: Object.create(null), unscopedDiscarded: 0 };
1626
+ return { v: ANNOUNCEMENTS_FORM, scopes: Object.create(null) };
1518
1627
  }
1519
1628
  function wholeCount(v) {
1520
1629
  return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
@@ -1545,13 +1654,11 @@ function coerceAnnouncements(raw) {
1545
1654
  if (!raw || typeof raw !== "object" || Array.isArray(raw))
1546
1655
  return rec;
1547
1656
  const r = raw;
1548
- if (r.v !== ANNOUNCEMENTS_FORM) {
1549
- rec.unscopedDiscarded = (Array.isArray(r.queue) ? r.queue.length : 0) + wholeCount(r.folded);
1550
- return rec;
1551
- }
1552
- rec.unscopedDiscarded = wholeCount(r.unscopedDiscarded);
1657
+ if (r.v !== ANNOUNCEMENTS_FORM)
1658
+ return withUnscoped(rec, (Array.isArray(r.queue) ? r.queue.length : 0) + wholeCount(r.folded));
1659
+ let unscoped = wholeCount(r.unscopedDiscarded);
1553
1660
  if (!r.scopes || typeof r.scopes !== "object" || Array.isArray(r.scopes))
1554
- return rec;
1661
+ return withUnscoped(rec, unscoped);
1555
1662
  for (const scope of Object.keys(r.scopes)) {
1556
1663
  const q = r.scopes[scope];
1557
1664
  if (scope === "" || !q || typeof q !== "object")
@@ -1563,17 +1670,36 @@ function coerceAnnouncements(raw) {
1563
1670
  if (a !== undefined)
1564
1671
  queue.push(a);
1565
1672
  else
1566
- rec.unscopedDiscarded += 1;
1673
+ unscoped += 1;
1567
1674
  }
1568
1675
  }
1569
1676
  const folded = wholeCount(q.folded);
1570
1677
  if (queue.length > 0 || folded > 0)
1571
1678
  rec.scopes[scope] = { folded, queue };
1572
1679
  }
1680
+ return withUnscoped(rec, unscoped);
1681
+ }
1682
+ function withUnscoped(rec, n) {
1683
+ if (n > 0)
1684
+ rec.unscopedDiscarded = n;
1685
+ else
1686
+ delete rec.unscopedDiscarded;
1573
1687
  return rec;
1574
1688
  }
1575
1689
  function persistedAnnouncements(rec) {
1576
- return { v: ANNOUNCEMENTS_FORM, scopes: rec.scopes, ...(rec.unscopedDiscarded > 0 ? { unscopedDiscarded: rec.unscopedDiscarded } : {}) };
1690
+ return { v: ANNOUNCEMENTS_FORM, scopes: rec.scopes, ...((rec.unscopedDiscarded ?? 0) > 0 ? { unscopedDiscarded: rec.unscopedDiscarded } : {}) };
1691
+ }
1692
+ const ANNOUNCEMENTS_DOC = "announcements";
1693
+ export function sayAnnounceFailure(sink, stage, cause) {
1694
+ if (sink === undefined)
1695
+ return;
1696
+ try {
1697
+ const err = new Error(`memory announcement queue ${stage} failed: ${thrownText(cause)}`);
1698
+ err.code = "memory.announce_failed";
1699
+ sink(err);
1700
+ }
1701
+ catch {
1702
+ }
1577
1703
  }
1578
1704
  function askedScopes(scopes, verb) {
1579
1705
  if (!Array.isArray(scopes) || !scopes.every((s) => typeof s === "string" && s !== "")) {
@@ -1594,7 +1720,7 @@ function mergeScopeQueues(rec, scopes) {
1594
1720
  lines.sort((x, y) => x.a.at - y.a.at || x.s - y.s || x.i - y.i);
1595
1721
  return { folded, queue: lines.map((l) => l.a) };
1596
1722
  }
1597
- export function enqueueMemoryAnnouncement(controlDir, ann, opts) {
1723
+ export async function enqueueMemoryAnnouncement(docs, ann, opts) {
1598
1724
  const o = opts === undefined ? undefined : receiveMembers(opts, { subject: "enqueueMemoryAnnouncement options", unit: "option", moment: "at enqueueMemoryAnnouncement" }, ANNOUNCEMENT_OPTION_KEYS);
1599
1725
  if (typeof ann.scope !== "string" || ann.scope === "") {
1600
1726
  throw new TypeError("enqueueMemoryAnnouncement: announcement.scope is required — each notice is filed under the one scope it reports on");
@@ -1604,19 +1730,19 @@ export function enqueueMemoryAnnouncement(controlDir, ann, opts) {
1604
1730
  const family = o?.supersedesPrefix === undefined ? undefined : egressText("same-principal", o.supersedesPrefix);
1605
1731
  if (ann.items.length === 0 && family === undefined)
1606
1732
  return;
1607
- lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
1608
- const rec = coerceAnnouncements(current);
1733
+ const line = { ...ann, scope };
1734
+ await docs.updateDoc(ANNOUNCEMENTS_DOC, coerceAnnouncements, (rec) => {
1609
1735
  const own = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : { folded: 0, queue: [] };
1610
1736
  if (family !== undefined) {
1611
1737
  const queued = own.queue.flatMap((a) => a.items.filter((i) => i.startsWith(family)));
1612
1738
  if (queued.length === ann.items.length && ann.items.every((i) => queued.includes(i)))
1613
- return undefined;
1739
+ return { result: undefined };
1614
1740
  for (const a of own.queue)
1615
1741
  a.items = a.items.filter((i) => !i.startsWith(family));
1616
1742
  own.queue = own.queue.filter((a) => a.items.length > 0);
1617
1743
  }
1618
- if (ann.items.length > 0)
1619
- own.queue.push({ ...ann, scope });
1744
+ if (line.items.length > 0)
1745
+ own.queue.push({ ...line });
1620
1746
  if (own.queue.length > MEMORY_ANNOUNCEMENTS_MAX) {
1621
1747
  own.folded += own.queue.length - MEMORY_ANNOUNCEMENTS_MAX;
1622
1748
  own.queue = own.queue.slice(-MEMORY_ANNOUNCEMENTS_MAX);
@@ -1625,65 +1751,63 @@ export function enqueueMemoryAnnouncement(controlDir, ann, opts) {
1625
1751
  rec.scopes[scope] = own;
1626
1752
  else
1627
1753
  delete rec.scopes[scope];
1628
- return persistedAnnouncements(rec);
1754
+ return { next: persistedAnnouncements(rec), result: undefined };
1629
1755
  });
1630
1756
  }
1631
- export function drainMemoryAnnouncements(controlDir, scopes) {
1757
+ export async function drainMemoryAnnouncements(docs, scopes) {
1632
1758
  const asked = askedScopes(scopes, "drainMemoryAnnouncements");
1633
- const file = join(controlDir, ANNOUNCEMENTS_FILE);
1634
- if (!existsSync(file) && !existsSync(`${file}.journal`))
1759
+ if ((await docs.readDoc(ANNOUNCEMENTS_DOC)) === undefined)
1635
1760
  return { folded: 0, queue: [], unscopedDiscarded: 0 };
1636
- let drained = { folded: 0, queue: [], unscopedDiscarded: 0 };
1637
- lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
1638
- const rec = coerceAnnouncements(current);
1761
+ let otherForm = false;
1762
+ return docs.updateDoc(ANNOUNCEMENTS_DOC, (raw) => {
1763
+ otherForm = !raw || typeof raw !== "object" || raw.v !== ANNOUNCEMENTS_FORM;
1764
+ return coerceAnnouncements(raw);
1765
+ }, (rec) => {
1639
1766
  const mine = mergeScopeQueues(rec, asked);
1640
- drained = { ...mine, unscopedDiscarded: rec.unscopedDiscarded };
1641
- const otherForm = !current || typeof current !== "object" || current.v !== ANNOUNCEMENTS_FORM;
1642
- if (mine.queue.length === 0 && mine.folded === 0 && rec.unscopedDiscarded === 0 && !otherForm)
1643
- return undefined;
1767
+ const drained = { ...mine, unscopedDiscarded: rec.unscopedDiscarded ?? 0 };
1768
+ if (mine.queue.length === 0 && mine.folded === 0 && drained.unscopedDiscarded === 0 && !otherForm)
1769
+ return { result: drained };
1644
1770
  for (const scope of asked)
1645
1771
  delete rec.scopes[scope];
1646
- rec.unscopedDiscarded = 0;
1647
- return persistedAnnouncements(rec);
1772
+ return { next: persistedAnnouncements(withUnscoped(rec, 0)), result: drained };
1648
1773
  });
1649
- return drained;
1650
1774
  }
1651
- export function peekMemoryAnnouncements(controlDir, scopes) {
1775
+ export async function peekMemoryAnnouncements(docs, scopes) {
1652
1776
  const asked = askedScopes(scopes, "peekMemoryAnnouncements");
1653
- const rec = coerceAnnouncements(readSidecarJson(controlDir, ANNOUNCEMENTS_FILE));
1654
- return { ...mergeScopeQueues(rec, asked), unscopedDiscarded: rec.unscopedDiscarded };
1777
+ const rec = coerceAnnouncements(await docs.readDoc(ANNOUNCEMENTS_DOC));
1778
+ return { ...mergeScopeQueues(rec, asked), unscopedDiscarded: rec.unscopedDiscarded ?? 0 };
1655
1779
  }
1656
- export function transferMemoryAnnouncements(fromControlDir, toControlDir) {
1657
- const file = join(fromControlDir, ANNOUNCEMENTS_FILE);
1658
- if (!existsSync(file) && !existsSync(`${file}.journal`))
1780
+ export async function transferMemoryAnnouncements(from, to) {
1781
+ const raw = await from.readDoc(ANNOUNCEMENTS_DOC);
1782
+ if (raw === undefined)
1659
1783
  return;
1660
- const taken = coerceAnnouncements(readSidecarJson(fromControlDir, ANNOUNCEMENTS_FILE));
1784
+ const taken = coerceAnnouncements(raw);
1785
+ const takenUnscoped = taken.unscopedDiscarded ?? 0;
1661
1786
  const carried = Object.keys(taken.scopes).flatMap((scope) => taken.scopes[scope].queue);
1662
- carried.sort((x, y) => x.at - y.at);
1663
- for (const ann of carried)
1664
- enqueueMemoryAnnouncement(toControlDir, ann);
1665
- const extraFolded = Object.keys(taken.scopes).map((scope) => ({ scope, folded: taken.scopes[scope].folded })).filter((x) => x.folded > 0);
1666
- if (extraFolded.length > 0 || taken.unscopedDiscarded > 0) {
1667
- lockedJournaledUpdate(toControlDir, ANNOUNCEMENTS_FILE, (current) => {
1668
- const rec = coerceAnnouncements(current);
1669
- for (const { scope, folded } of extraFolded) {
1670
- const own = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : { folded: 0, queue: [] };
1671
- own.folded += folded;
1672
- rec.scopes[scope] = own;
1787
+ const lineKey = (a) => JSON.stringify(a);
1788
+ await to.updateDoc(ANNOUNCEMENTS_DOC, coerceAnnouncements, (rec) => {
1789
+ for (const scope of Object.keys(taken.scopes)) {
1790
+ const src = taken.scopes[scope];
1791
+ const own = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : { folded: 0, queue: [] };
1792
+ own.queue.push(...[...src.queue].sort((x, y) => x.at - y.at));
1793
+ own.folded += src.folded;
1794
+ if (own.queue.length > MEMORY_ANNOUNCEMENTS_MAX) {
1795
+ own.folded += own.queue.length - MEMORY_ANNOUNCEMENTS_MAX;
1796
+ own.queue = own.queue.slice(-MEMORY_ANNOUNCEMENTS_MAX);
1673
1797
  }
1674
- rec.unscopedDiscarded += taken.unscopedDiscarded;
1675
- return persistedAnnouncements(rec);
1676
- });
1677
- }
1678
- const moved = new Map();
1679
- for (const ann of carried)
1680
- moved.set(JSON.stringify(ann), (moved.get(JSON.stringify(ann)) ?? 0) + 1);
1681
- lockedJournaledUpdate(fromControlDir, ANNOUNCEMENTS_FILE, (current) => {
1682
- const rec = coerceAnnouncements(current);
1798
+ if (own.queue.length > 0 || own.folded > 0)
1799
+ rec.scopes[scope] = own;
1800
+ }
1801
+ return { next: persistedAnnouncements(withUnscoped(rec, (rec.unscopedDiscarded ?? 0) + takenUnscoped)), result: undefined };
1802
+ });
1803
+ await from.updateDoc(ANNOUNCEMENTS_DOC, coerceAnnouncements, (rec) => {
1804
+ const moved = new Map();
1805
+ for (const ann of carried)
1806
+ moved.set(lineKey(ann), (moved.get(lineKey(ann)) ?? 0) + 1);
1683
1807
  for (const scope of Object.keys(rec.scopes)) {
1684
1808
  const own = rec.scopes[scope];
1685
1809
  own.queue = own.queue.filter((a) => {
1686
- const key = JSON.stringify(a);
1810
+ const key = lineKey(a);
1687
1811
  const n = moved.get(key) ?? 0;
1688
1812
  if (n === 0)
1689
1813
  return true;
@@ -1694,8 +1818,7 @@ export function transferMemoryAnnouncements(fromControlDir, toControlDir) {
1694
1818
  if (own.queue.length === 0 && own.folded === 0)
1695
1819
  delete rec.scopes[scope];
1696
1820
  }
1697
- rec.unscopedDiscarded = Math.max(0, rec.unscopedDiscarded - taken.unscopedDiscarded);
1698
- return persistedAnnouncements(rec);
1821
+ return { next: persistedAnnouncements(withUnscoped(rec, Math.max(0, (rec.unscopedDiscarded ?? 0) - takenUnscoped))), result: undefined };
1699
1822
  });
1700
1823
  }
1701
1824
  export function scanFuseKey(scope, rel) {
@@ -1755,6 +1878,16 @@ export function writeIndexRevs(controlDir, revs) {
1755
1878
  catch {
1756
1879
  }
1757
1880
  }
1881
+ function clearIndexRevs(controlDir) {
1882
+ let present = true;
1883
+ try {
1884
+ present = lstatSync(join(controlDir, INDEX_REVS_FILE), { throwIfNoEntry: false }) !== undefined;
1885
+ }
1886
+ catch {
1887
+ }
1888
+ if (present)
1889
+ writeIndexRevs(controlDir, {});
1890
+ }
1758
1891
  export function scanFuseCount(controlDir, key) {
1759
1892
  return coerceFuse(readSidecarJson(controlDir, SCAN_FUSE_FILE))[key] ?? 0;
1760
1893
  }
@@ -2087,6 +2220,25 @@ export function clearScanFuse(controlDir, keys) {
2087
2220
  }
2088
2221
  export const LINEAGE_FILE = "lineage.json";
2089
2222
  export const CHALLENGES_FILE = "challenges.json";
2223
+ export const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
2224
+ export const SESSION_ACCOUNTS_FILE = "session-accounts.json";
2225
+ const FILE_GOVERNANCE_DOCS = Object.freeze({
2226
+ lineage: Object.freeze({ file: LINEAGE_FILE, what: "memory lineage ledger" }),
2227
+ challenges: Object.freeze({ file: CHALLENGES_FILE, what: "memory challenge ledger" }),
2228
+ settlements: Object.freeze({ file: DELEGATION_SETTLEMENT_FILE, what: "memory delegation-settlement ledger" }),
2229
+ "session-accounts": Object.freeze({ file: SESSION_ACCOUNTS_FILE, what: "memory session-account ledger" }),
2230
+ announcements: Object.freeze({ file: ANNOUNCEMENTS_FILE, what: "memory announcement queue" }),
2231
+ holds: Object.freeze({ file: "holds.json", what: "memory instruction-hold ledger" }),
2232
+ "origin-clearances": Object.freeze({ file: "origin-clearances.json", what: "memory origin-clearance ledger" }),
2233
+ });
2234
+ export function fileGovernanceDocOf(name) {
2235
+ if (typeof name !== "string" || !Object.prototype.hasOwnProperty.call(FILE_GOVERNANCE_DOCS, name)) {
2236
+ const e = new Error(`memory governance store: ${JSON.stringify(String(name))} is not a governance document (one of ${MEMORY_GOVERNANCE_DOC_NAMES.join(", ")})`);
2237
+ e.code = "memory.governance_doc_unknown";
2238
+ throw e;
2239
+ }
2240
+ return FILE_GOVERNANCE_DOCS[name];
2241
+ }
2090
2242
  export const LINEAGE_AUDIT_FILE = "lineage-audit.json";
2091
2243
  export const LINEAGE_AUDIT_MAX_ROWS = 2048;
2092
2244
  export const CHALLENGED_HISTORY_FILE = "usage-challenged-history.json";
@@ -2241,22 +2393,22 @@ function coerceLineage(raw) {
2241
2393
  pending[txnId] = t;
2242
2394
  return { version: 1, committed, pending };
2243
2395
  }
2244
- export function stageLineagePending(controlDir, txnId, sessionId, rows, now, incarnation) {
2245
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2396
+ export async function stageLineagePending(docs, txnId, sessionId, rows, now, incarnation) {
2397
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2246
2398
  rec.pending[txnId] = { sessionId, at: now(), rows: [...rows], ...(incarnation !== undefined ? { incarnation } : {}) };
2247
2399
  return { next: rec, result: undefined };
2248
2400
  });
2249
2401
  }
2250
- export function discardLineagePending(controlDir, txnId) {
2251
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2402
+ export async function discardLineagePending(docs, txnId) {
2403
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2252
2404
  if (rec.pending[txnId] === undefined)
2253
2405
  return { result: undefined };
2254
2406
  delete rec.pending[txnId];
2255
2407
  return { next: rec, result: undefined };
2256
2408
  });
2257
2409
  }
2258
- export function recordLineageCredential(controlDir, txnId, appliedIds, now) {
2259
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2410
+ export async function recordLineageCredential(docs, txnId, appliedIds, now) {
2411
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2260
2412
  const txn = rec.pending[txnId];
2261
2413
  if (txn === undefined)
2262
2414
  throw new ControlPlaneCorruptError(`memory lineage ledger: credential for unknown pending transaction ${txnId}`);
@@ -2264,8 +2416,8 @@ export function recordLineageCredential(controlDir, txnId, appliedIds, now) {
2264
2416
  return { next: rec, result: undefined };
2265
2417
  });
2266
2418
  }
2267
- export function promoteLineagePending(controlDir, txnId) {
2268
- return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2419
+ export async function promoteLineagePending(docs, txnId) {
2420
+ return docs.updateDoc("lineage", coerceLineage, (rec) => {
2269
2421
  const txn = rec.pending[txnId];
2270
2422
  if (txn === undefined)
2271
2423
  return { result: [] };
@@ -2286,8 +2438,8 @@ export function promoteLineagePending(controlDir, txnId) {
2286
2438
  return { next: rec, result: promoted };
2287
2439
  });
2288
2440
  }
2289
- export function adjudicateLineagePending(controlDir, txnId, action, now) {
2290
- return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2441
+ export async function adjudicateLineagePending(docs, txnId, action, now) {
2442
+ return docs.updateDoc("lineage", coerceLineage, (rec) => {
2291
2443
  const txn = rec.pending[txnId];
2292
2444
  if (txn === undefined)
2293
2445
  return { result: [] };
@@ -2312,8 +2464,8 @@ export function adjudicateLineagePending(controlDir, txnId, action, now) {
2312
2464
  return { next: rec, result: promoted };
2313
2465
  });
2314
2466
  }
2315
- export function reconcileLineage(controlDir) {
2316
- return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2467
+ export async function reconcileLineage(docs) {
2468
+ return docs.updateDoc("lineage", coerceLineage, (rec) => {
2317
2469
  const promoted = [];
2318
2470
  const undecidable = [];
2319
2471
  let changed = false;
@@ -2348,9 +2500,9 @@ export function importLatchTxnId(bundleHash) {
2348
2500
  function importReceiptPath(controlDir, bundleHash) {
2349
2501
  return join(controlDir, IMPORT_RECEIPTS_DIR, `${bundleHash}.json`);
2350
2502
  }
2351
- export function stageImportLatch(controlDir, bundleHash, rows, now) {
2503
+ export async function stageImportLatch(docs, bundleHash, rows, now) {
2352
2504
  const txnId = importLatchTxnId(bundleHash);
2353
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2505
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2354
2506
  const existing = rec.pending[txnId];
2355
2507
  if (existing !== undefined && !isLatchOnlyTxn(existing)) {
2356
2508
  throw new ControlPlaneCorruptError(`memory lineage ledger: pending transaction ${txnId} exists and is NOT an import latch — refusing to overwrite a real staged transaction`);
@@ -2365,7 +2517,7 @@ export function stageImportLatch(controlDir, bundleHash, rows, now) {
2365
2517
  });
2366
2518
  return txnId;
2367
2519
  }
2368
- export function releaseImportLatch(controlDir, txnId) {
2520
+ export async function releaseImportLatch(docs, controlDir, txnId) {
2369
2521
  const prefix = "import:";
2370
2522
  if (!txnId.startsWith(prefix) || !/^[0-9a-f]{64}$/.test(txnId.slice(prefix.length))) {
2371
2523
  throw new ControlPlaneCorruptError(`releaseImportLatch: ${JSON.stringify(txnId)} is not an import-latch transaction id (import:<64-hex bundleHash>)`);
@@ -2385,7 +2537,7 @@ export function releaseImportLatch(controlDir, txnId) {
2385
2537
  if (!receiptPresent) {
2386
2538
  throw new ControlPlaneCorruptError(`releaseImportLatch: no completion receipt at ${receipt} — the import's governance legs are not proven landed, the latch stays; re-run the same bundle import to converge`);
2387
2539
  }
2388
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2540
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2389
2541
  const txn = rec.pending[txnId];
2390
2542
  if (txn === undefined)
2391
2543
  return { result: undefined };
@@ -2396,16 +2548,16 @@ export function releaseImportLatch(controlDir, txnId) {
2396
2548
  return { next: rec, result: undefined };
2397
2549
  });
2398
2550
  }
2399
- export function lineageLatchedIds(controlDir) {
2400
- const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
2551
+ export async function lineageLatchedIds(docs) {
2552
+ const rec = coerceLineage(await docs.readDoc("lineage"));
2401
2553
  const out = new Set();
2402
2554
  for (const txn of Object.values(rec.pending))
2403
2555
  for (const row of txn.rows)
2404
2556
  out.add(row.entryId);
2405
2557
  return out;
2406
2558
  }
2407
- export function lineageContributionsOfSession(controlDir, sessionId, asking) {
2408
- const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
2559
+ export async function lineageContributionsOfSession(docs, sessionId, asking) {
2560
+ const rec = coerceLineage(await docs.readDoc("lineage"));
2409
2561
  const out = [];
2410
2562
  for (const [entryId, sessions] of Object.entries(rec.committed)) {
2411
2563
  const c = Object.prototype.hasOwnProperty.call(sessions, sessionId) ? sessions[sessionId] : undefined;
@@ -2415,8 +2567,8 @@ export function lineageContributionsOfSession(controlDir, sessionId, asking) {
2415
2567
  }
2416
2568
  return out;
2417
2569
  }
2418
- export function lineageAccountOfEntry(controlDir, entryId) {
2419
- const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
2570
+ export async function lineageAccountOfEntry(docs, entryId) {
2571
+ const rec = coerceLineage(await docs.readDoc("lineage"));
2420
2572
  const sessions = Object.prototype.hasOwnProperty.call(rec.committed, entryId) ? rec.committed[entryId] : undefined;
2421
2573
  const contributors = sessions === undefined ? [] : Object.entries(sessions).map(([sessionId, c]) => ({ sessionId, lastRev: c.lastRev, lastAt: c.lastAt }));
2422
2574
  let pendingLatched = false;
@@ -2428,10 +2580,10 @@ export function lineageAccountOfEntry(controlDir, entryId) {
2428
2580
  }
2429
2581
  return { contributors, pendingLatched };
2430
2582
  }
2431
- export function clearLineageForEntries(controlDir, entryIds) {
2583
+ export async function clearLineageForEntries(docs, entryIds) {
2432
2584
  if (entryIds.length === 0)
2433
2585
  return;
2434
- lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2586
+ await docs.updateDoc("lineage", coerceLineage, (rec) => {
2435
2587
  let changed = false;
2436
2588
  for (const id of entryIds) {
2437
2589
  if (rec.committed[id] !== undefined) {
@@ -2442,10 +2594,10 @@ export function clearLineageForEntries(controlDir, entryIds) {
2442
2594
  return { ...(changed ? { next: rec } : {}), result: undefined };
2443
2595
  });
2444
2596
  }
2445
- export function captureAndClearLineageForEntries(controlDir, entryIds) {
2597
+ export async function captureAndClearLineageForEntries(docs, entryIds) {
2446
2598
  if (entryIds.length === 0)
2447
2599
  return new Map();
2448
- return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2600
+ return docs.updateDoc("lineage", coerceLineage, (rec) => {
2449
2601
  const want = new Set(entryIds);
2450
2602
  const captured = new Map();
2451
2603
  const add = (id, sessionId) => {
@@ -2481,10 +2633,10 @@ export function captureAndClearLineageForEntries(controlDir, entryIds) {
2481
2633
  return { ...(changed ? { next: rec } : {}), result };
2482
2634
  });
2483
2635
  }
2484
- export function importLineageCommitted(controlDir, rows) {
2636
+ export async function importLineageCommitted(docs, rows) {
2485
2637
  if (rows.length === 0)
2486
2638
  return [];
2487
- return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
2639
+ return docs.updateDoc("lineage", coerceLineage, (rec) => {
2488
2640
  const divergence = [];
2489
2641
  let changed = false;
2490
2642
  for (const row of rows) {
@@ -2508,8 +2660,8 @@ export function importLineageCommitted(controlDir, rows) {
2508
2660
  return { ...(changed ? { next: rec } : {}), result: divergence };
2509
2661
  });
2510
2662
  }
2511
- export function readLineageRecord(controlDir) {
2512
- const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
2663
+ export async function readLineageRecord(docs) {
2664
+ const rec = coerceLineage(await docs.readDoc("lineage"));
2513
2665
  return { committed: rec.committed, pending: rec.pending };
2514
2666
  }
2515
2667
  export function appendLineageAudit(controlDir, rows) {
@@ -2547,10 +2699,10 @@ function coerceChallenges(raw) {
2547
2699
  return raw;
2548
2700
  }
2549
2701
  export const CHALLENGE_LEDGER_MAX_EVENTS = 10_000;
2550
- export function appendChallengeEvents(controlDir, events, now) {
2702
+ export async function appendChallengeEvents(docs, events, now) {
2551
2703
  if (events.length === 0)
2552
2704
  return { assignments: [], eventCount: undefined };
2553
- return lockedStrictUpdate(controlDir, CHALLENGES_FILE, "memory challenge ledger", coerceChallenges, (rec) => {
2705
+ return docs.updateDoc("challenges", coerceChallenges, (rec) => {
2554
2706
  const byEventId = new Map(rec.events.map((e) => [e.eventId, e]));
2555
2707
  const maxGen = new Map();
2556
2708
  for (const e of rec.events) {
@@ -2586,8 +2738,8 @@ export function appendChallengeEvents(controlDir, events, now) {
2586
2738
  return { ...(changed ? { next: rec } : {}), result: { assignments: out, eventCount: rec.events.length } };
2587
2739
  });
2588
2740
  }
2589
- export function resolveChallengeEvent(controlDir, entryId, generation, reason, now, requestId) {
2590
- return lockedStrictUpdate(controlDir, CHALLENGES_FILE, "memory challenge ledger", coerceChallenges, (rec) => {
2741
+ export async function resolveChallengeEvent(docs, entryId, generation, reason, now, requestId) {
2742
+ return docs.updateDoc("challenges", coerceChallenges, (rec) => {
2591
2743
  const opened = rec.events.some((e) => e.kind === "challenge" && e.entryId === entryId && e.generation === generation);
2592
2744
  if (!opened)
2593
2745
  return { result: { resolved: false, eventCount: undefined } };
@@ -2605,8 +2757,8 @@ export function resolveChallengeEvent(controlDir, entryId, generation, reason, n
2605
2757
  return { next: rec, result: { resolved: true, eventCount: rec.events.length } };
2606
2758
  });
2607
2759
  }
2608
- export function challengedEntryIds(controlDir) {
2609
- const rec = coerceChallenges(readStrictSidecar(controlDir, CHALLENGES_FILE, "memory challenge ledger"));
2760
+ export async function challengedEntryIds(docs) {
2761
+ const rec = coerceChallenges(await docs.readDoc("challenges"));
2610
2762
  const resolved = new Set();
2611
2763
  for (const e of rec.events)
2612
2764
  if (e.kind === "resolve")
@@ -2621,13 +2773,17 @@ export function challengedEntryIds(controlDir) {
2621
2773
  }
2622
2774
  return out;
2623
2775
  }
2624
- export function readChallengeEvents(controlDir) {
2625
- return coerceChallenges(readStrictSidecar(controlDir, CHALLENGES_FILE, "memory challenge ledger")).events;
2776
+ export async function readChallengeEvents(docs) {
2777
+ return coerceChallenges(await docs.readDoc("challenges")).events;
2626
2778
  }
2779
+ const STRICT_LEDGER_SHAPES = Object.freeze({
2780
+ lineage: Object.freeze({ coerce: (raw) => coerceLineage(raw), empty: () => ({ version: 1, committed: {}, pending: {} }) }),
2781
+ challenges: Object.freeze({ coerce: (raw) => coerceChallenges(raw), empty: () => ({ version: 1, events: [] }) }),
2782
+ });
2783
+ export const STRICT_CONTROL_PLANE_LEDGERS = Object.freeze(Object.keys(STRICT_LEDGER_SHAPES));
2627
2784
  export function isStrictControlPlaneLedgerCorrupt(controlDir, ledger) {
2628
- const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
2629
- const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
2630
- const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
2785
+ const { file: fileName, what } = fileGovernanceDocOf(ledger);
2786
+ const { coerce } = STRICT_LEDGER_SHAPES[ledger];
2631
2787
  try {
2632
2788
  coerce(readStrictSidecar(controlDir, fileName, what));
2633
2789
  return false;
@@ -2639,10 +2795,9 @@ export function isStrictControlPlaneLedgerCorrupt(controlDir, ledger) {
2639
2795
  }
2640
2796
  }
2641
2797
  export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
2642
- const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
2643
- const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
2644
- const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
2645
- const empty = ledger === "lineage" ? { version: 1, committed: {}, pending: {} } : { version: 1, events: [] };
2798
+ const { file: fileName, what } = fileGovernanceDocOf(ledger);
2799
+ const { coerce } = STRICT_LEDGER_SHAPES[ledger];
2800
+ const empty = STRICT_LEDGER_SHAPES[ledger].empty();
2646
2801
  ensureDirExists(controlDir);
2647
2802
  const file = join(controlDir, fileName);
2648
2803
  const journal = `${file}.journal`;
@@ -2849,7 +3004,7 @@ export function writeAllSync(fd, data) {
2849
3004
  }
2850
3005
  export function atomicWriteFileSync(path, data) {
2851
3006
  ensureDirExists(dirname(path));
2852
- const tmp = join(dirname(path), `.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
3007
+ const tmp = join(dirname(path), `${ATOMIC_WRITE_TMP_PREFIX}${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
2853
3008
  const fd = openSync(tmp, O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW, 0o600);
2854
3009
  try {
2855
3010
  writeAllSync(fd, data);