@orkestrel/scaffold 0.0.115 → 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 (70) hide show
  1. package/dist/bin/main.js +137 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
  4. package/dist/host/claude/agents/orkestrel.md +1 -1
  5. package/dist/host/claude/rules/names.md +3 -1
  6. package/dist/host/guides/abort.md +17 -17
  7. package/dist/host/guides/agent.md +445 -445
  8. package/dist/host/guides/brief.md +143 -143
  9. package/dist/host/guides/browser.md +731 -731
  10. package/dist/host/guides/budget.md +39 -39
  11. package/dist/host/guides/capture.md +298 -298
  12. package/dist/host/guides/console.md +109 -109
  13. package/dist/host/guides/contract.md +335 -335
  14. package/dist/host/guides/csv.md +30 -30
  15. package/dist/host/guides/database.md +163 -163
  16. package/dist/host/guides/emitter.md +17 -17
  17. package/dist/host/guides/form.md +99 -99
  18. package/dist/host/guides/guide.md +361 -183
  19. package/dist/host/guides/html.md +49 -49
  20. package/dist/host/guides/indexeddb.md +40 -40
  21. package/dist/host/guides/interpret.md +139 -139
  22. package/dist/host/guides/lsp.md +114 -114
  23. package/dist/host/guides/markdown.md +68 -68
  24. package/dist/host/guides/mcp.md +3745 -3745
  25. package/dist/host/guides/middleware.md +170 -170
  26. package/dist/host/guides/msg.md +95 -95
  27. package/dist/host/guides/ndjson.md +8 -8
  28. package/dist/host/guides/ollama.md +56 -56
  29. package/dist/host/guides/pool.md +21 -21
  30. package/dist/host/guides/probe.md +82 -82
  31. package/dist/host/guides/process.md +99 -99
  32. package/dist/host/guides/program.md +98 -96
  33. package/dist/host/guides/qualifier.md +70 -70
  34. package/dist/host/guides/queue.md +37 -37
  35. package/dist/host/guides/rater.md +38 -38
  36. package/dist/host/guides/reason.md +308 -308
  37. package/dist/host/guides/relation.md +50 -50
  38. package/dist/host/guides/router.md +58 -58
  39. package/dist/host/guides/scaffold.md +554 -419
  40. package/dist/host/guides/sea.md +128 -128
  41. package/dist/host/guides/server.md +100 -100
  42. package/dist/host/guides/sqlite.md +28 -28
  43. package/dist/host/guides/sse.md +20 -20
  44. package/dist/host/guides/study.md +444 -444
  45. package/dist/host/guides/table.md +82 -82
  46. package/dist/host/guides/template.md +41 -41
  47. package/dist/host/guides/terminal.md +121 -121
  48. package/dist/host/guides/test.md +273 -273
  49. package/dist/host/guides/timeout.md +18 -18
  50. package/dist/host/guides/tool.md +27 -27
  51. package/dist/host/guides/toolbox.md +166 -166
  52. package/dist/host/guides/websocket.md +54 -54
  53. package/dist/host/guides/worker.md +24 -24
  54. package/dist/host/guides/workflow.md +187 -187
  55. package/dist/host/guides/workspace.md +55 -55
  56. package/dist/host/manifest.json +55 -55
  57. package/dist/host/tests/setupPolicy.ts +5 -3
  58. package/dist/src/core/index.cjs +89 -3
  59. package/dist/src/core/index.cjs.map +1 -1
  60. package/dist/src/core/index.d.cts +229 -144
  61. package/dist/src/core/index.d.ts +229 -144
  62. package/dist/src/core/index.js +87 -4
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +292 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +188 -6
  67. package/dist/src/server/index.d.ts +188 -6
  68. package/dist/src/server/index.js +287 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +4 -3
@@ -1287,9 +1287,8 @@ function readHostManifest(host, name = MANIFEST_NAME) {
1287
1287
  */
1288
1288
  function readHostFloor(root) {
1289
1289
  const location = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
1290
- const module = (0, node_path.dirname)(location);
1291
1290
  const source = root === void 0 && (0, node_path.extname)(location) === ".ts";
1292
- const host = root ?? (0, node_path.resolve)(module, source ? "../.." : "../../host");
1291
+ const host = root ?? resolveHostRoot();
1293
1292
  if (!isPhysicalDirectory(host)) throw new _src_core.ScaffoldError("TARGET", `The vendored host root is not readable at ${host}`, { host });
1294
1293
  const manifest = readHostManifest(host, source ? _src_core.HOST_INVENTORY_PATH : MANIFEST_NAME);
1295
1294
  if (manifest === void 0) throw new _src_core.ScaffoldError("TARGET", `The vendored host carries no manifest at ${host}`, { host });
@@ -1672,10 +1671,13 @@ function stageHost(checkout, host, options) {
1672
1671
  };
1673
1672
  });
1674
1673
  const collisions = readSurfaceCollisions((0, node_path.join)(root, "guides"));
1675
- const growth = published === void 0 ? [] : [...collisions].flatMap(([name, owners]) => {
1676
- const record = published.get(name);
1677
- return record !== void 0 && owners.every((owner) => record.includes(owner)) ? [] : [`${name} staged (${owners.join(", ")}), recorded (${record?.join(", ") ?? "absent"})`];
1678
- });
1674
+ const growth = published === void 0 ? [] : (0, _src_core.compareSurfaceCollisions)([...collisions].map(([name, owners]) => ({
1675
+ name,
1676
+ owners
1677
+ })), [...published].map(([name, owners]) => ({
1678
+ name,
1679
+ owners
1680
+ }))).filter(({ standing }) => standing === "error").map(({ name, owners }) => `${name} staged (${owners.join(", ")}), recorded (${published.get(name)?.join(", ") ?? "absent"})`);
1679
1681
  if (growth.length > 0) throw new _src_core.ScaffoldError("TARGET", `Staged Surface collisions differ from the inventory: ${growth.join("; ")}`, {
1680
1682
  checkout: source,
1681
1683
  host: root,
@@ -1728,26 +1730,199 @@ function stageHost(checkout, host, options) {
1728
1730
  * ```
1729
1731
  */
1730
1732
  function readSurfaceCollisions(root) {
1731
- if (!isPhysicalDirectory(root)) throw new _src_core.ScaffoldError("TARGET", `Surface guide directory is not readable at ${root}`, { root });
1732
- const loaded = (0, _orkestrel_contract.attempt)(() => (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("@orkestrel/guide"));
1733
- if (!loaded.success) throw new _src_core.ScaffoldError("TARGET", "Surface reflection requires the module @orkestrel/guide", {
1734
- root,
1735
- error: loaded.error
1733
+ return new Map((0, _src_core.collectSurfaceCollisions)(readSurfaceClaims(root)).map(({ name, owners }) => [name, owners]));
1734
+ }
1735
+ /**
1736
+ * Resolves the bundled host root from the executing module's location.
1737
+ *
1738
+ * @example
1739
+ * ```ts
1740
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
1741
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
1742
+ * ```
1743
+ */
1744
+ function resolveHostRoot() {
1745
+ const location = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
1746
+ return (0, node_path.resolve)((0, node_path.dirname)(location), (0, node_path.extname)(location) === ".ts" ? "../.." : "../../host");
1747
+ }
1748
+ /**
1749
+ * Loads and validates the guide functions required by surface reflection.
1750
+ *
1751
+ * @param loader - The module resolver. Default: Node resolution from this module.
1752
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
1753
+ * @example
1754
+ * ```ts
1755
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
1756
+ * readSurfaceModule().createGuide('# Sample').surface() // []
1757
+ * ```
1758
+ */
1759
+ function readSurfaceModule(loader = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)) {
1760
+ const loaded = (0, _orkestrel_contract.attempt)(() => loader("@orkestrel/guide"));
1761
+ if (!loaded.success || !isSurfaceModule(loaded.value)) throw new _src_core.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 } : {} });
1762
+ return loaded.value;
1763
+ }
1764
+ /**
1765
+ * Reads one guide's claims and reports parser refusals with its owner and source.
1766
+ *
1767
+ * @param source - The source label or path to name in a refusal.
1768
+ * @throws Thrown with TARGET when the module or the guide parser refuses the reading.
1769
+ * @example
1770
+ * ```ts
1771
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
1772
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
1773
+ * ```
1774
+ */
1775
+ function readSurfaceGuide(text, owner, source, loader) {
1776
+ const guide = readSurfaceModule(loader);
1777
+ const parsed = (0, _orkestrel_contract.attempt)(() => guide.createGuide(text).surface().map(({ name }) => name));
1778
+ if (!parsed.success) throw new _src_core.ScaffoldError("TARGET", `Surface guide for ${JSON.stringify(owner.slice(0, 512))} from ${JSON.stringify(source.slice(0, 512))} was refused: ${(0, _orkestrel_contract.isError)(parsed.error) ? parsed.error.message : String(parsed.error)}`, {
1779
+ owner,
1780
+ source
1736
1781
  });
1737
- const guide = loaded.value;
1738
- const claims = listFiles(root).filter((path) => !path.includes("/") && (0, node_path.extname)(path) === ".md" && path !== "README.md").flatMap((path) => {
1782
+ return {
1783
+ owner,
1784
+ names: parsed.value
1785
+ };
1786
+ }
1787
+ /**
1788
+ * Reads each immediate package guide's bare names under its file owner.
1789
+ *
1790
+ * @param root - The directory containing the package guides; README.md is excluded.
1791
+ * @param loader - The module resolver used by the shared validated guide loader.
1792
+ * @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
1793
+ *
1794
+ * @example
1795
+ * ```ts
1796
+ * import { readSurfaceClaims } from '@orkestrel/scaffold/server'
1797
+ *
1798
+ * readSurfaceClaims('./guides') // owners and the names their guides claim
1799
+ * ```
1800
+ */
1801
+ function readSurfaceClaims(root, loader) {
1802
+ if (!isPhysicalDirectory(root)) throw new _src_core.ScaffoldError("TARGET", `Surface guide directory is not readable at ${root}`, { root });
1803
+ readSurfaceModule(loader);
1804
+ return listFiles(root).filter((path) => !path.includes("/") && (0, node_path.extname)(path) === ".md" && path !== "README.md").map((path) => {
1739
1805
  const text = readFileText(root, path);
1740
1806
  if (text === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${path}`, {
1741
1807
  root,
1742
1808
  path
1743
1809
  });
1744
- return guide.createGuide(text).surface().map((symbol) => [symbol.name, (0, node_path.basename)(path, ".md")]);
1810
+ return readSurfaceGuide(text, (0, node_path.basename)(path, ".md"), (0, node_path.join)(root, path), loader);
1745
1811
  });
1746
- const grouped = Map.groupBy(claims, ([name]) => name);
1747
- return new Map([...grouped.keys()].sort().flatMap((name) => {
1748
- const owners = [...new Set((grouped.get(name) ?? []).map(([, owner]) => owner))];
1749
- return owners.length > 1 ? [[name, owners.sort()]] : [];
1812
+ }
1813
+ /**
1814
+ * Reads a checkout's combined guide and barrel claims under its manifest owner.
1815
+ *
1816
+ * @remarks
1817
+ * Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
1818
+ * src environment through @orkestrel/guide, loaded only when called, and reports each
1819
+ * name two or more environments export as a conflict.
1820
+ * Reads only .ts files and refuses barrel statements outside relative .js star exports.
1821
+ * A present unreadable guide refuses the candidate even when src exists.
1822
+ * `loader` selects the resolver used by the shared validated guide loader.
1823
+ * @throws Thrown when the manifest is unreadable, both claim sources are absent,
1824
+ * a source cannot be read, or @orkestrel/guide cannot be loaded.
1825
+ *
1826
+ * @example
1827
+ * ```ts
1828
+ * import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
1829
+ *
1830
+ * readSurfaceCandidate('.') // the working checkout's owner and combined names
1831
+ * ```
1832
+ */
1833
+ function readSurfaceCandidate(root, loader) {
1834
+ const manifest = readFileText(root, "package.json", _src_core.MAX_MANIFEST_BYTES);
1835
+ const name = manifest === void 0 ? void 0 : (0, _src_core.manifestToName)(manifest);
1836
+ if (name === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface candidate ${JSON.stringify(root.slice(0, 512))} needs package.json with a valid name.`, { root });
1837
+ const owner = name.replace(/^@orkestrel\//u, "");
1838
+ const guide = readSurfaceFile(root, owner, "candidate", loader);
1839
+ const source = (0, node_path.join)(root, "src");
1840
+ if (guide === void 0 && !isPhysicalDirectory(source)) throw new _src_core.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 });
1841
+ const reflection = readSurfaceModule(loader);
1842
+ const files = Object.fromEntries(listFiles(source).filter((file) => file.endsWith(".ts")).map((file) => {
1843
+ const text = readFileText(source, file);
1844
+ if (text === void 0) throw new _src_core.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.`, {
1845
+ root,
1846
+ path: file
1847
+ });
1848
+ return [`src/${file}`, text];
1750
1849
  }));
1850
+ for (const [file, text] of Object.entries(files)) {
1851
+ if (!file.endsWith("/index.ts")) continue;
1852
+ for (const line of reflection.extractSourceLines(text)) {
1853
+ if (line.code.trim() === "" || /^\s*export\s+\*\s+from\s+(?:'(\.\.?\/[^']+\.js)'|"(\.\.?\/[^"]+\.js)")\s*;?\s*$/u.test(line.code)) continue;
1854
+ throw new _src_core.ScaffoldError("TARGET", `Surface candidate barrel ${JSON.stringify((0, node_path.join)(root, file).slice(0, 512))} refuses statement ${JSON.stringify(line.source.trim().slice(0, 512))}; use only export * from './module.js' declarations.`, {
1855
+ root,
1856
+ path: file
1857
+ });
1858
+ }
1859
+ }
1860
+ const exports = Object.fromEntries(listDirectories(source).filter((directory) => !directory.includes("/")).map((directory) => [directory, reflection.createSource({
1861
+ files,
1862
+ module: `src/${directory}`
1863
+ }).surface().map((symbol) => symbol.name)]));
1864
+ return {
1865
+ owner,
1866
+ names: [.../* @__PURE__ */ new Set([...guide?.names ?? [], ...Object.values(exports).flat()])].sort(),
1867
+ conflicts: (0, _src_core.collectSurfaceConflicts)(owner, exports)
1868
+ };
1869
+ }
1870
+ /**
1871
+ * Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
1872
+ *
1873
+ * @param root - The checkout or data root holding the guide, or a verified host whose bytes
1874
+ * carry it at that destination.
1875
+ * @param owner - The unscoped package name the guide file is named for.
1876
+ * @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
1877
+ * @param loader - The module resolver used by the shared validated guide loader.
1878
+ * @returns The claim, or `undefined` when no file sits at the path or the host declares none.
1879
+ * @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
1880
+ * file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
1881
+ *
1882
+ * @example
1883
+ * ```ts
1884
+ * import { readSurfaceFile } from '@orkestrel/scaffold/server'
1885
+ *
1886
+ * readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
1887
+ * ```
1888
+ */
1889
+ function readSurfaceFile(root, owner, label, loader) {
1890
+ const destination = `guides/${owner}.md`;
1891
+ if (!(0, _orkestrel_contract.isString)(root)) {
1892
+ const hex = root.bytes[destination];
1893
+ const declared = hex === void 0 ? void 0 : decodeHexText(hex);
1894
+ if (hex !== void 0 && declared === void 0) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(destination)}`, { path: destination });
1895
+ return declared === void 0 ? void 0 : readSurfaceGuide(declared, owner, `${label} ${destination}`, loader);
1896
+ }
1897
+ const path = (0, node_path.join)(root, "guides", `${owner}.md`);
1898
+ const text = readFileText(root, destination);
1899
+ if (text === void 0 && isExactCaseFile(path)) throw new _src_core.ScaffoldError("TARGET", `Surface guide cannot be read at ${JSON.stringify(path.slice(0, 512))}`, {
1900
+ root,
1901
+ path: `guides/${owner}.md`
1902
+ });
1903
+ return text === void 0 ? void 0 : readSurfaceGuide(text, owner, `${label} ${path}`, loader);
1904
+ }
1905
+ /**
1906
+ * Reads a data root's verified collision record.
1907
+ *
1908
+ * @param root - The data root holding `manifest.json` or `host.json`.
1909
+ * @remarks
1910
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
1911
+ * Reads only local files and never contacts upstream or writes an inventory.
1912
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
1913
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
1914
+ *
1915
+ * @example
1916
+ * ```ts
1917
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
1918
+ *
1919
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
1920
+ * ```
1921
+ */
1922
+ function readSurfaceRecord(root) {
1923
+ const record = readSurfaceBaseline(root, "manifest.json") ?? readSurfaceBaseline(root);
1924
+ if (record === void 0) throw new _src_core.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 });
1925
+ return record;
1751
1926
  }
1752
1927
  /**
1753
1928
  * Reads the Surface collision baseline from a committed inventory.
@@ -1992,6 +2167,18 @@ function matchesPrecondition(precondition) {
1992
2167
  }
1993
2168
  // src/server/validators.ts
1994
2169
  /**
2170
+ * Narrows a value to the callable guide functions surface reflection requires.
2171
+ *
2172
+ * @example
2173
+ * ```ts
2174
+ * import { isSurfaceModule } from '@orkestrel/scaffold/server'
2175
+ * isSurfaceModule({}) // false
2176
+ * ```
2177
+ */
2178
+ function isSurfaceModule(value) {
2179
+ return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isObject)(value) && "createGuide" in value && (0, _orkestrel_contract.isFunction)(value.createGuide) && "createSource" in value && (0, _orkestrel_contract.isFunction)(value.createSource) && "extractSourceLines" in value && (0, _orkestrel_contract.isFunction)(value.extractSourceLines));
2180
+ }
2181
+ /**
1995
2182
  * Narrows a value to a path naming a location on this host.
1996
2183
  *
1997
2184
  * @param value - The candidate host path.
@@ -4102,7 +4289,7 @@ var Upstream = class {
4102
4289
  const observed = this.#accept(current, _src_core.isSnapshot, "current");
4103
4290
  if (accepted.length === 0) return [];
4104
4291
  const allowance = new ReadAllowance(this.#budget);
4105
- const inventory = await this.#inventory(allowance);
4292
+ const inventory = await this.inventory(allowance);
4106
4293
  return this.#gather(accepted, (path) => this.#file(path, inventory, observed, allowance));
4107
4294
  }
4108
4295
  /**
@@ -4121,7 +4308,9 @@ var Upstream = class {
4121
4308
  * unreadable list would otherwise be written into a target's catalog table as
4122
4309
  * a fleet with no packages in it. A package whose own version lookup then
4123
4310
  * fails still keeps its row, carrying the cause instead of a version, because
4124
- * the list already proved the package is published.
4311
+ * the list already proved the package is published. The `FETCH` failure's
4312
+ * context carries `unreachable: true` only when the list request produced no
4313
+ * HTTP response.
4125
4314
  *
4126
4315
  * @example
4127
4316
  * ```ts
@@ -4139,6 +4328,56 @@ var Upstream = class {
4139
4328
  return this.#gather(names, (name) => this.#entry(name, allowance));
4140
4329
  }
4141
4330
  /**
4331
+ * Reads the verified upstream inventory and its collision record.
4332
+ *
4333
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
4334
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
4335
+ * carrying `unreachable: true` only when the request produced no HTTP response.
4336
+ * @throws Thrown with DESTROYED when the reader has been torn down.
4337
+ * @example
4338
+ * ```ts
4339
+ * import { Upstream } from '@orkestrel/scaffold/server'
4340
+ * const upstream = new Upstream()
4341
+ * const inventory = await upstream.inventory()
4342
+ * inventory.surface // the verified record when lookup is found
4343
+ * upstream.destroy()
4344
+ * ```
4345
+ */
4346
+ async inventory(allowance = new ReadAllowance(this.#budget)) {
4347
+ this.#assertAlive();
4348
+ const url = this.#vendorURL(_src_core.HOST_INVENTORY_PATH);
4349
+ const empty = {
4350
+ digests: /* @__PURE__ */ new Map(),
4351
+ duplicates: /* @__PURE__ */ new Set(),
4352
+ surface: []
4353
+ };
4354
+ const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
4355
+ if (outcome.lookup !== "found") return {
4356
+ ...empty,
4357
+ lookup: outcome.lookup,
4358
+ note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`,
4359
+ ...outcome.unreachable === true ? { unreachable: true } : {}
4360
+ };
4361
+ const manifest = (0, _orkestrel_contract.parseJSONAs)(outcome.content, isHostManifest);
4362
+ if (manifest === void 0) return {
4363
+ ...empty,
4364
+ lookup: "failed",
4365
+ note: `the vendored inventory at ${url} is not a readable manifest`
4366
+ };
4367
+ if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
4368
+ ...empty,
4369
+ lookup: "failed",
4370
+ note: `the vendored inventory at ${url} does not match its own membership digest`
4371
+ };
4372
+ return {
4373
+ lookup: "found",
4374
+ digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
4375
+ duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
4376
+ surface: manifest.surface,
4377
+ note: ""
4378
+ };
4379
+ }
4380
+ /**
4142
4381
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
4143
4382
  *
4144
4383
  * @returns Nothing.
@@ -4280,36 +4519,6 @@ var Upstream = class {
4280
4519
  ...carried
4281
4520
  };
4282
4521
  }
4283
- async #inventory(allowance) {
4284
- const url = this.#vendorURL(_src_core.HOST_INVENTORY_PATH);
4285
- const empty = {
4286
- digests: /* @__PURE__ */ new Map(),
4287
- duplicates: /* @__PURE__ */ new Set()
4288
- };
4289
- const outcome = await this.#readWithRetries(url, this.#repositoryTimeout, allowance);
4290
- if (outcome.lookup !== "found") return {
4291
- ...empty,
4292
- lookup: outcome.lookup,
4293
- note: outcome.lookup === "missing" ? `the vendored inventory at ${url} is not published there` : `the vendored inventory at ${url} produced no answer: ${outcome.note}`
4294
- };
4295
- const manifest = (0, _orkestrel_contract.parseJSONAs)(outcome.content, isHostManifest);
4296
- if (manifest === void 0) return {
4297
- ...empty,
4298
- lookup: "failed",
4299
- note: `the vendored inventory at ${url} is not a readable manifest`
4300
- };
4301
- if (manifest.digest !== computeManifestDigest(manifest.entries, manifest.roots, manifest.surface)) return {
4302
- ...empty,
4303
- lookup: "failed",
4304
- note: `the vendored inventory at ${url} does not match its own membership digest`
4305
- };
4306
- return {
4307
- lookup: "found",
4308
- digests: new Map(manifest.entries.map((entry) => [entry.destination, entry.digest])),
4309
- duplicates: new Set(manifest.entries.map((entry) => entry.destination).filter((destination, index, destinations) => destinations.indexOf(destination) !== index)),
4310
- note: ""
4311
- };
4312
- }
4313
4522
  async #entry(name, allowance) {
4314
4523
  const outcome = await this.#readWithRetries(this.#registryURL(name), this.#registryTimeout, allowance, PACKUMENT_MEDIA_TYPE);
4315
4524
  const version = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
@@ -4345,7 +4554,8 @@ var Upstream = class {
4345
4554
  const outcome = await this.#readWithRetries(url, this.#registryTimeout, allowance);
4346
4555
  if (outcome.lookup !== "found") throw this.#error("FETCH", `The organization package list at ${url} produced no answer.`, {
4347
4556
  url,
4348
- note: outcome.note
4557
+ note: outcome.note,
4558
+ ...outcome.unreachable === true ? { unreachable: true } : {}
4349
4559
  });
4350
4560
  const parsed = (0, _orkestrel_contract.parseJSON)(outcome.content);
4351
4561
  if (!(0, _orkestrel_contract.isRecord)(parsed)) throw this.#error("FETCH", `The organization package list at ${url} is not a record.`, { url });
@@ -4405,15 +4615,7 @@ var Upstream = class {
4405
4615
  url,
4406
4616
  note
4407
4617
  });
4408
- return binary ? {
4409
- lookup: "failed",
4410
- hex: "",
4411
- note
4412
- } : {
4413
- lookup: "failed",
4414
- content: "",
4415
- note
4416
- };
4618
+ return outcome;
4417
4619
  }
4418
4620
  async #request(url, timeout, allowance, accept, binary = false) {
4419
4621
  if (allowance.remaining <= 0) {
@@ -4428,12 +4630,28 @@ var Upstream = class {
4428
4630
  note
4429
4631
  };
4430
4632
  }
4633
+ const fetched = await fetch(url, {
4634
+ signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
4635
+ redirect: "manual",
4636
+ ...accept === void 0 ? {} : { headers: { accept } }
4637
+ }).then((response) => ({ response }), (error) => ({ error }));
4638
+ if ("error" in fetched) {
4639
+ this.#assertAlive();
4640
+ const note = this.#note(fetched.error);
4641
+ return binary ? {
4642
+ lookup: "failed",
4643
+ hex: "",
4644
+ note,
4645
+ unreachable: true
4646
+ } : {
4647
+ lookup: "failed",
4648
+ content: "",
4649
+ note,
4650
+ unreachable: true
4651
+ };
4652
+ }
4431
4653
  try {
4432
- const response = await fetch(url, {
4433
- signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
4434
- redirect: "manual",
4435
- ...accept === void 0 ? {} : { headers: { accept } }
4436
- });
4654
+ const response = fetched.response;
4437
4655
  if (response.status === 404) {
4438
4656
  await response.body?.cancel();
4439
4657
  return binary ? {
@@ -4559,7 +4777,7 @@ var Upstream = class {
4559
4777
  #note(error) {
4560
4778
  if (!(0, _orkestrel_contract.isError)(error)) return "the request failed for an unreported reason";
4561
4779
  const cause = error.cause;
4562
- const code = (0, _orkestrel_contract.isRecord)(cause) && (0, _orkestrel_contract.isString)(cause.code) ? cause.code : void 0;
4780
+ const code = (0, _orkestrel_contract.isObject)(cause) && "code" in cause && (0, _orkestrel_contract.isString)(cause.code) ? cause.code : void 0;
4563
4781
  const message = `${error.name}: ${error.message}`;
4564
4782
  return code === void 0 ? message : `${message} (${code})`;
4565
4783
  }
@@ -4656,6 +4874,7 @@ exports.isMirrors = isMirrors;
4656
4874
  exports.isPaths = isPaths;
4657
4875
  exports.isPhysicalDirectory = isPhysicalDirectory;
4658
4876
  exports.isPhysicalFile = isPhysicalFile;
4877
+ exports.isSurfaceModule = isSurfaceModule;
4659
4878
  exports.isTimeout = isTimeout;
4660
4879
  exports.isUpstreamHooks = isUpstreamHooks;
4661
4880
  exports.isUpstreamOptions = isUpstreamOptions;
@@ -4684,8 +4903,15 @@ exports.readHostManifest = readHostManifest;
4684
4903
  exports.readManifestEntry = readManifestEntry;
4685
4904
  exports.readSnapshot = readSnapshot;
4686
4905
  exports.readSurfaceBaseline = readSurfaceBaseline;
4906
+ exports.readSurfaceCandidate = readSurfaceCandidate;
4907
+ exports.readSurfaceClaims = readSurfaceClaims;
4687
4908
  exports.readSurfaceCollisions = readSurfaceCollisions;
4909
+ exports.readSurfaceFile = readSurfaceFile;
4910
+ exports.readSurfaceGuide = readSurfaceGuide;
4911
+ exports.readSurfaceModule = readSurfaceModule;
4912
+ exports.readSurfaceRecord = readSurfaceRecord;
4688
4913
  exports.resolveContainedPath = resolveContainedPath;
4914
+ exports.resolveHostRoot = resolveHostRoot;
4689
4915
  exports.resolveRealPath = resolveRealPath;
4690
4916
  exports.stageBytes = stageBytes;
4691
4917
  exports.stageHost = stageHost;