owenloop 0.5.9 → 0.5.11

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 (86) hide show
  1. package/CHANGELOG.md +51 -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 +1200 -166
  28. package/dist/src/defs.d.ts +41 -1
  29. package/dist/src/defs.js +461 -92
  30. package/dist/src/engine.d.ts +108 -22
  31. package/dist/src/engine.js +573 -85
  32. package/dist/src/factory.js +5 -3
  33. package/dist/src/hub.d.ts +77 -0
  34. package/dist/src/hub.js +162 -0
  35. package/dist/src/implements.d.ts +37 -0
  36. package/dist/src/implements.js +790 -0
  37. package/dist/src/index.d.ts +12 -10
  38. package/dist/src/index.js +7 -6
  39. package/dist/src/mcp/serve.js +254 -45
  40. package/dist/src/mcp/server.d.ts +10 -7
  41. package/dist/src/mcp/server.js +53 -8
  42. package/dist/src/model.d.ts +46 -10
  43. package/dist/src/model.js +224 -78
  44. package/dist/src/order-resolver.js +1 -0
  45. package/dist/src/store/def-source.d.ts +19 -0
  46. package/dist/src/store/def-source.js +87 -17
  47. package/dist/src/store/gc-recovery.d.ts +46 -0
  48. package/dist/src/store/gc-recovery.js +258 -0
  49. package/dist/src/store/gc.d.ts +94 -0
  50. package/dist/src/store/gc.js +563 -0
  51. package/dist/src/store/index.d.ts +3 -1
  52. package/dist/src/store/index.js +2 -0
  53. package/dist/src/store/install.d.ts +34 -5
  54. package/dist/src/store/install.js +73 -11
  55. package/dist/src/store/pre-commit-verifier.js +42 -2
  56. package/dist/src/store/snapshot-guard.d.ts +18 -0
  57. package/dist/src/store/snapshot-guard.js +94 -0
  58. package/dist/src/store.d.ts +66 -4
  59. package/dist/src/store.js +333 -12
  60. package/dist/src/types.d.ts +97 -17
  61. package/dist/src/types.js +4 -0
  62. package/dist/src/util.js +4 -1
  63. package/docs/authoring.md +214 -9
  64. package/docs/bundles.md +19 -0
  65. package/docs/cli.md +270 -30
  66. package/docs/crypto.md +13 -7
  67. package/docs/design.md +107 -46
  68. package/docs/evals/mcp-charter-baseline.json +428 -0
  69. package/docs/mcp-charter-eval.md +124 -0
  70. package/docs/shift-logs.md +18 -0
  71. package/docs/wire-contracts.md +28 -7
  72. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  73. package/examples/workflows/ship.yaml +28 -2
  74. package/package.json +2 -1
  75. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  76. package/plugins/claude-code/plugin/.mcp.json +1 -1
  77. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  78. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  79. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  80. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  81. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  82. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  83. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  84. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  85. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  86. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
@@ -24,15 +24,50 @@
24
24
  import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
25
25
  import { dirname, join } from 'node:path';
26
26
  import { randId } from "../util.js";
27
- import { DefError, finalizeDefs, lintDef, loadDefFile, loadDefsRaw, validateDef } from "../defs.js";
27
+ import { DefError, digestScopedCallsTargetKey, finalizeDefs, lintDef, loadDefFile, loadDefsRaw, validateDef, } from "../defs.js";
28
28
  import { parseManifestBytes } from "../bundle/manifest.js";
29
29
  import { hasDefiniteCheckDefect, modelCheck } from "../model.js";
30
30
  import { acquireInstallLock, canonicalJsonBytes, commitInstall, createRecoveryMarker, ensureDirectoryPathNoSymlink, finalizeInstallCommit, guardStateFile, multiSegmentPathViolation, probeDirectoryPath, recoverInterruptedInstall, recordRecoveryMarkerPriorIdentity, releaseInstallLock, removeAddJournal, removeRecoveryMarker, rmRecursiveForce, RollbackFailedError, rollbackInstallCommit, sha256Hex, writeAddJournal, } from "../install.js";
31
31
  import { BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, StoreConflictError, StoreIntegrityError, StorePathError, } from "./types.js";
32
32
  import { readWorkflowStoreIndex, writeWorkflowStoreIndex } from "./index-file.js";
33
33
  import { verifyWorkflowObjectSync } from "./ingestor.js";
34
- import { defDigest } from "./types.js";
35
- import { storeIndexPath } from "./resolve.js";
34
+ import { loadCasDefs, loadCasDefsWithRepairReplacement } from "./def-source.js";
35
+ import { compareStoreText, defDigest, objectDirForDigest } from "./types.js";
36
+ import { projectStoreRoot, storeIndexPath } from "./resolve.js";
37
+ import { recoverInterruptedWorkflowStoreGc } from "./gc-recovery.js";
38
+ function assertManifestLocksResolvable(args) {
39
+ const entries = Object.entries(args.lock);
40
+ if (entries.length === 0)
41
+ return;
42
+ if (args.projectRoot === undefined || args.globalRoot === undefined) {
43
+ throw new Error('refusing bundle with exact lock targets: install requires both projectRoot and globalRoot for pre-commit revalidation');
44
+ }
45
+ const projectRoot = projectStoreRoot(args.projectRoot);
46
+ const globalRoot = projectStoreRoot(args.globalRoot);
47
+ const root = projectStoreRoot(args.root);
48
+ const expectedRoot = args.level === 'project' ? projectRoot : globalRoot;
49
+ if (root !== expectedRoot) {
50
+ throw new Error(`refusing bundle lock revalidation: ${args.level} install root '${root}' does not match '${expectedRoot}'`);
51
+ }
52
+ // Do not approximate execution reachability with index/object presence.
53
+ // Strict discovery also verifies coordinate identity, runtime compatibility,
54
+ // the callable default/sole-workflow target, and the exact project/global
55
+ // fallback semantics used when a running workflow resolves its bundleLock.
56
+ const loadArgs = { projectRoot, globalRoot, warn: () => { } };
57
+ const registrations = args.repairReplacement === undefined
58
+ ? loadCasDefs(loadArgs)
59
+ : loadCasDefsWithRepairReplacement(loadArgs, args.repairReplacement);
60
+ const callableKeys = new Set(registrations
61
+ .filter((registration) => registration.kind === 'coordinate')
62
+ .map((registration) => registration.key));
63
+ for (const [coordinate, rawDigest] of entries.sort(([a], [b]) => compareStoreText(a, b))) {
64
+ const digest = defDigest(rawDigest);
65
+ if (!callableKeys.has(digestScopedCallsTargetKey(digest, coordinate))) {
66
+ throw new Error(`refusing bundle install: lock target '${coordinate}' pinned to ${digest} ` +
67
+ 'is no longer exactly callable from the combined workflow store');
68
+ }
69
+ }
70
+ }
36
71
  /**
37
72
  * The CAS destination relative path for a validated digest: the single
38
73
  * relative path `objects/sha256/<digest>`, re-validated as a safe
@@ -104,8 +139,7 @@ export const workflowStoreReplacementRecovery = {
104
139
  *
105
140
  * Fixed commit order:
106
141
  * 1. acquire the root's install lock;
107
- * 2. recover a prior interrupted install (before stale-stage cleanup — the
108
- * backups a rollback needs live under the staging root);
142
+ * 2. recover prior GC parking and install transactions before stale-stage cleanup;
109
143
  * 3. clear stale staging debris;
110
144
  * 4. reread + validate the index INSIDE the lock (ownership/conflict
111
145
  * decisions must see the post-lock state — TOCTOU);
@@ -168,14 +202,15 @@ export async function installWorkflowBundle(args) {
168
202
  // root (a rollback double-fault) — then the `finally` must NOT clear it.
169
203
  let preserveStagingRoot = false;
170
204
  try {
171
- // Recover a prior interrupted install FIRST — before the stale-staging
172
- // clear, since the backups a rollback needs live under the staging root.
205
+ // Recover prior GC parking and install transactions FIRST — before the
206
+ // stale-staging clear, since either can own evidence below that shared root.
173
207
  // A v1 (GitHub) journal at a shared project journal path needs the
174
208
  // project ledger to vouch (supplied via `readLedger` — project bundle
175
209
  // installs share the project add lock/recovery ordering); without a
176
210
  // ledger a leftover v1 journal is refused. Any refusal preserves the
177
211
  // staging root + journal as evidence.
178
212
  try {
213
+ recoverInterruptedWorkflowStoreGc({ root, stateDir: dirname(lockPath) });
179
214
  recoverInterruptedInstall({
180
215
  defsDir: root,
181
216
  journalPath,
@@ -199,6 +234,9 @@ export async function installWorkflowBundle(args) {
199
234
  // A refusal here (tamper, bad manifest, oversized archive) leaves staging
200
235
  // debris only — no object, no index, no journal touched.
201
236
  const { coordinate, digest, workflows: ingestedWorkflows } = await ingestor.ingest({ source, bytes, stagingDir });
237
+ if (args.expectedDigest !== undefined && digest !== args.expectedDigest) {
238
+ throw new StoreIntegrityError('object-corrupt', args.expectedDigest, `canonical bundle digest mismatch — expected ${args.expectedDigest}, got ${digest}; nothing was committed`);
239
+ }
202
240
  const workflows = [...ingestedWorkflows].sort((a, b) => Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')));
203
241
  // Ownership/conflict decisions, inside the lock:
204
242
  const existing = index.entries[coordinate];
@@ -219,6 +257,7 @@ export async function installWorkflowBundle(args) {
219
257
  const reasons = [];
220
258
  let staged;
221
259
  let externalVersionedCalls = new Set();
260
+ let stagedBundleLock = {};
222
261
  const manifestPath = join(stagingDir, 'bundle.yaml');
223
262
  if (existsSync(manifestPath)) {
224
263
  // Real `.wnlp` bundles carry an explicit workflow map. Load every listed
@@ -227,6 +266,7 @@ export async function installWorkflowBundle(args) {
227
266
  try {
228
267
  const manifest = parseManifestBytes(readFileSync(manifestPath));
229
268
  externalVersionedCalls = new Set(Object.keys(manifest.lock));
269
+ stagedBundleLock = manifest.lock;
230
270
  for (const [workflowName, workflowPath] of Object.entries(manifest.workflows)) {
231
271
  const workflowFile = join(stagingDir, workflowPath);
232
272
  try {
@@ -291,7 +331,13 @@ export async function installWorkflowBundle(args) {
291
331
  }
292
332
  // A2 pre-commit verification: after content/engine validation, before ANY
293
333
  // destination swap or index write. A rejection commits nothing.
294
- await verifier.verify({ source, coordinate, digest, objectDir: stagingDir });
334
+ await verifier.verify({
335
+ source,
336
+ coordinate,
337
+ digest,
338
+ objectDir: stagingDir,
339
+ ...(args.verificationEvidence !== undefined ? { verificationEvidence: args.verificationEvidence } : {}),
340
+ });
295
341
  // Existing same-digest objects have two paths. A verified object keeps the
296
342
  // normal idempotent dedupe. A broken object is repaired only from the
297
343
  // supplied archive that already passed strict ingest, engine validation,
@@ -315,6 +361,21 @@ export async function installWorkflowBundle(args) {
315
361
  repairRequired = true;
316
362
  }
317
363
  }
364
+ // Re-read both roots while this install still owns its root lock. A
365
+ // destructive GC owns both root locks, so either this commit becomes visible
366
+ // to its reachability scan or a GC-first removal makes this stale caller
367
+ // fail here before any journal/object/index mutation. A verified staged
368
+ // same-digest repair may substitute its verified staged replacement only
369
+ // for the broken destination; every lock dependency, unrelated object, and
370
+ // same-digest physical copy at another root remains strict.
371
+ assertManifestLocksResolvable({
372
+ root,
373
+ level,
374
+ projectRoot: args.projectRoot,
375
+ globalRoot: args.globalRoot,
376
+ lock: stagedBundleLock,
377
+ ...(repairRequired ? { repairReplacement: { root, digest, objectDir: stagingDir } } : {}),
378
+ });
318
379
  // The post-install index, computed BEFORE the commit point so its exact
319
380
  // canonical bytes are what the journal's metadataHash commits to. A
320
381
  // same-digest repair intentionally preserves the existing index semantics.
@@ -527,11 +588,11 @@ export async function installWorkflowBundle(args) {
527
588
  }
528
589
  /**
529
590
  * Offline crash recovery for a workflow-store root — the `add --recover`
530
- * counterpart for bundle installs. Acquires the root lock, runs the generic
531
- * two-version recovery (v2 metadata-hash commit point), releases. No network,
591
+ * counterpart for bundle installs. Acquires the root lock, recovers GC parking
592
+ * before the generic two-version install recovery, then releases. No network,
532
593
  * no store open. A v2 journal recovers forward or back exactly as the inline
533
594
  * path would; a v1 journal is refused (the GitHub route owns v1 recovery).
534
- * Refusals throw and leave the journal, staging, and objects untouched.
595
+ * Refusals throw and preserve unrelated staging evidence.
535
596
  */
536
597
  export async function recoverWorkflowStore(args) {
537
598
  ensureDirectoryPathNoSymlink(args.root, 'workflow store root');
@@ -541,6 +602,7 @@ export async function recoverWorkflowStore(args) {
541
602
  guardStateFile(args.journalPath, 'crash-recovery journal');
542
603
  const lock = await acquireInstallLock(args.lockPath);
543
604
  try {
605
+ recoverInterruptedWorkflowStoreGc({ root: args.root, stateDir: dirname(args.lockPath) });
544
606
  return recoverInterruptedInstall({
545
607
  defsDir: args.root,
546
608
  journalPath: args.journalPath,
@@ -84,6 +84,44 @@ function sidecarPath(source, cwd, suffix) {
84
84
  const bundlePath = filesystemSourcePath(source, cwd);
85
85
  return bundlePath === undefined ? undefined : `${bundlePath}${suffix}`;
86
86
  }
87
+ /** Convert transport-supplied evidence into the same internal shape as files. */
88
+ function sidecarsFromEvidence(evidence) {
89
+ const originDsseBytes = evidence.originDsseBytes;
90
+ if (evidence.publication.state === 'signed') {
91
+ if (!(evidence.publication.dsseBytes instanceof Uint8Array)) {
92
+ return {
93
+ unsigned: false,
94
+ contradiction: false,
95
+ invalidReason: 'signed publication evidence is not raw DSSE bytes',
96
+ originDsseBytes,
97
+ };
98
+ }
99
+ return {
100
+ unsigned: false,
101
+ contradiction: false,
102
+ dsseBytes: evidence.publication.dsseBytes,
103
+ originDsseBytes,
104
+ };
105
+ }
106
+ if (evidence.publication.state === 'unsigned') {
107
+ if (evidence.publication.markerBytes !== undefined &&
108
+ !(evidence.publication.markerBytes instanceof Uint8Array)) {
109
+ return {
110
+ unsigned: true,
111
+ contradiction: false,
112
+ invalidReason: 'unsigned publication marker is not raw bytes',
113
+ originDsseBytes,
114
+ };
115
+ }
116
+ return { unsigned: true, contradiction: false, originDsseBytes };
117
+ }
118
+ return {
119
+ unsigned: false,
120
+ contradiction: false,
121
+ invalidReason: 'publication evidence state must be signed or unsigned',
122
+ originDsseBytes,
123
+ };
124
+ }
87
125
  function readSidecars(source, cwd) {
88
126
  if (source.kind !== 'file')
89
127
  return { unsigned: false, contradiction: false };
@@ -342,7 +380,7 @@ function warningText(source, coordinate, verdict) {
342
380
  }
343
381
  function absentOriginDetail(source, sidecars) {
344
382
  if (source.kind !== 'file') {
345
- return 'cannot carry an origin: installed from a non-file source, where no sidecar is available';
383
+ return 'no origin evidence was supplied or recorded for this remote source';
346
384
  }
347
385
  if (sidecars.unsigned) {
348
386
  return 'cannot carry an origin: the definition was published unsigned';
@@ -374,7 +412,9 @@ export function createPreCommitVerifier(options = {}) {
374
412
  const originPolicy = merged.originPolicy;
375
413
  let sidecars;
376
414
  try {
377
- sidecars = readSidecars(input.source, options.cwd);
415
+ sidecars = input.verificationEvidence === undefined
416
+ ? readSidecars(input.source, options.cwd)
417
+ : sidecarsFromEvidence(input.verificationEvidence);
378
418
  }
379
419
  catch (error) {
380
420
  const detail = `publication sidecar could not be inspected: ${error instanceof Error ? error.message : String(error)}`;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Cross-resource guard for persisting CAS-backed runtime definition snapshots.
3
+ *
4
+ * The workflow-store index/object tree and the runtime SQLite database cannot
5
+ * share one atomic transaction. Instead, every destructive store writer and
6
+ * every CAS snapshot writer share the store's existing `add.lock`. A snapshot
7
+ * writer acquires all provenance roots, revalidates that its digest is still
8
+ * indexed with verified bytes, and only then begins its SQLite transaction.
9
+ * GC either observes that committed row, or wins the lock and makes a stale
10
+ * writer fail validation after collection; a stranded snapshot cannot commit.
11
+ */
12
+ import type { WorkflowDef } from '../types.ts';
13
+ import type { DefDigest } from './types.ts';
14
+ /**
15
+ * Run `fn` while every CAS provenance root is locked and revalidated.
16
+ * Non-CAS definitions carry no roots and preserve the zero-lock path.
17
+ */
18
+ export declare function withWorkflowSnapshotStoreGuard<T>(defs: readonly WorkflowDef[], fn: (guardedDigests: ReadonlySet<DefDigest>) => T): T;
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Cross-resource guard for persisting CAS-backed runtime definition snapshots.
3
+ *
4
+ * The workflow-store index/object tree and the runtime SQLite database cannot
5
+ * share one atomic transaction. Instead, every destructive store writer and
6
+ * every CAS snapshot writer share the store's existing `add.lock`. A snapshot
7
+ * writer acquires all provenance roots, revalidates that its digest is still
8
+ * indexed with verified bytes, and only then begins its SQLite transaction.
9
+ * GC either observes that committed row, or wins the lock and makes a stale
10
+ * writer fail validation after collection; a stranded snapshot cannot commit.
11
+ */
12
+ import { lstatSync } from 'node:fs';
13
+ import { ensureDirectoryPathNoSymlink, guardStateFile } from "../install.js";
14
+ import { acquireFileLockSync, releaseFileLock } from "../lock.js";
15
+ import { readWorkflowStoreIndex } from "./index-file.js";
16
+ import { verifyWorkflowObjectSync } from "./ingestor.js";
17
+ import { projectStoreRoot, probeStoreRoot, storeIndexPath, workflowStoreStatePaths } from "./resolve.js";
18
+ import { compareStoreText, defDigest, objectDirForDigest } from "./types.js";
19
+ function guardedBundles(defs) {
20
+ const rootsByDigest = new Map();
21
+ for (const def of defs) {
22
+ if (def.bundleDigest === undefined || (def.bundleStoreRoots?.length ?? 0) === 0)
23
+ continue;
24
+ const digest = defDigest(def.bundleDigest);
25
+ const roots = rootsByDigest.get(digest) ?? new Set();
26
+ for (const rawRoot of def.bundleStoreRoots ?? []) {
27
+ if (typeof rawRoot !== 'string' || rawRoot.trim() === '') {
28
+ throw new Error(`bundle ${digest} has malformed workflow-store snapshot provenance`);
29
+ }
30
+ roots.add(projectStoreRoot(rawRoot));
31
+ }
32
+ rootsByDigest.set(digest, roots);
33
+ }
34
+ return [...rootsByDigest]
35
+ .map(([digest, roots]) => ({ digest, roots: [...roots].sort(compareStoreText) }))
36
+ .sort((a, b) => compareStoreText(a.digest, b.digest));
37
+ }
38
+ function digestIsReachable(bundle) {
39
+ for (const root of bundle.roots) {
40
+ if (probeStoreRoot(root) === 'absent')
41
+ continue;
42
+ const index = readWorkflowStoreIndex(storeIndexPath(root));
43
+ const indexed = Object.values(index.entries).some((entry) => entry.digest === bundle.digest);
44
+ if (!indexed)
45
+ continue;
46
+ const objectDir = objectDirForDigest(root, bundle.digest);
47
+ const st = lstatSync(objectDir, { throwIfNoEntry: false });
48
+ if (st === undefined)
49
+ continue;
50
+ if (st.isSymbolicLink() || !st.isDirectory()) {
51
+ throw new Error(`bundle ${bundle.digest} has unsafe object path '${objectDir}'`);
52
+ }
53
+ verifyWorkflowObjectSync(objectDir, bundle.digest, { coordinateRepair: false });
54
+ return true;
55
+ }
56
+ return false;
57
+ }
58
+ /**
59
+ * Run `fn` while every CAS provenance root is locked and revalidated.
60
+ * Non-CAS definitions carry no roots and preserve the zero-lock path.
61
+ */
62
+ export function withWorkflowSnapshotStoreGuard(defs, fn) {
63
+ const bundles = guardedBundles(defs);
64
+ if (bundles.length === 0)
65
+ return fn(new Set());
66
+ const rootAndStateByLockPath = new Map(bundles.flatMap((bundle) => bundle.roots)
67
+ .map((root) => ({ root, state: workflowStoreStatePaths(root) }))
68
+ .map((item) => [item.state.lockPath, item]));
69
+ const lockPaths = [...rootAndStateByLockPath.keys()].sort(compareStoreText);
70
+ const locks = [];
71
+ try {
72
+ for (const lockPath of lockPaths) {
73
+ const { root, state } = rootAndStateByLockPath.get(lockPath);
74
+ // Guard the store root before creating `<root>/.owenloop`. In particular,
75
+ // a global root reached through a symlinked `$HOME/.owenloop` must not
76
+ // redirect snapshot-lock state outside the intended home.
77
+ ensureDirectoryPathNoSymlink(root, 'workflow store root');
78
+ ensureDirectoryPathNoSymlink(state.stateDir, 'workflow store state directory');
79
+ guardStateFile(lockPath, 'install lock');
80
+ locks.push(acquireFileLockSync(lockPath, { label: 'workflow-store snapshot writer' }));
81
+ }
82
+ for (const bundle of bundles) {
83
+ if (!digestIsReachable(bundle)) {
84
+ throw new Error(`refusing to persist workflow snapshot for bundle ${bundle.digest}: ` +
85
+ 'the bundle is no longer indexed with verified object bytes; reload definitions and retry');
86
+ }
87
+ }
88
+ return fn(new Set(bundles.map((bundle) => bundle.digest)));
89
+ }
90
+ finally {
91
+ for (const lock of locks.reverse())
92
+ releaseFileLock(lock);
93
+ }
94
+ }
@@ -36,6 +36,26 @@ export interface WorkflowRow extends WorkflowData {
36
36
  parentPath: string;
37
37
  };
38
38
  }
39
+ /** The bundle identities retained by one persisted workflow definition snapshot. */
40
+ export interface RuntimeSnapshotBundlePins {
41
+ /** The snapshot's own containing bundle, when it came from the CAS store. */
42
+ bundleDigest?: string;
43
+ /** Exact cross-bundle dependencies copied from the snapshot's bundle lock. */
44
+ bundleLock: string[];
45
+ /** Exact versioned calls not already covered by this snapshot's bundle lock. */
46
+ exactCalls?: string[];
47
+ /** Start-bound implementation bundles retained before any child is spawned. */
48
+ interfaceBindingDigests?: string[];
49
+ }
50
+ /**
51
+ * Read bundle pins from an EXISTING runtime database without migrating or
52
+ * otherwise writing it. GC deliberately cannot use {@link openStore}: opening
53
+ * the normal store enables write-oriented pragmas and schema migration, while
54
+ * a dry run must remain observational. Legacy databases without the workflow
55
+ * table or def_snapshot column simply predate snapshot pinning and contribute
56
+ * no pins.
57
+ */
58
+ export declare function readRuntimeSnapshotBundlePins(path: string): RuntimeSnapshotBundlePins[];
39
59
  export declare function artifactId(workflow: string, path: string): string;
40
60
  export declare function taskId(workflow: string, step: string, key: string): string;
41
61
  /** Thrown by the `Store` constructor when the on-disk `schema_version` is
@@ -45,6 +65,7 @@ export declare class StoreVersionError extends Error {
45
65
  }
46
66
  export declare class Store {
47
67
  readonly db: DatabaseSync;
68
+ private readonly activeSnapshotDigests;
48
69
  constructor(path: string);
49
70
  /** Read the stored schema version without writing, refusing newer databases. */
50
71
  private refuseIfNewer;
@@ -75,6 +96,14 @@ export declare class Store {
75
96
  * does not support nested transactions.
76
97
  */
77
98
  tx<T>(fn: () => T): T;
99
+ /**
100
+ * Persist one or more CAS-backed definition snapshots under the same
101
+ * workflow-store lock used by install and GC. Reachability is revalidated
102
+ * before `BEGIN IMMEDIATE`; the guarded digest set then authorizes only the
103
+ * low-level snapshot writes performed by this transaction.
104
+ */
105
+ txWithWorkflowSnapshots<T>(snapshots: WorkflowDef | readonly WorkflowDef[], fn: () => T): T;
106
+ private assertWorkflowSnapshotGuard;
78
107
  getMeta(k: string): string | undefined;
79
108
  setMeta(k: string, v: string): void;
80
109
  insertWorkflow(id: string, data: WorkflowData, producedBy?: {
@@ -179,15 +208,48 @@ export declare class Store {
179
208
  lastProgressMs(workflow: string): number;
180
209
  insertRun(id: string, data: RunData, at?: number): RunRow;
181
210
  updateRun(id: string, patch: Partial<RunData>): RunRow;
211
+ /**
212
+ * Re-stamp ONE owed version target on a run's persisted order packet.
213
+ *
214
+ * The order is frozen at claim with exactly one exception, and this is it.
215
+ * When a reject re-arms a still-open claim, the artifact has already been
216
+ * bumped by the commit that preceded the reject, so the target the claim
217
+ * froze at issue names a version the next commit will overshoot — and the
218
+ * producer would sign that stale number into its submission proof while the
219
+ * hub keys the stored proof row by the version actually committed. Everything
220
+ * else about the packet stays frozen, and `updateRun` still cannot touch it
221
+ * at all.
222
+ *
223
+ * No-ops when the run has no persisted order (pre-schema-v7 rows), when the
224
+ * order does not owe `path`, or when the target already is `version` — so
225
+ * callers can call it unconditionally, and re-stamping is idempotent.
226
+ */
227
+ restampOrderTarget(id: string, path: string, version: number): void;
182
228
  getRun(id: string): RunRow | undefined;
183
- /** How many runs of this step since `sinceMs` (for the daily budget window). */
229
+ /**
230
+ * How many runs of this step since `sinceMs` (for the daily budget window).
231
+ *
232
+ * `released` RUNS ARE EXCLUDED — a lease returned unused is not a firing. See
233
+ * `RunData.outcome` for why this is not the same as `no_work`, which stays
234
+ * counted because the step did run.
235
+ */
184
236
  countRuns(workflow: string, step: string, sinceMs: number): number;
185
- /** The most recent run of this step, if any (for cadence gating). */
237
+ /**
238
+ * The most recent run of this step, if any (for cadence gating).
239
+ *
240
+ * `released` runs are excluded for the same reason `countRuns` excludes them:
241
+ * a lease handed straight back did not fire the step, so it must not restart
242
+ * the cadence clock. Without this a server that claims and releases on every
243
+ * sweep holds a throttled step off indefinitely — each handback pushes the
244
+ * next eligible time further out than the sweep interval that produced it.
245
+ */
186
246
  latestRun(workflow: string, step: string): RunRow | undefined;
187
247
  /**
188
248
  * Count of consecutive trailing `failed` runs for this step+key — the
189
- * crash-step signal. Any closed run that is NOT `failed` (ok/no_work/skipped)
190
- * breaks the streak; still-open runs (outcome NULL) are ignored.
249
+ * crash-step signal. Any closed run that is NOT `failed`
250
+ * (ok/no_work/released/skipped) breaks the streak; still-open runs (outcome
251
+ * NULL) are ignored. `released` breaks it exactly as `no_work` did before the
252
+ * two were split, so the crash-step signal is unchanged by that split.
191
253
  */
192
254
  recentFailedRuns(workflow: string, step: string, key?: string): number;
193
255
  /**