@orkestrel/scaffold 0.0.119 → 0.0.121

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 (73) hide show
  1. package/dist/bin/main.js +19 -19
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
  4. package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
  5. package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
  6. package/dist/host/claude/agents/orkestrel.md +52 -51
  7. package/dist/host/claude/rules/tests.md +2 -2
  8. package/dist/host/claude/rules/typescript.md +2 -3
  9. package/dist/host/guides/abort.md +0 -4
  10. package/dist/host/guides/agent.md +5 -5
  11. package/dist/host/guides/brief.md +7 -15
  12. package/dist/host/guides/browser.md +1 -1
  13. package/dist/host/guides/budget.md +1 -5
  14. package/dist/host/guides/capture.md +2 -2
  15. package/dist/host/guides/codec.md +18 -3
  16. package/dist/host/guides/console.md +4 -30
  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/guide.md +0 -1
  23. package/dist/host/guides/html.md +3 -7
  24. package/dist/host/guides/indexeddb.md +28 -32
  25. package/dist/host/guides/interpret.md +165 -182
  26. package/dist/host/guides/jsonrpc.md +187 -0
  27. package/dist/host/guides/lsp.md +26 -51
  28. package/dist/host/guides/markdown.md +132 -141
  29. package/dist/host/guides/mcp.md +220 -276
  30. package/dist/host/guides/middleware.md +14 -22
  31. package/dist/host/guides/msg.md +47 -63
  32. package/dist/host/guides/ndjson.md +0 -4
  33. package/dist/host/guides/ollama.md +1 -3
  34. package/dist/host/guides/pool.md +0 -4
  35. package/dist/host/guides/probe.md +71 -80
  36. package/dist/host/guides/process.md +71 -79
  37. package/dist/host/guides/program.md +26 -35
  38. package/dist/host/guides/qualifier.md +0 -6
  39. package/dist/host/guides/queue.md +0 -4
  40. package/dist/host/guides/rater.md +6 -12
  41. package/dist/host/guides/reason.md +30 -36
  42. package/dist/host/guides/relation.md +0 -2
  43. package/dist/host/guides/router.md +11 -18
  44. package/dist/host/guides/scaffold.md +148 -144
  45. package/dist/host/guides/sea.md +47 -51
  46. package/dist/host/guides/server.md +15 -19
  47. package/dist/host/guides/sqlite.md +0 -4
  48. package/dist/host/guides/sse.md +6 -10
  49. package/dist/host/guides/table.md +481 -493
  50. package/dist/host/guides/template.md +0 -4
  51. package/dist/host/guides/terminal.md +0 -26
  52. package/dist/host/guides/test.md +46 -66
  53. package/dist/host/guides/timeout.md +0 -6
  54. package/dist/host/guides/tool.md +2 -6
  55. package/dist/host/guides/toolbox.md +0 -10
  56. package/dist/host/guides/websocket.md +0 -4
  57. package/dist/host/guides/worker.md +57 -57
  58. package/dist/host/guides/workflow.md +13 -26
  59. package/dist/host/guides/workspace.md +15 -21
  60. package/dist/host/manifest.json +64 -909
  61. package/dist/src/core/index.cjs +128 -181
  62. package/dist/src/core/index.cjs.map +1 -1
  63. package/dist/src/core/index.d.cts +213 -213
  64. package/dist/src/core/index.d.ts +213 -213
  65. package/dist/src/core/index.js +117 -170
  66. package/dist/src/core/index.js.map +1 -1
  67. package/dist/src/server/index.cjs +35 -34
  68. package/dist/src/server/index.cjs.map +1 -1
  69. package/dist/src/server/index.d.cts +62 -58
  70. package/dist/src/server/index.d.ts +62 -58
  71. package/dist/src/server/index.js +36 -35
  72. package/dist/src/server/index.js.map +1 -1
  73. package/package.json +13 -13
@@ -68,8 +68,6 @@ On Windows, `SEAOptions.windows.sign` is optional Authenticode signing. When pre
68
68
 
69
69
  ### Constants
70
70
 
71
- A `Shape` cell holds the constant's declared type.
72
-
73
71
  | Name | Kind | Signature | Summary |
74
72
  | --------------------------------- | ----- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
75
73
  | `SEA_SENTINEL_FUSE` | const | `"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2"` | Holds the SEA sentinel fuse value embedded in the Node.js binary, `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`. |
@@ -108,55 +106,53 @@ A `Shape` cell holds the constant's declared type.
108
106
 
109
107
  ### Helpers and errors
110
108
 
111
- | Name | Kind | Signature | Summary |
112
- | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
113
- | `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
114
- | `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
115
- | `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
116
- | `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
117
- | `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
118
- | `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
119
- | `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
120
- | `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
121
- | `computeSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
122
- | `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
123
- | `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
124
- | `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
125
- | `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
126
- | `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
127
- | `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
128
- | `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
129
- | `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
130
- | `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
131
- | `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
132
- | `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
133
- | `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
134
- | `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
135
- | `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
136
- | `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
137
- | `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
138
- | `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
139
- | `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
140
- | `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
141
- | `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
142
- | `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
143
- | `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
144
- | `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
145
- | `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
146
- | `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
147
- | `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
148
- | `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
149
- | `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
150
- | `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
151
- | `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
152
- | `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
153
- | `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
154
- | `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
109
+ | Name | Kind | Signature | Summary |
110
+ | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
111
+ | `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
112
+ | `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
113
+ | `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
114
+ | `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
115
+ | `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
116
+ | `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
117
+ | `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
118
+ | `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
119
+ | `computeCompressionSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
120
+ | `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
121
+ | `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
122
+ | `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
123
+ | `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
124
+ | `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
125
+ | `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
126
+ | `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
127
+ | `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
128
+ | `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
129
+ | `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
130
+ | `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
131
+ | `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
132
+ | `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
133
+ | `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
134
+ | `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
135
+ | `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
136
+ | `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
137
+ | `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
138
+ | `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
139
+ | `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
140
+ | `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
141
+ | `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
142
+ | `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
143
+ | `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
144
+ | `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
145
+ | `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
146
+ | `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
147
+ | `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
148
+ | `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
149
+ | `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
150
+ | `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
151
+ | `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
152
+ | `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
155
153
 
156
154
  ### Types
157
155
 
158
- 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.
159
-
160
156
  | Name | Kind | Signature | Summary |
161
157
  | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
162
158
  | `SEACompressionSize` | interface | `{ original, compressed, ratio }` | Represents a size comparison between original and compressed data. |
@@ -197,7 +193,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
197
193
 
198
194
  ## Methods
199
195
 
200
- The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `Shape` cell and off these tables: `format` on `InjectorInterface`, `emitter` and `status` on `SEAInterface`, `emitter` and `count` on `AssetManagerInterface`. Each concrete class implements its interface exactly, so this doubles as the class's instance-method surface.
196
+ The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `Signature` cell and off these tables: `format` on `InjectorInterface`, `emitter` and `status` on `SEAInterface`, `emitter` and `count` on `AssetManagerInterface`. Each concrete class implements its interface exactly, so this doubles as the class's instance-method surface.
201
197
 
202
198
  #### `SEAInterface`
203
199
 
@@ -289,7 +285,7 @@ import {
289
285
  ensureExists,
290
286
  isCompressible,
291
287
  walkDirectory,
292
- computeSize,
288
+ computeCompressionSize,
293
289
  compressFile,
294
290
  compressDirectory,
295
291
  formatSize,
@@ -333,7 +329,7 @@ ensureExists('dist/server/serve.cjs', 'entry file is missing')
333
329
  walkDirectory('dist/app/browser') // every relative file path under the directory
334
330
  isCompressible('dist/app/browser/index.html') // true — not in SKIP_EXTENSIONS
335
331
 
336
- const size = computeSize(1000, 400) // { original: 1000, compressed: 400, ratio: 0.4 }
332
+ const size = computeCompressionSize(1000, 400) // { original: 1000, compressed: 400, ratio: 0.4 }
337
333
  compressFile('dist/index.html', 'dist/index.html.br')
338
334
  compressDirectory('dist/app/browser', { mode: 'text' })
339
335
 
@@ -58,11 +58,11 @@ Cross-face and substrate usage appear under [Patterns](#patterns).
58
58
 
59
59
  ### Factories
60
60
 
61
- | Name | Kind | Signature | Summary |
62
- | ------------------ | -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
63
- | `createNegotiator` | function | `() => NegotiatorInterface` | Creates a `NegotiatorInterface` — the reusable content-negotiation machine over the weighted `Accept` family. |
64
- | `createServer` | function | `<TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Creates a `ServerInterface` — the node face's HTTP server facade over a consumed `@orkestrel/router` dispatcher. |
65
- | `createStream` | function | `(options?: StreamOptions) => StreamInterface` | Creates a `StreamInterface` — a generic Server-Sent-Events stream whose `response` is a fetch-standard streaming `Response` a route returns. |
61
+ | Name | Kind | Signature | Summary |
62
+ | ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
63
+ | `createNegotiator` | function | `() => NegotiatorInterface` | Creates a `NegotiatorInterface` — the reusable content-negotiation machine over the weighted `Accept` family. |
64
+ | `createServer` | function | `<TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Creates a `ServerInterface` — the node face's HTTP server facade over a consumed `@orkestrel/router` dispatcher. |
65
+ | `createStream` | function | `(options?: StreamOptions) => SSEStreamInterface` | Creates an `SSEStreamInterface` — a generic Server-Sent-Events stream whose `response` is a fetch-standard streaming `Response` a route returns. |
66
66
 
67
67
  ### Startup ownership
68
68
 
@@ -77,8 +77,6 @@ cleanup finish before the start event is emitted.
77
77
 
78
78
  ### Constants
79
79
 
80
- A `Shape` cell holds the constant's declared type.
81
-
82
80
  | Name | Kind | Signature | Summary |
83
81
  | ---------------------------- | ----- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84
82
  | `DEFAULT_DRAIN_MS` | const | `10000` | Names the default graceful-stop deadline `stop()` gives in-flight requests and claimed upgraded sockets, `10_000` ms. |
@@ -148,12 +146,10 @@ A `Shape` cell holds the constant's declared type.
148
146
  | `ServerError` | class | `new (code: ServerErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => ServerError` | Represents the error this package raises when a caller programmed a call the entity refuses, carrying `'STATUS'` or `'NEXT'` as its code. |
149
147
  | `Negotiator` | class | `new () => NegotiatorInterface` | Represents the content-negotiation machine over the weighted `Accept` family — a reusable, cross-middleware entity rather than a middleware. Implements exactly `NegotiatorInterface`. |
150
148
  | `Server` | class | `new <TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Represents the HTTP server facade — an observable `node:http` lifecycle composing this module's own middleware onion around a consumed `@orkestrel/router` dispatcher. Implements exactly `ServerInterface`. |
151
- | `Stream` | class | `new (options?: StreamOptions) => StreamInterface` | Represents the Server-Sent-Events handle over an open, fetch-standard streaming `Response`. Implements exactly `StreamInterface`. |
149
+ | `Stream` | class | `new (options?: StreamOptions) => SSEStreamInterface` | Represents the Server-Sent-Events handle over an open, fetch-standard streaming `Response`. Implements exactly `SSEStreamInterface`. |
152
150
 
153
151
  ### Types
154
152
 
155
- 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 `\|`.
156
-
157
153
  | Name | Kind | Signature | Summary |
158
154
  | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
159
155
  | `MiddlewareContext` | interface | `{ url, method, state, body() }` | Represents the composition context — plain data, one per request, shared by every middleware and, as `state`, by the route handlers behind the dispatcher. |
@@ -169,8 +165,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
169
165
  | `FormatHandlerMap` | type | `Readonly<Record<string, (request: Request, context: MiddlewareContext<TState>) => Response \| Promise<Response>>>` | Represents a map of media type → handler for `NegotiatorInterface.format` — the content-negotiation dispatch table. |
170
166
  | `NegotiatorInterface` | interface | `{ negotiate(), encoding(), language(), format() }` | Represents content negotiation over the weighted `Accept` family — a reusable, cross-middleware machine (not itself a middleware). |
171
167
  | `SSEMessage` | interface | `{ data, event?, id?, retry? }` | Represents one Server-Sent Event to serialize to the wire. |
172
- | `StreamOptions` | interface | `{ status?, headers? }` | Options for a `StreamInterface` — how `createStream` opens the streaming response. |
173
- | `StreamInterface` | interface | `{ response, closed, write(), comment(), drain(), end() }` | Represents a handle to write Server-Sent Events to an open, fetch-standard streaming `Response` — the generic streaming surface `createStream` returns over a `ReadableStream`. |
168
+ | `StreamOptions` | interface | `{ status?, headers? }` | Options for an `SSEStreamInterface` — how `createStream` opens the streaming response. |
169
+ | `SSEStreamInterface` | interface | `{ response, closed, write(), comment(), drain(), end() }` | Represents a handle to write Server-Sent Events to an open, fetch-standard streaming `Response` — the generic streaming surface `createStream` returns over a `ReadableStream`. |
174
170
  | `RangeSpec` | type | `{ readonly satisfiable: true; readonly start: number; readonly end: number; } \| { readonly satisfiable: false; }` | Represents the parsed outcome of an HTTP `Range` request header. |
175
171
  | `BodyOptions` | interface | `{ limit?, decompression? }` | Options for `readBody` — how the shared body-collection pipeline caps and decompresses a request body. |
176
172
  | `ServerStatus` | type | `'idle' \| 'starting' \| 'listening' \| 'stopping' \| 'stopped'` | Represents the `Server`'s lifecycle state. |
@@ -201,7 +197,7 @@ The error guards and request readers expose these primitives.
201
197
 
202
198
  ## Methods
203
199
 
204
- The public methods of `NegotiatorInterface`, `StreamInterface`, and
200
+ The public methods of `NegotiatorInterface`, `SSEStreamInterface`, and
205
201
  `ServerInterface` — every call-signature member listed (their `readonly` data
206
202
  members stay Surface rows). `Negotiator`, `Server`, and `Stream` implement
207
203
  their interfaces exactly, so their tables also double as each class's
@@ -226,7 +222,7 @@ coding, because an absent `Accept-Encoding` makes identity the correct answer;
226
222
  | `language` | `string \| undefined` | Picks the best `available` language for an `Accept-Language` header — `negotiate` with a language-prefix match (`en` accepts `en-US`) and a bare `*` wildcard. |
227
223
  | `format` | `Promise<Response>` | Dispatches to the handler whose media type the client most prefers — reads the request `Accept`, negotiates against `handlers`' keys, and invokes the winner; `406` when none is acceptable. |
228
224
 
229
- #### `StreamInterface`
225
+ #### `SSEStreamInterface`
230
226
 
231
227
  `write` always accepts an event while open and returns whether the local
232
228
  `ReadableStream` queue still has positive desired size afterward. A producer
@@ -274,7 +270,7 @@ These invariants hold across `src/server` ↔ `server.md`.
274
270
  source directory, and every export appears as a Surface row — exhaustive,
275
271
  both directions.
276
272
  2. **Doc ↔ source method bijection.** The `## Methods` tables list exactly
277
- `NegotiatorInterface`'s, `StreamInterface`'s, and `ServerInterface`'s public
273
+ `NegotiatorInterface`'s, `SSEStreamInterface`'s, and `ServerInterface`'s public
278
274
  methods — exhaustive, both directions — and `Negotiator` / `Stream` /
279
275
  `Server` expose the same public methods, no more.
280
276
  3. **Status machine + bound address + restart-fresh-abort.**
@@ -484,7 +480,7 @@ These invariants hold across `src/server` ↔ `server.md`.
484
480
  Object and callable contexts are accepted. Subclass names are unrestricted. Transparent
485
481
  proxies, unbranded look-alikes, and branded plain objects are rejected.
486
482
  19. **SSE producers can cooperate with real process-local transport
487
- backpressure.** `StreamInterface.write` returns `true` only while the
483
+ backpressure.** `SSEStreamInterface.write` returns `true` only while the
488
484
  underlying `ReadableStream` controller retains positive desired size after
489
485
  accepting the event. A `false` result tells a cooperative producer to await
490
486
  `drain()`; that promise parks without polling until a consumer pull restores
@@ -592,10 +588,10 @@ handle afterwards; a `write` that reports `false` is backpressure `drain`
592
588
  waits out.
593
589
 
594
590
  ```ts
595
- import type { StreamInterface } from '@orkestrel/server'
591
+ import type { SSEStreamInterface } from '@orkestrel/server'
596
592
  import { createStream } from '@orkestrel/server'
597
593
 
598
- async function pumpStream(stream: StreamInterface): Promise<void> {
594
+ async function pumpStream(stream: SSEStreamInterface): Promise<void> {
599
595
  if (!stream.write({ event: 'token', data: 'hello' })) await stream.drain()
600
596
  stream.comment('keep-alive')
601
597
  stream.end()
@@ -774,7 +770,7 @@ new TextDecoder().decode(body) // 'hi' — capped decompression, the zip-bomb de
774
770
  ## Tests
775
771
 
776
772
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/server`
777
- bijection (value and type exports), the `NegotiatorInterface` / `StreamInterface` /
773
+ bijection (value and type exports), the `NegotiatorInterface` / `SSEStreamInterface` /
778
774
  `ServerInterface` ↔ implementing-class method bijections, and the equality gate:
779
775
  every `Summary` cell against its declaration's description paragraph, the titled
780
776
  `Substrate direct use — tokens, cookies, negotiation` fence against the `@example`
@@ -46,8 +46,6 @@ db.prepare('SELECT name FROM users WHERE age >= ?').all([18]) // → [{ name: 'A
46
46
 
47
47
  ### Constants
48
48
 
49
- A `Shape` cell holds the constant's declared type.
50
-
51
49
  | Name | Kind | Signature | Summary |
52
50
  | ------------------- | ----- | --------- | -------------------------------------------------------------------------------- |
53
51
  | `SQLITE_CONSTRAINT` | const | `19` | Names the SQLite result code whose low byte, `19`, flags a constraint violation. |
@@ -70,8 +68,6 @@ non-writable own property.
70
68
 
71
69
  ### Types
72
70
 
73
- 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 `\|`.
74
-
75
71
  | Name | Kind | Signature | Summary |
76
72
  | -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
77
73
  | `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. |
@@ -34,8 +34,6 @@ parser.clear() // drop any buffered partial line / event - ready for a fresh str
34
34
 
35
35
  ### Types
36
36
 
37
- 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 `\|`.
38
-
39
37
  | Name | Kind | Signature | Summary |
40
38
  | -------------------- | --------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
39
  | `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. |
@@ -51,20 +49,18 @@ const options: SSEParserOptions = { limit: 1_000_000 }
51
49
 
52
50
  ### Constants
53
51
 
54
- A `Shape` cell holds the constant's declared type.
55
-
56
- | Name | Kind | Signature | Summary |
57
- | ----- | ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
58
- | `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. |
59
- | `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). |
52
+ | Name | Kind | Signature | Summary |
53
+ | ----- | ----- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
54
+ | `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. |
60
55
 
61
56
  ```ts
62
- import { BOM, NUL } from '@orkestrel/sse'
57
+ import { NUL } from '@orkestrel/sse'
63
58
 
64
59
  NUL.charCodeAt(0) // 0
65
- BOM.charCodeAt(0) // 0xfeff
66
60
  ```
67
61
 
62
+ The parser strips the byte-order mark `BOM` that `@orkestrel/codec` exports from the first non-empty chunk of a stream; a leading mark on a later chunk is ordinary content.
63
+
68
64
  ### Errors
69
65
 
70
66
  | Name | Kind | Signature | Summary |