@sema-agent/core 7.62.0 → 7.64.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (320) hide show
  1. package/CHANGELOG.md +936 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  23. package/dist/agents/subagent-transcript-placement.js +14 -0
  24. package/dist/agents/subagent.js +102 -54
  25. package/dist/brain/route-adjudicator.js +9 -4
  26. package/dist/core/allow-entry.d.ts +4 -0
  27. package/dist/core/approval-object.js +1 -1
  28. package/dist/core/arg-summary.js +1 -1
  29. package/dist/core/ask-origin.d.ts +1 -1
  30. package/dist/core/ask-origin.js +2 -2
  31. package/dist/core/ask-question.d.ts +2 -2
  32. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  33. package/dist/core/ask-unresolvable-notice.js +10 -3
  34. package/dist/core/auto-compaction.d.ts +7 -5
  35. package/dist/core/background-agent-store.d.ts +7 -0
  36. package/dist/core/background-agent-store.js +3 -0
  37. package/dist/core/canonical-json.d.ts +23 -13
  38. package/dist/core/canonical-json.js +4 -4
  39. package/dist/core/checkpoint-queries.d.ts +50 -4
  40. package/dist/core/checkpoint-queries.js +42 -17
  41. package/dist/core/checkpoint-requirements.d.ts +3 -3
  42. package/dist/core/checkpoint-requirements.js +2 -1
  43. package/dist/core/checkpoint-row-verdict.d.ts +15 -4
  44. package/dist/core/checkpoint-row-verdict.js +22 -2
  45. package/dist/core/checkpoint-store.d.ts +28 -11
  46. package/dist/core/checkpoint-store.js +45 -4
  47. package/dist/core/compliance.d.ts +6 -2
  48. package/dist/core/compliance.js +3 -3
  49. package/dist/core/context-settings.d.ts +40 -9
  50. package/dist/core/context-settings.js +32 -10
  51. package/dist/core/engine-attestation.d.ts +27 -7
  52. package/dist/core/engine-attestation.js +5 -1
  53. package/dist/core/engine-notice.d.ts +43 -5
  54. package/dist/core/extension-requester.d.ts +9 -0
  55. package/dist/core/extension-requester.js +7 -0
  56. package/dist/core/file-history-store.d.ts +28 -0
  57. package/dist/core/file-history-store.js +48 -5
  58. package/dist/core/fs-write-gate-policy.js +1 -1
  59. package/dist/core/gate-fold.js +2 -0
  60. package/dist/core/gate-lanes.js +2 -0
  61. package/dist/core/gate-outcome.d.ts +39 -2
  62. package/dist/core/gate-outcome.js +20 -1
  63. package/dist/core/git-worktree-env.d.ts +62 -3
  64. package/dist/core/git-worktree-env.js +91 -30
  65. package/dist/core/governance-codes.d.ts +9 -3
  66. package/dist/core/governance-codes.js +17 -3
  67. package/dist/core/leg-identity.d.ts +19 -1
  68. package/dist/core/leg-identity.js +12 -0
  69. package/dist/core/mailbox-store.d.ts +39 -4
  70. package/dist/core/mailbox-store.js +14 -2
  71. package/dist/core/memory-engine/consolidation-driver.d.ts +32 -17
  72. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  73. package/dist/core/memory-engine/consolidation.d.ts +74 -10
  74. package/dist/core/memory-engine/consolidation.js +183 -11
  75. package/dist/core/memory-engine/control-objects.d.ts +25 -0
  76. package/dist/core/memory-engine/control-objects.js +151 -0
  77. package/dist/core/memory-engine/control-plane-adoption.d.ts +48 -0
  78. package/dist/core/memory-engine/control-plane-adoption.js +159 -0
  79. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  80. package/dist/core/memory-engine/data-plane.js +11 -6
  81. package/dist/core/memory-engine/delegation-settlement.d.ts +58 -40
  82. package/dist/core/memory-engine/delegation-settlement.js +270 -85
  83. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  84. package/dist/core/memory-engine/dual-root.js +11 -7
  85. package/dist/core/memory-engine/engine.d.ts +136 -58
  86. package/dist/core/memory-engine/engine.js +491 -394
  87. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  88. package/dist/core/memory-engine/entry-scan.js +3 -0
  89. package/dist/core/memory-engine/file-backend.d.ts +62 -60
  90. package/dist/core/memory-engine/file-backend.js +122 -198
  91. package/dist/core/memory-engine/index.d.ts +8 -7
  92. package/dist/core/memory-engine/index.js +7 -6
  93. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  94. package/dist/core/memory-engine/landing-admission.js +3 -3
  95. package/dist/core/memory-engine/layout.d.ts +127 -46
  96. package/dist/core/memory-engine/layout.js +264 -109
  97. package/dist/core/memory-engine/memory-backend-contract.d.ts +26 -1
  98. package/dist/core/memory-engine/memory-backend-contract.js +476 -0
  99. package/dist/core/memory-engine/memory-deployment.d.ts +42 -11
  100. package/dist/core/memory-engine/memory-deployment.js +54 -15
  101. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  102. package/dist/core/memory-engine/origin-clearance.js +68 -9
  103. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  104. package/dist/core/memory-engine/scope-contract.js +68 -19
  105. package/dist/core/memory-engine/session-write-home.d.ts +37 -2
  106. package/dist/core/memory-engine/session-write-home.js +38 -11
  107. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  108. package/dist/core/memory-engine/sync-client.js +7 -0
  109. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  110. package/dist/core/memory-engine/sync-report.js +6 -2
  111. package/dist/core/memory-engine/tools.d.ts +2 -2
  112. package/dist/core/memory-engine/tools.js +10 -10
  113. package/dist/core/memory-engine/types.d.ts +155 -19
  114. package/dist/core/memory-engine/types.js +2 -0
  115. package/dist/core/memory.js +15 -6
  116. package/dist/core/mode-policy.js +3 -3
  117. package/dist/core/mods/agent-stations.d.ts +18 -0
  118. package/dist/core/mods/agent-stations.js +8 -6
  119. package/dist/core/mods/extension-call.d.ts +4 -0
  120. package/dist/core/mods/extension-call.js +8 -0
  121. package/dist/core/mods/stations.d.ts +20 -1
  122. package/dist/core/mods/stations.js +21 -2
  123. package/dist/core/mods/tool-call.js +3 -4
  124. package/dist/core/parent-spec-seat.d.ts +2 -2
  125. package/dist/core/park-selfcheck.js +2 -2
  126. package/dist/core/pause-registry.d.ts +2 -0
  127. package/dist/core/pause-registry.js +3 -0
  128. package/dist/core/peer-channel.d.ts +5 -0
  129. package/dist/core/permission-rule-consent.d.ts +26 -8
  130. package/dist/core/permission-rule-consent.js +76 -36
  131. package/dist/core/permission-rule-store.d.ts +72 -13
  132. package/dist/core/permission-rule-store.js +29 -8
  133. package/dist/core/read-only-shell.js +3 -2
  134. package/dist/core/redaction-marks.d.ts +8 -0
  135. package/dist/core/redaction-marks.js +6 -0
  136. package/dist/core/refusal-echo.d.ts +20 -0
  137. package/dist/core/refusal-echo.js +33 -0
  138. package/dist/core/remote-env.d.ts +12 -1
  139. package/dist/core/remote-env.js +3 -0
  140. package/dist/core/retention.d.ts +180 -10
  141. package/dist/core/retention.js +45 -0
  142. package/dist/core/retired-keys.d.ts +5 -0
  143. package/dist/core/retired-keys.js +3 -0
  144. package/dist/core/rule-offer-read.d.ts +0 -4
  145. package/dist/core/rule-offer-read.js +2 -18
  146. package/dist/core/runner/child-tree.d.ts +29 -3
  147. package/dist/core/runner/child-tree.js +39 -16
  148. package/dist/core/runner/classifier-ladder.d.ts +7 -1
  149. package/dist/core/runner/classifier-ladder.js +4 -2
  150. package/dist/core/runner/compact-session.js +10 -7
  151. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  152. package/dist/core/runner/compaction-call-options.js +3 -2
  153. package/dist/core/runner/contracts.d.ts +39 -11
  154. package/dist/core/runner/delegation-owner.d.ts +10 -3
  155. package/dist/core/runner/delegation-owner.js +4 -1
  156. package/dist/core/runner/gate-exit.d.ts +6 -0
  157. package/dist/core/runner/gate-exit.js +13 -4
  158. package/dist/core/runner/inherited-ask-grants.js +1 -1
  159. package/dist/core/runner/memory-consolidation-driver.d.ts +10 -5
  160. package/dist/core/runner/memory-consolidation-driver.js +12 -9
  161. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  162. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  163. package/dist/core/runner/person-path-rows.d.ts +8 -3
  164. package/dist/core/runner/person-path-rows.js +5 -1
  165. package/dist/core/runner/placement-fence.d.ts +12 -0
  166. package/dist/core/runner/placement-fence.js +20 -6
  167. package/dist/core/runner/prepare-ask-lane.js +5 -5
  168. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -2
  169. package/dist/core/runner/prepare-caps-and-workflow.js +7 -4
  170. package/dist/core/runner/prepare-config-doors.js +4 -0
  171. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  172. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  173. package/dist/core/runner/prepare-execution-env.js +17 -6
  174. package/dist/core/runner/prepare-gate-stations.d.ts +5 -0
  175. package/dist/core/runner/prepare-gate-stations.js +5 -5
  176. package/dist/core/runner/prepare-hands-readface.d.ts +2 -1
  177. package/dist/core/runner/prepare-hands-readface.js +5 -4
  178. package/dist/core/runner/prepare-inherited-gate.d.ts +13 -9
  179. package/dist/core/runner/prepare-inherited-gate.js +12 -6
  180. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  181. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  182. package/dist/core/runner/prepare-memory.d.ts +7 -2
  183. package/dist/core/runner/prepare-memory.js +41 -39
  184. package/dist/core/runner/prepare-park-ask.js +4 -3
  185. package/dist/core/runner/prepare-policy-chain.js +7 -7
  186. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  187. package/dist/core/runner/prepare-task.js +26 -18
  188. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  189. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  190. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  191. package/dist/core/runner/resume-admission.d.ts +2 -2
  192. package/dist/core/runner/resume-admission.js +2 -23
  193. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  194. package/dist/core/runner/role-resolution-table.js +62 -0
  195. package/dist/core/runner/run-compaction-machinery.js +2 -2
  196. package/dist/core/runner/run-identity-wiring.js +12 -9
  197. package/dist/core/runner/run-leg.js +9 -5
  198. package/dist/core/runner/run-notification-lane.js +22 -22
  199. package/dist/core/runner/run-recovery-lanes.js +3 -3
  200. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  201. package/dist/core/runner/run-terminal-adoption.js +1 -1
  202. package/dist/core/runner/run-turn-boundary.js +14 -15
  203. package/dist/core/runner/runtask.js +1 -1
  204. package/dist/core/runner/terminal-account.js +1 -1
  205. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  206. package/dist/core/runner/tool-occurrence.js +2 -2
  207. package/dist/core/runner-deps.d.ts +7 -3
  208. package/dist/core/secret-env.d.ts +1 -1
  209. package/dist/core/secret-env.js +4 -4
  210. package/dist/core/session-checkout.d.ts +168 -0
  211. package/dist/core/session-checkout.js +579 -0
  212. package/dist/core/session-store.d.ts +12 -4
  213. package/dist/core/session-store.js +23 -3
  214. package/dist/core/session.d.ts +16 -2
  215. package/dist/core/session.js +3 -0
  216. package/dist/core/shell-read-silence.js +8 -0
  217. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +0 -12
  218. package/dist/core/store-contracts/checkpoint-store-contract.js +6 -7
  219. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  220. package/dist/core/store-contracts/session-store-contract.js +39 -0
  221. package/dist/core/task-event.d.ts +30 -5
  222. package/dist/core/task-notification.d.ts +119 -32
  223. package/dist/core/task-notification.js +186 -100
  224. package/dist/core/task-registry-agent.d.ts +25 -2
  225. package/dist/core/task-registry-agent.js +56 -22
  226. package/dist/core/task-registry-shared.d.ts +33 -11
  227. package/dist/core/task-registry.d.ts +33 -9
  228. package/dist/core/task-registry.js +36 -18
  229. package/dist/core/task-spec-members.js +1 -1
  230. package/dist/core/task-spec.d.ts +27 -2
  231. package/dist/core/tool-errors.d.ts +14 -6
  232. package/dist/core/tool-errors.js +1 -1
  233. package/dist/core/tool-policy.d.ts +32 -13
  234. package/dist/core/tool-policy.js +27 -17
  235. package/dist/core/tool-result-store.d.ts +20 -0
  236. package/dist/core/tool-spec.d.ts +42 -19
  237. package/dist/core/trace.d.ts +3 -2
  238. package/dist/core/types.d.ts +1 -1
  239. package/dist/core/untrusted-egress.d.ts +15 -4
  240. package/dist/core/untrusted-egress.js +23 -22
  241. package/dist/core/workflow-journal-store.d.ts +11 -0
  242. package/dist/core/workflow-journal-store.js +7 -0
  243. package/dist/core/workflow-run-store.d.ts +9 -0
  244. package/dist/core/workflow-run-store.js +6 -0
  245. package/dist/core/workspace-snapshot.d.ts +3 -1
  246. package/dist/core/workspace-snapshot.js +1 -0
  247. package/dist/engine/compaction/compaction.d.ts +2 -1
  248. package/dist/engine/harness/types.d.ts +67 -1
  249. package/dist/engine/harness/types.js +108 -0
  250. package/dist/engine/session/import-validate.js +6 -1
  251. package/dist/engine/session/session.d.ts +30 -1
  252. package/dist/engine/session/session.js +48 -1
  253. package/dist/index.d.ts +12 -7
  254. package/dist/index.js +12 -7
  255. package/dist/internal/harness-types.d.ts +1 -1
  256. package/dist/orchestration/run-workflow-tool.d.ts +8 -1
  257. package/dist/orchestration/run-workflow-tool.js +8 -0
  258. package/dist/orchestration/workflow-types.d.ts +2 -1
  259. package/dist/orchestration/workflow.d.ts +6 -0
  260. package/dist/orchestration/workflow.js +5 -2
  261. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  262. package/dist/stores/file/checkpoint-store.js +4 -1
  263. package/dist/stores/file/file-history-store.d.ts +13 -0
  264. package/dist/stores/file/file-history-store.js +75 -13
  265. package/dist/stores/file/index.d.ts +11 -1
  266. package/dist/stores/file/index.js +7 -11
  267. package/dist/stores/file/permission-rule-store.d.ts +23 -0
  268. package/dist/stores/file/permission-rule-store.js +75 -7
  269. package/dist/stores/file/session-store.js +2 -1
  270. package/dist/stores/file/tool-result-store.d.ts +14 -0
  271. package/dist/stores/file/tool-result-store.js +39 -2
  272. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  273. package/dist/stores/file/workflow-journal-store.js +17 -0
  274. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  275. package/dist/stores/file/workflow-run-store.js +15 -0
  276. package/dist/tools/fs/bash-program-position.js +3 -3
  277. package/dist/tools/fs/program-read-model.d.ts +34 -10
  278. package/dist/tools/fs/program-read-model.js +37 -7
  279. package/dist/tools/fs/program-read-model.rows.js +13 -2
  280. package/dist/tools/fs/read-deny.d.ts +28 -3
  281. package/dist/tools/fs/read-deny.js +18 -2
  282. package/dist/tools/fs/removal-targets.js +3 -3
  283. package/dist/tools/fs/safety.d.ts +2 -0
  284. package/dist/tools/fs/safety.js +1 -1
  285. package/dist/tools/fs/shell-read-argv.d.ts +8 -1
  286. package/dist/tools/fs/shell-read-argv.js +34 -29
  287. package/dist/tools/fs/shell-read-bindings.d.ts +2 -0
  288. package/dist/tools/fs/shell-read-bindings.js +5 -1
  289. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  290. package/dist/tools/fs/shell-read-brace.js +79 -0
  291. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  292. package/dist/tools/fs/shell-read-check.js +16 -14
  293. package/dist/tools/fs/shell-read-establish.js +23 -16
  294. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  295. package/dist/tools/fs/shell-read-judge.js +3 -3
  296. package/dist/tools/fs/shell-read-plan.d.ts +10 -0
  297. package/dist/tools/fs/shell-read-plan.js +189 -93
  298. package/dist/tools/fs/shell-read-start.d.ts +19 -9
  299. package/dist/tools/fs/shell-read-start.js +20 -12
  300. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  301. package/dist/tools/fs/shell-read-word.js +9 -5
  302. package/dist/tools/fs/shell-read-workdir.d.ts +26 -7
  303. package/dist/tools/fs/shell-read-workdir.js +73 -12
  304. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  305. package/dist/tools/worktree.d.ts +3 -2
  306. package/dist/tools/worktree.js +7 -35
  307. package/package.json +3 -2
  308. package/test/export-surface.snapshot.json +135 -11
  309. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  310. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  311. package/wire-changes/core@7.63.0.json +3523 -0
  312. package/wire-changes/core@7.64.0.json +2653 -0
  313. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  314. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  315. package/wire-changes/primitives@7.63.0.json +445 -0
  316. package/wire-changes/primitives@7.64.0.json +30 -0
  317. package/dist/core/credential-vocabulary.d.ts +0 -176
  318. package/dist/core/credential-vocabulary.js +0 -190
  319. package/dist/core/redaction-passes.d.ts +0 -82
  320. package/dist/core/redaction-passes.js +0 -377
@@ -17,14 +17,49 @@
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
- import type { MemoryEntry } from "./types.js";
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;
46
+ /** Where the session-account ledger is kept (the engine's governance store). */
47
+ docs: MemoryGovernanceDocs;
25
48
  sessionId: string;
26
49
  /** The caller's lineage read: entry id → this session's `lastAt` on it (undefined ⇔ that read faulted). */
27
50
  contributions: ReadonlyMap<string, number> | undefined;
28
51
  /** A committed, side-effect-free entry read (the engine's audit face). */
29
52
  readEntries: (ids: readonly string[]) => Promise<MemoryEntry[]>;
30
- }): 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,34 +1,61 @@
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))
13
16
  newest = { id, at };
14
17
  }
15
- const account = sessionAccountWriteHome(controlDir, sessionId);
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
  }
@@ -123,7 +123,9 @@ export interface MemorySyncClientConflict {
123
123
  export interface SyncMemoryScopeOptions {
124
124
  /** The LOCAL authority plane (TOC: the File backend). */
125
125
  backend: MemoryBackend;
126
- /** The scope this round syncs (one round = one scope, mirroring the server route). */
126
+ /** The scope this round syncs (one round = one scope, mirroring the server route). A scope that is not
127
+ * replicable ({@link isReplicableScope}: the `userlocal:` family) is refused with `config.memory_scope_key`
128
+ * before any read or request. */
127
129
  scope: string;
128
130
  /** The injected seam to the peer; its `peer` is the round's peer. */
129
131
  transport: MemorySyncTransport;
@@ -8,6 +8,7 @@ import { directoryPinOf } from "./dual-root.js";
8
8
  import { landingPathOf } from "./layout.js";
9
9
  import { egressText } from "../untrusted-egress.js";
10
10
  import { REDACTION_MARKS } from "../redaction-marks.js";
11
+ import { isReplicableScope } from "./scope-contract.js";
11
12
  const DROP_THE_CURSOR = "drop the cursor to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
12
13
  "and entries deleted on one side since the last round come back from the other side";
13
14
  const REFUSAL_ROWS = {
@@ -349,6 +350,12 @@ export async function syncMemoryScope(opts) {
349
350
  const { backend, scope, transport, cursor } = opts;
350
351
  if (!namesSomething(scope))
351
352
  throw new Error("memory sync: scope must be a non-empty string");
353
+ if (!isReplicableScope(scope)) {
354
+ const e = new Error(egressText("same-principal", `memory sync: scope ${quoted(scope)} is a userlocal: key — its layer never leaves the store it is written in, so no sync carries it; ` +
355
+ "nothing was read or sent. Leave this layer out of the sync (isReplicableScope)."));
356
+ e.code = "config.memory_scope_key";
357
+ throw e;
358
+ }
352
359
  const peer = transport?.peer;
353
360
  if (!namesSomething(peer))
354
361
  throw new Error("memory sync: transport.peer must be a non-empty string — a transport is { peer, post }, peer = the identity of the peer it reaches");
@@ -74,7 +74,7 @@ type RoundRefusal = {
74
74
  readonly code: "session_active";
75
75
  readonly message: string;
76
76
  };
77
- type GapWhy = "refused" | "failed" | "incomplete" | "not_replicated" | "not_read_at_destination";
77
+ type GapWhy = "local_only" | "refused" | "failed" | "incomplete" | "not_replicated" | "not_read_at_destination";
78
78
  /**
79
79
  * THE report of a memory sync — the one reading of how its `syncMemoryScope` calls settled, for every host that runs or
80
80
  * relays one. Give it the destination (`target`), the source revision, the source session's read set (`scopes`), and
@@ -93,7 +93,8 @@ export declare function memorySyncReportOf(round: {
93
93
  })): MemorySyncRoundReport;
94
94
  /**
95
95
  * What of a session's memory does not travel with it: every scope of the report's read set that did not arrive whole,
96
- * once, with why — `refused` (the sync, or its layer's last call, was refused and wrote nothing on either side), `failed`, `incomplete`,
96
+ * once, with why — `local_only` (the scope never replicates, {@link isReplicableScope}: whatever the sync did, its layer
97
+ * stays in the store it is written in), `refused` (the sync, or its layer's last call, was refused and wrote nothing on either side), `failed`, `incomplete`,
97
98
  * `not_replicated` (no layer was run for it), or `not_read_at_destination` (its layer synced, and the destination's
98
99
  * read set, when given, does not hold it). A scope absent from the result travelled. Keys are compared as written. A
99
100
  * report that is not one this engine's `memorySyncReportOf` could have minted (a layer with no scope, outside the read
@@ -1,5 +1,6 @@
1
1
  import { carriesCredential, readSyncRefusal } from "./sync-client.js";
2
2
  import { egressText, egressThrownText } from "../untrusted-egress.js";
3
+ import { isReplicableScope } from "./scope-contract.js";
3
4
  const OUTCOMES = new Set(["synced", "incomplete", "refused", "failed"]);
4
5
  const text = (s) => egressText("same-principal", s);
5
6
  function requireNamed(what, v) {
@@ -91,8 +92,9 @@ export function memoryTravelGapOf(report, readAtDestination) {
91
92
  throw new TypeError("memory travel gap: report must be a memory sync report");
92
93
  const scopes = requireNames("report.scopes", report.scopes);
93
94
  const destination = readAtDestination === undefined ? undefined : new Set(requireNames("readAtDestination", readAtDestination));
95
+ const localOnly = (scope) => !isReplicableScope(scope);
94
96
  if (!hasExactlyOne(report, "layers", "refused", "a sync report"))
95
- return scopes.map((scope) => ({ scope, why: "refused" }));
97
+ return scopes.map((scope) => ({ scope, why: localOnly(scope) ? "local_only" : "refused" }));
96
98
  const layers = report.layers;
97
99
  if (!Array.isArray(layers))
98
100
  throw new TypeError("memory travel gap: report.layers must be an array");
@@ -108,7 +110,9 @@ export function memoryTravelGapOf(report, readAtDestination) {
108
110
  const gap = [];
109
111
  for (const scope of scopes) {
110
112
  const layer = byScope.get(scope);
111
- if (layer === undefined)
113
+ if (localOnly(scope))
114
+ gap.push({ scope, why: "local_only" });
115
+ else if (layer === undefined)
112
116
  gap.push({ scope, why: "not_replicated" });
113
117
  else if (layer.outcome !== "synced")
114
118
  gap.push({ scope, why: layer.outcome });
@@ -69,11 +69,11 @@ export interface MemoryEnginePlane {
69
69
  * ledger must never read as "nothing withheld"). Absent ⇒ a plane with no control plane (direct
70
70
  * hosts / tests) — no exclusion, v1 behavior byte-identical.
71
71
  */
72
- challengeExclusions?: () => ReadonlyMap<string, {
72
+ challengeExclusions?: () => Promise<ReadonlyMap<string, {
73
73
  code: "challenged" | "lineage_pending";
74
74
  generation?: number;
75
75
  at?: number;
76
- }>;
76
+ }>>;
77
77
  /**
78
78
  * design/336 §5.5 — the recall-taint propagation seat, fired at the ONE tool-face content
79
79
  * delivery point of a marked entry (`memory_get`'s successful delivery; the search list never
@@ -5,7 +5,7 @@ import { defuseFenceMarkers, delimitUntrusted, FENCED_LANE_ENVELOPE_TAGS, inline
5
5
  import { formatMemoryAge } from "../memory-recall.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
- import { deriveSupersededSet, memorySupersededNote, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
8
+ import { deriveSupersededSet, memorySupersededNote, MEMORY_CHALLENGED_ENTRY_GUIDANCE, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
9
9
  import { deriveShadowedSet, memoryShadowedNote, shadowNamesOf, MEMORY_SEARCH_SHADOWED_TAG } from "./shadowing.js";
10
10
  import { mountRuleFace, toolFace } from "../tool-catalog-entries.js";
11
11
  export const MEMORY_SEARCH_TOOL_NAME = "memory_search";
@@ -251,7 +251,7 @@ export function createMemoryEngineTools(opts) {
251
251
  const exclusions = [];
252
252
  for (const plane of planes) {
253
253
  try {
254
- exclusions.push(plane.challengeExclusions?.());
254
+ exclusions.push(await plane.challengeExclusions?.());
255
255
  }
256
256
  catch {
257
257
  return refusedSearch("challenge_ledger_unavailable", "Memory search is unavailable: the challenge ledger for a mounted memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
@@ -321,7 +321,7 @@ export function createMemoryEngineTools(opts) {
321
321
  }
322
322
  let terminalExclusions;
323
323
  try {
324
- terminalExclusions = planes.map((plane) => plane.challengeExclusions?.());
324
+ terminalExclusions = await Promise.all(planes.map((plane) => plane.challengeExclusions?.()));
325
325
  }
326
326
  catch {
327
327
  return refusedSearch("challenge_ledger_unavailable", "Memory search is unavailable: the challenge ledger for a mounted memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
@@ -451,7 +451,7 @@ export function createMemoryEngineTools(opts) {
451
451
  pollutionSentence(), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
452
452
  }
453
453
  try {
454
- const names = await shadowNamesAcross(planes.map((plane) => plane.challengeExclusions?.()));
454
+ const names = await shadowNamesAcross(await Promise.all(planes.map((plane) => plane.challengeExclusions?.())));
455
455
  const [shadowed] = await pruneUndeliverableCarriers([shadowedOf(matches.map((m) => m.header), names)]);
456
456
  const standing = matches.filter((m) => shadowed?.has(m.header.id) !== true);
457
457
  if (standing.length > 0 && standing.length < matches.length) {
@@ -484,7 +484,7 @@ export function createMemoryEngineTools(opts) {
484
484
  }
485
485
  let withheld;
486
486
  try {
487
- withheld = entryPlane?.challengeExclusions?.().get(entry.id);
487
+ withheld = (await entryPlane?.challengeExclusions?.())?.get(entry.id);
488
488
  }
489
489
  catch {
490
490
  return refusedGet("challenge_ledger_unavailable", "Memory read is unavailable: the challenge ledger for this memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
@@ -492,7 +492,7 @@ export function createMemoryEngineTools(opts) {
492
492
  if (withheld !== undefined) {
493
493
  const genClause = withheld.generation !== undefined ? ` (challenge generation ${withheld.generation})` : "";
494
494
  const message = withheld.code === "challenged"
495
- ? `Memory entry ${entry.id} is withheld${genClause}: it has been challenged and its content is not available through memory tools. If the fact is still needed, verify it with the user and record a fresh entry from their current statement; tombstone the old entry.`
495
+ ? `Memory entry ${entry.id} is withheld${genClause}: it has been challenged and its content is not available through memory tools. ${MEMORY_CHALLENGED_ENTRY_GUIDANCE}`
496
496
  : `Memory entry ${entry.id} is withheld: its commit bookkeeping is unsettled (an interrupted transaction). It stays unavailable until the account reconciles or the host adjudicates.`;
497
497
  return refusedGet(withheld.code, message, "refused", {
498
498
  id: entry.id,
@@ -504,7 +504,7 @@ export function createMemoryEngineTools(opts) {
504
504
  let supersededBy;
505
505
  if (entryPlane !== undefined) {
506
506
  try {
507
- supersededBy = (await supersededOf(entryPlane, entryPlane.challengeExclusions?.())).get(entry.id);
507
+ supersededBy = (await supersededOf(entryPlane, await entryPlane.challengeExclusions?.())).get(entry.id);
508
508
  }
509
509
  catch {
510
510
  supersededBy = undefined;
@@ -513,7 +513,7 @@ export function createMemoryEngineTools(opts) {
513
513
  let shadowedBy;
514
514
  if (entryHeader !== undefined) {
515
515
  try {
516
- const names = await shadowNamesAcross(planes.map((plane) => plane.challengeExclusions?.()));
516
+ const names = await shadowNamesAcross(await Promise.all(planes.map((plane) => plane.challengeExclusions?.())));
517
517
  const [pruned] = await pruneUndeliverableCarriers([shadowedOf([entryHeader], names)]);
518
518
  shadowedBy = pruned?.get(entry.id);
519
519
  }
@@ -659,7 +659,7 @@ export function createMemoryEngineTools(opts) {
659
659
  const exclusions = [];
660
660
  for (const plane of planes) {
661
661
  try {
662
- exclusions.push(plane.challengeExclusions?.());
662
+ exclusions.push(await plane.challengeExclusions?.());
663
663
  }
664
664
  catch {
665
665
  return refusedIndex("challenge_ledger_unavailable", "Memory listing is unavailable: the challenge ledger for a mounted memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
@@ -774,7 +774,7 @@ export function createMemoryEngineTools(opts) {
774
774
  }
775
775
  let terminalExclusions;
776
776
  try {
777
- terminalExclusions = planes.map((plane) => plane.challengeExclusions?.());
777
+ terminalExclusions = await Promise.all(planes.map((plane) => plane.challengeExclusions?.()));
778
778
  }
779
779
  catch {
780
780
  return refusedIndex("challenge_ledger_unavailable", "Memory listing is unavailable: the challenge ledger for a mounted memory plane cannot be read (fail-closed). Report this to the operator.", "failed");
@@ -1,3 +1,6 @@
1
+ import type { ConsolidationGateRow, ConsolidationIntentCredentialRow, ConsolidationPlanFile, ConsolidationPlanRead } from "./consolidation.js";
2
+ import type { ConsolidationDriverRunRow } from "./consolidation-driver.js";
3
+ import type { LlmConsolidationPlan } from "./distiller.js";
1
4
  /**
2
5
  * design/336 §2.1 — the closed `cause` vocabulary of {@link MemoryEntryOrigin}. Mechanical facts
3
6
  * only (no free text, no tool names, no session ids — those stay on the control plane):
@@ -89,8 +92,9 @@ export interface MemoryEntryFrontmatter {
89
92
  description?: string;
90
93
  /** CC `metadata.type`: user | feedback | project | reference (unknown strings degrade, design/65). */
91
94
  type?: string;
92
- /** design/138 §2.4 删除防线 — the EXPLICIT tombstone. A file that merely disappears is NEVER a
93
- * delete; only `deleted: true` in frontmatter produces a delete patch. */
95
+ /** design/138 §2.4 — the frontmatter tombstone: `deleted: true` reads as the entry's deletion (the
96
+ * sync channel and the inclusion ladder carry deletions in this form). On the harvest's write face
97
+ * it is one of two spellings of the same delete — the other is removing the file. */
94
98
  deleted?: boolean;
95
99
  /**
96
100
  * design-A C-5 (AGENTS.md×ingest, [A1]) — TYPED provenance for entries an INGEST producer minted
@@ -409,7 +413,136 @@ export interface MemoryBackend {
409
413
  /** design/84 Seam B cursor pair, migrated verbatim onto the entry-id plane (S2 rewires consolidation). */
410
414
  getConsolidationCursor(scope: string): Promise<string | undefined>;
411
415
  setConsolidationCursor(scope: string, cursor: string): Promise<void>;
416
+ /** The consolidation state's store (gate rows, plan workbook, intent credentials, driver run account, mint archive):
417
+ * present ⇒ the engine keeps that state here, beside this backend's entries; absent ⇒ the engine keeps it in the
418
+ * replica's own control plane (`fileGovernanceStore` over it). The File backend always carries it, over its own
419
+ * control plane, byte for byte what the files were. Whether the state a consolidation reads survives the replica
420
+ * is answered by `memoryGovernanceDurability`, never by probing this member. */
421
+ readonly governance?: MemoryGovernanceStore;
412
422
  }
423
+ /**
424
+ * One transaction over the consolidation gate rows (every scope's row — one document) and the plan workbook: `fn`
425
+ * runs once, synchronously, over the rows and the plans named in `planIds` as they stood when the transaction took
426
+ * its serialization; its plan writes and — when it answers `writeGate: true` — its row changes are written after it
427
+ * returns, plans first, then the rows (a throw inside `fn` writes nothing and propagates unchanged). A failure while
428
+ * those writes land is not rolled back: the File store leaves the plans already written, as 7.62.0 did, and the
429
+ * engine never asks one transaction for a plan write and a row write together (each of its plan writes is its own
430
+ * transaction), so no reader meets half of one. Nobody else's transaction lands between the reads it saw and its
431
+ * writes: the plan owner fence (read the applier, then write the plan) relies on it.
432
+ */
433
+ export interface ConsolidationTx {
434
+ /** Every scope's gate row, mutable in place (a row added here is written when the transaction answers `writeGate`). */
435
+ readonly scopes: Record<string, ConsolidationGateRow>;
436
+ /** A plan named in the transaction's `planIds` as it stood (a plan not named ⇒ throws: it was not read under the transaction). */
437
+ plan(planId: string): ConsolidationPlanRead;
438
+ /** Stage a plan write; committed with the transaction. */
439
+ writePlan(plan: ConsolidationPlanFile): void;
440
+ }
441
+ /**
442
+ * The consolidation state's store contract ({@link MemoryBackend.governance}). Every read of a malformed record throws
443
+ * `ControlPlaneCorruptError` (fail-closed); a record that was never written reads as absent / empty — a missing row is
444
+ * never a corrupt one, and a corrupt one is never read as missing. `memoryGovernanceStoreContract` (the kit) states
445
+ * each clause as a case.
446
+ */
447
+ export interface MemoryGovernanceStore {
448
+ /** See {@link ConsolidationTx}. */
449
+ transact<T>(planIds: readonly string[], fn: (tx: ConsolidationTx) => {
450
+ writeGate: boolean;
451
+ result: T;
452
+ }): Promise<T>;
453
+ /** Every scope's gate row as last committed. */
454
+ readGate(): Promise<Record<string, ConsolidationGateRow>>;
455
+ /** A plan as last committed (`corrupt` carries the reason; an id outside the plan-id grammar reads `absent`). The one
456
+ * dual-form read: a store that answers synchronously (the File store) lets the engine confirm the plan's holder
457
+ * under a landing-admitting backend's lock, before each commit; a Promise answer has each patch applied alone, the
458
+ * holder read before each. */
459
+ readPlan(planId: string): ConsolidationPlanRead | Promise<ConsolidationPlanRead>;
460
+ /** The workbook's plan ids (custody copies excluded). */
461
+ listPlanIds(): Promise<string[]>;
462
+ /** Move a plan the valve discards aside, never deleting its bytes; answers the custody name, `undefined` when there was nothing to move. */
463
+ quarantinePlan(planId: string): Promise<string | undefined>;
464
+ /** Record intent credentials, idempotent on requestId (a standing row wins); answers the requestIds written. */
465
+ recordIntents(rows: readonly ConsolidationIntentCredentialRow[]): Promise<string[]>;
466
+ readIntents(): Promise<Record<string, ConsolidationIntentCredentialRow>>;
467
+ /** The run claim, one compare-and-set: a pending run of the scope is resumed (its `attempt` bumped — the writer
468
+ * takeover), otherwise `fresh()` opens a new one. */
469
+ claimRun(scope: string, fresh: () => ConsolidationDriverRunRow): Promise<{
470
+ row: ConsolidationDriverRunRow;
471
+ resumed: boolean;
472
+ }>;
473
+ readRun(scope: string): Promise<ConsolidationDriverRunRow | undefined>;
474
+ /** Write a run row only while the scope's standing claim is this row's `(runId, attempt)`; a newer claim refuses
475
+ * `memory.consolidation_driver_superseded` and writes nothing. */
476
+ writeRun(row: ConsolidationDriverRunRow): Promise<void>;
477
+ /** Archive one mint (what the model was shown and answered, verbatim) under the claim's name; answers the name. */
478
+ archiveMint(runId: string, attempt: number, plan: LlmConsolidationPlan): Promise<string>;
479
+ /** A mint archive by name (`undefined` when there is none). */
480
+ readMint(name: string): Promise<LlmConsolidationPlan | undefined>;
481
+ /** Erase a mint archive (its bytes gone, not moved); answers whether one was there. */
482
+ eraseMint(name: string): Promise<boolean>;
483
+ /** A governance document ({@link MEMORY_GOVERNANCE_DOC_NAMES}) as last committed, parsed but not judged: `undefined`
484
+ * when it was never written; a document that cannot be read or parsed throws `ControlPlaneCorruptError` — never
485
+ * read as missing. The engine judges the shape (each document's one reader lives in core). */
486
+ readDoc(name: MemoryGovernanceDocName): Promise<unknown>;
487
+ /** One serialized read-modify-write of a governance document: `coerce` judges what was committed (`undefined` when
488
+ * never written; it throws `ControlPlaneCorruptError` on a shape it refuses), `fn` runs once, synchronously, over
489
+ * that value, and `next` — when it answers one — is written before the call settles. A throw in `coerce` or `fn`
490
+ * writes nothing and propagates unchanged. Nobody else's update of the same document lands between the read `fn`
491
+ * saw and its write; a store that retries a serialization failure runs `coerce` and `fn` again over a fresh read. */
492
+ updateDoc<S, T>(name: MemoryGovernanceDocName, coerce: (raw: unknown) => S, fn: (current: S) => {
493
+ next?: S;
494
+ result: T;
495
+ }): Promise<T>;
496
+ /** Write a control object ({@link MEMORY_CONTROL_OBJECT_KINDS}) once: `"created"` ⇔ this call wrote `bytes` under
497
+ * `(kind, name)`, `"existed"` ⇔ that name already stood — whatever it holds, it is never overwritten. A reader never
498
+ * meets half an object. `meta.scope` names the memory scope the object concerns when the writer knows one (a store
499
+ * with a scope column keeps it; the File store has none and ignores it). A kind outside the closed set, or a name that
500
+ * is not one opaque segment (empty, `.` / `..`, a `/`, a `\` or a NUL), is refused `memory.control_object_unknown`.
501
+ *
502
+ * @contract memory.governance.object_written_once — once a name of a kind stands, no store call replaces its bytes:
503
+ * a second put answers `"existed"`, a move refuses a target holding other bytes, and only `deleteObject` takes it
504
+ * away; core keeps the records whose silent replacement would launder what they recorded (a pollution marker, a
505
+ * capture opt-out, a hold's captured bytes) on this promise. */
506
+ putObject(kind: MemoryControlObjectKind, name: string, bytes: Uint8Array, meta?: {
507
+ readonly scope?: string;
508
+ }): Promise<"created" | "existed">;
509
+ /** A control object's bytes, a copy: `undefined` ⇔ no object of that name; one that stands but cannot be read throws
510
+ * `ControlPlaneCorruptError` — an object that is there is never read as missing. */
511
+ getObject(kind: MemoryControlObjectKind, name: string): Promise<Uint8Array | undefined>;
512
+ /** The names of every object of `kind`, sorted. An enumeration that fails throws `ControlPlaneCorruptError` — it is
513
+ * never answered as an empty kind. */
514
+ listObjects(kind: MemoryControlObjectKind): Promise<string[]>;
515
+ /** Move one object to a new `(kind, name)` in one step, never overwriting: `"moved"` ⇔ the object now stands only at
516
+ * `to`; `"already-moved"` ⇔ the source was gone and `to` stands (a resumed move). A source and target that both stand
517
+ * with different bytes, or a source and target both gone, throw. */
518
+ moveObject(from: {
519
+ readonly kind: MemoryControlObjectKind;
520
+ readonly name: string;
521
+ }, to: {
522
+ readonly kind: MemoryControlObjectKind;
523
+ readonly name: string;
524
+ }): Promise<"moved" | "already-moved">;
525
+ /** Delete one object (its bytes gone, not moved); answers whether one was there. */
526
+ deleteObject(kind: MemoryControlObjectKind, name: string): Promise<boolean>;
527
+ }
528
+ /** The governance documents a {@link MemoryGovernanceStore} keeps (closed set): the harvest lineage ledger, the challenge
529
+ * ledger, the delegation-settlement ledger, the session-account ledger, the memory announcement queue (the notices a
530
+ * session's first injection reads, one bounded queue per scope — {@link import("./layout.js").enqueueMemoryAnnouncement}),
531
+ * the instruction-hold ledger and the origin-clearance account. One law for all seven: the store refuses what it cannot
532
+ * read; what a document means, the queue's leniency over a malformed record included, is core's. A row that points at
533
+ * bytes (a hold's capture, a clearance's custody) names a control object of the same store. */
534
+ export declare const MEMORY_GOVERNANCE_DOC_NAMES: readonly ["lineage", "challenges", "settlements", "session-accounts", "announcements", "holds", "origin-clearances"];
535
+ /** One of {@link MEMORY_GOVERNANCE_DOC_NAMES}. */
536
+ export type MemoryGovernanceDocName = (typeof MEMORY_GOVERNANCE_DOC_NAMES)[number];
537
+ /** The kinds of control object a {@link MemoryGovernanceStore} keeps (closed set) — each a record or custody bytes
538
+ * written once under a name core mints: a session's pollution marker, a bundle import's completion receipt, bytes moved
539
+ * aside into quarantine, an instruction hold's captured file, an origin clearance's custody text, and a session's
540
+ * capture opt-out record. One law for all six ({@link MemoryGovernanceStore.putObject}); what an object means is core's. */
541
+ export declare const MEMORY_CONTROL_OBJECT_KINDS: readonly ["pollution", "import-receipt", "quarantine", "hold", "clearance-custody", "capture"];
542
+ /** One of {@link MEMORY_CONTROL_OBJECT_KINDS}. */
543
+ export type MemoryControlObjectKind = (typeof MEMORY_CONTROL_OBJECT_KINDS)[number];
544
+ /** The part of a {@link MemoryGovernanceStore} the governance documents are kept through. */
545
+ export type MemoryGovernanceDocs = Pick<MemoryGovernanceStore, "readDoc" | "updateDoc">;
413
546
  /** One file the engine materialized into the session memory directory. */
414
547
  export interface MaterializedFile {
415
548
  /** Absolute canonical path of the projected file. */
@@ -482,8 +615,6 @@ export interface MemorySessionHandle {
482
615
  * scopes have a key; the tool faces derive their own LIVE answer per call, so a stale snapshot
483
616
  * can mis-report a number, never mis-serve an entry. */
484
617
  shadowedByScope?: ReadonlyMap<string, number>;
485
- /** Lines of the derived MEMORY.md at materialize time (the index-cleared fuse baseline). */
486
- indexBaselineLines: number;
487
618
  /** 评审 M6 — the derived index TEXT as of materialize. `inject` reads THIS when no on-disk
488
619
  * MEMORY.md exists (a read-only layering never writes one), so first-session read-only injection
489
620
  * works without a disk round-trip. */
@@ -577,9 +708,9 @@ export interface ScanFinding {
577
708
  }
578
709
  /**
579
710
  * design/138 S2-B — one queued memory-change announcement, drained into the NEXT session's first
580
- * injection (时机① only; there is no in-run delivery lane — O-F2/C-F4 裁撤). Queued via the
581
- * journaled control-plane queue ({@link import("./layout.js").enqueueMemoryAnnouncement}) so
582
- * concurrent writers never overwrite each other (O-F6/C-F5).
711
+ * injection (时机① only; there is no in-run delivery lane — O-F2/C-F4 裁撤). Queued in the governance
712
+ * store's `announcements` document ({@link import("./layout.js").enqueueMemoryAnnouncement}, one
713
+ * serialized update) so concurrent writers never overwrite each other (O-F6/C-F5).
583
714
  */
584
715
  export interface MemoryAnnouncement {
585
716
  /** `gate` = engine gate/harvest events (rejections, quarantine, incidents, restores, conflicts,
@@ -606,7 +737,7 @@ export interface MemoryAnnouncement {
606
737
  *
607
738
  * STRUCTURE-ONLY, deliberately: {@link import("./engine.js").renderAnnouncements} does not read
608
739
  * it, so the model-visible block is byte-for-byte what it always was. The consumer is a host
609
- * reading the queue (`drainMemoryAnnouncements` / `peekMemoryAnnouncements`), which can now join
740
+ * reading the queue (`drainMemoryAnnouncements` / `peekMemoryAnnouncements` over the governance store that keeps it), which can now join
610
741
  * a queued line to the `memory.harvest_quarantined` / `memory.hold_*` notices of the same
611
742
  * harvest instead of guessing from counts.
612
743
  *
@@ -673,7 +804,7 @@ export interface HarvestReport {
673
804
  /** Set when a fuse tripped (§2.4 删除防线 / B3 fail-closed): the harvest is refused wholesale, NO
674
805
  * patches (especially no deletes) are produced, and the report is surfaced as an alert. */
675
806
  incident?: {
676
- kind: "mass_deletion" | "index_cleared" | "dir_missing" | "sidecar_corrupt";
807
+ kind: "mass_deletion" | "dir_missing" | "sidecar_corrupt";
677
808
  detail: string;
678
809
  };
679
810
  /** Patch counts actually APPLIED by the backend. */
@@ -701,17 +832,22 @@ export interface HarvestReport {
701
832
  contained: boolean;
702
833
  detail: string;
703
834
  }>;
704
- /** Materialized files absent at harvest. NOT deletes (§2.4: 文件缺失≠删除). Files whose entry id
705
- * re-appears at another path (a RENAME) are NOT counted here (验收 M1 — a rename is an id-keyed
706
- * update, never a missing file, and never feeds the deletion fuse). */
835
+ /** Materialized files gone at harvest — absent, or blank (a blank file holds no entry). On the write
836
+ * face each is this session's removal of that entry, which the harvest commits as a delete (the
837
+ * deletion right is the write right) unless the deletion fuse refuses the whole harvest or a
838
+ * containment arm withholds it; on a read-only layer it is only listed — the session holds no
839
+ * write right there, so it is no delete and the entry stays committed. Files whose entry id
840
+ * re-appears at another path (a RENAME) are NOT counted here
841
+ * (验收 M1 — a rename is an id-keyed update, never a removal, and never feeds the deletion fuse). */
707
842
  missing: string[];
708
- /** B1 committed-shadow recovery: missing (non-tombstoned) files RESTORED onto disk from the
709
- * committed copy (backend/shadow). Disclosed here (the restore is an engine action, never silent).
710
- * Restored paths also appear in {@link missing} (the honest record of what vanished) — EXCEPT
711
- * the design/336 §4 hold arm: an UPDATE-form instruction hold captures the session's edit and
712
- * restores the committed bytes onto the plane seat it vacated (zero-copy: the file is the
713
- * storage), so those paths appear here beside {@link containment}.heldInstruction, never in
714
- * `missing` (the file never vanished — its edit is in custody). */
843
+ /** Files RESTORED onto disk from the committed copy (backend/shadow), disclosed here (the restore is
844
+ * an engine action, never silent): a read-only layer's edited files, and the write-face
845
+ * removals a containment arm withheld (a session that commits nothing; an instruction-form entry
846
+ * under the hard gate). Restored paths also appear in {@link missing} (the honest record of what
847
+ * vanished) — EXCEPT the design/336 §4 hold arm: an UPDATE-form instruction hold captures the
848
+ * session's edit and restores the committed bytes onto the plane seat it vacated (zero-copy: the
849
+ * file is the storage), so those paths appear here beside {@link containment}.heldInstruction,
850
+ * never in `missing` (the file never vanished — its edit is in custody). */
715
851
  restored: string[];
716
852
  /** The other outcome of the same restore: a path whose committed baseline was NOT written back, because
717
853
  * another writer held the file when the restore reached it. The newer bytes stand, the baseline is
@@ -1,4 +1,6 @@
1
1
  export const MEMORY_ORIGIN_CAUSES = Object.freeze(["observed", "derived", "static", "unattributed"]);
2
+ export const MEMORY_GOVERNANCE_DOC_NAMES = Object.freeze(["lineage", "challenges", "settlements", "session-accounts", "announcements", "holds", "origin-clearances"]);
3
+ export const MEMORY_CONTROL_OBJECT_KINDS = Object.freeze(["pollution", "import-receipt", "quarantine", "hold", "clearance-custody", "capture"]);
2
4
  export function writableRootOf(handle) {
3
5
  if (handle.writableRoot === null)
4
6
  throw new Error("memory session handle has no write face (writeScope is null) — writableRoot is not available");
@@ -4,7 +4,7 @@ import { termSet } from "./memory-vector.js";
4
4
  import { attrEscape } from "./task-notification.js";
5
5
  import { sanitizeUntrustedText, ENGINE_AUTHORITY_ENVELOPE_TAGS } from "./untrusted-text.js";
6
6
  import { thrownText } from "./thrown-value.js";
7
- import { CREDENTIAL_VOCABULARY, refuseWriteView } from "./credential-vocabulary.js";
7
+ import { CREDENTIAL_VOCABULARY, scanSecrets } from "@sema-agent/primitives";
8
8
  export function supportsConsolidation(store) {
9
9
  return (typeof store.searchScored === "function" &&
10
10
  typeof store.update === "function" &&
@@ -39,14 +39,23 @@ export class MemoryProjectionError extends Error {
39
39
  function hasPromotableMarker(note) {
40
40
  return note.outcomeStats !== undefined;
41
41
  }
42
- const REFUSE_WRITE_FORMS = refuseWriteView(CREDENTIAL_VOCABULARY);
42
+ const REFUSE_WRITE_POLICY = Object.freeze({
43
+ grade: "strict",
44
+ readings: Object.freeze([Object.freeze({ kind: "raw" })]),
45
+ urlUserinfo: "keep-username",
46
+ onUnresolvedReading: "secret",
47
+ });
48
+ const refuseLabel = (id) => id.replaceAll("-", "_");
43
49
  export function detectSecret(text) {
44
50
  if (!text)
45
51
  return null;
46
- for (const form of REFUSE_WRITE_FORMS) {
47
- if (form.re.test(text))
48
- return form.label;
49
- }
52
+ const scan = scanSecrets(text, REFUSE_WRITE_POLICY);
53
+ if (scan.outcome === "whole")
54
+ return refuseLabel(scan.reason);
55
+ const found = new Set(scan.spans.map((s) => s.family));
56
+ for (const row of CREDENTIAL_VOCABULARY.values)
57
+ if (row.strict !== undefined && found.has(row.id))
58
+ return refuseLabel(row.id);
50
59
  return null;
51
60
  }
52
61
  export function enforceSecretWriteGate(body) {
@@ -76,14 +76,14 @@ export function modeQuestionReaches(mode, roster, toolName, seat) {
76
76
  }
77
77
  const planAsk = (message, call, generic) => {
78
78
  const asked = { action: "ask", message, decisionReason: "mode" };
79
- return generic ? attest(asked, call, { genericQuestion: message }) : asked;
79
+ return generic !== undefined ? attest(asked, call, { sentence: { text: message, generic: true, ...generic } }) : asked;
80
80
  };
81
81
  export function createModeGatePolicy(modeRef, seats) {
82
82
  const askGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, defaultWrite: "ask" });
83
83
  const acceptSeat = seats.acceptDirs;
84
84
  const acceptDirs = typeof acceptSeat === "function" ? acceptSeat : acceptSeat !== undefined && acceptSeat.length > 0 ? [...acceptSeat] : [seats.rootPath];
85
85
  const acceptRootGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, acceptDirs, defaultWrite: "ask" });
86
- const planGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, defaultWrite: "ask", defaultAsk: (path, note, call) => planAsk(`Cannot write to ${path} while in plan mode.${note ?? ""}`, call, note === undefined) });
86
+ const planGate = createFsWriteGatePolicy({ env: seats.env, rootPath: seats.rootPath, defaultWrite: "ask", defaultAsk: (path, note, call) => planAsk(`Cannot write to ${path} while in plan mode.${note ?? ""}`, call, note === undefined ? { echoed: [Object.freeze({ kind: "path", value: path })] } : undefined) });
87
87
  return {
88
88
  async check(req, signal) {
89
89
  const gate = modePolicyOf(modeRef.current).writeGate;
@@ -93,7 +93,7 @@ export function createModeGatePolicy(modeRef, seats) {
93
93
  if (!planRefusesWrite(req, seats.roster?.current, seats.readOnlyDeclared))
94
94
  return { action: "allow" };
95
95
  if (!isProtectedWrite(req))
96
- return planAsk(`Cannot call ${req.toolName} while in plan mode.`, req, true);
96
+ return planAsk(`Cannot call ${req.toolName} while in plan mode.`, req, {});
97
97
  return planGate.check(req, signal);
98
98
  }
99
99
  return (gate === "ask" ? askGate : acceptRootGate).check(req, signal);