@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
@@ -1,7 +1,12 @@
1
1
  import assert from "node:assert";
2
+ import { mkdtempSync, rmSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import { join } from "node:path";
2
5
  import { computeEntryRev } from "./frontmatter.js";
3
- import { MEMORY_GOVERNANCE_DOC_NAMES } from "./types.js";
4
- import { ControlPlaneCorruptError } from "./layout.js";
6
+ import { MEMORY_CONTROL_OBJECT_KINDS, MEMORY_GOVERNANCE_DOC_NAMES } from "./types.js";
7
+ import { ControlPlaneCorruptError, STRICT_CONTROL_PLANE_LEDGERS } from "./layout.js";
8
+ import { fileGovernanceStore } from "./consolidation.js";
9
+ import { adoptReplicaControlPlane, readControlPlaneAdoptionReceipt, replicaControlPlaneStrays } from "./control-plane-adoption.js";
5
10
  function entry(id, scope, slug, body, fm = {}) {
6
11
  const e = { id, scope, slug, frontmatter: { ...fm }, body, rev: "" };
7
12
  e.rev = computeEntryRev(e);
@@ -1181,6 +1186,158 @@ export async function memoryGovernanceStoreContract(hooks) {
1181
1186
  await assert.rejects(s.readDoc("lineage.json"));
1182
1187
  await assert.rejects(s.updateDoc("__proto__", judgeDoc, (cur) => ({ next: cur, result: undefined })));
1183
1188
  });
1189
+ defer("the ledgers a host may rebuild are governance documents the store keeps", async () => {
1190
+ const s = await hooks.make();
1191
+ for (const ledger of STRICT_CONTROL_PLANE_LEDGERS) {
1192
+ assert.ok(MEMORY_GOVERNANCE_DOC_NAMES.includes(ledger), `${ledger} is a governance document`);
1193
+ assert.strictEqual(await s.readDoc(ledger), undefined, `${ledger} before any write`);
1194
+ }
1195
+ });
1196
+ const enc = (text) => new TextEncoder().encode(text);
1197
+ const same = (a, b) => a !== undefined && b !== undefined && Buffer.from(a).equals(Buffer.from(b));
1198
+ defer("every control-object kind never written lists empty, reads absent and deletes nothing", async () => {
1199
+ const s = await hooks.make();
1200
+ for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
1201
+ assert.deepStrictEqual(await s.listObjects(kind), [], `${kind} before any write`);
1202
+ assert.strictEqual(await s.getObject(kind, "obj-1.json"), undefined, `${kind}/obj-1.json before any write`);
1203
+ assert.strictEqual(await s.deleteObject(kind, "obj-1.json"), false, `${kind}: nothing to delete`);
1204
+ }
1205
+ });
1206
+ defer("an object is written once: a second put of the same bytes answers existed, a second put of other bytes is refused, and neither changes anything", async () => {
1207
+ const s = await hooks.make();
1208
+ for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
1209
+ assert.strictEqual(await s.putObject(kind, "once.json", enc(`first ${kind}`), { scope: "s1" }), "created", `${kind}: the first put creates`);
1210
+ assert.strictEqual(await s.putObject(kind, "once.json", enc(`first ${kind}`)), "existed", `${kind}: the same bytes find it`);
1211
+ await rejectsCoded(s.putObject(kind, "once.json", enc(`second ${kind}`)), /ControlPlaneCorruptError|corrupt/i, `${kind}: other bytes over a standing name`);
1212
+ assert.ok(same(await s.getObject(kind, "once.json"), enc(`first ${kind}`)), `${kind}: the first bytes stand`);
1213
+ }
1214
+ });
1215
+ defer("each kind is its own: one name under two kinds is two objects, and a listing answers its kind's names sorted", async () => {
1216
+ const s = await hooks.make();
1217
+ await s.putObject("pollution", "b.json", enc("pollution b"));
1218
+ await s.putObject("pollution", "a.json", enc("pollution a"));
1219
+ await s.putObject("quarantine", "a.json", enc("quarantine a"));
1220
+ assert.deepStrictEqual(await s.listObjects("pollution"), ["a.json", "b.json"]);
1221
+ assert.deepStrictEqual(await s.listObjects("quarantine"), ["a.json"]);
1222
+ assert.deepStrictEqual(await s.listObjects("hold"), []);
1223
+ assert.ok(same(await s.getObject("pollution", "a.json"), enc("pollution a")));
1224
+ assert.ok(same(await s.getObject("quarantine", "a.json"), enc("quarantine a")), "no alias across kinds");
1225
+ });
1226
+ defer("an object's answers are copies: changing the bytes handed in or read back changes nothing stored", async () => {
1227
+ const s = await hooks.make();
1228
+ const bytes = enc("custody");
1229
+ await s.putObject("hold", "h.md", bytes);
1230
+ bytes[0] = 0x58;
1231
+ const read = await s.getObject("hold", "h.md");
1232
+ assert.ok(same(read, enc("custody")), "the stored object is not the caller's buffer");
1233
+ read[0] = 0x59;
1234
+ assert.ok(same(await s.getObject("hold", "h.md"), enc("custody")), "a read answer is not the stored object");
1235
+ });
1236
+ defer("a move lands the bytes at the target and drops the source, a re-run resumes, and nothing is overwritten", async () => {
1237
+ const s = await hooks.make();
1238
+ await s.putObject("hold", "cap.md", enc("captured"));
1239
+ assert.strictEqual(await s.moveObject({ kind: "hold", name: "cap.md" }, { kind: "quarantine", name: "cap-disposed.md" }), "moved");
1240
+ assert.strictEqual(await s.getObject("hold", "cap.md"), undefined, "the source is gone");
1241
+ assert.ok(same(await s.getObject("quarantine", "cap-disposed.md"), enc("captured")), "the target holds the bytes");
1242
+ assert.strictEqual(await s.moveObject({ kind: "hold", name: "cap.md" }, { kind: "quarantine", name: "cap-disposed.md" }), "already-moved", "a re-run of the same move resumes");
1243
+ await rejectsCoded(s.moveObject({ kind: "hold", name: "never.md" }, { kind: "quarantine", name: "never.md" }), /ControlPlaneCorruptError|corrupt/i, "a move with neither side standing");
1244
+ await s.putObject("hold", "x.md", enc("one"));
1245
+ await s.putObject("quarantine", "y.md", enc("two"));
1246
+ await assert.rejects(s.moveObject({ kind: "hold", name: "x.md" }, { kind: "quarantine", name: "y.md" }), "a target with other bytes is never overwritten");
1247
+ assert.ok(same(await s.getObject("hold", "x.md"), enc("one")), "the refused move leaves its source");
1248
+ assert.ok(same(await s.getObject("quarantine", "y.md"), enc("two")), "the refused move leaves its target");
1249
+ });
1250
+ defer("a delete removes the bytes and answers whether they were there", async () => {
1251
+ const s = await hooks.make();
1252
+ await s.putObject("import-receipt", "r.json", enc("receipt"));
1253
+ assert.strictEqual(await s.deleteObject("import-receipt", "r.json"), true);
1254
+ assert.strictEqual(await s.getObject("import-receipt", "r.json"), undefined);
1255
+ assert.deepStrictEqual(await s.listObjects("import-receipt"), []);
1256
+ assert.strictEqual(await s.deleteObject("import-receipt", "r.json"), false);
1257
+ assert.strictEqual(await s.putObject("import-receipt", "r.json", enc("again")), "created", "a deleted name may be written again");
1258
+ });
1259
+ defer("a kind outside the closed set, or a name that is not one opaque segment, is refused memory.control_object_unknown", async () => {
1260
+ const s = await hooks.make();
1261
+ await rejectsCoded(s.putObject("ledger", "a.json", enc("x")), "memory.control_object_unknown", "an unknown kind");
1262
+ await rejectsCoded(s.listObjects("__proto__"), "memory.control_object_unknown", "a prototype key as a kind");
1263
+ for (const name of ["", ".", "..", "a/b", "../x", "a\\b", "a\u0000b", "n".repeat(256), "中".repeat(86)]) {
1264
+ await rejectsCoded(s.putObject("pollution", name, enc("x")), "memory.control_object_unknown", `put of the name ${JSON.stringify(name)}`);
1265
+ await rejectsCoded(s.getObject("pollution", name), "memory.control_object_unknown", `get of the name ${JSON.stringify(name)}`);
1266
+ }
1267
+ assert.deepStrictEqual(await s.listObjects("pollution"), [], "a refused name gave nothing storage");
1268
+ });
1269
+ defer("an object that stands but cannot be read is refused, never read as missing; a kind that cannot be enumerated is refused, never empty", async () => {
1270
+ const s = await hooks.make();
1271
+ await s.putObject("pollution", "kept.json", enc("marker"));
1272
+ await hooks.corrupt(s, { object: "pollution", name: "standing.json" });
1273
+ await rejectsCoded(s.getObject("pollution", "standing.json"), /ControlPlaneCorruptError|corrupt/i, "an unreadable object");
1274
+ await rejectsCoded(s.putObject("pollution", "standing.json", enc("over it")), /ControlPlaneCorruptError|corrupt/i, "an unreadable object still stands: a put neither overwrites it nor answers for bytes it could not compare");
1275
+ await hooks.corrupt(s, { listing: "quarantine" });
1276
+ await rejectsCoded(s.listObjects("quarantine"), /ControlPlaneCorruptError|corrupt/i, "an enumeration that fails");
1277
+ });
1278
+ const withReplica = async (fn) => {
1279
+ const replica = mkdtempSync(join(tmpdir(), "sema-adopt-"));
1280
+ try {
1281
+ await fn(replica, fileGovernanceStore(replica));
1282
+ }
1283
+ finally {
1284
+ rmSync(replica, { recursive: true, force: true });
1285
+ }
1286
+ };
1287
+ defer("adoption: what the store lacks is written, what it holds the same converges, and the replica keeps its records beside a receipt", async () => {
1288
+ const s = await hooks.make();
1289
+ await withReplica(async (replica, file) => {
1290
+ await file.updateDoc("holds", judgeDoc, () => ({ next: { v: 1, owner: "replica", n: 1 }, result: undefined }));
1291
+ await file.putObject("hold", "cap.md", enc("captured"));
1292
+ await file.putObject("pollution", "s1.json", enc("marker"));
1293
+ await s.putObject("pollution", "s1.json", enc("marker"));
1294
+ const report = await adoptReplicaControlPlane(replica, s);
1295
+ assert.deepStrictEqual(report.refused, []);
1296
+ assert.deepStrictEqual(report.adopted.map((r) => `${r.record}:${r.outcome}`).sort(), ["doc:holds:written", "hold/cap.md:written", "pollution/s1.json:converged"]);
1297
+ assert.deepStrictEqual(await s.readDoc("holds"), { v: 1, owner: "replica", n: 1 });
1298
+ assert.ok(same(await s.getObject("hold", "cap.md"), enc("captured")));
1299
+ assert.deepStrictEqual(replicaControlPlaneStrays(replica), { docs: ["holds"], objects: { hold: 1, pollution: 1 } }, "adoption copies: the replica's records stay where the engine's readers read them");
1300
+ assert.deepStrictEqual(readControlPlaneAdoptionReceipt(replica).map((r) => r.record).sort(), ["doc:holds", "hold/cap.md", "pollution/s1.json"]);
1301
+ });
1302
+ });
1303
+ defer("adoption: a record the store holds with a different value is refused by name and left where it is; the documents wait while an object is refused", async () => {
1304
+ const s = await hooks.make();
1305
+ await withReplica(async (replica, file) => {
1306
+ await file.updateDoc("lineage", judgeDoc, () => ({ next: { v: 1, owner: "replica", n: 1 }, result: undefined }));
1307
+ await s.updateDoc("lineage", judgeDoc, () => ({ next: { v: 1, owner: "carrier", n: 7 }, result: undefined }));
1308
+ await file.updateDoc("holds", judgeDoc, () => ({ next: { v: 1, owner: "replica", n: 3 }, result: undefined }));
1309
+ await file.putObject("quarantine", "q.md", enc("replica bytes"));
1310
+ await s.putObject("quarantine", "q.md", enc("carrier bytes"));
1311
+ const report = await adoptReplicaControlPlane(replica, s);
1312
+ assert.deepStrictEqual(report.adopted, []);
1313
+ assert.deepStrictEqual(report.refused.map((r) => r.record).sort(), ["doc:holds", "doc:lineage", "quarantine/q.md"]);
1314
+ assert.strictEqual(await s.readDoc("holds"), undefined, "a document never reaches the store ahead of an object that was refused");
1315
+ assert.ok(same(await s.getObject("quarantine", "q.md"), enc("carrier bytes")));
1316
+ assert.deepStrictEqual(replicaControlPlaneStrays(replica), { docs: ["lineage", "holds"], objects: { quarantine: 1 } }, "the refused records stay in the replica");
1317
+ await s.deleteObject("quarantine", "q.md");
1318
+ const again = await adoptReplicaControlPlane(replica, s);
1319
+ assert.deepStrictEqual(again.adopted.map((r) => `${r.record}:${r.outcome}`).sort(), ["doc:holds:written", "quarantine/q.md:written"]);
1320
+ assert.deepStrictEqual(again.refused.map((r) => r.record), ["doc:lineage"]);
1321
+ assert.deepStrictEqual(await s.readDoc("lineage"), { v: 1, owner: "carrier", n: 7 }, "no merge is invented");
1322
+ assert.deepStrictEqual(replicaControlPlaneStrays(replica), { docs: ["lineage", "holds"], objects: { quarantine: 1 } }, "adoption copies: nothing leaves the replica");
1323
+ });
1324
+ });
1325
+ defer("adoption: a re-run converges — an interrupted handover converges, a finished one converges again and writes no second receipt row", async () => {
1326
+ const s = await hooks.make();
1327
+ await withReplica(async (replica, file) => {
1328
+ await file.putObject("capture", "s2.json", enc("opted out"));
1329
+ await file.updateDoc("challenges", judgeDoc, () => ({ next: { v: 1, owner: "replica", n: 2 }, result: undefined }));
1330
+ await s.putObject("capture", "s2.json", enc("opted out"));
1331
+ const first = await adoptReplicaControlPlane(replica, s);
1332
+ assert.deepStrictEqual(first.refused, []);
1333
+ assert.deepStrictEqual(first.adopted.map((r) => `${r.record}:${r.outcome}`).sort(), ["capture/s2.json:converged", "doc:challenges:written"]);
1334
+ const again = await adoptReplicaControlPlane(replica, s);
1335
+ assert.deepStrictEqual(again.refused, []);
1336
+ assert.deepStrictEqual(again.adopted.map((r) => `${r.record}:${r.outcome}`).sort(), ["capture/s2.json:converged", "doc:challenges:converged"], "a finished adoption converges again");
1337
+ assert.deepStrictEqual(readControlPlaneAdoptionReceipt(replica).map((r) => r.record).sort(), ["capture/s2.json", "doc:challenges"], "one receipt row per record");
1338
+ assert.deepStrictEqual(await s.readDoc("challenges"), { v: 1, owner: "replica", n: 2 });
1339
+ });
1340
+ });
1184
1341
  const run = hooks.runAssertion ?? (async (_name, fn) => fn());
1185
1342
  for (const [name, fn] of cases)
1186
1343
  await run(name, fn);
@@ -38,13 +38,18 @@ export interface MemoryDeploymentStore {
38
38
  type FoldedStatusKey = "captureOptedOut" | "committedCount" | "foldedCount" | "optOutSource" | "lastCaptureAt";
39
39
  /**
40
40
  * A session's memory status across every store of the deployment ({@link MemoryDeployment.sessionMemoryStatus}):
41
- * the session keys folded by {@link foldSessionMemoryStatuses}, plus each store's own answer.
41
+ * the session keys folded by {@link foldSessionMemoryStatuses}, the session's write home, plus each store's own answer.
42
42
  */
43
43
  export interface DeploymentSessionMemoryStatus extends Pick<SessionMemoryStatus, FoldedStatusKey> {
44
+ /** The directory of the session's write home: the `writeHome` of the one `planes[]` row {@link chooseSessionWriteHome}
45
+ * names, handed back unchanged — its contract states when the key is absent. The path is a directory on the engine's
46
+ * disk: a host decides whether it is the caller's to see. */
47
+ writeHome?: string;
44
48
  /** Always present: one row per store of the deployment, in store order (project plane first) — each store's
45
49
  * answer exactly as its engine gave it. The folded keys are read from these rows; a store whose answer made a
46
50
  * folded key absent is the row whose key is absent; a store-bound key (`writeHome`, the directory of the
47
- * session's write home IN that store) is answered here only. A store that could not be opened answers
51
+ * session's write home IN that store) is answered here as that store's own value, and the session-level
52
+ * `writeHome` above is one of them. A store that could not be opened answers
48
53
  * `{ optOutSource: "fault" }` (every source unreadable). With the host's capture record carrier
49
54
  * (`memoryCaptureRecordStore`) the personal plane of a directory-pinned deployment also has a row while its
50
55
  * store is not in the set, whenever its engine answers a capture fact for the session — a standing record or a
@@ -64,7 +69,7 @@ export interface MemoryDeployment {
64
69
  * set exactly when its mount holds a record: a file under `<engine root>/personal/.engine` or
65
70
  * `<engine root>/personal/memory` other than the named artifacts an open or a read leaves, matched at that place
66
71
  * and by that name only (`*` = any rest of the name): control plane top level, files `root-anchor.json` ·
67
- * `scopes.json` · `scopes.json.journal` · `.tmp-*`; control plane top level, directories as whole trees
72
+ * `scopes.json` · `scopes.json.journal` · `.tmp-*` · `.link-probe-*`; control plane top level, directories as whole trees
68
73
  * `root-anchor.json.lock` · `scopes.json.lock` · `txn.lock` · `root-anchor.json.lock.stale-*` ·
69
74
  * `scopes.json.lock.stale-*` · `txn.lock.stale-*`; memory directory top level, files `.casefold-probe-*`. A
70
75
  * directory that cannot be read, for any reason but absence (a link that leads nowhere, at it or above it, is no
@@ -96,7 +101,10 @@ export interface MemoryDeployment {
96
101
  * order, and their receipts merge into one (`mergeErasureAttestations`: `complete` only when every store's
97
102
  * receipt is; one store ⇒ its receipt as given). A
98
103
  * failure in a later store throws after an earlier store executed: that store keeps its anchor and a replay
99
- * of the same requestId converges every store.
104
+ * of the same requestId converges every store. The thrown error is the refusing store's own (class, code and cause
105
+ * unchanged); its message opens with the sentence that says which stores had executed and how many entries they had
106
+ * erased, and what follows is that store's own sentence about itself — so "nothing was deleted" in it is never read
107
+ * as the request's. A refusal in the first store executed nothing and says only its own sentence.
100
108
  *
101
109
  * @contract memory.erasure.request_per_deployment — an erasure requestId names one request in the whole
102
110
  * deployment: its record is the anchor of the store that executed it, every store is read for that anchor
@@ -5,6 +5,7 @@ import { acquireStoreTxnLock, assertStoreTxnLockOwnership, ControlPlaneCorruptEr
5
5
  import { captureErasureInput, erasureRequestInvalid, erasureSelectHash } from "./file-backend.js";
6
6
  import { canonicalExpectedScopes } from "./export-bundle.js";
7
7
  import { thrownLabel, thrownText } from "../thrown-value.js";
8
+ import { chooseSessionWriteHome } from "./session-write-home.js";
8
9
  const FACE = "createMemoryDeployment";
9
10
  export const MEMORY_DEPLOYMENT_ERASURE_LOCK_DIR = ".memory-erasure-judge";
10
11
  const STATUS_KEYS_DECIDED = true;
@@ -138,9 +139,17 @@ export function createMemoryDeployment(input) {
138
139
  throw coded(`eraseMemoryEntries: requestId ${JSON.stringify(req.requestId)} was first executed ${anchor.selectHash === selectHash ? "in another of this deployment's memory stores" : "with a DIFFERENT selector"} — a requestId names ONE request in the deployment; use a new requestId for a new selector (nothing was deleted, nothing was recorded)`, "memory.erasure_selector_mismatch");
139
140
  }
140
141
  let receipt;
142
+ const executed = [];
141
143
  for (const store of reach) {
142
144
  fence(receipt === undefined ? "before any store executed" : "between two stores' executions");
143
- const part = await store.engine.eraseMemoryEntries(req);
145
+ let part;
146
+ try {
147
+ part = await store.engine.eraseMemoryEntries(req);
148
+ }
149
+ catch (err) {
150
+ throw receipt === undefined ? err : refusedAfterExecuting(err, executed, store.plane, receipt.erased.length);
151
+ }
152
+ executed.push(store.plane);
144
153
  receipt = receipt === undefined ? part : mergeErasureAttestations(receipt, part);
145
154
  }
146
155
  fence("while a store executed");
@@ -154,7 +163,7 @@ export function createMemoryDeployment(input) {
154
163
  }
155
164
  },
156
165
  async sessionMemoryStatus(sessionId) {
157
- const planes = [{ plane: "project", status: await project.engine.sessionMemoryStatus(sessionId) }];
166
+ const rows = [{ plane: "project", ...(await project.engine.sessionMemoryStatusRead(sessionId)) }];
158
167
  const inSet = hasPersonalStore();
159
168
  if (inSet || (pinned && memoryCaptureRecordStore !== undefined)) {
160
169
  let seat;
@@ -164,14 +173,30 @@ export function createMemoryDeployment(input) {
164
173
  catch {
165
174
  seat = undefined;
166
175
  }
167
- const status = seat !== undefined ? await seat.engine.sessionMemoryStatus(sessionId) : { optOutSource: "fault" };
168
- if (inSet || status.optOutSource !== undefined)
169
- planes.push({ plane: "personal", status });
176
+ const read = seat !== undefined ? await seat.engine.sessionMemoryStatusRead(sessionId) : { status: { optOutSource: "fault" }, writeHome: { state: "unreadable" } };
177
+ if (inSet || read.status.optOutSource !== undefined)
178
+ rows.push({ plane: "personal", ...read });
170
179
  }
171
- return { ...foldSessionMemoryStatuses(planes.map((p) => p.status)), planes };
180
+ const planes = rows.map(({ plane, status }) => ({ plane, status }));
181
+ const writeHome = chooseSessionWriteHome(rows.map((r) => r.writeHome));
182
+ return { ...foldSessionMemoryStatuses(planes.map((p) => p.status)), ...(writeHome !== undefined ? { writeHome } : {}), planes };
172
183
  },
173
184
  };
174
185
  }
186
+ function refusedAfterExecuting(err, executed, refusing, erased) {
187
+ if (!(err instanceof Error))
188
+ return err;
189
+ const done = executed.map((plane) => `the ${plane} store`).join(" and ");
190
+ const sentence = `eraseMemoryEntries: this request had already executed in ${done} (${erased} ${erased === 1 ? "entry" : "entries"} erased there; each keeps its anchor and a replay of the same requestId converges every store) when the ${refusing} store refused it — what follows describes the refusing store alone: ${err.message}`;
191
+ try {
192
+ const copy = Object.create(Object.getPrototypeOf(err), Object.getOwnPropertyDescriptors(err));
193
+ Object.defineProperty(copy, "message", { value: sentence, writable: true, configurable: true, enumerable: false });
194
+ return copy;
195
+ }
196
+ catch {
197
+ return err;
198
+ }
199
+ }
175
200
  async function anchorOf(store, requestId) {
176
201
  const face = store;
177
202
  if (typeof face.erasureAnchorOf === "function")
@@ -1,5 +1,8 @@
1
1
  import type { MemoryEntryOrigin } from "./types.js";
2
- export declare const ORIGIN_CLEARANCES_FILE = "origin-clearances.json";
2
+ export declare const ORIGIN_CLEARANCES_FILE: string;
3
+ /** The custody object a clearance's cleared-entry text is kept as (kind `clearance-custody`): named by the row, so the
4
+ * row alone finds it again. */
5
+ export declare function clearanceCustodyName(clearanceId: string): string;
3
6
  /** One clearance's terminal event (appended, never rewritten). */
4
7
  export interface OriginClearanceEvent {
5
8
  eventId: string;
@@ -29,7 +32,9 @@ export interface OriginClearanceRow {
29
32
  status: "pending" | "done" | "failed";
30
33
  /** CUSTODY: the full serialized cleared-entry file text. A crash between the tombstone batch and
31
34
  * the re-record batch leaves this as the only copy — the pending row is the loud recovery seat
32
- * (a later clearEntryOrigin call for the same entry resumes from it). */
35
+ * (a later clearEntryOrigin call for the same entry resumes from it). Kept as the row's custody
36
+ * object ({@link clearanceCustodyName}), never inside the account: the stored row carries the
37
+ * text's sha-256 (`custodyDigest`) and every read answers the text, checked against it. */
33
38
  entryText: string;
34
39
  /** Set the moment THIS clearance's tombstone commits ({@link markOriginClearanceTombstoned}) —
35
40
  * the resume arm's arbiter for an absent entry: with it, absence is the known crash window
@@ -68,7 +73,11 @@ export interface OriginClearanceShadow {
68
73
  requestId: string;
69
74
  settledAt: number;
70
75
  }
71
- /** Lock-free strict read of the whole account (host audit face; journal-aware, corrupt = throw). */
76
+ /** Move every custody text the account still carries inline out into its custody object, under the account's lock;
77
+ * writes nothing when there is none. */
78
+ export declare function moveOriginClearanceCustodyOut(controlDir: string): void;
79
+ /** Lock-free strict read of the whole account (host audit face; journal-aware, corrupt = throw). Each row answers its
80
+ * custody text, wherever the account keeps it. */
72
81
  export declare function readOriginClearances(controlDir: string): OriginClearanceRow[];
73
82
  /**
74
83
  * WRITE-AHEAD open: append the pending row (custody included) before any store mutation. Refuses a
@@ -1,6 +1,53 @@
1
- import { ControlPlaneCorruptError, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
1
+ import { createHash } from "node:crypto";
2
+ import { ControlPlaneCorruptError, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
3
+ import { getFileControlObject, putFileControlObject } from "./control-objects.js";
2
4
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
3
- export const ORIGIN_CLEARANCES_FILE = "origin-clearances.json";
5
+ const CLEARANCES = fileGovernanceDocOf("origin-clearances");
6
+ export const ORIGIN_CLEARANCES_FILE = CLEARANCES.file;
7
+ export function clearanceCustodyName(clearanceId) {
8
+ return `${clearanceId}.md`;
9
+ }
10
+ function sha256Hex(bytes) {
11
+ return createHash("sha256").update(bytes).digest("hex");
12
+ }
13
+ function custodyTextOf(controlDir, row) {
14
+ if (row.entryText !== undefined)
15
+ return row.entryText;
16
+ const name = clearanceCustodyName(row.clearanceId);
17
+ const bytes = getFileControlObject(controlDir, "clearance-custody", name);
18
+ if (bytes === undefined)
19
+ throw new ControlPlaneCorruptError(`memory origin-clearance ledger: clearance ${JSON.stringify(row.clearanceId)} names custody ${JSON.stringify(name)} that is not there (fail-closed)`);
20
+ if (sha256Hex(bytes) !== row.custodyDigest)
21
+ throw new ControlPlaneCorruptError(`memory origin-clearance ledger: clearance ${JSON.stringify(row.clearanceId)}'s custody does not match the digest its row records (fail-closed)`);
22
+ return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
23
+ }
24
+ function keepCustody(controlDir, clearanceId, text) {
25
+ const bytes = new TextEncoder().encode(text);
26
+ const digest = sha256Hex(bytes);
27
+ const name = clearanceCustodyName(clearanceId);
28
+ putFileControlObject(controlDir, "clearance-custody", name, bytes);
29
+ return digest;
30
+ }
31
+ function moveInlineCustody(controlDir, rec) {
32
+ let moved = false;
33
+ for (const row of rec.rows) {
34
+ if (row.entryText === undefined)
35
+ continue;
36
+ const custodyDigest = keepCustody(controlDir, row.clearanceId, row.entryText);
37
+ const r = row;
38
+ delete r.entryText;
39
+ r.custodyDigest = custodyDigest;
40
+ moved = true;
41
+ }
42
+ return moved;
43
+ }
44
+ function lockedClearanceUpdate(controlDir, fn) {
45
+ lockedStrictUpdate(controlDir, CLEARANCES.file, CLEARANCES.what, coerceClearances, (rec) => {
46
+ const moved = moveInlineCustody(controlDir, rec);
47
+ const out = fn(rec);
48
+ return out.next === undefined && moved ? { next: rec, result: out.result } : out;
49
+ });
50
+ }
4
51
  function reqStr(v) {
5
52
  return typeof v === "string" && v.length > 0;
6
53
  }
@@ -24,6 +71,8 @@ function coerceClearances(raw) {
24
71
  if (rec.version !== 1)
25
72
  throw new ControlPlaneCorruptError(`memory origin-clearance ledger has an unrecognized version (${String(rec.version)}) — refusing (fail-closed)`);
26
73
  for (const r of rec.rows) {
74
+ const custodyInline = typeof r?.entryText === "string" && r.entryText.length > 0 && r.custodyDigest === undefined;
75
+ const custodyKept = r?.entryText === undefined && typeof r?.custodyDigest === "string" && /^[0-9a-f]{64}$/.test(r.custodyDigest);
27
76
  if (typeof r !== "object" ||
28
77
  r === null ||
29
78
  !reqStr(r.clearanceId) ||
@@ -35,8 +84,7 @@ function coerceClearances(raw) {
35
84
  !reqStr(r.reason) ||
36
85
  typeof r.at !== "number" ||
37
86
  !Number.isFinite(r.at) ||
38
- typeof r.entryText !== "string" ||
39
- r.entryText.length === 0 ||
87
+ !(custodyInline || custodyKept) ||
40
88
  (r.tombstonedAt !== undefined && (typeof r.tombstonedAt !== "number" || !Number.isFinite(r.tombstonedAt))) ||
41
89
  (r.status !== "pending" && r.status !== "done" && r.status !== "failed") ||
42
90
  !Array.isArray(r.events)) {
@@ -51,22 +99,29 @@ function coerceClearances(raw) {
51
99
  }
52
100
  return rec;
53
101
  }
102
+ export function moveOriginClearanceCustodyOut(controlDir) {
103
+ lockedClearanceUpdate(controlDir, () => ({ result: undefined }));
104
+ }
54
105
  export function readOriginClearances(controlDir) {
55
- return coerceClearances(readStrictSidecar(controlDir, ORIGIN_CLEARANCES_FILE, "memory origin-clearance ledger")).rows.map((r) => ({ ...r, events: [...r.events] }));
106
+ return coerceClearances(readStrictSidecar(controlDir, CLEARANCES.file, CLEARANCES.what)).rows.map((r) => {
107
+ const { custodyDigest: _digest, entryText: _inline, ...row } = r;
108
+ return { ...row, entryText: custodyTextOf(controlDir, r), events: [...r.events] };
109
+ });
56
110
  }
57
111
  export function openOriginClearance(controlDir, row) {
58
- lockedStrictUpdate(controlDir, ORIGIN_CLEARANCES_FILE, "memory origin-clearance ledger", coerceClearances, (rec) => {
112
+ lockedClearanceUpdate(controlDir, (rec) => {
59
113
  if (rec.rows.some((r) => r.entryId === row.entryId && r.status === "pending")) {
60
114
  const e = new Error(`origin clearance for entry ${JSON.stringify(row.entryId)} is already pending — resume it (call clearEntryOrigin again) instead of opening a second row.`);
61
115
  e.code = "memory.origin_clear_pending";
62
116
  throw e;
63
117
  }
64
- rec.rows.push({ ...row, status: "pending", events: [] });
118
+ const { entryText, ...rest } = row;
119
+ rec.rows.push({ ...rest, custodyDigest: keepCustody(controlDir, row.clearanceId, entryText), status: "pending", events: [] });
65
120
  return { next: rec, result: undefined };
66
121
  });
67
122
  }
68
123
  export function markOriginClearanceTombstoned(controlDir, input) {
69
- lockedStrictUpdate(controlDir, ORIGIN_CLEARANCES_FILE, "memory origin-clearance ledger", coerceClearances, (rec) => {
124
+ lockedClearanceUpdate(controlDir, (rec) => {
70
125
  const r = rec.rows.find((x) => x.clearanceId === input.clearanceId);
71
126
  if (r === undefined || r.status !== "pending" || r.tombstonedAt !== undefined)
72
127
  return { result: undefined };
@@ -75,7 +130,7 @@ export function markOriginClearanceTombstoned(controlDir, input) {
75
130
  });
76
131
  }
77
132
  export function settleOriginClearance(controlDir, input) {
78
- lockedStrictUpdate(controlDir, ORIGIN_CLEARANCES_FILE, "memory origin-clearance ledger", coerceClearances, (rec) => {
133
+ lockedClearanceUpdate(controlDir, (rec) => {
79
134
  const r = rec.rows.find((x) => x.clearanceId === input.clearanceId);
80
135
  if (r === undefined) {
81
136
  const e = new Error(`origin clearance ${JSON.stringify(input.clearanceId)} is unknown`);
@@ -17,8 +17,29 @@
17
17
  * are never consulted. A registry that cannot derive a home (v1, an unfinished layout move)
18
18
  * answers absent before either source is read, so no read here goes through a face whose layout seat would finish the move
19
19
  * first and then name a post-move home.
20
+ *
21
+ * The reading keeps the absences apart ({@link SessionWriteHomeReading}) and the instant of the source that won, which is what
22
+ * {@link chooseSessionWriteHome} needs to choose among a deployment's stores.
20
23
  */
21
24
  import type { MemoryEntry, MemoryGovernanceDocs } from "./types.js";
25
+ /**
26
+ * What one store's control plane says of a session's write home:
27
+ * - `named` — the home, and `at`, the instant (ms epoch) of the source that named it (the account's (re-)open, or the
28
+ * newest contribution's commit);
29
+ * - `none` — neither source names a scope: a session that never opened an account here and never committed here (a
30
+ * readable absence — the store holds nothing of the session's writes);
31
+ * - `unreadable` — a source faulted, or the registry cannot derive a home: a newer write may be hidden, so the store
32
+ * answers no home and no stand-in.
33
+ */
34
+ export type SessionWriteHomeReading = {
35
+ readonly state: "named";
36
+ readonly home: string;
37
+ readonly at: number;
38
+ } | {
39
+ readonly state: "none";
40
+ } | {
41
+ readonly state: "unreadable";
42
+ };
22
43
  export declare function sessionWriteHomeOf(input: {
23
44
  memoryDir: string;
24
45
  controlDir: string;
@@ -29,4 +50,16 @@ export declare function sessionWriteHomeOf(input: {
29
50
  contributions: ReadonlyMap<string, number> | undefined;
30
51
  /** A committed, side-effect-free entry read (the engine's audit face). */
31
52
  readEntries: (ids: readonly string[]) => Promise<MemoryEntry[]>;
32
- }): Promise<string | undefined>;
53
+ }): Promise<SessionWriteHomeReading>;
54
+ /**
55
+ * The write home a session's status answers across a deployment's stores, from each store's reading
56
+ * ({@link SessionWriteHomeReading}).
57
+ *
58
+ * @contract memory.deployment_status.write_home — a session's write home across a deployment's stores is one store's own
59
+ * `writeHome`, chosen and never merged: the store whose reading names the newest home, ranked by the one law a store ranks
60
+ * its own two sources by (the newer wins); absent when no store names one, absent while any store's reading is unreadable
61
+ * (that store may hold the newer write, and another store's word would be a stand-in), and absent when two stores name theirs
62
+ * at the same instant (there is no newer one; a store's own tie has a writer, the account); a deployment of one store
63
+ * answers that store's own; a host projects the key and chooses no store itself
64
+ */
65
+ export declare function chooseSessionWriteHome(readings: readonly SessionWriteHomeReading[]): string | undefined;
@@ -1,12 +1,15 @@
1
1
  import { canonicalize, REGISTRY_SHAPE_DERIVES_PATHS, scopeDirFor, scopeRegistryShape } from "./layout.js";
2
2
  import { sessionAccountWriteHome } from "./delegation-settlement.js";
3
+ function rankNewer(a, b) {
4
+ return a >= b ? (a > b ? 1 : 0) : -1;
5
+ }
3
6
  export async function sessionWriteHomeOf(input) {
4
7
  const { memoryDir, controlDir, sessionId, contributions } = input;
5
8
  try {
6
9
  if (!REGISTRY_SHAPE_DERIVES_PATHS[scopeRegistryShape(controlDir)])
7
- return undefined;
10
+ return { state: "unreadable" };
8
11
  if (contributions === undefined)
9
- return undefined;
12
+ return { state: "unreadable" };
10
13
  let newest;
11
14
  for (const [id, at] of contributions) {
12
15
  if (newest === undefined || at > newest.at || (at === newest.at && id > newest.id))
@@ -14,21 +17,45 @@ export async function sessionWriteHomeOf(input) {
14
17
  }
15
18
  const account = await sessionAccountWriteHome(input.docs, sessionId);
16
19
  const sources = [];
17
- const fromAccount = async () => account?.writeScope;
18
- const fromNewest = async () => (newest === undefined ? undefined : (await input.readEntries([newest.id])).find((e) => e.id === newest.id)?.scope);
19
- if (account !== undefined && (newest === undefined || account.openedAt >= newest.at))
20
+ const fromAccount = async () => (account === undefined ? undefined : { scope: account.writeScope, at: account.openedAt });
21
+ const fromNewest = async () => {
22
+ if (newest === undefined)
23
+ return undefined;
24
+ const scope = (await input.readEntries([newest.id])).find((e) => e.id === newest.id)?.scope;
25
+ return scope === undefined ? undefined : { scope, at: newest.at };
26
+ };
27
+ if (account !== undefined && (newest === undefined || rankNewer(account.openedAt, newest.at) >= 0))
20
28
  sources.push(fromAccount, fromNewest);
21
29
  else
22
30
  sources.push(fromNewest, fromAccount);
23
- let scope;
31
+ let named;
24
32
  for (const source of sources) {
25
- scope = await source();
26
- if (scope !== undefined)
33
+ named = await source();
34
+ if (named !== undefined)
27
35
  break;
28
36
  }
29
- return scope === undefined ? undefined : canonicalize(scopeDirFor(memoryDir, controlDir, scope));
37
+ return named === undefined ? { state: "none" } : { state: "named", home: canonicalize(scopeDirFor(memoryDir, controlDir, named.scope)), at: named.at };
30
38
  }
31
39
  catch {
32
- return undefined;
40
+ return { state: "unreadable" };
41
+ }
42
+ }
43
+ export function chooseSessionWriteHome(readings) {
44
+ let best;
45
+ let tied = false;
46
+ for (const r of readings) {
47
+ if (r.state === "unreadable")
48
+ return undefined;
49
+ if (r.state !== "named")
50
+ continue;
51
+ const rank = best === undefined ? 1 : rankNewer(r.at, best.at);
52
+ if (rank === 1) {
53
+ best = r;
54
+ tied = false;
55
+ }
56
+ else if (rank === 0) {
57
+ tied = true;
58
+ }
33
59
  }
60
+ return best === undefined || tied ? undefined : best.home;
34
61
  }
@@ -125,9 +125,9 @@ export interface MemoryEngineToolsOptions {
125
125
  * Absent ⇒ no pollution face is wired (engine-direct hosts, tests): the empty-outcome wording is
126
126
  * then exactly the clean-session wording — nothing is inferred from the seat's absence.
127
127
  */
128
- sessionPollution?: () => {
128
+ sessionPollution?: () => Promise<{
129
129
  reason: string;
130
- } | undefined;
130
+ } | undefined>;
131
131
  /**
132
132
  * design/336 §13-3 — the provenance mode the write engine runs under. Two consumers here:
133
133
  * - the pollution sentence states what the mark actually DOES (under `"carry"` writes commit
@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
2
2
  import { Type } from "typebox";
3
3
  import { errorResult } from "../tools.js";
4
4
  import { defuseFenceMarkers, delimitUntrusted, FENCED_LANE_ENVELOPE_TAGS, inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
5
- import { formatMemoryAge } from "../memory-recall.js";
5
+ import { formatMemoryAge } from "./memory-age.js";
6
6
  import { committedOriginOf } from "./frontmatter.js";
7
7
  import { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_INDEX_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, MEMORY_SEARCH_BAND_ORDER_HEADER } from "./provenance-wording.js";
8
8
  import { deriveSupersededSet, memorySupersededNote, MEMORY_CHALLENGED_ENTRY_GUIDANCE, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
@@ -146,10 +146,10 @@ export function createMemoryEngineTools(opts) {
146
146
  }
147
147
  }
148
148
  const exposedEntry = (e) => committedOriginOf(e.frontmatter) !== undefined;
149
- const pollutionSentence = () => {
149
+ const pollutionSentence = async () => {
150
150
  let reason;
151
151
  try {
152
- reason = opts.sessionPollution?.()?.reason;
152
+ reason = (await opts.sessionPollution?.())?.reason;
153
153
  }
154
154
  catch {
155
155
  return "";
@@ -161,13 +161,13 @@ export function createMemoryEngineTools(opts) {
161
161
  }
162
162
  return ` This session is marked polluted (${inlineUntrusted(reason, 200)}): the memory it writes is not admitted to the library at harvest, so writing this down now would not make it retrievable later either.`;
163
163
  };
164
- const noMatch = (query) => {
164
+ const noMatch = async (query) => {
165
165
  const details = { outcome: "ok", hits: [] };
166
166
  return {
167
167
  content: `No memory entries matched ${JSON.stringify(inlineUntrusted(query, 120))}. Matching is lexical — other concrete ` +
168
168
  `wordings may still hit, and ${MEMORY_INDEX_TOOL_NAME} lists every mounted entry when no wording works. ` +
169
169
  `If the user expected you to know this, say that you checked memory and found nothing.` +
170
- pollutionSentence(),
170
+ (await pollutionSentence()),
171
171
  details,
172
172
  };
173
173
  };
@@ -448,7 +448,7 @@ export function createMemoryEngineTools(opts) {
448
448
  `Only entries carrying a committed entry id are served here, and a memory file written into the memory root during ` +
449
449
  `this session gets its id when the session-boundary harvest admits it — a file written in this session is not served here before then. ` +
450
450
  `If the slug is misremembered: ${MEMORY_SEARCH_TOOL_NAME} matches keywords; ${MEMORY_INDEX_TOOL_NAME} lists exact slugs.` +
451
- pollutionSentence(), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
451
+ (await pollutionSentence()), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
452
452
  }
453
453
  try {
454
454
  const names = await shadowNamesAcross(await Promise.all(planes.map((plane) => plane.challengeExclusions?.())));
@@ -741,7 +741,7 @@ export function createMemoryEngineTools(opts) {
741
741
  if (total === 0) {
742
742
  const where = scope !== undefined ? ` in scope ${inlineUntrusted(scope, 80)}` : "";
743
743
  const details = { outcome: "ok", entries: [], offset: 0, shown: 0, total: 0, ...(supersededHidden > 0 ? { supersededHidden } : {}), ...(shadowedHidden > 0 ? { shadowedHidden } : {}) };
744
- return { content: `No ${supersededHidden > 0 || shadowedHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + pollutionSentence(), details };
744
+ return { content: `No ${supersededHidden > 0 || shadowedHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + (await pollutionSentence()), details };
745
745
  }
746
746
  if (offset >= total) {
747
747
  return refusedIndex("offset_past_end", `offset ${offset} is past the end — the listing has ${total} row${total === 1 ? "" : "s"}.`);