@sema-agent/core 7.58.0 → 7.59.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 (284) hide show
  1. package/CHANGELOG.md +776 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent.js +33 -34
  10. package/dist/brain/anthropic.js +161 -45
  11. package/dist/brain/errors.d.ts +9 -3
  12. package/dist/brain/errors.js +7 -1
  13. package/dist/brain/failover.js +2 -1
  14. package/dist/brain/open-responses.js +3 -3
  15. package/dist/brain/openai.js +103 -53
  16. package/dist/brain/provider-dialect.d.ts +11 -0
  17. package/dist/brain/provider-dialect.js +5 -2
  18. package/dist/brain/reasoning-request.js +5 -4
  19. package/dist/brain/reasoning.d.ts +19 -0
  20. package/dist/brain/reasoning.js +17 -2
  21. package/dist/brain/request-route.d.ts +4 -1
  22. package/dist/brain/request-route.js +4 -1
  23. package/dist/brain/route-adjudicator.d.ts +84 -18
  24. package/dist/brain/route-adjudicator.js +87 -21
  25. package/dist/brain/route-conformance.js +1 -1
  26. package/dist/brain/stream-engine.js +84 -49
  27. package/dist/brain/stream-shared.d.ts +30 -0
  28. package/dist/brain/stream-shared.js +34 -1
  29. package/dist/brain/timeout.d.ts +62 -5
  30. package/dist/brain/timeout.js +93 -6
  31. package/dist/core/account-row.d.ts +61 -0
  32. package/dist/core/account-row.js +51 -0
  33. package/dist/core/advisor-verdict.d.ts +2 -1
  34. package/dist/core/advisor-verdict.js +1 -1
  35. package/dist/core/allow-entry.d.ts +18 -6
  36. package/dist/core/allow-entry.js +16 -8
  37. package/dist/core/approval-object.d.ts +29 -15
  38. package/dist/core/approval-object.js +47 -19
  39. package/dist/core/auto-compaction.js +1 -1
  40. package/dist/core/background-agent-store.d.ts +16 -3
  41. package/dist/core/checkpoint-requirements.d.ts +13 -1
  42. package/dist/core/checkpoint-requirements.js +3 -1
  43. package/dist/core/checkpoint-store.d.ts +58 -12
  44. package/dist/core/checkpoint-store.js +18 -6
  45. package/dist/core/child-clamp-seats.d.ts +29 -0
  46. package/dist/core/child-clamp-seats.js +56 -1
  47. package/dist/core/compliance.d.ts +2 -2
  48. package/dist/core/compliance.js +1 -1
  49. package/dist/core/effective-path-target.d.ts +8 -2
  50. package/dist/core/effective-path-target.js +8 -3
  51. package/dist/core/engine-notice.d.ts +98 -8
  52. package/dist/core/engine-notice.js +19 -5
  53. package/dist/core/gate-fold.js +1 -1
  54. package/dist/core/gate-lanes.js +8 -4
  55. package/dist/core/gate-outcome.d.ts +32 -3
  56. package/dist/core/gate-outcome.js +19 -1
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +13 -0
  59. package/dist/core/hooks.d.ts +31 -3
  60. package/dist/core/hooks.js +5 -6
  61. package/dist/core/image-admission.d.ts +6 -5
  62. package/dist/core/image-admission.js +18 -14
  63. package/dist/core/locked-config.d.ts +5 -2
  64. package/dist/core/locked-config.js +2 -1
  65. package/dist/core/mailbox-store.d.ts +45 -1
  66. package/dist/core/mailbox-store.js +53 -9
  67. package/dist/core/mcp-failure.d.ts +114 -18
  68. package/dist/core/mcp-failure.js +63 -5
  69. package/dist/core/mcp-server-link.d.ts +22 -1
  70. package/dist/core/mcp-server-link.js +25 -1
  71. package/dist/core/mcp.d.ts +12 -8
  72. package/dist/core/mcp.js +42 -25
  73. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  74. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  75. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  76. package/dist/core/memory-engine/consolidation.js +1 -0
  77. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  78. package/dist/core/memory-engine/distiller.js +2 -2
  79. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  80. package/dist/core/memory-engine/dual-root.js +44 -1
  81. package/dist/core/memory-engine/engine.d.ts +67 -14
  82. package/dist/core/memory-engine/engine.js +384 -212
  83. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  84. package/dist/core/memory-engine/export-bundle.js +23 -4
  85. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  86. package/dist/core/memory-engine/file-backend.js +290 -117
  87. package/dist/core/memory-engine/index.d.ts +1 -1
  88. package/dist/core/memory-engine/layout.d.ts +59 -11
  89. package/dist/core/memory-engine/layout.js +190 -40
  90. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  91. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  92. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  93. package/dist/core/memory-engine/sync-client.js +31 -8
  94. package/dist/core/memory-engine/sync.d.ts +5 -0
  95. package/dist/core/memory-engine/types.d.ts +6 -0
  96. package/dist/core/mods/classic-events.d.ts +5 -1
  97. package/dist/core/mods/kernel/dispatch.js +2 -1
  98. package/dist/core/mods/kernel/events.d.ts +2 -1
  99. package/dist/core/mods/kernel/events.js +2 -2
  100. package/dist/core/mods/kernel/registration.d.ts +4 -0
  101. package/dist/core/mods/kernel/registration.js +3 -0
  102. package/dist/core/mods/stations.d.ts +31 -10
  103. package/dist/core/mods/stations.js +44 -10
  104. package/dist/core/mods/tool-call.js +1 -1
  105. package/dist/core/parent-spec-seat.d.ts +8 -3
  106. package/dist/core/parent-spec-seat.js +2 -0
  107. package/dist/core/park-selfcheck.js +6 -0
  108. package/dist/core/peer-seat.d.ts +70 -8
  109. package/dist/core/peer-seat.js +143 -11
  110. package/dist/core/permission-rule-consent.js +10 -4
  111. package/dist/core/permission-rule-model.d.ts +16 -0
  112. package/dist/core/permission-rule-model.js +1 -1
  113. package/dist/core/present-plan-tool.d.ts +11 -3
  114. package/dist/core/present-plan-tool.js +2 -2
  115. package/dist/core/resume-startup-cause.js +1 -0
  116. package/dist/core/rewrite-rejudge.d.ts +1 -0
  117. package/dist/core/rewrite-rejudge.js +2 -2
  118. package/dist/core/roles.d.ts +34 -2
  119. package/dist/core/roles.js +43 -4
  120. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  121. package/dist/core/runner/announce-once-ledger.js +4 -2
  122. package/dist/core/runner/call-hook-stations.js +2 -2
  123. package/dist/core/runner/contracts.d.ts +20 -16
  124. package/dist/core/runner/credential-origin-seat.js +4 -3
  125. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  126. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  127. package/dist/core/runner/decide-continuation.d.ts +2 -2
  128. package/dist/core/runner/gate-exit.d.ts +12 -4
  129. package/dist/core/runner/gate-exit.js +10 -7
  130. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  131. package/dist/core/runner/image-removed-seat.js +19 -0
  132. package/dist/core/runner/inline-image.js +1 -1
  133. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  134. package/dist/core/runner/park-commit.d.ts +1 -1
  135. package/dist/core/runner/park-commit.js +3 -0
  136. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  137. package/dist/core/runner/prepare-ask-lane.js +2 -1
  138. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -5
  140. package/dist/core/runner/prepare-caps-and-workflow.js +2 -0
  141. package/dist/core/runner/prepare-config-doors.js +2 -0
  142. package/dist/core/runner/prepare-context-lane.js +2 -0
  143. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  144. package/dist/core/runner/prepare-delegation-surface.js +1 -0
  145. package/dist/core/runner/prepare-hands-readface.d.ts +4 -0
  146. package/dist/core/runner/prepare-hands-readface.js +5 -0
  147. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  148. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  149. package/dist/core/runner/prepare-memory.js +10 -17
  150. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  151. package/dist/core/runner/prepare-park-ask.js +2 -1
  152. package/dist/core/runner/prepare-policy-chain.d.ts +3 -3
  153. package/dist/core/runner/prepare-policy-chain.js +16 -13
  154. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  155. package/dist/core/runner/prepare-project-context.js +2 -2
  156. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  157. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  158. package/dist/core/runner/prepare-protocol-tools.js +9 -1
  159. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  160. package/dist/core/runner/prepare-run-refs.js +4 -1
  161. package/dist/core/runner/prepare-task.js +4 -2
  162. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -1
  163. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  164. package/dist/core/runner/reply-pricing.d.ts +30 -0
  165. package/dist/core/runner/reply-pricing.js +19 -0
  166. package/dist/core/runner/resume-admission.js +4 -2
  167. package/dist/core/runner/resume-apply.js +6 -1
  168. package/dist/core/runner/resume-policy-outcome.js +5 -5
  169. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  170. package/dist/core/runner/role-seat-defaulted.js +40 -0
  171. package/dist/core/runner/run-brain-sinks.js +2 -0
  172. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  173. package/dist/core/runner/run-identity-wiring.js +5 -4
  174. package/dist/core/runner/run-leg.d.ts +2 -0
  175. package/dist/core/runner/run-leg.js +37 -28
  176. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  177. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  178. package/dist/core/runner/run-terminal-adoption.js +9 -3
  179. package/dist/core/runner/run-turn-boundary.js +77 -70
  180. package/dist/core/runner/runtask.d.ts +1 -1
  181. package/dist/core/runner/runtask.js +2 -2
  182. package/dist/core/runner/side-call-account.d.ts +1 -1
  183. package/dist/core/runner/side-call-account.js +3 -18
  184. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  185. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  186. package/dist/core/runner/tool-end-body.js +2 -2
  187. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  188. package/dist/core/runner/tool-occurrence.js +2 -2
  189. package/dist/core/runner/turn-attachments.d.ts +26 -22
  190. package/dist/core/runner/turn-attachments.js +24 -26
  191. package/dist/core/runner-deps.d.ts +1 -1
  192. package/dist/core/secret-env.d.ts +32 -2
  193. package/dist/core/secret-env.js +65 -3
  194. package/dist/core/sensitive-path-policy.js +3 -3
  195. package/dist/core/session-policy-store.d.ts +3 -1
  196. package/dist/core/session-policy-store.js +13 -9
  197. package/dist/core/session-store.d.ts +2 -5
  198. package/dist/core/side-query.d.ts +11 -1
  199. package/dist/core/side-query.js +9 -0
  200. package/dist/core/skill-grant-binding.d.ts +31 -2
  201. package/dist/core/skill-grant-binding.js +31 -1
  202. package/dist/core/skill-grant.d.ts +8 -5
  203. package/dist/core/skill-grant.js +6 -6
  204. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  205. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  206. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  207. package/dist/core/synthetic-read-verdict.js +2 -1
  208. package/dist/core/task-event.d.ts +32 -8
  209. package/dist/core/task-notification.js +16 -10
  210. package/dist/core/task-registry-agent.js +1 -0
  211. package/dist/core/task-registry-shared.d.ts +5 -0
  212. package/dist/core/task-spec.d.ts +12 -1
  213. package/dist/core/terminal-cause.d.ts +10 -0
  214. package/dist/core/tool-check-reading.d.ts +1 -0
  215. package/dist/core/tool-check-reading.js +3 -3
  216. package/dist/core/tool-policy.d.ts +16 -0
  217. package/dist/core/tool-roster.d.ts +112 -5
  218. package/dist/core/tool-roster.js +42 -1
  219. package/dist/core/tool-spec.d.ts +3 -1
  220. package/dist/core/types.d.ts +2 -2
  221. package/dist/core/types.js +1 -1
  222. package/dist/core/user-attachment.js +1 -1
  223. package/dist/core/wiring-manifest.d.ts +6 -3
  224. package/dist/engine/compaction/compaction.js +29 -3
  225. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  226. package/dist/engine/execution-env/node-execution-env.js +9 -12
  227. package/dist/engine/harness/agent-harness.d.ts +25 -2
  228. package/dist/engine/harness/agent-harness.js +41 -12
  229. package/dist/engine/harness/messages.d.ts +3 -1
  230. package/dist/engine/harness/messages.js +3 -2
  231. package/dist/engine/harness/types.d.ts +8 -0
  232. package/dist/engine/llm/rejected-images.d.ts +46 -0
  233. package/dist/engine/llm/rejected-images.js +54 -0
  234. package/dist/engine/llm/tool-turns.d.ts +2 -1
  235. package/dist/engine/llm/types.d.ts +18 -7
  236. package/dist/engine/loop/agent-loop.d.ts +8 -0
  237. package/dist/engine/loop/agent-loop.js +52 -15
  238. package/dist/engine/loop/types.d.ts +3 -1
  239. package/dist/engine/session/path-to-root.d.ts +38 -0
  240. package/dist/engine/session/path-to-root.js +39 -0
  241. package/dist/engine/session/storage-base.js +4 -21
  242. package/dist/index.d.ts +16 -10
  243. package/dist/index.js +11 -7
  244. package/dist/internal/harness-types.d.ts +1 -1
  245. package/dist/internal/harness.d.ts +1 -0
  246. package/dist/internal/llm.d.ts +1 -0
  247. package/dist/orchestration/workflow-observe.d.ts +17 -1
  248. package/dist/orchestration/workflow-observe.js +20 -0
  249. package/dist/orchestration/workflow-types.d.ts +32 -7
  250. package/dist/orchestration/workflow.js +739 -489
  251. package/dist/shell/counting-pass.d.ts +50 -0
  252. package/dist/shell/counting-pass.js +502 -0
  253. package/dist/shell/lex.d.ts +4 -2
  254. package/dist/shell/lex.js +93 -34
  255. package/dist/shell/shell-words.d.ts +1 -1
  256. package/dist/shell/shell-words.js +7 -6
  257. package/dist/stores/file/mailbox-store.js +6 -10
  258. package/dist/tools/fs/fs-bash.d.ts +6 -0
  259. package/dist/tools/fs/fs-bash.js +6 -3
  260. package/dist/tools/fs/index.js +6 -2
  261. package/dist/tools/fs/program-read-model.d.ts +13 -0
  262. package/dist/tools/fs/program-read-model.js +15 -0
  263. package/dist/tools/fs/program-read-model.rows.js +1 -1
  264. package/dist/tools/fs/read-deny.d.ts +13 -10
  265. package/dist/tools/fs/read-deny.js +25 -5
  266. package/dist/tools/fs/read-floor.d.ts +19 -0
  267. package/dist/tools/fs/read-floor.js +23 -0
  268. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  269. package/dist/tools/fs/shell-read-check.js +2 -1
  270. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  271. package/dist/tools/fs/shell-read-judge.js +10 -6
  272. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  273. package/dist/tools/fs/shell-read-plan.js +22 -15
  274. package/dist/tools/fs/shell-read-start.js +1 -0
  275. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  276. package/dist/tools/fs/shell-reentry-text.js +25 -3
  277. package/dist/tools/monitor.d.ts +4 -0
  278. package/dist/tools/monitor.js +2 -0
  279. package/package.json +3 -2
  280. package/test/export-surface.snapshot.json +87 -1
  281. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  282. package/wire-changes/core@7.59.0.json +2459 -0
  283. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  284. package/wire-changes/primitives@7.59.0.json +29 -0
@@ -2,7 +2,7 @@ export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION
2
2
  export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_INDEX_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, type MemoryGetDetails, type MemoryIndexDetails, type MemoryIndexRow, type CleanMemoryIndexRow, type ExposedMemoryIndexRow, } from "./tools.js";
3
3
  export { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_RECALL_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow, } from "./provenance-wording.js";
4
4
  export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
5
- export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryExportSnapshot, } from "./file-backend.js";
5
+ export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureCarrierAnswer, type ErasureCarrierClass, type ErasureCountAnswer, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryExportSnapshot, } from "./file-backend.js";
6
6
  export { computeBundleSectionHashes, computeMemoryBundleHash, memoryBundleInvalid, type MemoryExportBundle, type MemoryImportReport, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, } from "./export-bundle.js";
7
7
  export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, layoutNeedsAdoption, adoptRootScopeLayout, v1MemoryPathKeyResolver, unresolvedProjectionDebts, scanFuseKey, type AdoptRootScopeLayoutOptions, type ScopeRegistryShape, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAppendResult, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, SESSION_CAPTURE_OPTOUT_DIR, markSessionCaptureOptOut, readSessionCaptureOptOut, listSessionCaptureOptOut, fileSessionCaptureRecordStore, type SessionCaptureOptOutRecord, type SessionCaptureOptOutMarkOutcome, type SessionCaptureRecordStore, } from "./layout.js";
8
8
  export { readV2HeaderHints, isInstructionEntry, type V2HeaderHints } from "./header-hints.js";
@@ -433,6 +433,32 @@ export interface StoreRootReanchor {
433
433
  /** The control plane the anchor lives in. */
434
434
  readonly controlDir: string;
435
435
  }
436
+ /**
437
+ * The TRANSIENT sweep record: per erasure requestId, the projection paths it deleted, kept in the
438
+ * control plane only until the derived-index sweep has cleared every MEMORY.md line naming them (the
439
+ * paths spell slugs, so the durable chain and the attestation never hold them). Written from the
440
+ * request's journal right after its commit point, and by recovery from a journal it rolls forward;
441
+ * swept and settled by `MemoryEngine.eraseMemoryEntries` under this file's lock. A request with a
442
+ * record is `partial` on `indexLine`. A row's paths are relative to the store root
443
+ * ({@link erasureSweepRecordPathOf}) and are read at the root the store is opened at now
444
+ * ({@link erasureSweepOwedAt}), so a row binds no root and follows a re-anchor. A record that cannot
445
+ * be read or written, or a row path that is absolute or leaves the root, refuses like every strict
446
+ * control-plane file (fail-closed).
447
+ */
448
+ export declare const ERASURE_SWEEP_RECORD_FILE = "erasure-sweeps.json";
449
+ export declare const ERASURE_SWEEP_RECORD_WHAT = "memory erasure sweep record";
450
+ export interface ErasureSweepRecordFile {
451
+ v: 1;
452
+ requests: Record<string, string[]>;
453
+ }
454
+ export declare function coerceErasureSweepRecord(raw: unknown): ErasureSweepRecordFile;
455
+ /** The row path of `target`, a projection `requestId` deleted under `storeRoot`: relative to the root's
456
+ * physical form, the target placed as the act gate places a delete ({@link landsOutsideStore}: its directory
457
+ * where it lands, the final component as spelled) — so every spelling of one root records one row. A target
458
+ * that does not land under the root is refused (fail-closed; the text names no path — paths spell slugs). */
459
+ export declare function erasureSweepRecordPathOf(storeRoot: string, requestId: string, target: string): string;
460
+ /** The paths `requestId`'s row owes, at the root the store is opened at now (`[]` without a row). */
461
+ export declare function erasureSweepOwedAt(file: ErasureSweepRecordFile, storeRoot: string, requestId: string): string[];
436
462
  /**
437
463
  * The ONE way a recorded root anchor changes: point it at where `dir` resolves now — a store moved on
438
464
  * purpose, or an anchor that is damaged. `opts.controlDir` names the store's control plane exactly as its
@@ -442,9 +468,10 @@ export interface StoreRootReanchor {
442
468
  * mistaken `controlDir` would otherwise record an anchor no opener reads. Moves nothing and says nothing
443
469
  * about whether the directory holds the same store. A re-anchor is a transaction of the store: it holds the
444
470
  * store's transaction lock ({@link acquireStoreTxnLock}; a commit in progress is waited for, never crossed) and
445
- * is refused while a committed transaction is pending recovery (its journal names paths under the recorded
446
- * root: replayed there first, never carried over). Every live holder judges against the new anchor at its
447
- * next face. Discloses `memory.root_reanchored` on `opts.onIncident`.
471
+ * is refused while the control plane owes anything at the recorded root ({@link rootBoundObligationOf}: a
472
+ * committed transaction pending recovery — its journal names paths under the recorded root and is replayed
473
+ * there first, never carried over). Every live holder judges against the new anchor at its next face.
474
+ * Discloses `memory.root_reanchored` on `opts.onIncident`.
448
475
  */
449
476
  export declare function reanchorMemoryStoreRoot(dir: string, opts?: {
450
477
  controlDir?: string;
@@ -598,9 +625,12 @@ export declare function dropStagingSecondNames(seat: string, opened: {
598
625
  */
599
626
  export declare function restoreContainedBaseline(path: string, committed: string, leftOnPlane: string | undefined): "written" | "kept" | "failed";
600
627
  export declare function quarantineAndTombstone(path: string, content: string, quarantineDir: string, now: () => number): QuarantineOutcome;
601
- /** S2-B — the queued memory-change announcements (control plane; drained at session-first inject). */
628
+ /** S2-B — the queued memory-change announcements (control plane; drained at session-first inject).
629
+ * One file, one bounded queue PER SCOPE inside it (see {@link enqueueMemoryAnnouncement}). */
602
630
  export declare const ANNOUNCEMENTS_FILE = "announcements.json";
603
- /** S2-B — bounded queue: overflow FOLDS (oldest dropped, counted) instead of growing unbounded. */
631
+ /** S2-B — bounded queue, per scope: overflow FOLDS (oldest dropped, counted) instead of growing
632
+ * unbounded. The bound, the fold count and the standing-condition sweep are all one scope's —
633
+ * a scope that floods its own queue never pushes another scope's notices out. */
604
634
  export declare const MEMORY_ANNOUNCEMENTS_MAX = 20;
605
635
  /** S2-C — per-file write-rejection counts (the beforeWrite silent-reject fuse; O-F9/C-F7: scoped
606
636
  * state in `.engine/`, so the count survives suspend/resume and backend re-construction). */
@@ -640,10 +670,17 @@ export declare function acquireSidecarLock(lockDir: string, opts?: SidecarLockOp
640
670
  * locked update) keeps the leniency, because its token writes are best-effort and an absent owner
641
671
  * file there is the documented pre-token degraded shape, not evidence of a steal. */
642
672
  export declare function assertSidecarLockOwnership(lockDir: string, token: string, what: string, mode?: "strict" | "lenient"): void;
643
- interface AnnouncementsRecord {
644
- /** How many announcements were dropped by the bounded-queue fold (disclosed at render). */
673
+ /** What a drain or a peek answers for the scopes it was asked about. */
674
+ export interface DrainedMemoryAnnouncements {
675
+ /** The asked scopes' fold counts, summed. */
645
676
  folded: number;
677
+ /** The asked scopes' announcements, in enqueue-time order. */
646
678
  queue: MemoryAnnouncement[];
679
+ /** Notices found in the queue file WITHOUT a scope (the pre-per-scope file form, or a hand-written
680
+ * line): they belong to no queue, so no session ever reads them — they are discarded on the first
681
+ * locked rewrite and only their number is kept, for the operator face. A drain hands the number
682
+ * over once and resets it; a peek reports it without resetting. */
683
+ unscopedDiscarded: number;
647
684
  }
648
685
  /**
649
686
  * S2-B — enqueue one announcement (journaled + locked; bounded with overflow folding).
@@ -670,10 +707,21 @@ interface AnnouncementsRecord {
670
707
  export declare function enqueueMemoryAnnouncement(controlDir: string, ann: MemoryAnnouncement, opts?: {
671
708
  supersedesPrefix?: string;
672
709
  }): void;
673
- /** S2-B — drain the queue (session-first inject, 时机①). Returns what was queued and resets it. */
674
- export declare function drainMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
675
- /** Test/observability peek (journal-aware, non-destructive). */
676
- export declare function peekMemoryAnnouncements(controlDir: string): AnnouncementsRecord;
710
+ /**
711
+ * S2-B — drain the queues of `scopes` (session-first inject, 时机①): returns what those scopes had
712
+ * queued and resets exactly them. Every other scope's queue is left as it was, for the session that
713
+ * mounts it — the drain that empties a queue is a reader of that queue, never a bystander.
714
+ */
715
+ export declare function drainMemoryAnnouncements(controlDir: string, scopes: readonly string[]): DrainedMemoryAnnouncements;
716
+ /** Test/observability peek of `scopes` (journal-aware, non-destructive). */
717
+ export declare function peekMemoryAnnouncements(controlDir: string, scopes: readonly string[]): DrainedMemoryAnnouncements;
718
+ /**
719
+ * Move every scope's queue from one control plane to another (a mount-key switch re-homes the control
720
+ * plane, and the notices queued under the old key must not be orphaned). Each line keeps its scope; the
721
+ * destination's per-scope bounds apply as each line lands. The only whole-file read there is: it hands
722
+ * lines to the same scopes' queues elsewhere, never to a reader.
723
+ */
724
+ export declare function transferMemoryAnnouncements(fromControlDir: string, toControlDir: string): void;
677
725
  /** The fuse key for a memory file: the ledger form `(scope, rel)` (`rel` relative to the scope's
678
726
  * home, `/`-separated) — location-free, so a home move never re-keys a count. */
679
727
  export declare function scanFuseKey(scope: string, rel: string): string;
@@ -2,7 +2,7 @@ import { closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSyn
2
2
  const { O_WRONLY, O_RDONLY, O_CREAT, O_NOFOLLOW, O_NONBLOCK, O_EXCL } = fsConstants;
3
3
  import { homedir } from "node:os";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
- import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
5
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
6
6
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
7
7
  import { physicalPathOf, physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
8
8
  import { thrownLabel, thrownText } from "../thrown-value.js";
@@ -1063,6 +1063,40 @@ function reanchorDestination(dir) {
1063
1063
  throw reanchorRefusal(`the store root ${JSON.stringify(dir)} resolves to ${to}, which is not a directory`);
1064
1064
  return to;
1065
1065
  }
1066
+ export const ERASURE_SWEEP_RECORD_FILE = "erasure-sweeps.json";
1067
+ export const ERASURE_SWEEP_RECORD_WHAT = "memory erasure sweep record";
1068
+ function isStoreRelativePath(p) {
1069
+ return p.length > 0 && !isAbsolute(p) && !p.split(sep === "/" ? "/" : /[\\/]/).includes("..");
1070
+ }
1071
+ export function coerceErasureSweepRecord(raw) {
1072
+ if (raw === undefined)
1073
+ return { v: 1, requests: Object.create(null) };
1074
+ const requests = raw?.requests;
1075
+ if (typeof raw !== "object" || raw === null || raw.v !== 1 || typeof requests !== "object" || requests === null || Array.isArray(requests)) {
1076
+ throw new ControlPlaneCorruptError(`${ERASURE_SWEEP_RECORD_WHAT} has an unrecognized shape (fail-closed sidecar)`);
1077
+ }
1078
+ const out = Object.create(null);
1079
+ for (const [req, paths] of Object.entries(requests)) {
1080
+ if (!Array.isArray(paths) || paths.some((p) => typeof p !== "string" || !isStoreRelativePath(p)))
1081
+ throw new ControlPlaneCorruptError(`${ERASURE_SWEEP_RECORD_WHAT} row for request ${JSON.stringify(req.slice(0, 80))} is malformed — a row names paths relative to the store root (fail-closed sidecar)`);
1082
+ out[req] = paths;
1083
+ }
1084
+ return { v: 1, requests: out };
1085
+ }
1086
+ export function erasureSweepRecordPathOf(storeRoot, requestId, target) {
1087
+ const rel = join(relative(landingPathOf(storeRoot), landingPathOf(dirname(target))), basename(target));
1088
+ if (!isStoreRelativePath(rel))
1089
+ throw new ControlPlaneCorruptError(`${ERASURE_SWEEP_RECORD_WHAT}: a path request ${JSON.stringify(requestId.slice(0, 80))} deleted is not under the store root ${storeRoot} — a row names paths relative to the root (fail-closed sidecar)`);
1090
+ return rel;
1091
+ }
1092
+ export function erasureSweepOwedAt(file, storeRoot, requestId) {
1093
+ return (file.requests[requestId] ?? []).map((rel) => join(storeRoot, rel));
1094
+ }
1095
+ function rootBoundObligationOf(controlDir) {
1096
+ if (lstatOrAbsent(join(controlDir, STORE_JOURNAL_FILE)) === undefined)
1097
+ return undefined;
1098
+ return { owed: "a committed transaction is still pending recovery", remedy: "open it once so the journal replays" };
1099
+ }
1066
1100
  function reanchorRefusal(sentence) {
1067
1101
  const e = new Error(`reanchorMemoryStoreRoot: ${sentence}`);
1068
1102
  e.code = "config.memory_reanchor";
@@ -1092,8 +1126,9 @@ export async function reanchorMemoryStoreRoot(dir, opts = {}) {
1092
1126
  catch {
1093
1127
  throw reanchorRefusal(`the store's transaction lock was lost while re-anchoring (held past its stale line and taken by another writer) — nothing changed; retry (control plane ${controlDir})`);
1094
1128
  }
1095
- if (lstatOrAbsent(join(controlDir, STORE_JOURNAL_FILE)) !== undefined) {
1096
- throw reanchorRefusal(`a committed transaction is still pending recovery at the recorded root — put the store back at ${from ?? "the root it was last opened at"}, open it once so the journal replays, then re-anchor (control plane ${controlDir})`);
1129
+ const obligation = rootBoundObligationOf(controlDir);
1130
+ if (obligation !== undefined) {
1131
+ throw reanchorRefusal(`${obligation.owed} at the recorded root — put the store back at ${from ?? "the root it was last opened at"}, ${obligation.remedy}, then re-anchor (control plane ${controlDir})`);
1097
1132
  }
1098
1133
  let still;
1099
1134
  try {
@@ -1468,75 +1503,190 @@ function readSidecarJson(controlDir, fileName) {
1468
1503
  }
1469
1504
  return undefined;
1470
1505
  }
1506
+ const ANNOUNCEMENTS_FORM = 2;
1507
+ function emptyAnnouncements() {
1508
+ return { scopes: Object.create(null), unscopedDiscarded: 0 };
1509
+ }
1510
+ function wholeCount(v) {
1511
+ return typeof v === "number" && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0;
1512
+ }
1513
+ function coerceAnnouncement(e, scope) {
1514
+ const a = e;
1515
+ if (!a ||
1516
+ typeof a !== "object" ||
1517
+ (a.kind !== "gate" && a.kind !== "external") ||
1518
+ typeof a.at !== "number" ||
1519
+ !Array.isArray(a.items) ||
1520
+ !a.items.every((i) => typeof i === "string") ||
1521
+ a.scope !== scope) {
1522
+ return undefined;
1523
+ }
1524
+ return {
1525
+ kind: a.kind,
1526
+ scope,
1527
+ at: a.at,
1528
+ ...(typeof a.sessionId === "string" ? { sessionId: a.sessionId } : {}),
1529
+ ...(typeof a.reportId === "string" ? { reportId: a.reportId } : {}),
1530
+ items: mintedItems(a.items),
1531
+ };
1532
+ }
1471
1533
  const mintedItems = (items) => items.map((item) => egressText("same-principal", item));
1472
1534
  function coerceAnnouncements(raw) {
1473
- const rec = { folded: 0, queue: [] };
1535
+ const rec = emptyAnnouncements();
1474
1536
  if (!raw || typeof raw !== "object" || Array.isArray(raw))
1475
1537
  return rec;
1476
1538
  const r = raw;
1477
- if (typeof r.folded === "number" && Number.isFinite(r.folded) && r.folded > 0)
1478
- rec.folded = Math.floor(r.folded);
1479
- if (Array.isArray(r.queue)) {
1480
- for (const e of r.queue) {
1481
- const a = e;
1482
- if (a &&
1483
- typeof a === "object" &&
1484
- (a.kind === "gate" || a.kind === "external") &&
1485
- typeof a.at === "number" &&
1486
- Array.isArray(a.items) &&
1487
- a.items.every((i) => typeof i === "string")) {
1488
- rec.queue.push({
1489
- kind: a.kind,
1490
- at: a.at,
1491
- ...(typeof a.sessionId === "string" ? { sessionId: a.sessionId } : {}),
1492
- ...(typeof a.reportId === "string" ? { reportId: a.reportId } : {}),
1493
- items: mintedItems(a.items),
1494
- });
1539
+ if (r.v !== ANNOUNCEMENTS_FORM) {
1540
+ rec.unscopedDiscarded = (Array.isArray(r.queue) ? r.queue.length : 0) + wholeCount(r.folded);
1541
+ return rec;
1542
+ }
1543
+ rec.unscopedDiscarded = wholeCount(r.unscopedDiscarded);
1544
+ if (!r.scopes || typeof r.scopes !== "object" || Array.isArray(r.scopes))
1545
+ return rec;
1546
+ for (const scope of Object.keys(r.scopes)) {
1547
+ const q = r.scopes[scope];
1548
+ if (scope === "" || !q || typeof q !== "object")
1549
+ continue;
1550
+ const queue = [];
1551
+ if (Array.isArray(q.queue)) {
1552
+ for (const e of q.queue) {
1553
+ const a = coerceAnnouncement(e, scope);
1554
+ if (a !== undefined)
1555
+ queue.push(a);
1556
+ else
1557
+ rec.unscopedDiscarded += 1;
1495
1558
  }
1496
1559
  }
1560
+ const folded = wholeCount(q.folded);
1561
+ if (queue.length > 0 || folded > 0)
1562
+ rec.scopes[scope] = { folded, queue };
1497
1563
  }
1498
1564
  return rec;
1499
1565
  }
1566
+ function persistedAnnouncements(rec) {
1567
+ return { v: ANNOUNCEMENTS_FORM, scopes: rec.scopes, ...(rec.unscopedDiscarded > 0 ? { unscopedDiscarded: rec.unscopedDiscarded } : {}) };
1568
+ }
1569
+ function askedScopes(scopes, verb) {
1570
+ if (!Array.isArray(scopes) || !scopes.every((s) => typeof s === "string" && s !== "")) {
1571
+ throw new TypeError(`${verb}: scopes must be an array of non-empty scope keys — the queue is read per scope`);
1572
+ }
1573
+ return [...new Set(scopes)];
1574
+ }
1575
+ function mergeScopeQueues(rec, scopes) {
1576
+ let folded = 0;
1577
+ const lines = [];
1578
+ scopes.forEach((scope, s) => {
1579
+ const q = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : undefined;
1580
+ if (q === undefined)
1581
+ return;
1582
+ folded += q.folded;
1583
+ q.queue.forEach((a, i) => lines.push({ a, s, i }));
1584
+ });
1585
+ lines.sort((x, y) => x.a.at - y.a.at || x.s - y.s || x.i - y.i);
1586
+ return { folded, queue: lines.map((l) => l.a) };
1587
+ }
1500
1588
  export function enqueueMemoryAnnouncement(controlDir, ann, opts) {
1589
+ if (typeof ann.scope !== "string" || ann.scope === "") {
1590
+ throw new TypeError("enqueueMemoryAnnouncement: announcement.scope is required — each notice is filed under the one scope it reports on");
1591
+ }
1592
+ const scope = ann.scope;
1501
1593
  ann = { ...ann, items: mintedItems(ann.items) };
1502
1594
  const family = opts?.supersedesPrefix === undefined ? undefined : egressText("same-principal", opts.supersedesPrefix);
1503
1595
  if (ann.items.length === 0 && family === undefined)
1504
1596
  return;
1505
1597
  lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
1506
1598
  const rec = coerceAnnouncements(current);
1599
+ const own = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : { folded: 0, queue: [] };
1507
1600
  if (family !== undefined) {
1508
- const queued = rec.queue.flatMap((a) => a.items.filter((i) => i.startsWith(family)));
1601
+ const queued = own.queue.flatMap((a) => a.items.filter((i) => i.startsWith(family)));
1509
1602
  if (queued.length === ann.items.length && ann.items.every((i) => queued.includes(i)))
1510
1603
  return undefined;
1511
- for (const a of rec.queue)
1604
+ for (const a of own.queue)
1512
1605
  a.items = a.items.filter((i) => !i.startsWith(family));
1513
- rec.queue = rec.queue.filter((a) => a.items.length > 0);
1514
- if (ann.items.length === 0)
1515
- return rec;
1606
+ own.queue = own.queue.filter((a) => a.items.length > 0);
1516
1607
  }
1517
- rec.queue.push(ann);
1518
- if (rec.queue.length > MEMORY_ANNOUNCEMENTS_MAX) {
1519
- rec.folded += rec.queue.length - MEMORY_ANNOUNCEMENTS_MAX;
1520
- rec.queue = rec.queue.slice(-MEMORY_ANNOUNCEMENTS_MAX);
1608
+ if (ann.items.length > 0)
1609
+ own.queue.push({ ...ann, scope });
1610
+ if (own.queue.length > MEMORY_ANNOUNCEMENTS_MAX) {
1611
+ own.folded += own.queue.length - MEMORY_ANNOUNCEMENTS_MAX;
1612
+ own.queue = own.queue.slice(-MEMORY_ANNOUNCEMENTS_MAX);
1521
1613
  }
1522
- return rec;
1614
+ if (own.queue.length > 0 || own.folded > 0)
1615
+ rec.scopes[scope] = own;
1616
+ else
1617
+ delete rec.scopes[scope];
1618
+ return persistedAnnouncements(rec);
1523
1619
  });
1524
1620
  }
1525
- export function drainMemoryAnnouncements(controlDir) {
1621
+ export function drainMemoryAnnouncements(controlDir, scopes) {
1622
+ const asked = askedScopes(scopes, "drainMemoryAnnouncements");
1526
1623
  const file = join(controlDir, ANNOUNCEMENTS_FILE);
1527
1624
  if (!existsSync(file) && !existsSync(`${file}.journal`))
1528
- return { folded: 0, queue: [] };
1529
- let drained = { folded: 0, queue: [] };
1625
+ return { folded: 0, queue: [], unscopedDiscarded: 0 };
1626
+ let drained = { folded: 0, queue: [], unscopedDiscarded: 0 };
1530
1627
  lockedJournaledUpdate(controlDir, ANNOUNCEMENTS_FILE, (current) => {
1531
- drained = coerceAnnouncements(current);
1532
- if (drained.queue.length === 0 && drained.folded === 0)
1628
+ const rec = coerceAnnouncements(current);
1629
+ const mine = mergeScopeQueues(rec, asked);
1630
+ drained = { ...mine, unscopedDiscarded: rec.unscopedDiscarded };
1631
+ const otherForm = !current || typeof current !== "object" || current.v !== ANNOUNCEMENTS_FORM;
1632
+ if (mine.queue.length === 0 && mine.folded === 0 && rec.unscopedDiscarded === 0 && !otherForm)
1533
1633
  return undefined;
1534
- return { folded: 0, queue: [] };
1634
+ for (const scope of asked)
1635
+ delete rec.scopes[scope];
1636
+ rec.unscopedDiscarded = 0;
1637
+ return persistedAnnouncements(rec);
1535
1638
  });
1536
1639
  return drained;
1537
1640
  }
1538
- export function peekMemoryAnnouncements(controlDir) {
1539
- return coerceAnnouncements(readSidecarJson(controlDir, ANNOUNCEMENTS_FILE));
1641
+ export function peekMemoryAnnouncements(controlDir, scopes) {
1642
+ const asked = askedScopes(scopes, "peekMemoryAnnouncements");
1643
+ const rec = coerceAnnouncements(readSidecarJson(controlDir, ANNOUNCEMENTS_FILE));
1644
+ return { ...mergeScopeQueues(rec, asked), unscopedDiscarded: rec.unscopedDiscarded };
1645
+ }
1646
+ export function transferMemoryAnnouncements(fromControlDir, toControlDir) {
1647
+ const file = join(fromControlDir, ANNOUNCEMENTS_FILE);
1648
+ if (!existsSync(file) && !existsSync(`${file}.journal`))
1649
+ return;
1650
+ const taken = coerceAnnouncements(readSidecarJson(fromControlDir, ANNOUNCEMENTS_FILE));
1651
+ const carried = Object.keys(taken.scopes).flatMap((scope) => taken.scopes[scope].queue);
1652
+ carried.sort((x, y) => x.at - y.at);
1653
+ for (const ann of carried)
1654
+ enqueueMemoryAnnouncement(toControlDir, ann);
1655
+ const extraFolded = Object.keys(taken.scopes).map((scope) => ({ scope, folded: taken.scopes[scope].folded })).filter((x) => x.folded > 0);
1656
+ if (extraFolded.length > 0 || taken.unscopedDiscarded > 0) {
1657
+ lockedJournaledUpdate(toControlDir, ANNOUNCEMENTS_FILE, (current) => {
1658
+ const rec = coerceAnnouncements(current);
1659
+ for (const { scope, folded } of extraFolded) {
1660
+ const own = Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : { folded: 0, queue: [] };
1661
+ own.folded += folded;
1662
+ rec.scopes[scope] = own;
1663
+ }
1664
+ rec.unscopedDiscarded += taken.unscopedDiscarded;
1665
+ return persistedAnnouncements(rec);
1666
+ });
1667
+ }
1668
+ const moved = new Map();
1669
+ for (const ann of carried)
1670
+ moved.set(JSON.stringify(ann), (moved.get(JSON.stringify(ann)) ?? 0) + 1);
1671
+ lockedJournaledUpdate(fromControlDir, ANNOUNCEMENTS_FILE, (current) => {
1672
+ const rec = coerceAnnouncements(current);
1673
+ for (const scope of Object.keys(rec.scopes)) {
1674
+ const own = rec.scopes[scope];
1675
+ own.queue = own.queue.filter((a) => {
1676
+ const key = JSON.stringify(a);
1677
+ const n = moved.get(key) ?? 0;
1678
+ if (n === 0)
1679
+ return true;
1680
+ moved.set(key, n - 1);
1681
+ return false;
1682
+ });
1683
+ own.folded = Math.max(0, own.folded - (taken.scopes[scope]?.folded ?? 0));
1684
+ if (own.queue.length === 0 && own.folded === 0)
1685
+ delete rec.scopes[scope];
1686
+ }
1687
+ rec.unscopedDiscarded = Math.max(0, rec.unscopedDiscarded - taken.unscopedDiscarded);
1688
+ return persistedAnnouncements(rec);
1689
+ });
1540
1690
  }
1541
1691
  export function scanFuseKey(scope, rel) {
1542
1692
  return JSON.stringify([scope, rel.split(sep).join("/")]);
@@ -22,7 +22,7 @@ export interface MemoryBackendContractHooks {
22
22
  * assembly answers it as capability-absent.
23
23
  */
24
24
  onOptionalMember?: (report: {
25
- member: "committedSnapshotOf" | "committedSnapshotsOfScopes" | "custodyOf" | "eraseWithEvidence" | "exportSnapshotOf" | "governanceExport" | "custodyImport" | "importBundleCommit";
25
+ member: "committedSnapshotOf" | "committedSnapshotsOfScopes" | "custodyOf" | "eraseWithEvidence" | "judgesErasureScopes" | "exportSnapshotOf" | "governanceExport" | "custodyImport" | "importBundleCommit";
26
26
  status: "verified" | "absent";
27
27
  }) => void;
28
28
  }
@@ -728,10 +728,16 @@ export async function memoryBackendContract(hooks) {
728
728
  return;
729
729
  }
730
730
  const erase = seat;
731
- const e = entry("id-erase-0001", "s1", "erasable", "erasable body", { name: "Erasable" });
731
+ const e = entry("id-erase-0001", "s1", "erasable-slugword", "erasable body", { name: "Erasable" });
732
732
  await b.applyPatches([{ op: "add", id: e.id, entry: e }]);
733
733
  const att = await erase.call(b, { requestId: "req-contract-1", select: { ids: [e.id, "id-ghost-8888"] } });
734
- assert.strictEqual(att.v, 1, "the attestation rides the v:1 envelope");
734
+ assert.strictEqual(att.v, 2, "the attestation rides the v:2 envelope");
735
+ for (const cls of ["projection", "shadow", "indexLine", "quarantineCopy", "planArchive", "planWorkbook", "evidenceBinding", "backendDerived"]) {
736
+ const answer = att.residuals.carriers[cls];
737
+ assert.ok(answer !== undefined && (answer.unverified === true || (typeof answer.removed === "number" && typeof answer.remaining === "number")), `carrier class ${cls} is answered (removed/remaining counts, or unverified)`);
738
+ }
739
+ assert.strictEqual(att.residuals.replay, "converges", "an evidence face's replay converges (no time limit)");
740
+ assert.ok(!JSON.stringify(att).includes("slugword") && !JSON.stringify(att).includes("erasable body"), "the attestation names no slug and no entry text");
735
741
  assert.strictEqual(att.evidenceCapability, "journal", "a face-claiming backend answers the evidenced capability");
736
742
  assert.deepStrictEqual(att.erased.map((r) => r.id), [e.id], "the existing id is erased");
737
743
  assert.ok(typeof att.erased[0]?.evidenceEv === "string" && att.erased[0].evidenceEv.length > 0, "an evidenced erase names its evidence row");
@@ -743,6 +749,37 @@ export async function memoryBackendContract(hooks) {
743
749
  await assert.rejects(async () => erase.call(b, { requestId: "req-contract-1", select: { ids: ["id-other-7777"] } }), (err) => err.code === "memory.erasure_selector_mismatch", "a reused requestId with a different selector refuses loudly");
744
750
  hooks.onOptionalMember?.({ member: "eraseWithEvidence", status: "verified" });
745
751
  });
752
+ defer("design/1068 S1a optional erasure authorization seat: post-resolution judgment, whole-request refusal, replay bound to its set (undeclared ⇒ reported)", async () => {
753
+ const b = await hooks.make();
754
+ const seat = b.eraseWithEvidence;
755
+ const declared = b.judgesErasureScopes;
756
+ assert.ok(declared === undefined || declared === true, "judgesErasureScopes must be absent or the literal true — any other occupant is a defect, not absence");
757
+ assert.ok(declared !== true || typeof seat === "function", "a backend declaring judgesErasureScopes must offer eraseWithEvidence");
758
+ if (declared !== true) {
759
+ hooks.onOptionalMember?.({ member: "judgesErasureScopes", status: "absent" });
760
+ return;
761
+ }
762
+ const erase = seat;
763
+ const mine = entry("id-grant-mine-0001", "tenant-mine", "mine", "mine body", { name: "Mine" });
764
+ const theirs = entry("id-grant-theirs-0001", "tenant-theirs", "theirs", "theirs body", { name: "Theirs" });
765
+ await b.applyPatches([
766
+ { op: "add", id: mine.id, entry: mine },
767
+ { op: "add", id: theirs.id, entry: theirs },
768
+ ]);
769
+ const refusedBySeat = (err) => err.code === "config.memory_erasure_scope";
770
+ await assert.rejects(async () => erase.call(b, { requestId: "req-grant-1", select: { ids: [mine.id, theirs.id] }, expectedScopes: ["tenant-mine"] }), refusedBySeat, "an id resolving outside the set refuses the WHOLE request");
771
+ await assert.rejects(async () => erase.call(b, { requestId: "req-grant-2", select: { ids: [mine.id, "id-grant-ghost-0001"] }, expectedScopes: ["tenant-mine"] }), refusedBySeat, "an id the store cannot attribute to a scope is not a member — refused the same way");
772
+ await assert.rejects(async () => erase.call(b, { requestId: "req-grant-3", select: { scope: "tenant-empty" }, expectedScopes: ["tenant-mine"] }), refusedBySeat, "a place selector naming a scope outside the set refuses — even when that scope resolves to nothing");
773
+ assert.deepStrictEqual((await b.getByIds([mine.id, theirs.id])).map((e) => e.id).sort(), [mine.id, theirs.id].sort(), "refused requests erase nothing");
774
+ const att = await erase.call(b, { requestId: "req-grant-4", select: { ids: [mine.id] }, expectedScopes: ["tenant-mine", "tenant-mine"] });
775
+ assert.deepStrictEqual(att.erased.map((r) => r.id), [mine.id], "inside the set the request erases");
776
+ const replay = await erase.call(b, { requestId: "req-grant-4", select: { ids: [mine.id] }, expectedScopes: ["tenant-mine"] });
777
+ assert.deepStrictEqual((replay.erasedPreviously ?? []).map((r) => r.id), [mine.id], "a replay under the same set (another spelling) converges — judged against the first resolution, not the live account");
778
+ await assert.rejects(async () => erase.call(b, { requestId: "req-grant-4", select: { ids: [mine.id] }, expectedScopes: ["tenant-mine", "tenant-theirs"] }), (err) => err.code === "config.memory_erasure_scope", "a replay under another set refuses");
779
+ await assert.rejects(async () => erase.call(b, { requestId: "req-grant-4", select: { ids: [mine.id] } }), (err) => err.code === "config.memory_erasure_scope", "a replay with no set refuses (absent and present are different authorizations)");
780
+ assert.deepStrictEqual((await b.getByIds([theirs.id])).map((e) => e.id), [theirs.id], "the other scope's entry survives every call");
781
+ hooks.onOptionalMember?.({ member: "judgesErasureScopes", status: "verified" });
782
+ });
746
783
  defer("design/178 v2-c optional export/import faces: export composite / governance slice / custody carriage (absent ⇒ reported)", async () => {
747
784
  const b = await hooks.make();
748
785
  const seats = [
@@ -1,5 +1,11 @@
1
1
  import { type MemorySyncCursor } from "./sync.js";
2
2
  import { type MemoryBackend, type MemoryEntry, type PatchReport } from "./types.js";
3
+ /**
4
+ * The identity a sync cursor is bound to — the one mint of {@link MemorySyncCursor.store}: the physical root of
5
+ * the local File store (the path its root anchor records). A store without a directory has no root to bind a
6
+ * baseline to and is refused as a sync plane (`config.memory_sync_store`).
7
+ */
8
+ export declare function memorySyncStoreOf(backend: MemoryBackend): string;
3
9
  /** The injected HTTP seam — core never bundles a fetch. The deployment maps `path` (e.g.
4
10
  * `/v1/memory/sync/user%3Aalice`) onto its server base URL, attaches auth, and returns the
5
11
  * DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
@@ -81,7 +87,9 @@ export interface SyncMemoryScopeOptions {
81
87
  scope: string;
82
88
  /** The injected HTTP seam. */
83
89
  transport: MemorySyncTransport;
84
- /** The persisted cursor from the last completed round with this peer; absent = first round. */
90
+ /** The persisted cursor from the last completed round with this peer; absent = first round. A cursor
91
+ * for another scope, peer or local store — or one with no store binding — is refused
92
+ * (`config.memory_sync_cursor_mismatch`) before any I/O; sync with no cursor instead. */
85
93
  cursor?: MemorySyncCursor;
86
94
  /** Peer name for the cursor partition (defaults to the cursor's peer, else "central"). */
87
95
  peer?: string;
@@ -4,6 +4,32 @@ import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
4
4
  import { MAX_MEMORY_BYTES } from "../memory.js";
5
5
  import { reconcileMemoryEntries } from "./sync.js";
6
6
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
7
+ import { directoryPinOf } from "./dual-root.js";
8
+ import { landingPathOf } from "./layout.js";
9
+ function syncRefusal(code, message) {
10
+ const e = new Error(message);
11
+ e.code = code;
12
+ return e;
13
+ }
14
+ export function memorySyncStoreOf(backend) {
15
+ return syncStoreOf(backend).identity;
16
+ }
17
+ function syncStoreOf(backend) {
18
+ const pin = directoryPinOf(backend);
19
+ if (pin === undefined)
20
+ throw syncRefusal("config.memory_sync_store", "memory sync: the local store has no directory — a sync baseline is bound to a File store's root, and this store has none");
21
+ const root = landingPathOf(pin);
22
+ return { root, identity: `file:${root}` };
23
+ }
24
+ function refuseForeignCursor(cursor, scope, peer, store) {
25
+ const axis = [["scope", cursor.scope, scope], ["peer", cursor.peer, peer], ["store", cursor.store, store]];
26
+ for (const [name, got, want] of axis) {
27
+ if (got === want)
28
+ continue;
29
+ const found = got === undefined ? `has no ${name} binding` : `is for ${name} ${JSON.stringify(typeof got === "string" ? got : typeof got)}`;
30
+ throw syncRefusal("config.memory_sync_cursor_mismatch", `memory sync: cursor ${found}; this round's ${name} is ${JSON.stringify(want)} — a baseline taken elsewhere would misjudge every entry; run this round from no cursor`);
31
+ }
32
+ }
7
33
  function memorySyncPath(scope) {
8
34
  return `/v1/memory/sync/${encodeURIComponent(scope)}`;
9
35
  }
@@ -207,12 +233,9 @@ export async function syncMemoryScope(opts) {
207
233
  throw new Error("memory sync: scope must be a non-empty string");
208
234
  const peer = opts.peer ?? cursor?.peer ?? "central";
209
235
  const now = opts.now ?? Date.now;
210
- if (cursor !== undefined && cursor.scope !== scope) {
211
- throw new Error(`memory sync: cursor is for scope ${JSON.stringify(cursor.scope)}, not ${JSON.stringify(scope)}`);
212
- }
213
- if (cursor !== undefined && cursor.peer !== peer) {
214
- throw new Error(`memory sync: cursor is for peer ${JSON.stringify(cursor.peer)}, not ${JSON.stringify(peer)}`);
215
- }
236
+ const { root: storeRoot, identity: store } = syncStoreOf(backend);
237
+ if (cursor !== undefined)
238
+ refuseForeignCursor(cursor, scope, peer, store);
216
239
  for (const [name, v] of [["maxPushEntries", opts.maxPushEntries], ["maxPullEntries", opts.maxPullEntries], ["maxEntryBytes", opts.maxEntryBytes]]) {
217
240
  if (v !== undefined && (!Number.isSafeInteger(v) || v < 1)) {
218
241
  throw new Error(`memory sync: ${name} must be a positive integer (>= 1) when set, got ${String(v)}`);
@@ -341,7 +364,7 @@ export async function syncMemoryScope(opts) {
341
364
  }),
342
365
  ...deletePatches,
343
366
  ];
344
- const report = patches.length > 0 ? await backend.applyPatches(patches) : { applied: [], conflicts: [] };
367
+ const report = patches.length > 0 ? await backend.applyPatches(patches, { anchoredRoot: storeRoot }) : { applied: [], conflicts: [] };
345
368
  for (const c of report.conflicts) {
346
369
  conflicts.push({
347
370
  side: "local",
@@ -388,7 +411,7 @@ export async function syncMemoryScope(opts) {
388
411
  nextBaseRevs[op.id] = landedRev;
389
412
  }
390
413
  }
391
- nextCursor = { scope, peer, baseRevs: nextBaseRevs, updatedAtMs: now() };
414
+ nextCursor = { scope, peer, store, baseRevs: nextBaseRevs, updatedAtMs: now() };
392
415
  }
393
416
  return {
394
417
  ok: cursorAdvanced && conflicts.length === 0,
@@ -10,6 +10,11 @@ export interface MemorySyncCursor {
10
10
  scope: string;
11
11
  /** The PEER this cursor tracks (e.g. "central", a repo remote name) — one cursor per peer. */
12
12
  peer: string;
13
+ /** The LOCAL store the baseline was taken against (minted by `memorySyncStoreOf`, sync-client.ts).
14
+ * A sync over any other store refuses the cursor: the baseline describes another store's
15
+ * entries, and an id it holds that this store lacks would be pushed as a delete. Persist it
16
+ * verbatim with the rest of the cursor. */
17
+ store: string;
13
18
  /** id → rev at the last completed sync round with this peer. */
14
19
  baseRevs: Record<string, string>;
15
20
  /** Caller-injected clock (never Date.now inside the engine — clock-injection precedent). */
@@ -586,6 +586,12 @@ export interface MemoryAnnouncement {
586
586
  * degradation, applied-patch summary); `external` = out-of-session changes the backend's read-side
587
587
  * detected (disk rev ≠ ledger: adopted external edits + inbound-gate rejects). */
588
588
  kind: "gate" | "external";
589
+ /** The one scope this notice reports on — the queue it is filed under, and therefore who reads it:
590
+ * only a session that mounts this scope drains it. Required: a notice that cannot name one scope
591
+ * (a count over several scopes, a fact of the whole control plane, a session-level event with no
592
+ * scope in hand) is not a model-face notice at all — the engine sends it to the host's incident
593
+ * sink instead, so no session reads a name or a count of a scope it does not mount. */
594
+ scope: string;
589
595
  /** ms epoch at enqueue. */
590
596
  at: number;
591
597
  /** Optional producing-session id (repo-level event stream — Q-G: no worktree attribution in S2). */
@@ -4,7 +4,7 @@
4
4
  * registration form types a handler by it. Its keys are the event table's `classic.*` rows that carry a station — the key
5
5
  * set is held to that table.
6
6
  */
7
- import type { PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "../hooks.js";
7
+ import type { PermissionDeniedPayload, PostCompactEvent, PostToolBatchEvent, PostToolBatchResult, PostToolUseEvent, PostToolUseFailureEvent, PostToolUseFailureResult, PostToolUseResult, PreCompactEvent, PreCompactResult, PreToolUseEvent, PreToolUseResult, StopEvent, StopFailureEvent, StopHookResult, SubagentStartEvent, SubagentStartResult, UserPromptSubmitEvent, UserPromptSubmitResult } from "../hooks.js";
8
8
  import type { MappedOn, ModRegistration } from "./kernel/index.js";
9
9
  import type { EngineDollar } from "./dollar.js";
10
10
  /** The answer of an event whose station reads none (an observation event): a chain handler passes `next(e)`'s on. */
@@ -31,6 +31,10 @@ export type ClassicEventMap = {
31
31
  readonly e: UserPromptSubmitEvent;
32
32
  readonly answer: UserPromptSubmitResult;
33
33
  };
34
+ readonly "classic.SubagentStart": {
35
+ readonly e: SubagentStartEvent;
36
+ readonly answer: SubagentStartResult;
37
+ };
34
38
  readonly "classic.Stop": {
35
39
  readonly e: StopEvent;
36
40
  readonly answer: StopHookResult;