@orkestrel/scaffold 0.0.114 → 0.0.116

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 (108) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/orchestration.md +5 -3
  4. package/dist/host/agents/platforms/windows.md +1 -0
  5. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  7. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  8. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  9. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  10. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  11. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  13. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
  14. package/dist/host/claude/agents/analyst.md +1 -1
  15. package/dist/host/claude/agents/astra.md +2 -2
  16. package/dist/host/claude/agents/builder.md +4 -4
  17. package/dist/host/claude/agents/opus.md +3 -3
  18. package/dist/host/claude/agents/orkestrel.md +5 -7
  19. package/dist/host/claude/agents/planner.md +8 -2
  20. package/dist/host/claude/rules/campaign.md +2 -1
  21. package/dist/host/claude/rules/documentation.md +1 -0
  22. package/dist/host/claude/rules/names.md +3 -1
  23. package/dist/host/claude/rules/tests.md +7 -4
  24. package/dist/host/claude/rules/writing.md +1 -0
  25. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  26. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  27. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  28. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  31. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  32. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  35. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  36. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  37. package/dist/host/codex/agents/analyst.toml +8 -5
  38. package/dist/host/codex/agents/astra.toml +4 -5
  39. package/dist/host/codex/agents/builder.toml +5 -5
  40. package/dist/host/codex/agents/opus.toml +3 -4
  41. package/dist/host/codex/agents/orkestrel.toml +2 -1
  42. package/dist/host/codex/agents/planner.toml +8 -5
  43. package/dist/host/codex/agents/reviewer.toml +5 -4
  44. package/dist/host/guides/abort.md +17 -17
  45. package/dist/host/guides/agent.md +445 -445
  46. package/dist/host/guides/brief.md +143 -143
  47. package/dist/host/guides/browser.md +731 -731
  48. package/dist/host/guides/budget.md +39 -39
  49. package/dist/host/guides/capture.md +298 -298
  50. package/dist/host/guides/console.md +109 -109
  51. package/dist/host/guides/contract.md +335 -335
  52. package/dist/host/guides/csv.md +30 -30
  53. package/dist/host/guides/database.md +163 -163
  54. package/dist/host/guides/emitter.md +17 -17
  55. package/dist/host/guides/form.md +99 -99
  56. package/dist/host/guides/guide.md +361 -183
  57. package/dist/host/guides/html.md +49 -49
  58. package/dist/host/guides/indexeddb.md +40 -40
  59. package/dist/host/guides/interpret.md +139 -139
  60. package/dist/host/guides/lsp.md +114 -114
  61. package/dist/host/guides/markdown.md +68 -68
  62. package/dist/host/guides/mcp.md +3745 -3745
  63. package/dist/host/guides/middleware.md +170 -170
  64. package/dist/host/guides/msg.md +95 -95
  65. package/dist/host/guides/ndjson.md +8 -8
  66. package/dist/host/guides/ollama.md +56 -56
  67. package/dist/host/guides/pool.md +21 -21
  68. package/dist/host/guides/probe.md +82 -82
  69. package/dist/host/guides/process.md +99 -99
  70. package/dist/host/guides/program.md +98 -96
  71. package/dist/host/guides/qualifier.md +70 -70
  72. package/dist/host/guides/queue.md +37 -37
  73. package/dist/host/guides/rater.md +38 -38
  74. package/dist/host/guides/reason.md +308 -308
  75. package/dist/host/guides/relation.md +50 -50
  76. package/dist/host/guides/router.md +58 -58
  77. package/dist/host/guides/scaffold.md +554 -419
  78. package/dist/host/guides/sea.md +128 -128
  79. package/dist/host/guides/server.md +100 -100
  80. package/dist/host/guides/sqlite.md +28 -28
  81. package/dist/host/guides/sse.md +20 -20
  82. package/dist/host/guides/study.md +444 -444
  83. package/dist/host/guides/table.md +82 -82
  84. package/dist/host/guides/template.md +41 -41
  85. package/dist/host/guides/terminal.md +121 -121
  86. package/dist/host/guides/test.md +273 -273
  87. package/dist/host/guides/timeout.md +18 -18
  88. package/dist/host/guides/tool.md +27 -27
  89. package/dist/host/guides/toolbox.md +166 -166
  90. package/dist/host/guides/websocket.md +54 -54
  91. package/dist/host/guides/worker.md +24 -24
  92. package/dist/host/guides/workflow.md +187 -187
  93. package/dist/host/guides/workspace.md +55 -55
  94. package/dist/host/manifest.json +93 -93
  95. package/dist/host/tests/setupPolicy.ts +5 -3
  96. package/dist/src/core/index.cjs +89 -3
  97. package/dist/src/core/index.cjs.map +1 -1
  98. package/dist/src/core/index.d.cts +229 -144
  99. package/dist/src/core/index.d.ts +229 -144
  100. package/dist/src/core/index.js +87 -4
  101. package/dist/src/core/index.js.map +1 -1
  102. package/dist/src/server/index.cjs +292 -66
  103. package/dist/src/server/index.cjs.map +1 -1
  104. package/dist/src/server/index.d.cts +188 -6
  105. package/dist/src/server/index.d.ts +188 -6
  106. package/dist/src/server/index.js +287 -69
  107. package/dist/src/server/index.js.map +1 -1
  108. package/package.json +4 -3
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from "node:module";
2
- import { andOf, arrayOf, attempt, boundsOf, compareValues, compileGuard, holds, isArray, isBoolean, isDefined, isError, isFunction, isInteger, isNonNegativeInteger, isNumber, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, recordShape, stringOf, stringShape, unionOf, whereOf } from "@orkestrel/contract";
3
- import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_END_MARKER, CATALOG_START_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeTotal, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, iterateAnswers, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
2
+ import { andOf, arrayOf, attempt, boundsOf, compareValues, compileGuard, holds, isArray, isBoolean, isDefined, isError, isFunction, isInteger, isNonNegativeInteger, isNumber, isObject, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, recordShape, stringOf, stringShape, unionOf, whereOf } from "@orkestrel/contract";
3
+ import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_END_MARKER, CATALOG_START_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, collectSurfaceCollisions, collectSurfaceConflicts, compareSurfaceCollisions, compareVersions, computeBytes, computeTotal, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, iterateAnswers, manifestToName, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestOverrides, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
4
4
  import { createHash, randomUUID } from "node:crypto";
5
5
  import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
6
6
  import { tmpdir } from "node:os";
@@ -1286,9 +1286,8 @@ function readHostManifest(host, name = MANIFEST_NAME) {
1286
1286
  */
1287
1287
  function readHostFloor(root) {
1288
1288
  const location = fileURLToPath(import.meta.url);
1289
- const module = dirname(location);
1290
1289
  const source = root === void 0 && extname(location) === ".ts";
1291
- const host = root ?? resolve(module, source ? "../.." : "../../host");
1290
+ const host = root ?? resolveHostRoot();
1292
1291
  if (!isPhysicalDirectory(host)) throw new ScaffoldError("TARGET", `The vendored host root is not readable at ${host}`, { host });
1293
1292
  const manifest = readHostManifest(host, source ? HOST_INVENTORY_PATH : MANIFEST_NAME);
1294
1293
  if (manifest === void 0) throw new ScaffoldError("TARGET", `The vendored host carries no manifest at ${host}`, { host });
@@ -1671,10 +1670,13 @@ function stageHost(checkout, host, options) {
1671
1670
  };
1672
1671
  });
1673
1672
  const collisions = readSurfaceCollisions(join(root, "guides"));
1674
- const growth = published === void 0 ? [] : [...collisions].flatMap(([name, owners]) => {
1675
- const record = published.get(name);
1676
- return record !== void 0 && owners.every((owner) => record.includes(owner)) ? [] : [`${name} staged (${owners.join(", ")}), recorded (${record?.join(", ") ?? "absent"})`];
1677
- });
1673
+ const growth = published === void 0 ? [] : compareSurfaceCollisions([...collisions].map(([name, owners]) => ({
1674
+ name,
1675
+ owners
1676
+ })), [...published].map(([name, owners]) => ({
1677
+ name,
1678
+ owners
1679
+ }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})`);
1678
1680
  if (growth.length > 0) throw new ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
1679
1681
  checkout: source,
1680
1682
  host: root,
@@ -1727,26 +1729,199 @@ function stageHost(checkout, host, options) {
1727
1729
  * ```
1728
1730
  */
1729
1731
  function readSurfaceCollisions(root) {
1730
- if (!isPhysicalDirectory(root)) throw new ScaffoldError("TARGET", `Surface guide directory is not readable at ${root}`, { root });
1731
- const loaded = attempt(() => createRequire(import.meta.url)("@orkestrel/guide"));
1732
- if (!loaded.success) throw new ScaffoldError("TARGET", "Surface reflection requires the module @orkestrel/guide", {
1733
- root,
1734
- error: loaded.error
1732
+ return new Map(collectSurfaceCollisions(readSurfaceClaims(root)).map(({ name, owners }) => [name, owners]));
1733
+ }
1734
+ /**
1735
+ * Resolves the bundled host root from the executing module's location.
1736
+ *
1737
+ * @example
1738
+ * ```ts
1739
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
1740
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
1741
+ * ```
1742
+ */
1743
+ function resolveHostRoot() {
1744
+ const location = fileURLToPath(import.meta.url);
1745
+ return resolve(dirname(location), extname(location) === ".ts" ? "../.." : "../../host");
1746
+ }
1747
+ /**
1748
+ * Loads and validates the guide functions required by surface reflection.
1749
+ *
1750
+ * @param loader - The module resolver. Default: Node resolution from this module.
1751
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
1752
+ * @example
1753
+ * ```ts
1754
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
1755
+ * readSurfaceModule().createGuide('# Sample').surface() // []
1756
+ * ```
1757
+ */
1758
+ function readSurfaceModule(loader = createRequire(import.meta.url)) {
1759
+ const loaded = attempt(() => loader("@orkestrel/guide"));
1760
+ if (!loaded.success || !isSurfaceModule(loaded.value)) throw new ScaffoldError("TARGET", "Surface reflection requires @orkestrel/guide with createGuide, createSource, and extractSourceLines. Supply that module in scaffold's resolution path.", { ...!loaded.success ? { error: loaded.error } : {} });
1761
+ return loaded.value;
1762
+ }
1763
+ /**
1764
+ * Reads one guide's claims and reports parser refusals with its owner and source.
1765
+ *
1766
+ * @param source - The source label or path to name in a refusal.
1767
+ * @throws Thrown with TARGET when the module or the guide parser refuses the reading.
1768
+ * @example
1769
+ * ```ts
1770
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
1771
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
1772
+ * ```
1773
+ */
1774
+ function readSurfaceGuide(text, owner, source, loader) {
1775
+ const guide = readSurfaceModule(loader);
1776
+ const parsed = attempt(() => guide.createGuide(text).surface().map(({ name }) => name));
1777
+ if (!parsed.success) throw new ScaffoldError("TARGET", `Surface guide for ${JSON.stringify(owner.slice(0, 512))} from ${JSON.stringify(source.slice(0, 512))} was refused: ${isError(parsed.error) ? parsed.error.message : String(parsed.error)}`, {
1778
+ owner,
1779
+ source
1735
1780
  });
1736
- const guide = loaded.value;
1737
- const claims = listFiles(root).filter((path) => !path.includes("/") && extname(path) === ".md" && path !== "README.md").flatMap((path) => {
1781
+ return {
1782
+ owner,
1783
+ names: parsed.value
1784
+ };
1785
+ }
1786
+ /**
1787
+ * Reads each immediate package guide's bare names under its file owner.
1788
+ *
1789
+ * @param root - The directory containing the package guides; README.md is excluded.
1790
+ * @param loader - The module resolver used by the shared validated guide loader.
1791
+ * @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
1792
+ *
1793
+ * @example
1794
+ * ```ts
1795
+ * import { readSurfaceClaims } from '@orkestrel/scaffold/server'
1796
+ *
1797
+ * readSurfaceClaims('./guides') // owners and the names their guides claim
1798
+ * ```
1799
+ */
1800
+ function readSurfaceClaims(root, loader) {
1801
+ if (!isPhysicalDirectory(root)) throw new ScaffoldError("TARGET", `Surface guide directory is not readable at ${root}`, { root });
1802
+ readSurfaceModule(loader);
1803
+ return listFiles(root).filter((path) => !path.includes("/") && extname(path) === ".md" && path !== "README.md").map((path) => {
1738
1804
  const text = readFileText(root, path);
1739
1805
  if (text === void 0) throw new ScaffoldError("TARGET", `Surface guide cannot be read at ${path}`, {
1740
1806
  root,
1741
1807
  path
1742
1808
  });
1743
- return guide.createGuide(text).surface().map((symbol) => [symbol.name, basename(path, ".md")]);
1809
+ return readSurfaceGuide(text, basename(path, ".md"), join(root, path), loader);
1744
1810
  });
1745
- const grouped = Map.groupBy(claims, ([name]) => name);
1746
- return new Map([...grouped.keys()].sort().flatMap((name) => {
1747
- const owners = [...new Set((grouped.get(name) ?? []).map(([, owner]) => owner))];
1748
- return owners.length > 1 ? [[name, owners.sort()]] : [];
1811
+ }
1812
+ /**
1813
+ * Reads a checkout's combined guide and barrel claims under its manifest owner.
1814
+ *
1815
+ * @remarks
1816
+ * Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
1817
+ * src environment through @orkestrel/guide, loaded only when called, and reports each
1818
+ * name two or more environments export as a conflict.
1819
+ * Reads only .ts files and refuses barrel statements outside relative .js star exports.
1820
+ * A present unreadable guide refuses the candidate even when src exists.
1821
+ * `loader` selects the resolver used by the shared validated guide loader.
1822
+ * @throws Thrown when the manifest is unreadable, both claim sources are absent,
1823
+ * a source cannot be read, or @orkestrel/guide cannot be loaded.
1824
+ *
1825
+ * @example
1826
+ * ```ts
1827
+ * import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
1828
+ *
1829
+ * readSurfaceCandidate('.') // the working checkout's owner and combined names
1830
+ * ```
1831
+ */
1832
+ function readSurfaceCandidate(root, loader) {
1833
+ const manifest = readFileText(root, "package.json", MAX_MANIFEST_BYTES);
1834
+ const name = manifest === void 0 ? void 0 : manifestToName(manifest);
1835
+ if (name === void 0) throw new ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} needs package.json with a valid name.`, { root });
1836
+ const owner = name.replace(/^@orkestrel\//u, "");
1837
+ const guide = readSurfaceFile(root, owner, "candidate", loader);
1838
+ const source = join(root, "src");
1839
+ if (guide === void 0 && !isPhysicalDirectory(source)) throw new ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} has neither ${JSON.stringify(`guides/${owner}.md`)} nor src/. Add its guide or source directory before checking its claims.`, { root });
1840
+ const reflection = readSurfaceModule(loader);
1841
+ const files = Object.fromEntries(listFiles(source).filter((file) => file.endsWith(".ts")).map((file) => {
1842
+ const text = readFileText(source, file);
1843
+ if (text === void 0) throw new ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} cannot read ${JSON.stringify(`src/${file}`.slice(0, 512))}. Restore a readable source file before checking its claims.`, {
1844
+ root,
1845
+ path: file
1846
+ });
1847
+ return [`src/${file}`, text];
1749
1848
  }));
1849
+ for (const [file, text] of Object.entries(files)) {
1850
+ if (!file.endsWith("/index.ts")) continue;
1851
+ for (const line of reflection.extractSourceLines(text)) {
1852
+ if (line.code.trim() === "" || /^\s*export\s+\*\s+from\s+(?:'(\.\.?\/[^']+\.js)'|"(\.\.?\/[^"]+\.js)")\s*;?\s*$/u.test(line.code)) continue;
1853
+ throw new ScaffoldError("TARGET", `Surface candidate barrel ${JSON.stringify(join(root, file).slice(0, 512))} refuses statement ${JSON.stringify(line.source.trim().slice(0, 512))}; use only export * from './module.js' declarations.`, {
1854
+ root,
1855
+ path: file
1856
+ });
1857
+ }
1858
+ }
1859
+ const exports = Object.fromEntries(listDirectories(source).filter((directory) => !directory.includes("/")).map((directory) => [directory, reflection.createSource({
1860
+ files,
1861
+ module: `src/${directory}`
1862
+ }).surface().map((symbol) => symbol.name)]));
1863
+ return {
1864
+ owner,
1865
+ names: [.../* @__PURE__ */ new Set([...guide?.names ?? [], ...Object.values(exports).flat()])].sort(),
1866
+ conflicts: collectSurfaceConflicts(owner, exports)
1867
+ };
1868
+ }
1869
+ /**
1870
+ * Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
1871
+ *
1872
+ * @param root - The checkout or data root holding the guide, or a verified host whose bytes
1873
+ * carry it at that destination.
1874
+ * @param owner - The unscoped package name the guide file is named for.
1875
+ * @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
1876
+ * @param loader - The module resolver used by the shared validated guide loader.
1877
+ * @returns The claim, or `undefined` when no file sits at the path or the host declares none.
1878
+ * @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
1879
+ * file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
1880
+ *
1881
+ * @example
1882
+ * ```ts
1883
+ * import { readSurfaceFile } from '@orkestrel/scaffold/server'
1884
+ *
1885
+ * readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
1886
+ * ```
1887
+ */
1888
+ function readSurfaceFile(root, owner, label, loader) {
1889
+ const destination = `guides/${owner}.md`;
1890
+ if (!isString(root)) {
1891
+ const hex = root.bytes[destination];
1892
+ const declared = hex === void 0 ? void 0 : decodeHexText(hex);
1893
+ if (hex !== void 0 && declared === void 0) throw new ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(destination)}`, { path: destination });
1894
+ return declared === void 0 ? void 0 : readSurfaceGuide(declared, owner, `${label} ${destination}`, loader);
1895
+ }
1896
+ const path = join(root, "guides", `${owner}.md`);
1897
+ const text = readFileText(root, destination);
1898
+ if (text === void 0 && isExactCaseFile(path)) throw new ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(path.slice(0, 512))}`, {
1899
+ root,
1900
+ path: `guides/${owner}.md`
1901
+ });
1902
+ return text === void 0 ? void 0 : readSurfaceGuide(text, owner, `${label} ${path}`, loader);
1903
+ }
1904
+ /**
1905
+ * Reads a data root's verified collision record.
1906
+ *
1907
+ * @param root - The data root holding `manifest.json` or `host.json`.
1908
+ * @remarks
1909
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
1910
+ * Reads only local files and never contacts upstream or writes an inventory.
1911
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
1912
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
1913
+ *
1914
+ * @example
1915
+ * ```ts
1916
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
1917
+ *
1918
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
1919
+ * ```
1920
+ */
1921
+ function readSurfaceRecord(root) {
1922
+ const record = readSurfaceBaseline(root, "manifest.json") ?? readSurfaceBaseline(root);
1923
+ if (record === void 0) throw new ScaffoldError("TARGET", `Surface data root ${JSON.stringify(root.slice(0, 512))} needs manifest.json or host.json with a surface record. Supply an inventoried root with --from.`, { root });
1924
+ return record;
1750
1925
  }
1751
1926
  /**
1752
1927
  * Reads the Surface collision baseline from a committed inventory.
@@ -1991,6 +2166,18 @@ function matchesPrecondition(precondition) {
1991
2166
  }
1992
2167
  // src/server/validators.ts
1993
2168
  /**
2169
+ * Narrows a value to the callable guide functions surface reflection requires.
2170
+ *
2171
+ * @example
2172
+ * ```ts
2173
+ * import { isSurfaceModule } from '@orkestrel/scaffold/server'
2174
+ * isSurfaceModule({}) // false
2175
+ * ```
2176
+ */
2177
+ function isSurfaceModule(value) {
2178
+ return holds(() => isObject(value) && "createGuide" in value && isFunction(value.createGuide) && "createSource" in value && isFunction(value.createSource) && "extractSourceLines" in value && isFunction(value.extractSourceLines));
2179
+ }
2180
+ /**
1994
2181
  * Narrows a value to a path naming a location on this host.
1995
2182
  *
1996
2183
  * @param value - The candidate host path.
@@ -4101,7 +4288,7 @@ var Upstream = class {
4101
4288
  const observed = this.#accept(current, isSnapshot, "current");
4102
4289
  if (accepted.length === 0) return [];
4103
4290
  const allowance = new ReadAllowance(this.#budget);
4104
- const inventory = await this.#inventory(allowance);
4291
+ const inventory = await this.inventory(allowance);
4105
4292
  return this.#gather(accepted, (path) => this.#file(path, inventory, observed, allowance));
4106
4293
  }
4107
4294
  /**
@@ -4120,7 +4307,9 @@ var Upstream = class {
4120
4307
  * unreadable list would otherwise be written into a target's catalog table as
4121
4308
  * a fleet with no packages in it. A package whose own version lookup then
4122
4309
  * fails still keeps its row, carrying the cause instead of a version, because
4123
- * the list already proved the package is published.
4310
+ * the list already proved the package is published. The `FETCH` failure's
4311
+ * context carries `unreachable: true` only when the list request produced no
4312
+ * HTTP response.
4124
4313
  *
4125
4314
  * @example
4126
4315
  * ```ts
@@ -4138,6 +4327,56 @@ var Upstream = class {
4138
4327
  return this.#gather(names, (name) => this.#entry(name, allowance));
4139
4328
  }
4140
4329
  /**
4330
+ * Reads the verified upstream inventory and its collision record.
4331
+ *
4332
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
4333
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
4334
+ * carrying `unreachable: true` only when the request produced no HTTP response.
4335
+ * @throws Thrown with DESTROYED when the reader has been torn down.
4336
+ * @example
4337
+ * ```ts
4338
+ * import { Upstream } from '@orkestrel/scaffold/server'
4339
+ * const upstream = new Upstream()
4340
+ * const inventory = await upstream.inventory()
4341
+ * inventory.surface // the verified record when lookup is found
4342
+ * upstream.destroy()
4343
+ * ```
4344
+ */
4345
+ async inventory(allowance = new ReadAllowance(this.#budget)) {
4346
+ this.#assertAlive();
4347
+ const url = this.#vendorURL(HOST_INVENTORY_PATH);
4348
+ const empty = {
4349
+ digests: /* @__PURE__ */ new Map(),
4350
+ duplicates: /* @__PURE__ */ new Set(),
4351
+ surface: []
4352
+ };
4353
+ const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
4354
+ if (outcome.lookup !== "found") return {
4355
+ ...empty,
4356
+ lookup: outcome.lookup,
4357
+ note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`,
4358
+ ...outcome.unreachable === true ? { unreachable: true } : {}
4359
+ };
4360
+ const manifest = parseJSONAs(outcome.content, isHostManifest);
4361
+ if (manifest === void 0) return {
4362
+ ...empty,
4363
+ lookup: "failed",
4364
+ note: `the vendored inventory at ${url} is not a readable manifest`
4365
+ };
4366
+ if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
4367
+ ...empty,
4368
+ lookup: "failed",
4369
+ note: `the vendored inventory at ${url} does not match its own membership digest`
4370
+ };
4371
+ return {
4372
+ lookup: "found",
4373
+ digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
4374
+ duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
4375
+ surface: manifest.surface,
4376
+ note: ""
4377
+ };
4378
+ }
4379
+ /**
4141
4380
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
4142
4381
  *
4143
4382
  * @returns Nothing.
@@ -4279,36 +4518,6 @@ var Upstream = class {
4279
4518
  ...carried
4280
4519
  };
4281
4520
  }
4282
- async #inventory(allowance) {
4283
- const url = this.#vendorURL(HOST_INVENTORY_PATH);
4284
- const empty = {
4285
- digests: /* @__PURE__ */ new Map(),
4286
- duplicates: /* @__PURE__ */ new Set()
4287
- };
4288
- const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
4289
- if (outcome.lookup !== "found") return {
4290
- ...empty,
4291
- lookup: outcome.lookup,
4292
- note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`
4293
- };
4294
- const manifest = parseJSONAs(outcome.content, isHostManifest);
4295
- if (manifest === void 0) return {
4296
- ...empty,
4297
- lookup: "failed",
4298
- note: `the vendored inventory at ${url} is not a readable manifest`
4299
- };
4300
- if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
4301
- ...empty,
4302
- lookup: "failed",
4303
- note: `the vendored inventory at ${url} does not match its own membership digest`
4304
- };
4305
- return {
4306
- lookup: "found",
4307
- digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
4308
- duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
4309
- note: ""
4310
- };
4311
- }
4312
4521
  async #entry(name, allowance) {
4313
4522
  const outcome = await this.#readWithRetries(this.#registryURL(name), this.#registryTimeout, allowance, PACKUMENT_MEDIA_TYPE);
4314
4523
  const version = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
@@ -4344,7 +4553,8 @@ var Upstream = class {
4344
4553
  const outcome = await this.#readWithRetries(url, this.#registryTimeout, allowance);
4345
4554
  if (outcome.lookup !== "found") throw this.#error("FETCH", `The organization package list at ${url} produced no answer.`, {
4346
4555
  url,
4347
- note: outcome.note
4556
+ note: outcome.note,
4557
+ ...outcome.unreachable === true ? { unreachable: true } : {}
4348
4558
  });
4349
4559
  const parsed = parseJSON(outcome.content);
4350
4560
  if (!isRecord(parsed)) throw this.#error("FETCH", `The organization package list at ${url} is not a record.`, { url });
@@ -4404,15 +4614,7 @@ var Upstream = class {
4404
4614
  url,
4405
4615
  note
4406
4616
  });
4407
- return binary ? {
4408
- lookup: "failed",
4409
- hex: "",
4410
- note
4411
- } : {
4412
- lookup: "failed",
4413
- content: "",
4414
- note
4415
- };
4617
+ return outcome;
4416
4618
  }
4417
4619
  async #request(url, timeout, allowance, accept, binary = false) {
4418
4620
  if (allowance.remaining <= 0) {
@@ -4427,12 +4629,28 @@ var Upstream = class {
4427
4629
  note
4428
4630
  };
4429
4631
  }
4632
+ const fetched = await fetch(url, {
4633
+ signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
4634
+ redirect: "manual",
4635
+ ...accept === void 0 ? {} : { headers: { accept } }
4636
+ }).then((response) => ({ response }), (error) => ({ error }));
4637
+ if ("error" in fetched) {
4638
+ this.#assertAlive();
4639
+ const note = this.#note(fetched.error);
4640
+ return binary ? {
4641
+ lookup: "failed",
4642
+ hex: "",
4643
+ note,
4644
+ unreachable: true
4645
+ } : {
4646
+ lookup: "failed",
4647
+ content: "",
4648
+ note,
4649
+ unreachable: true
4650
+ };
4651
+ }
4430
4652
  try {
4431
- const response = await fetch(url, {
4432
- signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
4433
- redirect: "manual",
4434
- ...accept === void 0 ? {} : { headers: { accept } }
4435
- });
4653
+ const response = fetched.response;
4436
4654
  if (response.status === 404) {
4437
4655
  await response.body?.cancel();
4438
4656
  return binary ? {
@@ -4558,7 +4776,7 @@ var Upstream = class {
4558
4776
  #note(error) {
4559
4777
  if (!isError(error)) return "the request failed for an unreported reason";
4560
4778
  const cause = error.cause;
4561
- const code = isRecord(cause) && isString(cause.code) ? cause.code : void 0;
4779
+ const code = isObject(cause) && "code" in cause && isString(cause.code) ? cause.code : void 0;
4562
4780
  const message = `${error.name}: ${error.message}`;
4563
4781
  return code === void 0 ? message : `${message} (${code})`;
4564
4782
  }
@@ -4600,6 +4818,6 @@ var Upstream = class {
4600
4818
  return error;
4601
4819
  }
4602
4820
  };
4603
- export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, ReadAllowance, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, Upstream, WriteTransaction, climbRealPath, collectIndexed, computeDigest, computeFileDigest, computeManifestDigest, decodeHexText, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listAncestors, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCollisions, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
4821
+ export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, ReadAllowance, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, Upstream, WriteTransaction, climbRealPath, collectIndexed, computeDigest, computeFileDigest, computeManifestDigest, decodeHexText, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isSurfaceModule, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listAncestors, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCandidate, readSurfaceClaims, readSurfaceCollisions, readSurfaceFile, readSurfaceGuide, readSurfaceModule, readSurfaceRecord, resolveContainedPath, resolveHostRoot, resolveRealPath, stageBytes, stageHost, stageInventory };
4604
4822
 
4605
4823
  //# sourceMappingURL=index.js.map