@sema-agent/core 7.62.0 → 7.63.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 (193) hide show
  1. package/CHANGELOG.md +528 -0
  2. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  3. package/dist/agents/subagent-transcript-placement.js +14 -0
  4. package/dist/agents/subagent.js +82 -51
  5. package/dist/brain/route-adjudicator.js +9 -4
  6. package/dist/core/approval-object.js +1 -1
  7. package/dist/core/arg-summary.js +1 -1
  8. package/dist/core/ask-question.d.ts +2 -2
  9. package/dist/core/canonical-json.d.ts +23 -13
  10. package/dist/core/canonical-json.js +4 -4
  11. package/dist/core/checkpoint-queries.d.ts +47 -4
  12. package/dist/core/checkpoint-queries.js +36 -16
  13. package/dist/core/checkpoint-requirements.d.ts +3 -3
  14. package/dist/core/checkpoint-requirements.js +2 -1
  15. package/dist/core/checkpoint-row-verdict.d.ts +15 -4
  16. package/dist/core/checkpoint-row-verdict.js +22 -2
  17. package/dist/core/checkpoint-store.d.ts +23 -10
  18. package/dist/core/checkpoint-store.js +45 -4
  19. package/dist/core/compliance.d.ts +6 -2
  20. package/dist/core/compliance.js +3 -3
  21. package/dist/core/engine-attestation.d.ts +1 -1
  22. package/dist/core/engine-notice.d.ts +19 -4
  23. package/dist/core/git-worktree-env.d.ts +62 -3
  24. package/dist/core/git-worktree-env.js +91 -30
  25. package/dist/core/governance-codes.d.ts +7 -3
  26. package/dist/core/governance-codes.js +13 -3
  27. package/dist/core/memory-engine/consolidation-driver.d.ts +32 -17
  28. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  29. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  30. package/dist/core/memory-engine/consolidation.js +167 -11
  31. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  32. package/dist/core/memory-engine/data-plane.js +11 -6
  33. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  34. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  35. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  36. package/dist/core/memory-engine/dual-root.js +9 -5
  37. package/dist/core/memory-engine/engine.d.ts +98 -35
  38. package/dist/core/memory-engine/engine.js +477 -380
  39. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  40. package/dist/core/memory-engine/entry-scan.js +3 -0
  41. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  42. package/dist/core/memory-engine/file-backend.js +66 -35
  43. package/dist/core/memory-engine/index.d.ts +7 -7
  44. package/dist/core/memory-engine/index.js +6 -6
  45. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  46. package/dist/core/memory-engine/landing-admission.js +3 -3
  47. package/dist/core/memory-engine/layout.d.ts +121 -45
  48. package/dist/core/memory-engine/layout.js +252 -102
  49. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  50. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  51. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  52. package/dist/core/memory-engine/memory-deployment.js +26 -12
  53. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  54. package/dist/core/memory-engine/scope-contract.js +68 -19
  55. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  56. package/dist/core/memory-engine/session-write-home.js +1 -1
  57. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  58. package/dist/core/memory-engine/sync-client.js +7 -0
  59. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  60. package/dist/core/memory-engine/sync-report.js +6 -2
  61. package/dist/core/memory-engine/tools.d.ts +2 -2
  62. package/dist/core/memory-engine/tools.js +10 -10
  63. package/dist/core/memory-engine/types.d.ts +118 -19
  64. package/dist/core/memory-engine/types.js +1 -0
  65. package/dist/core/memory.js +15 -6
  66. package/dist/core/mods/stations.d.ts +20 -1
  67. package/dist/core/mods/stations.js +21 -2
  68. package/dist/core/park-selfcheck.js +2 -2
  69. package/dist/core/pause-registry.d.ts +2 -0
  70. package/dist/core/pause-registry.js +3 -0
  71. package/dist/core/permission-rule-consent.d.ts +10 -3
  72. package/dist/core/permission-rule-consent.js +37 -24
  73. package/dist/core/permission-rule-store.d.ts +35 -1
  74. package/dist/core/permission-rule-store.js +27 -8
  75. package/dist/core/read-only-shell.js +3 -2
  76. package/dist/core/redaction-marks.d.ts +8 -0
  77. package/dist/core/redaction-marks.js +6 -0
  78. package/dist/core/remote-env.d.ts +12 -1
  79. package/dist/core/remote-env.js +3 -0
  80. package/dist/core/runner/child-tree.d.ts +29 -3
  81. package/dist/core/runner/child-tree.js +39 -16
  82. package/dist/core/runner/contracts.d.ts +18 -9
  83. package/dist/core/runner/gate-exit.js +2 -2
  84. package/dist/core/runner/inherited-ask-grants.js +1 -1
  85. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  86. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  87. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  88. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  89. package/dist/core/runner/person-path-rows.d.ts +8 -3
  90. package/dist/core/runner/person-path-rows.js +5 -1
  91. package/dist/core/runner/placement-fence.d.ts +12 -0
  92. package/dist/core/runner/placement-fence.js +20 -6
  93. package/dist/core/runner/prepare-ask-lane.js +2 -2
  94. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -1
  95. package/dist/core/runner/prepare-caps-and-workflow.js +5 -2
  96. package/dist/core/runner/prepare-execution-env.js +17 -6
  97. package/dist/core/runner/prepare-hands-readface.d.ts +2 -1
  98. package/dist/core/runner/prepare-hands-readface.js +4 -3
  99. package/dist/core/runner/prepare-inherited-gate.d.ts +10 -8
  100. package/dist/core/runner/prepare-inherited-gate.js +8 -4
  101. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  102. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  103. package/dist/core/runner/prepare-memory.d.ts +3 -2
  104. package/dist/core/runner/prepare-memory.js +28 -20
  105. package/dist/core/runner/prepare-park-ask.js +4 -3
  106. package/dist/core/runner/prepare-task.js +15 -12
  107. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  108. package/dist/core/runner/run-leg.js +1 -1
  109. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  110. package/dist/core/runner/terminal-account.js +1 -1
  111. package/dist/core/runner-deps.d.ts +6 -2
  112. package/dist/core/secret-env.d.ts +1 -1
  113. package/dist/core/secret-env.js +4 -4
  114. package/dist/core/session-checkout.d.ts +108 -0
  115. package/dist/core/session-checkout.js +485 -0
  116. package/dist/core/session-store.d.ts +12 -4
  117. package/dist/core/session-store.js +23 -3
  118. package/dist/core/session.d.ts +16 -2
  119. package/dist/core/session.js +3 -0
  120. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +0 -12
  121. package/dist/core/store-contracts/checkpoint-store-contract.js +6 -7
  122. package/dist/core/store-contracts/session-store-contract.js +39 -0
  123. package/dist/core/task-event.d.ts +21 -0
  124. package/dist/core/task-notification.d.ts +9 -1
  125. package/dist/core/task-notification.js +6 -0
  126. package/dist/core/task-registry-agent.d.ts +14 -2
  127. package/dist/core/task-registry-agent.js +45 -19
  128. package/dist/core/task-registry-shared.d.ts +26 -11
  129. package/dist/core/task-registry.d.ts +15 -9
  130. package/dist/core/task-registry.js +9 -10
  131. package/dist/core/task-spec-members.js +1 -1
  132. package/dist/core/task-spec.d.ts +20 -0
  133. package/dist/core/tool-policy.d.ts +14 -12
  134. package/dist/core/tool-policy.js +11 -10
  135. package/dist/core/tool-spec.d.ts +38 -19
  136. package/dist/core/types.d.ts +1 -1
  137. package/dist/core/untrusted-egress.d.ts +15 -4
  138. package/dist/core/untrusted-egress.js +23 -22
  139. package/dist/core/workspace-snapshot.d.ts +3 -1
  140. package/dist/core/workspace-snapshot.js +1 -0
  141. package/dist/engine/harness/types.d.ts +66 -1
  142. package/dist/engine/harness/types.js +108 -0
  143. package/dist/engine/session/import-validate.js +6 -1
  144. package/dist/engine/session/session.d.ts +24 -1
  145. package/dist/engine/session/session.js +45 -1
  146. package/dist/index.d.ts +7 -4
  147. package/dist/index.js +7 -4
  148. package/dist/internal/harness-types.d.ts +1 -1
  149. package/dist/orchestration/run-workflow-tool.d.ts +4 -1
  150. package/dist/orchestration/run-workflow-tool.js +1 -0
  151. package/dist/orchestration/workflow.d.ts +3 -0
  152. package/dist/orchestration/workflow.js +3 -1
  153. package/dist/stores/file/session-store.js +2 -1
  154. package/dist/tools/fs/bash-program-position.js +3 -3
  155. package/dist/tools/fs/program-read-model.d.ts +34 -10
  156. package/dist/tools/fs/program-read-model.js +37 -7
  157. package/dist/tools/fs/program-read-model.rows.js +13 -2
  158. package/dist/tools/fs/read-deny.d.ts +13 -1
  159. package/dist/tools/fs/read-deny.js +10 -2
  160. package/dist/tools/fs/removal-targets.js +3 -3
  161. package/dist/tools/fs/safety.d.ts +2 -0
  162. package/dist/tools/fs/safety.js +1 -1
  163. package/dist/tools/fs/shell-read-argv.d.ts +8 -1
  164. package/dist/tools/fs/shell-read-argv.js +34 -29
  165. package/dist/tools/fs/shell-read-bindings.d.ts +2 -0
  166. package/dist/tools/fs/shell-read-bindings.js +5 -1
  167. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  168. package/dist/tools/fs/shell-read-brace.js +79 -0
  169. package/dist/tools/fs/shell-read-check.js +10 -8
  170. package/dist/tools/fs/shell-read-establish.js +23 -16
  171. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  172. package/dist/tools/fs/shell-read-judge.js +3 -3
  173. package/dist/tools/fs/shell-read-plan.d.ts +10 -0
  174. package/dist/tools/fs/shell-read-plan.js +189 -93
  175. package/dist/tools/fs/shell-read-start.d.ts +19 -9
  176. package/dist/tools/fs/shell-read-start.js +20 -12
  177. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  178. package/dist/tools/fs/shell-read-word.js +9 -5
  179. package/dist/tools/fs/shell-read-workdir.d.ts +26 -7
  180. package/dist/tools/fs/shell-read-workdir.js +73 -12
  181. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  182. package/dist/tools/worktree.d.ts +3 -2
  183. package/dist/tools/worktree.js +7 -35
  184. package/package.json +3 -2
  185. package/test/export-surface.snapshot.json +73 -11
  186. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  187. package/wire-changes/core@7.63.0.json +3523 -0
  188. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  189. package/wire-changes/primitives@7.63.0.json +445 -0
  190. package/dist/core/credential-vocabulary.d.ts +0 -176
  191. package/dist/core/credential-vocabulary.js +0 -190
  192. package/dist/core/redaction-passes.d.ts +0 -82
  193. package/dist/core/redaction-passes.js +0 -377
@@ -1,7 +1,7 @@
1
- import { existsSync, readdirSync, renameSync } from "node:fs";
1
+ import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
2
2
  import { join } from "node:path";
3
3
  import { uuidv7 } from "../../engine/session/uuid.js";
4
- import { atomicWriteFileSync, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
4
+ import { atomicWriteFileSync, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
5
5
  import { thrownText } from "../thrown-value.js";
6
6
  import { optionKeys, receiveMembers } from "../own-property-receipt.js";
7
7
  export function deriveSupersededSet(headers, opts = {}) {
@@ -58,7 +58,7 @@ function coded(message, code) {
58
58
  e.code = code;
59
59
  return e;
60
60
  }
61
- export function screenConsolidationOptions(given, provenance) {
61
+ export function screenConsolidationOptions(given, provenance, durability) {
62
62
  if (provenance === "off") {
63
63
  throw coded(`MemoryEngineOptions.consolidation cannot be enabled under provenance: "off" — the consolidation fold law must be able to mint origin markers (a marked input's product would otherwise commit unmarked). Enable provenance "carry" or remove the consolidation options.`, "config.memory_consolidation_provenance_off");
64
64
  }
@@ -98,12 +98,23 @@ export function screenConsolidationOptions(given, provenance) {
98
98
  if (raw.lease !== undefined && typeof raw.lease.acquire !== "function") {
99
99
  throw coded(`MemoryEngineOptions.consolidation.lease.acquire must be a function.`, "config.memory_consolidation");
100
100
  }
101
+ if (screened.multiNode && durability === "replica-local") {
102
+ throw coded(`MemoryEngineOptions.consolidation.multiNode declared over a backend whose consolidation state is replica-local (memoryGovernanceDurability) — the challenge, settlement and lineage ledgers and the capture opt-out records a consolidation's eligibility reads stay in this replica's control plane, so another replica would consolidate entries this one excludes. Run consolidation on one node (remove the multiNode declaration) or use a backend whose state rides it.`, "config.memory_consolidation_replica_local");
103
+ }
101
104
  return screened;
102
105
  }
106
+ export const MEMORY_CHALLENGED_ENTRY_GUIDANCE = "If the fact is still needed, verify it with the user, record a fresh entry from their current statement, and delete the old entry.";
107
+ function fuseAllowance(n, ratio, floor) {
108
+ return Math.max(floor, Math.floor(ratio * n));
109
+ }
103
110
  export function supersessionFuseCeiling(activeSetSize, opts) {
104
111
  if (activeSetSize <= 1)
105
112
  return 0;
106
- return Math.min(activeSetSize - 1, Math.max(opts.supersedeAbsoluteFloor, Math.floor(opts.supersedeRatioCap * activeSetSize)));
113
+ return Math.min(activeSetSize - 1, fuseAllowance(activeSetSize, opts.supersedeRatioCap, opts.supersedeAbsoluteFloor));
114
+ }
115
+ export const DELETION_FUSE_FLOOR = 3;
116
+ export function deletionFuseCeiling(materialized, ratio) {
117
+ return fuseAllowance(materialized, ratio, DELETION_FUSE_FLOOR);
107
118
  }
108
119
  export function scanRefusalCeiling(submittedProducts, opts) {
109
120
  if (submittedProducts <= 0)
@@ -161,11 +172,11 @@ export function recommendationUnconsumed(row) {
161
172
  export function sessionsSinceExcludingCurrent(row) {
162
173
  return Math.max(0, (row?.sessions.count ?? 0) - 1);
163
174
  }
164
- export function recordConsolidationSession(controlDir, scope, sessionId, opts, now) {
165
- return updateConsolidationGate(controlDir, (file) => {
175
+ export function recordConsolidationSession(store, scope, sessionId, opts, now) {
176
+ return store.transact([], (file) => {
166
177
  const row = file.scopes[scope] ?? freshRow();
167
178
  if (row.sessions.ring.includes(sessionId)) {
168
- return { result: { recommended: false, sessionsSince: sessionsSinceExcludingCurrent(row) } };
179
+ return { writeGate: false, result: { recommended: false, sessionsSince: sessionsSinceExcludingCurrent(row) } };
169
180
  }
170
181
  row.sessions.count += 1;
171
182
  row.sessions.ring.push(sessionId);
@@ -182,17 +193,17 @@ export function recordConsolidationSession(controlDir, scope, sessionId, opts, n
182
193
  row.lastRecommendedAt = at;
183
194
  }
184
195
  file.scopes[scope] = row;
185
- return { next: file, result: { recommended, sessionsSince: banked } };
196
+ return { writeGate: true, result: { recommended, sessionsSince: banked } };
186
197
  });
187
198
  }
188
- export function recordActiveSetBaseline(controlDir, scope, size, ratioCap, _now) {
189
- return updateConsolidationGate(controlDir, (file) => {
199
+ export function recordActiveSetBaseline(store, scope, size, ratioCap) {
200
+ return store.transact([], (file) => {
190
201
  const row = file.scopes[scope] ?? freshRow();
191
202
  const prev = row.activeSetBaseline;
192
203
  row.activeSetBaseline = size;
193
204
  file.scopes[scope] = row;
194
205
  const collapsed = prev !== undefined && prev > 0 && size < prev && (prev - size) / prev > ratioCap ? { from: prev, to: size } : undefined;
195
- return { next: file, result: collapsed !== undefined ? { collapsed } : {} };
206
+ return { writeGate: true, result: collapsed !== undefined ? { collapsed } : {} };
196
207
  });
197
208
  }
198
209
  export function isValidConsolidationPlanId(value) {
@@ -362,6 +373,151 @@ export function readIntentCredentials(controlDir) {
362
373
  const raw = readStrictSidecar(controlDir, CONSOLIDATION_INTENTS_FILE, "memory consolidation intent-credential account");
363
374
  return coerceIntentFile(raw).rows;
364
375
  }
376
+ export const CONSOLIDATION_DRIVER_RUNS_FILE = "distiller-runs.json";
377
+ function coerceRunsFile(raw) {
378
+ if (raw === undefined)
379
+ return { v: 1, scopes: {} };
380
+ if (typeof raw !== "object" || raw === null || raw.v !== 1 || typeof raw.scopes !== "object" || raw.scopes === null) {
381
+ throw new ControlPlaneCorruptError("memory consolidation driver run account has an unrecognized shape (fail-closed sidecar)");
382
+ }
383
+ for (const [scope, rowRaw] of Object.entries(raw.scopes)) {
384
+ const r = rowRaw;
385
+ if (typeof r !== "object" || r === null || typeof r["runId"] !== "string" || (r["state"] !== "pending" && r["state"] !== "settled") || typeof r["cyclesDone"] !== "number") {
386
+ throw new ControlPlaneCorruptError(`memory consolidation driver run row for scope ${JSON.stringify(scope)} is malformed (fail-closed sidecar)`);
387
+ }
388
+ }
389
+ return raw;
390
+ }
391
+ export function distillerPlanArchiveName(runId, attempt) {
392
+ return `${runId}-a${attempt}.json`;
393
+ }
394
+ function mintPath(controlDir, name) {
395
+ return /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}-a[0-9]{1,9}\.json$/.test(name) ? join(controlDir, CONSOLIDATION_DRIVER_PLANS_DIR, name) : undefined;
396
+ }
397
+ export function consolidationRunSuperseded(scope, cur) {
398
+ const e = new Error(`memory consolidation driver run seat for scope ${JSON.stringify(scope)} was taken over by a newer invocation${cur !== undefined ? ` (run ${cur.runId} attempt ${cur.attempt ?? 0})` : ""} — this worker stops without settling; the newer claim owns the account.`);
399
+ e.code = "memory.consolidation_driver_superseded";
400
+ return e;
401
+ }
402
+ export function memoryGovernanceDurability(backend) {
403
+ const root = Reflect.get(backend, "controlPlaneRoot");
404
+ return typeof root === "string" && root !== "" ? "backend" : "replica-local";
405
+ }
406
+ const FILE_GOVERNANCE_DIRS = new WeakMap();
407
+ export function fileGovernanceStoreDir(store) {
408
+ return FILE_GOVERNANCE_DIRS.get(store);
409
+ }
410
+ function isMintArchive(value) {
411
+ return typeof value === "object" && value !== null && Reflect.get(value, "kind") === "llm-consolidation-plan";
412
+ }
413
+ export function fileGovernanceStore(controlDir) {
414
+ const runsWhat = "memory consolidation driver run account";
415
+ const store = Object.freeze({
416
+ async readDoc(name) {
417
+ const doc = fileGovernanceDocOf(name);
418
+ return readStrictSidecar(controlDir, doc.file, doc.what);
419
+ },
420
+ async updateDoc(name, coerce, fn) {
421
+ const doc = fileGovernanceDocOf(name);
422
+ return lockedStrictUpdate(controlDir, doc.file, doc.what, coerce, fn);
423
+ },
424
+ async transact(planIds, fn) {
425
+ return updateConsolidationGate(controlDir, (file) => {
426
+ const reads = new Map(planIds.map((id) => [id, readConsolidationPlan(controlDir, id)]));
427
+ const staged = new Map();
428
+ const tx = {
429
+ scopes: file.scopes,
430
+ plan(planId) {
431
+ const read = reads.get(planId);
432
+ if (read === undefined)
433
+ throw new Error(`consolidation transaction: plan ${JSON.stringify(planId)} was not named when the transaction began, so it was not read under it`);
434
+ return read;
435
+ },
436
+ writePlan(plan) {
437
+ staged.set(plan.planId, plan);
438
+ },
439
+ };
440
+ const { writeGate, result } = fn(tx);
441
+ for (const plan of staged.values())
442
+ writeConsolidationPlan(controlDir, plan);
443
+ return writeGate ? { next: file, result } : { result };
444
+ });
445
+ },
446
+ async readGate() {
447
+ return readConsolidationGateFile(controlDir).scopes;
448
+ },
449
+ readPlan(planId) {
450
+ return readConsolidationPlan(controlDir, planId);
451
+ },
452
+ async listPlanIds() {
453
+ return listConsolidationPlanIds(controlDir);
454
+ },
455
+ async quarantinePlan(planId) {
456
+ return quarantineCorruptPlan(controlDir, planId);
457
+ },
458
+ async recordIntents(rows) {
459
+ return recordIntentCredentials(controlDir, rows);
460
+ },
461
+ async readIntents() {
462
+ return readIntentCredentials(controlDir);
463
+ },
464
+ async claimRun(scope, fresh) {
465
+ return lockedStrictUpdate(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, runsWhat, coerceRunsFile, (file) => {
466
+ const cur = file.scopes[scope];
467
+ if (cur !== undefined && cur.state === "pending") {
468
+ cur.attempt = (cur.attempt ?? 0) + 1;
469
+ file.scopes[scope] = cur;
470
+ return { next: file, result: { row: structuredClone(cur), resumed: true } };
471
+ }
472
+ const row = fresh();
473
+ file.scopes[scope] = row;
474
+ return { next: file, result: { row: structuredClone(row), resumed: false } };
475
+ });
476
+ },
477
+ async readRun(scope) {
478
+ return coerceRunsFile(readStrictSidecar(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, runsWhat)).scopes[scope];
479
+ },
480
+ async writeRun(row) {
481
+ lockedStrictUpdate(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, runsWhat, coerceRunsFile, (file) => {
482
+ const cur = file.scopes[row.scope];
483
+ if (cur === undefined || cur.runId !== row.runId || (cur.attempt ?? 0) !== row.attempt)
484
+ throw consolidationRunSuperseded(row.scope, cur);
485
+ file.scopes[row.scope] = row;
486
+ return { next: file, result: undefined };
487
+ });
488
+ },
489
+ async archiveMint(runId, attempt, plan) {
490
+ ensureDirExists(join(controlDir, CONSOLIDATION_DRIVER_PLANS_DIR));
491
+ const name = distillerPlanArchiveName(runId, attempt);
492
+ atomicWriteFileSync(join(controlDir, CONSOLIDATION_DRIVER_PLANS_DIR, name), `${JSON.stringify(plan, null, 2)}\n`);
493
+ return name;
494
+ },
495
+ async readMint(name) {
496
+ const path = mintPath(controlDir, name);
497
+ if (path === undefined || !existsSync(path))
498
+ return undefined;
499
+ let parsed;
500
+ try {
501
+ parsed = JSON.parse(readFileSync(path, "utf8"));
502
+ }
503
+ catch (err) {
504
+ throw new ControlPlaneCorruptError(`memory consolidation mint archive ${JSON.stringify(name)} is unreadable or unparseable: ${thrownText(err)}`, { cause: err });
505
+ }
506
+ if (!isMintArchive(parsed))
507
+ throw new ControlPlaneCorruptError(`memory consolidation mint archive ${JSON.stringify(name)} does not carry the mint's kind (fail-closed)`);
508
+ return parsed;
509
+ },
510
+ async eraseMint(name) {
511
+ const path = mintPath(controlDir, name);
512
+ if (path === undefined || !existsSync(path))
513
+ return false;
514
+ rmSync(path, { force: true });
515
+ return true;
516
+ },
517
+ });
518
+ FILE_GOVERNANCE_DIRS.set(store, controlDir);
519
+ return store;
520
+ }
365
521
  export function deriveProductSlug(name, fallback) {
366
522
  const base = (name ?? "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
367
523
  return base.length > 0 ? base : fallback;
@@ -2,7 +2,8 @@ import type { HarvestRejection, MemoryBackend, MemoryEntry, NotePatch, PatchRepo
2
2
  /** Default per-file byte cap — SAME value as the host engine's MAX_MEMORY_BYTES (独立轨 F3: a 60KB
3
3
  * entry legal on the host must not be re-rejected every remote round; one cap, one truth). */
4
4
  export declare const REMOTE_HARVEST_PER_FILE_BYTES: number;
5
- /** Missing-file ratio above which the harvest refuses wholesale (engine MASS_DELETION_FUSE_RATIO). */
5
+ /** The deletion fuse's ratio leg on the remote lane (engine MASS_DELETION_FUSE_RATIO): with the shared
6
+ * floor, more removals than max(floor, ⌊ratio × N⌋) refuses the harvest wholesale. */
6
7
  export declare const REMOTE_MASS_DELETION_FUSE_RATIO = 0.5;
7
8
  /** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity). */
8
9
  export declare const REMOTE_HARVEST_MAX_FILES = 500;
@@ -52,7 +53,9 @@ export interface RemoteHarvestResult {
52
53
  /** Feed to `backend.applyPatches` (the deployment owns the call + the resulting PatchReport). */
53
54
  patches: NotePatch[];
54
55
  rejections: HarvestRejection[];
55
- /** Baseline files absent from the read-back set (info; NEVER a delete — tombstones only). */
56
+ /** Baseline files gone from the read-back set (absent, or blank). A writable one is the session's
57
+ * removal and rides `patches` as a delete (unless the fuse trips); a read-only one is only listed
58
+ * (no delete; any restore is the deployment's sandbox I/O). */
56
59
  missing: string[];
57
60
  /** Set instead of patches when the mass-deletion fuse trips (deployment surfaces it, human call). */
58
61
  incident?: {
@@ -71,8 +74,9 @@ export interface RemoteHarvestResult {
71
74
  /**
72
75
  * The pure gate+diff core over files read back from a remote sandbox. Same judgment order as the
73
76
  * host engine's harvest: readonly-layer tamper → rejection (restore is the deployment's I/O);
74
- * missing + fuse; per-file size cap → scan rule set (secret/injection/filename) → parse →
75
- * id-immutability (baseline id wins) → tombstone-only delete → CAS update / rename / add.
77
+ * removals + fuse (a removed writable file = a CAS'd delete); per-file size cap → scan rule set
78
+ * (secret/injection/filename) → parse → id-immutability (baseline id wins) → tombstone delete → CAS
79
+ * update / rename / add.
76
80
  */
77
81
  export declare function harvestFilesToPatches(baseline: RemoteMemoryBaseline, files: readonly RemoteMemoryFile[], opts?: {
78
82
  perFileBytes?: number;
@@ -2,7 +2,8 @@ import { uuidv7 } from "../../internal/harness.js";
2
2
  import { firstSentence } from "../memory.js";
3
3
  import { computeEntryRev, parseEntryFile, serializeEntryFile, UNCLOSED_MEMORY_FILE_REASON } from "./frontmatter.js";
4
4
  import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
5
- import { MEMORY_INDEX_FILENAME } from "./entry-scan.js";
5
+ import { MEMORY_INDEX_FILENAME, carriesEntry } from "./entry-scan.js";
6
+ import { deletionFuseCeiling } from "./consolidation.js";
6
7
  import { scopeDirName } from "./layout.js";
7
8
  export const REMOTE_HARVEST_PER_FILE_BYTES = 100 * 1024;
8
9
  export const REMOTE_MASS_DELETION_FUSE_RATIO = 0.5;
@@ -33,7 +34,8 @@ export function harvestFilesToPatches(baseline, files, opts = {}) {
33
34
  const writeScope = baseline.writeScope;
34
35
  if (writeScope === null)
35
36
  return out;
36
- const byRel = new Map(files.map((f) => [f.relPath, f]));
37
+ const carried = files.filter((f) => carriesEntry(f.content));
38
+ const byRel = new Map(carried.map((f) => [f.relPath, f]));
37
39
  const baseByRel = new Map(baseline.files.map((b) => [b.relPath, b]));
38
40
  const basePathById = new Map(baseline.files.filter((b) => !b.readonly).map((b) => [b.id, b.relPath]));
39
41
  const readonlyPrefixes = new Set();
@@ -70,7 +72,7 @@ export function harvestFilesToPatches(baseline, files, opts = {}) {
70
72
  }
71
73
  const presentIds = new Set();
72
74
  const parsedByRel = new Map();
73
- for (const f of files) {
75
+ for (const f of carried) {
74
76
  if (baseByRel.get(f.relPath)?.readonly)
75
77
  continue;
76
78
  const p = parseEntryFile(f.content);
@@ -81,16 +83,19 @@ export function harvestFilesToPatches(baseline, files, opts = {}) {
81
83
  const writable = baseline.files.filter((b) => !b.readonly);
82
84
  const missingWritable = writable.filter((b) => !byRel.has(b.relPath) && !presentIds.has(b.id));
83
85
  out.missing.push(...missingWritable.map((b) => b.relPath));
84
- if (writable.length > 0 && missingWritable.length / writable.length > fuseRatio) {
86
+ const ceiling = deletionFuseCeiling(writable.length, fuseRatio);
87
+ if (missingWritable.length > ceiling) {
85
88
  out.incident = {
86
89
  kind: "mass_deletion",
87
- detail: `${missingWritable.length}/${writable.length} materialized memory files are missing from the read-back set — judged an accident, harvest refused (no patches; explicit frontmatter tombstones are the only deletion channel)`,
90
+ detail: `${missingWritable.length}/${writable.length} materialized memory files are missing from the read-back set — more than one harvest may remove (${ceiling}), judged an accident: harvest refused, no patches`,
88
91
  };
89
92
  out.patches = [];
90
93
  return out;
91
94
  }
95
+ for (const b of missingWritable)
96
+ out.patches.push({ op: "delete", id: b.id, baseRev: b.rev });
92
97
  let kept = 0;
93
- for (const f of files) {
98
+ for (const f of carried) {
94
99
  const base = baseByRel.get(f.relPath);
95
100
  if (base?.readonly)
96
101
  continue;
@@ -1,5 +1,4 @@
1
- import type { MemoryOriginCause } from "./types.js";
2
- export declare const DELEGATION_SETTLEMENT_FILE = "delegation-settlement.json";
1
+ import type { MemoryGovernanceDocs, MemoryOriginCause } from "./types.js";
3
2
  /** A row's FIRST-WRITE status. Rows are immutable after their first write — every later transition
4
3
  * is an append-only event ({@link SettlementEvent}); the effective status is the fold. */
5
4
  export type SettlementRowStatus = "pending" | "unattestable";
@@ -45,12 +44,12 @@ export declare function syncSettleId(sessionId: string, toolCallId: string): str
45
44
  * or corrupt ledger — the launch site fails the launch loudly (a delegation that cannot be
46
45
  * accounted must not run: the whole point is that no child exists outside the account).
47
46
  */
48
- export declare function registerDelegationLaunch(controlDir: string, input: {
47
+ export declare function registerDelegationLaunch(docs: MemoryGovernanceDocs, input: {
49
48
  settleId: string;
50
49
  sessionId: string;
51
50
  now: () => number;
52
51
  toolUseId?: string;
53
- }): void;
52
+ }): Promise<void>;
54
53
  /**
55
54
  * §3.5 (r5-3) — the SYNC lane's unattestable row: a synchronous delegation delivered with a
56
55
  * missing/unknown attestation under the "attested-only" evidence standard. The row is a durable
@@ -59,11 +58,11 @@ export declare function registerDelegationLaunch(controlDir: string, input: {
59
58
  * throw here as "deliver an error instead" (fail-closed — unattested content must not ride into
60
59
  * the transcript of a session whose account could not record the fact).
61
60
  */
62
- export declare function recordSyncUnattestable(controlDir: string, input: {
61
+ export declare function recordSyncUnattestable(docs: MemoryGovernanceDocs, input: {
63
62
  sessionId: string;
64
63
  toolCallId: string;
65
64
  now: () => number;
66
- }): void;
65
+ }): Promise<void>;
67
66
  /**
68
67
  * §3.3 settle — append one observed terminal (idempotent per eventId; the default eventId keys on
69
68
  * (settleId, status) so an at-least-once observer replays into one event). Transition legality is
@@ -71,13 +70,13 @@ export declare function recordSyncUnattestable(controlDir: string, input: {
71
70
  * after `expired`) still lands — as an event row the fold reads as an annotation-grade fact — so
72
71
  * the account never loses an observation (事件不丢), it just doesn't let it rewrite history.
73
72
  */
74
- export declare function settleDelegation(controlDir: string, input: {
73
+ export declare function settleDelegation(docs: MemoryGovernanceDocs, input: {
75
74
  settleId: string;
76
75
  status: "clean" | "external" | "expired" | "void" | "unattestable";
77
76
  now: () => number;
78
77
  eventId?: string;
79
78
  note?: string;
80
- }): void;
79
+ }): Promise<void>;
81
80
  /**
82
81
  * §3.3 host valve — `resolveSettlement(settleId, "clean"|"external", requestId)`. Advisory, same
83
82
  * trust plane as the host API family; `requestId` is the audit anchor and is REQUIRED (a
@@ -85,12 +84,12 @@ export declare function settleDelegation(controlDir: string, input: {
85
84
  * semantics live in the fold: an admin `clean` flips the EFFECTIVE state (releases post-expiry)
86
85
  * but never the history bit, and a LATER observed `external` overrides it (观测证据>admin 裁决).
87
86
  */
88
- export declare function resolveSettlementRecord(controlDir: string, input: {
87
+ export declare function resolveSettlementRecord(docs: MemoryGovernanceDocs, input: {
89
88
  settleId: string;
90
89
  to: "clean" | "external";
91
90
  requestId: string;
92
91
  now: () => number;
93
- }): void;
92
+ }): Promise<void>;
94
93
  /** One settlement's folded (effective) view. */
95
94
  export interface EffectiveSettlement {
96
95
  row: DelegationSettlementRow;
@@ -104,9 +103,9 @@ export interface EffectiveSettlement {
104
103
  terminalEventId?: string;
105
104
  }
106
105
  /** Lock-less folded read of the whole ledger (journal-aware, fail-closed on corruption). */
107
- export declare function effectiveSettlements(controlDir: string): EffectiveSettlement[];
106
+ export declare function effectiveSettlements(docs: MemoryGovernanceDocs): Promise<EffectiveSettlement[]>;
108
107
  /** One session's folded rows (the harvest classifier's input). */
109
- export declare function sessionSettlements(controlDir: string, sessionId: string): EffectiveSettlement[];
108
+ export declare function sessionSettlements(docs: MemoryGovernanceDocs, sessionId: string): Promise<EffectiveSettlement[]>;
110
109
  /**
111
110
  * §3.1 — the session exposure classifier over the settlement account (the durable pollution marker
112
111
  * is the OTHER input; the caller ORs them). `exposed` ⇔ any {external, unattestable, expired}
@@ -123,10 +122,10 @@ export declare function classifySessionSettlements(rows: readonly EffectiveSettl
123
122
  * §3.3-4 — expire overdue pending rows (reconciliation's first leg). Every expiry is an event
124
123
  * (idempotent by (settleId, "expired") key); returns the settleIds newly expired this pass.
125
124
  */
126
- export declare function expireOverdueSettlements(controlDir: string, input: {
125
+ export declare function expireOverdueSettlements(docs: MemoryGovernanceDocs, input: {
127
126
  timeoutMs: number;
128
127
  now: () => number;
129
- }): string[];
128
+ }): Promise<string[]>;
130
129
  /**
131
130
  * §3.3-2 — replay the EXTERNAL rows' side effects (账先落、副作用可重放): ensure the durable
132
131
  * pollution marker is in place (wx, first-write-wins) and the retroaction challenge sweep has
@@ -136,14 +135,13 @@ export declare function expireOverdueSettlements(controlDir: string, input: {
136
135
  * `carry` scopes the sweep domain exactly like the engine's own sweeps (marked rows carry their
137
136
  * account under "carry"; the "off" width challenges everything).
138
137
  */
139
- export declare function replayExternalSettlementEffects(controlDir: string, input: {
138
+ export declare function replayExternalSettlementEffects(docs: MemoryGovernanceDocs, controlDir: string, input: {
140
139
  carry: boolean;
141
140
  now: () => number;
142
- }): Array<{
141
+ }): Promise<Array<{
143
142
  settleId: string;
144
143
  sessionId: string;
145
- }>;
146
- export declare const SESSION_ACCOUNTS_FILE = "session-accounts.json";
144
+ }>>;
147
145
  /** One member of the sticky set: the ledger form `(scope, rel)` — `rel` relative to the scope's
148
146
  * home, `/`-separated. Location-free, so a home move never re-keys the membership. */
149
147
  export interface UnattributedMember {
@@ -183,11 +181,14 @@ export interface SessionAccountRow {
183
181
  }
184
182
  /** The one-time v1 key-form conversions of the three engine sidecars, in one call (each in its own
185
183
  * lock, each idempotent). The layout adoption runs this before any later scope registration can
186
- * change what a v1 key's first segment names. */
184
+ * 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. */
187
188
  export declare function convertV1SidecarKeys(controlDir: string): void;
188
189
  /** The dangling-trigger read: open rows (and unadjudicated closes) belonging to OTHER sessions.
189
190
  * These are what arm the unattributed residue classification at a session's materialize. */
190
- export declare function foreignDanglingSessionAccounts(controlDir: string, selfSessionId: string): SessionAccountRow[];
191
+ export declare function foreignDanglingSessionAccounts(docs: MemoryGovernanceDocs, controlDir: string, selfSessionId: string): Promise<SessionAccountRow[]>;
191
192
  /** The live writers of the store's layers, as the account knows them: every row other than the one
192
193
  * held by `selfLeg` (the asking mount's own leg — another leg of the same session is another
193
194
  * writer) whose session's leg has not ended (no `terminatedAt` — running, or ended without
@@ -196,20 +197,20 @@ export declare function foreignDanglingSessionAccounts(controlDir: string, selfS
196
197
  * whether the leg ended) reads as before: live while never closed, counted in `unscoped` — a
197
198
  * writer of an unknown layer. Sessions that open no row (no session id, provenance "off", an
198
199
  * adoption-restricted mount) are not visible here. */
199
- export declare function openLayerWriters(controlDir: string, selfLeg: string | undefined): {
200
+ export declare function openLayerWriters(docs: MemoryGovernanceDocs, controlDir: string, selfLeg: string | undefined): Promise<{
200
201
  scopes: Set<string>;
201
202
  unscoped: number;
202
- };
203
+ }>;
203
204
  /** The leg that holds `sessionId`'s account row (undefined ⇔ no row, or a row without one). */
204
- export declare function sessionAccountLeg(controlDir: string, sessionId: string): string | undefined;
205
+ export declare function sessionAccountLeg(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<string | undefined>;
205
206
  /** The write scope `sessionId`'s account row records — the scope its newest account-opening mount wrote
206
207
  * under (the value that mount's handle carries as `writeScope`), whether that leg is still live or has
207
208
  * ended. Undefined ⇔ no row, a row written before the field, or a v1 ledger (whose rows predate it —
208
209
  * answered without the conversion, so this read writes nothing). Throws on a corrupt ledger. */
209
- export declare function sessionAccountWriteHome(controlDir: string, sessionId: string): {
210
+ export declare function sessionAccountWriteHome(docs: MemoryGovernanceDocs, sessionId: string): Promise<{
210
211
  writeScope: string;
211
212
  openedAt: number;
212
- } | undefined;
213
+ } | undefined>;
213
214
  /** The membership question the harvest asks per file: is `(scope, rel)` in the session's sticky
214
215
  * set? A session carrying members the conversion could not attribute answers yes for every seat. */
215
216
  export interface SessionUnattributedSet {
@@ -220,15 +221,15 @@ export interface SessionUnattributedSet {
220
221
  export declare function emptyUnattributedSet(): SessionUnattributedSet;
221
222
  /** Open (or re-open, on a same-session resume) the session's account row, persisting the sticky
222
223
  * unattributed classification frozen at THIS materialize. */
223
- export declare function openSessionAccount(controlDir: string, input: {
224
+ export declare function openSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
224
225
  sessionId: string;
225
226
  now: () => number;
226
227
  unattributed: readonly UnattributedMember[];
227
228
  writeScope?: string;
228
229
  leg?: string;
229
- }): void;
230
+ }): Promise<void>;
230
231
  /** The current session's sticky unattributed set (the harvest's residue-arm input). */
231
- export declare function sessionUnattributedSet(controlDir: string, sessionId: string): SessionUnattributedSet;
232
+ export declare function sessionUnattributedSet(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<SessionUnattributedSet>;
232
233
  /** Close the session's account row — called ONLY after a FULL-domain harvest (zero BUDGET-deferred
233
234
  * files, i.e. `HarvestReport.degraded` absent): a partial harvest's close would launder the deferred
234
235
  * residue window (§3.6 序则②). A normal full close also clears every standing `unadjudicated` flag
@@ -243,30 +244,30 @@ export declare function sessionUnattributedSet(controlDir: string, sessionId: st
243
244
  * Returns what happened ({@link SessionAccountWrite}): `"absent"` (a session that never opened an
244
245
  * account — e.g. an adoption-restricted materialize — has no close, and the caller's disclosure
245
246
  * must not claim one), or `"stale"` when `leg` names a mount that no longer holds the row. */
246
- export declare function closeSessionAccount(controlDir: string, input: {
247
+ export declare function closeSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
247
248
  sessionId: string;
248
249
  now: () => number;
249
250
  leg?: string;
250
- }): SessionAccountWrite;
251
+ }): Promise<SessionAccountWrite>;
251
252
  /** What a close / leg end did: wrote the row, found none, or found the row held by ANOTHER leg (the
252
253
  * caller's leg is over — a resume re-opened the row — so nothing was written). */
253
254
  export type SessionAccountWrite = "written" | "absent" | "stale";
254
255
  /** Record that the session's leg ended ({@link SessionAccountRow.terminatedAt}). Touches nothing
255
256
  * else — `closedAt` stays whatever the harvests made it. `leg` (the caller's mount) must hold the
256
257
  * row: a leg that is over does not end the one that re-opened it. */
257
- export declare function terminateSessionAccount(controlDir: string, input: {
258
+ export declare function terminateSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
258
259
  sessionId: string;
259
260
  now: () => number;
260
261
  leg?: string;
261
- }): SessionAccountWrite;
262
+ }): Promise<SessionAccountWrite>;
262
263
  /** The host valve for a dangling row (advisory; §3.6 — dangling rows never auto-expire). The
263
264
  * close is `closed-unadjudicated` (r7-3): it stops the row dangling but the residue arm keeps
264
265
  * firing until a full-domain harvest closes normally. `requestId` required (audit, #123). */
265
- export declare function resolveSessionAccountRecord(controlDir: string, input: {
266
+ export declare function resolveSessionAccountRecord(docs: MemoryGovernanceDocs, controlDir: string, input: {
266
267
  sessionId: string;
267
268
  requestId: string;
268
269
  now: () => number;
269
- }): void;
270
+ }): Promise<void>;
270
271
  export declare const HOLDS_FILE = "holds.json";
271
272
  export declare const HOLD_DIR = "hold";
272
273
  export type HoldStatus = "capturing" | "held" | "released" | "disposed";
@@ -388,6 +389,7 @@ export declare function openInstructionHold(controlDir: string, input: {
388
389
  export declare function reconcileHolds(controlDir: string, input: {
389
390
  homeOf: (scope: string) => string;
390
391
  now: () => number;
392
+ onStranded: (scope: string, line: string) => void;
391
393
  }): void;
392
394
  /** Dispose one held row: custody bytes move to the quarantine directory (host-auditable), the row
393
395
  * records its terminal + quarantineName (from-row-to-bytes addressing survives every terminal). */
@@ -444,4 +446,4 @@ export declare function clearHoldResolution(controlDir: string, input: {
444
446
  export declare function readHoldCustody(controlDir: string, row: HoldRow): string | undefined;
445
447
  /** True ⇔ the session's pollution marker or any non-clean settlement row blocks a clean release
446
448
  * (§4.2-1: any non-clean row in the session's account keeps the hold held/disposed). */
447
- export declare function sessionBlocksCleanRelease(controlDir: string, sessionId: string): boolean;
449
+ export declare function sessionBlocksCleanRelease(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<boolean>;