@orkestrel/scaffold 0.0.119 → 0.0.121

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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -365,7 +365,7 @@ function computeDigest(content) {
365
365
  * ```
366
366
  */
367
367
  function hexToDigest(hex) {
368
- if (!(0, _src_core.isHex)(hex)) throw new _src_core.ScaffoldError("INVALID", "Digest input is not exact hexadecimal bytes", { hex });
368
+ if (!(0, _src_core.isHexContent)(hex)) throw new _src_core.ScaffoldError("INVALID", "Digest input is not exact hexadecimal bytes", { hex });
369
369
  return (0, node_crypto.createHash)("sha256").update(Buffer.from(hex, "hex")).digest("hex");
370
370
  }
371
371
  /**
@@ -390,7 +390,7 @@ function hexToDigest(hex) {
390
390
  * ```
391
391
  */
392
392
  function decodeHexText(hex) {
393
- if (!(0, _src_core.isHex)(hex)) throw new _src_core.ScaffoldError("INVALID", "Decode input is not exact hexadecimal bytes", { hex });
393
+ if (!(0, _src_core.isHexContent)(hex)) throw new _src_core.ScaffoldError("INVALID", "Decode input is not exact hexadecimal bytes", { hex });
394
394
  const decoded = (0, _orkestrel_contract.attempt)(() => new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(hex, "hex")));
395
395
  return decoded.success ? decoded.value : void 0;
396
396
  }
@@ -1009,7 +1009,7 @@ function listCanonPaths(target, groups) {
1009
1009
  if (full === void 0) return [];
1010
1010
  if (isPhysicalFile(full)) return [member];
1011
1011
  return isPhysicalDirectory(full) ? listFiles(full).map((name) => `${member}/${name}`) : [];
1012
- }).filter((path) => groups.includes((0, _src_core.inferGroup)(path)));
1012
+ }).filter((path) => groups.includes((0, _src_core.inferArtifactGroup)(path)));
1013
1013
  }
1014
1014
  /**
1015
1015
  * Removes every directory one set of deletions emptied.
@@ -1042,7 +1042,7 @@ function listCanonPaths(target, groups) {
1042
1042
  * ```
1043
1043
  */
1044
1044
  function pruneEmptiedDirectories(target, removed) {
1045
- return [...new Set(Iterator.from(removed).flatMap((path) => listAncestors(path).slice(1, -1)).toArray())].sort((left, right) => (0, _orkestrel_contract.compareValues)(right.split("/").length, left.split("/").length) || (0, _orkestrel_contract.compareValues)(left, right)).flatMap((candidate) => {
1045
+ return [...new Set(Iterator.from(removed).flatMap((path) => listAncestors(path).slice(1, -1)).toArray())].sort((left, right) => (0, _orkestrel_contract.comparePrimitives)(right.split("/").length, left.split("/").length) || (0, _orkestrel_contract.comparePrimitives)(left, right)).flatMap((candidate) => {
1046
1046
  const directory = resolveContainedPath(target, candidate);
1047
1047
  if (directory === void 0 || !isPhysicalDirectory(directory)) return [];
1048
1048
  const entries = (0, _orkestrel_contract.attempt)(() => (0, node_fs.readdirSync)(directory));
@@ -1327,13 +1327,13 @@ function readHostFloor(root) {
1327
1327
  *
1328
1328
  * @example
1329
1329
  * ```ts
1330
- * import { readManifestEntry } from '@orkestrel/scaffold/server'
1330
+ * import { readHostManifestEntry } from '@orkestrel/scaffold/server'
1331
1331
  *
1332
- * readManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
1332
+ * readHostManifestEntry('.gitignore', '/tmp/checkout/.gitignore')
1333
1333
  * // { storage: 'dotfiles/gitignore', destination: '.gitignore', executable: false, digest: '...' }
1334
1334
  * ```
1335
1335
  */
1336
- function readManifestEntry(destination, source) {
1336
+ function readHostManifestEntry(destination, source) {
1337
1337
  const digest = computeFileDigest(source);
1338
1338
  if (digest === void 0) return void 0;
1339
1339
  return {
@@ -1483,8 +1483,8 @@ function stageBytes(host, root, destinations) {
1483
1483
  *
1484
1484
  * @param checkout - The checkout the vendored paths are read from.
1485
1485
  * @param host - The vendored host root to fill; it must be absent or empty.
1486
- * @param options - The inventory selection, establishment switch, and reporting callback.
1487
- * Default: no reporting.
1486
+ * @param options - The inventory selection, establishment switch, reporting callback, and
1487
+ * declared transfers. Default: no reporting, and the transfers in `SURFACE_TRANSFERS`.
1488
1488
  * @returns One entry per staged file, sorted by storage name.
1489
1489
  * @throws `ScaffoldError('INVALID', …)` when either argument is not a host path
1490
1490
  * or a vendored path leaves the checkout or the host root.
@@ -1492,8 +1492,8 @@ function stageBytes(host, root, destinations) {
1492
1492
  * host root is not vacant, the checkout does not carry every vendored path, two
1493
1493
  * vendored files claim one storage name, a vendored file is not a plain file
1494
1494
  * within the artifact ceiling, published guides are unreadable, a staged
1495
- * collision's owner set is not a subset of its published owner set, a
1496
- * `SURFACE_TRANSFERS` entry is spent because its keeper alone claims the name, the
1495
+ * collision's owner set is not a subset of its published owner set, a declared
1496
+ * transfer is spent because its keeper alone claims the name, the
1497
1497
  * inventory is absent without `establish: true`, or the staged manifest does not read back.
1498
1498
  * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
1499
1499
  * be written.
@@ -1530,10 +1530,11 @@ function stageBytes(host, root, destinations) {
1530
1530
  * the canon and reference files for reading. Every catalog package must have a
1531
1531
  * guide in the discovered membership before the host is written.
1532
1532
  * Copied guides must carry no collision whose name and exact owner set the
1533
- * committed inventory lacks. A `SURFACE_TRANSFERS` entry that another guide claims
1534
- * admits its keeper beside the recorded owners, or beside the one owner of a name
1535
- * the inventory lacks, and the staged surface records that keeper whether or not
1536
- * its guide is mirrored. An absent inventory requires `establish: true`;
1533
+ * committed inventory lacks. A declared transfer that another guide claims admits
1534
+ * its keeper beside the recorded owners, or beside the one owner of a name the
1535
+ * inventory lacks, and the staged surface records that keeper whether or not its
1536
+ * guide is mirrored. `options.transfers` declares the transfers, and its default is
1537
+ * `SURFACE_TRANSFERS`. An absent inventory requires `establish: true`;
1537
1538
  * an inventory without a valid recorded Surface is refused.
1538
1539
  * Everything downstream — the missing-path refusal, the
1539
1540
  * storage collision guard, the sort, the digests, and the root inventory — reads
@@ -1548,7 +1549,7 @@ function stageBytes(host, root, destinations) {
1548
1549
  * ```ts
1549
1550
  * import { stageHost } from '@orkestrel/scaffold/server'
1550
1551
  *
1551
- * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
1552
+ * stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
1552
1553
  * ```
1553
1554
  */
1554
1555
  function stageHost(checkout, host, options) {
@@ -1613,7 +1614,7 @@ function stageHost(checkout, host, options) {
1613
1614
  checkout: source,
1614
1615
  path: destination
1615
1616
  });
1616
- const entry = readManifestEntry(destination, full);
1617
+ const entry = readHostManifestEntry(destination, full);
1617
1618
  if (entry === void 0) throw new _src_core.ScaffoldError("TARGET", `Vendored path is not a plain file within the artifact ceiling at ${destination}`, {
1618
1619
  checkout: source,
1619
1620
  path: destination,
@@ -1679,7 +1680,7 @@ function stageHost(checkout, host, options) {
1679
1680
  name,
1680
1681
  owner
1681
1682
  }))), ({ name }) => name);
1682
- const transfers = _src_core.SURFACE_TRANSFERS.map((transfer) => {
1683
+ const transfers = (options?.transfers ?? _src_core.SURFACE_TRANSFERS).map((transfer) => {
1683
1684
  const owners = new Set(claimants.get(transfer.name)?.map(({ owner }) => owner));
1684
1685
  return {
1685
1686
  ...transfer,
@@ -2427,7 +2428,7 @@ var isMirrors = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orke
2427
2428
  /** Narrows a value to a bounded list of fleet catalog rows. */
2428
2429
  var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(_src_core.isCatalogEntry));
2429
2430
  /**
2430
- * Narrows a value to one {@link ManifestEntry}.
2431
+ * Narrows a value to one {@link HostManifestEntry}.
2431
2432
  *
2432
2433
  * @remarks
2433
2434
  * Both paths are measured by the core path law, because a vendored host's
@@ -2437,9 +2438,9 @@ var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0
2437
2438
  *
2438
2439
  * @example
2439
2440
  * ```ts
2440
- * import { isManifestEntry } from '@orkestrel/scaffold/server'
2441
+ * import { isHostManifestEntry } from '@orkestrel/scaffold/server'
2441
2442
  *
2442
- * isManifestEntry({
2443
+ * isHostManifestEntry({
2443
2444
  * storage: 'AGENTS.md',
2444
2445
  * destination: 'AGENTS.md',
2445
2446
  * executable: false,
@@ -2447,7 +2448,7 @@ var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0
2447
2448
  * }) // true
2448
2449
  * ```
2449
2450
  */
2450
- var isManifestEntry = (0, _orkestrel_contract.recordOf)({
2451
+ var isHostManifestEntry = (0, _orkestrel_contract.recordOf)({
2451
2452
  storage: _src_core.isPath,
2452
2453
  destination: _src_core.isPath,
2453
2454
  executable: _orkestrel_contract.isBoolean,
@@ -2463,7 +2464,7 @@ var isManifestEntry = (0, _orkestrel_contract.recordOf)({
2463
2464
  * the syntax of the digest that authenticates that membership.
2464
2465
  */
2465
2466
  var isHostManifest = (0, _orkestrel_contract.recordOf)({
2466
- entries: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(isManifestEntry)),
2467
+ entries: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(isHostManifestEntry)),
2467
2468
  roots: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(_src_core.isPath)),
2468
2469
  surface: (0, _orkestrel_contract.whereOf)((0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.recordOf)({
2469
2470
  name: (0, _orkestrel_contract.stringOf)({ min: 1 }),
@@ -3304,7 +3305,7 @@ var Materializer = class {
3304
3305
  * match the ones the audit carried for every path the plan owns; anything else
3305
3306
  * means the target moved, and the whole call is refused. The audit is checked
3306
3307
  * for agreement rather than for plausibility, so a verdict the comparison could
3307
- * not have produced — a birth-owned path reported stale, which the `Finding`
3308
+ * not have produced — a birth-owned path reported stale, which the `ArtifactFinding`
3308
3309
  * shape admits — disagrees with the derived one and is refused. A missing
3309
3310
  * destination is restored whatever its ownership; a stale one is replaced only
3310
3311
  * where the artifact claims its bytes, which is what leaves a presence-owned
@@ -3371,7 +3372,7 @@ var Materializer = class {
3371
3372
  preconditions.push(this.#bind(directory, fetched.path, current === void 0));
3372
3373
  writes.push(fetched.lookup === "found" ? {
3373
3374
  path: fetched.path,
3374
- group: (0, _src_core.inferGroup)(fetched.path),
3375
+ group: (0, _src_core.inferArtifactGroup)(fetched.path),
3375
3376
  ownership: "content",
3376
3377
  origin: "computed",
3377
3378
  content: fetched.content
@@ -3522,7 +3523,7 @@ var Materializer = class {
3522
3523
  this.#emitter.destroy();
3523
3524
  }
3524
3525
  #own(host) {
3525
- const owned = (0, _src_core.cloneValue)(host);
3526
+ const owned = (0, _src_core.parseOwnedJSONValue)(host);
3526
3527
  if (isHost(owned)) return owned;
3527
3528
  throw this.#error("INVALID", "The host argument is not the exact shape this materializer accepts.", { field: "host" });
3528
3529
  }
@@ -3612,7 +3613,7 @@ var Materializer = class {
3612
3613
  }
3613
3614
  }
3614
3615
  return {
3615
- findings: (0, _src_core.planToFindings)(hydrated, readSnapshot(target, [...paths])),
3616
+ findings: (0, _src_core.planToArtifactFindings)(hydrated, readSnapshot(target, [...paths])),
3616
3617
  questions
3617
3618
  };
3618
3619
  }
@@ -3782,7 +3783,7 @@ var Materializer = class {
3782
3783
  path: finding.path
3783
3784
  });
3784
3785
  if (other.drift === finding.drift && other.observed === finding.observed) continue;
3785
- if (!(0, _src_core.matchesDriftReachability)(finding.ownership, other)) throw this.#error("TARGET", `The path ${finding.path} carries an audit verdict this plan could not produce.`, {
3786
+ if (!(0, _src_core.matchesArtifactDriftReachability)(finding.ownership, other)) throw this.#error("TARGET", `The path ${finding.path} carries an audit verdict this plan could not produce.`, {
3786
3787
  target,
3787
3788
  path: finding.path,
3788
3789
  ownership: finding.ownership,
@@ -3859,7 +3860,7 @@ var Materializer = class {
3859
3860
  });
3860
3861
  return this.#apply(target, [{
3861
3862
  path,
3862
- group: (0, _src_core.inferGroup)(path),
3863
+ group: (0, _src_core.inferArtifactGroup)(path),
3863
3864
  ownership: "content",
3864
3865
  origin: "computed",
3865
3866
  content
@@ -4038,7 +4039,7 @@ var Materializer = class {
4038
4039
  return result;
4039
4040
  }
4040
4041
  #accept(value, guard, field) {
4041
- const snapshot = (0, _src_core.cloneValue)(value);
4042
+ const snapshot = (0, _src_core.parseOwnedJSONValue)(value);
4042
4043
  if (guard(snapshot)) return snapshot;
4043
4044
  throw this.#error("INVALID", `The ${field} argument is not the exact shape this materializer accepts.`, { field });
4044
4045
  }
@@ -4502,7 +4503,7 @@ var Upstream = class {
4502
4503
  note: inventory.note,
4503
4504
  ...carried
4504
4505
  };
4505
- if ((0, _src_core.inferGroup)(path) === "guides") return {
4506
+ if ((0, _src_core.inferArtifactGroup)(path) === "guides") return {
4506
4507
  path,
4507
4508
  lookup: "missing",
4508
4509
  note: `${path} is a guide mirror the fleet serves`,
@@ -4834,7 +4835,7 @@ var Upstream = class {
4834
4835
  return produced;
4835
4836
  }
4836
4837
  #accept(value, guard, field) {
4837
- const snapshot = (0, _src_core.cloneValue)(value);
4838
+ const snapshot = (0, _src_core.parseOwnedJSONValue)(value);
4838
4839
  if (guard(snapshot)) return snapshot;
4839
4840
  throw this.#error("INVALID", `The ${field} argument is not the exact shape this upstream reader accepts.`, { field });
4840
4841
  }
@@ -4893,8 +4894,8 @@ exports.isExactCaseFile = isExactCaseFile;
4893
4894
  exports.isFilesystemPath = isFilesystemPath;
4894
4895
  exports.isHost = isHost;
4895
4896
  exports.isHostManifest = isHostManifest;
4897
+ exports.isHostManifestEntry = isHostManifestEntry;
4896
4898
  exports.isInventory = isInventory;
4897
- exports.isManifestEntry = isManifestEntry;
4898
4899
  exports.isManifestRegionSet = isManifestRegionSet;
4899
4900
  exports.isMaterializerHooks = isMaterializerHooks;
4900
4901
  exports.isMaterializerOptions = isMaterializerOptions;
@@ -4928,7 +4929,7 @@ exports.readFileHex = readFileHex;
4928
4929
  exports.readFileText = readFileText;
4929
4930
  exports.readHostFloor = readHostFloor;
4930
4931
  exports.readHostManifest = readHostManifest;
4931
- exports.readManifestEntry = readManifestEntry;
4932
+ exports.readHostManifestEntry = readHostManifestEntry;
4932
4933
  exports.readSnapshot = readSnapshot;
4933
4934
  exports.readSurfaceBaseline = readSurfaceBaseline;
4934
4935
  exports.readSurfaceCandidate = readSurfaceCandidate;