@orkestrel/scaffold 0.0.129 → 0.0.131

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.
@@ -229,7 +229,7 @@ Engine, runner, preflight, and contact-sheet contracts from [`types.ts`](../src/
229
229
  | `CaptureSheetsInterface` | interface | `{ execute() }` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
230
230
  | `CaptureRegistryArguments` | interface | `{ config, variants, mode? }` | Carries the parsed registry command line: the wrapper, the variants to refresh, and the mode. |
231
231
  | `CaptureRegistrarOptions` | interface | `{ root, config, requests, argv, stdout?, stderr?, deadline? }` | Configures one registry refresh: its workspace, wrapper default, request directory, and command line. |
232
- | `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey per producing variant. |
232
+ | `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
233
233
  | `CaptureInputHandler` | type | `(file: string) => string \| undefined` | Reads a contained input through an owning operation's file snapshot memo. |
234
234
  | `CaptureRetractionHandler` | type | `() => void` | Removes one invocation's published request during shutdown. |
235
235
  | `CaptureTerminationHandler` | type | `() => Promise<boolean>` | Begins one independent child termination only after request removal has been attempted. |
@@ -257,7 +257,7 @@ The runner's names and bounds from [`constants.ts`](../src/server/constants.ts).
257
257
  | `CAPTURE_REPORT_LINES` | const | `Readonly<{ readonly preflight: 'READER'; readonly sheets: 'SHEETS'; }>` | Names the first word of the line a reader prints, followed by its JSON report. |
258
258
  | `CAPTURE_SHEET` | const | `Readonly<{ readonly cell: 320; readonly limit: 400; readonly mark: Readonly<{ width: 160; height: 20; present: 220; absent: 20; }>; readonly gap: 12; readonly pairs: 2; readonly rows: 4; }>` | Holds the contact-sheet geometry: how wide a cell shrinks toward, how tall it may grow, the mark that stands in for an unreadable image, the gap between neighbors, and how many cells, rows, and pairs a row and a sheet hold. |
259
259
  | `CAPTURE_SHEET_FILES` | const | `Readonly<{ readonly prefix: 'sheet-'; readonly digits: 3; readonly index: 'index.json'; readonly notes: 'index.md'; }>` | Names the contact-sheet files: the sheet prefix and digits, and the two index documents. |
260
- | `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the stage each producing variant's complete journey runs in, ahead of the variant's name. |
260
+ | `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the one stage a registry refresh runs every selected producing variant's complete journey in. |
261
261
  | `CAPTURE_REGISTRY_LINE` | const | `"REGISTRY"` | Names the first word of the line the registry refresh prints, followed by its JSON summary. |
262
262
  | `CAPTURE_REQUESTS_FLAG` | const | `"CAPTURE_REQUESTS"` | Names the environment variable that carries the absolute request directory to a Vitest child. |
263
263
  | `CAPTURE_DISCOVERY` | const | `Readonly<{ readonly phase: 'discover'; readonly description: 'description.json'; readonly arguments: readonly string[]; readonly deadline: 60000; }>` | Holds the discovery exchange's fixed names and bound. |
@@ -365,7 +365,7 @@ The integrity engine from [`CaptureIntegrity.ts`](../src/server/CaptureIntegrity
365
365
  | `CaptureSheets` | class | `new (options: CaptureSheetOptions) => CaptureSheetsInterface` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
366
366
  | `createCapturePreflight` | function | `(options: CaptureReaderOptions) => CapturePreflightInterface` | Creates the preflight that judges the selected frames' freshness, mixed observations, and coverage. |
367
367
  | `createCaptureSheets` | function | `(options: CaptureSheetOptions) => CaptureSheetsInterface` | Creates the contact-sheet writer for the selected frames. |
368
- | `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey per producing variant. |
368
+ | `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
369
369
  | `createCaptureRegistrar` | function | `(options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Creates the registry refresh that runs each producing variant's complete journey and publishes the registry. |
370
370
  | `CaptureCLI` | class | `new (options?: CaptureCLIOptions) => CaptureCLIInterface` | Dispatches capture commands and maps usage and evidence refusals to their exit codes. |
371
371
  | `createCaptureCLI` | function | `(options?: CaptureCLIOptions) => CaptureCLIInterface` | Creates the executable's command dispatcher over a workspace and injected writers. |
@@ -646,7 +646,7 @@ A module that cannot be loaded, exports no list of functions, or holds a reader
646
646
 
647
647
  ### Registry refresh
648
648
 
649
- The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and each execution child. It takes the same invocation entity and request file, and runs one stage per producing variant with the `all` selector, the `journey` command, and no capture variable.
649
+ The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and the execution child. It takes the same invocation entity and request file, and runs every selected producing variant in one stage, one Vitest child that receives each variant's project, with the `all` selector, the `journey` command, and no capture variable.
650
650
 
651
651
  Refresh a selected producing variant through the registrar:
652
652
 
@@ -666,7 +666,7 @@ const exit = await registrar.execute() // 0 when the registry was published
666
666
 
667
667
  **Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks their schemas. An unreadable or unsupported document refuses the refresh and names the file to inspect and repair before retrying. Publication still authenticates inherited evidence through the integrity engine.
668
668
 
669
- **Stages.** The stage for a variant is named `registry-<variant>`, so each variant's records sit under `<directory>/runs/<id>/registry-<variant>/`. The command takes the project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. It then reads the reporter and the final record, requires the record to carry the stage's own request, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration, and to be complete, and builds one receipt from them: the variant, the record's time, the reporter's path and digest, the input hashes, and the record's declarations and registry.
669
+ **Stages.** The one stage is named `registry`, so its reporter is `<requests>/runs/<id>/registry.json` and each variant's record is `<directory>/runs/<id>/registry/<variant>.json`. A partial refresh runs only the named variants in that stage. The command takes each selected project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. A child that exits unsuccessfully refuses the refresh with a message that names the stage and its variants. The command then reads the reporter once and, for each variant, reads the final record, requires it to carry the stage's own request, to name the variant, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration of that variant, and to be complete, and builds one receipt from them: the variant, the record's time, the reporter's path and digest, the input hashes, and the record's declarations and registry. Every receipt the stage builds names the same reporter and digest.
670
670
 
671
671
  **Publication.** `buildCaptureRegistry` imports the receipts only after each exit is zero and each reporter digest still equals its receipt. The registry is written to a candidate beside `registry.json`, read back through the integrity engine pointed at the candidate, and only then renamed over the target, so a registry the engine would refuse never replaces a good one and the old bytes survive a failed or interrupted refresh. The command prints one `REGISTRY` line of JSON: the file, the digest, the variants in the registry, the variants this run refreshed, and the entry count.
672
672
 
@@ -55,8 +55,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
55
55
  | `createDeadline` | function | `<TState>(options: DeadlineOptions) => MiddlewareHandler<TState>` | Creates the application-level per-request deadline battery. |
56
56
  | `createForwarded` | function | `<TState extends ClientState & ConnectionState>(options: ForwardedOptions) => MiddlewareHandler<TState>` | Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past the hops its options declare trusted. |
57
57
  | `createETag` | function | `<TState>(options?: ETagOptions) => MiddlewareHandler<TState>` | Creates the dynamic response `ETag` + conditional GET battery (RFC 7232). |
58
- | `createBearer` | function | `<TState extends BearerState>(options: BearerOptions) => MiddlewareHandler<TState>` | Creates the bearer-token authentication battery — reads the token from its header and verifies it with `verifyToken`. |
59
- | `createLimiter` | function | `<TState extends BearerState & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>` | Creates the fixed-window rate-limiting battery — checks a key's budget before consuming it, so one window admits exactly `max` requests. |
58
+ | `createBearer` | function | `<TState extends BearerState<TCredential>, TCredential = string>(options: BearerOptions<TCredential>) => MiddlewareHandler<TState>` | Creates the bearer-token authentication battery — reads the token from its header, resolves its credential through `verify`, and answers each `401` with a `WWW-Authenticate` challenge. |
59
+ | `createLimiter` | function | `<TState extends BearerState<unknown> & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>` | Creates the fixed-window rate-limiting battery — checks a key's budget before consuming it, so one window admits exactly `max` requests. |
60
60
  | `createBody` | function | `<TState extends BodyState = BodyState>() => MiddlewareHandler<TState>` | Creates the body-driving battery — eagerly awaits the cached `context.body()` so its throws (or a malformed-JSON `undefined`) surface before the handler runs, and stashes the resolved value onto `BodyState.body`. |
61
61
  | `createSession` | function | `<S extends SessionInterface = SessionInterface, TState extends SessionState & ConnectionState = SessionState & ConnectionState>(options: SessionOptions<S, TState>) => MiddlewareHandler<TState>` | Creates the generic session battery — resolves, mints, and persists a session across the request, with a mid-handler `regenerate`/`destroy` control handle. |
62
62
  | `createCSRF` | function | `<TState extends CSRFState & SessionState & ConnectionState>(options: CSRFOptions) => MiddlewareHandler<TState>` | Creates the session-bound double-submit CSRF protection battery. |
@@ -74,60 +74,61 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
74
74
 
75
75
  ### Types
76
76
 
77
- | Name | Kind | Signature | Summary |
78
- | --------------------------- | --------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
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. |
81
- | `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
82
- | `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
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. |
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. |
85
- | `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
86
- | `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
87
- | `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline. |
88
- | `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver. |
89
- | `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET. |
90
- | `BearerOptions` | interface | `{ secret, header?, scheme? }` | Configures `createBearer` — bearer-token authentication. |
91
- | `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting. |
92
- | `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state` once a token verifies. |
93
- | `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled. |
94
- | `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes. |
95
- | `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes. |
96
- | `ConnectionState` | interface | `{ connection? }` | Describes the connection-facts state slice `createLimiter`'s default key derivation falls back to when neither `BearerState` nor `ClientState` is present — the raw socket peer surfaced on `context.state` by the server's `state` option. |
97
- | `SessionInterface` | interface | `{ id, state, set(), delete(), clear() }` | Represents a server-managed session's public surface — an id, its live state, and the mutators that write it. |
98
- | `SessionControlInterface` | interface | `{ destroyed, successor, regenerate(), destroy() }` | Describes the mid-handler control handle `createSession` stashes alongside the session itself — the OWASP anti-fixation / logout primitives. |
99
- | `SessionState` | interface | `{ session?, control? }` | Describes the session state slice `createSession` stashes. |
100
- | `BodyState` | interface | `{ body? }` | Describes the body state slice `createBody` stashes. |
101
- | `SessionStoreInterface` | interface | `{ get(), set(), delete() }` | Describes the pluggable session persistence seam `createSession`'s `store` option implements — a point-access store keyed by session id. |
102
- | `SessionTransportInterface` | interface | `{ read(), write(), clear() }` | Describes the transport seam `createSession`'s `transport` option implements — how a session id travels to and from the client (a signed cookie, a header, …). |
103
- | `SessionOptions` | interface | `{ transport, store?, ttl?, lifetime?, capacity?, evict?, create?, mint?, required?, clock? }` | Configures `createSession` — the generic session battery. |
104
- | `CookieTransportOptions` | interface | `{ name?, secret, cookie? }` | Configures `createCookieTransport` — the signed-cookie `SessionTransportInterface`. |
105
- | `HeaderTransportOptions` | interface | `{ header? }` | Configures `createHeaderTransport` — the bare-header `SessionTransportInterface`. |
106
- | `MemorySessionStoreOptions` | interface | `{ capacity?, evict? }` | Configures `createMemorySessionStore` — the default in-process `SessionStoreInterface`. |
107
- | `SessionLimits` | interface | `{ ttl?, lifetime? }` | Describes the idle and absolute-lifetime thresholds a session store enforces — `sessionExpired`'s limits argument and both shipped stores' construction options. |
108
- | `SessionCursors` | interface | `{ seen, created }` | Describes the per-session instants a store stamps and `sessionExpired` measures against. |
109
- | `SessionRow` | interface | `{ id, session }` | Represents one persisted session row — an opaque snapshot column plus the store-owned idle/absolute-lifetime cursors, the shape a `DatabaseSessionStore`'s backing table holds. |
110
- | `SessionEntry` | interface | `{ session }` | Represents one in-process session entry — the payload `MemorySessionStore` holds against an id, alongside the same cursors a persisted row carries. |
111
- | `SessionSnapshot` | interface | `{ id, state }` | Represents a session's serializable projection — the value `snapshotSession` produces and a durable store's `set` writes. |
112
- | `SessionRestoreFunction` | type | `(value: unknown) => SessionInterface \| undefined` | Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed. |
113
- | `CSRFState` | interface | `{ csrf? }` | Describes the CSRF state slice `createCSRF` stashes — the raw token a safe-method response exposes for a subsequent mutating request to submit back. |
114
- | `CSRFOptions` | interface | `{ secret, cookie?, header?, field?, safe? }` | Configures `createCSRF` — session-bound double-submit CSRF protection. |
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. |
116
- | `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
117
- | `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
118
- | `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
119
- | `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
120
- | `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
121
- | `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
122
- | `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
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. |
124
- | `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
125
- | `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
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. |
127
- | `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
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. |
129
- | `PartHeaders` | interface | `{ name, filename, mime }` | Describes one multipart part's parsed header block — `parsePartHeaders`'s return shape. |
130
- | `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
77
+ | Name | Kind | Signature | Summary |
78
+ | --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
+ | `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
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. |
81
+ | `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
82
+ | `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
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. |
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. |
85
+ | `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
86
+ | `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
87
+ | `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline. |
88
+ | `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver. |
89
+ | `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET. |
90
+ | `BearerOptions` | interface | `{ verify, header?, scheme?, challenge? }` | Configures `createBearer` — bearer-token authentication. |
91
+ | `BearerVerifyFunction` | type | `(token: string, request: Request) => TCredential \| undefined \| Promise<TCredential \| undefined>` | Verifies a presented bearer token and resolves its credential, or `undefined` to refuse it. |
92
+ | `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting. |
93
+ | `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state` once a token verifies. |
94
+ | `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled. |
95
+ | `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes. |
96
+ | `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes. |
97
+ | `ConnectionState` | interface | `{ connection? }` | Describes the connection-facts state slice `createLimiter`'s default key derivation falls back to when neither `BearerState` nor `ClientState` is present — the raw socket peer surfaced on `context.state` by the server's `state` option. |
98
+ | `SessionInterface` | interface | `{ id, state, set(), delete(), clear() }` | Represents a server-managed session's public surface — an id, its live state, and the mutators that write it. |
99
+ | `SessionControlInterface` | interface | `{ destroyed, successor, regenerate(), destroy() }` | Describes the mid-handler control handle `createSession` stashes alongside the session itself — the OWASP anti-fixation / logout primitives. |
100
+ | `SessionState` | interface | `{ session?, control? }` | Describes the session state slice `createSession` stashes. |
101
+ | `BodyState` | interface | `{ body? }` | Describes the body state slice `createBody` stashes. |
102
+ | `SessionStoreInterface` | interface | `{ get(), set(), delete() }` | Describes the pluggable session persistence seam `createSession`'s `store` option implements — a point-access store keyed by session id. |
103
+ | `SessionTransportInterface` | interface | `{ read(), write(), clear() }` | Describes the transport seam `createSession`'s `transport` option implements — how a session id travels to and from the client (a signed cookie, a header, …). |
104
+ | `SessionOptions` | interface | `{ transport, store?, ttl?, lifetime?, capacity?, evict?, create?, mint?, required?, clock? }` | Configures `createSession` — the generic session battery. |
105
+ | `CookieTransportOptions` | interface | `{ name?, secret, cookie? }` | Configures `createCookieTransport` — the signed-cookie `SessionTransportInterface`. |
106
+ | `HeaderTransportOptions` | interface | `{ header? }` | Configures `createHeaderTransport` — the bare-header `SessionTransportInterface`. |
107
+ | `MemorySessionStoreOptions` | interface | `{ capacity?, evict? }` | Configures `createMemorySessionStore` — the default in-process `SessionStoreInterface`. |
108
+ | `SessionLimits` | interface | `{ ttl?, lifetime? }` | Describes the idle and absolute-lifetime thresholds a session store enforces — `sessionExpired`'s limits argument and both shipped stores' construction options. |
109
+ | `SessionCursors` | interface | `{ seen, created }` | Describes the per-session instants a store stamps and `sessionExpired` measures against. |
110
+ | `SessionRow` | interface | `{ id, session }` | Represents one persisted session row — an opaque snapshot column plus the store-owned idle/absolute-lifetime cursors, the shape a `DatabaseSessionStore`'s backing table holds. |
111
+ | `SessionEntry` | interface | `{ session }` | Represents one in-process session entry — the payload `MemorySessionStore` holds against an id, alongside the same cursors a persisted row carries. |
112
+ | `SessionSnapshot` | interface | `{ id, state }` | Represents a session's serializable projection — the value `snapshotSession` produces and a durable store's `set` writes. |
113
+ | `SessionRestoreFunction` | type | `(value: unknown) => SessionInterface \| undefined` | Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed. |
114
+ | `CSRFState` | interface | `{ csrf? }` | Describes the CSRF state slice `createCSRF` stashes — the raw token a safe-method response exposes for a subsequent mutating request to submit back. |
115
+ | `CSRFOptions` | interface | `{ secret, cookie?, header?, field?, safe? }` | Configures `createCSRF` — session-bound double-submit CSRF protection. |
116
+ | `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. |
117
+ | `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
118
+ | `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
119
+ | `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
120
+ | `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
121
+ | `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
122
+ | `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
123
+ | `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
124
+ | `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
125
+ | `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
126
+ | `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
127
+ | `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. |
128
+ | `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
129
+ | `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. |
130
+ | `PartHeaders` | interface | `{ name, filename, mime }` | Describes one multipart part's parsed header block — `parsePartHeaders`'s return shape. |
131
+ | `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
131
132
 
132
133
  ### Store and response types
133
134
 
@@ -183,6 +184,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
183
184
  | `DEFAULT_DEADLINE_STATUS` | const | `503` | Holds `503`, the default response status `createDeadline` returns when its deadline fires first. |
184
185
  | `DEFAULT_BEARER_HEADER` | const | `"authorization"` | Names `'authorization'`, the default header `createBearer` reads the token from. |
185
186
  | `DEFAULT_BEARER_SCHEME` | const | `"Bearer"` | Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. |
187
+ | `CHALLENGE_TOKEN` | const | `Readonly<RegExp>` | Matches an RFC 9110 `token`, the form a challenge scheme and an auth-param name take. |
188
+ | `CHALLENGE_VALUE` | const | `Readonly<RegExp>` | Matches the characters RFC 6750 § 3 admits in a quoted auth-param value: `%x20-21 / %x23-5B / %x5D-7E`. |
186
189
  | `DEFAULT_LIMITER_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. |
187
190
  | `DEFAULT_LIMITER_MESSAGE` | const | `"rate limit exceeded"` | Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. |
188
191
  | `DEFAULT_SESSION_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. |
@@ -219,7 +222,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
219
222
 
220
223
  | Name | Kind | Signature | Summary |
221
224
  | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
222
- | `resolveKey` | function | `(state: BearerState & ClientState & ConnectionState) => string` | Derives `createLimiter`'s default rate-limit bucket key from a request's resolved identity facts. |
225
+ | `resolveKey` | function | `(state: BearerState<unknown> & ClientState & ConnectionState) => string` | Derives `createLimiter`'s default rate-limit bucket key from a request's resolved identity facts. |
226
+ | `renderChallenge` | function | `(scheme: string, parameters?: Readonly<Record<string, string>>) => string` | Renders a `WWW-Authenticate` challenge as the scheme alone, or the scheme followed by quoted auth-params in the record's own key order. |
223
227
  | `resolveOptInHeader` | function | `(value: string \| boolean \| undefined, fallback: string) => string \| undefined` | Resolves an opt-in, value-bearing security header — `string \| boolean` (off by default, `true` uses the secure default), the shape `createSecurity`'s `coep`/`hsts` options use, distinct from the plain value-or-`false` shape `resolveSecurityHeader` (the peer substrate) handles. |
224
228
  | `buildRetryAfter` | function | `(expiry: number, now: number) => string` | Builds the `Retry-After` header value — whole seconds until a window reset, floored at a minimum of `1`. |
225
229
  | `buildRateLimitField` | function | `(remaining: number, expiry: number, now: number) => string` | Builds the draft `RateLimit` structured header field — emitted only when `createLimiter`'s `policy` option is `true`. |
@@ -450,8 +454,9 @@ prevents:
450
454
  over the uncompressed representation — hashing the compressed bytes
451
455
  would break revalidation the instant the negotiated coding changes.
452
456
  11. **`createBearer` sits before `createLimiter`.** The limiter's default key
453
- derivation prefers `BearerState.token` (the `token:<value>` idiom) over
454
- a client-IP fallback — bearer must have already stashed it.
457
+ derivation prefers a string `BearerState.token` (the `token:<value>` idiom)
458
+ over a client-IP fallback — bearer must have already stashed it. An object
459
+ credential never keys the limiter: the key falls through to the client address.
455
460
  12. **`createBody` sits before `createSession`/`createCSRF`.** `createSession`'s
456
461
  async `mint` and `createCSRF`'s `_csrf` body-field read both need the
457
462
  cached `context.body()` already resolved.
@@ -469,9 +474,14 @@ prevents:
469
474
  `crypto.randomUUID()` instead; a custom `csp` string replaces the
470
475
  default wholesale (never merges); `X-Content-Type-Options: nosniff` is
471
476
  unconditional, with no opt-out.
472
- 16. **Bearer.** `verifyToken` is total over garbage, tampered, expired, or
473
- empty-rotation input — every failure renders `401`, never a crash;
474
- verification is constant-time through `crypto.subtle.verify`.
477
+ 16. **Bearer.** `createBearer` returns a `401` for a missing, wrong-scheme, or empty token
478
+ and for a credential `verify` refuses, and a throw from `verify` propagates
479
+ unchanged. With `verify: (token) => verifyToken(token, secret)`, `verifyToken` is
480
+ total over garbage, tampered, expired, or empty-rotation input — every failure
481
+ renders `401`, never a crash; verification is constant-time through
482
+ `crypto.subtle.verify`. The `401` is a returned response, so each outer
483
+ battery decorates it and `createBoundary`'s `report` never sees it; read
484
+ refusals from `createTelemetry`'s status.
475
485
  17. **Limiter.** The key derivation never reads `X-Forwarded-For` itself (only
476
486
  `createForwarded`'s already-resolved `ClientState` does, when mounted) —
477
487
  so an unmounted `createForwarded` leaves XFF completely untrusted;
@@ -566,6 +576,14 @@ prevents:
566
576
  fail-open. Whichever combinator is used, keep its path set in lockstep
567
577
  with the router's actual routes — a route added after the fact and not
568
578
  added to the set is silently unscoped.
579
+ 26. **Challenge.** Every `401` `createBearer` returns carries a `WWW-Authenticate`
580
+ challenge (RFC 9110 § 15.5.2). A missing, wrong-scheme, or empty token renders
581
+ the configured `challenge` auth-params, and a refused credential adds
582
+ `error="invalid_token"` (RFC 6750 § 3). `renderChallenge` refuses a scheme or
583
+ parameter name that is not a `token`, two names that match ignoring case, and a
584
+ value outside `%x20-21 / %x23-5B / %x5D-7E`; it never escapes or strips. `createBearer`
585
+ refuses a `challenge` that names `error` at construction, because the battery
586
+ owns that parameter.
569
587
 
570
588
  ## Patterns
571
589
 
@@ -598,7 +616,7 @@ import type {
598
616
  IdentifierState,
599
617
  SessionState,
600
618
  } from '@orkestrel/middleware'
601
- import { compose } from '@orkestrel/server'
619
+ import { compose, verifyToken } from '@orkestrel/server'
602
620
 
603
621
  interface State extends BearerState, ClientState, CSRFState, IdentifierState, SessionState {
604
622
  readonly connection?: { readonly ip?: string }
@@ -613,7 +631,7 @@ const onion = [
613
631
  createCors({ origin: ['https://app.example'] }),
614
632
  createForwarded({ proxies: 1 }),
615
633
  createETag(),
616
- createBearer({ secret: 'shh' }),
634
+ createBearer({ verify: (token) => verifyToken(token, 'shh') }),
617
635
  createLimiter({ max: 100, window: 60_000 }),
618
636
  createBody(),
619
637
  createSession({ transport: createCookieTransport({ secret: 'shh' }) }),
@@ -992,22 +992,27 @@ Scaffold writes one part of the manifest rather than advising on it: the writabl
992
992
  and `prepublishOnly`. Each sheet face adds its `check:src:<face>` and `build:src:<face>` scripts.
993
993
  Each occupied framework face adds `check:<axis>:vue` and `build:<axis>:vue`; the application face also adds `dev:vue`.
994
994
  Selected showcase pages add `showcase`, `showcase:<framework>`, `build:showcase`, and `build:showcase:<framework>`; application journeys add `test:journey:<framework>`.
995
+ A workspace that plans the application server barrel adds `build:app:barrel`, which has no
996
+ predecessor form. A workspace with the server application adds `serve:build`, which runs `build`
997
+ before `serve` and accepts `npm run build:app:server && npm run serve` as its generated predecessor.
995
998
  Its `test:src:<face>` script accepts, as its generated predecessor, the command that ran the project
996
999
  without building the face first, and `build:src:styles` accepts the styles-only build as the
997
1000
  predecessor of the chain that builds themes after it. A publishing `test` chain joins the region when
998
1001
  it matches byte for byte the planned chain with the generated `test:app`, `test:journey`, and framework
999
1002
  journey invocations inserted after `test:src`, where that blueprint emitted them before.
1000
1003
  `repair` and `overwrite` remove those helper invocations from that exact predecessor.
1001
- The `test` chain also joins the region as a generated predecessor when it runs fewer steps than
1002
- the planned chain and every step it runs is a planned step in the planned
1003
- order, `repair` and `overwrite` write the planned chain in its place. That write lands only when
1004
+ When the `test` or `build:app` chain is a generated predecessor, which runs fewer steps than
1005
+ the planned chain and runs only planned steps in the planned order, that chain joins the region
1006
+ and `repair` and `overwrite` write the planned chain in its place. That write lands only when
1004
1007
  every step the planned chain adds runs a script the manifest declares or the region writes. The
1005
1008
  `test:src` and `test:app` aggregates sit outside the region. Only a private workspace's planned
1006
1009
  chain invokes `test:app`. A chain whose planned form adds an
1007
1010
  aggregate the manifest lacks stays with the package, and the `projects` question keeps its remedy.
1008
- `audit` reports this chain write only through the `projects` question, so a planned step that
1011
+ `audit` reports this `test` chain write only through the `projects` question, so a planned step that
1009
1012
  registers no Vitest project, such as `npm run test:guides`, lands on the next `repair` without an
1010
- earlier advisory. A `test` chain running any other step or order stays maintainer-owned, as do the
1013
+ earlier advisory. `audit` reports no `build:app` chain write, so in a barrel workspace only the
1014
+ `scripts` question's report of a missing `build:app:barrel` script precedes that write. A `test` or
1015
+ `build:app` chain running any other step or order stays maintainer-owned, as do the
1011
1016
  `check`, `build`, `dev`, `serve`, `format`, `lint`, `clean`, and `copy` gate chains. A
1012
1017
  declared value is overwritten only when it is already the value being written or is a recognized
1013
1018
  generated predecessor. The overwrite happens in place,
@@ -1693,7 +1698,9 @@ A workspace that selects `studies` and the `server` application also builds the
1693
1698
  `app/server/index.ts`, because `@orkestrel/study` loads the package under study as ES modules. The
1694
1699
  `appBarrel` factory, the content-owned `configs/app/vite.barrel.config.ts` wrapper, and the
1695
1700
  `build:app:barrel` script exist only under that condition, and `build:app` runs the script after
1696
- `build:app:server`. The build emits the single file `dist/app/server/index.js` with `@app/*` and
1701
+ `build:app:server`. `serve:build` runs `build` before `serve`, so the barrel, which the server
1702
+ build's emptied `dist/app/server` would otherwise lose, and every browser face the server serves are
1703
+ rebuilt. The build emits the single file `dist/app/server/index.js` with `@app/*` and
1697
1704
  `@src/*` specifiers and relative imports inlined, and `node:` and every installed package specifier
1698
1705
  left external. It sets `emptyOutDir` to `false`, so `main.cjs` stays byte-identical. A workspace
1699
1706
  without both conditions plans none of the three. Scaffold's `tests/src/core/templates.test.ts` builds both entries in a
@@ -16,7 +16,7 @@
16
16
  "storage": "agents/orchestration.md",
17
17
  "destination": ".agents/orchestration.md",
18
18
  "executable": false,
19
- "digest": "24c84e5e89148d6da9873e1b49b415e6c86a226fefab0752b6ac0329d8814017"
19
+ "digest": "67e49a59459fba935c1948d26c9b9fa48001e96d3b0fe0cee194ed724ea96c35"
20
20
  },
21
21
  {
22
22
  "storage": "agents/platforms/posix.md",
@@ -28,7 +28,7 @@
28
28
  "storage": "agents/platforms/windows.md",
29
29
  "destination": ".agents/platforms/windows.md",
30
30
  "executable": false,
31
- "digest": "a0c5593da4d898339208686be0c7adc23f1faca6041c84fa54340b83c81d764f"
31
+ "digest": "c852ff9886b2a2d24b8a0d69efe10f58dac37bd217d676c133048c148b5e877e"
32
32
  },
33
33
  {
34
34
  "storage": "agents/skills/enterprise-bootstrap/SKILL.md",
@@ -430,7 +430,7 @@
430
430
  "storage": "agents/skills/orkestrel-parallel/references/t3.md",
431
431
  "destination": ".agents/skills/orkestrel-parallel/references/t3.md",
432
432
  "executable": false,
433
- "digest": "52b9f7b2f6c9505feffdd599442221a030b646d6fa9a1afef0ace04db6eb8ff2"
433
+ "digest": "1669a45b33f53b6b560a65e64c0a13929e2703c4c907b87789518edf4c1b9a95"
434
434
  },
435
435
  {
436
436
  "storage": "agents/skills/orkestrel-parallel/scripts/cases.ts",
@@ -448,7 +448,7 @@
448
448
  "storage": "agents/skills/orkestrel-polish/SKILL.md",
449
449
  "destination": ".agents/skills/orkestrel-polish/SKILL.md",
450
450
  "executable": false,
451
- "digest": "33880efd86b950d4d43ada3e556adab33a14be55ad9764cd7abdb2ce0809d763"
451
+ "digest": "bb30bfc7b29d63176e39e345188e5eec45a14921a40671c9d8a4084c2a2e9512"
452
452
  },
453
453
  {
454
454
  "storage": "agents/skills/orkestrel-polish/agents/openai.yaml",
@@ -628,7 +628,7 @@
628
628
  "storage": "claude/agents/orkestrel.md",
629
629
  "destination": ".claude/agents/orkestrel.md",
630
630
  "executable": false,
631
- "digest": "a7517e676232471f4d4442b2ff7ad7fdeb5f4b2f5385888b16812495c0e3d07b"
631
+ "digest": "74c10351b39d44a2f59609664a42cfdfdcd7cc7e2839ef037e0221be2d04ca86"
632
632
  },
633
633
  {
634
634
  "storage": "claude/agents/planner.md",
@@ -700,7 +700,7 @@
700
700
  "storage": "claude/rules/patterns.md",
701
701
  "destination": ".claude/rules/patterns.md",
702
702
  "executable": false,
703
- "digest": "43920dca62ed88f1f117131f5830085cc709059bdb05ee98d90c807361f1d808"
703
+ "digest": "2ad9c0e6ca3c995fccb1163f52537252b3cc83e2e8ef0ca6365a20811959c942"
704
704
  },
705
705
  {
706
706
  "storage": "claude/rules/portability.md",
@@ -994,7 +994,7 @@
994
994
  "storage": "guides/agent.md",
995
995
  "destination": "guides/agent.md",
996
996
  "executable": false,
997
- "digest": "18ee2db2e6c120f2fbec55642a6230d1b48de5f9b07fa4143f644a3139f159dc"
997
+ "digest": "e254fceecdd111c66193ccaa2ec065ceaaba68a3386a1e4c29000fd02ec69ec9"
998
998
  },
999
999
  {
1000
1000
  "storage": "guides/brief.md",
@@ -1018,7 +1018,7 @@
1018
1018
  "storage": "guides/capture.md",
1019
1019
  "destination": "guides/capture.md",
1020
1020
  "executable": false,
1021
- "digest": "f19b7ea5ea06958756a20422518ace1078fe87bea4eeb89345b12401a0110d58"
1021
+ "digest": "07c53b0e17c49a01d9d71546bebf0890f3d340f6cb3a86f8c99a7eafe8edb2bf"
1022
1022
  },
1023
1023
  {
1024
1024
  "storage": "guides/codec.md",
@@ -1114,7 +1114,7 @@
1114
1114
  "storage": "guides/middleware.md",
1115
1115
  "destination": "guides/middleware.md",
1116
1116
  "executable": false,
1117
- "digest": "d4196f5768d1ff129d530ea0bc123f03a4b73fc206700ea7d8cc54815c85ca70"
1117
+ "digest": "dad75159938cd6179cc542a480b85e758043ba36d3f94a966f2bb42c3adb4049"
1118
1118
  },
1119
1119
  {
1120
1120
  "storage": "guides/msg.md",
@@ -1198,7 +1198,7 @@
1198
1198
  "storage": "guides/scaffold.md",
1199
1199
  "destination": "guides/scaffold.md",
1200
1200
  "executable": false,
1201
- "digest": "655087dbab9aa83f336b353ebbc1faf23eeea3454c184cc3292753ae0901555b"
1201
+ "digest": "9e17c6cdf212c440be057a5336983488329bb67bd66f334b85624d8e457c034a"
1202
1202
  },
1203
1203
  {
1204
1204
  "storage": "guides/sea.md",
@@ -1417,5 +1417,5 @@
1417
1417
  "scripts"
1418
1418
  ],
1419
1419
  "surface": [],
1420
- "digest": "40949d1d08e62f8022e42f51a9bb712b29c6c4d3eb91b55a9661c78671e28e19"
1420
+ "digest": "76a071e6da224c1cfef62b9e73f4f08e16b7cf91ff8a68b9a2464da95eaed082"
1421
1421
  }