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