@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
@@ -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,72 @@ 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 or the guide parser refuses the reading.
2121
+ * @example
2122
+ * ```ts
2123
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
2124
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
2125
+ * ```
2126
+ */
2127
+ export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
2128
+
2129
+ /**
2130
+ * Loads and validates the guide functions required by surface reflection.
2131
+ *
2132
+ * @param loader - The module resolver. Default: Node resolution from this module.
2133
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
2134
+ * @example
2135
+ * ```ts
2136
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
2137
+ * readSurfaceModule().createGuide('# Sample').surface() // []
2138
+ * ```
2139
+ */
2140
+ export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
2141
+
2142
+ /**
2143
+ * Reads a data root's verified collision record.
2144
+ *
2145
+ * @param root - The data root holding `manifest.json` or `host.json`.
2146
+ * @remarks
2147
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
2148
+ * Reads only local files and never contacts upstream or writes an inventory.
2149
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
2150
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
2151
+ *
2152
+ * @example
2153
+ * ```ts
2154
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
2155
+ *
2156
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
2157
+ * ```
2158
+ */
2159
+ export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
2160
+
2037
2161
  /**
2038
2162
  * Matches the Windows device names that stay reserved even when an extension follows.
2039
2163
  *
@@ -2084,6 +2208,17 @@ export declare class Materializer implements MaterializerInterface {
2084
2208
  */
2085
2209
  export declare function resolveContainedPath(root: string, path: string): string | undefined;
2086
2210
 
2211
+ /**
2212
+ * Resolves the bundled host root from the executing module's location.
2213
+ *
2214
+ * @example
2215
+ * ```ts
2216
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
2217
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
2218
+ * ```
2219
+ */
2220
+ export declare function resolveHostRoot(): string;
2221
+
2087
2222
  /**
2088
2223
  * Resolves a path through the real filesystem, keeping the part that does not exist yet.
2089
2224
  *
@@ -2278,10 +2413,34 @@ export declare class Materializer implements MaterializerInterface {
2278
2413
  */
2279
2414
  export declare function stageInventory(checkout: string, path?: string): HostManifest;
2280
2415
 
2281
- /** Represents a Surface name claimed by distinct package guides. */
2282
- export declare interface SurfaceCollision {
2283
- readonly name: string;
2284
- readonly owners: readonly string[];
2416
+ /** Loads a module by specifier for validated surface reflection. */
2417
+ export declare type SurfaceLoader = (specifier: string) => unknown;
2418
+
2419
+ /**
2420
+ * Describes the guide module functions required by surface reflection.
2421
+ *
2422
+ * @remarks
2423
+ * Declares only the members surface reflection calls, so a consumer of these declarations needs
2424
+ * no copy of `@orkestrel/guide`.
2425
+ */
2426
+ export declare interface SurfaceModule {
2427
+ readonly createGuide: (text: string) => {
2428
+ readonly surface: () => ReadonlyArray<{
2429
+ readonly name: string;
2430
+ }>;
2431
+ };
2432
+ readonly createSource: (options: {
2433
+ readonly files: Readonly<Record<string, string>>;
2434
+ readonly module: string;
2435
+ }) => {
2436
+ readonly surface: () => ReadonlyArray<{
2437
+ readonly name: string;
2438
+ }>;
2439
+ };
2440
+ readonly extractSourceLines: (text: string) => ReadonlyArray<{
2441
+ readonly code: string;
2442
+ readonly source: string;
2443
+ }>;
2285
2444
  }
2286
2445
 
2287
2446
  /**
@@ -2291,11 +2450,13 @@ export declare class Materializer implements MaterializerInterface {
2291
2450
  * `content` carries the body only when `lookup` is `found`; otherwise it is
2292
2451
  * empty and `note` states what happened. A read that is not `found` is an answer
2293
2452
  * rather than a throw, which is what lets one dead row sit beside live ones.
2453
+ * `unreachable` is true only when the request produced no HTTP response.
2294
2454
  */
2295
2455
  export declare interface TextReadResult {
2296
2456
  readonly lookup: Lookup;
2297
2457
  readonly content: string;
2298
2458
  readonly note: string;
2459
+ readonly unreachable?: boolean;
2299
2460
  }
2300
2461
 
2301
2462
  /** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
@@ -2479,7 +2640,9 @@ export declare class Materializer implements MaterializerInterface {
2479
2640
  * unreadable list would otherwise be written into a target's catalog table as
2480
2641
  * a fleet with no packages in it. A package whose own version lookup then
2481
2642
  * fails still keeps its row, carrying the cause instead of a version, because
2482
- * the list already proved the package is published.
2643
+ * the list already proved the package is published. The `FETCH` failure's
2644
+ * context carries `unreachable: true` only when the list request produced no
2645
+ * HTTP response.
2483
2646
  *
2484
2647
  * @example
2485
2648
  * ```ts
@@ -2491,6 +2654,23 @@ export declare class Materializer implements MaterializerInterface {
2491
2654
  * ```
2492
2655
  */
2493
2656
  catalog(): Promise<readonly CatalogEntry[]>;
2657
+ /**
2658
+ * Reads the verified upstream inventory and its collision record.
2659
+ *
2660
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
2661
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
2662
+ * carrying `unreachable: true` only when the request produced no HTTP response.
2663
+ * @throws Thrown with DESTROYED when the reader has been torn down.
2664
+ * @example
2665
+ * ```ts
2666
+ * import { Upstream } from '@orkestrel/scaffold/server'
2667
+ * const upstream = new Upstream()
2668
+ * const inventory = await upstream.inventory()
2669
+ * inventory.surface // the verified record when lookup is found
2670
+ * upstream.destroy()
2671
+ * ```
2672
+ */
2673
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2494
2674
  /**
2495
2675
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2496
2676
  *
@@ -2575,6 +2755,8 @@ export declare class Materializer implements MaterializerInterface {
2575
2755
  * @returns One row per published package, sorted by name.
2576
2756
  */
2577
2757
  catalog(): Promise<readonly CatalogEntry[]>;
2758
+ /** Reads the verified upstream inventory and its collision record. */
2759
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2578
2760
  /**
2579
2761
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2580
2762
  *
@@ -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,72 @@ 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 or the guide parser refuses the reading.
2121
+ * @example
2122
+ * ```ts
2123
+ * import { readSurfaceGuide } from '@orkestrel/scaffold/server'
2124
+ * readSurfaceGuide('# Sample', 'sample', 'live guides/sample.md') // { owner: 'sample', names: [] }
2125
+ * ```
2126
+ */
2127
+ export declare function readSurfaceGuide(text: string, owner: string, source: string, loader?: SurfaceLoader): SurfaceClaim;
2128
+
2129
+ /**
2130
+ * Loads and validates the guide functions required by surface reflection.
2131
+ *
2132
+ * @param loader - The module resolver. Default: Node resolution from this module.
2133
+ * @throws Thrown with TARGET when the module is absent or lacks a required function.
2134
+ * @example
2135
+ * ```ts
2136
+ * import { readSurfaceModule } from '@orkestrel/scaffold/server'
2137
+ * readSurfaceModule().createGuide('# Sample').surface() // []
2138
+ * ```
2139
+ */
2140
+ export declare function readSurfaceModule(loader?: SurfaceLoader): SurfaceModule;
2141
+
2142
+ /**
2143
+ * Reads a data root's verified collision record.
2144
+ *
2145
+ * @param root - The data root holding `manifest.json` or `host.json`.
2146
+ * @remarks
2147
+ * Reads `manifest.json` first, then `host.json` when no built manifest exists.
2148
+ * Reads only local files and never contacts upstream or writes an inventory.
2149
+ * @throws Thrown with TARGET when neither inventory exists, and as `readHostManifest`
2150
+ * throws when one is unreadable, malformed, or inconsistent with its digest.
2151
+ *
2152
+ * @example
2153
+ * ```ts
2154
+ * import { readSurfaceRecord, resolveHostRoot } from '@orkestrel/scaffold/server'
2155
+ *
2156
+ * readSurfaceRecord(resolveHostRoot()) // the bundled collision record
2157
+ * ```
2158
+ */
2159
+ export declare function readSurfaceRecord(root: string): readonly SurfaceCollision[];
2160
+
2037
2161
  /**
2038
2162
  * Matches the Windows device names that stay reserved even when an extension follows.
2039
2163
  *
@@ -2084,6 +2208,17 @@ export declare class Materializer implements MaterializerInterface {
2084
2208
  */
2085
2209
  export declare function resolveContainedPath(root: string, path: string): string | undefined;
2086
2210
 
2211
+ /**
2212
+ * Resolves the bundled host root from the executing module's location.
2213
+ *
2214
+ * @example
2215
+ * ```ts
2216
+ * import { resolveHostRoot } from '@orkestrel/scaffold/server'
2217
+ * resolveHostRoot() // the checkout in source, or the installed dist/host directory
2218
+ * ```
2219
+ */
2220
+ export declare function resolveHostRoot(): string;
2221
+
2087
2222
  /**
2088
2223
  * Resolves a path through the real filesystem, keeping the part that does not exist yet.
2089
2224
  *
@@ -2278,10 +2413,34 @@ export declare class Materializer implements MaterializerInterface {
2278
2413
  */
2279
2414
  export declare function stageInventory(checkout: string, path?: string): HostManifest;
2280
2415
 
2281
- /** Represents a Surface name claimed by distinct package guides. */
2282
- export declare interface SurfaceCollision {
2283
- readonly name: string;
2284
- readonly owners: readonly string[];
2416
+ /** Loads a module by specifier for validated surface reflection. */
2417
+ export declare type SurfaceLoader = (specifier: string) => unknown;
2418
+
2419
+ /**
2420
+ * Describes the guide module functions required by surface reflection.
2421
+ *
2422
+ * @remarks
2423
+ * Declares only the members surface reflection calls, so a consumer of these declarations needs
2424
+ * no copy of `@orkestrel/guide`.
2425
+ */
2426
+ export declare interface SurfaceModule {
2427
+ readonly createGuide: (text: string) => {
2428
+ readonly surface: () => ReadonlyArray<{
2429
+ readonly name: string;
2430
+ }>;
2431
+ };
2432
+ readonly createSource: (options: {
2433
+ readonly files: Readonly<Record<string, string>>;
2434
+ readonly module: string;
2435
+ }) => {
2436
+ readonly surface: () => ReadonlyArray<{
2437
+ readonly name: string;
2438
+ }>;
2439
+ };
2440
+ readonly extractSourceLines: (text: string) => ReadonlyArray<{
2441
+ readonly code: string;
2442
+ readonly source: string;
2443
+ }>;
2285
2444
  }
2286
2445
 
2287
2446
  /**
@@ -2291,11 +2450,13 @@ export declare class Materializer implements MaterializerInterface {
2291
2450
  * `content` carries the body only when `lookup` is `found`; otherwise it is
2292
2451
  * empty and `note` states what happened. A read that is not `found` is an answer
2293
2452
  * rather than a throw, which is what lets one dead row sit beside live ones.
2453
+ * `unreachable` is true only when the request produced no HTTP response.
2294
2454
  */
2295
2455
  export declare interface TextReadResult {
2296
2456
  readonly lookup: Lookup;
2297
2457
  readonly content: string;
2298
2458
  readonly note: string;
2459
+ readonly unreachable?: boolean;
2299
2460
  }
2300
2461
 
2301
2462
  /** Holds the note a release carries when its packument names no readable version under the `latest` tag. */
@@ -2479,7 +2640,9 @@ export declare class Materializer implements MaterializerInterface {
2479
2640
  * unreadable list would otherwise be written into a target's catalog table as
2480
2641
  * a fleet with no packages in it. A package whose own version lookup then
2481
2642
  * fails still keeps its row, carrying the cause instead of a version, because
2482
- * the list already proved the package is published.
2643
+ * the list already proved the package is published. The `FETCH` failure's
2644
+ * context carries `unreachable: true` only when the list request produced no
2645
+ * HTTP response.
2483
2646
  *
2484
2647
  * @example
2485
2648
  * ```ts
@@ -2491,6 +2654,23 @@ export declare class Materializer implements MaterializerInterface {
2491
2654
  * ```
2492
2655
  */
2493
2656
  catalog(): Promise<readonly CatalogEntry[]>;
2657
+ /**
2658
+ * Reads the verified upstream inventory and its collision record.
2659
+ *
2660
+ * @param allowance - A shared call allowance; omitted calls open their own budget.
2661
+ * @returns A found inventory with its surface, or an unfound verdict with empty collections,
2662
+ * carrying `unreachable: true` only when the request produced no HTTP response.
2663
+ * @throws Thrown with DESTROYED when the reader has been torn down.
2664
+ * @example
2665
+ * ```ts
2666
+ * import { Upstream } from '@orkestrel/scaffold/server'
2667
+ * const upstream = new Upstream()
2668
+ * const inventory = await upstream.inventory()
2669
+ * inventory.surface // the verified record when lookup is found
2670
+ * upstream.destroy()
2671
+ * ```
2672
+ */
2673
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2494
2674
  /**
2495
2675
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2496
2676
  *
@@ -2575,6 +2755,8 @@ export declare class Materializer implements MaterializerInterface {
2575
2755
  * @returns One row per published package, sorted by name.
2576
2756
  */
2577
2757
  catalog(): Promise<readonly CatalogEntry[]>;
2758
+ /** Reads the verified upstream inventory and its collision record. */
2759
+ inventory(allowance?: ReadAllowanceInterface): Promise<HostInventory>;
2578
2760
  /**
2579
2761
  * Tears the reader down, aborting every request in flight. Teardown is idempotent.
2580
2762
  *