@orkestrel/scaffold 0.0.120 → 0.0.122
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.
- package/dist/agents/skills/orkestrel-dispatch/scripts/brief.js +57 -9
- package/dist/agents/skills/orkestrel-dispatch/scripts/chain.js +22 -2
- package/dist/agents/skills/orkestrel-publish/scripts/pins.js +5 -5
- package/dist/agents/skills/orkestrel-publish/scripts/wave.js +67 -5
- package/dist/bin/main.js +5 -5
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +16 -11
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/references/launch.md +2 -1
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts +65 -9
- package/dist/host/agents/skills/orkestrel-dispatch/scripts/chain.ts +28 -2
- package/dist/host/agents/skills/orkestrel-falsify/references/brief.md +2 -1
- package/dist/host/agents/skills/orkestrel-harden/SKILL.md +8 -8
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +3 -3
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/SKILL.md +10 -8
- package/dist/host/agents/skills/orkestrel-publish/references/release.md +2 -2
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -8
- package/dist/host/agents/skills/orkestrel-publish/references/window.md +5 -1
- package/dist/host/agents/skills/orkestrel-publish/scripts/pins.ts +5 -5
- package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +86 -7
- package/dist/host/claude/AGENTS.md +1 -1
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/opus.md +7 -6
- package/dist/host/claude/agents/orkestrel.md +26 -26
- package/dist/host/claude/agents/planner.md +3 -3
- package/dist/host/claude/agents/reviewer.md +3 -3
- package/dist/host/claude/agents/verifier.md +1 -1
- package/dist/host/claude/rules/campaign.md +3 -2
- package/dist/host/claude/rules/names.md +13 -7
- package/dist/host/claude/rules/tests.md +1 -1
- package/dist/host/claude/rules/workspace.md +9 -0
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +2 -5
- package/dist/host/codex/agents/opus.toml +5 -3
- package/dist/host/codex/agents/planner.toml +6 -5
- package/dist/host/codex/agents/reviewer.toml +4 -7
- package/dist/host/codex/agents/verifier.toml +2 -2
- package/dist/host/dotfiles/gitignore +1 -2
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/scaffold.md +18 -9
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +63 -483
- package/dist/host/tests/config.test.ts +7 -0
- package/dist/src/core/index.cjs +13 -46
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +13 -46
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +10 -9
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +12 -8
- package/dist/src/server/index.d.ts +12 -8
- package/dist/src/server/index.js +10 -9
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -5
- /package/dist/host/agents/skills/orkestrel-parallel/references/{claude.md → claude-code.md} +0 -0
|
@@ -65,24 +65,22 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
65
65
|
|
|
66
66
|
### Middlewares — node
|
|
67
67
|
|
|
68
|
-
| Name
|
|
69
|
-
|
|
|
70
|
-
| `createAssets`
|
|
71
|
-
| `createStatic`
|
|
72
|
-
| `createMultipart`
|
|
73
|
-
| `
|
|
68
|
+
| Name | Kind | Signature | Summary |
|
|
69
|
+
| ----------------------- | -------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation. |
|
|
71
|
+
| `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests. |
|
|
72
|
+
| `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery. |
|
|
73
|
+
| `createNodeCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`, guaranteed on any Node runtime rather than dependent on the WHATWG `CompressionStream` global. This battery is the node-bound sibling of the core face's feature-detected `createCompression`, and both compose the same `compressResponse` skeleton. |
|
|
74
74
|
|
|
75
75
|
### Types
|
|
76
76
|
|
|
77
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
78
|
-
|
|
79
77
|
| Name | Kind | Signature | Summary |
|
|
80
78
|
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
79
|
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
|
|
82
80
|
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
|
|
83
81
|
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
|
|
84
82
|
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
|
|
85
|
-
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each
|
|
83
|
+
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
|
|
86
84
|
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
|
|
87
85
|
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
|
|
88
86
|
| `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
|
|
@@ -117,14 +115,14 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
117
115
|
| `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware/server`) produces per uploaded file. |
|
|
118
116
|
| `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
|
|
119
117
|
| `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
|
|
120
|
-
| `
|
|
118
|
+
| `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
|
|
121
119
|
| `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
|
|
122
120
|
| `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
|
|
123
121
|
| `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
|
|
124
122
|
| `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
|
|
125
123
|
| `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
|
|
126
124
|
| `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
|
|
127
|
-
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures
|
|
125
|
+
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
|
|
128
126
|
| `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
|
|
129
127
|
| `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
|
|
130
128
|
| `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of the pure core's `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared core shape. |
|
|
@@ -166,8 +164,6 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
166
164
|
|
|
167
165
|
### Constants
|
|
168
166
|
|
|
169
|
-
A `Shape` cell holds the constant's declared type.
|
|
170
|
-
|
|
171
167
|
| Name | Kind | Signature | Summary |
|
|
172
168
|
| --------------------------------- | ----- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
173
169
|
| `DEFAULT_COMPRESSION_THRESHOLD` | const | `1024` | Holds `1024`, the default minimum buffered body size in bytes `createCompression` will compress. |
|
|
@@ -198,7 +194,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
198
194
|
| `DEFAULT_CSRF_SAFE_METHODS` | const | `readonly string[]` | Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). |
|
|
199
195
|
| `MULTIPART_STATUS` | const | `Readonly<Record<MultipartErrorCode, number>>` | Holds the HTTP status `createMultipart` renders for each `MultipartErrorCode`: `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415. |
|
|
200
196
|
| `MULTIPART_ERROR_BRAND` | const | `unique symbol` | Holds the `Symbol.for` brand `MultipartError` carries so `isMultipartError` recognizes an instance across duplicate copies of this package — a registry symbol rather than a module-local `Symbol()`, which would mint an unequal symbol per copy. |
|
|
201
|
-
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings
|
|
197
|
+
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings `createNodeCompression` offers — what `node:zlib` guarantees on every Node runtime, so this face never feature-detects. |
|
|
202
198
|
| `DEFAULT_STATIC_INDEX` | const | `"index.html"` | Names `'index.html'`, `createStatic`'s default directory-index filename. |
|
|
203
199
|
| `DEFAULT_STATIC_FALLBACK_EXCLUDE` | const | `"/api"` | Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. |
|
|
204
200
|
| `DEFAULT_STATIC_DOTFILES` | const | `NonNullable<StaticOptions['dotfiles']>` | Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. |
|
|
@@ -215,8 +211,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
215
211
|
|
|
216
212
|
### Shapers
|
|
217
213
|
|
|
218
|
-
A `Shape` cell holds the constant's declared type.
|
|
219
|
-
|
|
220
214
|
| Name | Kind | Signature | Summary |
|
|
221
215
|
| ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
216
|
| `sessionColumns` | const | `{ id: import("@orkestrel/contract").StringShape; session: import("@orkestrel/contract").JSONShape; seen: import("@orkestrel/contract").NumberShape; created: import("@orkestrel/contract").NumberShape; }` | Holds the `@orkestrel/database` column shape for a `SessionRow` table. Pass it as-is to `createDatabase({ tables: { sessions: sessionColumns } })` so an app declaring a durable session table never hand-writes the shape. |
|
|
@@ -237,7 +231,7 @@ A `Shape` cell holds the constant's declared type.
|
|
|
237
231
|
| `matchesUnbufferableResponse` | function | `(method: string, response: Response, skipHeader: string) => boolean` | Checks whether a response must skip the compression and ETag buffering pipeline — the shared cheap-skip predicate both batteries apply before ever touching `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or otherwise bodyless response, an `event-stream` response, and a response already carrying the header the caller is about to set. |
|
|
238
232
|
| `isCompressionNegotiated` | function | `(encoding: Encoding \| undefined) => encoding is Exclude<Encoding, 'identity'>` | Checks whether a negotiated `Accept-Encoding` outcome is worth acting on — `createCompression`'s negotiation-eligibility half of the skip list. |
|
|
239
233
|
| `rebuildResponse` | function | `(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]) => Response` | Rebuilds a `Response` around a replacement body while preserving its status/statusText — the buffered-response reconstruction shared by the compression and ETag batteries after they have consumed `response.arrayBuffer()`. |
|
|
240
|
-
| `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton
|
|
234
|
+
| `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton `createCompression` and `createNodeCompression` compose — response-body compression over a caller-supplied set of feature-detected codings. |
|
|
241
235
|
| `transferSessionState` | function | `(from: SessionInterface, to: SessionInterface) => void` | Copies every entry of one session's `state` into another — the regenerate state-carry `createSession`'s `control.regenerate()` applies. |
|
|
242
236
|
| `sessionExpired` | function | `(cursors: SessionCursors, now: number, limits: SessionLimits) => boolean` | Checks whether a session has aged past its idle timeout or absolute lifetime as of `now` — the pure expiry predicate `MemorySessionStore` delegates to. |
|
|
243
237
|
| `snapshotSession` | function | `(session: SessionInterface) => SessionSnapshot` | Snapshots a session's `state` into a plain, serializable record — the projection a durable store's `set` writes to disk. |
|
|
@@ -250,8 +244,6 @@ A `Shape` cell holds the constant's declared type.
|
|
|
250
244
|
|
|
251
245
|
Each guard in the following table is total: it accepts any input, returns `false` off-shape, and never throws.
|
|
252
246
|
|
|
253
|
-
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
254
|
-
|
|
255
247
|
| Name | Kind | Signature | Summary |
|
|
256
248
|
| ------------------ | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
249
|
| `isSession` | function | `(value: unknown) => value is SessionInterface` | Determines whether a value implements `SessionInterface` — a total structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`, and `clear` mutators. Prototype-agnostic — accepts a plain object, a null-prototype object, and a class instance (a real `Session`), because a restored or stored session is routinely a class instance rather than a literal. |
|
|
@@ -340,9 +332,9 @@ The in-memory lookup seam. `createAssets` validates a request key before it
|
|
|
340
332
|
calls `read`, copies each successful result, and caches that key for the
|
|
341
333
|
factory's lifetime. A miss may be read again later.
|
|
342
334
|
|
|
343
|
-
| Method | Returns
|
|
344
|
-
| ------ |
|
|
345
|
-
| `read` | `
|
|
335
|
+
| Method | Returns | Summary |
|
|
336
|
+
| ------ | ---------------------------------- | ------------------------------------------------------------------------------- |
|
|
337
|
+
| `read` | `AssetRepresentation \| undefined` | Reads one identity or Brotli asset representation for a validated relative key. |
|
|
346
338
|
|
|
347
339
|
#### `SessionInterface`
|
|
348
340
|
|
|
@@ -72,8 +72,6 @@ Pass `tools` (a non-empty `ToolDefinition[]` from `@orkestrel/tool`) to advertis
|
|
|
72
72
|
|
|
73
73
|
### Surface
|
|
74
74
|
|
|
75
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none. A `Shape` cell holds the constant's declared type.
|
|
76
|
-
|
|
77
75
|
| Name | Kind | Signature | Summary |
|
|
78
76
|
| -------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
77
|
| `createOllama` | function | `(options: OllamaOptions) => ProviderInterface` | Creates a local Ollama inference provider — a `ProviderInterface` over the daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `stream`. |
|
|
@@ -173,7 +171,7 @@ The session composes the following validators and protocol helpers, each exporte
|
|
|
173
171
|
| `readOllamaBody` | function | `(response: Response, limit: number) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Reads a bounded response and preserves its partial bytes on a transport refusal. |
|
|
174
172
|
| `readOllamaReply` | function | `(origin: string, path: string, options?: OllamaMetadataOptions, signal?: AbortSignal, request?: OllamaBytes, transport?: OllamaDaemonOptions['fetch']) => Promise<Pick<OllamaMaintenance, 'response' \| 'status' \| 'error'>>` | Exchanges metadata or unload bytes with a dedicated origin under one complete-request deadline. |
|
|
175
173
|
|
|
176
|
-
`OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `
|
|
174
|
+
`OllamaDaemonInterface` keeps its data members in its row: `url` is the declared origin, `identity` is the verified startup receipt (`undefined` before verification and kept after stop), `maintenance` is every unload attempt in sequence order, and `emitter` is the typed lifecycle surface. Its lifecycle methods are documented under [Methods](#methods). `DuplexOptions` is owned by `@orkestrel/process`, and `EmitterInterface`, `EmitterHooks`, and `EmitterErrorHandler` by `@orkestrel/emitter`; the server face reuses them and redefines none of them.
|
|
177
175
|
|
|
178
176
|
## Methods
|
|
179
177
|
|
|
@@ -5,9 +5,9 @@
|
|
|
5
5
|
|
|
6
6
|
A `Claim`, a `Verdict`, and a `receipt` carry the package. A `Claim` is the question: a case, a
|
|
7
7
|
control that must break, and the TypeScript project both are judged under. A `Verdict` is the
|
|
8
|
-
answer: one `
|
|
9
|
-
one-line summary of the conditions it was reached under, and it exists only when the
|
|
10
|
-
itself.
|
|
8
|
+
answer: one `StageResult` per stage in each phase, the case and the control. A `receipt` is the
|
|
9
|
+
verdict's one-line summary of the conditions it was reached under, and it exists only when the
|
|
10
|
+
claim proved itself.
|
|
11
11
|
|
|
12
12
|
The type stage runs the workspace's own compiler over a mirror of the tree, and the lint and runtime
|
|
13
13
|
stages hold resident Oxlint and Vitest engines. Source: [`src/core`](../src/core),
|
|
@@ -29,8 +29,6 @@ trust with a shell.
|
|
|
29
29
|
The data shapes, from [`types.ts`](../src/core/types.ts). Every property is readonly, and an absent
|
|
30
30
|
optional field is absent rather than empty.
|
|
31
31
|
|
|
32
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
33
|
-
|
|
34
32
|
| Name | Kind | Signature | Summary |
|
|
35
33
|
| ------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
36
34
|
| `Stage` | type | `(typeof PROBE_STAGES)[number]` | Names an inspection a claim passes through, derived from `PROBE_STAGES`. |
|
|
@@ -40,7 +38,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
40
38
|
| `Claim` | interface | `{ project, case, control }` | Carries everything the service needs to produce one verdict. |
|
|
41
39
|
| `Party` | type | `(typeof PROBE_PARTIES)[number]` | Names who must act on an issue or probe failure. |
|
|
42
40
|
| `Issue` | interface | `{ origin, path, message, range? }` | Carries one message a stage reported, where it reported it, and whose fault it names. |
|
|
43
|
-
| `
|
|
41
|
+
| `StageResult` | interface | `{ stage, elapsed, issues }` | Carries one stage's outcome: what it cost and what it reported. |
|
|
44
42
|
| `Toolchain` | interface | `{ typescript, oxlint, vitest }` | Names the tool versions a verdict was produced with. |
|
|
45
43
|
| `Project` | interface | `{ path, digest }` | Names the TypeScript project that judged a verdict's candidate drafts. |
|
|
46
44
|
| `Verdict` | interface | `{ id, digest, toolchain, project, reason?, case, control, elapsed, receipt? }` | Carries the full result of one claim: every stage, for both the case and its control. |
|
|
@@ -51,15 +49,13 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
51
49
|
| `ProbeErrorContext` | interface | `{ stage?, path?, project?, name?, deadline?, value? }` | Carries the structured detail one probe failure reports beside its message. |
|
|
52
50
|
| `ProbeErrorOptions` | interface | `{ origin, code, context?, cause? }` | Configures one probe failure at construction. |
|
|
53
51
|
|
|
54
|
-
A row whose `
|
|
55
|
-
[`## Methods`](#methods); the data members
|
|
52
|
+
A row whose `Signature` cell names members with parentheses carries those members in
|
|
53
|
+
[`## Methods`](#methods); the data members it names without parentheses stay here.
|
|
56
54
|
|
|
57
55
|
### Constants
|
|
58
56
|
|
|
59
57
|
From [`constants.ts`](../src/core/constants.ts). Each is frozen.
|
|
60
58
|
|
|
61
|
-
A `Shape` cell holds the constant's declared type.
|
|
62
|
-
|
|
63
59
|
| Name | Kind | Signature | Summary |
|
|
64
60
|
| ---------------------- | ----- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
61
|
| `PROBE_STAGES` | const | `readonly ["type", "lint", "runtime"]` | Lists the stages a claim passes through, in the order a verdict reports them: `['type', 'lint', 'runtime']`. |
|
|
@@ -96,8 +92,6 @@ Schema. The schema is the wire contract's shape and `isClaim` is the admission r
|
|
|
96
92
|
narrower on `Draft.path`: see
|
|
97
93
|
[The advertised schema is wider than the admission rule](#registering-the-server).
|
|
98
94
|
|
|
99
|
-
A `Shape` cell holds the constant's declared type.
|
|
100
|
-
|
|
101
95
|
| Name | Kind | Signature | Summary |
|
|
102
96
|
| --------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
103
97
|
| `DRAFT_SHAPE` | const | `import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").StringShape; text: import("@orkestrel/contract").StringShape; }, false>` | Describes one proposed file a claim carries. |
|
|
@@ -110,21 +104,19 @@ A `Shape` cell holds the constant's declared type.
|
|
|
110
104
|
Total guards, from [`validators.ts`](../src/core/validators.ts). Each returns a boolean for any
|
|
111
105
|
input and never throws.
|
|
112
106
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
|
116
|
-
|
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `isProject` | const | `Guard<Project>` | Checks whether a value names one resolved TypeScript project and what it contained. |
|
|
127
|
-
| `isVerdict` | const | `Guard<Verdict>` | Checks whether a value carries a complete verdict. |
|
|
107
|
+
| Name | Kind | Signature | Summary |
|
|
108
|
+
| --------------- | ----- | -------------------- | ----------------------------------------------------------------------------------------------- |
|
|
109
|
+
| `isStage` | const | `Guard<Stage>` | Checks whether a value names a stage. |
|
|
110
|
+
| `isParty` | const | `Guard<Party>` | Checks whether a value names a party an issue carries. |
|
|
111
|
+
| `isDraft` | const | `Guard<Draft>` | Checks whether a value carries a proposed file's path and text. |
|
|
112
|
+
| `isCase` | const | `Guard<Case>` | Checks whether a value carries a claim's candidate drafts and its test. |
|
|
113
|
+
| `isControl` | const | `Guard<Control>` | Checks whether a value carries a case plus the stage and reason it must fail for. |
|
|
114
|
+
| `isClaim` | const | `Guard<Claim>` | Checks whether a value carries a project, a case, and a control. |
|
|
115
|
+
| `isIssue` | const | `Guard<Issue>` | Checks whether a value carries one message, its location, and the origin of the fault it names. |
|
|
116
|
+
| `isStageResult` | const | `Guard<StageResult>` | Checks whether a value carries one stage's outcome. |
|
|
117
|
+
| `isToolchain` | const | `Guard<Toolchain>` | Checks whether a value names every resolved tool version. |
|
|
118
|
+
| `isProject` | const | `Guard<Project>` | Checks whether a value names one resolved TypeScript project and what it contained. |
|
|
119
|
+
| `isVerdict` | const | `Guard<Verdict>` | Checks whether a value carries a complete verdict. |
|
|
128
120
|
|
|
129
121
|
### Formatters and the token
|
|
130
122
|
|
|
@@ -133,7 +125,7 @@ Pure leaves, from [`helpers.ts`](../src/core/helpers.ts).
|
|
|
133
125
|
| Name | Kind | Signature | Summary |
|
|
134
126
|
| ---------------------- | -------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
135
127
|
| `formatIssue` | function | `(issue: Issue) => string` | Renders one tool message as a single line an agent can classify and locate. |
|
|
136
|
-
| `
|
|
128
|
+
| `formatStageResult` | function | `(result: StageResult) => string` | Renders one stage's outcome as its summary line followed by every message it reported. |
|
|
137
129
|
| `formatProof` | function | `(verdict: Verdict) => string` | Renders the closing line a rendered verdict ends with: the receipt it earned, or its absence. |
|
|
138
130
|
| `formatReceipt` | function | `(verdict: Verdict) => string` | Renders the smallest text a verdict can travel as: what it judged, and how it ended. |
|
|
139
131
|
| `formatVerdict` | function | `(verdict: Verdict) => string` | Renders a whole verdict as the text an agent reads. |
|
|
@@ -145,8 +137,6 @@ Pure leaves, from [`helpers.ts`](../src/core/helpers.ts).
|
|
|
145
137
|
|
|
146
138
|
From [`types.ts`](../src/server/types.ts).
|
|
147
139
|
|
|
148
|
-
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
149
|
-
|
|
150
140
|
| Name | Kind | Signature | Summary |
|
|
151
141
|
| ---------------------- | --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
152
142
|
| `Inspection` | interface | `{ subject, claim }` | Carries one queued inspection: the case a stage reads and the claim it belongs to. |
|
|
@@ -260,7 +250,7 @@ Pure leaves and workspace readers, from [`helpers.ts`](../src/server/helpers.ts)
|
|
|
260
250
|
| `guardStage` | function | `<T>(stage: Stage, operation: Promise<T>) => Promise<T>` | Guards one stage operation with the stage failure contract. |
|
|
261
251
|
| `findRefusedPaths` | function | `(value: unknown) => readonly string[]` | Names every draft member of a claim-shaped value whose `path` this package's guard refuses. |
|
|
262
252
|
| `normalizeValue` | function | `(workspace: string, value: unknown) => unknown` | Rewrites every workspace-contained absolute path in a value to its workspace-relative form and sorts every record's keys. |
|
|
263
|
-
| `
|
|
253
|
+
| `computeWorkspaceDigest` | function | `(workspace: string, value: unknown) => string` | Computes the canonical digest of one value as it stands in a target workspace. |
|
|
264
254
|
| `captureListeners` | function | `(emitter: EventEmitter, events: readonly string[]) => ListenerCapture` | Records the listeners one emitter carries for a set of events. |
|
|
265
255
|
| `releaseListeners` | function | `(emitter: EventEmitter, capture: ListenerCapture) => void` | Removes every listener one emitter gained for the captured events since its capture. |
|
|
266
256
|
|
|
@@ -288,21 +278,21 @@ The public call-signature members of each behavioral interface, one table per in
|
|
|
288
278
|
|
|
289
279
|
#### `StageInterface`
|
|
290
280
|
|
|
291
|
-
| Method | Returns
|
|
292
|
-
| --------- |
|
|
293
|
-
| `start` | `Promise<void>`
|
|
294
|
-
| `inspect` | `Promise<
|
|
295
|
-
| `destroy` | `Promise<void>`
|
|
281
|
+
| Method | Returns | Summary |
|
|
282
|
+
| --------- | ---------------------- | ---------------------------------------------------------------------- |
|
|
283
|
+
| `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
|
|
284
|
+
| `inspect` | `Promise<StageResult>` | Inspects one case. |
|
|
285
|
+
| `destroy` | `Promise<void>` | Tears down the resident tool or the mirror and releases its resources. |
|
|
296
286
|
|
|
297
287
|
#### `RuntimeStage`
|
|
298
288
|
|
|
299
289
|
The stage implements the preceding `StageInterface` contract.
|
|
300
290
|
|
|
301
|
-
| Method | Returns
|
|
302
|
-
| --------- |
|
|
303
|
-
| `start` | `Promise<void>`
|
|
304
|
-
| `inspect` | `Promise<
|
|
305
|
-
| `destroy` | `Promise<void>`
|
|
291
|
+
| Method | Returns | Summary |
|
|
292
|
+
| --------- | ---------------------- | ---------------------------------------------------------------------- |
|
|
293
|
+
| `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
|
|
294
|
+
| `inspect` | `Promise<StageResult>` | Inspects one case. |
|
|
295
|
+
| `destroy` | `Promise<void>` | Tears down the resident tool or the mirror and releases its resources. |
|
|
306
296
|
|
|
307
297
|
#### `TypeStageInterface`
|
|
308
298
|
|
|
@@ -311,20 +301,20 @@ mirror. Each termination utility has the existing `PROBE_DEADLINE` budget of 30,
|
|
|
311
301
|
run concurrently. POSIX teardown retains `SIGTERM`. Warming settles before mirror removal on either
|
|
312
302
|
host. The termination attempt remains best effort if the host utility fails.
|
|
313
303
|
|
|
314
|
-
| Method | Returns
|
|
315
|
-
| --------- |
|
|
316
|
-
| `start` | `Promise<void>`
|
|
317
|
-
| `inspect` | `Promise<
|
|
318
|
-
| `resolve` | `Promise<Project>`
|
|
319
|
-
| `destroy` | `Promise<void>`
|
|
304
|
+
| Method | Returns | Summary |
|
|
305
|
+
| --------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
306
|
+
| `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
|
|
307
|
+
| `inspect` | `Promise<StageResult>` | Inspects one case, against a caller-named project where the caller names one. |
|
|
308
|
+
| `resolve` | `Promise<Project>` | Resolves one project to the path and digest the stage applies for it. Calls `start()` before reading the project. |
|
|
309
|
+
| `destroy` | `Promise<void>` | Tears down the resident tool or the mirror and releases its resources. |
|
|
320
310
|
|
|
321
311
|
#### `LintStageInterface`
|
|
322
312
|
|
|
323
|
-
| Method | Returns
|
|
324
|
-
| --------- |
|
|
325
|
-
| `start` | `Promise<void>`
|
|
326
|
-
| `inspect` | `Promise<
|
|
327
|
-
| `destroy` | `Promise<void>`
|
|
313
|
+
| Method | Returns | Summary |
|
|
314
|
+
| --------- | ---------------------- | ---------------------------------------------------------------------- |
|
|
315
|
+
| `start` | `Promise<void>` | Begins the warm or joins the warm already begun. |
|
|
316
|
+
| `inspect` | `Promise<StageResult>` | Inspects one case, under the bound the caller supplies. |
|
|
317
|
+
| `destroy` | `Promise<void>` | Tears down the resident tool or the mirror and releases its resources. |
|
|
328
318
|
|
|
329
319
|
#### `OverlayInterface`
|
|
330
320
|
|
|
@@ -377,13 +367,13 @@ keeps one commit checked out at two paths reading as one claim. A claim carrying
|
|
|
377
367
|
therefore digests the same in every workspace; a claim that carries one digests per workspace, so
|
|
378
368
|
compare two such tokens only when both were minted against the same tree.
|
|
379
369
|
|
|
380
|
-
`prove` runs every stage over the case, then every stage over the control, and returns one
|
|
381
|
-
per stage for each. A stage that cannot start throws rather than returning an empty
|
|
382
|
-
verdict ever reports a stage that did not run.
|
|
370
|
+
`prove` runs every stage over the case, then every stage over the control, and returns one
|
|
371
|
+
`StageResult` per stage for each. A stage that cannot start throws rather than returning an empty
|
|
372
|
+
stage result, so no verdict ever reports a stage that did not run.
|
|
383
373
|
|
|
384
374
|
The receipt is minted on these conditions together:
|
|
385
375
|
|
|
386
|
-
- both phases report one
|
|
376
|
+
- both phases report one stage result per stage; and
|
|
387
377
|
- the case produced no issue at any stage; and
|
|
388
378
|
- the control produced an `origin: 'claimant'` issue at the stage it declared, and neither phase
|
|
389
379
|
produced an `origin: 'instrument'` issue; and
|
|
@@ -394,10 +384,10 @@ receipt is minted for it. An `origin: 'instrument'` issue in either phase says t
|
|
|
394
384
|
not complete, so nothing was learned about the code and no receipt is minted either. An
|
|
395
385
|
`origin: 'workspace'` issue in the control decides neither break condition: it names the target
|
|
396
386
|
tree rather than the candidate. A case carrying any issue did not run clean and earns no receipt.
|
|
397
|
-
The
|
|
398
|
-
control entries a verdict carries: a control that omits a stage would otherwise read as a
|
|
399
|
-
that stayed clean. `prove` records every stage for both phases, so that condition refuses
|
|
400
|
-
verdict you assembled by hand and passed to `computeReceipt` yourself.
|
|
387
|
+
The one-stage-result-per-stage condition binds both phases, because the clean-elsewhere condition
|
|
388
|
+
reads the control entries a verdict carries: a control that omits a stage would otherwise read as a
|
|
389
|
+
stage that stayed clean. `prove` records every stage for both phases, so that condition refuses
|
|
390
|
+
only a verdict you assembled by hand and passed to `computeReceipt` yourself.
|
|
401
391
|
|
|
402
392
|
`Issue.origin` names the party that must act, and the receipt conditions read that value rather
|
|
403
393
|
than the message beside it. **A `claimant` issue is a tool's diagnostic about a candidate draft,
|
|
@@ -414,8 +404,8 @@ message about an inspection that did not complete — a specification it could n
|
|
|
414
404
|
directory exists, for a reason the target tree does not own, a module that ran no test, or a covered
|
|
415
405
|
module probe's own loader received and did not resolve.
|
|
416
406
|
`formatIssue` renders the value first as `[claimant]`, `[workspace]`, or `[instrument]`, so the
|
|
417
|
-
ownership survives `formatVerdict`. A clean runtime
|
|
418
|
-
that the module reported itself passed.
|
|
407
|
+
ownership survives `formatVerdict`. A clean runtime stage result means every collected test
|
|
408
|
+
passed, not that the module reported itself passed.
|
|
419
409
|
|
|
420
410
|
**A diagnostic about a project belongs to the workspace.** The compiler reports a configuration
|
|
421
411
|
fault — a JSON syntax error, an option it cannot apply, a `types` entry or an extended project it
|
|
@@ -497,12 +487,13 @@ A TypeScript project whose JSON the compiler cannot parse reaches you as that `w
|
|
|
497
487
|
An `instrument` failure carries the same meaning it carries on `Issue.origin`: the inspection did
|
|
498
488
|
not complete, so nothing was learned about the code. Do not read it as evidence about a candidate.
|
|
499
489
|
|
|
500
|
-
**The pure leaves are total over a validated claim and not over every value.**
|
|
501
|
-
`normalizeValue`, and the other exported leaves are written for the
|
|
502
|
-
admit can carry, so a caller that hands one a value `isClaim` would
|
|
503
|
-
`BigInt` — gets the host's own `RangeError` or `TypeError` unchanged
|
|
504
|
-
Measured on 2026-08-20: `
|
|
505
|
-
`RangeError: Maximum call stack size exceeded`, and
|
|
490
|
+
**The pure leaves are total over a validated claim and not over every value.**
|
|
491
|
+
`computeWorkspaceDigest`, `normalizeValue`, and the other exported leaves are written for the
|
|
492
|
+
values a `Claim` the guards admit can carry, so a caller that hands one a value `isClaim` would
|
|
493
|
+
refuse — a cyclic record, a `BigInt` — gets the host's own `RangeError` or `TypeError` unchanged
|
|
494
|
+
rather than a `ProbeError`. Measured on 2026-08-20: `computeWorkspaceDigest(workspace, cyclic)`
|
|
495
|
+
raises `RangeError: Maximum call stack size exceeded`, and
|
|
496
|
+
`computeWorkspaceDigest(workspace, { n: 1n })` raises
|
|
506
497
|
`TypeError: Do not know how to serialize a BigInt`. Validate with `isClaim` before you reach past
|
|
507
498
|
`prove` into a leaf.
|
|
508
499
|
|
|
@@ -532,7 +523,7 @@ and proof waits for type readiness and the boot controls. See [Lifecycle](#lifec
|
|
|
532
523
|
- **That project is composed in the root configuration, not declared as a path string.** The
|
|
533
524
|
runtime stage installs its own overlay plugin into each project's configuration so the candidate
|
|
534
525
|
drafts resolve from memory. A project the root configuration names by path carries no such
|
|
535
|
-
plugin, so the stage installs no overlay and runs no test. The
|
|
526
|
+
plugin, so the stage installs no overlay and runs no test. The stage result carries an
|
|
536
527
|
`origin: 'workspace'` issue, because the party that must act is the workspace owner editing
|
|
537
528
|
`vite.config.ts`:
|
|
538
529
|
`The runtime stage cannot instrument the string-declared Vitest project <name> because its configuration carries no runtime overlay plugin`.
|
|
@@ -785,9 +776,9 @@ import { RuntimeStage } from '@orkestrel/probe/server'
|
|
|
785
776
|
|
|
786
777
|
const runtime = new RuntimeStage(process.cwd())
|
|
787
778
|
try {
|
|
788
|
-
const
|
|
789
|
-
|
|
790
|
-
|
|
779
|
+
const result = await runtime.inspect(claim.case)
|
|
780
|
+
result.stage // 'runtime'
|
|
781
|
+
result.issues // []
|
|
791
782
|
} finally {
|
|
792
783
|
await runtime.destroy()
|
|
793
784
|
}
|
|
@@ -881,12 +872,12 @@ itself.
|
|
|
881
872
|
|
|
882
873
|
The project digest is the digest of the `compilerOptions` member of `tsc --showConfig -p <project>`,
|
|
883
874
|
read against the mirrored copy of the project with the mirror as the current directory, so the
|
|
884
|
-
digest and the check read one set of files. `
|
|
885
|
-
path the project declares that escapes the workspace root resolves against the mirror's
|
|
886
|
-
ancestors, and the mirror carries nothing such a path names. It still **moves with the
|
|
887
|
-
version**, because a compiler decides which options it resolves and how it spells them.
|
|
888
|
-
contained rather than surprising: the token already names `typescript@<version>`, so any
|
|
889
|
-
pinning a digest already pins the version.
|
|
875
|
+
digest and the check read one set of files. `computeWorkspaceDigest` canonicalizes the record: a
|
|
876
|
+
relative path the project declares that escapes the workspace root resolves against the mirror's
|
|
877
|
+
own ancestors, and the mirror carries nothing such a path names. It still **moves with the
|
|
878
|
+
TypeScript version**, because a compiler decides which options it resolves and how it spells them.
|
|
879
|
+
That is contained rather than surprising: the token already names `typescript@<version>`, so any
|
|
880
|
+
policy pinning a digest already pins the version.
|
|
890
881
|
|
|
891
882
|
Further limits belong beside those:
|
|
892
883
|
|
|
@@ -991,7 +982,7 @@ already supply test code the runtime stage runs.
|
|
|
991
982
|
|
|
992
983
|
**A path the workspace's version-control ignore excludes is a path the lint stage reports nothing
|
|
993
984
|
for.** Oxlint's language server honours `.gitignore`, and it does so for text supplied from memory
|
|
994
|
-
exactly as it does for a file on disk. The stage reports a clean
|
|
985
|
+
exactly as it does for a file on disk. The stage reports a clean stage result, not a skipped one.
|
|
995
986
|
|
|
996
987
|
This reaches the flagship claim stated earlier: its test lives at `tmp/probes/greeting.test.ts`, and
|
|
997
988
|
`tmp` is ignored in this workspace, so the lint stage inspects the candidate `src/core/factories.ts`
|
|
@@ -1007,7 +998,7 @@ carries. Put every candidate draft you want linted at a path version control tra
|
|
|
1007
998
|
The lint stage owns the workspace, the candidate's identity, and the projection from a diagnostic to
|
|
1008
999
|
an `Issue`. `@orkestrel/lsp` owns everything between them, and the hookup is fixed:
|
|
1009
1000
|
|
|
1010
|
-
- **The transport is `
|
|
1001
|
+
- **The transport is `createLSPStdioTransport` from `@orkestrel/lsp/server`.** Its command vector
|
|
1011
1002
|
is the current executable, the entry `resolveWorkspaceBinary` resolves for `oxlint` in the target
|
|
1012
1003
|
workspace, and `--lsp`; its directory is that workspace. The child is therefore the workspace's
|
|
1013
1004
|
own installed Oxlint entry rather than a `node_modules/.bin` shim, for the reason the
|