owenloop 0.5.0 → 0.5.2

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 (229) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +144 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +29 -4
  5. package/dist/packages/work/src/agent/brief.js +49 -4
  6. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  7. package/dist/packages/work/src/agent/capability-model.js +148 -0
  8. package/dist/packages/work/src/agent/loop.d.ts +56 -7
  9. package/dist/packages/work/src/agent/loop.js +166 -9
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +29 -1
  20. package/dist/packages/work/src/exec/loop.js +313 -35
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +84 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +30 -10
  38. package/dist/packages/work/src/harness/session-store.js +317 -89
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +134 -12
  41. package/dist/packages/work/src/hub/client.d.ts +8 -1
  42. package/dist/packages/work/src/hub/client.js +15 -1
  43. package/dist/packages/work/src/hub/types.d.ts +137 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +115 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +6 -0
  53. package/dist/packages/work/src/roles/hold.js +83 -13
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +19 -2
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +36 -2
  59. package/dist/packages/work/src/settings/settings.d.ts +70 -1
  60. package/dist/packages/work/src/settings/settings.js +90 -4
  61. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  62. package/dist/packages/work/src/shift/logretention.js +407 -0
  63. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  64. package/dist/packages/work/src/shift/logsink.js +98 -0
  65. package/dist/packages/work/src/shift/loop.d.ts +32 -4
  66. package/dist/packages/work/src/shift/loop.js +687 -166
  67. package/dist/packages/work/src/shift/protocol.d.ts +128 -1
  68. package/dist/packages/work/src/shift/protocol.js +14 -0
  69. package/dist/packages/work/src/shift/runtime.d.ts +16 -0
  70. package/dist/packages/work/src/shift/runtime.js +291 -5
  71. package/dist/packages/work/src/shift/server.d.ts +13 -0
  72. package/dist/packages/work/src/shift/server.js +61 -36
  73. package/dist/packages/work/src/shift/spawn.d.ts +115 -19
  74. package/dist/packages/work/src/shift/spawn.js +234 -30
  75. package/dist/packages/work/src/shift/state.d.ts +76 -49
  76. package/dist/packages/work/src/shift/state.js +350 -103
  77. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  78. package/dist/packages/work/src/shift/truncate.js +73 -0
  79. package/dist/packages/work/src/submit-proof.d.ts +61 -0
  80. package/dist/packages/work/src/submit-proof.js +119 -0
  81. package/dist/packages/work/src/submit-value.d.ts +48 -0
  82. package/dist/packages/work/src/submit-value.js +118 -0
  83. package/dist/packages/work/src/usage.d.ts +1 -1
  84. package/dist/packages/work/src/usage.js +11 -0
  85. package/dist/src/add.d.ts +64 -259
  86. package/dist/src/add.js +81 -615
  87. package/dist/src/archive.d.ts +97 -0
  88. package/dist/src/archive.js +591 -0
  89. package/dist/src/bundle/index.d.ts +64 -0
  90. package/dist/src/bundle/index.js +508 -0
  91. package/dist/src/bundle/manifest.d.ts +50 -0
  92. package/dist/src/bundle/manifest.js +435 -0
  93. package/dist/src/bundle/runtime.d.ts +26 -0
  94. package/dist/src/bundle/runtime.js +64 -0
  95. package/dist/src/bundle/tar.d.ts +62 -0
  96. package/dist/src/bundle/tar.js +238 -0
  97. package/dist/src/bundle/types.d.ts +105 -0
  98. package/dist/src/bundle/types.js +21 -0
  99. package/dist/src/capabilities.d.ts +93 -0
  100. package/dist/src/capabilities.js +101 -0
  101. package/dist/src/cli.d.ts +90 -20
  102. package/dist/src/cli.js +2421 -374
  103. package/dist/src/credentials.d.ts +4 -3
  104. package/dist/src/credentials.js +21 -19
  105. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  106. package/dist/src/crypto/allowed-signers.js +307 -0
  107. package/dist/src/crypto/canonical.d.ts +8 -0
  108. package/dist/src/crypto/canonical.js +92 -0
  109. package/dist/src/crypto/chain.d.ts +65 -0
  110. package/dist/src/crypto/chain.js +377 -0
  111. package/dist/src/crypto/dsse.d.ts +209 -0
  112. package/dist/src/crypto/dsse.js +282 -0
  113. package/dist/src/crypto/enrollment.d.ts +78 -0
  114. package/dist/src/crypto/enrollment.js +186 -0
  115. package/dist/src/crypto/index.d.ts +48 -0
  116. package/dist/src/crypto/index.js +44 -0
  117. package/dist/src/crypto/keys.d.ts +258 -0
  118. package/dist/src/crypto/keys.js +908 -0
  119. package/dist/src/crypto/org-root.d.ts +33 -0
  120. package/dist/src/crypto/org-root.js +78 -0
  121. package/dist/src/crypto/origin-rules.d.ts +56 -0
  122. package/dist/src/crypto/origin-rules.js +143 -0
  123. package/dist/src/crypto/policy-floor.d.ts +98 -0
  124. package/dist/src/crypto/policy-floor.js +353 -0
  125. package/dist/src/crypto/records.d.ts +319 -0
  126. package/dist/src/crypto/records.js +168 -0
  127. package/dist/src/crypto/scope.d.ts +49 -0
  128. package/dist/src/crypto/scope.js +83 -0
  129. package/dist/src/crypto/ssh.d.ts +171 -0
  130. package/dist/src/crypto/ssh.js +396 -0
  131. package/dist/src/crypto/submission.d.ts +33 -0
  132. package/dist/src/crypto/submission.js +47 -0
  133. package/dist/src/crypto/trust-roots.d.ts +29 -0
  134. package/dist/src/crypto/trust-roots.js +39 -0
  135. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  136. package/dist/src/crypto/verify-consumed.js +259 -0
  137. package/dist/src/crypto/verify-origin.d.ts +50 -0
  138. package/dist/src/crypto/verify-origin.js +151 -0
  139. package/dist/src/crypto/verify-publication.d.ts +60 -0
  140. package/dist/src/crypto/verify-publication.js +150 -0
  141. package/dist/src/defs.d.ts +24 -1
  142. package/dist/src/defs.js +335 -27
  143. package/dist/src/engine.d.ts +211 -6
  144. package/dist/src/engine.js +459 -59
  145. package/dist/src/factory.d.ts +16 -0
  146. package/dist/src/factory.js +16 -4
  147. package/dist/src/global-config.d.ts +59 -0
  148. package/dist/src/global-config.js +84 -0
  149. package/dist/src/hub.d.ts +102 -32
  150. package/dist/src/hub.js +147 -58
  151. package/dist/src/index.d.ts +19 -2
  152. package/dist/src/index.js +23 -2
  153. package/dist/src/install.d.ts +538 -0
  154. package/dist/src/install.js +1981 -0
  155. package/dist/src/lock.d.ts +15 -57
  156. package/dist/src/lock.js +251 -143
  157. package/dist/src/mcp/serve.d.ts +46 -22
  158. package/dist/src/mcp/serve.js +174 -44
  159. package/dist/src/mcp/server.js +12 -1
  160. package/dist/src/model.d.ts +51 -0
  161. package/dist/src/model.js +157 -1
  162. package/dist/src/order-resolver.d.ts +184 -0
  163. package/dist/src/order-resolver.js +252 -0
  164. package/dist/src/package-version.d.ts +10 -0
  165. package/dist/src/package-version.js +42 -0
  166. package/dist/src/paths.d.ts +14 -1
  167. package/dist/src/paths.js +18 -0
  168. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  169. package/dist/src/schemas/index.d.ts +1433 -0
  170. package/dist/src/schemas/index.js +31 -0
  171. package/dist/src/schemas/order.v1.schema.json +120 -0
  172. package/dist/src/schemas/origin.v1.schema.json +68 -0
  173. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  174. package/dist/src/schemas/publication.v1.schema.json +31 -0
  175. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  176. package/dist/src/schemas/submission.v1.schema.json +61 -0
  177. package/dist/src/store/def-source.d.ts +52 -0
  178. package/dist/src/store/def-source.js +335 -0
  179. package/dist/src/store/index-file.d.ts +69 -0
  180. package/dist/src/store/index-file.js +151 -0
  181. package/dist/src/store/index.d.ts +27 -0
  182. package/dist/src/store/index.js +22 -0
  183. package/dist/src/store/ingestor.d.ts +43 -0
  184. package/dist/src/store/ingestor.js +211 -0
  185. package/dist/src/store/install.d.ts +228 -0
  186. package/dist/src/store/install.js +555 -0
  187. package/dist/src/store/instruction-source.d.ts +49 -0
  188. package/dist/src/store/instruction-source.js +298 -0
  189. package/dist/src/store/origin-evidence.d.ts +21 -0
  190. package/dist/src/store/origin-evidence.js +66 -0
  191. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  192. package/dist/src/store/pre-commit-verifier.js +418 -0
  193. package/dist/src/store/resolve.d.ts +138 -0
  194. package/dist/src/store/resolve.js +363 -0
  195. package/dist/src/store/types.d.ts +288 -0
  196. package/dist/src/store/types.js +356 -0
  197. package/dist/src/store.d.ts +33 -1
  198. package/dist/src/store.js +57 -4
  199. package/dist/src/types.d.ts +146 -12
  200. package/dist/src/untar.d.ts +8 -23
  201. package/dist/src/untar.js +10 -136
  202. package/docs/agent-runner.md +86 -0
  203. package/docs/authoring.md +64 -6
  204. package/docs/bundles.md +350 -0
  205. package/docs/cli.md +1298 -106
  206. package/docs/crypto.md +832 -0
  207. package/docs/design.md +342 -20
  208. package/docs/embedding.md +132 -25
  209. package/docs/shift-logs.md +642 -0
  210. package/docs/wire-contracts.md +395 -0
  211. package/package.json +6 -1
  212. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  213. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  214. package/plugins/claude-code/plugin/.mcp.json +14 -0
  215. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  216. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  217. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  218. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  219. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  220. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  221. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  222. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  223. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  224. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  225. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  226. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  227. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  228. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  229. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -0,0 +1,555 @@
1
+ /**
2
+ * Workflow-bundle installation into the content-addressed store — its trust
3
+ * boundary. This module OWNS the install orchestration (staging → engine
4
+ * validation → pre-commit verification → hardening → atomic swap → atomic
5
+ * index commit → finalize), but deliberately does NOT own bundle
6
+ * parsing/digest (the `BundleIngestor` port) or pre-commit verification (the
7
+ * `PreCommitVerifier` port). Neither port has a permissive fallback: with
8
+ * either adapter missing, installation fails closed BEFORE any
9
+ * object/index/journal commit — there is no default accepting parser, digest
10
+ * algorithm, or no-op verifier.
11
+ *
12
+ * The transaction rides the host-neutral machinery in `src/install.ts`
13
+ * (staging, swap+retained backup, journal, lock, recovery). CAS specifics:
14
+ * metadata = `index.json` at the store root; destination = the validated
15
+ * three-segment object path `objects/sha256/<digest>`; journal = v2 (identity
16
+ * is a metadata-hash match, no route-specific fields); lock/staging/journal
17
+ * live PER ROOT (project installs share the project add lock path; global
18
+ * installs keep equivalent state below the global root).
19
+ *
20
+ * Engine core: this module imports Node builtins, defs/model validation
21
+ * helpers, and the generic transaction — never `cli.ts`, `add.ts`, `untar.ts`,
22
+ * or a hub module.
23
+ */
24
+ import { chmodSync, existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
25
+ import { dirname, join } from 'node:path';
26
+ import { randId } from "../util.js";
27
+ import { DefError, finalizeDefs, lintDef, loadDefFile, loadDefsRaw, validateDef } from "../defs.js";
28
+ import { parseManifestBytes } from "../bundle/manifest.js";
29
+ import { hasDefiniteCheckDefect, modelCheck } from "../model.js";
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
+ import { BundleIngestorUnavailableError, PreCommitVerifierUnavailableError, StoreConflictError, StoreIntegrityError, StorePathError, } from "./types.js";
32
+ import { readWorkflowStoreIndex, writeWorkflowStoreIndex } from "./index-file.js";
33
+ import { verifyWorkflowObjectSync } from "./ingestor.js";
34
+ import { defDigest } from "./types.js";
35
+ import { storeIndexPath } from "./resolve.js";
36
+ /**
37
+ * The CAS destination relative path for a validated digest: the single
38
+ * relative path `objects/sha256/<digest>`, re-validated as a safe
39
+ * multi-segment path before any join/rename (reject-don't-normalize, same as
40
+ * every other destination path in the transaction).
41
+ */
42
+ export function objectDestRelPath(digest) {
43
+ const rel = `objects/sha256/${digest}`;
44
+ const violation = multiSegmentPathViolation(rel);
45
+ if (violation) {
46
+ // Unreachable for a validated digest — kept so the mutation site never
47
+ // trusts its inputs even if a caller bypassed the brand.
48
+ throw new StorePathError(`refusing unsafe object destination '${rel}': ${violation}`);
49
+ }
50
+ return rel;
51
+ }
52
+ // ---- permission hardening --------------------------------------------------------
53
+ /**
54
+ * Set non-executable regular files read-only (0o444), executable regular
55
+ * files read/execute-only (0o555), and directories non-writable (0o555) under
56
+ * `dir`, recursively, INCLUDING `dir` itself. Preserving the executable bit is
57
+ * required to reconstruct the canonical 0644/0755 bundle identity. Defense in
58
+ * depth only —
59
+ * permissions are NOT the integrity proof (verification is). Any chmod
60
+ * failure propagates: an object that cannot be hardened is not committed
61
+ * (the caller rolls staging back), so a partially-hardened object never
62
+ * lands in the store. A symlink anywhere in the object is refused outright —
63
+ * an extracted object must never contain links.
64
+ */
65
+ export function hardenObjectModes(dir) {
66
+ const st = lstatSync(dir);
67
+ if (st.isSymbolicLink()) {
68
+ throw new StorePathError(`refusing to harden '${dir}': it is a symlink`);
69
+ }
70
+ if (!st.isDirectory()) {
71
+ throw new StorePathError(`refusing to harden '${dir}': it is not a directory`);
72
+ }
73
+ for (const entry of readdirSync(dir)) {
74
+ const full = join(dir, entry);
75
+ const entrySt = lstatSync(full);
76
+ if (entrySt.isSymbolicLink()) {
77
+ throw new StorePathError(`refusing to harden '${full}': object contains a symlink`);
78
+ }
79
+ if (entrySt.isDirectory()) {
80
+ hardenObjectModes(full);
81
+ }
82
+ else if (entrySt.isFile()) {
83
+ chmodSync(full, (entrySt.mode & 0o111) === 0 ? 0o444 : 0o555);
84
+ }
85
+ else {
86
+ throw new StorePathError(`refusing to harden '${full}': unexpected file type`);
87
+ }
88
+ }
89
+ chmodSync(dir, 0o555);
90
+ }
91
+ /** Concrete recovery actions for v2 content-addressed replacement journals. */
92
+ export const workflowStoreReplacementRecovery = {
93
+ harden: hardenObjectModes,
94
+ verify(objectDir, rawDigest) {
95
+ verifyWorkflowObjectSync(objectDir, defDigest(rawDigest), {
96
+ coordinateRepair: false,
97
+ requireHardenedModes: true,
98
+ });
99
+ },
100
+ };
101
+ // ---- the install transaction -----------------------------------------------------
102
+ /**
103
+ * Install one `.wnlp` bundle into a store root as one recoverable operation.
104
+ *
105
+ * Fixed commit order:
106
+ * 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);
109
+ * 3. clear stale staging debris;
110
+ * 4. reread + validate the index INSIDE the lock (ownership/conflict
111
+ * decisions must see the post-lock state — TOCTOU);
112
+ * 5. stage via the A1 ingestor (unpack + manifest + digest + coordinate);
113
+ * 6. validate the staged tree with the engine's strict pass (loadDefsRaw +
114
+ * lint + validate + bounded modelCheck(assumeProvided) + strict loadDefs);
115
+ * 7. run the A2 pre-commit verifier (after content validation, before ANY
116
+ * destination swap or index write);
117
+ * 8. when the digest object exists, verify the installed object; if that
118
+ * verification fails, completely verify the staged reconstruction and
119
+ * mark the transaction as a repair; a verified object remains a dedupe;
120
+ * 9. compute the post-install index and write the `applying` journal (v2,
121
+ * with the hash of that exact index state);
122
+ * 10. atomically install or repair the object — a fresh install or repair
123
+ * swaps the staged directory into place (retaining displaced content on
124
+ * the handle), THEN hardens file/directory modes at the destination; a
125
+ * repair verifies that exact hardened destination before the commit point,
126
+ * while a dedupe commits no object rewrite;
127
+ * 11. atomically write the index — the DURABLE COMMIT POINT;
128
+ * 12. write the `finalizing` journal;
129
+ * 13. discard the retained backup + staging;
130
+ * 14. remove the journal; release the lock.
131
+ *
132
+ * Fetching/reading the source bytes may happen before the lock (the caller's
133
+ * job); index ownership/conflict decisions happen inside it.
134
+ *
135
+ * Failure semantics: any rejection before the swap (A1 tamper refusal, A2
136
+ * refusal, engine validation, digest mismatch) leaves objects/index/journal
137
+ * untouched and staging is cleared by the `finally`. A swap failure, a
138
+ * post-swap hardening or repair-verification failure, or an index-write failure
139
+ * rolls the directory state back in-process so the previous object + index are
140
+ * left exactly as they were. A crash anywhere leaves the journal behind for the
141
+ * next recovery.
142
+ *
143
+ * Conflict semantics: an existing coordinate at a DIFFERENT digest is a
144
+ * {@link StoreConflictError} (no implicit retarget). An existing coordinate at
145
+ * the SAME digest deduplicates when the installed object verifies. When only
146
+ * installed-object verification fails, the already-admitted supplied archive
147
+ * is verified again from staging and atomically replaces the broken object;
148
+ * bytes from the broken object are never reused. The index keeps the same
149
+ * coordinate-to-digest meaning.
150
+ */
151
+ export async function installWorkflowBundle(args) {
152
+ const { bytes, source, root, level, lockPath, journalPath, recoveryMarkerDir, ingestor, verifier, readLedger } = args;
153
+ if (ingestor === undefined || ingestor === null)
154
+ throw new BundleIngestorUnavailableError();
155
+ if (verifier === undefined || verifier === null)
156
+ throw new PreCommitVerifierUnavailableError();
157
+ const indexPath = storeIndexPath(root);
158
+ const stagingRoot = join(root, '.owenloop-staging');
159
+ const stagingId = randId('stg');
160
+ const stagingDir = join(stagingRoot, stagingId);
161
+ ensureDirectoryPathNoSymlink(root, 'workflow store root');
162
+ ensureDirectoryPathNoSymlink(dirname(lockPath), 'install state directory');
163
+ ensureDirectoryPathNoSymlink(dirname(journalPath), 'install state directory');
164
+ guardStateFile(lockPath, 'install lock');
165
+ guardStateFile(journalPath, 'crash-recovery journal');
166
+ const lock = await acquireInstallLock(lockPath);
167
+ // Set true only when the ONLY copy of some content sits under the staging
168
+ // root (a rollback double-fault) — then the `finally` must NOT clear it.
169
+ let preserveStagingRoot = false;
170
+ 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.
173
+ // A v1 (GitHub) journal at a shared project journal path needs the
174
+ // project ledger to vouch (supplied via `readLedger` — project bundle
175
+ // installs share the project add lock/recovery ordering); without a
176
+ // ledger a leftover v1 journal is refused. Any refusal preserves the
177
+ // staging root + journal as evidence.
178
+ try {
179
+ recoverInterruptedInstall({
180
+ defsDir: root,
181
+ journalPath,
182
+ lockfilePath: indexPath,
183
+ readLedger,
184
+ recoveryMarkerDir,
185
+ v2Replacement: workflowStoreReplacementRecovery,
186
+ });
187
+ }
188
+ catch (e) {
189
+ preserveStagingRoot = true;
190
+ throw e;
191
+ }
192
+ // The lock holder is the only legitimate writer under the staging root —
193
+ // anything already there is debris from a crashed/killed prior run.
194
+ rmRecursiveForce(stagingRoot);
195
+ // Reread + validate the index INSIDE the lock (fail-closed; a corrupt
196
+ // index is a hard error, never a silent reset).
197
+ const index = readWorkflowStoreIndex(indexPath);
198
+ // Stage via A1: unpack, manifest integrity, canonical digest, coordinate.
199
+ // A refusal here (tamper, bad manifest, oversized archive) leaves staging
200
+ // debris only — no object, no index, no journal touched.
201
+ const { coordinate, digest, workflows: ingestedWorkflows } = await ingestor.ingest({ source, bytes, stagingDir });
202
+ const workflows = [...ingestedWorkflows].sort((a, b) => Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')));
203
+ // Ownership/conflict decisions, inside the lock:
204
+ const existing = index.entries[coordinate];
205
+ const destRelPath = objectDestRelPath(digest);
206
+ const objectDir = join(root, destRelPath);
207
+ if (existing !== undefined && existing.digest !== digest) {
208
+ throw new StoreConflictError(coordinate, existing.digest);
209
+ }
210
+ let objectAlreadyPresent;
211
+ try {
212
+ objectAlreadyPresent = probeDirectoryPath(objectDir, 'workflow object', root) === 'dir';
213
+ }
214
+ catch (e) {
215
+ throw new StoreIntegrityError('object-corrupt', digest, e.message);
216
+ }
217
+ // Validate the staged tree with the engine's strict pass — the exact
218
+ // bytes that will be committed, with no re-write after validation.
219
+ const reasons = [];
220
+ let staged;
221
+ let externalVersionedCalls = new Set();
222
+ const manifestPath = join(stagingDir, 'bundle.yaml');
223
+ if (existsSync(manifestPath)) {
224
+ // Real `.wnlp` bundles carry an explicit workflow map. Load every listed
225
+ // path and key the staged definitions by the manifest's workflow name.
226
+ staged = new Map();
227
+ try {
228
+ const manifest = parseManifestBytes(readFileSync(manifestPath));
229
+ externalVersionedCalls = new Set(Object.keys(manifest.lock));
230
+ for (const [workflowName, workflowPath] of Object.entries(manifest.workflows)) {
231
+ const workflowFile = join(stagingDir, workflowPath);
232
+ try {
233
+ const stagedDef = loadDefFile(workflowFile);
234
+ if (stagedDef.name !== workflowName) {
235
+ reasons.push(`${workflowFile}: definition name '${stagedDef.name}' must equal workflow map key '${workflowName}'`);
236
+ }
237
+ staged.set(stagedDef.name, stagedDef);
238
+ }
239
+ catch (e) {
240
+ if (e instanceof DefError) {
241
+ reasons.push(`${workflowFile}: ${e.message}`);
242
+ }
243
+ else {
244
+ throw e;
245
+ }
246
+ }
247
+ }
248
+ }
249
+ catch (e) {
250
+ if (e instanceof DefError) {
251
+ reasons.push(`${manifestPath}: ${e.message}`);
252
+ }
253
+ else {
254
+ throw e;
255
+ }
256
+ }
257
+ }
258
+ else {
259
+ // The fallback preserves the installer port's ability to validate
260
+ // non-archive adapters used by callers and tests.
261
+ const failures = [];
262
+ staged = loadDefsRaw(stagingDir, failures);
263
+ reasons.push(...failures.map((failure) => `${failure.file}: ${failure.error}`));
264
+ }
265
+ for (const stagedDef of staged.values()) {
266
+ const lintResult = lintDef(stagedDef);
267
+ reasons.push(...lintResult.errors.map((err) => `${stagedDef.name}: ${err}`));
268
+ reasons.push(...validateDef(stagedDef).map((err) => `${stagedDef.name}: ${err}`));
269
+ const report = modelCheck(stagedDef, { assumeProvided: true });
270
+ if (hasDefiniteCheckDefect(report)) {
271
+ reasons.push(`${stagedDef.name}: definite defects found (${report.invariantViolations.length} invariant violation(s), ` +
272
+ `${report.structurallyDeadSteps.length} structurally dead step(s), ` +
273
+ `${report.deadlocks.length} true deadlock(s))`);
274
+ }
275
+ }
276
+ if (reasons.length === 0) {
277
+ try {
278
+ finalizeDefs(staged, { allowUnresolvedVersionedCalls: externalVersionedCalls });
279
+ }
280
+ catch (e) {
281
+ if (e instanceof DefError) {
282
+ reasons.push(`cross-definition validation failed: ${e.message}`);
283
+ }
284
+ else {
285
+ throw e;
286
+ }
287
+ }
288
+ }
289
+ if (reasons.length > 0) {
290
+ throw new Error(`refusing to install bundle '${coordinate}' — ${reasons.length} problem(s) found; nothing written:\n - ${reasons.join('\n - ')}`);
291
+ }
292
+ // A2 pre-commit verification: after content/engine validation, before ANY
293
+ // destination swap or index write. A rejection commits nothing.
294
+ await verifier.verify({ source, coordinate, digest, objectDir: stagingDir });
295
+ // Existing same-digest objects have two paths. A verified object keeps the
296
+ // normal idempotent dedupe. A broken object is repaired only from the
297
+ // supplied archive that already passed strict ingest, engine validation,
298
+ // and A2 policy above. Verify the staged reconstruction through the same
299
+ // complete installed-object verifier before journaling or replacing
300
+ // anything; never copy or otherwise trust bytes from the broken object.
301
+ let repairRequired = false;
302
+ if (objectAlreadyPresent) {
303
+ try {
304
+ await ingestor.verifyInstalledObject({ objectDir, digest });
305
+ }
306
+ catch (existingError) {
307
+ try {
308
+ const verifyStaged = ingestor.verifyStagedObject ?? ingestor.verifyInstalledObject;
309
+ await verifyStaged.call(ingestor, { objectDir: stagingDir, digest });
310
+ }
311
+ catch (stagedError) {
312
+ throw new StoreIntegrityError('object-corrupt', digest, `existing object failed verification (${existingError.message}); ` +
313
+ `the supplied archive could not produce a verified repair object (${stagedError.message})`);
314
+ }
315
+ repairRequired = true;
316
+ }
317
+ }
318
+ // The post-install index, computed BEFORE the commit point so its exact
319
+ // canonical bytes are what the journal's metadataHash commits to. A
320
+ // same-digest repair intentionally preserves the existing index semantics.
321
+ const nextIndex = {
322
+ version: 1,
323
+ entries: {
324
+ ...index.entries,
325
+ [coordinate]: { digest, pinned: existing?.pinned ?? false, workflows: [...workflows] },
326
+ },
327
+ };
328
+ const metadataHash = sha256Hex(canonicalJsonBytes(nextIndex));
329
+ // Every swap gets an external transaction marker. Fresh installs need the
330
+ // marker to corroborate an otherwise ambiguous orphan destination. Repairs
331
+ // record both directory identities before the journal is written or any
332
+ // rename occurs. A crash in the destination → backup callback window then
333
+ // still leaves complete ownership evidence for fail-closed recovery.
334
+ const recoveryMarker = !objectAlreadyPresent || repairRequired
335
+ ? createRecoveryMarker({
336
+ root,
337
+ destSegments: ['objects', 'sha256', digest],
338
+ stagingId,
339
+ markerDir: recoveryMarkerDir,
340
+ operation: repairRequired ? 'repair' : 'install',
341
+ replacementDir: stagingDir,
342
+ })
343
+ : undefined;
344
+ if (repairRequired && recoveryMarker !== undefined) {
345
+ try {
346
+ recordRecoveryMarkerPriorIdentity(recoveryMarker, objectDir);
347
+ }
348
+ catch (error) {
349
+ removeRecoveryMarker(recoveryMarker);
350
+ throw error;
351
+ }
352
+ }
353
+ // Journal (v2, phase `applying`) BEFORE the first destructive step.
354
+ const journalBase = {
355
+ version: 2,
356
+ phase: 'applying',
357
+ operation: repairRequired ? 'repair' : objectAlreadyPresent ? 'dedupe' : 'install',
358
+ destSegments: ['objects', 'sha256', digest],
359
+ stagingId,
360
+ hadDest: objectAlreadyPresent,
361
+ root,
362
+ metadataHash,
363
+ label: coordinate,
364
+ recoveryMarkerId: recoveryMarker?.id,
365
+ };
366
+ try {
367
+ writeAddJournal(journalPath, journalBase);
368
+ }
369
+ catch (e) {
370
+ if (recoveryMarker !== undefined)
371
+ removeRecoveryMarker(recoveryMarker);
372
+ throw e;
373
+ }
374
+ let handle;
375
+ const rollbackCommittedSwap = (committedHandle) => {
376
+ if (!repairRequired) {
377
+ rollbackInstallCommit(committedHandle);
378
+ return;
379
+ }
380
+ if (recoveryMarker === undefined) {
381
+ throw new Error('internal error: repair rollback is missing its recovery marker');
382
+ }
383
+ let rollbackReplacementMode;
384
+ rollbackInstallCommit(committedHandle, {
385
+ beforeRollback: () => {
386
+ rollbackReplacementMode = lstatSync(committedHandle.dest).mode & 0o7777;
387
+ writeAddJournal(journalPath, {
388
+ ...journalBase,
389
+ phase: 'rollback-started',
390
+ operation: 'repair',
391
+ rollbackReplacementMode,
392
+ });
393
+ },
394
+ afterDestinationParked: () => {
395
+ writeAddJournal(journalPath, {
396
+ ...journalBase,
397
+ phase: 'rollback-replacement-parked',
398
+ operation: 'repair',
399
+ rollbackReplacementMode,
400
+ });
401
+ },
402
+ afterPriorRestored: () => {
403
+ writeAddJournal(journalPath, {
404
+ ...journalBase,
405
+ phase: 'rollback-prior-restored',
406
+ operation: 'repair',
407
+ rollbackReplacementMode,
408
+ });
409
+ },
410
+ cleanupUndo: true,
411
+ afterUndoCleanup: () => {
412
+ writeAddJournal(journalPath, {
413
+ ...journalBase,
414
+ phase: 'rollback-complete',
415
+ operation: 'repair',
416
+ rollbackReplacementMode,
417
+ });
418
+ },
419
+ });
420
+ };
421
+ if (!objectAlreadyPresent || repairRequired) {
422
+ // Fresh install and repair use the same atomic swap. For repair,
423
+ // commitInstall quarantines the broken object under the staging root as
424
+ // the retained backup until the unchanged index is durably committed.
425
+ try {
426
+ handle = commitInstall(root, destRelPath, stagingDir);
427
+ }
428
+ catch (e) {
429
+ if (e instanceof RollbackFailedError) {
430
+ preserveStagingRoot = true;
431
+ }
432
+ else {
433
+ // commitInstall either made no change or restored the displaced object.
434
+ // Remove the now-obsolete journal so a later run does not mistake the
435
+ // already-restored state for an interrupted repair.
436
+ removeAddJournal(journalPath);
437
+ if (recoveryMarker !== undefined)
438
+ removeRecoveryMarker(recoveryMarker);
439
+ }
440
+ throw e;
441
+ }
442
+ try {
443
+ if (repairRequired) {
444
+ writeAddJournal(journalPath, { ...journalBase, phase: 'replacement-swapped' });
445
+ }
446
+ hardenObjectModes(handle.dest);
447
+ if (repairRequired) {
448
+ writeAddJournal(journalPath, { ...journalBase, phase: 'replacement-hardened' });
449
+ // Re-check the exact hardened destination before the commit point.
450
+ // Canonical 0755 files reconstruct from hardened 0555 execute bits;
451
+ // exact 0444/0555 store modes are verified separately by the adapter.
452
+ const verifyInstalled = ingestor.verifyInstalledObjectAfterCoordination ?? ingestor.verifyInstalledObject;
453
+ await verifyInstalled.call(ingestor, { objectDir: handle.dest, digest });
454
+ writeAddJournal(journalPath, { ...journalBase, phase: 'replacement-verified' });
455
+ }
456
+ }
457
+ catch (e) {
458
+ try {
459
+ rollbackCommittedSwap(handle);
460
+ }
461
+ catch (rollbackError) {
462
+ preserveStagingRoot = true;
463
+ throw new StoreIntegrityError('object-corrupt', digest, `replacement verification or hardening failed (${e.message}) and restoring the previous object failed too ` +
464
+ `(${rollbackError.message}) — the journal remains for the next recovery`);
465
+ }
466
+ removeAddJournal(journalPath);
467
+ if (recoveryMarker !== undefined)
468
+ removeRecoveryMarker(recoveryMarker);
469
+ throw new Error(`refusing to install bundle '${coordinate}': replacement verification or hardening failed ` +
470
+ `(${e.message}) — install rolled back, previous state restored`);
471
+ }
472
+ }
473
+ // Atomic index write — the DURABLE COMMIT POINT. Past here a crash rolls
474
+ // forward. On failure, roll back a fresh-install or repair swap (dedupe has
475
+ // no swap), drop the journal, and leave the previous object + index exactly
476
+ // as they were.
477
+ try {
478
+ writeWorkflowStoreIndex(indexPath, nextIndex);
479
+ }
480
+ catch (e) {
481
+ if (handle !== undefined) {
482
+ try {
483
+ rollbackCommittedSwap(handle);
484
+ }
485
+ catch (rollbackErr) {
486
+ // Double fault: preserve the parked content and LEAVE the journal
487
+ // (phase `applying`, index not committed) so the next recovery
488
+ // restores the previous state before anything clears staging.
489
+ preserveStagingRoot = true;
490
+ throw new StoreIntegrityError('object-corrupt', digest, `index write failed (${e.message}) and rolling the object back failed too ` +
491
+ `(${rollbackErr.message}) — the journal remains for the next recovery`);
492
+ }
493
+ }
494
+ removeAddJournal(journalPath);
495
+ if (recoveryMarker !== undefined)
496
+ removeRecoveryMarker(recoveryMarker);
497
+ throw new Error(`could not record install of '${coordinate}' in ${indexPath}: ${e.message} — ` +
498
+ `install rolled back, previous state restored`);
499
+ }
500
+ // The index write is the durable commit point: past here a crash rolls
501
+ // FORWARD. Keep the retained backup if the finalizing phase cannot be written;
502
+ // a replacement-verified journal can then re-verify and finish recovery.
503
+ preserveStagingRoot = true;
504
+ writeAddJournal(journalPath, { ...journalBase, phase: 'finalizing' });
505
+ preserveStagingRoot = false;
506
+ if (handle !== undefined)
507
+ finalizeInstallCommit(handle);
508
+ rmRecursiveForce(stagingRoot);
509
+ removeAddJournal(journalPath);
510
+ if (recoveryMarker !== undefined)
511
+ removeRecoveryMarker(recoveryMarker);
512
+ return {
513
+ source,
514
+ level,
515
+ coordinate,
516
+ digest,
517
+ workflows: [...workflows],
518
+ objectPath: objectDir,
519
+ installed: !objectAlreadyPresent,
520
+ };
521
+ }
522
+ finally {
523
+ if (!preserveStagingRoot)
524
+ rmRecursiveForce(stagingRoot);
525
+ releaseInstallLock(lock);
526
+ }
527
+ }
528
+ /**
529
+ * 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,
532
+ * no store open. A v2 journal recovers forward or back exactly as the inline
533
+ * path would; a v1 journal is refused (the GitHub route owns v1 recovery).
534
+ * Refusals throw and leave the journal, staging, and objects untouched.
535
+ */
536
+ export async function recoverWorkflowStore(args) {
537
+ ensureDirectoryPathNoSymlink(args.root, 'workflow store root');
538
+ ensureDirectoryPathNoSymlink(dirname(args.lockPath), 'install state directory');
539
+ ensureDirectoryPathNoSymlink(dirname(args.journalPath), 'install state directory');
540
+ guardStateFile(args.lockPath, 'install lock');
541
+ guardStateFile(args.journalPath, 'crash-recovery journal');
542
+ const lock = await acquireInstallLock(args.lockPath);
543
+ try {
544
+ return recoverInterruptedInstall({
545
+ defsDir: args.root,
546
+ journalPath: args.journalPath,
547
+ lockfilePath: storeIndexPath(args.root),
548
+ recoveryMarkerDir: args.recoveryMarkerDir,
549
+ v2Replacement: workflowStoreReplacementRecovery,
550
+ });
551
+ }
552
+ finally {
553
+ releaseInstallLock(lock);
554
+ }
555
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Store-backed reference instruction resolution.
3
+ *
4
+ * The engine's `OrderInstructionSource.lookup` seam is synchronous because the
5
+ * engine performs lookup inside the same SQLite transaction that claims an
6
+ * order. A store lookup is filesystem I/O, so callers must first `prime` the
7
+ * requested order digest. `lookup` then reads only the verified definition held
8
+ * in the in-memory cache populated by that prime.
9
+ */
10
+ import type { OrderInstructionSource } from '../order-resolver.ts';
11
+ import type { StepDef, WorkflowDef } from '../types.ts';
12
+ import type { DefDigest } from './types.ts';
13
+ import type { BundleIngestor } from './install.ts';
14
+ /** Optional recovery hook for a digest that is not indexed locally. */
15
+ export interface MissingObjectHandler {
16
+ onMissing(defDigest: string): Promise<'retry' | 'refuse'>;
17
+ }
18
+ export interface StoreInstructionSourceArgs {
19
+ /** The project workflow store root, normally `<cwd>/workflows`. */
20
+ projectRoot?: string;
21
+ /** The global workflow store root, derived from injected environment state. */
22
+ globalRoot: string;
23
+ /** The adapter that verifies every object before its workflow is loaded. */
24
+ verifier: BundleIngestor;
25
+ /** Optional one-shot recovery hook for an unknown order digest. */
26
+ onMissing?: MissingObjectHandler;
27
+ }
28
+ export declare class StoreInstructionSourceError extends Error {
29
+ readonly name = "StoreInstructionSourceError";
30
+ readonly code: 'digest-of-unavailable';
31
+ constructor(message: string);
32
+ }
33
+ /** A synchronous lookup source backed by verified local workflow-store objects. */
34
+ export interface StoreInstructionSource extends OrderInstructionSource {
35
+ /** Load and verify the bundle that corresponds to an order or bundle digest. */
36
+ prime(defDigest: string): Promise<'resolved' | 'unknown-digest'>;
37
+ /** Return a step only after `prime(defDigest)` has resolved that digest. */
38
+ getVerifiedStep(defDigest: string, step: string): StepDef | undefined;
39
+ /** Return the full verified definition cached by `prime`, narrowed by step when a bundle contains several workflows. */
40
+ getVerifiedDefinition(defDigest: string, step?: string): WorkflowDef | undefined;
41
+ /** Return the installed bundle identity and object path cached by `prime`. */
42
+ getVerifiedObject(defDigest: string): {
43
+ bundleDigest: DefDigest;
44
+ objectPath: string;
45
+ } | undefined;
46
+ }
47
+ export declare function createStoreInstructionSource(args: StoreInstructionSourceArgs): StoreInstructionSource;
48
+ /** A small helper for callers that receive a raw order digest before priming. */
49
+ export declare function isResolvableOrderDigest(value: string): value is DefDigest;