@orkestrel/scaffold 0.0.118 → 0.0.120

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 (55) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/platforms/windows.md +2 -1
  4. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  5. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  8. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +2 -1
  9. package/dist/host/claude/agents/orkestrel.md +27 -26
  10. package/dist/host/claude/rules/names.md +3 -2
  11. package/dist/host/claude/rules/tests.md +4 -2
  12. package/dist/host/claude/rules/typescript.md +2 -3
  13. package/dist/host/claude/rules/workspace.md +2 -1
  14. package/dist/host/guides/abort.md +0 -4
  15. package/dist/host/guides/budget.md +1 -5
  16. package/dist/host/guides/codec.md +18 -3
  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/html.md +3 -7
  23. package/dist/host/guides/indexeddb.md +28 -32
  24. package/dist/host/guides/jsonrpc.md +187 -0
  25. package/dist/host/guides/markdown.md +132 -141
  26. package/dist/host/guides/msg.md +47 -63
  27. package/dist/host/guides/ndjson.md +0 -4
  28. package/dist/host/guides/pool.md +0 -4
  29. package/dist/host/guides/process.md +71 -79
  30. package/dist/host/guides/reason.md +30 -36
  31. package/dist/host/guides/router.md +11 -18
  32. package/dist/host/guides/scaffold.md +147 -137
  33. package/dist/host/guides/sqlite.md +0 -4
  34. package/dist/host/guides/sse.md +6 -10
  35. package/dist/host/guides/table.md +481 -493
  36. package/dist/host/guides/template.md +0 -4
  37. package/dist/host/guides/test.md +46 -66
  38. package/dist/host/guides/timeout.md +0 -6
  39. package/dist/host/guides/tool.md +2 -6
  40. package/dist/host/guides/websocket.md +0 -4
  41. package/dist/host/manifest.json +100 -428
  42. package/dist/host/tests/setupPolicy.ts +18 -6
  43. package/dist/src/core/index.cjs +171 -122
  44. package/dist/src/core/index.cjs.map +1 -1
  45. package/dist/src/core/index.d.cts +236 -213
  46. package/dist/src/core/index.d.ts +236 -213
  47. package/dist/src/core/index.js +159 -111
  48. package/dist/src/core/index.js.map +1 -1
  49. package/dist/src/server/index.cjs +62 -39
  50. package/dist/src/server/index.cjs.map +1 -1
  51. package/dist/src/server/index.d.cts +59 -54
  52. package/dist/src/server/index.d.ts +59 -54
  53. package/dist/src/server/index.js +63 -40
  54. package/dist/src/server/index.js.map +1 -1
  55. package/package.json +9 -9
@@ -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 {
@@ -1492,8 +1492,9 @@ 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, the inventory is absent without
1496
- * `establish: true`, or the staged manifest does not read back.
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
1497
+ * inventory is absent without `establish: true`, or the staged manifest does not read back.
1497
1498
  * @throws `ScaffoldError('WRITE', …)` when a staged file or the manifest cannot
1498
1499
  * be written.
1499
1500
  *
@@ -1529,7 +1530,10 @@ function stageBytes(host, root, destinations) {
1529
1530
  * the canon and reference files for reading. Every catalog package must have a
1530
1531
  * guide in the discovered membership before the host is written.
1531
1532
  * Copied guides must carry no collision whose name and exact owner set the
1532
- * committed inventory lacks. An absent inventory requires `establish: true`;
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
1537
  * an inventory without a valid recorded Surface is refused.
1534
1538
  * Everything downstream — the missing-path refusal, the
1535
1539
  * storage collision guard, the sort, the digests, and the root inventory — reads
@@ -1544,7 +1548,7 @@ function stageBytes(host, root, destinations) {
1544
1548
  * ```ts
1545
1549
  * import { stageHost } from '@orkestrel/scaffold/server'
1546
1550
  *
1547
- * stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
1551
+ * stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
1548
1552
  * ```
1549
1553
  */
1550
1554
  function stageHost(checkout, host, options) {
@@ -1609,7 +1613,7 @@ function stageHost(checkout, host, options) {
1609
1613
  checkout: source,
1610
1614
  path: destination
1611
1615
  });
1612
- const entry = readManifestEntry(destination, full);
1616
+ const entry = readHostManifestEntry(destination, full);
1613
1617
  if (entry === void 0) throw new _src_core.ScaffoldError("TARGET", `Vendored path is not a plain file within the artifact ceiling at ${destination}`, {
1614
1618
  checkout: source,
1615
1619
  path: destination,
@@ -1670,29 +1674,48 @@ function stageHost(checkout, host, options) {
1670
1674
  digest
1671
1675
  };
1672
1676
  });
1673
- const collisions = readSurfaceCollisions((0, node_path.join)(root, "guides"));
1674
- const growth = published === void 0 ? [] : (0, _src_core.compareSurfaceCollisions)([...collisions].map(([name, owners]) => ({
1677
+ const claims = readSurfaceClaims((0, node_path.join)(root, "guides"));
1678
+ const claimants = Map.groupBy(claims.flatMap(({ owner, names }) => names.map((name) => ({
1675
1679
  name,
1676
- owners
1677
- })), [...published].map(([name, owners]) => ({
1680
+ owner
1681
+ }))), ({ name }) => name);
1682
+ const transfers = _src_core.SURFACE_TRANSFERS.map((transfer) => {
1683
+ const owners = new Set(claimants.get(transfer.name)?.map(({ owner }) => owner));
1684
+ return {
1685
+ ...transfer,
1686
+ claimed: owners.has(transfer.keeper),
1687
+ givers: [...owners].filter((owner) => owner !== transfer.keeper).sort()
1688
+ };
1689
+ });
1690
+ const spent = transfers.filter(({ claimed, givers }) => claimed && givers.length === 0).map(({ name, keeper, item }) => `${name} to ${keeper} under item ${item}`);
1691
+ if (spent.length > 0) throw new _src_core.ScaffoldError("TARGET", `Surface transfers are spent, so remove them from SURFACE_TRANSFERS: ${spent.join("; ")}`, {
1692
+ checkout: source,
1693
+ host: root,
1694
+ transfers: spent
1695
+ });
1696
+ const active = transfers.filter(({ givers }) => givers.length > 0);
1697
+ const collisions = (0, _src_core.collectSurfaceCollisions)([...claims, ...active.map(({ name, keeper }) => ({
1698
+ owner: keeper,
1699
+ names: [name]
1700
+ }))]);
1701
+ const growth = published === void 0 ? [] : (0, _src_core.compareSurfaceCollisions)(collisions, [...new Map([...published, ...active.map(({ name, keeper, givers }) => [name, [...published.get(name) ?? (givers.length === 1 ? givers : []), keeper]])])].map(([name, owners]) => ({
1678
1702
  name,
1679
1703
  owners
1680
- }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})`);
1704
+ }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => {
1705
+ const keeper = active.find((transfer) => transfer.name === name)?.keeper;
1706
+ return `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})${keeper === void 0 ? "" : `, transferred to ${keeper}`}`;
1707
+ });
1681
1708
  if (growth.length > 0) throw new _src_core.ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
1682
1709
  checkout: source,
1683
1710
  host: root,
1684
1711
  baseline,
1685
1712
  collisions: growth
1686
1713
  });
1687
- const surface = [...collisions].map(([name, owners]) => ({
1688
- name,
1689
- owners
1690
- }));
1691
1714
  const manifest = {
1692
1715
  entries,
1693
1716
  roots,
1694
- surface,
1695
- digest: computeManifestDigest(entries, roots, surface)
1717
+ surface: collisions,
1718
+ digest: computeManifestDigest(entries, roots, collisions)
1696
1719
  };
1697
1720
  const metadata = resolveContainedPath(root, MANIFEST_NAME);
1698
1721
  if (metadata === void 0) throw new _src_core.ScaffoldError("INVALID", `Host manifest leaves its root at ${root}`, { host: root });
@@ -2404,7 +2427,7 @@ var isMirrors = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orke
2404
2427
  /** Narrows a value to a bounded list of fleet catalog rows. */
2405
2428
  var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(_src_core.isCatalogEntry));
2406
2429
  /**
2407
- * Narrows a value to one {@link ManifestEntry}.
2430
+ * Narrows a value to one {@link HostManifestEntry}.
2408
2431
  *
2409
2432
  * @remarks
2410
2433
  * Both paths are measured by the core path law, because a vendored host's
@@ -2414,9 +2437,9 @@ var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0
2414
2437
  *
2415
2438
  * @example
2416
2439
  * ```ts
2417
- * import { isManifestEntry } from '@orkestrel/scaffold/server'
2440
+ * import { isHostManifestEntry } from '@orkestrel/scaffold/server'
2418
2441
  *
2419
- * isManifestEntry({
2442
+ * isHostManifestEntry({
2420
2443
  * storage: 'AGENTS.md',
2421
2444
  * destination: 'AGENTS.md',
2422
2445
  * executable: false,
@@ -2424,7 +2447,7 @@ var isCatalogEntries = (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0
2424
2447
  * }) // true
2425
2448
  * ```
2426
2449
  */
2427
- var isManifestEntry = (0, _orkestrel_contract.recordOf)({
2450
+ var isHostManifestEntry = (0, _orkestrel_contract.recordOf)({
2428
2451
  storage: _src_core.isPath,
2429
2452
  destination: _src_core.isPath,
2430
2453
  executable: _orkestrel_contract.isBoolean,
@@ -2440,7 +2463,7 @@ var isManifestEntry = (0, _orkestrel_contract.recordOf)({
2440
2463
  * the syntax of the digest that authenticates that membership.
2441
2464
  */
2442
2465
  var isHostManifest = (0, _orkestrel_contract.recordOf)({
2443
- entries: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(isManifestEntry)),
2466
+ entries: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(isHostManifestEntry)),
2444
2467
  roots: (0, _orkestrel_contract.andOf)(_src_core.isCollection, (0, _orkestrel_contract.arrayOf)(_src_core.isPath)),
2445
2468
  surface: (0, _orkestrel_contract.whereOf)((0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.recordOf)({
2446
2469
  name: (0, _orkestrel_contract.stringOf)({ min: 1 }),
@@ -3281,7 +3304,7 @@ var Materializer = class {
3281
3304
  * match the ones the audit carried for every path the plan owns; anything else
3282
3305
  * means the target moved, and the whole call is refused. The audit is checked
3283
3306
  * for agreement rather than for plausibility, so a verdict the comparison could
3284
- * not have produced — a birth-owned path reported stale, which the `Finding`
3307
+ * not have produced — a birth-owned path reported stale, which the `ArtifactFinding`
3285
3308
  * shape admits — disagrees with the derived one and is refused. A missing
3286
3309
  * destination is restored whatever its ownership; a stale one is replaced only
3287
3310
  * where the artifact claims its bytes, which is what leaves a presence-owned
@@ -3348,7 +3371,7 @@ var Materializer = class {
3348
3371
  preconditions.push(this.#bind(directory, fetched.path, current === void 0));
3349
3372
  writes.push(fetched.lookup === "found" ? {
3350
3373
  path: fetched.path,
3351
- group: (0, _src_core.inferGroup)(fetched.path),
3374
+ group: (0, _src_core.inferArtifactGroup)(fetched.path),
3352
3375
  ownership: "content",
3353
3376
  origin: "computed",
3354
3377
  content: fetched.content
@@ -3499,7 +3522,7 @@ var Materializer = class {
3499
3522
  this.#emitter.destroy();
3500
3523
  }
3501
3524
  #own(host) {
3502
- const owned = (0, _src_core.cloneValue)(host);
3525
+ const owned = (0, _src_core.parseOwnedJSONValue)(host);
3503
3526
  if (isHost(owned)) return owned;
3504
3527
  throw this.#error("INVALID", "The host argument is not the exact shape this materializer accepts.", { field: "host" });
3505
3528
  }
@@ -3589,7 +3612,7 @@ var Materializer = class {
3589
3612
  }
3590
3613
  }
3591
3614
  return {
3592
- findings: (0, _src_core.planToFindings)(hydrated, readSnapshot(target, [...paths])),
3615
+ findings: (0, _src_core.planToArtifactFindings)(hydrated, readSnapshot(target, [...paths])),
3593
3616
  questions
3594
3617
  };
3595
3618
  }
@@ -3759,7 +3782,7 @@ var Materializer = class {
3759
3782
  path: finding.path
3760
3783
  });
3761
3784
  if (other.drift === finding.drift && other.observed === finding.observed) continue;
3762
- 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.`, {
3785
+ 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.`, {
3763
3786
  target,
3764
3787
  path: finding.path,
3765
3788
  ownership: finding.ownership,
@@ -3836,7 +3859,7 @@ var Materializer = class {
3836
3859
  });
3837
3860
  return this.#apply(target, [{
3838
3861
  path,
3839
- group: (0, _src_core.inferGroup)(path),
3862
+ group: (0, _src_core.inferArtifactGroup)(path),
3840
3863
  ownership: "content",
3841
3864
  origin: "computed",
3842
3865
  content
@@ -4015,7 +4038,7 @@ var Materializer = class {
4015
4038
  return result;
4016
4039
  }
4017
4040
  #accept(value, guard, field) {
4018
- const snapshot = (0, _src_core.cloneValue)(value);
4041
+ const snapshot = (0, _src_core.parseOwnedJSONValue)(value);
4019
4042
  if (guard(snapshot)) return snapshot;
4020
4043
  throw this.#error("INVALID", `The ${field} argument is not the exact shape this materializer accepts.`, { field });
4021
4044
  }
@@ -4479,7 +4502,7 @@ var Upstream = class {
4479
4502
  note: inventory.note,
4480
4503
  ...carried
4481
4504
  };
4482
- if ((0, _src_core.inferGroup)(path) === "guides") return {
4505
+ if ((0, _src_core.inferArtifactGroup)(path) === "guides") return {
4483
4506
  path,
4484
4507
  lookup: "missing",
4485
4508
  note: `${path} is a guide mirror the fleet serves`,
@@ -4811,7 +4834,7 @@ var Upstream = class {
4811
4834
  return produced;
4812
4835
  }
4813
4836
  #accept(value, guard, field) {
4814
- const snapshot = (0, _src_core.cloneValue)(value);
4837
+ const snapshot = (0, _src_core.parseOwnedJSONValue)(value);
4815
4838
  if (guard(snapshot)) return snapshot;
4816
4839
  throw this.#error("INVALID", `The ${field} argument is not the exact shape this upstream reader accepts.`, { field });
4817
4840
  }
@@ -4870,8 +4893,8 @@ exports.isExactCaseFile = isExactCaseFile;
4870
4893
  exports.isFilesystemPath = isFilesystemPath;
4871
4894
  exports.isHost = isHost;
4872
4895
  exports.isHostManifest = isHostManifest;
4896
+ exports.isHostManifestEntry = isHostManifestEntry;
4873
4897
  exports.isInventory = isInventory;
4874
- exports.isManifestEntry = isManifestEntry;
4875
4898
  exports.isManifestRegionSet = isManifestRegionSet;
4876
4899
  exports.isMaterializerHooks = isMaterializerHooks;
4877
4900
  exports.isMaterializerOptions = isMaterializerOptions;
@@ -4905,7 +4928,7 @@ exports.readFileHex = readFileHex;
4905
4928
  exports.readFileText = readFileText;
4906
4929
  exports.readHostFloor = readHostFloor;
4907
4930
  exports.readHostManifest = readHostManifest;
4908
- exports.readManifestEntry = readManifestEntry;
4931
+ exports.readHostManifestEntry = readHostManifestEntry;
4909
4932
  exports.readSnapshot = readSnapshot;
4910
4933
  exports.readSurfaceBaseline = readSurfaceBaseline;
4911
4934
  exports.readSurfaceCandidate = readSurfaceCandidate;