owenloop 0.5.0 → 0.5.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 +45 -0
- package/README.md +137 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +8 -4
- package/dist/packages/work/src/agent/brief.js +7 -3
- package/dist/packages/work/src/agent/loop.d.ts +13 -7
- package/dist/packages/work/src/agent/loop.js +136 -9
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/bundle/cache.d.ts +7 -5
- package/dist/packages/work/src/bundle/cache.js +20 -6
- package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
- package/dist/packages/work/src/bundle/fetch.js +27 -7
- package/dist/packages/work/src/bundle/types.d.ts +8 -4
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +12 -1
- package/dist/packages/work/src/exec/loop.js +137 -20
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +9 -6
- package/dist/packages/work/src/exec/receipt.js +12 -1
- package/dist/packages/work/src/exec/runner.d.ts +7 -1
- package/dist/packages/work/src/exec/runner.js +74 -3
- package/dist/packages/work/src/harness/child-env.js +7 -0
- package/dist/packages/work/src/harness/claude.d.ts +20 -8
- package/dist/packages/work/src/harness/claude.js +260 -58
- package/dist/packages/work/src/harness/codex.d.ts +5 -4
- package/dist/packages/work/src/harness/codex.js +169 -41
- package/dist/packages/work/src/harness/contract.d.ts +36 -11
- package/dist/packages/work/src/harness/fake.js +1 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
- package/dist/packages/work/src/harness/permissions.d.ts +16 -3
- package/dist/packages/work/src/harness/permissions.js +102 -13
- package/dist/packages/work/src/harness/session-store.d.ts +27 -9
- package/dist/packages/work/src/harness/session-store.js +271 -67
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +126 -11
- package/dist/packages/work/src/hub/client.d.ts +2 -1
- package/dist/packages/work/src/hub/client.js +14 -1
- package/dist/packages/work/src/hub/types.d.ts +69 -33
- package/dist/packages/work/src/hub/types.js +8 -10
- package/dist/packages/work/src/mcp/server.js +1 -1
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
- package/dist/packages/work/src/roles/agent-run.js +116 -34
- package/dist/packages/work/src/roles/exec.d.ts +8 -0
- package/dist/packages/work/src/roles/exec.js +27 -2
- package/dist/packages/work/src/roles/hold.d.ts +4 -0
- package/dist/packages/work/src/roles/hold.js +44 -5
- package/dist/packages/work/src/roles/lint.d.ts +3 -4
- package/dist/packages/work/src/roles/lint.js +41 -7
- package/dist/packages/work/src/roles/settings.js +5 -0
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +23 -1
- package/dist/packages/work/src/settings/settings.d.ts +17 -1
- package/dist/packages/work/src/settings/settings.js +39 -0
- package/dist/packages/work/src/shift/loop.d.ts +14 -3
- package/dist/packages/work/src/shift/loop.js +447 -164
- package/dist/packages/work/src/shift/protocol.d.ts +4 -0
- package/dist/packages/work/src/shift/runtime.d.ts +2 -0
- package/dist/packages/work/src/shift/runtime.js +66 -3
- package/dist/packages/work/src/shift/spawn.d.ts +41 -18
- package/dist/packages/work/src/shift/spawn.js +89 -31
- package/dist/packages/work/src/shift/state.d.ts +53 -51
- package/dist/packages/work/src/shift/state.js +325 -102
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/src/add.d.ts +64 -259
- package/dist/src/add.js +81 -615
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/src/cli.d.ts +90 -20
- package/dist/src/cli.js +2407 -365
- package/dist/src/credentials.d.ts +4 -3
- package/dist/src/credentials.js +21 -19
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/src/defs.d.ts +24 -1
- package/dist/src/defs.js +145 -25
- package/dist/src/engine.d.ts +99 -3
- package/dist/src/engine.js +238 -34
- package/dist/src/factory.d.ts +16 -0
- package/dist/src/factory.js +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/src/hub.d.ts +75 -21
- package/dist/src/hub.js +123 -40
- package/dist/src/index.d.ts +17 -2
- package/dist/src/index.js +20 -2
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +15 -57
- package/dist/src/lock.js +251 -143
- package/dist/src/mcp/serve.d.ts +46 -22
- package/dist/src/mcp/serve.js +167 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +15 -0
- package/dist/src/model.js +111 -1
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/src/paths.d.ts +14 -1
- package/dist/src/paths.js +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/src/types.d.ts +45 -11
- package/dist/src/untar.d.ts +8 -23
- package/dist/src/untar.js +10 -136
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +57 -6
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1171 -97
- package/docs/crypto.md +816 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/wire-contracts.md +380 -0
- package/package.json +6 -1
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- 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;
|