@orkestrel/scaffold 0.0.134 → 0.0.135

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +610 -79
  2. package/dist/agents/skills/orkestrel-publish/scripts/wave.js +307 -16
  3. package/dist/bin/main.js +253 -35
  4. package/dist/bin/main.js.map +1 -1
  5. package/dist/host/AGENTS.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
  7. package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +782 -115
  8. package/dist/host/agents/skills/orkestrel-publish/references/release.md +1 -0
  9. package/dist/host/agents/skills/orkestrel-publish/references/wave.md +22 -5
  10. package/dist/host/agents/skills/orkestrel-publish/scripts/wave.ts +379 -27
  11. package/dist/host/claude/agents/orkestrel.md +14 -14
  12. package/dist/host/claude/rules/architecture.md +1 -1
  13. package/dist/host/claude/rules/patterns.md +2 -0
  14. package/dist/host/claude/rules/workspace.md +64 -63
  15. package/dist/host/configs/helpers.ts +88 -67
  16. package/dist/host/dotfiles/oxlintrc.json +1 -57
  17. package/dist/host/guides/agent.md +989 -395
  18. package/dist/host/guides/database.md +357 -342
  19. package/dist/host/guides/middleware.md +5 -5
  20. package/dist/host/guides/ollama.md +41 -42
  21. package/dist/host/guides/scaffold.md +177 -105
  22. package/dist/host/guides/study.md +12 -12
  23. package/dist/host/guides/test.md +158 -46
  24. package/dist/host/guides/toolbox.md +127 -81
  25. package/dist/host/guides/workspace.md +21 -14
  26. package/dist/host/manifest.json +23 -23
  27. package/dist/host/tests/config.test.ts +166 -112
  28. package/dist/src/core/index.cjs +491 -195
  29. package/dist/src/core/index.cjs.map +1 -1
  30. package/dist/src/core/index.d.cts +217 -24
  31. package/dist/src/core/index.d.ts +217 -24
  32. package/dist/src/core/index.js +482 -193
  33. package/dist/src/core/index.js.map +1 -1
  34. package/dist/src/server/index.cjs +18 -8
  35. package/dist/src/server/index.cjs.map +1 -1
  36. package/dist/src/server/index.d.cts +4 -3
  37. package/dist/src/server/index.d.ts +4 -3
  38. package/dist/src/server/index.js +19 -9
  39. package/dist/src/server/index.js.map +1 -1
  40. package/package.json +2 -2
@@ -755,10 +755,10 @@ The `session` column holds the `SessionSnapshot` JSON that `snapshotSession`
755
755
  writes and `createRestoredSession` reads back: `{ id, state }`, where `state`
756
756
  carries the session's entries. The cursor columns are `seen` and `created`. A
757
757
  table still declared with the earlier `lastSeen` and `createdAt` columns fails
758
- closed rather than reading a stale row as live: the table's own read guard
759
- refuses a row that does not satisfy `sessionColumns`, `store.get` resolves
760
- `undefined`, and the row stays in place until the table is migrated or
761
- recreated.
758
+ closed rather than reading a stale row as live: the table raises a `DRIVER`
759
+ `DatabaseError` for a row that does not satisfy `sessionColumns`, `store.get`
760
+ and `store.set` reject with it, and the row stays in place until the table is
761
+ migrated or recreated.
762
762
 
763
763
  ### Session transport seam — direct calls
764
764
 
@@ -1064,7 +1064,7 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
1064
1064
  absolute-lifetime eviction (including the underlying row's removal),
1065
1065
  `created` stamped once and preserved across re-set, guard rejection,
1066
1066
  construction guards, rebuild through the injected restore step, and the
1067
- fail-closed read of a row stored under the earlier cursor columns.
1067
+ propagated `DRIVER` refusal of a row stored under the earlier cursor columns.
1068
1068
  - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) —
1069
1069
  `createCookieTransport`/`createHeaderTransport` round-trips over real
1070
1070
  `Request`/`Response`, `createMemorySessionStore` shallow mirror,
@@ -3,7 +3,7 @@
3
3
  > The Ollama chat provider wire on the `/api/chat` path and the raw judge wire for Mica
4
4
  > on the `/api/generate` path, with shared engines from the `@orkestrel/agent` package.
5
5
 
6
- The package supplies a chat provider wire on the `/api/chat` path and a raw judge wire for Mica on the `/api/generate` path. The `OllamaProvider` class extends the `AgentProvider` engine for chat generation and streaming. The `OllamaJudge` class extends the `AgentJudge` engine for calibrated candidate probabilities. The shared engines own deadlines, transport, headers, and result assembly; see [Agent](agent.md) for their contracts. The server face, `@orkestrel/ollama/server`, owns a dedicated daemon session in Node: it starts a declared Ollama executable on a dedicated loopback port, verifies the executable's version and every declared model digest, unloads the declared models, and stops the process tree it started; see [Daemon session](#daemon-session).
6
+ The package supplies a chat provider wire on the `/api/chat` path and a raw judge wire for Mica on the `/api/generate` path. The `OllamaProvider` class extends the `AgentProvider` engine for chat generation and streaming. The `OllamaJudge` class extends the `AgentJudge` engine for calibrated candidate probabilities. The shared engines own deadlines, transport, headers, and result assembly; see [Agent](agent.md) for their contracts. The server face, `@orkestrel/ollama/server`, owns a dedicated daemon session in Node: it starts a declared Ollama executable on a dedicated loopback port, records the version the daemon reports, verifies every declared model digest, unloads the declared models, and stops the process tree it started; see [Daemon session](#daemon-session).
7
7
 
8
8
  The design is deliberately spare — an external boundary kept honest. Every `unknown` wire value is narrowed through the `@orkestrel/contract` guards (`isRecord`, `isString`) rather than a type assertion. A field the record leaves out reads as absent (empty content, no usage), and a field that is present and malformed refuses as `ProviderError` `'PROTOCOL'`. Every provider call streams: the request always carries `stream: true`, and `generate` drains the same NDJSON path `stream` exposes, so neither call can report content the other would not. The wire `think` flag is configurable through `OllamaOptions.think` (default `false`) and overrideable per call through `ProviderStreamOptions.think`; with `think: true` the daemon returns reasoning on the separate `message.thinking` channel, streamed live as `thinking` deltas. Either way the base's splitter separates any `<think>` span the daemon inlines anyway, so the assembled `content` is clean and the reasoning surfaces as `ProviderResult.thinking`. The agent records that reasoning on the assistant message. The provider's `replay` policy filters stored reasoning at the provider input boundary; the Ollama request mapper omits that reasoning from the wire. A per-call `ProviderStreamOptions.schema` (a JSON schema object, from `@orkestrel/agent`) forwards verbatim as the wire's structured-output `format` field, and is omitted from the request when no schema is supplied. `OllamaOptions.truncate` defaults to `false` and rides every body, so a prompt over the context window refuses instead of losing its earlier turns, and `OllamaOptions.shift` is sent only when set; see [A prompt over the context window](#a-prompt-over-the-context-window). Token usage reuses the `TokenUsage` shape rather than minting its own.
9
9
 
@@ -149,39 +149,39 @@ The raw judge exports the following declarations.
149
149
 
150
150
  The server face, `@orkestrel/ollama/server`, exports the following daemon session declarations. It runs in Node only; [Daemon session](#daemon-session) states the lifecycle these declarations carry.
151
151
 
152
- | Name | Kind | Signature | Summary |
153
- | ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
154
- | `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface` | Creates an unstarted daemon with a snapshot of the caller's declaration and lifecycle hooks. |
155
- | `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface` | Owns a dedicated daemon through verified startup, declared maintenance, and permanent cleanup. |
156
- | `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }` | Owns a dedicated daemon from validated startup through declared-model maintenance and stop. |
157
- | `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }` | Configures a dedicated daemon with explicit executable, endpoint, and model declarations. |
158
- | `OllamaExecutable` | interface | `{ path, digest, version, arguments? }` | Declares the executable identity required before a daemon starts. |
159
- | `OllamaModel` | interface | `{ name, digest }` | Declares a model name and the digest its inventory entry must report. |
160
- | `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }` | Bounds each metadata or unload response independently of the startup deadline. |
161
- | `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }` | Records the executable, endpoint, root process, and model identities verified at startup. |
162
- | `OllamaBytes` | interface | `{ content, size, digest, complete }` | Preserves a bounded HTTP body as base64 with its byte count and SHA-256 digest. |
163
- | `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }` | Records one declared model's unload request and the response observed for that attempt. |
164
- | `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }` | Reports verified startup, recorded unloads, permanent stop, and daemon failures. |
165
- | `ollamaDaemonShape` | const | `import("@orkestrel/contract").ObjectShape<{ executable: import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; version: import("@orkestrel/contract").StringShape; arguments: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; }, boolean \| import("@orkestrel/contract").ContractShape>; url: import("@orkestrel/contract").StringShape; models: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; }, boolean \| import("@orkestrel/contract").ContractShape>>; workspace: import("@orkestrel/contract").StringShape; environment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>>; store: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; readiness: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; metadata: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bytes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; termination: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ grace: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; drain: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; }, false>` | Describes the serializable part of `OllamaDaemonOptions`, the record whose audit names a refused declaration's faults by path. |
166
- | `ollamaDaemonContract` | const | `ContractInterface<unknown>` | Holds the compiled contract whose audit names a refused daemon declaration's faults by path. |
167
- | `OLLAMA_TIMER_LIMIT` | const | `2147483647` | Bounds a daemon duration to 2147483647 milliseconds, the longest a Node timer holds. |
168
- | `OLLAMA_DAEMON_LIVE` | const | `readonly string[]` | Lists the keys of a daemon declaration that hold live values, which no shape declares. |
169
- | `OLLAMA_DAEMON_KEYS` | const | `Readonly<{ daemon: readonly string[]; executable: readonly string[]; model: readonly string[]; metadata: readonly string[]; termination: readonly string[]; }>` | Lists the keys each record of a daemon declaration admits, live values included. |
170
- | `OLLAMA_READINESS` | const | `60000` | Bounds startup through version and model verification to 60000 milliseconds by default. |
171
- | `OLLAMA_METADATA_TIMEOUT` | const | `10000` | Bounds each metadata or unload request and body read to 10000 milliseconds by default. |
172
- | `OLLAMA_METADATA_BYTES` | const | `1048576` | Bounds each retained metadata or unload response to 1048576 bytes by default. |
152
+ | Name | Kind | Signature | Summary |
153
+ | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
154
+ | `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface` | Creates an unstarted daemon with a snapshot of the caller's declaration and lifecycle hooks. |
155
+ | `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface` | Owns a dedicated daemon through verified startup, declared maintenance, and permanent cleanup. |
156
+ | `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }` | Owns a dedicated daemon from validated startup through declared-model maintenance and stop. |
157
+ | `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }` | Configures a dedicated daemon with explicit executable, endpoint, and model declarations. |
158
+ | `OllamaExecutable` | interface | `{ path, digest, arguments? }` | Declares the executable identity required before a daemon starts. |
159
+ | `OllamaModel` | interface | `{ name, digest }` | Declares a model name and the digest its inventory entry must report. |
160
+ | `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }` | Bounds each metadata or unload response independently of the startup deadline. |
161
+ | `OllamaDaemonIdentity` | interface | `{ executable, url, pid, version, models }` | Records the executable, endpoint, root process, and model identities verified at startup. |
162
+ | `OllamaBytes` | interface | `{ content, size, digest, complete }` | Preserves a bounded HTTP body as base64 with its byte count and SHA-256 digest. |
163
+ | `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }` | Records one declared model's unload request and the response observed for that attempt. |
164
+ | `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }` | Reports verified startup, recorded unloads, permanent stop, and daemon failures. |
165
+ | `ollamaDaemonShape` | const | `import("@orkestrel/contract").ObjectShape<{ executable: import("@orkestrel/contract").ObjectShape<{ path: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; arguments: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").StringShape>>; }, boolean \| import("@orkestrel/contract").ContractShape>; url: import("@orkestrel/contract").StringShape; models: import("@orkestrel/contract").ArrayShape<import("@orkestrel/contract").ObjectShape<{ name: import("@orkestrel/contract").StringShape; digest: import("@orkestrel/contract").StringShape; }, boolean \| import("@orkestrel/contract").ContractShape>>; workspace: import("@orkestrel/contract").StringShape; environment: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<Record<never, never>, import("@orkestrel/contract").StringShape>>; store: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").StringShape>; readiness: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; metadata: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ timeout: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; bytes: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; termination: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").ObjectShape<{ grace: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; drain: import("@orkestrel/contract").OptionalShape<import("@orkestrel/contract").NumberShape>; }, boolean \| import("@orkestrel/contract").ContractShape>>; }, false>` | Describes the serializable part of `OllamaDaemonOptions`, the record whose audit names a refused declaration's faults by path. |
166
+ | `ollamaDaemonContract` | const | `ContractInterface<unknown>` | Holds the compiled contract whose audit names a refused daemon declaration's faults by path. |
167
+ | `OLLAMA_TIMER_LIMIT` | const | `2147483647` | Bounds a daemon duration to 2147483647 milliseconds, the longest a Node timer holds. |
168
+ | `OLLAMA_DAEMON_LIVE` | const | `readonly string[]` | Lists the keys of a daemon declaration that hold live values, which no shape declares. |
169
+ | `OLLAMA_DAEMON_KEYS` | const | `Readonly<{ daemon: readonly string[]; executable: readonly string[]; model: readonly string[]; metadata: readonly string[]; termination: readonly string[]; }>` | Lists the keys each record of a daemon declaration admits, live values included. |
170
+ | `OLLAMA_READINESS` | const | `60000` | Bounds startup through the version probe and model verification to 60000 milliseconds by default. |
171
+ | `OLLAMA_METADATA_TIMEOUT` | const | `10000` | Bounds each metadata or unload request and body read to 10000 milliseconds by default. |
172
+ | `OLLAMA_METADATA_BYTES` | const | `1048576` | Bounds each retained metadata or unload response to 1048576 bytes by default. |
173
173
 
174
174
  The server face reports every refusal as one branded error class.
175
175
 
176
- | Name | Kind | Signature | Summary |
177
- | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
178
- | `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError` | Carries a daemon refusal with a machine-readable category, observations, and original cause. |
179
- | `OllamaErrorOptions` | interface | `{ code, context?, cause? }` | Configures a daemon refusal with its category, observations, and original cause. |
180
- | `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence?, faults? }` | Carries the operation and identity observations accompanying a daemon refusal. |
181
- | `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]` | Defines the machine-readable refusal categories of the daemon lifecycle. |
182
- | `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "version", "model", "owner", "metadata", "unload", "cleanup", "aborted", "state"]` | Lists every machine-readable daemon refusal category. |
183
- | `OLLAMA_ERROR_BRAND` | const | `unique symbol` | Identifies daemon errors across installations and module formats through the global symbol registry. |
184
- | `isOllamaError` | function | `(value: unknown) => value is OllamaError` | Checks whether an unknown value carries the daemon error brand and declared members. |
176
+ | Name | Kind | Signature | Summary |
177
+ | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
178
+ | `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError` | Carries a daemon refusal with a machine-readable category, observations, and original cause. |
179
+ | `OllamaErrorOptions` | interface | `{ code, context?, cause? }` | Configures a daemon refusal with its category, observations, and original cause. |
180
+ | `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence?, faults? }` | Carries the operation and identity observations accompanying a daemon refusal. |
181
+ | `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]` | Defines the machine-readable refusal categories of the daemon lifecycle. |
182
+ | `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "model", "owner", "metadata", "unload", "cleanup", "aborted", "state"]` | Lists every machine-readable daemon refusal category. |
183
+ | `OLLAMA_ERROR_BRAND` | const | `unique symbol` | Identifies daemon errors across installations and module formats through the global symbol registry. |
184
+ | `isOllamaError` | function | `(value: unknown) => value is OllamaError` | Checks whether an unknown value carries the daemon error brand and declared members. |
185
185
 
186
186
  The session composes the following validators and protocol helpers, each exported so a caller can check a declaration or a retained body without starting a daemon.
187
187
 
@@ -194,7 +194,7 @@ The session composes the following validators and protocol helpers, each exporte
194
194
  | `isOllamaOrigin` | function | `(value: unknown) => value is string` | Checks whether a string selects an explicit dedicated HTTP loopback origin. |
195
195
  | `buildOllamaEnvironment` | function | `(inherited: Readonly<Record<string, string \| undefined>>, environment: Readonly<Record<string, string \| undefined>> \| undefined, url: string, store?: string) => Readonly<Record<string, string \| undefined>>` | Builds the environment with dedicated values overriding every inherited or caller casing. |
196
196
  | `matchesOllamaAnnouncement` | function | `(line: string, url: string) => boolean` | Checks whether stderr announces the dedicated loopback listener. |
197
- | `verifyOllamaVersion` | function | `(value: unknown, expected: string) => void` | Verifies a metadata reply against the declared executable version. |
197
+ | `readOllamaVersion` | function | `(value: unknown) => string` | Reads the version a metadata reply reports, whatever it is. |
198
198
  | `verifyOllamaModels` | function | `(value: unknown, models: readonly OllamaModel[]) => void` | Verifies every declared model against a complete metadata inventory. |
199
199
  | `retainOllamaBytes` | function | `(bytes: Uint8Array, complete: boolean) => OllamaBytes` | Retains exact body bytes with an independently reproducible digest. |
200
200
  | `readOllamaJSON` | function | `(bytes: OllamaBytes) => Readonly<Record<string, unknown>>` | Reads a complete retained JSON metadata body without reserializing it. |
@@ -278,9 +278,9 @@ The optional `fetch` collaborator carries every `/api/version` probe, `/api/tags
278
278
 
279
279
  A session moves through these steps in order. `PORT` stands for the dedicated port you choose and `NAME` for a declared model name.
280
280
 
281
- 1. **Declare.** Record the executable's absolute path, its lowercase hexadecimal SHA-256 digest, and the version its `/api/version` route reports, all read before the run. Add the dedicated origin `http://127.0.0.1:PORT` with an explicit port other than 11434 and 0, an absolute working directory, and each model with the digest its `/api/tags` entry reports. `createOllamaDaemon` and the `OllamaDaemon` constructor validate the declaration and copy it before any file, socket, or process operation. A malformed declaration throws `OllamaError` with code `invalid`, and an undeclared key in the declaration, `executable`, a `models` entry, `metadata`, or `termination` refuses too, with its path in `context.faults`.
281
+ 1. **Declare.** Record the executable's absolute path and its lowercase hexadecimal SHA-256 digest, both read before the run. The declaration names no version, so an Ollama update never invalidates it. Add the dedicated origin `http://127.0.0.1:PORT` with an explicit port other than 11434 and 0, an absolute working directory, and each model with the digest its `/api/tags` entry reports. `createOllamaDaemon` and the `OllamaDaemon` constructor validate the declaration and copy it before any file, socket, or process operation. A malformed declaration throws `OllamaError` with code `invalid`, and an undeclared key in the declaration, `executable`, a `models` entry, `metadata`, or `termination` refuses too, with its path in `context.faults`.
282
282
  2. **Start.** `start` checks that the workspace and the optional `store` are existing directories, that the executable is a regular file — a `.exe` or `.com` file on Windows and an executable file elsewhere — and not a `#!` script, and that its bytes hash to the declared digest. It then binds the declared port and releases it, refusing with `occupied` when another process holds the port, and spawns the executable through a process session with the declared `arguments` (default `serve`) and the selected environment. Concurrent and repeated calls share the first startup result.
283
- 3. **Verify.** Readiness wakes on the child's own stderr. `start` requires the child's listen announcement for the declared port, then a `/api/version` reply equal to the declared version, then a `/api/tags` inventory that reports every declared model with its declared digest, and it checks that the owned child is live at each of those replies. Only after every check passes does `start` emit `start` and resolve the frozen `OllamaDaemonIdentity` receipt. `readiness` bounds the whole sequence, `OLLAMA_READINESS` (60000 ms) by default. A failed startup stops and joins the owned session before it rejects, and a cleanup that isn't confirmed rejects with `cleanup` and the startup failure as its `cause`.
283
+ 3. **Verify.** Readiness wakes on the child's own stderr. `start` requires the child's listen announcement for the declared port, then a `/api/version` reply that names a nonempty version, then a `/api/tags` inventory that reports every declared model with its declared digest, and it checks that the owned child is live at each of those replies. The reported version is an observation: `start` compares it with nothing and records it as the receipt's `version`, and a reply that names no version refuses with `metadata`. Only after every check passes does `start` emit `start` and resolve the frozen `OllamaDaemonIdentity` receipt. `readiness` bounds the whole sequence, `OLLAMA_READINESS` (60000 ms) by default. A failed startup stops and joins the owned session before it rejects, and a cleanup that isn't confirmed rejects with `cleanup` and the startup failure as its `cause`.
284
284
  4. **Use.** Point the core face at `daemon.url`, for example `createOllama({ model: NAME, url: daemon.url })`. The session admits no unload before verification and doesn't observe the requests you send.
285
285
  5. **Unload.** `unload` posts `{"model":NAME,"keep_alive":0}` to `/api/generate` for each declared model in declaration order, with no prompt, and retains each request and response as `OllamaBytes`: the base64 content, its byte count, its SHA-256 digest, and whether the body ended within its bound. An attempt succeeds only when the complete terminal reply carries `done: true` and names the declared model. The first refused attempt ends the call, and every attempt, refused ones included, stays in `maintenance` in sequence order. A transport or collaborator failure, or a refused reply, rejects `unload` and leaves the daemon running until `stop`; a rejection during `start` stops and joins the child before rejecting. A call that overlaps another refuses with `state`.
286
286
  6. **Stop.** `stop` is permanent. It aborts pending startup and maintenance, stops the owned process tree, joins the session's exit barrier, and hashes the executable again. It resolves `true` when the root exit is confirmed and the digest is unchanged, or when no child ever started; otherwise it emits `error` and resolves `false`. It never rejects, every call shares one barrier, and a stopped session refuses to start with `state`. `destroy` stops the session and then releases its emitter; `identity` and `maintenance` stay readable after it.
@@ -325,10 +325,9 @@ Declare each model's digest as the `digest` field its `/api/tags` entry reports,
325
325
  | `digest` | an executable whose digest differs or can't be read, before spawn or after stop |
326
326
  | `spawn` | another preflight or spawn failure, such as a missing executable or a child that couldn't be created |
327
327
  | `readiness` | the startup deadline, which a child that never announces its listener reaches |
328
- | `version` | a `/api/version` reply that differs from the declared version |
329
328
  | `model` | a declared model the inventory omits or reports with another digest |
330
329
  | `owner` | an owned child that isn't live at a readiness reply or at maintenance |
331
- | `metadata` | a refused status, a redirect, a malformed or oversized body, or an elapsed request bound |
330
+ | `metadata` | a refused status, a redirect, a malformed or oversized body, a version reply that names no version, or an elapsed request bound |
332
331
  | `unload` | an unload reply that doesn't confirm the declared model |
333
332
  | `cleanup` | a termination that wasn't confirmed |
334
333
  | `aborted` | a cancellation through `signal`, or a stop during startup or maintenance |
@@ -713,13 +712,13 @@ declare const MODEL_DIGEST: string
713
712
  declare const WORKSPACE: string
714
713
 
715
714
  const daemon = createOllamaDaemon({
716
- executable: { path: OLLAMA_PATH, digest: OLLAMA_DIGEST, version: '0.40.8' },
715
+ executable: { path: OLLAMA_PATH, digest: OLLAMA_DIGEST },
717
716
  url: 'http://127.0.0.1:11437',
718
717
  models: [{ name: 'qwen3.5:2b-q4_K_M', digest: MODEL_DIGEST }],
719
718
  workspace: WORKSPACE,
720
719
  })
721
720
  try {
722
- const identity = await daemon.start() // the verified receipt: executable, url, pid, and models
721
+ const identity = await daemon.start() // the verified receipt: executable, url, pid, the reported version, and models
723
722
  const provider = createOllama({ model: 'qwen3.5:2b-q4_K_M', url: daemon.url })
724
723
  const answer = await provider.generate(
725
724
  [{ id: '1', role: 'user', content: 'Reply with exactly: ok' }],
@@ -747,7 +746,7 @@ isOllamaOrigin('http://127.0.0.1:11434') // false — the default port is never
747
746
  isOllamaOrigin('http://localhost:11437') // false — the origin names 127.0.0.1 exactly
748
747
 
749
748
  const declaration = {
750
- executable: { path: '/opt/ollama/bin/ollama', digest: 'a'.repeat(64), version: '0.40.8' },
749
+ executable: { path: '/opt/ollama/bin/ollama', digest: 'a'.repeat(64) },
751
750
  url: 'http://127.0.0.1:11437',
752
751
  models: [{ name: 'qwen3.5:2b-q4_K_M', digest: 'b'.repeat(64) }],
753
752
  workspace: '/srv/ollama',
@@ -843,10 +842,10 @@ The judge proofs cover the recorded wire and the live models.
843
842
 
844
843
  The daemon session proofs run in the `src:server` project against `tests/src/server/fixtures/daemon.mjs`, a self-contained fake daemon that the running Node executable starts on a loopback port and that answers each route with the fields a real daemon sends, and in the `service` project against a real Ollama executable.
845
844
 
846
- - [`tests/src/server/OllamaDaemon.test.ts`](../tests/src/server/OllamaDaemon.test.ts) drives the lifecycle over the fake daemon: a shared startup behind a delayed version reply, verification before any model request, retained maintenance including a refused unload, an overlapping unload, and a refused restart; ordered requests through an optional transport and its global control, exact maintenance bytes across re-chunked replies, a retained transport reference after caller mutation, and transport refusals at each send boundary, with startup joining the child before rejecting and unload leaving it running until `stop`; a mismatched inventory digest refused with `model`, metadata-only requests, and the owned child joined before startup rejects; a stale executable digest and an occupied port, each refused before a child exists; silence, an exit before listening, a bind failure, and an exit before answering, each refused with the owned child gone; executable bytes replaced through the declared path during use, which `stop` reports as `false` with a `digest` error; and a stop and an abort that each end the daemon and its runner while an unrelated process survives.
847
- - [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) proves the environment merge by case-folded name, the listen announcement match, the version and model comparisons, the bounded metadata exchange and its refusals, the retained bytes and their digests, the exact unload body, and the terminal reply check, over an in-process peer that answers the metadata routes.
845
+ - [`tests/src/server/OllamaDaemon.test.ts`](../tests/src/server/OllamaDaemon.test.ts) drives the lifecycle over the fake daemon: a shared startup behind a delayed version reply, a startup across a version the declaration never named that records the reported version, verification before any model request, retained maintenance including a refused unload, an overlapping unload, and a refused restart; ordered requests through an optional transport and its global control, exact maintenance bytes across re-chunked replies, a retained transport reference after caller mutation, and transport refusals at each send boundary, with startup joining the child before rejecting and unload leaving it running until `stop`; a mismatched inventory digest refused with `model`, metadata-only requests, and the owned child joined before startup rejects; a stale executable digest and an occupied port, each refused before a child exists; silence, an exit before listening, a bind failure, and an exit before answering, each refused with the owned child gone; executable bytes replaced through the declared path during use, which `stop` reports as `false` with a `digest` error; and a stop and an abort that each end the daemon and its runner while an unrelated process survives.
846
+ - [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) proves the environment merge by case-folded name, the listen announcement match, the version reader and the model comparison, the bounded metadata exchange and its refusals, the retained bytes and their digests, the exact unload body, and the terminal reply check, over an in-process peer that answers the metadata routes.
848
847
  - [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts), [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts), and [`tests/src/server/errors.test.ts`](../tests/src/server/errors.test.ts) prove the declaration refusals before any spawn, the undeclared keys by path, the guards in lockstep with the shape, an unstarted session's release without a spawn, and the error brand, its context copy, its cause, and the guard's refusals.
849
- - [`tests/service/OllamaDaemon.test.ts`](../tests/service/OllamaDaemon.test.ts) starts a dedicated real daemon, verifies its receipt, unloads every declared model with the exact request body, and requires a confirmed stop without generation. An explicit `OLLAMA_DAEMON_DECLARATION` JSON value wins. Otherwise the proof resolves `OLLAMA_DAEMON_EXECUTABLE` or the `ollama` executable on `PATH` to its canonical path, computes its SHA-256, reads the provisioned service at `OLLAMA_HOST` for its version and the selected model's `/api/tags` digest, and chooses an ephemeral loopback port apart from 11434 and the provisioned service port. The executable must be the build the provisioned service runs, because the proof compares their versions: when `OLLAMA_HOST` names a held runner, set `OLLAMA_DAEMON_EXECUTABLE` to that runner's executable, or the proof takes the `ollama` on `PATH` and refuses with `Executable version differs`. It runs only in the `service` project.
848
+ - [`tests/service/OllamaDaemon.test.ts`](../tests/service/OllamaDaemon.test.ts) starts a dedicated real daemon, verifies its receipt, unloads every declared model with the exact request body, and requires a confirmed stop without generation. An explicit `OLLAMA_DAEMON_DECLARATION` JSON value wins. Otherwise the proof resolves `OLLAMA_DAEMON_EXECUTABLE` or the `ollama` executable on `PATH` to its canonical path, computes its SHA-256, reads the provisioned service at `OLLAMA_HOST` for the selected model's `/api/tags` digest, and chooses an ephemeral loopback port apart from 11434 and the provisioned service port. The proof compares no versions, so the executable can be another build than the one the provisioned service runs, and the receipt records the version the dedicated daemon reports. It runs only in the `service` project.
850
849
 
851
850
  The hermetic projects — `src:core`, `src:server`, `setup`, `guides`, `conformance`, `policy`, and `config` — run with no Ollama daemon and no network beyond loopback. The `src:server` project starts no Ollama executable: its lifecycle proofs spawn the fake daemon and bind loopback ports only. The `service` project requires a warm local Ollama and, for the page proof, a Chromium-family browser and a built `dist`, and for the daemon session proof an executable on `PATH`, an `OLLAMA_DAEMON_EXECUTABLE` path, or an explicit `OLLAMA_DAEMON_DECLARATION` value; `distribution` packs and installs the artifact. The import guard reads `distribution` with the hermetic projects, because it never reaches the daemon; it leaves out `probe` and `service` alone, the two projects that may.
852
851