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,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;