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,356 @@
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
+ import { createRequire } from 'node:module';
29
+ import { join } from 'node:path';
30
+ import { isCanonicalSemver } from "../bundle/runtime.js";
31
+ const semver = createRequire(import.meta.url)('semver');
32
+ /** A lowercase 64-char SHA-256 hex digest — the store's only object identity. */
33
+ export const DIGEST_RE = /^[0-9a-f]{64}$/;
34
+ /**
35
+ * One coordinate component (`namespace`, `name`, or `version`). The grammar is
36
+ * deliberately broad: a component is a non-empty string free of control
37
+ * characters and path-significant characters. This module deliberately does
38
+ * NOT impose a semver grammar on `version` — the bundle format module owns
39
+ * version content; this module only keeps components filesystem-safe and
40
+ * unambiguous.
41
+ */
42
+ // eslint-disable-next-line no-control-regex -- the control-character exclusion IS the point: components must be filesystem-safe, so the range is deliberate.
43
+ export const COORDINATE_COMPONENT_RE = /^[^\x00-\x1f\x7f\\/:%#?]+$/;
44
+ /**
45
+ * A named store error: every fail-closed refusal the store produces carries a
46
+ * stable machine-readable `code` alongside the human message, so callers
47
+ * (CLI dispatch, resolution callers, tests) can branch on `instanceof` +
48
+ * `code` instead of matching message text. `path`/`entry`/`coordinate` are
49
+ * present only in messages, never trusted for control flow.
50
+ */
51
+ export class WorkflowStoreError extends Error {
52
+ code;
53
+ constructor(code, message) {
54
+ super(message);
55
+ this.name = 'WorkflowStoreError';
56
+ this.code = code;
57
+ }
58
+ }
59
+ /** The index file failed to parse or failed fail-closed validation. */
60
+ export class StoreIndexError extends WorkflowStoreError {
61
+ constructor(message) {
62
+ super('index-invalid', message);
63
+ this.name = 'StoreIndexError';
64
+ }
65
+ }
66
+ /** A digest string failed validation (wrong length/case/charset). */
67
+ export class StoreDigestError extends WorkflowStoreError {
68
+ constructor(message) {
69
+ super('digest-invalid', message);
70
+ this.name = 'StoreDigestError';
71
+ }
72
+ }
73
+ /** A coordinate string failed construction/parsing validation. */
74
+ export class StoreCoordinateError extends WorkflowStoreError {
75
+ constructor(message) {
76
+ super('coordinate-invalid', message);
77
+ this.name = 'StoreCoordinateError';
78
+ }
79
+ }
80
+ /**
81
+ * @deprecated Coordinate resolution is project-first and no longer throws this
82
+ * error when project and global indexes name different digests. The export and
83
+ * constructor remain for compatibility with older callers that import or
84
+ * instantiate the error class.
85
+ */
86
+ export class StoreAmbiguityError extends WorkflowStoreError {
87
+ coordinate;
88
+ projectDigest;
89
+ globalDigest;
90
+ constructor(coordinate, projectDigest, globalDigest) {
91
+ super('coordinate-ambiguous', `coordinate '${coordinate}' resolves to different digests in the project store ` +
92
+ `(${projectDigest}) and the global store (${globalDigest}) — ` +
93
+ `resolve the ambiguity explicitly instead of guessing`);
94
+ this.name = 'StoreAmbiguityError';
95
+ this.coordinate = coordinate;
96
+ this.projectDigest = projectDigest;
97
+ this.globalDigest = globalDigest;
98
+ }
99
+ }
100
+ /** The coordinate was not found in any consulted level's index. */
101
+ export class StoreNotFoundError extends WorkflowStoreError {
102
+ coordinate;
103
+ constructor(coordinate) {
104
+ super('coordinate-not-found', `coordinate '${coordinate}' is not in the workflow store index`);
105
+ this.name = 'StoreNotFoundError';
106
+ this.coordinate = coordinate;
107
+ }
108
+ }
109
+ /** An index entry names a digest whose object is missing or failed verification. */
110
+ export class StoreIntegrityError extends WorkflowStoreError {
111
+ digest;
112
+ constructor(code, digest, detail) {
113
+ super(code, `object ${digest}: ${detail}`);
114
+ this.name = 'StoreIntegrityError';
115
+ this.digest = digest;
116
+ }
117
+ }
118
+ /** Installing a coordinate the index already records at a DIFFERENT digest. */
119
+ export class StoreConflictError extends WorkflowStoreError {
120
+ coordinate;
121
+ existingDigest;
122
+ constructor(coordinate, existingDigest) {
123
+ super('coordinate-conflict', `coordinate '${coordinate}' is already recorded at digest ${existingDigest} — ` +
124
+ `an existing coordinate is never silently retargeted to a different digest ` +
125
+ `(use an explicit pin/update)`);
126
+ this.name = 'StoreConflictError';
127
+ this.coordinate = coordinate;
128
+ this.existingDigest = existingDigest;
129
+ }
130
+ }
131
+ /** The required bundle ingestion adapter was not supplied. Fail-closed. */
132
+ export class BundleIngestorUnavailableError extends WorkflowStoreError {
133
+ constructor() {
134
+ super('bundle-ingestor-unavailable', 'bundle ingestion is unavailable: no BundleIngestor adapter is bound — ' +
135
+ 'nothing was staged or committed');
136
+ this.name = 'BundleIngestorUnavailableError';
137
+ }
138
+ }
139
+ /** The required pre-commit signature/policy verifier was not supplied. Fail-closed. */
140
+ export class PreCommitVerifierUnavailableError extends WorkflowStoreError {
141
+ constructor() {
142
+ super('pre-commit-verifier-unavailable', 'pre-commit verification is unavailable: no PreCommitVerifier adapter is bound — ' +
143
+ 'nothing was staged or committed');
144
+ this.name = 'PreCommitVerifierUnavailableError';
145
+ }
146
+ }
147
+ /** A publication signature verdict was refused by the configured definition policy. */
148
+ export class StoreDefinitionVerificationError extends WorkflowStoreError {
149
+ verdict;
150
+ policy;
151
+ coordinate;
152
+ constructor(verdict, policy, coordinate, reason) {
153
+ super('definition-verification-refused', `definition '${coordinate}' was refused by defPolicy=${policy}: ${verdict} — ${reason}`);
154
+ this.name = 'StoreDefinitionVerificationError';
155
+ this.verdict = verdict;
156
+ this.policy = policy;
157
+ this.coordinate = coordinate;
158
+ }
159
+ }
160
+ /** A provenance rule refused a workflow definition before execution or install. */
161
+ export class StoreOriginPolicyError extends WorkflowStoreError {
162
+ coordinate;
163
+ namespace;
164
+ rule;
165
+ verdict;
166
+ constructor(coordinate, namespace, rule, verdict, detail) {
167
+ super('origin-policy-refused', `definition '${coordinate}' was refused by originRules=${rule} for namespace '${namespace}': ${verdict} — ${detail}`);
168
+ this.name = 'StoreOriginPolicyError';
169
+ this.coordinate = coordinate;
170
+ this.namespace = namespace;
171
+ this.rule = rule;
172
+ this.verdict = verdict;
173
+ }
174
+ }
175
+ /** A store root, objects dir, index file, or state path failed a type/symlink guard. */
176
+ export class StorePathError extends WorkflowStoreError {
177
+ constructor(message) {
178
+ super('path-refused', message);
179
+ this.name = 'StorePathError';
180
+ }
181
+ }
182
+ /** Validate a raw string as a {@link DefDigest}; throw {@link StoreDigestError} otherwise. */
183
+ export function defDigest(raw) {
184
+ if (!DIGEST_RE.test(raw)) {
185
+ throw new StoreDigestError(`invalid def digest ${JSON.stringify(raw)} — expected a lowercase 64-char sha256 hex value`);
186
+ }
187
+ return raw;
188
+ }
189
+ /** True when `raw` is a well-formed digest (lowercase 64-hex). */
190
+ export function isDefDigest(raw) {
191
+ return DIGEST_RE.test(raw);
192
+ }
193
+ function validateCoordinateComponent(kind, value) {
194
+ if (value === '') {
195
+ throw new StoreCoordinateError(`invalid coordinate: ${kind} is empty`);
196
+ }
197
+ if (!COORDINATE_COMPONENT_RE.test(value)) {
198
+ throw new StoreCoordinateError(`invalid coordinate: ${kind} ${JSON.stringify(value)} contains a control or path-significant character`);
199
+ }
200
+ }
201
+ /**
202
+ * Construct a validated {@link WorkflowCoordinate} from its three parts.
203
+ * Each part must be non-empty and free of control/path-significant characters;
204
+ * a violation throws {@link StoreCoordinateError}. The full text
205
+ * `namespace/name@version` is returned branded — the ONLY string shape the
206
+ * store accepts as a coordinate key.
207
+ */
208
+ export function workflowCoordinate(parts) {
209
+ validateCoordinateComponent('namespace', parts.namespace);
210
+ validateCoordinateComponent('name', parts.name);
211
+ validateCoordinateComponent('version', parts.version);
212
+ return `${parts.namespace}/${parts.name}@${parts.version}`;
213
+ }
214
+ /**
215
+ * Parse a full `namespace/name@version` coordinate text into its parts. The
216
+ * version is split at the FINAL `@` and the name at the FIRST `/` before it
217
+ * (a namespace/name itself never contains a slash); every component is
218
+ * validated exactly as {@link workflowCoordinate} validates it. A malformed
219
+ * shape throws {@link StoreCoordinateError}. Never used on untrusted input
220
+ * that then bypasses validation — the returned parts are only as safe as this
221
+ * function's checks.
222
+ */
223
+ export function parseWorkflowCoordinate(text) {
224
+ const at = text.lastIndexOf('@');
225
+ if (at <= 0 || at === text.length - 1) {
226
+ throw new StoreCoordinateError(`invalid coordinate ${JSON.stringify(text)} — expected 'namespace/name@version'`);
227
+ }
228
+ const namespaceAndName = text.slice(0, at);
229
+ const version = text.slice(at + 1);
230
+ const slash = namespaceAndName.indexOf('/');
231
+ if (slash <= 0 || slash === namespaceAndName.length - 1) {
232
+ throw new StoreCoordinateError(`invalid coordinate ${JSON.stringify(text)} — expected 'namespace/name@version'`);
233
+ }
234
+ const namespace = namespaceAndName.slice(0, slash);
235
+ const name = namespaceAndName.slice(slash + 1);
236
+ if (name.includes('/')) {
237
+ throw new StoreCoordinateError(`invalid coordinate ${JSON.stringify(text)} — expected exactly one '/' before the version`);
238
+ }
239
+ const coordinate = workflowCoordinate({ namespace, name, version });
240
+ // Defensive round-trip: the reconstructed full text must equal the input —
241
+ // a coordinate is only ever stored/compared in its exact input form.
242
+ if (coordinate !== text) {
243
+ throw new StoreCoordinateError(`invalid coordinate ${JSON.stringify(text)} — non-canonical form`);
244
+ }
245
+ return { namespace, name, version };
246
+ }
247
+ // ---- deterministic ordering and version selection -----------------------------
248
+ /**
249
+ * A total, LOCALE-INDEPENDENT order on store text (coordinates, digests,
250
+ * qualified names). `String.prototype.localeCompare` is deliberately avoided
251
+ * throughout the store: without an explicit locale its result depends on the
252
+ * host's ICU data, so two machines walking the same index could disagree on
253
+ * order.
254
+ *
255
+ * This is UTF-16 code-unit order (JS `<` on strings), which differs from true
256
+ * codepoint order for astral characters. That difference does not matter here:
257
+ * the requirement is a total order identical on every host, not one that
258
+ * matches any particular alphabet.
259
+ *
260
+ * This orders ENUMERATION only. It never decides which version of a package is
261
+ * the current one — {@link selectLatestVersion} owns that and is the store's
262
+ * only version-selection rule.
263
+ */
264
+ export function compareStoreText(a, b) {
265
+ if (a < b)
266
+ return -1;
267
+ if (a > b)
268
+ return 1;
269
+ return 0;
270
+ }
271
+ /**
272
+ * Rank two same-level candidates, BEST FIRST.
273
+ *
274
+ * 1. A canonical SemVer version outranks a non-SemVer one. A version the store
275
+ * cannot order never displaces one it can.
276
+ * 2. Between two canonical SemVer versions, higher SemVer precedence wins
277
+ * (SemVer §11 — so `0.1.10` beats `0.1.2`, and `1.0.0` beats `1.0.0-rc.1`).
278
+ * 3. Otherwise the two are indistinguishable by precedence: either they differ
279
+ * only in build metadata, or neither is SemVer at all. Fall through to raw
280
+ * text, then to the digest, purely so the answer is STABLE. Neither of those
281
+ * last two steps claims to say which version is newer; they exist so the
282
+ * result never depends on index insertion, filesystem, or install order.
283
+ */
284
+ function compareVersionCandidates(a, b) {
285
+ const aOrderable = isCanonicalSemver(a.version);
286
+ const bOrderable = isCanonicalSemver(b.version);
287
+ if (aOrderable !== bOrderable)
288
+ return aOrderable ? -1 : 1;
289
+ if (aOrderable && bOrderable) {
290
+ const byPrecedence = semver.compare(b.version, a.version);
291
+ if (byPrecedence !== 0)
292
+ return byPrecedence;
293
+ }
294
+ const byText = compareStoreText(b.version, a.version);
295
+ if (byText !== 0)
296
+ return byText;
297
+ return compareStoreText(a.digest, b.digest);
298
+ }
299
+ /**
300
+ * Choose the ONE candidate that holds an unqualified `package/workflow` name.
301
+ *
302
+ * Two rules apply in order, and neither consults arrival order:
303
+ *
304
+ * 1. LEVEL FIRST. If any candidate is named by the project index, only project
305
+ * candidates compete. This mirrors `resolveWorkflowCoordinate`, where the
306
+ * project index is the deterministic override: a project install of
307
+ * `pkg@0.1.0` beats a global install of `pkg@0.9.9`, because the project
308
+ * store is how an operator pins a workspace to a specific definition.
309
+ * 2. VERSION SECOND, by {@link compareVersionCandidates}, among the candidates
310
+ * at that one level.
311
+ *
312
+ * When the surviving group holds more than one candidate and none carries a
313
+ * canonical SemVer version, the result is `unorderable` and the unqualified name
314
+ * goes unregistered. A SINGLE non-SemVer candidate still wins its name — there
315
+ * is nothing to order, so refusing it would break `pkg@nightly` installs for no
316
+ * determinism gain.
317
+ */
318
+ export function selectLatestVersion(candidates) {
319
+ if (candidates.length === 0)
320
+ return { kind: 'unorderable', shadowed: [], competing: [] };
321
+ const hasProject = candidates.some((candidate) => candidate.level === 'project');
322
+ const competing = hasProject
323
+ ? candidates.filter((candidate) => candidate.level === 'project')
324
+ : [...candidates];
325
+ const outranked = hasProject
326
+ ? candidates.filter((candidate) => candidate.level !== 'project')
327
+ : [];
328
+ const ranked = [...competing].sort(compareVersionCandidates);
329
+ const best = ranked[0];
330
+ // Rule 1 sorts every orderable candidate ahead of every unorderable one, so a
331
+ // non-SemVer `best` proves the whole competing group is unorderable.
332
+ if (!isCanonicalSemver(best.version) && ranked.length > 1) {
333
+ return { kind: 'unorderable', shadowed: [...ranked, ...outranked], competing: ranked };
334
+ }
335
+ return { kind: 'selected', winner: best, shadowed: [...ranked.slice(1), ...outranked] };
336
+ }
337
+ /** The index filename at a store root. */
338
+ export const WORKFLOW_STORE_INDEX_FILENAME = 'index.json';
339
+ /** The objects subtree at a store root: `objects/sha256/<digest>/`. */
340
+ export const WORKFLOW_OBJECTS_DIRNAME = 'objects';
341
+ /** The digest algorithm directory under `objects/` (sha256 is the only one). */
342
+ export const WORKFLOW_OBJECTS_ALGO = 'sha256';
343
+ /**
344
+ * Derive the object directory for a validated digest under `root`. Digests are
345
+ * validated BEFORE this joins anything: a coordinate or URL must never reach a
346
+ * filesystem path. The digest is a single path segment by construction (64 hex
347
+ * chars), so the join cannot escape `root`.
348
+ */
349
+ export function objectDirForDigest(root, digest) {
350
+ // Re-assert the shape at the derivation site (belt-and-braces; the brand is
351
+ // compile-time only).
352
+ if (!DIGEST_RE.test(digest)) {
353
+ throw new StoreDigestError(`refusing to derive an object path from ${JSON.stringify(digest)}`);
354
+ }
355
+ return join(root, WORKFLOW_OBJECTS_DIRNAME, WORKFLOW_OBJECTS_ALGO, digest);
356
+ }
@@ -13,7 +13,7 @@
13
13
  * and (de)serialized at the boundary so callers always see real objects.
14
14
  */
15
15
  import { DatabaseSync } from 'node:sqlite';
16
- import type { ArtifactData, ArtifactHistory, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
16
+ import type { ArtifactData, ArtifactHistory, Author, RunData, TaskData, WorkflowData, WorkflowDef } from './types.ts';
17
17
  export interface ArtifactRow extends ArtifactData {
18
18
  id: string;
19
19
  updatedAt: number;
@@ -120,6 +120,38 @@ export declare class Store {
120
120
  key?: string;
121
121
  }): ArtifactRow;
122
122
  private insertArtifactEvent;
123
+ /**
124
+ * Append one engine-authored history record for an artifact, WITHOUT touching
125
+ * the artifact row.
126
+ *
127
+ * `putArtifact` already writes an event per lifecycle change, but only when
128
+ * the artifact's own data changed. Some engine decisions are about an
129
+ * artifact without changing it — the escalation transition is the first: the
130
+ * routing of the next offer changes, the artifact does not. Those need a
131
+ * record too, and this is the only way to write one.
132
+ *
133
+ * **Idempotent by construction.** The row id is derived from
134
+ * `(workflow, path, version, dedupe)` and the insert is
135
+ * `ON CONFLICT(id) DO NOTHING`, so a caller that recomputes the same decision
136
+ * on every tick — as the escalation rule does, since it is derived state and
137
+ * not a stored flag — writes exactly one row. The caller owns `dedupe`: make
138
+ * it identify the EPISODE, not the moment.
139
+ *
140
+ * Pass `version: 0` for a record that belongs to the artifact as a whole
141
+ * rather than to one produced version; `getArtifactHistory` surfaces those in
142
+ * its artifact-level `events` bucket. Detail goes in `metadata`.
143
+ */
144
+ recordArtifactEvent(event: {
145
+ workflow: string;
146
+ path: string;
147
+ version: number;
148
+ action: string;
149
+ actor: Author;
150
+ dedupe: string;
151
+ timestamp: number;
152
+ reason?: string;
153
+ metadata?: Record<string, unknown>;
154
+ }): void;
123
155
  /** Returns history for exactly one artifact; list/status reads stay projection-only. */
124
156
  getArtifactHistory(workflow: string, path: string): ArtifactHistory | undefined;
125
157
  deleteArtifact(workflow: string, path: string): void;
package/dist/src/store.js CHANGED
@@ -28,6 +28,7 @@ CREATE TABLE IF NOT EXISTS workflow (
28
28
  def TEXT NOT NULL,
29
29
  title TEXT,
30
30
  params TEXT NOT NULL DEFAULT '{}',
31
+ modifier TEXT,
31
32
  created_at INTEGER NOT NULL
32
33
  );
33
34
 
@@ -144,8 +145,13 @@ CREATE TABLE IF NOT EXISTS meta (
144
145
  * driver ticks cannot each insert a child for the same `calls:` step.
145
146
  *
146
147
  * Bumped to '9' for immutable artifact payload/version and lifecycle-event history.
148
+ *
149
+ * Bumped to '10' for the routing modifier: the `workflow` table gains a
150
+ * nullable `modifier` column (see `migrate()`). Additive and un-backfilled —
151
+ * NULL on every existing row means "unmodified run", which is the correct
152
+ * reading of an instance created before modifiers existed.
147
153
  */
148
- const SCHEMA_VERSION = '9';
154
+ const SCHEMA_VERSION = '10';
149
155
  /** Thrown by the `Store` constructor when the on-disk `schema_version` is
150
156
  * newer than this binary's `SCHEMA_VERSION` — the operator needs to
151
157
  * upgrade their owenloop install to open this database. */
@@ -358,6 +364,11 @@ function mapWorkflow(r) {
358
364
  out.defSnapshot = defSnapshot;
359
365
  if (r.def_hash !== null)
360
366
  out.defHash = r.def_hash;
367
+ // NULL (a pre-modifier row, or a run started without one) maps to absent,
368
+ // never to an empty string — 'unmodified run' and 'modifier ""' must not
369
+ // become the same thing downstream, where '' would compose 'build:'.
370
+ if (r.modifier !== null)
371
+ out.modifier = r.modifier;
361
372
  return out;
362
373
  }
363
374
  // ---- the store ---------------------------------------------------------------
@@ -506,6 +517,14 @@ export class Store {
506
517
  if (!wfCols.some((c) => c.name === 'def_hash')) {
507
518
  this.db.exec(`ALTER TABLE workflow ADD COLUMN def_hash TEXT`);
508
519
  }
520
+ // Routing modifier: the ONE modifier this instance carries, set once at
521
+ // creation and never written again. NULL on every pre-existing row, which
522
+ // is exactly right — an instance created before modifiers existed is an
523
+ // unmodified run and every step is offered on bare capabilities. No
524
+ // backfill: there is no value to invent.
525
+ if (!wfCols.some((c) => c.name === 'modifier')) {
526
+ this.db.exec(`ALTER TABLE workflow ADD COLUMN modifier TEXT`);
527
+ }
509
528
  // Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
510
529
  // reason thread. Re-opening an already-v8 database must not manufacture a
511
530
  // second copy of its lifecycle events (even though the legacy keys differ
@@ -562,9 +581,9 @@ export class Store {
562
581
  const at = nowMs();
563
582
  this.db
564
583
  .prepare(`INSERT INTO workflow
565
- (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, created_at)
566
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
567
- .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, at);
584
+ (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, created_at)
585
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
586
+ .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, at);
568
587
  return this.getWorkflow(id);
569
588
  }
570
589
  /**
@@ -717,6 +736,40 @@ export class Store {
717
736
  this.db.prepare(`INSERT INTO artifact_event (id, workflow, path, version, action, actor, reason, kind, metadata, created_at)
718
737
  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(id) DO NOTHING`).run(id, event.workflow, event.path, event.version, event.action, event.actor, event.reason ?? null, event.kind ?? null, toJson(event.metadata), event.timestamp);
719
738
  }
739
+ /**
740
+ * Append one engine-authored history record for an artifact, WITHOUT touching
741
+ * the artifact row.
742
+ *
743
+ * `putArtifact` already writes an event per lifecycle change, but only when
744
+ * the artifact's own data changed. Some engine decisions are about an
745
+ * artifact without changing it — the escalation transition is the first: the
746
+ * routing of the next offer changes, the artifact does not. Those need a
747
+ * record too, and this is the only way to write one.
748
+ *
749
+ * **Idempotent by construction.** The row id is derived from
750
+ * `(workflow, path, version, dedupe)` and the insert is
751
+ * `ON CONFLICT(id) DO NOTHING`, so a caller that recomputes the same decision
752
+ * on every tick — as the escalation rule does, since it is derived state and
753
+ * not a stored flag — writes exactly one row. The caller owns `dedupe`: make
754
+ * it identify the EPISODE, not the moment.
755
+ *
756
+ * Pass `version: 0` for a record that belongs to the artifact as a whole
757
+ * rather than to one produced version; `getArtifactHistory` surfaces those in
758
+ * its artifact-level `events` bucket. Detail goes in `metadata`.
759
+ */
760
+ recordArtifactEvent(event) {
761
+ this.insertArtifactEvent({
762
+ workflow: event.workflow,
763
+ path: event.path,
764
+ version: event.version,
765
+ action: event.action,
766
+ actor: event.actor,
767
+ timestamp: event.timestamp,
768
+ key: event.dedupe,
769
+ ...(event.reason !== undefined ? { reason: event.reason } : {}),
770
+ ...(event.metadata !== undefined ? { metadata: event.metadata } : {}),
771
+ });
772
+ }
720
773
  /** Returns history for exactly one artifact; list/status reads stay projection-only. */
721
774
  getArtifactHistory(workflow, path) {
722
775
  const current = this.getArtifact(workflow, path);