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.
Files changed (83) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +77 -37
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.js +7 -0
  5. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  6. package/dist/packages/work/src/bundle/pull.js +118 -0
  7. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  8. package/dist/packages/work/src/exec/instructions.js +3 -0
  9. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  10. package/dist/packages/work/src/exec/loop.js +92 -14
  11. package/dist/packages/work/src/harness/claude.js +16 -0
  12. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  13. package/dist/packages/work/src/harness/codex.js +27 -1
  14. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  15. package/dist/packages/work/src/roles/agent-run.js +38 -10
  16. package/dist/packages/work/src/roles/exec.js +25 -8
  17. package/dist/packages/work/src/shift/loop.js +118 -4
  18. package/dist/packages/work/src/shift/runtime.d.ts +3 -0
  19. package/dist/packages/work/src/shift/runtime.js +10 -1
  20. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  21. package/dist/packages/work/src/submit-proof.js +11 -8
  22. package/dist/src/capabilities.d.ts +70 -6
  23. package/dist/src/capabilities.js +49 -6
  24. package/dist/src/capability-mapping-client.d.ts +29 -0
  25. package/dist/src/capability-mapping-client.js +160 -0
  26. package/dist/src/cli.d.ts +2 -2
  27. package/dist/src/cli.js +1196 -164
  28. package/dist/src/defs.d.ts +32 -1
  29. package/dist/src/defs.js +391 -79
  30. package/dist/src/engine.d.ts +62 -19
  31. package/dist/src/engine.js +180 -70
  32. package/dist/src/hub.d.ts +77 -0
  33. package/dist/src/hub.js +162 -0
  34. package/dist/src/implements.d.ts +56 -0
  35. package/dist/src/implements.js +790 -0
  36. package/dist/src/index.d.ts +8 -6
  37. package/dist/src/index.js +4 -3
  38. package/dist/src/mcp/serve.js +254 -45
  39. package/dist/src/mcp/server.d.ts +10 -7
  40. package/dist/src/mcp/server.js +53 -8
  41. package/dist/src/model.d.ts +46 -10
  42. package/dist/src/model.js +220 -74
  43. package/dist/src/store/def-source.d.ts +19 -0
  44. package/dist/src/store/def-source.js +87 -17
  45. package/dist/src/store/gc-recovery.d.ts +46 -0
  46. package/dist/src/store/gc-recovery.js +258 -0
  47. package/dist/src/store/gc.d.ts +94 -0
  48. package/dist/src/store/gc.js +562 -0
  49. package/dist/src/store/index.d.ts +3 -1
  50. package/dist/src/store/index.js +2 -0
  51. package/dist/src/store/install.d.ts +34 -5
  52. package/dist/src/store/install.js +73 -11
  53. package/dist/src/store/pre-commit-verifier.js +42 -2
  54. package/dist/src/store/snapshot-guard.d.ts +18 -0
  55. package/dist/src/store/snapshot-guard.js +94 -0
  56. package/dist/src/store.d.ts +64 -4
  57. package/dist/src/store.js +211 -8
  58. package/dist/src/types.d.ts +61 -17
  59. package/dist/src/util.js +4 -1
  60. package/docs/authoring.md +145 -8
  61. package/docs/bundles.md +19 -0
  62. package/docs/cli.md +270 -30
  63. package/docs/crypto.md +13 -7
  64. package/docs/design.md +107 -46
  65. package/docs/evals/mcp-charter-baseline.json +428 -0
  66. package/docs/mcp-charter-eval.md +124 -0
  67. package/docs/shift-logs.md +18 -0
  68. package/docs/wire-contracts.md +28 -7
  69. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  70. package/examples/workflows/ship.yaml +28 -2
  71. package/package.json +2 -1
  72. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  73. package/plugins/claude-code/plugin/.mcp.json +1 -1
  74. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  75. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  76. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  77. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  81. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  82. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  83. 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';
@@ -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 a prior interrupted install (before stale-stage cleanup — the
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, runs the generic
223
- * two-version recovery (v2 metadata-hash commit point), releases. No network,
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 leave the journal, staging, and objects untouched.
255
+ * Refusals throw and preserve unrelated staging evidence.
227
256
  */
228
257
  export declare function recoverWorkflowStore(args: RecoverWorkflowStoreArgs): Promise<RecoveryOutcome>;