owenloop 0.5.9 → 0.5.10
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 +44 -0
- package/README.md +77 -37
- package/bin/owenloop.mjs +16 -1
- package/dist/packages/work/src/agent/loop.js +7 -0
- package/dist/packages/work/src/bundle/pull.d.ts +21 -0
- package/dist/packages/work/src/bundle/pull.js +118 -0
- package/dist/packages/work/src/exec/instructions.d.ts +4 -1
- package/dist/packages/work/src/exec/instructions.js +3 -0
- package/dist/packages/work/src/exec/loop.d.ts +1 -1
- package/dist/packages/work/src/exec/loop.js +92 -14
- package/dist/packages/work/src/harness/claude.js +16 -0
- package/dist/packages/work/src/harness/codex.d.ts +8 -0
- package/dist/packages/work/src/harness/codex.js +27 -1
- package/dist/packages/work/src/harness/contract.d.ts +9 -0
- package/dist/packages/work/src/roles/agent-run.js +38 -10
- package/dist/packages/work/src/roles/exec.js +25 -8
- package/dist/packages/work/src/shift/loop.js +118 -4
- package/dist/packages/work/src/shift/runtime.d.ts +3 -0
- package/dist/packages/work/src/shift/runtime.js +10 -1
- package/dist/packages/work/src/submit-proof.d.ts +11 -8
- package/dist/packages/work/src/submit-proof.js +11 -8
- package/dist/src/capabilities.d.ts +70 -6
- package/dist/src/capabilities.js +49 -6
- package/dist/src/capability-mapping-client.d.ts +29 -0
- package/dist/src/capability-mapping-client.js +160 -0
- package/dist/src/cli.d.ts +2 -2
- package/dist/src/cli.js +1196 -164
- package/dist/src/defs.d.ts +32 -1
- package/dist/src/defs.js +391 -79
- package/dist/src/engine.d.ts +62 -19
- package/dist/src/engine.js +180 -70
- package/dist/src/hub.d.ts +77 -0
- package/dist/src/hub.js +162 -0
- package/dist/src/implements.d.ts +56 -0
- package/dist/src/implements.js +790 -0
- package/dist/src/index.d.ts +8 -6
- package/dist/src/index.js +4 -3
- package/dist/src/mcp/serve.js +254 -45
- package/dist/src/mcp/server.d.ts +10 -7
- package/dist/src/mcp/server.js +53 -8
- package/dist/src/model.d.ts +46 -10
- package/dist/src/model.js +220 -74
- package/dist/src/store/def-source.d.ts +19 -0
- package/dist/src/store/def-source.js +87 -17
- package/dist/src/store/gc-recovery.d.ts +46 -0
- package/dist/src/store/gc-recovery.js +258 -0
- package/dist/src/store/gc.d.ts +94 -0
- package/dist/src/store/gc.js +562 -0
- package/dist/src/store/index.d.ts +3 -1
- package/dist/src/store/index.js +2 -0
- package/dist/src/store/install.d.ts +34 -5
- package/dist/src/store/install.js +73 -11
- package/dist/src/store/pre-commit-verifier.js +42 -2
- package/dist/src/store/snapshot-guard.d.ts +18 -0
- package/dist/src/store/snapshot-guard.js +94 -0
- package/dist/src/store.d.ts +64 -4
- package/dist/src/store.js +211 -8
- package/dist/src/types.d.ts +61 -17
- package/dist/src/util.js +4 -1
- package/docs/authoring.md +145 -8
- package/docs/bundles.md +19 -0
- package/docs/cli.md +270 -30
- package/docs/crypto.md +13 -7
- package/docs/design.md +107 -46
- package/docs/evals/mcp-charter-baseline.json +428 -0
- package/docs/mcp-charter-eval.md +124 -0
- package/docs/shift-logs.md +18 -0
- package/docs/wire-contracts.md +28 -7
- package/examples/workflows/compile-dev-playbook.yaml +1 -1
- package/examples/workflows/ship.yaml +28 -2
- package/package.json +2 -1
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
- package/plugins/claude-code/plugin/.mcp.json +1 -1
- package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
- package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
- package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
- package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
- package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
- package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
- package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
- package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
|
@@ -0,0 +1,562 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reachability-based garbage collection for the content-addressed workflow
|
|
3
|
+
* store. Planning is synchronous and side-effect free. Applying recomputes the
|
|
4
|
+
* plan under the store's existing writer lock, commits the pruned index first,
|
|
5
|
+
* then parks and removes unreferenced immutable objects.
|
|
6
|
+
*/
|
|
7
|
+
import { lstatSync, readFileSync, readdirSync, } from 'node:fs';
|
|
8
|
+
import { dirname, join } from 'node:path';
|
|
9
|
+
import { parseManifestBytes } from "../bundle/manifest.js";
|
|
10
|
+
import { loadDefFile } from "../defs.js";
|
|
11
|
+
import { acquireInstallLock, ensureDirectoryPathNoSymlink, guardStateFile, probeDirectoryPath, recoverInterruptedInstall, releaseInstallLock, rmRecursiveForce, STAGING_DIRNAME, } from "../install.js";
|
|
12
|
+
import { randId } from "../util.js";
|
|
13
|
+
import { loadCasDefs } from "./def-source.js";
|
|
14
|
+
import { readWorkflowStoreIndex, serializeWorkflowStoreIndex, writeWorkflowStoreIndex } from "./index-file.js";
|
|
15
|
+
import { verifyWorkflowObjectSync } from "./ingestor.js";
|
|
16
|
+
import { workflowStoreReplacementRecovery } from "./install.js";
|
|
17
|
+
import { fsyncWorkflowStoreFileAndParent, parkWorkflowStoreGcObject, recoverInterruptedWorkflowStoreGc, removeParkedWorkflowStoreGcObject, workflowStoreGcJournalPath, } from "./gc-recovery.js";
|
|
18
|
+
import { compareStoreText, defDigest, objectDirForDigest, selectLatestVersion, } from "./types.js";
|
|
19
|
+
import { probeStoreRoot, projectStoreRoot, storeIndexPath, workflowStoreStatePaths, } from "./resolve.js";
|
|
20
|
+
function assertKeep(keep) {
|
|
21
|
+
if (!Number.isSafeInteger(keep) || keep <= 0) {
|
|
22
|
+
throw new Error(`invalid workflow-store GC keep count ${JSON.stringify(keep)}: expected a positive integer`);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
function emptyIndex() {
|
|
26
|
+
return { version: 1, entries: {} };
|
|
27
|
+
}
|
|
28
|
+
function readIndexAtRoot(root) {
|
|
29
|
+
return probeStoreRoot(root) === 'absent'
|
|
30
|
+
? emptyIndex()
|
|
31
|
+
: readWorkflowStoreIndex(storeIndexPath(root));
|
|
32
|
+
}
|
|
33
|
+
/** Size one already-validated object without following links or special files. */
|
|
34
|
+
function regularTreeBytes(path) {
|
|
35
|
+
const st = lstatSync(path, { throwIfNoEntry: false });
|
|
36
|
+
if (st === undefined)
|
|
37
|
+
throw new Error(`workflow-store object path '${path}' disappeared while sizing`);
|
|
38
|
+
if (st.isSymbolicLink())
|
|
39
|
+
throw new Error(`refusing workflow-store GC candidate '${path}': it is a symlink`);
|
|
40
|
+
if (st.isFile())
|
|
41
|
+
return st.size;
|
|
42
|
+
if (!st.isDirectory()) {
|
|
43
|
+
throw new Error(`refusing workflow-store GC candidate '${path}': it is a special filesystem node`);
|
|
44
|
+
}
|
|
45
|
+
let bytes = 0;
|
|
46
|
+
for (const entry of readdirSync(path).sort(compareStoreText)) {
|
|
47
|
+
bytes += regularTreeBytes(join(path, entry));
|
|
48
|
+
}
|
|
49
|
+
return bytes;
|
|
50
|
+
}
|
|
51
|
+
function readObjectMetadata(root, digest) {
|
|
52
|
+
const objectDir = objectDirForDigest(root, digest);
|
|
53
|
+
verifyWorkflowObjectSync(objectDir, digest, { coordinateRepair: false });
|
|
54
|
+
const manifest = parseManifestBytes(readFileSync(join(objectDir, 'bundle.yaml')));
|
|
55
|
+
const qualifiedWorkflows = [];
|
|
56
|
+
for (const [workflowName, workflowPath] of Object.entries(manifest.workflows).sort(([a], [b]) => compareStoreText(a, b))) {
|
|
57
|
+
const def = loadDefFile(join(objectDir, workflowPath));
|
|
58
|
+
if (def.name !== workflowName) {
|
|
59
|
+
throw new Error(`workflow-store object ${digest}: workflow '${workflowPath}' has definition name ` +
|
|
60
|
+
`'${def.name}', expected '${workflowName}'`);
|
|
61
|
+
}
|
|
62
|
+
qualifiedWorkflows.push(`${manifest.package.name}/${workflowName}`);
|
|
63
|
+
}
|
|
64
|
+
return {
|
|
65
|
+
digest,
|
|
66
|
+
root,
|
|
67
|
+
packageName: manifest.package.name,
|
|
68
|
+
version: manifest.package.version,
|
|
69
|
+
qualifiedWorkflows,
|
|
70
|
+
dependencies: Object.entries(manifest.lock)
|
|
71
|
+
.map(([coordinate, value]) => ({ coordinate, digest: defDigest(value) }))
|
|
72
|
+
.sort((a, b) => compareStoreText(a.coordinate, b.coordinate) || compareStoreText(a.digest, b.digest)),
|
|
73
|
+
bytes: regularTreeBytes(objectDir),
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
/** Inventory every immutable object at one root, including index orphans. */
|
|
77
|
+
function scanObjects(root) {
|
|
78
|
+
const objects = new Map();
|
|
79
|
+
if (probeStoreRoot(root) === 'absent')
|
|
80
|
+
return objects;
|
|
81
|
+
const objectsRoot = join(root, 'objects');
|
|
82
|
+
if (probeDirectoryPath(objectsRoot, 'workflow objects directory', root) === 'absent')
|
|
83
|
+
return objects;
|
|
84
|
+
const digestRoot = join(objectsRoot, 'sha256');
|
|
85
|
+
if (probeDirectoryPath(digestRoot, 'workflow sha256 objects directory', root) === 'absent')
|
|
86
|
+
return objects;
|
|
87
|
+
for (const entry of readdirSync(digestRoot).sort(compareStoreText)) {
|
|
88
|
+
const digest = defDigest(entry);
|
|
89
|
+
const objectDir = objectDirForDigest(root, digest);
|
|
90
|
+
const st = lstatSync(objectDir, { throwIfNoEntry: false });
|
|
91
|
+
if (st === undefined)
|
|
92
|
+
throw new Error(`workflow-store object '${objectDir}' disappeared during inventory`);
|
|
93
|
+
if (st.isSymbolicLink())
|
|
94
|
+
throw new Error(`refusing workflow-store object '${objectDir}': it is a symlink`);
|
|
95
|
+
if (!st.isDirectory())
|
|
96
|
+
throw new Error(`refusing workflow-store object '${objectDir}': it is not a directory`);
|
|
97
|
+
objects.set(digest, readObjectMetadata(root, digest));
|
|
98
|
+
}
|
|
99
|
+
return objects;
|
|
100
|
+
}
|
|
101
|
+
function sameObjectMetadata(a, b) {
|
|
102
|
+
return a.packageName === b.packageName
|
|
103
|
+
&& a.version === b.version
|
|
104
|
+
&& JSON.stringify(a.qualifiedWorkflows) === JSON.stringify(b.qualifiedWorkflows)
|
|
105
|
+
&& JSON.stringify(a.dependencies) === JSON.stringify(b.dependencies);
|
|
106
|
+
}
|
|
107
|
+
function combineMetadata(first, second) {
|
|
108
|
+
const combined = new Map(first);
|
|
109
|
+
for (const [digest, metadata] of second) {
|
|
110
|
+
const existing = combined.get(digest);
|
|
111
|
+
if (existing !== undefined && !sameObjectMetadata(existing, metadata)) {
|
|
112
|
+
throw new Error(`workflow-store digest ${digest} has inconsistent verified metadata at ` +
|
|
113
|
+
`'${existing.root}' and '${metadata.root}'`);
|
|
114
|
+
}
|
|
115
|
+
if (existing === undefined)
|
|
116
|
+
combined.set(digest, metadata);
|
|
117
|
+
}
|
|
118
|
+
return combined;
|
|
119
|
+
}
|
|
120
|
+
function emptyReport(level, root, keep, dryRun) {
|
|
121
|
+
return {
|
|
122
|
+
ok: true,
|
|
123
|
+
dryRun,
|
|
124
|
+
level,
|
|
125
|
+
root,
|
|
126
|
+
keep,
|
|
127
|
+
count: 0,
|
|
128
|
+
bytes: 0,
|
|
129
|
+
coordinates: [],
|
|
130
|
+
objects: [],
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Compute one deterministic, fail-closed GC plan without creating any path.
|
|
135
|
+
* `keep=2` at the CLI means the current version plus one immediate rollback
|
|
136
|
+
* version: bounded history without giving up the cheapest recovery option.
|
|
137
|
+
*/
|
|
138
|
+
export function planWorkflowStoreGc(args) {
|
|
139
|
+
assertKeep(args.keep);
|
|
140
|
+
const projectRoot = projectStoreRoot(args.projectRoot);
|
|
141
|
+
const globalRoot = projectStoreRoot(args.globalRoot);
|
|
142
|
+
const targetRoot = args.level === 'project' ? projectRoot : globalRoot;
|
|
143
|
+
if (probeStoreRoot(targetRoot) === 'absent') {
|
|
144
|
+
return { report: emptyReport(args.level, targetRoot, args.keep, true), nextIndex: emptyIndex() };
|
|
145
|
+
}
|
|
146
|
+
const sameRoot = projectRoot === globalRoot;
|
|
147
|
+
const projectIndex = readIndexAtRoot(projectRoot);
|
|
148
|
+
const globalIndex = sameRoot ? projectIndex : readIndexAtRoot(globalRoot);
|
|
149
|
+
const targetIndex = args.level === 'project' ? projectIndex : globalIndex;
|
|
150
|
+
// The strict loader proves every indexed coordinate/object/manifest/definition
|
|
151
|
+
// relationship before any index entry can become a deletion candidate.
|
|
152
|
+
const registrations = loadCasDefs({
|
|
153
|
+
...(sameRoot ? {} : { projectRoot }),
|
|
154
|
+
globalRoot,
|
|
155
|
+
warn: () => { },
|
|
156
|
+
});
|
|
157
|
+
const directCoordinateDigests = new Map();
|
|
158
|
+
for (const registration of registrations) {
|
|
159
|
+
if (registration.kind === 'coordinate'
|
|
160
|
+
&& registration.coordinate !== undefined
|
|
161
|
+
&& registration.key === registration.coordinate) {
|
|
162
|
+
directCoordinateDigests.set(registration.coordinate, registration.bundleDigest);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
const projectObjects = scanObjects(projectRoot);
|
|
166
|
+
const globalObjects = sameRoot ? projectObjects : scanObjects(globalRoot);
|
|
167
|
+
const installed = combineMetadata(projectObjects, globalObjects);
|
|
168
|
+
const indexNamesDigest = (index, digest) => Object.values(index.entries).some((entry) => entry.digest === digest);
|
|
169
|
+
// The combined metadata map is useful for dependency traversal, but it is not
|
|
170
|
+
// evidence that bytes exist at the root whose index named them. Preserve the
|
|
171
|
+
// loader's intentionally asymmetric contract: project rows may use a globally
|
|
172
|
+
// indexed exact-digest copy, while global rows must have global bytes.
|
|
173
|
+
for (const [coordinate, entry] of Object.entries(projectIndex.entries)) {
|
|
174
|
+
const digest = defDigest(entry.digest);
|
|
175
|
+
const projectResolvable = projectObjects.has(digest)
|
|
176
|
+
|| (indexNamesDigest(globalIndex, digest) && globalObjects.has(digest));
|
|
177
|
+
if (!projectResolvable) {
|
|
178
|
+
throw new Error(`project workflow-store coordinate '${coordinate}' references digest ${entry.digest}, ` +
|
|
179
|
+
'but neither project bytes nor a globally indexed exact-digest fallback is installed');
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
for (const [coordinate, entry] of Object.entries(globalIndex.entries)) {
|
|
183
|
+
const digest = defDigest(entry.digest);
|
|
184
|
+
if (!globalObjects.has(digest)) {
|
|
185
|
+
throw new Error(`global workflow-store coordinate '${coordinate}' references digest ${entry.digest}, ` +
|
|
186
|
+
'but no verified object is installed at the global store root');
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
const targetObjects = args.level === 'project' ? projectObjects : globalObjects;
|
|
190
|
+
const nonTargetIndex = args.level === 'project' ? globalIndex : projectIndex;
|
|
191
|
+
const requiredTargetDigests = new Set();
|
|
192
|
+
const protectedTargetObjects = new Set();
|
|
193
|
+
const dependencyQueue = [];
|
|
194
|
+
const queuedDependencies = new Set();
|
|
195
|
+
const queueDependencies = (digest) => {
|
|
196
|
+
if (queuedDependencies.has(digest))
|
|
197
|
+
return;
|
|
198
|
+
queuedDependencies.add(digest);
|
|
199
|
+
dependencyQueue.push(digest);
|
|
200
|
+
};
|
|
201
|
+
const targetCoordinatesForDigest = (digest) => Object.entries(targetIndex.entries)
|
|
202
|
+
.filter(([, entry]) => entry.digest === digest)
|
|
203
|
+
.map(([coordinate]) => coordinate)
|
|
204
|
+
.sort(compareStoreText);
|
|
205
|
+
const requireTargetDigest = (digest, reason) => {
|
|
206
|
+
if (requiredTargetDigests.has(digest))
|
|
207
|
+
return;
|
|
208
|
+
if (targetCoordinatesForDigest(digest).length === 0) {
|
|
209
|
+
throw new Error(`workflow-store GC cannot preserve ${reason}: target ${args.level} index has no coordinate for digest ${digest}`);
|
|
210
|
+
}
|
|
211
|
+
requiredTargetDigests.add(digest);
|
|
212
|
+
queueDependencies(digest);
|
|
213
|
+
};
|
|
214
|
+
// Every retained non-target coordinate remains exactly callable after this
|
|
215
|
+
// target-only mutation. Its own copy can satisfy that requirement without
|
|
216
|
+
// retaining a redundant target copy, but all of its lock edges are roots.
|
|
217
|
+
if (!sameRoot) {
|
|
218
|
+
for (const entry of Object.values(nonTargetIndex.entries)) {
|
|
219
|
+
queueDependencies(defDigest(entry.digest));
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
// Cross-root selected winners hold their ordinary qualified names. A target
|
|
223
|
+
// winner is also covered by keep>=1; this explicit root documents and guards
|
|
224
|
+
// that invariant if selection policy changes independently.
|
|
225
|
+
for (const registration of registrations) {
|
|
226
|
+
if (registration.kind !== 'workflow' || registration.key !== registration.qualified)
|
|
227
|
+
continue;
|
|
228
|
+
if (targetCoordinatesForDigest(registration.bundleDigest).length > 0) {
|
|
229
|
+
requireTargetDigest(registration.bundleDigest, `selected workflow '${registration.qualified}'`);
|
|
230
|
+
}
|
|
231
|
+
else {
|
|
232
|
+
queueDependencies(registration.bundleDigest);
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
// Keep the best N target-level objects for every exported qualified workflow.
|
|
236
|
+
const targetDigests = [...new Set(Object.values(targetIndex.entries).map((entry) => defDigest(entry.digest)))].sort(compareStoreText);
|
|
237
|
+
const candidatesByWorkflow = new Map();
|
|
238
|
+
for (const digest of targetDigests) {
|
|
239
|
+
const metadata = installed.get(digest);
|
|
240
|
+
for (const qualified of metadata.qualifiedWorkflows) {
|
|
241
|
+
const candidates = candidatesByWorkflow.get(qualified) ?? [];
|
|
242
|
+
candidates.push({ digest, version: metadata.version, level: args.level });
|
|
243
|
+
candidatesByWorkflow.set(qualified, candidates);
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
for (const qualified of [...candidatesByWorkflow.keys()].sort(compareStoreText)) {
|
|
247
|
+
const selection = selectLatestVersion(candidatesByWorkflow.get(qualified));
|
|
248
|
+
if (selection.kind === 'unorderable') {
|
|
249
|
+
for (const candidate of selection.shadowed) {
|
|
250
|
+
requireTargetDigest(candidate.digest, `unorderable workflow '${qualified}'`);
|
|
251
|
+
}
|
|
252
|
+
continue;
|
|
253
|
+
}
|
|
254
|
+
for (const candidate of [selection.winner, ...selection.shadowed].slice(0, args.keep)) {
|
|
255
|
+
requireTargetDigest(candidate.digest, `keep window for workflow '${qualified}'`);
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
// Explicit index pins are stronger than retention policy.
|
|
259
|
+
for (const entry of Object.values(targetIndex.entries)) {
|
|
260
|
+
if (entry.pinned)
|
|
261
|
+
requireTargetDigest(defDigest(entry.digest), 'an explicit index pin');
|
|
262
|
+
}
|
|
263
|
+
const retainedExactCalls = new Set(args.exactCalls ?? []);
|
|
264
|
+
// Every retained workflow row remains replay/adopt/debug state until delete.
|
|
265
|
+
for (const snapshot of args.snapshotPins) {
|
|
266
|
+
const digests = [
|
|
267
|
+
...(snapshot.bundleDigest === undefined ? [] : [defDigest(snapshot.bundleDigest)]),
|
|
268
|
+
...snapshot.bundleLock.map((digest) => defDigest(digest)),
|
|
269
|
+
];
|
|
270
|
+
for (const digest of digests) {
|
|
271
|
+
if (targetCoordinatesForDigest(digest).length > 0) {
|
|
272
|
+
requireTargetDigest(digest, 'a retained runtime snapshot');
|
|
273
|
+
}
|
|
274
|
+
else if (targetObjects.has(digest)) {
|
|
275
|
+
// A pin can name an orphan object. Preserve the bytes even though there
|
|
276
|
+
// is no coordinate to retain or print.
|
|
277
|
+
protectedTargetObjects.add(digest);
|
|
278
|
+
queueDependencies(digest);
|
|
279
|
+
}
|
|
280
|
+
else {
|
|
281
|
+
queueDependencies(digest);
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
for (const coordinate of snapshot.exactCalls ?? [])
|
|
285
|
+
retainedExactCalls.add(coordinate);
|
|
286
|
+
}
|
|
287
|
+
// Every project-indexed digest is an external protection root for global GC,
|
|
288
|
+
// even when project-local bytes currently exist. Keeping the globally indexed
|
|
289
|
+
// coordinate/object pair preserves the plan's cross-root fallback contract if
|
|
290
|
+
// the project replica later disappears or needs repair.
|
|
291
|
+
if (args.level === 'global' && !sameRoot) {
|
|
292
|
+
for (const entry of Object.values(projectIndex.entries)) {
|
|
293
|
+
const digest = defDigest(entry.digest);
|
|
294
|
+
if (targetCoordinatesForDigest(digest).length > 0) {
|
|
295
|
+
requireTargetDigest(digest, 'a digest named by the project index');
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
const entryMatches = (index, coordinate, digest) => index.entries[coordinate]?.digest === digest;
|
|
300
|
+
/** Retain target state only when the non-target root cannot satisfy an exact coordinate itself. */
|
|
301
|
+
const preserveCoordinate = (coordinate, digest, reason, missingMessage) => {
|
|
302
|
+
if (sameRoot) {
|
|
303
|
+
if (!entryMatches(targetIndex, coordinate, digest) || !targetObjects.has(digest)) {
|
|
304
|
+
throw new Error(missingMessage);
|
|
305
|
+
}
|
|
306
|
+
// There is no independent non-target copy in single-root mode. Queueing
|
|
307
|
+
// only its dependencies would let this exact coordinate/object itself be
|
|
308
|
+
// pruned before the fixed-point walk reaches its children.
|
|
309
|
+
requireTargetDigest(digest, reason);
|
|
310
|
+
return;
|
|
311
|
+
}
|
|
312
|
+
const nonTargetSelfSufficient = args.level === 'project'
|
|
313
|
+
? entryMatches(globalIndex, coordinate, digest) && globalObjects.has(digest)
|
|
314
|
+
: entryMatches(projectIndex, coordinate, digest) && projectObjects.has(digest);
|
|
315
|
+
if (nonTargetSelfSufficient) {
|
|
316
|
+
queueDependencies(digest);
|
|
317
|
+
return;
|
|
318
|
+
}
|
|
319
|
+
const targetCanSatisfy = args.level === 'project'
|
|
320
|
+
? entryMatches(projectIndex, coordinate, digest) && (projectObjects.has(digest)
|
|
321
|
+
|| (indexNamesDigest(globalIndex, digest) && globalObjects.has(digest)))
|
|
322
|
+
: globalObjects.has(digest) && (entryMatches(globalIndex, coordinate, digest)
|
|
323
|
+
|| (entryMatches(projectIndex, coordinate, digest) && !projectObjects.has(digest)));
|
|
324
|
+
if (!targetCanSatisfy) {
|
|
325
|
+
throw new Error(missingMessage);
|
|
326
|
+
}
|
|
327
|
+
requireTargetDigest(digest, reason);
|
|
328
|
+
};
|
|
329
|
+
const preserveDependency = (parent, coordinate, digest) => {
|
|
330
|
+
preserveCoordinate(coordinate, digest, `bundle ${parent} lock '${coordinate}'`, `workflow-store bundle ${parent} locks '${coordinate}' to ${digest}, ` +
|
|
331
|
+
'but no exact callable coordinate with verified bytes is installed');
|
|
332
|
+
};
|
|
333
|
+
// A retained filesystem/add/legacy parent carries no bundle digest or lock,
|
|
334
|
+
// but its explicit namespace/name@version call still resolves through the
|
|
335
|
+
// direct CAS coordinate alias. Root that exact coordinate and the digest it
|
|
336
|
+
// selects before walking the selected object's own manifest locks.
|
|
337
|
+
for (const coordinate of [...retainedExactCalls].sort(compareStoreText)) {
|
|
338
|
+
const digest = directCoordinateDigests.get(coordinate);
|
|
339
|
+
if (digest === undefined) {
|
|
340
|
+
throw new Error(`workflow-store GC cannot preserve retained exact calls target '${coordinate}': ` +
|
|
341
|
+
'no callable exact coordinate is installed');
|
|
342
|
+
}
|
|
343
|
+
preserveCoordinate(coordinate, digest, `retained exact calls target '${coordinate}'`, `workflow-store GC cannot preserve retained exact calls target '${coordinate}' at ${digest}: ` +
|
|
344
|
+
'no exact callable coordinate with verified bytes is installed');
|
|
345
|
+
}
|
|
346
|
+
// Follow exact coordinate+digest locks to a fixed point. Digest alone is not
|
|
347
|
+
// enough: runtime resolution needs the digest-scoped alias for that exact
|
|
348
|
+
// coordinate, and project-to-global fallback is intentionally asymmetric.
|
|
349
|
+
for (let cursor = 0; cursor < dependencyQueue.length; cursor += 1) {
|
|
350
|
+
const digest = dependencyQueue[cursor];
|
|
351
|
+
const metadata = installed.get(digest);
|
|
352
|
+
if (metadata === undefined)
|
|
353
|
+
continue;
|
|
354
|
+
for (const dependency of metadata.dependencies) {
|
|
355
|
+
preserveDependency(digest, dependency.coordinate, dependency.digest);
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
const nextEntries = {};
|
|
359
|
+
const removedCoordinatesByDigest = new Map();
|
|
360
|
+
for (const coordinate of Object.keys(targetIndex.entries).sort(compareStoreText)) {
|
|
361
|
+
const entry = targetIndex.entries[coordinate];
|
|
362
|
+
const digest = defDigest(entry.digest);
|
|
363
|
+
if (requiredTargetDigests.has(digest)) {
|
|
364
|
+
nextEntries[coordinate] = entry;
|
|
365
|
+
continue;
|
|
366
|
+
}
|
|
367
|
+
const coordinates = removedCoordinatesByDigest.get(digest) ?? [];
|
|
368
|
+
coordinates.push(coordinate);
|
|
369
|
+
removedCoordinatesByDigest.set(digest, coordinates);
|
|
370
|
+
}
|
|
371
|
+
const nextIndex = { ...targetIndex, entries: nextEntries };
|
|
372
|
+
const nextDigests = new Set(Object.values(nextEntries).map((entry) => defDigest(entry.digest)));
|
|
373
|
+
const objects = [];
|
|
374
|
+
for (const digest of [...targetObjects.keys()].sort(compareStoreText)) {
|
|
375
|
+
if (protectedTargetObjects.has(digest) || nextDigests.has(digest))
|
|
376
|
+
continue;
|
|
377
|
+
const metadata = targetObjects.get(digest);
|
|
378
|
+
objects.push({
|
|
379
|
+
digest,
|
|
380
|
+
bytes: metadata.bytes,
|
|
381
|
+
coordinates: [...(removedCoordinatesByDigest.get(digest) ?? [])].sort(compareStoreText),
|
|
382
|
+
});
|
|
383
|
+
}
|
|
384
|
+
const coordinates = [...removedCoordinatesByDigest.values()].flat().sort(compareStoreText);
|
|
385
|
+
return {
|
|
386
|
+
report: {
|
|
387
|
+
ok: true,
|
|
388
|
+
dryRun: true,
|
|
389
|
+
level: args.level,
|
|
390
|
+
root: targetRoot,
|
|
391
|
+
keep: args.keep,
|
|
392
|
+
count: objects.length,
|
|
393
|
+
bytes: objects.reduce((sum, object) => sum + object.bytes, 0),
|
|
394
|
+
coordinates,
|
|
395
|
+
objects,
|
|
396
|
+
},
|
|
397
|
+
nextIndex,
|
|
398
|
+
};
|
|
399
|
+
}
|
|
400
|
+
async function acquireGcLocks(roots, additionalLockPaths = []) {
|
|
401
|
+
const statesByLock = new Map();
|
|
402
|
+
for (const root of [...new Set(roots.map((candidate) => projectStoreRoot(candidate)))]) {
|
|
403
|
+
// Applied GC may need coordination state at an absent counterpart root. Guard
|
|
404
|
+
// and create the store root itself before recursing into `<root>/.owenloop`;
|
|
405
|
+
// otherwise mkdir could follow a symlink at the root's immediate parent
|
|
406
|
+
// (notably `$HOME/.owenloop`) and place a lock outside the intended home.
|
|
407
|
+
ensureDirectoryPathNoSymlink(root, 'workflow store root');
|
|
408
|
+
const state = workflowStoreStatePaths(root);
|
|
409
|
+
statesByLock.set(state.lockPath, state);
|
|
410
|
+
}
|
|
411
|
+
for (const candidate of additionalLockPaths) {
|
|
412
|
+
const lockPath = projectStoreRoot(candidate);
|
|
413
|
+
statesByLock.set(lockPath, { lockPath, stateDir: dirname(lockPath) });
|
|
414
|
+
}
|
|
415
|
+
const locks = [];
|
|
416
|
+
try {
|
|
417
|
+
for (const lockPath of [...statesByLock.keys()].sort(compareStoreText)) {
|
|
418
|
+
const state = statesByLock.get(lockPath);
|
|
419
|
+
ensureDirectoryPathNoSymlink(state.stateDir, 'workflow store state directory');
|
|
420
|
+
guardStateFile(state.lockPath, 'install lock');
|
|
421
|
+
locks.push(await acquireInstallLock(state.lockPath));
|
|
422
|
+
}
|
|
423
|
+
return locks;
|
|
424
|
+
}
|
|
425
|
+
catch (error) {
|
|
426
|
+
for (const lock of locks.reverse())
|
|
427
|
+
releaseInstallLock(lock);
|
|
428
|
+
throw error;
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
/** Plan, or recompute under both store writer locks and apply, one target-root GC. */
|
|
432
|
+
export async function collectWorkflowStoreGarbage(args) {
|
|
433
|
+
assertKeep(args.keep);
|
|
434
|
+
const projectRoot = projectStoreRoot(args.projectRoot);
|
|
435
|
+
const globalRoot = projectStoreRoot(args.globalRoot);
|
|
436
|
+
const targetRoot = args.level === 'project' ? projectRoot : globalRoot;
|
|
437
|
+
if (probeStoreRoot(targetRoot) === 'absent') {
|
|
438
|
+
return emptyReport(args.level, targetRoot, args.keep, !args.yes);
|
|
439
|
+
}
|
|
440
|
+
if (!args.yes) {
|
|
441
|
+
return planWorkflowStoreGc({
|
|
442
|
+
projectRoot,
|
|
443
|
+
globalRoot,
|
|
444
|
+
level: args.level,
|
|
445
|
+
keep: args.keep,
|
|
446
|
+
snapshotPins: args.readSnapshotPins(),
|
|
447
|
+
exactCalls: args.readExactCalls?.() ?? [],
|
|
448
|
+
}).report;
|
|
449
|
+
}
|
|
450
|
+
const state = workflowStoreStatePaths(targetRoot);
|
|
451
|
+
// A destructive plan observes both independently written indexes. Acquire
|
|
452
|
+
// both roots in canonical order so no install or snapshot writer can commit
|
|
453
|
+
// into either side of the scan-to-delete window. This may create coordination
|
|
454
|
+
// state at a known-but-missing counterpart root; dry-run remains side-effect
|
|
455
|
+
// free and only the target index/object tree is changed.
|
|
456
|
+
const locks = await acquireGcLocks([projectRoot, globalRoot], [
|
|
457
|
+
...(args.legacyRecovery === undefined ? [] : [args.legacyRecovery.lockPath]),
|
|
458
|
+
...(args.legacyReadBarrier === undefined ? [] : [args.legacyReadBarrier.lockPath]),
|
|
459
|
+
]);
|
|
460
|
+
try {
|
|
461
|
+
guardStateFile(state.journalPath, 'crash-recovery journal');
|
|
462
|
+
guardStateFile(workflowStoreGcJournalPath(state.stateDir), 'workflow-store GC journal');
|
|
463
|
+
const stagingRoot = join(targetRoot, STAGING_DIRNAME);
|
|
464
|
+
recoverInterruptedWorkflowStoreGc({ root: targetRoot, stateDir: state.stateDir });
|
|
465
|
+
recoverInterruptedInstall({
|
|
466
|
+
defsDir: targetRoot,
|
|
467
|
+
journalPath: state.journalPath,
|
|
468
|
+
lockfilePath: storeIndexPath(targetRoot),
|
|
469
|
+
...(args.recoveryMarkerDir === undefined ? {} : { recoveryMarkerDir: args.recoveryMarkerDir }),
|
|
470
|
+
...((args.readLedger ?? args.legacyRecovery?.readLedger) === undefined
|
|
471
|
+
? {}
|
|
472
|
+
: { readLedger: args.readLedger ?? args.legacyRecovery?.readLedger }),
|
|
473
|
+
v2Replacement: workflowStoreReplacementRecovery,
|
|
474
|
+
});
|
|
475
|
+
if (args.legacyRecovery !== undefined
|
|
476
|
+
&& projectStoreRoot(args.legacyRecovery.journalPath) !== projectStoreRoot(state.journalPath)) {
|
|
477
|
+
guardStateFile(args.legacyRecovery.journalPath, 'legacy crash-recovery journal');
|
|
478
|
+
guardStateFile(args.legacyRecovery.lockfilePath, 'installed ledger');
|
|
479
|
+
recoverInterruptedInstall({
|
|
480
|
+
defsDir: targetRoot,
|
|
481
|
+
journalPath: args.legacyRecovery.journalPath,
|
|
482
|
+
lockfilePath: args.legacyRecovery.lockfilePath,
|
|
483
|
+
readLedger: args.legacyRecovery.readLedger,
|
|
484
|
+
...(args.recoveryMarkerDir === undefined ? {} : { recoveryMarkerDir: args.recoveryMarkerDir }),
|
|
485
|
+
v2Replacement: workflowStoreReplacementRecovery,
|
|
486
|
+
});
|
|
487
|
+
}
|
|
488
|
+
if (args.legacyReadBarrier !== undefined) {
|
|
489
|
+
guardStateFile(args.legacyReadBarrier.journalPath, 'legacy crash-recovery journal');
|
|
490
|
+
if (lstatSync(args.legacyReadBarrier.journalPath, { throwIfNoEntry: false }) !== undefined) {
|
|
491
|
+
throw new Error(`refusing workflow-store GC while legacy crash-recovery journal ` +
|
|
492
|
+
`'${args.legacyReadBarrier.journalPath}' is pending`);
|
|
493
|
+
}
|
|
494
|
+
}
|
|
495
|
+
// Only clear the shared tree when every writer that can own an entry has
|
|
496
|
+
// been locked and recovered. Global staging has no GitHub-add owner;
|
|
497
|
+
// project staging is safe only when its legacy lock/journal were supplied.
|
|
498
|
+
// Otherwise this probe remains a pre-commit symlink/type guard and leaves
|
|
499
|
+
// unrelated evidence untouched.
|
|
500
|
+
const stagingState = probeDirectoryPath(stagingRoot, 'workflow store staging directory', targetRoot);
|
|
501
|
+
const ownsEveryStagingWriter = args.level === 'global' || args.legacyRecovery !== undefined;
|
|
502
|
+
if (stagingState === 'dir' && ownsEveryStagingWriter) {
|
|
503
|
+
rmRecursiveForce(stagingRoot);
|
|
504
|
+
}
|
|
505
|
+
const snapshotPins = args.readSnapshotPins();
|
|
506
|
+
const exactCalls = args.readExactCalls?.() ?? [];
|
|
507
|
+
args.hooks?.afterSnapshotPinsRead?.();
|
|
508
|
+
const plan = planWorkflowStoreGc({
|
|
509
|
+
projectRoot,
|
|
510
|
+
globalRoot,
|
|
511
|
+
level: args.level,
|
|
512
|
+
keep: args.keep,
|
|
513
|
+
snapshotPins,
|
|
514
|
+
exactCalls,
|
|
515
|
+
});
|
|
516
|
+
const currentIndex = readWorkflowStoreIndex(storeIndexPath(targetRoot));
|
|
517
|
+
if (serializeWorkflowStoreIndex(currentIndex) !== serializeWorkflowStoreIndex(plan.nextIndex)) {
|
|
518
|
+
const indexPath = storeIndexPath(targetRoot);
|
|
519
|
+
writeWorkflowStoreIndex(indexPath, plan.nextIndex);
|
|
520
|
+
// The pruned index is the durable commit point. Persist both its bytes and
|
|
521
|
+
// containing directory entry before any object can leave the CAS path.
|
|
522
|
+
fsyncWorkflowStoreFileAndParent(indexPath);
|
|
523
|
+
}
|
|
524
|
+
args.hooks?.afterIndexWrite?.();
|
|
525
|
+
if (plan.report.objects.length > 0) {
|
|
526
|
+
ensureDirectoryPathNoSymlink(stagingRoot, 'workflow store staging directory');
|
|
527
|
+
}
|
|
528
|
+
for (const object of plan.report.objects) {
|
|
529
|
+
const digest = defDigest(object.digest);
|
|
530
|
+
const parkedName = `gc-${digest}-${randId('park')}`;
|
|
531
|
+
const parked = parkWorkflowStoreGcObject({
|
|
532
|
+
root: targetRoot,
|
|
533
|
+
stateDir: state.stateDir,
|
|
534
|
+
digest,
|
|
535
|
+
parkedName,
|
|
536
|
+
...(args.hooks?.afterLiveObjectMadeWritable === undefined
|
|
537
|
+
? {}
|
|
538
|
+
: { afterLiveObjectMadeWritable: args.hooks.afterLiveObjectMadeWritable }),
|
|
539
|
+
...(args.hooks?.afterObjectParked === undefined
|
|
540
|
+
? {}
|
|
541
|
+
: { afterObjectParked: args.hooks.afterObjectParked }),
|
|
542
|
+
});
|
|
543
|
+
removeParkedWorkflowStoreGcObject({
|
|
544
|
+
root: targetRoot,
|
|
545
|
+
stateDir: state.stateDir,
|
|
546
|
+
parked,
|
|
547
|
+
...(args.hooks?.removeParkedObject === undefined
|
|
548
|
+
? {}
|
|
549
|
+
: { remove: args.hooks.removeParkedObject }),
|
|
550
|
+
});
|
|
551
|
+
}
|
|
552
|
+
if (ownsEveryStagingWriter
|
|
553
|
+
&& probeDirectoryPath(stagingRoot, 'workflow store staging directory', targetRoot) === 'dir') {
|
|
554
|
+
rmRecursiveForce(stagingRoot);
|
|
555
|
+
}
|
|
556
|
+
return { ...plan.report, dryRun: false };
|
|
557
|
+
}
|
|
558
|
+
finally {
|
|
559
|
+
for (const lock of locks.reverse())
|
|
560
|
+
releaseInstallLock(lock);
|
|
561
|
+
}
|
|
562
|
+
}
|
|
@@ -19,9 +19,11 @@ export { createBundleIngestor, verifyHardenedWorkflowObjectModesSync, verifyWork
|
|
|
19
19
|
export type { BundleIngestorOptions } from './ingestor.ts';
|
|
20
20
|
export { inspectCasDefs, loadCasDefs } from './def-source.ts';
|
|
21
21
|
export type { CasDefInspectionResult, CasDefRegistration, LoadCasDefsArgs, } from './def-source.ts';
|
|
22
|
+
export { collectWorkflowStoreGarbage, planWorkflowStoreGc } from './gc.ts';
|
|
23
|
+
export type { CollectWorkflowStoreGcArgs, PlanWorkflowStoreGcArgs, WorkflowStoreGcObject, WorkflowStoreGcPlan, WorkflowStoreGcReport, } from './gc.ts';
|
|
22
24
|
export { originEvidencePath, persistOriginEvidence, readOriginEvidence, } from './origin-evidence.ts';
|
|
23
25
|
export { createStoreInstructionSource, isResolvableOrderDigest, StoreInstructionSourceError, } from './instruction-source.ts';
|
|
24
26
|
export type { MissingObjectHandler, StoreInstructionSource, StoreInstructionSourceArgs, } from './instruction-source.ts';
|
|
25
|
-
export type { BundleInstallResult, BundleIngestor, BundleSource, InstallWorkflowBundleArgs, PreCommitVerifier, RecoverWorkflowStoreArgs, } from './install.ts';
|
|
27
|
+
export type { BundleInstallResult, BundleIngestor, BundleSource, BundleVerificationEvidence, InstallWorkflowBundleArgs, PreCommitVerifier, RecoverWorkflowStoreArgs, } from './install.ts';
|
|
26
28
|
export { createExecutionDefinitionVerifier, createExecutionOriginVerifier, createPreCommitVerifier, createProductionPreCommitVerifier, resolveArtifactPolicy, resolveDefPolicy, resolveOriginPolicy, resolveOriginRules, } from './pre-commit-verifier.ts';
|
|
27
29
|
export type { ExecutionDefinitionVerifierInput, ExecutionOriginVerifierInput, PreCommitVerifierOptions, } from './pre-commit-verifier.ts';
|
package/dist/src/store/index.js
CHANGED
|
@@ -16,6 +16,8 @@ export { hardenObjectModes, installWorkflowBundle, objectDestRelPath, recoverWor
|
|
|
16
16
|
export { createBundleIngestor, verifyHardenedWorkflowObjectModesSync, verifyWorkflowObjectSync, } from "./ingestor.js";
|
|
17
17
|
// ---- WS-6 CAS -> calls: def bridge ----
|
|
18
18
|
export { inspectCasDefs, loadCasDefs } from "./def-source.js";
|
|
19
|
+
// ---- workflow-store reachability GC ----
|
|
20
|
+
export { collectWorkflowStoreGarbage, planWorkflowStoreGc } from "./gc.js";
|
|
19
21
|
// ---- WP-E2a origin execution policy ----
|
|
20
22
|
export { originEvidencePath, persistOriginEvidence, readOriginEvidence, } from "./origin-evidence.js";
|
|
21
23
|
export { createStoreInstructionSource, isResolvableOrderDigest, StoreInstructionSourceError, } from "./instruction-source.js";
|
|
@@ -36,6 +36,26 @@ export type BundleSource = {
|
|
|
36
36
|
kind: 'url';
|
|
37
37
|
url: string;
|
|
38
38
|
};
|
|
39
|
+
/**
|
|
40
|
+
* Publication and optional origin statements obtained alongside a bundle.
|
|
41
|
+
*
|
|
42
|
+
* This is deliberately separate from {@link BundleSource}: a URL says where
|
|
43
|
+
* bytes were obtained, while these bytes are the claims that the required
|
|
44
|
+
* pre-commit verifier must independently validate. A remote caller must make
|
|
45
|
+
* an explicit signed/unsigned publication declaration; absence is never
|
|
46
|
+
* silently converted into an unsigned marker by this contract.
|
|
47
|
+
*/
|
|
48
|
+
export interface BundleVerificationEvidence {
|
|
49
|
+
publication: {
|
|
50
|
+
state: 'signed';
|
|
51
|
+
dsseBytes: Uint8Array;
|
|
52
|
+
} | {
|
|
53
|
+
state: 'unsigned';
|
|
54
|
+
markerBytes?: Uint8Array;
|
|
55
|
+
};
|
|
56
|
+
/** Exact optional origin DSSE bytes; undefined means the publisher supplied no origin statement. */
|
|
57
|
+
originDsseBytes?: Uint8Array;
|
|
58
|
+
}
|
|
39
59
|
/**
|
|
40
60
|
* The bundle-ingestion port: bundle unpacking, canonical digest computation,
|
|
41
61
|
* manifest integrity, safe extraction, and the full `namespace/name@version`
|
|
@@ -88,6 +108,8 @@ export interface PreCommitVerifier {
|
|
|
88
108
|
coordinate: WorkflowCoordinate;
|
|
89
109
|
digest: DefDigest;
|
|
90
110
|
objectDir: string;
|
|
111
|
+
/** Explicit remote publication/origin evidence, when the caller fetched it. */
|
|
112
|
+
verificationEvidence?: BundleVerificationEvidence;
|
|
91
113
|
}): Promise<void>;
|
|
92
114
|
}
|
|
93
115
|
/** What a successful bundle install reports. No signature contents or keys — ever. */
|
|
@@ -111,6 +133,10 @@ export interface InstallWorkflowBundleArgs {
|
|
|
111
133
|
root: string;
|
|
112
134
|
/** Which level `root` is (result metadata only). */
|
|
113
135
|
level: StoreLevel;
|
|
136
|
+
/** Project root used to revalidate exact manifest locks before commit. */
|
|
137
|
+
projectRoot?: string;
|
|
138
|
+
/** Global root used to revalidate exact manifest locks before commit. */
|
|
139
|
+
globalRoot?: string;
|
|
114
140
|
/** Path of the per-root install lock (project installs share the project add lock). */
|
|
115
141
|
lockPath: string;
|
|
116
142
|
/** Path of the per-root crash-recovery journal. */
|
|
@@ -121,6 +147,10 @@ export interface InstallWorkflowBundleArgs {
|
|
|
121
147
|
ingestor: BundleIngestor;
|
|
122
148
|
/** Pre-commit verifier — REQUIRED (fail-closed without it). */
|
|
123
149
|
verifier: PreCommitVerifier;
|
|
150
|
+
/** Digest the caller requested. A mismatch is refused before any store ownership mutation. */
|
|
151
|
+
expectedDigest?: DefDigest;
|
|
152
|
+
/** Explicit publication/origin evidence forwarded to the mandatory verifier. */
|
|
153
|
+
verificationEvidence?: BundleVerificationEvidence;
|
|
124
154
|
/**
|
|
125
155
|
* Project-level installs ONLY: the installed.json ledger lookup so the
|
|
126
156
|
* inline recovery can roll back/forward a legacy v1 (GitHub-route) journal
|
|
@@ -162,8 +192,7 @@ export declare const workflowStoreReplacementRecovery: {
|
|
|
162
192
|
*
|
|
163
193
|
* Fixed commit order:
|
|
164
194
|
* 1. acquire the root's install lock;
|
|
165
|
-
* 2. recover
|
|
166
|
-
* backups a rollback needs live under the staging root);
|
|
195
|
+
* 2. recover prior GC parking and install transactions before stale-stage cleanup;
|
|
167
196
|
* 3. clear stale staging debris;
|
|
168
197
|
* 4. reread + validate the index INSIDE the lock (ownership/conflict
|
|
169
198
|
* decisions must see the post-lock state — TOCTOU);
|
|
@@ -219,10 +248,10 @@ export interface RecoverWorkflowStoreArgs {
|
|
|
219
248
|
}
|
|
220
249
|
/**
|
|
221
250
|
* Offline crash recovery for a workflow-store root — the `add --recover`
|
|
222
|
-
* counterpart for bundle installs. Acquires the root lock,
|
|
223
|
-
*
|
|
251
|
+
* counterpart for bundle installs. Acquires the root lock, recovers GC parking
|
|
252
|
+
* before the generic two-version install recovery, then releases. No network,
|
|
224
253
|
* no store open. A v2 journal recovers forward or back exactly as the inline
|
|
225
254
|
* path would; a v1 journal is refused (the GitHub route owns v1 recovery).
|
|
226
|
-
* Refusals throw and
|
|
255
|
+
* Refusals throw and preserve unrelated staging evidence.
|
|
227
256
|
*/
|
|
228
257
|
export declare function recoverWorkflowStore(args: RecoverWorkflowStoreArgs): Promise<RecoveryOutcome>;
|