owenloop 0.2.1 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,60 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.3.1](https://github.com/typicalday/owenloop/compare/v0.3.0...v0.3.1) (2026-07-17)
8
+
9
+
10
+ ### Bug Fixes
11
+
12
+ * **ci:** make pack manifest test robust to npm 12 pack --json schema ([#64](https://github.com/typicalday/owenloop/issues/64)) ([25f556d](https://github.com/typicalday/owenloop/commit/25f556df13260a487a182695b3bf38483faccb03))
13
+
14
+ ## [0.3.0](https://github.com/typicalday/owenloop/compare/v0.2.1...v0.3.0) (2026-07-17)
15
+
16
+
17
+ ### Features
18
+
19
+ * **add:** offline crash-recovery via add --recover ([#63](https://github.com/typicalday/owenloop/issues/63)) ([17b1842](https://github.com/typicalday/owenloop/commit/17b1842cd1e2c079ffe6e832c6cbef21e935c5d5))
20
+ * CLI adopts hub parity — whoami-verified auth, server-truth push diff ([#27](https://github.com/typicalday/owenloop/issues/27)) ([e882c70](https://github.com/typicalday/owenloop/commit/e882c7065dcbd91647fce4cd508748fd6700967b))
21
+ * deep tick drives calls: children; surface child stalls on parent status ([#20](https://github.com/typicalday/owenloop/issues/20)) ([b1cc889](https://github.com/typicalday/owenloop/commit/b1cc88935be32429b73d6b1dd123aafab0490cf3))
22
+ * **defs:** auto-discover add-installed workflow defs by default ([#62](https://github.com/typicalday/owenloop/issues/62)) ([cd2d62b](https://github.com/typicalday/owenloop/commit/cd2d62b7b6319c3d51241d2ad488996da394d0ff))
23
+ * **hub:** transport + OAuth origin policy, strict push responses (SEC-2/4, REL-9/10) ([#33](https://github.com/typicalday/owenloop/issues/33)) ([2f5e999](https://github.com/typicalday/owenloop/commit/2f5e999d0a7eed9260b42e813681f9fcd855f3f7))
24
+ * owenloop add <owner>/<repo>[[@ref](https://github.com/ref)] -- install workflow defs from GitHub ([#23](https://github.com/typicalday/owenloop/issues/23)) ([a74ea1c](https://github.com/typicalday/owenloop/commit/a74ea1cc63f0563e3d6a78d7588251280d27e4cc))
25
+ * owenloop login/connect/push/logout — hub onboarding for the CLI ([#24](https://github.com/typicalday/owenloop/issues/24)) ([bedf856](https://github.com/typicalday/owenloop/commit/bedf856c7a5494ea6f16b3d6f39347790198c784))
26
+ * persist issued order packet at claim; add 'owenloop order' read verb ([#30](https://github.com/typicalday/owenloop/issues/30)) ([f77de53](https://github.com/typicalday/owenloop/commit/f77de539db7626f6df9bb5ea7b2a13cc0976a76b))
27
+ * re-home hashDefForHub into hub module, add core/hub boundary lint (0.3.0) ([#29](https://github.com/typicalday/owenloop/issues/29)) ([61f50bc](https://github.com/typicalday/owenloop/commit/61f50bc22adae57a966e0edcd9b33d88931d5010))
28
+ * retain immutable artifact history ([#32](https://github.com/typicalday/owenloop/issues/32)) ([e0dc624](https://github.com/typicalday/owenloop/commit/e0dc624ec79435fc87b2ba82b9fd549687fd5bb7))
29
+ * validate in-memory def sets + hard deep-tick call-depth bound (REL-4) ([#35](https://github.com/typicalday/owenloop/issues/35)) ([ad3564b](https://github.com/typicalday/owenloop/commit/ad3564bdc446d6e228e5ef083464997b9ad668b9))
30
+ * worker-label claim filter and per-step max-lease clamp ([#31](https://github.com/typicalday/owenloop/issues/31)) ([0345044](https://github.com/typicalday/owenloop/commit/034504407fa8b2182b5ada02a3860f6f791d9888))
31
+
32
+
33
+ ### Bug Fixes
34
+
35
+ * **add:** atomic, collision-free, validated installs (REL-1/REL-2/REL-3) ([#40](https://github.com/typicalday/owenloop/issues/40)) ([7904446](https://github.com/typicalday/owenloop/commit/7904446c0175bba61a55ead6d52b1a0c725c4e38))
36
+ * **add:** correct recovery guidance in the park double-fault error message ([#57](https://github.com/typicalday/owenloop/issues/57)) ([571824e](https://github.com/typicalday/owenloop/commit/571824ef3b53abcd38ae6994923cc290a9f56e8c))
37
+ * **add:** crash-recovery journal so an interrupted install rolls forward or back to a consistent state ([#56](https://github.com/typicalday/owenloop/issues/56)) ([79aa875](https://github.com/typicalday/owenloop/commit/79aa8752fc024a6641cee35e50bf2d32947913fd))
38
+ * **add:** make directory commit + lockfile write one recoverable operation ([#46](https://github.com/typicalday/owenloop/issues/46)) ([7c43fef](https://github.com/typicalday/owenloop/commit/7c43fef6dc698a65b5e4f533dd42cf91f42d84fa))
39
+ * **add:** park old-name dir inside the rollback envelope; stop cleanup masking rename error ([#48](https://github.com/typicalday/owenloop/issues/48)) ([74bea2b](https://github.com/typicalday/owenloop/commit/74bea2b0ff2136d627c0e69a16b64a8b85d20b48))
40
+ * atomic child creation and transactional, order-checked store open (REL-5) ([#37](https://github.com/typicalday/owenloop/issues/37)) ([59119d2](https://github.com/typicalday/owenloop/commit/59119d276080946690182b0971e2f281d5783fa4))
41
+ * **calls:** atomic fresh-snapshot child provision (C2 creation-side isolation) ([#59](https://github.com/typicalday/owenloop/issues/59)) ([e6e951c](https://github.com/typicalday/owenloop/commit/e6e951ca5dc51730c0bc16abceef24560e602edf))
42
+ * CLI nits from PR [#25](https://github.com/typicalday/owenloop/issues/25) review — NaN flag guard, timeout message, stale comment ([#26](https://github.com/typicalday/owenloop/issues/26)) ([e438dcb](https://github.com/typicalday/owenloop/commit/e438dcb7b9709dcd31338565172caebeede5e5d9))
43
+ * **cli:** reject unknown options before any side effect ([#60](https://github.com/typicalday/owenloop/issues/60)) ([73fea0c](https://github.com/typicalday/owenloop/commit/73fea0cd485f0965b517dd12cdbd1ef3a793b3b6))
44
+ * credential backend authority, hub/auth deadlines, atomic symlink-refusing writes (REL-6/REL-7/SEC-3) ([#39](https://github.com/typicalday/owenloop/issues/39)) ([f71853b](https://github.com/typicalday/owenloop/commit/f71853b0893415c8d578b847262180a5b8d861b1))
45
+ * **engine:** atomic snapshot-and-commit for maintainCalls machine-green (cross-connection stale publish) ([#52](https://github.com/typicalday/owenloop/issues/52)) ([a496620](https://github.com/typicalday/owenloop/commit/a496620f1d79ae673327922f30a5c52062c9f439))
46
+ * **engine:** guard deep-tick calls: descent against cross-connection races ([#61](https://github.com/typicalday/owenloop/issues/61)) ([6867beb](https://github.com/typicalday/owenloop/commit/6867beb606c8c9a521c920e898384d67bdf0386f))
47
+ * **engine:** make max-lease cap opt-in; distinguish reap reasons (REL-8) ([#38](https://github.com/typicalday/owenloop/issues/38)) ([074fb5e](https://github.com/typicalday/owenloop/commit/074fb5e6a58248d172320fdf38f22418a13fe6b4))
48
+ * guard status child summary against unresolvable child def; test dueAt min-fold ([#22](https://github.com/typicalday/owenloop/issues/22)) ([cb7ccd2](https://github.com/typicalday/owenloop/commit/cb7ccd2404f7477ed38d596321ec032c2e3756b5))
49
+ * hub CLI hardening — portable push hash, boolean-flag parse, login timeout ([#25](https://github.com/typicalday/owenloop/issues/25)) ([c36e1b6](https://github.com/typicalday/owenloop/commit/c36e1b6d67a425c0af42b99b705e603f68aaad46))
50
+ * **security:** contain bodyFile resolution and bound archive extraction in add (SEC-1) ([#34](https://github.com/typicalday/owenloop/issues/34)) ([6d8ccfa](https://github.com/typicalday/owenloop/commit/6d8ccfac2cc92164fe6f0548a038423d983e2ca9))
51
+ * **security:** enforce response-size caps during download with a bounded streaming reader ([#54](https://github.com/typicalday/owenloop/issues/54)) ([47f8096](https://github.com/typicalday/owenloop/commit/47f8096cec701204094009421cde48ae4f3694e6))
52
+ * **security:** fail closed on uncorroborated add.journal crash recovery ([#58](https://github.com/typicalday/owenloop/issues/58)) ([d9a1890](https://github.com/typicalday/owenloop/commit/d9a1890d1933d274cf1b77c6f5e7f4e38f921c2a))
53
+ * **security:** ownership-token install lock with liveness-aware stale reclamation ([#55](https://github.com/typicalday/owenloop/issues/55)) ([647d008](https://github.com/typicalday/owenloop/commit/647d00893ef6f023c6d4126ce96ef230ea97b15f))
54
+ * **security:** refuse a symlinked .owenloop and default defs dir in add (SEC-3) ([#53](https://github.com/typicalday/owenloop/issues/53)) ([5bc96b1](https://github.com/typicalday/owenloop/commit/5bc96b17cf6fec6b771fbfc955af7443852afa79))
55
+ * **security:** refuse a symlinked default state.db and its SQLite sidecars (SEC-3 file-level) ([#49](https://github.com/typicalday/owenloop/issues/49)) ([0a54a2f](https://github.com/typicalday/owenloop/commit/0a54a2fa4eb153f9de7d05a21cf5211fba3b76a0))
56
+ * **security:** refuse a symlinked project .owenloop on state writes (SEC-3) ([#47](https://github.com/typicalday/owenloop/issues/47)) ([033bdef](https://github.com/typicalday/owenloop/commit/033bdef7c54b331aae28b0b0c47e5f4c6662dc0d))
57
+ * **security:** refuse HTTP redirects on all hub/auth requests ([#50](https://github.com/typicalday/owenloop/issues/50)) ([70617bc](https://github.com/typicalday/owenloop/commit/70617bc4e188339c39a12b5d1bc7df4c1cfcaea1))
58
+ * **security:** validate and contain installed.json paths before any filesystem operation ([#51](https://github.com/typicalday/owenloop/issues/51)) ([4496aa5](https://github.com/typicalday/owenloop/commit/4496aa5ea8573f6cec3277ffbc26f4b45e4dfbf9))
59
+ * **store:** deterministic legacy-child lookup + structural artifact change-detection ([#45](https://github.com/typicalday/owenloop/issues/45)) ([2350793](https://github.com/typicalday/owenloop/commit/235079347fc6d7cccc9c12da214ebdaab6cc36ae))
60
+
7
61
  ## [0.2.1](https://github.com/typicalday/owenloop/compare/v0.2.0...v0.2.1) (2026-07-04)
8
62
 
9
63
 
package/README.md CHANGED
@@ -295,7 +295,9 @@ looks like:
295
295
  - **Your own harness** — a `while` loop, a cron job, a CI stage: tick, run
296
296
  each order with whatever executes your work (an agent CLI, an API call, a
297
297
  script), report, repeat. Fully deterministic dispatch if you want it —
298
- see [Embedding it](#embedding-it) for the in-process version.
298
+ see [Embedding it](#embedding-it) for the in-process version. A reference
299
+ dispatcher/conductor, owenwork, is available separately — the engine core
300
+ ships no host harness of its own.
299
301
  - **An agent as the orchestrator** — point any tool-using agent (Claude Code,
300
302
  Codex, Gemini CLI, anything that can run a shell command) at the CLI and
301
303
  tell it to drive the instance to done. A slash command or skill that wraps
@@ -339,8 +341,8 @@ definition, then conducts the instance to done — dispatching each order to a
339
341
  fresh subagent, relaying knock-backs, and escalating stalls to you. Already
340
342
  have a def? *"Conduct the report workflow"* hands it to
341
343
  [`owenloop-conduct`](skills/owenloop-conduct/SKILL.md). The engine itself
342
- arrives via `npx owenloop` — no clone, no build, no environment variables, no
343
- CLI verbs to memorize.
344
+ arrives via `npx owenloop` (Node ≥ 22.13 required) — no clone, no build, no
345
+ environment variables, no CLI verbs to memorize.
344
346
 
345
347
  **Want to see or drive the machinery yourself?** Everything above goes
346
348
  through the same small CLI (`create`, `tick`, `green`, `reject`, …).
@@ -354,13 +356,31 @@ collections-heavy research pipeline
354
356
  [`docs/authoring.md`](docs/authoring.md). Driving it from your own code:
355
357
  [Embedding it](#embedding-it).
356
358
 
359
+ Want someone else's workflow defs instead of writing your own?
360
+ `owenloop add <owner>/<repo>` fetches a public GitHub repo's `workflows/**`,
361
+ validates every def, and installs them locally with pinned provenance — see
362
+ the `add` entry in [`docs/cli.md`](docs/cli.md). An installed def's steps later
363
+ run with your workers' full privileges and owenloop never executes them itself,
364
+ so install only sources you trust, and pin a commit SHA (`@<sha>`) for anything
365
+ you re-add — the [trust model](docs/cli.md#add--installing-shared-workflow-defs-from-github)
366
+ is spelled out there.
367
+
368
+ Publishing your defs to a hosted hub instead? `owenloop login` authenticates
369
+ the CLI (loopback OAuth, or a pasted token via `--with-token`; the credential
370
+ goes into the macOS Keychain or a `0600` file, never the repo, and is verified
371
+ against the hub before it's ever stored), `owenloop connect` binds the project
372
+ to a hub, and `owenloop push` publishes your defs — idempotent against the
373
+ hub's own def hashes, so an unchanged re-push is a no-op. See the
374
+ [Hub](docs/cli.md#hub-login--connect--push--logout) section in `docs/cli.md`.
375
+
357
376
  ---
358
377
 
359
378
  ## Requirements
360
379
 
361
380
  - **Node ≥ 22.13.** Storage is Node's built-in `node:sqlite`, which is available
362
381
  unflagged from 22.13 onward (it still prints an experimental warning until it
363
- stabilises in Node 24.15 / 25.7). owenloop is an ESM-only package.
382
+ stabilises in Node 24.15 / 25.7). owenloop is an ESM-only package. CI runs the
383
+ full check on Node 22 (active LTS) and 24 (current).
364
384
  - **No native dependencies.** `node:sqlite` is built in, so there's nothing to
365
385
  compile. The only runtime deps are `yaml` (parsing defs) and
366
386
  `@cfworker/json-schema` (optional per-artifact schema validation).
@@ -375,6 +395,45 @@ import { createEngine } from 'owenloop'; // see "Embedding it" below
375
395
 
376
396
  ---
377
397
 
398
+ ## Upgrading from 0.2.1
399
+
400
+ Upgrading a project from the 0.2.1 release pulls in everything that has landed
401
+ since. The changes that need operator or embedder attention:
402
+
403
+ - **Deep recursive ticking.** One `tick` now advances the whole `calls:` tree
404
+ by default, so a single call can drive many workflow instances at once and
405
+ their execution timing shifts. Embedders that key per-workflow logic —
406
+ checkpoints, transactions, counters — must key on `order.workflow`, not the
407
+ id passed to `tick` (`--shallow` / `{ deep: false }` is the single-instance
408
+ escape hatch). See
409
+ [Migrating from shallow ticking](docs/embedding.md#the-worker-step) and
410
+ [Deep tick and `order.workflow`](docs/cli.md#what-a-job-looks-like); the full
411
+ guidance lives there.
412
+ - **Node ≥ 22.13 required.** The `engines` field pins Node ≥ 22.13, and CI runs
413
+ the full check on Node 22 and 24 — see [Requirements](#requirements) just
414
+ above.
415
+ - **Database schema v9.** The first open by a new binary migrates the database
416
+ in a single transaction that rolls back on failure; a database whose stored
417
+ version is newer than the binary is refused rather than opened. Migrated
418
+ databases do **not** get backfilled artifact-history payload snapshots —
419
+ durable payload history begins after migration (legacy lifecycle reasons are
420
+ carried over exactly once). Copy the SQLite database (`.owenloop/state.db`
421
+ plus its `-wal`/`-shm` sidecars) before upgrading; downgrading means
422
+ restoring that copy, because an older binary refuses a v9 database.
423
+ - **New retained plaintext data.** Issued order packets and artifact history
424
+ now persist in the database, so rotating and disposing of that data is the
425
+ operator's job — see [Retention and disposal](#storage).
426
+ - **New network-facing commands and credential storage.** `owenloop login` /
427
+ `connect` / `push` (and `add`, for installing shared defs) reach the network
428
+ and store a credential in the macOS Keychain or a `0600` file — see the
429
+ [Hub](docs/cli.md#hub-login--connect--push--logout) section and the `add`
430
+ [trust model](docs/cli.md#add--installing-shared-workflow-defs-from-github).
431
+ - **Max-lease cap is now opt-in.** There is no default lease ceiling; anyone who
432
+ relied on the brief post-0.2.1 default cap must set `maxLeaseMs` (or a
433
+ per-step `maxLease`) explicitly.
434
+
435
+ ---
436
+
378
437
  ## Embedding it
379
438
 
380
439
  The CLI is a thin adapter: it maps `argv` to engine calls and prints JSON. The engine
@@ -449,6 +508,16 @@ is rejected ("born-rejected") if any of those inputs moved underneath it. Each a
449
508
  carries a monotonic version, so the engine can always ask "is this green output still
450
509
  resting on the inputs it was built from?".
451
510
 
511
+ **Retention and disposal.** That file is the system of record and it keeps
512
+ everything: every artifact version's value and every run's issued order packet —
513
+ including any sensitive values that flowed through an input — persist after a
514
+ workflow finishes. The default location is `.owenloop/state.db` (plus its WAL
515
+ `-wal`/`-shm` sidecar files), or wherever `--db` / `OWENLOOP_DB` / the `db:`
516
+ embed option points. Rotating or scrubbing that data is the operator's job:
517
+ `owenloop delete <wf>` removes an instance's rows, but SQLite frees those pages
518
+ without erasing or shrinking the file on disk, so for reliable disposal delete
519
+ the database file together with its `-wal`/`-shm` sidecars.
520
+
452
521
  ## Testing
453
522
 
454
523
  ```sh
@@ -458,19 +527,19 @@ npm run check # both
458
527
  npm run build # compile src/ → dist/ (also runs automatically on npm pack/publish)
459
528
  ```
460
529
 
461
- The suite is **579 tests**: unit tests (`paths`, `store`, `model`, `defs`, `schema`,
530
+ The suite spans unit tests (`paths`, `store`, `model`, `defs`, `schema`,
462
531
  `util`, `cli`), engine integration tests (the cascade, the stall, schema validation,
463
532
  the concurrency check, `judges:` sign-off/CAS/throttling in `test/judges.test.ts`),
464
533
  and end-to-end tests that spawn the real `bin/owenloop.mjs` binary and drive the
465
534
  example workflows through their full lifecycles.
466
535
 
467
536
  Two e2e files carry most of the weight, by opposite intent.
468
- [`test/edge.e2e.test.ts`](test/edge.e2e.test.ts) is a 26-case edge battery aimed at the
537
+ [`test/edge.e2e.test.ts`](test/edge.e2e.test.ts) is an edge battery aimed at the
469
538
  corners the design is most particular about: cascade invalidation, terminal completion
470
539
  surviving an upstream reject, empty / fully-retracted collections, the commit check,
471
540
  cadence and daily-budget gating, the skip-cascade, and CLI robustness against malformed
472
541
  input. [`test/scenarios.e2e.test.ts`](test/scenarios.e2e.test.ts) takes the opposite
473
- tack — eight multi-step *positive* stories that confirm the documented behaviors hold
542
+ tack — multi-step *positive* stories that confirm the documented behaviors hold
474
543
  end to end: the map `parallel` cap, map and reduce firing as concurrent branches, the
475
544
  reason thread riding the next job, stall → retry → re-stall, and the cascade re-firing on
476
545
  a re-provided input while leaving a healthy graph and a terminal output untouched.
package/bin/owenloop.mjs CHANGED
@@ -2,6 +2,6 @@
2
2
  // Thin shim: all real logic lives in src/cli.ts (so it stays testable) and is
3
3
  // shipped compiled to dist/cli.js. Node cannot type-strip files under
4
4
  // node_modules, so the published package runs plain JS, not TypeScript source.
5
- import { main } from '../dist/cli.js';
5
+ import { mainAsync } from '../dist/cli.js';
6
6
 
7
- process.exit(main(process.argv.slice(2)));
7
+ mainAsync(process.argv.slice(2)).then((code) => process.exit(code));
package/dist/add.d.ts ADDED
@@ -0,0 +1,412 @@
1
+ /**
2
+ * Pure helpers for the `owenloop add <owner>/<repo>[@ref]` CLI verb (workflow
3
+ * distribution Stage 1 — see the design doc this implements,
4
+ * `docs/workflow-distribution.md` §3 in the companion hub repo).
5
+ *
6
+ * These are the network-free, filesystem-adjacent pieces: spec parsing, URL
7
+ * building, lockfile read/write, and file installation. The network fetch and
8
+ * arg glue live in `src/cli.ts` (`dispatchAdd`) so this module stays trivially
9
+ * unit-testable and `cli.ts` doesn't widen its export surface just to reuse
10
+ * `Args`/`CliError`/etc.
11
+ */
12
+ /**
13
+ * Returns `undefined` if `relPath` is safe to `join()` under a destination
14
+ * directory, else a human-readable reason it must be rejected. This is
15
+ * reject-don't-normalize: a synthetic archive entry like
16
+ * `workflows/../../victim` is refused outright, never canonicalized into a
17
+ * "safe" path. Part of SEC-1 — an unnormalized entry name must never escape
18
+ * the staging or install directory.
19
+ */
20
+ export declare function archivePathViolation(relPath: string): string | undefined;
21
+ /**
22
+ * Returns `undefined` if `relPath` is a safe SINGLE-SEGMENT lockfile install
23
+ * path, else a human-readable reason it must be rejected. Stricter than
24
+ * {@link archivePathViolation}: a lockfile entry's `path` is one on-disk path
25
+ * segment by construction — both the current `<owner>-<repo>-<hash>` scheme and
26
+ * the only legacy scheme this tool ever wrote (`<owner>-<repo>`, see
27
+ * {@link installFolder}) — so ANY separator is refused outright. That single
28
+ * rule makes `..` traversal, `.owenloop/../../x`, and nested escape shapes
29
+ * unrepresentable before any `join`/`rename` ever touches the path. Like
30
+ * `archivePathViolation` this is reject-don't-normalize: a bad path is refused,
31
+ * never canonicalized into a "safe" one.
32
+ */
33
+ export declare function lockfilePathViolation(relPath: string): string | undefined;
34
+ export interface RepoSpec {
35
+ owner: string;
36
+ repo: string;
37
+ ref: string;
38
+ }
39
+ /** Parse `owner/repo` or `owner/repo@ref` into its parts; `ref` defaults to `'HEAD'`. */
40
+ export declare function parseRepoSpec(spec: string): RepoSpec;
41
+ /**
42
+ * The single-path-segment install folder for a package, derived from its
43
+ * `owner/repo` identity: `<owner>-<repo>-<sha256(owner/repo)[:8]>`. The 8-hex
44
+ * suffix makes the (owner,repo)→folder mapping injective in practice — the old
45
+ * `<owner>-<repo>` scheme collided (`a-b/c` and `a/b-c` both mapped to
46
+ * `a-b-c`, and the second install clobbered the first). Keying on the source
47
+ * (matching the lockfile key) keeps the folder STABLE across versions, so a
48
+ * user's documented `--defs workflows/<folder>` pointer survives upgrades.
49
+ */
50
+ export declare function installFolder(owner: string, repo: string): string;
51
+ export declare function githubShaUrl(owner: string, repo: string, ref: string): string;
52
+ export declare function githubTarballUrl(owner: string, repo: string, sha: string): string;
53
+ /**
54
+ * One installed-package record. `path` is a single on-disk folder segment (see
55
+ * {@link lockfilePathViolation}); `sha` is a 40-char hex commit sha; `source`
56
+ * equals the record's key in {@link Lockfile.installed}. These invariants are
57
+ * NOT trusted from disk — {@link validateLockfile} enforces every one on read,
58
+ * fail-closed, before any consumer acts on an entry.
59
+ */
60
+ export interface InstalledEntry {
61
+ source: string;
62
+ ref: string;
63
+ sha: string;
64
+ installedAt: number;
65
+ path: string;
66
+ files: string[];
67
+ }
68
+ export interface Lockfile {
69
+ version: 1;
70
+ installed: Record<string, InstalledEntry>;
71
+ }
72
+ /**
73
+ * Structurally validate a parsed `installed.json`, fail-closed. A
74
+ * parseable-but-schema-invalid lockfile is a hard error naming the offending
75
+ * entry+field — never silently reset to `{}` (which would erase ownership
76
+ * records and re-enable the clobbering {@link installFolder} was hardened
77
+ * against) and never normalized. This is the trust boundary for the lockfile:
78
+ * downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
79
+ * that have passed through here. Critically, EVERY entry is validated, not just
80
+ * the one being installed — `dispatchAdd` re-serializes the whole lockfile on
81
+ * success, so acting while carrying a poisoned sibling entry would re-persist
82
+ * it. Unknown extra keys (on the lockfile or an entry) are tolerated for
83
+ * forward compatibility; required shape is enforced, additions are not
84
+ * forbidden. Returns the value narrowed to {@link Lockfile}. `path` appears
85
+ * only in error messages.
86
+ */
87
+ export declare function validateLockfile(parsed: unknown, path: string): Lockfile;
88
+ /**
89
+ * Read `.owenloop/installed.json`; a missing file is an empty lockfile, not an
90
+ * error. A file that exists but does not parse is a hard error naming the path
91
+ * — never silently reset to `{}`, which would erase ownership records and
92
+ * re-enable the clobbering `installFolder` was hardened against. A file that
93
+ * parses but is structurally invalid (bad version, malformed entry, a `path`
94
+ * that is not a safe single segment, a bad `sha`/`files`) is likewise a
95
+ * fail-closed hard error — see {@link validateLockfile}. The lockfile is never
96
+ * trusted for filesystem paths.
97
+ */
98
+ export declare function readLockfile(path: string): Lockfile;
99
+ /**
100
+ * Write the lockfile atomically: serialize into a sibling temp file, then
101
+ * `renameSync` over the destination. A crash or a concurrent reader never sees
102
+ * a half-written `installed.json` (rename is atomic within a directory), and
103
+ * two racing writers can only ever leave a fully-formed file.
104
+ *
105
+ * If the final `renameSync` throws (EACCES, EISDIR on `path`, a full disk),
106
+ * the temp sibling is removed on a best-effort basis before the error
107
+ * propagates so a failed write cannot leak an `installed.json.tmp.<pid>` file.
108
+ * The original rename error is surfaced unchanged — never swallowed, and never
109
+ * masked by a failure of that cleanup removal (if the removal itself throws,
110
+ * that error is swallowed and the tmp sibling may remain in that double fault).
111
+ */
112
+ export interface WriteLockfileOpts {
113
+ /**
114
+ * Removal op used to clean up the temp sibling when the atomic rename fails.
115
+ * Defaults to `rmSync`; injectable so a test can force the cleanup itself to
116
+ * throw and prove the ORIGINAL rename error still surfaces — the same
117
+ * test-determinism seam as `AcquireLockOpts` in this file.
118
+ */
119
+ rm?: (path: string, opts: {
120
+ force: true;
121
+ }) => void;
122
+ }
123
+ export declare function writeLockfile(path: string, lf: Lockfile, opts?: WriteLockfileOpts): void;
124
+ /** The staging root under a defs dir where installs are assembled + validated. */
125
+ export declare const STAGING_DIRNAME = ".owenloop-staging";
126
+ /**
127
+ * Write `files` (relative path → bytes) into `targetDir` (a staging dir), NOT
128
+ * the final install destination. Unlike a direct install, this never clears a
129
+ * live folder: the caller stages here, validates, then `commitInstall`s with an
130
+ * atomic rename, so a failure mid-write can only ever corrupt throwaway staging
131
+ * content. Returns the sorted list of relative paths written.
132
+ */
133
+ export declare function stageFiles(targetDir: string, files: Map<string, Uint8Array>): string[];
134
+ /**
135
+ * Thrown by `commitInstall` when the atomic swap fails AND the rollback of it
136
+ * fails too — a near-impossible same-filesystem double-fault. Carries the path
137
+ * where the previous version was left so the caller can preserve it (its
138
+ * `preservedAt` sits under the staging root, which the caller would otherwise
139
+ * clean up as debris). A distinguishable type so the caller can tell this
140
+ * "must-preserve" double-fault apart from an ordinary swap failure.
141
+ */
142
+ export declare class RollbackFailedError extends Error {
143
+ readonly preservedAt: string;
144
+ constructor(message: string, preservedAt: string);
145
+ }
146
+ /**
147
+ * A handle to a committed-but-not-yet-finalized install, returned by
148
+ * `commitInstall`. The install directory already holds the NEW content, but the
149
+ * displaced previous install (and any migrated old-name dir) are RETAINED under
150
+ * the staging root — not yet discarded — so the caller can still roll the
151
+ * directory state back if a later step (the lockfile write) fails. The caller
152
+ * MUST eventually either `finalizeInstallCommit` (discard the retained dirs) or
153
+ * `rollbackInstallCommit` (restore the previous state). All retained/undo paths
154
+ * derive from `stagingDir`, so they live under `<defsDir>/.owenloop-staging/` —
155
+ * same filesystem (renames stay atomic), and the staging-root cleanup covers
156
+ * them.
157
+ */
158
+ export interface InstallCommitHandle {
159
+ /** `defsDir/folder` — now holding the NEW content. */
160
+ dest: string;
161
+ /** `${stagingDir}-old` — the displaced previous dest, if one existed. */
162
+ backupDir?: string;
163
+ /** `${stagingDir}-undo` — where a rollback parks the new content before restoring. */
164
+ undoDir: string;
165
+ /** Set by `parkOldNameDir` when an old-naming dir was migrated off. */
166
+ oldName?: {
167
+ originalPath: string;
168
+ parkedAt: string;
169
+ };
170
+ }
171
+ /**
172
+ * Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
173
+ * rolling back to the previous install if the swap itself fails. Both dirs live
174
+ * on the same filesystem by construction (staging is under `defsDir`), so the
175
+ * renames are atomic and `EXDEV` is impossible.
176
+ *
177
+ * Two-phase commit: unlike a one-shot swap, this does NOT delete the displaced
178
+ * previous install on success — it returns an {@link InstallCommitHandle} whose
179
+ * `backupDir` still holds it. The caller must then either
180
+ * {@link finalizeInstallCommit} (discard the backup, making the swap permanent)
181
+ * once its follow-on work — the lockfile write — has durably succeeded, or
182
+ * {@link rollbackInstallCommit} to restore the previous directory state if that
183
+ * work fails. This is what lets "commit the directory + write the lockfile" be
184
+ * one recoverable operation.
185
+ *
186
+ * Sequence: back up any existing install (rename dest → `<stagingDir>-old`) — if
187
+ * that fails nothing has changed; rename staging → dest; on failure rename the
188
+ * backup back (throwing {@link RollbackFailedError} if even that fails, so the
189
+ * caller can preserve the named copy).
190
+ */
191
+ export declare function commitInstall(defsDir: string, folder: string, stagingDir: string): InstallCommitHandle;
192
+ /**
193
+ * Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
194
+ * (rename → `<stagingDir>-undo-oldname`) instead of deleting it, so a later
195
+ * rollback can put it back where the (still-unchanged) lockfile expects it.
196
+ * Records the move on `handle.oldName`. If the old dir does not exist on disk
197
+ * (the lockfile names a path that is already gone), records nothing — matching
198
+ * the previous `rmSync(..., { force: true })` tolerance of absence.
199
+ *
200
+ * Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
201
+ * the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
202
+ * segment, the authoritative containment check is re-asserted HERE, at the
203
+ * mutation site, before any rename — a poisoned `existing.path` must never move
204
+ * a directory outside `defsDir` (which `finalizeInstallCommit` would then
205
+ * recursively delete). Following this project's TOCTOU discipline, the check
206
+ * that matters is the one at the filesystem operation, not only up front:
207
+ * `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
208
+ * target must be a real directory — a symlink at the legacy path is refused (a
209
+ * symlinked segment must never be parked/finalized, since finalize deletes it).
210
+ * Deliberate behavior change vs. the old `existsSync` probe: a DANGLING symlink
211
+ * at the old path was previously silently ignored (existsSync follows links);
212
+ * it is now refused, which is fail-closed and correct.
213
+ */
214
+ export declare function parkOldNameDir(handle: InstallCommitHandle, defsDir: string, oldRelPath: string): void;
215
+ /**
216
+ * Make the commit permanent: discard the retained previous install and any
217
+ * parked old-name dir. Call ONLY after the follow-on lockfile write has durably
218
+ * succeeded — this is the point of no return.
219
+ */
220
+ export declare function finalizeInstallCommit(handle: InstallCommitHandle): void;
221
+ /**
222
+ * Undo a `commitInstall` (plus any `parkOldNameDir`), restoring the pre-commit
223
+ * directory state. Order matters:
224
+ * 1. park the new content out of `dest` (rename dest → undoDir) — for a fresh
225
+ * install, this alone restores "nothing installed";
226
+ * 2. if a previous install was displaced, rename its backup back over `dest`;
227
+ * 3. if an old-name dir was parked, rename it back to where the lockfile says.
228
+ * The parked new content under `undoDir` is left for the caller's staging-root
229
+ * cleanup to dispose of. Any throw propagates to the caller.
230
+ *
231
+ * Safe to call from a FAILED `parkOldNameDir`: that helper records
232
+ * `handle.oldName` only after its single rename succeeds, so a park failure
233
+ * leaves `oldName` unset and step 3 self-skips — there is no "park partially
234
+ * happened" state to reconcile (the park is one atomic rename).
235
+ */
236
+ export declare function rollbackInstallCommit(handle: InstallCommitHandle): void;
237
+ export interface InstallLockHandle {
238
+ lockPath: string;
239
+ acquired: boolean;
240
+ /** Per-acquisition ownership token — present when `acquired`; proof of ownership for release. */
241
+ token?: string;
242
+ }
243
+ export interface AcquireLockOpts {
244
+ /** Max time to wait for a live lock before failing cleanly (default 10s). */
245
+ waitMs?: number;
246
+ /**
247
+ * Age (by mtime) past which an *unparseable/abandoned* lock may be reclaimed
248
+ * (default 10m). Age NEVER reclaims a lock whose recorded pid is alive on
249
+ * this host — it only governs the fail-closed fallback for a lock we cannot
250
+ * attribute to a live owner (unparseable payload, or one without a pid).
251
+ */
252
+ staleMs?: number;
253
+ /** Poll interval while waiting on a live lock (default 100ms). */
254
+ pollMs?: number;
255
+ /** Liveness probe for the holder pid — injectable so tests are deterministic. */
256
+ isPidAlive?: (pid: number) => boolean;
257
+ /** Clock — injectable so tests are deterministic. */
258
+ now?: () => number;
259
+ /** Current hostname — injectable so cross-host tests are deterministic (default `os.hostname`). */
260
+ hostname?: () => string;
261
+ }
262
+ /**
263
+ * Acquire the per-project install lock at `lockPath` (an exclusive-create of the
264
+ * file, `openSync(..,'wx')` — the O_EXCL create is the real serialization point).
265
+ * The payload carries an ownership token, the owner pid, a start timestamp, and
266
+ * the host. If another process holds it: reclaim it only when liveness-aware
267
+ * staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
268
+ * frees, and if it does not free within `waitMs` fail cleanly with a clear
269
+ * in-progress message. Always pair with `releaseInstallLock` in a `finally`.
270
+ */
271
+ export declare function acquireInstallLock(lockPath: string, opts?: AcquireLockOpts): Promise<InstallLockHandle>;
272
+ /**
273
+ * Release a lock acquired by `acquireInstallLock`. Token-checked and
274
+ * best-effort: a no-op if not acquired, if the lock is already gone/unparseable,
275
+ * or if its token no longer matches this handle (someone else legitimately
276
+ * re-acquired it — deleting would steal *their* lock). Never throws; it runs in
277
+ * `dispatchAdd`'s `finally` and must not mask the real error.
278
+ */
279
+ export declare function releaseInstallLock(handle: InstallLockHandle): void;
280
+ /** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
281
+ export declare const ADD_JOURNAL_FILENAME = "add.journal";
282
+ /**
283
+ * The two durable phases an in-flight install can be caught in. Absent (no
284
+ * file) is the third, happy state. Deliberately coarse — every extra journal
285
+ * rewrite is itself a crash window, and each install step is a single atomic
286
+ * rename, so directory existence/absence recovers the fine-grained progress the
287
+ * two phases don't record.
288
+ *
289
+ * - `applying`: written after staging+validation succeed, immediately before
290
+ * `commitInstall`. The ledger write (the documented commit point) has NOT yet
291
+ * happened, so recovery rolls BACK — unless the ledger turns out to already
292
+ * match (a crash in the tiny writeLockfile→rewrite window), in which case it
293
+ * rolls forward.
294
+ * - `finalizing`: written immediately after the ledger write succeeds, before
295
+ * `finalizeInstallCommit`. The commit point has passed, so recovery rolls
296
+ * FORWARD (finishes discarding the retained backup + parked old-name dir).
297
+ */
298
+ export type AddJournalPhase = 'applying' | 'finalizing';
299
+ /**
300
+ * One crash-recovery journal record. `folder`, `stagingId`, and `oldNamePath`
301
+ * are single on-disk path segments (each {@link lockfilePathViolation}-checked
302
+ * on read); `defsDir` is compared for equality ONLY and is never joined into a
303
+ * mutation path; `ref`/`startedAt` are diagnostics. These invariants are NOT
304
+ * trusted from disk — {@link validateAddJournal} enforces every one, fail-closed.
305
+ */
306
+ export interface AddJournal {
307
+ version: 1;
308
+ phase: AddJournalPhase;
309
+ /** Ledger key of the source being installed — for the ledger-match check. */
310
+ source: string;
311
+ /** 40-char hex commit sha being installed — for the ledger-match check. */
312
+ sha: string;
313
+ /** Install folder segment (`dest = join(defsDir, folder)`). Single segment. */
314
+ folder: string;
315
+ /** Basename of this run's staging dir (`stg_<hex>`). Single segment. */
316
+ stagingId: string;
317
+ /** Did `dest` exist when the journal was written (⇒ a backup dir will exist)? */
318
+ hadDest: boolean;
319
+ /** Set only for an old-name (`<owner>-<repo>`) migration. Single segment. */
320
+ oldNamePath?: string;
321
+ /** Resolved defs dir at journal-write time — equality-checked, never joined. */
322
+ defsDir: string;
323
+ /** The `@ref` this install pinned — diagnostics only. */
324
+ ref: string;
325
+ /** Journal-write epoch ms — diagnostics only. */
326
+ startedAt: number;
327
+ }
328
+ /**
329
+ * Structurally validate a parsed `add.journal`, fail-closed — the trust
330
+ * boundary for the journal, mirroring {@link validateLockfile}. A
331
+ * parseable-but-invalid journal is a hard error naming the file and the manual
332
+ * remedy; recovery NEVER acts on a field that has not passed through here. Every
333
+ * path field must be a safe single segment so a crafted journal cannot represent
334
+ * traversal before any `join`/`rename`. Unknown extra keys are tolerated
335
+ * (forward compatibility, same as the lockfile). `ref`/`startedAt` are
336
+ * diagnostics: validated for type when present, but not required. `path`
337
+ * appears only in error messages.
338
+ */
339
+ export declare function validateAddJournal(parsed: unknown, path: string): AddJournal;
340
+ /**
341
+ * Read `.owenloop/add.journal`. Absent ⇒ `null` (the happy path — no
342
+ * interrupted install to recover). Present-but-unparseable ⇒ a hard error;
343
+ * present-but-schema-invalid ⇒ a hard error via {@link validateAddJournal}.
344
+ * Never silently ignores a malformed journal (that would let a crafted file
345
+ * quietly disable recovery) and never trusts it for filesystem paths.
346
+ */
347
+ export declare function readAddJournal(path: string): AddJournal | null;
348
+ /** Write the journal atomically (tmp+rename), same discipline as the lockfile. */
349
+ export declare function writeAddJournal(path: string, journal: AddJournal, opts?: WriteLockfileOpts): void;
350
+ /** Remove the journal (force: absence is not an error — clean-completion / idempotent). */
351
+ export declare function removeAddJournal(path: string): void;
352
+ export interface RecoverInterruptedInstallArgs {
353
+ /** The CURRENT run's resolved defs dir — every mutation path derives from it. */
354
+ defsDir: string;
355
+ /** Path to `.owenloop/add.journal`. */
356
+ journalPath: string;
357
+ /** Path to `.owenloop/installed.json` — read to decide the commit-point boundary. */
358
+ lockfilePath: string;
359
+ }
360
+ /**
361
+ * What `recoverInterruptedInstall` DID, for callers (the offline `add --recover`
362
+ * entry point) that report the result to the user. A refusal is NOT an outcome —
363
+ * it throws. `'rolled-back'` collapses the roll-back table's terminal arms,
364
+ * including the touch-nothing / already-consistent ones (distinguishing
365
+ * "restored" from "was already consistent" per arm would thread state through
366
+ * the decision table for message cosmetics only).
367
+ */
368
+ export type RecoveryOutcome = 'no-journal' | 'rolled-forward' | 'rolled-back';
369
+ /**
370
+ * Bring an interrupted install back to a consistent (defs ⇔ ledger) state, then
371
+ * remove the journal. Called by `dispatchAdd` under the A3 install lock,
372
+ * BEFORE the stale-staging cleanup (the backups a rollback needs live under the
373
+ * staging root). No journal ⇒ returns immediately (happy path unchanged).
374
+ *
375
+ * Roll-forward vs roll-back rule: the durable ledger write is the commit point.
376
+ * At or past it, roll FORWARD (finish the discard); before it, roll BACK
377
+ * (restore the previous state). Concretely:
378
+ *
379
+ * 1. `finalizing` ⇒ roll forward: the ledger is durably new; only finalize's
380
+ * discards may be missing. Clear the retained backup + parked old-name and
381
+ * the staging root. Trivially idempotent.
382
+ * 2. `applying` + the ledger already records this source at `journal.sha`/
383
+ * `journal.folder` ⇒ the commit MAY have landed, but the ledger match alone
384
+ * does not prove it — branch on disk: dest present ⇒ the swap completed ⇒
385
+ * roll forward; dest ABSENT ⇒ a same-sha re-add crashed inside commitInstall's
386
+ * dest→backup / staging→dest window and backupDir holds the only copy ⇒ roll
387
+ * back (restore it) rather than discarding it (which would be silent data
388
+ * loss against a ledger that still records the install).
389
+ * 3. `applying`, no ledger match (or ledger match with dest absent) ⇒ roll back
390
+ * through the guarded, idempotent decision table below (mirroring
391
+ * `rollbackInstallCommit`'s order) — EXCEPT the case-(c) fresh-install
392
+ * discard, which acts on the journal alone (staging + backup both absent) and
393
+ * so requires LEDGER corroboration of an interrupted old-name migration
394
+ * (`installed.path === journal.oldNamePath`) before it will delete an
395
+ * existing dest; uncorroborated ⇒ refuse fail-closed, mutate nothing, leave
396
+ * the journal and dest in place (the journal is repo-committable, so a forged
397
+ * one must never drive a deletion).
398
+ *
399
+ * Crash-safety of recovery itself: the journal is removed LAST, after all
400
+ * restore/discard renames, and every step is a single atomic rename guarded by
401
+ * existence probes — so a crash mid-recovery leaves the journal intact and a
402
+ * strict subset of the work done; the next attempt re-derives state from disk
403
+ * and continues (the dest-absent arm of case (b), the touch-nothing arm of
404
+ * case (c), and the case-(c) uncorroborated refusal ARE the mid-rollback resume
405
+ * / fail-closed states). Running it twice is a no-op the second time.
406
+ *
407
+ * Any refusal (invalid journal, defsDir mismatch, symlink where a directory is
408
+ * expected, contradictory disk state) throws WITHOUT mutating anything and
409
+ * leaves the journal in place; `dispatchAdd` sets `preserveStagingRoot` so its
410
+ * `finally` cannot then destroy the backups a later attempt needs.
411
+ */
412
+ export declare function recoverInterruptedInstall(args: RecoverInterruptedInstallArgs): RecoveryOutcome;