@orkestrel/scaffold 0.0.115 → 0.0.117

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 (70) hide show
  1. package/dist/bin/main.js +138 -16
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
  4. package/dist/host/claude/agents/orkestrel.md +2 -2
  5. package/dist/host/claude/rules/names.md +3 -1
  6. package/dist/host/guides/abort.md +17 -17
  7. package/dist/host/guides/agent.md +445 -445
  8. package/dist/host/guides/brief.md +143 -143
  9. package/dist/host/guides/browser.md +731 -731
  10. package/dist/host/guides/budget.md +39 -39
  11. package/dist/host/guides/capture.md +298 -298
  12. package/dist/host/guides/console.md +109 -109
  13. package/dist/host/guides/contract.md +335 -335
  14. package/dist/host/guides/csv.md +30 -30
  15. package/dist/host/guides/database.md +163 -163
  16. package/dist/host/guides/emitter.md +17 -17
  17. package/dist/host/guides/form.md +99 -99
  18. package/dist/host/guides/guide.md +368 -183
  19. package/dist/host/guides/html.md +49 -49
  20. package/dist/host/guides/indexeddb.md +40 -40
  21. package/dist/host/guides/interpret.md +139 -139
  22. package/dist/host/guides/lsp.md +114 -114
  23. package/dist/host/guides/markdown.md +68 -68
  24. package/dist/host/guides/mcp.md +3745 -3745
  25. package/dist/host/guides/middleware.md +170 -170
  26. package/dist/host/guides/msg.md +95 -95
  27. package/dist/host/guides/ndjson.md +8 -8
  28. package/dist/host/guides/ollama.md +56 -56
  29. package/dist/host/guides/pool.md +21 -21
  30. package/dist/host/guides/probe.md +82 -82
  31. package/dist/host/guides/process.md +99 -99
  32. package/dist/host/guides/program.md +98 -96
  33. package/dist/host/guides/qualifier.md +70 -70
  34. package/dist/host/guides/queue.md +37 -37
  35. package/dist/host/guides/rater.md +38 -38
  36. package/dist/host/guides/reason.md +308 -308
  37. package/dist/host/guides/relation.md +50 -50
  38. package/dist/host/guides/router.md +58 -58
  39. package/dist/host/guides/scaffold.md +558 -419
  40. package/dist/host/guides/sea.md +128 -128
  41. package/dist/host/guides/server.md +100 -100
  42. package/dist/host/guides/sqlite.md +28 -28
  43. package/dist/host/guides/sse.md +20 -20
  44. package/dist/host/guides/study.md +444 -444
  45. package/dist/host/guides/table.md +82 -82
  46. package/dist/host/guides/template.md +41 -41
  47. package/dist/host/guides/terminal.md +121 -121
  48. package/dist/host/guides/test.md +273 -273
  49. package/dist/host/guides/timeout.md +18 -18
  50. package/dist/host/guides/tool.md +27 -27
  51. package/dist/host/guides/toolbox.md +166 -166
  52. package/dist/host/guides/websocket.md +54 -54
  53. package/dist/host/guides/worker.md +24 -24
  54. package/dist/host/guides/workflow.md +187 -187
  55. package/dist/host/guides/workspace.md +55 -55
  56. package/dist/host/manifest.json +55 -55
  57. package/dist/host/tests/setupPolicy.ts +5 -3
  58. package/dist/src/core/index.cjs +90 -4
  59. package/dist/src/core/index.cjs.map +1 -1
  60. package/dist/src/core/index.d.cts +229 -144
  61. package/dist/src/core/index.d.ts +229 -144
  62. package/dist/src/core/index.js +88 -5
  63. package/dist/src/core/index.js.map +1 -1
  64. package/dist/src/server/index.cjs +295 -66
  65. package/dist/src/server/index.cjs.map +1 -1
  66. package/dist/src/server/index.d.cts +193 -6
  67. package/dist/src/server/index.d.ts +193 -6
  68. package/dist/src/server/index.js +290 -69
  69. package/dist/src/server/index.js.map +1 -1
  70. package/package.json +5 -4
@@ -29,46 +29,46 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
29
29
 
30
30
  ### Primitive & null-ish guards
31
31
 
32
- | Guard | Kind | Shape | Summary |
33
- | ---------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------- |
34
- | `isNull` | function | `null` | Determines whether a value is `null`. |
35
- | `isUndefined` | function | `undefined` | Determines whether a value is `undefined`. |
36
- | `isDefined` | function | `T` | Determines whether a value is defined (neither `null` nor `undefined`). |
37
- | `isString` | function | `string` | Determines whether a value is a string. |
38
- | `isNumber` | function | `number` | Determines whether a value is a number. |
39
- | `isFiniteNumber` | function | `number` | Determines whether a value is a finite number (excludes `NaN` and `±Infinity`). |
40
- | `isInteger` | function | `number` | Determines whether a value is a finite integer (excludes `NaN`, `±Infinity`, and fractional numbers). |
41
- | `isNonNegativeNumber` | function | `number` | Determines whether a value is a finite primitive number at or above positive zero. |
42
- | `isNonNegativeInteger` | function | `number` | Determines whether a value is a non-negative finite primitive integer. |
43
- | `isBoolean` | function | `boolean` | Determines whether a value is a boolean. |
44
- | `isLiteralValue` | function | `LiteralValue` | Determines whether a value belongs to the string, number, or boolean literal domain. |
45
- | `isTrue` | function | `true` | Determines whether a value is exactly `true`. |
46
- | `isFalse` | function | `false` | Determines whether a value is exactly `false`. |
47
- | `isBigInt` | function | `bigint` | Determines whether a value is a bigint. |
48
- | `isSymbol` | function | `symbol` | Determines whether a value is a symbol. |
49
- | `isNullableString` | function | `string \| null` | Determines whether a value is a string or `null`. |
50
- | `isNullableNumber` | function | `number \| null` | Determines whether a value is a number or `null` (the number may be `NaN` / `±Infinity`). |
51
- | `isNullableBoolean` | function | `boolean \| null` | Determines whether a value is a boolean or `null`. |
32
+ | Name | Kind | Signature | Summary |
33
+ | ---------------------- | -------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
34
+ | `isNull` | function | `(value: unknown) => value is null` | Determines whether a value is `null`. |
35
+ | `isUndefined` | function | `(value: unknown) => value is undefined` | Determines whether a value is `undefined`. |
36
+ | `isDefined` | function | `<T>(value: T \| null \| undefined) => value is T` | Determines whether a value is defined (neither `null` nor `undefined`). |
37
+ | `isString` | function | `(value: unknown) => value is string` | Determines whether a value is a string. |
38
+ | `isNumber` | function | `(value: unknown) => value is number` | Determines whether a value is a number. |
39
+ | `isFiniteNumber` | function | `(value: unknown) => value is number` | Determines whether a value is a finite number (excludes `NaN` and `±Infinity`). |
40
+ | `isInteger` | function | `(value: unknown) => value is number` | Determines whether a value is a finite integer (excludes `NaN`, `±Infinity`, and fractional numbers). |
41
+ | `isNonNegativeNumber` | function | `(value: unknown) => value is number` | Determines whether a value is a finite primitive number at or above positive zero. |
42
+ | `isNonNegativeInteger` | function | `(value: unknown) => value is number` | Determines whether a value is a non-negative finite primitive integer. |
43
+ | `isBoolean` | function | `(value: unknown) => value is boolean` | Determines whether a value is a boolean. |
44
+ | `isLiteralValue` | function | `(value: unknown) => value is LiteralValue` | Determines whether a value belongs to the string, number, or boolean literal domain. |
45
+ | `isTrue` | function | `(value: unknown) => value is true` | Determines whether a value is exactly `true`. |
46
+ | `isFalse` | function | `(value: unknown) => value is false` | Determines whether a value is exactly `false`. |
47
+ | `isBigInt` | function | `(value: unknown) => value is bigint` | Determines whether a value is a bigint. |
48
+ | `isSymbol` | function | `(value: unknown) => value is symbol` | Determines whether a value is a symbol. |
49
+ | `isNullableString` | function | `(value: unknown) => value is string \| null` | Determines whether a value is a string or `null`. |
50
+ | `isNullableNumber` | function | `(value: unknown) => value is number \| null` | Determines whether a value is a number or `null` (the number may be `NaN` / `±Infinity`). |
51
+ | `isNullableBoolean` | function | `(value: unknown) => value is boolean \| null` | Determines whether a value is a boolean or `null`. |
52
52
 
53
53
  ### Structural & collection guards
54
54
 
55
- | Guard | Kind | Shape | Summary |
56
- | --------------------- | -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
57
- | `isObject` | function | `object` | Determines whether a value is a non-null object. |
58
- | `isRecord` | function | `Record<string, unknown>` | Determines whether a value is a plain record (object literal or null-prototype), not an array or class instance. |
59
- | `isMap` | function | `ReadonlyMap<K, V>` | Determines whether a value is a `Map`. |
60
- | `isSet` | function | `ReadonlySet<T>` | Determines whether a value is a `Set`. |
61
- | `isWeakMap` | function | `WeakMap<object, unknown>` | Determines whether a value is a `WeakMap`. |
62
- | `isWeakSet` | function | `WeakSet<object>` | Determines whether a value is a `WeakSet`. |
63
- | `isDate` | function | `Date` | Determines whether a value is a `Date`. |
64
- | `isRegExp` | function | `RegExp` | Determines whether a value is a `RegExp`. |
65
- | `isError` | function | `Error` | Determines whether a value is an `Error`. |
66
- | `isPromise` | function | `Promise<T>` | Determines whether a value is a native `Promise` (use `isPromiseLike` for any thenable). |
67
- | `isPromiseLike` | function | `PromiseLike<T>` | Determines whether a value is promise-like — an object exposing callable `then`, `catch`, and `finally` methods. |
68
- | `isIterable` | function | `Iterable<T>` | Determines whether a value implements the iterable protocol (`Symbol.iterator`). |
69
- | `isAsyncIterable` | function | `AsyncIterable<T>` | Determines whether a value implements the async iterable protocol (`Symbol.asyncIterator`). |
70
- | `isArrayBuffer` | function | `ArrayBuffer` | Determines whether a value is an `ArrayBuffer`. |
71
- | `isSharedArrayBuffer` | function | `SharedArrayBuffer` | Determines whether a value is a `SharedArrayBuffer`. |
55
+ | Name | Kind | Signature | Summary |
56
+ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
57
+ | `isObject` | function | `(value: unknown) => value is object` | Determines whether a value is a non-null object. |
58
+ | `isRecord` | function | `(value: unknown) => value is Record<string, unknown>` | Determines whether a value is a plain record (object literal or null-prototype), not an array or class instance. |
59
+ | `isMap` | function | `<K = unknown, V = unknown>(value: unknown) => value is ReadonlyMap<K, V>` | Determines whether a value is a `Map`. |
60
+ | `isSet` | function | `<T = unknown>(value: unknown) => value is ReadonlySet<T>` | Determines whether a value is a `Set`. |
61
+ | `isWeakMap` | function | `(value: unknown) => value is WeakMap<object, unknown>` | Determines whether a value is a `WeakMap`. |
62
+ | `isWeakSet` | function | `(value: unknown) => value is WeakSet<object>` | Determines whether a value is a `WeakSet`. |
63
+ | `isDate` | function | `(value: unknown) => value is Date` | Determines whether a value is a `Date`. |
64
+ | `isRegExp` | function | `(value: unknown) => value is RegExp` | Determines whether a value is a `RegExp`. |
65
+ | `isError` | function | `(value: unknown) => value is Error` | Determines whether a value is an `Error`. |
66
+ | `isPromise` | function | `<T = unknown>(value: unknown) => value is Promise<T>` | Determines whether a value is a native `Promise` (use `isPromiseLike` for any thenable). |
67
+ | `isPromiseLike` | function | `<T = unknown>(value: unknown) => value is Promise<T> \| (PromiseLike<T> & { catch: unknown; finally: unknown; })` | Determines whether a value is promise-like — an object exposing callable `then`, `catch`, and `finally` methods. |
68
+ | `isIterable` | function | `<T = unknown>(value: unknown) => value is Iterable<T>` | Determines whether a value implements the iterable protocol (`Symbol.iterator`). |
69
+ | `isAsyncIterable` | function | `<T = unknown>(value: unknown) => value is AsyncIterable<T>` | Determines whether a value implements the async iterable protocol (`Symbol.asyncIterator`). |
70
+ | `isArrayBuffer` | function | `(value: unknown) => value is ArrayBuffer` | Determines whether a value is an `ArrayBuffer`. |
71
+ | `isSharedArrayBuffer` | function | `(value: unknown) => value is SharedArrayBuffer` | Determines whether a value is a `SharedArrayBuffer`. |
72
72
 
73
73
  #### Recognizing a plain record
74
74
 
@@ -78,118 +78,118 @@ That is a structural test rather than a provenance one, and the residual is exac
78
78
 
79
79
  ### Array & typed-array guards
80
80
 
81
- | Guard | Kind | Shape | Summary |
82
- | --------------------- | -------- | ------------------- | ----------------------------------------------------------------------------------- |
83
- | `isArray` | function | `readonly T[]` | Determines whether a value is an array. |
84
- | `isDataView` | function | `DataView` | Determines whether a value is a `DataView`. |
85
- | `isArrayBufferView` | function | `ArrayBufferView` | Determines whether a value is an `ArrayBufferView` (any typed array or `DataView`). |
86
- | `isInt8Array` | function | `Int8Array` | Determines whether a value is an `Int8Array`. |
87
- | `isUint8Array` | function | `Uint8Array` | Determines whether a value is a `Uint8Array`. |
88
- | `isUint8ClampedArray` | function | `Uint8ClampedArray` | Determines whether a value is a `Uint8ClampedArray`. |
89
- | `isInt16Array` | function | `Int16Array` | Determines whether a value is an `Int16Array`. |
90
- | `isUint16Array` | function | `Uint16Array` | Determines whether a value is a `Uint16Array`. |
91
- | `isInt32Array` | function | `Int32Array` | Determines whether a value is an `Int32Array`. |
92
- | `isUint32Array` | function | `Uint32Array` | Determines whether a value is a `Uint32Array`. |
93
- | `isFloat32Array` | function | `Float32Array` | Determines whether a value is a `Float32Array`. |
94
- | `isFloat64Array` | function | `Float64Array` | Determines whether a value is a `Float64Array`. |
95
- | `isBigInt64Array` | function | `BigInt64Array` | Determines whether a value is a `BigInt64Array`. |
96
- | `isBigUint64Array` | function | `BigUint64Array` | Determines whether a value is a `BigUint64Array`. |
81
+ | Name | Kind | Signature | Summary |
82
+ | --------------------- | -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
83
+ | `isArray` | function | `<T = unknown>(value: unknown) => value is readonly T[]` | Determines whether a value is an array. |
84
+ | `isDataView` | function | `(value: unknown) => value is DataView<ArrayBufferLike>` | Determines whether a value is a `DataView`. |
85
+ | `isArrayBufferView` | function | `(value: unknown) => value is ArrayBufferView` | Determines whether a value is an `ArrayBufferView` (any typed array or `DataView`). |
86
+ | `isInt8Array` | function | `(value: unknown) => value is Int8Array` | Determines whether a value is an `Int8Array`. |
87
+ | `isUint8Array` | function | `(value: unknown) => value is Uint8Array` | Determines whether a value is a `Uint8Array`. |
88
+ | `isUint8ClampedArray` | function | `(value: unknown) => value is Uint8ClampedArray` | Determines whether a value is a `Uint8ClampedArray`. |
89
+ | `isInt16Array` | function | `(value: unknown) => value is Int16Array` | Determines whether a value is an `Int16Array`. |
90
+ | `isUint16Array` | function | `(value: unknown) => value is Uint16Array` | Determines whether a value is a `Uint16Array`. |
91
+ | `isInt32Array` | function | `(value: unknown) => value is Int32Array` | Determines whether a value is an `Int32Array`. |
92
+ | `isUint32Array` | function | `(value: unknown) => value is Uint32Array` | Determines whether a value is a `Uint32Array`. |
93
+ | `isFloat32Array` | function | `(value: unknown) => value is Float32Array` | Determines whether a value is a `Float32Array`. |
94
+ | `isFloat64Array` | function | `(value: unknown) => value is Float64Array` | Determines whether a value is a `Float64Array`. |
95
+ | `isBigInt64Array` | function | `(value: unknown) => value is BigInt64Array` | Determines whether a value is a `BigInt64Array`. |
96
+ | `isBigUint64Array` | function | `(value: unknown) => value is BigUint64Array` | Determines whether a value is a `BigUint64Array`. |
97
97
 
98
98
  ### Emptiness guards
99
99
 
100
- | Guard | Kind | Shape | Summary |
101
- | ------------------ | -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
102
- | `isEmptyString` | function | `''` | Determines whether a value is the empty string `''`. |
103
- | `isEmptyArray` | function | `readonly []` | Determines whether a value is an empty array. |
104
- | `isEmptyObject` | function | `Record<string \| symbol, never>` | Determines whether a value is an empty plain object — no OWN keys at all, of any kind: string or symbol, enumerable or not. |
105
- | `isEmptyMap` | function | `ReadonlyMap<never, never>` | Determines whether a value is an empty `Map`. |
106
- | `isEmptySet` | function | `ReadonlySet<never>` | Determines whether a value is an empty `Set`. |
107
- | `isNonEmptyString` | function | `string` | Determines whether a value is a non-empty string (at least one character). |
108
- | `isNonEmptyArray` | function | `readonly [T, ...T[]]` | Determines whether a value is a non-empty array (at least one element). |
109
- | `isNonEmptyObject` | function | `Record<string \| symbol, unknown>` | Determines whether a value is a non-empty plain object — at least one own key of any kind: string or symbol, enumerable or not. |
110
- | `isNonEmptyMap` | function | `ReadonlyMap<K, V>` | Determines whether a value is a non-empty `Map` (at least one entry). |
111
- | `isNonEmptySet` | function | `ReadonlySet<T>` | Determines whether a value is a non-empty `Set` (at least one element). |
100
+ | Name | Kind | Signature | Summary |
101
+ | ------------------ | -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
102
+ | `isEmptyString` | function | `(value: unknown) => value is ''` | Determines whether a value is the empty string `''`. |
103
+ | `isEmptyArray` | function | `(value: unknown) => value is readonly []` | Determines whether a value is an empty array. |
104
+ | `isEmptyObject` | function | `(value: unknown) => value is Record<string \| symbol, never>` | Determines whether a value is an empty plain object — no OWN keys at all, of any kind: string or symbol, enumerable or not. |
105
+ | `isEmptyMap` | function | `(value: unknown) => value is ReadonlyMap<never, never>` | Determines whether a value is an empty `Map`. |
106
+ | `isEmptySet` | function | `(value: unknown) => value is ReadonlySet<never>` | Determines whether a value is an empty `Set`. |
107
+ | `isNonEmptyString` | function | `(value: unknown) => value is string` | Determines whether a value is a non-empty string (at least one character). |
108
+ | `isNonEmptyArray` | function | `<T = unknown>(value: unknown) => value is readonly [T, ...T[]]` | Determines whether a value is a non-empty array (at least one element). |
109
+ | `isNonEmptyObject` | function | `(value: unknown) => value is Record<string \| symbol, unknown>` | Determines whether a value is a non-empty plain object — at least one own key of any kind: string or symbol, enumerable or not. |
110
+ | `isNonEmptyMap` | function | `<K = unknown, V = unknown>(value: unknown) => value is ReadonlyMap<K, V>` | Determines whether a value is a non-empty `Map` (at least one entry). |
111
+ | `isNonEmptySet` | function | `<T = unknown>(value: unknown) => value is ReadonlySet<T>` | Determines whether a value is a non-empty `Set` (at least one element). |
112
112
 
113
113
  ### Function & constructor guards
114
114
 
115
- | Guard | Kind | Shape | Summary |
116
- | -------------------------- | -------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
117
- | `isFunction` | function | `AnyFunction` | Determines whether a value is callable. |
118
- | `isZeroArg` | function | `ZeroArgFunction` | Determines whether a value is a function that declares zero parameters (`Function.length === 0`). |
119
- | `isAsyncFunction` | function | `AnyAsyncFunction` | Determines whether a value is a native `async function`. |
120
- | `isGeneratorFunction` | function | `(...args: unknown[]) => Generator<unknown, unknown, unknown>` | Determines whether a value is a generator function (`function*`). |
121
- | `isAsyncGeneratorFunction` | function | `(...args: unknown[]) => AsyncGenerator<unknown, unknown, unknown>` | Determines whether a value is an async generator function (`async function*`). |
122
- | `isZeroArgAsync` | function | `ZeroArgAsyncFunction` | Determines whether a value is a zero-argument async function. |
123
- | `isZeroArgGenerator` | function | `() => Generator<unknown, unknown, unknown>` | Determines whether a value is a zero-argument generator function. |
124
- | `isZeroArgAsyncGenerator` | function | `() => AsyncGenerator<unknown, unknown, unknown>` | Determines whether a value is a zero-argument async generator function. |
125
- | `isConstructor` | function | `AnyConstructor` | Determines whether a value can be used as a `new`-target constructor. |
126
- | `isInstance` | function | `InstanceType<C>` | Determines whether a value is an instance of a constructor, contained against a throwing `instanceof` check. |
115
+ | Name | Kind | Signature | Summary |
116
+ | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
117
+ | `isFunction` | function | `(value: unknown) => value is AnyFunction` | Determines whether a value is callable. |
118
+ | `isZeroArg` | function | `(value: unknown) => value is ZeroArgFunction` | Determines whether a value is a function that declares zero parameters (`Function.length === 0`). |
119
+ | `isAsyncFunction` | function | `(value: unknown) => value is AnyAsyncFunction` | Determines whether a value is a native `async function`. |
120
+ | `isGeneratorFunction` | function | `(value: unknown) => value is (...args: unknown[]) => Generator<unknown, unknown, unknown>` | Determines whether a value is a generator function (`function*`). |
121
+ | `isAsyncGeneratorFunction` | function | `(value: unknown) => value is (...args: unknown[]) => AsyncGenerator<unknown, unknown, unknown>` | Determines whether a value is an async generator function (`async function*`). |
122
+ | `isZeroArgAsync` | function | `(value: unknown) => value is ZeroArgAsyncFunction` | Determines whether a value is a zero-argument async function. |
123
+ | `isZeroArgGenerator` | function | `(value: unknown) => value is () => Generator<unknown, unknown, unknown>` | Determines whether a value is a zero-argument generator function. |
124
+ | `isZeroArgAsyncGenerator` | function | `(value: unknown) => value is () => AsyncGenerator<unknown, unknown, unknown>` | Determines whether a value is a zero-argument async generator function. |
125
+ | `isConstructor` | function | `(value: unknown) => value is AnyConstructor<object>` | Determines whether a value can be used as a `new`-target constructor. |
126
+ | `isInstance` | function | `<C extends abstract new (...args: never) => object>(value: unknown, ctor: C) => value is InstanceType<C>` | Determines whether a value is an instance of a constructor, contained against a throwing `instanceof` check. |
127
127
 
128
128
  ### Combinators
129
129
 
130
130
  Each combinator builds a fresh guard out of guards you already hold. There is no
131
131
  `iterableOf`; guard a `Set`, a `Map`, or an array with `setOf`, `mapOf`, or `arrayOf`.
132
132
 
133
- | Combinator | Kind | Summary |
134
- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
135
- | `arrayOf` | function | Builds a guard that accepts DENSE arrays whose every element satisfies `elementGuard`. |
136
- | `tupleOf` | function | Builds a guard that accepts fixed-arity DENSE tuples, testing each index with the corresponding guard. |
137
- | `setOf` | function | Builds a guard that accepts `Set` instances whose every element satisfies `elementGuard`. |
138
- | `mapOf` | function | Builds a guard that accepts `Map` instances where every key satisfies `keyGuard` and every value satisfies `valueGuard`. |
139
- | `recordOf` | function | Builds a guard that accepts plain records matching a guard shape. |
140
- | `objectOf` | function | Builds a guard that accepts non-array objects matching an open guard shape. |
141
- | `literalOf` | function | Builds a guard that accepts a provided literal primitive using SameValueZero comparison. |
142
- | `instanceOf` | function | Builds a guard that accepts instances of the provided constructor. |
143
- | `enumOf` | function | Builds a guard from a native `enum` or any object whose values are strings or numbers. |
144
- | `keyOf` | function | Builds a guard that accepts values that are own keys of the provided object. |
145
- | `pickOf` | function | Builds a new guard shape by keeping only the listed keys — the structural equivalent of `Pick<T, K>`. Produces a shape for `recordOf`, not a guard. |
146
- | `omitOf` | function | Builds a new guard shape by removing the listed keys — the structural equivalent of `Omit<T, K>`. Produces a shape for `recordOf`, not a guard. |
147
- | `andOf` | function | Combines `left` and `right` with logical AND — passes only when both pass. |
148
- | `orOf` | function | Combines `left` and `right` with logical OR — passes when at least one passes. Prefer `unionOf` for a wider set of variants. |
149
- | `notOf` | function | Negates a guard or predicate — passes when `guard` returns `false`. |
150
- | `complementOf` | function | Builds a guard for `Exclude<TBase, TExcluded>` — accepts values that pass `base` but not `excluded`. |
151
- | `unionOf` | function | Builds a guard that accepts values matching at least one of the provided guards — the variadic form of `orOf`. |
152
- | `intersectionOf` | function | Builds a guard that accepts values matching ALL of the provided guards — the variadic form of `andOf`. |
153
- | `whereOf` | function | Refines a base guard with an additional predicate that runs only when the base passes. |
154
- | `lazyOf` | function | Defers guard creation until first use by calling `thunk()` on every invocation. |
155
- | `transformOf` | function | Builds a guard that passes when the base passes AND the projection of the value satisfies the target guard. Still narrows to `T` (the base type) — the target check is a validity constraint on a derived view, not a type transformation. |
156
- | `nullableOf` | function | Extends a guard to also allow `null`. |
157
- | `optionalOf` | function | Extends a guard to also allow `undefined` — the optional counterpart of `nullableOf`. |
158
- | `boundsOf` | function | Builds a guard that accepts finite numbers within an inclusive `[min, max]` range. |
159
- | `matchOf` | function | Builds a guard that accepts strings matching a regular expression. |
160
- | `stringOf` | function | Builds a guard that accepts strings satisfying optional length and pattern refinements — `min` / `max` length and a `pattern`. |
133
+ | Name | Kind | Signature | Summary |
134
+ | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
135
+ | `arrayOf` | function | `(<T>(elementGuard: Guard<T>) => Guard<readonly T[]>) & ((elementGuard: (value: unknown) => boolean) => Guard<readonly unknown[]>)` | Builds a guard that accepts DENSE arrays whose every element satisfies `elementGuard`. |
136
+ | `tupleOf` | function | `(<const Gs extends ReadonlyArray<Guard<unknown>>>(...guards: Gs) => Guard<TupleFromGuards<Gs>>) & ((...predicates: ReadonlyArray<(value: unknown) => boolean>) => Guard<readonly unknown[]>)` | Builds a guard that accepts fixed-arity DENSE tuples, testing each index with the corresponding guard. |
137
+ | `setOf` | function | `(<T>(elementGuard: Guard<T>) => Guard<ReadonlySet<T>>) & ((elementGuard: (value: unknown) => boolean) => Guard<ReadonlySet<unknown>>)` | Builds a guard that accepts `Set` instances whose every element satisfies `elementGuard`. |
138
+ | `mapOf` | function | `(<K, V>(keyGuard: Guard<K>, valueGuard: Guard<V>) => Guard<ReadonlyMap<K, V>>) & ((keyPredicate: (value: unknown) => boolean, valuePredicate: (value: unknown) => boolean) => Guard<ReadonlyMap<unknown, unknown>>)` | Builds a guard that accepts `Map` instances where every key satisfies `keyGuard` and every value satisfies `valueGuard`. |
139
+ | `recordOf` | function | `(<S extends GuardsShape>(shape: S) => Guard<FromGuards<S>>) & (<S extends GuardsShape, K extends ReadonlyArray<keyof S & string>>(shape: S, optional: K) => Guard<OptionalFromGuards<S, K>>) & (<S extends GuardsShape>(shape: S, optional: true) => Guard<Readonly<{ [P in keyof S]?: FromGuards<S>[P]; }>>)` | Builds a guard that accepts plain records matching a guard shape. |
140
+ | `objectOf` | function | `(<S extends GuardsShape>(shape: S) => Guard<FromGuards<S>>) & (<S extends GuardsShape, K extends ReadonlyArray<keyof S & string>>(shape: S, optional: K) => Guard<OptionalFromGuards<S, K>>) & (<S extends GuardsShape>(shape: S, optional: true) => Guard<Readonly<{ [P in keyof S]?: FromGuards<S>[P]; }>>)` | Builds a guard that accepts non-array objects matching an open guard shape. |
141
+ | `literalOf` | function | `(<const Literals extends readonly LiteralValue[]>(literals: Literals) => Guard<Literals[number]>) & (<const Literals extends readonly LiteralValue[]>(...literals: Literals) => Guard<Literals[number]>)` | Builds a guard that accepts a provided literal primitive using SameValueZero comparison. |
142
+ | `instanceOf` | function | `<C extends abstract new (...args: never) => object>(ctor: C) => Guard<InstanceType<C>>` | Builds a guard that accepts instances of the provided constructor. |
143
+ | `enumOf` | function | `<const E extends Record<string, string \| number>>(enumeration: E) => Guard<E[keyof E]>` | Builds a guard from a native `enum` or any object whose values are strings or numbers. |
144
+ | `keyOf` | function | `<const O extends Readonly<Record<PropertyKey, unknown>>>(value: O) => Guard<keyof O>` | Builds a guard that accepts values that are own keys of the provided object. |
145
+ | `pickOf` | function | `<S extends GuardsShape, K extends ReadonlyArray<keyof S & string>>(shape: S, keys: K) => Pick<S, K[number]>` | Builds a new guard shape by keeping only the listed keys — the structural equivalent of `Pick<T, K>`. Produces a shape for `recordOf`, not a guard. |
146
+ | `omitOf` | function | `<S extends GuardsShape, K extends ReadonlyArray<keyof S & string>>(shape: S, keys: K) => Omit<S, K[number]>` | Builds a new guard shape by removing the listed keys — the structural equivalent of `Omit<T, K>`. Produces a shape for `recordOf`, not a guard. |
147
+ | `andOf` | function | `(<A, B>(left: Guard<A>, right: Guard<B>) => Guard<A & B>) & (<T, U extends T>(left: Guard<T>, right: (value: T) => value is U) => Guard<U>) & (<T>(left: Guard<T>, right: (value: T) => boolean) => Guard<T>) & ((left: (value: unknown) => boolean, right: (value: unknown) => boolean) => Guard<unknown>)` | Combines `left` and `right` with logical AND — passes only when both pass. |
148
+ | `orOf` | function | `(<A, B>(left: Guard<A>, right: Guard<B>) => Guard<A \| B>) & ((left: (value: unknown) => boolean, right: (value: unknown) => boolean) => Guard<unknown>)` | Combines `left` and `right` with logical OR — passes when at least one passes. Prefer `unionOf` for a wider set of variants. |
149
+ | `notOf` | function | `(guard: (value: unknown) => boolean) => Guard<unknown>` | Negates a guard or predicate — passes when `guard` returns `false`. |
150
+ | `complementOf` | function | `<TBase, TExcluded extends TBase>(base: Guard<TBase>, excluded: Guard<TExcluded> \| ((value: TBase) => value is TExcluded)) => Guard<Exclude<TBase, TExcluded>>` | Builds a guard for `Exclude<TBase, TExcluded>` — accepts values that pass `base` but not `excluded`. |
151
+ | `unionOf` | function | `(<const Gs extends ReadonlyArray<Guard<unknown>>>(...guards: Gs) => Guard<GuardType<Gs[number]>>) & ((...predicates: ReadonlyArray<(value: unknown) => boolean>) => Guard<unknown>)` | Builds a guard that accepts values matching at least one of the provided guards — the variadic form of `orOf`. |
152
+ | `intersectionOf` | function | `(<const Gs extends ReadonlyArray<Guard<unknown>>>(...guards: Gs) => Guard<IntersectionFromGuards<Gs>>) & ((...predicates: ReadonlyArray<(value: unknown) => boolean>) => Guard<unknown>)` | Builds a guard that accepts values matching ALL of the provided guards — the variadic form of `andOf`. |
153
+ | `whereOf` | function | `(<T, U extends T>(base: Guard<T>, predicate: (value: T) => value is U) => Guard<U>) & (<T>(base: Guard<T>, predicate: (value: T) => boolean) => Guard<T>)` | Refines a base guard with an additional predicate that runs only when the base passes. |
154
+ | `lazyOf` | function | `<T>(thunk: () => Guard<T>) => Guard<T>` | Defers guard creation until first use by calling `thunk()` on every invocation. |
155
+ | `transformOf` | function | `(<T, U>(base: Guard<T>, project: (value: T) => U, target: Guard<U>) => Guard<T>) & (<T>(base: Guard<T>, project: (value: T) => unknown, target: (value: unknown) => boolean) => Guard<T>)` | Builds a guard that passes when the base passes AND the projection of the value satisfies the target guard. Still narrows to `T` (the base type) — the target check is a validity constraint on a derived view, not a type transformation. |
156
+ | `nullableOf` | function | `<T>(guard: Guard<T>) => Guard<T \| null>` | Extends a guard to also allow `null`. |
157
+ | `optionalOf` | function | `<T>(guard: Guard<T>) => Guard<T \| undefined>` | Extends a guard to also allow `undefined` — the optional counterpart of `nullableOf`. |
158
+ | `boundsOf` | function | `(min?: number, max?: number) => Guard<number>` | Builds a guard that accepts finite numbers within an inclusive `[min, max]` range. |
159
+ | `matchOf` | function | `(pattern: RegExp) => Guard<string>` | Builds a guard that accepts strings matching a regular expression. |
160
+ | `stringOf` | function | `(options?: StringGuardOptions) => Guard<string>` | Builds a guard that accepts strings satisfying optional length and pattern refinements — `min` / `max` length and a `pattern`. |
161
161
 
162
162
  The bound the combinators carry is not itself a combinator, and its `Value` cell holds
163
163
  the constant's own literal:
164
164
 
165
- | Bound | Kind | Value | Summary |
166
- | ------------------- | ----- | ----- | ----------------------------------------------------------------------------- |
167
- | `GUARD_DEPTH_LIMIT` | const | `512` | Caps the active recursion or JSON container depth for runtime guards, frozen. |
165
+ | Name | Kind | Signature | Summary |
166
+ | ------------------- | ----- | --------- | ----------------------------------------------------------------------------- |
167
+ | `GUARD_DEPTH_LIMIT` | const | `512` | Caps the active recursion or JSON container depth for runtime guards, frozen. |
168
168
 
169
169
  ### Parsers
170
170
 
171
171
  **Coercion policy.** Number and string coerce into each other bidirectionally by design: `parseNumber` accepts a numeric string (`'42'` → `42`) and `parseString` accepts a finite number, stringifying it (`42` → `'42'`) — use `isString` / `isFiniteNumber` directly when you need strict rejection with no coercion. Boolean is a coercion **sink only**, never a source: `parseBoolean` accepts `'true'` / `'false'` / `'1'` / `'0'` / `1` / `0` and coerces them TO a boolean, but `parseNumber` and `parseString` both reject booleans outright — a boolean never coerces into a number or string. `'1'` meaning "the number one" and `'1'` meaning "true" are different domains; only the boolean parser treats the numeric/string forms as booleans.
172
172
 
173
- | Parser | Kind | Summary |
174
- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
175
- | `parseString` | function | Parses an unknown value to a string. |
176
- | `parseNumber` | function | Parses an unknown value to a finite number. |
177
- | `parseInteger` | function | Parses an unknown value to a finite integer. |
178
- | `parseBoolean` | function | Parses an unknown value to a boolean. |
179
- | `parseRecord` | function | Parses an unknown value to a plain record — the input reference, never cloned. |
180
- | `parseArray` | function | Parses an unknown value to an array — the input reference, never cloned — optionally guarding every element. |
181
- | `parseEnum` | function | Parses an unknown value as one of the allowed literal primitives. |
182
- | `parseNull` | function | Parses an unknown value to `null`. |
183
- | `parseJSONValue` | function | Parses an unknown value to a cycle-safe JSON value — the input reference, never cloned. |
184
- | `parseStringField` | function | Reads and parses a string field from a record by key or nested key path. |
185
- | `parseNumberField` | function | Reads and parses a finite-number field from a record by key or nested key path. |
186
- | `parseIntegerField` | function | Reads and parses a finite-integer field from a record by key or nested key path. |
187
- | `parseBooleanField` | function | Reads and parses a boolean field from a record by key or nested key path. |
188
- | `parseRecordField` | function | Reads and parses a nested record field from a record by key or nested key path. |
189
- | `parseArrayField` | function | Reads and parses an array field from a record by key or nested key path, optionally guarding elements. |
190
- | `parseEnumField` | function | Reads and parses an enum field from a record by key or nested key path. |
191
- | `parseNullField` | function | Reads and parses a `null` field from a record by key or nested key path. |
192
- | `parseJSONValueField` | function | Reads and parses a JSON-value field from a record by key or nested key path. |
173
+ | Name | Kind | Signature | Summary |
174
+ | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
175
+ | `parseString` | function | `(value: unknown) => string \| undefined` | Parses an unknown value to a string. |
176
+ | `parseNumber` | function | `(value: unknown) => number \| undefined` | Parses an unknown value to a finite number. |
177
+ | `parseInteger` | function | `(value: unknown) => number \| undefined` | Parses an unknown value to a finite integer. |
178
+ | `parseBoolean` | function | `(value: unknown) => boolean \| undefined` | Parses an unknown value to a boolean. |
179
+ | `parseRecord` | function | `(value: unknown) => Record<string, unknown> \| undefined` | Parses an unknown value to a plain record — the input reference, never cloned. |
180
+ | `parseArray` | function | `<T = unknown>(value: unknown, guard?: Guard<T>) => readonly T[] \| undefined` | Parses an unknown value to an array — the input reference, never cloned — optionally guarding every element. |
181
+ | `parseEnum` | function | `(<const T extends LiteralValue>(value: unknown, allowed: readonly T[]) => T \| undefined) & ((value: unknown, allowed: readonly LiteralValue[]) => LiteralValue \| undefined)` | Parses an unknown value as one of the allowed literal primitives. |
182
+ | `parseNull` | function | `(value: unknown) => null \| undefined` | Parses an unknown value to `null`. |
183
+ | `parseJSONValue` | function | `(value: unknown) => JSONValue \| undefined` | Parses an unknown value to a cycle-safe JSON value — the input reference, never cloned. |
184
+ | `parseStringField` | function | `(record: Record<string, unknown>, path: FieldPath) => string \| undefined` | Reads and parses a string field from a record by key or nested key path. |
185
+ | `parseNumberField` | function | `(record: Record<string, unknown>, path: FieldPath) => number \| undefined` | Reads and parses a finite-number field from a record by key or nested key path. |
186
+ | `parseIntegerField` | function | `(record: Record<string, unknown>, path: FieldPath) => number \| undefined` | Reads and parses a finite-integer field from a record by key or nested key path. |
187
+ | `parseBooleanField` | function | `(record: Record<string, unknown>, path: FieldPath) => boolean \| undefined` | Reads and parses a boolean field from a record by key or nested key path. |
188
+ | `parseRecordField` | function | `(record: Record<string, unknown>, path: FieldPath) => Record<string, unknown> \| undefined` | Reads and parses a nested record field from a record by key or nested key path. |
189
+ | `parseArrayField` | function | `<T = unknown>(record: Record<string, unknown>, path: FieldPath, guard?: Guard<T>) => readonly T[] \| undefined` | Reads and parses an array field from a record by key or nested key path, optionally guarding elements. |
190
+ | `parseEnumField` | function | `<const T extends LiteralValue>(record: Record<string, unknown>, path: FieldPath, allowed: readonly T[]) => T \| undefined` | Reads and parses an enum field from a record by key or nested key path. |
191
+ | `parseNullField` | function | `(record: Record<string, unknown>, path: FieldPath) => null \| undefined` | Reads and parses a `null` field from a record by key or nested key path. |
192
+ | `parseJSONValueField` | function | `(record: Record<string, unknown>, path: FieldPath) => JSONValue \| undefined` | Reads and parses a JSON-value field from a record by key or nested key path. |
193
193
 
194
194
  ### JSON
195
195
 
@@ -200,17 +200,17 @@ optional member and `plus` introducing its call-signature members, and a type al
200
200
  literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
201
201
  guard row's the type it narrows to.
202
202
 
203
- | API | Kind | Shape | Summary |
203
+ | Name | Kind | Signature | Summary |
204
204
  | --------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
205
- | `isJSONPrimitive` | function | `JSONPrimitive` | Determines whether a value is a primitive JSON value. |
206
- | `isJSONValue` | function | `JSONValue` | Determines whether a value is a cycle-safe JSON value. |
207
- | `isBoundedJSONValue` | function | `JSONValue` | Determines whether a value is JSON-valid within the fixed container-depth limit. |
208
- | `isBoundedJSONRecord` | function | `JSONRecord` | Determines whether a value is a depth-bounded JSON record. |
205
+ | `isJSONPrimitive` | function | `(value: unknown) => value is JSONPrimitive` | Determines whether a value is a primitive JSON value. |
206
+ | `isJSONValue` | function | `(value: unknown) => value is JSONValue` | Determines whether a value is a cycle-safe JSON value. |
207
+ | `isBoundedJSONValue` | function | `(value: unknown) => value is JSONValue` | Determines whether a value is JSON-valid within the fixed container-depth limit. |
208
+ | `isBoundedJSONRecord` | function | `(value: unknown) => value is JSONRecord` | Determines whether a value is a depth-bounded JSON record. |
209
209
  | `parseJSON` | function | `(value: string) => unknown` | Parses a JSON string, returning `undefined` instead of throwing. |
210
210
  | `parseJSONAs` | function | `<T>(value: string, guard: Guard<T>) => T \| undefined` | Parses a JSON string and validates the result against a guard. |
211
211
  | `JSON_SCHEMA_TYPES` | const | `readonly JSONSchemaType[]` | Lists the seven standard JSON Schema `type` names, frozen. |
212
212
  | `JSONPrimitive` | type | `string \| number \| boolean \| null` | Represents a primitive JSON value — the flat leaf of any JSON document. |
213
- | `JSONRecord` | type | `{ readonly [key: string]: JSONValue }` | Represents a readonly string-keyed JSON object record. |
213
+ | `JSONRecord` | type | `{ readonly [key: string]: JSONValue; }` | Represents a readonly string-keyed JSON object record. |
214
214
  | `JSONValue` | type | `JSONPrimitive \| readonly JSONValue[] \| JSONRecord` | Represents a recursive JSON value — primitives, arrays, and object records. |
215
215
  | `JSONSchemaType` | type | `'null' \| 'boolean' \| 'object' \| 'array' \| 'number' \| 'integer' \| 'string'` | Lists the seven standard JSON Schema `type` names. |
216
216
  | `JSONSchema` | interface | `{ type?, description?, enum?, minLength?, maxLength?, pattern?, format?, minimum?, maximum?, minItems?, maxItems?, items?, properties?, required?, additionalProperties?, anyOf?, oneOf? }` | Represents a JSON Schema fragment — the supported keyword vocabulary the contract compiler emits and `RawShape` validates before embedding. |
@@ -218,64 +218,64 @@ guard row's the type it narrows to.
218
218
 
219
219
  ### Helper
220
220
 
221
- | Constant | Kind | Summary |
222
- | ---------------------- | ----- | --------------------------------------------------------------------------------------------- |
223
- | `CONTRACT_ERROR_BRAND` | const | Holds the registry-global key used to recognize `ContractError` values across package copies. |
224
-
225
- | Helper | Kind | Summary |
226
- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
227
- | `attempt` | function | Invokes a callback once and synchronously captures its exact outcome as a `Result`. |
228
- | `INTRINSICS` | const | Captures every host operation this package dispatches through, while this module evaluates. |
229
- | `contain` | function | Runs a public door's whole body and publishes only this package's error class. |
230
- | `appendEntries` | function | Appends every element of one array onto another, by index. |
231
- | `limitEntries` | function | Takes at most `limit` leading elements of an array, by index. |
232
- | `compareValues` | function | Orders two primitive keys or indices ascending. |
233
- | `sortValues` | function | Orders primitive keys or indices deterministically, on an owned copy, through the captured sort. |
234
- | `pathOf` | function | Builds a diagnostic path from an existing path and further segments, without dispatching through array iteration. |
235
- | `readValue` | function | Reads a value through the shared containment boundary or refuses it with the contract module's uniform read diagnostic. |
236
- | `readArrayEntries` | function | Snapshots an array through its reflected own-index population. |
237
- | `readGuardShape` | function | Snapshots a guard shape and its optional-key mode for a shape combinator. |
238
- | `holds` | function | Invokes a predicate through the sanctioned never-throw boundary. |
239
- | `enumerableKeys` | function | Snapshots an object's own enumerable string keys through a total boundary. |
240
- | `readOptions` | function | Validates and snapshots a shape-builder options record through every reflective operation the builder relies on. |
241
- | `drawRandom` | function | Draws and validates one generator random sample. |
242
- | `enumerableSymbolCount` | function | Counts the enumerable own-symbol keys on a value. |
243
- | `matchesJSONValue` | function | Matches an unknown value against the recursive JSON value structure. |
244
- | `matchesRecordBrand` | function | Determines whether a value carries the plain-record brand, raising a hostile prototype observation instead of answering it. |
245
- | `matchesJSONDepth` | function | Determines whether a readable value stays within the fixed JSON container-depth limit. |
246
- | `resolveField` | function | Resolves a (possibly nested) field value from a record by a key or key path. |
247
- | `seededRandom` | function | Builds a deterministic pseudo-random source seeded from a single number. |
248
- | `schemaToParameters` | function | Narrows a compiled `JSONSchema` down to the open `Readonly<Record<string, unknown>>` shape tool definitions advertise as `parameters` — through the `isRecord` boundary guard, never an assertion, as `.claude/rules/patterns.md` § Validation and contracts requires. |
249
- | `schemaToObject` | function | Wraps a non-object `JSONSchema` root in a single-property object schema, so an inferred primitive/array/union schema can flow into `schemaToParameters` as an MCP-compatible `inputSchema`. |
250
- | `collectMembers` | function | Collects an array's entries into a membership collection this package owns. |
251
- | `matchesMember` | function | Determines whether a value is a member of a collected vocabulary, by SameValueZero. |
252
- | `admitMember` | function | Collects one more member into a vocabulary that grows as a walk proceeds. |
253
- | `matchesVisited` | function | Determines whether an object is already on a traversal's active path. |
254
- | `admitVisited` | function | Records an object as entered on a traversal's active path. |
255
- | `omitVisited` | function | Records an object as exited from a traversal's active path. |
256
- | `retainDepth` | function | Records one node's answer at one remaining-depth allowance in a shared memo. |
257
- | `collectEntries` | function | Builds the collector a captured `forEach` sweep appends through. |
258
- | `readSetEntries` | function | Snapshots the genuine contents of a caller's `Set` without running an iterator. |
259
- | `readMapEntries` | function | Snapshots the genuine entries of a caller's `Map` without running an iterator. |
260
- | `matchesPattern` | function | Determines whether a string is in the language of a pattern this package owns. |
261
- | `readPatternSource` | function | Reads a regular expression's source text through the captured accessor. |
262
- | `readPatternFlags` | function | Reads a regular expression's flag text through the captured accessor. |
263
- | `readPattern` | function | Rebuilds a caller's regular expression as a stateless pattern this package owns. |
264
- | `ownPattern` | function | Rebuilds a declaration's regular expression as a stateless pattern this package owns, and refuses an unreadable one under the reader's own name. |
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
- | `refuseExpansion` | function | Refuses a validated declaration whose compiled expansion exceeds `COMPILE_NODE_LIMIT`. |
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. |
221
+ | Name | Kind | Signature | Summary |
222
+ | ---------------------- | ----- | --------------- | --------------------------------------------------------------------------------------------- |
223
+ | `CONTRACT_ERROR_BRAND` | const | `unique symbol` | Holds the registry-global key used to recognize `ContractError` values across package copies. |
224
+
225
+ | Name | Kind | Signature | Summary |
226
+ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
227
+ | `attempt` | function | `<T>(callback: () => T) => Result<T>` | Invokes a callback once and synchronously captures its exact outcome as a `Result`. |
228
+ | `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
+ | `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
+ | `appendEntries` | function | `<T>(target: T[], source: readonly T[]) => void` | Appends every element of one array onto another, by index. |
231
+ | `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. |
233
+ | `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
+ | `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
+ | `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. |
236
+ | `readArrayEntries` | function | `<T>(value: readonly T[]) => Result<ArrayRead<T>>` | Snapshots an array through its reflected own-index population. |
237
+ | `readGuardShape` | function | `(shape: GuardsShape, optional: readonly string[] \| true \| undefined, reader: string) => GuardShapeRead` | Snapshots a guard shape and its optional-key mode for a shape combinator. |
238
+ | `holds` | function | `(callback: () => boolean) => boolean` | Invokes a predicate through the sanctioned never-throw boundary. |
239
+ | `enumerableKeys` | function | `(value: object) => readonly string[] \| undefined` | Snapshots an object's own enumerable string keys through a total boundary. |
240
+ | `readOptions` | function | `<T extends object>(source: T \| undefined, keys: ReadonlyArray<keyof T & string>, builder: string, shape: string) => T \| undefined` | Validates and snapshots a shape-builder options record through every reflective operation the builder relies on. |
241
+ | `drawRandom` | function | `(random: RandomFunction, shape: string) => number` | Draws and validates one generator random sample. |
242
+ | `enumerableSymbolCount` | function | `(value: object) => number` | Counts the enumerable own-symbol keys on a value. |
243
+ | `matchesJSONValue` | function | `(entry: unknown, ancestors: WeakSet<object>) => entry is JSONValue` | Matches an unknown value against the recursive JSON value structure. |
244
+ | `matchesRecordBrand` | function | `(value: unknown) => boolean` | Determines whether a value carries the plain-record brand, raising a hostile prototype observation instead of answering it. |
245
+ | `matchesJSONDepth` | function | `(value: unknown) => boolean` | Determines whether a readable value stays within the fixed JSON container-depth limit. |
246
+ | `resolveField` | function | `(record: Readonly<Record<string, unknown>>, path: FieldPath) => unknown` | Resolves a (possibly nested) field value from a record by a key or key path. |
247
+ | `seededRandom` | function | `(seed: number) => RandomFunction` | Builds a deterministic pseudo-random source seeded from a single number. |
248
+ | `schemaToParameters` | function | `(schema: JSONSchema) => Readonly<Record<string, unknown>> \| undefined` | Narrows a compiled `JSONSchema` down to the open `Readonly<Record<string, unknown>>` shape tool definitions advertise as `parameters` — through the `isRecord` boundary guard, never an assertion, as `.claude/rules/patterns.md` § Validation and contracts requires. |
249
+ | `schemaToObject` | function | `(schema: JSONSchema) => JSONSchema` | Wraps a non-object `JSONSchema` root in a single-property object schema, so an inferred primitive/array/union schema can flow into `schemaToParameters` as an MCP-compatible `inputSchema`. |
250
+ | `collectMembers` | function | `(values: readonly unknown[]) => Set<unknown>` | Collects an array's entries into a membership collection this package owns. |
251
+ | `matchesMember` | function | `(members: ReadonlySet<unknown>, value: unknown) => boolean` | Determines whether a value is a member of a collected vocabulary, by SameValueZero. |
252
+ | `admitMember` | function | `(members: Set<unknown>, value: unknown) => void` | Collects one more member into a vocabulary that grows as a walk proceeds. |
253
+ | `matchesVisited` | function | `(visited: WeakSet<object>, value: object) => boolean` | Determines whether an object is already on a traversal's active path. |
254
+ | `admitVisited` | function | `(visited: WeakSet<object>, value: object) => void` | Records an object as entered on a traversal's active path. |
255
+ | `omitVisited` | function | `(visited: WeakSet<object>, value: object) => void` | Records an object as exited from a traversal's active path. |
256
+ | `retainDepth` | function | `<T>(memo: WeakMap<object, Map<number, T>>, node: object, depth: number, answer: T) => void` | Records one node's answer at one remaining-depth allowance in a shared memo. |
257
+ | `collectEntries` | function | `(target: unknown[][]) => EntryCollectorFunction` | Builds the collector a captured `forEach` sweep appends through. |
258
+ | `readSetEntries` | function | `(value: ReadonlySet<unknown>) => Result<readonly unknown[]>` | Snapshots the genuine contents of a caller's `Set` without running an iterator. |
259
+ | `readMapEntries` | function | `(value: ReadonlyMap<unknown, unknown>) => Result<ReadonlyArray<readonly unknown[]>>` | Snapshots the genuine entries of a caller's `Map` without running an iterator. |
260
+ | `matchesPattern` | function | `(pattern: RegExp, value: string) => boolean` | Determines whether a string is in the language of a pattern this package owns. |
261
+ | `readPatternSource` | function | `(pattern: unknown) => string \| undefined` | Reads a regular expression's source text through the captured accessor. |
262
+ | `readPatternFlags` | function | `(pattern: unknown) => string \| undefined` | Reads a regular expression's flag text through the captured accessor. |
263
+ | `readPattern` | function | `(pattern: RegExp) => RegExp` | Rebuilds a caller's regular expression as a stateless pattern this package owns. |
264
+ | `ownPattern` | function | `(pattern: RegExp, reader: string) => RegExp` | Rebuilds a declaration's regular expression as a stateless pattern this package owns, and refuses an unreadable one under the reader's own name. |
265
+ | `pinMembers` | function | `(prototype: object, owner: string) => void` | 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
+ | `refuseExpansion` | function | `(expansion: number \| undefined) => void` | Refuses a validated declaration whose compiled expansion exceeds `COMPILE_NODE_LIMIT`. |
267
+
268
+ | Name | Kind | Signature | Summary |
269
+ | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
270
+ | `iterateIndices` | function | `(read: LengthReader) => Generator<number, void, unknown>` | Iterates indices while rereading the upper bound before every step. |
271
+ | `encodeParts` | function | `(members: readonly unknown[], keys: readonly string[] \| undefined, encodings: WeakMap<object, string>) => Generator<string, void, unknown>` | Encodes ordered members, stopping before the first unencodable member. |
272
+ | `previewParts` | function | `(source: string, index: number, capacity: number, quoted: boolean) => readonly string[]` | Builds bounded escaped preview parts without splitting a surrogate pair. |
273
+ | `buildPositions` | function | `(names: readonly string[]) => Readonly<Record<string, number>>` | Builds a null-prototype lookup from names to their last index. |
274
+ | `readPresence` | function | `(names: readonly string[], positions: Readonly<Record<string, number>>) => number` | Derives the bit mask of names present in an indexed lookup. |
275
+ | `LengthReader` | type | `() => number` | Reads the current upper bound of an indexed walk. |
276
+ | `EvaluationFunction` | type | `(value: unknown, path: readonly string[]) => T` | Evaluates a compiled node at one diagnostic path. |
277
+ | `parseEnumValues` | function | `<const T extends LiteralValue>(values: readonly unknown[], allowed: readonly T[]) => Generator<T \| undefined, void, unknown>` | Parses indexed enum members, ending after the first undefined result. |
278
+ | `readIndexView` | function | `(values: readonly unknown[]) => object` | Exposes indexed reads through a non-array receiver without species dispatch. |
279
279
 
280
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.
281
281
 
@@ -313,43 +313,43 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
313
313
  optional member and `plus` introducing its call-signature members, and a type alias's own type
314
314
  literal with a union's arms escaped as `\|`.
315
315
 
316
- | Type | Kind | Shape | Summary |
317
- | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
318
- | `Failure` | interface | `{ success, error }` | Represents the discriminated failure branch of a `Result`. |
319
- | `ArrayRead<T = unknown>` | interface | `{ entries, dense }` | Represents the owned result of reading one array through its reflected own-index lens. |
320
- | `GuardShapeRead` | interface | `{ guards, names, optional, vocabulary }` | Represents the owned result of reading one guard shape and its optional-key mode. |
321
- | `BoundsRead` | interface | `{ min?, max? }` | Represents a derived numeric bounds pair, either member absent. |
322
- | `EntryCollectorFunction` | type | `(value: unknown, key: unknown) => void` | Represents the collector a captured `forEach` sweep invokes per entry. |
323
- | `StringGuardOptions` | interface | `{ min?, max?, pattern? }` | Groups the options for the `stringOf` guard builder. |
324
- | `FieldPath` | type | `string \| readonly string[]` | Addresses one field in a record: a single key, or an ordered list of keys to descend through nested objects. |
325
- | `Guard` | type | `(value: unknown) => value is T` | Represents a runtime type guard: returns `true` when `value` satisfies `T` and narrows it. |
326
- | `GuardType` | type | `G extends Guard<infer T> ? T : never` | Extracts the guarded type `T` from a `Guard<T>`. |
327
- | `GuardsShape` | type | `Readonly<Record<string, Guard<unknown>>>` | Represents a mapping of string keys to guards. |
328
- | `FromGuards` | type | `Readonly<{ [K in keyof G]: GuardType<G[K]> }>` | Resolves a `GuardsShape` to a readonly object type of its guarded property types. |
329
- | `OptionalFromGuards` | type | `Readonly<{ [P in Exclude<keyof S, K[number]>]: FromGuards<S>[P] } & { [P in Extract<keyof S, K[number]>]?: FromGuards<S>[P] }>` | Mirrors `FromGuards`, but every key listed in `K` becomes a true optional member (`?`) rather than a required key widened with `\| undefined`. |
330
- | `TupleFromGuards` | type | `Readonly<{ [K in keyof Ts]: GuardType<Ts[K]> }>` | Maps a tuple of element guards to a readonly tuple of their guarded types. |
331
- | `UnionToIntersection` | type | `(U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never` | Converts a union type to an intersection type. |
332
- | `IntersectionFromGuards` | type | `UnionToIntersection<GuardType<Gs[number]>>` | Intersects the types guarded by a tuple of guards — backs `intersectionOf`. |
333
- | `Parser` | type | `(value: unknown) => T \| undefined` | Coerces an unknown value to `T`, or returns `undefined`. |
334
- | `LiteralValue` | type | `string \| number \| boolean` | Represents a string, number, or boolean literal. |
335
- | `Result` | type | `Success<T> \| Failure<E>` | Represents a discriminated union for operations that can succeed or fail without throwing. |
336
- | `ReadValueOptions` | interface | `{ subject?, code?, context? }` | Represents optional diagnostic metadata for a required read. |
337
- | `ContainOptions` | interface | `{ code?, context? }` | Represents optional diagnostic metadata for a public door's containment boundary. |
338
- | `ShapeProperty` | interface | `{ key, child }` | Represents one captured property of an object shape, held as an ordered entry rather than as a `Map` pair. |
339
- | `Success` | interface | `{ success, value }` | Represents the discriminated success branch of a `Result`. |
340
- | `AnyConstructor` | type | `new (...args: unknown[]) => T` | Represents a constructor signature that produces instances of `T`. |
341
- | `AnyFunction` | type | `(...args: unknown[]) => unknown` | Represents a function accepting any arguments and returning `unknown`. |
342
- | `AnyAsyncFunction` | type | `(...args: unknown[]) => Promise<unknown>` | Represents an async function accepting any arguments and returning a `Promise`. |
343
- | `ZeroArgFunction` | type | `() => unknown` | Represents a function accepting zero arguments and returning `unknown`. |
344
- | `ZeroArgAsyncFunction` | type | `() => Promise<unknown>` | Represents an async function accepting zero arguments and returning a `Promise`. |
316
+ | Name | Kind | Signature | Summary |
317
+ | ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
318
+ | `Failure` | interface | `{ success, error }` | Represents the discriminated failure branch of a `Result`. |
319
+ | `ArrayRead<T = unknown>` | interface | `{ entries, dense }` | Represents the owned result of reading one array through its reflected own-index lens. |
320
+ | `GuardShapeRead` | interface | `{ guards, names, optional, vocabulary }` | Represents the owned result of reading one guard shape and its optional-key mode. |
321
+ | `BoundsRead` | interface | `{ min?, max? }` | Represents a derived numeric bounds pair, either member absent. |
322
+ | `EntryCollectorFunction` | type | `(value: unknown, key: unknown) => void` | Represents the collector a captured `forEach` sweep invokes per entry. |
323
+ | `StringGuardOptions` | interface | `{ min?, max?, pattern? }` | Groups the options for the `stringOf` guard builder. |
324
+ | `FieldPath` | type | `string \| readonly string[]` | Addresses one field in a record: a single key, or an ordered list of keys to descend through nested objects. |
325
+ | `Guard` | type | `(value: unknown) => value is T` | Represents a runtime type guard: returns `true` when `value` satisfies `T` and narrows it. |
326
+ | `GuardType` | type | `G extends Guard<infer T> ? T : never` | Extracts the guarded type `T` from a `Guard<T>`. |
327
+ | `GuardsShape` | type | `Readonly<Record<string, Guard<unknown>>>` | Represents a mapping of string keys to guards. |
328
+ | `FromGuards` | type | `Readonly<{ [K in keyof G]: GuardType<G[K]>; }>` | Resolves a `GuardsShape` to a readonly object type of its guarded property types. |
329
+ | `OptionalFromGuards` | type | `Readonly<{ [P in Exclude<keyof S, K[number]>]: FromGuards<S>[P]; } & { [P in Extract<keyof S, K[number]>]?: FromGuards<S>[P]; }>` | Mirrors `FromGuards`, but every key listed in `K` becomes a true optional member (`?`) rather than a required key widened with `\| undefined`. |
330
+ | `TupleFromGuards` | type | `Readonly<{ [K in keyof Ts]: GuardType<Ts[K]>; }>` | Maps a tuple of element guards to a readonly tuple of their guarded types. |
331
+ | `UnionToIntersection` | type | `(U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never` | Converts a union type to an intersection type. |
332
+ | `IntersectionFromGuards` | type | `UnionToIntersection<GuardType<Gs[number]>>` | Intersects the types guarded by a tuple of guards — backs `intersectionOf`. |
333
+ | `Parser` | type | `(value: unknown) => T \| undefined` | Coerces an unknown value to `T`, or returns `undefined`. |
334
+ | `LiteralValue` | type | `string \| number \| boolean` | Represents a string, number, or boolean literal. |
335
+ | `Result` | type | `Success<T> \| Failure<E>` | Represents a discriminated union for operations that can succeed or fail without throwing. |
336
+ | `ReadValueOptions` | interface | `{ subject?, code?, context? }` | Represents optional diagnostic metadata for a required read. |
337
+ | `ContainOptions` | interface | `{ code?, context? }` | Represents optional diagnostic metadata for a public door's containment boundary. |
338
+ | `ShapeProperty` | interface | `{ key, child }` | Represents one captured property of an object shape, held as an ordered entry rather than as a `Map` pair. |
339
+ | `Success` | interface | `{ success, value }` | Represents the discriminated success branch of a `Result`. |
340
+ | `AnyConstructor` | type | `new (...args: unknown[]) => T` | Represents a constructor signature that produces instances of `T`. |
341
+ | `AnyFunction` | type | `(...args: unknown[]) => unknown` | Represents a function accepting any arguments and returning `unknown`. |
342
+ | `AnyAsyncFunction` | type | `(...args: unknown[]) => Promise<unknown>` | Represents an async function accepting any arguments and returning a `Promise`. |
343
+ | `ZeroArgFunction` | type | `() => unknown` | Represents a function accepting zero arguments and returning `unknown`. |
344
+ | `ZeroArgAsyncFunction` | type | `() => Promise<unknown>` | Represents an async function accepting zero arguments and returning a `Promise`. |
345
345
 
346
346
  ### Classes
347
347
 
348
348
  `ContractError` is documented in full under its own heading following this table.
349
349
 
350
- | API | Kind | Summary |
351
- | --------------- | ----- | -------------------------------------------------------------------------------------------- |
352
- | `ContractError` | class | Carries a machine-readable contract category, optional context, and an exact optional cause. |
350
+ | Name | Kind | Signature | Summary |
351
+ | --------------- | ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
352
+ | `ContractError` | class | `new (message: string, options: ContractErrorOptions) => ContractError` | Carries a machine-readable contract category, optional context, and an exact optional cause. |
353
353
 
354
354
  ### `ContractError`
355
355
 
@@ -374,9 +374,9 @@ optional member and `plus` introducing its call-signature members, and a type al
374
374
  literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
375
375
  guard row's the type it narrows to.
376
376
 
377
- | API | Kind | Shape | Summary |
377
+ | Name | Kind | Signature | Summary |
378
378
  | ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
379
- | `isContractError` | function | `ContractError` | Checks whether an unknown value is a `ContractError`. |
379
+ | `isContractError` | function | `(value: unknown) => value is ContractError` | Checks whether an unknown value is a `ContractError`. |
380
380
  | `ContractCode` | type | `'bound' \| 'range' \| 'empty' \| 'placement' \| 'structure' \| 'literal' \| 'cycle' \| 'pattern' \| 'generate' \| 'random' \| 'clone' \| 'depth' \| 'expansion'` | Names the machine-readable category carried by a `ContractError`. |
381
381
  | `CONTRACT_CODES` | const | `readonly ContractCode[]` | Lists every declared `ContractCode` refusal category, frozen. |
382
382
  | `ContractErrorContext` | interface | `{ path?, shape?, limit?, received? }` | Represents the optional structured details carried by a `ContractError`. |
@@ -395,14 +395,14 @@ optional member and `plus` introducing its call-signature members, and a type al
395
395
  literal with a union's arms escaped as `\|`. A class row's `Shape` cell holds the interface it
396
396
  implements, or its constructor signature where it implements none.
397
397
 
398
- | API | Kind | Shape | Summary |
399
- | ----------------------- | --------- | ----------------------- | ------------------------------------------------------------------------- |
400
- | `JSONCloner` | class | `JSONClonerInterface` | Owns the state of one exact JSON snapshot operation. |
401
- | `JSONClonerInterface` | interface | `{} plus clone` | Settles one exact JSON snapshot of a retained source, then replays it. |
402
- | `SchemaCloner` | class | `SchemaClonerInterface` | Owns the state of one JSON Schema snapshot operation. |
403
- | `SchemaClonerInterface` | interface | `{} plus clone` | Settles one JSON Schema snapshot of a retained schema, then replays it. |
404
- | `ShapeCloner` | class | `ShapeClonerInterface` | Owns the state of one contract-shape snapshot operation. |
405
- | `ShapeClonerInterface` | interface | `{} plus clone` | Settles one contract-shape snapshot of a retained shape, then replays it. |
398
+ | Name | Kind | Signature | Summary |
399
+ | ----------------------- | --------- | ---------------------------------------------------- | ------------------------------------------------------------------------- |
400
+ | `JSONCloner` | class | `new (value: unknown) => JSONClonerInterface` | Owns the state of one exact JSON snapshot operation. |
401
+ | `JSONClonerInterface` | interface | `{ clone() }` | Settles one exact JSON snapshot of a retained source, then replays it. |
402
+ | `SchemaCloner` | class | `new (schema: JSONSchema) => SchemaClonerInterface` | Owns the state of one JSON Schema snapshot operation. |
403
+ | `SchemaClonerInterface` | interface | `{ clone() }` | Settles one JSON Schema snapshot of a retained schema, then replays it. |
404
+ | `ShapeCloner` | class | `new (shape: ContractShape) => ShapeClonerInterface` | Owns the state of one contract-shape snapshot operation. |
405
+ | `ShapeClonerInterface` | interface | `{ clone() }` | Settles one contract-shape snapshot of a retained shape, then replays it. |
406
406
 
407
407
  `cloneShape` is the fresh eager boundary over `ShapeCloner`: every call constructs a new class instance and invokes `clone()`, so separate calls re-observe the source and produce distinct composite roots or diagnostics when identity is observable.
408
408
 
@@ -410,14 +410,14 @@ implements, or its constructor signature where it implements none.
410
410
 
411
411
  The machinery behind owned snapshots (see Shape builders, below) — from [`JSONCloner.ts`](../src/core/JSONCloner.ts), [`SchemaCloner.ts`](../src/core/SchemaCloner.ts), [`ShapeCloner.ts`](../src/core/ShapeCloner.ts), and the eager boundaries in [`cloners.ts`](../src/core/cloners.ts). The JSON cloner accepts only exact acyclic JSON data, rejects sparse or decorated arrays and non-data record properties without invoking accessors, and builds deeply frozen standard arrays plus null-prototype records. “Decorated” means the array own-key set contains anything other than intrinsic `length` and every canonical index, including an extra, substituted, symbol, hidden, or accessor key. Index writability and configurability are normalized rather than treated as JSON data, so frozen arrays and nonwritable data indices remain valid. Because JSON persistence is a tree, repeated noncyclic source aliases are duplicated into distinct equal output branches; active-path back-edges fail as cycles. `cloneJSONRecord` adds record-root validation over the same engine. `cloneSchema` preserves shared-child identity and closes cyclic schema edges onto its clone; `cloneShape` preserves sharing, carries one accepted declaration population into its clone, and runs the complete declaration gate on that carried clone before returning, so a cyclic shape is refused with the same `cycle` diagnosis as every other shape entry. A key literally named `__proto__` stays own data. Every hostile reflective operation is contained through the sanctioned total boundary, and so is every caller-reachable dispatch on the declaration gate's own path: `ShapeValidator.validate` and `validateShape` translate a failure they did not author into a coded `ContractError` carrying the exact thrown value, rather than rethrowing it verbatim. JSON reflection failures and schema enumeration failures remain cause-free. A schema property-read failure instead retains the exact thrown value as its cause, including an explicit `undefined`; caller-owned errors never become terminal errors by identity. Only the exact errors owned or explicitly adopted by an engine can replay by terminal identity.
412
412
 
413
- | API | Kind | Summary |
414
- | ------------------ | -------- | ---------------------------------------------------------------------------------------------- |
415
- | `cloneJSONValue` | function | Deep-clones exact JSON data into an owned frozen snapshot. |
416
- | `cloneJSONRecord` | function | Deep-clones an exact JSON object record into an owned frozen snapshot. |
417
- | `cloneSchema` | function | Deep-clones a JSON Schema graph into an owned frozen snapshot. |
418
- | `cloneShape` | function | Deep-clones a contract shape graph into an owned frozen snapshot. |
419
- | `CLONE_NODE_LIMIT` | const | Caps at `262144` the number of nodes one JSON snapshot may produce, frozen. |
420
- | `ownShape` | function | Takes ownership of a contract shape node as an independent `cloneShape` snapshot of its graph. |
413
+ | Name | Kind | Signature | Summary |
414
+ | ------------------ | -------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
415
+ | `cloneJSONValue` | function | `(value: unknown) => JSONValue` | Deep-clones exact JSON data into an owned frozen snapshot. |
416
+ | `cloneJSONRecord` | function | `(value: unknown) => JSONRecord` | Deep-clones an exact JSON object record into an owned frozen snapshot. |
417
+ | `cloneSchema` | function | `(schema: JSONSchema) => JSONSchema` | Deep-clones a JSON Schema graph into an owned frozen snapshot. |
418
+ | `cloneShape` | function | `((shape: StringShape) => StringShape) & ((shape: ContractShape) => ContractShape)` | Deep-clones a contract shape graph into an owned frozen snapshot. |
419
+ | `CLONE_NODE_LIMIT` | const | `262144` | Caps at `262144` the number of nodes one JSON snapshot may produce, frozen. |
420
+ | `ownShape` | function | `(shape: ContractShape) => ContractShape` | Takes ownership of a contract shape node as an independent `cloneShape` snapshot of its graph. |
421
421
 
422
422
  This constructs a `JSONCloner` directly and clones a record through `cloneJSONRecord`, showing that each snapshot is independently owned.
423
423
 
@@ -454,26 +454,26 @@ Declarative constructors for the `ContractShape` union (`src/core/shapers.ts`).
454
454
 
455
455
  **The snapshot-ownership model.** A builder freezes the node it returns and copies every collection you hand it — a `values` list, a `properties` map, a variant list, a `rawShape` fragment — while a `pattern` is captured and re-exposed as a fresh frozen `RegExp` per read, so editing your originals afterwards cannot reach the shape. `objectShape` enumerates a caller-owned property declaration once and carries that key/value snapshot. `cloneShape`, which must also validate a hand-authored graph, first requires every node to be a plain, null-prototype, or foreign-realm record before it reads the discriminant, then captures each declared field through own descriptors plus two agreeing reads before it builds the shell. Missing fields are carried as absent without a read; inherited fields and ordinary accessors are refused without invocation. The documented `pattern` accessor is the one exception, and its two frozen genuine-RegExp results must independently expose agreeing primitive-string `source` and `flags` pairs; no caller scalar object or conversion hook is retained. Structural children, literal values, variants, property maps, and raw-schema roots are then wired only from those captured references, never by rereading the source node. Property maps retain their separate stability mechanism: `cloneShape` compares exactly two caller enumerations and refuses second-population disagreement, while the first enumeration obtains every property child's own data descriptor and requires its value plus two reads to agree by identity. The complete declaration gate validates the carried cloned root; it does not repair or replace a captured population. Consequently, `createContract` reads a property entry exactly as often as `cloneShape` does — twice, and the two readings must agree — because it reaches the declaration the same way: there is no discarded pre-ownership walk, so there is no second caller population to disagree with the captured one. That single captured clone controls every artifact, an invalid captured population is refused by the gate that runs over the clone, and no third caller value read occurs. `ownShape` retains the already-performed `cloneShape` result for frozen and unfrozen inputs alike, so no caller-owned root or reference-bearing child is returned by identity. Thus a malformed value container, raw-schema child, discriminant, scalar, or structural slot cannot become plausible merely because copying would normalize it. A hand-authored `{ category: 'string', pattern }` node receives the same accessor-owned pattern snapshot as builder output and must likewise use an unflagged genuine local- or foreign-realm `RegExp`; inline constructs express the supported flag-like behavior. `createContract` takes its own `cloneShape` snapshot of the whole graph, so its `schema` / `is` / `parse` / `audit` / `explain` / `generate` are fixed at construction and cannot drift with a later edit to the shape you passed. The practical rule: build shapes with the builders, and treat a shape you assemble by hand as caller-owned until a compiler or `ownShape` has copied it.
456
456
 
457
- | Builder | Kind | Summary |
458
- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
459
- | `stringShape` | function | Builds a string `StringShape`. |
460
- | `numberShape` | function | Builds a numeric `NumberShape`. |
461
- | `integerShape` | function | Builds an integer `NumberShape` — forces `integer: true`. |
462
- | `booleanShape` | function | Builds a `BooleanShape`. |
463
- | `nullShape` | function | Builds a `NullShape`. |
464
- | `literalShape` | function | Builds a literal shape from a fixed set of primitive values. |
465
- | `arrayShape` | function | Builds an `ArrayShape` from an element shape. |
466
- | `objectShape` | function | Builds an `ObjectShape` from a property map. |
467
- | `recordShape` | function | Builds an open `ObjectShape` with no fixed properties — a dictionary. |
468
- | `unionShape` | function | Builds a `UnionShape` from a list of variant shapes (`anyOf` in JSON Schema). |
469
- | `oneOfShape` | function | Builds a `UnionShape` that emits `oneOf` (exactly one match) in JSON Schema. |
470
- | `optionalShape` | function | Wraps a shape so it may be absent (`undefined`). |
471
- | `nullableShape` | function | Wraps a shape so it may be `null`. |
472
- | `jsonShape` | function | Builds a `JSONShape`. |
473
- | `rawShape` | function | Builds a `RawShape` from a supported JSON Schema fragment. |
474
- | `schemaToShape` | function | Converts a runtime `JSONSchema` value into a validating `ContractShape` — the inverse of `compileSchema`. Unlike direct `rawShape` construction, which rejects malformed supported-vocabulary keywords, this conversion is total and widens an inexpressible input to a valid raw `{}`. |
475
- | `deriveLengthBounds` | function | Derives `min`/`max` shape bounds from a pair of non-negative-integer JSON Schema length keywords (`minLength`/`maxLength`, `minItems`/`maxItems`). |
476
- | `deriveRangeBounds` | function | Derives `min`/`max` shape bounds from a pair of finite-number JSON Schema range keywords (`minimum`/`maximum`). |
457
+ | Name | Kind | Signature | Summary |
458
+ | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
459
+ | `stringShape` | function | `(options?: StringShapeOptions) => StringShape` | Builds a string `StringShape`. |
460
+ | `numberShape` | function | `(options?: NumberShapeOptions) => NumberShape` | Builds a numeric `NumberShape`. |
461
+ | `integerShape` | function | `(options?: Omit<NumberShapeOptions, 'integer'>) => NumberShape` | Builds an integer `NumberShape` — forces `integer: true`. |
462
+ | `booleanShape` | function | `(options?: BooleanShapeOptions) => BooleanShape` | Builds a `BooleanShape`. |
463
+ | `nullShape` | function | `(options?: NullShapeOptions) => NullShape` | Builds a `NullShape`. |
464
+ | `literalShape` | function | `<const T extends readonly LiteralValue[]>(values: T, options?: LiteralShapeOptions) => LiteralShape<Readonly<T>>` | Builds a literal shape from a fixed set of primitive values. |
465
+ | `arrayShape` | function | `<S extends ContractShape>(items: S, options?: ArrayShapeOptions) => ArrayShape<S>` | Builds an `ArrayShape` from an element shape. |
466
+ | `objectShape` | function | `<P extends Readonly<Record<string, ContractShape>>, const A extends boolean \| ContractShape = false>(properties: P, options?: ObjectShapeOptions<A>) => ObjectShape<P, A>` | Builds an `ObjectShape` from a property map. |
467
+ | `recordShape` | function | `<S extends ContractShape>(values: S, options?: RecordShapeOptions) => ObjectShape<Record<never, never>, S>` | Builds an open `ObjectShape` with no fixed properties — a dictionary. |
468
+ | `unionShape` | function | `<V extends readonly ContractShape[]>(...variants: V) => UnionShape<Readonly<V>>` | Builds a `UnionShape` from a list of variant shapes (`anyOf` in JSON Schema). |
469
+ | `oneOfShape` | function | `<V extends readonly ContractShape[]>(...variants: V) => UnionShape<Readonly<V>>` | Builds a `UnionShape` that emits `oneOf` (exactly one match) in JSON Schema. |
470
+ | `optionalShape` | function | `<S extends ContractShape>(inner: S) => OptionalShape<S>` | Wraps a shape so it may be absent (`undefined`). |
471
+ | `nullableShape` | function | `<S extends ContractShape>(inner: S) => NullableShape<S>` | Wraps a shape so it may be `null`. |
472
+ | `jsonShape` | function | `(options?: JSONShapeOptions) => JSONShape` | Builds a `JSONShape`. |
473
+ | `rawShape` | function | `(schema: JSONSchema) => RawShape` | Builds a `RawShape` from a supported JSON Schema fragment. |
474
+ | `schemaToShape` | function | `(schema: JSONSchema) => ContractShape` | Converts a runtime `JSONSchema` value into a validating `ContractShape` — the inverse of `compileSchema`. Unlike direct `rawShape` construction, which rejects malformed supported-vocabulary keywords, this conversion is total and widens an inexpressible input to a valid raw `{}`. |
475
+ | `deriveLengthBounds` | function | `(min: unknown, max: unknown) => BoundsRead` | Derives `min`/`max` shape bounds from a pair of non-negative-integer JSON Schema length keywords (`minLength`/`maxLength`, `minItems`/`maxItems`). |
476
+ | `deriveRangeBounds` | function | `(min: unknown, max: unknown) => BoundsRead` | Derives `min`/`max` shape bounds from a pair of finite-number JSON Schema range keywords (`minimum`/`maximum`). |
477
477
 
478
478
  Raw-schema validation is deliberately structural and vocabulary-domain validation, not a full JSON Schema solver. It checks that every keyword is supported, every keyword value has the declared runtime domain, arrays are dense and vocabularies unique where required, every member captured from a present `properties`, dense `anyOf`, or dense `oneOf` population is a plain record, patterns compile, and the graph stays acyclic and within the depth limit. Population is determined by membership, so a present member valued `undefined` is refused rather than erased as absence; omitted optional keywords, plus explicitly `undefined` `items` and `additionalProperties`, retain their absence behavior. It does not resolve cross-keyword contradictions such as `minLength: 5` with `maxLength: 1`, require each `required` name to appear in `properties`, enforce keyword/type coherence, compare `enum` members with `type`, or restrict `format` to a known vocabulary; those semantic interactions remain the responsibility of a full JSON Schema implementation.
479
479
 
@@ -508,36 +508,36 @@ optional member and `plus` introducing its call-signature members, and a type al
508
508
  literal with a union's arms escaped as `\|`. A resolver whose value is a multi-branch
509
509
  conditional carries none, and its `Summary` states what the resolution produces.
510
510
 
511
- | Type | Kind | Shape | Summary |
512
- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
513
- | `ContractShape` | type | `StringShape \| NumberShape \| BooleanShape \| NullShape \| LiteralShape \| ArrayShape \| ObjectShape \| UnionShape \| OptionalShape \| NullableShape \| JSONShape \| RawShape` | Describes a value declaratively — a declaration the shape builders build and the compilers turn into a guard, a parser, a JSON Schema, and a generator. |
514
- | `StringShape` | interface | `{ category, min?, max?, pattern?, description? }` | Describes a string with optional length and pattern constraints. |
515
- | `NumberShape` | interface | `{ category, min?, max?, integer?, description? }` | Describes a number with optional bounds; `integer` restricts to whole numbers. |
516
- | `BooleanShape` | interface | `{ category, description? }` | Describes a boolean — accepts only `true` or `false`. |
517
- | `NullShape` | interface | `{ category, description? }` | Describes a null value — accepts only `null`. |
518
- | `LiteralShape` | interface | `{ category, values, description? }` | Describes a literal — accepts exactly one of a fixed set of primitive values. |
519
- | `ArrayShape` | interface | `{ category, items, min?, max?, description? }` | Describes an array with an element shape and optional length bounds. |
520
- | `ObjectShape` | interface | `{ category, properties, additionalProperties?, description? }` | Describes an object — a map of property names to child shapes. |
521
- | `UnionShape` | interface | `{ category, variants, mode?, description? }` | Describes a union — accepts a value matching any one variant (first match wins). |
522
- | `OptionalShape` | interface | `{ category, inner }` | Wraps an inner shape that may be absent (`undefined`). |
523
- | `NullableShape` | interface | `{ category, inner }` | Wraps an inner shape that may be `null`. |
524
- | `JSONShape` | interface | `{ category, description? }` | Describes a JSON passthrough — accepts any JSON value. |
525
- | `RawShape` | interface | `{ category, schema }` | Describes a validated raw JSON Schema passthrough — embeds a supported schema fragment directly. |
526
- | `Infer` | type | | Resolves the static TypeScript type a `ContractShape` describes. |
527
- | `InferObject` | type | | Resolves `Infer` of an object shape's `properties` — the required keys, plus the `optional`-wrapped keys as optional members, plus the index-signature contribution of `additionalProperties` (see `InferIndex`). |
528
- | `InferIndex` | type | | Computes the index-signature contribution of a pure record shape's `additionalProperties` — the `recordShape` case, where `properties` is empty. |
529
- | `InferOpenIndex` | type | | Computes the index-signature contribution of a MIXED object shape's `additionalProperties` — one with both fixed `properties` and an open tail. |
530
- | `InferMutable` | type | `{ -readonly [K in keyof Infer<S>]: Infer<S>[K] }` | Strips the TOP-LEVEL `readonly` modifiers from `Infer` (a shallow strip — nested object/array properties stay readonly) — for consumers writing the parsed value's own fields. |
531
- | `InferUnion` | type | `V extends ReadonlyArray<infer U> ? (U extends ContractShape ? Infer<U> : never) : never` | Resolves `Infer` of a union shape's `variants` — the union of each variant's inferred type. |
532
- | `StringShapeOptions` | interface | `{ min?, max?, pattern?, description? }` | Groups the options for `StringShape` (through `stringShape`). |
533
- | `NumberShapeOptions` | interface | `{ min?, max?, integer?, description? }` | Groups the options for `NumberShape` (through `numberShape` / `integerShape`). |
534
- | `BooleanShapeOptions` | interface | `{ description? }` | Groups the options for `BooleanShape` (through `booleanShape`). |
535
- | `NullShapeOptions` | interface | `{ description? }` | Groups the options for `NullShape` (through `nullShape`). |
536
- | `JSONShapeOptions` | interface | `{ description? }` | Groups the options for `JSONShape` (through `jsonShape`). |
537
- | `LiteralShapeOptions` | interface | `{ description? }` | Groups the options for `LiteralShape` (through `literalShape`). |
538
- | `ArrayShapeOptions` | interface | `{ min?, max?, description? }` | Groups the options for `ArrayShape` (through `arrayShape`). |
539
- | `ObjectShapeOptions` | interface | `{ additionalProperties?, description? }` | Groups the options for `ObjectShape` (through `objectShape`). |
540
- | `RecordShapeOptions` | interface | `{ description? }` | Groups the options for record shapes (through `recordShape`). |
511
+ | Name | Kind | Signature | Summary |
512
+ | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
513
+ | `ContractShape` | type | `StringShape \| NumberShape \| BooleanShape \| NullShape \| LiteralShape \| ArrayShape \| ObjectShape \| UnionShape \| OptionalShape \| NullableShape \| JSONShape \| RawShape` | Describes a value declaratively — a declaration the shape builders build and the compilers turn into a guard, a parser, a JSON Schema, and a generator. |
514
+ | `StringShape` | interface | `{ category, min?, max?, pattern?, description? }` | Describes a string with optional length and pattern constraints. |
515
+ | `NumberShape` | interface | `{ category, min?, max?, integer?, description? }` | Describes a number with optional bounds; `integer` restricts to whole numbers. |
516
+ | `BooleanShape` | interface | `{ category, description? }` | Describes a boolean — accepts only `true` or `false`. |
517
+ | `NullShape` | interface | `{ category, description? }` | Describes a null value — accepts only `null`. |
518
+ | `LiteralShape` | interface | `{ category, values, description? }` | Describes a literal — accepts exactly one of a fixed set of primitive values. |
519
+ | `ArrayShape` | interface | `{ category, items, min?, max?, description? }` | Describes an array with an element shape and optional length bounds. |
520
+ | `ObjectShape` | interface | `{ category, properties, additionalProperties?, description? }` | Describes an object — a map of property names to child shapes. |
521
+ | `UnionShape` | interface | `{ category, variants, mode?, description? }` | Describes a union — accepts a value matching any one variant (first match wins). |
522
+ | `OptionalShape` | interface | `{ category, inner }` | Wraps an inner shape that may be absent (`undefined`). |
523
+ | `NullableShape` | interface | `{ category, inner }` | Wraps an inner shape that may be `null`. |
524
+ | `JSONShape` | interface | `{ category, description? }` | Describes a JSON passthrough — accepts any JSON value. |
525
+ | `RawShape` | interface | `{ category, schema }` | Describes a validated raw JSON Schema passthrough — embeds a supported schema fragment directly. |
526
+ | `Infer` | type | `[ContractShape] extends [S] ? unknown : S extends StringShape ? string : S extends NumberShape ? number : S extends BooleanShape ? boolean : S extends NullShape ? null : S extends { readonly category: 'literal'; readonly values: infer V; } ? V extends ReadonlyArray<infer L> ? L : never : S extends { readonly category: 'array'; readonly items: infer I; } ? I extends ContractShape ? ReadonlyArray<Infer<I>> : never : S extends ObjectShape<infer P, infer A> ? P extends Readonly<Record<string, ContractShape>> ? [A] extends [boolean \| ContractShape] ? InferObject<P, A> : never : never : S extends { readonly category: 'union'; readonly variants: infer V; } ? V extends readonly ContractShape[] ? InferUnion<V> : never : S extends { readonly category: 'optional'; readonly inner: infer I; } ? I extends ContractShape ? Infer<I> \| undefined : never : S extends { readonly category: 'nullable'; readonly inner: infer I; } ? I extends ContractShape ? Infer<I> \| null : never : S extends JSONShape ? JSONValue : unknown` | Resolves the static TypeScript type a `ContractShape` describes. |
527
+ | `InferObject` | type | `[keyof P] extends [never] ? [A] extends [false] ? Readonly<Record<never, never>> : InferIndex<A> : Readonly<{ [K in keyof P as P[K] extends { readonly category: 'optional'; } ? never : K]: Infer<P[K]>; } & { [K in keyof P as P[K] extends { readonly category: 'optional'; } ? K : never]?: P[K] extends { readonly category: 'optional'; readonly inner: infer I; } ? I extends ContractShape ? Infer<I> : never : never; }> & InferOpenIndex<A>` | Resolves `Infer` of an object shape's `properties` — the required keys, plus the `optional`-wrapped keys as optional members, plus the index-signature contribution of `additionalProperties` (see `InferIndex`). |
528
+ | `InferIndex` | type | `[A] extends [false] ? unknown : [A] extends [true] ? { readonly [k: string]: unknown; } : [A] extends [ContractShape] ? { readonly [k: string]: Infer<A>; } : unknown` | Computes the index-signature contribution of a pure record shape's `additionalProperties` — the `recordShape` case, where `properties` is empty. |
529
+ | `InferOpenIndex` | type | `[A] extends [false] ? unknown : [A] extends [true] ? { readonly [k: string]: unknown; } : [A] extends [ContractShape] ? { readonly [k: string]: unknown; } : unknown` | Computes the index-signature contribution of a MIXED object shape's `additionalProperties` — one with both fixed `properties` and an open tail. |
530
+ | `InferMutable` | type | `{ -readonly [K in keyof Infer<S>]: Infer<S>[K]; }` | Strips the TOP-LEVEL `readonly` modifiers from `Infer` (a shallow strip — nested object/array properties stay readonly) — for consumers writing the parsed value's own fields. |
531
+ | `InferUnion` | type | `V extends ReadonlyArray<infer U> ? (U extends ContractShape ? Infer<U> : never) : never` | Resolves `Infer` of a union shape's `variants` — the union of each variant's inferred type. |
532
+ | `StringShapeOptions` | interface | `{ min?, max?, pattern?, description? }` | Groups the options for `StringShape` (through `stringShape`). |
533
+ | `NumberShapeOptions` | interface | `{ min?, max?, integer?, description? }` | Groups the options for `NumberShape` (through `numberShape` / `integerShape`). |
534
+ | `BooleanShapeOptions` | interface | `{ description? }` | Groups the options for `BooleanShape` (through `booleanShape`). |
535
+ | `NullShapeOptions` | interface | `{ description? }` | Groups the options for `NullShape` (through `nullShape`). |
536
+ | `JSONShapeOptions` | interface | `{ description? }` | Groups the options for `JSONShape` (through `jsonShape`). |
537
+ | `LiteralShapeOptions` | interface | `{ description? }` | Groups the options for `LiteralShape` (through `literalShape`). |
538
+ | `ArrayShapeOptions` | interface | `{ min?, max?, description? }` | Groups the options for `ArrayShape` (through `arrayShape`). |
539
+ | `ObjectShapeOptions` | interface | `{ additionalProperties?, description? }` | Groups the options for `ObjectShape` (through `objectShape`). |
540
+ | `RecordShapeOptions` | interface | `{ description? }` | Groups the options for record shapes (through `recordShape`). |
541
541
 
542
542
  ### Compilers
543
543
 
@@ -549,27 +549,27 @@ literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds
549
549
  guard row's the type it narrows to. A class row's `Shape` cell holds the interface it
550
550
  implements, or its constructor signature where it implements none.
551
551
 
552
- | API | Kind | Shape | Summary |
553
- | --------------------------- | --------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
554
- | `ShapeValidator` | class | `ShapeValidatorInterface` | Validates one retained contract-shape source live on every call. |
555
- | `ShapeValidatorInterface` | interface | `{ expansion } plus validate` | Validates one retained contract-shape source on demand. |
556
- | `validateShape` | function | `(shape: ContractShape) => void` | Gates recursive compiler work on shape structure, depth, and cycles. |
557
- | `compileGuard` | function | `<S extends ContractShape>(shape: S) => Guard<Infer<S>>` | Compiles a `ContractShape` into a runtime type guard. |
558
- | `compileParser` | function | `<S extends ContractShape>(shape: S) => Parser<Infer<S>>` | Compiles a `ContractShape` into an input parser. |
559
- | `compileSchema` | function | `(shape: ContractShape) => JSONSchema` | Compiles a `ContractShape` into a JSON Schema document. |
560
- | `compileGenerator` | function | `<S extends ContractShape>(shape: S, random?: RandomFunction) => Infer<S>` | Compiles a `ContractShape` into a deterministic seed value. |
561
- | `createContract` | function | `<S extends ContractShape>(shape: S) => ContractInterface<Infer<S>>` | Compiles a `ContractShape` into a `ContractInterface` — the lockstep outputs from one declaration, lockstep meaning derived from one owned snapshot rather than accepting the same values. |
562
- | `ContractInterface` | interface | `{ schema, is } plus parse, audit, explain, generate` | Represents a compiled contract — the lockstep outputs derived from one shape. |
563
- | `ContractCompiler` | class | `ContractCompilerInterface` | Owns one contract shape's artifacts and their bundle, compiled lazily. |
564
- | `ContractCompilerInterface` | interface | `{ schema, guard, parser, auditor, reporter, generator, contract }` | Owns one contract shape's compiled artifacts plus their bundle, lazily. |
565
- | `RandomFunction` | type | `() => number` | Represents a deterministic random source returning a value in `[0, 1)`. |
566
- | `AuditorFunction` | type | `(value: unknown, path?: readonly string[]) => readonly AuditFault[]` | Represents a compiled strict-domain diagnostic — the shape of `compileAuditor` bound to one shape. |
567
- | `ReporterFunction` | type | `(value: unknown, path?: readonly string[]) => readonly Fault[]` | Represents a compiled coercive-domain diagnostic — the shape of `compileReporter` bound to one shape. |
568
- | `SeederFunction` | type | `(random?: RandomFunction) => T` | Represents a compiled seed-data source — the shape of `compileGenerator` bound to one shape. |
569
- | `GENERATION_ATTEMPT_LIMIT` | const | `number` | Caps at `32` the number of candidate-generation attempts for a constrained generated value, frozen. |
570
- | `COMPILE_DEPTH_LIMIT` | const | `number` | Caps at `512` the supported nesting depth of a compiled contract shape, frozen. |
571
- | `COMPILE_NODE_LIMIT` | const | `number` | Caps at `16384` the number of nodes a compiled artifact may expand a shape into, frozen. |
572
- | `PRESENCE_MASK_LIMIT` | const | `number` | Caps at `31` the number of object keys one compiled presence mask carries, frozen. |
552
+ | Name | Kind | Signature | Summary |
553
+ | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
554
+ | `ShapeValidator` | class | `new (shape: ContractShape) => ShapeValidatorInterface` | Validates one retained contract-shape source live on every call. |
555
+ | `ShapeValidatorInterface` | interface | `{ expansion, validate() }` | Validates one retained contract-shape source on demand. |
556
+ | `validateShape` | function | `(shape: ContractShape) => void` | Gates recursive compiler work on shape structure, depth, and cycles. |
557
+ | `compileGuard` | function | `(<S extends ContractShape>(shape: S) => Guard<Infer<S>>) & ((shape: ContractShape) => Guard<unknown>)` | Compiles a `ContractShape` into a runtime type guard. |
558
+ | `compileParser` | function | `(<S extends ContractShape>(shape: S) => Parser<Infer<S>>) & ((shape: ContractShape) => Parser<unknown>)` | Compiles a `ContractShape` into an input parser. |
559
+ | `compileSchema` | function | `(shape: ContractShape) => JSONSchema` | Compiles a `ContractShape` into a JSON Schema document. |
560
+ | `compileGenerator` | function | `(<S extends ContractShape>(shape: S, random?: RandomFunction) => Infer<S>) & ((shape: ContractShape, random?: RandomFunction) => unknown)` | Compiles a `ContractShape` into a deterministic seed value. |
561
+ | `createContract` | function | `(<S extends ContractShape>(shape: S) => ContractInterface<Infer<S>>) & ((shape: ContractShape) => ContractInterface<unknown>)` | Compiles a `ContractShape` into a `ContractInterface` — the lockstep outputs from one declaration, lockstep meaning derived from one owned snapshot rather than accepting the same values. |
562
+ | `ContractInterface` | interface | `{ schema, is, parse(), audit(), explain(), generate() }` | Represents a compiled contract — the lockstep outputs derived from one shape. |
563
+ | `ContractCompiler` | class | `new <S extends ContractShape = ContractShape>(shape: S) => ContractCompilerInterface<S>` | Owns one contract shape's artifacts and their bundle, compiled lazily. |
564
+ | `ContractCompilerInterface` | interface | `{ schema, guard, parser, auditor, reporter, generator, contract }` | Owns one contract shape's compiled artifacts plus their bundle, lazily. |
565
+ | `RandomFunction` | type | `() => number` | Represents a deterministic random source returning a value in `[0, 1)`. |
566
+ | `AuditorFunction` | type | `(value: unknown, path?: readonly string[]) => readonly AuditFault[]` | Represents a compiled strict-domain diagnostic — the shape of `compileAuditor` bound to one shape. |
567
+ | `ReporterFunction` | type | `(value: unknown, path?: readonly string[]) => readonly Fault[]` | Represents a compiled coercive-domain diagnostic — the shape of `compileReporter` bound to one shape. |
568
+ | `SeederFunction` | type | `(random?: RandomFunction) => T` | Represents a compiled seed-data source — the shape of `compileGenerator` bound to one shape. |
569
+ | `GENERATION_ATTEMPT_LIMIT` | const | `32` | Caps at `32` the number of candidate-generation attempts for a constrained generated value, frozen. |
570
+ | `COMPILE_DEPTH_LIMIT` | const | `512` | Caps at `512` the supported nesting depth of a compiled contract shape, frozen. |
571
+ | `COMPILE_NODE_LIMIT` | const | `16384` | Caps at `16384` the number of nodes a compiled artifact may expand a shape into, frozen. |
572
+ | `PRESENCE_MASK_LIMIT` | const | `31` | Caps at `31` the number of object keys one compiled presence mask carries, frozen. |
573
573
 
574
574
  `ContractCompilerInterface` declares no call-signature member, so it has no Methods table: its
575
575
  whole surface is the readonly data properties — `schema` (a `JSONSchema`), `guard` (a
@@ -622,7 +622,7 @@ optional member and `plus` introducing its call-signature members, and a type al
622
622
  literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
623
623
  guard row's the type it narrows to.
624
624
 
625
- | API | Kind | Shape | Summary |
625
+ | Name | Kind | Signature | Summary |
626
626
  | ---------------------- | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
627
627
  | `valueToSchema` | function | `(value: unknown, options?: ValueToSchemaOptions) => JSONSchema` | Infers a `JSONSchema` for one unknown value — the reverse direction of `compileSchema`. |
628
628
  | `samplesToSchema` | function | `(samples: readonly unknown[], options?: ValueToSchemaOptions) => JSONSchema` | Infers a `JSONSchema` from a set of example values — the multi-example counterpart of `valueToSchema` (for example inferring one schema from several database rows). |
@@ -641,10 +641,10 @@ guard row's the type it narrows to.
641
641
  | `SampleMemo` | interface | `{ rows, schemas }` | Holds the per-walk memo the multi-sample walk behind `samplesToSchema` owns, keyed by the ORDERED identities of the rows a slot collected. |
642
642
  | `sanitizeDepth` | function | `(value: number \| undefined) => number` | Resolves a caller's depth budget to one the traversal can actually survive. |
643
643
  | `sanitizeBudget` | function | `(value: number \| undefined, fallback: number) => number` | Sanitizes a user-supplied inference budget (`limits.depth` / `limits.properties`) to a finite non-negative integer, selecting a valid fallback for anything else. |
644
- | `INFER_DEPTH_LIMIT` | const | `number` | Caps at `32` the object/array nesting depth `valueToSchema` walks, frozen. |
645
- | `INFER_BREADTH_LIMIT` | const | `number` | Caps by default at `256` the number of object properties / array elements `valueToSchema` samples per container, frozen. |
646
- | `INFER_ENUM_LIMIT` | const | `number` | Caps by default at `12` the number of distinct values a multi-sample slot may hold before enum inference gives up and falls back to a bare `type`, frozen. |
647
- | `FORMAT_MAX_LENGTH` | const | `number` | Caps at `128` the string length `stringToFormat` attempts to classify, frozen. |
644
+ | `INFER_DEPTH_LIMIT` | const | `32` | Caps at `32` the object/array nesting depth `valueToSchema` walks, frozen. |
645
+ | `INFER_BREADTH_LIMIT` | const | `256` | Caps by default at `256` the number of object properties / array elements `valueToSchema` samples per container, frozen. |
646
+ | `INFER_ENUM_LIMIT` | const | `12` | Caps by default at `12` the number of distinct values a multi-sample slot may hold before enum inference gives up and falls back to a bare `type`, frozen. |
647
+ | `FORMAT_MAX_LENGTH` | const | `128` | Caps at `128` the string length `stringToFormat` attempts to classify, frozen. |
648
648
  | `FORMAT_PATTERNS` | const | `Readonly<Record<'uuid' \| 'email' \| 'uri', RegExp>>` | Holds the pure-regex matchers backing `stringToFormat`'s pattern-only formats (`uuid` / `email` / `uri`), frozen as data. |
649
649
 
650
650
  Canonicalization classifies every non-null object at the read boundary before choosing a traversal. Arrays retain the dense indexed path; the shared realm-neutral `matchesRecordBrand` rule selects sorted own keys for ordinary, null-prototype, and foreign-realm plain records; every other readable exotic object — including a class whose prototype a caller reparented to `null` — keeps the existing `JSON.stringify` fallback. A failed prototype inspection is unreadable structure, reported as `canonicalStringify: value could not be read`.
@@ -678,23 +678,23 @@ optional member and `plus` introducing its call-signature members, and a type al
678
678
  literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature, and a
679
679
  guard row's the type it narrows to.
680
680
 
681
- | API | Kind | Shape | Summary |
682
- | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
683
- | `compileAuditor` | function | `(shape: ContractShape, value: unknown, path?: readonly string[]) => readonly AuditFault[]` | Audits a value against the strict acceptance domain of a `ContractShape`. |
684
- | `compileReporter` | function | `(shape: ContractShape, value: unknown, path?: readonly string[]) => readonly Fault[]` | Compiles a `ContractShape` into a structured fault report for a value — the diagnostic counterpart of `compileGuard` / `compileParser`. |
685
- | `buildStringFaults` | function | `(shape: StringShape, value: string, path: readonly string[], pattern?: RegExp) => readonly Fault[]` | Builds the refinement faults a string value has against a `StringShape`. |
686
- | `buildNumberFaults` | function | `(shape: NumberShape, value: number, path: readonly string[]) => readonly Fault[]` | Builds the refinement faults a number value has against a `NumberShape`. |
687
- | `buildArrayFaults` | function | `(shape: ArrayShape, length: number, path: readonly string[]) => readonly Fault[]` | Builds the length faults an array has against an `ArrayShape`. |
688
- | `selectClosestFaults` | function | `<T extends AuditFault>(reports: ReadonlyArray<readonly T[]>) => readonly T[]` | Selects the report of the variant that came closest to matching. |
689
- | `shapeToKind` | function | `(shape: ContractShape) => FaultKind` | Projects a `ContractShape` to the `FaultKind` it describes. |
690
- | `preview` | function | `(value: unknown) => string` | Renders an unknown value as a short, safe, TOTAL string for a `Fault`'s `received` field. |
691
- | `FAULT_LIMIT` | const | `number` | Caps at `64` the number of `Fault` / `AuditFault` entries a single `explain` or `audit` report ever returns, frozen. |
692
- | `PREVIEW_LIMIT` | const | `number` | Caps at `64` the character length of a `preview`-rendered string, frozen. |
693
- | `Fault` | type | `{ reason: 'type', path, expected, received } \| { reason: 'missing', path, expected } \| { reason: 'constraint', path, expected, constraint, limit?, received } \| { reason: 'variant', path, variants } \| { reason: 'oneOf', path, matched }` | Represents a single structured parse-failure diagnostic — one entry of an `ContractInterface.explain` report. |
694
- | `ExtraFault` | interface | `{ reason, path }` | Represents a key present on a value that its closed object shape does not declare. |
695
- | `AuditFault` | type | `Fault \| ExtraFault` | Covers every fault an audit reports — the parse faults plus undeclared keys. |
696
- | `FaultKind` | type | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'literal' \| 'array' \| 'object' \| 'union' \| 'json'` | Names the kind of value a `Fault` expected — the shape-projected counterpart of a `ContractShape`'s `category`. |
697
- | `FaultConstraint` | type | `'min' \| 'max' \| 'pattern' \| 'integer'` | Names the refinement a `Fault` of reason `'constraint'` violates. |
681
+ | Name | Kind | Signature | Summary |
682
+ | --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
683
+ | `compileAuditor` | function | `(shape: ContractShape, value: unknown, path?: readonly string[]) => readonly AuditFault[]` | Audits a value against the strict acceptance domain of a `ContractShape`. |
684
+ | `compileReporter` | function | `(shape: ContractShape, value: unknown, path?: readonly string[]) => readonly Fault[]` | Compiles a `ContractShape` into a structured fault report for a value — the diagnostic counterpart of `compileGuard` / `compileParser`. |
685
+ | `buildStringFaults` | function | `(shape: StringShape, value: string, path: readonly string[], pattern?: RegExp) => readonly Fault[]` | Builds the refinement faults a string value has against a `StringShape`. |
686
+ | `buildNumberFaults` | function | `(shape: NumberShape, value: number, path: readonly string[]) => readonly Fault[]` | Builds the refinement faults a number value has against a `NumberShape`. |
687
+ | `buildArrayFaults` | function | `(shape: ArrayShape, length: number, path: readonly string[]) => readonly Fault[]` | Builds the length faults an array has against an `ArrayShape`. |
688
+ | `selectClosestFaults` | function | `<T extends AuditFault>(reports: ReadonlyArray<readonly T[]>) => readonly T[]` | Selects the report of the variant that came closest to matching. |
689
+ | `shapeToKind` | function | `(shape: ContractShape) => FaultKind` | Projects a `ContractShape` to the `FaultKind` it describes. |
690
+ | `preview` | function | `(value: unknown) => string` | Renders an unknown value as a short, safe, TOTAL string for a `Fault`'s `received` field. |
691
+ | `FAULT_LIMIT` | const | `64` | Caps at `64` the number of `Fault` / `AuditFault` entries a single `explain` or `audit` report ever returns, frozen. |
692
+ | `PREVIEW_LIMIT` | const | `64` | Caps at `64` the character length of a `preview`-rendered string, frozen. |
693
+ | `Fault` | type | `{ readonly reason: 'type'; readonly path: FieldPath; readonly expected: FaultKind; readonly received: string; } \| { readonly reason: 'missing'; readonly path: FieldPath; readonly expected: FaultKind; } \| { readonly reason: 'constraint'; readonly path: FieldPath; readonly expected: FaultKind; readonly constraint: FaultConstraint; readonly limit?: number \| string; readonly received: string; } \| { readonly reason: 'variant'; readonly path: FieldPath; readonly variants: number; } \| { readonly reason: 'oneOf'; readonly path: FieldPath; readonly matched: number; }` | Represents a single structured parse-failure diagnostic — one entry of an `ContractInterface.explain` report. |
694
+ | `ExtraFault` | interface | `{ reason, path }` | Represents a key present on a value that its closed object shape does not declare. |
695
+ | `AuditFault` | type | `Fault \| ExtraFault` | Covers every fault an audit reports — the parse faults plus undeclared keys. |
696
+ | `FaultKind` | type | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'null' \| 'literal' \| 'array' \| 'object' \| 'union' \| 'json'` | Names the kind of value a `Fault` expected — the shape-projected counterpart of a `ContractShape`'s `category`. |
697
+ | `FaultConstraint` | type | `'min' \| 'max' \| 'pattern' \| 'integer'` | Names the refinement a `Fault` of reason `'constraint'` violates. |
698
698
 
699
699
  #### How a union is audited and reported
700
700