@orkestrel/scaffold 0.0.66 → 0.0.68

package/dist/host/guides/sqlite.md

@@ -0,0 +1,330 @@
+# SQLite
+
+> A lean, typed, synchronous wrapper over Node's built-in `node:sqlite` — a thin skin on
+> `DatabaseSync` / `StatementSync` that exposes prepared statements, transactions, and pragmas,
+> with one runtime dependency, `@orkestrel/contract`, for boundary narrowing.
+
+The wrapper is the raw native handle rather than an ORM: it carries no query, filter, sort, or
+aggregate builder, so a caller reaching for typed querying builds that layer on top.
+`@orkestrel/database`'s SQLite driver is that layer, adapting these synchronous calls to its own
+asynchronous driver contract. Source: [`src/server`](../src/server). Surfaced through the
+`@src/server` barrel. Requires Node.js ^22.18 || >=24.4 for
+[`node:sqlite`](https://nodejs.org/api/sqlite.html) (the releases carrying the `timeout`,
+`isTransaction`, and `readBigInts` options and `StatementSync.iterate`).
+
+## Surface
+
+Creates the database, connects, creates a table, then inserts and queries a row:
+
+```ts
+import { createSQLiteDatabase } from '@orkestrel/sqlite'
+
+const db = createSQLiteDatabase({ path: ':memory:' }) // omit `path` for the same in-memory default
+db.connect() // open the handle (lazy + idempotent); calls before this throw a CLOSED SQLiteError
+db.execute('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT, age INTEGER)')
+
+// `readonly`, `timeout`, and `foreignKeys` thread straight to node:sqlite's native
+// options; the database itself also implements `[Symbol.dispose]` (same as
+// `close`), so `using db = createSQLiteDatabase()` releases it automatically.
+
+db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u1', 'Ada', 36]) // → { changes: 1, rowid: 1 }
+db.prepare('SELECT name FROM users WHERE age >= ?').all([18]) // → [{ name: 'Ada' }] — every adult
+```
+
+### Factories
+
+| API                    | Kind     | Summary                                                                                      |
+| ---------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `createSQLiteDatabase` | function | Creates a synchronous SQLite database over `node:sqlite`, defaulting its path to `:memory:`. |
+
+### Classes
+
+| API               | Kind  | Summary                                                                                                                                                                                                            |
+| ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SQLiteDatabase`  | class | Implements `SQLiteDatabaseInterface` over a lazily opened `DatabaseSync` the instance owns, gating every operation on that connection and mapping each native fault to a `SQLiteError`.                            |
+| `SQLiteStatement` | class | Implements `SQLiteStatementInterface` over one compiled `StatementSync`, gating each call on its owning connection still being open and mapping every native fault, a mid-stream one included, to a `SQLiteError`. |
+
+### Constants
+
+A `Shape` cell holds the constant's declared type.
+
+| API                 | Kind  | Shape    | Summary                                                                          |
+| ------------------- | ----- | -------- | -------------------------------------------------------------------------------- |
+| `SQLITE_CONSTRAINT` | const | `number` | Names the SQLite result code whose low byte, `19`, flags a constraint violation. |
+| `SQLITE_BUSY`       | const | `number` | Names the SQLite result code whose low byte, `5`, flags a locked-database fault. |
+
+### Helpers and errors
+
+| API              | Kind     | Summary                                                                                                                                         |
+| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `wrapError`      | function | Converts a thrown native `node:sqlite` error into a typed `SQLiteError` at the wrapper's one boundary.                                          |
+| `bindParameters` | function | Normalizes `SQLiteParameters` to the binding shape a native `StatementSync` call expects — a positional spread, or a single named record.       |
+| `SQLiteError`    | class    | Represents an error thrown by the SQLite wrapper, carrying a machine-readable `code` — `CLOSED`, `CONSTRAINT`, `BUSY`, `INVALID`, or `UNKNOWN`. |
+| `isSQLiteError`  | function | Checks whether a value is a `SQLiteError`.                                                                                                      |
+
+### Types
+
+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 `\|`.
+
+| API                        | Kind      | Shape                                                                                                                                 | Summary                                                                                                                                                                                                          |
+| -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SQLiteValue`              | type      | `null \| number \| bigint \| string \| Uint8Array`                                                                                    | Represents a value SQLite stores and returns natively — the bridge between SQLite's storage classes and their JS types.                                                                                          |
+| `SQLiteRow`                | type      | `Record<string, SQLiteValue>`                                                                                                         | Represents a result row — a record of column name to `SQLiteValue`.                                                                                                                                              |
+| `SQLiteParameters`         | type      | `readonly SQLiteValue[] \| Readonly<Record<string, SQLiteValue>>`                                                                     | Represents the bind parameters for a prepared statement — positional (an array, bound to `?`) or named (a record, bound to bare `:name` placeholders).                                                           |
+| `SQLiteBinding`            | type      | `{ positional } \| { named }`                                                                                                         | Represents the normalized binding shape a native `StatementSync` call expects — what `SQLiteParameters` become on the way into `node:sqlite`.                                                                    |
+| `SQLiteExecuteResult`      | interface | `{ changes, rowid }`                                                                                                                  | Represents the outcome of a non-query statement (`INSERT` / `UPDATE` / `DELETE` / DDL).                                                                                                                          |
+| `SQLiteErrorCode`          | type      | `'CLOSED' \| 'CONSTRAINT' \| 'BUSY' \| 'INVALID' \| 'UNKNOWN'`                                                                        | Represents a machine-readable `SQLiteError` code.                                                                                                                                                                |
+| `SQLiteDatabaseOptions`    | interface | `{ path?, readonly?, timeout?, foreignKeys?, bigints? }`                                                                              | Represents the options for opening a SQLite connection, accepted by the `createSQLiteDatabase` function and the `SQLiteDatabase` constructor.                                                                    |
+| `SQLiteStatementInterface` | interface | `{} plus execute, get, all, iterate`                                                                                                  | Represents a prepared statement — the only way the wrapper runs SQL.                                                                                                                                             |
+| `SQLiteDatabaseInterface`  | interface | `{ path, connected, transacting } plus connect, close, execute, prepare, transact, begin, commit, rollback, pragma, [Symbol.dispose]` | Represents the contract a synchronous SQLite database fulfills over `node:sqlite`'s `DatabaseSync` — prepared statements, transactions, and pragmas, every call returning a plain value rather than a `Promise`. |
+
+The `path`, `connected`, and `transacting` members of `SQLiteDatabaseInterface` are `readonly` data members (the preceding Surface row) — its call-signature methods are documented under [Methods](#methods).
+
+Row values arrive as the native `SQLiteValue` types and are handed back as-is — the precise per-row shape is imposed one layer up, by `@orkestrel/database`'s SQLite driver, through a contract, never re-narrowed here. Keys and columns are plain SQL: this layer moves `SQLiteValue`s in and out, and typing each row is the job of the layer above.
+
+## Methods
+
+Each class implements its interface exactly — no extra public method. Every one of these calls is **synchronous** and returns a plain value, never a `Promise`.
+
+The `transacting` member of `SQLiteDatabaseInterface` reports whether a transaction is open on this connection (node:sqlite's `isTransaction`, wrapping `sqlite3_get_autocommit()`), and reads `false` when not connected. `transact(scope)` sets it for the scope's duration; `begin()` / `commit()` / `rollback()` set and clear it identically, because `transact` is itself built on those same primitives. `transact(scope)` remains the right tool whenever the whole transaction fits in one synchronous scope; `begin` / `commit` / `rollback` exist for a long-lived or externally-driven transaction that spans async caller code and so cannot be expressed as a single synchronous scope.
+
+`SQLiteDatabaseInterface` also declares `[Symbol.dispose](): void` — a symbol-keyed member, so it is documented here in prose rather than as a `Methods` table row (the guide-parity tooling keys method rows by identifier name). It closes the connection exactly like `close`, letting `using db = createSQLiteDatabase(...)` release it deterministically at the end of a block.
+
+#### `SQLiteDatabaseInterface`
+
+| Method     | Returns                    | Summary                                                                                                     |
+| ---------- | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `connect`  | `void`                     | Opens the underlying connection — lazy and idempotent, so a second call is a no-op.                         |
+| `close`    | `void`                     | Releases the connection; afterward every operation gates `CLOSED` until reconnect.                          |
+| `execute`  | `void`                     | Runs one or more result-less SQL statements (DDL, pragmas) in a single call.                                |
+| `prepare`  | `SQLiteStatementInterface` | Compiles SQL into a reusable prepared statement — the only path that runs queries.                          |
+| `transact` | `R`                        | Runs `scope` between `BEGIN` and `COMMIT`, rolling the whole scope back and rethrowing on a throw.          |
+| `begin`    | `void`                     | Opens a transaction (`BEGIN`); throws the native fault, a nested `BEGIN` included, as a `SQLiteError`.      |
+| `commit`   | `void`                     | Commits the open transaction (`COMMIT`); throws the native fault as a `SQLiteError` when none is open.      |
+| `rollback` | `void`                     | Rolls back the open transaction (`ROLLBACK`); throws the native fault as a `SQLiteError` when none is open. |
+| `pragma`   | `SQLiteValue \| undefined` | Reads a single PRAGMA, or sets then reads it when a `value` is passed.                                      |
+
+#### `SQLiteStatementInterface`
+
+| Method    | Returns                       | Summary                                                                                        |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------- |
+| `execute` | `SQLiteExecuteResult`         | Runs a non-query (`INSERT` / `UPDATE` / `DELETE` / DDL) and returns its `changes` and `rowid`. |
+| `get`     | `SQLiteRow \| undefined`      | Runs the statement and returns its first row, or `undefined` when none matched.                |
+| `all`     | `readonly SQLiteRow[]`        | Runs the statement and returns every matching row eagerly, as an array.                        |
+| `iterate` | `IterableIterator<SQLiteRow>` | Streams the matching rows lazily, one row materialized at a time, for a large result set.      |
+
+## Contract
+
+These invariants hold across `src/server` ↔ `sqlite.md`:
+
+1. **One barrel, one surface.** Every name a consumer imports comes from `src/server/index.ts`, published as the `.` entry of the `exports` field. `.` is the only code entry; `./package.json` is the manifest.
+2. **Synchronous.** Every operation runs synchronously, because `node:sqlite` does — no Promises. `@orkestrel/database`'s SQLite driver adapts it to that package's asynchronous driver contract, one layer up.
+3. **Native, not a second query engine.** The wrapper exposes only what `node:sqlite` offers natively — prepared statements, transactions, and pragmas. It has **no** `where` / `filter` / `order` / aggregate builder; that is the core database engine over `scan`, the same discipline as the IndexedDB wrapper.
+4. **`SQLiteValue` values, plain SQL.** Reads return `SQLiteRow`s of native `SQLiteValue`s; writes bind `SQLiteValue`s. Per-row typing belongs above this layer, in the core database's contracts.
+5. **Native faults become `SQLiteError`.** Every native `node:sqlite` throw is mapped at the boundary to a `SQLiteError` carrying a machine-readable `code` — a constraint violation (a UNIQUE / PRIMARY KEY conflict) maps to `'CONSTRAINT'`, a locked-database fault to `'BUSY'`, a wrapper-lifecycle fault to `'CLOSED'`, the wrapper's own invalid-argument refusal to `'INVALID'`, and every unclassified native fault to `'UNKNOWN'`. This holds for `iterate` too: its lazy native iterator is stepped inside its own try/catch, so a fault surfacing mid-stream (for example an out-of-range integer on a later row) maps to a `SQLiteError` exactly like an eager fault, never escaping raw from the caller's `for...of`. Finalizing is the exception to that mapping: on every exit after the first step the wrapper finalizes the native iterator, and a fault from that finalize call is discarded rather than mapped, so leaving the loop never throws. Narrow a caught value with `isSQLiteError`.
+6. **`CLOSED` before connect, and after close for any statement too.** The database connects lazily; an operation before `connect` (or after `close`) throws a `CLOSED` `SQLiteError`. `connect` is idempotent. A `SQLiteStatementInterface` retains a liveness check to its owning connection: after that connection is closed, every one of the statement's methods (`execute` / `get` / `all` / `iterate`) also throws `CLOSED` — even a statement prepared before the close and still held by the caller. Reconnecting afterward does not revive it: a statement prepared on the earlier connection stays `CLOSED` permanently; prepare a fresh statement on the new connection.
+7. **`BUSY` on lock contention — `SQLITE_LOCKED` is not `BUSY`.** A write that finds the database locked by another connection retries for `timeout` milliseconds (default `0` — fail immediately), then throws a `BUSY` `SQLiteError` — retryable, unlike the other codes. A `SQLITE_LOCKED` fault (result code `6`, a same-connection table-lock conflict, distinct from `SQLITE_BUSY`'s cross-connection database lock) is **not** mapped to `'BUSY'` — `wrapError` only recognizes `SQLITE_BUSY`, so a `SQLITE_LOCKED` fault surfaces as `'UNKNOWN'` and is not retryable the same way.
+8. **`transacting` mirrors native autocommit state.** `db.transacting` is `true` exactly while a transaction is open (inside `transact(scope)`, or between a manual `BEGIN` and its `COMMIT` / `ROLLBACK`) and `false` otherwise, including when disconnected.
+9. **`transact(scope)` requires a synchronous scope.** If `scope` returns a thenable (an `async` function or a function returning a `Promise`), the transaction is rolled back immediately and a `SQLiteError` with code `'INVALID'` is thrown — an async scope would otherwise return before its awaited work runs, letting `transact` commit prematurely. A transaction that must span async caller code uses `begin()` / `commit()` / `rollback()` directly instead.
+
+## Patterns
+
+### Connect, execute, and round-trip a row
+
+Connects, creates a table, inserts a row, and reads it back by id:
+
+```ts
+import { createSQLiteDatabase } from '@orkestrel/sqlite'
+
+const db = createSQLiteDatabase() // path defaults to ':memory:'
+db.connect()
+db.execute('CREATE TABLE users (id TEXT PRIMARY KEY, name TEXT, age INTEGER)')
+const result = db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u1', 'Ada', 36])
+result.changes // 1
+db.prepare('SELECT * FROM users WHERE id = ?').get(['u1']) // { id: 'u1', name: 'Ada', age: 36 }
+```
+
+### Positional and named parameters
+
+Binds parameters positionally or by name:
+
+```ts
+// Positional — an array bound to `?` placeholders:
+db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u2', 'Lin', 29])
+
+// Named — a record bound to bare `:name` placeholders (no prefix needed in JS):
+db.prepare('INSERT INTO users VALUES (:id, :name, :age)').execute({
+	id: 'u3',
+	name: 'Max',
+	age: 41,
+})
+```
+
+### Reading: get, all, iterate
+
+Reads a single row, every row, or a lazy stream of rows:
+
+```ts
+db.prepare('SELECT name FROM users WHERE id = ?').get(['u1']) // first row or undefined
+db.prepare('SELECT * FROM users ORDER BY age').all() // every row
+for (const row of db.prepare('SELECT id FROM users').iterate()) handle(row) // lazy stream
+```
+
+### Atomic transactions
+
+Runs several statements inside one committed-or-rolled-back scope:
+
+```ts
+db.transact(() => {
+	db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u4', 'Sam', 22])
+	db.prepare('UPDATE users SET age = age + 1 WHERE id = ?').execute(['u1'])
+}) // commits together; a throw rolls the whole scope back and rethrows
+```
+
+### Long-lived transactions with begin / commit / rollback
+
+Opens, holds across awaited caller code, then commits or rolls back a transaction with the primitives directly:
+
+```ts
+// A transaction that must span async caller code (a request handle held open
+// across awaits) can't fit in one synchronous transact(scope) — use the
+// primitives directly instead.
+db.begin()
+try {
+	db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u5', 'Kai', 19])
+	await doSomethingAsync() // caller-driven work between begin and commit
+	db.commit()
+} catch (error) {
+	db.rollback()
+	throw error
+}
+
+// Branch on `transacting` instead of catching a nested-BEGIN fault:
+if (!db.transacting) db.begin()
+```
+
+### Branching on a typed fault
+
+Catches a native fault and branches on its `code`:
+
+```ts
+import { createSQLiteDatabase, isSQLiteError } from '@orkestrel/sqlite'
+
+try {
+	db.prepare('INSERT INTO users VALUES (?, ?, ?)').execute(['u1', 'Dup', 30]) // 'u1' already exists
+} catch (error) {
+	if (isSQLiteError(error) && error.code === 'CONSTRAINT') {
+		// a UNIQUE / PRIMARY KEY conflict — distinguished by `code`, not a parsed message
+	}
+}
+```
+
+### Pragmas
+
+Reads a PRAGMA, then sets and reads it:
+
+```ts
+db.pragma('user_version') // read → 0
+db.pragma('user_version', 7) // set then read → 7 (a cheap on-disk schema-version counter)
+db.pragma('journal_mode', 'WAL') // set then read → 'wal' — durable write-ahead logging for a file db
+```
+
+### Closing a connection
+
+Closes the connection and reads `connected` afterward:
+
+```ts
+db.close() // releases the connection; every operation gates CLOSED until reconnect
+db.connected // false
+```
+
+### Production options: readonly, timeout, foreignKeys
+
+Opens a connection with `readonly`, `timeout`, `foreignKeys`, and `bigints`:
+
+```ts
+// Open an existing file read-only — a write throws (the file must already exist):
+const reader = createSQLiteDatabase({ path: '/data/app.db', readonly: true })
+
+// A busy timeout retries a locked database before failing BUSY:
+const writer = createSQLiteDatabase({ path: '/data/app.db', timeout: 2000 })
+
+// Foreign-key enforcement (node:sqlite defaults this to true when omitted):
+const enforced = createSQLiteDatabase({ foreignKeys: true })
+
+// Writes always accept a bigint; a stored integer beyond Number.MAX_SAFE_INTEGER
+// throws on read unless `bigints` is enabled — enabling it returns every integer
+// column as bigint, not the out-of-range ones alone:
+const exact = createSQLiteDatabase({ bigints: true })
+```
+
+### Disposing with `using`
+
+Releases the connection automatically at the end of a `using` block:
+
+```ts
+{
+	using db = createSQLiteDatabase()
+	db.connect()
+	db.execute('CREATE TABLE t (id INTEGER)')
+} // db.close() runs automatically at the end of the block
+```
+
+### Retrying on BUSY
+
+Catches a `BUSY` fault from a locked database to retry:
+
+```ts
+import { isSQLiteError } from '@orkestrel/sqlite'
+
+try {
+	db.prepare('INSERT INTO t VALUES (?)').execute([1]) // another connection holds the lock
+} catch (error) {
+	if (isSQLiteError(error) && error.code === 'BUSY') {
+		// retryable — back off briefly and retry, or raise the `timeout` option
+	}
+}
+```
+
+### The boundary helpers directly
+
+Calls the boundary helpers directly to normalize parameters and wrap a native throw:
+
+```ts
+import { bindParameters, wrapError } from '@orkestrel/sqlite'
+
+bindParameters(['u1', 'Ada']) // → { positional: ['u1', 'Ada'] }
+bindParameters({ id: 'u1' }) // → { named: { id: 'u1' } }
+
+try {
+	db.execute('not sql')
+} catch (error) {
+	wrapError(error) // a typed SQLiteError, mapped from the native throw
+}
+```
+
+### Practices
+
+- **Use prepared statements with bound parameters**, never string-interpolated values — binding is the SQL-injection-safe path (pragmas, which can't bind, take trusted internal names only).
+- **Keep a transaction scope synchronous and tight** — the wrapper is synchronous, so a scope is a plain function body that commits on return and rolls back on a throw.
+- **Branch on `error.code`** (through `isSQLiteError`) rather than parsing a message — `'CONSTRAINT'` distinguishes a key conflict from any other fault, and `'INVALID'` distinguishes the wrapper's own refusal from an unclassified native fault.
+- **Retry `'BUSY'`, not the others** — it is the one retryable code; back off briefly (or raise `timeout`) before retrying the same operation.
+- **Prefer `using`** over a manual `try` / `finally close()` when a database's lifetime matches one block scope.
+- **Enable `bigints` when integers may exceed `Number.MAX_SAFE_INTEGER`** — writes already accept `bigint`, but a read of an out-of-range stored integer throws unless `bigints` is set; note the option applies to every integer column, not selectively.
+- **Branch on `transacting` instead of catching a nested-`BEGIN` error** — a consumer composing its own `begin()` (for example a migration step joining an enclosing transaction) checks `db.transacting` first and skips its own `begin()` / `commit()` when one is already open, rather than issuing `begin()` unconditionally and handling the "cannot start a transaction within a transaction" fault.
+- **Use `begin()` / `commit()` / `rollback()` only for a long-lived or externally-driven transaction** that spans async caller code — `transact(scope)` stays the right tool whenever the whole transaction fits in one synchronous scope.
+- **Never pass an `async` scope to `transact(scope)`** — a thenable return is rejected (rolled back, then thrown as `'INVALID'`) rather than silently committing before the awaited work runs; reach for `begin()` / `commit()` / `rollback()` for anything that must `await`.
+- **`'BUSY'` is the only retryable code from lock contention** — a `SQLITE_LOCKED` fault (a same-connection conflict) is not mapped to `'BUSY'` and surfaces as `'UNKNOWN'`, so do not treat every lock-shaped fault as retryable; branch on `error.code === 'BUSY'` specifically.
+
+## Tests
+
+- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/server` bijection, the `## Methods` ↔ interface/class method parity, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Connect, execute, and round-trip a row` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
+- [`tests/src/server/SQLiteDatabase.test.ts`](../tests/src/server/SQLiteDatabase.test.ts) — the database in a real `:memory:` SQLite: connect / close lifecycle, the `CLOSED` gate, execute DDL, prepare round-trip, transact commit and rollback, pragma get + set, and the production options — `readonly` rejecting a write, `foreignKeys` enforcing a real FK violation, `timeout` surfacing `BUSY` from a genuinely locked second connection, and `[Symbol.dispose]` closing inside a `using` block.
+- [`tests/src/server/SQLiteStatement.test.ts`](../tests/src/server/SQLiteStatement.test.ts) — prepared statements: `execute`'s result, positional and named binding, `get` / `all` / `iterate`, an abandoned `iterate` releasing its read lock and finalizing without throwing, and a `CONSTRAINT` violation.
+- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) — the wrapper's boundary helpers as pure units: `wrapError` mapping a thrown value to a typed `SQLiteError` (real constraint fault → `CONSTRAINT`, real locked-database fault → `BUSY`, non-error → `UNKNOWN`, pass-through) and `bindParameters` normalizing parameters to the native binding shape (array → positional, record → named).
+- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) — `createSQLiteDatabase` returns a working `SQLiteDatabaseInterface` and defaults its path to `:memory:`.
+
+## See also
+
+- [`AGENTS.md`](../AGENTS.md) — the coding law this package is written against.
+- [`README.md`](README.md) — the guides index.

package/dist/host/guides/sse.md

@@ -0,0 +1,187 @@
+# SSE
+
+> A stateful Server-Sent-Events (SSE) stream parser: a handle that turns string chunks into
+> the complete events a blank line has dispatched, buffering a partial line or in-progress
+> event until the rest arrives and persisting the sticky `id` / `retry` connection state.
+
+SSE is a UTF-8 text stream of events separated by a blank line. Within an event each
+`field: value` line accumulates onto an in-progress event — multiple `data:` lines concatenate
+with `\n`, and `event:` / `id:` / `retry:` are last-wins — and the blank line dispatches the
+accumulated event, but only when its data buffer is non-empty. The `id` and `retry` fields
+follow WHATWG last-event-id semantics: each survives dispatch, is read through the getter of
+its own name, and is dropped only by `clear()`. An optional `limit` bounds the total buffered
+characters, throwing a typed `SSEError('OVERFLOW')` rather than growing unbounded, and
+`flush()` forces out a trailing unterminated event at end-of-stream. A pure functional
+primitive — no Emitter, no server / HTTP / agent coupling; it never throws on malformed input,
+only `SSEError('OVERFLOW')` when a configured `limit` is exceeded.
+Source: [`src/core`](../src/core). Surfaced through the `@src/core` barrel.
+
+## Surface
+
+Create a parser and feed it chunks as they arrive; each `parse(chunk)`
+returns the events a blank line has dispatched so far, and an in-progress
+event / trailing partial line is held for the next call:
+
+```ts
+import { createSSEParser } from '@orkestrel/sse'
+
+const parser = createSSEParser()
+parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+parser.parse('event: ping\ndata: 1') // [] - the event is buffered until its blank line
+parser.parse('\n\n') // [{ data: '1', event: 'ping' }]
+parser.clear() // drop any buffered partial line / event - ready for a fresh stream
+```
+
+### Types
+
+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 `\|`.
+
+| Type                 | Kind      | Shape                                    | Summary                                                                                                                                                                                                                                                                                                           |
+| -------------------- | --------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SSEEvent`           | interface | `{ data, event?, id?, retry? }`          | Represents one dispatched Server-Sent Event — the value a blank line flushes from an `SSEParserInterface`. Its `data` holds every `data:` field of that event joined by `\n` with no trailing newline, and `event` / `id` / `retry` hold the last field of each name the event carried.                           |
+| `SSEParserInterface` | interface | `{ id, retry } plus parse, flush, clear` | Represents a stateful Server-Sent-Events (SSE) stream parser: feed it string chunks, get back the complete events dispatched so far. A trailing partial line / in-progress event is buffered until the rest arrives, and the sticky `id` / `retry` getters carry the connection state a dispatch leaves in place. |
+| `SSEParserOptions`   | interface | `{ limit? }`                             | Configures the parser `createSSEParser` builds and the `SSEParser` constructor accepts — `limit` caps the total buffered characters held at once, and leaving it unset keeps the buffering unbounded.                                                                                                             |
+| `SSEErrorCode`       | type      | `'OVERFLOW'`                             | Names the machine-readable code an `SSEError` carries — `'OVERFLOW'` alone, thrown when a `parse(chunk)` call would push the buffered total over a configured `limit`.                                                                                                                                            |
+
+```ts
+import type { SSEParserOptions } from '@orkestrel/sse'
+
+const options: SSEParserOptions = { limit: 1_000_000 }
+```
+
+### Constants
+
+A `Shape` cell holds the constant's declared type.
+
+| API   | Kind  | Shape  | Summary                                                                                                                                              |
+| ----- | ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NUL` | const | string | Names the null byte (`U+0000`). The SSE spec voids an `id:` field whose value contains it, so an `id` carrying a NUL is never surfaced.              |
+| `BOM` | const | string | Names the byte-order mark (`U+FEFF`), stripped from the first non-empty chunk of an SSE stream (a leading mark on later chunks is ordinary content). |
+
+```ts
+import { BOM, NUL } from '@orkestrel/sse'
+
+NUL.charCodeAt(0) // 0
+BOM.charCodeAt(0) // 0xfeff
+```
+
+### Errors
+
+| API          | Kind     | Summary                                                                                                                                                       |
+| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SSEError`   | class    | Represents an error the SSE parser throws, carrying the machine-readable `SSEErrorCode` a `catch` branches on and an optional `context` of diagnostic detail. |
+| `isSSEError` | function | Narrows an unknown caught value to an `SSEError`.                                                                                                             |
+
+```ts
+import { isSSEError, SSEError } from '@orkestrel/sse'
+
+try {
+	throw new SSEError('OVERFLOW', 'SSE parser buffer would exceed the configured limit', {
+		limit: 100,
+		size: 150,
+	})
+} catch (error) {
+	if (isSSEError(error)) error.code // 'OVERFLOW'
+}
+```
+
+### Factories
+
+| API               | Kind     | Summary                                                                                                                                                                                |
+| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createSSEParser` | function | Creates a Server-Sent-Events (SSE) stream parser — a stateful `SSEParserInterface` handle, backed by `SSEParser`, that turns string chunks into the complete events dispatched so far. |
+
+#### Create a bounded parser and feed it chunks
+
+The following builds a parser bounded by `limit` and feeds it chunks as they arrive:
+
+```ts
+import { createSSEParser } from '@orkestrel/sse'
+
+const parser = createSSEParser({ limit: 1_000_000 })
+parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+parser.parse('event: ping\ndata: 1') // [] - buffered until its blank line
+parser.parse('\n\n') // [{ data: '1', event: 'ping' }]
+```
+
+### Classes
+
+| API         | Kind  | Summary                                                                                                                                                                                                                         |
+| ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SSEParser` | class | Implements `SSEParserInterface` over one internal line buffer, reassembling an event split across chunk boundaries once its blank line arrives and holding the sticky `id` / `retry` connection state until `clear()` drops it. |
+
+## Methods
+
+The public methods of `SSEParserInterface` — the class's full method surface
+(AGENTS.md, Documentation contract). The `readonly` data members `id` / `retry`
+(sticky connection state) stay off the following method table and are documented
+after it.
+
+#### `SSEParserInterface`
+
+| Method  | Returns               | Summary                                                                                                                                                                                                                                                                                                                                                                    |
+| ------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parse` | `readonly SSEEvent[]` | Appends `chunk`, then returns every event a blank line has dispatched — each event's `data:` fields concatenated with `\n`, plus the last `event:` / `id:` / `retry:` field it carried. An in-progress event and a trailing partial line are retained for the next call, and a call that would exceed a configured `limit` throws instead, leaving parser state unchanged. |
+| `flush` | `readonly SSEEvent[]` | Treats any remaining buffered partial line as if it had been terminated, then dispatches the in-progress event when its data buffer is non-empty.                                                                                                                                                                                                                          |
+| `clear` | `void`                | Drops any buffered partial line, in-progress event, and persisted `id` / `retry`, leaving the parser ready for a fresh stream.                                                                                                                                                                                                                                             |
+
+```ts
+import { SSEParser } from '@orkestrel/sse'
+
+const parser = new SSEParser()
+parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+parser.parse('event: ping\ndata: 1') // [] - the event is buffered until its blank line
+parser.parse('\n\n') // [{ data: '1', event: 'ping' }]
+parser.clear() // drop any buffered partial line / event / persisted id/retry - ready for a fresh stream
+parser.parse('data: fresh\n\n') // [{ data: 'fresh' }]
+```
+
+`flush()` is a convenience beyond the WHATWG algorithm, which discards an
+unterminated final event at end-of-stream — without calling `flush()`, that
+spec-faithful discard is the parser's default behavior:
+
+```ts
+import { SSEParser } from '@orkestrel/sse'
+
+const parser = new SSEParser()
+parser.parse('data: incomplete') // [] - no blank line yet, buffered
+parser.flush() // [{ data: 'incomplete' }] - forced out at end-of-stream
+```
+
+`id` / `retry` are sticky connection state (WHATWG last-event-id semantics):
+each valid `id:` / `retry:` field updates them, dispatch does not clear them,
+and only `clear()` does — useful for reconnection (`Last-Event-ID` header):
+
+```ts
+import { SSEParser } from '@orkestrel/sse'
+
+const parser = new SSEParser()
+parser.id // undefined - no id: field seen yet
+parser.parse('id: 42\nretry: 3000\ndata: x\n\n') // [{ data: 'x', id: '42', retry: 3000 }]
+parser.id // '42' - persisted, survives dispatch
+parser.retry // 3000 - persisted, survives dispatch
+parser.clear()
+parser.id // undefined - clear() drops sticky state
+```
+
+A configured `limit` throws a typed `SSEError` instead of growing the buffer
+unbounded:
+
+```ts
+import { isSSEError, SSEParser } from '@orkestrel/sse'
+
+const parser = new SSEParser({ limit: 10 })
+try {
+	parser.parse('x'.repeat(20))
+} catch (error) {
+	if (isSSEError(error) && error.code === 'OVERFLOW') parser.clear()
+}
+```
+
+## Tests
+
+- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), the `SSEParserInterface` ↔ `SSEParser` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Create a bounded parser and feed it chunks` fence against the `@example` block of that title (pinned so the titled pair cannot be retired silently), and the README pitch against this guide's tagline. It also runs the flagship fences and asserts the values their comments claim.
+- [`tests/src/core/SSEParser.test.ts`](../tests/src/core/SSEParser.test.ts) — the parser against the WHATWG algorithm: dispatch on the blank line, stripping only the first space after a colon, multi-line `data:` concatenation with no trailing newline, every field together with last-wins repeats, comment and unknown-field handling, the empty-data rule that emits no spurious event, cross-chunk reassembly, LF / CRLF / bare-CR terminators including a CRLF split across chunks, first-chunk BOM stripping, integer-only `retry:`, a NUL-voided `id:`, sticky `id` / `retry` surviving dispatch until `clear()` drops them, `clear()` dropping the buffered line and the carriage hold and re-arming BOM stripping, returned arrays never aliased across calls, a configured `limit` throwing `SSEError('OVERFLOW')` with parser state unchanged, unicode and adversarial input, volume runs, and the invariant suites that feed one corpus through every fixed-size and two-way-split chunking and require the whole-string parse back.
+- [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createSSEParser` returns a working `SSEParserInterface`, hands back handles that share no buffer state, matches `new SSEParser()` over a shared corpus, and threads `limit` through to the same overflow.
+- [`tests/policy.test.ts`](../tests/policy.test.ts) — this repository's own conventions: the scratch containment guard, the mirror register pairing each test with its module, the population controls with their negative controls, the skill family and bridge rules, the rule map, portability, the prose denylist and its currency, and the policy configuration wiring.
+- [`tests/config.test.ts`](../tests/config.test.ts) — the root configuration read from the real config files, the Oxlint policy plugin's rules driven through `RuleTester`, and the configuration helpers.