@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
@@ -134,6 +134,7 @@ export class FileFileHistoryStore {
134
134
  spentAttempts = new Map();
135
135
  activeCaptures = new Map();
136
136
  activeImports = new Map();
137
+ writers = new Map();
137
138
  reapedCache = new Map();
138
139
  boundaryKeep;
139
140
  lastCommittedAt = 0;
@@ -405,7 +406,23 @@ export class FileFileHistoryStore {
405
406
  throw err;
406
407
  }
407
408
  }
408
- async trackEdit(scope, absPath, env, root, signal) {
409
+ async writing(scope, write) {
410
+ this.writers.set(scope, (this.writers.get(scope) ?? 0) + 1);
411
+ try {
412
+ return await write();
413
+ }
414
+ finally {
415
+ const left = (this.writers.get(scope) ?? 1) - 1;
416
+ if (left === 0)
417
+ this.writers.delete(scope);
418
+ else
419
+ this.writers.set(scope, left);
420
+ }
421
+ }
422
+ trackEdit(scope, absPath, env, root, signal) {
423
+ return this.writing(scope, () => this.trackEditCounted(scope, absPath, env, root, signal));
424
+ }
425
+ async trackEditCounted(scope, absPath, env, root, signal) {
409
426
  try {
410
427
  const { key, kind, family } = describeTrackKey(root, absPath);
411
428
  const before = this.readTrackedState(scope);
@@ -456,7 +473,10 @@ export class FileFileHistoryStore {
456
473
  return { ok: false, error: { code: "track_failed", message: `first-touch record for ${absPath} could not be persisted: ${thrownText(err)}`, ...caughtFault(err) } };
457
474
  }
458
475
  }
459
- async annulTrack(scope, absPath, root, verify) {
476
+ annulTrack(scope, absPath, root, verify) {
477
+ return this.writing(scope, () => this.annulTrackCounted(scope, absPath, root, verify));
478
+ }
479
+ async annulTrackCounted(scope, absPath, root, verify) {
460
480
  try {
461
481
  const key = trackKeyOf(root, absPath);
462
482
  const state = this.readTrackedState(scope);
@@ -573,7 +593,10 @@ export class FileFileHistoryStore {
573
593
  return ids;
574
594
  return { fault: worstFault(faults), what: `boundaries that cannot be used (${unusable.slice(0, 3).map((i) => JSON.stringify(i)).join(", ")}${unusable.length > 3 ? ", …" : ""})` };
575
595
  }
576
- async snapshot(scope, entryId, env, root, signal) {
596
+ snapshot(scope, entryId, env, root, signal) {
597
+ return this.writing(scope, () => this.snapshotCounted(scope, entryId, env, root, signal));
598
+ }
599
+ async snapshotCounted(scope, entryId, env, root, signal) {
577
600
  const bpath = this.tryBoundaryPath(scope, entryId);
578
601
  if (bpath === null)
579
602
  return { ok: false, error: { code: "snapshot_failed", message: `unsafe boundary key ${JSON.stringify(entryId)}` } };
@@ -913,6 +936,40 @@ export class FileFileHistoryStore {
913
936
  this.collectBlobs();
914
937
  return removed;
915
938
  }
939
+ async deleteBySession(scope) {
940
+ if (this.writers.has(scope)) {
941
+ throw Object.assign(new Error(`file history scope "${scope}" has a write in flight in this store (a capture, a first-touch record, a retraction or an import) — a session's history is erased when no leg of it runs`), { code: "conflict" });
942
+ }
943
+ const sdir = this.scopeDir(scope);
944
+ const ledger = this.reapedLogPath(scope);
945
+ let removed = 0;
946
+ if (existsSync(sdir)) {
947
+ try {
948
+ removed += readdirSync(this.boundaryDir(scope)).filter((f) => f.endsWith(".json")).length;
949
+ }
950
+ catch (err) {
951
+ if (err.code !== "ENOENT")
952
+ removed += 1;
953
+ }
954
+ const read = this.readTrackedState(scope);
955
+ if (read.corrupt)
956
+ removed += 1;
957
+ else
958
+ for (const rec of read.tracked.values())
959
+ removed += rec.versions.length;
960
+ rmSync(sdir, { recursive: true, force: true });
961
+ }
962
+ rmSync(ledger, { force: true });
963
+ this.reapedCache.delete(scope);
964
+ this.spentAttempts.delete(scope);
965
+ this.seededScopes.delete(scope);
966
+ this.activeCaptures.delete(scope);
967
+ this.activeImports.delete(scope);
968
+ const kept = this.collectBlobs();
969
+ if (kept !== undefined)
970
+ throw new Error(`file history scope "${scope}" is erased but its blobs are not: ${kept}`);
971
+ return removed;
972
+ }
916
973
  collectBlobs() {
917
974
  const live = new Set();
918
975
  let complete = true;
@@ -922,9 +979,9 @@ export class FileFileHistoryStore {
922
979
  }
923
980
  catch (err) {
924
981
  if (err.code === "ENOENT")
925
- return;
982
+ return undefined;
926
983
  this.disclose(this.scopesDir, `scope root unreadable (${err.code ?? "unknown"}) — blob GC aborted, every blob kept`);
927
- return;
984
+ return "the scope root could not be read, so every blob was kept";
928
985
  }
929
986
  const liveJournals = new Set([...[...this.activeCaptures.values()].flatMap((m) => [...m.values()]), ...[...this.activeImports.values()].flatMap((set) => [...set])]);
930
987
  for (const name of scopeDirs) {
@@ -1009,20 +1066,22 @@ export class FileFileHistoryStore {
1009
1066
  break;
1010
1067
  }
1011
1068
  if (!complete)
1012
- return;
1069
+ return "a scope's history or staging could not be judged during the live-set scan, so every blob was kept";
1013
1070
  let blobs;
1014
1071
  try {
1015
1072
  blobs = readdirSync(this.blobsDir);
1016
1073
  }
1017
1074
  catch (err) {
1018
- if (err.code !== "ENOENT") {
1019
- this.disclose(this.blobsDir, `blob directory unreadable (${err.code ?? "unknown"}) — blob GC skipped, every blob kept`);
1020
- }
1021
- return;
1075
+ if (err.code === "ENOENT")
1076
+ return undefined;
1077
+ this.disclose(this.blobsDir, `blob directory unreadable (${err.code ?? "unknown"}) — blob GC skipped, every blob kept`);
1078
+ return "the blob directory could not be read, so every blob was kept";
1022
1079
  }
1080
+ let stuck = 0;
1023
1081
  for (const blob of blobs)
1024
- if (!live.has(blob))
1025
- safeRm(join(this.blobsDir, blob));
1082
+ if (!live.has(blob) && !safeRm(join(this.blobsDir, blob)))
1083
+ stuck++;
1084
+ return stuck === 0 ? undefined : `${stuck} unreferenced blob(s) could not be removed`;
1026
1085
  }
1027
1086
  async adoptScope(fromScope, toScope) {
1028
1087
  try {
@@ -1145,7 +1204,10 @@ export class FileFileHistoryStore {
1145
1204
  };
1146
1205
  return { ok: true, history };
1147
1206
  }
1148
- async importHistory(scope, data, srcGetBlob) {
1207
+ importHistory(scope, data, srcGetBlob) {
1208
+ return this.writing(scope, () => this.importHistoryCounted(scope, data, srcGetBlob));
1209
+ }
1210
+ async importHistoryCounted(scope, data, srcGetBlob) {
1149
1211
  try {
1150
1212
  const shaped = validateFileHistoryExport(data);
1151
1213
  if (!shaped.ok)
@@ -1,4 +1,3 @@
1
- import { type MemoryStore, type UtilityGate } from "../../core/memory.js";
2
1
  import type { CheckpointStore } from "../../core/checkpoint-store.js";
3
2
  import type { ToolResultStore } from "../../core/tool-result-store.js";
4
3
  import { type EvictPolicy } from "../../core/session-store.js";
@@ -15,8 +14,8 @@ import { type SessionPolicyStore } from "../../core/session-policy-store.js";
15
14
  import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
16
15
  import type { UsageWindowStore } from "../../core/usage-window-store.js";
17
16
  import type { EngineStorageBackend } from "../../core/engine-storage-backend.js";
17
+ import { type RetentionDeclaration } from "../../core/retention.js";
18
18
  export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, type CheckpointLedgerEventKind, type CheckpointLedgerReading, type FileCheckpointStoreOptions, type ReadCheckpointLedgerOptions, } from "./checkpoint-store.js";
19
- export { FileMemoryStore } from "./memory-store.js";
20
19
  export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
21
20
  export { FileToolResultStore } from "./tool-result-store.js";
22
21
  export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
@@ -34,7 +33,7 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
34
33
  * design/80 — the file-backed {@link EngineStorageBackend} for the local (TOC) single-user binary, selected
35
34
  * purely by what the embedder injects into `RunnerDeps` (no engine change). Construct one over a single data
36
35
  * root and pass its members into the `RunnerDeps` seats of the same names (every member of the contract is
37
- * one; the class's extra members — `root`, `memoryStore` — are not seats):
36
+ * one; the class's extra member `root` is not a seat):
38
37
  *
39
38
  * ```ts
40
39
  * const backend = new FileStorageBackend(); // ~/.ai-agent (or $AGENT_DATA_DIR)
@@ -62,15 +61,22 @@ export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdopt
62
61
  export interface FileStorageBackendOptions {
63
62
  /** Data root. Default `$AGENT_DATA_DIR ?? ~/.ai-agent`, NFC-normalized + realpath-canonicalized. */
64
63
  root?: string;
65
- /** Profile-injected promotable-write gate (design/77 §2). Threaded into `guardedMemoryStore`. */
66
- utilityGate?: UtilityGate;
67
64
  /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
68
65
  * deleted by an idle timer). */
69
66
  evict?: EvictPolicy;
70
67
  /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold, the holder judge). The
71
68
  * corrupt-read sink and the session head read are the backend's own — the sink is {@link FileStorageBackendOptions.onCorruptRead}
72
69
  * (one failure grammar, one sink) and the head read is its session store's — so neither is accepted here. */
73
- checkpoint?: Omit<FileCheckpointStoreOptions, "onCorruptRead" | "sessionHeadOf">;
70
+ checkpoint?: Omit<FileCheckpointStoreOptions, "onCorruptRead" | "sessionHeadOf" | "retention">;
71
+ /**
72
+ * The managed-retention declaration of this backend's three declaring stores — {@link FileStorageBackend.sessionStore},
73
+ * {@link FileStorageBackend.checkpointStore} and {@link FileStorageBackend.toolResultStore} — stated by the party that runs the sweep
74
+ * (`"managed"`: an executor deletes their rows on schedule; default `"none"`; a third word refused, `config.retention_capability`).
75
+ * The backend carries no executor of its own: a deployment that says `"managed"` runs one over these stores (the legs it calls are
76
+ * `RETENTION_CASCADE`'s) and hands it to `assertRetentionCapability` as `executor`, which refuses `"managed"` beside `executor: null`.
77
+ * One word for the three, because one sweep covers them; it is not a per-store choice, so the `checkpoint` record does not take it.
78
+ */
79
+ retention?: RetentionDeclaration;
74
80
  /**
75
81
  * design/381 §片2 — file-history tuning, today just the boundary RETENTION bound (omitted ⇒ the
76
82
  * engine default; `{ retention: { keep: "unbounded" } }` hands the GC schedule to the deployment).
@@ -82,12 +88,6 @@ export interface FileStorageBackendOptions {
82
88
  * (`mountedToolNames`, the roster its write and loosening checks judge rule names against). The corrupt-read sink is
83
89
  * wired from {@link FileStorageBackendOptions.onCorruptRead}, as for {@link fileHistory}. */
84
90
  sessionPolicy?: Omit<FileSessionPolicyStoreOptions, "onCorruptRead">;
85
- /** design/81 Slice 5 — an optional {@link import("../../core/memory.js").Embedder}. Injected ⇒ the memory
86
- * store does portable (in-process) vector recall over a rebuildable sidecar index (`vectorMode:"portable"`);
87
- * absent ⇒ the lexical floor, byte-identical to before. Config-driven (the deployment injects it); OFF by
88
- * default. 🔴 the consolidation band `{0.05,0.3}` is tuned for the lexical distance — a real embedding model
89
- * needs it re-tuned + a no-mis-merge live check BEFORE production-enable (design/81 Slice 5 release gate). */
90
- embedder?: import("../../core/memory.js").Embedder;
91
91
  /**
92
92
  * Disclosure sink for a durable read this backend's stores treat as ABSENT because the bytes were
93
93
  * corrupt or unreadable (never fires on plain ENOENT — real absence).
@@ -135,9 +135,6 @@ export declare class FileStorageBackend implements EngineStorageBackend {
135
135
  readonly root: string;
136
136
  readonly sessionStore: SessionStore;
137
137
  readonly checkpointStore: CheckpointStore;
138
- /** Wrapped in `guardedMemoryStore` (Gate-2 chokepoint). design/81: implements the id-addressable trio on
139
- * a lexical cosine-distance → `supportsConsolidation` is true → end-of-task consolidation lights up. */
140
- readonly memoryStore: MemoryStore;
141
138
  readonly toolResultStore: ToolResultStore;
142
139
  /** design/99 §E6 — file-backed per-session permission rules (E6). Wire into `RunnerDeps.sessionPolicyStore`
143
140
  * for a local deployment that needs session rules to survive a restart. */
@@ -174,7 +171,6 @@ export declare class FileStorageBackend implements EngineStorageBackend {
174
171
  private readonly fileAgentRows;
175
172
  private readonly fileMailbox;
176
173
  private readonly fileCheckpoints;
177
- private readonly fileMemory;
178
174
  private readonly ttl;
179
175
  /** RB-437 — kept so {@link dispose} can release the shared per-session authorities (and their append
180
176
  * descriptors) this backend joined; `TtlSessionStore.dispose()` only clears the sweep timer. */
@@ -1,11 +1,9 @@
1
1
  import { join } from "node:path";
2
- import { guardedMemoryStore } from "../../core/memory.js";
3
2
  import { STORE_HOOK_KEYS, TtlSessionStore } from "../../core/session-store.js";
4
3
  import { BootLock, resolveDataRoot } from "./fs-atomic.js";
5
4
  import { assertAdoptionBootGate } from "./adoption/marker.js";
6
5
  import { FileCheckpointStore } from "./checkpoint-store.js";
7
6
  import { readLedgerTuning } from "./ledger-tuning.js";
8
- import { FileMemoryStore } from "./memory-store.js";
9
7
  import { FileSessionRepo } from "./session-store.js";
10
8
  import { FileToolResultStore } from "./tool-result-store.js";
11
9
  import { FileSessionPolicyStore } from "./session-policy-store.js";
@@ -16,13 +14,13 @@ import { FileMailboxStore } from "./mailbox-store.js";
16
14
  import { FileRosterStore } from "../../agents/roster-store.js";
17
15
  import { FileFileHistoryStore } from "./file-history-store.js";
18
16
  import { readMountedToolNames } from "../../core/session-policy-store.js";
19
- import { optionKeys, receiveMembers, receiveOptions, refuseProxy, refuseStrayMembers } from "../../core/own-property-receipt.js";
17
+ import { optionKeys, receiveMembers, receiveOptions, refuseStrayMembers } from "../../core/own-property-receipt.js";
20
18
  import { receiveFileHistoryRetention } from "../../core/file-history-retention.js";
19
+ import { readRetentionDeclaration } from "../../core/retention.js";
21
20
  function nestedOptions(value, member, keys) {
22
21
  return value === undefined ? undefined : receiveMembers(value, { subject: `FileStorageBackendOptions.${member}`, unit: "option", moment: "at new FileStorageBackend" }, keys);
23
22
  }
24
23
  export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, } from "./checkpoint-store.js";
25
- export { FileMemoryStore } from "./memory-store.js";
26
24
  export { FileSessionRepo } from "./session-store.js";
27
25
  export { FileToolResultStore } from "./tool-result-store.js";
28
26
  export { FileSessionPolicyStore } from "./session-policy-store.js";
@@ -36,7 +34,7 @@ export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog
36
34
  export { processFingerprint, isProcessLive } from "./fs-atomic.js";
37
35
  export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
38
36
  export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
39
- const FILE_STORAGE_BACKEND_OPTION_KEYS = optionKeys()({ root: 0, utilityGate: 0, evict: 0, checkpoint: 0, fileHistory: 0, sessionPolicy: 0, embedder: 0, onCorruptRead: 0, sessions: 0 });
37
+ const FILE_STORAGE_BACKEND_OPTION_KEYS = optionKeys()({ root: 0, evict: 0, checkpoint: 0, retention: 0, fileHistory: 0, sessionPolicy: 0, onCorruptRead: 0, sessions: 0 });
40
38
  const NESTED_FILE_HISTORY_OPTION_KEYS = optionKeys()({ retention: 0 });
41
39
  const NESTED_SESSION_POLICY_OPTION_KEYS = optionKeys()({ mountedToolNames: 0 });
42
40
  const NESTED_CHECKPOINT_OPTION_KEYS = optionKeys()({ fsync: 0, compactEvery: 0, holderIsCurrent: 0 });
@@ -44,7 +42,6 @@ export class FileStorageBackend {
44
42
  root;
45
43
  sessionStore;
46
44
  checkpointStore;
47
- memoryStore;
48
45
  toolResultStore;
49
46
  sessionPolicyStore;
50
47
  workflowJournalStore;
@@ -57,18 +54,12 @@ export class FileStorageBackend {
57
54
  fileAgentRows;
58
55
  fileMailbox;
59
56
  fileCheckpoints;
60
- fileMemory;
61
57
  ttl;
62
58
  fileSessions;
63
59
  fileWorkflowJournal;
64
60
  constructor(options) {
65
- if (options !== undefined && options !== null && typeof options === "object") {
66
- refuseProxy(options, { subject: "FileStorageBackend options", unit: "option", moment: "at new FileStorageBackend" });
67
- if (Object.hasOwn(options, "retention")) {
68
- throw Object.assign(new Error(`FileStorageBackend runs no retention executor, so its options take no \`retention\` word: its stores declare "none".`), { code: "config.retention_capability" });
69
- }
70
- }
71
61
  const opts = receiveOptions(options, "FileStorageBackend", FILE_STORAGE_BACKEND_OPTION_KEYS);
62
+ const retention = readRetentionDeclaration("FileStorageBackendOptions.retention", opts.retention);
72
63
  const checkpointRecord = nestedOptions(opts.checkpoint, "checkpoint", NESTED_CHECKPOINT_OPTION_KEYS);
73
64
  const checkpointOptions = checkpointRecord === undefined ? undefined : { ...checkpointRecord, ...readLedgerTuning(checkpointRecord, "FileCheckpointStore", "FileStorageBackendOptions.checkpoint") };
74
65
  const sessionPolicyRecord = nestedOptions(opts.sessionPolicy, "sessionPolicy", NESTED_SESSION_POLICY_OPTION_KEYS);
@@ -86,16 +77,13 @@ export class FileStorageBackend {
86
77
  const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
87
78
  const repo = new FileSessionRepo(this.root, corruptRead);
88
79
  this.fileSessions = repo;
89
- this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } }, ...(opts.sessions !== undefined ? { hooks: opts.sessions } : {}) });
80
+ this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } }, retention, ...(opts.sessions !== undefined ? { hooks: opts.sessions } : {}) });
90
81
  this.sessionStore = this.ttl;
91
82
  const sessionHeadOf = this.ttl.headOf;
92
- this.fileCheckpoints = new FileCheckpointStore(this.root, { ...checkpointOptions, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
83
+ this.fileCheckpoints = new FileCheckpointStore(this.root, { ...checkpointOptions, ...corruptRead, retention, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
93
84
  built.push(() => this.fileCheckpoints.close());
94
85
  this.checkpointStore = this.fileCheckpoints;
95
- this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
96
- built.push(() => this.fileMemory.close());
97
- this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
98
- this.toolResultStore = new FileToolResultStore(this.root, corruptRead);
86
+ this.toolResultStore = new FileToolResultStore(this.root, { ...corruptRead, retention });
99
87
  this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...sessionPolicyOptions, ...corruptRead });
100
88
  this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root, true, corruptRead);
101
89
  built.push(() => this.fileWorkflowJournal.dispose());
@@ -142,12 +130,6 @@ export class FileStorageBackend {
142
130
  catch {
143
131
  }
144
132
  this.fileCheckpoints.close();
145
- try {
146
- await this.fileMemory.flushEmbeds();
147
- }
148
- catch {
149
- }
150
- this.fileMemory.close();
151
133
  this.fileWorkflowJournal.dispose();
152
134
  try {
153
135
  this.fileAgentRows.close();
@@ -251,6 +251,40 @@ export declare class FileDurableRulePartitionProvider implements DurableRulePart
251
251
  * into a retired bucket. A corrupt marker throws (fail-closed) rather than guessing an owner.
252
252
  */
253
253
  forLocalOwner(): DurableRulePartition;
254
+ /**
255
+ * The owners this directory can NAME that hold a bucket here, and how many buckets it cannot name — the one listing a host
256
+ * that must visit every bucket (a one-time migration over the rules of every owner) reads, so a bucket no record points at is
257
+ * not skipped. Names only: no rule, tombstone or revision is read, and no bucket file is opened.
258
+ *
259
+ * A bucket's file is named by a one-way digest of its owner (`principalRuleFileName`) and holds no owner name, so the
260
+ * directory names an owner only by what it records: `local-owner` when the local-owner bucket file is present, and the principals
261
+ * the adoption marker names (the adopted principal, and a principal source) when their bucket file is present. After an adoption
262
+ * the renamed bucket is the adopted principal's, so it is listed under that name whether or not any approval record ever named it.
263
+ * Every other digest-named bucket file is counted in `unnamedBuckets` — present, unreadable as to whose, and never silently
264
+ * dropped. A host reads `owners` through {@link forPrincipal} / {@link forLocalOwner} like any owner it knows; `unnamedBuckets > 0`
265
+ * says its census of owners is incomplete by that many, not that they are empty.
266
+ *
267
+ * A host may know owners the directory does not record (a File store beside this one derives some from its own import records):
268
+ * `opts.knownOwners` hands those principal names over, and each one whose bucket file is present here (the file the one digest,
269
+ * {@link principalRuleFileName}, names for it — the host never computes a bucket name) is listed in `owners`, after the ones the
270
+ * directory names, and is no longer counted in `unnamedBuckets`; so `unnamedBuckets` is then the count of buckets neither the
271
+ * directory nor the host can name (#3494). A name the host gives whose file is absent lists nothing and changes nothing, and a
272
+ * name given twice (or one the marker names too) is one owner. It is a plain object with that one member, and a list of
273
+ * principal names ({@link principalNameOf}: the one reading every face that takes a name judges by) — anything else refuses
274
+ * (`config.invalid_argument`), before the directory is looked at, rather than being read as "no known owners".
275
+ *
276
+ * Reading takes no lock and writes nothing. A directory this engine refuses to use refuses with
277
+ * {@link PERMISSION_RULES_DAMAGED_BUCKET_CODE}, as the read faces refuse it; a listing that failed to read refuses with
278
+ * {@link PERMISSION_RULES_UNREADABLE_BUCKET_CODE} and the system error's name in `errno`; an adoption marker that does not read
279
+ * refuses as {@link forPrincipal} refuses it (the marker is the truth of whose bucket is whose, so a listing never guesses
280
+ * past it). An absent directory lists nothing.
281
+ */
282
+ listBucketOwners(opts?: {
283
+ readonly knownOwners?: readonly string[];
284
+ }): {
285
+ readonly owners: readonly RuleOwner[];
286
+ readonly unnamedBuckets: number;
287
+ };
254
288
  /** Release the writer lock. A long-lived deployment holds it for its lifetime; a test or a short-lived
255
289
  * tool releases so the next holder is not told a live process owns the directory. */
256
290
  dispose(): void;
@@ -1,17 +1,18 @@
1
- import { closeSync, constants as FS, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
1
+ import { closeSync, constants as FS, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { createHash, randomBytes } from "node:crypto";
4
4
  import { isRuleBehavior } from "../../core/permission-rule-model.js";
5
5
  import { posixModeBitsMeaningful } from "../../core/posix-mode-face.js";
6
6
  import { readRuleOwner } from "../../core/rule-owner.js";
7
- import { principalNameOf, readPrincipal } from "../../core/principal-name.js";
8
- import { PERMISSION_RULES_LATER_GRAMMAR_CODE, PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
7
+ import { principalNameFault, principalNameOf, readPrincipal } from "../../core/principal-name.js";
8
+ import { PERMISSION_RULES_DAMAGED_BUCKET_CODE, PERMISSION_RULES_LATER_GRAMMAR_CODE, PERMISSION_RULES_UNREADABLE_BUCKET_CODE, PERMISSION_RULE_WRITER, applySyncJoin, applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, unknownRuleWriteDeltaError, } from "../../core/permission-rule-store.js";
9
9
  import { sameOrgPolicyContent } from "../../core/permission-rule-org.js";
10
10
  import { SESSION_RULES_GRAMMAR, readRuleGrammarStamp } from "../../core/session-policy-store.js";
11
11
  import { canonicalize } from "../../core/canonical-json.js";
12
12
  import { BootLock, FileStoreLockError } from "./fs-atomic.js";
13
13
  import { assertAdoptionBootGate } from "./adoption/marker.js";
14
- import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
14
+ import { CONFIG_RECEIPT_MODE, optionKeys, receiptRefusal, receiveMembers, receiveOptions } from "../../core/own-property-receipt.js";
15
+ import { describeFault, receive } from "../../core/mods/kernel/receive.js";
15
16
  import { thrownText } from "../../core/thrown-value.js";
16
17
  function isRuleFile(v) {
17
18
  const p = v;
@@ -31,6 +32,7 @@ export const ORG_STATE_FILE = "org.json";
31
32
  export class OrgRevisionRefusal extends Error {
32
33
  }
33
34
  const LOCAL_OWNER_FILE = "local-owner.json";
35
+ const HASHED_BUCKET_FILE = /^[0-9a-f]{64}\.json$/;
34
36
  const ADOPTION_FILE = "PERMISSION-RULES-ADOPTION.json";
35
37
  function judgeRuleAdoptionFile(dir) {
36
38
  let raw;
@@ -143,7 +145,18 @@ function refusalText(onError, sentence, location) {
143
145
  return `${sentence}. The location is reported to the store's error disclosure (onError), not in this message.`;
144
146
  }
145
147
  function unreadableError(r, sentence = r.unreadable) {
146
- return r.code !== undefined ? Object.assign(new Error(sentence), { code: r.code }) : new Error(sentence);
148
+ return Object.assign(new Error(sentence), { code: r.code, ...(r.errno !== undefined ? { errno: r.errno } : {}) });
149
+ }
150
+ function errnoOf(err) {
151
+ const code = err?.code;
152
+ return typeof code === "string" && /^E[A-Z0-9]+$/.test(code) ? code : undefined;
153
+ }
154
+ function systemFaultRefusal(onError, err, sentence, location) {
155
+ const errno = errnoOf(err);
156
+ const unreadable = refusalText(onError, sentence, location);
157
+ if (errno === "EEXIST" || errno === "ENOTDIR")
158
+ return { unreadable, code: PERMISSION_RULES_DAMAGED_BUCKET_CODE };
159
+ return { unreadable, code: PERMISSION_RULES_UNREADABLE_BUCKET_CODE, ...(errno !== undefined ? { errno } : {}) };
147
160
  }
148
161
  function discloseTo(onError, message) {
149
162
  try {
@@ -153,9 +166,15 @@ function discloseTo(onError, message) {
153
166
  }
154
167
  }
155
168
  function assertSafeDirAtRequest(dir, onError, act, vetting) {
156
- const fault = unsafeDirFault(dir, vetting);
169
+ let fault;
170
+ try {
171
+ fault = unsafeDirFault(dir, vetting);
172
+ }
173
+ catch (err) {
174
+ throw unreadableError(systemFaultRefusal(onError, err, `the permission-rule store directory could not be examined (${err?.code ?? err?.name ?? "unknown"}); refusing to ${act} it`, `${dir}: ${thrownText(err)}`));
175
+ }
157
176
  if (fault !== undefined)
158
- throw new Error(refusalText(onError, `the permission-rule store directory ${fault}; refusing to ${act} it`, dir));
177
+ throw unreadableError({ unreadable: refusalText(onError, `the permission-rule store directory ${fault}; refusing to ${act} it`, dir), code: PERMISSION_RULES_DAMAGED_BUCKET_CODE });
159
178
  }
160
179
  function writerLockRefusal(err, onError) {
161
180
  let sentence;
@@ -194,7 +213,7 @@ class FileDurableRulePartition {
194
213
  read() {
195
214
  const bucket = "this owner's permission-rule bucket";
196
215
  const whole = "refusing the whole file and loading zero rules — repair the file, or remove it (removing it gives up every rule and tombstone it held)";
197
- const unreadable = (sentence, location = this.file) => ({ unreadable: refusalText(this.onError, sentence, location) });
216
+ const unreadable = (sentence, location = this.file) => ({ unreadable: refusalText(this.onError, sentence, location), code: PERMISSION_RULES_DAMAGED_BUCKET_CODE });
198
217
  let raw;
199
218
  try {
200
219
  const dirFault = unsafeDirFault(this.dir, this.vetting);
@@ -209,7 +228,7 @@ class FileDurableRulePartition {
209
228
  const e = err;
210
229
  if (e?.code === "ENOENT")
211
230
  return { absent: true };
212
- return unreadable(`${bucket} could not be read (${e?.code ?? err?.name ?? "unknown"}); loading zero rules`, `${this.file}: ${thrownText(err)}`);
231
+ return systemFaultRefusal(this.onError, err, `${bucket} could not be read (${e?.code ?? err?.name ?? "unknown"}); loading zero rules`, `${this.file}: ${thrownText(err)}`);
213
232
  }
214
233
  let parsed;
215
234
  try {
@@ -404,6 +423,31 @@ class FileDurableRulePartition {
404
423
  };
405
424
  }
406
425
  const FILE_DURABLE_RULE_PARTITION_PROVIDER_OPTION_KEYS = optionKeys()({ dataRoot: 0, platform: 0 });
426
+ const LIST_BUCKET_OWNERS_OPTION_KEYS = optionKeys()({ knownOwners: 0 });
427
+ function receiveKnownOwners(opts) {
428
+ if (opts === undefined)
429
+ return [];
430
+ const given = receiveMembers(opts, { subject: "listBucketOwners options", unit: "option", moment: "at listBucketOwners" }, LIST_BUCKET_OWNERS_OPTION_KEYS).knownOwners;
431
+ if (given === undefined)
432
+ return [];
433
+ const received = receive(given, CONFIG_RECEIPT_MODE);
434
+ if (!received.ok)
435
+ throw receiptRefusal(`listBucketOwners options.knownOwners could not be read — ${describeFault(received.fault)}; refused rather than read as "no known owners"`);
436
+ const list = received.value;
437
+ if (!Array.isArray(list) || list === given) {
438
+ throw receiptRefusal(`listBucketOwners options.knownOwners must be an array of principal names (got ${given === null ? "null" : Array.isArray(given) ? "an array the engine cannot copy" : typeof given}); refused rather than read as "no known owners"`);
439
+ }
440
+ const names = new Set();
441
+ for (let index = 0; index < list.length; index++) {
442
+ const element = Object.hasOwn(list, index) ? list[index] : undefined;
443
+ const name = principalNameOf(element);
444
+ if (name === undefined) {
445
+ throw receiptRefusal(`listBucketOwners options.knownOwners[${index}] is not a principal name (got ${principalNameFault(element)}); refused rather than skipped — a skipped name would be counted as a bucket nobody can name`);
446
+ }
447
+ names.add(name);
448
+ }
449
+ return [...names];
450
+ }
407
451
  export class FileDurableRulePartitionProvider {
408
452
  dir;
409
453
  onError;
@@ -487,6 +531,57 @@ export class FileDurableRulePartitionProvider {
487
531
  }
488
532
  return new FileDurableRulePartition(this.dir, join(this.dir, LOCAL_OWNER_FILE), this.acquireWriteLock, this.onError, this.vetting);
489
533
  }
534
+ listBucketOwners(opts) {
535
+ const knownOwners = receiveKnownOwners(opts);
536
+ const faulted = (err, what) => unreadableError(systemFaultRefusal(this.onError, err, `the permission-rule store directory could not be ${what} (${err?.code ?? err?.name ?? "unknown"})`, `${this.dir}: ${thrownText(err)}`));
537
+ try {
538
+ lstatSync(this.dir);
539
+ }
540
+ catch (err) {
541
+ if (err?.code === "ENOENT")
542
+ return Object.freeze({ owners: Object.freeze([]), unnamedBuckets: 0 });
543
+ throw faulted(err, "examined");
544
+ }
545
+ let dirFault;
546
+ try {
547
+ dirFault = unsafeDirFault(this.dir, this.vetting);
548
+ }
549
+ catch (err) {
550
+ throw faulted(err, "examined");
551
+ }
552
+ if (dirFault !== undefined) {
553
+ throw unreadableError({ unreadable: refusalText(this.onError, `the permission-rule store directory ${dirFault}; refusing to list its buckets`, this.dir), code: PERMISSION_RULES_DAMAGED_BUCKET_CODE });
554
+ }
555
+ const adoption = this.adoptionMarker();
556
+ const rec = adoption === undefined ? undefined : "adopted" in adoption ? adoption.adopted : adoption.marker;
557
+ let names;
558
+ try {
559
+ names = new Set(readdirSync(this.dir));
560
+ }
561
+ catch (err) {
562
+ throw faulted(err, "listed");
563
+ }
564
+ const owners = [];
565
+ if (names.has(LOCAL_OWNER_FILE))
566
+ owners.push({ kind: "local-owner" });
567
+ const claimed = new Set();
568
+ const named = new Set();
569
+ for (const principal of [rec?.toPrincipal, rec?.from.kind === "principal" ? rec.from.principal : undefined, ...knownOwners]) {
570
+ if (principal === undefined || named.has(principal))
571
+ continue;
572
+ named.add(principal);
573
+ const file = principalRuleFileName(principal);
574
+ if (!names.has(file))
575
+ continue;
576
+ claimed.add(file);
577
+ owners.push({ kind: "principal", principal });
578
+ }
579
+ let unnamedBuckets = 0;
580
+ for (const name of names)
581
+ if (HASHED_BUCKET_FILE.test(name) && !claimed.has(name))
582
+ unnamedBuckets++;
583
+ return Object.freeze({ owners: Object.freeze(owners), unnamedBuckets });
584
+ }
490
585
  dispose() {
491
586
  this.lock?.release();
492
587
  this.lock = undefined;
@@ -55,7 +55,7 @@ class FileSessionStorage extends BaseSessionStorage {
55
55
  this.log.close();
56
56
  }
57
57
  isViewOf(row) {
58
- return this.log.isFileAtPath() && compareOccupants(this.occupant, row) !== "different";
58
+ return this.log.isFileAtPath() && compareOccupants(this.occupant, row) === "same";
59
59
  }
60
60
  persistSync(entry) {
61
61
  this.log.append({ kind: "entry", entry }, true);
@@ -1,3 +1,4 @@
1
+ import { type RetentionDeclaration } from "../../core/retention.js";
1
2
  import type { ToolResultDeletionReport, ToolResultProvenance, ToolResultSessionListing, ToolResultSlice, ToolResultStore } from "../../core/tool-result-store.js";
2
3
  import { type CorruptReadInfo } from "./corrupt-read-sink.js";
3
4
  /**
@@ -32,8 +33,13 @@ export interface FileToolResultStoreOptions {
32
33
  * FileToolResultStore.ownerOf} answers `undefined` — the same word it uses for an entry nobody owns,
33
34
  * so a host that authorizes on it reads damage as "unowned". Swallow-guarded. */
34
35
  onCorruptRead?: (info: CorruptReadInfo) => void;
36
+ /** The store's managed-retention declaration (retention.ts), stated by the party that runs the sweep; default `"none"`, a third
37
+ * word refused (`config.retention_capability`). */
38
+ retention?: RetentionDeclaration;
35
39
  }
36
40
  export declare class FileToolResultStore implements ToolResultStore {
41
+ /** {@link FileToolResultStoreOptions.retention}, as read at construction. */
42
+ readonly retention: RetentionDeclaration;
37
43
  private readonly dir;
38
44
  private readonly discloseCorrupt;
39
45
  constructor(root: string, options?: FileToolResultStoreOptions);
@@ -116,6 +122,14 @@ export declare class FileToolResultStore implements ToolResultStore {
116
122
  reap(now: number, opts?: {
117
123
  maxAgeMs?: number;
118
124
  }): number;
125
+ /**
126
+ * Delete the entries with no owner record stored before `cutoffMs` (interface: {@link ToolResultStore.deleteUnattributable}): a
127
+ * content file with no owner record beside it. A present owner record keeps its entry whether it reads or not, and age is the
128
+ * content file's modification time, as {@link reap} reads it — so a `put` caught between its content and its owner record (its
129
+ * content is as new as the write) is never past a cutoff in the past. The owner record is looked for again just before the
130
+ * unlink, so one that landed after the listing still keeps its entry. Both namespaces; names this store writes only.
131
+ */
132
+ deleteUnattributable(cutoffMs: number): number;
119
133
  /**
120
134
  * The entries `sessionId` owns, as ref + recorded owner (interface: {@link ToolResultStore.listBySession}). The selection is
121
135
  * {@link deleteBySession}'s own: it walks the same two namespaces and matches on the SIDECAR's `sessionId`, never on a file name; a