@orkestrel/scaffold 0.0.118 → 0.0.120

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/dist/bin/main.js +15 -15
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/platforms/windows.md +2 -1
  4. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  5. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  8. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +2 -1
  9. package/dist/host/claude/agents/orkestrel.md +27 -26
  10. package/dist/host/claude/rules/names.md +3 -2
  11. package/dist/host/claude/rules/tests.md +4 -2
  12. package/dist/host/claude/rules/typescript.md +2 -3
  13. package/dist/host/claude/rules/workspace.md +2 -1
  14. package/dist/host/guides/abort.md +0 -4
  15. package/dist/host/guides/budget.md +1 -5
  16. package/dist/host/guides/codec.md +18 -3
  17. package/dist/host/guides/contract.md +23 -44
  18. package/dist/host/guides/csv.md +86 -93
  19. package/dist/host/guides/database.md +0 -4
  20. package/dist/host/guides/emitter.md +0 -2
  21. package/dist/host/guides/form.md +26 -47
  22. package/dist/host/guides/html.md +3 -7
  23. package/dist/host/guides/indexeddb.md +28 -32
  24. package/dist/host/guides/jsonrpc.md +187 -0
  25. package/dist/host/guides/markdown.md +132 -141
  26. package/dist/host/guides/msg.md +47 -63
  27. package/dist/host/guides/ndjson.md +0 -4
  28. package/dist/host/guides/pool.md +0 -4
  29. package/dist/host/guides/process.md +71 -79
  30. package/dist/host/guides/reason.md +30 -36
  31. package/dist/host/guides/router.md +11 -18
  32. package/dist/host/guides/scaffold.md +147 -137
  33. package/dist/host/guides/sqlite.md +0 -4
  34. package/dist/host/guides/sse.md +6 -10
  35. package/dist/host/guides/table.md +481 -493
  36. package/dist/host/guides/template.md +0 -4
  37. package/dist/host/guides/test.md +46 -66
  38. package/dist/host/guides/timeout.md +0 -6
  39. package/dist/host/guides/tool.md +2 -6
  40. package/dist/host/guides/websocket.md +0 -4
  41. package/dist/host/manifest.json +100 -428
  42. package/dist/host/tests/setupPolicy.ts +18 -6
  43. package/dist/src/core/index.cjs +171 -122
  44. package/dist/src/core/index.cjs.map +1 -1
  45. package/dist/src/core/index.d.cts +236 -213
  46. package/dist/src/core/index.d.ts +236 -213
  47. package/dist/src/core/index.js +159 -111
  48. package/dist/src/core/index.js.map +1 -1
  49. package/dist/src/server/index.cjs +62 -39
  50. package/dist/src/server/index.cjs.map +1 -1
  51. package/dist/src/server/index.d.cts +59 -54
  52. package/dist/src/server/index.d.ts +59 -54
  53. package/dist/src/server/index.js +63 -40
  54. package/dist/src/server/index.js.map +1 -1
  55. package/package.json +9 -9
@@ -6,7 +6,7 @@
6
6
  > streaming, and export operations.
7
7
 
8
8
  Parse once, then treat every read as a projection of the parsed table.
9
- `parseCSV` runs a tokenizer phase — `readRecords`, a character scanner
9
+ `parseCSV` runs a tokenizer phase — `scanRecords`, a character scanner
10
10
  honoring quoting, escaping, and CRLF, LF, and CR line endings — then a
11
11
  table-building phase of header mapping, ragged-row handling, and optional
12
12
  whole-column type inference, and returns a `CSVParseResult` pairing the table
@@ -41,13 +41,9 @@ The full parse/render/export shape, from [`types.ts`](../src/core/types.ts). An
41
41
  interface's call-signature members are documented under
42
42
  [`## Methods`](#methods).
43
43
 
44
- A `Shape` cell holds an interface's data members as bare names in braces, `?`
45
- marking an optional member and `plus` introducing its call-signature members,
46
- and a type alias's own type literal with a union's arms escaped as `\|`.
47
-
48
44
  | Name | Kind | Signature | Summary |
49
45
  | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50
- | `Row` | type | `Record<string, unknown>` | Represents a CSV row — a plain record of column values keyed by column name. |
46
+ | `CSVRow` | type | `Record<string, unknown>` | Represents a CSV row — a plain record of column values keyed by column name. |
51
47
  | `CSVTable` | interface | `{ columns, rows }` | Represents a parsed CSV table — the typed rows plus the column order they were parsed (or declared) in. |
52
48
  | `RawField` | interface | `{ value, quoted }` | Represents one raw parsed field — the value exactly as it appeared in a record, before type inference or column mapping, plus whether it was quoted in the source. |
53
49
  | `Position` | interface | `{ offset, line, column }` | Represents a cursor position in a parsed source text — relative to the input after byte-order-mark removal. |
@@ -55,7 +51,7 @@ and a type alias's own type literal with a union's arms escaped as `\|`.
55
51
  | `FieldScan` | interface | `{ field, next, errors }` | Represents one scanned field — a single `RawField` the tokenizer produced, the `Position` immediately after it, and any malformations found while scanning it. |
56
52
  | `RecordScan` | interface | `{ record, next, errors }` | Represents one scanned record — a single `RawRecord` the tokenizer produced, the `Position` immediately after it, and any malformations found while scanning it. |
57
53
  | `HeaderResult` | interface | `{ columns, body, errors }` | Represents the result of resolving a header record — the disambiguated column names, the remaining body records, and any header-related errors. |
58
- | `RowResult` | interface | `{ row?, error? }` | Represents the result of building one `RawRecord` into a typed `Row` — the row, the error that excluded it, or both when `ParseOptions.ragged` is `'collect'`. |
54
+ | `RowResult` | interface | `{ row?, error? }` | Represents the result of building one `RawRecord` into a typed `CSVRow` — the row, the error that excluded it, or both when `ParseOptions.ragged` is `'collect'`. |
59
55
  | `RecordsResult` | interface | `{ records, errors }` | Represents the result of the record-splitting phase — every `RawRecord` the tokenizer produced plus any `CSVError`s collected along the way. |
60
56
  | `CSVParseResult` | interface | `{ table, errors }` | Represents the result of a full parse — the assembled `CSVTable` plus any `CSVError`s collected along the way. |
61
57
  | `EscapeStyle` | type | `'double' \| 'backslash'` | Names how an embedded quote character is escaped inside a quoted field. |
@@ -88,23 +84,20 @@ into a result's `errors` unless `strict` is set.
88
84
  Centralized, frozen data the parser/renderer draw their defaults and
89
85
  canonical patterns from, from [`constants.ts`](../src/core/constants.ts).
90
86
 
91
- A `Shape` cell holds the constant's declared type.
92
-
93
- | Name | Kind | Signature | Summary |
94
- | -------------------------- | ----- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
95
- | `BOM` | const | `"\uFEFF"` | Names the UTF-8 byte-order-mark character, `'\uFEFF'`, prepended when `RenderOptions.bom` is `true`. |
96
- | `DEFAULT_PARSE_OPTIONS` | const | `Required<Omit<ParseOptions, 'comment'>>` | Holds the resolved default `ParseOptions` (everything but `comment`, which has no default) — what `parseCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', header: true, blanks: true, trim: false, ragged: 'collect', infer: false, limit: 0, strict: false }`. |
97
- | `DEFAULT_RENDER_OPTIONS` | const | `Required<Omit<RenderOptions, 'columns'>>` | Holds the resolved default `RenderOptions` (everything but `columns`, which has no default) — what `renderCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', newline: '\r\n', header: true, quotes: 'minimal', blank: '', sanitize: true, bom: false }`. |
98
- | `SANITIZE_PREFIXES` | const | `ReadonlySet<string>` | Lists the leading characters the OWASP CSV-injection guard treats as formula-triggering — a field starting with any of these is prefixed with a protective `'` when `RenderOptions.sanitize` is `true`. |
99
- | `POSITIONAL_COLUMN_PREFIX` | const | `"column"` | Names the prefix used for positional columns (`column1`, `column2`, …) when `ParseOptions.header` is `false`, or a header field is empty — 1-based, `'column'`. |
100
- | `SANITIZE_ESCAPE` | const | `"'"` | Names the protective prefix `sanitizeField` prepends to a field starting with a formula-triggering character (the OWASP CSV-injection guidance), `"'"`. |
101
- | `SUFFIX_SEPARATOR` | const | `"_"` | Names the separator between a disambiguated column name and its collision counter (`name` → `name_2`, `name_3`, …) — see `uniqueName`, `'_'`. |
102
- | `INTEGER_PATTERN` | const | `RegExp` | Matches a canonical integer only — an optional leading `-`, no leading zeros (except the bare digit `0`), digits only. No `+` sign, no whitespace. |
103
- | `REAL_PATTERN` | const | `RegExp` | Matches a canonical decimal only — an optional leading `-`, an integer part with no leading zeros (except the bare digit `0`), an optional `.` followed by at least one digit. No scientific notation, no `NaN` / `Infinity`, no decimal comma, no trailing dot. |
104
- | `NUMERIC_PATTERN` | const | `RegExp` | Matches what the renderer treats as a plain number for the `'nonnumeric'` `QuoteStyle` and the sanitize `+` / `-` exemption — like `REAL_PATTERN` but also allowing a leading `+`. |
105
- | `BOOLEAN_TRUE` | const | `"true"` | Names the canonical serialized form of the boolean `true` — the string `'true'`. |
106
- | `BOOLEAN_FALSE` | const | `"false"` | Names the canonical serialized form of the boolean `false` — the string `'false'`. |
107
- | `MAX_ERRORS` | const | `100` | Sets the maximum number of `CSVError`s collected into a parse result, `100` — once reached, error collection stops (earlier records already parsed are kept, later malformations are silently no longer recorded). |
87
+ | Name | Kind | Signature | Summary |
88
+ | --------------------------- | ----- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
89
+ | `DEFAULT_PARSE_OPTIONS` | const | `Required<Omit<ParseOptions, 'comment'>>` | Holds the resolved default `ParseOptions` (everything but `comment`, which has no default) — what `parseCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', header: true, blanks: true, trim: false, ragged: 'collect', infer: false, limit: 0, strict: false }`. |
90
+ | `DEFAULT_RENDER_OPTIONS` | const | `Required<Omit<RenderOptions, 'columns'>>` | Holds the resolved default `RenderOptions` (everything but `columns`, which has no default) — what `renderCSV` uses for any option left unspecified: `{ delimiter: ',', quote: '"', escape: 'double', newline: '\r\n', header: true, quotes: 'minimal', blank: '', sanitize: true, bom: false }`. |
91
+ | `SANITIZE_PREFIXES` | const | `ReadonlySet<string>` | Lists the leading characters the OWASP CSV-injection guard treats as formula-triggering — a field starting with any of these is prefixed with a protective `'` when `RenderOptions.sanitize` is `true`. |
92
+ | `POSITIONAL_COLUMN_PREFIX` | const | `"column"` | Names the prefix used for positional columns (`column1`, `column2`, …) when `ParseOptions.header` is `false`, or a header field is empty — 1-based, `'column'`. |
93
+ | `SANITIZE_ESCAPE` | const | `"'"` | Names the protective prefix `sanitizeField` prepends to a field starting with a formula-triggering character (the OWASP CSV-injection guidance), `"'"`. |
94
+ | `SUFFIX_SEPARATOR` | const | `"_"` | Names the separator between a disambiguated column name and its collision counter (`name` → `name_2`, `name_3`, …) — see `uniqueName`, `'_'`. |
95
+ | `CANONICAL_INTEGER_PATTERN` | const | `RegExp` | Matches a canonical integer only — an optional leading `-`, no leading zeros (except the bare digit `0`), digits only. No `+` sign, no whitespace. |
96
+ | `REAL_PATTERN` | const | `RegExp` | Matches a canonical decimal only — an optional leading `-`, an integer part with no leading zeros (except the bare digit `0`), an optional `.` followed by at least one digit. No scientific notation, no `NaN` / `Infinity`, no decimal comma, no trailing dot. |
97
+ | `NUMERIC_PATTERN` | const | `RegExp` | Matches what the renderer treats as a plain number for the `'nonnumeric'` `QuoteStyle` and the sanitize `+` / `-` exemption — like `REAL_PATTERN` but also allowing a leading `+`. |
98
+ | `BOOLEAN_TRUE` | const | `"true"` | Names the canonical serialized form of the boolean `true` — the string `'true'`. |
99
+ | `BOOLEAN_FALSE` | const | `"false"` | Names the canonical serialized form of the boolean `false` — the string `'false'`. |
100
+ | `MAX_ERRORS` | const | `100` | Sets the maximum number of `CSVError`s collected into a parse result, `100` — once reached, error collection stops (earlier records already parsed are kept, later malformations are silently no longer recorded). |
108
101
 
109
102
  ### Helpers
110
103
 
@@ -114,35 +107,35 @@ hand-written tokenizer and table builders `parsers.ts` composes, and the
114
107
  rendering projections callers reach for directly. Every function is
115
108
  unit-testable in isolation.
116
109
 
117
- | Name | Kind | Signature | Summary |
118
- | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
119
- | `assertValidSeparators` | function | `(delimiter: string, quote: string) => void` | Validates a delimiter / quote pair shared by both `resolveParseOptions` and `resolveRenderOptions` — each must be exactly one character, they must differ, and neither may be CR, LF, or the BOM character. |
120
- | `resolveParseOptions` | function | `(options?: ParseOptions) => ResolvedParseOptions` | Merges `options` over `DEFAULT_PARSE_OPTIONS` into a fully-resolved parse configuration. |
121
- | `resolveRenderOptions` | function | `(options?: RenderOptions) => ResolvedRenderOptions` | Merges `options` over `DEFAULT_RENDER_OPTIONS` into a fully-resolved render configuration. |
122
- | `uniqueName` | function | `(name: string, taken: ReadonlySet<string>) => string` | Disambiguates a single column name against the names already taken — the collision leaf `uniqueColumns` composes over an entire header. |
123
- | `uniqueColumns` | function | `(names: readonly string[]) => readonly string[]` | Disambiguates a header's column names deterministically — an empty (or whitespace-only) name becomes positional, and a name that repeats an earlier kept name is suffixed `_2`, `_3`, … until unique. |
124
- | `sanitizeField` | function | `(field: string) => string` | Guards a field against CSV/spreadsheet formula injection (the OWASP CSV-injection guidance) — a field starting with a formula-triggering character is prefixed with a protective `SANITIZE_ESCAPE`. |
125
- | `serializeCell` | function | `(value: unknown, blank: string) => string` | Serializes one cell value to its rendered text — the renderer's stringify leaf, applied before sanitize/quote. |
126
- | `deriveColumns` | function | `(rows: readonly Row[]) => readonly string[]` | Derives a column order from a plain row list — the first-seen union of every row's keys, in encounter order. |
127
- | `needsQuote` | function | `(field: string, options: ResolvedRenderOptions) => boolean` | Checks `field` against the correctness floor every `QuoteStyle` policy respects — a field containing the delimiter, the quote character, CR, or LF must ALWAYS be quoted regardless of policy. |
128
- | `wrapQuoted` | function | `(field: string, options: ResolvedRenderOptions) => string` | Wraps `field` in quotes, escaping per `options.escape` — the shared quote-and-escape step every quoting policy applies once it decides `field` needs quoting; it IS the `'always'` `QuoteStyle` as well (every field quoted unconditionally). |
129
- | `quoteMinimal` | function | `(field: string, options: ResolvedRenderOptions) => string` | Implements the `'minimal'` `QuoteStyle` — quotes a field only when `needsQuote` requires it. |
130
- | `quoteNonnumeric` | function | `(field: string, options: ResolvedRenderOptions) => string` | Implements the `'nonnumeric'` `QuoteStyle` — quotes every field whose value is not a plain number (or that `needsQuote` requires regardless). |
131
- | `renderRecord` | function | `(row: Row, columns: readonly string[], options: ResolvedRenderOptions, quote: (field: string, options: ResolvedRenderOptions) => string) => string` | Renders one row to one delimited line — serializes every column's cell, optionally sanitizes it, then applies the given quoting policy. |
132
- | `quoteStyleToPolicy` | function | `(quotes: ResolvedRenderOptions['quotes']) => (field: string, options: ResolvedRenderOptions) => string` | Selects the quoting-policy function for a resolved `options.quotes`. |
133
- | `isRowList` | function | `(source: CSVTable \| readonly Row[]) => source is readonly Row[]` | Narrows a `CSVTable \| readonly Row[]` union to its row-list member. |
134
- | `renderCSV` | function | `(input: CSVTable \| readonly Row[], options?: RenderOptions) => string` | Renders a `CSVTable` (or a plain row list) to CSV text. |
135
- | `advancePosition` | function | `(position: Position, count?: number) => Position` | Advances a `Position` by `count` NON-line-break characters. |
136
- | `isBreakChar` | function | `(char: string) => boolean` | Checks whether `char` starts a record separator (CR or LF). |
137
- | `scanBreak` | function | `(source: string, position: Position) => Position \| undefined` | Consumes exactly one line break (CRLF, bare LF, or bare CR) at `position` — a CRLF pair counts as ONE break. |
138
- | `scanComment` | function | `(source: string, position: Position, options: ResolvedParseOptions) => Position \| undefined` | Consumes a comment line at `position`, when `options.comment` names one starting there — through the end of that line INCLUDING its break (or end-of-input). |
139
- | `scanUnquoted` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one unquoted field starting at `position` — content runs until the delimiter, a line break, or end-of-input. |
140
- | `scanQuoted` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one quoted field starting at `position` — `position` must be AT the opening quote character. |
141
- | `scanField` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one field at `position` — dispatches to `scanQuoted` when the character there is `options.quote`, else `scanUnquoted`. |
142
- | `scanRecord` | function | `(source: string, position: Position, options: ResolvedParseOptions) => RecordScan` | Scans one full record at `position` — fields separated by `options.delimiter`, ending at a break (consumed through `scanBreak`) or end-of-input. |
143
- | `readRecords` | function | `(input: string, options?: ParseOptions) => RecordsResult` | Splits `input` into raw, un-mapped `RawRecord`s — the tokenizer phase beneath `parseCSV`. |
144
- | `deriveHeader` | function | `(records: readonly RawRecord[], options: ResolvedParseOptions) => HeaderResult` | Resolves a table's header from its raw records — disambiguates the first record's names when `options.header` is `true`, or generates positional names sized to the widest record otherwise. |
145
- | `buildRow` | function | `(record: RawRecord, columns: readonly string[], options: ResolvedParseOptions) => RowResult` | Builds one `RawRecord` into one null-prototype `Row`, padding or truncating to `columns.length` per `options.ragged`. |
110
+ | Name | Kind | Signature | Summary |
111
+ | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
112
+ | `assertValidSeparators` | function | `(delimiter: string, quote: string) => void` | Validates a delimiter / quote pair shared by both `resolveParseOptions` and `resolveRenderOptions` — each must be exactly one character, they must differ, and neither may be CR, LF, or the BOM character. |
113
+ | `resolveParseOptions` | function | `(options?: ParseOptions) => ResolvedParseOptions` | Merges `options` over `DEFAULT_PARSE_OPTIONS` into a fully-resolved parse configuration. |
114
+ | `resolveRenderOptions` | function | `(options?: RenderOptions) => ResolvedRenderOptions` | Merges `options` over `DEFAULT_RENDER_OPTIONS` into a fully-resolved render configuration. |
115
+ | `uniqueName` | function | `(name: string, taken: ReadonlySet<string>) => string` | Disambiguates a single column name against the names already taken — the collision leaf `uniqueColumns` composes over an entire header. |
116
+ | `uniqueColumns` | function | `(names: readonly string[]) => readonly string[]` | Disambiguates a header's column names deterministically — an empty (or whitespace-only) name becomes positional, and a name that repeats an earlier kept name is suffixed `_2`, `_3`, … until unique. |
117
+ | `sanitizeField` | function | `(field: string) => string` | Guards a field against CSV/spreadsheet formula injection (the OWASP CSV-injection guidance) — a field starting with a formula-triggering character is prefixed with a protective `SANITIZE_ESCAPE`. |
118
+ | `serializeCell` | function | `(value: unknown, blank: string) => string` | Serializes one cell value to its rendered text — the renderer's stringify leaf, applied before sanitize/quote. |
119
+ | `deriveColumns` | function | `(rows: readonly CSVRow[]) => readonly string[]` | Derives a column order from a plain row list — the first-seen union of every row's keys, in encounter order. |
120
+ | `needsQuote` | function | `(field: string, options: ResolvedRenderOptions) => boolean` | Checks `field` against the correctness floor every `QuoteStyle` policy respects — a field containing the delimiter, the quote character, CR, or LF must ALWAYS be quoted regardless of policy. |
121
+ | `wrapQuoted` | function | `(field: string, options: ResolvedRenderOptions) => string` | Wraps `field` in quotes, escaping per `options.escape` — the shared quote-and-escape step every quoting policy applies once it decides `field` needs quoting; it IS the `'always'` `QuoteStyle` as well (every field quoted unconditionally). |
122
+ | `quoteMinimal` | function | `(field: string, options: ResolvedRenderOptions) => string` | Implements the `'minimal'` `QuoteStyle` — quotes a field only when `needsQuote` requires it. |
123
+ | `quoteNonnumeric` | function | `(field: string, options: ResolvedRenderOptions) => string` | Implements the `'nonnumeric'` `QuoteStyle` — quotes every field whose value is not a plain number (or that `needsQuote` requires regardless). |
124
+ | `renderRecord` | function | `(row: CSVRow, columns: readonly string[], options: ResolvedRenderOptions, quote: (field: string, options: ResolvedRenderOptions) => string) => string` | Renders one row to one delimited line — serializes every column's cell, optionally sanitizes it, then applies the given quoting policy. |
125
+ | `quoteStyleToPolicy` | function | `(quotes: ResolvedRenderOptions['quotes']) => (field: string, options: ResolvedRenderOptions) => string` | Selects the quoting-policy function for a resolved `options.quotes`. |
126
+ | `isRowList` | function | `(source: CSVTable \| readonly CSVRow[]) => source is readonly CSVRow[]` | Narrows a `CSVTable \| readonly CSVRow[]` union to its row-list member. |
127
+ | `renderCSV` | function | `(input: CSVTable \| readonly CSVRow[], options?: RenderOptions) => string` | Renders a `CSVTable` (or a plain row list) to CSV text. |
128
+ | `advancePosition` | function | `(position: Position, count?: number) => Position` | Advances a `Position` by `count` NON-line-break characters. |
129
+ | `isBreakChar` | function | `(char: string) => boolean` | Checks whether `char` starts a record separator (CR or LF). |
130
+ | `scanBreak` | function | `(source: string, position: Position) => Position \| undefined` | Consumes exactly one line break (CRLF, bare LF, or bare CR) at `position` — a CRLF pair counts as ONE break. |
131
+ | `scanCommentLine` | function | `(source: string, position: Position, options: ResolvedParseOptions) => Position \| undefined` | Consumes a comment line at `position`, when `options.comment` names one starting there — through the end of that line INCLUDING its break (or end-of-input). |
132
+ | `scanUnquoted` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one unquoted field starting at `position` — content runs until the delimiter, a line break, or end-of-input. |
133
+ | `scanQuoted` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one quoted field starting at `position` — `position` must be AT the opening quote character. |
134
+ | `scanField` | function | `(source: string, position: Position, options: ResolvedParseOptions) => FieldScan` | Scans one field at `position` — dispatches to `scanQuoted` when the character there is `options.quote`, else `scanUnquoted`. |
135
+ | `scanRecord` | function | `(source: string, position: Position, options: ResolvedParseOptions) => RecordScan` | Scans one full record at `position` — fields separated by `options.delimiter`, ending at a break (consumed through `scanBreak`) or end-of-input. |
136
+ | `scanRecords` | function | `(input: string, options?: ParseOptions) => RecordsResult` | Splits `input` into raw, un-mapped `RawRecord`s — the tokenizer phase beneath `parseCSV`. |
137
+ | `deriveHeader` | function | `(records: readonly RawRecord[], options: ResolvedParseOptions) => HeaderResult` | Resolves a table's header from its raw records — disambiguates the first record's names when `options.header` is `true`, or generates positional names sized to the widest record otherwise. |
138
+ | `buildRow` | function | `(record: RawRecord, columns: readonly string[], options: ResolvedParseOptions) => RowResult` | Builds one `RawRecord` into one null-prototype `CSVRow`, padding or truncating to `columns.length` per `options.ragged`. |
146
139
 
147
140
  ### Inferers
148
141
 
@@ -151,11 +144,11 @@ Whole-column type inference from
151
144
  holds, rules which `ColumnType` it carries, and applies that ruling cell by
152
145
  cell.
153
146
 
154
- | Name | Kind | Signature | Summary |
155
- | ----------------- | -------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
- | `inferColumnType` | function | `(values: readonly string[]) => ColumnType` | Infers a whole column's `ColumnType` conservatively from its raw string values — never `'json'` or `'blob'` (those require an explicit `Columns` declaration). Empty-string cells are ignored entirely (they neither confirm nor demote a type); a column with no non-empty cells is `'text'`. |
157
- | `coerceInferred` | function | `(value: string, type: ColumnType) => unknown` | Coerces one string cell to `type`'s typed representation — the exhaustive per-cell dispatch `inferRows` applies once a column's type is known. |
158
- | `inferRows` | function | `(rows: readonly Row[], columns: readonly string[]) => readonly Row[]` | Applies whole-column type inference to a built row set — per column, infers its `ColumnType` from its string cells, then coerces every cell of that type through `coerceInferred`. |
147
+ | Name | Kind | Signature | Summary |
148
+ | ----------------- | -------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
149
+ | `inferColumnType` | function | `(values: readonly string[]) => ColumnType` | Infers a whole column's `ColumnType` conservatively from its raw string values — never `'json'` or `'blob'` (those require an explicit `Columns` declaration). Empty-string cells are ignored entirely (they neither confirm nor demote a type); a column with no non-empty cells is `'text'`. |
150
+ | `coerceInferred` | function | `(value: string, type: ColumnType) => unknown` | Coerces one string cell to `type`'s typed representation — the exhaustive per-cell dispatch `inferRows` applies once a column's type is known. |
151
+ | `inferRows` | function | `(rows: readonly CSVRow[], columns: readonly string[]) => readonly CSVRow[]` | Applies whole-column type inference to a built row set — per column, infers its `ColumnType` from its string cells, then coerces every cell of that type through `coerceInferred`. |
159
152
 
160
153
  ### Parsers
161
154
 
@@ -164,12 +157,12 @@ entry point, which composes the `helpers.ts` tokenizer, the `helpers.ts` table
164
157
  builders, and the `inferers.ts` column inference into a `CSVParseResult`, plus
165
158
  the flat cell coercers that inference dispatches to.
166
159
 
167
- | Name | Kind | Signature | Summary |
168
- | -------------- | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
169
- | `parseCSV` | function | `(input: string, options?: ParseOptions) => CSVParseResult` | Parses `input` into a typed `CSVParseResult` — header mapping, ragged-row handling, and optional type inference on top of `readRecords`, `deriveHeader`, `buildRow`, and `inferRows`. |
170
- | `parseInteger` | function | `(value: string) => number \| undefined` | Parses a raw cell string into a canonical integer — `undefined` for anything else (leading zeros, decimals, out-of-safe-range magnitude, non-numeric text). |
171
- | `parseReal` | function | `(value: string) => number \| undefined` | Parses a raw cell string into a canonical decimal (or integer) — `undefined` for anything else. |
172
- | `parseBoolean` | function | `(value: string) => boolean \| undefined` | Parses a raw cell string into a strict boolean — `undefined` for anything other than the exact canonical forms. |
160
+ | Name | Kind | Signature | Summary |
161
+ | ------------------ | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
162
+ | `parseCSV` | function | `(input: string, options?: ParseOptions) => CSVParseResult` | Parses `input` into a typed `CSVParseResult` — header mapping, ragged-row handling, and optional type inference on top of `scanRecords`, `deriveHeader`, `buildRow`, and `inferRows`. |
163
+ | `parseIntegerCell` | function | `(value: string) => number \| undefined` | Parses a raw cell string into a canonical integer — `undefined` for anything else (leading zeros, decimals, out-of-safe-range magnitude, non-numeric text). |
164
+ | `parseReal` | function | `(value: string) => number \| undefined` | Parses a raw cell string into a canonical decimal (or integer) — `undefined` for anything else. |
165
+ | `parseBooleanCell` | function | `(value: string) => boolean \| undefined` | Parses a raw cell string into a strict boolean — `undefined` for anything other than the exact canonical forms. |
173
166
 
174
167
  ### Shapers
175
168
 
@@ -189,12 +182,10 @@ whole `Columns` map of them from a table's own cell values.
189
182
  Guards from [`validators.ts`](../src/core/validators.ts) — total, never
190
183
  throw, return `false` for any off-shape input.
191
184
 
192
- In a guard table a `Shape` cell holds the type the guard narrows to.
193
-
194
- | Name | Kind | Signature | Summary |
195
- | -------------- | ----- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
196
- | `isCSVTable` | const | `Guard<CSVTable>` | Determines whether an arbitrary value is a valid `CSVTable` — an array of column names plus an array of `Row`s. |
197
- | `isColumnType` | const | `Guard<ColumnType>` | Determines whether a value is a valid `ColumnType` literal. |
185
+ | Name | Kind | Signature | Summary |
186
+ | -------------- | ----- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
187
+ | `isCSVTable` | const | `Guard<CSVTable>` | Determines whether an arbitrary value is a valid `CSVTable` — an array of column names plus an array of `CSVRow`s. |
188
+ | `isColumnType` | const | `Guard<ColumnType>` | Determines whether a value is a valid `ColumnType` literal. |
198
189
 
199
190
  ### Classes
200
191
 
@@ -218,10 +209,10 @@ never mutates the stored table, it returns a new `CSV`. See
218
209
 
219
210
  From [`factories.ts`](../src/core/factories.ts).
220
211
 
221
- | Name | Kind | Signature | Summary |
222
- | --------------------- | -------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
223
- | `createCSV` | function | `(input: string \| CSVTable, options?: ParseOptions) => CSVInterface` | Creates a working `CSVInterface` from a CSV string or an already-parsed `CSVTable`. |
224
- | `createTableContract` | function | `(columns: Columns) => ContractInterface<Row>` | Compiles a `Columns` map into a `ContractInterface` for a `Row` — a guard, coercing parser, JSON Schema, and seeded generator from one shape declaration. |
212
+ | Name | Kind | Signature | Summary |
213
+ | --------------------- | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
214
+ | `createCSV` | function | `(input: string \| CSVTable, options?: ParseOptions) => CSVInterface` | Creates a working `CSVInterface` from a CSV string or an already-parsed `CSVTable`. |
215
+ | `createTableContract` | function | `(columns: Columns) => ContractInterface<CSVRow>` | Compiles a `Columns` map into a `ContractInterface` for a `CSVRow` — a guard, coercing parser, JSON Schema, and seeded generator from one shape declaration. |
225
216
 
226
217
  ## Methods
227
218
 
@@ -229,29 +220,31 @@ The public methods of `CSVInterface`, keyed by its backticked name.
229
220
 
230
221
  #### `CSVInterface`
231
222
 
232
- | Method | Returns | Summary |
233
- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
234
- | `find` | `Row \| undefined` | Finds the first row matching `predicate`, called with each row and its index in table order. |
235
- | `filter` | `readonly Row[]` | Collects every row matching `predicate`, called with each row and its index in table order. |
236
- | `map` | `CSVInterface` | Rewrites every row (copy-on-write) and returns a new `CSVInterface`, never mutating this one. |
237
- | `reduce` | `T` | Folds the rows, in table order, into an accumulator through `callback`. |
238
- | `stream` | `ReadableStream<Row>` | Returns a web-standard `ReadableStream` over the table's rows (source order) — a lazy, pull-based, backpressure-respecting source that enqueues one row per `pull`. A fresh, independently-replayable stream every call; never mutates the table. |
239
- | `toJSON` | `CSVTable` | Returns the stored `CSVTable` — the JSON-serializable projection. |
240
- | `export` | `TableExport` | Produces a portable `TableExport` for moving this CSV's schema elsewhere. |
223
+ | Method | Returns | Summary |
224
+ | -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
225
+ | `find` | `CSVRow \| undefined` | Finds the first row matching `predicate`, called with each row and its index in table order. |
226
+ | `filter` | `readonly CSVRow[]` | Collects every row matching `predicate`, called with each row and its index in table order. |
227
+ | `map` | `CSVInterface` | Rewrites every row (copy-on-write) and returns a new `CSVInterface`, never mutating this one. |
228
+ | `reduce` | `T` | Folds the rows, in table order, into an accumulator through `callback`. |
229
+ | `stream` | `ReadableStream<CSVRow>` | Returns a web-standard `ReadableStream` over the table's rows (source order) — a lazy, pull-based, backpressure-respecting source that enqueues one row per `pull`. A fresh, independently-replayable stream every call; never mutates the table. |
230
+ | `toJSON` | `CSVTable` | Returns the stored `CSVTable` — the JSON-serializable projection. |
231
+ | `export` | `TableExport` | Produces a portable `TableExport` for moving this CSV's schema elsewhere. |
241
232
 
242
233
  ## RFC 4180 and dialects
243
234
 
244
- `parseCSV` / `readRecords` honor the RFC 4180 grammar — quoted fields, an
235
+ `parseCSV` / `scanRecords` honor the RFC 4180 grammar — quoted fields, an
245
236
  embedded delimiter/quote/newline inside a quoted field, and doubled quotes as
246
237
  the escape convention — while accepting the common real-world dialect
247
238
  variants: `\r\n`, bare `\n`, and bare `\r` line endings are all recognized (a
248
239
  CRLF pair counts as one line break), and a mix of them within the same
249
- document is handled record-by-record. A single leading UTF-8 byte-order-mark
250
- is always stripped before scanning, regardless of `options`. `delimiter`,
240
+ document is handled record-by-record. A single leading UTF-8 byte-order-mark,
241
+ the `BOM` constant `@orkestrel/codec` exports, is always stripped before
242
+ scanning, regardless of `options`, and `renderCSV` prepends the same `BOM`
243
+ when `RenderOptions.bom` is `true`. `delimiter`,
251
244
  `quote`, and `escape` (`'double'` doubles an embedded quote, `'backslash'`
252
245
  prefixes it) are all caller-configurable knobs, validated by
253
246
  `assertValidSeparators` (each exactly one character, distinct from each
254
- other, and never CR/LF/BOM). Tab-separated output is a `renderCSV` dialect,
247
+ other, and never CR, LF, or `BOM`). Tab-separated output is a `renderCSV` dialect,
255
248
  not a separate parser: call `renderCSV` with `delimiter: '\t'`.
256
249
 
257
250
  ## Total parsing and the error model
@@ -308,11 +301,11 @@ as a `string` unless a caller opts in. When enabled, `inferColumnType`
308
301
  decides a type for a WHOLE column at once (never per-cell), so a column with
309
302
  even one non-conforming value stays `'text'` entirely. Several common traps
310
303
  stay text deliberately: a leading-zero numeral (`'007'`) fails
311
- `INTEGER_PATTERN` (which permits no leading zeros beyond a bare `0`) and so
304
+ `CANONICAL_INTEGER_PATTERN` (which permits no leading zeros beyond a bare `0`) and so
312
305
  never infers as a number — a phone number or zip code is preserved verbatim;
313
306
  scientific notation (`'1e5'`) and `NaN`/`Infinity` are not matched by either
314
307
  numeric pattern and stay text; a value outside `Number.isSafeInteger` range
315
- stays text even though its digits match `INTEGER_PATTERN`; a date string and
308
+ stays text even though its digits match `CANONICAL_INTEGER_PATTERN`; a date string and
316
309
  a decimal-comma number (`'3,14'`) both fail both numeric patterns and stay
317
310
  text. The two numeric outcomes split on whether any cell carries a fractional
318
311
  part: all-integer cells infer `'integer'`, any decimal cell present promotes
@@ -321,7 +314,7 @@ the WHOLE column to `'real'`. `inferColumnType` never infers `'json'` or
321
314
 
322
315
  ## Database interop without dependency
323
316
 
324
- A `Row` is `Record<string, unknown>` — a plain record any database `Table`'s
317
+ A `CSVRow` is `Record<string, unknown>` — a plain record any database `Table`'s
325
318
  `set`/`add` primitives can accept directly, with no adapter layer and no
326
319
  runtime dependency on `@orkestrel/database` (this package never imports it).
327
320
  `CSVInterface.toJSON` returns the stored `CSVTable` — the JSON-serializable
@@ -336,7 +329,7 @@ no import crosses the package boundary in either direction.
336
329
 
337
330
  ## Streaming boundary
338
331
 
339
- `CSVInterface.stream` returns a web-standard `ReadableStream<Row>` — a fresh,
332
+ `CSVInterface.stream` returns a web-standard `ReadableStream<CSVRow>` — a fresh,
340
333
  pull-based stream every call, enqueuing one already-parsed row per `pull` so
341
334
  a slow consumer's backpressure is respected. This is a POST-PARSE row
342
335
  stream, not chunked ingestion: the entire CSV text is parsed up front (by
@@ -359,8 +352,8 @@ import { createCSV } from '@orkestrel/csv'
359
352
  const csv = createCSV('name,age\nAda,36\nGrace,85', { infer: true })
360
353
  csv.table // { columns: ['name', 'age'], rows: [{ name: 'Ada', age: 36 }, { name: 'Grace', age: 85 }] }
361
354
 
362
- const ada = csv.find((row) => row.name === 'Ada') // Row | undefined
363
- const adults = csv.filter((row) => Number(row.age) >= 40) // readonly Row[]
355
+ const ada = csv.find((row) => row.name === 'Ada') // CSVRow | undefined
356
+ const adults = csv.filter((row) => Number(row.age) >= 40) // readonly CSVRow[]
364
357
  ```
365
358
 
366
359
  ### Rewrite with `map`, then render back
@@ -251,8 +251,6 @@ Pure helpers behind the query engine's pattern matching.
251
251
 
252
252
  ### Constants
253
253
 
254
- A `Shape` cell holds the constant's declared type.
255
-
256
254
  | Name | Kind | Signature | Summary |
257
255
  | -------------------------- | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
258
256
  | `DEFAULT_PRIMARY` | const | `"id"` | Supplies the primary-key column, `'id'`, assumed when `PrimaryMap` does not name one. |
@@ -263,8 +261,6 @@ A `Shape` cell holds the constant's declared type.
263
261
 
264
262
  ### Types
265
263
 
266
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
267
-
268
264
  | Name | Kind | Signature | Summary |
269
265
  | -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
270
266
  | `Key` | type | `string \| number` | Represents a primary key — the value identifying a row within its table. |
@@ -64,8 +64,6 @@ The reserved `on` option wires initial listeners at construction; the optional `
64
64
 
65
65
  ### Types
66
66
 
67
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
68
-
69
67
  | Name | Kind | Signature | Summary |
70
68
  | --------------------- | --------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
71
69
  | `EventMap` | type | `Record<string, readonly unknown[]>` | Maps each event name to the argument tuple its listeners receive. |
@@ -49,11 +49,6 @@ The document itself — what a form asks, in the order it asks it. All data, no
49
49
  control's own interface adds its members to `FieldBase`, and the control values themselves are
50
50
  worked through in [Controls](#controls).
51
51
 
52
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
53
- optional member and `plus` introducing its call-signature members, and a type alias's own type
54
- literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`,
55
- with the members it adds after.
56
-
57
52
  | Name | Kind | Signature | Summary |
58
53
  | --------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
59
54
  | `FormSchema` | interface | `{ name?, label?, help?, groups?, fields }` | Describes everything a form asks. |
@@ -80,10 +75,6 @@ with the members it adds after.
80
75
 
81
76
  What a form holds, what its answers must satisfy, and how a failure reports itself.
82
77
 
83
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
84
- optional member and `plus` introducing its call-signature members, and a type alias's own type
85
- literal with a union's arms escaped as `\|`.
86
-
87
78
  | Name | Kind | Signature | Summary |
88
79
  | ------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
89
80
  | `FieldValue` | type | `string \| number \| boolean \| readonly string[]` | Represents every value a field can hold. |
@@ -98,12 +89,6 @@ literal with a union's arms escaped as `\|`.
98
89
 
99
90
  The entity, its factory, its contract, and the error it raises.
100
91
 
101
- A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an
102
- optional member and `plus` introducing its call-signature members, and a type alias's own type
103
- literal with a union's arms escaped as `\|`. A function row's `Shape` cell holds its signature,
104
- and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it
105
- implements, or its constructor signature where it implements none.
106
-
107
92
  | Name | Kind | Signature | Summary |
108
93
  | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
109
94
  | `Form` | class | `new (schema: FormSchema, options?: FormOptions) => FormInterface` | Implements `FormInterface` exactly, over an owned schema, the answers given against it, and the errors they carry. |
@@ -119,8 +104,8 @@ implements, or its constructor signature where it implements none.
119
104
  | `FormErrorCode` | type | `'SCHEMA' \| 'FIELD' \| 'CONTROL' \| 'SETTLED' \| 'ABANDONED' \| 'PENDING'` | Names the machine-readable code a form error carries. |
120
105
  | `isFormError` | function | `(input: unknown) => input is FormError` | Determines whether an unknown value is a form error. |
121
106
 
122
- `FormInterface`'s readonly data members are the names in its `Shape` cell before `plus`, and they
123
- stay here rather than in `## Methods`; the call-signature members after `plus` are documented under
107
+ `FormInterface`'s readonly data members are the names its `Signature` cell lists without
108
+ parentheses, and they stay here rather than in `## Methods`; the members it lists with parentheses are documented under
124
109
  [Methods](#methods).
125
110
 
126
111
  ### Constants
@@ -134,8 +119,6 @@ control; `COLOR_PATTERN`, `DATE_PATTERN`, `TIME_PATTERN`, and `DATETIME_PATTERN`
134
119
  [Budgets](#budgets) then works each ceiling through beside the unit it counts, and
135
120
  [Patterns and where trust lives](#patterns-and-where-trust-lives) does the same for `PATTERN_LIMIT`.
136
121
 
137
- A `Shape` cell holds the constant's declared type.
138
-
139
122
  | Name | Kind | Signature | Summary |
140
123
  | ---------------------- | ----- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
141
124
  | `FIELD_CONTROLS` | const | `readonly FieldControl[]` | Lists every field control, in the order declared by the public contract. |
@@ -154,12 +137,7 @@ A `Shape` cell holds the constant's declared type.
154
137
  | `PATTERN_LIMIT` | const | `256` | Caps the accepted source length for an authored regular expression, at 256. |
155
138
  | `FIELD_LIMIT` | const | `512` | Caps the number of fields one schema may declare, at 512. |
156
139
  | `GROUP_LIMIT` | const | `64` | Caps the number of groups one schema may declare, at 64. |
157
- | `CHOICE_LIMIT` | const | `1024` | Caps the number of choices one `select` or `checkbox` field may offer, at 1024. |
158
140
  | `LIST_LIMIT` | const | `1024` | Caps the number of entries one list-valued answer may hold, at 1024. |
159
- | `NAME_LIMIT` | const | `128` | Caps the length, in UTF-16 code units, of a schema, group, or field name, at 128. |
160
- | `STRING_LIMIT` | const | `65536` | Caps the length, in UTF-16 code units, of any single retained string, at 65536. |
161
- | `TEXT_LIMIT` | const | `1048576` | Caps the total length, in UTF-16 code units, of every string one schema retains, at 1048576. |
162
- | `NODE_LIMIT` | const | `16384` | Caps the total number of records, arrays, and leaves one schema retains, at 16384. |
163
141
 
164
142
  ### Guards
165
143
 
@@ -168,8 +146,6 @@ anything off-shape — including an unexpected prototype, a symbol key, or a cyc
168
146
  also refuses a number that is not finite, so `NaN` and `Infinity` are not field values, and
169
147
  `isFormSchema` reads structure alone: domain soundness is `auditSchema`'s question.
170
148
 
171
- In a guard table a `Shape` cell holds the type the guard narrows to.
172
-
173
149
  | Name | Kind | Signature | Summary |
174
150
  | ---------------- | -------- | ------------------------------------------- | -------------------------------------------------------------------------- |
175
151
  | `isFieldControl` | function | `(input: unknown) => input is FieldControl` | Determines whether an unknown value is a declared field control. |
@@ -876,7 +852,8 @@ evaluateField(long, 'aaa', {})
876
852
  `PATTERN_LIMIT` is one of the budgets. The others bound how much a schema and its answers can be, so
877
853
  a document that arrives from a wire cannot cost unbounded memory or unbounded scanning before
878
854
  anything decides to trust it. Every one is exported, so a host can check against the same number the
879
- package checks against.
855
+ package checks against: `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`, `TEXT_LIMIT`, and
856
+ `NODE_LIMIT` from `@orkestrel/contract`, and the rest from this package.
880
857
 
881
858
  | Constant | Value | Unit | Bounds |
882
859
  | -------------- | ------- | ----------------------- | ----------------------------------------- |
@@ -896,19 +873,19 @@ text, and total nodes — `meta` included, because it is retained like everythin
896
873
  human diagnostic per breach, beside `PATTERN_LIMIT`'s. `createForm` throws `SCHEMA` carrying them
897
874
  and `parseForm` refuses the schema, so no over-budget schema is ever held.
898
875
 
899
- **The value door refuses.** `matchesField` checks `STRING_LIMIT` on any string and `LIST_LIMIT` on
900
- any list before it consults the control, so the check happens **before any regular expression sees
901
- the value**. `fill` and a seeded value throw `CONTROL`; `parseValue` and `parseValues` return
902
- `undefined`.
876
+ **The value door refuses.** `matchesField` checks `STRING_LIMIT`, from `@orkestrel/contract`, on
877
+ any string and `LIST_LIMIT` on any list before it consults the control, so the check happens **before
878
+ any regular expression sees the value**. `fill` and a seeded value throw `CONTROL`; `parseValue` and
879
+ `parseValues` return `undefined`.
903
880
 
904
- `STRING_LIMIT` is the one that stands at both: the same ceiling holds a schema's own strings and an
905
- answer's, so no string this package retains is longer than 65536 code units whichever way it
906
- arrived.
881
+ `STRING_LIMIT` is the one that stands at both: the same ceiling holds a
882
+ schema's own strings and an answer's, so no string this package retains is longer than 65536 code
883
+ units whichever way it arrived.
907
884
 
908
885
  The whole-schema ceilings are what make the arithmetic safe. Whatever the per-item limits admit, one
909
886
  audited schema retains at most 1048576 string code units and at most 16384 nodes — roughly two
910
- megabytes of text — so the worst case is `TEXT_LIMIT` and `NODE_LIMIT`, never the product of the
911
- others.
887
+ megabytes of text — so the worst case is `TEXT_LIMIT` and `NODE_LIMIT`, from
888
+ `@orkestrel/contract`, never the product of the others.
912
889
 
913
890
  Regular-expression time, a `custom` validator's own work, and the structural read at the parse door
914
891
  stay unbounded, each for its own reason. Regular-expression **time** is not bounded here, exactly as
@@ -921,14 +898,15 @@ what it does.
921
898
  The structural **read** at the parse door is unbounded for a different reason, and refusing an
922
899
  over-budget schema is where it shows. The budgets bound what a schema may **retain**, and they bound
923
900
  how far the audit **walks** to name a fault: the field pass stops at `FIELD_LIMIT` and the node pass
924
- stops at `NODE_LIMIT`, so a fault beyond either ceiling goes unnamed while the breached ceiling
925
- itself is reported. They do not bound the read that happens before any of that. `parseForm` copies
926
- and guards every field that arrived before the audit sees one of them, so a payload four times over
927
- `FIELD_LIMIT` is read four times over and then refused. Bound the size of a payload at the transport
901
+ stops at `NODE_LIMIT`, so a fault beyond either ceiling goes unnamed while
902
+ the breached ceiling itself is reported. They do not bound the read that happens before any of that.
903
+ `parseForm` copies and guards every field that arrived before the audit sees one of them, so a
904
+ payload four times over `FIELD_LIMIT` is read four times over and then refused. Bound the size of a payload at the transport
928
905
  that delivers it, which is the only layer holding the bytes.
929
906
 
930
907
  ```ts
931
- import { auditSchema, matchesField, LIST_LIMIT, STRING_LIMIT } from '@orkestrel/form'
908
+ import { STRING_LIMIT } from '@orkestrel/contract'
909
+ import { auditSchema, matchesField, LIST_LIMIT } from '@orkestrel/form'
932
910
  import type { CheckboxField } from '@orkestrel/form'
933
911
 
934
912
  auditSchema({ fields: [{ control: 'text', name: 'n'.repeat(129) }] })
@@ -1932,8 +1910,8 @@ matchesValues({ topics: ['a'] }, { topics: ['a'] }) // true
1932
1910
  ## Methods
1933
1911
 
1934
1912
  The public methods of `FormInterface`, which the `Form` class implements exactly and adds nothing
1935
- to. Its readonly data members stay in the preceding `## Surface` rows, in the `Shape` cell before
1936
- `plus`, and are not repeated here.
1913
+ to. Its readonly data members stay in the preceding `## Surface` rows, in the `Signature` cell, and
1914
+ are not repeated here.
1937
1915
 
1938
1916
  A record of answers and a list of names are checked in full before anything moves, so a refused call
1939
1917
  changes nothing.
@@ -2087,10 +2065,11 @@ These invariants hold across [`src/core`](../src/core) and this guide.
2087
2065
  A pattern within `PATTERN_LIMIT` can still backtrack catastrophically; this package applies no
2088
2066
  time bound, so evaluating an untrusted pattern spends the caller's thread.
2089
2067
  11. **Every retained size is budgeted.** `auditSchema` reports a breach of `FIELD_LIMIT`,
2090
- `GROUP_LIMIT`, `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`, `TEXT_LIMIT`, `NODE_LIMIT`, or
2091
- `PATTERN_LIMIT`, so `createForm` throws `SCHEMA` and `parseForm` refuses; `matchesField` refuses
2092
- a value breaching `STRING_LIMIT` or `LIST_LIMIT` before any regular expression sees it, so
2093
- `fill` and a seeded value throw `CONTROL` and the parsers return `undefined`. `TEXT_LIMIT` and
2068
+ `GROUP_LIMIT`, or `PATTERN_LIMIT`, or of `CHOICE_LIMIT`, `NAME_LIMIT`, `STRING_LIMIT`,
2069
+ `TEXT_LIMIT`, or `NODE_LIMIT` from `@orkestrel/contract`, so `createForm` throws `SCHEMA` and `parseForm`
2070
+ refuses; `matchesField` refuses a value breaching `STRING_LIMIT` or this package's
2071
+ `LIST_LIMIT` before any regular expression sees it, so `fill` and a seeded value throw
2072
+ `CONTROL` and the parsers return `undefined`. `TEXT_LIMIT` and
2094
2073
  `NODE_LIMIT` are whole-schema ceilings, `meta` included, so the per-item limits never multiply.
2095
2074
  They bound retention and the audit's own walk, never the structural read at the parse door,
2096
2075
  which is the transport's to bound. Regular-expression time and a `custom` validator's own work