@orkestrel/scaffold 0.0.119 → 0.0.120

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +27 -26
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/budget.md +1 -5
  11. package/dist/host/guides/codec.md +18 -3
  12. package/dist/host/guides/contract.md +23 -44
  13. package/dist/host/guides/csv.md +86 -93
  14. package/dist/host/guides/database.md +0 -4
  15. package/dist/host/guides/emitter.md +0 -2
  16. package/dist/host/guides/form.md +26 -47
  17. package/dist/host/guides/html.md +3 -7
  18. package/dist/host/guides/indexeddb.md +28 -32
  19. package/dist/host/guides/jsonrpc.md +187 -0
  20. package/dist/host/guides/markdown.md +132 -141
  21. package/dist/host/guides/msg.md +47 -63
  22. package/dist/host/guides/ndjson.md +0 -4
  23. package/dist/host/guides/pool.md +0 -4
  24. package/dist/host/guides/process.md +71 -79
  25. package/dist/host/guides/reason.md +30 -36
  26. package/dist/host/guides/router.md +11 -18
  27. package/dist/host/guides/scaffold.md +136 -136
  28. package/dist/host/guides/sqlite.md +0 -4
  29. package/dist/host/guides/sse.md +6 -10
  30. package/dist/host/guides/table.md +481 -493
  31. package/dist/host/guides/template.md +0 -4
  32. package/dist/host/guides/test.md +46 -66
  33. package/dist/host/guides/timeout.md +0 -6
  34. package/dist/host/guides/tool.md +2 -6
  35. package/dist/host/guides/websocket.md +0 -4
  36. package/dist/host/manifest.json +39 -464
  37. package/dist/src/core/index.cjs +162 -177
  38. package/dist/src/core/index.cjs.map +1 -1
  39. package/dist/src/core/index.d.cts +213 -213
  40. package/dist/src/core/index.d.ts +213 -213
  41. package/dist/src/core/index.js +151 -166
  42. package/dist/src/core/index.js.map +1 -1
  43. package/dist/src/server/index.cjs +25 -25
  44. package/dist/src/server/index.cjs.map +1 -1
  45. package/dist/src/server/index.d.cts +50 -50
  46. package/dist/src/server/index.d.ts +50 -50
  47. package/dist/src/server/index.js +26 -26
  48. package/dist/src/server/index.js.map +1 -1
  49. package/package.json +9 -9
@@ -25,8 +25,6 @@ Sibling families, each with its own job:
25
25
 
26
26
  The `*Field` parsers read a (possibly nested) record field through a `FieldPath` (`string | readonly string[]`, in [`src/core/types.ts`](../src/core/types.ts)) — a single string is **one** key (no dot-splitting); an array descends own properties of nested objects/arrays through the `resolveField` core helper. The root must satisfy `isRecord`, and inherited properties are rejected at every segment. This is deliberate: a field reader receives a record, so accepting a root the module's record guard rejects or a value visible only through its prototype would contradict that contract; arrays remain supported as nested containers because indexed path segments are their own properties. The `whereOf` / `lazyOf` / `transformOf` combinators run caller-supplied callbacks _inside_ a guard body; they contain any throw through the core `attempt` helper, so even a guard that runs your code stays total and returns `false` rather than propagating.
27
27
 
28
- In a guard table a `Shape` cell holds the type the guard narrows to.
29
-
30
28
  ### Primitive & null-ish guards
31
29
 
32
30
  | Name | Kind | Signature | Summary |
@@ -195,11 +193,6 @@ the constant's own literal:
195
193
 
196
194
  The safe JSON surface keeps text parsing lazy: `parseJSON` returns `unknown`, while `parseJSONAs` walks only the guard shape supplied by its caller. `isJSONValue` and `parseJSONValue` are shipped explicit deep whole-tree gates; `isBoundedJSONValue` adds the fixed resource boundary, and `isBoundedJSONRecord` adds the record-root invariant. `JSONRecord` and `cloneJSONRecord` provide the record-root ownership contract required by metadata and persistence consumers, while `cloneJSONValue` owns any JSON root. A dedicated `JSONArray` alias, broad deep `isJSONObject` / `isJSONSchema` validators, and the ~50-field `JSONSchemaDefinition` remain deliberately omitted. Compose narrower shapes from the combinators and read a parsed blob field-by-field with the `parse*Field` readers when whole-tree work is unnecessary.
197
195
 
198
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
199
- optional member and `plus` introducing its call-signature members, and a type alias's own type
200
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
201
- guard row's the type it narrows to.
202
-
203
196
  | Name | Kind | Signature | Summary |
204
197
  | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
205
198
  | `isJSONPrimitive` | function | `(value: unknown) => value is JSONPrimitive` | Determines whether a value is a primitive JSON value. |
@@ -224,12 +217,17 @@ guard row's the type it narrows to.
224
217
 
225
218
  | Name | Kind | Signature | Summary |
226
219
  | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
220
+ | `success` | function | `<T>(value: T) => Success<T>` | Boxes a value as the `Success` branch of a `Result`. |
221
+ | `failure` | function | `<E>(error: E) => Failure<E>` | Boxes an error as the `Failure` branch of a `Result`. |
222
+ | `isSuccess` | function | `<T, E>(result: Result<T, E>) => result is Success<T>` | Narrows a `Result` to its `Success` branch. |
223
+ | `isFailure` | function | `<T, E>(result: Result<T, E>) => result is Failure<E>` | Narrows a `Result` to its `Failure` branch. |
227
224
  | `attempt` | function | `<T>(callback: () => T) => Result<T>` | Invokes a callback once and synchronously captures its exact outcome as a `Result`. |
225
+ | `errorToMessage` | function | `(error: unknown) => string` | Renders a thrown value as a non-empty message. |
228
226
  | `INTRINSICS` | const | `Readonly<{ freeze: { <T extends Function>(f: T): T; <T extends { [idx: string]: U \| null \| undefined \| object; }, U extends string \| bigint \| number \| boolean \| symbol>(o: T): Readonly<T>; <T>(o: T): Readonly<T>; }; frozen: (o: any) => boolean; keys: { (o: object): string[]; (o: {}): string[]; }; values: { <T>(o: { [s: string]: T; } \| ArrayLike<T>): T[]; (o: {}): any[]; }; own: (o: object, v: PropertyKey) => boolean; same: (value1: any, value2: any) => boolean; create: { (o: object \| null): any; (o: object \| null, properties: PropertyDescriptorMap & ThisType<any>): any; }; proxy: ProxyConstructor; describe: (o: any, p: PropertyKey) => PropertyDescriptor \| undefined; define: <T>(o: T, p: PropertyKey, attributes: PropertyDescriptor & ThisType<any>) => T; definitions: <T>(o: T, properties: PropertyDescriptorMap & ThisType<any>) => T; prototype: (o: any) => any; symbols: (o: any) => symbol[]; base: Object; reflect: Readonly<{ read: typeof Reflect.get; write: typeof Reflect.set; members: typeof Reflect.ownKeys; present: typeof Reflect.has; describe: typeof Reflect.getOwnPropertyDescriptor; define: typeof Reflect.defineProperty; prototype: typeof Reflect.getPrototypeOf; apply: typeof Reflect.apply; construct: typeof Reflect.construct; }>; finite: (number: unknown) => boolean; integer: (number: unknown) => boolean; safe: (number: unknown) => boolean; nan: (number: unknown) => boolean; array: (arg: any) => arg is any[]; stringify: { (value: any, replacer?: (this: any, key: string, value: any) => any, space?: string \| number): string; (value: any, replacer?: (number \| string)[] \| null, space?: string \| number): string; }; decode: (text: string, reviver?: (this: any, key: string, value: any) => any) => any; floor: (x: number) => number; ceil: (x: number) => number; max: (...values: number[]) => number; min: (...values: number[]) => number; imul: (x: number, y: number) => number; text: StringConstructor; numeric: NumberConstructor; pattern: RegExpConstructor; captures: (string: string) => RegExpExecArray \| null; expression: (() => any) \| undefined; modifiers: (() => any) \| undefined; list: ArrayConstructor; order: (compareFn?: ((a: any, b: any) => number) \| undefined) => any[]; some: (predicate: (value: any, index: number, array: any[]) => unknown, thisArg?: any) => boolean; find: (predicate: (value: any, index: number, obj: any[]) => unknown, thisArg?: any) => number; each: (callbackfn: (value: any, index: number, array: any[]) => void, thisArg?: any) => void; from: { <T>(arrayLike: ArrayLike<T>): T[]; <T, U>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[]; <T>(iterable: Iterable<T> \| ArrayLike<T>): T[]; <T, U>(iterable: Iterable<T> \| ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[]; }; fold: { (callbackfn: (previousValue: any, currentValue: any, currentIndex: number, array: any[]) => any): any; (callbackfn: (previousValue: any, currentValue: any, currentIndex: number, array: any[]) => any, initialValue: any): any; <U>(callbackfn: (previousValue: U, currentValue: any, currentIndex: number, array: any[]) => U, initialValue: U): U; }; reduce: { (callbackfn: (previousValue: any, currentValue: any, currentIndex: number) => any): any; (callbackfn: (previousValue: any, currentValue: any, currentIndex: number) => any, initialValue: any): any; <U>(callbackfn: (previousValue: U, currentValue: any, currentIndex: number) => U, initialValue: U): U; }; select: { <S extends any>(predicate: (value: any, index: number, array: any[]) => value is S, thisArg?: any): S[]; (predicate: (value: any, index: number, array: any[]) => unknown, thisArg?: any): any[]; }; project: <U>(callbackfn: (value: any, index: number, array: any[]) => U, thisArg?: any) => U[]; expand: <U, This = undefined>(callback: (this: This, value: any, index: number, array: any[]) => U \| readonly U[], thisArg?: This \| undefined) => U[]; flip: () => any[]; iterator: () => ArrayIterator<any>; indices: () => ArrayIterator<number>; advance: any; join: (separator?: string) => string; bind: (this: Function, thisArg: any, ...argArray: any[]) => any; record: { <T = any>(entries: Iterable<readonly [PropertyKey, T]>): { [k: string]: T; }; (entries: Iterable<readonly any[]>): any; }; rebase: (o: any, proto: object \| null) => any; map: MapConstructor; fetch: (key: any) => any; store: (key: any, value: any) => Map<any, any>; keyed: (key: any) => boolean; pairs: (callbackfn: (value: any, key: any, map: Map<any, any>) => void, thisArg?: any) => void; set: SetConstructor; union: <U>(other: ReadonlySetLike<U>) => Set<any>; member: (value: any) => boolean; admit: (value: any) => Set<any>; sweep: (callbackfn: (value: any, value2: any, set: Set<any>) => void, thisArg?: any) => void; remove: (value: any) => boolean; weakMap: WeakMapConstructor; recall: (key: WeakKey) => any; retain: (key: WeakKey, value: any) => WeakMap<WeakKey, any>; weakSet: WeakSetConstructor; tracked: (value: WeakKey) => boolean; track: (value: WeakKey) => WeakSet<WeakKey>; untrack: (value: WeakKey) => boolean; error: ErrorConstructor; date: DateConstructor; instant: () => number; now: () => number; }>` | Captures every host operation this package dispatches through, while this module evaluates. |
229
227
  | `contain` | function | `<T>(callback: () => T, door: string, options?: ContainOptions) => T` | Runs a public door's whole body and publishes only this package's error class. |
230
228
  | `appendEntries` | function | `<T>(target: T[], source: readonly T[]) => void` | Appends every element of one array onto another, by index. |
231
229
  | `limitEntries` | function | `<T>(entries: readonly T[], limit: number) => readonly T[]` | Takes at most `limit` leading elements of an array, by index. |
232
- | `compareValues` | function | `<T extends string \| number>(left: T, right: T) => number` | Orders two primitive keys or indices ascending. |
230
+ | `comparePrimitives` | function | `<T extends string \| number>(left: T, right: T) => number` | Orders two primitive keys or indices ascending. |
233
231
  | `sortValues` | function | `<T extends string \| number>(values: readonly T[]) => readonly T[]` | Orders primitive keys or indices deterministically, on an owned copy, through the captured sort. |
234
232
  | `pathOf` | function | `(path: readonly string[], ...segments: ReadonlyArray<string \| undefined>) => readonly string[]` | Builds a diagnostic path from an existing path and further segments, without dispatching through array iteration. |
235
233
  | `readValue` | function | `<T>(callback: () => T, reader: string, options?: ReadValueOptions) => T` | Reads a value through the shared containment boundary or refuses it with the contract module's uniform read diagnostic. |
@@ -258,6 +256,7 @@ guard row's the type it narrows to.
258
256
  | `readSetEntries` | function | `(value: ReadonlySet<unknown>) => Result<readonly unknown[]>` | Snapshots the genuine contents of a caller's `Set` without running an iterator. |
259
257
  | `readMapEntries` | function | `(value: ReadonlyMap<unknown, unknown>) => Result<ReadonlyArray<readonly unknown[]>>` | Snapshots the genuine entries of a caller's `Map` without running an iterator. |
260
258
  | `matchesPattern` | function | `(pattern: RegExp, value: string) => boolean` | Determines whether a string is in the language of a pattern this package owns. |
259
+ | `escapeRegExp` | function | `(value: string) => string` | Escapes every regular-expression metacharacter in a text, so the text matches literally inside a larger `RegExp` source. |
261
260
  | `readPatternSource` | function | `(pattern: unknown) => string \| undefined` | Reads a regular expression's source text through the captured accessor. |
262
261
  | `readPatternFlags` | function | `(pattern: unknown) => string \| undefined` | Reads a regular expression's flag text through the captured accessor. |
263
262
  | `readPattern` | function | `(pattern: RegExp) => RegExp` | Rebuilds a caller's regular expression as a stateless pattern this package owns. |
@@ -279,6 +278,18 @@ guard row's the type it narrows to.
279
278
 
280
279
  `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.
281
280
 
281
+ ### Retention limits
282
+
283
+ A package whose schema retains authored data, such as a form or table schema, enforces the following limits; this package declares them and enforces none of them:
284
+
285
+ | Name | Kind | Signature | Summary |
286
+ | -------------- | ----- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
287
+ | `CHOICE_LIMIT` | const | `1024` | Caps at `1024` the number of choices one schema field may offer, frozen. |
288
+ | `NAME_LIMIT` | const | `128` | Caps at `128` the length, in UTF-16 code units, of one name a schema declares, frozen: a schema, group, or field name, or a column key. |
289
+ | `STRING_LIMIT` | const | `65536` | Caps at `65536` the length, in UTF-16 code units, of any single string one schema retains, frozen. |
290
+ | `TEXT_LIMIT` | const | `1048576` | Caps at `1048576` the total length, in UTF-16 code units, of every string one schema retains, frozen. |
291
+ | `NODE_LIMIT` | const | `16384` | Caps at `16384` the total number of records, arrays, and leaves one schema retains, frozen. |
292
+
282
293
  ### Membership
283
294
 
284
295
  Membership is the answer a validation package exists to be right about, and it is asked through MODULE BINDINGS rather than through any property. `Set` is the right data structure for SameValueZero membership and the wrong dispatch surface: a caller who writes `Set.prototype.has = () => true` changed what `contract.is`, `literalOf`, `enumOf` and `parseEnum` ANSWERED — no throw, no diagnostic, a wrong yes. Moving those reads onto the `has` method of an exported class reproduces the defect verbatim, because every public class method is dispatched through a prototype every consumer can reach. Relocating an answer onto a reachable member moves the defect rather than removing it. This package instead asks through a module-scope function, which the specification makes immutable to every importer, over an operation `INTRINSICS` captured while it evaluated.
@@ -309,10 +320,6 @@ What is NOT guaranteed, beyond the realm assumption above: a value whose observa
309
320
 
310
321
  ### Types
311
322
 
312
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
313
- optional member and `plus` introducing its call-signature members, and a type alias's own type
314
- literal with a union's arms escaped as `\|`.
315
-
316
323
  | Name | Kind | Signature | Summary |
317
324
  | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
318
325
  | `Failure` | interface | `{ success, error }` | Represents the discriminated failure branch of a `Result`. |
@@ -353,9 +360,9 @@ literal with a union's arms escaped as `\|`.
353
360
 
354
361
  ### `ContractError`
355
362
 
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.
363
+ `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.ContractError')` passes recognition. The brand is therefore a cross-copy recognition marker, not proof that this package constructed the value.
357
364
 
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.
365
+ 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.ContractError')`. `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.
359
366
 
360
367
  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.
361
368
 
@@ -369,11 +376,6 @@ const error = new ContractError('Minimum exceeds maximum', {
369
376
  isContractError(error) // true
370
377
  ```
371
378
 
372
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
373
- optional member and `plus` introducing its call-signature members, and a type alias's own type
374
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
375
- guard row's the type it narrows to.
376
-
377
379
  | Name | Kind | Signature | Summary |
378
380
  | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
379
381
  | `isContractError` | function | `(value: unknown) => value is ContractError` | Checks whether an unknown value is a `ContractError`. |
@@ -390,11 +392,6 @@ guard row's the type it narrows to.
390
392
 
391
393
  `ShapeCloner` is the public state-owning contract-shape engine. Its source-only constructor is inert; the first `clone()` requires every node to satisfy the realm-neutral plain-record brand before discriminant observation, then iteratively captures and wires the graph, composes raw nodes through `SchemaCloner`, freezes the completed root, validates that exact root through `ShapeValidator`, and only then applies deferred source-fidelity refusal. Success and failure replay the exact terminal root or class-owned/adopted `ContractError` without rereading the source. Active reentry permanently poisons nested, outer, and later calls with one cause-free `ShapeCloner.clone: shape cloning may not be reentered` error (`clone`, `{ shape: 'shape' }`), including caught reentry. Only errors created by this instance or adopted directly from its schema cloner or validator may replay by identity; unexpected foreign failures become `cloneShape: failed to create an owned shape snapshot` with the exact cause. Terminal settlement releases graph-working state through preconstructed replacement state before nonredirectable terminal publication, while retaining the source and exact terminal result. Distinct instances are independent, while `cloneShape` constructs a fresh instance for every eager call.
392
394
 
393
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
394
- optional member and `plus` introducing its call-signature members, and a type alias's own type
395
- literal with a union's arms escaped as `\|`. A class row's `Shape` cell holds the interface it
396
- implements, or its constructor signature where it implements none.
397
-
398
395
  | Name | Kind | Signature | Summary |
399
396
  | ----------------------- | --------- | ---------------------------------------------------- | ------------------------------------------------------------------------- |
400
397
  | `JSONCloner` | class | `new (value: unknown) => JSONClonerInterface` | Owns the state of one exact JSON snapshot operation. |
@@ -503,10 +500,8 @@ contract.parse({ id: 'nope', name: 'x' }) // undefined
503
500
 
504
501
  ### Shape types
505
502
 
506
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
507
- optional member and `plus` introducing its call-signature members, and a type alias's own type
508
- literal with a union's arms escaped as `\|`. A resolver whose value is a multi-branch
509
- conditional carries none, and its `Summary` states what the resolution produces.
503
+ A resolver whose value is a multi-branch conditional carries none, and its `Summary` states
504
+ what the resolution produces.
510
505
 
511
506
  | Name | Kind | Signature | Summary |
512
507
  | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -543,12 +538,6 @@ conditional carries none, and its `Summary` states what the resolution produces.
543
538
 
544
539
  Turn one `ContractShape` into the six lockstep outputs — `schema` / `is` / `parse` / `audit` / `explain` / `generate` (`src/core/compilers.ts`). `createContract` is the one door in this section that returns an entity rather than a compiled projection, so it lives in `src/core/factories.ts` over the same engine. Two engines sit under those functions. `ShapeValidator` owns the sole stateful declaration walk; `validateShape` constructs a fresh validator as its eager function boundary, while `cloners.ts`, `ShapeCloner`, and the shape builders use the class directly so lower validation no longer imports the compiler module. `ContractCompiler` owns ownership, preparation, and the six artifact families; every function in this section is a real typed door over it that requests exactly the root it is named for, so asking for a guard never compiles a generator. LOCKSTEP here means DERIVED FROM ONE SNAPSHOT, not equal in what they accept: `createContract` compiles all six from a single owned copy of the declaration, so no later edit to the shape you passed can move one of them without the others. It does not mean the six accept the same values — deliberately, they do not (see Domains, below). The individual compilers return untyped runtime functions; `createContract` is the typed entry point — its `is` / `parse` / `generate` carry `Infer<S>` by inferring once, at the boundary (so the recursion stays cheap). `compileGuard` / `compileParser` / `compileReporter` / `compileAuditor` reuse the existing combinators and parsers rather than re-implementing them: `literalOf` IS the literal match at all four (one SameValueZero implementation, taking its vocabulary as an array), and each leaf's refinements (`min` / `max` / `pattern`) are read off the one shape node rather than restated per artifact — `compileGuard` and `compileParser` compose them through the **same** combinators (`stringOf` for a string's length and pattern, `boundsOf` for a number's value and an array's length), while `compileReporter` and `compileAuditor` check those same three against that same node inline, so each violated refinement can carry its own fault; the pattern test is the same flag-stripped owned `RegExp` in every artifact (`matchOf` for the two reports, the identical construction inside `stringOf` for the guard and parser). No artifact — not `compileGuard`, not `compileParser`, not `compileReporter`, not `compileAuditor` — holds a bound of its own to drift from the other three. What the four do NOT share is the leaf TYPE test: `compileGuard` and `compileAuditor` demand a `string`, `compileParser` and `compileReporter` accept whatever `parseString` coerces — which is where the two domains part company. Every entry point reaches the same declaration-rule set through validation or ownership, and `cloneShape` asks that claim of the carried cloned root after its node fields have completed descriptor/two-read capture and its property map has completed its separate enumeration and child-capture checks. The validator mirrors the ownership boundary by rejecting ordinary declared-field accessors before `Reflect.get`, while preserving the documented `pattern` exception. No entry can therefore launder a malformed property/variant/value container, discriminant, scalar accessor, vocabulary, raw-schema child, or structural child into a plausible contract. Every compiled object artifact — guard, parser, reporter, auditor, and the inference direction too — reads an object through the one `enumerableKeys` property view (own enumerable string keys, the set `JSON.stringify` serializes), so all of them see the SAME key set. What each does with an undeclared key in that set differs by design: for a CLOSED object `is` rejects the object, `audit` reports an `'extra'` fault at the key, `parse` drops the key WITHOUT reading it, `explain` says nothing about it, and `schema` forbids it with `additionalProperties: false`. For an OPEN one they all READ it, including under `additionalProperties: true` where nothing constrains the value: open means unconstrained, not unobserved, and the parser copies every such key into its result. Skipping that read on three of the four doors is how `is`, `audit` and `explain` all certified a value clean that `parse` then refused as unreadable.
545
540
 
546
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
547
- optional member and `plus` introducing its call-signature members, and a type alias's own type
548
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
549
- guard row's the type it narrows to. A class row's `Shape` cell holds the interface it
550
- implements, or its constructor signature where it implements none.
551
-
552
541
  | Name | Kind | Signature | Summary |
553
542
  | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
554
543
  | `ShapeValidator` | class | `new (shape: ContractShape) => ShapeValidatorInterface` | Validates one retained contract-shape source live on every call. |
@@ -617,11 +606,6 @@ One deliberate asymmetry with the compiled direction: an inferred schema is a PL
617
606
 
618
607
  The canonicalization leaves (`canonicalStringify`, `encodeLeaf`) and the format-classification leaves (`classifyFormat`, `matchesISOInstant`) are listed here beside the inferers that consume them, and they live in `src/core/helpers.ts`: each is a pure encoding or classification leaf that emits no schema.
619
608
 
620
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
621
- optional member and `plus` introducing its call-signature members, and a type alias's own type
622
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
623
- guard row's the type it narrows to.
624
-
625
609
  | Name | Kind | Signature | Summary |
626
610
  | ---------------------- | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
627
611
  | `valueToSchema` | function | `(value: unknown, options?: ValueToSchemaOptions) => JSONSchema` | Infers a `JSONSchema` for one unknown value — the reverse direction of `compileSchema`. |
@@ -673,11 +657,6 @@ schemaToParameters(valueToSchema(row)) // the open record a tool advertises as `
673
657
 
674
658
  One diagnostic for each artifact that answers yes-or-no. `compileReporter` is the counterpart of `compileParser`: instead of a coerced value it returns every structured `Fault` a value has against a shape — MIRROR-PARSE semantics, so it reuses the exact leaf parsers/guards `compileParser` uses and the soundness invariant `explain(v).length === 0 ⟺ parse(v) !== undefined` holds structurally for READABLE input (`explain` mirrors `parse`'s coercion leniency, not the stricter `is`). `compileAuditor` is the counterpart of `compileGuard`: instead of a `boolean` it returns every `AuditFault` a value has against the STRICT domain, reusing the leaf guards `compileGuard` uses, so `audit(v).length === 0 ⟺ is(v)`. Each report mirrors exactly one artifact, and neither mirrors both, because `is` and `parse` accept different values — which is the subject of the next section. Before either pair compiles, `validateShape` rejects structural and bound-domain malformations; the laws are evaluated only for a valid declaration. Both biconditionals span two separate calls, so both require STABLE reads; the parse biconditional additionally requires the read to succeed rather than raise its coded refusal (see Domains).
675
659
 
676
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
677
- optional member and `plus` introducing its call-signature members, and a type alias's own type
678
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
679
- guard row's the type it narrows to.
680
-
681
660
  | Name | Kind | Signature | Summary |
682
661
  | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
683
662
  | `compileAuditor` | function | `(shape: ContractShape, value: unknown, path?: readonly string[]) => readonly AuditFault[]` | Audits a value against the strict acceptance domain of a `ContractShape`. |