@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
@@ -4,6 +4,7 @@ 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
6
  import { MEMORY_GOVERNANCE_DOC_NAMES, MEMORY_ORIGIN_CAUSES } from "./types.js";
7
+ import { parseEntryFile } from "./frontmatter.js";
7
8
  import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
8
9
  import { thrownLabel, thrownText } from "../thrown-value.js";
9
10
  import { egressText } from "../untrusted-egress.js";
@@ -748,9 +749,10 @@ export function isContainedIn(root, child) {
748
749
  const c = canonicalize(child);
749
750
  return c === r || c.startsWith(`${r}${sep}`);
750
751
  }
751
- export const STORE_FORM_REFUSAL_CODES = Object.freeze(["memory.target_outside_store", "memory.scope_home_not_directory"]);
752
+ export const STORE_FORM_REFUSAL_CODES = Object.freeze(["memory.target_outside_store", "memory.scope_home_not_directory", "memory.control_plane_links_unsupported"]);
752
753
  export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
753
754
  export const SCOPE_HOME_NOT_DIRECTORY = "memory.scope_home_not_directory";
755
+ export const CONTROL_PLANE_LINKS_UNSUPPORTED = "memory.control_plane_links_unsupported";
754
756
  export const SCOPE_HOME_FORMS = Object.freeze(["symlink", "file", "other"]);
755
757
  const SCOPE_HOME_FORM_PHRASE = {
756
758
  symlink: "a symbolic link",
@@ -775,6 +777,9 @@ export function storeRootAbsentRefusal(path, anchor) {
775
777
  export function scopeHomeRefusal(form, path) {
776
778
  return storeFormRefusal(SCOPE_HOME_NOT_DIRECTORY, `a scope home must be a real directory, but this one is ${SCOPE_HOME_FORM_PHRASE[form]} — refused (fail-closed); put the real directory back`, { path, form });
777
779
  }
780
+ export function controlPlaneLinksRefusal(path, fault) {
781
+ return storeFormRefusal(CONTROL_PLANE_LINKS_UNSUPPORTED, `the memory control plane is on a file system that cannot make hard links (link answered ${fault ?? "an error with no code"}) — the store publishes its control objects (quarantine copies, held files, pollution markers) with link, so it is not opened and no entry or control object was written; move the control plane (controlDir, or the memory engine root) to a volume that supports hard links`, { path });
782
+ }
778
783
  export function landingPathOf(p) {
779
784
  return landingPathWithin(resolve(p), 0);
780
785
  }
@@ -1313,31 +1318,109 @@ export function restoreContainedBaseline(path, committed, leftOnPlane) {
1313
1318
  }
1314
1319
  }
1315
1320
  let quarantineSeq = 0;
1316
- export function quarantineAndTombstone(path, content, quarantineDir, now) {
1317
- let captured;
1318
- let detail;
1319
- try {
1320
- ensureDirExists(quarantineDir);
1321
- const base = `${now()}-${basename(path)}`;
1322
- for (let attempt = 0; captured === undefined && attempt < 10; attempt++) {
1323
- const candidate = join(quarantineDir, attempt === 0 ? base : `${base}.${attempt}`);
1324
- try {
1325
- writeFileSync(candidate, content, { encoding: "utf8", flag: "wx" });
1326
- captured = candidate;
1327
- }
1328
- catch (err) {
1329
- if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
1330
- throw err;
1331
- }
1321
+ export async function putControlObjectOnce(objects, kind, name, bytes) {
1322
+ try {
1323
+ return await objects.putObject(kind, name, bytes);
1324
+ }
1325
+ catch (err) {
1326
+ let standing;
1327
+ try {
1328
+ standing = await objects.getObject(kind, name);
1332
1329
  }
1333
- if (captured === undefined) {
1334
- const last = join(quarantineDir, `${base}.${process.pid}.${quarantineSeq++}`);
1335
- writeFileSync(last, content, { encoding: "utf8", flag: "wx" });
1336
- captured = last;
1330
+ catch {
1331
+ throw err;
1332
+ }
1333
+ if (standing === undefined)
1334
+ throw err;
1335
+ return "existed";
1336
+ }
1337
+ }
1338
+ export function quarantineCaptureName(base, attempt) {
1339
+ return attempt === 0 ? base : attempt < 10 ? `${base}.${attempt}` : `${base}.${process.pid}.${quarantineSeq++}`;
1340
+ }
1341
+ export function quarantineCaptureBase(path, now) {
1342
+ return `${now()}-${basename(path).replace(/\\/g, "%5C")}`;
1343
+ }
1344
+ export async function captureIntoQuarantine(objects, path, content, now) {
1345
+ const bytes = new TextEncoder().encode(content);
1346
+ const base = quarantineCaptureBase(path, now);
1347
+ try {
1348
+ for (let attempt = 0; attempt <= 10; attempt++) {
1349
+ const name = quarantineCaptureName(base, attempt);
1350
+ if ((await putControlObjectOnce(objects, "quarantine", name, bytes)) === "created")
1351
+ return { name };
1337
1352
  }
1353
+ return { failed: "quarantine copy failed: every capture name already stands" };
1354
+ }
1355
+ catch (err) {
1356
+ return { failed: `quarantine copy failed: ${thrownText(err)}` };
1357
+ }
1358
+ }
1359
+ export async function eraseQuarantineCopies(objects, ids) {
1360
+ let listed;
1361
+ try {
1362
+ listed = await objects.listObjects("quarantine");
1338
1363
  }
1339
1364
  catch (err) {
1340
- detail = `quarantine copy failed: ${thrownText(err)}`;
1365
+ throw new ControlPlaneCorruptError(`memory erasure: the quarantine objects could not be listed (${thrownText(err)}) — the attestation must not silently claim an empty residual set; retry after the store's fault clears (the deletions themselves are committed and a replay converges)`, { cause: err });
1366
+ }
1367
+ if (!Array.isArray(listed) || !Array.from(listed).every((name) => typeof name === "string")) {
1368
+ throw new ControlPlaneCorruptError("memory erasure: the store's listing of its quarantine objects is not a list of names — the attestation must not silently claim an empty residual set; retry after the store's fault clears (the deletions themselves are committed and a replay converges)");
1369
+ }
1370
+ const out = { removed: 0, remaining: 0, unreadable: 0, unattributed: 0 };
1371
+ for (const name of new Set(listed)) {
1372
+ let text;
1373
+ try {
1374
+ const bytes = await objects.getObject("quarantine", name);
1375
+ if (bytes === undefined)
1376
+ continue;
1377
+ text = new TextDecoder().decode(bytes);
1378
+ }
1379
+ catch {
1380
+ text = undefined;
1381
+ }
1382
+ if (text === undefined) {
1383
+ out.remaining++;
1384
+ out.unreadable++;
1385
+ continue;
1386
+ }
1387
+ const id = parseEntryFile(text).id;
1388
+ if (id === undefined) {
1389
+ out.unattributed++;
1390
+ continue;
1391
+ }
1392
+ if (!ids.has(id))
1393
+ continue;
1394
+ try {
1395
+ const deleted = await objects.deleteObject("quarantine", name);
1396
+ if (deleted === true)
1397
+ out.removed++;
1398
+ else if (deleted !== false)
1399
+ out.remaining++;
1400
+ }
1401
+ catch {
1402
+ out.remaining++;
1403
+ }
1404
+ }
1405
+ return out;
1406
+ }
1407
+ export function clearContainedPath(path, content, capture) {
1408
+ const captured = "name" in capture ? capture.name : undefined;
1409
+ let detail = "failed" in capture ? capture.failed : undefined;
1410
+ let onDisk;
1411
+ try {
1412
+ onDisk = readFileSync(path, "utf8");
1413
+ }
1414
+ catch {
1415
+ onDisk = undefined;
1416
+ }
1417
+ if (onDisk !== undefined && onDisk !== content) {
1418
+ return {
1419
+ ...(captured !== undefined ? { dest: captured } : {}),
1420
+ removed: false,
1421
+ leftOnPlane: content,
1422
+ detail: `${detail !== undefined ? `${detail}; ` : ""}the file was rewritten after it was read — the newer bytes are not the captured copy and were left in place`,
1423
+ };
1341
1424
  }
1342
1425
  let left = content;
1343
1426
  let removed = false;
@@ -1364,11 +1447,32 @@ export function quarantineAndTombstone(path, content, quarantineDir, now) {
1364
1447
  ...(detail !== undefined ? { detail } : {}),
1365
1448
  };
1366
1449
  }
1450
+ export async function keepCopiesBeforeOverwrite(text, keep, reread) {
1451
+ const failed = [];
1452
+ let held = text;
1453
+ for (let copies = 0; copies < 3; copies++) {
1454
+ const outcome = await keep(held);
1455
+ if (outcome !== true)
1456
+ failed.push(outcome);
1457
+ let onDisk;
1458
+ try {
1459
+ onDisk = reread();
1460
+ }
1461
+ catch (err) {
1462
+ return { landed: false, failed: [...failed, `the file could not be read again after its copy: ${thrownText(err)}`] };
1463
+ }
1464
+ if (onDisk === undefined || onDisk === held)
1465
+ return { landed: failed.length === 0, failed };
1466
+ held = onDisk;
1467
+ }
1468
+ return { landed: false, failed: [...failed, "the file kept being rewritten while its copy was kept — its last version was not captured"] };
1469
+ }
1367
1470
  export const ATOMIC_WRITE_TMP_PREFIX = ".tmp-";
1471
+ export const LINK_PROBE_PREFIX = ".link-probe-";
1368
1472
  export const LOCK_TOMB_INFIX = ".stale-";
1369
1473
  export const STORE_OPEN_ARTIFACTS = Object.freeze({
1370
1474
  files: Object.freeze([ROOT_ANCHOR_FILE, SCOPES_FILE, `${SCOPES_FILE}.journal`]),
1371
- filePrefixes: Object.freeze([ATOMIC_WRITE_TMP_PREFIX]),
1475
+ filePrefixes: Object.freeze([ATOMIC_WRITE_TMP_PREFIX, LINK_PROBE_PREFIX]),
1372
1476
  lockDirs: Object.freeze([`${ROOT_ANCHOR_FILE}.lock`, `${SCOPES_FILE}.lock`, STORE_TXN_LOCK_DIR]),
1373
1477
  memoryFilePrefixes: Object.freeze([CASEFOLD_PROBE_PREFIX]),
1374
1478
  });
@@ -1914,8 +2018,10 @@ export function usableSessionIncarnation(raw) {
1914
2018
  return isIncarnationSeat(raw) ? raw : undefined;
1915
2019
  }
1916
2020
  function sessionRecordPath(controlDir, dir, sessionId, incarnation) {
1917
- const name = incarnation === undefined ? `${encodeURIComponent(sessionId)}.json` : `${encodeURIComponent(sessionId)}@${encodeURIComponent(incarnation)}.json`;
1918
- return join(controlDir, dir, name);
2021
+ return join(controlDir, dir, sessionRecordName(sessionId, incarnation));
2022
+ }
2023
+ function sessionRecordName(sessionId, incarnation) {
2024
+ return incarnation === undefined ? `${encodeURIComponent(sessionId)}.json` : `${encodeURIComponent(sessionId)}@${encodeURIComponent(incarnation)}.json`;
1919
2025
  }
1920
2026
  function standingOwnerAt(path) {
1921
2027
  let raw;
@@ -1992,38 +2098,72 @@ function sessionIdOfRecordName(name) {
1992
2098
  }
1993
2099
  }
1994
2100
  export const SESSION_POLLUTION_DIR = "session-pollution";
1995
- function pollutionPath(controlDir, sessionId, incarnation) {
1996
- return sessionRecordPath(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation);
1997
- }
1998
- export function markSessionPolluted(controlDir, sessionId, reason, now, cause, incarnation) {
2101
+ export async function markSessionPolluted(objects, sessionId, reason, now, cause, incarnation) {
1999
2102
  const record = { at: now(), reason, ...(cause !== undefined ? { cause } : {}), ...(incarnation !== undefined ? { incarnation } : {}) };
2000
- return mintSessionRecordSlots(controlDir, SESSION_POLLUTION_DIR, sessionId, incarnation, `${JSON.stringify(record, null, 2)}\n`);
2103
+ return mintPollutionSlots(objects, sessionId, incarnation, new TextEncoder().encode(`${JSON.stringify(record, null, 2)}\n`));
2104
+ }
2105
+ async function mintPollutionSlots(objects, sessionId, incarnation, bytes) {
2106
+ try {
2107
+ if ((await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId), bytes)) === "created")
2108
+ return "created";
2109
+ }
2110
+ catch {
2111
+ return "unpersisted";
2112
+ }
2113
+ const own = usableSessionIncarnation(incarnation);
2114
+ const standing = await pollutionOwnerOf(objects, sessionRecordName(sessionId));
2115
+ const vouches = standing !== "unattributable" && (standing.owner === undefined || standing.owner === own);
2116
+ const unnamed = vouches || own === undefined ? undefined : await pollutionOwnerOf(objects, sessionRecordName(sessionId, ""));
2117
+ if (vouches || (unnamed !== undefined && unnamed !== "unattributable" && unnamed.owner === undefined))
2118
+ return "existed";
2119
+ try {
2120
+ return (await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId, own ?? ""), bytes)) === "created" ? "created" : "existed";
2121
+ }
2122
+ catch {
2123
+ return "unpersisted";
2124
+ }
2001
2125
  }
2002
- export function readSessionPollution(controlDir, sessionId, identity) {
2126
+ async function pollutionOwnerOf(objects, name) {
2127
+ let bytes;
2128
+ try {
2129
+ bytes = await objects.getObject("pollution", name);
2130
+ }
2131
+ catch {
2132
+ return "unattributable";
2133
+ }
2134
+ if (bytes === undefined)
2135
+ return "unattributable";
2136
+ try {
2137
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
2138
+ if (parsed !== null && typeof parsed === "object")
2139
+ return { owner: readIncarnationSeat(parsed) };
2140
+ }
2141
+ catch {
2142
+ }
2143
+ return "unattributable";
2144
+ }
2145
+ export async function readSessionPollution(objects, sessionId, identity) {
2003
2146
  const asking = usableSessionIncarnation(identity?.incarnation);
2004
2147
  if (asking !== undefined) {
2005
- const own = readPollutionAt(pollutionPath(controlDir, sessionId, asking));
2148
+ const own = await readPollutionObject(objects, sessionRecordName(sessionId, asking));
2006
2149
  if (own !== undefined)
2007
2150
  return own;
2008
2151
  }
2009
- const unnamedSlot = () => readPollutionAt(pollutionPath(controlDir, sessionId, ""));
2010
- const standing = readPollutionAt(pollutionPath(controlDir, sessionId));
2011
- return standing === undefined ? unnamedSlot() : bindOrSeparate(standing, identity, asking, unnamedSlot);
2152
+ const unnamed = await readPollutionObject(objects, sessionRecordName(sessionId, ""));
2153
+ const standing = await readPollutionObject(objects, sessionRecordName(sessionId));
2154
+ return standing === undefined ? unnamed : bindOrSeparate(standing, identity, asking, () => unnamed);
2012
2155
  }
2013
- function readPollutionAt(path) {
2014
- let raw;
2156
+ async function readPollutionObject(objects, name) {
2157
+ let bytes;
2015
2158
  try {
2016
- raw = readFileSync(path, "utf8");
2159
+ bytes = await objects.getObject("pollution", name);
2017
2160
  }
2018
2161
  catch {
2019
- try {
2020
- lstatSync(path);
2021
- }
2022
- catch {
2023
- return undefined;
2024
- }
2025
2162
  return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
2026
2163
  }
2164
+ return bytes === undefined ? undefined : pollutionRecordOf(new TextDecoder().decode(bytes));
2165
+ }
2166
+ function pollutionRecordOf(raw) {
2027
2167
  try {
2028
2168
  const parsed = JSON.parse(raw);
2029
2169
  if (parsed !== null && typeof parsed === "object") {
@@ -2040,40 +2180,24 @@ function readPollutionAt(path) {
2040
2180
  }
2041
2181
  return { at: 0, reason: "pollution marker present but unreadable (kept fail-closed)" };
2042
2182
  }
2043
- export function listSessionPollution(controlDir) {
2044
- const dir = join(controlDir, SESSION_POLLUTION_DIR);
2045
- let names;
2046
- try {
2047
- names = readdirSync(dir);
2048
- }
2049
- catch (err) {
2050
- if (err.code === "ENOENT")
2051
- return {};
2052
- throw new ControlPlaneCorruptError(`session pollution markers could not be enumerated (${err.code ?? "io error"}) at ${dir} — an enumeration failure is not an empty set (fail-closed)`, { cause: err });
2053
- }
2183
+ export async function listSessionPollution(objects) {
2184
+ const names = await objects.listObjects("pollution");
2054
2185
  const out = Object.create(null);
2055
- for (const name of names.sort()) {
2186
+ for (const name of [...names].sort()) {
2056
2187
  const sessionId = sessionIdOfRecordName(name);
2057
2188
  if (sessionId === undefined || Object.prototype.hasOwnProperty.call(out, sessionId))
2058
2189
  continue;
2059
- const rec = readPollutionAt(join(dir, name));
2190
+ const rec = await readPollutionObject(objects, name);
2060
2191
  if (rec !== undefined)
2061
2192
  out[sessionId] = rec;
2062
2193
  }
2063
2194
  return out;
2064
2195
  }
2065
- export function importSessionPollution(controlDir, sessionId, record) {
2066
- const path = pollutionPath(controlDir, sessionId);
2067
- ensureDirExists(dirname(path));
2068
- try {
2069
- writeFileSync(path, `${JSON.stringify({ at: record.at, reason: record.reason, ...(record.cause !== undefined ? { cause: record.cause } : {}) }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
2196
+ export async function importSessionPollution(objects, sessionId, record) {
2197
+ const text = `${JSON.stringify({ at: record.at, reason: record.reason, ...(record.cause !== undefined ? { cause: record.cause } : {}) }, null, 2)}\n`;
2198
+ if ((await putControlObjectOnce(objects, "pollution", sessionRecordName(sessionId), new TextEncoder().encode(text))) === "created")
2070
2199
  return "written";
2071
- }
2072
- catch (err) {
2073
- if (!(err instanceof Error && "code" in err && err.code === "EEXIST"))
2074
- throw err;
2075
- }
2076
- const standing = readSessionPollution(controlDir, sessionId);
2200
+ const standing = await readSessionPollution(objects, sessionId);
2077
2201
  return standing !== undefined && standing.at === record.at && standing.reason === record.reason ? "already" : "divergent";
2078
2202
  }
2079
2203
  export const SESSION_CAPTURE_OPTOUT_DIR = "session-capture-optout";
@@ -2228,6 +2352,8 @@ const FILE_GOVERNANCE_DOCS = Object.freeze({
2228
2352
  settlements: Object.freeze({ file: DELEGATION_SETTLEMENT_FILE, what: "memory delegation-settlement ledger" }),
2229
2353
  "session-accounts": Object.freeze({ file: SESSION_ACCOUNTS_FILE, what: "memory session-account ledger" }),
2230
2354
  announcements: Object.freeze({ file: ANNOUNCEMENTS_FILE, what: "memory announcement queue" }),
2355
+ holds: Object.freeze({ file: "holds.json", what: "memory instruction-hold ledger" }),
2356
+ "origin-clearances": Object.freeze({ file: "origin-clearances.json", what: "memory origin-clearance ledger" }),
2231
2357
  });
2232
2358
  export function fileGovernanceDocOf(name) {
2233
2359
  if (typeof name !== "string" || !Object.prototype.hasOwnProperty.call(FILE_GOVERNANCE_DOCS, name)) {
@@ -2495,8 +2621,8 @@ export const IMPORT_RECEIPTS_DIR = "import-receipts";
2495
2621
  export function importLatchTxnId(bundleHash) {
2496
2622
  return `import:${bundleHash}`;
2497
2623
  }
2498
- function importReceiptPath(controlDir, bundleHash) {
2499
- return join(controlDir, IMPORT_RECEIPTS_DIR, `${bundleHash}.json`);
2624
+ export function importReceiptName(bundleHash) {
2625
+ return `${bundleHash}.json`;
2500
2626
  }
2501
2627
  export async function stageImportLatch(docs, bundleHash, rows, now) {
2502
2628
  const txnId = importLatchTxnId(bundleHash);
@@ -2515,27 +2641,23 @@ export async function stageImportLatch(docs, bundleHash, rows, now) {
2515
2641
  });
2516
2642
  return txnId;
2517
2643
  }
2518
- export async function releaseImportLatch(docs, controlDir, txnId) {
2644
+ export async function releaseImportLatch(store, txnId) {
2519
2645
  const prefix = "import:";
2520
2646
  if (!txnId.startsWith(prefix) || !/^[0-9a-f]{64}$/.test(txnId.slice(prefix.length))) {
2521
2647
  throw new ControlPlaneCorruptError(`releaseImportLatch: ${JSON.stringify(txnId)} is not an import-latch transaction id (import:<64-hex bundleHash>)`);
2522
2648
  }
2523
- const receipt = importReceiptPath(controlDir, txnId.slice(prefix.length));
2524
- let receiptPresent;
2649
+ const receipt = importReceiptName(txnId.slice(prefix.length));
2650
+ let bytes;
2525
2651
  try {
2526
- readFileSync(receipt);
2527
- receiptPresent = true;
2652
+ bytes = await store.getObject("import-receipt", receipt);
2528
2653
  }
2529
2654
  catch (err) {
2530
- if (err.code !== "ENOENT") {
2531
- throw new ControlPlaneCorruptError(`releaseImportLatch: the completion receipt at ${receipt} could not be read (${err.code ?? "io error"}) — a probe failure is not absence (fail-closed), and absence would refuse the release`, { cause: err });
2532
- }
2533
- receiptPresent = false;
2655
+ throw new ControlPlaneCorruptError(`releaseImportLatch: the completion receipt ${receipt} could not be read (${thrownText(err)}) — a probe failure is not absence (fail-closed), and absence would refuse the release`, { cause: err });
2534
2656
  }
2535
- if (!receiptPresent) {
2536
- 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`);
2657
+ if (bytes === undefined) {
2658
+ throw new ControlPlaneCorruptError(`releaseImportLatch: no completion receipt ${receipt} — the import's governance legs are not proven landed, the latch stays; re-run the same bundle import to converge`);
2537
2659
  }
2538
- await docs.updateDoc("lineage", coerceLineage, (rec) => {
2660
+ await store.updateDoc("lineage", coerceLineage, (rec) => {
2539
2661
  const txn = rec.pending[txnId];
2540
2662
  if (txn === undefined)
2541
2663
  return { result: undefined };
@@ -2774,10 +2896,14 @@ export async function challengedEntryIds(docs) {
2774
2896
  export async function readChallengeEvents(docs) {
2775
2897
  return coerceChallenges(await docs.readDoc("challenges")).events;
2776
2898
  }
2899
+ const STRICT_LEDGER_SHAPES = Object.freeze({
2900
+ lineage: Object.freeze({ coerce: (raw) => coerceLineage(raw), empty: () => ({ version: 1, committed: {}, pending: {} }) }),
2901
+ challenges: Object.freeze({ coerce: (raw) => coerceChallenges(raw), empty: () => ({ version: 1, events: [] }) }),
2902
+ });
2903
+ export const STRICT_CONTROL_PLANE_LEDGERS = Object.freeze(Object.keys(STRICT_LEDGER_SHAPES));
2777
2904
  export function isStrictControlPlaneLedgerCorrupt(controlDir, ledger) {
2778
- const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
2779
- const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
2780
- const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
2905
+ const { file: fileName, what } = fileGovernanceDocOf(ledger);
2906
+ const { coerce } = STRICT_LEDGER_SHAPES[ledger];
2781
2907
  try {
2782
2908
  coerce(readStrictSidecar(controlDir, fileName, what));
2783
2909
  return false;
@@ -2789,10 +2915,9 @@ export function isStrictControlPlaneLedgerCorrupt(controlDir, ledger) {
2789
2915
  }
2790
2916
  }
2791
2917
  export function rebuildStrictControlPlaneLedger(controlDir, ledger, now) {
2792
- const fileName = ledger === "lineage" ? LINEAGE_FILE : CHALLENGES_FILE;
2793
- const what = ledger === "lineage" ? "memory lineage ledger" : "memory challenge ledger";
2794
- const coerce = ledger === "lineage" ? coerceLineage : coerceChallenges;
2795
- const empty = ledger === "lineage" ? { version: 1, committed: {}, pending: {} } : { version: 1, events: [] };
2918
+ const { file: fileName, what } = fileGovernanceDocOf(ledger);
2919
+ const { coerce } = STRICT_LEDGER_SHAPES[ledger];
2920
+ const empty = STRICT_LEDGER_SHAPES[ledger].empty();
2796
2921
  ensureDirExists(controlDir);
2797
2922
  const file = join(controlDir, fileName);
2798
2923
  const journal = `${file}.journal`;
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Render a memory entry's age as a natural-language phrase (CC-parity P0-1). CC's eval found
3
+ * models reason about memory age much better from natural language ("3 days ago") than from a boolean
4
+ * "older note" flag (verify-claims 0/2 → 3/3 once the age was spelled out), because the model can weigh
5
+ * staleness proportionally instead of as a single cliff. This is the relative phrase only; it is additional
6
+ * signal beside the entry, not a verdict on it.
7
+ *
8
+ * Buckets (each chooses the coarsest unit that's ≥1): `today` (<1 day, incl. future mtime / clock skew →
9
+ * clamped to today, never a negative age), `yesterday` (1–2 days), `N days ago` (2–7 days),
10
+ * `N weeks ago` (1 week – ~1 month), `N months ago` (≥ ~1 month). N is floored to the whole unit.
11
+ */
12
+ export declare function formatMemoryAge(ageMs: number): string;
@@ -0,0 +1,17 @@
1
+ const ONE_DAY_MS = 24 * 60 * 60 * 1_000;
2
+ const ONE_WEEK_MS = 7 * ONE_DAY_MS;
3
+ const ONE_MONTH_MS = 30.44 * ONE_DAY_MS;
4
+ export function formatMemoryAge(ageMs) {
5
+ if (ageMs < ONE_DAY_MS)
6
+ return "today";
7
+ if (ageMs < 2 * ONE_DAY_MS)
8
+ return "yesterday";
9
+ if (ageMs < ONE_WEEK_MS)
10
+ return `${Math.floor(ageMs / ONE_DAY_MS)} days ago`;
11
+ if (ageMs < ONE_MONTH_MS) {
12
+ const weeks = Math.floor(ageMs / ONE_WEEK_MS);
13
+ return `${weeks} ${weeks === 1 ? "week" : "weeks"} ago`;
14
+ }
15
+ const months = Math.floor(ageMs / ONE_MONTH_MS);
16
+ return `${months} ${months === 1 ? "month" : "months"} ago`;
17
+ }
@@ -1,4 +1,4 @@
1
- import { type MemoryBackend, type MemoryGovernanceDocName, type MemoryGovernanceStore } from "./types.js";
1
+ import { type MemoryBackend, type MemoryControlObjectKind, type MemoryGovernanceDocName, type MemoryGovernanceStore } from "./types.js";
2
2
  export interface MemoryBackendContractHooks {
3
3
  make: () => Promise<MemoryBackend> | MemoryBackend;
4
4
  /** A second backend instance over the SAME storage as the given one (cross-instance CAS cases). */
@@ -33,8 +33,15 @@ export interface MemoryGovernanceStoreContractHooks {
33
33
  make: () => Promise<MemoryGovernanceStore> | MemoryGovernanceStore;
34
34
  /** Leave `store`'s record of `record` malformed in its own storage (bytes that are not the record's shape — for a
35
35
  * governance document, bytes that do not parse): the fail-closed cases read it back and must be refused, never read
36
- * as an empty record. */
37
- corrupt: (store: MemoryGovernanceStore, record: "gate" | "intents" | "run" | MemoryGovernanceDocName) => Promise<void> | void;
36
+ * as an empty record. For a control object, leave `{ object, name }` standing but unreadable (the File store: a
37
+ * directory or a link to nothing in its place), and `{ listing }` a kind whose names cannot be enumerated (the File
38
+ * store: a file where the kind's directory is). */
39
+ corrupt: (store: MemoryGovernanceStore, record: "gate" | "intents" | "run" | MemoryGovernanceDocName | {
40
+ readonly object: MemoryControlObjectKind;
41
+ readonly name: string;
42
+ } | {
43
+ readonly listing: MemoryControlObjectKind;
44
+ }) => Promise<void> | void;
38
45
  /** Wrap each case (vitest `it`, …). Default: run sequentially. */
39
46
  runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
40
47
  }