@orkestrel/scaffold 0.0.139 → 0.0.141

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 (37) hide show
  1. package/dist/bin/main.js +86 -26
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +2 -1
  4. package/dist/host/claude/agents/orkestrel.md +51 -51
  5. package/dist/host/claude/rules/architecture.md +4 -2
  6. package/dist/host/claude/rules/typescript.md +23 -10
  7. package/dist/host/configs/policy.ts +174 -11
  8. package/dist/host/guides/abort.md +2 -0
  9. package/dist/host/guides/agent.md +447 -531
  10. package/dist/host/guides/browser.md +1 -1
  11. package/dist/host/guides/guide.md +10 -2
  12. package/dist/host/guides/mcp.md +9 -9
  13. package/dist/host/guides/middleware.md +34 -49
  14. package/dist/host/guides/ollama.md +44 -12
  15. package/dist/host/guides/probe.md +1 -2
  16. package/dist/host/guides/scaffold.md +25 -16
  17. package/dist/host/guides/server.md +5 -5
  18. package/dist/host/guides/study.md +2680 -760
  19. package/dist/host/manifest.json +18 -18
  20. package/dist/host/scripts/browsers.sh +0 -0
  21. package/dist/host/scripts/codex.sh +0 -0
  22. package/dist/host/scripts/cursor.sh +0 -0
  23. package/dist/host/scripts/deps.sh +0 -0
  24. package/dist/host/scripts/npm.sh +0 -0
  25. package/dist/host/scripts/ollama.sh +0 -0
  26. package/dist/host/tests/config.test.ts +185 -1
  27. package/dist/src/core/index.cjs +14 -14
  28. package/dist/src/core/index.cjs.map +1 -1
  29. package/dist/src/core/index.js +14 -14
  30. package/dist/src/core/index.js.map +1 -1
  31. package/dist/src/server/index.cjs +6 -24
  32. package/dist/src/server/index.cjs.map +1 -1
  33. package/dist/src/server/index.d.cts +1 -1
  34. package/dist/src/server/index.d.ts +1 -1
  35. package/dist/src/server/index.js +7 -25
  36. package/dist/src/server/index.js.map +1 -1
  37. package/package.json +11 -11
@@ -273,7 +273,7 @@ The core supplies the entities a browser session and an agent use. Its host-spec
273
273
  | `BROWSER_DEFAULT_VIEWPORT_HEIGHT` | const | `720` | Sets the default viewport height, `720` pixels. |
274
274
  | `BROWSER_DEFAULT_VIEWPORT_WIDTH` | const | `1280` | Sets the default viewport width, `1280` pixels. |
275
275
  | `BROWSER_FRAME_WORLD_NAME` | const | `"__orkestrelBrowserFrame"` | Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. |
276
- | `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.34"; }>` | Names the tool identity embedded in HAR 1.2 documents. |
276
+ | `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.35"; }>` | Names the tool identity embedded in HAR 1.2 documents. |
277
277
  | `BROWSER_KEY_MODIFIERS` | const | `Readonly<Record<string, number>>` | Maps a canonical modifier name to its CDP Input modifier bit value. |
278
278
  | `BROWSER_MOUSE_BUTTON_MASKS` | const | `Readonly<Record<BrowserMouseButton, number>>` | Maps each public mouse button to its CDP Input pressed-button bit value. |
279
279
  | `BROWSER_NAVIGATION_REASONS` | const | `readonly BrowserNavigationReason[]` | Lists every CDP `Page.ClientNavigationReason` value a page accepts as a navigation's reason, as of Chromium 141; a page reads any other reason as undefined. |
@@ -128,6 +128,9 @@ workflow paths and usage text come from [`constants.ts`](../src/server/constants
128
128
  | `SURFACE_HEADER` | const | `readonly string[]` | Lists the uniform `## Surface` table header, column by column, that guide construction requires. |
129
129
  | `EXTERNAL_SCHEMES` | const | `readonly string[]` | Lists the link `href` schemes a guides-parity link check skips as external — a link with one of these prefixes (or a bare `#` anchor, handled separately in `isExternalLink`) is never resolved against the filesystem. |
130
130
  | `WRAP_WIDTH` | const | `number` | Holds the default character budget a rewritten doc block's description paragraph wraps inside — the greatest number of characters a re-wrapped line may carry, counted from the line's first character with a tab counting as one, so a wrapped line reads `${indent} * ${text}` and never passes that count. |
131
+ | `WIDE_CHARACTER` | const | `RegExp` | Matches one character that occupies two terminal columns: an emoji presentation character other than a regional indicator, or a character of the East Asian wide and fullwidth classes. |
132
+ | `ZERO_WIDTH` | const | `RegExp` | Matches a character that occupies no terminal column: a nonspacing, enclosing, or extending mark, a format character such as a zero width space, a control character, and the Hangul medial and final jamo, less the format and mark characters the formatter counts one column. |
133
+ | `EMOJI_SEQUENCE` | const | `RegExp` | Matches a grapheme cluster the formatter counts two columns whole: a pictograph sequence joined by a zero width joiner, an emoji followed by a skin-tone modifier, an emoji followed by the emoji variation selector, or a keycap that carries that selector. |
131
134
 
132
135
  ### Server constants
133
136
 
@@ -222,6 +225,8 @@ directly.
222
225
  | `findDrift` | function | `(guide: GuideInterface, source: SourceInterface) => readonly Drift[]` | Finds every disagreement between a guide and the source it documents, naming both sites: each `## Surface` row against its declaration's description paragraph, each present `Signature` cell against the declaration's computed signature written as a code span, each `## Methods` row against its member's, and the first titled guide fence of a heading against the `@example` block of the same title. An example's compared text is its language on the first line and its body beneath, so a fence that names another language drifts on its own. |
223
226
  | `renderSurface` | function | `(symbols: readonly SurfaceSymbol[]) => string` | Renders a uniform `Name \| Kind \| Signature \| Summary` table with one row per symbol, the name as a code span, the keyword as text, and the signature and summary through `buildCell`. An absent signature or summary renders an empty cell, which `extractSurface` reads back as absent. Guide construction refuses an empty signature cell. |
224
227
  | `renderMethods` | function | `(group: MethodGroup) => string` | Renders one `## Methods` group — the `####` heading naming the interface as a code span, then a `Name` and `SUMMARY` table with one row per documented member. A member carrying no summary renders an empty cell, which `extractMethods` reads back as an absent summary. |
228
+ | `computeCellWidth` | function | `(text: string) => number` | Measures how many terminal columns `text` occupies the way the checkout's formatter pads a Markdown table cell: each grapheme cluster counts two columns when it is wide — a character of the East Asian wide and fullwidth blocks, an emoji, or a sequence of them — and otherwise one column per character that has a width, with marks, format characters, and control characters counting none. |
229
+ | `renderMarkdownTable` | function | `(table: TableNode) => string` | Renders `table` as the bytes the checkout's formatter writes for it: every column padded to its widest cell, at least three columns wide, each cell justified to its column's alignment, and a delimiter row of dashes the column's width carrying the alignment's colons. |
225
230
  | `renderExample` | function | `(example: SourceExample) => string` | Renders one `@example` block as the guide fence it pairs with — an H3 heading carrying the block's title, then a fence carrying its language and its code. An untitled block renders the fence alone, because a fence pairs on its nearest preceding heading and an untitled block claims none. |
226
231
  | `buildTable` | function | `(table: TableNode, row: number, column: number, cell: readonly InlineNode[]) => TableNode` | Builds a copy of `table` with one cell's inline content replaced by `cell`. Every other cell keeps its own nodes, so a rewrite touches the one cell it names and the header and the alignment row travel unchanged. |
227
232
  | `buildFence` | function | `(example: SourceExample) => CodeBlockNode` | Builds the fenced code block one `@example` block renders as — its code inside a fence carrying its language, and an untagged fence when the block names none. |
@@ -924,7 +929,10 @@ splices the render over the region through `spliceSpan`. Only the located node's
924
929
  rewritten, so every byte of the guide outside it travels unchanged. `replaceCell` takes the header
925
930
  of the column it writes and the cell's inline content: `--to guide` passes `SUMMARY` with
926
931
  `buildCell(summary)` for a summary, and `SIGNATURE` with one code span carrying the computed
927
- signature, which the render writes with `|` as `\|` and a longer fence around a backtick.
932
+ signature, which the render writes with `|` as `\|` and a longer fence around a backtick. The
933
+ rewritten table renders through `renderMarkdownTable`, which pads every row to the column widths the
934
+ checkout's formatter writes, measured by `computeCellWidth`, so a `--to guide` rewrite leaves a
935
+ guide the formatter's check accepts without a formatter pass.
928
936
 
929
937
  `replaceSummary` and `replaceExample` rewrite one doc block's raw text — its description paragraph,
930
938
  or the body of the `@example` tag carrying a given title. `locateComment` is how a caller finds
@@ -1161,7 +1169,7 @@ const guide =
1161
1169
 
1162
1170
  // The guide's text back, with that one cell replaced and every byte outside the table unchanged.
1163
1171
  replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks a tree.'))
1164
- // '## Surface\n\n| Name | Kind | Signature | Summary |\n| --- | --- | --- | --- |\n| `walk` | function | `() => void` | Walks a tree. |'
1172
+ // '## Surface\n\n| Name | Kind | Signature | Summary |\n| ------ | -------- | ------------ | ------------- |\n| `walk` | function | `() => void` | Walks a tree. |'
1165
1173
  replaceCell(guide, 'function phantom', SUMMARY, buildCell('Absent.')) // undefined — no row carries that key
1166
1174
  replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks the tree.')) === guide // true — the row already carries it
1167
1175
 
@@ -1158,8 +1158,8 @@ present origin requires an exact entry in the shared `origin.origins` list. A de
1158
1158
  that validates upstream sets `origin.enabled` to `false` on the one options value passed to
1159
1159
  the route and the session middleware. No shared session primitive is composed; the store, mint, and stream are
1160
1160
  implemented here. Because the body can only be read once, the middleware
1161
- buffers `request.text()` and forwards a freshly built `Request` carrying that
1162
- text to `next(...)` so the downstream route can re-read it. Omit the
1161
+ reads `request.clone()` and calls `next()` on the one `Request` the server built,
1162
+ so the downstream route reads the body itself. Omit the
1163
1163
  middleware for the byte-identical stateless default. The WebSocket and stdio
1164
1164
  transports are inherently one session per connection, so they carry no
1165
1165
  session header — `createMCPSession` is for the HTTP transport only.
@@ -5852,8 +5852,8 @@ the exact statement:
5852
5852
  response-stream cancellation to `mcp.dispatch`. After origin/body/JSON-RPC/modern-metadata-shape/header
5853
5853
  validation, and only for a request that will dispatch, it synchronously calls the optional
5854
5854
  `MCPCallerHandler` immediately before dispatch; a defined result is added as asserted
5855
- `caller`, while absence is omitted. The session middleware preserves the incoming signal,
5856
- headers, and route state across each forwarded `Request`; the pump awaits
5855
+ `caller`, while absence is omitted. The session middleware calls `next()` on the one `Request` the server built, so the
5856
+ signal, headers, and route state reach the route unchanged; the pump awaits
5857
5857
  the async iterator and never polls. An SSE comment is written every configured
5858
5858
  `keepalive.interval` (default `DEFAULT_MCP_KEEPALIVE_INTERVAL`), so an idle
5859
5859
  streamed response notices a dead client within one interval; this is transport
@@ -6094,7 +6094,8 @@ the exact statement:
6094
6094
  while `enabled: false` delegates each site to an upstream validator. A
6095
6095
  modern-shaped POST passes straight through with `next()`, ignoring
6096
6096
  `Mcp-Session-Id`. Otherwise, for its `path`, it makes the legacy transport
6097
- stateful across its verbs: a `POST` buffers `await request.text()` — resolves a session through
6097
+ stateful across its verbs: a `POST` reads its body text from `request.clone()` (an unusable body, used or locked, reads as
6098
+ absent text and passes through to the route) — resolves a session through
6098
6099
  `readSessionHeader`; a valid id touches the entry and sets
6099
6100
  `context.state.session`; an absent / unknown id whose (guarded) body
6100
6101
  parses to an `initialize` request (`isInitializeRequest`) mints a fresh
@@ -6105,10 +6106,9 @@ the exact statement:
6105
6106
  Other unresolved requests return `rejectUnknownSession()` (`404`). The candidate is stored
6106
6107
  and advertised only after `context.state.initialization` records a successful dispatch
6107
6108
  result, independently of JSON or SSE framing. It
6108
- then forwards a fresh `Request` carrying the buffered text
6109
- (`next(forwarded)`) — never the already-consumed original — so the route
6110
- re-reads the same body, retains front-middleware state for caller extraction,
6111
- injects that pinned revision when a live-session POST
6109
+ then calls `next()` on that same `Request` — so the route reads the body itself
6110
+ and retains front-middleware state for caller extraction — sets the pinned
6111
+ revision on it when a live-session POST
6112
6112
  is headerless, and stamps the response with `MCP_SESSION_HEADER`. A
6113
6113
  live-session POST whose `MCP-Protocol-Version` header names a different
6114
6114
  revision than the session pinned is `400` + `-32020` — a session negotiates its
@@ -81,7 +81,6 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
81
81
 
82
82
  | Name | Kind | Signature | Summary |
83
83
  | --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84
- | `ForeignContract` | interface | `{ expected, is }` | Describes a foreign implementation contract an options key admits — the members its published interface declares, checked as that interface declares them. |
85
84
  | `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the error-rendering battery. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
86
85
  | `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. |
87
86
  | `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
@@ -227,43 +226,31 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
227
226
 
228
227
  ### Contracts
229
228
 
230
- | Name | Kind | Signature | Summary |
231
- | ------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
232
- | `BOUNDARY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { expose?: boolean; report?: (...args: never[]) => unknown; }>>` | Admits `BoundaryOptions` whole for `createBoundary`: a boolean `expose` and a function `report`. |
233
- | `TELEMETRY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ record: (...args: never[]) => unknown; } & {}>>` | Admits `TelemetryOptions` whole for `createTelemetry`: a required function `record`. |
234
- | `COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; encodings?: readonly ("deflate" \| "gzip" \| "identity")[]; filter?: (...args: never[]) => unknown; }>>` | Admits `CompressionOptions` whole for `createCompression`: a non-negative finite `threshold`, an `encodings` array of `Encoding` literals, and a function `filter`. |
235
- | `NODE_COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; filter?: (...args: never[]) => unknown; }>>` | Admits `NodeCompressionOptions` whole for `createNodeCompression`: a non-negative finite `threshold` and a function `filter`. |
236
- | `SECURITY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { frame?: "DENY" \| "SAMEORIGIN" \| false; csp?: string \| false; referrer?: string \| false; permissions?: string \| false; coop?: string \| false; corp?: string \| false; cluster?: string \| false; coep?: string \| boolean; hsts?: string \| boolean; identifier?: false \| Readonly<{} & { trust?: boolean; }>; }>>` | Admits `SecurityOptions` whole for `createSecurity`: each header option is a string or `false`, `coep` and `hsts` are a string or a boolean, and `identifier` is `{ trust? }` or `false`. |
237
- | `CORS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { origin?: string \| readonly string[]; methods?: readonly string[]; headers?: readonly string[]; }>>` | Admits `CORSOptions` whole for `createCORS`: `origin` is a string or a string array, and `methods` and `headers` are string arrays. |
238
- | `DEADLINE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ ms: number; } & { status?: number; }>>` | Admits `DeadlineOptions` whole for `createDeadline`: an integer `ms` from 1 through 2147483647, the range `@orkestrel/timeout` enforces, and an integer `status` from 200 through 599. |
239
- | `FORWARDED_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ proxies: number; } & {}> \| Readonly<{ trusted: readonly string[]; } & {}>>` | Admits `ForwardedOptions` whole for `createForwarded`: exactly one of an integer `proxies` of at least 1 or a `trusted` string array. |
240
- | `ETAG_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { weak?: boolean; }>>` | Admits `ETagOptions` whole for `createETag`: a boolean `weak`. |
241
- | `BEARER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ verify: (...args: never[]) => unknown; } & { header?: string; scheme?: string; challenge?: { readonly [k: string]: string; }; }>>` | Admits `BearerOptions` whole for `createBearer`: a required function `verify`, string `header` and `scheme`, and a `challenge` record of strings. |
242
- | `LIMITER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ max: number; window: number; } & { store?: unknown; capacity?: number; key?: (...args: never[]) => unknown; message?: string; clock?: (...args: never[]) => unknown; policy?: boolean; evict?: (...args: never[]) => unknown; }>>` | Admits `LimiterOptions` whole for `createLimiter`: an integer `max` of at least 1, a positive finite `window`, an integer `capacity` of at least 1, and the declared functions; `store` is a foreign key that `LIMITER_STORE_FOREIGN` checks after admission. |
243
- | `SESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ transport: unknown; } & { store?: unknown; ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; create?: (...args: never[]) => unknown; mint?: (...args: never[]) => unknown; required?: boolean; clock?: (...args: never[]) => unknown; }>>` | Admits `SessionOptions` whole for `createSession`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and the declared functions; `transport` and `store` are foreign keys that `SESSION_TRANSPORT_FOREIGN` and `SESSION_STORE_FOREIGN` check after admission. |
244
- | `COOKIE_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: unknown; } & { name?: string; cookie?: Readonly<{} & { path?: string; domain?: string; maxAge?: number; httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" \| "None" \| "Strict"; }>; }>>` | Admits `CookieTransportOptions` whole for `createCookieTransport`: a string `name`, a required `signer`, checked as a foreign key, and an owned `cookie` record of the six optional members `@orkestrel/server` declares: string `path` and `domain`, a finite number `maxAge` (a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`), boolean `httpOnly` and `secure`, and a `sameSite` of `'Strict'`, `'Lax'`, or `'None'`. |
245
- | `HEADER_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { header?: string; }>>` | Admits `HeaderTransportOptions` whole for `createHeaderTransport`: a string `header`. |
246
- | `SESSION_LIMITS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; }>>` | Admits `SessionLimits` whole for `createDatabaseSessionStore`: positive finite `ttl` and `lifetime`. |
247
- | `MEMORY_SESSION_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemorySessionStoreOptions` whole for `createMemorySessionStore`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and a function `evict`. |
248
- | `MEMORY_LIMITER_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemoryLimiterStoreOptions` whole for `createMemoryLimiterStore`: an integer `capacity` of at least 1 and a function `evict`. |
249
- | `CSRF_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: unknown; } & { cookie?: string; header?: string; field?: string; safe?: readonly string[]; }>>` | Admits `CSRFOptions` whole for `createCSRF`: a required `signer` that `SIGNER_FOREIGN` checks after admission, string `cookie`, `header`, and `field`, and a `safe` string array. |
250
- | `SCOPE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ paths: string \| readonly string[]; handler: (...args: never[]) => unknown; } & {}>>` | Admits the arguments of `only` and `except` whole: `paths` is a string or a string array, and `handler` is a function. |
251
- | `ASSET_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ source: unknown; } & { store?: unknown; }>>` | Admits `AssetOptions` whole for `createAssets`: both keys are foreign, so `ASSET_SOURCE_FOREIGN` and `ASSET_STORE_FOREIGN` check them after admission. |
252
- | `STATIC_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ root: string; } & { prefix?: string; index?: string; dotfiles?: "allow" \| "deny" \| "ignore"; cache?: number; etag?: boolean; fallback?: boolean \| Readonly<{} & { exclude?: string; }>; }>>` | Admits `StaticOptions` whole for `createStatic`: a non-empty string `root`, a non-negative finite `cache`, a `dotfiles` literal, and a `fallback` that is a boolean or `{ exclude? }`. |
253
- | `MULTIPART_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { limits?: Readonly<{} & { file?: Readonly<{} & { size?: number; count?: number; }>; field?: Readonly<{} & { size?: number; count?: number; }>; total?: number; }>; allowed?: readonly string[]; directory?: string; }>>` | Admits `MultipartOptions` whole for `createMultipart`: non-negative finite sizes and totals, non-negative integer counts, a string array `allowed`, and a string `directory`. |
254
- | `UPLOADED_FILE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ field: string; name: string; size: number; mime: string; validated: boolean; status: "moved" \| "staged"; path: string; } & {}>>` | Admits one `UploadedFile` whole for `createUploadedFile`: string `field`, `name`, `mime`, and `path`, a non-negative finite `size`, a boolean `validated`, and a `status` literal. |
255
- | `LIMITER_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `LimiterOptions.store` declares: `consume`. |
256
- | `SESSION_TRANSPORT_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `SessionOptions.transport` declares: `read`, `write`, and `clear`. |
257
- | `SESSION_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `SessionOptions.store` declares: `get`, `set`, and `delete`. |
258
- | `SIGNER_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `CookieTransportOptions.signer` and `CSRFOptions.signer` declare: `sign` and `verify`. |
259
- | `ASSET_SOURCE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `AssetOptions.source` declares: `read`. |
260
- | `ASSET_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `AssetOptions.store` declares: `get`, `set`, and `delete`. |
261
-
262
- ### Combinators
263
-
264
- | Name | Kind | Signature | Summary |
265
- | ---------------------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
266
- | `buildForeignContract` | function | `(members: readonly string[]) => ForeignContract` | Builds a `ForeignContract` whose every declared member is a function — the contract an implementation key admits, such as a store, a transport, or a source. |
229
+ | Name | Kind | Signature | Summary |
230
+ | ------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
231
+ | `BOUNDARY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { expose?: boolean; report?: (...args: never[]) => unknown; }>>` | Admits `BoundaryOptions` whole for `createBoundary`: a boolean `expose` and a function `report`. |
232
+ | `TELEMETRY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ record: (...args: never[]) => unknown; } & {}>>` | Admits `TelemetryOptions` whole for `createTelemetry`: a required function `record`. |
233
+ | `COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; encodings?: readonly ("deflate" \| "gzip" \| "identity")[]; filter?: (...args: never[]) => unknown; }>>` | Admits `CompressionOptions` whole for `createCompression`: a non-negative finite `threshold`, an `encodings` array of `Encoding` literals, and a function `filter`. |
234
+ | `NODE_COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; filter?: (...args: never[]) => unknown; }>>` | Admits `NodeCompressionOptions` whole for `createNodeCompression`: a non-negative finite `threshold` and a function `filter`. |
235
+ | `SECURITY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { frame?: "DENY" \| "SAMEORIGIN" \| false; csp?: string \| false; referrer?: string \| false; permissions?: string \| false; coop?: string \| false; corp?: string \| false; cluster?: string \| false; coep?: string \| boolean; hsts?: string \| boolean; identifier?: false \| Readonly<{} & { trust?: boolean; }>; }>>` | Admits `SecurityOptions` whole for `createSecurity`: each header option is a string or `false`, `coep` and `hsts` are a string or a boolean, and `identifier` is `{ trust? }` or `false`. |
236
+ | `CORS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { origin?: string \| readonly string[]; methods?: readonly string[]; headers?: readonly string[]; }>>` | Admits `CORSOptions` whole for `createCORS`: `origin` is a string or a string array, and `methods` and `headers` are string arrays. |
237
+ | `DEADLINE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ ms: number; } & { status?: number; }>>` | Admits `DeadlineOptions` whole for `createDeadline`: an integer `ms` from 1 through 2147483647, the range `@orkestrel/timeout` enforces, and an integer `status` from 200 through 599. |
238
+ | `FORWARDED_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ proxies: number; } & {}> \| Readonly<{ trusted: readonly string[]; } & {}>>` | Admits `ForwardedOptions` whole for `createForwarded`: exactly one of an integer `proxies` of at least 1 or a `trusted` string array. |
239
+ | `ETAG_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { weak?: boolean; }>>` | Admits `ETagOptions` whole for `createETag`: a boolean `weak`. |
240
+ | `BEARER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ verify: (...args: never[]) => unknown; } & { header?: string; scheme?: string; challenge?: { readonly [k: string]: string; }; }>>` | Admits `BearerOptions` whole for `createBearer`: a required function `verify`, string `header` and `scheme`, and a `challenge` record of strings. |
241
+ | `LIMITER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ max: number; window: number; } & { store?: Readonly<{ consume: (...args: never[]) => unknown; } & {}>; capacity?: number; key?: (...args: never[]) => unknown; message?: string; clock?: (...args: never[]) => unknown; policy?: boolean; evict?: (...args: never[]) => unknown; }>>` | Admits `LimiterOptions` whole for `createLimiter`: an integer `max` of at least 1, a positive finite `window`, an integer `capacity` of at least 1, and the declared functions; `store` is an implementation that declares the function `consume`. |
242
+ | `SESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ transport: Readonly<{ read: (...args: never[]) => unknown; write: (...args: never[]) => unknown; clear: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; create?: (...args: never[]) => unknown; mint?: (...args: never[]) => unknown; required?: boolean; clock?: (...args: never[]) => unknown; }>>` | Admits `SessionOptions` whole for `createSession`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and the declared functions; `transport` is an implementation that declares the functions `read`, `write`, and `clear`, and `store` one that declares `get`, `set`, and `delete`. |
243
+ | `COOKIE_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { name?: string; cookie?: Readonly<{} & { path?: string; domain?: string; maxAge?: number; httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" \| "None" \| "Strict"; }>; }>>` | Admits `CookieTransportOptions` whole for `createCookieTransport`: a string `name`, a required `signer` implementation that declares the functions `sign` and `verify`, and an owned `cookie` record of the six optional members `@orkestrel/server` declares: string `path` and `domain`, a finite number `maxAge` (a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`), boolean `httpOnly` and `secure`, and a `sameSite` of `'Strict'`, `'Lax'`, or `'None'`. |
244
+ | `HEADER_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { header?: string; }>>` | Admits `HeaderTransportOptions` whole for `createHeaderTransport`: a string `header`. |
245
+ | `SESSION_LIMITS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; }>>` | Admits `SessionLimits` whole for `createDatabaseSessionStore`: positive finite `ttl` and `lifetime`. |
246
+ | `MEMORY_SESSION_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemorySessionStoreOptions` whole for `createMemorySessionStore`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and a function `evict`. |
247
+ | `MEMORY_LIMITER_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemoryLimiterStoreOptions` whole for `createMemoryLimiterStore`: an integer `capacity` of at least 1 and a function `evict`. |
248
+ | `CSRF_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { cookie?: string; header?: string; field?: string; safe?: readonly string[]; }>>` | Admits `CSRFOptions` whole for `createCSRF`: a required `signer` implementation that declares the functions `sign` and `verify`, string `cookie`, `header`, and `field`, and a `safe` string array. |
249
+ | `SCOPE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ paths: string \| readonly string[]; handler: (...args: never[]) => unknown; } & {}>>` | Admits the arguments of `only` and `except` whole: `paths` is a string or a string array, and `handler` is a function. |
250
+ | `ASSET_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ source: Readonly<{ read: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; }>>` | Admits `AssetOptions` whole for `createAssets`: `source` is an implementation that declares the function `read`, and `store` one that declares `get`, `set`, and `delete`. |
251
+ | `STATIC_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ root: string; } & { prefix?: string; index?: string; dotfiles?: "allow" \| "deny" \| "ignore"; cache?: number; etag?: boolean; fallback?: boolean \| Readonly<{} & { exclude?: string; }>; }>>` | Admits `StaticOptions` whole for `createStatic`: a non-empty string `root`, a non-negative finite `cache`, a `dotfiles` literal, and a `fallback` that is a boolean or `{ exclude? }`. |
252
+ | `MULTIPART_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { limits?: Readonly<{} & { file?: Readonly<{} & { size?: number; count?: number; }>; field?: Readonly<{} & { size?: number; count?: number; }>; total?: number; }>; allowed?: readonly string[]; directory?: string; }>>` | Admits `MultipartOptions` whole for `createMultipart`: non-negative finite sizes and totals, non-negative integer counts, a string array `allowed`, and a string `directory`. |
253
+ | `UPLOADED_FILE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ field: string; name: string; size: number; mime: string; validated: boolean; status: "moved" \| "staged"; path: string; } & {}>>` | Admits one `UploadedFile` whole for `createUploadedFile`: string `field`, `name`, `mime`, and `path`, a non-negative finite `size`, a boolean `validated`, and a `status` literal. |
267
254
 
268
255
  ### Shapers
269
256
 
@@ -298,8 +285,7 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
298
285
  | `verifyCSRFToken` | function | `(signer: SignerInterface, binding: string, token: string) => Promise<boolean>` | Verifies a CSRF token against `binding`: the token's random part must match `CSRF_NONCE_PATTERN`, and its signature must be the signer's HMAC over `CSRF_LABEL`, `binding`, and that random part, under any held key. |
299
286
  | `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. |
300
287
  | `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. |
301
- | `admitForeign` | function | `(door: string, path: readonly string[], foreign: ForeignContract, value: unknown) => void` | Admits one foreign implementation key against the members its published interface declares, accepting a class instance and unknown members. |
302
- | `admitOptions` | function | `<T>(door: string, contract: ContractInterface<T>, value: unknown) => void` | Admits an options bag whole against its compiled contract, refusing a missing required key, an undeclared key, and a value outside a declared range. |
288
+ | `admitOptions` | function | `<T>(door: string, contract: ContractInterface<T>, value: unknown) => void` | Admits an options bag whole against its compiled contract through the contract's `own`, refusing a missing required key, an undeclared key, a value outside a declared range, and an implementation key that lacks a member its `interfaceShape` declares. |
303
289
  | `isPreflight` | function | `(method: string, headers: Headers) => boolean` | Determines whether a request is a CORS preflight — an `OPTIONS` request carrying an `Access-Control-Request-Method` header. |
304
290
  | `buildClient` | function | `(ip: string \| undefined) => Client` | Builds the `Client` slice `createForwarded` stashes, from the resolved client IP — a leaf shaping helper. |
305
291
  | `equalsConstantTime` | function | `(a: string, b: string) => boolean` | Compares two strings in constant time when their lengths match, so a per-character mismatch never changes how long the comparison takes. |
@@ -1113,28 +1099,27 @@ still served through the fallback, because the operator configured that path.
1113
1099
 
1114
1100
  ### Admission: option bags admitted whole
1115
1101
 
1116
- Every factory admits its options bag whole through the strict `admitValue` function of `@orkestrel/contract`, against the compiled contract its options interface declares, before it reads a default. The store classes `MemorySessionStore`, `MemoryLimiterStore`, and `DatabaseSessionStore` admit in their constructors, so a direct `new` call and the factory refuse alike, and their messages lead with the class name. A bag must be a plain object: a class instance, an array, `null`, and a primitive refuse. A bag refuses on an undeclared key such as `origins` for `createCORS`, on a missing required key, on a wrong type, on an explicit `undefined`, and on a number outside its range; a `status` lies from 200 through 599, a `ms` is an integer from 1 through 2147483647 (the range `@orkestrel/timeout` enforces), a size is a non-negative finite number, a count is a non-negative integer, and `NaN` refuses everywhere. An absent bag (`undefined`) admits as `{}`, so a factory with a required key refuses it at that key.
1102
+ Every factory admits its options bag whole through the `own` method of the compiled contract its options interface declares, which reads the bag one time and refuses as the strict `admitValue` function of `@orkestrel/contract` does, against the compiled contract its options interface declares, before it reads a default. The store classes `MemorySessionStore`, `MemoryLimiterStore`, and `DatabaseSessionStore` admit in their constructors, so a direct `new` call and the factory refuse alike, and their messages lead with the class name. A bag must be a plain object: a class instance, an array, `null`, and a primitive refuse. A bag refuses on an undeclared key such as `origins` for `createCORS`, on a missing required key, on a wrong type, on an explicit `undefined`, and on a number outside its range; a `status` lies from 200 through 599, a `ms` is an integer from 1 through 2147483647 (the range `@orkestrel/timeout` enforces), a size is a non-negative finite number, a count is a non-negative integer, and `NaN` refuses everywhere. An absent bag (`undefined`) admits as `{}`, so a factory with a required key refuses it at that key.
1117
1103
 
1118
- Each refusal is a `ContractError`, and the message leads with the factory name. A refusal from `admitOptions` reports the first fault's path in `context.path`, every fault in `cause`, and, for an undeclared key, the declared keys in the message. `createForwarded` admits a union of its two forms, so its refusal carries the root path `[]` and a message that lists both forms. A foreign-key check (`admitForeign`) reports the key as `context.path`, such as `['store']`, with a message of the form `createSession: options.store must be an object with function members get, set, delete`. `renderChallenge` and the `createBearer` refusal of a `challenge` that names `error` report `['scheme']` or `['challenge', name]` as `context.path`, and carry no `cause`.
1104
+ Each refusal is a `ContractError`, and the message leads with the factory name. A refusal from `admitOptions` reports the first fault's path in `context.path`, every fault in `cause`, and, for an undeclared key, the declared keys in the message. `createForwarded` admits a union of its two forms, so its refusal carries the root path `[]` and a message that lists both forms. An implementation key that lacks a declared member reports the member as `context.path`, such as `['store', 'get']`, and a value that is not an object reports the key, such as `['store']`. `renderChallenge` and the `createBearer` refusal of a `challenge` that names `error` report `['scheme']` or `['challenge', name]` as `context.path`, and carry no `cause`.
1119
1105
 
1120
- An implementation key (`LimiterOptions.store`, `SessionOptions.transport`, `SessionOptions.store`, `CookieTransportOptions.signer`, `CSRFOptions.signer`, `AssetOptions.source`, and `AssetOptions.store`) is a foreign contract. The bag's contract carries it as present or absent, and `admitForeign` then checks each member the published interface declares, accepts a class instance and unknown members, and refuses a value that is not an object with every declared member a function, with a `ContractError` at the key. It reports the first implementation key that fails, in one sentence that names every member the interface declares, such as `get, set, delete`; it neither names the member that failed nor reports a fault for each member. The `cookie` record of `CookieTransportOptions` is an owned plain record the caller writes: the bag's contract admits its six members (`path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`) and refuses any other key, so `maxage` refuses. `maxAge` is a finite number because a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`.
1106
+ An implementation key (`LimiterOptions.store`, `SessionOptions.transport`, `SessionOptions.store`, `CookieTransportOptions.signer`, `CSRFOptions.signer`, `AssetOptions.source`, and `AssetOptions.store`) is an `interfaceShape` member of the bag's contract. The shape declares each member the published interface lists as a function. It holds a class instance, a callable, and an object whose prototype carries the members by identity, accepts unknown members, reads each declared member one time on admission and at most two times on a refusal, and refuses a missing member or a member that is not a function with one fault per member at the member's path, such as `['store', 'get']`. The same admission that refuses a malformed bag therefore refuses a malformed implementation key. The `cookie` record of `CookieTransportOptions` is an owned plain record the caller writes: the bag's contract admits its six members (`path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`) and refuses any other key, so `maxage` refuses. `maxAge` is a finite number because a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`.
1121
1107
 
1122
1108
  ```ts
1123
1109
  import {
1124
- admitForeign,
1125
1110
  admitOptions,
1126
- buildForeignContract,
1127
1111
  CORS_CONTRACT,
1128
1112
  DEADLINE_CONTRACT,
1113
+ SESSION_CONTRACT,
1129
1114
  } from '@orkestrel/middleware'
1130
1115
 
1131
1116
  admitOptions('createCORS', CORS_CONTRACT, { origin: ['https://app.example'] }) // returns
1132
1117
  admitOptions('createCORS', CORS_CONTRACT, { origins: ['https://app.example'] }) // throws a ContractError at ['origins']
1133
1118
  admitOptions('createDeadline', DEADLINE_CONTRACT, { ms: 1_000, status: 1000 }) // throws a ContractError at ['status']
1134
1119
 
1135
- const store = buildForeignContract(['get', 'set', 'delete'])
1136
- admitForeign('createSession', ['store'], store, new Map()) // returns: a class instance with the members
1137
- admitForeign('createSession', ['store'], store, {}) // throws a ContractError at ['store']
1120
+ const transport = { read: () => undefined, write: () => undefined, clear: () => undefined }
1121
+ admitOptions('createSession', SESSION_CONTRACT, { transport, store: new Map() }) // returns: a class instance with the members
1122
+ admitOptions('createSession', SESSION_CONTRACT, { transport, store: {} }) // throws a ContractError at ['store', 'get']
1138
1123
  ```
1139
1124
 
1140
1125
  ### Practices
@@ -1303,7 +1288,7 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
1303
1288
  `resolveForwardedFor` matrices, `detectEncodings`, `compressBytes`, buffering-eligibility
1304
1289
  predicates, `transferSessionState`, `matchesSessionState`, `generateNonce`,
1305
1290
  `signCSRFToken` and `verifyCSRFToken` over the malformed-token table, `isPreflight`, `buildClient`,
1306
- `admitOptions` and `admitForeign`, traversal and SPA-fallback resolution, byte-signature matching, node zlib
1291
+ `admitOptions`, traversal and SPA-fallback resolution, byte-signature matching, node zlib
1307
1292
  compression, multipart limit resolution, boundary extraction, part-header
1308
1293
  parsing, `streamFile`'s pull-driven backpressure and descriptor release, and
1309
1294
  the uploaded-file operations, including `moveUploadedFile`'s cross-device