@orkestrel/scaffold 0.0.119 → 0.0.121

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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -55,30 +55,30 @@ Exported from `@orkestrel/scaffold`, and reachable from
55
55
 
56
56
  #### Types
57
57
 
58
- | Name | Kind | Signature | Summary |
59
- | ------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
60
- | `Artifact` | type | `HostArtifact \| HydratedArtifact \| ContentArtifact` | Represents one file in a plan, discriminated by how its content is produced and what scaffold claims of it. |
61
- | `Axis` | type | `'src' \| 'app'` | Names the workspace axis an extension occupies. |
62
- | `BuildFormat` | type | `'es' \| 'cjs'` | Names one module format a published library environment builds. |
63
- | `CatalogEntry` | type | `{ readonly name: string; readonly lookup: 'found'; readonly version: string; readonly dependencies: readonly Dependency[]; readonly peers: readonly Dependency[]; readonly note?: never; } \| { readonly name: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly version?: never; readonly dependencies?: never; readonly peers?: never; }` | Represents one package row of the fleet catalog. |
64
- | `CompileStage` | type | `'draft' \| 'gate' \| 'pin'` | Names the compile phases, in the order they run. |
65
- | `CompilerEventMap` | type | `{ readonly compile: readonly [result: CompileResult]; readonly audit: readonly [audit: Audit]; readonly block: readonly [questions: readonly Question[]]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the compiler's observation channel. |
66
- | `HostFile` | type | `{ readonly path: string; readonly lookup: 'found'; readonly hex: string; readonly observed?: string; readonly note?: never; } \| { readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly hex?: never; }` | Represents one vendored file read from the repository, beside the target bytes it answers for. |
67
- | `Drift` | type | `'aligned' \| 'stale' \| 'missing' \| 'foreign'` | Names how one target path compares to the artifact planned for it. |
68
- | `Environment` | type | `'core' \| 'browser' \| 'server'` | Names one environment a generated workspace selects on its `src` or `app` axis. |
69
- | `Extension` | type | `BrowserExtension \| StylesExtension` | Represents an extension discriminated by its surface. |
70
- | `Finding` | type | `{ readonly path: string; readonly group: Group; readonly ownership: Ownership; readonly drift: 'stale'; readonly observed: string; } \| { readonly path: string; readonly group: Group; readonly ownership?: never; readonly drift: 'foreign'; readonly observed: string; } \| { readonly path: string; readonly group: Group; readonly ownership: Ownership; readonly drift: 'missing'; readonly observed?: never; } \| { readonly path: string; readonly group: Group; readonly ownership: Ownership; readonly drift: 'aligned'; readonly observed?: string; }` | Represents one drift verdict against a target path. |
71
- | `Framework` | type | `'vue'` | Names a supported browser framework. |
72
- | `Group` | type | `'manifest' \| 'configs' \| 'source' \| 'tests' \| 'guides' \| 'docs' \| 'orchestration'` | Names the artifact group a plan selects over. |
73
- | `Lookup` | type | `'found' \| 'missing' \| 'unmatched' \| 'failed'` | Names how an upstream lookup resolved: found, missing, unmatched, or failed. |
74
- | `Mirror` | type | `{ readonly name: string; readonly path: string; readonly lookup: 'found'; readonly content: string; readonly observed?: string; readonly note?: never; } \| { readonly name: string; readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly content?: never; }` | Represents one dependency guide fetched from upstream, beside the local mirror it answers for. |
75
- | `Origin` | type | `'host' \| 'template' \| 'computed'` | Names how an artifact's content is produced. |
76
- | `Ownership` | type | `'content' \| 'presence' \| 'birth'` | Names what scaffold claims at an artifact's path. |
77
- | `Release` | type | `{ readonly name: string; readonly range: string; readonly lookup: 'found'; readonly latest: string; readonly major?: number; readonly note?: never; } \| { readonly name: string; readonly range: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly major?: number; readonly latest?: never; }` | Represents one declared dependency range measured against a registry release. |
78
- | `ScaffoldErrorCode` | type | `'INVALID' \| 'BLOCKED' \| 'DESTROYED' \| 'TARGET' \| 'WRITE' \| 'FETCH'` | Names the coded reasons a scaffold error is raised. |
79
- | `SetupRuntime` | type | `'node' \| 'browser'` | Names the runtime a root setup proof requires. |
80
- | `Snapshot` | type | `Readonly<Record<string, string>>` | Holds exact lowercase hexadecimal target bytes keyed by artifact-relative path. |
81
- | `Surface` | type | `'browser' \| 'styles'` | Names the surface an extension extends. |
58
+ | Name | Kind | Signature | Summary |
59
+ | ------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
60
+ | `Artifact` | type | `HostArtifact \| HydratedArtifact \| ContentArtifact` | Represents one file in a plan, discriminated by how its content is produced and what scaffold claims of it. |
61
+ | `ArtifactDrift` | type | `'aligned' \| 'stale' \| 'missing' \| 'foreign'` | Names how one target path compares to the artifact planned for it. |
62
+ | `ArtifactFinding` | type | `{ readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'stale'; readonly observed: string; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership?: never; readonly drift: 'foreign'; readonly observed: string; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'missing'; readonly observed?: never; } \| { readonly path: string; readonly group: ArtifactGroup; readonly ownership: Ownership; readonly drift: 'aligned'; readonly observed?: string; }` | Represents one drift verdict against a target path. |
63
+ | `ArtifactGroup` | type | `'manifest' \| 'configs' \| 'source' \| 'tests' \| 'guides' \| 'docs' \| 'orchestration'` | Names the artifact group a plan selects over. |
64
+ | `Axis` | type | `'src' \| 'app'` | Names the workspace axis an extension occupies. |
65
+ | `BuildFormat` | type | `'es' \| 'cjs'` | Names one module format a published library environment builds. |
66
+ | `CatalogEntry` | type | `{ readonly name: string; readonly lookup: 'found'; readonly version: string; readonly dependencies: readonly Dependency[]; readonly peers: readonly Dependency[]; readonly note?: never; } \| { readonly name: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly version?: never; readonly dependencies?: never; readonly peers?: never; }` | Represents one package row of the fleet catalog. |
67
+ | `CompileStage` | type | `'draft' \| 'gate' \| 'pin'` | Names the compile phases, in the order they run. |
68
+ | `CompilerEventMap` | type | `{ readonly compile: readonly [result: CompileResult]; readonly audit: readonly [audit: Audit]; readonly block: readonly [questions: readonly Question[]]; readonly error: readonly [error: unknown]; readonly destroy: readonly []; }` | Represents the compiler's observation channel. |
69
+ | `HostFile` | type | `{ readonly path: string; readonly lookup: 'found'; readonly hex: string; readonly observed?: string; readonly note?: never; } \| { readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly hex?: never; }` | Represents one vendored file read from the repository, beside the target bytes it answers for. |
70
+ | `Environment` | type | `'core' \| 'browser' \| 'server'` | Names one environment a generated workspace selects on its `src` or `app` axis. |
71
+ | `Extension` | type | `BrowserExtension \| StylesExtension` | Represents an extension discriminated by its surface. |
72
+ | `Framework` | type | `'vue'` | Names a supported browser framework. |
73
+ | `Lookup` | type | `'found' \| 'missing' \| 'unmatched' \| 'failed'` | Names how an upstream lookup resolved: found, missing, unmatched, or failed. |
74
+ | `Mirror` | type | `{ readonly name: string; readonly path: string; readonly lookup: 'found'; readonly content: string; readonly observed?: string; readonly note?: never; } \| { readonly name: string; readonly path: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly observed?: string; readonly content?: never; }` | Represents one dependency guide fetched from upstream, beside the local mirror it answers for. |
75
+ | `Origin` | type | `'host' \| 'template' \| 'computed'` | Names how an artifact's content is produced. |
76
+ | `Ownership` | type | `'content' \| 'presence' \| 'birth'` | Names what scaffold claims at an artifact's path. |
77
+ | `Release` | type | `{ readonly name: string; readonly range: string; readonly lookup: 'found'; readonly latest: string; readonly major?: number; readonly note?: never; } \| { readonly name: string; readonly range: string; readonly lookup: 'missing' \| 'unmatched' \| 'failed'; readonly note: string; readonly major?: number; readonly latest?: never; }` | Represents one declared dependency range measured against a registry release. |
78
+ | `ScaffoldErrorCode` | type | `'INVALID' \| 'BLOCKED' \| 'DESTROYED' \| 'TARGET' \| 'WRITE' \| 'FETCH'` | Names the coded reasons a scaffold error is raised. |
79
+ | `SetupRuntime` | type | `'node' \| 'browser'` | Names the runtime a root setup proof requires. |
80
+ | `Snapshot` | type | `Readonly<Record<string, string>>` | Holds exact lowercase hexadecimal target bytes keyed by artifact-relative path. |
81
+ | `Surface` | type | `'browser' \| 'styles'` | Names the surface an extension extends. |
82
82
 
83
83
  #### Interfaces
84
84
 
@@ -136,6 +136,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
136
136
  | `APP_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency every private `app` environment adds. |
137
137
  | `APP_MATRIX` | const | `Readonly<Record<Environment, AppDefinition>>` | Holds the configuration and runtime-entry settings each private `app` environment contributes, frozen. |
138
138
  | `APP_SERVER_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies a private server application adds. |
139
+ | `ARTIFACT_GROUPS` | const | `readonly ArtifactGroup[]` | Lists the `ArtifactGroup` values in plan order, frozen. |
139
140
  | `ARTIFACT_TEMPLATES` | const | `ArtifactTemplateSet` | Holds formatter-stable template text for source, test, document, guide, and service artifacts. |
140
141
  | `AXES` | const | `readonly Axis[]` | Lists the axes a browser extension may occupy, frozen. |
141
142
  | `BASE_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Holds the baseline tooling versions, before framework holds apply. |
@@ -168,7 +169,6 @@ Exported from `@orkestrel/scaffold`, and reachable from
168
169
  | `FRAMEWORKS` | const | `readonly Framework[]` | Lists the supported browser frameworks, frozen. |
169
170
  | `FRAMEWORK_MATRIX` | const | `Readonly<Record<Framework, FrameworkDefinition>>` | Describes the tooling and package boundaries of each browser framework, frozen. |
170
171
  | `GLOBAL_SETUP_PATH` | const | `"tests/setupGlobal.ts"` | Names the shared Vitest global-setup module whose presence makes a workspace `global`. |
171
- | `GROUPS` | const | `readonly Group[]` | Lists the `Group` values in plan order, frozen. |
172
172
  | `GUIDES_TEST_PATH` | const | `"tests/guides.test.ts"` | Names the package-owned guide-parity entry used by `test:guides` and to select the `guides` project. |
173
173
  | `HEX_PATTERN` | const | `RegExp` | Matches exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. |
174
174
  | `HOST_INVENTORY_PATH` | const | `"host.json"` | Names the repository-relative path where the committed vendored-file inventory is served. |
@@ -233,6 +233,9 @@ Exported from `@orkestrel/scaffold`, and reachable from
233
233
  | Name | Kind | Signature | Summary |
234
234
  | -------------------- | -------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
235
235
  | `isArtifact` | const | `Guard<Artifact>` | Narrows a value to an `Artifact`. |
236
+ | `isArtifactFinding` | const | `Guard<ArtifactFinding>` | Narrows a value to an `ArtifactFinding`. |
237
+ | `isArtifactGroup` | const | `Guard<ArtifactGroup>` | Narrows a value to one `ArtifactGroup` a plan selects over. |
238
+ | `isArtifactGroups` | const | `Guard<readonly ArtifactGroup[]>` | Narrows a value to a bounded group selection. |
236
239
  | `isAudit` | const | `Guard<Audit>` | Narrows a value to an `Audit`. |
237
240
  | `isBlueprint` | const | `Guard<Blueprint>` | Narrows a value to a `Blueprint`. |
238
241
  | `isBrowserExtension` | const | `Guard<BrowserExtension>` | Narrows a value to a supported browser framework with distinct occupied axes. |
@@ -245,10 +248,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
245
248
  | `isDependencyName` | const | `Guard<string>` | Narrows a value to the scoped package name a runtime dependency carries. |
246
249
  | `isEnvironment` | const | `Guard<Environment>` | Narrows a value to one `Environment` a workspace may select. |
247
250
  | `isExtension` | const | `Guard<Extension>` | Narrows a value to an extension of a supported surface. |
248
- | `isFinding` | const | `Guard<Finding>` | Narrows a value to a `Finding`. |
249
- | `isGroup` | const | `Guard<Group>` | Narrows a value to one `Group` a plan selects over. |
250
- | `isGroups` | const | `Guard<readonly Group[]>` | Narrows a value to a bounded group selection. |
251
- | `isHex` | const | `Guard<string>` | Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit. |
251
+ | `isHexContent` | const | `Guard<string>` | Narrows a value to exact lowercase hexadecimal bytes within one artifact's limit. |
252
252
  | `isManifestScript` | const | `Guard<ManifestScript>` | Narrows a value to a `ManifestScript`. |
253
253
  | `isMirror` | const | `Guard<Mirror>` | Narrows a value to a `Mirror`. |
254
254
  | `isOverride` | const | `Guard<Override>` | Narrows a value to an `Override`. |
@@ -263,52 +263,52 @@ Exported from `@orkestrel/scaffold`, and reachable from
263
263
 
264
264
  #### Parsers
265
265
 
266
- | Name | Kind | Signature | Summary |
267
- | ---------------------- | -------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
268
- | `parseBlueprint` | function | `(value: unknown) => Blueprint \| undefined` | Coerces an untrusted value to a `Blueprint`. |
269
- | `parseCompilerOptions` | function | `(value: unknown) => CompilerOptions \| undefined` | Coerces an untrusted value to `CompilerOptions`. |
270
- | `parseExtension` | function | `(value: unknown) => Extension \| undefined` | Coerces an extension value or a `surface:name` selection into an extension. |
271
- | `parseGroups` | function | `(value: unknown) => readonly Group[] \| undefined` | Coerces an untrusted value to a group selection. |
272
- | `parseSnapshot` | function | `(value: unknown) => Snapshot \| undefined` | Coerces an untrusted value to a `Snapshot`. |
266
+ | Name | Kind | Signature | Summary |
267
+ | ---------------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------- |
268
+ | `parseArtifactGroups` | function | `(value: unknown) => readonly ArtifactGroup[] \| undefined` | Coerces an untrusted value to a group selection. |
269
+ | `parseBlueprint` | function | `(value: unknown) => Blueprint \| undefined` | Coerces an untrusted value to a `Blueprint`. |
270
+ | `parseCompilerOptions` | function | `(value: unknown) => CompilerOptions \| undefined` | Coerces an untrusted value to `CompilerOptions`. |
271
+ | `parseExtension` | function | `(value: unknown) => Extension \| undefined` | Coerces an extension value or a `surface:name` selection into an extension. |
272
+ | `parseSnapshot` | function | `(value: unknown) => Snapshot \| undefined` | Coerces an untrusted value to a `Snapshot`. |
273
273
 
274
274
  #### Helpers
275
275
 
276
- | Name | Kind | Signature | Summary |
277
- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
278
- | `artifactToFinding` | function | `(artifact: Artifact, observed?: string) => Finding` | Projects one planned artifact and the bytes found at its path into a verdict. |
279
- | `artifactToHex` | function | `(artifact: Artifact) => string \| undefined` | Projects an artifact to the exact bytes it claims, as hexadecimal. |
280
- | `bytesToHex` | function | `(bytes: Uint8Array) => string` | Encodes bytes as exact lowercase hexadecimal text. |
281
- | `catalogToLayers` | function | `(entries: readonly CatalogEntry[]) => ReadonlyArray<readonly string[]>` | Projects a catalog into the layers it publishes in. |
282
- | `cloneValue` | function | `(value: unknown) => JSONValue \| undefined` | Snapshots an untrusted value into exact JSON data the caller owns. |
283
- | `compareVersions` | function | `(left: string, right: string) => number` | Compares two versions by their numeric components. |
284
- | `computeBytes` | function | `(content: string) => number` | Counts the UTF-8 bytes text encodes to. |
285
- | `computeHash` | function | `(text: string) => string` | Computes the deterministic content identity of text. |
286
- | `computeTotal` | function | `(values: readonly number[]) => number` | Computes the sum of a list of numbers. |
287
- | `contentToHex` | function | `(content: string) => string` | Encodes text as the exact lowercase hexadecimal form of its UTF-8 bytes. |
288
- | `extractRangeMajor` | function | `(range: string) => number \| undefined` | Extracts the major component of an admitted dependency range. |
289
- | `extractVersion` | function | `(version: string) => readonly [major: number, minor: number, patch: number] \| undefined` | Extracts the major, minor, and patch components of an exact version. |
290
- | `inferDrift` | function | `(artifact: Artifact, observed?: string) => Exclude<Drift, 'foreign'>` | Infers how one target path compares to the artifact planned for it. |
291
- | `inferGroup` | function | `(path: string) => Group` | Infers the `Group` a path belongs to. |
292
- | `isCanonPath` | function | `(path: string) => boolean` | Checks whether a path belongs to the instruction canon a target reads rather than holds. |
293
- | `isDeferredPath` | function | `(path: string) => boolean` | Checks whether another surface owns the vendored bytes at a path. |
294
- | `isFloorPath` | function | `(path: string) => boolean` | Checks whether a destination's floor bytes survive a live overlay. |
295
- | `isRetainedPath` | function | `(path: string) => boolean` | Checks whether another surface owns a target's present bytes at a path. |
296
- | `iterateAnswers` | function | `<TValue, TAnswer>(source: Iterable<TValue>, answer: (value: TValue) => TAnswer \| undefined) => Generator<TAnswer \| undefined, void, undefined>` | Yields the answer to each value of a source and ends after the first refused answer. |
297
- | `manifestToDependencies` | function | `(manifest: string) => ManifestDependencySet` | Projects a package manifest's text to the `@orkestrel/*` packages each dependency section declares. |
298
- | `manifestToName` | function | `(manifest: string) => string \| undefined` | Projects a package manifest's text to its own name. |
299
- | `matchesDriftReachability` | function | `(ownership: Ownership, finding: Finding) => boolean` | Tests whether `inferDrift` could have produced a finding for an ownership. |
300
- | `matchesEngines` | function | `(engines: string) => boolean` | Tests whether a declared engines floor is at or above the supported minimum. |
301
- | `matchesOrchestrationPath` | function | `(path: string) => boolean` | Tests whether a path instructs or wires an agent rather than the toolchain. |
302
- | `matchesPrintWidth` | function | `(line: string) => boolean` | Tests whether one emitted line fits the vendored formatter width. |
303
- | `matchesRange` | function | `(range: string, latest: string) => boolean` | Tests whether a declared range already admits a published version. |
304
- | `nameToGuide` | function | `(name: string) => string` | Derives the guide mirror path a package name answers for. |
305
- | `planToSummary` | function | `(plan: Plan) => PlanSummary` | Projects a plan into its tally by artifact origin. |
306
- | `renderSkillPointer` | function | `(canonical: string, name: string) => string \| undefined` | Renders the `SKILL.md` pointer a target carries in place of a canonical skill. |
307
- | `scanManifestTokens` | function | `(text: string) => readonly ManifestToken[] \| undefined` | Scans manifest text for its strings and object braces, in order. |
308
- | `selectGroups` | function | `(groups?: readonly Group[]) => readonly Group[]` | Selects the groups a compile covers, in plan order. |
309
- | `selectHostPaths` | function | `(paths: readonly string[], name: string) => readonly string[]` | Selects the host paths a named workspace vendors. |
310
- | `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
311
- | `srcToRoot` | function | `(src: readonly Environment[]) => Environment \| undefined` | Selects the single published environment a package root points at. |
276
+ | Name | Kind | Signature | Summary |
277
+ | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
278
+ | `artifactToArtifactFinding` | function | `(artifact: Artifact, observed?: string) => ArtifactFinding` | Projects one planned artifact and the bytes found at its path into a verdict. |
279
+ | `artifactToHex` | function | `(artifact: Artifact) => string \| undefined` | Projects an artifact to the exact bytes it claims, as hexadecimal. |
280
+ | `bytesToHex` | function | `(bytes: Uint8Array) => string` | Encodes bytes as exact lowercase hexadecimal text. |
281
+ | `catalogToLayers` | function | `(entries: readonly CatalogEntry[]) => ReadonlyArray<readonly string[]>` | Projects a catalog into the layers it publishes in. |
282
+ | `compareVersions` | function | `(left: string, right: string) => number` | Compares two versions by their numeric components. |
283
+ | `computeBytes` | function | `(content: string) => number` | Counts the UTF-8 bytes text encodes to. |
284
+ | `computeHash` | function | `(text: string) => string` | Computes the deterministic content identity of text. |
285
+ | `computeTotal` | function | `(values: readonly number[]) => number` | Computes the sum of a list of numbers. |
286
+ | `contentToHex` | function | `(content: string) => string` | Encodes text as the exact lowercase hexadecimal form of its UTF-8 bytes. |
287
+ | `extractRangeMajor` | function | `(range: string) => number \| undefined` | Extracts the major component of an admitted dependency range. |
288
+ | `extractVersion` | function | `(version: string) => readonly [major: number, minor: number, patch: number] \| undefined` | Extracts the major, minor, and patch components of an exact version. |
289
+ | `inferArtifactDrift` | function | `(artifact: Artifact, observed?: string) => Exclude<ArtifactDrift, 'foreign'>` | Infers how one target path compares to the artifact planned for it. |
290
+ | `inferArtifactGroup` | function | `(path: string) => ArtifactGroup` | Infers the `ArtifactGroup` a path belongs to. |
291
+ | `isCanonPath` | function | `(path: string) => boolean` | Checks whether a path belongs to the instruction canon a target reads rather than holds. |
292
+ | `isDeferredPath` | function | `(path: string) => boolean` | Checks whether another surface owns the vendored bytes at a path. |
293
+ | `isFloorPath` | function | `(path: string) => boolean` | Checks whether a destination's floor bytes survive a live overlay. |
294
+ | `isRetainedPath` | function | `(path: string) => boolean` | Checks whether another surface owns a target's present bytes at a path. |
295
+ | `iterateAnswers` | function | `<TValue, TAnswer>(source: Iterable<TValue>, answer: (value: TValue) => TAnswer \| undefined) => Generator<TAnswer \| undefined, void, undefined>` | Yields the answer to each value of a source and ends after the first refused answer. |
296
+ | `manifestToDependencies` | function | `(manifest: string) => ManifestDependencySet` | Projects a package manifest's text to the `@orkestrel/*` packages each dependency section declares. |
297
+ | `manifestToName` | function | `(manifest: string) => string \| undefined` | Projects a package manifest's text to its own name. |
298
+ | `matchesArtifactDriftReachability` | function | `(ownership: Ownership, finding: ArtifactFinding) => boolean` | Tests whether `inferArtifactDrift` could have produced a finding for an ownership. |
299
+ | `matchesEngines` | function | `(engines: string) => boolean` | Tests whether a declared engines floor is at or above the supported minimum. |
300
+ | `matchesOrchestrationPath` | function | `(path: string) => boolean` | Tests whether a path instructs or wires an agent rather than the toolchain. |
301
+ | `matchesPrintWidth` | function | `(line: string) => boolean` | Tests whether one emitted line fits the vendored formatter width. |
302
+ | `matchesRange` | function | `(range: string, latest: string) => boolean` | Tests whether a declared range already admits a published version. |
303
+ | `nameToGuide` | function | `(name: string) => string` | Derives the guide mirror path a package name answers for. |
304
+ | `parseOwnedJSONValue` | function | `(value: unknown) => JSONValue \| undefined` | Snapshots an untrusted value into exact JSON data the caller owns. |
305
+ | `planToSummary` | function | `(plan: Plan) => PlanSummary` | Projects a plan into its tally by artifact origin. |
306
+ | `renderSkillPointer` | function | `(canonical: string, name: string) => string \| undefined` | Renders the `SKILL.md` pointer a target carries in place of a canonical skill. |
307
+ | `scanManifestTokens` | function | `(text: string) => readonly ManifestToken[] \| undefined` | Scans manifest text for its strings and object braces, in order. |
308
+ | `selectArtifactGroups` | function | `(groups?: readonly ArtifactGroup[]) => readonly ArtifactGroup[]` | Selects the groups a compile covers, in plan order. |
309
+ | `selectHostPaths` | function | `(paths: readonly string[], name: string) => readonly string[]` | Selects the host paths a named workspace vendors. |
310
+ | `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
311
+ | `srcToRoot` | function | `(src: readonly Environment[]) => Environment \| undefined` | Selects the single published environment a package root points at. |
312
312
 
313
313
  | Name | Kind | Signature | Summary |
314
314
  | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -353,7 +353,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
353
353
  | `insertManifestSection` | function | `(manifest: string, section: 'dependencies' \| 'devDependencies', dependencies: readonly Dependency[], present: boolean) => string \| undefined` | Inserts dependencies into one section of package manifest text. |
354
354
  | `overridesToQuestions` | function | `(overrides: readonly Override[], artifacts: readonly Artifact[]) => readonly Question[]` | Measures a blueprint's overrides against the artifacts drafted for it. |
355
355
  | `pathToCondition` | function | `(path: string, formats: readonly BuildFormat[]) => Readonly<Record<string, unknown>>` | Builds one `exports` condition block for a built environment. |
356
- | `planToFindings` | function | `(plan: Plan, current: Snapshot) => readonly Finding[]` | Compares a plan against a target's current content. |
356
+ | `planToArtifactFindings` | function | `(plan: Plan, current: Snapshot) => readonly ArtifactFinding[]` | Compares a plan against a target's current content. |
357
357
  | `planToHash` | function | `(plan: Plan) => string \| undefined` | Computes a plan's content identity. |
358
358
  | `replaceManifestRanges` | function | `(manifest: string, pins: DependencyPinSet) => string \| undefined` | Replaces the runtime and development dependency ranges in package manifest text, and never a peer range. |
359
359
  | `replaceManifestOverride` | function | `(manifest: string, path: readonly string[], range: string) => string \| undefined` | Replaces one npm override leaf in manifest text, inserting its absent ancestors. |
@@ -397,8 +397,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
397
397
  | `Host` | interface | `{ manifest, bytes }` | Represents a whole vendored host supplied as a value: the membership beside the bytes filling it. |
398
398
  | `HostInventory` | interface | `{ lookup, digests, duplicates, note, surface, unreachable? }` | Represents the committed vendored-file inventory as one call's reads are decided against. |
399
399
  | `HostManifest` | interface | `{ entries, roots, surface, digest }` | Represents the complete vendored-host inventory. |
400
- | `HostStageOptions` | interface | `{ inventory?, establish?, report? }` | Configures the committed inventory baseline and staging reports. |
401
- | `ManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
400
+ | `HostManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
401
+ | `HostStageOptions` | interface | `{ inventory?, establish?, report?, transfers? }` | Configures the committed inventory baseline and staging reports. |
402
402
  | `MaterializeResult` | interface | `{ target, written, skipped, removed }` | Reports the outcome of one mutation of a target. |
403
403
  | `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
404
404
  | `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
@@ -455,8 +455,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
455
455
  | `isFilesystemPath` | function | `(value: unknown) => value is string` | Narrows a value to a path naming a location on this host. |
456
456
  | `isHost` | const | `Guard<Host>` | Narrows a value to one `Host`. |
457
457
  | `isHostManifest` | const | `Guard<HostManifest>` | Narrows a value to one `HostManifest`. |
458
+ | `isHostManifestEntry` | const | `Guard<HostManifestEntry>` | Narrows a value to one `HostManifestEntry`. |
458
459
  | `isInventory` | function | `(value: unknown) => value is readonly unknown[]` | Narrows a value to a working-tree inventory within the limit one target may report. |
459
- | `isManifestEntry` | const | `Guard<ManifestEntry>` | Narrows a value to one `ManifestEntry`. |
460
460
  | `isManifestRegionSet` | const | `Guard<ManifestRegionSet>` | Narrows a value to one `ManifestRegionSet`. |
461
461
  | `isMaterializerHooks` | const | `Guard<EmitterHooks<MaterializerEventMap>>` | Narrows a value to the materializer's initial listener record. |
462
462
  | `isMaterializerOptions` | const | `Guard<MaterializerOptions>` | Narrows a value to `MaterializerOptions`. |
@@ -470,56 +470,56 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
470
470
 
471
471
  #### Helpers
472
472
 
473
- | Name | Kind | Signature | Summary |
474
- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
475
- | `climbRealPath` | function | `(current: string, pending: readonly string[], depth: number) => string \| undefined` | Climbs from an absolute path to its deepest existing ancestor and resolves it through every link. |
476
- | `collectIndexed` | function | `<TResult>(entries: ReadonlyArray<readonly [number, TResult]>) => readonly TResult[]` | Places each result at the index its entry names, in a fresh array. |
477
- | `computeDigest` | function | `(content: string) => string` | Computes the SHA-256 digest of text. |
478
- | `computeFileDigest` | function | `(path: string) => string \| undefined` | Computes the SHA-256 digest of one file's exact bytes. |
479
- | `computeManifestDigest` | function | `(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]) => string` | Computes the digest of a vendored host's declared membership. |
480
- | `decodeHexText` | function | `(hex: string) => string \| undefined` | Decodes exact bytes stated in hexadecimal as strict UTF-8 text. |
481
- | `filesToHost` | function | `(files: readonly HostFile[], floor: Host) => Host \| undefined` | Assembles a whole vendored host from live files and the installed floor. |
482
- | `hexToDigest` | function | `(hex: string) => string` | Projects exact bytes stated in hexadecimal to their SHA-256 digest. |
483
- | `isExactCaseFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file with exact on-disk casing. |
484
- | `isPhysicalDirectory` | function | `(path: string) => boolean` | Tests whether a path is a physical directory this package will read or write into. |
485
- | `isPhysicalFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file this package will read or replace. |
486
- | `isVacant` | function | `(target: string) => boolean` | Tests whether a target is safe to write a fresh workspace into. |
487
- | `listAncestors` | function | `(path: string, limit?: number) => readonly string[]` | Lists a path followed by each directory above it, nearest first. |
488
- | `listCanonPaths` | function | `(target: string, groups: readonly Group[]) => readonly string[]` | Lists the canon paths a target holds, filtered to a plan's groups. |
489
- | `listDirectories` | function | `(root: string) => readonly string[]` | Lists a directory's descendant directories as sorted root-relative paths. |
490
- | `listFiles` | function | `(root: string) => readonly string[]` | Lists a directory's files as sorted root-relative paths. |
491
- | `matchesAnchor` | function | `(anchor: WriteAnchor) => boolean` | Tests whether a path still holds the captured directory identity. |
492
- | `matchesExecutablePath` | function | `(path: string) => boolean` | Tests whether a vendored path is one a target receives executable. |
493
- | `matchesExpectation` | function | `(expectation: WriteExpectation) => boolean` | Tests whether a destination still holds what was captured of it. |
494
- | `matchesGitPath` | function | `(path: string) => boolean` | Tests whether a path addresses a target's own repository metadata. |
495
- | `matchesMissingPath` | function | `(error: unknown) => boolean` | Tests whether a caught filesystem error reports an absent path. |
496
- | `matchesPrecondition` | function | `(precondition: WritePrecondition) => boolean` | Tests whether a destination still matches the narrower state a caller observed. |
497
- | `matchesProtectedPath` | function | `(path: string) => boolean` | Tests whether a target-relative path is one no verb may delete. |
498
- | `matchesSensitivePath` | function | `(path: string) => boolean` | Tests whether a path names local configuration or a credential. |
499
- | `pathToStorage` | function | `(path: string) => string` | Projects a target-relative path to the storage name a vendored host holds it under. |
500
- | `pruneEmptiedDirectories` | function | `(target: string, removed: readonly string[]) => readonly string[]` | Removes every directory one set of deletions emptied. |
501
- | `readAnchor` | function | `(path: string) => WriteAnchor \| undefined` | Captures one directory's physical identity. |
502
- | `readExpectation` | function | `(path: string) => WriteExpectation \| undefined` | Captures what one destination holds before a write. |
503
- | `readFileHex` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as its exact bytes in lowercase hexadecimal. |
504
- | `readFileText` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as bounded UTF-8 text. |
505
- | `readHostFloor` | function | `(root?: string) => Host` | Reads the installed vendored host floor as a value. |
506
- | `readHostManifest` | function | `(host: string, name?: string) => HostManifest \| undefined` | Reads a vendored host's manifest, when it carries one. |
507
- | `readManifestEntry` | function | `(destination: string, source: string) => ManifestEntry \| undefined` | Derives one vendored-host manifest entry from a file in a checkout. |
508
- | `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
509
- | `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
510
- | `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
511
- | `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
512
- | `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
513
- | `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceContract \| undefined` | Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim. |
514
- | `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceContract` | Reads one guide's claims and reports parser refusals with its owner and source. |
515
- | `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
516
- | `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
517
- | `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
518
- | `resolveContainedPath` | function | `(root: string, path: string) => string \| undefined` | Resolves a root-relative path and refuses one that leaves its root. |
519
- | `resolveRealPath` | function | `(path: string) => string \| undefined` | Resolves a path through the real filesystem, keeping the part that does not exist yet. |
520
- | `stageBytes` | function | `(host: Host, root: string, destinations: readonly string[]) => readonly ManifestEntry[]` | Stages the named destinations of a value host into a private root. |
521
- | `stageHost` | function | `(checkout: string, host: string, options?: HostStageOptions) => readonly ManifestEntry[]` | Stages a vendored host root from a real checkout. |
522
- | `stageInventory` | function | `(checkout: string, path?: string) => HostManifest` | Stages the committed inventory of the files a vendored host carries. |
473
+ | Name | Kind | Signature | Summary |
474
+ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
475
+ | `climbRealPath` | function | `(current: string, pending: readonly string[], depth: number) => string \| undefined` | Climbs from an absolute path to its deepest existing ancestor and resolves it through every link. |
476
+ | `collectIndexed` | function | `<TResult>(entries: ReadonlyArray<readonly [number, TResult]>) => readonly TResult[]` | Places each result at the index its entry names, in a fresh array. |
477
+ | `computeDigest` | function | `(content: string) => string` | Computes the SHA-256 digest of text. |
478
+ | `computeFileDigest` | function | `(path: string) => string \| undefined` | Computes the SHA-256 digest of one file's exact bytes. |
479
+ | `computeManifestDigest` | function | `(entries: readonly HostManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]) => string` | Computes the digest of a vendored host's declared membership. |
480
+ | `decodeHexText` | function | `(hex: string) => string \| undefined` | Decodes exact bytes stated in hexadecimal as strict UTF-8 text. |
481
+ | `filesToHost` | function | `(files: readonly HostFile[], floor: Host) => Host \| undefined` | Assembles a whole vendored host from live files and the installed floor. |
482
+ | `hexToDigest` | function | `(hex: string) => string` | Projects exact bytes stated in hexadecimal to their SHA-256 digest. |
483
+ | `isExactCaseFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file with exact on-disk casing. |
484
+ | `isPhysicalDirectory` | function | `(path: string) => boolean` | Tests whether a path is a physical directory this package will read or write into. |
485
+ | `isPhysicalFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file this package will read or replace. |
486
+ | `isVacant` | function | `(target: string) => boolean` | Tests whether a target is safe to write a fresh workspace into. |
487
+ | `listAncestors` | function | `(path: string, limit?: number) => readonly string[]` | Lists a path followed by each directory above it, nearest first. |
488
+ | `listCanonPaths` | function | `(target: string, groups: readonly ArtifactGroup[]) => readonly string[]` | Lists the canon paths a target holds, filtered to a plan's groups. |
489
+ | `listDirectories` | function | `(root: string) => readonly string[]` | Lists a directory's descendant directories as sorted root-relative paths. |
490
+ | `listFiles` | function | `(root: string) => readonly string[]` | Lists a directory's files as sorted root-relative paths. |
491
+ | `matchesAnchor` | function | `(anchor: WriteAnchor) => boolean` | Tests whether a path still holds the captured directory identity. |
492
+ | `matchesExecutablePath` | function | `(path: string) => boolean` | Tests whether a vendored path is one a target receives executable. |
493
+ | `matchesExpectation` | function | `(expectation: WriteExpectation) => boolean` | Tests whether a destination still holds what was captured of it. |
494
+ | `matchesGitPath` | function | `(path: string) => boolean` | Tests whether a path addresses a target's own repository metadata. |
495
+ | `matchesMissingPath` | function | `(error: unknown) => boolean` | Tests whether a caught filesystem error reports an absent path. |
496
+ | `matchesPrecondition` | function | `(precondition: WritePrecondition) => boolean` | Tests whether a destination still matches the narrower state a caller observed. |
497
+ | `matchesProtectedPath` | function | `(path: string) => boolean` | Tests whether a target-relative path is one no verb may delete. |
498
+ | `matchesSensitivePath` | function | `(path: string) => boolean` | Tests whether a path names local configuration or a credential. |
499
+ | `pathToStorage` | function | `(path: string) => string` | Projects a target-relative path to the storage name a vendored host holds it under. |
500
+ | `pruneEmptiedDirectories` | function | `(target: string, removed: readonly string[]) => readonly string[]` | Removes every directory one set of deletions emptied. |
501
+ | `readAnchor` | function | `(path: string) => WriteAnchor \| undefined` | Captures one directory's physical identity. |
502
+ | `readExpectation` | function | `(path: string) => WriteExpectation \| undefined` | Captures what one destination holds before a write. |
503
+ | `readFileHex` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as its exact bytes in lowercase hexadecimal. |
504
+ | `readFileText` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as bounded UTF-8 text. |
505
+ | `readHostFloor` | function | `(root?: string) => Host` | Reads the installed vendored host floor as a value. |
506
+ | `readHostManifest` | function | `(host: string, name?: string) => HostManifest \| undefined` | Reads a vendored host's manifest, when it carries one. |
507
+ | `readHostManifestEntry` | function | `(destination: string, source: string) => HostManifestEntry \| undefined` | Derives one vendored-host manifest entry from a file in a checkout. |
508
+ | `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
509
+ | `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
510
+ | `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
511
+ | `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
512
+ | `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
513
+ | `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceContract \| undefined` | Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim. |
514
+ | `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceContract` | Reads one guide's claims and reports parser refusals with its owner and source. |
515
+ | `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
516
+ | `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
517
+ | `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
518
+ | `resolveContainedPath` | function | `(root: string, path: string) => string \| undefined` | Resolves a root-relative path and refuses one that leaves its root. |
519
+ | `resolveRealPath` | function | `(path: string) => string \| undefined` | Resolves a path through the real filesystem, keeping the part that does not exist yet. |
520
+ | `stageBytes` | function | `(host: Host, root: string, destinations: readonly string[]) => readonly HostManifestEntry[]` | Stages the named destinations of a value host into a private root. |
521
+ | `stageHost` | function | `(checkout: string, host: string, options?: HostStageOptions) => readonly HostManifestEntry[]` | Stages a vendored host root from a real checkout. |
522
+ | `stageInventory` | function | `(checkout: string, path?: string) => HostManifest` | Stages the committed inventory of the files a vendored host carries. |
523
523
 
524
524
  #### Classes
525
525
 
@@ -784,10 +784,11 @@ scaffold surface ../router ../server --from . --json
784
784
  The comparison uses the bare identifier, case included, across declaration keywords and
785
785
  environments. A name claimed by distinct owners is a collision. A collision absent from the record,
786
786
  or carrying an owner absent from its recorded owner set, has `error` standing. When another guide
787
- claims the name, the keeper a `SURFACE_TRANSFERS` entry declares is a recorded owner of it from the
788
- first build after the declaration, so its claim reads `recorded` before its guide is mirrored. A collision with the
789
- same or fewer owners has `recorded` standing. A recorded name that no longer collides has `closed`
790
- standing, so a release can shrink the record.
787
+ claims the name, the keeper a declared transfer names is a recorded owner of it from the first build
788
+ after the declaration, so its claim reads `recorded` before its guide is mirrored. A release build
789
+ declares the transfers in `SURFACE_TRANSFERS`. A collision with the same or fewer owners has
790
+ `recorded` standing. A recorded name that no longer collides has `closed` standing, so a release can
791
+ shrink the record.
791
792
 
792
793
  A name a candidate adds is one its claims hold and its owner's published guide does not. The
793
794
  published guide is read in the order the Claims row gives for any other owner: the guide on `main`,
@@ -1742,7 +1743,7 @@ than a silent no-op.
1742
1743
  A plan selects over the following groups, and a compile that names none covers all of them. Their
1743
1744
  order is the order a plan lists its artifacts in.
1744
1745
 
1745
- | Group | Holds |
1746
+ | `ArtifactGroup` | Holds |
1746
1747
  | --------------- | ------------------------------------------------------------------------------------------------- |
1747
1748
  | `manifest` | `package.json` |
1748
1749
  | `configs` | The root and per-target build configuration, and the root dotfiles |
@@ -1760,7 +1761,7 @@ target that lacks the file. It also carries the skill pointer set, three host-or
1760
1761
  each name in `TARGET_SKILL_NAMES`, so every harness in a target discovers the package-facing skills
1761
1762
  while their bodies, references, and scripts stay in the installed package. Every other canon path is
1762
1763
  staged for reading, so no group selection copies a contract into a target, and a copy a target holds
1763
- at one of them is foreign drift in the group `inferGroup` gives it. A scoped audit reads the canon
1764
+ at one of them is foreign drift in the group `inferArtifactGroup` gives it. A scoped audit reads the canon
1764
1765
  through that same selection, so a run excluding a group reports nothing there.
1765
1766
 
1766
1767
  ## Ownership and drift
@@ -2033,7 +2034,7 @@ defining paths, `studies` by an exact-case `*.test.ts` file beneath `tests/studi
2033
2034
  configuration must keep those edits outside a content-owned file; `repair` restores that file to the
2034
2035
  canonical project set.
2035
2036
 
2036
- An audit reports one `Finding` per planned path, followed by every foreign path in the groups the
2037
+ An audit reports one `ArtifactFinding` per planned path, followed by every foreign path in the groups the
2037
2038
  plan covers. That second list draws on a file beneath a vendored directory the plan expands and on a
2038
2039
  file the target holds at a canon path the plan does not claim. Every planned finding carries its
2039
2040
  artifact's `ownership`. A foreign finding has no ownership because no artifact was planned for its
@@ -2049,12 +2050,12 @@ aggregate tally.
2049
2050
  The plan and snapshot are each bounded at `MAX_COLLECTION_ITEMS`. An audit may therefore carry one
2050
2051
  finding per planned artifact plus one per unplanned snapshot path, up to `MAX_AUDIT_FINDINGS`.
2051
2052
 
2052
- | `Drift` | Means |
2053
- | --------- | ------------------------------------- |
2054
- | `aligned` | The target matches the plan |
2055
- | `stale` | The target holds different bytes |
2056
- | `missing` | The target holds no file at that path |
2057
- | `foreign` | The plan does not own the path at all |
2053
+ | `ArtifactDrift` | Means |
2054
+ | --------------- | ------------------------------------- |
2055
+ | `aligned` | The target matches the plan |
2056
+ | `stale` | The target holds different bytes |
2057
+ | `missing` | The target holds no file at that path |
2058
+ | `foreign` | The plan does not own the path at all |
2058
2059
 
2059
2060
  A stale or foreign finding carries the destination's exact bytes in `observed`, and that record is
2060
2061
  the precondition the mutation is held to. A write that replaces stale bytes and a deletion that
@@ -2062,7 +2063,7 @@ removes a foreign file each fail when the destination no longer matches what the
2062
2063
  The requirement sits in the type rather than in prose, because a deletion that cannot bind to what
2063
2064
  the audit showed is the one thing the destructive verb must never do.
2064
2065
 
2065
- `isFinding` proves the shape a reader may destructure and nothing about whether the verdict is one
2066
+ `isArtifactFinding` proves the shape a reader may destructure and nothing about whether the verdict is one
2066
2067
  an audit could have reached. `repair` and `remove` re-derive every verdict themselves and act only
2067
2068
  on what they derived, so a verdict the comparison could not have produced is refused by name rather
2068
2069
  than acted on.
@@ -2282,6 +2283,7 @@ The inventory contracts carry these data members.
2282
2283
  | `HostStageOptions.inventory` | Optional checkout-relative inventory path. Default: `HOST_INVENTORY_PATH` (`host.json`). |
2283
2284
  | `HostStageOptions.establish` | Optional boolean. If `true`, an absent inventory establishes the baseline; if `false`, staging refuses it. Default: `false`. |
2284
2285
  | `HostStageOptions.report` | Optional callback receiving the baseline location or its absence. Default: no reporting. |
2286
+ | `HostStageOptions.transfers` | Optional readonly `SurfaceTransfer[]` the stage admits. Default: `SURFACE_TRANSFERS`. |
2285
2287
 
2286
2288
  The vendored data root is the shared file set, staged into the published package as plain data.
2287
2289
  Staging walks `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS`, and a release ships what those
@@ -2427,7 +2429,7 @@ one; `.claude/AGENTS.md` § Models owns the rule.
2427
2429
  ```ts
2428
2430
  import { stageHost } from '@orkestrel/scaffold/server'
2429
2431
 
2430
- stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
2432
+ stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
2431
2433
  ```
2432
2434
 
2433
2435
  Each staged path is copied to a storage name, and every dot that opens a segment comes off,
@@ -2459,7 +2461,8 @@ committed inventory does not already record: `stageHost` reads the baseline thro
2459
2461
  `readSurfaceBaseline` before the build rewrites the inventory, and refuses a name whose staged
2460
2462
  owner set differs from the inventory — absent from the record, or not a subset of its recorded
2461
2463
  owners — which is what stops a release from widening the set of names more than one package claims.
2462
- A `SURFACE_TRANSFERS` entry that another staged guide claims admits exactly its keeper beside the
2464
+ `HostStageOptions.transfers` declares the transfers, and its default is `SURFACE_TRANSFERS`. A
2465
+ declared transfer that another staged guide claims admits exactly its keeper beside the
2463
2466
  recorded owners, or beside the one owner of a name the record lacks, and the stage records that
2464
2467
  keeper whether or not its guide is mirrored; any other added owner is still refused. A transfer
2465
2468
  whose keeper alone claims the name is spent, and the stage refuses it with `TARGET`, naming the
@@ -2474,8 +2477,9 @@ An absent inventory refuses staging unless `HostStageOptions.establish` is `true
2474
2477
  option to bootstrap a fresh checkout deliberately. An inventory whose `surface` is missing,
2475
2478
  malformed, or at odds with its digest is refused even during bootstrap.
2476
2479
 
2477
- `npm run build` is the release path, and it passes neither `HostStageOptions.inventory` nor
2478
- `HostStageOptions.establish`. Its `build:host` step stages
2480
+ `npm run build` is the release path, and it passes none of `HostStageOptions.inventory`,
2481
+ `HostStageOptions.establish`, and `HostStageOptions.transfers`, so it admits the transfers in
2482
+ `SURFACE_TRANSFERS`. Its `build:host` step stages
2479
2483
  `dist/host`, and its `build:inventory` step stages a temporary root and writes the manifest that
2480
2484
  run produced to `host.json`; each reads the committed inventory at the default path, refuses an
2481
2485
  absent one, and compares the staged collisions against what that inventory records. Deleting