@sema-agent/core 7.64.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 (103) hide show
  1. package/CHANGELOG.md +317 -0
  2. package/dist/agents/peer-held-queue.js +1 -1
  3. package/dist/agents/peer-idle.js +1 -1
  4. package/dist/agents/peer-session-drain.js +3 -3
  5. package/dist/agents/subagent.js +5 -2
  6. package/dist/core/auto-promote.d.ts +3 -2
  7. package/dist/core/background-agent-store.d.ts +7 -0
  8. package/dist/core/checkpoint-store.d.ts +2 -3
  9. package/dist/core/context-settings.d.ts +1 -2
  10. package/dist/core/context-settings.js +1 -1
  11. package/dist/core/engine-attestation.d.ts +2 -2
  12. package/dist/core/engine-notice.d.ts +13 -1
  13. package/dist/core/engine-notice.js +3 -1
  14. package/dist/core/file-history-store.d.ts +2 -2
  15. package/dist/core/file-history-store.js +0 -4
  16. package/dist/core/gate-fold.js +3 -1
  17. package/dist/core/governance-codes.d.ts +6 -4
  18. package/dist/core/governance-codes.js +4 -3
  19. package/dist/core/leg-identity.d.ts +18 -2
  20. package/dist/core/leg-identity.js +5 -7
  21. package/dist/core/mailbox-store.d.ts +1 -1
  22. package/dist/core/memory-engine/consolidation.d.ts +10 -4
  23. package/dist/core/memory-engine/consolidation.js +11 -1
  24. package/dist/core/memory-engine/control-objects.d.ts +36 -3
  25. package/dist/core/memory-engine/control-objects.js +134 -12
  26. package/dist/core/memory-engine/control-plane-adoption.d.ts +5 -2
  27. package/dist/core/memory-engine/control-plane-adoption.js +5 -3
  28. package/dist/core/memory-engine/delegation-settlement.d.ts +59 -42
  29. package/dist/core/memory-engine/delegation-settlement.js +175 -202
  30. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  31. package/dist/core/memory-engine/dual-root.js +5 -1
  32. package/dist/core/memory-engine/engine.d.ts +16 -10
  33. package/dist/core/memory-engine/engine.js +138 -145
  34. package/dist/core/memory-engine/file-backend.d.ts +17 -11
  35. package/dist/core/memory-engine/file-backend.js +53 -103
  36. package/dist/core/memory-engine/layout.d.ts +129 -49
  37. package/dist/core/memory-engine/layout.js +202 -82
  38. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  39. package/dist/core/memory-engine/memory-age.js +17 -0
  40. package/dist/core/memory-engine/memory-backend-contract.js +5 -4
  41. package/dist/core/memory-engine/memory-deployment.d.ts +1 -1
  42. package/dist/core/memory-engine/origin-clearance.js +1 -5
  43. package/dist/core/memory-engine/tools.d.ts +2 -2
  44. package/dist/core/memory-engine/tools.js +7 -7
  45. package/dist/core/memory-engine/types.d.ts +16 -10
  46. package/dist/core/memory-vector.d.ts +6 -14
  47. package/dist/core/memory.d.ts +0 -462
  48. package/dist/core/memory.js +0 -333
  49. package/dist/core/permission-rule-consent.d.ts +49 -18
  50. package/dist/core/permission-rule-consent.js +59 -38
  51. package/dist/core/permission-rule-store.d.ts +24 -14
  52. package/dist/core/retention.d.ts +2 -7
  53. package/dist/core/retention.js +0 -1
  54. package/dist/core/runner/classifier-ladder.d.ts +3 -1
  55. package/dist/core/runner/classifier-ladder.js +2 -2
  56. package/dist/core/runner/contracts.d.ts +9 -9
  57. package/dist/core/runner/delegation-owner.d.ts +0 -8
  58. package/dist/core/runner/delegation-owner.js +1 -3
  59. package/dist/core/runner/prepare-gate-stations.d.ts +8 -5
  60. package/dist/core/runner/prepare-gate-stations.js +13 -5
  61. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  62. package/dist/core/runner/prepare-memory.js +9 -9
  63. package/dist/core/runner/prepare-policy-chain.js +11 -3
  64. package/dist/core/runner/prepare-task.d.ts +5 -1
  65. package/dist/core/runner/prepare-task.js +3 -3
  66. package/dist/core/runner/run-notification-lane.js +1 -1
  67. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  68. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  69. package/dist/core/secret-env.d.ts +2 -2
  70. package/dist/core/secret-env.js +6 -20
  71. package/dist/core/session-store.d.ts +6 -6
  72. package/dist/core/session-store.js +3 -3
  73. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  74. package/dist/core/task-notification.d.ts +35 -8
  75. package/dist/core/task-notification.js +31 -13
  76. package/dist/core/task-registry-agent.js +1 -0
  77. package/dist/core/task-registry-shared.d.ts +4 -0
  78. package/dist/core/tool-errors.d.ts +3 -3
  79. package/dist/core/tool-spec.d.ts +7 -7
  80. package/dist/core/write-protect.d.ts +16 -0
  81. package/dist/core/write-protect.js +10 -0
  82. package/dist/engine/session/repo-utils.d.ts +14 -4
  83. package/dist/engine/session/repo-utils.js +5 -4
  84. package/dist/index.d.ts +6 -6
  85. package/dist/index.js +6 -6
  86. package/dist/prompts/default.d.ts +1 -2
  87. package/dist/scenarios/full-body.d.ts +1 -1
  88. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  89. package/dist/stores/file/index.d.ts +1 -15
  90. package/dist/stores/file/index.js +1 -15
  91. package/dist/stores/file/permission-rule-store.d.ts +12 -1
  92. package/dist/stores/file/permission-rule-store.js +31 -4
  93. package/dist/stores/file/session-store.js +1 -1
  94. package/package.json +2 -2
  95. package/test/export-surface.snapshot.json +9 -73
  96. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  97. package/wire-changes/core@7.65.0.json +1650 -0
  98. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  99. package/wire-changes/primitives@7.65.0.json +337 -0
  100. package/dist/core/memory-recall.d.ts +0 -208
  101. package/dist/core/memory-recall.js +0 -136
  102. package/dist/stores/file/memory-store.d.ts +0 -124
  103. package/dist/stores/file/memory-store.js +0 -353
@@ -2,7 +2,8 @@ import { closeSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, read
2
2
  import { randomUUID } from "node:crypto";
3
3
  import { join } from "node:path";
4
4
  import { MEMORY_CONTROL_OBJECT_KINDS } from "./types.js";
5
- import { ControlPlaneCorruptError, IMPORT_RECEIPTS_DIR, QUARANTINE_DIR, SESSION_CAPTURE_OPTOUT_DIR, SESSION_POLLUTION_DIR, ensureDirExists } from "./layout.js";
5
+ import { ControlPlaneCorruptError, IMPORT_RECEIPTS_DIR, LINK_PROBE_PREFIX, QUARANTINE_DIR, SESSION_CAPTURE_OPTOUT_DIR, SESSION_POLLUTION_DIR, controlPlaneLinksRefusal, ensureDirExists, quarantineCaptureBase, quarantineCaptureName } from "./layout.js";
6
+ import { thrownText } from "../thrown-value.js";
6
7
  const FILE_CONTROL_OBJECT_DIRS = Object.freeze({
7
8
  pollution: SESSION_POLLUTION_DIR,
8
9
  "import-receipt": IMPORT_RECEIPTS_DIR,
@@ -22,8 +23,9 @@ export function fileControlObjectDirOf(kind) {
22
23
  throw unknownObject(`${JSON.stringify(String(kind))} is not a control-object kind`);
23
24
  return FILE_CONTROL_OBJECT_DIRS[kind];
24
25
  }
26
+ const CONTROL_OBJECT_NAME_MAX_BYTES = 255;
25
27
  export function isControlObjectName(name) {
26
- return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name);
28
+ return typeof name === "string" && name !== "" && name !== "." && name !== ".." && !/[/\\\0]/.test(name) && Buffer.byteLength(name, "utf8") <= CONTROL_OBJECT_NAME_MAX_BYTES;
27
29
  }
28
30
  function objectPath(controlDir, kind, name) {
29
31
  const dir = fileControlObjectDirOf(kind);
@@ -34,21 +36,87 @@ function objectPath(controlDir, kind, name) {
34
36
  function errnoOf(err) {
35
37
  return typeof err === "object" && err !== null ? Reflect.get(err, "code") : undefined;
36
38
  }
37
- function stands(path) {
39
+ export function fileControlObjectFaultCode(err) {
40
+ if (err instanceof ControlPlaneCorruptError)
41
+ return errnoOf(err.cause);
42
+ return errnoOf(err);
43
+ }
44
+ function unprobeable(path, err) {
45
+ return new ControlPlaneCorruptError(`memory control object at ${path} could not be probed (${errnoOf(err) ?? "io error"}) — whether it stands is unknown (fail-closed)`, { cause: err });
46
+ }
47
+ function entryAt(path) {
48
+ let found;
38
49
  try {
39
- lstatSync(path);
40
- return true;
50
+ found = lstatSync(path);
41
51
  }
42
52
  catch (err) {
43
53
  if (errnoOf(err) === "ENOENT")
44
- return false;
45
- throw new ControlPlaneCorruptError(`memory control object at ${path} could not be probed (${errnoOf(err) ?? "io error"}) — whether it stands is unknown (fail-closed)`, { cause: err });
54
+ return "absent";
55
+ throw unprobeable(path, err);
56
+ }
57
+ if (found.isFile())
58
+ return "object";
59
+ if (!found.isSymbolicLink())
60
+ return "other";
61
+ try {
62
+ return statSync(path).isFile() ? "object" : "other";
63
+ }
64
+ catch (err) {
65
+ const code = errnoOf(err);
66
+ if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
67
+ return "other";
68
+ throw unprobeable(path, err);
69
+ }
70
+ }
71
+ function stands(path) {
72
+ return entryAt(path) !== "absent";
73
+ }
74
+ function notAnObject(kind, name, refusal) {
75
+ return new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but is not a control object (a regular file under a legal name) — ${refusal} (fail-closed)`);
76
+ }
77
+ function otherBytesStand(kind, name) {
78
+ return new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name already stands with different bytes — refusing to overwrite it (fail-closed)`);
79
+ }
80
+ function standingHolds(controlDir, kind, name, bytes) {
81
+ const standing = getFileControlObject(controlDir, kind, name);
82
+ return standing === undefined ? undefined : Buffer.from(standing).equals(bytes);
83
+ }
84
+ export function probeControlPlaneLinks(controlDir) {
85
+ const source = join(controlDir, `${LINK_PROBE_PREFIX}${randomUUID()}`);
86
+ const linked = `${source}.link`;
87
+ try {
88
+ closeSync(openSync(source, "wx", 0o600));
89
+ }
90
+ catch {
91
+ return;
92
+ }
93
+ let made = false;
94
+ try {
95
+ linkSync(source, linked);
96
+ made = true;
97
+ }
98
+ catch (err) {
99
+ const fault = errnoOf(err);
100
+ if (fault !== "EEXIST")
101
+ throw controlPlaneLinksRefusal(controlDir, fault);
102
+ }
103
+ finally {
104
+ for (const path of made ? [linked, source] : [source]) {
105
+ try {
106
+ rmSync(path, { force: true });
107
+ }
108
+ catch {
109
+ }
110
+ }
46
111
  }
47
112
  }
48
113
  export function putFileControlObject(controlDir, kind, name, bytes) {
49
114
  const path = objectPath(controlDir, kind, name);
50
- if (stands(path))
115
+ const held = standingHolds(controlDir, kind, name, bytes);
116
+ if (held === true)
51
117
  return "existed";
118
+ if (held === false)
119
+ throw otherBytesStand(kind, name);
52
120
  ensureDirExists(join(controlDir, fileControlObjectDirOf(kind)));
53
121
  const stageDir = join(controlDir, CONTROL_OBJECT_STAGE_DIR);
54
122
  ensureDirExists(stageDir);
@@ -72,8 +140,14 @@ export function putFileControlObject(controlDir, kind, name, bytes) {
72
140
  return "created";
73
141
  }
74
142
  catch (err) {
75
- if (errnoOf(err) === "EEXIST")
76
- return "existed";
143
+ if (errnoOf(err) === "EEXIST") {
144
+ const held = standingHolds(controlDir, kind, name, bytes);
145
+ if (held === true)
146
+ return "existed";
147
+ if (held === false)
148
+ throw otherBytesStand(kind, name);
149
+ throw new ControlPlaneCorruptError(`memory control object put ${kind}/${name}: the name stood when the object was published and was gone when its bytes were compared — nothing was written (fail-closed)`);
150
+ }
77
151
  throw err;
78
152
  }
79
153
  finally {
@@ -82,6 +156,11 @@ export function putFileControlObject(controlDir, kind, name, bytes) {
82
156
  }
83
157
  export function getFileControlObject(controlDir, kind, name) {
84
158
  const path = objectPath(controlDir, kind, name);
159
+ const state = entryAt(path);
160
+ if (state === "absent")
161
+ return undefined;
162
+ if (state === "other")
163
+ throw notAnObject(kind, name, "it is never read as missing");
85
164
  try {
86
165
  return new Uint8Array(readFileSync(path));
87
166
  }
@@ -91,7 +170,7 @@ export function getFileControlObject(controlDir, kind, name) {
91
170
  throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but cannot be read (${errnoOf(err) ?? "io error"}) — it is never read as missing (fail-closed)`, { cause: err });
92
171
  }
93
172
  }
94
- export function listFileControlObjects(controlDir, kind) {
173
+ export function standingFileControlObjectNames(controlDir, kind) {
95
174
  const dir = join(controlDir, fileControlObjectDirOf(kind));
96
175
  try {
97
176
  return readdirSync(dir).sort();
@@ -102,6 +181,10 @@ export function listFileControlObjects(controlDir, kind) {
102
181
  throw new ControlPlaneCorruptError(`memory control objects of kind ${kind} could not be enumerated (${errnoOf(err) ?? "io error"}) at ${dir} — an enumeration failure is not an empty kind (fail-closed)`, { cause: err });
103
182
  }
104
183
  }
184
+ export function listFileControlObjects(controlDir, kind) {
185
+ const dir = join(controlDir, fileControlObjectDirOf(kind));
186
+ return standingFileControlObjectNames(controlDir, kind).filter((name) => isControlObjectName(name) && entryAt(join(dir, name)) === "object");
187
+ }
105
188
  function sameBytes(a, b) {
106
189
  const sa = statSync(a);
107
190
  const sb = statSync(b);
@@ -131,14 +214,53 @@ export function moveFileControlObject(controlDir, from, to) {
131
214
  }
132
215
  if (code !== "EEXIST")
133
216
  throw err;
217
+ if (!lstatSync(dst).isFile())
218
+ throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands but is not a file of its own (a link, or no file) — refusing to drop the source onto it (fail-closed)`);
134
219
  if (!sameBytes(src, dst))
135
220
  throw new ControlPlaneCorruptError(`memory control object move ${from.kind}/${from.name} → ${to.kind}/${to.name}: the target already stands with different bytes — refusing to overwrite it (fail-closed)`);
136
221
  }
137
222
  unlinkSync(src);
138
223
  return "moved";
139
224
  }
225
+ export function putFileControlObjectOnce(controlDir, kind, name, bytes) {
226
+ try {
227
+ return putFileControlObject(controlDir, kind, name, bytes);
228
+ }
229
+ catch (err) {
230
+ let standing;
231
+ try {
232
+ standing = getFileControlObject(controlDir, kind, name);
233
+ }
234
+ catch {
235
+ throw err;
236
+ }
237
+ if (standing === undefined)
238
+ throw err;
239
+ return "existed";
240
+ }
241
+ }
242
+ export function captureIntoFileQuarantine(controlDir, path, content, now) {
243
+ const bytes = new TextEncoder().encode(content);
244
+ const base = quarantineCaptureBase(path, now);
245
+ try {
246
+ for (let attempt = 0; attempt <= 10; attempt++) {
247
+ const name = quarantineCaptureName(base, attempt);
248
+ if (putFileControlObjectOnce(controlDir, "quarantine", name, bytes) === "created")
249
+ return { name };
250
+ }
251
+ return { failed: "quarantine copy failed: every capture name already stands" };
252
+ }
253
+ catch (err) {
254
+ return { failed: `quarantine copy failed: ${thrownText(err)}` };
255
+ }
256
+ }
140
257
  export function deleteFileControlObject(controlDir, kind, name) {
141
258
  const path = objectPath(controlDir, kind, name);
259
+ const state = entryAt(path);
260
+ if (state === "absent")
261
+ return false;
262
+ if (state === "other")
263
+ throw notAnObject(kind, name, "refusing to delete it");
142
264
  try {
143
265
  unlinkSync(path);
144
266
  return true;
@@ -146,6 +268,6 @@ export function deleteFileControlObject(controlDir, kind, name) {
146
268
  catch (err) {
147
269
  if ((errnoOf(err) === "ENOENT" || errnoOf(err) === "ENOTDIR") && !stands(path))
148
270
  return false;
149
- throw err;
271
+ throw new ControlPlaneCorruptError(`memory control object ${kind}/${name} stands but could not be deleted (${errnoOf(err) ?? "io error"}) (fail-closed)`, { cause: err });
150
272
  }
151
273
  }
@@ -3,7 +3,8 @@ import { type MemoryControlObjectKind, type MemoryGovernanceDocName, type Memory
3
3
  export interface ReplicaControlPlaneStrays {
4
4
  /** The governance documents with a file (or a journal) in the replica. */
5
5
  readonly docs: readonly MemoryGovernanceDocName[];
6
- /** How many control objects of each kind the replica holds (kinds it holds none of are absent). */
6
+ /** How many entries stand in each kind's directory of the replica (kinds with none are absent): the control objects, and whatever
7
+ * else stands where an object's record belongs — adoption refuses each of those by name, never skips it. */
7
8
  readonly objects: Readonly<Partial<Record<MemoryControlObjectKind, number>>>;
8
9
  }
9
10
  /** One record adoption handled: a document (`doc:<name>`) or an object (`<kind>/<name>`). */
@@ -35,7 +36,9 @@ export declare function replicaControlPlaneStrays(controlDir: string): ReplicaCo
35
36
  /**
36
37
  * Copy the replica control plane's carrier records into `carrier` (see the module note). Answers what the carrier now
37
38
  * holds with the replica's value and what was refused; the replica's records are not removed either way. When `carrier`
38
- * is the File store over `controlDir` itself there is nothing to hand over and the answer is empty.
39
+ * is the File store over `controlDir` itself there is nothing to hand over and the answer is empty. A `controlDir` that does
40
+ * not exist is refused (`ControlPlaneCorruptError`): the call is an operator's, over a path they named, and a wrong path must
41
+ * not read as "nothing to adopt".
39
42
  */
40
43
  export declare function adoptReplicaControlPlane(controlDir: string, carrier: MemoryGovernanceStore, opts?: {
41
44
  readonly now?: () => number;
@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
4
4
  import { isDeepStrictEqual } from "node:util";
5
5
  import { MEMORY_CONTROL_OBJECT_KINDS, MEMORY_GOVERNANCE_DOC_NAMES } from "./types.js";
6
6
  import { ControlPlaneCorruptError, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
7
- import { getFileControlObject, listFileControlObjects } from "./control-objects.js";
7
+ import { getFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
8
8
  import { fileGovernanceStoreDir } from "./consolidation.js";
9
9
  import { moveOriginClearanceCustodyOut } from "./origin-clearance.js";
10
10
  import { thrownText } from "../thrown-value.js";
@@ -38,7 +38,7 @@ export function replicaControlPlaneStrays(controlDir) {
38
38
  });
39
39
  const objects = {};
40
40
  for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
41
- const n = listFileControlObjects(controlDir, kind).length;
41
+ const n = standingFileControlObjectNames(controlDir, kind).length;
42
42
  if (n > 0)
43
43
  objects[kind] = n;
44
44
  }
@@ -65,6 +65,8 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
65
65
  const refused = [];
66
66
  if (carriesThisDirectory(carrier, controlDir))
67
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)`);
68
70
  const receipt = (record, digest) => {
69
71
  lockedStrictUpdate(controlDir, CONTROL_PLANE_ADOPTION_FILE, "memory control-plane adoption receipt", coerceReceipt, (rec) => {
70
72
  if (rec.adopted.some((r) => r.record === record && r.digest === digest))
@@ -83,7 +85,7 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
83
85
  }
84
86
  }
85
87
  for (const kind of MEMORY_CONTROL_OBJECT_KINDS) {
86
- for (const name of listFileControlObjects(controlDir, kind)) {
88
+ for (const name of standingFileControlObjectNames(controlDir, kind)) {
87
89
  const record = `${kind}/${name}`;
88
90
  try {
89
91
  const bytes = getFileControlObject(controlDir, kind, name);
@@ -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,10 +269,14 @@ export declare function resolveSessionAccountRecord(docs: MemoryGovernanceDocs,
268
269
  requestId: string;
269
270
  now: () => number;
270
271
  }): Promise<void>;
271
- /** The hold ledger's file: the File store's coordinate of the governance document `holds`. */
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}). */
272
274
  export declare const HOLDS_FILE: string;
273
275
  /** The hold custody directory: the File store's directory of the control-object kind `hold`. */
274
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;
275
280
  export type HoldStatus = "capturing" | "held" | "released" | "disposed";
276
281
  export type HoldTerminal = "dirty" | "expired" | "conflict" | "discarded" | "capture_lost";
277
282
  export interface HoldRow {
@@ -313,24 +318,26 @@ export interface HoldRow {
313
318
  * rows resolved before the member existed (a generation-less clear matches those). */
314
319
  resolvedAt?: number;
315
320
  }
316
- export declare function readHolds(controlDir: string): HoldRow[];
321
+ export declare function readHolds(docs: MemoryGovernanceDocs): Promise<HoldRow[]>;
317
322
  /** Where a plane file is staged while it is displaced: a SIBLING in the file's OWN directory.
318
323
  * `rename` is atomic only WITHIN one filesystem, and the control plane is routinely a different mount
319
324
  * from the memory dir — staging there surrenders the atomicity the rename-first law exists for, and a
320
325
  * cross-device refusal is the ordinary shape of a two-volume deployment, not an exotic failure. A
321
326
  * sibling is on the file's filesystem by construction, so one path serves both layouts. The staged
322
- * 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}). */
323
328
  export declare function stagingPathBeside(absPath: string, stagingName: string): string;
324
- /** Move whatever still sits at a staged generation into control-plane custody and report WHERE the
325
- * bytes ended up. Withheld bytes belong in the control plane, never on the model-visible plane — but
326
- * a copy that cannot be made there must leave the only copy where it is and SAY so, so the coordinate
327
- * is the host's recovery address either way and `settled` answers one question: in custody, with
328
- * nothing left beside the seat? Takes an ALREADY-CLAIMED path (read, decision and removal address
329
- * one inode) and removes it only after {@link writeCustodyVerified} has proven the copy. */
330
- 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<{
331
338
  settled: boolean;
332
339
  at: string;
333
- };
340
+ }>;
334
341
  /** ATOMIC no-replace restore of a staged file onto a plane path (adversarial round 2: an
335
342
  * existsSync-then-rename pair is a TOCTOU — POSIX rename REPLACES a destination created between
336
343
  * the check and the call, clobbering a third writer's newer bytes). `link` refuses EEXIST
@@ -341,8 +348,9 @@ export declare function noReplaceRestore(stagingPath: string, destPath: string):
341
348
  * §4.2 — open one hold over an instruction-form file: the two-stage journal.
342
349
  * ① append row `status:"capturing"` (deterministic captureName + contentDigest minted from the
343
350
  * one read buffer) — the account exists before any byte moves;
344
- * ② write the custody file FROM THE SAME BUFFER, read it back, verify the digest;
345
- * ③ 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
346
354
  * directory — {@link stagingPathBeside}), then hash what actually moved: equal ⇒ the staged
347
355
  * duplicate is dropped (custody already holds verified bytes); unequal ⇒ a third writer replaced
348
356
  * the file between read and rename — NO-CLOBBER rollback (the newer bytes go back ONLY if the
@@ -355,7 +363,7 @@ export declare function noReplaceRestore(stagingPath: string, destPath: string):
355
363
  * plane, revoked permission) is one such refusal: the file would stay on the plane, the one outcome
356
364
  * a hold may not produce.
357
365
  */
358
- export declare function openInstructionHold(controlDir: string, input: {
366
+ export declare function openInstructionHold(store: HoldStore, input: {
359
367
  sessionId: string;
360
368
  /** The seat in the ledger form (relative to the write scope's home). */
361
369
  rel: string;
@@ -368,7 +376,10 @@ export declare function openInstructionHold(controlDir: string, input: {
368
376
  scope: string;
369
377
  settleIds: readonly string[];
370
378
  now: () => number;
371
- }): {
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<{
372
383
  ok: true;
373
384
  holdId: string;
374
385
  thirdWriterStrandedAt?: string;
@@ -376,7 +387,7 @@ export declare function openInstructionHold(controlDir: string, input: {
376
387
  ok: false;
377
388
  holdId?: string;
378
389
  reason: string;
379
- };
390
+ }>;
380
391
  /**
381
392
  * §4.2 reconciliation — converge half-way holds (a crash between the journal stages):
382
393
  * - `capturing` + custody file present & digest-equal ⇒ flip held (the crash was after ②);
@@ -387,14 +398,17 @@ export declare function openInstructionHold(controlDir: string, input: {
387
398
  * - `capturing` + custody absent + plane file gone ⇒ `capture_lost` (nothing to hold).
388
399
  * - `held` + plane file REAPPEARED at the seat ⇒ left alone (a fresh write is a fresh file —
389
400
  * the next harvest judges it on its own; the hold's custody bytes stay the hold's).
390
- * - `disposed` + the row names its quarantine seat + the custody file is still at the custody seat
401
+ * - `disposed` + the row names its quarantine seat + the custody object still stands
391
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.
392
405
  */
393
- export declare function reconcileHolds(controlDir: string, input: {
406
+ export declare function reconcileHolds(store: HoldStore, input: {
394
407
  homeOf: (scope: string) => string;
395
408
  now: () => number;
396
409
  onStranded: (scope: string, line: string) => void;
397
- }): void;
410
+ actRefused: (path: string, act: string) => string | undefined;
411
+ }): Promise<void>;
398
412
  /** The quarantine seat of a hold's custody bytes: a function of the ROW, never of a clock. The same
399
413
  * row names the same seat on every call, in every process, after any crash — the old
400
414
  * `<ms>-hold-<captureName>` shape with the row's own content digest where the wall clock was. */
@@ -404,35 +418,37 @@ export declare function holdQuarantineNameOf(row: Pick<HoldRow, "captureName" |
404
418
  * from-row-to-bytes addressing survives every terminal). Row first, bytes second: a crash between
405
419
  * the two leaves a row whose bytes are at the custody seat or the quarantine seat — both of which
406
420
  * {@link readHoldCustody} tries — and {@link reconcileHolds} finishes the move; the reverse order
407
- * would leave bytes in quarantine under a name no row recorded. Whether the row names a seat is read
408
- * INSIDE the ledger lock, from what stands at the custody seat and the quarantine seat at that
409
- * moment: a row with no custody bytes anywhere records the terminal with no name (nothing to move).
410
- * The verdict always lands: a quarantine seat held by something that is not the hold's bytes records
411
- * the terminal with no name, leaves the custody bytes where they are and replaces nothing — and then
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
412
428
  * refuses loudly (the caller hears it; a refused intake is terminal all the same). */
413
- export declare function disposeHold(controlDir: string, input: {
429
+ export declare function disposeHold(store: HoldStore, input: {
414
430
  holdId: string;
415
431
  terminal: HoldTerminal;
416
- }): {
432
+ }): Promise<{
417
433
  ok: boolean;
418
434
  quarantineName?: string;
419
- };
435
+ }>;
420
436
  /** Flip one row to released (the caller — the harvest release leg — has already committed the
421
- * custody bytes through the full gate set; the custody file is dropped after the flip). */
422
- 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: {
423
439
  holdId: string;
424
440
  now: () => number;
425
- }): void;
441
+ }): Promise<void>;
426
442
  /** The host valve — `resolveHold(holdId, "release"|"discard", requestId)`: records the verdict on
427
443
  * the row; the NEXT harvest reconciliation executes it ("release" re-walks the full gates and
428
444
  * commits WITH cause "static" — a timeout release is not proof of cleanliness; "discard"
429
445
  * disposes to quarantine). requestId required (audit, #123). */
430
- export declare function resolveHoldRecord(controlDir: string, input: {
446
+ export declare function resolveHoldRecord(docs: MemoryGovernanceDocs, input: {
431
447
  holdId: string;
432
448
  action: "release" | "discard";
433
449
  requestId: string;
434
450
  now: () => number;
435
- }): void;
451
+ }): Promise<void>;
436
452
  /**
437
453
  * Consume a standing valve verdict WITHOUT any other transition — the settle leg's exit for a
438
454
  * valve release that FAILED on an already-disposed row (an expired hold whose release hit a
@@ -451,15 +467,16 @@ export declare function resolveHoldRecord(controlDir: string, input: {
451
467
  * on purpose (refusing it would revive the forever-re-firing valve loop for every verdict minted
452
468
  * before the upgrade). Idempotent; unknown/verdict-less/other-generation rows are a no-op.
453
469
  */
454
- export declare function clearHoldResolution(controlDir: string, input: {
470
+ export declare function clearHoldResolution(docs: MemoryGovernanceDocs, input: {
455
471
  holdId: string;
456
472
  ifResolvedAt: number | undefined;
457
- }): void;
473
+ }): Promise<void>;
458
474
  /** Read one hold's custody bytes (release leg + expired-release valve). Returns undefined when
459
- * 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
460
476
  * unverified bytes. For an expired-released row the bytes may already sit in quarantine
461
477
  * (disposition.quarantineName) — both seats are tried, digest-verified either way. */
462
- export declare function readHoldCustody(controlDir: string, row: HoldRow): string | undefined;
478
+ export declare function readHoldCustody(objects: Pick<MemoryGovernanceObjects, "getObject">, row: HoldRow): Promise<string | undefined>;
463
479
  /** True ⇔ the session's pollution marker or any non-clean settlement row blocks a clean release
464
480
  * (§4.2-1: any non-clean row in the session's account keeps the hold held/disposed). */
465
- 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 {};