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