@orkestrel/scaffold 0.0.115 → 0.0.117

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 +138 -16
  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 +2 -2
  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 +368 -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 +558 -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 +90 -4
  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 +88 -5
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +295 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +193 -6
  67. package/dist/src/server/index.d.ts +193 -6
  68. package/dist/src/server/index.js +290 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +5 -4
@@ -13,6 +13,9 @@ import type { Mirror } from '@orkestrel/scaffold';
13
13
  import type { Plan } from '@orkestrel/scaffold';
14
14
  import type { Release } from '@orkestrel/scaffold';
15
15
  import type { Snapshot } from '@orkestrel/scaffold';
16
+ import type { SurfaceCandidate } from '@orkestrel/scaffold';
17
+ import type { SurfaceClaim } from '@orkestrel/scaffold';
18
+ import type { SurfaceCollision } from '@orkestrel/scaffold';
16
19
 
17
20
  /**
18
21
  * Matches the Git branch syntax the repository endpoint accepts.
@@ -33,11 +36,13 @@ export declare const BRANCH_PATTERN: RegExp;
33
36
  * `found`; otherwise it is empty and `note` states what happened. Bytes rather
34
37
  * than text, because a vendored file is compared by digest and a decode would
35
38
  * change what is hashed.
39
+ * `unreachable` is true only when the request produced no HTTP response.
36
40
  */
37
41
  export declare interface BytesReadResult {
38
42
  readonly lookup: Lookup;
39
43
  readonly hex: string;
40
44
  readonly note: string;
45
+ readonly unreachable?: boolean;
41
46
  }
42
47
 
43
48
  /**
@@ -324,13 +329,17 @@ export declare interface Host {
324
329
  * call inherits it when it is not `found`. `digests` maps a target-relative
325
330
  * destination to the exact bytes the inventory declares for it, `duplicates`
326
331
  * names every destination the inventory claims more than once, and `note` states
327
- * why a lookup that is not `found` produced no inventory.
332
+ * why a lookup that is not `found` produced no inventory. `surface` holds the
333
+ * verified collision record when found and an empty collection otherwise.
334
+ * `unreachable` is true only when the inventory request produced no HTTP response.
328
335
  */
329
336
  export declare interface HostInventory {
330
337
  readonly lookup: Lookup;
331
338
  readonly digests: ReadonlyMap<string, string>;
332
339
  readonly duplicates: ReadonlySet<string>;
333
340
  readonly note: string;
341
+ readonly surface: readonly SurfaceCollision[];
342
+ readonly unreachable?: boolean;
334
343
  }
335
344
 
336
345
  /**
@@ -713,6 +722,17 @@ export declare function isPhysicalDirectory(path: string): boolean;
713
722
  */
714
723
  export declare function isPhysicalFile(path: string): boolean;
715
724
 
725
+ /**
726
+ * Narrows a value to the callable guide functions surface reflection requires.
727
+ *
728
+ * @example
729
+ * ```ts
730
+ * import { isSurfaceModule } from '@orkestrel/scaffold/server'
731
+ * isSurfaceModule({}) // false
732
+ * ```
733
+ */
734
+ export declare function isSurfaceModule(value: unknown): value is SurfaceModule;
735
+
716
736
  /**
717
737
  * Narrows a value to a per-request timeout in milliseconds.
718
738
  *
@@ -2011,6 +2031,44 @@ export declare class Materializer implements MaterializerInterface {
2011
2031
  */
2012
2032
  export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
2013
2033
 
2034
+ /**
2035
+ * Reads a checkout's combined guide and barrel claims under its manifest owner.
2036
+ *
2037
+ * @remarks
2038
+ * Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
2039
+ * src environment through @orkestrel/guide, loaded only when called, and reports each
2040
+ * name two or more environments export as a conflict.
2041
+ * Reads only .ts files and refuses barrel statements outside relative .js star exports.
2042
+ * A present unreadable guide refuses the candidate even when src exists.
2043
+ * `loader` selects the resolver used by the shared validated guide loader.
2044
+ * @throws Thrown when the manifest is unreadable, both claim sources are absent,
2045
+ * a source cannot be read, or @orkestrel/guide cannot be loaded.
2046
+ *
2047
+ * @example
2048
+ * ```ts
2049
+ * import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
2050
+ *
2051
+ * readSurfaceCandidate('.') // the working checkout's owner and combined names
2052
+ * ```
2053
+ */
2054
+ export declare function readSurfaceCandidate(root: string, loader?: SurfaceLoader): SurfaceCandidate;
2055
+
2056
+ /**
2057
+ * Reads each immediate package guide's bare names under its file owner.
2058
+ *
2059
+ * @param root - The directory containing the package guides; README.md is excluded.
2060
+ * @param loader - The module resolver used by the shared validated guide loader.
2061
+ * @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
2062
+ *
2063
+ * @example
2064
+ * ```ts
2065
+ * import { readSurfaceClaims } from '@orkestrel/scaffold/server'
2066
+ *
2067
+ * readSurfaceClaims('./guides') // owners and the names their guides claim
2068
+ * ```
2069
+ */
2070
+ export declare function readSurfaceClaims(root: string, loader?: SurfaceLoader): readonly SurfaceClaim[];
2071
+
2014
2072
  /**
2015
2073
  * Reads bare Surface names claimed by distinct package guides.
2016
2074
  *
@@ -2034,6 +2092,73 @@ export declare class Materializer implements MaterializerInterface {
2034
2092
  */
2035
2093
  export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
2036
2094
 
2095
+ /**
2096
+ * Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
2097
+ *
2098
+ * @param root - The checkout or data root holding the guide, or a verified host whose bytes
2099
+ * carry it at that destination.
2100
+ * @param owner - The unscoped package name the guide file is named for.
2101
+ * @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
2102
+ * @param loader - The module resolver used by the shared validated guide loader.
2103
+ * @returns The claim, or `undefined` when no file sits at the path or the host declares none.
2104
+ * @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
2105
+ * file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
2106
+ *
2107
+ * @example
2108
+ * ```ts
2109
+ * import { readSurfaceFile } from '@orkestrel/scaffold/server'
2110
+ *
2111
+ * readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
2112
+ * ```
2113
+ */
2114
+ export declare function readSurfaceFile(root: string | Host, owner: string, label: string, loader?: SurfaceLoader): SurfaceClaim | undefined;
2115
+
2116
+ /**
2117
+ * Reads one guide's claims and reports parser refusals with its owner and source.
2118
+ *
2119
+ * @param source - The source label or path to name in a refusal.
2120
+ * @throws Thrown with TARGET when the module is unusable or the guide parser refuses the guide
2121
+ * with an error its `isGuideError` guard accepts; every other parser error propagates unchanged.
2122
+ * @example
2123
+ * ```ts
2124
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
2125
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
2126
+ * ```
2127
+ */
2128
+ export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
2129
+
2130
+ /**
2131
+ * Loads and validates the guide functions required by surface reflection.
2132
+ *
2133
+ * @param loader - The module resolver. Default: Node resolution from this module.
2134
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
2135
+ * @example
2136
+ * ```ts
2137
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
2138
+ * readSurfaceModule().createGuide('# Sample').surface() // []
2139
+ * ```
2140
+ */
2141
+ export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
2142
+
2143
+ /**
2144
+ * Reads a data root's verified collision record.
2145
+ *
2146
+ * @param root - The data root holding `manifest.json` or `host.json`.
2147
+ * @remarks
2148
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
2149
+ * Reads only local files and never contacts upstream or writes an inventory.
2150
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
2151
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
2152
+ *
2153
+ * @example
2154
+ * ```ts
2155
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
2156
+ *
2157
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
2158
+ * ```
2159
+ */
2160
+ export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
2161
+
2037
2162
  /**
2038
2163
  * Matches the Windows device names that stay reserved even when an extension follows.
2039
2164
  *
@@ -2084,6 +2209,17 @@ export declare class Materializer implements MaterializerInterface {
2084
2209
  */
2085
2210
  export declare function resolveContainedPath(root: string, path: string): string | undefined;
2086
2211
 
2212
+ /**
2213
+ * Resolves the bundled host root from the executing module's location.
2214
+ *
2215
+ * @example
2216
+ * ```ts
2217
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
2218
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
2219
+ * ```
2220
+ */
2221
+ export declare function resolveHostRoot(): string;
2222
+
2087
2223
  /**
2088
2224
  * Resolves a path through the real filesystem, keeping the part that does not exist yet.
2089
2225
  *
@@ -2278,10 +2414,38 @@ export declare class Materializer implements MaterializerInterface {
2278
2414
  */
2279
2415
  export declare function stageInventory(checkout: string, path?: string): HostManifest;
2280
2416
 
2281
- /** Represents a Surface name claimed by distinct package guides. */
2282
- export declare interface SurfaceCollision {
2283
- readonly name: string;
2284
- readonly owners: readonly string[];
2417
+ /** Loads a module by specifier for validated surface reflection. */
2418
+ export declare type SurfaceLoader = (specifier: string) => unknown;
2419
+
2420
+ /**
2421
+ * Describes the guide module functions required by surface reflection.
2422
+ *
2423
+ * @remarks
2424
+ * Declares only the members surface reflection calls, so a consumer of these declarations needs
2425
+ * no copy of `@orkestrel/guide`.
2426
+ */
2427
+ export declare interface SurfaceModule {
2428
+ readonly createGuide: (text: string) => {
2429
+ readonly surface: () => ReadonlyArray<{
2430
+ readonly name: string;
2431
+ }>;
2432
+ };
2433
+ readonly createSource: (options: {
2434
+ readonly files: Readonly<Record<string, string>>;
2435
+ readonly module: string;
2436
+ }) => {
2437
+ readonly surface: () => ReadonlyArray<{
2438
+ readonly name: string;
2439
+ }>;
2440
+ };
2441
+ readonly extractSourceLines: (text: string) => ReadonlyArray<{
2442
+ readonly code: string;
2443
+ readonly source: string;
2444
+ }>;
2445
+ readonly isGuideError: (value: unknown) => value is Error & {
2446
+ readonly code: string;
2447
+ readonly message: string;
2448
+ };
2285
2449
  }
2286
2450
 
2287
2451
  /**
@@ -2291,11 +2455,13 @@ export declare class Materializer implements MaterializerInterface {
2291
2455
  * `content` carries the body only when `lookup` is `found`; otherwise it is
2292
2456
  * empty and `note` states what happened. A read that is not `found` is an answer
2293
2457
  * rather than a throw, which is what lets one dead row sit beside live ones.
2458
+ * `unreachable` is true only when the request produced no HTTP response.
2294
2459
  */
2295
2460
  export declare interface TextReadResult {
2296
2461
  readonly lookup: Lookup;
2297
2462
  readonly content: string;
2298
2463
  readonly note: string;
2464
+ readonly unreachable?: boolean;
2299
2465
  }
2300
2466
 
2301
2467
  /** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
@@ -2479,7 +2645,9 @@ export declare class Materializer implements MaterializerInterface {
2479
2645
  * unreadable list would otherwise be written into a target's catalog table as
2480
2646
  * a fleet with no packages in it. A package whose own version lookup then
2481
2647
  * fails still keeps its row, carrying the cause instead of a version, because
2482
- * the list already proved the package is published.
2648
+ * the list already proved the package is published. The `FETCH` failure's
2649
+ * context carries `unreachable: true` only when the list request produced no
2650
+ * HTTP response.
2483
2651
  *
2484
2652
  * @example
2485
2653
  * ```ts
@@ -2491,6 +2659,23 @@ export declare class Materializer implements MaterializerInterface {
2491
2659
  * ```
2492
2660
  */
2493
2661
  catalog(): Promise<readonly CatalogEntry[]>;
2662
+ /**
2663
+ * Reads the verified upstream inventory and its collision record.
2664
+ *
2665
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
2666
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
2667
+ * carrying `unreachable: true` only when the request produced no HTTP response.
2668
+ * @throws Thrown with DESTROYED when the reader has been torn down.
2669
+ * @example
2670
+ * ```ts
2671
+ * import { Upstream } from '@orkestrel/scaffold/server'
2672
+ * const upstream = new Upstream()
2673
+ * const inventory = await upstream.inventory()
2674
+ * inventory.surface // the verified record when lookup is found
2675
+ * upstream.destroy()
2676
+ * ```
2677
+ */
2678
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2494
2679
  /**
2495
2680
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2496
2681
  *
@@ -2575,6 +2760,8 @@ export declare class Materializer implements MaterializerInterface {
2575
2760
  * @returns One row per published package, sorted by name.
2576
2761
  */
2577
2762
  catalog(): Promise<readonly CatalogEntry[]>;
2763
+ /** Reads the verified upstream inventory and its collision record. */
2764
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2578
2765
  /**
2579
2766
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2580
2767
  *
@@ -13,6 +13,9 @@ import type { Mirror } from '@orkestrel/scaffold';
13
13
  import type { Plan } from '@orkestrel/scaffold';
14
14
  import type { Release } from '@orkestrel/scaffold';
15
15
  import type { Snapshot } from '@orkestrel/scaffold';
16
+ import type { SurfaceCandidate } from '@orkestrel/scaffold';
17
+ import type { SurfaceClaim } from '@orkestrel/scaffold';
18
+ import type { SurfaceCollision } from '@orkestrel/scaffold';
16
19
 
17
20
  /**
18
21
  * Matches the Git branch syntax the repository endpoint accepts.
@@ -33,11 +36,13 @@ export declare const BRANCH_PATTERN: RegExp;
33
36
  * `found`; otherwise it is empty and `note` states what happened. Bytes rather
34
37
  * than text, because a vendored file is compared by digest and a decode would
35
38
  * change what is hashed.
39
+ * `unreachable` is true only when the request produced no HTTP response.
36
40
  */
37
41
  export declare interface BytesReadResult {
38
42
  readonly lookup: Lookup;
39
43
  readonly hex: string;
40
44
  readonly note: string;
45
+ readonly unreachable?: boolean;
41
46
  }
42
47
 
43
48
  /**
@@ -324,13 +329,17 @@ export declare interface Host {
324
329
  * call inherits it when it is not `found`. `digests` maps a target-relative
325
330
  * destination to the exact bytes the inventory declares for it, `duplicates`
326
331
  * names every destination the inventory claims more than once, and `note` states
327
- * why a lookup that is not `found` produced no inventory.
332
+ * why a lookup that is not `found` produced no inventory. `surface` holds the
333
+ * verified collision record when found and an empty collection otherwise.
334
+ * `unreachable` is true only when the inventory request produced no HTTP response.
328
335
  */
329
336
  export declare interface HostInventory {
330
337
  readonly lookup: Lookup;
331
338
  readonly digests: ReadonlyMap<string, string>;
332
339
  readonly duplicates: ReadonlySet<string>;
333
340
  readonly note: string;
341
+ readonly surface: readonly SurfaceCollision[];
342
+ readonly unreachable?: boolean;
334
343
  }
335
344
 
336
345
  /**
@@ -713,6 +722,17 @@ export declare function isPhysicalDirectory(path: string): boolean;
713
722
  */
714
723
  export declare function isPhysicalFile(path: string): boolean;
715
724
 
725
+ /**
726
+ * Narrows a value to the callable guide functions surface reflection requires.
727
+ *
728
+ * @example
729
+ * ```ts
730
+ * import { isSurfaceModule } from '@orkestrel/scaffold/server'
731
+ * isSurfaceModule({}) // false
732
+ * ```
733
+ */
734
+ export declare function isSurfaceModule(value: unknown): value is SurfaceModule;
735
+
716
736
  /**
717
737
  * Narrows a value to a per-request timeout in milliseconds.
718
738
  *
@@ -2011,6 +2031,44 @@ export declare class Materializer implements MaterializerInterface {
2011
2031
  */
2012
2032
  export declare function readSurfaceBaseline(root: string, name?: string): readonly SurfaceCollision[] | undefined;
2013
2033
 
2034
+ /**
2035
+ * Reads a checkout's combined guide and barrel claims under its manifest owner.
2036
+ *
2037
+ * @remarks
2038
+ * Removes the @orkestrel/ scope from the manifest name. Reflects each immediate
2039
+ * src environment through @orkestrel/guide, loaded only when called, and reports each
2040
+ * name two or more environments export as a conflict.
2041
+ * Reads only .ts files and refuses barrel statements outside relative .js star exports.
2042
+ * A present unreadable guide refuses the candidate even when src exists.
2043
+ * `loader` selects the resolver used by the shared validated guide loader.
2044
+ * @throws Thrown when the manifest is unreadable, both claim sources are absent,
2045
+ * a source cannot be read, or @orkestrel/guide cannot be loaded.
2046
+ *
2047
+ * @example
2048
+ * ```ts
2049
+ * import { readSurfaceCandidate } from '@orkestrel/scaffold/server'
2050
+ *
2051
+ * readSurfaceCandidate('.') // the working checkout's owner and combined names
2052
+ * ```
2053
+ */
2054
+ export declare function readSurfaceCandidate(root: string, loader?: SurfaceLoader): SurfaceCandidate;
2055
+
2056
+ /**
2057
+ * Reads each immediate package guide's bare names under its file owner.
2058
+ *
2059
+ * @param root - The directory containing the package guides; README.md is excluded.
2060
+ * @param loader - The module resolver used by the shared validated guide loader.
2061
+ * @throws Thrown when the directory, a guide, or the lazily loaded @orkestrel/guide module is unreadable.
2062
+ *
2063
+ * @example
2064
+ * ```ts
2065
+ * import { readSurfaceClaims } from '@orkestrel/scaffold/server'
2066
+ *
2067
+ * readSurfaceClaims('./guides') // owners and the names their guides claim
2068
+ * ```
2069
+ */
2070
+ export declare function readSurfaceClaims(root: string, loader?: SurfaceLoader): readonly SurfaceClaim[];
2071
+
2014
2072
  /**
2015
2073
  * Reads bare Surface names claimed by distinct package guides.
2016
2074
  *
@@ -2034,6 +2092,73 @@ export declare class Materializer implements MaterializerInterface {
2034
2092
  */
2035
2093
  export declare function readSurfaceCollisions(root: string): ReadonlyMap<string, readonly string[]>;
2036
2094
 
2095
+ /**
2096
+ * Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim.
2097
+ *
2098
+ * @param root - The checkout or data root holding the guide, or a verified host whose bytes
2099
+ * carry it at that destination.
2100
+ * @param owner - The unscoped package name the guide file is named for.
2101
+ * @param label - The source word a refusal names beside the path, such as `candidate` or `floor`.
2102
+ * @param loader - The module resolver used by the shared validated guide loader.
2103
+ * @returns The claim, or `undefined` when no file sits at the path or the host declares none.
2104
+ * @throws Thrown with TARGET when the file or the declared bytes are not UTF-8 text, when the
2105
+ * file exceeds the artifact bound, or when the guide module or its parser refuses the guide.
2106
+ *
2107
+ * @example
2108
+ * ```ts
2109
+ * import { readSurfaceFile } from '@orkestrel/scaffold/server'
2110
+ *
2111
+ * readSurfaceFile('.', 'scaffold', 'candidate')?.names // the names the checkout's guide claims
2112
+ * ```
2113
+ */
2114
+ export declare function readSurfaceFile(root: string | Host, owner: string, label: string, loader?: SurfaceLoader): SurfaceClaim | undefined;
2115
+
2116
+ /**
2117
+ * Reads one guide's claims and reports parser refusals with its owner and source.
2118
+ *
2119
+ * @param source - The source label or path to name in a refusal.
2120
+ * @throws Thrown with TARGET when the module is unusable or the guide parser refuses the guide
2121
+ * with an error its `isGuideError` guard accepts; every other parser error propagates unchanged.
2122
+ * @example
2123
+ * ```ts
2124
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
2125
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
2126
+ * ```
2127
+ */
2128
+ export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
2129
+
2130
+ /**
2131
+ * Loads and validates the guide functions required by surface reflection.
2132
+ *
2133
+ * @param loader - The module resolver. Default: Node resolution from this module.
2134
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
2135
+ * @example
2136
+ * ```ts
2137
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
2138
+ * readSurfaceModule().createGuide('# Sample').surface() // []
2139
+ * ```
2140
+ */
2141
+ export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
2142
+
2143
+ /**
2144
+ * Reads a data root's verified collision record.
2145
+ *
2146
+ * @param root - The data root holding `manifest.json` or `host.json`.
2147
+ * @remarks
2148
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
2149
+ * Reads only local files and never contacts upstream or writes an inventory.
2150
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
2151
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
2152
+ *
2153
+ * @example
2154
+ * ```ts
2155
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
2156
+ *
2157
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
2158
+ * ```
2159
+ */
2160
+ export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
2161
+
2037
2162
  /**
2038
2163
  * Matches the Windows device names that stay reserved even when an extension follows.
2039
2164
  *
@@ -2084,6 +2209,17 @@ export declare class Materializer implements MaterializerInterface {
2084
2209
  */
2085
2210
  export declare function resolveContainedPath(root: string, path: string): string | undefined;
2086
2211
 
2212
+ /**
2213
+ * Resolves the bundled host root from the executing module's location.
2214
+ *
2215
+ * @example
2216
+ * ```ts
2217
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
2218
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
2219
+ * ```
2220
+ */
2221
+ export declare function resolveHostRoot(): string;
2222
+
2087
2223
  /**
2088
2224
  * Resolves a path through the real filesystem, keeping the part that does not exist yet.
2089
2225
  *
@@ -2278,10 +2414,38 @@ export declare class Materializer implements MaterializerInterface {
2278
2414
  */
2279
2415
  export declare function stageInventory(checkout: string, path?: string): HostManifest;
2280
2416
 
2281
- /** Represents a Surface name claimed by distinct package guides. */
2282
- export declare interface SurfaceCollision {
2283
- readonly name: string;
2284
- readonly owners: readonly string[];
2417
+ /** Loads a module by specifier for validated surface reflection. */
2418
+ export declare type SurfaceLoader = (specifier: string) => unknown;
2419
+
2420
+ /**
2421
+ * Describes the guide module functions required by surface reflection.
2422
+ *
2423
+ * @remarks
2424
+ * Declares only the members surface reflection calls, so a consumer of these declarations needs
2425
+ * no copy of `@orkestrel/guide`.
2426
+ */
2427
+ export declare interface SurfaceModule {
2428
+ readonly createGuide: (text: string) => {
2429
+ readonly surface: () => ReadonlyArray<{
2430
+ readonly name: string;
2431
+ }>;
2432
+ };
2433
+ readonly createSource: (options: {
2434
+ readonly files: Readonly<Record<string, string>>;
2435
+ readonly module: string;
2436
+ }) => {
2437
+ readonly surface: () => ReadonlyArray<{
2438
+ readonly name: string;
2439
+ }>;
2440
+ };
2441
+ readonly extractSourceLines: (text: string) => ReadonlyArray<{
2442
+ readonly code: string;
2443
+ readonly source: string;
2444
+ }>;
2445
+ readonly isGuideError: (value: unknown) => value is Error & {
2446
+ readonly code: string;
2447
+ readonly message: string;
2448
+ };
2285
2449
  }
2286
2450
 
2287
2451
  /**
@@ -2291,11 +2455,13 @@ export declare class Materializer implements MaterializerInterface {
2291
2455
  * `content` carries the body only when `lookup` is `found`; otherwise it is
2292
2456
  * empty and `note` states what happened. A read that is not `found` is an answer
2293
2457
  * rather than a throw, which is what lets one dead row sit beside live ones.
2458
+ * `unreachable` is true only when the request produced no HTTP response.
2294
2459
  */
2295
2460
  export declare interface TextReadResult {
2296
2461
  readonly lookup: Lookup;
2297
2462
  readonly content: string;
2298
2463
  readonly note: string;
2464
+ readonly unreachable?: boolean;
2299
2465
  }
2300
2466
 
2301
2467
  /** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
@@ -2479,7 +2645,9 @@ export declare class Materializer implements MaterializerInterface {
2479
2645
  * unreadable list would otherwise be written into a target's catalog table as
2480
2646
  * a fleet with no packages in it. A package whose own version lookup then
2481
2647
  * fails still keeps its row, carrying the cause instead of a version, because
2482
- * the list already proved the package is published.
2648
+ * the list already proved the package is published. The `FETCH` failure's
2649
+ * context carries `unreachable: true` only when the list request produced no
2650
+ * HTTP response.
2483
2651
  *
2484
2652
  * @example
2485
2653
  * ```ts
@@ -2491,6 +2659,23 @@ export declare class Materializer implements MaterializerInterface {
2491
2659
  * ```
2492
2660
  */
2493
2661
  catalog(): Promise<readonly CatalogEntry[]>;
2662
+ /**
2663
+ * Reads the verified upstream inventory and its collision record.
2664
+ *
2665
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
2666
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
2667
+ * carrying `unreachable: true` only when the request produced no HTTP response.
2668
+ * @throws Thrown with DESTROYED when the reader has been torn down.
2669
+ * @example
2670
+ * ```ts
2671
+ * import { Upstream } from '@orkestrel/scaffold/server'
2672
+ * const upstream = new Upstream()
2673
+ * const inventory = await upstream.inventory()
2674
+ * inventory.surface // the verified record when lookup is found
2675
+ * upstream.destroy()
2676
+ * ```
2677
+ */
2678
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2494
2679
  /**
2495
2680
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2496
2681
  *
@@ -2575,6 +2760,8 @@ export declare class Materializer implements MaterializerInterface {
2575
2760
  * @returns One row per published package, sorted by name.
2576
2761
  */
2577
2762
  catalog(): Promise<readonly CatalogEntry[]>;
2763
+ /** Reads the verified upstream inventory and its collision record. */
2764
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2578
2765
  /**
2579
2766
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2580
2767
  *