@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
@@ -0,0 +1,161 @@
1
+ import { createHash } from "node:crypto";
2
+ import { lstatSync, statSync } from "node:fs";
3
+ import { join, resolve } from "node:path";
4
+ import { isDeepStrictEqual } from "node:util";
5
+ import { MEMORY_CONTROL_OBJECT_KINDS, MEMORY_GOVERNANCE_DOC_NAMES } from "./types.js";
6
+ import { ControlPlaneCorruptError, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
7
+ import { getFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
8
+ import { fileGovernanceStoreDir } from "./consolidation.js";
9
+ import { moveOriginClearanceCustodyOut } from "./origin-clearance.js";
10
+ import { thrownText } from "../thrown-value.js";
11
+ export const CONTROL_PLANE_ADOPTION_FILE = "control-plane-adoption.json";
12
+ function coerceReceipt(raw) {
13
+ if (raw === undefined)
14
+ return { version: 1, adopted: [] };
15
+ if (typeof raw !== "object" || raw === null || Reflect.get(raw, "version") !== 1 || !Array.isArray(Reflect.get(raw, "adopted"))) {
16
+ throw new ControlPlaneCorruptError("memory control-plane adoption receipt has the wrong shape (fail-closed)");
17
+ }
18
+ return raw;
19
+ }
20
+ function sha256Hex(bytes) {
21
+ return createHash("sha256").update(bytes).digest("hex");
22
+ }
23
+ function standsAt(path) {
24
+ try {
25
+ lstatSync(path);
26
+ return true;
27
+ }
28
+ catch (err) {
29
+ if (Reflect.get(err, "code") === "ENOENT")
30
+ return false;
31
+ throw new ControlPlaneCorruptError(`memory control plane: ${path} could not be probed (${String(Reflect.get(err, "code") ?? "io error")}) (fail-closed)`, { cause: err });
32
+ }
33
+ }
34
+ export function replicaControlPlaneStrays(controlDir) {
35
+ const docs = MEMORY_GOVERNANCE_DOC_NAMES.filter((name) => {
36
+ const file = join(controlDir, fileGovernanceDocOf(name).file);
37
+ return standsAt(file) || standsAt(`${file}.journal`);
38
+ });
39
+ const objects = {};
40
+ for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
41
+ const n = standingFileControlObjectNames(controlDir, kind).length;
42
+ if (n > 0)
43
+ objects[kind] = n;
44
+ }
45
+ return { docs, objects };
46
+ }
47
+ function carriesThisDirectory(carrier, controlDir) {
48
+ const dir = fileGovernanceStoreDir(carrier);
49
+ if (dir === undefined)
50
+ return false;
51
+ if (resolve(dir) === resolve(controlDir))
52
+ return true;
53
+ try {
54
+ const a = statSync(dir);
55
+ const b = statSync(controlDir);
56
+ return a.dev === b.dev && a.ino === b.ino;
57
+ }
58
+ catch {
59
+ return false;
60
+ }
61
+ }
62
+ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
63
+ const now = opts?.now ?? Date.now;
64
+ const adopted = [];
65
+ const refused = [];
66
+ if (carriesThisDirectory(carrier, controlDir))
67
+ return { adopted, refused };
68
+ if (!standsAt(controlDir))
69
+ throw new ControlPlaneCorruptError(`memory control-plane adoption: ${controlDir} does not exist — a replica control plane to adopt from is a directory that stands (a wrong path hands over nothing and says so) (fail-closed)`);
70
+ const receipt = (record, digest) => {
71
+ lockedStrictUpdate(controlDir, CONTROL_PLANE_ADOPTION_FILE, "memory control-plane adoption receipt", coerceReceipt, (rec) => {
72
+ if (rec.adopted.some((r) => r.record === record && r.digest === digest))
73
+ return { result: undefined };
74
+ rec.adopted.push({ record, digest, at: now() });
75
+ return { next: rec, result: undefined };
76
+ });
77
+ };
78
+ const clearances = join(controlDir, fileGovernanceDocOf("origin-clearances").file);
79
+ if (standsAt(clearances) || standsAt(`${clearances}.journal`)) {
80
+ try {
81
+ moveOriginClearanceCustodyOut(controlDir);
82
+ }
83
+ catch (err) {
84
+ refused.push({ record: "doc:origin-clearances", reason: `its inline custody could not be moved out first: ${thrownText(err)}` });
85
+ }
86
+ }
87
+ for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
88
+ for (const name of standingFileControlObjectNames(controlDir, kind)) {
89
+ const record = `${kind}/${name}`;
90
+ try {
91
+ const bytes = getFileControlObject(controlDir, kind, name);
92
+ if (bytes === undefined)
93
+ continue;
94
+ const digest = sha256Hex(bytes);
95
+ const outcome = (await carrier.putObject(kind, name, bytes)) === "created" ? "written" : "converged";
96
+ const held = await carrier.getObject(kind, name);
97
+ if (held === undefined || sha256Hex(held) !== digest) {
98
+ refused.push({ record, reason: outcome === "converged" ? "the carrier already holds an object of this name with different bytes" : "the carrier's copy does not read back the same" });
99
+ continue;
100
+ }
101
+ const again = getFileControlObject(controlDir, kind, name);
102
+ if (again === undefined || sha256Hex(again) !== digest) {
103
+ refused.push({ record, reason: "the replica's bytes changed while they were adopted" });
104
+ continue;
105
+ }
106
+ receipt(record, digest);
107
+ adopted.push({ record, outcome, digest });
108
+ }
109
+ catch (err) {
110
+ refused.push({ record, reason: thrownText(err) });
111
+ }
112
+ }
113
+ }
114
+ const before = refused.map((r) => r.record);
115
+ if (before.length > 0) {
116
+ for (const name of replicaControlPlaneStrays(controlDir).docs) {
117
+ if (!before.includes(`doc:${name}`))
118
+ refused.push({ record: `doc:${name}`, reason: `left in the replica until every record before it is adopted (refused: ${before.join(", ")})` });
119
+ }
120
+ return { adopted, refused };
121
+ }
122
+ for (const name of MEMORY_GOVERNANCE_DOC_NAMES) {
123
+ const record = `doc:${name}`;
124
+ const { file, what } = fileGovernanceDocOf(name);
125
+ const path = join(controlDir, file);
126
+ try {
127
+ if (!standsAt(path) && !standsAt(`${path}.journal`))
128
+ continue;
129
+ const value = readStrictSidecar(controlDir, file, what);
130
+ if (value === undefined)
131
+ continue;
132
+ const digest = sha256Hex(JSON.stringify(value));
133
+ const outcome = await carrier.updateDoc(name, (raw) => raw, (cur) => {
134
+ if (cur === undefined)
135
+ return { next: value, result: "written" };
136
+ return { result: isDeepStrictEqual(cur, value) ? "converged" : "different" };
137
+ });
138
+ if (outcome === "different") {
139
+ refused.push({ record, reason: "the carrier already holds a different document of this name" });
140
+ continue;
141
+ }
142
+ if (!isDeepStrictEqual(await carrier.readDoc(name), value)) {
143
+ refused.push({ record, reason: "the carrier's copy does not read back the same" });
144
+ continue;
145
+ }
146
+ if (!isDeepStrictEqual(readStrictSidecar(controlDir, file, what), value)) {
147
+ refused.push({ record, reason: "the replica's document changed while it was adopted" });
148
+ continue;
149
+ }
150
+ receipt(record, digest);
151
+ adopted.push({ record, outcome, digest });
152
+ }
153
+ catch (err) {
154
+ refused.push({ record, reason: thrownText(err) });
155
+ }
156
+ }
157
+ return { adopted, refused };
158
+ }
159
+ export function readControlPlaneAdoptionReceipt(controlDir) {
160
+ return coerceReceipt(readStrictSidecar(controlDir, CONTROL_PLANE_ADOPTION_FILE, "memory control-plane adoption receipt")).adopted;
161
+ }
@@ -1,4 +1,5 @@
1
- import type { MemoryGovernanceDocs, MemoryOriginCause } from "./types.js";
1
+ import type { MemoryControlObjectKind, MemoryGovernanceDocs, MemoryGovernanceObjects, MemoryOriginCause } from "./types.js";
2
+ import { type SessionPollutionObjects } from "./layout.js";
2
3
  /** A row's FIRST-WRITE status. Rows are immutable after their first write — every later transition
3
4
  * is an append-only event ({@link SettlementEvent}); the effective status is the fold. */
4
5
  export type SettlementRowStatus = "pending" | "unattestable";
@@ -135,7 +136,7 @@ export declare function expireOverdueSettlements(docs: MemoryGovernanceDocs, inp
135
136
  * `carry` scopes the sweep domain exactly like the engine's own sweeps (marked rows carry their
136
137
  * account under "carry"; the "off" width challenges everything).
137
138
  */
138
- export declare function replayExternalSettlementEffects(docs: MemoryGovernanceDocs, controlDir: string, input: {
139
+ export declare function replayExternalSettlementEffects(docs: MemoryGovernanceDocs & SessionPollutionObjects, input: {
139
140
  carry: boolean;
140
141
  now: () => number;
141
142
  }): Promise<Array<{
@@ -182,9 +183,9 @@ export interface SessionAccountRow {
182
183
  /** The one-time v1 key-form conversions of the three engine sidecars, in one call (each in its own
183
184
  * lock, each idempotent). The layout adoption runs this before any later scope registration can
184
185
  * change what a v1 key's first segment names. A step of the File layout's own upgrade: it converts
185
- * the hold ledger (a control-plane file, beside its custody) and the session-account document the File
186
- * store keeps under `controlDir`, in place (a store that keeps documents elsewhere never held the v1
187
- * form); the reads below convert the same way on first touch. */
186
+ * the hold ledger and the session-account document the File store keeps under `controlDir`, in place
187
+ * (a store that keeps documents elsewhere never held the v1 form); the reads below convert the same
188
+ * way on first touch. */
188
189
  export declare function convertV1SidecarKeys(controlDir: string): void;
189
190
  /** The dangling-trigger read: open rows (and unadjudicated closes) belonging to OTHER sessions.
190
191
  * These are what arm the unattributed residue classification at a session's materialize. */
@@ -268,8 +269,14 @@ export declare function resolveSessionAccountRecord(docs: MemoryGovernanceDocs,
268
269
  requestId: string;
269
270
  now: () => number;
270
271
  }): Promise<void>;
271
- export declare const HOLDS_FILE = "holds.json";
272
- export declare const HOLD_DIR = "hold";
272
+ /** The hold ledger's file: the File store's coordinate of the governance document `holds` (read here only by the
273
+ * File layout's own key-form upgrade, {@link convertV1SidecarKeys}). */
274
+ export declare const HOLDS_FILE: string;
275
+ /** The hold custody directory: the File store's directory of the control-object kind `hold`. */
276
+ export declare const HOLD_DIR: string;
277
+ /** What a hold is kept through: the governance store's ledger document `holds`, its `hold` custody objects and the
278
+ * `quarantine` objects a disposal moves them to. */
279
+ type HoldStore = MemoryGovernanceDocs & MemoryGovernanceObjects;
273
280
  export type HoldStatus = "capturing" | "held" | "released" | "disposed";
274
281
  export type HoldTerminal = "dirty" | "expired" | "conflict" | "discarded" | "capture_lost";
275
282
  export interface HoldRow {
@@ -311,24 +318,26 @@ export interface HoldRow {
311
318
  * rows resolved before the member existed (a generation-less clear matches those). */
312
319
  resolvedAt?: number;
313
320
  }
314
- export declare function readHolds(controlDir: string): HoldRow[];
321
+ export declare function readHolds(docs: MemoryGovernanceDocs): Promise<HoldRow[]>;
315
322
  /** Where a plane file is staged while it is displaced: a SIBLING in the file's OWN directory.
316
323
  * `rename` is atomic only WITHIN one filesystem, and the control plane is routinely a different mount
317
324
  * from the memory dir — staging there surrenders the atomicity the rename-first law exists for, and a
318
325
  * cross-device refusal is the ordinary shape of a two-volume deployment, not an exotic failure. A
319
326
  * sibling is on the file's filesystem by construction, so one path serves both layouts. The staged
320
- * name is never `.md`-suffixed; custody stays in the control plane ({@link retireStagingToCustody}). */
327
+ * name is never `.md`-suffixed; custody stays in the control plane ({@link retireStagingToObject}). */
321
328
  export declare function stagingPathBeside(absPath: string, stagingName: string): string;
322
- /** Move whatever still sits at a staged generation into control-plane custody and report WHERE the
323
- * bytes ended up. Withheld bytes belong in the control plane, never on the model-visible plane — but
324
- * a copy that cannot be made there must leave the only copy where it is and SAY so, so the coordinate
325
- * is the host's recovery address either way and `settled` answers one question: in custody, with
326
- * nothing left beside the seat? Takes an ALREADY-CLAIMED path (read, decision and removal address
327
- * one inode) and removes it only after {@link writeCustodyVerified} has proven the copy. */
328
- export declare function retireStagingToCustody(claimedPath: string, custodyDir: string, stagingName: string): {
329
+ /** Move whatever still sits at a staged generation into the governance store's control objects and report WHERE the
330
+ * bytes ended up. Withheld bytes belong in the control plane, never on the model-visible plane — but a copy that
331
+ * cannot be made there leaves the only copy where it is and SAYS so, so the coordinate is the host's recovery address
332
+ * either way and `settled` answers one question: in the store, with nothing left beside the seat? Takes an
333
+ * ALREADY-CLAIMED path (read, decision and removal address one inode): the staged bytes become the `kind` object
334
+ * `name`, read back through the store before the staged copy is removed. The removal is an act on the memory plane
335
+ * after this function's awaits, so `refusedAt` (the caller's anchor read) runs immediately before it — a refusal
336
+ * leaves the staged copy where it is and reports it, exactly as an unremovable copy does. */
337
+ export declare function retireStagingToObject(objects: Pick<MemoryGovernanceObjects, "putObject" | "getObject">, claimedPath: string, kind: MemoryControlObjectKind, name: string, refusedAt: () => string | undefined): Promise<{
329
338
  settled: boolean;
330
339
  at: string;
331
- };
340
+ }>;
332
341
  /** ATOMIC no-replace restore of a staged file onto a plane path (adversarial round 2: an
333
342
  * existsSync-then-rename pair is a TOCTOU — POSIX rename REPLACES a destination created between
334
343
  * the check and the call, clobbering a third writer's newer bytes). `link` refuses EEXIST
@@ -339,8 +348,9 @@ export declare function noReplaceRestore(stagingPath: string, destPath: string):
339
348
  * §4.2 — open one hold over an instruction-form file: the two-stage journal.
340
349
  * ① append row `status:"capturing"` (deterministic captureName + contentDigest minted from the
341
350
  * one read buffer) — the account exists before any byte moves;
342
- * ② write the custody file FROM THE SAME BUFFER, read it back, verify the digest;
343
- * ③ remove the plane file RENAME-FIRST (atomic move to a staged sibling in the file's OWN
351
+ * ② write the custody object FROM THE SAME BUFFER, read it back through the store, verify the digest;
352
+ * ③ the anchor read at the act (`actRefused` — ① and ② awaited the store), then remove the plane
353
+ * file RENAME-FIRST (atomic move to a staged sibling in the file's OWN
344
354
  * directory — {@link stagingPathBeside}), then hash what actually moved: equal ⇒ the staged
345
355
  * duplicate is dropped (custody already holds verified bytes); unequal ⇒ a third writer replaced
346
356
  * the file between read and rename — NO-CLOBBER rollback (the newer bytes go back ONLY if the
@@ -353,7 +363,7 @@ export declare function noReplaceRestore(stagingPath: string, destPath: string):
353
363
  * plane, revoked permission) is one such refusal: the file would stay on the plane, the one outcome
354
364
  * a hold may not produce.
355
365
  */
356
- export declare function openInstructionHold(controlDir: string, input: {
366
+ export declare function openInstructionHold(store: HoldStore, input: {
357
367
  sessionId: string;
358
368
  /** The seat in the ledger form (relative to the write scope's home). */
359
369
  rel: string;
@@ -366,7 +376,10 @@ export declare function openInstructionHold(controlDir: string, input: {
366
376
  scope: string;
367
377
  settleIds: readonly string[];
368
378
  now: () => number;
369
- }): {
379
+ /** The caller's act gate on the memory plane (the engine's anchor read), asked immediately before each act this
380
+ * function performs there: the refusal's text, or `undefined` when the act may proceed. */
381
+ actRefused: (path: string, act: string) => string | undefined;
382
+ }): Promise<{
370
383
  ok: true;
371
384
  holdId: string;
372
385
  thirdWriterStrandedAt?: string;
@@ -374,7 +387,7 @@ export declare function openInstructionHold(controlDir: string, input: {
374
387
  ok: false;
375
388
  holdId?: string;
376
389
  reason: string;
377
- };
390
+ }>;
378
391
  /**
379
392
  * §4.2 reconciliation — converge half-way holds (a crash between the journal stages):
380
393
  * - `capturing` + custody file present & digest-equal ⇒ flip held (the crash was after ②);
@@ -385,38 +398,57 @@ export declare function openInstructionHold(controlDir: string, input: {
385
398
  * - `capturing` + custody absent + plane file gone ⇒ `capture_lost` (nothing to hold).
386
399
  * - `held` + plane file REAPPEARED at the seat ⇒ left alone (a fresh write is a fresh file —
387
400
  * the next harvest judges it on its own; the hold's custody bytes stay the hold's).
401
+ * - `disposed` + the row names its quarantine seat + the custody object still stands
402
+ * ⇒ the disposal's move finishes (the row is written before the bytes move).
403
+ * The walk awaits the store between its acts on the memory plane, so the caller's anchor read
404
+ * (`actRefused`) is asked immediately before each of them.
388
405
  */
389
- export declare function reconcileHolds(controlDir: string, input: {
406
+ export declare function reconcileHolds(store: HoldStore, input: {
390
407
  homeOf: (scope: string) => string;
391
408
  now: () => number;
392
409
  onStranded: (scope: string, line: string) => void;
393
- }): void;
394
- /** Dispose one held row: custody bytes move to the quarantine directory (host-auditable), the row
395
- * records its terminal + quarantineName (from-row-to-bytes addressing survives every terminal). */
396
- export declare function disposeHold(controlDir: string, input: {
410
+ actRefused: (path: string, act: string) => string | undefined;
411
+ }): Promise<void>;
412
+ /** The quarantine seat of a hold's custody bytes: a function of the ROW, never of a clock. The same
413
+ * row names the same seat on every call, in every process, after any crash — the old
414
+ * `<ms>-hold-<captureName>` shape with the row's own content digest where the wall clock was. */
415
+ export declare function holdQuarantineNameOf(row: Pick<HoldRow, "captureName" | "contentDigest">): string;
416
+ /** Dispose one held row: the row records its terminal and the quarantine seat NAMED BY THE ROW
417
+ * ({@link holdQuarantineNameOf}) first, then the custody bytes move there (host-auditable;
418
+ * from-row-to-bytes addressing survives every terminal). Row first, bytes second: a crash between
419
+ * the two leaves a row whose bytes are at the custody seat or the quarantine seat — both of which
420
+ * {@link readHoldCustody} tries — and {@link reconcileHolds} finishes the move; the reverse order
421
+ * would leave bytes in quarantine under a name no row recorded. Whether the row names a seat is
422
+ * decided inside the ledger's update, on the fresh row, from what stands at the custody seat and the
423
+ * quarantine seat as read just before it (the update's callback runs synchronously and reads no
424
+ * object; a mover between that read and the update is the compound-decision window, KL-3308-c): a
425
+ * row with no custody bytes anywhere records the terminal with no name (nothing to move). The
426
+ * verdict always lands: a quarantine seat held by something that is not the hold's bytes records the
427
+ * terminal with no name, leaves the custody bytes where they are and replaces nothing — and then
428
+ * refuses loudly (the caller hears it; a refused intake is terminal all the same). */
429
+ export declare function disposeHold(store: HoldStore, input: {
397
430
  holdId: string;
398
431
  terminal: HoldTerminal;
399
- now: () => number;
400
- }): {
432
+ }): Promise<{
401
433
  ok: boolean;
402
434
  quarantineName?: string;
403
- };
435
+ }>;
404
436
  /** Flip one row to released (the caller — the harvest release leg — has already committed the
405
- * custody bytes through the full gate set; the custody file is dropped after the flip). */
406
- export declare function markHoldReleased(controlDir: string, input: {
437
+ * custody bytes through the full gate set; the custody object is deleted after the flip). */
438
+ export declare function markHoldReleased(store: HoldStore, input: {
407
439
  holdId: string;
408
440
  now: () => number;
409
- }): void;
441
+ }): Promise<void>;
410
442
  /** The host valve — `resolveHold(holdId, "release"|"discard", requestId)`: records the verdict on
411
443
  * the row; the NEXT harvest reconciliation executes it ("release" re-walks the full gates and
412
444
  * commits WITH cause "static" — a timeout release is not proof of cleanliness; "discard"
413
445
  * disposes to quarantine). requestId required (audit, #123). */
414
- export declare function resolveHoldRecord(controlDir: string, input: {
446
+ export declare function resolveHoldRecord(docs: MemoryGovernanceDocs, input: {
415
447
  holdId: string;
416
448
  action: "release" | "discard";
417
449
  requestId: string;
418
450
  now: () => number;
419
- }): void;
451
+ }): Promise<void>;
420
452
  /**
421
453
  * Consume a standing valve verdict WITHOUT any other transition — the settle leg's exit for a
422
454
  * valve release that FAILED on an already-disposed row (an expired hold whose release hit a
@@ -435,15 +467,16 @@ export declare function resolveHoldRecord(controlDir: string, input: {
435
467
  * on purpose (refusing it would revive the forever-re-firing valve loop for every verdict minted
436
468
  * before the upgrade). Idempotent; unknown/verdict-less/other-generation rows are a no-op.
437
469
  */
438
- export declare function clearHoldResolution(controlDir: string, input: {
470
+ export declare function clearHoldResolution(docs: MemoryGovernanceDocs, input: {
439
471
  holdId: string;
440
472
  ifResolvedAt: number | undefined;
441
- }): void;
473
+ }): Promise<void>;
442
474
  /** Read one hold's custody bytes (release leg + expired-release valve). Returns undefined when
443
- * the custody file is gone or fails its digest — the caller records capture_lost, never commits
475
+ * the custody object is gone or fails its digest — the caller records capture_lost, never commits
444
476
  * unverified bytes. For an expired-released row the bytes may already sit in quarantine
445
477
  * (disposition.quarantineName) — both seats are tried, digest-verified either way. */
446
- export declare function readHoldCustody(controlDir: string, row: HoldRow): string | undefined;
478
+ export declare function readHoldCustody(objects: Pick<MemoryGovernanceObjects, "getObject">, row: HoldRow): Promise<string | undefined>;
447
479
  /** True ⇔ the session's pollution marker or any non-clean settlement row blocks a clean release
448
480
  * (§4.2-1: any non-clean row in the session's account keeps the hold held/disposed). */
449
- export declare function sessionBlocksCleanRelease(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<boolean>;
481
+ export declare function sessionBlocksCleanRelease(docs: MemoryGovernanceDocs & SessionPollutionObjects, sessionId: string): Promise<boolean>;
482
+ export {};