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,363 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Two-level store roots and fail-closed resolution.
|
|
3
|
+
*
|
|
4
|
+
* Two SEPARATE resolution APIs, so execution code cannot accidentally call
|
|
5
|
+
* human-name resolution:
|
|
6
|
+
*
|
|
7
|
+
* - {@link resolveWorkflowDigest} — execution path: digest only, no index,
|
|
8
|
+
* no workflow name. Project first, fall-through to global when the
|
|
9
|
+
* project object is ABSENT; a corrupt/invalid project hit is a hard error
|
|
10
|
+
* (never masked by falling back to a valid global copy).
|
|
11
|
+
*
|
|
12
|
+
* - {@link resolveWorkflowCoordinate} — human/CLI path: reads the project
|
|
13
|
+
* index first and uses the global index only as a fallback. When both
|
|
14
|
+
* levels name the coordinate, the project definition wins deterministically.
|
|
15
|
+
*
|
|
16
|
+
* Every successful resolution verifies the object it returns through the
|
|
17
|
+
* ingest adapter's `verifyInstalledObject` before handing back a path — the
|
|
18
|
+
* permissions/object shape on disk are defense in depth, not an integrity
|
|
19
|
+
* proof. There is no bare-name resolution anywhere in this module.
|
|
20
|
+
*/
|
|
21
|
+
import { lstatSync } from 'node:fs';
|
|
22
|
+
import { dirname, join, resolve as resolvePath } from 'node:path';
|
|
23
|
+
import { StoreIndexError, StoreIntegrityError, StoreNotFoundError, StorePathError, objectDirForDigest, WORKFLOW_STORE_INDEX_FILENAME, } from "./types.js";
|
|
24
|
+
import { readWorkflowStoreIndex } from "./index-file.js";
|
|
25
|
+
import { probeDirectoryPath, readAddJournal } from "../install.js";
|
|
26
|
+
/**
|
|
27
|
+
* The PROJECT store root: the resolved defs directory itself — project pins
|
|
28
|
+
* stay reviewable in git, and the nested `objects/sha256/<digest>/` path
|
|
29
|
+
* stays below the def loader's scan depth.
|
|
30
|
+
*/
|
|
31
|
+
export function projectStoreRoot(defsDir) {
|
|
32
|
+
return resolvePath(defsDir);
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* The GLOBAL store root: `<home>/.owenloop/workflows`. `home` is required so
|
|
36
|
+
* library callers and tests must pin a fixture HOME from the first write and
|
|
37
|
+
* never fall back to the ambient process home.
|
|
38
|
+
*/
|
|
39
|
+
export function globalStoreRoot(home) {
|
|
40
|
+
if (home.trim() === '')
|
|
41
|
+
throw new StorePathError('cannot derive global workflow store root from an empty home');
|
|
42
|
+
return join(home, '.owenloop', 'workflows');
|
|
43
|
+
}
|
|
44
|
+
/** The index file path at a store root. */
|
|
45
|
+
export function storeIndexPath(root) {
|
|
46
|
+
return join(root, WORKFLOW_STORE_INDEX_FILENAME);
|
|
47
|
+
}
|
|
48
|
+
export function workflowStoreStatePaths(root) {
|
|
49
|
+
const stateDir = join(root, '.owenloop');
|
|
50
|
+
return {
|
|
51
|
+
stateDir,
|
|
52
|
+
lockPath: join(stateDir, 'add.lock'),
|
|
53
|
+
journalPath: join(stateDir, 'add.journal'),
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
const DEFAULT_REPAIR_WAIT_TIMEOUT_MS = 5_000;
|
|
57
|
+
const DEFAULT_REPAIR_RETRY_MS = 10;
|
|
58
|
+
const syncSleepWord = new Int32Array(new SharedArrayBuffer(4));
|
|
59
|
+
function isMissingDuringJournalRead(error) {
|
|
60
|
+
return error.code === 'ENOENT';
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* True only while the matching digest is inside the non-stable part of a v2
|
|
64
|
+
* same-digest replacement. `finalizing` is stable after replacement commit;
|
|
65
|
+
* `rollback-prior-restored` and `rollback-complete` are stable after the exact
|
|
66
|
+
* prior directory is back. Cleanup after any stable phase never renames the
|
|
67
|
+
* digest path again. An old v2 `applying` journal without
|
|
68
|
+
* `operation` waits conservatively whenever `hadDest` is true: before the first
|
|
69
|
+
* rename, a repair and a dedupe are indistinguishable, and probing for the backup
|
|
70
|
+
* would leave a race between that probe and destination → backup.
|
|
71
|
+
*/
|
|
72
|
+
function digestRepairNeedsWait(root, digest) {
|
|
73
|
+
let journal;
|
|
74
|
+
try {
|
|
75
|
+
journal = readAddJournal(workflowStoreStatePaths(root).journalPath);
|
|
76
|
+
}
|
|
77
|
+
catch (error) {
|
|
78
|
+
// Atomic journal removal can race the lstat/read pair. Absence means the
|
|
79
|
+
// transaction reached a stable state; malformed or hostile journals remain
|
|
80
|
+
// fail-closed integrity errors.
|
|
81
|
+
if (isMissingDuringJournalRead(error))
|
|
82
|
+
return false;
|
|
83
|
+
throw new StoreIntegrityError('object-corrupt', digest, `could not inspect active replacement transaction: ${error.message}`);
|
|
84
|
+
}
|
|
85
|
+
if (journal === null || journal.version !== 2)
|
|
86
|
+
return false;
|
|
87
|
+
if (journal.destSegments.length !== 3 ||
|
|
88
|
+
journal.destSegments[0] !== 'objects' ||
|
|
89
|
+
journal.destSegments[1] !== 'sha256' ||
|
|
90
|
+
journal.destSegments[2] !== digest) {
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
if (journal.phase === 'finalizing')
|
|
94
|
+
return false;
|
|
95
|
+
if (journal.phase === 'rollback-prior-restored' || journal.phase === 'rollback-complete') {
|
|
96
|
+
const stagingDir = join(root, '.owenloop-staging', journal.stagingId);
|
|
97
|
+
const destination = join(root, ...journal.destSegments);
|
|
98
|
+
try {
|
|
99
|
+
const destinationStable = probeDirectoryPath(destination, 'workflow object', root) === 'dir';
|
|
100
|
+
const stagingAbsent = probeDirectoryPath(stagingDir, 'repair staging directory', root) === 'absent';
|
|
101
|
+
const backupAbsent = probeDirectoryPath(`${stagingDir}-old`, 'repair backup directory', root) === 'absent';
|
|
102
|
+
const undoAbsent = probeDirectoryPath(`${stagingDir}-undo`, 'repair undo directory', root) === 'absent';
|
|
103
|
+
if (journal.phase === 'rollback-prior-restored') {
|
|
104
|
+
return !(destinationStable && stagingAbsent && backupAbsent);
|
|
105
|
+
}
|
|
106
|
+
return !(destinationStable && stagingAbsent && backupAbsent && undoAbsent);
|
|
107
|
+
}
|
|
108
|
+
catch (error) {
|
|
109
|
+
throw new StoreIntegrityError('object-corrupt', digest, `could not validate stable repair rollback state: ${error.message}`);
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
if (journal.operation === 'repair')
|
|
113
|
+
return true;
|
|
114
|
+
if (journal.operation === 'install' || journal.operation === 'dedupe')
|
|
115
|
+
return false;
|
|
116
|
+
if (journal.phase !== 'applying')
|
|
117
|
+
return true;
|
|
118
|
+
// Backward compatibility for journals written before `operation` existed.
|
|
119
|
+
// Waiting on every had-destination transaction is conservative for old dedupe
|
|
120
|
+
// journals, but it closes the destination-probe → backup-rename race for old
|
|
121
|
+
// repair journals. The timeout handles a stale journal fail-closed.
|
|
122
|
+
return journal.hadDest;
|
|
123
|
+
}
|
|
124
|
+
function repairWaitError(digest, timeoutMs) {
|
|
125
|
+
return new StoreIntegrityError('object-corrupt', digest, `matching replacement transaction did not reach a stable state within ${timeoutMs}ms; ` +
|
|
126
|
+
`the transaction may have crashed and must be recovered before this object can be read`);
|
|
127
|
+
}
|
|
128
|
+
async function waitForDigestRepairUntil(root, digest, deadline, timeoutMs, retryMs) {
|
|
129
|
+
while (digestRepairNeedsWait(root, digest)) {
|
|
130
|
+
if (Date.now() >= deadline)
|
|
131
|
+
throw repairWaitError(digest, timeoutMs);
|
|
132
|
+
await new Promise((resolveWait) => setTimeout(resolveWait, retryMs));
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
function waitForDigestRepairUntilSync(root, digest, deadline, timeoutMs, retryMs) {
|
|
136
|
+
while (digestRepairNeedsWait(root, digest)) {
|
|
137
|
+
if (Date.now() >= deadline)
|
|
138
|
+
throw repairWaitError(digest, timeoutMs);
|
|
139
|
+
Atomics.wait(syncSleepWord, 0, 0, retryMs);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
/** Bounded asynchronous coordination for digest-backed async readers. */
|
|
143
|
+
export async function waitForDigestRepair(root, digest, options = {}) {
|
|
144
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_REPAIR_WAIT_TIMEOUT_MS;
|
|
145
|
+
const retryMs = options.retryMs ?? DEFAULT_REPAIR_RETRY_MS;
|
|
146
|
+
await waitForDigestRepairUntil(root, digest, Date.now() + timeoutMs, timeoutMs, retryMs);
|
|
147
|
+
}
|
|
148
|
+
/** Bounded synchronous coordination for `openCtx`/definition discovery readers. */
|
|
149
|
+
export function waitForDigestRepairSync(root, digest, options = {}) {
|
|
150
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_REPAIR_WAIT_TIMEOUT_MS;
|
|
151
|
+
const retryMs = options.retryMs ?? DEFAULT_REPAIR_RETRY_MS;
|
|
152
|
+
waitForDigestRepairUntilSync(root, digest, Date.now() + timeoutMs, timeoutMs, retryMs);
|
|
153
|
+
}
|
|
154
|
+
/**
|
|
155
|
+
* Run one asynchronous digest-backed read outside every active replacement
|
|
156
|
+
* phase. A replacement can start after the initial journal check, so a failed
|
|
157
|
+
* read checks the journal again and retries after the transaction stabilizes.
|
|
158
|
+
* One immediate retry is also allowed when the transaction completed quickly
|
|
159
|
+
* enough for both journal checks to observe absence; a genuinely missing or
|
|
160
|
+
* corrupt object therefore keeps its normal error after two immediate reads,
|
|
161
|
+
* rather than waiting for the full timeout.
|
|
162
|
+
*/
|
|
163
|
+
export async function coordinateDigestRead(root, digest, read, options = {}) {
|
|
164
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_REPAIR_WAIT_TIMEOUT_MS;
|
|
165
|
+
const retryMs = options.retryMs ?? DEFAULT_REPAIR_RETRY_MS;
|
|
166
|
+
const deadline = Date.now() + timeoutMs;
|
|
167
|
+
let retriedWithoutObservedJournal = false;
|
|
168
|
+
for (;;) {
|
|
169
|
+
await waitForDigestRepairUntil(root, digest, deadline, timeoutMs, retryMs);
|
|
170
|
+
try {
|
|
171
|
+
return await read();
|
|
172
|
+
}
|
|
173
|
+
catch (error) {
|
|
174
|
+
if (digestRepairNeedsWait(root, digest))
|
|
175
|
+
continue;
|
|
176
|
+
if (retriedWithoutObservedJournal)
|
|
177
|
+
throw error;
|
|
178
|
+
retriedWithoutObservedJournal = true;
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
/** Synchronous counterpart of {@link coordinateDigestRead}. */
|
|
183
|
+
export function coordinateDigestReadSync(root, digest, read, options = {}) {
|
|
184
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_REPAIR_WAIT_TIMEOUT_MS;
|
|
185
|
+
const retryMs = options.retryMs ?? DEFAULT_REPAIR_RETRY_MS;
|
|
186
|
+
const deadline = Date.now() + timeoutMs;
|
|
187
|
+
let retriedWithoutObservedJournal = false;
|
|
188
|
+
for (;;) {
|
|
189
|
+
waitForDigestRepairUntilSync(root, digest, deadline, timeoutMs, retryMs);
|
|
190
|
+
try {
|
|
191
|
+
return read();
|
|
192
|
+
}
|
|
193
|
+
catch (error) {
|
|
194
|
+
if (digestRepairNeedsWait(root, digest))
|
|
195
|
+
continue;
|
|
196
|
+
if (retriedWithoutObservedJournal)
|
|
197
|
+
throw error;
|
|
198
|
+
retriedWithoutObservedJournal = true;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Probe a store root: `'absent'` (nothing installed here — NOT an error), or
|
|
204
|
+
* a real directory. A symlink or non-directory squatting at the root is a
|
|
205
|
+
* hard {@link StorePathError}: resolution must never read through a link that
|
|
206
|
+
* redirects it outside the intended tree (SEC-3). `lstat`, never `stat`.
|
|
207
|
+
*/
|
|
208
|
+
export function probeStoreRoot(root) {
|
|
209
|
+
const st = lstatSync(root, { throwIfNoEntry: false });
|
|
210
|
+
if (st === undefined)
|
|
211
|
+
return 'absent';
|
|
212
|
+
if (st.isSymbolicLink()) {
|
|
213
|
+
throw new StorePathError(`refusing workflow store root '${root}': it is a symlink`);
|
|
214
|
+
}
|
|
215
|
+
if (!st.isDirectory()) {
|
|
216
|
+
throw new StorePathError(`refusing workflow store root '${root}': it is not a directory`);
|
|
217
|
+
}
|
|
218
|
+
return 'dir';
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Probe an object directory (`objects/sha256/<digest>`): `'dir'` or
|
|
222
|
+
* `'absent'`. Anything else — a symlink, a regular file, any non-directory —
|
|
223
|
+
* is a hard {@link StoreIntegrityError} naming the digest and level: a
|
|
224
|
+
* wrong-typed or linked object must never be returned, and (at project level)
|
|
225
|
+
* must never be papered over by a global fall-through.
|
|
226
|
+
*/
|
|
227
|
+
export function probeObjectDir(objectDir, digest, level) {
|
|
228
|
+
try {
|
|
229
|
+
const root = dirname(dirname(dirname(objectDir)));
|
|
230
|
+
return probeDirectoryPath(objectDir, `${level}-level workflow object`, root);
|
|
231
|
+
}
|
|
232
|
+
catch (e) {
|
|
233
|
+
const leaf = lstatSync(objectDir, { throwIfNoEntry: false });
|
|
234
|
+
const detail = leaf?.isSymbolicLink()
|
|
235
|
+
? `${level}-level object dir is a symlink — refusing (no fallback)`
|
|
236
|
+
: leaf !== undefined && !leaf.isDirectory()
|
|
237
|
+
? `${level}-level object dir is not a directory — refusing (no fallback)`
|
|
238
|
+
: `${e.message} — refusing (no fallback)`;
|
|
239
|
+
throw new StoreIntegrityError('object-corrupt', digest, detail);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
class ObjectAbsentDuringCoordinatedRead extends Error {
|
|
243
|
+
}
|
|
244
|
+
async function probeObjectDirCoordinated(root, objectDir, digest, level) {
|
|
245
|
+
try {
|
|
246
|
+
return await coordinateDigestRead(root, digest, () => {
|
|
247
|
+
if (probeObjectDir(objectDir, digest, level) !== 'dir') {
|
|
248
|
+
throw new ObjectAbsentDuringCoordinatedRead();
|
|
249
|
+
}
|
|
250
|
+
return true;
|
|
251
|
+
});
|
|
252
|
+
}
|
|
253
|
+
catch (error) {
|
|
254
|
+
if (error instanceof ObjectAbsentDuringCoordinatedRead)
|
|
255
|
+
return false;
|
|
256
|
+
throw error;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
/** Verify `objectDir` through the A1 adapter, wrapping failures as integrity errors. */
|
|
260
|
+
async function verifyObjectAt(verifier, root, objectDir, digest, level) {
|
|
261
|
+
try {
|
|
262
|
+
await coordinateDigestRead(root, digest, async () => {
|
|
263
|
+
const verify = verifier.verifyInstalledObjectAfterCoordination ?? verifier.verifyInstalledObject;
|
|
264
|
+
await verify.call(verifier, { objectDir, digest });
|
|
265
|
+
});
|
|
266
|
+
}
|
|
267
|
+
catch (e) {
|
|
268
|
+
throw new StoreIntegrityError('object-corrupt', digest, `${level}-level object failed verification: ${e.message}`);
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* Digest-only resolution for EXECUTION. Tests the project object path first
|
|
273
|
+
* when a project root exists, then the global path. An ABSENT project object
|
|
274
|
+
* may fall through to global; a PRESENT project object that fails type
|
|
275
|
+
* probing or verification is a hard integrity error — project tampering is
|
|
276
|
+
* never hidden by falling back to a valid global copy. When both levels hold
|
|
277
|
+
* the same digest, ONE logical result is returned (level `project`, with
|
|
278
|
+
* presence metadata), not two candidates. No index and no workflow name
|
|
279
|
+
* participate. Throws {@link StoreIntegrityError} (`object-missing`) when the
|
|
280
|
+
* digest is present nowhere, or (`object-corrupt`) on any invalid hit.
|
|
281
|
+
*/
|
|
282
|
+
export async function resolveWorkflowDigest(args) {
|
|
283
|
+
const { digest, projectRoot, globalRoot, verifier } = args;
|
|
284
|
+
let projectPresent = false;
|
|
285
|
+
if (projectRoot !== undefined) {
|
|
286
|
+
if (probeStoreRoot(projectRoot) === 'dir') {
|
|
287
|
+
const projectObjectDir = objectDirForDigest(projectRoot, digest);
|
|
288
|
+
projectPresent = await probeObjectDirCoordinated(projectRoot, projectObjectDir, digest, 'project');
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
if (probeStoreRoot(globalRoot) !== 'dir') {
|
|
292
|
+
// An absent/never-initialized global root cannot hold the object.
|
|
293
|
+
if (!projectPresent) {
|
|
294
|
+
throw new StoreIntegrityError('object-missing', digest, 'digest not present in the project or global workflow store');
|
|
295
|
+
}
|
|
296
|
+
// Project present, global root absent: resolve from the project alone.
|
|
297
|
+
const root = projectRoot;
|
|
298
|
+
const objectPath = objectDirForDigest(root, digest);
|
|
299
|
+
await verifyObjectAt(verifier, root, objectPath, digest, 'project');
|
|
300
|
+
return { digest, objectPath, level: 'project', presentAt: { project: true, global: false } };
|
|
301
|
+
}
|
|
302
|
+
const globalObjectDir = objectDirForDigest(globalRoot, digest);
|
|
303
|
+
const globalPresent = await probeObjectDirCoordinated(globalRoot, globalObjectDir, digest, 'global');
|
|
304
|
+
if (projectPresent) {
|
|
305
|
+
// Project wins; verify the object actually returned. The global presence
|
|
306
|
+
// bit is metadata only (same digest by construction — the digest IS the
|
|
307
|
+
// identity), so its copy is not verified here.
|
|
308
|
+
const root = projectRoot;
|
|
309
|
+
const objectPath = objectDirForDigest(root, digest);
|
|
310
|
+
await verifyObjectAt(verifier, root, objectPath, digest, 'project');
|
|
311
|
+
return { digest, objectPath, level: 'project', presentAt: { project: true, global: globalPresent } };
|
|
312
|
+
}
|
|
313
|
+
if (!globalPresent) {
|
|
314
|
+
throw new StoreIntegrityError('object-missing', digest, 'digest not present in the project or global workflow store');
|
|
315
|
+
}
|
|
316
|
+
await verifyObjectAt(verifier, globalRoot, globalObjectDir, digest, 'global');
|
|
317
|
+
return { digest, objectPath: globalObjectDir, level: 'global', presentAt: { project: false, global: true } };
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Human/CLI coordinate resolution. Reads BOTH indexes (fail-closed — a
|
|
321
|
+
* corrupt index is a {@link StoreIndexError}, never silently empty). No
|
|
322
|
+
* entries for the coordinate ⇒ {@link StoreNotFoundError}. A project entry is
|
|
323
|
+
* authoritative when present, even when the global index maps the same
|
|
324
|
+
* coordinate to a different digest; the global entry is the fallback only
|
|
325
|
+
* when the project has no match. The selected object's presence metadata is
|
|
326
|
+
* still reported at both levels. An index entry whose selected object is
|
|
327
|
+
* missing or corrupt is a {@link StoreIntegrityError}, never a returned path.
|
|
328
|
+
* This API is for humans/CLI only — execution resolves digests via
|
|
329
|
+
* {@link resolveWorkflowDigest}.
|
|
330
|
+
*/
|
|
331
|
+
export async function resolveWorkflowCoordinate(args) {
|
|
332
|
+
const { coordinate, projectRoot, globalRoot, verifier } = args;
|
|
333
|
+
let projectDigest;
|
|
334
|
+
if (projectRoot !== undefined && probeStoreRoot(projectRoot) === 'dir') {
|
|
335
|
+
projectDigest = readWorkflowStoreIndex(storeIndexPath(projectRoot)).entries[coordinate]?.digest;
|
|
336
|
+
}
|
|
337
|
+
let globalDigest;
|
|
338
|
+
if (probeStoreRoot(globalRoot) === 'dir') {
|
|
339
|
+
globalDigest = readWorkflowStoreIndex(storeIndexPath(globalRoot)).entries[coordinate]?.digest;
|
|
340
|
+
}
|
|
341
|
+
if (projectDigest === undefined && globalDigest === undefined) {
|
|
342
|
+
throw new StoreNotFoundError(coordinate);
|
|
343
|
+
}
|
|
344
|
+
// Project is the deterministic override. Global participates only when the
|
|
345
|
+
// project index has no matching coordinate.
|
|
346
|
+
const digest = (projectDigest ?? globalDigest);
|
|
347
|
+
const level = projectDigest !== undefined ? 'project' : 'global';
|
|
348
|
+
const root = level === 'project' ? projectRoot : globalRoot;
|
|
349
|
+
const objectDir = objectDirForDigest(root, digest);
|
|
350
|
+
if (!await probeObjectDirCoordinated(root, objectDir, digest, level)) {
|
|
351
|
+
throw new StoreIntegrityError('object-missing', digest, `${level} index references a missing object for '${coordinate}'`);
|
|
352
|
+
}
|
|
353
|
+
await verifyObjectAt(verifier, root, objectDir, digest, level);
|
|
354
|
+
return {
|
|
355
|
+
digest,
|
|
356
|
+
objectPath: objectDir,
|
|
357
|
+
level,
|
|
358
|
+
presentAt: {
|
|
359
|
+
project: projectDigest !== undefined,
|
|
360
|
+
global: globalDigest !== undefined,
|
|
361
|
+
},
|
|
362
|
+
};
|
|
363
|
+
}
|
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The content-addressed workflow store's value types, constructors, and named
|
|
3
|
+
* error classes.
|
|
4
|
+
*
|
|
5
|
+
* TWO DISTINCT "STORES" live in this package — do not conflate them:
|
|
6
|
+
* - `src/store.ts` — the SQLite RUNTIME store (`Store`/`openStore`): engine
|
|
7
|
+
* execution state (workflows, runs, artifacts).
|
|
8
|
+
* - `src/store/` (this directory) — the content-addressed WORKFLOW store:
|
|
9
|
+
* immutable, digest-addressed workflow-definition objects plus a
|
|
10
|
+
* coordinate→digest index, installed from `.wnlp` bundles. This module is
|
|
11
|
+
* its type surface.
|
|
12
|
+
*
|
|
13
|
+
* On-disk layout, at EACH of two levels (project = the resolved defs dir;
|
|
14
|
+
* global = `~/.owenloop/workflows`):
|
|
15
|
+
*
|
|
16
|
+
* <root>/index.json coordinate → digest (+ pinned) index
|
|
17
|
+
* <root>/objects/sha256/<64-hex>/ one immutable object per digest
|
|
18
|
+
*
|
|
19
|
+
* Identity rules: a digest is a lowercase 64-char SHA-256 hex value owned by
|
|
20
|
+
* the bundle format module — this module only VALIDATES the
|
|
21
|
+
* shape (rejecting uppercase/noncanonical input rather than normalizing
|
|
22
|
+
* attacker-controlled data); it never recomputes bundle digests itself. A
|
|
23
|
+
* coordinate is `namespace/name@version` (the FULL coordinate — this module
|
|
24
|
+
* never derives one from a filename or URL). Object paths derive ONLY from
|
|
25
|
+
* validated digests; a coordinate or source URL is never joined into a
|
|
26
|
+
* filesystem path.
|
|
27
|
+
*/
|
|
28
|
+
/** A lowercase 64-char SHA-256 hex digest — the store's only object identity. */
|
|
29
|
+
export declare const DIGEST_RE: RegExp;
|
|
30
|
+
/**
|
|
31
|
+
* One coordinate component (`namespace`, `name`, or `version`). The grammar is
|
|
32
|
+
* deliberately broad: a component is a non-empty string free of control
|
|
33
|
+
* characters and path-significant characters. This module deliberately does
|
|
34
|
+
* NOT impose a semver grammar on `version` — the bundle format module owns
|
|
35
|
+
* version content; this module only keeps components filesystem-safe and
|
|
36
|
+
* unambiguous.
|
|
37
|
+
*/
|
|
38
|
+
export declare const COORDINATE_COMPONENT_RE: RegExp;
|
|
39
|
+
/**
|
|
40
|
+
* A validated bundle object digest (lowercase 64-hex). Construct with
|
|
41
|
+
* {@link defDigest}; the type is branded (a compile-time-only marker — no
|
|
42
|
+
* runtime representation) so a raw string cannot be passed where a validated
|
|
43
|
+
* digest is expected.
|
|
44
|
+
*/
|
|
45
|
+
export type DefDigest = string & {
|
|
46
|
+
readonly __defDigest: true;
|
|
47
|
+
};
|
|
48
|
+
/**
|
|
49
|
+
* A validated full workflow coordinate `namespace/name@version`. Construct
|
|
50
|
+
* with {@link workflowCoordinate} (or parse one with {@link parseWorkflowCoordinate}).
|
|
51
|
+
*/
|
|
52
|
+
export type WorkflowCoordinate = string & {
|
|
53
|
+
readonly __workflowCoordinate: true;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* A named store error: every fail-closed refusal the store produces carries a
|
|
57
|
+
* stable machine-readable `code` alongside the human message, so callers
|
|
58
|
+
* (CLI dispatch, resolution callers, tests) can branch on `instanceof` +
|
|
59
|
+
* `code` instead of matching message text. `path`/`entry`/`coordinate` are
|
|
60
|
+
* present only in messages, never trusted for control flow.
|
|
61
|
+
*/
|
|
62
|
+
export declare class WorkflowStoreError extends Error {
|
|
63
|
+
readonly code: string;
|
|
64
|
+
constructor(code: string, message: string);
|
|
65
|
+
}
|
|
66
|
+
/** The index file failed to parse or failed fail-closed validation. */
|
|
67
|
+
export declare class StoreIndexError extends WorkflowStoreError {
|
|
68
|
+
constructor(message: string);
|
|
69
|
+
}
|
|
70
|
+
/** A digest string failed validation (wrong length/case/charset). */
|
|
71
|
+
export declare class StoreDigestError extends WorkflowStoreError {
|
|
72
|
+
constructor(message: string);
|
|
73
|
+
}
|
|
74
|
+
/** A coordinate string failed construction/parsing validation. */
|
|
75
|
+
export declare class StoreCoordinateError extends WorkflowStoreError {
|
|
76
|
+
constructor(message: string);
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* @deprecated Coordinate resolution is project-first and no longer throws this
|
|
80
|
+
* error when project and global indexes name different digests. The export and
|
|
81
|
+
* constructor remain for compatibility with older callers that import or
|
|
82
|
+
* instantiate the error class.
|
|
83
|
+
*/
|
|
84
|
+
export declare class StoreAmbiguityError extends WorkflowStoreError {
|
|
85
|
+
readonly coordinate: WorkflowCoordinate;
|
|
86
|
+
readonly projectDigest: string;
|
|
87
|
+
readonly globalDigest: string;
|
|
88
|
+
constructor(coordinate: WorkflowCoordinate, projectDigest: string, globalDigest: string);
|
|
89
|
+
}
|
|
90
|
+
/** The coordinate was not found in any consulted level's index. */
|
|
91
|
+
export declare class StoreNotFoundError extends WorkflowStoreError {
|
|
92
|
+
readonly coordinate: WorkflowCoordinate;
|
|
93
|
+
constructor(coordinate: WorkflowCoordinate);
|
|
94
|
+
}
|
|
95
|
+
/** An index entry names a digest whose object is missing or failed verification. */
|
|
96
|
+
export declare class StoreIntegrityError extends WorkflowStoreError {
|
|
97
|
+
readonly digest: string;
|
|
98
|
+
constructor(code: 'object-missing' | 'object-corrupt', digest: string, detail: string);
|
|
99
|
+
}
|
|
100
|
+
/** Installing a coordinate the index already records at a DIFFERENT digest. */
|
|
101
|
+
export declare class StoreConflictError extends WorkflowStoreError {
|
|
102
|
+
readonly coordinate: WorkflowCoordinate;
|
|
103
|
+
readonly existingDigest: string;
|
|
104
|
+
constructor(coordinate: WorkflowCoordinate, existingDigest: string);
|
|
105
|
+
}
|
|
106
|
+
/** The required bundle ingestion adapter was not supplied. Fail-closed. */
|
|
107
|
+
export declare class BundleIngestorUnavailableError extends WorkflowStoreError {
|
|
108
|
+
constructor();
|
|
109
|
+
}
|
|
110
|
+
/** The required pre-commit signature/policy verifier was not supplied. Fail-closed. */
|
|
111
|
+
export declare class PreCommitVerifierUnavailableError extends WorkflowStoreError {
|
|
112
|
+
constructor();
|
|
113
|
+
}
|
|
114
|
+
/** A publication signature verdict was refused by the configured definition policy. */
|
|
115
|
+
export declare class StoreDefinitionVerificationError extends WorkflowStoreError {
|
|
116
|
+
readonly verdict: 'unsigned' | 'unverifiable' | 'invalid';
|
|
117
|
+
readonly policy: 'enforce' | 'warn' | 'off';
|
|
118
|
+
readonly coordinate: WorkflowCoordinate;
|
|
119
|
+
constructor(verdict: 'unsigned' | 'unverifiable' | 'invalid', policy: 'enforce' | 'warn' | 'off', coordinate: WorkflowCoordinate, reason: string);
|
|
120
|
+
}
|
|
121
|
+
/** A provenance rule refused a workflow definition before execution or install. */
|
|
122
|
+
export declare class StoreOriginPolicyError extends WorkflowStoreError {
|
|
123
|
+
readonly coordinate: WorkflowCoordinate;
|
|
124
|
+
readonly namespace: string;
|
|
125
|
+
readonly rule: string;
|
|
126
|
+
readonly verdict: 'absent' | 'unverifiable' | 'invalid' | 'weaker';
|
|
127
|
+
constructor(coordinate: WorkflowCoordinate, namespace: string, rule: string, verdict: 'absent' | 'unverifiable' | 'invalid' | 'weaker', detail: string);
|
|
128
|
+
}
|
|
129
|
+
/** A store root, objects dir, index file, or state path failed a type/symlink guard. */
|
|
130
|
+
export declare class StorePathError extends WorkflowStoreError {
|
|
131
|
+
constructor(message: string);
|
|
132
|
+
}
|
|
133
|
+
/** Validate a raw string as a {@link DefDigest}; throw {@link StoreDigestError} otherwise. */
|
|
134
|
+
export declare function defDigest(raw: string): DefDigest;
|
|
135
|
+
/** True when `raw` is a well-formed digest (lowercase 64-hex). */
|
|
136
|
+
export declare function isDefDigest(raw: string): raw is DefDigest;
|
|
137
|
+
/**
|
|
138
|
+
* Construct a validated {@link WorkflowCoordinate} from its three parts.
|
|
139
|
+
* Each part must be non-empty and free of control/path-significant characters;
|
|
140
|
+
* a violation throws {@link StoreCoordinateError}. The full text
|
|
141
|
+
* `namespace/name@version` is returned branded — the ONLY string shape the
|
|
142
|
+
* store accepts as a coordinate key.
|
|
143
|
+
*/
|
|
144
|
+
export declare function workflowCoordinate(parts: {
|
|
145
|
+
namespace: string;
|
|
146
|
+
name: string;
|
|
147
|
+
version: string;
|
|
148
|
+
}): WorkflowCoordinate;
|
|
149
|
+
/**
|
|
150
|
+
* Parse a full `namespace/name@version` coordinate text into its parts. The
|
|
151
|
+
* version is split at the FINAL `@` and the name at the FIRST `/` before it
|
|
152
|
+
* (a namespace/name itself never contains a slash); every component is
|
|
153
|
+
* validated exactly as {@link workflowCoordinate} validates it. A malformed
|
|
154
|
+
* shape throws {@link StoreCoordinateError}. Never used on untrusted input
|
|
155
|
+
* that then bypasses validation — the returned parts are only as safe as this
|
|
156
|
+
* function's checks.
|
|
157
|
+
*/
|
|
158
|
+
export declare function parseWorkflowCoordinate(text: string): {
|
|
159
|
+
namespace: string;
|
|
160
|
+
name: string;
|
|
161
|
+
version: string;
|
|
162
|
+
};
|
|
163
|
+
/** The two store levels. Project = the resolved defs dir; global = `~/.owenloop/workflows`. */
|
|
164
|
+
export type StoreLevel = 'project' | 'global';
|
|
165
|
+
/** Where a resolution found its object (human-facing result metadata). */
|
|
166
|
+
export type ResolutionLevel = 'project' | 'global';
|
|
167
|
+
/**
|
|
168
|
+
* A total, LOCALE-INDEPENDENT order on store text (coordinates, digests,
|
|
169
|
+
* qualified names). `String.prototype.localeCompare` is deliberately avoided
|
|
170
|
+
* throughout the store: without an explicit locale its result depends on the
|
|
171
|
+
* host's ICU data, so two machines walking the same index could disagree on
|
|
172
|
+
* order.
|
|
173
|
+
*
|
|
174
|
+
* This is UTF-16 code-unit order (JS `<` on strings), which differs from true
|
|
175
|
+
* codepoint order for astral characters. That difference does not matter here:
|
|
176
|
+
* the requirement is a total order identical on every host, not one that
|
|
177
|
+
* matches any particular alphabet.
|
|
178
|
+
*
|
|
179
|
+
* This orders ENUMERATION only. It never decides which version of a package is
|
|
180
|
+
* the current one — {@link selectLatestVersion} owns that and is the store's
|
|
181
|
+
* only version-selection rule.
|
|
182
|
+
*/
|
|
183
|
+
export declare function compareStoreText(a: string, b: string): number;
|
|
184
|
+
/**
|
|
185
|
+
* One competitor for an unqualified `package/workflow` registration: a single
|
|
186
|
+
* verified bundle object that exports that workflow.
|
|
187
|
+
*
|
|
188
|
+
* `version` is the bundle MANIFEST's package version, never a version parsed
|
|
189
|
+
* back out of a coordinate string — the manifest is the object's own statement
|
|
190
|
+
* of what it is, and the caller has already proven the coordinate agrees with
|
|
191
|
+
* it before building a candidate.
|
|
192
|
+
*
|
|
193
|
+
* `level` is the level of the INDEX that named the object, not the store the
|
|
194
|
+
* object's bytes were read from. A project-indexed object whose bytes were
|
|
195
|
+
* served from the global store by exact-digest fallback is still a project
|
|
196
|
+
* candidate: the project index is what pins it.
|
|
197
|
+
*/
|
|
198
|
+
export interface VersionSelectionCandidate {
|
|
199
|
+
/** Manifest package version of the bundle supplying this candidate. */
|
|
200
|
+
version: string;
|
|
201
|
+
/** Store level that supplied the candidate's verified bytes. */
|
|
202
|
+
level: ResolutionLevel;
|
|
203
|
+
/** Verified bundle object digest — unique per object, so the final tiebreak never ties. */
|
|
204
|
+
digest: string;
|
|
205
|
+
}
|
|
206
|
+
/**
|
|
207
|
+
* The outcome of {@link selectLatestVersion}.
|
|
208
|
+
*
|
|
209
|
+
* `selected` — `winner` takes the unqualified name; every entry in `shadowed`
|
|
210
|
+
* stays reachable only under its digest-scoped key.
|
|
211
|
+
*
|
|
212
|
+
* `unorderable` — no candidate may take the unqualified name, because more than
|
|
213
|
+
* one candidate competes and NONE carries a canonical SemVer version. Every
|
|
214
|
+
* candidate is returned in `shadowed`. This is fail-closed on purpose: silently
|
|
215
|
+
* picking one of several versions that have no defined precedence is exactly
|
|
216
|
+
* the accidental-order defect this helper exists to remove.
|
|
217
|
+
*
|
|
218
|
+
* An EMPTY candidate list also yields `unorderable`, with an empty `shadowed`.
|
|
219
|
+
* There is no winner to report and nothing to shadow, so a caller that
|
|
220
|
+
* registers `winner` and every `shadowed` entry correctly registers nothing.
|
|
221
|
+
*
|
|
222
|
+
* `unorderable.competing` is the subset of `shadowed` that actually reached the
|
|
223
|
+
* version comparison — i.e. what survived the level filter. Anything in
|
|
224
|
+
* `shadowed` but not in `competing` was dropped by LEVEL, never judged on its
|
|
225
|
+
* version, and a diagnostic must not describe it as if it had been. A global
|
|
226
|
+
* `1.0.0` sitting behind a project-indexed `nightly` is perfectly good SemVer;
|
|
227
|
+
* it simply never competed.
|
|
228
|
+
*/
|
|
229
|
+
export type LatestVersionSelection<T> = {
|
|
230
|
+
kind: 'selected';
|
|
231
|
+
winner: T;
|
|
232
|
+
shadowed: T[];
|
|
233
|
+
} | {
|
|
234
|
+
kind: 'unorderable';
|
|
235
|
+
shadowed: T[];
|
|
236
|
+
competing: T[];
|
|
237
|
+
};
|
|
238
|
+
/**
|
|
239
|
+
* Choose the ONE candidate that holds an unqualified `package/workflow` name.
|
|
240
|
+
*
|
|
241
|
+
* Two rules apply in order, and neither consults arrival order:
|
|
242
|
+
*
|
|
243
|
+
* 1. LEVEL FIRST. If any candidate is named by the project index, only project
|
|
244
|
+
* candidates compete. This mirrors `resolveWorkflowCoordinate`, where the
|
|
245
|
+
* project index is the deterministic override: a project install of
|
|
246
|
+
* `pkg@0.1.0` beats a global install of `pkg@0.9.9`, because the project
|
|
247
|
+
* store is how an operator pins a workspace to a specific definition.
|
|
248
|
+
* 2. VERSION SECOND, by {@link compareVersionCandidates}, among the candidates
|
|
249
|
+
* at that one level.
|
|
250
|
+
*
|
|
251
|
+
* When the surviving group holds more than one candidate and none carries a
|
|
252
|
+
* canonical SemVer version, the result is `unorderable` and the unqualified name
|
|
253
|
+
* goes unregistered. A SINGLE non-SemVer candidate still wins its name — there
|
|
254
|
+
* is nothing to order, so refusing it would break `pkg@nightly` installs for no
|
|
255
|
+
* determinism gain.
|
|
256
|
+
*/
|
|
257
|
+
export declare function selectLatestVersion<T extends VersionSelectionCandidate>(candidates: readonly T[]): LatestVersionSelection<T>;
|
|
258
|
+
/** One index entry: the digest a coordinate currently records, plus its pin state. */
|
|
259
|
+
export interface WorkflowStoreIndexEntry {
|
|
260
|
+
digest: string;
|
|
261
|
+
pinned: boolean;
|
|
262
|
+
/** Sorted workflow names carried by the installed bundle, when known. */
|
|
263
|
+
workflows?: string[];
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* The workflow-store index shape (one per store root). Keys are FULL
|
|
267
|
+
* coordinates `namespace/name@version`; values record the coordinate's digest
|
|
268
|
+
* and pin state. `version` is always exactly `1` (validated fail-closed on
|
|
269
|
+
* read). Unknown additive fields are tolerated for forward compatibility;
|
|
270
|
+
* required fields are enforced.
|
|
271
|
+
*/
|
|
272
|
+
export interface WorkflowStoreIndex {
|
|
273
|
+
version: 1;
|
|
274
|
+
entries: Record<string, WorkflowStoreIndexEntry>;
|
|
275
|
+
}
|
|
276
|
+
/** The index filename at a store root. */
|
|
277
|
+
export declare const WORKFLOW_STORE_INDEX_FILENAME = "index.json";
|
|
278
|
+
/** The objects subtree at a store root: `objects/sha256/<digest>/`. */
|
|
279
|
+
export declare const WORKFLOW_OBJECTS_DIRNAME = "objects";
|
|
280
|
+
/** The digest algorithm directory under `objects/` (sha256 is the only one). */
|
|
281
|
+
export declare const WORKFLOW_OBJECTS_ALGO = "sha256";
|
|
282
|
+
/**
|
|
283
|
+
* Derive the object directory for a validated digest under `root`. Digests are
|
|
284
|
+
* validated BEFORE this joins anything: a coordinate or URL must never reach a
|
|
285
|
+
* filesystem path. The digest is a single path segment by construction (64 hex
|
|
286
|
+
* chars), so the join cannot escape `root`.
|
|
287
|
+
*/
|
|
288
|
+
export declare function objectDirForDigest(root: string, digest: DefDigest): string;
|