@orkestrel/scaffold 0.0.113 → 0.0.115

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 (94) hide show
  1. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +83 -16
  2. package/dist/bin/main.js +71 -23
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/agents/orchestration.md +5 -3
  5. package/dist/host/agents/platforms/windows.md +1 -0
  6. package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
  8. package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
  9. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
  10. package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
  11. package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
  12. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  13. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
  14. package/dist/host/agents/skills/orkestrel-publish/SKILL.md +7 -7
  15. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +31 -11
  16. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +150 -49
  17. package/dist/host/claude/agents/analyst.md +1 -1
  18. package/dist/host/claude/agents/astra.md +2 -2
  19. package/dist/host/claude/agents/builder.md +4 -4
  20. package/dist/host/claude/agents/opus.md +3 -3
  21. package/dist/host/claude/agents/orkestrel.md +57 -59
  22. package/dist/host/claude/agents/planner.md +8 -2
  23. package/dist/host/claude/rules/campaign.md +2 -1
  24. package/dist/host/claude/rules/documentation.md +1 -0
  25. package/dist/host/claude/rules/tests.md +13 -8
  26. package/dist/host/claude/rules/workspace.md +28 -28
  27. package/dist/host/claude/rules/writing.md +1 -0
  28. package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
  29. package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
  30. package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
  31. package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
  32. package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
  33. package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
  34. package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
  35. package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
  36. package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
  37. package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
  38. package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
  39. package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
  40. package/dist/host/codex/agents/analyst.toml +8 -5
  41. package/dist/host/codex/agents/astra.toml +4 -5
  42. package/dist/host/codex/agents/builder.toml +5 -5
  43. package/dist/host/codex/agents/opus.toml +3 -4
  44. package/dist/host/codex/agents/orkestrel.toml +2 -1
  45. package/dist/host/codex/agents/planner.toml +8 -5
  46. package/dist/host/codex/agents/reviewer.toml +5 -4
  47. package/dist/host/guides/agent.md +13 -13
  48. package/dist/host/guides/brief.md +4 -0
  49. package/dist/host/guides/browser.md +162 -44
  50. package/dist/host/guides/budget.md +1 -1
  51. package/dist/host/guides/capture.md +4 -0
  52. package/dist/host/guides/console.md +13 -0
  53. package/dist/host/guides/contract.md +38 -3
  54. package/dist/host/guides/csv.md +5 -0
  55. package/dist/host/guides/database.md +58 -8
  56. package/dist/host/guides/form.md +17 -0
  57. package/dist/host/guides/guide.md +36 -33
  58. package/dist/host/guides/html.md +72 -44
  59. package/dist/host/guides/indexeddb.md +4 -0
  60. package/dist/host/guides/lsp.md +49 -8
  61. package/dist/host/guides/markdown.md +146 -1
  62. package/dist/host/guides/mcp.md +117 -22
  63. package/dist/host/guides/middleware.md +194 -26
  64. package/dist/host/guides/msg.md +9 -5
  65. package/dist/host/guides/pool.md +8 -1
  66. package/dist/host/guides/probe.md +13 -1
  67. package/dist/host/guides/process.md +102 -90
  68. package/dist/host/guides/program.md +4 -0
  69. package/dist/host/guides/qualifier.md +4 -0
  70. package/dist/host/guides/rater.md +4 -0
  71. package/dist/host/guides/reason.md +6 -4
  72. package/dist/host/guides/relation.md +4 -0
  73. package/dist/host/guides/scaffold.md +32 -14
  74. package/dist/host/guides/server.md +29 -13
  75. package/dist/host/guides/sqlite.md +6 -0
  76. package/dist/host/guides/sse.md +6 -0
  77. package/dist/host/guides/study.md +473 -473
  78. package/dist/host/guides/table.md +3 -0
  79. package/dist/host/guides/template.md +3 -0
  80. package/dist/host/guides/test.md +38 -20
  81. package/dist/host/guides/tool.md +3 -0
  82. package/dist/host/guides/toolbox.md +21 -0
  83. package/dist/host/guides/websocket.md +3 -1
  84. package/dist/host/guides/workflow.md +103 -11
  85. package/dist/host/guides/workspace.md +4 -0
  86. package/dist/host/manifest.json +84 -84
  87. package/dist/host/tests/config.test.ts +7 -13
  88. package/dist/src/core/index.cjs +20 -28
  89. package/dist/src/core/index.cjs.map +1 -1
  90. package/dist/src/core/index.d.cts +7 -7
  91. package/dist/src/core/index.d.ts +7 -7
  92. package/dist/src/core/index.js +20 -28
  93. package/dist/src/core/index.js.map +1 -1
  94. package/package.json +12 -12
@@ -46,6 +46,19 @@ spinner.succeed('deployed') // ✔ deployed — the timer cleared, the line comm
46
46
 
47
47
  Style is **data**: a `Style` is a frozen `{ foreground?, background?, attributes }` record, and a `RendererInterface` turns it into output for one target. The `Styler` is the fluent surface — `styler.red.bold('hi')` accumulates a style and renders it through the injected renderer; swap the renderer (ANSI default → browser `%c`) and the style model never changes. Logging is **orthogonal to styling**: a `LogLevel` is one coherent ascending scale (`debug` < `info` < `warn` < `error`), and a level's color is a styling choice, never a pseudo-level. Every retention buffer (a logger's tail, a capture's buffers) is **bounded** — never an unbounded leak.
48
48
 
49
+ ### Scan and layout primitives
50
+
51
+ The layout and browser scan expose these primitives:
52
+
53
+ | API | Kind | Shape | Summary |
54
+ | ---------------- | --------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
55
+ | `renderBoxTop` | function | `(options: BoxOptions, span: number) => string` | Renders a box's top border across the supplied inner span. |
56
+ | `LineIterator` | class | `IterableIterator<number>` | Yields a position for each requested blank line without allocating the whole sequence. |
57
+ | `ConsoleSegment` | interface | `{ active, cursor, text, style }` | Records the style and visible text at one ANSI scan boundary. |
58
+
59
+ The `isConsoleError` guard recognizes an own identity brand across package copies. It accepts
60
+ subclasses regardless of their `name`, and rejects transparent proxies and unbranded errors.
61
+
49
62
  ### Styling
50
63
 
51
64
  The style engine — text style as data, rendered by a swappable renderer (ANSI default; a browser `%c` renderer at the same seam).
@@ -265,6 +265,18 @@ guard row's the type it narrows to.
265
265
  | `pinMembers` | function | Pins every own member of a class prototype as a non-configurable member — non-writable too when it is a data property — and verify the pin took. |
266
266
  | `refuseExpansion` | function | Refuses a validated declaration whose compiled expansion exceeds `COMPILE_NODE_LIMIT`. |
267
267
 
268
+ | API | Kind | Summary |
269
+ | -------------------- | -------- | ---------------------------------------------------------------------------- |
270
+ | `iterateIndices` | function | Iterates indices while rereading the upper bound before every step. |
271
+ | `encodeParts` | function | Encodes ordered members, stopping before the first unencodable member. |
272
+ | `previewParts` | function | Builds bounded escaped preview parts without splitting a surrogate pair. |
273
+ | `buildPositions` | function | Builds a null-prototype lookup from names to their last index. |
274
+ | `readPresence` | function | Derives the bit mask of names present in an indexed lookup. |
275
+ | `LengthReader` | type | Reads the current upper bound of an indexed walk. |
276
+ | `EvaluationFunction` | type | Evaluates a compiled node at one diagnostic path. |
277
+ | `parseEnumValues` | function | Parses indexed enum members, ending after the first undefined result. |
278
+ | `readIndexView` | function | Exposes indexed reads through a non-array receiver without species dispatch. |
279
+
268
280
  `matchesJSONDepth` is deliberately depth-only: active cycles terminate successfully at the depth layer but remain invalid JSON, honest sparse holes add no child depth but fail the dense `isJSONValue` contract, and readable exotics pass as leaves but fail JSON validity. `isBoundedJSONValue` therefore performs two total sequential observations — fixed depth first, then the existing JSON guard — rather than promising an atomic snapshot of caller-owned state. It validates but does not own; use `cloneJSONValue` / `cloneJSONRecord` when an independent frozen snapshot is required. The fixed cap is package safety mechanism, not configurable product policy: byte budgets, key budgets, configured wire depth, unsafe-name rejection, descriptor policy, and application-specific limits remain with their consuming package.
269
281
 
270
282
  ### Membership
@@ -341,9 +353,9 @@ literal with a union's arms escaped as `\|`.
341
353
 
342
354
  ### `ContractError`
343
355
 
344
- `CONTRACT_ERROR_BRAND` is the registry-global symbol captured while `constants.ts` evaluates. The constructor stores the error itself under that key, and `isContractError` requires the descriptor value to be the value under inspection. That identity check keeps cross-copy recognition and refuses accidental property lookalikes and transparent wrappers: a proxy forwards a descriptor that stores its target, not the proxy. The registry makes the stamp forgeable by design. A complete `Error` subclass forgery with the exact name, a declared code, and its own identity stored under `Symbol.for('@orkestrel/contract.error')` passes recognition. The brand is therefore a cross-copy recognition marker, not proof that this package constructed the value.
356
+ `CONTRACT_ERROR_BRAND` is the registry-global symbol captured while `constants.ts` evaluates. The constructor stores the error itself under that key, and `isContractError` requires the descriptor value to be the value under inspection. That identity check keeps cross-copy recognition and refuses accidental property lookalikes and transparent wrappers: a proxy forwards a descriptor that stores its target, not the proxy. The registry makes the stamp forgeable by design. A complete `Error` subclass forgery with a declared code, valid context, and its own identity stored under `Symbol.for('@orkestrel/contract.error')` passes recognition. The brand is therefore a cross-copy recognition marker, not proof that this package constructed the value.
345
357
 
346
- The one error class thrown across this module — an `Error` subclass carrying a machine-readable `code`, optional structured `context`, and an exact optional `cause`, from [`errors.ts`](../src/core/errors.ts). Omitting `cause` creates no own cause property; supplying `cause: undefined` creates an own property whose value is exactly `undefined`; every other cause retains its identity. Both optional options are read as OWN properties and ownership is established before the value is read at all, so an inherited `cause` or `context` counts as omission: an unqualified read of an absent option would leave the container and land on `Object.prototype`, which any caller can write, and would let that caller decide what a refusal an engine authored carries. `code` is required by the options type, so an internal literal always carries it own; a caller who hands in a container that INHERITS `code` still gets the inherited value, because the type promised a value rather than an own property, and that caller is choosing what its own error carries. `name` is fixed to `'ContractError'`; `code` and `context` are readonly. The constructor stamps the global own-property brand `Symbol.for('@orkestrel/contract.error')`. `isContractError` requires that brand plus the native `Error` base, a prototype other than `Error.prototype`, the exact `ContractError` name, and a declared `ContractCode`. The global symbol registry makes recognition work across duplicate installations and ESM/CommonJS module copies at 0.0.13 or later. A copy earlier than 0.0.13 stamps no brand, so its errors remain outside the type. An ordinary `Error`, a plain object, or a partial property lookalike remains outside the type.
358
+ The one error class thrown across this module — an `Error` subclass carrying a machine-readable `code`, optional structured `context`, and an exact optional `cause`, from [`errors.ts`](../src/core/errors.ts). Omitting `cause` creates no own cause property; supplying `cause: undefined` creates an own property whose value is exactly `undefined`; every other cause retains its identity. Both optional options are read as OWN properties and ownership is established before the value is read at all, so an inherited `cause` or `context` counts as omission: an unqualified read of an absent option would leave the container and land on `Object.prototype`, which any caller can write, and would let that caller decide what a refusal an engine authored carries. `code` is required by the options type, so an internal literal always carries it own; a caller who hands in a container that INHERITS `code` still gets the inherited value, because the type promised a value rather than an own property, and that caller is choosing what its own error carries. `name` defaults to `'ContractError'` and a subclass may override it; `code` and `context` are readonly. The constructor stamps the global own-property brand `Symbol.for('@orkestrel/contract.error')`. `isContractError` requires that brand plus the native `Error` base, a prototype other than `Error.prototype`, an own declared `ContractCode` read through captured ownership and reflection, and valid optional context members read through captured own-property checks. A context may be a class instance or callable object with the declared fields. Array paths are checked by index without retrieving their iterator. Numeric limits admit every number, including non-finite values. Inherited optional context fields count as omission. It never reads `name`, so a subclass with a different name remains recognized. The global symbol registry makes recognition work across duplicate installations and ESM/CommonJS module copies at 0.0.13 or later. A copy earlier than 0.0.13 stamps no brand, so its errors remain outside the type. An ordinary `Error`, a plain object, or a partial property lookalike remains outside the type.
347
359
 
348
360
  These refusal families may throw, and whenever they do they throw only this class: REQUIRED READS (`readValue` and the public inferer/helper/combinator/compiler readers layered over it — normally `structure` with `<reader>: <subject> could not be read`, while `RegExp` readers use `pattern`), shape CONSTRUCTION (every builder validates every runtime argument position before returning — `bound` / `range` / `empty` / `placement` / `pattern` / `literal` / `structure`), CLONING (`cloneJSONValue` / `cloneJSONRecord` for inexact JSON data, cycles, or hostile traversal; `cloneSchema` / `cloneShape` / `ownShape`, and `rawShape` through its snapshot — `clone` plus declaration-policy codes), VALIDATION (`validateShape` and `ShapeValidator` — `range` / `empty` / `placement` / `structure` / `literal` / `cycle` / `bound` / `pattern`), the COMPILATION gate (every `compile*` export plus `createContract` routes through that same `validateShape` — the same declaration-policy codes, plus `depth`), and GENERATION (`compileGenerator` on an unsatisfiable request — `generate`; `drawRandom` on a broken sample source — `random`). Every message opens with the reader that OWNS the rule it enforces, never the engine that happened to run it. A declaration rule belongs to the shared gate and reads `validateShape: …` wherever it is applied, including inside `ShapeCloner`, which enforces the same rules while capturing; `cloneShape: …` is reserved for the ownership rules the cloner itself owns — own data discriminants, inherited fields, accessors, read stability, unreadable property maps, and a failed snapshot; and `ShapeCloner.clone: …`, `SchemaCloner.clone: …`, `JSONCloner.clone: …` and `ShapeValidator.validate: …` name a refusal about the CALL rather than the declaration, such as reentry. One rule therefore has one diagnostic at each of those doors: `cloneShape`, `ownShape`, `validateShape`, `ShapeValidator`, every `compile*` export and `createContract` report the same malformed declaration with the same code and the same message, across every declaration-policy family the gate owns (`placement`, `range`, `bound`, `pattern`, `empty`, `literal`, `cycle`, `depth`, `structure`). That is a statement about those doors and those families, enforced by a sweep rather than asserted: it says nothing about a door outside the list. `createContract` observes its caller’s source twice — once as the declaration, once while cloning it — so a LIVE declaration that changes between those walks can be refused by ownership rather than by the gate, and each refusal names the boundary that owns the rule it broke. An error adopted by identity from another engine keeps the prefix that engine gave it. Hand-authored string declarations use the same unflagged-pattern policy as builders: a stable genuine `RegExp` carrying flags is a `pattern` refusal, and inline pattern constructs are the supported alternative. Total guards and optional readers use their non-throwing outcomes; `compileReporter` contains its diagnostic walk, while required `parse`/`audit` reads and schema inversion refuse traversal failure. Root ownership, including the frozen-state probe itself, is contained before standalone compilation begins: a revoked `Proxy`, throwing getter, or caller-thrown value becomes a coded `clone` / `structure` `ContractError`. Malformed containers, hostile proxies, and wrong primitives at any builder position become coded `ContractError` values. Every public door that can refuse runs its whole body through `contain`, which republishes anything that is not this class under the door's own name with the exact thrown value as `cause`; a door whose body cannot throw carries no boundary, because wrapping code that cannot fail misreports where the refusals are. A boundary placed per STATEMENT is only ever as complete as the last sweep, while a boundary at the door covers whatever the body reaches, enumerated or not. Its limits are named rather than promised away. A boundary covers a BODY, so it cannot reach a parameter-default initializer, which is evaluated in the function environment before the first statement runs: the one such default this package had (`compileGenerator`'s wall-clock seed) was moved into the contained body, and any future computed default belongs there too. And a boundary is not a fidelity guarantee: containment answers what a door may THROW, while what a door PUBLISHES under a redirect that lies instead of throwing is the separate job of `INTRINSICS`, the module-scope membership functions layered over it, and the indexed publication walks. Every such site is reached from the captured table — which is a claim a sweep checks, not a claim this sentence makes.
349
361
 
@@ -568,7 +580,7 @@ whole surface is the readonly data properties — `schema` (a `JSONSchema`), `gu
568
580
  value the corresponding getter publishes — `contract.is` is exactly `compiler.guard`, by
569
581
  identity rather than as a copy of it.
570
582
 
571
- Compilation costs ONE ownership and ONE validation per call, not one per node. Every `compile*` entry and `createContract` construct a `ContractCompiler`, which owns the declaration once, validates that owned graph once, and indexes each unique node and structural edge once; the artifact families are postorder passes over that index. This is what replaced the arrangement where each recursive invocation re-ran `ownShape` AND `validateShape` over the subgraph it received — quadratic work for a linear declaration, and the reason a 129-node depth chain used to measure 6.3 ms of gate plus 7.9 ms of ownership and a 257-node chain 26.0 + 41.9 ms. A 30-alias depth-100 declaration now compiles a guard in 3 ms and a whole contract in 4 ms, against 640 ms and 1.87 s before. `createContract` precompiles every artifact, so `audit`, `explain` and `generate` re-walk and re-gate nothing on a later call either; `contract.audit` and `compileAuditor` are the same compiled function reached by different names. A compiled artifact is no longer a TREE either. Each family holds one entry per unique node and a parent points at its children, so a shared child is compiled once and the emitted schema preserves that sharing — which is why the cap boundary stopped being expensive: `createContract` over the two-edge-per-level DAG at the 16,383-node boundary now takes under a millisecond where it took 1,342 ms, because it compiles fourteen nodes rather than sixteen thousand. Cost tracks AUTHORED nodes and edges instead: measured here, a depth-100 chain and a 30-alias depth-100 staircase answer every door in 1–5 ms, and a flat 10,001-node object takes 52–68 ms per artifact and 110 ms for a whole contract. One level past the cap boundary — 32,767 emitted nodes over thirty-one authored ones — still refuses in about two milliseconds with code `expansion`, because the count is measured over the captured graph rather than by walking the expansion. What the cap now protects is the consumer's side of the artifacts rather than the compiler's: `generate` materializes the whole tree, and so does serializing the schema. The JSON cloner is capped for the opposite reason — it DUPLICATES a shared alias by contract rather than re-walking it: see `CLONE_NODE_LIMIT`. The `samplesToSchema` family is not on this list and was never meant to be reachable: its record path carried neither an ancestor set nor a memo, so an ordinary shared reference bought `k^depth` visits; it now memoizes a single-row slot on `(row, remaining depth)` exactly as the record branch of `valueToSchema` does. Everything above is the DECLARATION side, and for one release that was the only side measured. A compiled artifact applies each child artifact once per OCCURRENCE, which is right for a tree and wrong for a graph, so a value whose levels each held two references to one object was walked once per PATH: twenty-two shared arrays against a twenty-three-node chain of `arrayShape` — zero aliases in the declaration, every published limit satisfied — cost 524,286 node reads, 4.4 s for `is` and 8.4 s for `audit`, growing fourfold per two levels, while the same declaration over a TREE value answered instantly and `valueToSchema` answered the same graph in 4 ms because it already memoized. The verdict families now carry a per-CALL identity memo keyed by `(compiled node, value object)`, and the same value now costs thirty-six reads and under a millisecond. These details are exact rather than incidental. The guard reuses either answer while the auditor and reporter reuse only the CLEAN one, because a fault carries the path it was found at and emptiness carries nothing — a faulted node is re-walked and bounded by `FAULT_LIMIT` instead. Each node's memo is tagged with the call that filled it and nothing else releases it, so an answer never survives into a later call where the caller may have changed the value. And a leaf is not tracked at all: it descends into no child, so tracking one would buy nothing and would replace the package's own guards and parsers in the artifacts a leaf-rooted declaration publishes. `parse` is deliberately absent from that list, because its result IS the expansion; the threat model names what that costs.
583
+ Compilation costs ONE ownership and ONE validation per call, not one per node. Every `compile*` entry and `createContract` construct a `ContractCompiler`, which owns the declaration once, validates that owned graph once, and indexes each unique node and structural edge once; the artifact families are postorder passes over that index. This is what replaced the arrangement where each recursive invocation re-ran `ownShape` AND `validateShape` over the subgraph it received — quadratic work for a linear declaration, and the reason a 129-node depth chain used to measure 6.3 ms of gate plus 7.9 ms of ownership and a 257-node chain 26.0 + 41.9 ms. A 30-alias depth-100 declaration now compiles a guard in 3 ms and a whole contract in 4 ms, against 640 ms and 1.87 s before. `createContract` precompiles every artifact, so `audit`, `explain` and `generate` re-walk and re-gate nothing on a later call either; `contract.audit` and `compileAuditor` are the same compiled function reached by different names. A compiled artifact is no longer a TREE either. Each family holds one entry per unique node and a parent points at its children, so a shared child is compiled once and the emitted schema preserves that sharing — which is why the cap boundary stopped being expensive: `createContract` over the two-edge-per-level DAG at the 16,383-node boundary now takes under a millisecond where it took 1,342 ms, because it compiles fourteen nodes rather than sixteen thousand. Cost tracks AUTHORED nodes and edges instead: measured here, a depth-100 chain and a 30-alias depth-100 staircase answer every door in 1–5 ms, and a flat 10,001-node object takes 52–68 ms per artifact and 110 ms for a whole contract. One level past the cap boundary — 32,767 emitted nodes over thirty-one authored ones — still refuses in about two milliseconds with code `expansion`, because the count is measured over the captured graph rather than by walking the expansion. What the cap now protects is the consumer's side of the artifacts rather than the compiler's: `generate` materializes the whole tree, and so does serializing the schema. The JSON cloner is capped for the opposite reason — it DUPLICATES a shared alias by contract rather than re-walking it: see `CLONE_NODE_LIMIT`. The `samplesToSchema` family is not on this list and was never meant to be reachable: its record path carried neither an ancestor set nor a memo, so an ordinary shared reference bought `k^depth` visits; it now memoizes a single-row slot on `(row, remaining depth)` exactly as the record branch of `valueToSchema` does. Everything above is the DECLARATION side, and for one release that was the only side measured. A compiled artifact applies each child artifact once per OCCURRENCE, which is right for a tree and wrong for a graph, so a value whose levels each held two references to one object was walked once per PATH: twenty-two shared arrays against a twenty-three-node chain of `arrayShape` — zero aliases in the declaration, every published limit satisfied — cost 524,286 node reads, 4.4 s for `is` and 8.4 s for `audit`, growing fourfold per two levels, while the same declaration over a TREE value answered instantly and `valueToSchema` answered the same graph in 4 ms because it already memoized. The verdict families now carry a per-CALL identity memo keyed by `(compiled node, value object)`, and the same value now costs thirty-six reads and under a millisecond. These details are exact rather than incidental. The guard reuses either answer while the auditor and reporter reuse only the CLEAN one, because a fault carries the path it was found at and emptiness carries nothing — a faulted node is re-walked and bounded by `FAULT_LIMIT` instead. The active synchronous call owns each node's memo and releases the scope on settlement, so an answer never survives into a later call where the caller may have changed the value. And a leaf is not tracked at all: it descends into no child, so tracking one would buy nothing and would replace the package's own guards and parsers in the artifacts a leaf-rooted declaration publishes. `parse` is deliberately absent from that list, because its result IS the expansion; the threat model names what that costs.
572
584
 
573
585
  String and array length bounds deliberately use the builders' FULL rule — every present bound is a non-negative safe integer — rather than merely checking finiteness. A finiteness-only gate would close the `NaN` / infinity bypass but still admit hand-authored negative, fractional, and unsafe-integer length keywords that no builder can produce and that are not valid JSON Schema length bounds. Matching the builders costs compatibility only for those already-malformed hand-authored shapes; it preserves every legitimate builder output and keeps guard, parser, audit, and schema semantics on one domain.
574
586
 
@@ -1191,3 +1203,26 @@ contract.explain({ id: 'nope', name: 'x', role: 'y' })
1191
1203
 
1192
1204
  - [`AGENTS.md`](../AGENTS.md) — the rules; see § Documentation contract. Guard totality and parse↔guard soundness are `.claude/rules/patterns.md` § Validation and contracts.
1193
1205
  - [`README.md`](README.md) — the guides index.
1206
+
1207
+ ### Indexed derivation helpers
1208
+
1209
+ These leaves expose the indexed operations used by the compiler and inference engines. `readIndexView` forwards lazy length, membership, and element reads through the source receiver while giving captured array methods a non-array receiver, preventing constructor and species lookup. Its callbacks receive the view as their collection argument. Array construction consumes the pinned indexed cursors instead of synthetic objects that could inherit an iterator. `iterateIndices` rereads its bound before each step and yields the last index below a fractional bound. `encodeParts` stops before an unencodable member; `parseEnumValues` includes the first invalid member as `undefined` and then stops. Their iterator protocols are pinned when the module evaluates. These leaves propagate failed input observations to their consuming boundary.
1210
+
1211
+ ```ts
1212
+ import {
1213
+ buildPositions,
1214
+ encodeParts,
1215
+ iterateIndices,
1216
+ parseEnumValues,
1217
+ previewParts,
1218
+ readPresence,
1219
+ } from '@orkestrel/contract'
1220
+
1221
+ Array.from(iterateIndices(() => 2.5)) // [0, 1, 2]
1222
+ Array.from(encodeParts([1, undefined, 2], undefined, new WeakMap())) // ['1']
1223
+ Array.from(parseEnumValues(['a', 'x', 'b'], ['a', 'b'])) // ['a', undefined]
1224
+ previewParts('abc', 0, 2, false) // ['a', 'b', '…']
1225
+ const positions = buildPositions(['id', '__proto__'])
1226
+ positions.id // 0
1227
+ readPresence(['__proto__'], positions) // 2
1228
+ ```
@@ -256,6 +256,11 @@ not a separate parser: call `renderCSV` with `delimiter: '\t'`.
256
256
 
257
257
  ## Total parsing and the error model
258
258
 
259
+ `isCSVError` recognizes the error's own identity brand, declared code, and
260
+ optional location and context members across package copies. It accepts subclass
261
+ instances without requiring an exact name and refuses transparent proxies,
262
+ unbranded look-alikes, and plain objects carrying only the brand.
263
+
259
264
  `parseCSV` never throws on malformed DATA — every malformation (an
260
265
  unterminated quote, a bad quote placement, a ragged row, a duplicate or
261
266
  empty header, the record limit) is collected as a `CSVError` into the
@@ -83,14 +83,17 @@ produces the JSON Schema, and seeds fixtures.
83
83
 
84
84
  ### Classes
85
85
 
86
- | Class | Kind | Summary |
87
- | ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
88
- | `Database` | class | Exposes a typed view over one shared internal lifecycle and storage context. |
89
- | `DriverIterator` | class | Forms the internal continuation boundary for a root driver async iterator. |
90
- | `MemoryDriver` | class | Implements the reference `DriverInterface` — nested maps, no I/O. |
91
- | `JSONDriver` | class | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
92
- | `SQLiteDriver` | class | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
93
- | `IndexedDBDriver` | class | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
86
+ | Class | Kind | Summary |
87
+ | ------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
88
+ | `Database` | class | Exposes a typed view over one shared internal lifecycle and storage context. |
89
+ | `DriverIterator` | class | Forms the internal continuation boundary for a root driver async iterator. |
90
+ | `MemoryDriver` | class | Implements the reference `DriverInterface` — nested maps, no I/O. |
91
+ | `JSONDriver` | class | Implements a persistent `DriverInterface` backed by a single JSON file — the reference `MemoryDriver` plus file load / flush. |
92
+ | `SQLiteDriver` | class | Implements the `DriverInterface` over SQLite — the server-native, trusted-mode backend built on the published `@orkestrel/sqlite` synchronous wrapper. |
93
+ | `IndexedDBDriver` | class | Implements the `DriverInterface` over IndexedDB — the persistent browser backend, built on the published `@orkestrel/indexeddb` wrapper. |
94
+ | `StreamPage` | class | Tracks the matching-row position of one streaming page. |
95
+ | `JSONTransaction` | class | Owns the isolated memory store and schema of one JSON transaction. |
96
+ | `SQLiteTransaction` | class | Owns the candidate schema and table identities of one SQLite transaction. |
94
97
 
95
98
  ### Server
96
99
 
@@ -135,6 +138,7 @@ None of these import a SQLite package; they speak strings and values only.
135
138
  | `schemaToTable` | function | Projects a `TableSchema` to its `CREATE TABLE IF NOT EXISTS` statement. |
136
139
  | `schemaToIndexes` | function | Projects a `TableSchema` to its declared SQLite indexes. |
137
140
  | `stepToSQL` | function | Projects one `MigrationStep` to SQLite DDL. |
141
+ | `compileBoundSQL` | function | Encodes condition operands for a SQL fragment using their declared or inferred storage. |
138
142
 
139
143
  ### Browser
140
144
 
@@ -160,6 +164,13 @@ lossy.
160
164
  | `DatabaseError` | class | Represents an error thrown by the database layer. |
161
165
  | `isDatabaseError` | function | Narrows an unknown caught value to a `DatabaseError`. |
162
166
 
167
+ The constructor installs an own, non-enumerable, non-writable
168
+ `Symbol.for('@orkestrel/database.DatabaseError')` property whose value is the
169
+ error itself. `isDatabaseError` accepts branded subclasses across package copies
170
+ and ESM/CJS entries without requiring an exact `name`. It validates the declared
171
+ code and optional context, and refuses unbranded look-alikes, transparent proxies,
172
+ and plain objects carrying only the brand.
173
+
163
174
  ### Query engine
164
175
 
165
176
  The portable semantics every backend shares — pure, total functions the
@@ -223,6 +234,7 @@ Pure helpers behind the query engine's pattern matching.
223
234
  | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
224
235
  | `cloneDriverMetadata` | function | Clones unknown driver metadata into a distinct deeply frozen snapshot. |
225
236
  | `matchesWildcardPattern` | function | Matches a value against a wildcard pattern in linear time — the shared, ReDoS-safe engine behind `matchesLikePattern` and `matchesGlobPattern`. |
237
+ | `matchesWildcardSegment` | function | Checks whether a fixed-length wildcard segment matches a value at an offset. |
226
238
  | `matchesLikePattern` | function | Matches a value against a SQL `LIKE` pattern, folding case. |
227
239
  | `matchesGlobPattern` | function | Matches a value against a `GLOB` pattern, preserving case. |
228
240
  | `isDriverMetadata` | function | Checks whether a value is persisted driver metadata. |
@@ -235,6 +247,7 @@ Pure helpers behind the query engine's pattern matching.
235
247
  | `isKey` | function | Checks whether a value is a usable database key. |
236
248
  | `cloneDriverSchema` | function | Clones unknown driver schema into a distinct deeply frozen snapshot. |
237
249
  | `cloneMigrationInput` | function | Clones unknown migration input into a distinct deeply frozen snapshot. |
250
+ | `captureFailure` | function | Captures the exact rejection or synchronous throw from a driver conformance operation. |
238
251
 
239
252
  ### Constants
240
253
 
@@ -296,6 +309,43 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
296
309
  | `QueryInterface` | interface | `{} plus condition, order, filter, limit, offset, collect, find, count, stream, aggregate` | Builds a read through a fluent chain. |
297
310
  | `CursorInterface` | interface | `{ value, index, done } plus next, update, remove, close` | Walks a table's rows forward for bulk in-place mutation. |
298
311
 
312
+ ### Operation state
313
+
314
+ `StreamPage(offset)` owns one stream's matching-row position. `next()` advances
315
+ that position and returns whether it exceeds the offset; `count` reports the
316
+ number of matching rows after the offset.
317
+
318
+ The server transaction entities hold each transaction's candidate schema and
319
+ table identities. `SQLiteTransaction(schema, identities)` copies the initial
320
+ maps; `project(schema, identities)` replaces the candidate state.
321
+ `JSONTransaction(memory, schema, identities)` owns the candidate memory driver;
322
+ its `project` replaces the schema and identities, and `stop()` invalidates the
323
+ `memory` getter with `CONFLICT`. Their `schema` and `identities` getters expose
324
+ readonly views. Drivers retain these entities in transaction registries until
325
+ settlement.
326
+
327
+ ```ts
328
+ import { captureFailure, MemoryDriver, StreamPage } from '@orkestrel/database'
329
+ import { compileBoundSQL, JSONTransaction, SQLiteTransaction } from '@orkestrel/database/server'
330
+
331
+ const page = new StreamPage(1)
332
+ page.next() // false
333
+ page.next() // true
334
+ page.count // 1
335
+
336
+ const sqlite = new SQLiteTransaction(new Map(), new Map())
337
+ sqlite.project([], new Map())
338
+ sqlite.schema.size // 0
339
+
340
+ const json = new JSONTransaction(new MemoryDriver(), [], new Map())
341
+ json.project([], new Map())
342
+ json.stop()
343
+ await captureFailure(async () => json.memory) // DatabaseError with code CONFLICT
344
+
345
+ compileBoundSQL('"age" > ?', [18], false, undefined)
346
+ // { sql: '"age" > ?', parameters: ['18'] }
347
+ ```
348
+
299
349
  ## Methods
300
350
 
301
351
  The public methods of each behavioral interface — one table per type, keyed
@@ -207,6 +207,18 @@ projection.
207
207
  | `serializeForm` | function | Projects a schema into JSON while removing custom validators and absent values. |
208
208
  | `extractGroups` | function | Selects referenced groups in first-reference field order. |
209
209
  | `auditSchema` | function | Audits a structurally valid schema for domain invariants. |
210
+ | `failsFieldBound` | function | Checks whether a field value violates a numeric or temporal bound. |
211
+ | `failsTextRule` | function | Checks whether text violates an enabled lexical field rule. |
212
+
213
+ The evaluation engine exposes its bound and lexical predicates for independent rule checks.
214
+ The boolean selects the minimum bound when true and the maximum bound when false.
215
+
216
+ ```ts
217
+ import { failsFieldBound, failsTextRule } from '@orkestrel/form'
218
+
219
+ failsFieldBound({ control: 'text', name: 'name' }, 'Ada', { minimum: 4 }, true) // true
220
+ failsTextRule({ email: true }, 'email', 'invalid') // true
221
+ ```
210
222
 
211
223
  ### Cloners
212
224
 
@@ -1963,6 +1975,11 @@ The native binding exposes only synchronization and teardown methods.
1963
1975
  value with `isFormError` and branch on `code`; never match on message text. A custom validator's own
1964
1976
  throw is the caller's exception and escapes unchanged.
1965
1977
 
1978
+ `isFormError` and `isFormBindingError` accept self-branded instances from another installed copy
1979
+ and subclass instances, even when their `name` differs. Each guard checks the global `Error`
1980
+ prototype chain, its own identity brand, its declared code, message, and context. Unbranded
1981
+ look-alikes, transparent proxies, and plain branded objects are refused.
1982
+
1966
1983
  | Code | Raised when |
1967
1984
  | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1968
1985
  | `SCHEMA` | The schema is not a form schema, `auditSchema` found a domain fault, or `cloneFormField` cannot own a field's `meta`. The constructor raises each; `cloneFormField` and `serializeForm` each raise the metadata one on their own. |
@@ -31,39 +31,42 @@ precedence. This package publishes core through `@orkestrel/guide` and the comma
31
31
  The manifest/extraction shapes every check is built from, from [`types.ts`](../src/core/types.ts).
32
32
  A `Shape` cell lists an interface's property names alone, and a type alias's value.
33
33
 
34
- | Name | Kind | Shape | Summary |
35
- | ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
36
- | `ExportKeyword` | type | `'type' \| 'interface' \| 'const' \| 'function' \| 'class'` | Represents the declaration keyword a documented / exported symbol carries — the reflected `type`, `interface`, `const`, `function`, and `class` heads, derived from `EXPORT_KEYWORDS` so the type, the guard, and the shape name one population. Comment/template payload is excluded before reflection. `enum` is outside this population, not forbidden by general package policy. |
37
- | `SurfaceSymbol` | interface | `{ name, keyword, summary? }` | Represents one documented / exported symbol — its identifier, its declaration keyword, and the description paragraph the guide and the doc block are compared on. |
38
- | `GuideModule` | type | `string \| readonly string[]` | Represents the source scope a guide's manifest entry covers — one module directory, or several when a layer guide spans multiple source directories (a core module plus its backend implementations). `'.'` is the canonical workspace-root directory; empty, trailing-slash, and dot-segment spellings canonicalize to the same value before reflection. |
39
- | `SourceLine` | interface | `{ source, code, jsdoc }` | Represents one terminator-free physical source line and its aligned reflection projections. Every projection has the same length as `source`, and every genuine JSDoc span retains its physical opener column; the final physical line is present even when it is empty. |
40
- | `SourceComment` | interface | `{ text, line }` | Represents one eligible genuine JSDoc block paired with the physical record it documents — the block's unwrapped body and the `SourceLine` that follows its chain. |
41
- | `MethodEntry` | interface | `{ name, summary? }` | Represents one documented method — its identifier plus the description paragraph the guide's `Summary` cell and the member's doc block are compared on. |
42
- | `SourceExample` | interface | `{ name, title?, code, language? }` | Represents one `@example` block read from a doc comment — the declaration it documents, its pairing title, its code, and its fence language. |
43
- | `DriftCategory` | type | `'summary' \| 'example'` | Represents the compared site one disagreement came from. |
44
- | `Drift` | interface | `{ key, category, guide?, source? }` | Represents one disagreement between a guide and the source it documents — the compared key with the text each side carries there, the side carrying no text omitted. |
45
- | `ManifestEntry` | interface | `{ concept, spec, source, tests }` | Represents one `## By concept` manifest row — a single guides-parity check target, paths normalized to workspace root. |
46
- | `ParityPitch` | interface | `{ readme, spec }` | Names the inventory keys paired for README pitch parity. |
47
- | `ParityOptions` | interface | `{ files, entries, modules, languages, language, pitch? }` | Represents the pure inputs that configure a guides-parity composition. |
48
- | `ParityRow` | interface | `{ entry, guide, source }` | Represents a manifest row joined to its parsed guide and reflected source. |
49
- | `ParityFinding` | interface | `{ spec?, text }` | Represents a preformatted guides-parity finding. |
50
- | `ParityExampleResult` | interface | `{ fences, functions, methods, titles }` | Groups executable-example findings by their independent evidence populations. |
51
- | `ParityResult` | interface | `{ input, sections, surface, methods, declarations, links, tests, fences, examples, imports, drift, pitch }` | Groups independently assertable guides-parity findings by subject. |
52
- | `ParityDirection` | type | `'guide' \| 'source'` | Represents the destination an explicit parity rewrite updates. |
53
- | `ParityChange` | interface | `{ path, content }` | Represents a changed inventory text returned by a parity rewrite. |
54
- | `ParityRewriteResult` | interface | `{ changes, findings }` | Represents the changed texts and unresolved findings from an explicit rewrite. |
55
- | `ParityInterface` | interface | `{ rows, inspect, document, annotate }` | Represents a pure guides-parity composition over caller-supplied inventory. |
56
- | `MethodGroup` | interface | `{ interface, methods }` | Represents one behavioral interface a guide's `## Methods` section documents — the H4 heading naming that interface as a code span, and the member entries its table lists. |
57
- | `FenceImport` | interface | `{ specifier, names }` | Represents one brace `import` statement projected from a guide fence — its specifier paired with the exported names it binds. |
58
- | `GuideFence` | interface | `{ language, code, title? }` | Represents one fenced code block projected from a guide document — its `language` is the fence's info-string tag and is absent when the fence is untagged, and its `title` is the flattened text of its nearest preceding heading. |
59
- | `GuideInterface` | interface | `{ sections, tagline, surface, methods, unnamed, links, tests, fences }` | Represents the structured, pure view of one parsed guide — every projection extracted and cached once at construction (see `createGuide`). |
60
- | `SourceInterface` | interface | `{ exports, surface, methods, exists, hidden, examples }` | Represents the reflected source truth a guide's documented surface is checked against — a pure view over a consumer-supplied file inventory (see `Source`). |
61
- | `SourceManagerInterface` | interface | `{ source, sources }` | Represents a specifier resolver that shares one `SourceInterface` per module and enumerates those views. |
62
- | `SourceOptions` | interface | `{ files, module }` | Represents the construction input for a `Source` — a consumer-supplied file inventory (root-relative path → file text) plus the module scope to reflect. The consumer gathers `files` however their environment allows (`node:fs` in a Node script, `import.meta.glob` in a browser/vitest run) — `Source` itself never touches disk. |
63
- | `SourceManagerOptions` | interface | `{ files, modules }` | Represents the construction input for a `SourceManager`: one shared file inventory plus the consumer's specifier-to-module policy. |
64
- | `DeclarationHead` | interface | `{ text, end }` | Pairs a declaration head joined into a single line with the index of the line carrying its opening `{` — how a head that oxfmt wrapped across lines (printWidth 100) is matched as if it were written on one. |
65
- | `Declaration` | interface | `{ body, bases }` | Represents one located `export class` / `export interface` declaration — the body lines and the base identifiers read from the same head, so a consumer never pairs one declaration's body with another declaration's heritage (see `collectDeclarations`). |
66
- | `DeclarationKeyword` | type | `'class' \| 'interface'` | Represents which declaration head `collectDeclarations` and `Source` locate — a `class` or an `interface`. That pair is the subset of `ExportKeyword` carrying a body whose members a guide's `## Methods` table documents. |
34
+ | Name | Kind | Shape | Summary |
35
+ | ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
36
+ | `ExportKeyword` | type | `'type' \| 'interface' \| 'const' \| 'function' \| 'class'` | Represents the declaration keyword a documented / exported symbol carries — the reflected `type`, `interface`, `const`, `function`, and `class` heads, derived from `EXPORT_KEYWORDS` so the type, the guard, and the shape name one population. Comment/template payload is excluded before reflection. `enum` is outside this population, not forbidden by general package policy. |
37
+ | `SurfaceSymbol` | interface | `{ name, keyword, summary? }` | Represents one documented / exported symbol — its identifier, its declaration keyword, and the description paragraph the guide and the doc block are compared on. |
38
+ | `GuideModule` | type | `string \| readonly string[]` | Represents the source scope a guide's manifest entry covers — one module directory, or several when a layer guide spans multiple source directories (a core module plus its backend implementations). `'.'` is the canonical workspace-root directory; empty, trailing-slash, and dot-segment spellings canonicalize to the same value before reflection. |
39
+ | `SourceLine` | interface | `{ source, code, jsdoc }` | Represents one terminator-free physical source line and its aligned reflection projections. Every projection has the same length as `source`, and every genuine JSDoc span retains its physical opener column; the final physical line is present even when it is empty. |
40
+ | `SourceParenthesis` | interface | `{ role, phase, binding, previous }` | Represents one parenthesis frame in the source projector's lexical stack. |
41
+ | `SourceTemplate` | interface | `{ depth, previous }` | Represents one template frame in the source projector's lexical stack. |
42
+ | `SourceProjection` | interface | `{ offset, start, token, mode, escaped, regex, operand, member, role, restricted, separated, block, line, jsdoc, present, parentheses, templates }` | Represents the immutable continuation of a source-character projection. |
43
+ | `SourceComment` | interface | `{ text, line }` | Represents one eligible genuine JSDoc block paired with the physical record it documents — the block's unwrapped body and the `SourceLine` that follows its chain. |
44
+ | `MethodEntry` | interface | `{ name, summary? }` | Represents one documented method — its identifier plus the description paragraph the guide's `Summary` cell and the member's doc block are compared on. |
45
+ | `SourceExample` | interface | `{ name, title?, code, language? }` | Represents one `@example` block read from a doc comment — the declaration it documents, its pairing title, its code, and its fence language. |
46
+ | `DriftCategory` | type | `'summary' \| 'example'` | Represents the compared site one disagreement came from. |
47
+ | `Drift` | interface | `{ key, category, guide?, source? }` | Represents one disagreement between a guide and the source it documents — the compared key with the text each side carries there, the side carrying no text omitted. |
48
+ | `ManifestEntry` | interface | `{ concept, spec, source, tests }` | Represents one `## By concept` manifest row — a single guides-parity check target, paths normalized to workspace root. |
49
+ | `ParityPitch` | interface | `{ readme, spec }` | Names the inventory keys paired for README pitch parity. |
50
+ | `ParityOptions` | interface | `{ files, entries, modules, languages, language, pitch? }` | Represents the pure inputs that configure a guides-parity composition. |
51
+ | `ParityRow` | interface | `{ entry, guide, source }` | Represents a manifest row joined to its parsed guide and reflected source. |
52
+ | `ParityFinding` | interface | `{ spec?, text }` | Represents a preformatted guides-parity finding. |
53
+ | `ParityExampleResult` | interface | `{ fences, functions, methods, titles }` | Groups executable-example findings by their independent evidence populations. |
54
+ | `ParityResult` | interface | `{ input, sections, surface, methods, declarations, links, tests, fences, examples, imports, drift, pitch }` | Groups independently assertable guides-parity findings by subject. |
55
+ | `ParityDirection` | type | `'guide' \| 'source'` | Represents the destination an explicit parity rewrite updates. |
56
+ | `ParityChange` | interface | `{ path, content }` | Represents a changed inventory text returned by a parity rewrite. |
57
+ | `ParityRewriteResult` | interface | `{ changes, findings }` | Represents the changed texts and unresolved findings from an explicit rewrite. |
58
+ | `ParityInterface` | interface | `{ rows, inspect, document, annotate }` | Represents a pure guides-parity composition over caller-supplied inventory. |
59
+ | `MethodGroup` | interface | `{ interface, methods }` | Represents one behavioral interface a guide's `## Methods` section documents — the H4 heading naming that interface as a code span, and the member entries its table lists. |
60
+ | `FenceImport` | interface | `{ specifier, names }` | Represents one brace `import` statement projected from a guide fence — its specifier paired with the exported names it binds. |
61
+ | `GuideFence` | interface | `{ language, code, title? }` | Represents one fenced code block projected from a guide document — its `language` is the fence's info-string tag and is absent when the fence is untagged, and its `title` is the flattened text of its nearest preceding heading. |
62
+ | `GuideInterface` | interface | `{ sections, tagline, surface, methods, unnamed, links, tests, fences }` | Represents the structured, pure view of one parsed guide — every projection extracted and cached once at construction (see `createGuide`). |
63
+ | `SourceInterface` | interface | `{ exports, surface, methods, exists, hidden, examples }` | Represents the reflected source truth a guide's documented surface is checked against — a pure view over a consumer-supplied file inventory (see `Source`). |
64
+ | `SourceManagerInterface` | interface | `{ source, sources }` | Represents a specifier resolver that shares one `SourceInterface` per module and enumerates those views. |
65
+ | `SourceOptions` | interface | `{ files, module }` | Represents the construction input for a `Source` — a consumer-supplied file inventory (root-relative path → file text) plus the module scope to reflect. The consumer gathers `files` however their environment allows (`node:fs` in a Node script, `import.meta.glob` in a browser/vitest run) — `Source` itself never touches disk. |
66
+ | `SourceManagerOptions` | interface | `{ files, modules }` | Represents the construction input for a `SourceManager`: one shared file inventory plus the consumer's specifier-to-module policy. |
67
+ | `DeclarationHead` | interface | `{ text, end }` | Pairs a declaration head joined into a single line with the index of the line carrying its opening `{` — how a head that oxfmt wrapped across lines (printWidth 100) is matched as if it were written on one. |
68
+ | `Declaration` | interface | `{ body, bases }` | Represents one located `export class` / `export interface` declaration — the body lines and the base identifiers read from the same head, so a consumer never pairs one declaration's body with another declaration's heritage (see `collectDeclarations`). |
69
+ | `DeclarationKeyword` | type | `'class' \| 'interface'` | Represents which declaration head `collectDeclarations` and `Source` locate — a `class` or an `interface`. That pair is the subset of `ExportKeyword` carrying a body whose members a guide's `## Methods` table documents. |
67
70
 
68
71
  The server command contracts come from [`types.ts`](../src/server/types.ts).
69
72