@sema-agent/core 7.65.0 → 7.66.1

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 (129) hide show
  1. package/CHANGELOG.md +269 -0
  2. package/dist/agents/delegation-registry-seat.d.ts +15 -0
  3. package/dist/agents/delegation-registry-seat.js +13 -0
  4. package/dist/agents/org-delivery-gate.d.ts +8 -1
  5. package/dist/agents/org-delivery-gate.js +9 -3
  6. package/dist/agents/peer-session-drain.d.ts +51 -12
  7. package/dist/agents/peer-session-drain.js +44 -31
  8. package/dist/agents/read-inbox-tool.d.ts +6 -2
  9. package/dist/agents/read-inbox-tool.js +18 -5
  10. package/dist/agents/subagent.d.ts +3 -1
  11. package/dist/agents/subagent.js +79 -75
  12. package/dist/brain/reasoning.d.ts +2 -0
  13. package/dist/brain/reasoning.js +1 -0
  14. package/dist/core/allow-entry.d.ts +9 -0
  15. package/dist/core/allow-entry.js +7 -1
  16. package/dist/core/ask-origin.d.ts +23 -3
  17. package/dist/core/ask-origin.js +11 -1
  18. package/dist/core/engine-notice.d.ts +3 -3
  19. package/dist/core/governance-codes.js +1 -0
  20. package/dist/core/human-input-projection.d.ts +9 -0
  21. package/dist/core/human-input-projection.js +13 -0
  22. package/dist/core/input-author.d.ts +66 -6
  23. package/dist/core/input-author.js +21 -3
  24. package/dist/core/memory-engine/consolidation.d.ts +23 -9
  25. package/dist/core/memory-engine/consolidation.js +30 -5
  26. package/dist/core/memory-engine/control-plane-adoption.d.ts +11 -10
  27. package/dist/core/memory-engine/control-plane-adoption.js +54 -29
  28. package/dist/core/memory-engine/delegation-settlement.d.ts +18 -12
  29. package/dist/core/memory-engine/delegation-settlement.js +36 -26
  30. package/dist/core/memory-engine/engine.d.ts +17 -6
  31. package/dist/core/memory-engine/engine.js +78 -35
  32. package/dist/core/memory-engine/file-backend.d.ts +4 -1
  33. package/dist/core/memory-engine/file-backend.js +5 -1
  34. package/dist/core/memory-engine/index.d.ts +2 -2
  35. package/dist/core/memory-engine/index.js +2 -2
  36. package/dist/core/memory-engine/layout.d.ts +57 -36
  37. package/dist/core/memory-engine/layout.js +109 -134
  38. package/dist/core/memory-engine/memory-backend-contract.js +7 -7
  39. package/dist/core/memory-engine/memory-deployment.d.ts +3 -2
  40. package/dist/core/memory-engine/memory-deployment.js +6 -3
  41. package/dist/core/memory-engine/origin-clearance.d.ts +43 -15
  42. package/dist/core/memory-engine/origin-clearance.js +143 -55
  43. package/dist/core/model-receipt.d.ts +2 -1
  44. package/dist/core/model-receipt.js +5 -0
  45. package/dist/core/mods/dollar.d.ts +12 -0
  46. package/dist/core/mods/kernel/dispatch.d.ts +3 -1
  47. package/dist/core/mods/kernel/dispatch.js +5 -2
  48. package/dist/core/mods/kernel/events.d.ts +3 -1
  49. package/dist/core/mods/kernel/events.js +2 -2
  50. package/dist/core/mods/prompt-submit.d.ts +4 -0
  51. package/dist/core/mods/prompt-submit.js +24 -0
  52. package/dist/core/mods/stations.d.ts +23 -4
  53. package/dist/core/mods/stations.js +14 -7
  54. package/dist/core/retired-host-table-account.d.ts +19 -0
  55. package/dist/core/retired-host-table-account.js +28 -0
  56. package/dist/core/retired-tool-name-account.d.ts +60 -0
  57. package/dist/core/retired-tool-name-account.js +32 -0
  58. package/dist/core/roles.d.ts +3 -1
  59. package/dist/core/roles.js +5 -2
  60. package/dist/core/runner/compact-session.js +2 -1
  61. package/dist/core/runner/contracts.d.ts +1 -1
  62. package/dist/core/runner/gate-exit.js +9 -2
  63. package/dist/core/runner/memory-consolidation-driver.js +2 -2
  64. package/dist/core/runner/prepare-config-doors.js +1 -1
  65. package/dist/core/runner/prepare-delegation-surface.d.ts +1 -1
  66. package/dist/core/runner/prepare-delegation-surface.js +5 -3
  67. package/dist/core/runner/prepare-inherited-gate.js +2 -0
  68. package/dist/core/runner/prepare-memory.js +26 -5
  69. package/dist/core/runner/prepare-park-ask.d.ts +2 -0
  70. package/dist/core/runner/prepare-park-ask.js +3 -1
  71. package/dist/core/runner/prepare-policy-chain.js +2 -1
  72. package/dist/core/runner/prepare-project-context.js +2 -2
  73. package/dist/core/runner/prepare-question-face.d.ts +2 -2
  74. package/dist/core/runner/prepare-task.d.ts +5 -1
  75. package/dist/core/runner/prepare-task.js +5 -4
  76. package/dist/core/runner/prepare-wiring-manifest.js +5 -4
  77. package/dist/core/runner/prompt-suggestions.js +1 -1
  78. package/dist/core/runner/run-identity-wiring.js +2 -2
  79. package/dist/core/runner/run-leg.js +3 -3
  80. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  81. package/dist/core/runner/run-notification-lane.js +2 -2
  82. package/dist/core/runner/runtask.js +6 -3
  83. package/dist/core/runner/steer-admission.d.ts +11 -2
  84. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  85. package/dist/core/runner/stream-steer-verb.js +67 -14
  86. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -27
  87. package/dist/core/runner/sub-agent-deny-lists.js +22 -33
  88. package/dist/core/runner-deps.d.ts +4 -4
  89. package/dist/core/shell-run-candidates.js +3 -3
  90. package/dist/core/side-query.js +1 -1
  91. package/dist/core/skill-grant.d.ts +7 -0
  92. package/dist/core/skill-grant.js +14 -5
  93. package/dist/core/task-event.d.ts +14 -0
  94. package/dist/core/tool-policy.js +2 -3
  95. package/dist/core/tool-spec.d.ts +13 -3
  96. package/dist/core/user-attachment.d.ts +5 -1
  97. package/dist/core/user-attachment.js +11 -5
  98. package/dist/engine/harness/agent-harness.d.ts +19 -11
  99. package/dist/engine/harness/agent-harness.js +7 -4
  100. package/dist/engine/llm/types.d.ts +22 -10
  101. package/dist/index.d.ts +4 -2
  102. package/dist/index.js +3 -1
  103. package/dist/shell/lex.d.ts +50 -15
  104. package/dist/shell/lex.js +43 -9
  105. package/dist/tools/fs/fs-bash.js +3 -3
  106. package/dist/tools/fs/removal-targets.d.ts +8 -2
  107. package/dist/tools/fs/removal-targets.js +31 -4
  108. package/dist/tools/fs/shell-read-argv.js +7 -1
  109. package/dist/tools/fs/shell-read-bindings.d.ts +21 -5
  110. package/dist/tools/fs/shell-read-bindings.js +130 -44
  111. package/dist/tools/fs/shell-read-plan.js +95 -29
  112. package/dist/tools/fs/shell-read-sourced.d.ts +25 -0
  113. package/dist/tools/fs/shell-read-sourced.js +119 -0
  114. package/dist/tools/fs/shell-read-word.d.ts +2 -2
  115. package/dist/tools/fs/shell-read-word.js +4 -5
  116. package/dist/tools/fs/shell-read-workdir.d.ts +19 -3
  117. package/dist/tools/fs/shell-read-workdir.js +60 -15
  118. package/dist/tools/fs/shell-reentry-text.d.ts +10 -2
  119. package/dist/tools/fs/shell-reentry-text.js +11 -4
  120. package/package.json +2 -2
  121. package/test/export-surface.snapshot.json +13 -7
  122. package/wire-changes/core-stores-sql@7.66.0.json +30 -0
  123. package/wire-changes/core-stores-sql@7.66.1.json +30 -0
  124. package/wire-changes/core@7.66.0.json +1218 -0
  125. package/wire-changes/core@7.66.1.json +46 -0
  126. package/wire-changes/mods-kernel@7.66.0.json +65 -0
  127. package/wire-changes/mods-kernel@7.66.1.json +30 -0
  128. package/wire-changes/primitives@7.66.0.json +30 -0
  129. package/wire-changes/primitives@7.66.1.json +30 -0
@@ -53,6 +53,13 @@ export interface HumanInputFrame {
53
53
  * harness's empty-injection no-op stays a no-op — a frame must never materialize from nothing.
54
54
  */
55
55
  export declare function frameMidTurnUserInput(projected: string): string;
56
+ /**
57
+ * The frame of an extension's prompt (`$.prompt.submit`, author `extension`): the extension named, its text, and the tail —
58
+ * the model reads it as the extension's, never as the person's (CC `tzt`, cli316.js:273469). `name` is the calling
59
+ * registration's (the registration-name form: letters, digits, `.`, `_`, `:`, `-`); absent ⇒ the frame names no extension.
60
+ * A blank text passes through untouched (the harness's empty-injection no-op), like the person's frame.
61
+ */
62
+ export declare function frameExtensionInput(name: string | undefined, projected: string): string;
56
63
  /**
57
64
  * Render the speaker envelope for one human-input frame. Pure; see the module contract above.
58
65
  * Call BEFORE any trust framing (`formatHookFeedback` / `delimitUntrusted`) so the label stays
@@ -78,4 +85,6 @@ export declare function buildAppliedHumanInputEvent(input: {
78
85
  principal?: string | undefined;
79
86
  runOrigin?: HumanInputEvent["runOrigin"];
80
87
  rewrittenBy?: readonly string[] | undefined;
88
+ author?: HumanInputEvent["author"];
89
+ extension?: string | undefined;
81
90
  }): HumanInputEvent;
@@ -11,6 +11,13 @@ export function frameMidTurnUserInput(projected) {
11
11
  return projected;
12
12
  return `${MID_TURN_USER_INPUT_HEAD}${projected}${MID_TURN_USER_INPUT_TAIL}`;
13
13
  }
14
+ const EXTENSION_INPUT_TAIL = "\n\nThis is how a prompt an extension submits is surfaced: between turns, starting this turn in the user's place. Address " +
15
+ "the message above.";
16
+ export function frameExtensionInput(name, projected) {
17
+ if (projected.trim().length === 0)
18
+ return projected;
19
+ return `${name !== undefined ? `The extension "${name}"` : "An extension"} sent a message:\n${projected}${EXTENSION_INPUT_TAIL}`;
20
+ }
14
21
  export function projectHumanInput(frame) {
15
22
  if (frame.actor === undefined || frame.source === "system")
16
23
  return frame.text;
@@ -34,6 +41,8 @@ const HANDLED_HUMAN_INPUT_KEYS = {
34
41
  attachments: "forwarded",
35
42
  runOrigin: "forwarded",
36
43
  rewrittenBy: "forwarded",
44
+ author: "forwarded",
45
+ extension: "forwarded",
37
46
  };
38
47
  export function buildHumanInputEvent(input) {
39
48
  void HANDLED_HUMAN_INPUT_KEYS;
@@ -51,6 +60,8 @@ export function buildHumanInputEvent(input) {
51
60
  ...(input.attachments !== undefined && input.attachments.length > 0 ? { attachments: input.attachments.map((a) => ({ ...a })) } : {}),
52
61
  ...(input.runOrigin !== undefined ? { runOrigin: input.runOrigin } : {}),
53
62
  ...(input.rewrittenBy !== undefined ? { rewrittenBy: Object.freeze([...input.rewrittenBy]) } : {}),
63
+ ...(input.author !== undefined ? { author: input.author } : {}),
64
+ ...(input.extension !== undefined ? { extension: input.extension } : {}),
54
65
  };
55
66
  }
56
67
  export function buildAppliedHumanInputEvent(input) {
@@ -65,5 +76,7 @@ export function buildAppliedHumanInputEvent(input) {
65
76
  ...(input.principal !== undefined ? { principal: input.principal } : {}),
66
77
  ...(input.runOrigin !== undefined ? { runOrigin: input.runOrigin } : {}),
67
78
  ...(input.rewrittenBy !== undefined ? { rewrittenBy: input.rewrittenBy } : {}),
79
+ ...(input.author !== undefined ? { author: input.author } : {}),
80
+ ...(input.extension !== undefined ? { extension: input.extension } : {}),
68
81
  });
69
82
  }
@@ -1,5 +1,7 @@
1
1
  import type { RunInternals } from "./runner/contracts.js";
2
- export declare const INPUT_AUTHORS: readonly ["operator", "parent_model", "workflow", "peer", "observer", "engine"];
2
+ import type { ModFrame, ModOrigin } from "./mods/kernel/index.js";
3
+ import type { AssertAllKeysHandled } from "./ask-origin.js";
4
+ export declare const INPUT_AUTHORS: readonly ["operator", "parent_model", "workflow", "peer", "observer", "engine", "extension"];
3
5
  export type InputAuthor = (typeof INPUT_AUTHORS)[number];
4
6
  /** Membership test for {@link InputAuthor}. */
5
7
  export declare function isInputAuthor(v: unknown): v is InputAuthor;
@@ -7,9 +9,31 @@ export declare function isInputAuthor(v: unknown): v is InputAuthor;
7
9
  export type InputAuthorReading = InputAuthor | "unknown";
8
10
  /** The one reader: a member reads as itself, anything else (`undefined` included) as `unknown`. */
9
11
  export declare function readInputAuthor(raw: unknown): InputAuthorReading;
10
- /** THE predicate: does this input count as the operator's — screened by `classic.UserPromptSubmit`, carried across a pause, on
11
- * the person's undelivered-input account? An unreadable word does (a filter's safe side); the five other words do not. */
12
+ /** How the model reads an input that arrives mid-run: `person` — the person's mid-turn frame (a trusted caller's reminder);
13
+ * `extension` — the extension's frame, naming the extension; `verbatim` — the text as the relay hands it (an observer's
14
+ * report already carries its own envelope). */
15
+ export type InputFrame = "person" | "extension" | "verbatim";
16
+ /** One word's row: the three facts the module header names. */
17
+ interface AuthorRow {
18
+ readonly screened: boolean;
19
+ readonly countsAsOperator: boolean;
20
+ readonly frame: InputFrame;
21
+ }
22
+ /** The table, one row per member (a new word does not compile without its row). */
23
+ declare const AUTHOR_ROWS: {
24
+ readonly [A in InputAuthor]: AuthorRow;
25
+ };
26
+ /** The table's fence (docs/CLOSED-SETS.md): `never` while every author has a row. */
27
+ export type AuthorTableCoversEveryAuthor = AssertAllKeysHandled<Exclude<InputAuthor, keyof typeof AUTHOR_ROWS>>;
28
+ /** The word a reading is judged as: a member as itself, `unknown` as the operator's (the row it reads). */
29
+ export declare function judgedAuthorOf(reading: InputAuthorReading): InputAuthor;
30
+ /** Does this input count as the operator's — carried across a pause, on the person's undelivered-input account, past the hold
31
+ * of a run a person stopped? Only the operator's words do (an unreadable word reads as theirs). */
12
32
  export declare function countsAsOperator(reading: InputAuthorReading): boolean;
33
+ /** Does the prompt screen judge this input at the door it enters? The operator's words and an extension's are screened. */
34
+ export declare function isScreened(reading: InputAuthorReading): boolean;
35
+ /** How the model reads this input when it arrives mid-run ({@link InputFrame}). */
36
+ export declare function inputFrameOf(reading: InputAuthorReading): InputFrame;
13
37
  /**
14
38
  * The objective's author on a leg, from the trusted channel's word (`RunInternals.objectiveAuthor`): absent is the public
15
39
  * entry's own mint, `operator` — the host that called `runTask` wrote the objective or relays the person who did; a member is
@@ -21,12 +45,47 @@ export declare function objectiveAuthorOf(declared: unknown, onUnreadable: (erro
21
45
  * otherwise, its objective the recipe's own words (the caller's request rode the recipe's first leg). A composition whose later legs
22
46
  * re-run the caller's objective (a cascade's rungs) does not call it. */
23
47
  export declare function recipeContinuationLeg(internals: RunInternals | undefined): RunInternals;
48
+ /** What the engine's relay is told beside the text, for an input an extension's `$.prompt.submit` call hands it: the call's
49
+ * `frames` and `origin` (the prompt screen is raised under them, so the caller's own handlers stay out of it), the calling
50
+ * registration's name (`extension`) and the call's cancel. Absent for the observer's report. */
51
+ export interface AuthoredRelayCall {
52
+ readonly frames: readonly ModFrame[];
53
+ readonly origin: ModOrigin;
54
+ readonly extension: string;
55
+ /** The door's tier: an extension's prompt waits for the leg's would-otherwise-stop seat (CC `hWe = "later"`). */
56
+ readonly priority: "later";
57
+ readonly signal?: AbortSignal;
58
+ }
59
+ /** The relay's answer, decided when the input is taken (never when it is read): the text that entered the leg — the caller's,
60
+ * or the prompt screen's rewrite of it — or why it did not enter. */
61
+ export type AuthoredRelayAnswer = {
62
+ readonly entered: string;
63
+ } | {
64
+ readonly drop: string;
65
+ };
24
66
  /**
25
67
  * The engine's own relay into a running stream's steer lane, under the author it states. The public `TaskStream.steer` mints
26
- * `operator` on every call; this seat is how the engine hands a stream an input someone else wrote (an observer's report). It
27
- * lives on the stream object the Runner minted — registered here, never on the package face — so no caller can name an author.
68
+ * `operator` on every call; this seat is how the engine hands a stream an input someone else wrote (an observer's report, an
69
+ * extension's prompt). It lives on the stream object the Runner minted — registered here, never on the package face — so no
70
+ * caller can name an author. Every refusal the verb answers (the run not live, the hold of a stopped run, the screen's) is a
71
+ * `drop`; a fault the verb does not answer rejects.
28
72
  */
29
- export type AuthoredSteer = (author: InputAuthor, text: string) => Promise<void>;
73
+ export type AuthoredSteer = (author: InputAuthor, text: string, call?: AuthoredRelayCall) => Promise<AuthoredRelayAnswer>;
74
+ /** Where a leg's loop stands for an input: `before` — the run is live and its loop has not begun taking input (an injection
75
+ * would wait out the birth window); `open` — it takes input; `over` — it will take no more. */
76
+ export type InputWindow = "before" | "open" | "over";
77
+ /** The stream's relay as the leg's `$.prompt.submit` entry reaches it: the relay, and the one fact the relay's birth-window
78
+ * wait reads ({@link InputWindow}) — the entry refuses a call that would wait on the leg it is called from. */
79
+ export interface PromptSubmitSeat {
80
+ readonly relay: AuthoredSteer;
81
+ readonly inputWindow: () => InputWindow;
82
+ }
83
+ /** `$.prompt.submit`'s binding, minted by the stream layer once per stream and filled with that stream's own relay; the leg's
84
+ * entry reads it at call time (unfilled ⇒ the call is dropped). Handed down the leg's prepare as a parameter, never inside the
85
+ * run's internals — those are copied into a child's snapshot, and a child's prompt is never its parent's. */
86
+ export interface PromptSubmitRef {
87
+ seat?: PromptSubmitSeat;
88
+ }
30
89
  /** Register the authored steer of a stream the Runner minted (the driver calls this once per stream). */
31
90
  export declare function bindAuthoredSteer(stream: object, steer: AuthoredSteer): void;
32
91
  /** The authored steer of a stream the Runner minted; `undefined` for any other object. */
@@ -34,3 +93,4 @@ export declare function authoredSteerOf(stream: object): AuthoredSteer | undefin
34
93
  /** The terminal account's sentence for inputs of other authors a run accepted and never delivered: they are dropped, never
35
94
  * carried across a pause and never counted as the person's (the caller hands it to `onError` once, `phase: "degraded"`). */
36
95
  export declare function droppedInputsDisclosure(authors: readonly InputAuthor[]): Error;
96
+ export {};
@@ -1,5 +1,5 @@
1
1
  import { describeRejectedValue } from "./tool-search-setting.js";
2
- export const INPUT_AUTHORS = Object.freeze(["operator", "parent_model", "workflow", "peer", "observer", "engine"]);
2
+ export const INPUT_AUTHORS = Object.freeze(["operator", "parent_model", "workflow", "peer", "observer", "engine", "extension"]);
3
3
  const INPUT_AUTHOR_SET = new Set(INPUT_AUTHORS);
4
4
  export function isInputAuthor(v) {
5
5
  return INPUT_AUTHOR_SET.has(v);
@@ -7,9 +7,27 @@ export function isInputAuthor(v) {
7
7
  export function readInputAuthor(raw) {
8
8
  return isInputAuthor(raw) ? raw : "unknown";
9
9
  }
10
- const COUNTS_AS_OPERATOR = Object.freeze({ operator: true, parent_model: false, workflow: false, peer: false, observer: false, engine: false });
10
+ const row = (screened, countsAsOperator, frame) => Object.freeze({ screened, countsAsOperator, frame });
11
+ const AUTHOR_ROWS = Object.freeze({
12
+ operator: row(true, true, "person"),
13
+ parent_model: row(false, false, "verbatim"),
14
+ workflow: row(false, false, "verbatim"),
15
+ peer: row(false, false, "verbatim"),
16
+ observer: row(false, false, "verbatim"),
17
+ engine: row(false, false, "verbatim"),
18
+ extension: row(true, false, "extension"),
19
+ });
20
+ export function judgedAuthorOf(reading) {
21
+ return reading === "unknown" ? "operator" : reading;
22
+ }
11
23
  export function countsAsOperator(reading) {
12
- return reading === "unknown" || COUNTS_AS_OPERATOR[reading];
24
+ return AUTHOR_ROWS[judgedAuthorOf(reading)].countsAsOperator;
25
+ }
26
+ export function isScreened(reading) {
27
+ return AUTHOR_ROWS[judgedAuthorOf(reading)].screened;
28
+ }
29
+ export function inputFrameOf(reading) {
30
+ return AUTHOR_ROWS[judgedAuthorOf(reading)].frame;
13
31
  }
14
32
  export function objectiveAuthorOf(declared, onUnreadable) {
15
33
  if (declared === undefined)
@@ -8,6 +8,7 @@
8
8
  * they land) — a second implementation would be a drift seam, exactly the class the challenge
9
9
  * exclusion view closed.
10
10
  */
11
+ import { type SessionCaptureRecordStore } from "./layout.js";
11
12
  import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryGovernanceObjects, MemoryGovernanceStore, NotePatch } from "./types.js";
12
13
  import type { ConsolidationDriverRunRow } from "./consolidation-driver.js";
13
14
  /**
@@ -544,19 +545,23 @@ export type MemoryGovernanceDurability = "backend" | "replica-local";
544
545
  * consolidation asks here, never of a backend member it probes itself. A deployment-wide memory face asks a different
545
546
  * fact — whether the backend publishes a control plane — and does not ask here.
546
547
  *
547
- * `"backend"` ⇔ the backend publishes its own control plane (`controlPlaneRoot`, a non-empty string — the File backend:
548
- * every control-plane record, the consolidation store and the governance ledgers alike, sits in its directory). A
549
- * backend that carries `MemoryBackend.governance` but no control plane still answers `"replica-local"`: the
550
- * consolidation state, the governance documents (lineage, challenges, settlements, session accounts and the
551
- * announcement queue a consolidation writes) and the instruction holds with their captured bytes (#3485) ride its
552
- * store, and the answer stays `"replica-local"` there: eligibility also reads the capture opt-out records
553
- * (`MemoryEngineOptions.captureRecordStore`: a carrier the host injects is its declaration of a store every replica
554
- * reads; the default is a file in the engine's control plane — the store's own directory on the File backend): an
555
- * answer that turns `"backend"` for a backend without a control plane must hold for the default carrier as well.
548
+ * `"backend"` ⇔ the backend carries a governance store (`MemoryBackend.governance` — the File backend's is the File store
549
+ * over its own control plane): every record a consolidation reads and writes rides that store — the consolidation
550
+ * state, the governance documents (lineage, challenges, settlements, session accounts, the announcement queue, the
551
+ * holds and the origin clearances), the control objects (pollution markers, quarantine copies, holds' captures,
552
+ * clearance custody) and the capture opt-out records the eligibility reads (#3484: the default capture carrier is the
553
+ * store's `capture` objects; a carrier the host injects, `MemoryEngineOptions.captureRecordStore`, is its declaration
554
+ * of a store every replica reads). A backend that carries none answers `"replica-local"`: the engine then keeps those
555
+ * records in the File store over the replica's own control plane.
556
556
  */
557
557
  export declare function memoryGovernanceDurability(backend: MemoryBackend): MemoryGovernanceDurability;
558
558
  /** The control plane a File governance store keeps its documents in; `undefined` for any other store. */
559
559
  export declare function fileGovernanceStoreDir(store: MemoryGovernanceStore): string | undefined;
560
+ /** `true` ⇔ `store` is the File governance store over `controlDir` itself (the same directory, however it is spelled —
561
+ * the same path once resolved, or the same device and inode): that plane's records are the store's own. The one reading
562
+ * of "this control plane is its own carrier" — adoption has nothing to hand over, the engine converts its own v1 documents
563
+ * in place and refuses no strays, and an ancestor coordinate at that plane names this carrier (#3484). */
564
+ export declare function governanceStoreIsFileOver(store: MemoryGovernanceStore, controlDir: string): boolean;
560
565
  /** A store's control objects as a reader that must see damage rather than be spared it reads them — an erasure's count,
561
566
  * an export's roster: for a File store the listing names every entry standing in the kind's directory
562
567
  * (`standingFileControlObjectNames`) — a subdirectory, a dangling link, a name no writer could have used — so the verbs
@@ -571,6 +576,15 @@ export declare function standingControlObjectsOf(store: MemoryGovernanceStore):
571
576
  * whose backend carries no store keeps its state with this over the replica's control plane.
572
577
  */
573
578
  export declare function fileGovernanceStore(controlDir: string): MemoryGovernanceStore;
579
+ /** The capture opt-out records ({@link SessionCaptureRecordStore}) kept as the `capture` objects of a governance store
580
+ * (#3484): the engine's default carrier — the store its backend carries, else the File store over its control plane.
581
+ * Read through the store's damage-visible view ({@link standingControlObjectsOf}), so a record that stands unreadable
582
+ * reads as one, and a store that cannot answer is the indeterminate fault axis. */
583
+ export declare function governanceCaptureRecordStore(store: MemoryGovernanceStore): SessionCaptureRecordStore;
584
+ /** The {@link SessionCaptureRecordStore} of the File store over `controlDir` — the `capture` objects under
585
+ * `<controlDir>/session-capture-optout/`, the names and bytes the File form has always had. A host that keeps a
586
+ * replica's records in its own durable control plane declares it with this. */
587
+ export declare function fileSessionCaptureRecordStore(controlDir: string): SessionCaptureRecordStore;
574
588
  /** Derive a product's slug from its proposed name (memory filename charset; collisions are the
575
589
  * backend's deterministic -n suffix). */
576
590
  export declare function deriveProductSlug(name: string | undefined, fallback: string): string;
@@ -1,7 +1,7 @@
1
- import { existsSync, readdirSync, readFileSync, renameSync, rmSync } from "node:fs";
2
- import { join } from "node:path";
1
+ import { existsSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from "node:fs";
2
+ import { join, resolve } from "node:path";
3
3
  import { uuidv7 } from "../../engine/session/uuid.js";
4
- import { atomicWriteFileSync, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
4
+ import { atomicWriteFileSync, fileGovernanceDocOf, listSessionCaptureObjects, lockedStrictUpdate, markSessionCaptureObjects, readSessionCaptureObjects, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
5
5
  import { deleteFileControlObject, getFileControlObject, listFileControlObjects, moveFileControlObject, putFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
6
6
  import { thrownText } from "../thrown-value.js";
7
7
  import { optionKeys, receiveMembers } from "../own-property-receipt.js";
@@ -401,13 +401,27 @@ export function consolidationRunSuperseded(scope, cur) {
401
401
  return e;
402
402
  }
403
403
  export function memoryGovernanceDurability(backend) {
404
- const root = Reflect.get(backend, "controlPlaneRoot");
405
- return typeof root === "string" && root !== "" ? "backend" : "replica-local";
404
+ return backend.governance !== undefined ? "backend" : "replica-local";
406
405
  }
407
406
  const FILE_GOVERNANCE_DIRS = new WeakMap();
408
407
  export function fileGovernanceStoreDir(store) {
409
408
  return FILE_GOVERNANCE_DIRS.get(store);
410
409
  }
410
+ export function governanceStoreIsFileOver(store, controlDir) {
411
+ const dir = fileGovernanceStoreDir(store);
412
+ if (dir === undefined)
413
+ return false;
414
+ if (resolve(dir) === resolve(controlDir))
415
+ return true;
416
+ try {
417
+ const a = statSync(dir);
418
+ const b = statSync(controlDir);
419
+ return a.dev === b.dev && a.ino === b.ino;
420
+ }
421
+ catch {
422
+ return false;
423
+ }
424
+ }
411
425
  export function standingControlObjectsOf(store) {
412
426
  const dir = fileGovernanceStoreDir(store);
413
427
  return {
@@ -544,6 +558,17 @@ export function fileGovernanceStore(controlDir) {
544
558
  FILE_GOVERNANCE_DIRS.set(store, controlDir);
545
559
  return store;
546
560
  }
561
+ export function governanceCaptureRecordStore(store) {
562
+ const objects = standingControlObjectsOf(store);
563
+ return {
564
+ mark: (sessionId, record) => markSessionCaptureObjects(objects, sessionId, record),
565
+ read: (sessionId, identity) => readSessionCaptureObjects(objects, sessionId, identity),
566
+ list: () => listSessionCaptureObjects(objects),
567
+ };
568
+ }
569
+ export function fileSessionCaptureRecordStore(controlDir) {
570
+ return governanceCaptureRecordStore(fileGovernanceStore(controlDir));
571
+ }
547
572
  export function deriveProductSlug(name, fallback) {
548
573
  const base = (name ?? "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
549
574
  return base.length > 0 ? base : fallback;
@@ -10,19 +10,20 @@ export interface ReplicaControlPlaneStrays {
10
10
  /** One record adoption handled: a document (`doc:<name>`) or an object (`<kind>/<name>`). */
11
11
  export interface AdoptedControlRecord {
12
12
  readonly record: string;
13
- /** What the carrier holds now, never what became of the replica's copy (which stays): `"written"` ⇔ the carrier
14
- * lacked the record and now holds the same value; `"converged"` ⇔ it already held the same value. */
13
+ /** What the carrier holds now, never what became of the replica's copy: `"written"` ⇔ the carrier lacked the record
14
+ * and now holds the same value; `"converged"` ⇔ it already held the same value. */
15
15
  readonly outcome: "written" | "converged";
16
16
  /** sha-256 of the record as the replica held it: an object's bytes, a document's committed JSON value. */
17
17
  readonly digest: string;
18
18
  }
19
19
  /** {@link adoptReplicaControlPlane}'s answer. */
20
20
  export interface ControlPlaneAdoptionReport {
21
- /** Records the carrier now holds with the replica's value (the replica keeps its copy). */
21
+ /** Records the carrier now holds with the replica's value. When `refused` is empty, the replica's copies of these are
22
+ * removed; otherwise the replica keeps every copy. */
22
23
  readonly adopted: readonly AdoptedControlRecord[];
23
24
  /** Records whose adoption did not complete, each with why — a different value already in the carrier, a record that
24
- * could not be read or verified, or a receipt row that could not be written (then the carrier may already hold the
25
- * value, and a re-run converges it). */
25
+ * could not be read or verified, a receipt row that could not be written (then the carrier may already hold the
26
+ * value, and a re-run converges it), or a replica copy that could not be removed once the carrier held it. */
26
27
  readonly refused: readonly {
27
28
  readonly record: string;
28
29
  readonly reason: string;
@@ -34,11 +35,11 @@ export declare const CONTROL_PLANE_ADOPTION_FILE = "control-plane-adoption.json"
34
35
  * fails throws `ControlPlaneCorruptError` (never an empty answer). */
35
36
  export declare function replicaControlPlaneStrays(controlDir: string): ReplicaControlPlaneStrays;
36
37
  /**
37
- * Copy the replica control plane's carrier records into `carrier` (see the module note). Answers what the carrier now
38
- * holds with the replica's value and what was refused; the replica's records are not removed either way. When `carrier`
39
- * is the File store over `controlDir` itself there is nothing to hand over and the answer is empty. A `controlDir` that does
40
- * not exist is refused (`ControlPlaneCorruptError`): the call is an operator's, over a path they named, and a wrong path must
41
- * not read as "nothing to adopt".
38
+ * Hand the replica control plane's carrier records to `carrier` (see the module note). Answers what the carrier now
39
+ * holds with the replica's value and what was refused; the replica's copies are removed only when nothing was refused.
40
+ * When `carrier` is the File store over `controlDir` itself there is nothing to hand over and the answer is empty. A
41
+ * `controlDir` that does not exist is refused (`ControlPlaneCorruptError`): the call is an operator's, over a path they
42
+ * named, and a wrong path must not read as "nothing to adopt".
42
43
  */
43
44
  export declare function adoptReplicaControlPlane(controlDir: string, carrier: MemoryGovernanceStore, opts?: {
44
45
  readonly now?: () => number;
@@ -1,12 +1,13 @@
1
1
  import { createHash } from "node:crypto";
2
- import { lstatSync, statSync } from "node:fs";
3
- import { join, resolve } from "node:path";
2
+ import { lstatSync } from "node:fs";
3
+ import { join } from "node:path";
4
4
  import { isDeepStrictEqual } from "node:util";
5
5
  import { MEMORY_CONTROL_OBJECT_KINDS, MEMORY_GOVERNANCE_DOC_NAMES } from "./types.js";
6
- import { ControlPlaneCorruptError, fileGovernanceDocOf, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
7
- import { getFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
8
- import { fileGovernanceStoreDir } from "./consolidation.js";
6
+ import { ControlPlaneCorruptError, fileGovernanceDocOf, lockedStrictRemove, lockedStrictUpdate, readStrictSidecar } from "./layout.js";
7
+ import { deleteFileControlObject, getFileControlObject, standingFileControlObjectNames } from "./control-objects.js";
8
+ import { fileGovernanceStore, governanceStoreIsFileOver } from "./consolidation.js";
9
9
  import { moveOriginClearanceCustodyOut } from "./origin-clearance.js";
10
+ import { convertV1SessionAccountsAt } from "./delegation-settlement.js";
10
11
  import { thrownText } from "../thrown-value.js";
11
12
  export const CONTROL_PLANE_ADOPTION_FILE = "control-plane-adoption.json";
12
13
  function coerceReceipt(raw) {
@@ -44,27 +45,12 @@ export function replicaControlPlaneStrays(controlDir) {
44
45
  }
45
46
  return { docs, objects };
46
47
  }
47
- function carriesThisDirectory(carrier, controlDir) {
48
- const dir = fileGovernanceStoreDir(carrier);
49
- if (dir === undefined)
50
- return false;
51
- if (resolve(dir) === resolve(controlDir))
52
- return true;
53
- try {
54
- const a = statSync(dir);
55
- const b = statSync(controlDir);
56
- return a.dev === b.dev && a.ino === b.ino;
57
- }
58
- catch {
59
- return false;
60
- }
61
- }
62
48
  export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
63
49
  const now = opts?.now ?? Date.now;
64
- const adopted = [];
50
+ const handed = [];
65
51
  const refused = [];
66
- if (carriesThisDirectory(carrier, controlDir))
67
- return { adopted, refused };
52
+ if (governanceStoreIsFileOver(carrier, controlDir))
53
+ return { adopted: [], refused };
68
54
  if (!standsAt(controlDir))
69
55
  throw new ControlPlaneCorruptError(`memory control-plane adoption: ${controlDir} does not exist — a replica control plane to adopt from is a directory that stands (a wrong path hands over nothing and says so) (fail-closed)`);
70
56
  const receipt = (record, digest) => {
@@ -75,10 +61,21 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
75
61
  return { next: rec, result: undefined };
76
62
  });
77
63
  };
78
- const clearances = join(controlDir, fileGovernanceDocOf("origin-clearances").file);
79
- if (standsAt(clearances) || standsAt(`${clearances}.journal`)) {
64
+ const docStands = (name) => {
65
+ const file = join(controlDir, fileGovernanceDocOf(name).file);
66
+ return standsAt(file) || standsAt(`${file}.journal`);
67
+ };
68
+ if (docStands("session-accounts")) {
80
69
  try {
81
- moveOriginClearanceCustodyOut(controlDir);
70
+ convertV1SessionAccountsAt(controlDir);
71
+ }
72
+ catch (err) {
73
+ refused.push({ record: "doc:session-accounts", reason: `its v1 key form could not be converted first: ${thrownText(err)}` });
74
+ }
75
+ }
76
+ if (docStands("origin-clearances")) {
77
+ try {
78
+ await moveOriginClearanceCustodyOut(fileGovernanceStore(controlDir));
82
79
  }
83
80
  catch (err) {
84
81
  refused.push({ record: "doc:origin-clearances", reason: `its inline custody could not be moved out first: ${thrownText(err)}` });
@@ -104,7 +101,18 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
104
101
  continue;
105
102
  }
106
103
  receipt(record, digest);
107
- adopted.push({ record, outcome, digest });
104
+ handed.push({
105
+ adopted: { record, outcome, digest },
106
+ removeSource: () => {
107
+ const current = getFileControlObject(controlDir, kind, name);
108
+ if (current === undefined)
109
+ return true;
110
+ if (sha256Hex(current) !== digest)
111
+ return false;
112
+ deleteFileControlObject(controlDir, kind, name);
113
+ return true;
114
+ },
115
+ });
108
116
  }
109
117
  catch (err) {
110
118
  refused.push({ record, reason: thrownText(err) });
@@ -117,7 +125,7 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
117
125
  if (!before.includes(`doc:${name}`))
118
126
  refused.push({ record: `doc:${name}`, reason: `left in the replica until every record before it is adopted (refused: ${before.join(", ")})` });
119
127
  }
120
- return { adopted, refused };
128
+ return { adopted: handed.map((h) => h.adopted), refused };
121
129
  }
122
130
  for (const name of MEMORY_GOVERNANCE_DOC_NAMES) {
123
131
  const record = `doc:${name}`;
@@ -148,12 +156,29 @@ export async function adoptReplicaControlPlane(controlDir, carrier, opts) {
148
156
  continue;
149
157
  }
150
158
  receipt(record, digest);
151
- adopted.push({ record, outcome, digest });
159
+ handed.push({
160
+ adopted: { record, outcome, digest },
161
+ removeSource: () => lockedStrictRemove(controlDir, file, what, (committed) => sha256Hex(JSON.stringify(committed)) === digest) !== "kept",
162
+ });
152
163
  }
153
164
  catch (err) {
154
165
  refused.push({ record, reason: thrownText(err) });
155
166
  }
156
167
  }
168
+ if (refused.length > 0)
169
+ return { adopted: handed.map((h) => h.adopted), refused };
170
+ const adopted = [];
171
+ for (const h of handed) {
172
+ try {
173
+ if (h.removeSource())
174
+ adopted.push(h.adopted);
175
+ else
176
+ refused.push({ record: h.adopted.record, reason: "the carrier holds it; the replica's copy changed after it was adopted and is kept" });
177
+ }
178
+ catch (err) {
179
+ refused.push({ record: h.adopted.record, reason: `the carrier holds it; removing the replica's copy failed: ${thrownText(err)}` });
180
+ }
181
+ }
157
182
  return { adopted, refused };
158
183
  }
159
184
  export function readControlPlaneAdoptionReceipt(controlDir) {
@@ -184,12 +184,18 @@ export interface SessionAccountRow {
184
184
  * lock, each idempotent). The layout adoption runs this before any later scope registration can
185
185
  * change what a v1 key's first segment names. A step of the File layout's own upgrade: it converts
186
186
  * the hold ledger and the session-account document the File store keeps under `controlDir`, in place
187
- * (a store that keeps documents elsewhere never held the v1 form); the reads below convert the same
188
- * way on first touch. */
187
+ * (a store that keeps documents elsewhere never held the v1 form), and the control-plane adoption runs
188
+ * it on a replica before handing these documents to another store. It is the one converter: the
189
+ * readers below refuse the v1 form ({@link sessionAccountsV2}). */
189
190
  export declare function convertV1SidecarKeys(controlDir: string): void;
191
+ /** The session-account document of `controlDir` converted in place when it stands in the v1 key form (in its lock);
192
+ * any other form — v2, absent, or one its readers refuse as corrupt — is left exactly as it stands. The control-plane
193
+ * adoption runs this before handing the document to another store (#3484): that store's readers refuse the v1 form,
194
+ * and nothing there converts it. The conversion is the File layout's own ({@link convertSessionAccounts}). */
195
+ export declare function convertV1SessionAccountsAt(controlDir: string): void;
190
196
  /** The dangling-trigger read: open rows (and unadjudicated closes) belonging to OTHER sessions.
191
197
  * These are what arm the unattributed residue classification at a session's materialize. */
192
- export declare function foreignDanglingSessionAccounts(docs: MemoryGovernanceDocs, controlDir: string, selfSessionId: string): Promise<SessionAccountRow[]>;
198
+ export declare function foreignDanglingSessionAccounts(docs: MemoryGovernanceDocs, selfSessionId: string): Promise<SessionAccountRow[]>;
193
199
  /** The live writers of the store's layers, as the account knows them: every row other than the one
194
200
  * held by `selfLeg` (the asking mount's own leg — another leg of the same session is another
195
201
  * writer) whose session's leg has not ended (no `terminatedAt` — running, or ended without
@@ -198,16 +204,16 @@ export declare function foreignDanglingSessionAccounts(docs: MemoryGovernanceDoc
198
204
  * whether the leg ended) reads as before: live while never closed, counted in `unscoped` — a
199
205
  * writer of an unknown layer. Sessions that open no row (no session id, provenance "off", an
200
206
  * adoption-restricted mount) are not visible here. */
201
- export declare function openLayerWriters(docs: MemoryGovernanceDocs, controlDir: string, selfLeg: string | undefined): Promise<{
207
+ export declare function openLayerWriters(docs: MemoryGovernanceDocs, selfLeg: string | undefined): Promise<{
202
208
  scopes: Set<string>;
203
209
  unscoped: number;
204
210
  }>;
205
211
  /** The leg that holds `sessionId`'s account row (undefined ⇔ no row, or a row without one). */
206
- export declare function sessionAccountLeg(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<string | undefined>;
212
+ export declare function sessionAccountLeg(docs: MemoryGovernanceDocs, sessionId: string): Promise<string | undefined>;
207
213
  /** The write scope `sessionId`'s account row records — the scope its newest account-opening mount wrote
208
214
  * under (the value that mount's handle carries as `writeScope`), whether that leg is still live or has
209
- * ended. Undefined ⇔ no row, a row written before the field, or a v1 ledger (whose rows predate it —
210
- * answered without the conversion, so this read writes nothing). Throws on a corrupt ledger. */
215
+ * ended. Undefined ⇔ no row, or a row written before the field. Throws on a corrupt ledger, and on one still in the v1
216
+ * key form (refused like every reader of it, {@link sessionAccountsV2}). */
211
217
  export declare function sessionAccountWriteHome(docs: MemoryGovernanceDocs, sessionId: string): Promise<{
212
218
  writeScope: string;
213
219
  openedAt: number;
@@ -222,7 +228,7 @@ export interface SessionUnattributedSet {
222
228
  export declare function emptyUnattributedSet(): SessionUnattributedSet;
223
229
  /** Open (or re-open, on a same-session resume) the session's account row, persisting the sticky
224
230
  * unattributed classification frozen at THIS materialize. */
225
- export declare function openSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
231
+ export declare function openSessionAccount(docs: MemoryGovernanceDocs, input: {
226
232
  sessionId: string;
227
233
  now: () => number;
228
234
  unattributed: readonly UnattributedMember[];
@@ -230,7 +236,7 @@ export declare function openSessionAccount(docs: MemoryGovernanceDocs, controlDi
230
236
  leg?: string;
231
237
  }): Promise<void>;
232
238
  /** The current session's sticky unattributed set (the harvest's residue-arm input). */
233
- export declare function sessionUnattributedSet(docs: MemoryGovernanceDocs, controlDir: string, sessionId: string): Promise<SessionUnattributedSet>;
239
+ export declare function sessionUnattributedSet(docs: MemoryGovernanceDocs, sessionId: string): Promise<SessionUnattributedSet>;
234
240
  /** Close the session's account row — called ONLY after a FULL-domain harvest (zero BUDGET-deferred
235
241
  * files, i.e. `HarvestReport.degraded` absent): a partial harvest's close would launder the deferred
236
242
  * residue window (§3.6 序则②). A normal full close also clears every standing `unadjudicated` flag
@@ -245,7 +251,7 @@ export declare function sessionUnattributedSet(docs: MemoryGovernanceDocs, contr
245
251
  * Returns what happened ({@link SessionAccountWrite}): `"absent"` (a session that never opened an
246
252
  * account — e.g. an adoption-restricted materialize — has no close, and the caller's disclosure
247
253
  * must not claim one), or `"stale"` when `leg` names a mount that no longer holds the row. */
248
- export declare function closeSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
254
+ export declare function closeSessionAccount(docs: MemoryGovernanceDocs, input: {
249
255
  sessionId: string;
250
256
  now: () => number;
251
257
  leg?: string;
@@ -256,7 +262,7 @@ export type SessionAccountWrite = "written" | "absent" | "stale";
256
262
  /** Record that the session's leg ended ({@link SessionAccountRow.terminatedAt}). Touches nothing
257
263
  * else — `closedAt` stays whatever the harvests made it. `leg` (the caller's mount) must hold the
258
264
  * row: a leg that is over does not end the one that re-opened it. */
259
- export declare function terminateSessionAccount(docs: MemoryGovernanceDocs, controlDir: string, input: {
265
+ export declare function terminateSessionAccount(docs: MemoryGovernanceDocs, input: {
260
266
  sessionId: string;
261
267
  now: () => number;
262
268
  leg?: string;
@@ -264,7 +270,7 @@ export declare function terminateSessionAccount(docs: MemoryGovernanceDocs, cont
264
270
  /** The host valve for a dangling row (advisory; §3.6 — dangling rows never auto-expire). The
265
271
  * close is `closed-unadjudicated` (r7-3): it stops the row dangling but the residue arm keeps
266
272
  * firing until a full-domain harvest closes normally. `requestId` required (audit, #123). */
267
- export declare function resolveSessionAccountRecord(docs: MemoryGovernanceDocs, controlDir: string, input: {
273
+ export declare function resolveSessionAccountRecord(docs: MemoryGovernanceDocs, input: {
268
274
  sessionId: string;
269
275
  requestId: string;
270
276
  now: () => number;