@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
@@ -65,24 +65,22 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
65
65
 
66
66
  ### Middlewares — node
67
67
 
68
- | Name | Kind | Signature | Summary |
69
- | ------------------- | -------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
- | `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation. |
71
- | `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests. |
72
- | `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery. |
73
- | `createCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather than dependent on the WHATWG `CompressionStream` global. This battery is the node-bound sibling of the core face's feature-detected `createCompression`, and it ships from a separate package entry point (`@orkestrel/middleware/server`) so the shared name is unambiguous per consumer import path. |
68
+ | Name | Kind | Signature | Summary |
69
+ | ----------------------- | -------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
70
+ | `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation. |
71
+ | `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests. |
72
+ | `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery. |
73
+ | `createNodeCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather than dependent on the WHATWG `CompressionStream` global. This battery is the node-bound sibling of the core face's feature-detected `createCompression`, and both compose the same `compressResponse` skeleton. |
74
74
 
75
75
  ### Types
76
76
 
77
- 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.
78
-
79
77
  | Name | Kind | Signature | Summary |
80
78
  | --------------------------- | --------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
81
79
  | `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
82
80
  | `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
83
81
  | `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
84
82
  | `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
85
- | `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each face's `createCompression` builds from its own option bag. |
83
+ | `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
86
84
  | `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
87
85
  | `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
88
86
  | `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
@@ -117,14 +115,14 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
117
115
  | `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware/server`) produces per uploaded file. |
118
116
  | `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
119
117
  | `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
120
- | `Asset` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
118
+ | `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
121
119
  | `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
122
120
  | `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
123
121
  | `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
124
122
  | `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
125
123
  | `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
126
124
  | `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
127
- | `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures the node face's `createCompression` — `node:zlib`-backed response compression. |
125
+ | `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
128
126
  | `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
129
127
  | `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
130
128
  | `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of the pure core's `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared core shape. |
@@ -166,8 +164,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
166
164
 
167
165
  ### Constants
168
166
 
169
- A `Shape` cell holds the constant's declared type.
170
-
171
167
  | Name | Kind | Signature | Summary |
172
168
  | --------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
173
169
  | `DEFAULT_COMPRESSION_THRESHOLD` | const | `1024` | Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. |
@@ -198,7 +194,7 @@ A `Shape` cell holds the constant's declared type.
198
194
  | `DEFAULT_CSRF_SAFE_METHODS` | const | `readonly string[]` | Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). |
199
195
  | `MULTIPART_STATUS` | const | `Readonly<Record<MultipartErrorCode, number>>` | Holds the HTTP status `createMultipart` renders for each `MultipartErrorCode`: `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415. |
200
196
  | `MULTIPART_ERROR_BRAND` | const | `unique symbol` | Holds the `Symbol.for` brand `MultipartError` carries so `isMultipartError` recognizes an instance across duplicate copies of this package — a registry symbol rather than a module-local `Symbol()`, which would mint an unequal symbol per copy. |
201
- | `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings the node face's `createCompression` offers — what `node:zlib` guarantees on every Node runtime, so this face never feature-detects. |
197
+ | `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings `createNodeCompression` offers — what `node:zlib` guarantees on every Node runtime, so this face never feature-detects. |
202
198
  | `DEFAULT_STATIC_INDEX` | const | `"index.html"` | Names `'index.html'`, `createStatic`'s default directory-index filename. |
203
199
  | `DEFAULT_STATIC_FALLBACK_EXCLUDE` | const | `"/api"` | Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. |
204
200
  | `DEFAULT_STATIC_DOTFILES` | const | `NonNullable<StaticOptions['dotfiles']>` | Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. |
@@ -215,8 +211,6 @@ A `Shape` cell holds the constant's declared type.
215
211
 
216
212
  ### Shapers
217
213
 
218
- A `Shape` cell holds the constant's declared type.
219
-
220
214
  | Name | Kind | Signature | Summary |
221
215
  | ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222
216
  | `sessionColumns` | const | `{ id: import("@orkestrel/contract").StringShape; session: import("@orkestrel/contract").JSONShape; seen: import("@orkestrel/contract").NumberShape; created: import("@orkestrel/contract").NumberShape; }` | Holds the `@orkestrel/database` column shape for a `SessionRow` table. Pass it as-is to `createDatabase({ tables: { sessions: sessionColumns } })` so an app declaring a durable session table never hand-writes the shape. |
@@ -237,7 +231,7 @@ A `Shape` cell holds the constant's declared type.
237
231
  | `matchesUnbufferableResponse` | function | `(method: string, response: Response, skipHeader: string) => boolean` | Checks whether a response must skip the compression and ETag buffering pipeline — the shared cheap-skip predicate both batteries apply before ever touching `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or otherwise bodyless response, an `event-stream` response, and a response already carrying the header the caller is about to set. |
238
232
  | `isCompressionNegotiated` | function | `(encoding: Encoding \| undefined) => encoding is Exclude<Encoding, 'identity'>` | Checks whether a negotiated `Accept-Encoding` outcome is worth acting on — `createCompression`'s negotiation-eligibility half of the skip list. |
239
233
  | `rebuildResponse` | function | `(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]) => Response` | Rebuilds a `Response` around a replacement body while preserving its status/statusText — the buffered-response reconstruction shared by the compression and ETag batteries after they have consumed `response.arrayBuffer()`. |
240
- | `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton both faces' `createCompression` batteries compose — response-body compression over a caller-supplied set of feature-detected codings. |
234
+ | `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton `createCompression` and `createNodeCompression` compose — response-body compression over a caller-supplied set of feature-detected codings. |
241
235
  | `transferSessionState` | function | `(from: SessionInterface, to: SessionInterface) => void` | Copies every entry of one session's `state` into another — the regenerate state-carry `createSession`'s `control.regenerate()` applies. |
242
236
  | `sessionExpired` | function | `(cursors: SessionCursors, now: number, limits: SessionLimits) => boolean` | Checks whether a session has aged past its idle timeout or absolute lifetime as of `now` — the pure expiry predicate `MemorySessionStore` delegates to. |
243
237
  | `snapshotSession` | function | `(session: SessionInterface) => SessionSnapshot` | Snapshots a session's `state` into a plain, serializable record — the projection a durable store's `set` writes to disk. |
@@ -250,8 +244,6 @@ A `Shape` cell holds the constant's declared type.
250
244
 
251
245
  Each guard in the following table is total: it accepts any input, returns `false` off-shape, and never throws.
252
246
 
253
- In a guard table a `Shape` cell holds the type the guard narrows to.
254
-
255
247
  | Name | Kind | Signature | Summary |
256
248
  | ------------------ | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
257
249
  | `isSession` | function | `(value: unknown) => value is SessionInterface` | Determines whether a value implements `SessionInterface` — a total structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`, and `clear` mutators. Prototype-agnostic — accepts a plain object, a null-prototype object, and a class instance (a real `Session`), because a restored or stored session is routinely a class instance rather than a literal. |
@@ -340,9 +332,9 @@ The in-memory lookup seam. `createAssets` validates a request key before it
340
332
  calls `read`, copies each successful result, and caches that key for the
341
333
  factory's lifetime. A miss may be read again later.
342
334
 
343
- | Method | Returns | Summary |
344
- | ------ | -------------------- | ------------------------------------------------------------------------------- |
345
- | `read` | `Asset \| undefined` | Reads one identity or Brotli asset representation for a validated relative key. |
335
+ | Method | Returns | Summary |
336
+ | ------ | ---------------------------------- | ------------------------------------------------------------------------------- |
337
+ | `read` | `AssetRepresentation \| undefined` | Reads one identity or Brotli asset representation for a validated relative key. |
346
338
 
347
339
  #### `SessionInterface`
348
340
 
@@ -25,7 +25,8 @@ error still propagates. Reach for `new MSG()` directly when a thrown
25
25
  `MSGError` is the control flow you want:
26
26
 
27
27
  ```ts
28
- import { createMSG, isSuccess } from '@orkestrel/msg'
28
+ import { isSuccess } from '@orkestrel/contract'
29
+ import { createMSG } from '@orkestrel/msg'
29
30
 
30
31
  const result = createMSG({ bytes, name: 'message.eml' })
31
32
  if (isSuccess(result)) {
@@ -37,13 +38,11 @@ if (isSuccess(result)) {
37
38
 
38
39
  ### Types
39
40
 
40
- From [`types.ts`](../src/core/types.ts). A `Shape` cell holds an interface's data members as bare
41
- names in braces, `?` marking an optional member and `plus` introducing its call-signature members,
42
- and a type alias's own type literal with a union's arms escaped as `\|`. `MSGInterface`'s
43
- call-signature members are documented under [`## Methods`](#methods). `Success`, `Failure`, and
44
- `Result` are the originating types from `@orkestrel/contract` (mirrored at
45
- [`contract.md`](contract.md)); this package's `success` / `failure` / `isSuccess` / `isFailure`
46
- wrap them and do not re-export the types.
41
+ From [`types.ts`](../src/core/types.ts). `MSGInterface`'s call-signature members are documented
42
+ under [`## Methods`](#methods). `Success`, `Failure`, and `Result` are the originating types from
43
+ `@orkestrel/contract` (mirrored at [`contract.md`](contract.md)), which also exports the
44
+ `success`, `failure`, `isSuccess`, and `isFailure` functions; import each from there, because this
45
+ package re-exports none of them.
47
46
 
48
47
  | Name | Kind | Signature | Summary |
49
48
  | --------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -74,8 +73,6 @@ wrap them and do not re-export the types.
74
73
 
75
74
  The CFB layout offsets and sizes, the MSG/EML sniffing tables, the MAPI field name mappings, and the burner's geometry, from [`constants.ts`](../src/core/constants.ts). None of them carries runtime behavior. Every value is a fixed offset, a size, or a lookup table that the parsing and burning code in `MSG.ts`, `parsers.ts`, and `helpers.ts` reads.
76
75
 
77
- A `Shape` cell holds the constant's declared type.
78
-
79
76
  | Name | Kind | Signature | Summary |
80
77
  | ----------------------------------- | ----- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
81
78
  | `MSG_FILE_HEADER` | const | `readonly number[]` | Holds the 8-byte CFB/OLE2 magic signature (`D0 CF 11 E0 A1 B1 1A E1`) a `.msg` file must open with. |
@@ -163,44 +160,35 @@ It refuses transparent proxies, unbranded errors, and plain objects carrying the
163
160
 
164
161
  ### Helpers
165
162
 
166
- Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the `Result` constructors/guards, the CFB byte/string/UUID readers and magic check `MSG.ts` composes, the format sniffer, and the MIME/text codecs `parsers.ts` and `shapers.ts` compose.
167
-
168
- | Name | Kind | Signature | Summary |
169
- | --------------------- | -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
170
- | `success` | function | `<T>(value: T) => Success<T>` | Constructs a `Success` wrapping a value. |
171
- | `failure` | function | `<E>(error: E) => Failure<E>` | Constructs a `Failure` wrapping an error. |
172
- | `isSuccess` | function | `<T, E>(result: Result<T, E>) => result is Success<T>` | Narrows a `Result` to a `Success`. |
173
- | `isFailure` | function | `<T, E>(result: Result<T, E>) => result is Failure<E>` | Narrows a `Result` to a `Failure`. |
174
- | `truncateAtNull` | function | `(text: string) => string` | Truncates a string at its first `\0` character. |
175
- | `readUTF16String` | function | `(view: DataView, offset: number, charCount: number) => string` | Reads a UTF-16LE string out of a `DataView`, throwing when the requested range exceeds the view's bounds. |
176
- | `decodeText` | function | `(bytes: Uint8Array, encoding?: MSGEncoding) => string` | Decodes bytes into a string with a pure-ES decoder, dispatching on the named encoding. Default: `windows-1252`. |
177
- | `fileTimeToUTCString` | function | `(low: number, high: number) => string` | Converts a Windows FILETIME (100-ns ticks since 1601-01-01) to a UTC date string. |
178
- | `toHexLower` | function | `(value: number, length: number) => string` | Converts a number to a zero-padded lowercase hex string of the requested digit count. |
179
- | `readMicrosoftUUID` | function | `(bytes: Uint8Array, offset: number) => string` | Reads a mixed-endian Microsoft UUID starting at an offset in a byte array, throwing past the array's bounds. |
180
- | `roundUpToMultiple` | function | `(value: number, boundary: number) => number` | Rounds a value up to the nearest multiple of a boundary, which must be a power of 2. |
181
- | `computeSectors` | function | `(bytes: number, sectorSize: number) => number` | Computes how many sectors of a given size hold a byte count, answering 0 for a count at or below zero. |
182
- | `compareCFBName` | function | `(a: string, b: string) => number` | Orders two directory names as the compound file format requires, comparing by UTF-16 length first and then by uppercased code points. |
183
- | `isMSGFile` | function | `(view: DataView) => boolean` | Reports whether a `DataView`'s first 8 bytes match the CFB magic signature. |
184
- | `decodeBase64` | function | `(text: string) => Uint8Array` | Decodes a Base64 string into raw bytes without relying on `atob`, ignoring ASCII whitespace and tolerating missing padding. |
185
- | `encodeUTF8` | function | `(text: string) => Uint8Array` | Encodes a string into UTF-8 bytes, pairing surrogates and encoding a lone (unpaired) surrogate as U+FFFD. |
186
- | `decodeUTF8` | function | `(bytes: Uint8Array) => string` | Decodes UTF-8 bytes into a string WHATWG-style: an invalid byte sequence decodes as U+FFFD rather than throwing. |
187
- | `decodeLatin1` | function | `(bytes: Uint8Array) => string` | Decodes Latin-1 (ISO-8859-1) bytes into a string, byte-for-code-point. |
188
- | `decodeWindows1252` | function | `(bytes: Uint8Array) => string` | Decodes Windows-1252 bytes into a string, resolving the `0x80`\-`0x9F` range through `WINDOWS_1252_HIGH` and otherwise matching `decodeLatin1`. |
189
- | `resolveEncoding` | function | `(label: string \| undefined) => MSGEncoding` | Resolves a free-form charset label, as a MIME `charset` parameter carries it, to a supported `MSGEncoding`, falling back to `FALLBACK_CHARSET`'s encoding for an unrecognized or absent label. |
190
- | `detectFormat` | function | `(name: string \| undefined, mime: string \| undefined) => EmailFormat \| undefined` | Derives the `EmailFormat` from a file name, a MIME type, or both, answering `undefined` when neither hints at a format. |
191
- | `parseMIMEHeaders` | function | `(text: string) => ReadonlyMap<string, MIMEHeader>` | Parses an RFC 2822 / MIME header block, folding continuation lines. |
192
- | `decodeMIMEEncoding` | function | `(body: string, encoding: string) => Uint8Array` | Decodes a MIME body — `base64`, `quoted-printable`, or passthrough — into raw bytes, throwing on invalid Base64. |
193
- | `decodeMIMEText` | function | `(body: string, encoding: string, charset: string) => string` | Decodes a MIME body to text through `decodeMIMEEncoding` and `resolveEncoding`, taking the charset from a free-form label. |
194
- | `decodeMIMEWords` | function | `(text: string) => string` | Decodes the RFC 2047 encoded words (`=?charset?B/Q?...?=`) in a header value, reading the Base64 (`B`) and quoted-printable (`Q`) forms alike. |
195
- | `formatEmailAddress` | function | `(name: string \| undefined, email: string \| undefined) => string` | Formats a display name and an email address into `"Name <email>"`, or into whichever half is present. |
196
- | `inferExtension` | function | `(mimeType?: string, fileName?: string) => string` | Infers an attachment's file extension from its file name or its MIME type, returning the extension with its leading dot and falling back to `.bin`. |
163
+ Pure, mostly-total leaves from [`helpers.ts`](../src/core/helpers.ts) — the CFB byte/string/UUID readers and magic check `MSG.ts` composes, the format sniffer, and the MIME/text codecs `parsers.ts` and `shapers.ts` compose.
164
+
165
+ | Name | Kind | Signature | Summary |
166
+ | ------------------------ | -------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
167
+ | `truncateAtNull` | function | `(text: string) => string` | Truncates a string at its first `\0` character. |
168
+ | `readUTF16String` | function | `(view: DataView, offset: number, charCount: number) => string` | Reads a UTF-16LE string out of a `DataView`, throwing when the requested range exceeds the view's bounds. |
169
+ | `decodeText` | function | `(bytes: Uint8Array, encoding?: MSGEncoding) => string` | Decodes bytes into a string with a pure-ES decoder, dispatching on the named encoding. Default: `windows-1252`. |
170
+ | `fileTimeToUTCString` | function | `(low: number, high: number) => string` | Converts a Windows FILETIME (100-ns ticks since 1601-01-01) to a UTC date string. |
171
+ | `toHexLower` | function | `(value: number, length: number) => string` | Converts a number to a zero-padded lowercase hex string of the requested digit count. |
172
+ | `readMicrosoftUUID` | function | `(bytes: Uint8Array, offset: number) => string` | Reads a mixed-endian Microsoft UUID starting at an offset in a byte array, throwing past the array's bounds. |
173
+ | `roundUpToMultiple` | function | `(value: number, boundary: number) => number` | Rounds a value up to the nearest multiple of a boundary, which must be a power of 2. |
174
+ | `computeSectors` | function | `(bytes: number, sectorSize: number) => number` | Computes how many sectors of a given size hold a byte count, answering 0 for a count at or below zero. |
175
+ | `compareCFBName` | function | `(a: string, b: string) => number` | Orders two directory names as the compound file format requires, comparing by UTF-16 length first and then by uppercased code points. |
176
+ | `isMSGFile` | function | `(view: DataView) => boolean` | Reports whether a `DataView`'s first 8 bytes match the CFB magic signature. |
177
+ | `decodeForgivingBase64` | function | `(text: string) => Uint8Array` | Decodes a Base64 string into raw bytes without relying on `atob`, ignoring ASCII whitespace and tolerating missing padding. |
178
+ | `encodeLossyUTF8` | function | `(text: string) => Uint8Array` | Encodes a string into UTF-8 bytes, pairing surrogates and encoding a lone (unpaired) surrogate as U+FFFD. |
179
+ | `decodeLossyUTF8` | function | `(bytes: Uint8Array) => string` | Decodes UTF-8 bytes into a string WHATWG-style: an invalid byte sequence decodes as U+FFFD rather than throwing. |
180
+ | `decodeLossyWindows1252` | function | `(bytes: Uint8Array) => string` | Decodes Windows-1252 bytes into a string, resolving the `0x80`\-`0x9F` range through `WINDOWS_1252_HIGH` and otherwise matching `decodeLatin1` from `@orkestrel/codec`. |
181
+ | `resolveEncoding` | function | `(label: string \| undefined) => MSGEncoding` | Resolves a free-form charset label, as a MIME `charset` parameter carries it, to a supported `MSGEncoding`, falling back to `FALLBACK_CHARSET`'s encoding for an unrecognized or absent label. |
182
+ | `detectFormat` | function | `(name: string \| undefined, mime: string \| undefined) => EmailFormat \| undefined` | Derives the `EmailFormat` from a file name, a MIME type, or both, answering `undefined` when neither hints at a format. |
183
+ | `parseMIMEHeaders` | function | `(text: string) => ReadonlyMap<string, MIMEHeader>` | Parses an RFC 2822 / MIME header block, folding continuation lines. |
184
+ | `decodeMIMEEncoding` | function | `(body: string, encoding: string) => Uint8Array` | Decodes a MIME body — `base64`, `quoted-printable`, or passthrough — into raw bytes, throwing on invalid Base64. |
185
+ | `decodeMIMEText` | function | `(body: string, encoding: string, charset: string) => string` | Decodes a MIME body to text through `decodeMIMEEncoding` and `resolveEncoding`, taking the charset from a free-form label. |
186
+ | `decodeMIMEWords` | function | `(text: string) => string` | Decodes the RFC 2047 encoded words (`=?charset?B/Q?...?=`) in a header value, reading the Base64 (`B`) and quoted-printable (`Q`) forms alike. |
187
+ | `formatEmailAddress` | function | `(name: string \| undefined, email: string \| undefined) => string` | Formats a display name and an email address into `"Name <email>"`, or into whichever half is present. |
188
+ | `inferExtension` | function | `(mimeType?: string, fileName?: string) => string` | Infers an attachment's file extension from its file name or its MIME type, returning the extension with its leading dot and falling back to `.bin`. |
197
189
 
198
190
  ```ts
199
191
  import {
200
- success,
201
- failure,
202
- isSuccess,
203
- isFailure,
204
192
  truncateAtNull,
205
193
  readUTF16String,
206
194
  fileTimeToUTCString,
@@ -210,11 +198,10 @@ import {
210
198
  computeSectors,
211
199
  compareCFBName,
212
200
  isMSGFile,
213
- decodeBase64,
214
- encodeUTF8,
215
- decodeUTF8,
216
- decodeLatin1,
217
- decodeWindows1252,
201
+ decodeForgivingBase64,
202
+ encodeLossyUTF8,
203
+ decodeLossyUTF8,
204
+ decodeLossyWindows1252,
218
205
  resolveEncoding,
219
206
  detectFormat,
220
207
  parseMIMEHeaders,
@@ -231,17 +218,14 @@ computeSectors(100, 64) // 2
231
218
  compareCFBName('a', 'b') // negative
232
219
  isMSGFile(new DataView(new Uint8Array(8).buffer)) // false — no CFB magic
233
220
  detectFormat('message.eml', undefined) // 'eml'
234
- isSuccess(success(1)) // true
235
- isFailure(failure(new Error())) // true
236
- decodeLatin1(new Uint8Array([65])) // 'A'
237
- decodeWindows1252(new Uint8Array([65])) // 'A'
221
+ decodeLossyWindows1252(new Uint8Array([65])) // 'A'
238
222
  resolveEncoding('utf-8') // 'utf-8'
239
223
  formatEmailAddress('A', 'a@x.dev') // 'A <a@x.dev>'
240
224
  inferExtension('image/png') // '.png'
241
225
  decodeMIMEEncoding('aGk=', 'base64') // Uint8Array of 'hi'
242
226
  decodeMIMEText('aGk=', 'base64', 'utf-8') // 'hi'
243
- encodeUTF8('hi') // Uint8Array
244
- decodeUTF8(new Uint8Array([65])) // 'A'
227
+ encodeLossyUTF8('hi') // Uint8Array
228
+ decodeLossyUTF8(new Uint8Array([65])) // 'A'
245
229
 
246
230
  const view = new DataView(new Uint8Array([0x48, 0x00, 0x69, 0x00]).buffer)
247
231
  readUTF16String(view, 0, 2) // 'Hi'
@@ -305,8 +289,6 @@ parseMIMEPart('Subject: Hi\n\nBody text') // MIMEPart — { headers, body: 'Body
305
289
 
306
290
  The from-unknown guards from [`validators.ts`](../src/core/validators.ts). Each validates an arbitrary `unknown` value from scratch, against the `EmailChain`, `EmailMessage`, or `EmailAttachment` shape, or the `EmailFormat` union, using `isRecord` from `@orkestrel/contract`. `isMSGError` validates the global Error instance, its package brand, its code, and its context.
307
291
 
308
- In a guard table a `Shape` cell holds the type the guard narrows to.
309
-
310
292
  | Name | Kind | Signature | Summary |
311
293
  | ------------------- | -------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
312
294
  | `isEmailFormat` | function | `(value: unknown) => value is EmailFormat` | Narrows an unknown value to a valid `EmailFormat`: a total from-unknown guard, true for `'eml'` and `'msg'`. |
@@ -366,10 +348,11 @@ From [`factories.ts`](../src/core/factories.ts).
366
348
 
367
349
  #### Parse an email file and read its format
368
350
 
369
- Narrows the `createMSG` `Result` with `isSuccess` before reading the parsed `chain`'s format.
351
+ Narrows the `createMSG` `Result` with `isSuccess` from `@orkestrel/contract` before reading the parsed `chain`'s format.
370
352
 
371
353
  ```ts
372
- import { createMSG, isSuccess } from '@orkestrel/msg'
354
+ import { isSuccess } from '@orkestrel/contract'
355
+ import { createMSG } from '@orkestrel/msg'
373
356
 
374
357
  const result = createMSG(bytes)
375
358
  if (isSuccess(result)) {
@@ -396,7 +379,8 @@ The public methods of the behavioral interfaces this package publishes. `options
396
379
  | `attachment` | `MSGAttachment` | Reads attachment binary content by zero-based index, returning its `name` and `bytes`. |
397
380
 
398
381
  ```ts
399
- import { createMSG, isSuccess } from '@orkestrel/msg'
382
+ import { isSuccess } from '@orkestrel/contract'
383
+ import { createMSG } from '@orkestrel/msg'
400
384
 
401
385
  const result = createMSG(bytes) // Uint8Array of a .msg file
402
386
  if (isSuccess(result)) {
@@ -424,8 +408,8 @@ A caller extracting an embedded `.msg` attachment and burning it standalone goes
424
408
  - [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/core` bijection (value and type exports), the `MSGInterface` ↔ `MSG` method bijection, and the equality gate: every `Summary` cell against its declaration's description paragraph, the titled `Parse an email file and read its format` 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.
425
409
  - [`tests/src/core/MSG.test.ts`](../tests/src/core/MSG.test.ts) — construction (`.eml` / `.msg` / malformed input), `chain`, `fields`, `attachment`, `burn`, and the embedded-`.msg` extraction path.
426
410
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — `createMSG`'s `Result` contract (`Success`/`Failure`, with parse failures surfaced as `Failure<MSGError>` rather than thrown).
427
- - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `isMSGFile` / `decodeUTF8` / `detectFormat` / `parseMIMEPart` / `extractMessage` / `extractMessageFromMSG`, incl. `MIME_MAX_DEPTH` cycle guarding.
428
- - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the `Result` constructors/guards, CFB byte/string/UUID readers, and MIME/text codecs.
411
+ - [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) — `isMSGFile` / `decodeLossyUTF8` / `detectFormat` / `parseMIMEPart` / `extractMessage` / `extractMessageFromMSG`, incl. `MIME_MAX_DEPTH` cycle guarding.
412
+ - [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — the CFB byte/string/UUID readers and the MIME/text codecs.
429
413
  - [`tests/src/core/shapers.test.ts`](../tests/src/core/shapers.test.ts) — `burnCFB` validity, mini-stream/FAT/DIFAT boundaries, red-black directory ordering, cycle/name limits, and real-parser round trips.
430
414
  - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — `isEmailFormat` / `isEmailAttachment` / `isEmailMessage` / `isEmailChain` soundness on well-formed and malformed input.
431
415
  - `MSGError` shape and `isMSGError` narrowing are covered across [`tests/src/core/MSG.test.ts`](../tests/src/core/MSG.test.ts), [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts), and [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) — no standalone `errors.test.ts` file exists.
@@ -37,10 +37,6 @@ parser.clear() // drop any buffered partial - ready for a fresh stream
37
37
 
38
38
  ### Types
39
39
 
40
- A `Shape` cell holds an interface's data members as bare names in braces, `?`
41
- marking an optional member and `plus` introducing its call-signature members,
42
- and a type alias's own type literal with a union's arms escaped as `\|`.
43
-
44
40
  | Name | Kind | Signature | Summary |
45
41
  | ----------------------- | --------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
42
  | `NDJSONParserInterface` | interface | `{ parse(), clear() }` | Represents the stateful NDJSON (newline-delimited JSON) stream-parser contract a consumer holds — a `parse` that turns each string chunk into the complete records decoded so far, and a `clear` that drops the buffered partial line. |
@@ -72,8 +72,6 @@ Pass `tools` (a non-empty `ToolDefinition[]` from `@orkestrel/tool`) to advertis
72
72
 
73
73
  ### Surface
74
74
 
75
- 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. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none. A `Shape` cell holds the constant's declared type.
76
-
77
75
  | Name | Kind | Signature | Summary |
78
76
  | -------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
77
  | `createOllama` | function | `(options: OllamaOptions) => ProviderInterface` | Creates a local Ollama inference provider — a `ProviderInterface` over the daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `stream`. |
@@ -173,7 +171,7 @@ The session composes the following validators and protocol helpers, each exporte
173
171
  | `readOllamaBody` | function | `(response: Response, limit: number) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Reads a bounded response and preserves its partial bytes on a transport refusal. |
174
172
  | `readOllamaReply` | function | `(origin: string, path: string, options?: OllamaMetadataOptions, signal?: AbortSignal, request?: OllamaBytes, transport?: OllamaDaemonOptions['fetch']) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Exchanges metadata or unload bytes with a dedicated origin under one complete-request deadline. |
175
173
 
176
- `OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `SessionOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
174
+ `OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `DuplexOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
177
175
 
178
176
  ## Methods
179
177
 
@@ -52,8 +52,6 @@ try {
52
52
 
53
53
  ### Guards
54
54
 
55
- In a guard table a `Shape` cell holds the type the guard narrows to.
56
-
57
55
  | Name | Kind | Signature | Summary |
58
56
  | -------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
59
57
  | `isPoolError` | function | `(value: unknown) => value is PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
@@ -62,8 +60,6 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
62
60
 
63
61
  ### Types
64
62
 
65
- 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 `\|`.
66
-
67
63
  | Name | Kind | Signature | Summary |
68
64
  | ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
65
  | `PoolCode` | type | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'` | Names the machine-readable failure codes produced by `PoolError`. |