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,238 @@
1
+ /**
2
+ * Deterministic `.wnlp` archive writer (WP-A1).
3
+ *
4
+ * Canonical tar rules (see `docs/bundles.md`): regular-file entries only,
5
+ * `/`-separated paths sorted by ascending UTF-8 bytes, uid/gid 0, empty
6
+ * uname/gname, mtime 0, mode 0755 when any source execute bit is set and
7
+ * 0644 otherwise, USTAR name when it fits (UTF-8 bytes ≤ 100), else ONE
8
+ * deterministic POSIX PAX `path` extended record in a `PaxHeader` block
9
+ * (mode 0644, uid/gid 0, mtime 0), exactly two trailing zero blocks. The
10
+ * gzip wrapper uses fixed options, zero mtime bytes, and OS byte 0 (patched
11
+ * explicitly — Node reports OS 19 on Darwin). The raw header helpers are
12
+ * deliberately module-private: the public bundle surface exposes only the
13
+ * high-level pack/inspect/digest/unpack API.
14
+ */
15
+ import { lstatSync, readdirSync } from 'node:fs';
16
+ import { join, resolve } from 'node:path';
17
+ import { gzipSync } from 'node:zlib';
18
+ import { canonicalBundleFilePrefix, canonicalBundlePathViolation, canonicalPaxNamePlaceholder, DEFAULT_TAR_LIMITS, } from "../archive.js";
19
+ import { BundleError } from "./types.js";
20
+ const BLOCK = 512;
21
+ /** Fixed gzip level for canonical output. */
22
+ export const BUNDLE_GZIP_LEVEL = 9;
23
+ /** An octal header field: `width - 1` zero-padded octal digits plus a trailing NUL. */
24
+ function octalField(value, width) {
25
+ const digits = value.toString(8);
26
+ if (digits.length > width - 1) {
27
+ throw new BundleError('MANIFEST_ERROR', `tar field overflow: ${value} does not fit ${width} bytes`);
28
+ }
29
+ return Buffer.from(digits.padStart(width - 1, '0') + '\0', 'ascii');
30
+ }
31
+ function padBlock(data) {
32
+ const padded = Math.ceil(data.length / BLOCK) * BLOCK;
33
+ const out = Buffer.alloc(padded);
34
+ Buffer.from(data).copy(out);
35
+ return out;
36
+ }
37
+ /**
38
+ * One 512-byte canonical USTAR header: name (ASCII, ≤100 bytes), mode,
39
+ * uid/gid 0, size, mtime 0, checksum, typeflag, magic `ustar\0`, version
40
+ * `00`, empty uname/gname and blank prefix/dev fields (zero-filled).
41
+ */
42
+ function buildHeader(name, size, typeflag, mode) {
43
+ const buf = Buffer.alloc(BLOCK);
44
+ const nameBytes = Buffer.from(name, 'utf8');
45
+ if (nameBytes.length > 100) {
46
+ throw new BundleError('ARCHIVE_PATH_TOO_LONG', `tar name field cannot hold '${name}'`);
47
+ }
48
+ nameBytes.copy(buf, 0);
49
+ octalField(mode, 8).copy(buf, 100);
50
+ octalField(0, 8).copy(buf, 108); // uid
51
+ octalField(0, 8).copy(buf, 116); // gid
52
+ octalField(size, 12).copy(buf, 124);
53
+ octalField(0, 12).copy(buf, 136); // mtime
54
+ buf.fill(0x20, 148, 156); // checksum field: spaces while computing
55
+ buf[156] = typeflag.charCodeAt(0);
56
+ buf.write('ustar', 257, 'ascii'); // magic "ustar\0" (rest zero-filled)
57
+ buf[262] = 0;
58
+ buf.write('00', 263, 2, 'ascii'); // version
59
+ // uname/gname (265..329), linkname (329..400), prefix (345..500), devmajor/
60
+ // devminor stay zero — canonical.
61
+ let sum = 0;
62
+ for (let i = 0; i < BLOCK; i++)
63
+ sum += buf[i];
64
+ const chksum = Buffer.from(sum.toString(8).padStart(6, '0') + '\0 ', 'ascii');
65
+ chksum.copy(buf, 148);
66
+ return buf;
67
+ }
68
+ /** The one canonical pax extended-header data block: a single self-inclusive `path` record. */
69
+ function buildPaxPathRecord(path) {
70
+ const valueBytes = Buffer.byteLength(path, 'utf8');
71
+ // Record: "<len> path=<value>\n"; len counts every byte of the record.
72
+ const suffixLen = 1 + 'path='.length + valueBytes + 1;
73
+ let digits = String(suffixLen).length;
74
+ let total = digits + suffixLen;
75
+ while (String(total).length !== digits) {
76
+ digits = String(total).length;
77
+ total = digits + suffixLen;
78
+ }
79
+ return Buffer.from(`${total} path=${path}\n`, 'utf8');
80
+ }
81
+ /**
82
+ * Build the canonical uncompressed tar bytes for a set of files. The input
83
+ * MUST already be sorted by ascending UTF-8 byte order of `path` and carry
84
+ * canonical modes; the bundle packer guarantees both.
85
+ */
86
+ export function buildCanonicalTar(files, limits = DEFAULT_TAR_LIMITS) {
87
+ let headerCount = 0;
88
+ const chunks = [];
89
+ let previousPath;
90
+ const filePaths = new Set();
91
+ for (const f of files) {
92
+ const violation = canonicalBundlePathViolation(f.path);
93
+ if (violation) {
94
+ throw new BundleError('SOURCE_INVALID_PATH', `unsafe path '${f.path}': ${violation}`, f.path);
95
+ }
96
+ if (previousPath !== undefined) {
97
+ const order = compareUtf8Paths(previousPath, f.path);
98
+ if (order === 0) {
99
+ throw new BundleError('ARCHIVE_DUPLICATE_PATH', `duplicate archive path '${f.path}'`, f.path);
100
+ }
101
+ if (order > 0) {
102
+ throw new BundleError('NON_CANONICAL_HEADER', `archive entries are not sorted by UTF-8 path: '${f.path}' follows '${previousPath}'`, f.path);
103
+ }
104
+ }
105
+ const filePrefix = canonicalBundleFilePrefix(f.path, filePaths);
106
+ if (filePrefix !== undefined) {
107
+ throw new BundleError('ARCHIVE_PATH_PREFIX_COLLISION', `archive file path '${filePrefix}' is a complete-segment prefix of '${f.path}'`, f.path);
108
+ }
109
+ filePaths.add(f.path);
110
+ previousPath = f.path;
111
+ if (f.path.length > limits.maxPathLength) {
112
+ throw new BundleError('ARCHIVE_PATH_TOO_LONG', `archive entry path length ${f.path.length} exceeds limit of ${limits.maxPathLength} chars`, f.path);
113
+ }
114
+ if (f.bytes.length > limits.maxFileBytes) {
115
+ throw new BundleError('ARCHIVE_ENTRY_TOO_LARGE', `archive entry '${f.path}' is ${f.bytes.length} bytes; limit is ${limits.maxFileBytes}`, f.path);
116
+ }
117
+ if (f.mode !== 0o644 && f.mode !== 0o755) {
118
+ throw new BundleError('NON_CANONICAL_HEADER', `archive entry '${f.path}' must use mode 0644 or 0755`, f.path);
119
+ }
120
+ const nameBytes = Buffer.byteLength(f.path, 'utf8');
121
+ if (nameBytes > 100) {
122
+ // USTAR name cannot hold it — emit a deterministic PAX path header.
123
+ headerCount += 2;
124
+ const paxData = buildPaxPathRecord(f.path);
125
+ chunks.push(buildHeader('PaxHeader', paxData.length, 'x', 0o644));
126
+ chunks.push(padBlock(paxData));
127
+ // The 100-byte name field is only a deterministic placeholder; the PAX
128
+ // record carries the effective UTF-8 path. Use the shared placeholder
129
+ // rule so the strict reader requires exactly what the writer emits.
130
+ chunks.push(buildHeader(canonicalPaxNamePlaceholder(f.path), f.bytes.length, '0', f.mode));
131
+ }
132
+ else {
133
+ headerCount += 1;
134
+ chunks.push(buildHeader(f.path, f.bytes.length, '0', f.mode));
135
+ }
136
+ if (headerCount > limits.maxFileCount) {
137
+ throw new BundleError('ARCHIVE_TOO_MANY_ENTRIES', `archive entry count exceeds limit of ${limits.maxFileCount}`);
138
+ }
139
+ chunks.push(padBlock(f.bytes));
140
+ }
141
+ chunks.push(Buffer.alloc(BLOCK * 2)); // two zero blocks end the archive
142
+ const tar = Buffer.concat(chunks);
143
+ if (tar.length > limits.maxExpandedBytes) {
144
+ throw new BundleError('BUNDLE_LIMIT', `expanded archive size ${tar.length} exceeds limit of ${limits.maxExpandedBytes} bytes`);
145
+ }
146
+ return tar;
147
+ }
148
+ /**
149
+ * Gzip `tar` with fixed options and a normalized header: no FEXTRA/FNAME/
150
+ * FCOMMENT, mtime bytes zeroed, OS byte forced to 0. Node's zlib reports
151
+ * OS 19 on Darwin and embeds the clock in mtime by default — patch both so
152
+ * the output is byte-identical across platforms and times.
153
+ */
154
+ export function gzipDeterministic(tar) {
155
+ const gz = gzipSync(Buffer.from(tar), { level: BUNDLE_GZIP_LEVEL });
156
+ gz[4] = 0; // mtime byte 0
157
+ gz[5] = 0; // mtime byte 1
158
+ gz[6] = 0; // mtime byte 2
159
+ gz[7] = 0; // mtime byte 3
160
+ gz[9] = 0; // OS byte (Darwin reports 19; the format fixes 0)
161
+ return gz;
162
+ }
163
+ /** Compare archive paths by ascending UTF-8 bytes, as required by canonical packing. */
164
+ export function compareUtf8Paths(a, b) {
165
+ return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
166
+ }
167
+ const byNameBytes = (a, b) => compareUtf8Paths(a.name, b.name);
168
+ export function collectSourceFiles(sourceRoot, limits = DEFAULT_TAR_LIMITS, options = {}) {
169
+ const root = resolve(sourceRoot);
170
+ const readDir = options.readDir ?? ((directory) => readdirSync(directory, { withFileTypes: true }));
171
+ let rootStat;
172
+ try {
173
+ rootStat = lstatSync(root);
174
+ }
175
+ catch {
176
+ throw new BundleError('SOURCE_NOT_A_DIRECTORY', `source directory '${sourceRoot}' does not exist`);
177
+ }
178
+ if (rootStat.isSymbolicLink()) {
179
+ throw new BundleError('SOURCE_SYMLINK', `source root '${sourceRoot}' is a symbolic link`);
180
+ }
181
+ if (!rootStat.isDirectory()) {
182
+ throw new BundleError('SOURCE_NOT_A_DIRECTORY', `source '${sourceRoot}' is not a directory`);
183
+ }
184
+ const out = [];
185
+ let archiveEntryCount = 0;
186
+ const walk = (dirAbs, relPrefix) => {
187
+ let dirents;
188
+ try {
189
+ dirents = readDir(dirAbs);
190
+ }
191
+ catch (e) {
192
+ throw new BundleError('SOURCE_NOT_A_DIRECTORY', `cannot read '${dirAbs}': ${e.message}`);
193
+ }
194
+ dirents.sort(byNameBytes);
195
+ for (const d of dirents) {
196
+ const abs = join(dirAbs, d.name);
197
+ const rel = relPrefix === '' ? d.name : `${relPrefix}/${d.name}`;
198
+ options.onVisit?.(rel);
199
+ const violation = canonicalBundlePathViolation(rel);
200
+ if (violation) {
201
+ throw new BundleError('SOURCE_INVALID_PATH', `unsafe path '${rel}': ${violation}`, rel);
202
+ }
203
+ if (rel.length > limits.maxPathLength) {
204
+ throw new BundleError('ARCHIVE_PATH_TOO_LONG', `archive entry path length ${rel.length} exceeds limit of ${limits.maxPathLength} chars`, rel);
205
+ }
206
+ const st = lstatSync(abs);
207
+ if (st.isSymbolicLink()) {
208
+ throw new BundleError('SOURCE_SYMLINK', `symbolic link '${rel}' cannot be packed`, rel);
209
+ }
210
+ if (st.isDirectory()) {
211
+ walk(abs, rel);
212
+ continue;
213
+ }
214
+ if (!st.isFile()) {
215
+ throw new BundleError('SOURCE_NOT_A_FILE', `'${rel}' is not a regular file or directory`, rel);
216
+ }
217
+ if (st.size > limits.maxFileBytes) {
218
+ throw new BundleError('ARCHIVE_ENTRY_TOO_LARGE', `archive entry '${rel}' is ${st.size} bytes; limit is ${limits.maxFileBytes}`, rel);
219
+ }
220
+ out.push({ rel, abs, executable: (st.mode & 0o111) !== 0 });
221
+ archiveEntryCount += Buffer.byteLength(rel, 'utf8') > 100 ? 2 : 1;
222
+ if (archiveEntryCount > limits.maxFileCount) {
223
+ throw new BundleError('ARCHIVE_TOO_MANY_ENTRIES', `archive entry count exceeds limit of ${limits.maxFileCount}`);
224
+ }
225
+ }
226
+ };
227
+ walk(root, '');
228
+ out.sort((a, b) => compareUtf8Paths(a.rel, b.rel));
229
+ const filePaths = new Set();
230
+ for (const file of out) {
231
+ const filePrefix = canonicalBundleFilePrefix(file.rel, filePaths);
232
+ if (filePrefix !== undefined) {
233
+ throw new BundleError('ARCHIVE_PATH_PREFIX_COLLISION', `source file path '${filePrefix}' is a complete-segment prefix of '${file.rel}'`, file.rel);
234
+ }
235
+ filePaths.add(file.rel);
236
+ }
237
+ return out;
238
+ }
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Public types for the deterministic `.wnlp` bundle format (WP-A1).
3
+ *
4
+ * A `.wnlp` file is gzip-compressed canonical POSIX/PAX tar; its identity
5
+ * ("def digest") is the lowercase SHA-256 of the UNCOMPRESSED canonical tar
6
+ * bytes. See `docs/bundles.md` for the full format contract.
7
+ */
8
+ import type { TarLimits } from '../archive.ts';
9
+ /** Every bundle failure carries one of these stable codes (machines match on `code`). */
10
+ export type BundleErrorCode = 'BUNDLE_IO' | 'BUNDLE_NOT_GZIP' | 'BUNDLE_LIMIT' | 'ARCHIVE_TOO_MANY_ENTRIES' | 'ARCHIVE_ENTRY_TOO_LARGE' | 'ARCHIVE_PATH_TOO_LONG' | 'ARCHIVE_PATH_VIOLATION' | 'ARCHIVE_DUPLICATE_PATH' | 'ARCHIVE_PATH_PREFIX_COLLISION' | 'ARCHIVE_TRUNCATED' | 'ARCHIVE_BAD_CHECKSUM' | 'ARCHIVE_BAD_OCTAL' | 'ARCHIVE_BAD_PAX' | 'ARCHIVE_DANGLING_PAX' | 'ARCHIVE_TRAILING_BYTES' | 'UNSUPPORTED_ENTRY_TYPE' | 'NON_CANONICAL_HEADER' | 'MANIFEST_ERROR' | 'RUNTIME_INCOMPATIBLE' | 'UNSUPPORTED_FORMAT_VERSION' | 'MANIFEST_MISSING' | 'WORKFLOW_MISSING' | 'WORKFLOW_INVALID' | 'INTEGRITY_MISMATCH' | 'SOURCE_NOT_A_DIRECTORY' | 'SOURCE_NOT_A_FILE' | 'SOURCE_SYMLINK' | 'SOURCE_INVALID_PATH' | 'SOURCE_FILE_CHANGED' | 'OUTPUT_INSIDE_SOURCE' | 'OUTPUT_INVALID' | 'DESTINATION_EXISTS' | 'DESTINATION_PARENT_INVALID' | 'WORKFLOW_ERROR';
11
+ /**
12
+ * A typed bundle failure. `message` is human-readable; `entryPath` carries
13
+ * the offending archive/manifest entry when applicable.
14
+ */
15
+ export declare class BundleError extends Error {
16
+ readonly code: BundleErrorCode;
17
+ readonly entryPath?: string;
18
+ constructor(code: BundleErrorCode, message: string, entryPath?: string);
19
+ }
20
+ /** Compatibility requirements that a format-v2 bundle places on its reader/runtime. */
21
+ export interface BundleRuntimeRequirements {
22
+ /** Minimum canonical Owenloop SemVer accepted by the bundle. */
23
+ minVersion?: string;
24
+ /** Versioned runtime feature identifiers that the reader must implement. */
25
+ features?: string[];
26
+ }
27
+ /**
28
+ * The v2 package-only manifest (`bundle.yaml`). All collections are
29
+ * duplicate-free; serialization order is deterministic (see
30
+ * `docs/bundles.md` §Manifest).
31
+ */
32
+ export interface BundleManifest {
33
+ /** Always `2` in this format version. */
34
+ formatVersion: 2;
35
+ package: {
36
+ /** Portable package namespace. */
37
+ name: string;
38
+ /** Non-empty version string. */
39
+ version: string;
40
+ };
41
+ /** Optional reader/runtime compatibility requirements. */
42
+ runtime?: BundleRuntimeRequirements;
43
+ /** Workflow name to archive-relative definition path. */
44
+ workflows: Record<string, string>;
45
+ /** Optional default workflow name. */
46
+ default?: string;
47
+ /** Platform selectors this package targets (may be empty). */
48
+ platforms: string[];
49
+ integrity: {
50
+ /** Always `'sha256'`. */
51
+ algorithm: 'sha256';
52
+ /**
53
+ * Lowercase 64-hex SHA-256 for every regular archive file EXCEPT
54
+ * `bundle.yaml` (self-hash is recursive; the def digest still covers the
55
+ * manifest through the canonical tar).
56
+ */
57
+ files: Record<string, string>;
58
+ };
59
+ /**
60
+ * Requested capability classes and values — REQUESTS only; this format
61
+ * neither grants nor enforces them.
62
+ */
63
+ capabilities: Record<string, string[]>;
64
+ /**
65
+ * Digest-pinned cross-bundle references: exact `namespace/name@version`
66
+ * reference text → lowercase 64-hex def digest of the called bundle.
67
+ */
68
+ lock: Record<string, string>;
69
+ }
70
+ /** One regular-file entry of a bundle, as returned by pack/inspect. */
71
+ export interface BundleEntryInfo {
72
+ path: string;
73
+ size: number;
74
+ /** True when the source carried any execute bit (canonical mode 0755). */
75
+ executable: boolean;
76
+ /** Lowercase 64-hex SHA-256 of the entry's bytes. */
77
+ sha256: string;
78
+ }
79
+ /** Result of {@link packBundle}. */
80
+ export interface PackResult {
81
+ /** The complete `.wnlp` bytes (gzip of the canonical tar). */
82
+ bytes: Uint8Array;
83
+ /** Lowercase 64-hex SHA-256 over the uncompressed canonical tar bytes. */
84
+ digest: string;
85
+ /** The canonical manifest actually archived (source manifest regenerated). */
86
+ manifest: BundleManifest;
87
+ /** Archive entries in canonical (sorted) order, including `bundle.yaml`. */
88
+ entries: BundleEntryInfo[];
89
+ }
90
+ /** Result of {@link inspectBundle}. */
91
+ export interface InspectResult {
92
+ digest: string;
93
+ manifest: BundleManifest;
94
+ entries: BundleEntryInfo[];
95
+ }
96
+ /** Resource bounds for reading/writing bundles (the shared archive limits). */
97
+ export type BundleLimits = TarLimits;
98
+ /** Options for {@link packBundle}. */
99
+ export interface PackOptions {
100
+ limits?: Partial<BundleLimits>;
101
+ }
102
+ /** Options for {@link inspectBundle} / {@link digestBundle} / {@link unpackBundle}. */
103
+ export interface InspectOptions {
104
+ limits?: Partial<BundleLimits>;
105
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Public types for the deterministic `.wnlp` bundle format (WP-A1).
3
+ *
4
+ * A `.wnlp` file is gzip-compressed canonical POSIX/PAX tar; its identity
5
+ * ("def digest") is the lowercase SHA-256 of the UNCOMPRESSED canonical tar
6
+ * bytes. See `docs/bundles.md` for the full format contract.
7
+ */
8
+ /**
9
+ * A typed bundle failure. `message` is human-readable; `entryPath` carries
10
+ * the offending archive/manifest entry when applicable.
11
+ */
12
+ export class BundleError extends Error {
13
+ code;
14
+ entryPath;
15
+ constructor(code, message, entryPath) {
16
+ super(message);
17
+ this.code = code;
18
+ if (entryPath !== undefined)
19
+ this.entryPath = entryPath;
20
+ }
21
+ }
@@ -0,0 +1,93 @@
1
+ /**
2
+ * Routing capabilities: composition at offer time, and the claim-side match.
3
+ *
4
+ * Three vocabularies meet here and must not be confused:
5
+ *
6
+ * - **Authored capability** — what a def writes on a step (`wise`). Never
7
+ * contains the separator; the parser rejects one that does.
8
+ * - **Modifier** — the ONE plain name a run carries (`deep`). Optional. The
9
+ * engine attaches no meaning, no order and no arithmetic to it.
10
+ * - **Compound capability** — `<authored>:<modifier>` (`wise:deep`), composed
11
+ * by the engine when it builds an order. Only the engine composes it.
12
+ *
13
+ * Nothing here reads the store, the def or the clock. Composition is a pure
14
+ * function of (authored capabilities, modifier); matching is a pure function of
15
+ * (offered capabilities, caller capabilities, per-capability match mode).
16
+ */
17
+ /**
18
+ * The character the engine reserves as the capability/modifier separator.
19
+ *
20
+ * A def author never writes it. `wise:deep` is a value the ENGINE composes at
21
+ * offer time from an authored capability plus the run's modifier, and a crew
22
+ * binding is matched against that composed form. If an author could also write
23
+ * a literal `wise:deep` capability, two different things — an authored name and
24
+ * a composed compound — would be indistinguishable downstream, and the name
25
+ * part of a compound would stop being recoverable by splitting on the first
26
+ * colon. So the position is reserved, and reserving it is enforced in the def
27
+ * parser (`assertAuthoredCapability`).
28
+ */
29
+ export declare const MODIFIER_SEPARATOR = ":";
30
+ /**
31
+ * How a claim is matched against one offered capability.
32
+ *
33
+ * - `'exact'` — the caller must present the offered string literally. Stamped
34
+ * by the hub when at least one crew is bound to the exact compound
35
+ * (Scenario A): the binding exists, so the order belongs to the crews that
36
+ * opted into serving that slice, and a name-part-only crew must not take it.
37
+ * - `'name'` — the caller matches on the name part alone, modifier ignored
38
+ * both sides. Stamped when no binding for the compound exists (Scenario B),
39
+ * and re-stamped when a wait policy degrades an Scenario-A order.
40
+ *
41
+ * The mode is a HUB decision — it depends on `capability_routes`, which the
42
+ * pure engine cannot see. The engine only enforces the mode it is handed, and
43
+ * defaults to `'name'` for any capability the caller says nothing about.
44
+ */
45
+ export type MatchMode = 'exact' | 'name';
46
+ /** The default when a caller supplies no mode for an offered capability. */
47
+ export declare const DEFAULT_MATCH_MODE: MatchMode;
48
+ /**
49
+ * The name part of a capability: everything before the FIRST separator.
50
+ *
51
+ * Split on the first, not the last: an authored name can never contain the
52
+ * separator, so the first occurrence is always the one the engine composed at.
53
+ * A bare capability is its own name part.
54
+ */
55
+ export declare function capabilityName(capability: string): string;
56
+ /**
57
+ * Compose a step's authored capabilities against a run's modifier.
58
+ *
59
+ * No modifier (an unmodified run) returns the authored list unchanged — the
60
+ * order is offered on bare capabilities, exactly as before modifiers existed.
61
+ * An empty authored list stays empty: a capability-silent step has nothing to
62
+ * compose onto, and inventing a lone `:deep` would be meaningless.
63
+ */
64
+ export declare function composeCapabilities(authored: readonly string[] | undefined, modifier: string | undefined): string[];
65
+ /**
66
+ * The claim-side match: may a caller presenting `caller` claim a step offered
67
+ * on `offered`?
68
+ *
69
+ * `caller` distinguishes two states that must not be collapsed:
70
+ *
71
+ * - `undefined` — **no filter presented**. The caller is not claiming as a
72
+ * crew at all (a local operator running `owenloop tick`, a test driver).
73
+ * Everything matches, exactly as before capabilities existed.
74
+ * - `[]` — **a caller that serves nothing**. A crew presenting an empty
75
+ * capability list. This matches only capability-silent steps (case 2).
76
+ *
77
+ * Four cases, kept explicit because they are genuinely different rules:
78
+ *
79
+ * 1. **No filter presented** — always matches. See above.
80
+ * 2. **Capability-silent step** (`offered` empty) — claimable by anyone,
81
+ * including a caller presenting an empty list. Unchanged behavior: a def
82
+ * that authors no capabilities expresses no routing preference.
83
+ * 3. **Empty caller list, capabilities offered** — NO match. This is the A2
84
+ * caller-side change: today an empty list bypasses the filter and can
85
+ * claim every step, including compounds its shift cannot resolve, costing
86
+ * a claim/release cycle per order and able to hot-loop. Such a caller now
87
+ * matches only case 2.
88
+ * 4. **Both non-empty** — match when SOME offered capability is satisfied by
89
+ * SOME caller capability under that offered capability's own mode. The
90
+ * mode is looked up per offered capability, so an order carrying two
91
+ * compounds with different bindings is judged correctly on each.
92
+ */
93
+ export declare function claimMatches(offered: readonly string[], caller: readonly string[] | undefined, modes?: Readonly<Record<string, MatchMode>>): boolean;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * Routing capabilities: composition at offer time, and the claim-side match.
3
+ *
4
+ * Three vocabularies meet here and must not be confused:
5
+ *
6
+ * - **Authored capability** — what a def writes on a step (`wise`). Never
7
+ * contains the separator; the parser rejects one that does.
8
+ * - **Modifier** — the ONE plain name a run carries (`deep`). Optional. The
9
+ * engine attaches no meaning, no order and no arithmetic to it.
10
+ * - **Compound capability** — `<authored>:<modifier>` (`wise:deep`), composed
11
+ * by the engine when it builds an order. Only the engine composes it.
12
+ *
13
+ * Nothing here reads the store, the def or the clock. Composition is a pure
14
+ * function of (authored capabilities, modifier); matching is a pure function of
15
+ * (offered capabilities, caller capabilities, per-capability match mode).
16
+ */
17
+ /**
18
+ * The character the engine reserves as the capability/modifier separator.
19
+ *
20
+ * A def author never writes it. `wise:deep` is a value the ENGINE composes at
21
+ * offer time from an authored capability plus the run's modifier, and a crew
22
+ * binding is matched against that composed form. If an author could also write
23
+ * a literal `wise:deep` capability, two different things — an authored name and
24
+ * a composed compound — would be indistinguishable downstream, and the name
25
+ * part of a compound would stop being recoverable by splitting on the first
26
+ * colon. So the position is reserved, and reserving it is enforced in the def
27
+ * parser (`assertAuthoredCapability`).
28
+ */
29
+ export const MODIFIER_SEPARATOR = ':';
30
+ /** The default when a caller supplies no mode for an offered capability. */
31
+ export const DEFAULT_MATCH_MODE = 'name';
32
+ /**
33
+ * The name part of a capability: everything before the FIRST separator.
34
+ *
35
+ * Split on the first, not the last: an authored name can never contain the
36
+ * separator, so the first occurrence is always the one the engine composed at.
37
+ * A bare capability is its own name part.
38
+ */
39
+ export function capabilityName(capability) {
40
+ const i = capability.indexOf(MODIFIER_SEPARATOR);
41
+ return i === -1 ? capability : capability.slice(0, i);
42
+ }
43
+ /**
44
+ * Compose a step's authored capabilities against a run's modifier.
45
+ *
46
+ * No modifier (an unmodified run) returns the authored list unchanged — the
47
+ * order is offered on bare capabilities, exactly as before modifiers existed.
48
+ * An empty authored list stays empty: a capability-silent step has nothing to
49
+ * compose onto, and inventing a lone `:deep` would be meaningless.
50
+ */
51
+ export function composeCapabilities(authored, modifier) {
52
+ if (authored === undefined || authored.length === 0)
53
+ return [];
54
+ if (modifier === undefined)
55
+ return [...authored];
56
+ return authored.map((c) => `${c}${MODIFIER_SEPARATOR}${modifier}`);
57
+ }
58
+ /** True when one caller capability satisfies one offered capability under `mode`. */
59
+ function matchesOne(offered, caller, mode) {
60
+ return mode === 'exact' ? caller === offered : capabilityName(caller) === capabilityName(offered);
61
+ }
62
+ /**
63
+ * The claim-side match: may a caller presenting `caller` claim a step offered
64
+ * on `offered`?
65
+ *
66
+ * `caller` distinguishes two states that must not be collapsed:
67
+ *
68
+ * - `undefined` — **no filter presented**. The caller is not claiming as a
69
+ * crew at all (a local operator running `owenloop tick`, a test driver).
70
+ * Everything matches, exactly as before capabilities existed.
71
+ * - `[]` — **a caller that serves nothing**. A crew presenting an empty
72
+ * capability list. This matches only capability-silent steps (case 2).
73
+ *
74
+ * Four cases, kept explicit because they are genuinely different rules:
75
+ *
76
+ * 1. **No filter presented** — always matches. See above.
77
+ * 2. **Capability-silent step** (`offered` empty) — claimable by anyone,
78
+ * including a caller presenting an empty list. Unchanged behavior: a def
79
+ * that authors no capabilities expresses no routing preference.
80
+ * 3. **Empty caller list, capabilities offered** — NO match. This is the A2
81
+ * caller-side change: today an empty list bypasses the filter and can
82
+ * claim every step, including compounds its shift cannot resolve, costing
83
+ * a claim/release cycle per order and able to hot-loop. Such a caller now
84
+ * matches only case 2.
85
+ * 4. **Both non-empty** — match when SOME offered capability is satisfied by
86
+ * SOME caller capability under that offered capability's own mode. The
87
+ * mode is looked up per offered capability, so an order carrying two
88
+ * compounds with different bindings is judged correctly on each.
89
+ */
90
+ export function claimMatches(offered, caller, modes = {}) {
91
+ if (caller === undefined)
92
+ return true;
93
+ if (offered.length === 0)
94
+ return true;
95
+ if (caller.length === 0)
96
+ return false;
97
+ return offered.some((o) => {
98
+ const mode = modes[o] ?? DEFAULT_MATCH_MODE;
99
+ return caller.some((c) => matchesOne(o, c, mode));
100
+ });
101
+ }