@orkestrel/scaffold 0.0.133 → 0.0.134

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 (82) hide show
  1. package/dist/agents/skills/orkestrel-dispatch/scripts/bench.js +61 -96
  2. package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +48 -76
  3. package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +27 -66
  4. package/dist/agents/skills/orkestrel-dispatch/scripts/cite.js +31 -64
  5. package/dist/agents/skills/orkestrel-dispatch/scripts/launch.js +43 -57
  6. package/dist/agents/skills/orkestrel-dispatch/scripts/login.js +43 -86
  7. package/dist/agents/skills/orkestrel-dispatch/scripts/patch.js +68 -104
  8. package/dist/agents/skills/orkestrel-dispatch/scripts/result.js +35 -69
  9. package/dist/agents/skills/orkestrel-dispatch/scripts/sweep.js +47 -84
  10. package/dist/agents/skills/orkestrel-falsify/scripts/mutate.js +134 -116
  11. package/dist/agents/skills/orkestrel-harden/scripts/discovery.js +38 -90
  12. package/dist/agents/skills/orkestrel-harden/scripts/interleave.js +39 -103
  13. package/dist/agents/skills/orkestrel-harden/scripts/measure.js +40 -89
  14. package/dist/agents/skills/orkestrel-harden/scripts/titles.js +41 -87
  15. package/dist/agents/skills/orkestrel-parallel/scripts/cases.js +43 -88
  16. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +1018 -194
  17. package/dist/agents/skills/orkestrel-publish/scripts/compare.js +40 -60
  18. package/dist/agents/skills/orkestrel-publish/scripts/pins.js +47 -81
  19. package/dist/agents/skills/orkestrel-publish/scripts/steps.js +66 -104
  20. package/dist/agents/skills/orkestrel-publish/scripts/swap.js +74 -88
  21. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +95 -108
  22. package/dist/agents/skills/orkestrel-publish/scripts/window.js +55 -96
  23. package/dist/agents/skills/orkestrel-scout/scripts/map.js +54 -101
  24. package/dist/bin/main.js +27 -3
  25. package/dist/bin/main.js.map +1 -1
  26. package/dist/host/agents/skills/orkestrel-dispatch/scripts/bench.ts +81 -97
  27. package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +64 -72
  28. package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +41 -63
  29. package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts +56 -79
  30. package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts +61 -74
  31. package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts +59 -89
  32. package/dist/host/agents/skills/orkestrel-dispatch/scripts/patch.ts +87 -106
  33. package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts +57 -76
  34. package/dist/host/agents/skills/orkestrel-dispatch/scripts/sweep.ts +73 -88
  35. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +2 -2
  36. package/dist/host/agents/skills/orkestrel-falsify/scripts/mutate.ts +167 -119
  37. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +1 -1
  38. package/dist/host/agents/skills/orkestrel-harden/scripts/discovery.ts +58 -75
  39. package/dist/host/agents/skills/orkestrel-harden/scripts/interleave.ts +55 -99
  40. package/dist/host/agents/skills/orkestrel-harden/scripts/measure.ts +59 -90
  41. package/dist/host/agents/skills/orkestrel-harden/scripts/titles.ts +60 -80
  42. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +4 -4
  43. package/dist/host/agents/skills/orkestrel-parallel/scripts/cases.ts +71 -108
  44. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +1288 -239
  45. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +10 -6
  46. package/dist/host/agents/skills/orkestrel-publish/scripts/compare.ts +58 -79
  47. package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +66 -87
  48. package/dist/host/agents/skills/orkestrel-publish/scripts/steps.ts +84 -102
  49. package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts +92 -99
  50. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +130 -126
  51. package/dist/host/agents/skills/orkestrel-publish/scripts/window.ts +82 -120
  52. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +3 -3
  53. package/dist/host/agents/skills/orkestrel-scout/scripts/map.ts +85 -112
  54. package/dist/host/claude/agents/orkestrel.md +4 -4
  55. package/dist/host/claude/rules/documentation.md +1 -1
  56. package/dist/host/claude/rules/patterns.md +5 -4
  57. package/dist/host/claude/rules/styles.md +1 -1
  58. package/dist/host/claude/rules/tests.md +3 -3
  59. package/dist/host/claude/rules/workspace.md +47 -35
  60. package/dist/host/configs/helpers.ts +40 -15
  61. package/dist/host/dotfiles/oxlintrc.json +62 -0
  62. package/dist/host/guides/form.md +79 -4
  63. package/dist/host/guides/scaffold.md +93 -65
  64. package/dist/host/guides/table.md +20 -6
  65. package/dist/host/guides/test.md +9 -7
  66. package/dist/host/manifest.json +44 -44
  67. package/dist/host/tests/config.test.ts +201 -11
  68. package/dist/host/tests/policy.test.ts +14 -21
  69. package/dist/host/tests/setupPolicy.ts +43 -36
  70. package/dist/src/core/index.cjs +191 -93
  71. package/dist/src/core/index.cjs.map +1 -1
  72. package/dist/src/core/index.d.cts +27 -13
  73. package/dist/src/core/index.d.ts +27 -13
  74. package/dist/src/core/index.js +189 -93
  75. package/dist/src/core/index.js.map +1 -1
  76. package/dist/src/server/index.cjs +8 -9
  77. package/dist/src/server/index.cjs.map +1 -1
  78. package/dist/src/server/index.d.cts +1 -1
  79. package/dist/src/server/index.d.ts +1 -1
  80. package/dist/src/server/index.js +8 -9
  81. package/dist/src/server/index.js.map +1 -1
  82. package/package.json +2 -2
@@ -82,39 +82,39 @@ Exported from `@orkestrel/scaffold`, and reachable from
82
82
 
83
83
  #### Interfaces
84
84
 
85
- | Name | Kind | Signature | Summary |
86
- | ----------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
87
- | `AppDefinition` | interface | `{ configs, project, entry? }` | Describes the configuration and runtime-entry settings one private `app` environment contributes. |
88
- | `ArtifactBase` | interface | `{ path, group, ownership, environment? }` | Describes the fields every planned file carries. |
89
- | `ArtifactTemplateSet` | interface | `{ source, tests, docs, guides, orchestration }` | Represents the source, test, document, guide, and service template text. |
90
- | `Audit` | interface | `{ findings, questions }` | Represents the whole comparison of a plan against a target's current content. |
91
- | `Blueprint` | interface | `{ name, description?, keywords, src, app, extensions, styles, themes, dependencies, peers, extras, version, engines, overrides, bin, setup, guides, integration, conformance, tree, service, vendors, studies, global, showcase, journey, base, skills }` | Represents the closed, JSON-serializable workspace specification. |
92
- | `BrowserExtension` | interface | `{ surface, name, axes }` | Represents a browser framework and its physically occupied axes. |
93
- | `CompileFailure` | interface | `{ code, message }` | Represents the coded reason one compile stage failed. |
94
- | `CompileRecord` | interface | `{ stage, input, output, failure? }` | Holds the input and output snapshot of one compile stage. |
95
- | `CompilerInterface` | interface | `{ emitter, compile(), audit(), destroy() }` | Describes the compilation contract: pure, synchronous, and host-independent. |
96
- | `CompilerOptions` | interface | `{ on?, error? }` | Represents the options for the compiler. |
97
- | `ConfigTemplateSet` | interface | `{ root, factories, tsconfigs, vites, browsers, commands }` | Represents the configuration template text, grouped by the artifact each template builds. |
98
- | `ContentArtifact` | interface | `{ origin, content, hex?, source? }` | Represents a text file produced by the template or computed compilation path. |
99
- | `Dependency` | interface | `{ name, range, optional? }` | Represents one runtime `@orkestrel/*` dependency of a generated workspace. |
100
- | `DependencyPinSet` | interface | `{ runtime, development }` | Describes the runtime and development sections a range-writing operation may change. |
101
- | `FrameworkDefinition` | interface | `{ plugin, checker, suffixes, refused, dependencies }` | Describes the tooling and package boundaries a browser framework contributes. |
102
- | `HostArtifact` | interface | `{ origin, ownership, source?, pointer?, hex?, content? }` | Represents a file byte-copied from the vendored data root, planned before its bytes are read. |
103
- | `HydratedArtifact` | interface | `{ origin, ownership, source?, hex, content? }` | Represents a vendored file whose exact bytes have been read, so its content can be compared. |
104
- | `ManifestDependencySet` | interface | `{ runtime, development, peer }` | Describes the runtime, development, and peer sections read from an existing package manifest. |
105
- | `ManifestEdit` | interface | `{ start, end, text }` | Represents one in-place replacement of manifest text. |
106
- | `ManifestRegionSet` | interface | `{ pins, scripts, additions?, overrides? }` | Describes the manifest regions a writing operation may change. |
107
- | `ManifestScript` | interface | `{ name, command, accepted }` | Represents one manifest script a region-writing operation may replace. |
108
- | `ManifestToken` | interface | `{ text, index, depth, value }` | Represents one string or object brace found in manifest text. |
109
- | `Override` | interface | `{ path, content }` | Represents one artifact override. |
110
- | `Plan` | interface | `{ blueprint, groups, artifacts, hash? }` | Holds the compiled, ordered artifact list and the selection it covers. |
111
- | `PlanSummary` | interface | `{ name, src, app, groups, host, template, computed }` | Represents the tally of one plan by artifact origin. |
112
- | `Question` | interface | `{ field, message, blocking, candidates? }` | Represents one validation issue raised against a blueprint or a plan. |
113
- | `CompileResult` | interface | `{ plan?, questions, stages }` | Represents the replayable outcome of one compile. |
114
- | `SrcDefinition` | interface | `{ configs, project, path, formats }` | Describes the build and export settings one published `src` environment contributes. |
115
- | `StylesExtension` | interface | `{ surface, name }` | Represents a named sheet face under `src/<name>`. |
116
- | `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
117
- | `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
85
+ | Name | Kind | Signature | Summary |
86
+ | ----------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
87
+ | `AppDefinition` | interface | `{ configs, project, entry? }` | Describes the configuration and runtime-entry settings one private `app` environment contributes. |
88
+ | `ArtifactBase` | interface | `{ path, group, ownership, environment? }` | Describes the fields every planned file carries. |
89
+ | `ArtifactTemplateSet` | interface | `{ source, tests, docs, guides, orchestration }` | Represents the source, test, document, guide, and service template text. |
90
+ | `Audit` | interface | `{ findings, questions }` | Represents the whole comparison of a plan against a target's current content. |
91
+ | `Blueprint` | interface | `{ name, description?, keywords, src, app, extensions, styles, themes, dependencies, peers, extras, version, engines, overrides, bin, reporter, setup, guides, integration, conformance, tree, service, vendors, studies, global, showcase, journey, base, skills }` | Represents the closed, JSON-serializable workspace specification. |
92
+ | `BrowserExtension` | interface | `{ surface, name, axes }` | Represents a browser framework and its physically occupied axes. |
93
+ | `CompileFailure` | interface | `{ code, message }` | Represents the coded reason one compile stage failed. |
94
+ | `CompileRecord` | interface | `{ stage, input, output, failure? }` | Holds the input and output snapshot of one compile stage. |
95
+ | `CompilerInterface` | interface | `{ emitter, compile(), audit(), destroy() }` | Describes the compilation contract: pure, synchronous, and host-independent. |
96
+ | `CompilerOptions` | interface | `{ on?, error? }` | Represents the options for the compiler. |
97
+ | `ConfigTemplateSet` | interface | `{ root, factories, tsconfigs, vites, browsers, commands }` | Represents the configuration template text, grouped by the artifact each template builds. |
98
+ | `ContentArtifact` | interface | `{ origin, content, hex?, source? }` | Represents a text file produced by the template or computed compilation path. |
99
+ | `Dependency` | interface | `{ name, range, optional? }` | Represents one runtime `@orkestrel/*` dependency of a generated workspace. |
100
+ | `DependencyPinSet` | interface | `{ runtime, development }` | Describes the runtime and development sections a range-writing operation may change. |
101
+ | `FrameworkDefinition` | interface | `{ plugin, checker, suffixes, refused, dependencies }` | Describes the tooling and package boundaries a browser framework contributes. |
102
+ | `HostArtifact` | interface | `{ origin, ownership, source?, pointer?, hex?, content? }` | Represents a file byte-copied from the vendored data root, planned before its bytes are read. |
103
+ | `HydratedArtifact` | interface | `{ origin, ownership, source?, hex, content? }` | Represents a vendored file whose exact bytes have been read, so its content can be compared. |
104
+ | `ManifestDependencySet` | interface | `{ runtime, development, peer }` | Describes the runtime, development, and peer sections read from an existing package manifest. |
105
+ | `ManifestEdit` | interface | `{ start, end, text }` | Represents one in-place replacement of manifest text. |
106
+ | `ManifestRegionSet` | interface | `{ pins, scripts, additions?, overrides? }` | Describes the manifest regions a writing operation may change. |
107
+ | `ManifestScript` | interface | `{ name, command, accepted }` | Represents one manifest script a region-writing operation may replace. |
108
+ | `ManifestToken` | interface | `{ text, index, depth, value }` | Represents one string or object brace found in manifest text. |
109
+ | `Override` | interface | `{ path, content }` | Represents one artifact override. |
110
+ | `Plan` | interface | `{ blueprint, groups, artifacts, hash? }` | Holds the compiled, ordered artifact list and the selection it covers. |
111
+ | `PlanSummary` | interface | `{ name, src, app, groups, host, template, computed }` | Represents the tally of one plan by artifact origin. |
112
+ | `Question` | interface | `{ field, message, blocking, candidates? }` | Represents one validation issue raised against a blueprint or a plan. |
113
+ | `CompileResult` | interface | `{ plan?, questions, stages }` | Represents the replayable outcome of one compile. |
114
+ | `SrcDefinition` | interface | `{ configs, project, path, formats }` | Describes the build and export settings one published `src` environment contributes. |
115
+ | `StylesExtension` | interface | `{ surface, name }` | Represents a named sheet face under `src/<name>`. |
116
+ | `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
117
+ | `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
118
118
 
119
119
  | Name | Kind | Signature | Summary |
120
120
  | ------------------- | --------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
@@ -133,7 +133,6 @@ Exported from `@orkestrel/scaffold`, and reachable from
133
133
  | Name | Kind | Signature | Summary |
134
134
  | --------------------------------- | ----- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
135
135
  | `APP_BROWSER_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies a private browser application adds. |
136
- | `APP_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Names the development dependency every private `app` environment adds. |
137
136
  | `APP_MATRIX` | const | `Readonly<Record<Environment, AppDefinition>>` | Holds the configuration and runtime-entry settings each private `app` environment contributes, frozen. |
138
137
  | `APP_SERVER_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies a private server application adds. |
139
138
  | `ARTIFACT_GROUPS` | const | `readonly ArtifactGroup[]` | Lists the `ArtifactGroup` values in plan order, frozen. |
@@ -201,6 +200,9 @@ Exported from `@orkestrel/scaffold`, and reachable from
201
200
  | `PRINT_WIDTH` | const | `100` | Caps the columns one emitted line may occupy, matching `printWidth` in `.oxfmtrc.json`. |
202
201
  | `REFERENCE_PATHS` | const | `readonly string[]` | Lists the reference paths staged for offline reading, frozen. |
203
202
  | `RELEASE_PROOF_COMMAND` | const | `"npm run test:distribution -- --mode release"` | Names the `prepublishOnly` row that runs the packed-package proof against a real registry. |
203
+ | `REPORTER_CONFIGS` | const | `readonly string[]` | Lists the configuration files a workspace that publishes a Vitest reporter adds, frozen. |
204
+ | `REPORTER_ENTRY_PATH` | const | `"src/reporter/main.ts"` | Names the reporter entry whose presence makes a workspace `reporter`. |
205
+ | `REPORTER_OUTPUT_PATH` | const | `"dist/reporter/main.js"` | Names the built reporter module a reporter workspace's `./reporter` export loads. |
204
206
  | `RESERVED_SHEET_NAMES` | const | `readonly string[]` | Lists the names a styles extension cannot occupy, frozen. |
205
207
  | `SEED_GUIDE_PATHS` | const | `readonly string[]` | Lists the guide paths a generated workspace starts with, frozen. |
206
208
  | `SERVICE_SCRIPT_PATH` | const | `"scripts/service.sh"` | Names the inventory skeleton a workspace with declared service vendors is given once. |
@@ -333,7 +335,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
333
335
  | `blueprintToDevDependencies` | function | `(blueprint: Blueprint) => Readonly<Record<string, string>>` | Projects a blueprint into the development dependencies its manifest declares. |
334
336
  | `blueprintToToolchainHolds` | function | `(blueprint: Blueprint) => Readonly<Record<string, ToolchainHold>>` | Projects a blueprint into the toolchain holds its browser frameworks require. |
335
337
  | `blueprintToDocumentArtifacts` | function | `(blueprint: Blueprint) => readonly ContentArtifact[]` | Compiles the generated workspace's root documentation. |
336
- | `blueprintToExports` | function | `(blueprint: Blueprint) => Readonly<Record<string, unknown>>` | Projects published environments and sheets into the manifest export map. |
338
+ | `blueprintToExports` | function | `(blueprint: Blueprint) => Readonly<Record<string, unknown>>` | Projects published environments, sheets, and the reporter entry into the manifest export map. |
337
339
  | `blueprintToFaces` | function | `(blueprint: Blueprint) => readonly BrowserExtension[]` | Projects a blueprint into browser extensions restricted to occupied browser axes. |
338
340
  | `blueprintToGuideArtifacts` | function | `(blueprint: Blueprint) => readonly ContentArtifact[]` | Compiles the generated workspace's guide index. |
339
341
  | `blueprintToHostArtifacts` | function | `(blueprint: Blueprint) => readonly Artifact[]` | Compiles the vendored host artifacts a workspace plans. |
@@ -697,9 +699,25 @@ files on `main`, the scaffold repository's `host.json` file, and changed vendore
697
699
  `ORKESTREL_SCAFFOLD_REPOSITORY` replaces the repository base. These settings change which host
698
700
  answers a read and grant no verb write authority that it did not already have.
699
701
 
700
- `new --bin` creates the executable entry, its test, and its scoped Vite and TypeScript wrappers. The
701
- `new --app browser` command selects the journey axis, creates its birth-owned wrapper, defines
702
- `appJourney` in the root configuration, and excludes the browser integration suite from
702
+ `new --bin` creates the executable entry, its test, and its scoped Vite and TypeScript wrappers.
703
+
704
+ A Vitest reporter takes no creation option. Write `src/reporter/main.ts`, the one reporter entry a
705
+ package holds, as an import of the reporter class from `@src/server` followed by `export default`
706
+ of that class, because Vitest's `--reporter=<specifier>` constructs the module's default export.
707
+ The reading verbs then select `reporter`. The manifest exports `./reporter` as the ES-only
708
+ `dist/reporter/main.js` with its `main.d.ts`, packs `dist/reporter`, and declares
709
+ `check:src:reporter`, `build:src:reporter`, and `test:src:reporter`. The root configuration adds the
710
+ `srcReporter` factory and the `src:reporter` project over `tests/src/reporter`, and the selection
711
+ adds `configs/src/vite.reporter.config.ts` and `configs/src/tsconfig.reporter.json`. The reporter
712
+ build keeps every `@src/*` specifier external and rewrites it through `output.paths` to the built
713
+ `../src/<environment>/index.js`. The vendored `.oxlintrc.json` exempts `src/reporter/main.ts`, and
714
+ no other path, from `import/no-default-export`, and refuses a relative import of `src/core` or
715
+ `src/server` from `src/reporter`, which would bundle a second copy of the class. The distribution
716
+ proof reads `dist/reporter` as its own face and reports a server source copied into it. A consumer
717
+ runs it as `--reporter=@orkestrel/<name>/reporter`.
718
+
719
+ The `new --app browser` command selects the journey axis, creates its birth-owned wrapper,
720
+ defines `appJourney` in the root configuration, and excludes the browser integration suite from
703
721
  `app:browser`. Its manifest declares `test:journey`. A `private: true` workspace invokes it after
704
722
  `npm run test:app` in `test`; a publishing workspace runs application and journey suites on demand,
705
723
  outside release gates and chains. It also declares `journey: capture journey` and `capture: capture frames` for explicit
@@ -771,7 +789,8 @@ environment's export a distinct name. The record never holds a conflict, so a co
771
789
  run that reads its owner as a candidate.
772
790
 
773
791
  A candidate refuses, naming its path, when its manifest is unreadable, when it has neither its guide
774
- nor `src/`, when its guide exists but is not UTF-8 text within the artifact bound, or when a
792
+ nor `src/` (an app-only workspace, which publishes no surface and relies on its `test:policy`
793
+ `surface` rule), when its guide exists but is not UTF-8 text within the artifact bound, or when a
775
794
  TypeScript source under `src/` cannot be read. Only `.ts` files under `src/` are read, so a binary
776
795
  asset there is ignored. A barrel holding a statement other than `export * from './module.js'`
777
796
  refuses with the statement named, because the reflection follows nothing else and an incomplete
@@ -877,7 +896,7 @@ and the declared `@orkestrel/*` packages come from `package.json`. The environme
877
896
  the directories the target actually ships, because a directory is the fact and a declaration beside
878
897
  it could disagree. The styles surface, its themes target, the showcase, and every extension are
879
898
  read from the markers Surfaces and extensions lists. The remaining facts come from exact-case
880
- files: `src/bin/main.ts` selects `bin`, each root `tests/setup*.test.ts` match selects `setup`,
899
+ files: `src/bin/main.ts` selects `bin`, `src/reporter/main.ts` selects `reporter`, each root `tests/setup*.test.ts` match selects `setup`,
881
900
  `tests/guides.test.ts` selects `guides`, `tests/integration.test.ts` selects `integration`,
882
901
  `tests/conformance.test.ts` selects `conformance`, `tests/tree.test.ts` selects `tree`,
883
902
  `tests/setupService.ts` selects `service`,
@@ -1010,9 +1029,12 @@ chain invokes `test:app`. A chain whose planned form adds an
1010
1029
  aggregate the manifest lacks stays with the package, and the `projects` question keeps its remedy.
1011
1030
  `audit` reports this `test` chain write only through the `projects` question, so a planned step that
1012
1031
  registers no Vitest project, such as `npm run test:guides`, lands on the next `repair` without an
1013
- earlier advisory. `audit` reports no `build:app` chain write, so in a barrel workspace only the
1014
- `scripts` question's report of a missing `build:app:barrel` script precedes that write. A `test` or
1015
- `build:app` chain running any other step or order stays maintainer-owned, as do the
1032
+ earlier advisory. `audit` reports no `build:app` chain write, so `repair` rewrites a predecessor
1033
+ `build:app` with no earlier advisory after `build:app:barrel` is declared, and before then only the
1034
+ `scripts` question's report of a missing `build:app:barrel` script precedes that write. A
1035
+ package-owned `build:app` chain that omits the barrel step stays with the package, and the `scripts`
1036
+ question reports that no chain from `build` reaches `build:app:barrel`. A `test` or `build:app` chain
1037
+ running any other step or order stays maintainer-owned, as do the
1016
1038
  `check`, `build`, `dev`, `serve`, `format`, `lint`, `clean`, and `copy` gate chains. A
1017
1039
  declared value is overwritten only when it is already the value being written or is a recognized
1018
1040
  generated predecessor. The overwrite happens in place,
@@ -1242,7 +1264,7 @@ a fleet pin; every other peer is a floor. `extras` are development dependencies
1242
1264
  valid npm name. A peer reaches the generated workspace through separate representations:
1243
1265
  `Blueprint.peers` validates the scope rule and compiles the manifest declarations, while the
1244
1266
  `peers` binding in the generated `vite.config.ts` derives from the target's live
1245
- `peerDependencies`. Each published build face — core, browser, server, and `bin` — externalizes
1267
+ `peerDependencies`. Each published build face — core, browser, server, `bin`, and `reporter` — externalizes
1246
1268
  every name in that binding, so a peer the workspace declares by hand, such as `vitest`, is left as
1247
1269
  an import in the emitted bundle rather than inlined into it.
1248
1270
 
@@ -1273,8 +1295,8 @@ because the shape is chosen once and read afterwards: `new` refuses the advisory
1273
1295
  `repair` need the plan to describe and restore a target that already has that shape. A library
1274
1296
  caller creating a workspace holds the same refusal, and the Compile section states it.
1275
1297
 
1276
- `bin`, `setup`, `guides`, `integration`, `conformance`, `tree`, `service`, `vendors`, `studies`,
1277
- `global`, `styles`, `themes`, `showcase`, `journey`, `base`, and `skills` are structural facts, and `extensions` lists the
1298
+ `bin`, `reporter`, `setup`, `guides`, `integration`, `conformance`, `tree`, `service`, `vendors`,
1299
+ `studies`, `global`, `styles`, `themes`, `showcase`, `journey`, `base`, and `skills` are structural facts, and `extensions` lists the
1278
1300
  extension faces. Reading verbs set each fact and list each extension only when the workspace
1279
1301
  physically ships the directory or exact-case file that defines it, never because of the workspace's
1280
1302
  name and never because a sibling fact is set.
@@ -1448,8 +1470,8 @@ workspace carries:
1448
1470
  `BrowserExtension.axes` lists the axes a browser extension physically occupies, so a target holding
1449
1471
  `app/vue` and no `src/vue` carries `axes: ['app']`. `FRAMEWORKS` holds `vue` alone. A
1450
1472
  `StylesExtension` name passes `isSheetName`: it matches `NAME_PATTERN` and is none of the
1451
- `RESERVED_SHEET_NAMES` values, which are `core`, `browser`, `server`, `bin`, `styles`, `themes`, and
1452
- `vue`.
1473
+ `RESERVED_SHEET_NAMES` values, which are `core`, `browser`, `server`, `bin`, `reporter`, `styles`,
1474
+ `themes`, and `vue`.
1453
1475
 
1454
1476
  `parseExtension` reads one `surface:name` entry, and `isSurface` decides whether its surface is
1455
1477
  one the generator plans, so `styles:print` parses and `themes:print` does not. Browser text carries
@@ -1600,8 +1622,8 @@ The `vue` extension gives each axis it occupies a face of its own:
1600
1622
  `check` script typechecks the whole tree through `vue-tsc` in place of `tsc`.
1601
1623
 
1602
1624
  The vendored `.oxlintrc.json` holds each face to the import direction `AGENTS.md` § Project model fixes, and
1603
- refuses, from `src/browser`, `src/server`, `src/vue`, and `src/bin`, a relative path to `src/core`, to
1604
- `src/browser` from `src/vue`, or to `src/server` from `src/bin` with a message naming the alias, because a face's
1625
+ refuses, from `src/browser`, `src/server`, `src/vue`, `src/bin`, and `src/reporter`, a relative path to
1626
+ `src/core`, to `src/browser` from `src/vue`, or to `src/server` from `src/bin` or `src/reporter` with a message naming the alias, because a face's
1605
1627
  build bundles what a relative path reaches. The vendored
1606
1628
  `tests/config.test.ts` drives those directions through Oxlint.
1607
1629
 
@@ -1700,14 +1722,14 @@ A workspace that selects `studies` and the `server` application also builds the
1700
1722
  `build:app:barrel` script exist only under that condition, and `build:app` runs the script after
1701
1723
  `build:app:server`. `serve:build` runs `build` before `serve`, so the barrel, which the server
1702
1724
  build's emptied `dist/app/server` would otherwise lose, and every browser face the server serves are
1703
- rebuilt. The build emits the single file `dist/app/server/index.js` with `@app/*` and
1704
- `@src/*` specifiers and relative imports inlined, and `node:` and every installed package specifier
1705
- left external. It sets `emptyOutDir` to `false`, so `main.cjs` stays byte-identical. A workspace
1706
- without both conditions plans none of the three. Scaffold's `tests/src/core/templates.test.ts` builds both entries in a
1707
- staged root, compares the `main.cjs` digest across the barrel step, builds the barrel twice for one
1708
- `index.js` digest, imports the file in Node, and holds each claim under a control. The vendored
1709
- `tests/config.test.ts` repeats the externals, digest, and `main.cjs` readings in each target that
1710
- plans the barrel.
1725
+ rebuilt. The build emits the single file `dist/app/server/index.js` with `@app/*` and `@src/*`
1726
+ specifiers and relative imports inlined, and `node:` and every installed package specifier left
1727
+ external. It sets `emptyOutDir` to `false`, so `main.cjs` stays byte-identical. A workspace without
1728
+ both conditions plans none of the three. Scaffold's `tests/src/core/templates.test.ts` builds both
1729
+ entries in a staged root, compares the `main.cjs` digest across the barrel step, builds the barrel
1730
+ twice for one `index.js` digest, imports the file in Node, and holds each claim under a control.
1731
+ The vendored `tests/config.test.ts` repeats the externals, digest, and `main.cjs` readings in each
1732
+ target that plans the barrel.
1711
1733
 
1712
1734
  ### The migration guard
1713
1735
 
@@ -1889,7 +1911,7 @@ bytes.
1889
1911
  You own `tests/setup.ts`, the selected `tests/setupBrowser.ts`, `tests/setupServer.ts`,
1890
1912
  `tests/setupService.ts`, `tests/setupStyles.ts`, and `tests/setupGlobal.ts` modules, each root
1891
1913
  `tests/setup*.test.ts` proof, the selected environment and sheet-face entry tests under `tests/src`
1892
- and `tests/app`, the `tests/src/bin/main.test.ts` file, and the `tests/integration.test.ts` seed.
1914
+ and `tests/app`, the `tests/src/bin/main.test.ts` and `tests/src/reporter/main.test.ts` files, and the `tests/integration.test.ts` seed.
1893
1915
  Every sheet face's seed under `src` is yours on the same terms. Scaffold writes those
1894
1916
  planned files only during materialize and leaves later edits or deletions alone. You also own the
1895
1917
  `tests/guides.test.ts`, `tests/conformance.test.ts`, `tests/tree.test.ts`, and
@@ -2007,8 +2029,10 @@ declaration, a binding that is not an identifier, a barrel statement outside the
2007
2029
  A missing guide root, an empty catalog, a catalog row with no hosted guide, and a hosted guide
2008
2030
  carrying no `Surface` section report one the same way, so a reading the sweep could not complete
2009
2031
  never reports clean. A collision reads
2010
- `surface name belongs to one package: NAME (OWNER)` and carries the declaring path and line, sorted
2011
- by path, line, and message. Which package keeps a claimed name is the answer
2032
+ `surface name belongs to one package: NAME (OWNER)`, then the correction: delete the local declaration
2033
+ and `import { NAME } from "@orkestrel/OWNER"` (or the owner's environment entry that exports it)
2034
+ where the contracts match, and rename only where the local contract differs. It carries the
2035
+ declaring path and line, sorted by path, line, and message. Which package keeps a claimed name is the answer
2012
2036
  `.claude/rules/names.md` § Fleet name ownership gives; the rule carries no allowlist and no
2013
2037
  suppression.
2014
2038
 
@@ -2029,6 +2053,7 @@ set is reachable through a published specifier.
2029
2053
  | `POLICY_SURFACE_HOST` | const | Names the installed host root containing the fleet's reference guides. |
2030
2054
  | `createPolicySurfaceFixture` | function | Creates a scratch target with a complete installed guide population. |
2031
2055
  | `createPolicySurfaceGuide` | function | Creates a guide whose surface claims the supplied fixture names. |
2056
+ | `describeSurfaceCollision` | function | Describes the refusal for a name that two packages claim, with the owner's import. |
2032
2057
  | `inspectPolicySurface` | function | Inspects source and target-owned setup names against the hosted fleet guides. |
2033
2058
  | `readPolicyDeclarations` | function | Locates parsed exports at their physical declaration lines. |
2034
2059
  | `readPolicySurface` | function | Reads reachable source declarations and refuses unread barrel statements or targets. |
@@ -2599,10 +2624,10 @@ Nothing is fixed except the manifest.
2599
2624
  `--ignore-scripts` to `npm pack` so a suite never re-runs the build it already gates.
2600
2625
  - One template artifact per configuration file the selection needs: the root `tsconfig.json` and
2601
2626
  `vite.config.ts`, plus a Vite config and a scoped TypeScript config per selected environment and
2602
- for `bin` when it is set. The root `tsconfig.json` maps the `@src` and `@app` aliases the selection
2627
+ for `bin` and for `reporter` when each is set. The root `tsconfig.json` maps the `@src` and `@app` aliases the selection
2603
2628
  reaches, and beside them the workspace's own published specifiers — `@orkestrel/<name>` and one
2604
- `@orkestrel/<name>/<environment>` entry per subpath the `exports` map publishes — each to its
2605
- source entry. Without them the workspace's own name resolves through that `exports` map to
2629
+ `@orkestrel/<name>/<environment>` entry per environment subpath the `exports` map publishes —
2630
+ each to its source entry. The `./reporter` subpath and each sheet subpath map no entry. Without them the workspace's own name resolves through that `exports` map to
2606
2631
  `dist/`, and `npm run check` would wait on `npm run build`. Every subpath is written before the
2607
2632
  bare specifier, because `vite.config.ts` derives its `alias` record from these entries in order and
2608
2633
  a bare specifier also matches its own subpaths. An `app` environment publishes nothing and maps no
@@ -2740,7 +2765,10 @@ compiler API of its own. The browser and server faces pass `rewriteCoreSpecifier
2740
2765
  emits the `@src/core` specifier unrewritten and the extractor keeps it external, so the rewrite
2741
2766
  replaces it with the workspace's own published name and a consumer of the packed face reaches core
2742
2767
  through the root export the tarball declares. The seeded `bin` config calls no roll-up, because an
2743
- executable ships no declarations.
2768
+ executable ships no declarations. The reporter config passes `rewriteServerSpecifier`, which
2769
+ replaces `@src/server` with `../src/server/index.js`, so `dist/reporter/main.d.ts` reads the server
2770
+ declarations at the path `dist/reporter/main.js` imports. The roll-up takes the entry's own name,
2771
+ so a face ships `index.d.ts` and the reporter ships `main.d.ts`.
2744
2772
 
2745
2773
  `planToSummary` reports the tally rather than a number written down here:
2746
2774
 
@@ -320,7 +320,7 @@ The entity, its managers, its factory, its contract, and the error it raises.
320
320
  | `FilterManagerInterface` | interface | `{ filter(), filters(), set(), remove() }` | Manages which rows a grid keeps. |
321
321
  | `SelectionManagerInterface` | interface | `{ keys, select(), clear(), toggle() }` | Manages the rows somebody has picked. |
322
322
  | `ExpansionManagerInterface` | interface | `{ keys, expand(), clear(), toggle() }` | Manages the rows somebody has opened up. |
323
- | `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), resize() }` | Manages which stretch of the filtered rows the view shows. |
323
+ | `PaginationManagerInterface` | interface | `{ page, limit, offset, count, move(), locate(), resize() }` | Manages which stretch of the filtered rows the view shows. |
324
324
  | `GridError` | class | `new (code: GridErrorCode, message: string, context?: JSONRecord) => GridError` | Represents an error raised by the grid domain — a machine-readable `code` and optional structured `context`. |
325
325
  | `GridErrorCode` | type | `'SCHEMA' \| 'COLUMN' \| 'KEY' \| 'CELL' \| 'DESTROYED'` | Names the reason a `GridError` carries — the machine-readable code a `catch` branches on. |
326
326
  | `isGridError` | function | `(input: unknown) => input is GridError` | Determines whether a caught value is a grid error, so a `catch` branches on `code` without an assertion. |
@@ -971,6 +971,10 @@ the filter admits, so nothing here can drift out of step with what the grid hold
971
971
  "page 1 of 1" over an empty list needs no separate case for it.
972
972
  - A page beyond the last one clamps to the last one. Narrowing the filter therefore moves the page
973
973
  on its own, and moving to page 9 of 3 shows page 3 rather than nothing.
974
+ - `locate` names the page that holds one row under the current filter and sort, so a host turns to
975
+ a row with `move(locate(key))` and keeps no copy of the lens to work it out. An unpaged grid
976
+ answers `1`, and a key the filter hides or no row holds answers `undefined`, never a page the
977
+ row is not on. `locate` moves nothing.
974
978
  - `resize` keeps the first row the view was showing, so the page moves to wherever that row
975
979
  falls. Resizing is a change of magnification, not a jump to the top.
976
980
 
@@ -988,6 +992,13 @@ grid.pagination.page // 3 — clamped to the last page
988
992
  grid.pagination.offset // 4
989
993
  grid.view.map((row) => row.id) // ['5']
990
994
 
995
+ grid.pagination.locate('3') // 2 — rows 3 and 4 fill the second page
996
+ grid.pagination.locate('9') // undefined — no row holds that key
997
+ grid.filter.set({ column: 'id', operator: 'contains', text: '5' })
998
+ grid.pagination.locate('3') // undefined — the filter hides the row
999
+ grid.pagination.locate('5') // 1 — one admitted row fills one page
1000
+ grid.filter.remove()
1001
+
991
1002
  grid.pagination.resize()
992
1003
  grid.pagination.limit // undefined — not paged
993
1004
  grid.view.length // 5
@@ -1503,10 +1514,11 @@ it either way.
1503
1514
 
1504
1515
  #### `PaginationManagerInterface`
1505
1516
 
1506
- | Method | Returns | Summary |
1507
- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
1508
- | `move` | `void` | Shows another page, counted from one and clamped to the pages that exist. |
1509
- | `resize` | `void` | Sets how many rows a page holds, keeping the first row the view was showing. Leave the argument out to stop paging. |
1517
+ | Method | Returns | Summary |
1518
+ | -------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
1519
+ | `move` | `void` | Shows another page, counted from one and clamped to the pages that exist. |
1520
+ | `locate` | `number` or `undefined` | Finds the page that holds one row under the current filter and sort. |
1521
+ | `resize` | `void` | Sets how many rows a page holds, keeping the first row the view was showing. Leave the argument out to stop paging. |
1510
1522
 
1511
1523
  ### Errors
1512
1524
 
@@ -1623,7 +1635,9 @@ These invariants hold across [`src/core`](../src/core) and this guide.
1623
1635
  `offset` is `(page - 1) * limit` and zero when unpaged; `count` is `max(1, ceil(rows / limit))`
1624
1636
  and `1` when unpaged — so a paged grid with no admitted rows holds one page, and that page's
1625
1637
  `view` is empty. A page beyond the last clamps to the last, including when a filter or a removal
1626
- shrinks the rows underneath it. `resize` keeps the first row the view was showing.
1638
+ shrinks the rows underneath it. `locate` is derived the same way: the page of a key among the rows
1639
+ the filter admits, in the order the sort gives them, `1` when unpaged, and `undefined` for a
1640
+ key the filter hides or no row holds. `resize` keeps the first row the view was showing.
1627
1641
  14. **Every event fires after commit, and a no-op is silent.** No listener sees a state the grid has
1628
1642
  not finished writing, and a call that moves nothing announces nothing — the same sort term twice,
1629
1643
  a toggle back to where it was, a `move` to the index a row already occupies. When one call moves
@@ -1051,7 +1051,7 @@ The provider command consumes the browser journey's resolved selector inside Vit
1051
1051
  | `requireContained` | function | `(root: string, target: string) => string` | Resolves a target that stays below a root directory, refusing a path outside it. |
1052
1052
  | `hasScratchPath` | function | `(root: string, target: string) => boolean` | Reports whether a contained entry exists under a scratch directory without following its final link. |
1053
1053
  | `isExcluded` | function | `(key: string, exclusions: readonly string[]) => boolean` | Reports whether a root-relative key matches an exclusion. |
1054
- | `readIdentity` | function | `(status: Stats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1054
+ | `readIdentity` | function | `(status: BigIntStats) => ScratchIdentity` | Reads the identity of one allocated directory off a host status. |
1055
1055
  | `matchesIdentity` | function | `(current: ScratchIdentity, allocation: ScratchIdentity) => boolean` | Reports whether two directory identities name the same allocation. |
1056
1056
  | `readErrorCode` | function | `(error: unknown) => string \| undefined` | Reads the `code` an unknown thrown value carries. |
1057
1057
  | `createLink` | function | `(path: string, source: string) => void` | Creates a symbolic link with a directory-junction fallback for hosts that refuse symbolic links. |
@@ -1106,7 +1106,9 @@ All three fields are compared because none of them alone identifies an allocatio
1106
1106
  shared by every directory on one filesystem, an index node is reused after its directory is removed,
1107
1107
  and a creation time repeats within the host's timestamp resolution. It is exported so a fixture that
1108
1108
  manages its own directory can make the same check rather than trusting a path. `readIdentity` reads
1109
- that triple off a `node:fs` `Stats`, and it is the one reading `createScratch` takes at allocation,
1109
+ that triple off a `node:fs` `BigIntStats` taken with `{ bigint: true }`, with the creation time in
1110
+ nanoseconds as `birthtimeNs`. A number `Stats` rounds a file identifier past 2^53, and two distinct
1111
+ entries then compare equal. `readIdentity` is the one reading `createScratch` takes at allocation,
1110
1112
  before a `remove`, and before a `destroy`, so the three sites cannot drift on which fields name an
1111
1113
  allocation.
1112
1114
 
@@ -1678,8 +1680,8 @@ These hold across `src/core`, `src/browser`, `src/server`, and this guide.
1678
1680
  reads the entry and then removes the path as separate steps, so an allocation swapped between
1679
1681
  them is removed anyway; whoever swaps it runs as the same uid, which is the population the threat
1680
1682
  model already declines to defend against. And birth time is the host's to supply. This host
1681
- supplies a real one — the allocation's `birthtimeMs` does not move when files are written into
1682
- it, while its `ctimeMs` does — so `destroy()` is sound here. Where a host has none, libuv reports
1683
+ supplies a real one — the allocation's `birthtimeNs` does not move when files are written into
1684
+ it, while its `ctimeNs` does — so `destroy()` is sound here. Where a host has none, libuv reports
1683
1685
  `ctime` in its place, the first seeded write moves it, and `destroy()` takes its early return. It
1684
1686
  returns `void`, so that refusal is indistinguishable from success and the allocation leaks
1685
1687
  silently.
@@ -4439,11 +4441,11 @@ Each entry names the contracts its file proves. The test names carry the cases.
4439
4441
  contained relative and absolute targets and both spellings of a path outside the root, and `requireContained`
4440
4442
  takes the same contained pair and each path outside the root refused with the message naming the target it was
4441
4443
  given. `readIdentity` takes a real
4442
- allocation's three fields, that allocation matching itself across a `stat` and an `lstat`, and a
4444
+ allocation's three bigint fields, that allocation matching itself across a `stat` and an `lstat`, and a
4443
4445
  second allocation reading as a different identity. `readErrorCode` takes a real `ENOENT` off the
4444
4446
  host, a plain object, an `Error` carrying a non-string `code` and one carrying none, a
4445
4447
  null-prototype record, and the values that are not objects at all. `matchesIdentity` takes a triple
4446
- matching in every field and one differing in each. `isExcluded` takes a key, an ancestor, the root, and a sibling that only
4448
+ matching in every field, one differing in each, and two index nodes that differ only past 2^53. `isExcluded` takes a key, an ancestor, the root, and a sibling that only
4447
4449
  looks like a match. `readInventory` takes key order, extension filtering, exclusion at the named
4448
4450
  door and at the walked one with its spellings normalized to one rule, each of its link refusals
4449
4451
  with a contained intermediate link as the control on the intermediate-link one, a root-level
@@ -4483,7 +4485,7 @@ Each entry names the contracts its file proves. The test names carry the cases.
4483
4485
  `ensure` takes an empty directory, every missing parent, and a repeated call. `link` takes
4484
4486
  traversal through a planted link, the final segment `has` reports rather than follows, and the
4485
4487
  `EEXIST` an occupied final segment throws. `remove` takes a file beside a kept
4486
- sibling, an empty directory, a populated subtree, a missing target, an ancestor link back to the
4488
+ sibling, a file written immediately after allocation, an empty directory, a populated subtree, a missing target, an ancestor link back to the
4487
4489
  allocation with every seeded file read back afterwards, a final link whose destination is read back
4488
4490
  afterwards, a sibling directory reached through that same ancestor link, a target outside the root with
4489
4491
  the file outside left intact, the root refused as `''`, as `'.'`, and as its absolute path, a