owenloop 0.5.8 → 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 (131) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +81 -39
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  5. package/dist/packages/work/src/agent/loop.js +55 -6
  6. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  7. package/dist/packages/work/src/bundle/pull.js +118 -0
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  10. package/dist/packages/work/src/exec/instructions.js +3 -0
  11. package/dist/packages/work/src/exec/loop.d.ts +2 -2
  12. package/dist/packages/work/src/exec/loop.js +273 -46
  13. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  14. package/dist/packages/work/src/exec/receipt.js +6 -6
  15. package/dist/packages/work/src/harness/claude.js +116 -0
  16. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  17. package/dist/packages/work/src/harness/codex.js +27 -1
  18. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  19. package/dist/packages/work/src/hub/client.d.ts +19 -4
  20. package/dist/packages/work/src/hub/client.js +7 -3
  21. package/dist/packages/work/src/hub/types.d.ts +84 -0
  22. package/dist/packages/work/src/main.js +1 -0
  23. package/dist/packages/work/src/roles/agent-run.js +57 -32
  24. package/dist/packages/work/src/roles/exec.js +27 -8
  25. package/dist/packages/work/src/roles/settings.js +2 -0
  26. package/dist/packages/work/src/roles/shift.js +14 -2
  27. package/dist/packages/work/src/roles/util.d.ts +1 -0
  28. package/dist/packages/work/src/roles/util.js +10 -0
  29. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  31. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  32. package/dist/packages/work/src/settings/roster.js +364 -5
  33. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  34. package/dist/packages/work/src/settings/serving.js +79 -0
  35. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  36. package/dist/packages/work/src/settings/settings.js +14 -0
  37. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  38. package/dist/packages/work/src/shift/loop.js +416 -54
  39. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  40. package/dist/packages/work/src/shift/runtime.d.ts +18 -0
  41. package/dist/packages/work/src/shift/runtime.js +104 -5
  42. package/dist/packages/work/src/shift/server.js +2 -0
  43. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  44. package/dist/packages/work/src/shift/spawn.js +16 -13
  45. package/dist/packages/work/src/shift/state.d.ts +29 -2
  46. package/dist/packages/work/src/shift/state.js +45 -15
  47. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  48. package/dist/packages/work/src/submit-proof.js +11 -8
  49. package/dist/packages/work/src/usage.d.ts +1 -1
  50. package/dist/packages/work/src/usage.js +7 -1
  51. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  52. package/dist/packages/work/src/util/modifier-init.js +73 -0
  53. package/dist/src/bundle/tar.d.ts +9 -4
  54. package/dist/src/bundle/tar.js +9 -4
  55. package/dist/src/capabilities.d.ts +76 -6
  56. package/dist/src/capabilities.js +49 -6
  57. package/dist/src/capability-mapping-client.d.ts +29 -0
  58. package/dist/src/capability-mapping-client.js +160 -0
  59. package/dist/src/cli.d.ts +16 -3
  60. package/dist/src/cli.js +1925 -281
  61. package/dist/src/config-dir.d.ts +1 -1
  62. package/dist/src/config-dir.js +1 -1
  63. package/dist/src/crypto/index.d.ts +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/org-root.d.ts +30 -12
  66. package/dist/src/crypto/org-root.js +162 -14
  67. package/dist/src/crypto/records.d.ts +2 -0
  68. package/dist/src/crypto/records.js +2 -0
  69. package/dist/src/defs.d.ts +38 -2
  70. package/dist/src/defs.js +593 -86
  71. package/dist/src/engine.d.ts +103 -25
  72. package/dist/src/engine.js +331 -79
  73. package/dist/src/hub.d.ts +77 -0
  74. package/dist/src/hub.js +162 -0
  75. package/dist/src/implements.d.ts +56 -0
  76. package/dist/src/implements.js +790 -0
  77. package/dist/src/index.d.ts +11 -9
  78. package/dist/src/index.js +6 -5
  79. package/dist/src/mcp/serve.d.ts +22 -0
  80. package/dist/src/mcp/serve.js +330 -41
  81. package/dist/src/mcp/server.d.ts +10 -7
  82. package/dist/src/mcp/server.js +53 -8
  83. package/dist/src/model.d.ts +48 -10
  84. package/dist/src/model.js +252 -99
  85. package/dist/src/order-resolver.d.ts +1 -0
  86. package/dist/src/order-resolver.js +8 -1
  87. package/dist/src/schemas/index.d.ts +11 -0
  88. package/dist/src/schemas/order.v1.schema.json +7 -1
  89. package/dist/src/store/def-source.d.ts +19 -0
  90. package/dist/src/store/def-source.js +87 -17
  91. package/dist/src/store/gc-recovery.d.ts +46 -0
  92. package/dist/src/store/gc-recovery.js +258 -0
  93. package/dist/src/store/gc.d.ts +94 -0
  94. package/dist/src/store/gc.js +562 -0
  95. package/dist/src/store/index.d.ts +3 -1
  96. package/dist/src/store/index.js +2 -0
  97. package/dist/src/store/install.d.ts +34 -5
  98. package/dist/src/store/install.js +73 -11
  99. package/dist/src/store/pre-commit-verifier.js +42 -2
  100. package/dist/src/store/snapshot-guard.d.ts +18 -0
  101. package/dist/src/store/snapshot-guard.js +94 -0
  102. package/dist/src/store.d.ts +69 -4
  103. package/dist/src/store.js +254 -16
  104. package/dist/src/types.d.ts +101 -20
  105. package/dist/src/util.js +4 -1
  106. package/docs/authoring.md +235 -10
  107. package/docs/bundles.md +45 -2
  108. package/docs/cli.md +437 -55
  109. package/docs/crypto.md +32 -10
  110. package/docs/design.md +177 -47
  111. package/docs/evals/mcp-charter-baseline.json +428 -0
  112. package/docs/mcp-charter-eval.md +124 -0
  113. package/docs/routing.md +189 -34
  114. package/docs/shift-logs.md +38 -9
  115. package/docs/wire-contracts.md +78 -14
  116. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  117. package/examples/workflows/delivery.yaml +31 -14
  118. package/examples/workflows/ship.yaml +38 -4
  119. package/package.json +2 -1
  120. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  121. package/plugins/claude-code/plugin/.mcp.json +1 -1
  122. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  123. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  124. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  125. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  126. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  127. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  128. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  129. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  130. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  131. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -0,0 +1,94 @@
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 type { LedgerLookup } from '../install.ts';
8
+ import type { RuntimeSnapshotBundlePins } from '../store.ts';
9
+ import type { StoreLevel, WorkflowStoreIndex } from './types.ts';
10
+ export interface WorkflowStoreGcObject {
11
+ digest: string;
12
+ bytes: number;
13
+ coordinates: string[];
14
+ }
15
+ export interface WorkflowStoreGcReport {
16
+ ok: true;
17
+ dryRun: boolean;
18
+ level: StoreLevel;
19
+ root: string;
20
+ keep: number;
21
+ /** Number of unique object directories selected for removal. */
22
+ count: number;
23
+ /** Sum of regular-file logical sizes in selected object directories. */
24
+ bytes: number;
25
+ /** Target-index coordinates selected for removal. */
26
+ coordinates: string[];
27
+ objects: WorkflowStoreGcObject[];
28
+ }
29
+ export interface PlanWorkflowStoreGcArgs {
30
+ projectRoot: string;
31
+ globalRoot: string;
32
+ level: StoreLevel;
33
+ keep: number;
34
+ snapshotPins: readonly RuntimeSnapshotBundlePins[];
35
+ /** Exact versioned calls from currently loadable non-CAS definitions. */
36
+ exactCalls?: readonly string[];
37
+ }
38
+ export interface WorkflowStoreGcPlan {
39
+ report: WorkflowStoreGcReport;
40
+ /** Canonical target index to commit before deleting objects. */
41
+ nextIndex: WorkflowStoreIndex;
42
+ }
43
+ export interface CollectWorkflowStoreGcArgs {
44
+ projectRoot: string;
45
+ globalRoot: string;
46
+ level: StoreLevel;
47
+ keep: number;
48
+ yes: boolean;
49
+ /** Re-run inside the writer lock when `yes` is true. */
50
+ readSnapshotPins: () => readonly RuntimeSnapshotBundlePins[];
51
+ /** Re-read exact versioned calls from current project/add definitions under the writer locks. */
52
+ readExactCalls?: () => readonly string[];
53
+ /** Project mode supplies the same legacy installed-ledger reader as bundle installation. */
54
+ readLedger?: () => LedgerLookup;
55
+ /**
56
+ * Project GitHub-add transaction state sharing this root's staging tree.
57
+ * When supplied, GC takes this lock and recovers this journal before it may
58
+ * clear staging entries not owned by the current GC transaction.
59
+ */
60
+ legacyRecovery?: {
61
+ lockPath: string;
62
+ journalPath: string;
63
+ lockfilePath: string;
64
+ readLedger: () => LedgerLookup;
65
+ };
66
+ /**
67
+ * Read-only coordination for non-CAS project/add definitions when their root
68
+ * is not the GC target. A pending journal is refused rather than recovered so
69
+ * global GC never mutates the non-target project tree.
70
+ */
71
+ legacyReadBarrier?: {
72
+ lockPath: string;
73
+ journalPath: string;
74
+ };
75
+ recoveryMarkerDir?: string;
76
+ /** Narrow failure-injection seams for commit-order regression tests. */
77
+ hooks?: {
78
+ afterSnapshotPinsRead?: () => void;
79
+ afterIndexWrite?: () => void;
80
+ /** Process-interruption seam after durable evidence and the temporary live chmod. */
81
+ afterLiveObjectMadeWritable?: (path: string) => void;
82
+ /** Process-interruption seam after the object rename and parent fsyncs. */
83
+ afterObjectParked?: (path: string) => void;
84
+ removeParkedObject?: (path: string) => void;
85
+ };
86
+ }
87
+ /**
88
+ * Compute one deterministic, fail-closed GC plan without creating any path.
89
+ * `keep=2` at the CLI means the current version plus one immediate rollback
90
+ * version: bounded history without giving up the cheapest recovery option.
91
+ */
92
+ export declare function planWorkflowStoreGc(args: PlanWorkflowStoreGcArgs): WorkflowStoreGcPlan;
93
+ /** Plan, or recompute under both store writer locks and apply, one target-root GC. */
94
+ export declare function collectWorkflowStoreGarbage(args: CollectWorkflowStoreGcArgs): Promise<WorkflowStoreGcReport>;
@@ -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';