@orkestrel/scaffold 0.0.116 → 0.0.118

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.
@@ -168,6 +168,7 @@ registry copy over any staged tip, so every consumer stays red until that tip is
168
168
  ## Prepare a layer
169
169
 
170
170
  - After the re-pin and before `prepublishOnly`, run `scaffold surface` live over every candidate checkout of the layer, never with `--offline`. Stop the upload on any exit but `0`, and resolve every name it reports under `.claude/rules/names.md` § Fleet name ownership. In scaffold's own layer, run `scaffold catalog` and then `scaffold surface --from .`.
171
+ - When `scaffold surface` prints an advisory, rule it under `.claude/rules/names.md` § Fleet name ownership before the upload; an advisory never stops the upload.
171
172
  - Begin each release chain plan with the clean reinstall and the clean, whether it runs in a clone or the checkout.
172
173
  - When a writer owns a script the preparation needs, run its installed built twin and record the executable's identity.
173
174
  - Derive each release row's ruling from the measured distribution comparison and final runtime-range result under § Rule on the bump.
@@ -56,7 +56,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
56
56
  | `@orkestrel/database` | `0.0.19` | L2 | `@orkestrel/sqlite` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/indexeddb` `^0.0.15` | |
57
57
  | `@orkestrel/emitter` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
58
58
  | `@orkestrel/form` | `0.0.14` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
59
- | `@orkestrel/guide` | `0.0.26` | L3 | `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18` | |
59
+ | `@orkestrel/guide` | `0.0.28` | L3 | `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18` | |
60
60
  | `@orkestrel/html` | `0.0.13` | L1 | `@orkestrel/contract` `^0.0.20` | |
61
61
  | `@orkestrel/indexeddb` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
62
62
  | `@orkestrel/interpret` | `0.0.18` | L3 | `@orkestrel/reason` `^0.0.15`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/template` `^0.0.11` | |
@@ -77,7 +77,7 @@ Treat generated package identifiers, versions, layers, and dependency ranges as
77
77
  | `@orkestrel/reason` | `0.0.15` | L2 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
78
78
  | `@orkestrel/relation` | `0.0.17` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/database` `^0.0.19` | |
79
79
  | `@orkestrel/router` | `0.0.18` | L2 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/contract` `^0.0.20` | |
80
- | `@orkestrel/scaffold` | `0.0.115` | L3 | `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18`, `@orkestrel/template` `^0.0.11` | |
80
+ | `@orkestrel/scaffold` | `0.0.116` | L3 | `@orkestrel/console` `^0.0.17`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20`, `@orkestrel/markdown` `^0.0.18`, `@orkestrel/template` `^0.0.11` | |
81
81
  | `@orkestrel/sea` | `0.0.20` | L3 | `@orkestrel/emitter` `^0.0.13`, `@orkestrel/process` `^0.0.16`, `@orkestrel/contract` `^0.0.20` | |
82
82
  | `@orkestrel/server` | `0.0.24` | L3 | `@orkestrel/abort` `^0.0.14`, `@orkestrel/codec` `^0.0.7`, `@orkestrel/router` `^0.0.18`, `@orkestrel/emitter` `^0.0.13`, `@orkestrel/timeout` `^0.0.14`, `@orkestrel/contract` `^0.0.20` | |
83
83
  | `@orkestrel/sqlite` | `0.0.15` | L1 | `@orkestrel/contract` `^0.0.20` | |
@@ -235,13 +235,14 @@ directly.
235
235
 
236
236
  The server command leaves come from [`helpers.ts`](../src/server/helpers.ts).
237
237
 
238
- | Name | Kind | Signature | Summary |
239
- | --------------------- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
240
- | `formatGuideFinding` | function | `(finding: ParityFinding) => string` | Formats one finding with its guide prefix when needed. |
241
- | `matchesGuideResult` | function | `(result: unknown) => boolean` | Reads an owned foreign result view and accepts passed modules without unhandled errors. |
242
- | `resolveGuideRoot` | function | `(root: URL \| string) => string` | Resolves a command root to a native absolute path. |
243
- | `selectGuidePitch` | function | `(entries: readonly ManifestEntry[], name: string \| undefined) => string \| undefined` | Selects the indexed guide matching a package's bare name. |
244
- | `computeGuideProject` | function | `(module: string) => string \| undefined` | Computes the scoped project a guide module's declarations are emitted through. |
238
+ | Name | Kind | Signature | Summary |
239
+ | ------------------------- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
240
+ | `formatGuideFinding` | function | `(finding: ParityFinding) => string` | Formats one finding with its guide prefix when needed. |
241
+ | `matchesGuideResult` | function | `(result: unknown) => boolean` | Reads an owned foreign result view and accepts passed modules without unhandled errors. |
242
+ | `resolveGuideRoot` | function | `(root: URL \| string) => string` | Resolves a command root to a native absolute path. |
243
+ | `selectGuidePitch` | function | `(entries: readonly ManifestEntry[], name: string \| undefined) => string \| undefined` | Selects the indexed guide matching a package's bare name. |
244
+ | `computeGuideProject` | function | `(module: string) => string \| undefined` | Computes the scoped project a guide module's declarations are emitted through. |
245
+ | `computeGuideEnvironment` | function | `(source: string) => string \| undefined` | Computes the environment directory whose project compiles a guide source. |
245
246
 
246
247
  ### Parsers
247
248
 
@@ -357,9 +358,15 @@ no-write and rewrite failures preserve a higher existing process exit code.
357
358
 
358
359
  Every inventory read first constructs `Parity` without declarations, so every manifest guide
359
360
  parses, and every name two modules of one entry declare refuses, before any module compiles. It
360
- then compiles each distinct directory the parsed rows' sources name through `GuideCompiler` and
361
- passes the emitted declarations to `Parity` as `declarations`. A module compiles once per `execute`
362
- call: a `--to` run's second inventory read reuses the first read's declarations, which a
361
+ then compiles, through `GuideCompiler`, each distinct `src/<env>` or `app/<env>` directory that a
362
+ parsed row's source equals or sits beneath, and passes every emitted declaration to `Parity` as
363
+ `declarations`. A row over `src/core/panels` reads its signatures from the `src/core` compile. A
364
+ source under no `src/<env>` or `app/<env>` directory refuses with code `compile`, naming the
365
+ module, and a source whose environment's emit holds no declaration under it refuses with code
366
+ `empty`, naming each such module and its project in `context.missing`. An environment compiles
367
+ once per `execute` call: a manifest that lists `src/core` and
368
+ `src/core/panels` compiles `src/core` once, and a `--to` run's second inventory read reuses the
369
+ first read's declarations, which a
363
370
  `--to source` rewrite cannot change, because it rewrites doc blocks and the emit removes comments.
364
371
  A refusal names the guide or the module; a compile refusal carries the compiler's output in its
365
372
  message and in `context.output`. The native command writes the message to stderr and raises the
@@ -1219,9 +1226,9 @@ source with `npm run test:guides -- --to source`; never weaken the case.
1219
1226
  - [`tests/src/core/Parity.test.ts`](../tests/src/core/Parity.test.ts) — parity findings, rewrite boundaries, and propagation of parse refusals with the guide path and cause. The `Signature` cell rewrite under guide authority and its report under source authority; the README named in a refused pitch parse; a name two modules of one entry export, refused with the guide, the name, and both modules, beside a distinct-name control.
1220
1227
  - [`tests/src/core/sources/Source.test.ts`](../tests/src/core/sources/Source.test.ts) — direct/barrel projections, lexical and JSDoc regressions, canonical-key populations, root and nested indexes, exact row grammar, graph invariants, and correlated population controls; signatures carried from supplied emitted declarations
1221
1228
  - [`tests/src/core/sources/SourceManager.test.ts`](../tests/src/core/sources/SourceManager.test.ts) — `computeModuleKey` boundary collision, specifier resolution, the `undefined` skip for an unmapped specifier, array-valued module scopes, `sources()` enumeration, and per-module entity sharing with a differently-scoped identity control.
1222
- - [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — malformed guide rejection with its path, code, and required header; direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation; compile refusal naming the module; native `--to guide` signature rewrite and `--to source` report with exit codes; a malformed guide refused before any compile; one compile per module across a `--to guide` run, counted through a recording compiler; native exit 1 for a header refusal and for a compile refusal; a name `src/core` and `src/server` both export, refused, beside a distinct-name control that resolves
1229
+ - [`tests/src/server/GuideCommand.test.ts`](../tests/src/server/GuideCommand.test.ts) — malformed guide rejection with its path, code, and required header; direct installed reader and runner ports, fresh worker context, registration rejection, real runner cleanup after start failure, cleanup failure reporting, and higher native exit preservation; compile refusal naming the module; native `--to guide` signature rewrite and `--to source` report with exit codes; a malformed guide refused before any compile; one compile per environment across a `--to guide` run and across an environment's own and nested module rows, counted through a recording compiler; a nested module row read from its environment's compile, with a drifted cell reported for that row alone; a nested module its environment's project emits nothing under, refused with code `empty`; a source outside every `src/<env>` and `app/<env>` directory, refused with code `compile`; native exit 1 for a header refusal and for a compile refusal; a name `src/core` and `src/server` both export, refused, beside a distinct-name control that resolves
1223
1230
  - [`tests/src/server/GuideCompiler.test.ts`](../tests/src/server/GuideCompiler.test.ts) — every signature form computed from a fixture workspace compiler; byte-equal repeated compiles; refusal of a failing compile, a missing project, a module outside `src/<env>` and `app/<env>`, and a workspace with no compiler; coded `compile` refusals with the compiler output in `context`; `empty` refusals for a `declarationDir` and for an `include` that misses the module; `timeout` and `overflow` refusals; the scratch directory gone after a success and after a failure; sorted keys.
1224
- - [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — finding formatting, native and file-URL root resolution, pitch selection, and owned foreign-result reading with live receivers. Module-to-project mapping.
1231
+ - [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — finding formatting, native and file-URL root resolution, pitch selection, and owned foreign-result reading with live receivers. Module-to-project mapping, and the environment directory a source equals or sits beneath, matched by whole segments.
1225
1232
  - [`tests/src/server/parsers.test.ts`](../tests/src/server/parsers.test.ts) — native direction arguments and package-name parsing. `rootDir` reading from `--showConfig` output.
1226
1233
  - [`tests/setupServer.test.ts`](../tests/setupServer.test.ts) — the native carrier and `readGuideBuild`, which returns the built server entry the native-command cases load and refuses a missing build or one older than a source.
1227
1234
  - [`tests/distribution.test.ts`](../tests/distribution.test.ts) — the packed package through the `tests/setupDistribution.ts` harness, and `isGuideError` across the packed `import` and `require` entries and a copy at a second path: pairwise-distinct constructors, a hidden brand, subclass recognition, and refusal of a look-alike, a proxy, and a brand-only object.
@@ -116,13 +116,16 @@ Exported from `@orkestrel/scaffold`, and reachable from
116
116
  | `ToolchainHold` | interface | `{ framework, range, reason }` | Represents one foreign tool range required by a browser framework. |
117
117
  | `ViteMachinery` | interface | `{ browser, frameworks, output, showcase }` | Names which host-specific pipelines a generated root Vite configuration carries. |
118
118
 
119
- | Name | Kind | Signature | Summary |
120
- | ------------------ | --------- | ------------------------------- | ---------------------------------------------------------------------------------------------- |
121
- | `SurfaceCandidate` | interface | `{ conflicts }` | Represents a candidate checkout's claim with each name two or more of its environments export. |
122
- | `SurfaceClaim` | interface | `{ owner, names }` | Represents one owner's bare exported names, including an empty candidate surface. |
123
- | `SurfaceCollision` | interface | `{ name, owners }` | Represents a bare name claimed by distinct package owners. |
124
- | `SurfaceConflict` | interface | `{ name, owner, environments }` | Represents a bare name one owner's barrels export from two or more of its environments. |
125
- | `SurfaceFinding` | interface | `{ standing }` | Reports a collision's standing against the recorded owner set. |
119
+ | Name | Kind | Signature | Summary |
120
+ | ------------------- | --------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
121
+ | `SurfaceAdvisory` | interface | `{ name, owner, peer, similarity }` | Reports a name a candidate adds beside a near name or an equal contract another owner claims. |
122
+ | `SurfaceCandidate` | interface | `{ conflicts }` | Represents a candidate checkout's contract with each name two or more of its environments export. |
123
+ | `SurfaceClaim` | interface | `{ owner, names }` | Represents one owner's bare exported names, including an empty candidate surface. |
124
+ | `SurfaceCollision` | interface | `{ name, owners }` | Represents a bare name claimed by distinct package owners. |
125
+ | `SurfaceConflict` | interface | `{ name, owner, environments }` | Represents a bare name one owner's barrels export from two or more of its environments. |
126
+ | `SurfaceContract` | interface | `{ signatures }` | Represents one owner's claim with the guide `Signature` cell of each name a Surface row documents. |
127
+ | `SurfaceFinding` | interface | `{ standing }` | Reports a collision's standing against the recorded owner set. |
128
+ | `SurfaceSimilarity` | type | `'case' \| 'plural' \| 'edit' \| 'signature'` | Names how an added name resembles a name another owner claims. |
126
129
 
127
130
  #### Constants
128
131
 
@@ -212,6 +215,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
212
215
  | `STYLES_DEV_DEPENDENCIES` | const | `Readonly<Record<string, string>>` | Lists the development dependencies the styles surface adds, frozen. |
213
216
  | `STYLES_ENTRY_PATH` | const | `"src/styles/index.scss"` | Names the base stylesheet marker. |
214
217
  | `SURFACES` | const | `readonly Surface[]` | Lists the surfaces an extension may extend, frozen. |
218
+ | `SURFACE_EDIT_LENGTH` | const | `6` | Sets the shortest name length at which a one-edit neighbor counts as a near name. |
215
219
  | `TAB_WIDTH` | const | `2` | Sets the columns one tab occupies when the formatter measures a line, matching `tabWidth`. |
216
220
  | `TARGET_SKILL_NAMES` | const | `readonly string[]` | Lists the package-facing skills a target receives pointers for, frozen and alphabetical. |
217
221
  | `THEMES_BARREL_PATH` | const | `"src/styles/themes/index.scss"` | Names the themes stylesheet marker. |
@@ -304,11 +308,15 @@ Exported from `@orkestrel/scaffold`, and reachable from
304
308
  | `serializeTypeScriptString` | function | `(value: string) => string` | Serializes one string as a single-quoted TypeScript literal. |
305
309
  | `srcToRoot` | function | `(src: readonly Environment[]) => Environment \| undefined` | Selects the single published environment a package root points at. |
306
310
 
307
- | Name | Kind | Signature | Summary |
308
- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
309
- | `collectSurfaceCollisions` | function | `(claims: readonly SurfaceClaim[]) => readonly SurfaceCollision[]` | Collects bare names claimed by distinct owners in sorted order. |
310
- | `collectSurfaceConflicts` | function | `(owner: string, exports: Readonly<Record<string, readonly string[]>>) => readonly SurfaceConflict[]` | Collects the bare names one owner exports from two or more of its environments. |
311
- | `compareSurfaceCollisions` | function | `(collisions: readonly SurfaceCollision[], record: readonly SurfaceCollision[]) => readonly SurfaceFinding[]` | Compares collisions with the record and reports errors, recorded subsets, and closures. |
311
+ | Name | Kind | Signature | Summary |
312
+ | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
313
+ | `collectSurfaceAdvisories` | function | `(candidate: SurfaceContract, published: readonly string[], contracts: readonly SurfaceContract[]) => readonly SurfaceAdvisory[]` | Collects the near names and equal contracts other owners claim beside each name a candidate adds. |
314
+ | `collectSurfaceCollisions` | function | `(claims: readonly SurfaceClaim[]) => readonly SurfaceCollision[]` | Collects bare names claimed by distinct owners in sorted order. |
315
+ | `collectSurfaceConflicts` | function | `(owner: string, exports: Readonly<Record<string, readonly string[]>>) => readonly SurfaceConflict[]` | Collects the bare names one owner exports from two or more of its environments. |
316
+ | `compareSurfaceCollisions` | function | `(collisions: readonly SurfaceCollision[], record: readonly SurfaceCollision[]) => readonly SurfaceFinding[]` | Compares collisions with the record and reports errors, recorded subsets, and closures. |
317
+ | `inferSurfaceSimilarity` | function | `(name: string, other: string) => SurfaceSimilarity \| undefined` | Infers how two different names resemble each other by spelling. |
318
+ | `matchesGuideRefusal` | function | `(error: unknown) => boolean` | Checks whether an error is the `TARGET` refusal a surface reader raises for a guide its parser refuses, which carries the parser's code in its context. |
319
+ | `matchesSurfaceStructure` | function | `(signature: string) => boolean` | Checks whether a guide `Signature` cell spells a structure rather than a literal or a type name. |
312
320
 
313
321
  #### Compilers
314
322
 
@@ -393,7 +401,7 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
393
401
  | `MaterializerInterface` | interface | `{ emitter, audit(), materialize(), repair(), mirror(), catalog(), declare(), remove(), destroy() }` | Describes the mutation contract: the package's only filesystem writer. |
394
402
  | `MaterializerOptions` | interface | `{ host?, on?, error? }` | Represents the options for the materializer. |
395
403
  | `ReadAllowanceInterface` | interface | `{ remaining, spend() }` | Describes the byte allowance one upstream call spends across every read it makes. |
396
- | `SurfaceModule` | interface | `{ createGuide, createSource, extractSourceLines }` | Describes the guide module functions required by surface reflection. |
404
+ | `SurfaceModule` | interface | `{ createGuide, createSource, extractSourceLines, isGuideError }` | Describes the guide module functions required by surface reflection. |
397
405
  | `TextReadResult` | interface | `{ lookup, content, note, unreachable? }` | Reports the outcome of one bounded read whose body is taken as text. |
398
406
  | `Worktree` | interface | `{ tracked, dirty }` | Describes what git reports about a target's working tree. |
399
407
  | `UpstreamInterface` | interface | `{ emitter, lookup(), fetch(), read(), catalog(), inventory(), destroy() }` | Describes the upstream contract: the package's only network reader, and it never writes. |
@@ -498,10 +506,10 @@ Exported from `@orkestrel/scaffold/server`, and reachable from
498
506
  | `readSnapshot` | function | `(target: string, paths: readonly string[]) => Snapshot` | Reads a target's current bytes at the paths a plan claims. |
499
507
  | `readSurfaceBaseline` | function | `(root: string, name?: string) => readonly SurfaceCollision[] \| undefined` | Reads the Surface collision baseline from a committed inventory. |
500
508
  | `readSurfaceCollisions` | function | `(root: string) => ReadonlyMap<string, readonly string[]>` | Reads bare Surface names claimed by distinct package guides. |
501
- | `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceClaim[]` | Reads each immediate package guide's bare names under its file owner. |
509
+ | `readSurfaceClaims` | function | `(root: string, loader?: SurfaceLoader) => readonly SurfaceContract[]` | Reads each immediate package guide's bare names under its file owner. |
502
510
  | `readSurfaceCandidate` | function | `(root: string, loader?: SurfaceLoader) => SurfaceCandidate` | Reads a checkout's combined guide and barrel claims under its manifest owner. |
503
- | `readSurfaceFile` | function | `(root: string \| Host, owner: string, label: string, loader?: SurfaceLoader) => SurfaceClaim \| undefined` | Reads one owner's `guides/<owner>.md` under a root, or from a verified host value, as a claim. |
504
- | `readSurfaceGuide` | function | `(text: string, owner: string, source: string, loader?: SurfaceLoader) => SurfaceClaim` | Reads one guide's claims and reports parser refusals with its owner and source. |
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. |
505
513
  | `readSurfaceModule` | function | `(loader?: SurfaceLoader) => SurfaceModule` | Loads and validates the guide functions required by surface reflection. |
506
514
  | `readSurfaceRecord` | function | `(root: string) => readonly SurfaceCollision[]` | Reads a data root's verified collision record. |
507
515
  | `resolveHostRoot` | function | `() => string` | Resolves the bundled host root from the executing module's location. |
@@ -759,8 +767,11 @@ nor `src/`, when its guide exists but is not UTF-8 text within the artifact boun
759
767
  TypeScript source under `src/` cannot be read. Only `.ts` files under `src/` are read, so a binary
760
768
  asset there is ignored. A barrel holding a statement other than `export * from './module.js'`
761
769
  refuses with the statement named, because the reflection follows nothing else and an incomplete
762
- reading never reports clean. When `@orkestrel/guide` refuses a guide from any source, the command
763
- refuses with `TARGET`, naming the owner and the source and carrying the parser's message.
770
+ reading never reports clean. When `@orkestrel/guide` refuses a guide from any source with an error
771
+ its `isGuideError` guard accepts, such as a `## Surface` header other than
772
+ `Name | Kind | Signature | Summary`, the command refuses with `TARGET`, naming the owner and the
773
+ source, carrying the parser's message, and holding the guide error's `code` in the refusal's
774
+ context. Any other error the parser raises propagates unchanged.
764
775
 
765
776
  Compare unpublished candidates together with this command:
766
777
 
@@ -774,6 +785,28 @@ or carrying an owner absent from its recorded owner set, has `error` standing. A
774
785
  same or fewer owners has `recorded` standing. A recorded name that no longer collides has `closed`
775
786
  standing, so a release can shrink the record.
776
787
 
788
+ A name a candidate adds is one its claims hold and its owner's published guide does not. The
789
+ published guide is read in the order the Claims row gives for any other owner: the guide on `main`,
790
+ then the data root's `guides/<owner>.md`, or that root's guide alone under `--from`. That guide
791
+ sets only the advisory baseline, so when its parser refuses it the command reads the next source,
792
+ and with none left every name the candidate claims counts as added; a refused guide for any other
793
+ owner stops the run. The command compares each added name with every other owner's claimed names, never with the candidate's own,
794
+ and reports an advisory for each near name: a case-fold twin (`case`), a singular or plural form by
795
+ `s`, `es`, or `y` to `ies` (`plural`), or a name one insertion, deletion, or substitution away when
796
+ both names hold at least `SURFACE_EDIT_LENGTH` characters (`edit`). It also reports a different
797
+ name whose `Signature` cell equals the added name's cell (`signature`) when `matchesSurfaceStructure`
798
+ reads that cell as a structure: a member list with at least one member, its array and union forms
799
+ included. A pair that is both a near name and an equal structure reports once in each class. A literal, a bare
800
+ primitive, a type reference, a function type, and an empty member list are no structure, and a name
801
+ only a barrel claims carries no cell. An advisory never changes the exit code; rule each one under
802
+ `.claude/rules/names.md` § Fleet name ownership before you publish. Each advisory prints one line,
803
+ where `NAME` is the added name, `OWNER` the candidate, `PEER` the other name, `HOLDER` the other
804
+ owner, and `CLASS` the similarity:
805
+
806
+ ```text
807
+ Surface advisory "NAME": "OWNER" adds it beside "PEER" from "HOLDER" (CLASS). Rule it under fleet name ownership before the upload.
808
+ ```
809
+
777
810
  The command returns `1` when a collision has `error` standing, a candidate carries a conflict, or
778
811
  an owner is unread. A run without
779
812
  `--offline` or `--from` also returns `1` when membership fell to the floor catalog table, any
@@ -781,26 +814,35 @@ owner fell to the floor guide, or the record fell to the floor inventory. Every
781
814
 
782
815
  The human report names membership when it fell to the floor catalog table, with the failure the
783
816
  registry read reported, then each owner that fell to the floor guide, each unread owner, the record
784
- when it fell to the floor inventory, each `error` collision with its owners, and each conflict
785
- with its owner and environments, then prints the recorded and closed counts. The `--json` option
786
- emits one value with `owners`, `collisions`, `conflicts`, and `provenance`. Each owner carries `owner`, `source` (`candidate`, `live`, `floor`, or `unread`), and
817
+ when it fell to the floor inventory, each `error` collision with its owners, each conflict
818
+ with its owner and environments, and each advisory, then prints the recorded and closed counts. The `--json` option
819
+ emits one value with `owners`, `collisions`, `conflicts`, `advisories`, and `provenance`. Each owner carries `owner`, `source` (`candidate`, `live`, `floor`, or `unread`), and
787
820
  `names` unless it is unread. Each collision carries `name`, `owners`, and `standing`, sorted by
788
821
  name, including closed entries with their recorded owners. Each conflict carries `name`, `owner`,
789
- and `environments`, sorted by name within each candidate. `provenance.membership` names the
822
+ and `environments`, sorted by name within each candidate. Each advisory carries the candidate's
823
+ `name` and `owner`, the other owner's name as `peer`, and `similarity`, sorted within each candidate
824
+ by added name, peer owner, and peer name, with a spelling class before `signature`. `provenance.membership` names the
790
825
  package list's baseline, `provenance.guides` is `live` only when no owner fell to the floor, and
791
826
  `provenance.record` names the record's baseline; a `--from` run reports none of them. The command changes no files.
792
827
 
793
828
  The core `SurfaceClaim` interface carries `owner` and `names`. `SurfaceCollision` carries `name`
794
829
  and `owners`; `SurfaceFinding` adds `standing`. `SurfaceConflict` carries `name`, `owner`, and
795
- `environments`, and `SurfaceCandidate` adds `conflicts` to a claim. `collectSurfaceCollisions`
830
+ `environments`. `SurfaceContract` adds `signatures`, the `Signature` cell of each name a guide row
831
+ documents, to a claim, and `SurfaceCandidate` adds `conflicts` to a contract. `SurfaceAdvisory`
832
+ carries `name`, `owner`, `peer`, and a `SurfaceSimilarity` as `similarity`. `collectSurfaceCollisions`
796
833
  deduplicates owners, `compareSurfaceCollisions` applies the record, and `collectSurfaceConflicts`
797
- finds the names one owner exports from more than one environment. `readSurfaceClaims` reads
834
+ finds the names one owner exports from more than one environment. `collectSurfaceAdvisories`
835
+ compares a candidate's added names with other owners' contracts through `inferSurfaceSimilarity`
836
+ and `matchesSurfaceStructure`, and `matchesGuideRefusal` recognizes the refusal a reader raises for
837
+ a guide its parser refuses. `readSurfaceClaims` reads
798
838
  immediate package guides, excluding the README index. `readSurfaceCandidate` adds live barrel names
799
839
  and the candidate's conflicts. `readSurfaceFile` reads
800
- one owner's guide file under a root, and `readSurfaceGuide` parses guide text from any source.
840
+ one owner's guide file under a root, and `readSurfaceGuide` parses guide text from any source into
841
+ a contract.
801
842
  `readSurfaceRecord` reads a data root's record, and `resolveHostRoot` resolves the bundled root.
802
- `readSurfaceModule` loads `@orkestrel/guide` lazily and narrows it with `isSurfaceModule`; every
803
- reader takes an optional `SurfaceLoader` that resolves the module, and requires the package in
843
+ `readSurfaceModule` loads `@orkestrel/guide` lazily and narrows it with `isSurfaceModule`, which
844
+ requires `createGuide`, `createSource`, `extractSourceLines`, and `isGuideError` as functions, and
845
+ refuses with `TARGET` a module that lacks one or holds another value there; every reader takes an optional `SurfaceLoader` that resolves the module, and requires the package in
804
846
  scaffold's resolution path when none is supplied. Importing the server entry alone does not load
805
847
  it.
806
848
 
@@ -472,7 +472,7 @@
472
472
  "storage": "agents/skills/orkestrel-publish/references/wave.md",
473
473
  "destination": ".agents/skills/orkestrel-publish/references/wave.md",
474
474
  "executable": false,
475
- "digest": "cb20949b031e9b9b7a2d0202c9b4d6f8fce1657e2f9e9bb59ebec55e4f75d71d"
475
+ "digest": "51f5303628eae0b7508955382ac4173d2e8245a93e424179dbeb6bd3a4311440"
476
476
  },
477
477
  {
478
478
  "storage": "agents/skills/orkestrel-publish/references/window.md",
@@ -604,7 +604,7 @@
604
604
  "storage": "claude/agents/orkestrel.md",
605
605
  "destination": ".claude/agents/orkestrel.md",
606
606
  "executable": false,
607
- "digest": "e38ce6624566e4bb00281516faf8ea67869f16e5a4ecbc96ddda7aa263d1e94b"
607
+ "digest": "4ad75a62b6d394db889f1754956bbd053c2a68c5ed34b1cfae0d81841835a6f9"
608
608
  },
609
609
  {
610
610
  "storage": "claude/agents/planner.md",
@@ -1042,7 +1042,7 @@
1042
1042
  "storage": "guides/guide.md",
1043
1043
  "destination": "guides/guide.md",
1044
1044
  "executable": false,
1045
- "digest": "e1e677fe395af8153c5ceeb496630784507cee05d17f6f5cdaf7f9a221033117"
1045
+ "digest": "b8747025c58c3ea720c02db45d88a1047093f792c2fccde363080f82b0fb38be"
1046
1046
  },
1047
1047
  {
1048
1048
  "storage": "guides/html.md",
@@ -1168,7 +1168,7 @@
1168
1168
  "storage": "guides/scaffold.md",
1169
1169
  "destination": "guides/scaffold.md",
1170
1170
  "executable": false,
1171
- "digest": "9311d0b55f5d08c20ce417b84ac115e3c8400cf167cf7d108d1ef1cb846de837"
1171
+ "digest": "ef9158ff72a362260dece3d5f1bacc37d6c9ceb6f75e4b8814e5b64dabc39a5b"
1172
1172
  },
1173
1173
  {
1174
1174
  "storage": "guides/sea.md",
@@ -2141,5 +2141,5 @@
2141
2141
  ]
2142
2142
  }
2143
2143
  ],
2144
- "digest": "f7b980503c2ad03619c833ea066b67d682ec26c894ea5b52a6f013c93aaa491f"
2144
+ "digest": "461c2456d47acc1b510a19690530ee7ee12346677c6a2858210daeb0242f5488"
2145
2145
  }
@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
4
4
  let _orkestrel_emitter = require("@orkestrel/emitter");
5
5
  var package_default = {
6
6
  name: "@orkestrel/scaffold",
7
- version: "0.0.116",
7
+ version: "0.0.118",
8
8
  description: "Scaffold workspaces with commands: new, audit, surface, repair, catalog, and overwrite.",
9
9
  keywords: [
10
10
  "audit",
@@ -106,7 +106,7 @@ var package_default = {
106
106
  devDependencies: {
107
107
  "@microsoft/api-extractor": "^7.60.0",
108
108
  "@orkestrel/browser": "^0.0.30",
109
- "@orkestrel/guide": "^0.0.26",
109
+ "@orkestrel/guide": "^0.0.28",
110
110
  "@orkestrel/html": "^0.0.13",
111
111
  "@orkestrel/probe": "^0.0.26",
112
112
  "@orkestrel/test": "^0.0.31",
@@ -600,6 +600,8 @@ var MAX_RANGE_LENGTH = 2048;
600
600
  var MAX_SCRIPT_LENGTH = 4096;
601
601
  /** Caps the length of one path, matching the longest a supported filesystem accepts. */
602
602
  var MAX_PATH_LENGTH = 32767;
603
+ /** Sets the shortest name length at which a one-edit neighbor counts as a near name. */
604
+ var SURFACE_EDIT_LENGTH = 6;
603
605
  /** Caps the items accepted in one public collection. */
604
606
  var MAX_COLLECTION_ITEMS = 1e3;
605
607
  /** Caps the columns one emitted line may occupy, matching `printWidth` in `.oxfmtrc.json`. */
@@ -5592,6 +5594,122 @@ function collectSurfaceConflicts(owner, exports) {
5592
5594
  });
5593
5595
  }
5594
5596
  /**
5597
+ * Infers how two different names resemble each other by spelling.
5598
+ *
5599
+ * @returns The first class that holds, or `undefined` when none does or the names are equal.
5600
+ *
5601
+ * @remarks
5602
+ * Reads, in order, a case-fold twin, a singular or plural form (`s`, `es`, or `y` to `ies`), and
5603
+ * one insertion, deletion, or substitution of a code unit when both names hold at least
5604
+ * `SURFACE_EDIT_LENGTH` characters. Never returns `signature`, which compares cells.
5605
+ *
5606
+ * @example
5607
+ * ```ts
5608
+ * import { inferSurfaceSimilarity } from '@orkestrel/scaffold'
5609
+ *
5610
+ * inferSurfaceSimilarity('Route', 'Routes') // 'plural'
5611
+ * ```
5612
+ */
5613
+ function inferSurfaceSimilarity(name, other) {
5614
+ const [short, long] = name.length <= other.length ? [name, other] : [other, name];
5615
+ if (name === other) return void 0;
5616
+ if (name.toLowerCase() === other.toLowerCase()) return "case";
5617
+ if (long === `${short}s` || long === `${short}es` || short.endsWith("y") && long === `${short.slice(0, -1)}ies`) return "plural";
5618
+ if (short.length < 6 || long.length - short.length > 1) return void 0;
5619
+ const found = short.split("").findIndex((character, position) => character !== long[position]);
5620
+ const index = found === -1 ? short.length : found;
5621
+ const rest = long.length === short.length ? short.slice(index + 1) : short.slice(index);
5622
+ return long.slice(index + 1) === rest ? "edit" : void 0;
5623
+ }
5624
+ /**
5625
+ * Checks whether an error is the `TARGET` refusal a surface reader raises for a guide its parser
5626
+ * refuses, which carries the parser's code in its context.
5627
+ *
5628
+ * @returns True if the error is that refusal; false otherwise.
5629
+ *
5630
+ * @example
5631
+ * ```ts
5632
+ * import { matchesGuideRefusal, ScaffoldError } from '@orkestrel/scaffold'
5633
+ *
5634
+ * matchesGuideRefusal(new ScaffoldError('TARGET', 'Refused', { code: 'header' })) // true
5635
+ * ```
5636
+ */
5637
+ function matchesGuideRefusal(error) {
5638
+ return isScaffoldError(error) && error.code === "TARGET" && (0, _orkestrel_contract.isRecord)(error.context) && (0, _orkestrel_contract.isString)(error.context.code);
5639
+ }
5640
+ /**
5641
+ * Checks whether a guide `Signature` cell spells a structure rather than a literal or a type name.
5642
+ *
5643
+ * @returns True if the cell is one code span that opens with a member list holding at least one
5644
+ * member, its array and union forms included; false otherwise.
5645
+ *
5646
+ * @remarks
5647
+ * A literal (`2000`, `" "`, `'live' | 'floor'`), a bare primitive (`string`), a type reference
5648
+ * (`RegExp`, `Guard<string>`, `readonly string[]`), a function type, an empty member list, and
5649
+ * prose are no structure: two names sharing one of those share a type, not a contract.
5650
+ *
5651
+ * @example
5652
+ * ```ts
5653
+ * import { matchesSurfaceStructure } from '@orkestrel/scaffold'
5654
+ *
5655
+ * matchesSurfaceStructure('`{ owner, names }`') // true
5656
+ * ```
5657
+ */
5658
+ function matchesSurfaceStructure(signature) {
5659
+ const code = /^`([^`]+)`$/u.exec(signature)?.[1]?.trim();
5660
+ return code !== void 0 && code.startsWith("{") && !/^\{\s*\}$/u.test(code);
5661
+ }
5662
+ /**
5663
+ * Collects the near names and equal contracts other owners claim beside each name a candidate adds.
5664
+ *
5665
+ * @param candidate - The candidate owner's contract.
5666
+ * @param published - The names the candidate owner's published guide claims; empty when none.
5667
+ * @param contracts - Every owner's contract; the candidate owner's own entry is skipped.
5668
+ * @returns One advisory per added name, peer, and class, sorted by added name, peer owner, and peer
5669
+ * name, with a spelling class before `signature`.
5670
+ *
5671
+ * @remarks
5672
+ * An added name is one `candidate` claims and `published` does not. A spelling class comes from
5673
+ * `inferSurfaceSimilarity`; `signature` holds when both names carry equal cells that
5674
+ * `matchesSurfaceStructure` accepts. A name equal to the added name is a collision, not an
5675
+ * advisory.
5676
+ *
5677
+ * @example
5678
+ * ```ts
5679
+ * import { collectSurfaceAdvisories } from '@orkestrel/scaffold'
5680
+ *
5681
+ * const advisories = collectSurfaceAdvisories(
5682
+ * { owner: 'alpha', names: ['Routes'], signatures: new Map() },
5683
+ * [],
5684
+ * [{ owner: 'router', names: ['Route'], signatures: new Map() }],
5685
+ * )
5686
+ * advisories[0]?.similarity // 'plural'
5687
+ * ```
5688
+ */
5689
+ function collectSurfaceAdvisories(candidate, published, contracts) {
5690
+ const known = new Set(published);
5691
+ const peers = contracts.filter(({ owner }) => owner !== candidate.owner).flatMap(({ owner, names, signatures }) => [...new Set(names)].map((name) => ({
5692
+ name,
5693
+ owner,
5694
+ signature: signatures.get(name)
5695
+ }))).sort((left, right) => (0, _orkestrel_contract.compareValues)(left.owner, right.owner) || (0, _orkestrel_contract.compareValues)(left.name, right.name));
5696
+ return [...new Set(candidate.names)].filter((name) => !known.has(name)).sort(_orkestrel_contract.compareValues).flatMap((name) => {
5697
+ const signature = candidate.signatures.get(name);
5698
+ const structure = signature !== void 0 && matchesSurfaceStructure(signature);
5699
+ return peers.flatMap((peer) => {
5700
+ return [inferSurfaceSimilarity(name, peer.name), structure && peer.name !== name && peer.signature === signature ? "signature" : void 0].flatMap((similarity) => similarity === void 0 ? [] : [{
5701
+ name,
5702
+ owner: candidate.owner,
5703
+ peer: {
5704
+ name: peer.name,
5705
+ owner: peer.owner
5706
+ },
5707
+ similarity
5708
+ }]);
5709
+ });
5710
+ });
5711
+ }
5712
+ /**
5595
5713
  * Encodes bytes as exact lowercase hexadecimal text.
5596
5714
  *
5597
5715
  * @param bytes - The bytes to encode.
@@ -9793,6 +9911,7 @@ exports.STUDIES_TEST_INCLUDE = STUDIES_TEST_INCLUDE;
9793
9911
  exports.STYLES_DEV_DEPENDENCIES = STYLES_DEV_DEPENDENCIES;
9794
9912
  exports.STYLES_ENTRY_PATH = STYLES_ENTRY_PATH;
9795
9913
  exports.SURFACES = SURFACES;
9914
+ exports.SURFACE_EDIT_LENGTH = SURFACE_EDIT_LENGTH;
9796
9915
  exports.ScaffoldError = ScaffoldError;
9797
9916
  exports.TAB_WIDTH = TAB_WIDTH;
9798
9917
  exports.TARGET_SKILL_NAMES = TARGET_SKILL_NAMES;
@@ -9832,6 +9951,7 @@ exports.blueprintToWritableScripts = blueprintToWritableScripts;
9832
9951
  exports.bytesToHex = bytesToHex;
9833
9952
  exports.catalogToLayers = catalogToLayers;
9834
9953
  exports.cloneValue = cloneValue;
9954
+ exports.collectSurfaceAdvisories = collectSurfaceAdvisories;
9835
9955
  exports.collectSurfaceCollisions = collectSurfaceCollisions;
9836
9956
  exports.collectSurfaceConflicts = collectSurfaceConflicts;
9837
9957
  exports.compareSurfaceCollisions = compareSurfaceCollisions;
@@ -9846,6 +9966,7 @@ exports.extractRangeMajor = extractRangeMajor;
9846
9966
  exports.extractVersion = extractVersion;
9847
9967
  exports.inferDrift = inferDrift;
9848
9968
  exports.inferGroup = inferGroup;
9969
+ exports.inferSurfaceSimilarity = inferSurfaceSimilarity;
9849
9970
  exports.insertManifestDependencies = insertManifestDependencies;
9850
9971
  exports.insertManifestSection = insertManifestSection;
9851
9972
  exports.isArtifact = isArtifact;
@@ -9885,9 +10006,11 @@ exports.manifestToDependencies = manifestToDependencies;
9885
10006
  exports.manifestToName = manifestToName;
9886
10007
  exports.matchesDriftReachability = matchesDriftReachability;
9887
10008
  exports.matchesEngines = matchesEngines;
10009
+ exports.matchesGuideRefusal = matchesGuideRefusal;
9888
10010
  exports.matchesOrchestrationPath = matchesOrchestrationPath;
9889
10011
  exports.matchesPrintWidth = matchesPrintWidth;
9890
10012
  exports.matchesRange = matchesRange;
10013
+ exports.matchesSurfaceStructure = matchesSurfaceStructure;
9891
10014
  exports.nameToGuide = nameToGuide;
9892
10015
  exports.overridesToQuestions = overridesToQuestions;
9893
10016
  exports.parseBlueprint = parseBlueprint;