@orkestrel/scaffold 0.0.118 → 0.0.120

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 (55) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/platforms/windows.md +2 -1
  4. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  5. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  8. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +2 -1
  9. package/dist/host/claude/agents/orkestrel.md +27 -26
  10. package/dist/host/claude/rules/names.md +3 -2
  11. package/dist/host/claude/rules/tests.md +4 -2
  12. package/dist/host/claude/rules/typescript.md +2 -3
  13. package/dist/host/claude/rules/workspace.md +2 -1
  14. package/dist/host/guides/abort.md +0 -4
  15. package/dist/host/guides/budget.md +1 -5
  16. package/dist/host/guides/codec.md +18 -3
  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/html.md +3 -7
  23. package/dist/host/guides/indexeddb.md +28 -32
  24. package/dist/host/guides/jsonrpc.md +187 -0
  25. package/dist/host/guides/markdown.md +132 -141
  26. package/dist/host/guides/msg.md +47 -63
  27. package/dist/host/guides/ndjson.md +0 -4
  28. package/dist/host/guides/pool.md +0 -4
  29. package/dist/host/guides/process.md +71 -79
  30. package/dist/host/guides/reason.md +30 -36
  31. package/dist/host/guides/router.md +11 -18
  32. package/dist/host/guides/scaffold.md +147 -137
  33. package/dist/host/guides/sqlite.md +0 -4
  34. package/dist/host/guides/sse.md +6 -10
  35. package/dist/host/guides/table.md +481 -493
  36. package/dist/host/guides/template.md +0 -4
  37. package/dist/host/guides/test.md +46 -66
  38. package/dist/host/guides/timeout.md +0 -6
  39. package/dist/host/guides/tool.md +2 -6
  40. package/dist/host/guides/websocket.md +0 -4
  41. package/dist/host/manifest.json +100 -428
  42. package/dist/host/tests/setupPolicy.ts +18 -6
  43. package/dist/src/core/index.cjs +171 -122
  44. package/dist/src/core/index.cjs.map +1 -1
  45. package/dist/src/core/index.d.cts +236 -213
  46. package/dist/src/core/index.d.ts +236 -213
  47. package/dist/src/core/index.js +159 -111
  48. package/dist/src/core/index.js.map +1 -1
  49. package/dist/src/server/index.cjs +62 -39
  50. package/dist/src/server/index.cjs.map +1 -1
  51. package/dist/src/server/index.d.cts +59 -54
  52. package/dist/src/server/index.d.ts +59 -54
  53. package/dist/src/server/index.js +63 -40
  54. package/dist/src/server/index.js.map +1 -1
  55. package/package.json +9 -9
@@ -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
 
@@ -126,6 +126,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
126
126
  | `SurfaceContract` | interface | `{ signatures }` | Represents one owner's claim with the guide `Signature` cell of each name a Surface row documents. |
127
127
  | `SurfaceFinding` | interface | `{ standing }` | Reports a collision's standing against the recorded owner set. |
128
128
  | `SurfaceSimilarity` | type | `'case' \| 'plural' \| 'edit' \| 'signature'` | Names how an added name resembles a name another owner claims. |
129
+ | `SurfaceTransfer` | interface | `{ name, keeper, item }` | Represents a declared transfer of one bare name to the package a roadmap item rules keeps it. |
129
130
 
130
131
  #### Constants
131
132
 
@@ -135,6 +136,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
135
136
  | `APP_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency every private `app` environment adds. |
136
137
  | `APP_MATRIX` | const | `Readonly<Record<Environment, AppDefinition>>` | Holds the configuration and runtime-entry settings each private `app` environment contributes, frozen. |
137
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. |
138
140
  | `ARTIFACT_TEMPLATES` | const | `ArtifactTemplateSet` | Holds formatter-stable template text for source, test, document, guide, and service artifacts. |
139
141
  | `AXES` | const | `readonly Axis[]` | Lists the axes a browser extension may occupy, frozen. |
140
142
  | `BASE_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Holds the baseline tooling versions, before framework holds apply. |
@@ -167,7 +169,6 @@ Exported from `@orkestrel/scaffold`, and reachable from
167
169
  | `FRAMEWORKS` | const | `readonly Framework[]` | Lists the supported browser frameworks, frozen. |
168
170
  | `FRAMEWORK_MATRIX` | const | `Readonly<Record<Framework, FrameworkDefinition>>` | Describes the tooling and package boundaries of each browser framework, frozen. |
169
171
  | `GLOBAL_SETUP_PATH` | const | `"tests/setupGlobal.ts"` | Names the shared Vitest global-setup module whose presence makes a workspace `global`. |
170
- | `GROUPS` | const | `readonly Group[]` | Lists the `Group` values in plan order, frozen. |
171
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. |
172
173
  | `HEX_PATTERN` | const | `RegExp` | Matches exact lowercase hexadecimal bytes: two digits per byte, and empty content is valid. |
173
174
  | `HOST_INVENTORY_PATH` | const | `"host.json"` | Names the repository-relative path where the committed vendored-file inventory is served. |
@@ -216,6 +217,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
216
217
  | `STYLES_ENTRY_PATH` | const | `"src/styles/index.scss"` | Names the base stylesheet marker. |
217
218
  | `SURFACES` | const | `readonly Surface[]` | Lists the surfaces an extension may extend, frozen. |
218
219
  | `SURFACE_EDIT_LENGTH` | const | `6` | Sets the shortest name length at which a one-edit neighbor counts as a near name. |
220
+ | `SURFACE_TRANSFERS` | const | `readonly SurfaceTransfer[]` | Lists the declared transfers of bare names to their ruled keepers, frozen. |
219
221
  | `TAB_WIDTH` | const | `2` | Sets the columns one tab occupies when the formatter measures a line, matching `tabWidth`. |
220
222
  | `TARGET_SKILL_NAMES` | const | `readonly string[]` | Lists the package-facing skills a target receives pointers for, frozen and alphabetical. |
221
223
  | `THEMES_BARREL_PATH` | const | `"src/styles/themes/index.scss"` | Names the themes stylesheet marker. |
@@ -231,6 +233,9 @@ Exported from `@orkestrel/scaffold`, and reachable from
231
233
  | Name | Kind | Signature | Summary |
232
234
  | -------------------- | -------- | ------------------------------------------------- | --------------------------------------------------------------------------------- |
233
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. |
234
239
  | `isAudit` | const | `Guard<Audit>` | Narrows a value to an `Audit`. |
235
240
  | `isBlueprint` | const | `Guard<Blueprint>` | Narrows a value to a `Blueprint`. |
236
241
  | `isBrowserExtension` | const | `Guard<BrowserExtension>` | Narrows a value to a supported browser framework with distinct occupied axes. |
@@ -243,10 +248,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
243
248
  | `isDependencyName` | const | `Guard<string>` | Narrows a value to the scoped package name a runtime dependency carries. |
244
249
  | `isEnvironment` | const | `Guard<Environment>` | Narrows a value to one `Environment` a workspace may select. |
245
250
  | `isExtension` | const | `Guard<Extension>` | Narrows a value to an extension of a supported surface. |
246
- | `isFinding` | const | `Guard<Finding>` | Narrows a value to a `Finding`. |
247
- | `isGroup` | const | `Guard<Group>` | Narrows a value to one `Group` a plan selects over. |
248
- | `isGroups` | const | `Guard<readonly Group[]>` | Narrows a value to a bounded group selection. |
249
- | `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. |
250
252
  | `isManifestScript` | const | `Guard<ManifestScript>` | Narrows a value to a `ManifestScript`. |
251
253
  | `isMirror` | const | `Guard<Mirror>` | Narrows a value to a `Mirror`. |
252
254
  | `isOverride` | const | `Guard<Override>` | Narrows a value to an `Override`. |
@@ -261,52 +263,52 @@ Exported from `@orkestrel/scaffold`, and reachable from
261
263
 
262
264
  #### Parsers
263
265
 
264
- | Name | Kind | Signature | Summary |
265
- | ---------------------- | -------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
266
- | `parseBlueprint` | function | `(value: unknown) => Blueprint \| undefined` | Coerces an untrusted value to a `Blueprint`. |
267
- | `parseCompilerOptions` | function | `(value: unknown) => CompilerOptions \| undefined` | Coerces an untrusted value to `CompilerOptions`. |
268
- | `parseExtension` | function | `(value: unknown) => Extension \| undefined` | Coerces an extension value or a `surface:name` selection into an extension. |
269
- | `parseGroups` | function | `(value: unknown) => readonly Group[] \| undefined` | Coerces an untrusted value to a group selection. |
270
- | `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`. |
271
273
 
272
274
  #### Helpers
273
275
 
274
- | Name | Kind | Signature | Summary |
275
- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
276
- | `artifactToFinding` | function | `(artifact: Artifact, observed?: string) => Finding` | Projects one planned artifact and the bytes found at its path into a verdict. |
277
- | `artifactToHex` | function | `(artifact: Artifact) => string \| undefined` | Projects an artifact to the exact bytes it claims, as hexadecimal. |
278
- | `bytesToHex` | function | `(bytes: Uint8Array) => string` | Encodes bytes as exact lowercase hexadecimal text. |
279
- | `catalogToLayers` | function | `(entries: readonly CatalogEntry[]) => ReadonlyArray<readonly string[]>` | Projects a catalog into the layers it publishes in. |
280
- | `cloneValue` | function | `(value: unknown) => JSONValue \| undefined` | Snapshots an untrusted value into exact JSON data the caller owns. |
281
- | `compareVersions` | function | `(left: string, right: string) => number` | Compares two versions by their numeric components. |
282
- | `computeBytes` | function | `(content: string) => number` | Counts the UTF-8 bytes text encodes to. |
283
- | `computeHash` | function | `(text: string) => string` | Computes the deterministic content identity of text. |
284
- | `computeTotal` | function | `(values: readonly number[]) => number` | Computes the sum of a list of numbers. |
285
- | `contentToHex` | function | `(content: string) => string` | Encodes text as the exact lowercase hexadecimal form of its UTF-8 bytes. |
286
- | `extractRangeMajor` | function | `(range: string) => number \| undefined` | Extracts the major component of an admitted dependency range. |
287
- | `extractVersion` | function | `(version: string) => readonly [major: number, minor: number, patch: number] \| undefined` | Extracts the major, minor, and patch components of an exact version. |
288
- | `inferDrift` | function | `(artifact: Artifact, observed?: string) => Exclude<Drift, 'foreign'>` | Infers how one target path compares to the artifact planned for it. |
289
- | `inferGroup` | function | `(path: string) => Group` | Infers the `Group` a path belongs to. |
290
- | `isCanonPath` | function | `(path: string) => boolean` | Checks whether a path belongs to the instruction canon a target reads rather than holds. |
291
- | `isDeferredPath` | function | `(path: string) => boolean` | Checks whether another surface owns the vendored bytes at a path. |
292
- | `isFloorPath` | function | `(path: string) => boolean` | Checks whether a destination's floor bytes survive a live overlay. |
293
- | `isRetainedPath` | function | `(path: string) => boolean` | Checks whether another surface owns a target's present bytes at a path. |
294
- | `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. |
295
- | `manifestToDependencies` | function | `(manifest: string) => ManifestDependencySet` | Projects a package manifest's text to the `@orkestrel/*` packages each dependency section declares. |
296
- | `manifestToName` | function | `(manifest: string) => string \| undefined` | Projects a package manifest's text to its own name. |
297
- | `matchesDriftReachability` | function | `(ownership: Ownership, finding: Finding) => boolean` | Tests whether `inferDrift` could have produced a finding for an ownership. |
298
- | `matchesEngines` | function | `(engines: string) => boolean` | Tests whether a declared engines floor is at or above the supported minimum. |
299
- | `matchesOrchestrationPath` | function | `(path: string) => boolean` | Tests whether a path instructs or wires an agent rather than the toolchain. |
300
- | `matchesPrintWidth` | function | `(line: string) => boolean` | Tests whether one emitted line fits the vendored formatter width. |
301
- | `matchesRange` | function | `(range: string, latest: string) => boolean` | Tests whether a declared range already admits a published version. |
302
- | `nameToGuide` | function | `(name: string) => string` | Derives the guide mirror path a package name answers for. |
303
- | `planToSummary` | function | `(plan: Plan) => PlanSummary` | Projects a plan into its tally by artifact origin. |
304
- | `renderSkillPointer` | function | `(canonical: string, name: string) => string \| undefined` | Renders the `SKILL.md` pointer a target carries in place of a canonical skill. |
305
- | `scanManifestTokens` | function | `(text: string) => readonly ManifestToken[] \| undefined` | Scans manifest text for its strings and object braces, in order. |
306
- | `selectGroups` | function | `(groups?: readonly Group[]) => readonly Group[]` | Selects the groups a compile covers, in plan order. |
307
- | `selectHostPaths` | function | `(paths: readonly string[], name: string) => readonly string[]` | Selects the host paths a named workspace vendors. |
308
- | `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
309
- | `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. |
310
312
 
311
313
  | Name | Kind | Signature | Summary |
312
314
  | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -351,7 +353,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
351
353
  | `insertManifestSection` | function | `(manifest: string, section: 'dependencies' \| 'devDependencies', dependencies: readonly Dependency[], present: boolean) => string \| undefined` | Inserts dependencies into one section of package manifest text. |
352
354
  | `overridesToQuestions` | function | `(overrides: readonly Override[], artifacts: readonly Artifact[]) => readonly Question[]` | Measures a blueprint's overrides against the artifacts drafted for it. |
353
355
  | `pathToCondition` | function | `(path: string, formats: readonly BuildFormat[]) => Readonly<Record<string, unknown>>` | Builds one `exports` condition block for a built environment. |
354
- | `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. |
355
357
  | `planToHash` | function | `(plan: Plan) => string \| undefined` | Computes a plan's content identity. |
356
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. |
357
359
  | `replaceManifestOverride` | function | `(manifest: string, path: readonly string[], range: string) => string \| undefined` | Replaces one npm override leaf in manifest text, inserting its absent ancestors. |
@@ -395,8 +397,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
395
397
  | `Host` | interface | `{ manifest, bytes }` | Represents a whole vendored host supplied as a value: the membership beside the bytes filling it. |
396
398
  | `HostInventory` | interface | `{ lookup, digests, duplicates, note, surface, unreachable? }` | Represents the committed vendored-file inventory as one call's reads are decided against. |
397
399
  | `HostManifest` | interface | `{ entries, roots, surface, digest }` | Represents the complete vendored-host inventory. |
400
+ | `HostManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
398
401
  | `HostStageOptions` | interface | `{ inventory?, establish?, report? }` | Configures the committed inventory baseline and staging reports. |
399
- | `ManifestEntry` | interface | `{ storage, destination, executable, digest }` | Represents one file record of the vendored host's manifest. |
400
402
  | `MaterializeResult` | interface | `{ target, written, skipped, removed }` | Reports the outcome of one mutation of a target. |
401
403
  | `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
402
404
  | `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
@@ -453,8 +455,8 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
453
455
  | `isFilesystemPath` | function | `(value: unknown) => value is string` | Narrows a value to a path naming a location on this host. |
454
456
  | `isHost` | const | `Guard<Host>` | Narrows a value to one `Host`. |
455
457
  | `isHostManifest` | const | `Guard<HostManifest>` | Narrows a value to one `HostManifest`. |
458
+ | `isHostManifestEntry` | const | `Guard<HostManifestEntry>` | Narrows a value to one `HostManifestEntry`. |
456
459
  | `isInventory` | function | `(value: unknown) => value is readonly unknown[]` | Narrows a value to a working-tree inventory within the limit one target may report. |
457
- | `isManifestEntry` | const | `Guard<ManifestEntry>` | Narrows a value to one `ManifestEntry`. |
458
460
  | `isManifestRegionSet` | const | `Guard<ManifestRegionSet>` | Narrows a value to one `ManifestRegionSet`. |
459
461
  | `isMaterializerHooks` | const | `Guard<EmitterHooks<MaterializerEventMap>>` | Narrows a value to the materializer's initial listener record. |
460
462
  | `isMaterializerOptions` | const | `Guard<MaterializerOptions>` | Narrows a value to `MaterializerOptions`. |
@@ -468,56 +470,56 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
468
470
 
469
471
  #### Helpers
470
472
 
471
- | Name | Kind | Signature | Summary |
472
- | ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
473
- | `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. |
474
- | `collectIndexed` | function | `<TResult>(entries: ReadonlyArray<readonly [number, TResult]>) => readonly TResult[]` | Places each result at the index its entry names, in a fresh array. |
475
- | `computeDigest` | function | `(content: string) => string` | Computes the SHA-256 digest of text. |
476
- | `computeFileDigest` | function | `(path: string) => string \| undefined` | Computes the SHA-256 digest of one file's exact bytes. |
477
- | `computeManifestDigest` | function | `(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]) => string` | Computes the digest of a vendored host's declared membership. |
478
- | `decodeHexText` | function | `(hex: string) => string \| undefined` | Decodes exact bytes stated in hexadecimal as strict UTF-8 text. |
479
- | `filesToHost` | function | `(files: readonly HostFile[], floor: Host) => Host \| undefined` | Assembles a whole vendored host from live files and the installed floor. |
480
- | `hexToDigest` | function | `(hex: string) => string` | Projects exact bytes stated in hexadecimal to their SHA-256 digest. |
481
- | `isExactCaseFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file with exact on-disk casing. |
482
- | `isPhysicalDirectory` | function | `(path: string) => boolean` | Tests whether a path is a physical directory this package will read or write into. |
483
- | `isPhysicalFile` | function | `(path: string) => boolean` | Tests whether a path is a physical file this package will read or replace. |
484
- | `isVacant` | function | `(target: string) => boolean` | Tests whether a target is safe to write a fresh workspace into. |
485
- | `listAncestors` | function | `(path: string, limit?: number) => readonly string[]` | Lists a path followed by each directory above it, nearest first. |
486
- | `listCanonPaths` | function | `(target: string, groups: readonly Group[]) => readonly string[]` | Lists the canon paths a target holds, filtered to a plan's groups. |
487
- | `listDirectories` | function | `(root: string) => readonly string[]` | Lists a directory's descendant directories as sorted root-relative paths. |
488
- | `listFiles` | function | `(root: string) => readonly string[]` | Lists a directory's files as sorted root-relative paths. |
489
- | `matchesAnchor` | function | `(anchor: WriteAnchor) => boolean` | Tests whether a path still holds the captured directory identity. |
490
- | `matchesExecutablePath` | function | `(path: string) => boolean` | Tests whether a vendored path is one a target receives executable. |
491
- | `matchesExpectation` | function | `(expectation: WriteExpectation) => boolean` | Tests whether a destination still holds what was captured of it. |
492
- | `matchesGitPath` | function | `(path: string) => boolean` | Tests whether a path addresses a target's own repository metadata. |
493
- | `matchesMissingPath` | function | `(error: unknown) => boolean` | Tests whether a caught filesystem error reports an absent path. |
494
- | `matchesPrecondition` | function | `(precondition: WritePrecondition) => boolean` | Tests whether a destination still matches the narrower state a caller observed. |
495
- | `matchesProtectedPath` | function | `(path: string) => boolean` | Tests whether a target-relative path is one no verb may delete. |
496
- | `matchesSensitivePath` | function | `(path: string) => boolean` | Tests whether a path names local configuration or a credential. |
497
- | `pathToStorage` | function | `(path: string) => string` | Projects a target-relative path to the storage name a vendored host holds it under. |
498
- | `pruneEmptiedDirectories` | function | `(target: string, removed: readonly string[]) => readonly string[]` | Removes every directory one set of deletions emptied. |
499
- | `readAnchor` | function | `(path: string) => WriteAnchor \| undefined` | Captures one directory's physical identity. |
500
- | `readExpectation` | function | `(path: string) => WriteExpectation \| undefined` | Captures what one destination holds before a write. |
501
- | `readFileHex` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as its exact bytes in lowercase hexadecimal. |
502
- | `readFileText` | function | `(root: string, path: string, limit?: number) => string \| undefined` | Reads one contained file as bounded UTF-8 text. |
503
- | `readHostFloor` | function | `(root?: string) => Host` | Reads the installed vendored host floor as a value. |
504
- | `readHostManifest` | function | `(host: string, name?: string) => HostManifest \| undefined` | Reads a vendored host's manifest, when it carries one. |
505
- | `readManifestEntry` | function | `(destination: string, source: string) => ManifestEntry \| undefined` | Derives one vendored-host manifest entry from a file in a checkout. |
506
- | `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
507
- | `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
508
- | `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
509
- | `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
510
- | `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
511
- | `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. |
512
- | `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. |
513
- | `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
514
- | `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
515
- | `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
516
- | `resolveContainedPath` | function | `(root: string, path: string) => string \| undefined` | Resolves a root-relative path and refuses one that leaves its root. |
517
- | `resolveRealPath` | function | `(path: string) => string \| undefined` | Resolves a path through the real filesystem, keeping the part that does not exist yet. |
518
- | `stageBytes` | function | `(host: Host, root: string, destinations: readonly string[]) => readonly ManifestEntry[]` | Stages the named destinations of a value host into a private root. |
519
- | `stageHost` | function | `(checkout: string, host: string, options?: HostStageOptions) => readonly ManifestEntry[]` | Stages a vendored host root from a real checkout. |
520
- | `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. |
521
523
 
522
524
  #### Classes
523
525
 
@@ -781,7 +783,9 @@ scaffold surface ../router ../server --from . --json
781
783
 
782
784
  The comparison uses the bare identifier, case included, across declaration keywords and
783
785
  environments. A name claimed by distinct owners is a collision. A collision absent from the record,
784
- or carrying an owner absent from its recorded owner set, has `error` standing. A collision with the
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
785
789
  same or fewer owners has `recorded` standing. A recorded name that no longer collides has `closed`
786
790
  standing, so a release can shrink the record.
787
791
 
@@ -1738,7 +1742,7 @@ than a silent no-op.
1738
1742
  A plan selects over the following groups, and a compile that names none covers all of them. Their
1739
1743
  order is the order a plan lists its artifacts in.
1740
1744
 
1741
- | Group | Holds |
1745
+ | `ArtifactGroup` | Holds |
1742
1746
  | --------------- | ------------------------------------------------------------------------------------------------- |
1743
1747
  | `manifest` | `package.json` |
1744
1748
  | `configs` | The root and per-target build configuration, and the root dotfiles |
@@ -1756,7 +1760,7 @@ target that lacks the file. It also carries the skill pointer set, three host-or
1756
1760
  each name in `TARGET_SKILL_NAMES`, so every harness in a target discovers the package-facing skills
1757
1761
  while their bodies, references, and scripts stay in the installed package. Every other canon path is
1758
1762
  staged for reading, so no group selection copies a contract into a target, and a copy a target holds
1759
- at one of them is foreign drift in the group `inferGroup` gives it. A scoped audit reads the canon
1763
+ at one of them is foreign drift in the group `inferArtifactGroup` gives it. A scoped audit reads the canon
1760
1764
  through that same selection, so a run excluding a group reports nothing there.
1761
1765
 
1762
1766
  ## Ownership and drift
@@ -2029,7 +2033,7 @@ defining paths, `studies` by an exact-case `*.test.ts` file beneath `tests/studi
2029
2033
  configuration must keep those edits outside a content-owned file; `repair` restores that file to the
2030
2034
  canonical project set.
2031
2035
 
2032
- An audit reports one `Finding` per planned path, followed by every foreign path in the groups the
2036
+ An audit reports one `ArtifactFinding` per planned path, followed by every foreign path in the groups the
2033
2037
  plan covers. That second list draws on a file beneath a vendored directory the plan expands and on a
2034
2038
  file the target holds at a canon path the plan does not claim. Every planned finding carries its
2035
2039
  artifact's `ownership`. A foreign finding has no ownership because no artifact was planned for its
@@ -2045,12 +2049,12 @@ aggregate tally.
2045
2049
  The plan and snapshot are each bounded at `MAX_COLLECTION_ITEMS`. An audit may therefore carry one
2046
2050
  finding per planned artifact plus one per unplanned snapshot path, up to `MAX_AUDIT_FINDINGS`.
2047
2051
 
2048
- | `Drift` | Means |
2049
- | --------- | ------------------------------------- |
2050
- | `aligned` | The target matches the plan |
2051
- | `stale` | The target holds different bytes |
2052
- | `missing` | The target holds no file at that path |
2053
- | `foreign` | The plan does not own the path at all |
2052
+ | `ArtifactDrift` | 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 |
2054
2058
 
2055
2059
  A stale or foreign finding carries the destination's exact bytes in `observed`, and that record is
2056
2060
  the precondition the mutation is held to. A write that replaces stale bytes and a deletion that
@@ -2058,7 +2062,7 @@ removes a foreign file each fail when the destination no longer matches what the
2058
2062
  The requirement sits in the type rather than in prose, because a deletion that cannot bind to what
2059
2063
  the audit showed is the one thing the destructive verb must never do.
2060
2064
 
2061
- `isFinding` proves the shape a reader may destructure and nothing about whether the verdict is one
2065
+ `isArtifactFinding` proves the shape a reader may destructure and nothing about whether the verdict is one
2062
2066
  an audit could have reached. `repair` and `remove` re-derive every verdict themselves and act only
2063
2067
  on what they derived, so a verdict the comparison could not have produced is refused by name rather
2064
2068
  than acted on.
@@ -2423,7 +2427,7 @@ one; `.claude/AGENTS.md` § Models owns the rule.
2423
2427
  ```ts
2424
2428
  import { stageHost } from '@orkestrel/scaffold/server'
2425
2429
 
2426
- stageHost(process.cwd(), 'dist/host') // one ManifestEntry per file staged
2430
+ stageHost(process.cwd(), 'dist/host') // one HostManifestEntry per file staged
2427
2431
  ```
2428
2432
 
2429
2433
  Each staged path is copied to a storage name, and every dot that opens a segment comes off,
@@ -2455,6 +2459,12 @@ committed inventory does not already record: `stageHost` reads the baseline thro
2455
2459
  `readSurfaceBaseline` before the build rewrites the inventory, and refuses a name whose staged
2456
2460
  owner set differs from the inventory — absent from the record, or not a subset of its recorded
2457
2461
  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
2463
+ recorded owners, or beside the one owner of a name the record lacks, and the stage records that
2464
+ keeper whether or not its guide is mirrored; any other added owner is still refused. A transfer
2465
+ whose keeper alone claims the name is spent, and the stage refuses it with `TARGET`, naming the
2466
+ name, the keeper, and the item to remove from `SURFACE_TRANSFERS`. A transfer that no staged guide
2467
+ claims stays inert.
2458
2468
  A collision the baseline records and the stage no longer produces, or whose staged owners are a
2459
2469
  narrower subset of the recorded set, is accepted, so closing one needs no separate step. `HostStageOptions.inventory` selects the
2460
2470
  checkout-relative inventory path, defaulting to `HOST_INVENTORY_PATH` (`host.json`).