@orkestrel/scaffold 0.0.104 → 0.0.105

package/dist/host/guides/study.md

@@ -2,7 +2,7 @@
 
 > Bounded comparative execution with captured artifacts and separate grading.
 
-The host-independent engine is exported from `@orkestrel/study`; custody and native workers are exported from `@orkestrel/study/server`.
+The host-independent engine is exported from `@orkestrel/study`; custody and native workers are exported from `@orkestrel/study/server`. Study requires Node.js 22.18.0 or later. TypeScript consumers of the server entry must install `@types/node` because its declarations import `node:` modules. The core entry needs no Node.js types.
 
 ## Execution and evidence
 
@@ -10,15 +10,19 @@ Declare the question, purpose, arms, scenarios, repetition order, and rubric bef
 
 The request meter reserves token and byte ceilings before an adapter dispatches work. Request, goal, trial, and series limits bound enclosing work. Missing actual usage remains unknown and consumes the admitted ceiling. Capacity, infrastructure, deadline, and interruption are operational outcomes; a product never awards its own task verdict. An error that carries a failure keeps that attribution; a study error without one reads as capacity for the `CAPACITY` code and as deadline for the `DEADLINE` code. A branded `BudgetError` from any module copy reads as capacity with a `budget` stop and retains its source readings. Every other rejection reads as infrastructure, including an unbranded budget lookalike.
 
-A study error stamps an own `STUDY_ERROR_BRAND` descriptor whose value is the error itself. `isStudyError` requires that descriptor with an `Error` subclass, the `StudyError` name, and a declared code, so a study error thrown by another package, ESM, CommonJS, or captured module copy keeps its code and attribution. The brand uses the global symbol registry: it is recognition, not unforgeable provenance. An unbranded older copy, an inherited or borrowed brand, a proxy, and a property-only lookalike read as infrastructure.
+A study error stamps an own, non-enumerable, non-writable `STUDY_ERROR_BRAND` descriptor whose value is the error itself. `isStudyError` requires that descriptor with an `Error` subclass, a declared code, and valid optional failure attribution. Subclasses can replace the name. The guard validates the Error name, message, and optional stack. Failure stop readings retain their declared number type, including nonfinite values; serialized admission and the standalone stop guard require finite readings. Failure stops are checked structurally, including class instances and inherited fields; serialized admission retains its exact-record checks. The guard reads through the contract package's captured reflection inside its never-throw boundary, so a study error thrown by another package, ESM, CommonJS, or captured module copy keeps its code and attribution. The brand uses the global symbol registry: the brand recognizes the contract without proving its origin. An unbranded older copy, an inherited or borrowed brand, a transparent proxy, malformed failure attribution, and a property-only lookalike read as infrastructure.
+
+The `ArtifactError` class stamps `ARTIFACT_ERROR_BRAND` under the global key `@orkestrel/study.ArtifactError`. Its guard recognizes subclasses and other installed or module copies through the identity stamp, a code from `ARTIFACT_ERROR_CODES`, and the declared Error members. A look-alike without the brand, a transparent proxy, a plain branded object, and malformed members return false.
+
+Within one module format, the root and server entries share one `StudyError` class, so both `instanceof StudyError` and `isStudyError` recognize server errors. The ESM and CommonJS builds carry separate classes. Across module formats, recognize a server error with `isStudyError`; `instanceof StudyError` is false.
 
 A product that exceeds its goal, trial, or series output allowance is omitted from custody with a capacity failure. Previously admitted products remain retained, and the remaining horizon is explicitly unexecuted. A genuine custody write or metadata-capacity failure still rejects execution and leaves the result unsealed.
 
 Each observation and attempt records an explicit execution fact. An observation is executed when the engine dispatched its goal to the session, and unexecuted when it fills the horizon after a terminal failure; an unexecuted observation holds a failure and no product, usage, or duration. An attempt is executed when it entered trial execution without an inherited terminal series failure, including a failure before the driver opened, so the fact does not claim that the driver was opened. Executed goals form a prefix of the horizon, and an executed goal that fails ends it. Both facts are required booleans, never inferred from a product, usage, duration, or failure message, and custody refuses an attempt that omits one or contradicts them. A terminal attempt holds a failure whenever a goal failed or went unexecuted. Study carries no format counter; the artifact inventory records the exact implementation fingerprints, and the definition, rubric, and label versions are caller-authored metadata that identify supplied content.
 
-A ticket reports `settled` from its own settlement, never from `signal.aborted`: a worker ticket whose signal aborted is unsettled locally because the parent owns that failure. After work escapes, call `failStudyTicket` with the caught value. It leaves a ticket that already settled or aborted untouched, so no request is accounted twice. Otherwise it fails the ticket once with the reading `readStudyFailure` gives the value; an optional role replaces any role that reading carries, and without one the carried role, then the ticket's admitted role, applies. A refusal thrown by the ticket's own settlement propagates. A consumer that must account known bytes when an operation throws, or finish an expected refusal, keeps that choice in its own code.
+A ticket reports `settled` from its own settlement, never from `signal.aborted`: a worker ticket whose signal aborted is unsettled locally because the parent owns that failure. After work throws, call `failStudyTicket` with the caught value. It leaves a ticket that already settled or aborted untouched, so no request is accounted twice. Otherwise it fails the ticket once with the reading `readStudyFailure` gives the value; an optional role replaces any role that reading carries, and without one the carried role, then the ticket's admitted role, applies. A refusal thrown by the ticket's own settlement propagates. A consumer that must account known bytes when an operation throws, or finish an expected refusal, keeps that choice in its own code.
 
-The driver receives a borrowed admission interface and an evidence sink. The concrete engine owns the meter's closing lifecycle. Native workers await parent admission and acknowledge request settlement; each trial runs in a fresh child. Trusted adapters can access native resources, so process supervision is not a hostile-code sandbox.
+The driver receives a borrowed admission interface and an evidence sink. The concrete engine owns the meter's closing lifecycle. Native workers await parent admission and acknowledge request settlement; each trial runs in a fresh child. Trusted adapters can access native resources, so process supervision is not a sandbox for untrusted code.
 
 Execution custody creates a result directory exclusively, appends evidence, retains terminal attempts, and seals only a complete scheduled population. A result without a seal remains interrupted. Offline reading verifies the seal's exact file inventory and digests. Changed execution bytes refuse custody verification.
 
@@ -75,7 +79,7 @@ const sealed = reading.status === 'sealed' && reading.seal.id === seal.id // tru
 
 ## Limits
 
-Captured identities bind admitted files, module selections, and Node runtime settings. They do not identify the entire machine or replay external services. Neutral semantic identifiers omit treatment and model names, but input and product text can reveal design details. This guide's executable examples prove local admission and custody; they do not establish GPU capacity or model quality.
+Captured identities bind admitted files, module selections, and Node runtime settings. Recorded replay reproduces exact application HTTP bodies through the declared collaborator; it identifies neither the entire machine nor the external service, TLS records, or transfer framing. Neutral semantic identifiers omit treatment and model names, but input and product text can reveal design details. This guide's executable examples prove local admission and custody; they do not establish GPU capacity or model quality.
 
 ## Captured loading
 
@@ -83,9 +87,13 @@ Select canonical absolute package roots and built ESM entries under each package
 
 Admit every package root reached by native dependency resolution, including installed copies alongside a selected local package. Distinct canonical roots may share a package name; each root and its captured bytes retain their own identity. Repeated roots refuse inspection, and imports into omitted roots refuse loading before evaluation.
 
-Select a consumer-owned source directory separately when the adapter needs strip-only TypeScript. Its graph cannot overlap a built package graph. Source JSON assets are excluded; fixture and rubric bytes retain separate identities. Native package exports and extension rules still govern resolution. The inventory records package manifests, captured files, selected entries, Node version, and runtime settings.
+Select a consumer-owned source directory separately when the adapter needs strip-only TypeScript. Its graph cannot overlap a built package graph. Source JSON files cannot be executable imports. Explicit assets retain exact file bytes in custody without granting import eligibility. Fixture and rubric bytes retain separate execution identities. Native package exports and extension rules still govern resolution. The inventory records package manifests, captured files, explicit assets, selected entries, Node version, and runtime settings.
+
+Select excluded built files to refuse every import edge that reaches them; exclusion leaves the inventory identity unchanged. Run loading in a disposable worker and terminate the worker afterwards. A process admits one loaded inventory. Trusted code can use native process APIs, evaluation, and external services; the loader does not replay those resources or sandbox untrusted code.
 
-Select excluded built files to refuse every import edge that reaches them; exclusion leaves the inventory identity unchanged. Run loading in a disposable worker and terminate the worker afterwards. A process admits one loaded inventory. Trusted code can use native process APIs, evaluation, and external services; the loader does not replay those resources or sandbox hostile code.
+Call the `materialize` method with an absent absolute destination under an existing physical parent. Materialization preserves the admitted physical forest, including nested node_modules and duplicate package copies. It copies exact bytes and verifies source before and after copying and the entire destination before returning. Explicit assets join the existing aggregate capture limits. Different source or destination volumes, overlap, occupied destinations, links and redirected ancestors, aliases, unsafe names, duplicate keys, and stale source references refuse before copying through them. A refusal before copying writes nothing; an occupied destination stays unchanged. A refusal during copying, including source drift or a link added mid-copy, can leave an incomplete destination without closure.json.
+
+The portable closure digest binds sorted member keys, byte digests, sizes, and relative package identities. It excludes source provenance and the destination path. The relocated loader identity retains its canonical paths and runtime settings separately. Path checks and reads do not provide an atomic filesystem snapshot, concurrent hardlink-race resistance, or crash recovery.
 
 ### Inspect selected bytes
 
@@ -115,20 +123,79 @@ Call `gradeStudyEvidence` from an adapter's grade method to traverse the declare
 
 An Agent-backed consumer passes the admitted Agent namespace to the shared instrumentation, which imports Agent types only and constructs nothing from an installed Agent copy. Request measurements, the nominal Agent error, and daemon timing keep the types their owning Agent and Ollama packages export; Study declares no copy of them. The `StudyAgentObserver` class delegates every provider call unchanged and records one size reading before each dispatch. The gauge is explicit: without one, a reading carries no projection. The enforced option selects the usage policy separately from observation, so a passive reading refuses no return. The `StudyAgentJudge` class binds a real judge to a `StudyLatchInterface` owner, so a caught classification failure stays visible to the study.
 
-The `StudyOllamaTransport` class admits each Ollama wire request through the goal's meter, reads each response under the declared byte and duration limits, accounts actual usage before any policy refusal, and retains the first operational failure with its identity. Each model role declares its wire policy: the exact Ollama options object, the think allowance, the strict truncate and shift fields, and whether a length finish is the declared completion. The transport supplies no default policy, refuses an undeclared role, and keeps unreported usage unknown. The `prepare` method binds later requests to one goal until the `clear` or `close` method ends it, and refuses with the `FAULT` code while a goal is bound or a model response is open. The `fetch` and `verify` methods refuse with the `FAULT` code when no goal is bound, and `verify` retains that refusal as the transport's failure. A request admitted before `clear` keeps its goal, and each goal's checkpoint joins only that goal's first observed dispatch.
+The `StudyOllamaTransport` class admits model requests through the goal's meter and metadata through an independent declared budget for calls, bytes, and duration. Metadata has no model-meter parent. Each response retains its byte and duration limits, actual usage precedes a policy refusal, and the first operational failure keeps its identity. Each model role declares its exact Ollama options, think allowance, strict truncate and shift fields, and length-finish policy. Maintenance attribution carries no generation policy. The transport refuses an undeclared role and keeps unreported usage unknown. The `prepare` method binds later requests to one goal until the `clear` or `close` method ends it, and refuses with the `FAULT` code while a goal is bound or a response is open. The `fetch` and `verify` methods refuse with the `FAULT` code when no goal is bound, and `verify` retains that refusal. A request admitted before `clear` keeps its goal, and each goal's checkpoint joins only that goal's first observed dispatch.
+
+Recording requires version, procedure, and exchange sink together. Preflight and postflight verify version, tags, and show for each distinct pinned model. Ordered exact steps compare UTF-8 bytes and verify their declared SHA-256 receipt; capture steps require their declared positive safe byte length and forbid body or input members. Goal, role, route, policy, and order are checked before sending. A second request and verification during request admission refuse. The sink supplies each HTTP ordinal, which joins dispatch and wire evidence even without passive observation. An attempt retains request bytes before sending. A validated response retains native status, selected headers, exact bytes, and chunk lengths; a failure retains bounded partial bytes and cannot produce completion. Successful postflight appends completion after every declared step has finished. The worker owns the preceding declaration and any maintenance prefix.
+
+The transport owns its configuration before validation and snapshots each outbound URL, settings, headers, and request correlation before awaiting admission. Later caller mutation cannot change the admitted request. Cancellation signals, the timing callback, and the optional fetch collaborator retain their live identity.
+
+The `StudyOllamaTransportOptions` interface accepts an optional `fetch` collaborator with the `StudyOllamaFetchFunction` signature. Omit the option to keep native fetch. When supplied, the collaborator receives the validated Study role, URL, encoded body, headers, bounded signal, and `redirect: 'error'` at the send boundary. Agent and summary keep distinct roles even when they share a model. Construction refuses a present non-callable collaborator with the `CONFIG` code.
+
+The collaborator returns a native `Response` and never settles a Study ticket. Study keeps request validation, admission, dispatch evidence, response status and byte bounds, terminal and timing checks, cancellation, accounting, and the failure latch. A synchronous throw, HTTP refusal, incomplete stream, abort, or cap follows the existing accounting path. Caller abort, the request deadline, and the `close` method settle a pending collaborator wait with the signal's reason even if the collaborator ignores cancellation; Study accounts the request once, retains the failure, and cancels a response that arrives later.
+
+### Forward admitted requests by role
+
+Supply the forwarding function inside the process that constructs the transport. This example retains the roles and delegates the supplied request settings to native fetch.
 
-The transport owns its configuration before validation and snapshots each outbound URL, settings, headers, and request correlation before awaiting admission. Later caller mutation cannot change the admitted request. Cancellation signals and the timing callback retain their live identity.
+```ts
+import type { StudyRole } from '@orkestrel/study'
+import type { StudyOllamaTransportOptions } from '@orkestrel/study/server'
+import { StudyOllamaTransport } from '@orkestrel/study/server'
+
+declare const configured: StudyOllamaTransportOptions
+const roles: StudyRole[] = []
+const transport = new StudyOllamaTransport({
+	...configured,
+	fetch: (role, input, init) => {
+		roles.push(role)
+		return globalThis.fetch(input, init)
+	},
+})
+// Prepare the goal, then use transport.fetch or transport.verify as usual.
+// Study reads each returned response before completing its accounting.
+```
 
 The server entry adds a trace, a gauged summary, and a scripted provider over the same admitted Agent capabilities. The consumer passes those capabilities as `runtime`; none of the three imports an Agent runtime. The consumer keeps its model prompts, treatment options, origin joins, and grade policy.
 
 The `StudyAgentTrace` class numbers each measured request and retains its context, estimate, and capacity-refusal rows for the active goal. Ordinals, dispatch numbers, and role identities continue across a trial's goals. The `observe` option selects those measurement and refusal rows. When it is `false`, `append` still retains a domain row for an active goal, and a row outside a goal is dropped. The `start` method refuses with the `CONFIG` code while a goal is active and leaves that goal and its rows unchanged. The `flush` method appends the rows to a `StudySinkInterface` in order, keeps rows appended during the flush, and ends the goal and clears its rows, including when custody refuses a row. A `flush` with no active goal does nothing, and a `flush` while another is pending refuses with the `CONFIG` code and leaves the pending one untouched. The `origins` handler joins each measured message to its consumer origin.
 
-The `StudyAgentSummary` class measures one canonical array, the folded messages followed by the instruction, and sends the very same array to the provider. Construction refuses with the `CONFIG` code unless `limit` is a positive safe integer, the gauge `scale` is finite and greater than 0, and the gauge `overhead` is finite and at least 0; the summary keeps its own copy of the gauge. A projection that reaches `limit` fails with the `CAPACITY` code before any request is sent. A summary outside an active goal, or with blank content after its evidence row, fails with the `FAULT` code.
+The `StudyAgentSummary` class measures one canonical array, the folded messages followed by the instruction, and sends the very same array to the provider. Construction refuses with the `CONFIG` code unless `limit` is a positive safe integer and the copied gauge passes `isStudyAgentGauge`: its `scale` is finite and greater than 0 and its `overhead` is finite and at least 0. The summary reads each gauge field once and keeps that validated copy. The guard admits extra members; a consumer that requires exact settings keys composes its own key check. A projection that reaches `limit` fails with the `CAPACITY` code before any request is sent. A summary outside an active goal, or with blank content after its evidence row, fails with the `FAULT` code.
 
 The `StudyAgentScript` class serves declared inert responses through the Agent provider boundary. Its constructor takes an explicit encoded `bytes` bound and refuses a value that is not a nonnegative safe integer. The `prepare` method keeps an owned snapshot of a goal's responses, so later caller mutation cannot change a served call. The `prepare` method refuses with the `CONFIG` code while a goal is prepared, and the `clear` method ends the prepared goal. A stream refuses with the `CONFIG` code when no goal is prepared, and a stream already running when `clear` is called finishes under its own goal. The `isStudyAgentResponse` guard accepts a response with JSON calls and sets no limit on content, call count, or `consume`; the consumer composes its own workload bounds. A stream abandoned after admission accounts for an Agent budget cut without latching a failure. Other abandoned streams fail the admitted request with the run signal's reason, or a `FAULT` when the signal carries none.
 
 The `readStudyAgentMessages` function projects provider messages onto the role, content, and call fields a workload reads. The `buildStudyAgentReadings` function projects a Ledger result's readings onto JSON. The `buildStudyOllamaModels` function pins the model, and the judge when the provider declares both its name and digest. The `buildStudyOllamaOptions` function projects a role policy onto provider options and adds `truncate` and `shift` as `false` only for a strict policy.
 
+The `buildStudyAgentToolResult` function projects an executed Agent tool call into its `id`, `name`, owned JSON `arguments`, boolean `success`, and owned JSON `value` or string `error`. The `buildStudyAgentToolDenial` function projects a denied call into its `id` and `name`, with a `reason` only when it is a string. Both refuse a malformed call with the `FAULT` code. The result projection also refuses a missing boolean `success`, non-JSON arguments or value, and a malformed failure error. Tool accounting, expected refusals, and workload grading remain in the consumer.
+
+Both projections use `readStudyAgentToolCall` to read each foreign call field once and validate the fresh envelope. The reader retains the arguments record by reference; the result projection owns its JSON copy.
+
+### Read an Agent tool call
+
+Read the envelope before projecting executed or denied evidence.
+
+```ts
+import { readStudyAgentToolCall } from '@orkestrel/study/server'
+
+const call = readStudyAgentToolCall({ id: 'c1', name: 'write', arguments: { path: 'note.txt' } })
+// { id: 'c1', name: 'write', arguments: { path: 'note.txt' } }
+```
+
+### Inspect Agent tool evidence
+
+Validate the gauge independently of settings keys, then retain the Agent's executed or denied call.
+
+```ts
+import { isStudyAgentGauge } from '@orkestrel/study'
+import { buildStudyAgentToolResult, buildStudyAgentToolDenial } from '@orkestrel/study/server'
+
+const gauge = isStudyAgentGauge({ scale: 1, overhead: -0, label: 'summary' }) // true
+const call = { id: 'c1', name: 'write', arguments: { path: 'note.txt' } }
+const result = buildStudyAgentToolResult(call, { success: true, value: 'stored' })
+// { id: 'c1', name: 'write', arguments: { path: 'note.txt' }, success: true, value: 'stored' }
+const denial = buildStudyAgentToolDenial(call, 'refused')
+// { id: 'c1', name: 'write', reason: 'refused' }
+```
+
 ## Stop attribution
 
 A `StudyFailure` record carries an optional reading under `stop`. The `StudyStop` record names the ceiling's `layer`, its `id`, its `max`, and the `consumed` tally including the refused charge. The `StudyLayer` union admits `scope`, `window`, `custody`, `meter`, `budget`, and `model`. A deadline has cause `deadline` and layer `scope`; its id names the duration allowance. An absent reading stays undefined in memory and projects to null through `studyStopToJSON`. The `isStudyStop` guard admits finite source readings, including negative and fractional values. Translation, IPC admission, and custody admission preserve those readings without clamping or relabelling them.
@@ -141,8 +208,30 @@ The Ollama transport appends a `stop` evidence row after its `wire` row when com
 
 ## Native command
 
+Recording declares `record.bytes` on the profile. The manifest retains the same declaration, and the parent reserves that complete allowance separately for each trial before starting workers. The allowance covers every serialized sidecar byte, including base64 expansion, opening and terminal rows, and LF framing. It consumes series custody without consuming goal evidence or model quota. Recording profiles explicitly supply `settings.version`, `settings.metadata`, and `settings.procedure`; the worker validates those declarations before constructing the adapter driver.
+
+The `StudyExchangeSink` class owns the trial's exclusive exchanges.jsonl descriptor. Its `next` property derives the next HTTP ordinal from accepted attempts, including a verified maintenance prefix. Callers await every append before sending or appending another row. The sink reserves failure-terminal space before an attempt and retains its first refusal. A failure omits response when no reply arrived or its bytes did not fit the sidecar allowance; the reason names which. Caught refusals prevent successful completion.
+
+The store admits exchanges.jsonl only when recording is declared. Sealing requires each scheduled trial's complete sidecar, exact declaration order, paired identities, valid raw-body receipts, and one ordered dispatch and wire evidence row per HTTP ordinal. Duplicate, orphaned, reordered, failed, partial, missing, and unrequested histories refuse with the CUSTODY code. Every other unknown file remains refused. The `readStudyExchanges` function reverifies the complete seal and this evidence join before returning a replay history.
+
+Replay execution requires `--replay <result> --prefix <JSON trial counts> --offline <true|false>`. Each positive prefix counts complete HTTP exchanges, including metadata and maintenance. The command verifies every selected trial before adapter validation or worker startup, and each worker rechecks its selected history. Replay requires the recording's exact Node runtime identity; another Node version, including a patch release, refuses before any worker starts. The executing profile supplies replay bounds. A supervisor fingerprint also pins changed execution bounds before dependent replay work.
+
+The `StudyOllamaReplay` class validates the complete retained history before construction succeeds. Its projected procedure supplies recorded exact bodies inside the prefix, including bodies originally admitted as capture. A capture declaration without a sealed completed history cannot replay. A changed request inside the prefix refuses without forwarding. After the prefix, only an explicit live collaborator can send requests. Offline replay consumes the complete recorded population and constructs no daemon or native sender. Recorded maintenance consumes prefix positions without sending unload requests. Its `check` method refuses an incomplete prefix, unread responses, or a retained mismatch; its `close` method releases response readers.
+
+The process driver accepts `StudyProcessDriverOptions`. Its optional `prepare` callback runs in the parent before session construction, preserves the reserved destination and allowance, and never crosses structured cloning or IPC. Offline replay refuses a preparation callback. A worker verifies any retained maintenance prefix before resuming the sidecar and projects those ordinals into its first goal's evidence.
+
+A provider's optional `daemon` declaration makes live execution own a dedicated Ollama session at the provider URL. The declaration pins a canonical absolute executable, its SHA-256 digest, the exact version, explicit environment overrides, and distinct model names and inventory digests equal to the provider's model and judge pins. A shared model and judge pin requires one entry. A maintenance-only model, a relative executable, port 11434, a missing model digest, or conflicting environment-name casing refuses at profile load. The daemon owns the effective OLLAMA_HOST value. Without this declaration, the provider URL selects an external daemon.
+
+The `StudyDaemonSession` class starts and verifies the daemon before trial execution. The manifest's `host.daemon` string retains the verified startup identity; startup version and inventory probes belong to no trial sidecar. Before each trial worker opens, preparation unloads the declared models in order. The `StudyDaemonTrial` class synchronizes each maintenance attempt before sending, retains status, allowed headers, original sender chunk lengths, and exact body bytes, and closes the prefix after daemon validation. A failed exchange retains a failure row. The worker joins the maintenance ordinals to the scenario's first declared goal. Every execution ending awaits daemon stop and process-tree join; an unconfirmed cleanup refuses completion. Offline replay constructs no daemon or preparation callback and sends no maintenance request.
+
 Install the package in the consumer workspace, then run the study executable from that workspace. The selected declaration lives at studies/<name>/study.json, and its declared rubric path resolves inside that same directory. Its driver field selects a bundle at studies/<driver>/ containing scenarios/<scenario>.json, profiles/<profile>.json, and the adapter module index.ts. Several declarations can share one driver bundle while each keeps its own rubric. The profile defaults to local. JSON declarations use the public definition, scenario, profile, and rubric contracts.
 
+The `readStudyDeclaration` function reads the selected definition, scenarios in declared order, and the rubric the definition names. It returns a `StudyDeclaration` record with the driver bundle and each scenario's bundle-relative fixture path and exact byte digest. It refuses a definition name or scenario identity that differs from its selection. The command uses this reader before reading the selected profile, so the refusal order is definition, scenarios, rubric, profile. The `StudyPreparation` record carries the driver's directory as `bundle`.
+
+The `readStudyDeclarationBytes` function reads an already resolved, contained declaration path under the custody metadata allowance. A missing declaration, scenario, rubric, or profile, or a declaration path reached through a symbolic link or junction, refuses with the `CONFIG` code and exit code 64. The reader refuses a link before traversing it. Its diagnostic names the missing path or linked component relative to the consumer root with forward slashes. A missing result refuses with the `CUSTODY` code and exit code 1, naming the result selector as supplied. Result and grading storage retain their custody refusals.
+
+The `matchesSystemError` predicate matches a system code only on an `Error` from this realm and returns false for a throwing code accessor. Structured cloning, such as a worker's `postMessage`, drops a Node error's system code, so the cloned error does not match.
+
 A profile selects the Agent runtime entry in its required agent field and the package under study in its required subject field. The two fields can name the same entry or two entries, including entries from different installed copies of Agent. Each selected entry is captured and loaded once, and the driver receives both namespaces under the declared roles. The selected entries and their bytes are part of the execution identity.
 
 The recap allowance of the room and the judge of the provider are optional. A study that produces no recap omits the recap allowance. A provider declares its judge model and its judge digest together or omits both; declaring only one refuses the profile. A declared recap and a declared judge keep their finite bounds.
@@ -151,23 +240,34 @@ A profile may carry an optional settings object of JSON values. The selected dri
 
 The command supports explicit operations with operation-specific flags. Every flag takes a value and can appear once.
 
-| Operation     | Command                                                                       | Result                                                                |
-| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Validate      | study check <study> [--profile <name>]                                        | Fingerprint and suggested pinned execution arguments                  |
-| Execute       | study execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] | Execution result identity and suggested independent grading arguments |
-| Grade         | study grade <result> --rubric <path>                                          | Immutable grading identity and suggested report arguments             |
-| Import labels | study label <result> --grading <sha256> --labels <path>                       | Another immutable grading identity and suggested report arguments     |
-| Report        | study report <result> --grading <sha256>                                      | Whole-horizon results for the selected grading                        |
+| Operation     | Command                                                                                                                                                                        | Result                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| Validate      | study check <study> [--profile <name>] [--closure <directory>]                                                                                                                 | Fingerprint and suggested pinned execution arguments                  |
+| Execute       | study execute <study> [--profile <name>] [--out <path>] [--expected <sha256>] [--closure <directory>] [--replay <result> --prefix <JSON trial counts> --offline <true\|false>] | Execution result identity and suggested independent grading arguments |
+| Grade         | study grade <result> --rubric <path>                                                                                                                                           | Immutable grading identity and suggested report arguments             |
+| Import labels | study label <result> --grading <sha256> --labels <path>                                                                                                                        | Another immutable grading identity and suggested report arguments     |
+| Report        | study report <result> --grading <sha256>                                                                                                                                       | Whole-horizon results for the selected grading                        |
+| Freeze        | study freeze <study> --profile <name> --to <directory>                                                                                                                         | Verified closure publication and relocated check fingerprint          |
 
 Success writes a JSON document. The next field contains suggested argv and never executes it automatically. Execution returns a result identity independently of the original study selector. Result selection accepts an identity under tmp/studies, a contained root-relative path, or an absolute path. Relative output paths stay inside the consumer working directory; existing output directories refuse execution. A relative result, --out, --rubric or --labels path, and a declared rubric path, separates its names with forward slashes and names no . or .. segment; profile paths resolve against the consumer root. Without --out, execution writes its result under tmp/studies by its new identity; the suggested execution arguments a check returns carry no --out.
 
+Freeze retains the selected declarations, exact scenario and profile bytes, the adapter graph, every admitted package member, and the trusted runtime entry. It validates the relocated selection in a fresh captured child, rechecks source and destination, and writes closure.json exclusively after those checks pass. The publication retains the original execution identity, the relocated identity, and the relocated fingerprint separately. A validation-time write leaves the destination available for inspection with no publication marker; retry with an absent destination.
+
+Check and execute accept --closure <directory>. Each operation verifies the published member census and bytes, uses the relocated root, entry, profile, and adapter, and compares the fresh check to the retained relocated identity. Only the root closure.json marker sits outside the copied-member census. An added file, omitted member, or changed non-entry dependency or asset refuses validation. The suggested execution arguments retain the closure selection for the supervisor.
+
 Check returns a fingerprint for the declared execution selection. Pass that fingerprint through --expected to pin execution. Both check and execute require a quality profile to declare a qualification path. Execute then requires that path to select a sealed capacity result with the same identity, bounds, schedule, and scenarios and no operational failures. Check validates the declaration offline without opening the capacity result. Capacity and mechanism studies execute without a qualification. Grade names an exact independent rubric path. Label and report require an exact grading identity; no operation guesses a grading version. Imported labels are caller-supplied bytes, not a labeler invoked by this command. A labeled grading binds the preceding grading's instrument, so equal labels over different gradings retain different identities.
 
+The `validateStudyInputs` function enforces the quality qualification requirement after the existing population, profile, room, reference, and coverage checks. Direct callers receive the same `CONFIG` refusal as the command when a quality profile omits its qualification. Capacity and mechanism inputs require no qualification.
+
+A labeled grading's instrument combines the executable entry's byte hash with the inventory digest for its owning Study package. The inventory binds the exact bytes of `package.json` and every `.js`, `.mjs`, `.cjs`, and `.json` file under `dist`, including the server and core entries, with the selected entry, canonical paths, package identity, file sizes, Node version, runtime arguments, `NODE_OPTIONS`, platform, and architecture. Declaration and source-map files are excluded from module capture unless explicitly selected as custody-only assets. Changing an admitted manifest, module, or explicit asset changes its inventory digest. Label identities are host-sensitive, as grading identities are.
+
 Help succeeds on stdout when --help appears anywhere. Empty arguments and invalid public grammar report on stderr with exit code 64. Operational diagnostics carry a study:CODE prefix and the refused token or path when applicable. Other exits are 0 for success, 124 for deadline, 130 for interruption, and 1 for operational failure. Private child routes require the native IPC boundary.
 
+The `study --version` command prints the installed Study package's version and a newline without reading consumer declarations or starting child work. The `readStudyVersion` function reads that package's manifest at run time, independently of the consumer's manifest. Additional version arguments refuse with exit code 64; `--help` still takes precedence. A missing or empty runtime version refuses with the `CONFIG` code.
+
 An adapter error response preserves the `CONFIG` code and translates other returned codes to `FAULT`.
 
-Check, grade, label, and report have a fixed 60-second allowance. Execution checks first, then uses the declared series duration with a 15-second cleanup allowance. The command supervises process trees; consumer adapters remain trusted code.
+Check, freeze, grade, label, and report have a fixed 60-second allowance. Execution checks first with the selected closure, then forwards the complete closure and replay selections unchanged and uses the declared series duration with a 15-second cleanup allowance. The command supervises process trees; consumer adapters remain trusted code.
 
 ## Guide parity
 
@@ -187,6 +287,8 @@ The following declarations describe this concept.
 | Name                               | Kind      | Summary                                                                                                                        |
 | ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
 | `ARTIFACT_BYTES`                   | const     | Bounds all captured input bytes to 128 MiB.                                                                                    |
+| `ARTIFACT_ERROR_BRAND`             | const     | Marks artifact errors across module formats and installations.                                                                 |
+| `ARTIFACT_ERROR_CODES`             | const     | Lists the artifact refusal codes.                                                                                              |
 | `ARTIFACT_DEPTH`                   | const     | Bounds directory nesting below each selected root.                                                                             |
 | `ARTIFACT_FILES`                   | const     | Bounds admitted files before another capture is allocated.                                                                     |
 | `ARTIFACT_FILE_BYTES`              | const     | Bounds one captured input file to 16 MiB.                                                                                      |
@@ -315,6 +417,7 @@ The following declarations describe this concept.
 | `StudyMeterOptions`                | interface | Supplies the request allowance and all enclosing admission scopes.                                                             |
 | `StudyObservation`                 | interface | Holds the retained outcome of a scheduled goal.                                                                                |
 | `StudyOllamaActivity`              | interface | Holds one active goal's accounting and attribution.                                                                            |
+| `StudyOllamaFetchFunction`         | type      | Sends one validated, admitted request under its Study role and returns the native response.                                    |
 | `StudyOllamaModel`                 | interface | Pins one served model identity the inventory verifies.                                                                         |
 | `StudyOllamaOptions`               | type      | Holds the Ollama provider options one role's declared policy determines.                                                       |
 | `StudyOllamaPolicy`                | interface | Declares one model role's exact wire policy.                                                                                   |
@@ -384,9 +487,13 @@ The following declarations describe this concept.
 | `StudyWorker`                      | class     | Executes one verified trial behind parent-authorized admission and custody.                                                    |
 | `buildStudyAgentDispatch`          | function  | Builds the evidence join of a wire request to its canonical dispatch.                                                          |
 | `buildStudyAgentParts`             | function  | Projects a request's structural components onto plain JSON without storing a total.                                            |
+| `readStudyAgentToolCall`           | function  | Reads an Agent tool call into a validated envelope from one read of each foreign field.                                        |
+| `buildStudyAgentToolResult`        | function  | Builds the JSON evidence form of an Agent tool call and its executed result.                                                   |
+| `buildStudyAgentToolDenial`        | function  | Builds the JSON evidence form of an Agent tool call the Agent denied before dispatch.                                          |
 | `buildStudyAgentReadings`          | function  | Builds the JSON evidence form of a Ledger result's logical classifier readings.                                                |
 | `buildStudyAgentRevision`          | function  | Builds a request revision by hashing its canonical rendering exactly as rendered.                                              |
 | `buildStudyOllamaModels`           | function  | Declares the pinned serving identities the Ollama transport verifies, keyed by the label their inventory evidence carries.     |
+| `buildStudyOllamaBytes`            | function  | Encodes exact application bytes with their decoded size and SHA-256 identity.                                                  |
 | `buildStudyOllamaOptions`          | function  | Builds the provider options one role's declared wire policy determines.                                                        |
 | `buildStudyOllamaRaw`              | function  | Builds a reading of the raw prompt text an encoded request body carries, as sent.                                              |
 | `buildStudyOllamaSnapshot`         | function  | Builds an owned snapshot of one outbound request before anything is awaited.                                                   |
@@ -414,13 +521,14 @@ The following declarations describe this concept.
 | `decodeStudyJSON`                  | function  | Decodes strict UTF-8 custody bytes and parses their JSON text.                                                                 |
 | `drainStudyChild`                  | function  | Releases inherited output handles a bounded time after native exit.                                                            |
 | `encodeStudyJSON`                  | function  | Encodes deterministic JSON bytes without synthesizing execution metadata.                                                      |
-| `failStudyTicket`                  | function  | Records an error that escaped admitted work as the failure of its ticket.                                                      |
+| `failStudyTicket`                  | function  | Records an error thrown by admitted work as the failure of its ticket.                                                         |
 | `failureToStudyError`              | function  | Converts an operational reading to its throwable boundary.                                                                     |
 | `gradeStudyEvidence`               | function  | Grades every declared trial and criterion pair through the consumer's predicate.                                               |
 | `hashStudyBytes`                   | function  | Computes the lowercase SHA-256 identity of exact bytes or UTF-8 text.                                                          |
 | `isArtifactError`                  | function  | Narrows a caught value to an artifact refusal.                                                                                 |
 | `isStudyAdapter`                   | function  | Checks whether a factory returned the complete consumer adapter contract.                                                      |
 | `isStudyAgentResponse`             | function  | Checks whether a scripted response has JSON calls and workload controls.                                                       |
+| `isStudyAgentGauge`                | function  | Checks whether a value is a gauge with a finite positive scale and a finite nonnegative overhead.                              |
 | `isStudyAgentRuntime`              | function  | Checks whether a namespace exposes the Agent capabilities the instrumentation invokes.                                         |
 | `isStudyBounds`                    | function  | Checks whether nested scopes admit no larger allowance than their parent.                                                      |
 | `isStudyCause`                     | const     | Checks whether a value names an operational ending.                                                                            |
@@ -437,7 +545,7 @@ The following declarations describe this concept.
 | `isStudyCustodyTrial`              | function  | Checks whether a scheduled trial has exact valid identity fields.                                                              |
 | `isStudyDefinition`                | function  | Checks whether a study freezes a complete arm order for every repetition.                                                      |
 | `isStudyDigest`                    | function  | Checks whether a byte identity is a lowercase SHA-256 digest.                                                                  |
-| `isStudyError`                     | function  | Narrows a caught value to an attributable study error.                                                                         |
+| `isStudyError`                     | function  | Narrows a caught value to a branded study error with valid failure attribution.                                                |
 | `isStudyErrorCode`                 | function  | Checks whether a value names a supported study error code.                                                                     |
 | `isStudyEvidence`                  | function  | Checks append-only public evidence.                                                                                            |
 | `isStudyFrame`                     | function  | Checks the complete transport envelope before domain handling.                                                                 |
@@ -501,6 +609,12 @@ The following declarations describe this concept.
 | `validateStudyOllamaCompletion`    | function  | Checks terminal policy after the actual wire cost has been retained.                                                           |
 | `validateStudyOllamaInventory`     | function  | Verifies that each pinned name resolves to one inventory entry with its pinned digest.                                         |
 | `validateStudyOllamaRoles`         | function  | Validates declared role policies against the pinned inventory before any dispatch.                                             |
+| `validateStudyOllamaRecording`     | function  | Validates independent metadata bounds and the complete optional recording group.                                               |
+| `validateStudyOllamaStep`          | function  | Admits one model request against its next exact or capture declaration.                                                        |
+| `isStudyOllamaMetadata`            | function  | Checks whether a value declares independent positive metadata allowances.                                                      |
+| `isStudyOllamaModel`               | function  | Checks whether a value pins a served model name and SHA-256 digest.                                                            |
+| `isStudyOllamaPolicy`              | function  | Checks whether a value declares a complete finite model-generation policy.                                                     |
+| `isStudyOllamaStep`                | function  | Checks whether a value declares exclusive exact or capture admission with a valid receipt.                                     |
 | `validateStudyRuntime`             | function  | Refuses a profile that omits the actual host runtime's declared dependency bytes.                                              |
 | `valueToWire`                      | function  | Projects optional domain fields into the JSON wire representation.                                                             |
 | `writeStudyBytes`                  | function  | Writes an exclusive regular record and synchronizes it before reporting success.                                               |
@@ -516,20 +630,135 @@ The following declarations describe this concept.
 | `parseStudyReading`                | function  | Parses a foreign reading into a number a stop can retain.                                                                      |
 | `computeStudyAdmittedStop`         | function  | Computes the stop of a request whose actual usage crossed the ceiling it was admitted under.                                   |
 | `computeStudyOutputStop`           | function  | Computes the stop of a product the output allowances cannot hold.                                                              |
+| `StudyDeclaration`                 | interface | Holds a parsed study declaration with its driver bundle, scenarios, scenario fixtures, and rubric.                             |
+| `readStudyDeclaration`             | function  | Reads a study declaration, its driver's scenarios, and its rubric as the command resolves them.                                |
+| `readStudyDeclarationBytes`        | function  | Reads one declaration file and refuses a missing or linked path with its root-relative path.                                   |
+| `readStudyVersion`                 | function  | Reads the version of the study package that owns an executable entry.                                                          |
+| `matchesSystemError`               | function  | Reports whether a caught value is a Node error carrying the given system code.                                                 |
+| `StudyDaemon`                      | interface | Pins an executable and the model population an execution owns until cleanup.                                                   |
+| `StudyDaemonModel`                 | interface | Pins one model the declared daemon verifies and unloads before each trial.                                                     |
+| `StudyRecord`                      | interface | Bounds the serialized exchange sidecar retained for each scheduled trial.                                                      |
+| `ArtifactErrorCode`                | type      | Names the refused boundary of a captured or materialized artifact graph.                                                       |
+| `ArtifactMember`                   | interface | Maps one admitted physical file to its exact bytes inside a materialized forest.                                               |
+| `ArtifactClosure`                  | interface | Binds a verified physical forest to its relocated selections and complete membership.                                          |
+| `ArtifactLoaderInterface`          | interface | Captures, verifies, loads, and materializes one admitted physical artifact graph.                                              |
+| `computeArtifactClosureDigest`     | function  | Computes a destination-independent digest of members and relative package identities.                                          |
+| `isArtifactClosure`                | function  | Checks a bounded materialization record before any path is used.                                                               |
+| `isArtifactKey`                    | function  | Checks whether a key names portable, non-credential members within a closure.                                                  |
+| `isArtifactLoaderOptions`          | function  | Checks the bounded loader selections retained in a publication.                                                                |
+| `isArtifactMember`                 | function  | Checks the exact file identity and provenance of a closure member.                                                             |
+| `isStudyClosure`                   | function  | Checks a closure publication before using its command inputs.                                                                  |
+| `matchesArtifactCredential`        | function  | Checks whether a portable segment identifies credentials.                                                                      |
+| `readArtifactPhysical`             | function  | Checks every existing physical ancestor before using a canonical absolute path.                                                |
+| `readStudyClosure`                 | function  | Reads and independently verifies an exclusively published closure.                                                             |
+| `relocateArtifactPath`             | function  | Relocates an original path through a closure's retained physical forest.                                                       |
+| `resolveArtifactBase`              | function  | Finds the common physical parent that preserves every selected path's relative resolution.                                     |
+| `resolveArtifactMember`            | function  | Resolves a portable member key without traversing outside its destination.                                                     |
+| `resolveStudyClosurePath`          | function  | Resolves a profile path through a retained physical relocation when selected.                                                  |
+| `verifyArtifactClosure`            | function  | Verifies complete copied membership, path safety, exact bytes, and portable identity.                                          |
+| `StudyOllamaMetadata`              | interface | Bounds metadata calls, encoded bytes, and elapsed milliseconds outside model quotas.                                           |
+| `StudyOllamaStage`                 | type      | Names the ordered verification, model work, and daemon maintenance stages.                                                     |
+| `StudyOllamaStepIdentity`          | interface | Declares an ordered model request's goal, responsibility, route, and wire policy.                                              |
+| `StudyOllamaExactStep`             | interface | Declares an exact UTF-8 request body and its SHA-256 input receipt.                                                            |
+| `StudyOllamaCaptureStep`           | interface | Declares a captured request's positive safe byte length without predicting its content.                                        |
+| `StudyOllamaStep`                  | type      | Separates exact request admission from length-declared capture admission.                                                      |
+| `StudyOllamaReplaySelection`       | interface | Selects a sealed recording and an explicit replay prefix for every scheduled trial.                                            |
+| `StudyOllamaReplayOptions`         | interface | Configures exact recorded replies and optional live continuation after a declared prefix.                                      |
+| `StudyOllamaReplayInterface`       | interface | Answers an exact recorded prefix through the role-aware transport collaborator.                                                |
+| `StudyExchangeDestination`         | interface | Holds the parent-reserved destination of one trial's exchange sidecar.                                                         |
+| `StudyExchangeBytes`               | interface | Retains an application HTTP body's exact bytes independently of text decoding.                                                 |
+| `StudyExchangeIdentity`            | interface | Binds one HTTP exchange to its trial-local position and declared execution stage.                                              |
+| `StudyExchangeDeclaration`         | interface | Declares the complete trial procedure before any exchange attempt is appended.                                                 |
+| `StudyExchangeAttempt`             | interface | Retains admitted request bytes durably before the corresponding send begins.                                                   |
+| `StudyExchangeReply`               | interface | Retains response status, headers, and original application-body chunk lengths.                                                 |
+| `StudyExchangeResponse`            | interface | Retains a fully consumed response only after status and terminal validation succeed.                                           |
+| `StudyExchangeFailure`             | interface | Retains an attempted exchange's failure and any bounded response bytes already observed.                                       |
+| `StudyExchangeCompletion`          | interface | Closes a sidecar after the declared procedure and postflight have fully completed.                                             |
+| `StudyExchangeRow`                 | type      | Names every admitted row of the bounded per-trial exchange sidecar.                                                            |
+| `StudyRecordedExchange`            | interface | Holds a strictly verified successful request and response pair.                                                                |
+| `StudyExchangeHistory`             | interface | Binds complete ordered exchanges to a verified sealed sidecar and its declaration.                                             |
+| `StudyExchangeSinkInterface`       | interface | Owns serialized exchange appends under a reserved trial byte allowance.                                                        |
+| `StudyExchangeSinkOptions`         | interface | Supplies an exclusive sidecar descriptor and its parent-reserved byte allowance.                                               |
+| `StudyFreezeRequest`               | interface | Requests exclusive materialization and captured validation before publishing closure.json.                                     |
+| `StudyClosure`                     | interface | Publishes a validated closure with relocated command inputs and execution provenance.                                          |
+| `StudyTrialPreparationFunction`    | type      | Prepares one trial's external resources before its worker starts.                                                              |
+| `StudyProcessDriverOptions`        | interface | Supplies parent-only trial preparation separately from serializable worker options.                                            |
+| `StudyExchangeSink`                | class     | Retains ordered exchange rows under a parent-reserved serialized byte allowance.                                               |
+| `StudyOllamaReplay`                | class     | Answers declared HTTP prefixes from complete ordered recorded application bytes.                                               |
+| `isStudyRecord`                    | function  | Checks whether a recording declaration bounds every serialized sidecar byte.                                                   |
+| `isStudyExchangeBytes`             | function  | Checks whether encoded body bytes have their exact canonical base64 and SHA-256 identity.                                      |
+| `isStudyExchangeIdentity`          | function  | Checks whether an exchange carries an admissible ordered HTTP identity.                                                        |
+| `isStudyExchangeReply`             | function  | Checks whether a retained reply describes bounded successful application bytes and chunks.                                     |
+| `isStudyExchangeDeclaration`       | function  | Checks whether the opening row declares a finite ordered procedure and serving identities.                                     |
+| `isStudyExchangeRow`               | function  | Checks whether a sidecar row has exactly its declared fields and verified byte identities.                                     |
+| `isStudyExchangeHistory`           | function  | Checks whether a history has verified row shapes before its complete relational validation.                                    |
+| `buildStudyExchangeSequence`       | function  | Projects the declaration onto its complete ordered HTTP identity population.                                                   |
+| `projectStudyExchangeIdentity`     | function  | Projects only the repeated identity fields of a retained HTTP exchange.                                                        |
+| `validateStudyExchangeRequest`     | function  | Validates the exact declaration order and request bytes of an admitted exchange.                                               |
+| `validateStudyExchangeRows`        | function  | Validates a serialized journal prefix or its complete successful population.                                                   |
+| `readStudyExchangeRows`            | function  | Reads strict complete LF-framed exchange rows with verified bodies and declaration joins.                                      |
+| `validateStudyExchangeHistory`     | function  | Validates complete history envelopes again before a replay may perform dependent work.                                         |
+| `validateStudyExchangeEvidence`    | function  | Joins recorded exchanges to exactly one dispatch and wire evidence identity per ordinal.                                       |
+| `readStudyTrialExchanges`          | function  | Reads and joins a complete trial sidecar before or after sealing.                                                              |
+| `readStudyExchanges`               | function  | Reads a sealed trial's exact complete exchange history after reverifying its entire result.                                    |
+| `isStudyExchangeDestination`       | function  | Checks whether a worker destination has an absolute sidecar path and finite reservation.                                       |
+| `isStudyReplaySelection`           | function  | Checks whether replay explicitly selects a sealed directory and per-trial prefix counts.                                       |
+| `readStudyRecordingDeclaration`    | function  | Reads the executing profile's explicit recording declarations before a worker starts.                                          |
+| `readStudyPreparedDestination`     | function  | Validates parent preparation output without permitting a destination or allowance substitution.                                |
+| `readStudyReplayHistory`           | function  | Rechecks the sealed source and this trial's prefix under the executing profile declaration.                                    |
+
+| API                         | Kind      | Summary                                                                                     |
+| --------------------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `StudyDaemonSession`        | class     | Owns the declared daemon and its serial trial preparation through permanent cleanup.        |
+| `StudyDaemonTrial`          | class     | Records one trial's daemon maintenance before handing its verified prefix to a worker.      |
+| `StudyDaemonSessionOptions` | interface | Supplies the resolved provider, trial population, workspace, and execution cancellation.    |
+| `StudyDaemonTrialOptions`   | interface | Supplies one reserved sidecar and its complete maintenance declaration.                     |
+| `isStudyDaemon`             | function  | Checks whether an owned daemon declaration pins an absolute executable and distinct models. |
 
 ## Methods
 
+#### `StudyDaemonSession`
+
+The execution host composes these methods.
+
+| Method    | Summary                                                            |
+| --------- | ------------------------------------------------------------------ |
+| `start`   | Starts the daemon and returns its verified execution provenance.   |
+| `prepare` | Unloads the declared population before opening one trial worker.   |
+| `stop`    | Stops and joins the owned tree and refuses an unconfirmed cleanup. |
+
+#### `StudyDaemonTrial`
+
+The preparation sender composes these methods.
+
+| Method    | Summary                                                                                |
+| --------- | -------------------------------------------------------------------------------------- |
+| `execute` | Unloads declared models, drains the journal, and returns its exact retained identity.  |
+| `fetch`   | Retains each request before sending and preserves the sender's native response chunks. |
+
 The following tables name the callable members.
 
 #### `ArtifactLoader`
 
 The declaration exposes these methods.
 
-| Method    | Summary                                                                  |
-| --------- | ------------------------------------------------------------------------ |
-| `inspect` | Reads and identifies admitted files without evaluating selected modules. |
-| `load`    | Imports one selected entry through synchronous captured-byte hooks.      |
-| `verify`  | Refuses byte and population drift since inspection.                      |
+| Method        | Summary                                                                    |
+| ------------- | -------------------------------------------------------------------------- |
+| `inspect`     | Reads and identifies admitted files without evaluating selected modules.   |
+| `load`        | Imports one selected entry through synchronous captured-byte hooks.        |
+| `materialize` | Copies the inspected physical forest into an exclusive absent destination. |
+| `verify`      | Refuses byte and population drift since inspection.                        |
+
+#### `ArtifactLoaderInterface`
+
+The declaration exposes these methods.
+
+| Method        | Summary                                                                    |
+| ------------- | -------------------------------------------------------------------------- |
+| `inspect`     | Captures the complete admitted population without evaluating modules.      |
+| `verify`      | Refuses changed bytes or membership after inspection.                      |
+| `load`        | Loads an admitted entry through captured-byte hooks in a fresh process.    |
+| `materialize` | Copies the inspected physical forest into an exclusive absent destination. |
 
 #### `Resolution`
 
@@ -835,23 +1064,61 @@ The declaration exposes these methods.
 
 The declaration exposes these methods.
 
-| Method   | Summary                                                                           |
-| -------- | --------------------------------------------------------------------------------- |
-| `create` | Exclusively creates the result directory and initial manifest bytes.              |
-| `finish` | Closes evidence admission, drains admitted appends, and writes a terminal record. |
-| `seal`   | Seals exact execution inventory after every scheduled trial has terminated.       |
-| `start`  | Exclusively creates the evidence sink for an exact scheduled trial.               |
+| Method      | Summary                                                                           |
+| ----------- | --------------------------------------------------------------------------------- |
+| `create`    | Exclusively creates the result directory and initial manifest bytes.              |
+| `exchanges` | Reserves a trial's entire exchange allowance before any worker starts.            |
+| `finish`    | Closes evidence admission, drains admitted appends, and writes a terminal record. |
+| `seal`      | Seals exact execution inventory after every scheduled trial has terminated.       |
+| `start`     | Exclusively creates the evidence sink for an exact scheduled trial.               |
+
+#### `StudyExchangeSink`
+
+The declaration exposes these methods.
+
+| Method   | Summary                                                                                  |
+| -------- | ---------------------------------------------------------------------------------------- |
+| `append` | Appends one owned row after validating order and reserving its complete serialized size. |
+| `close`  | Closes admission, drains accepted writes and synchronizes the owned descriptor.          |
+
+#### `StudyExchangeSinkInterface`
+
+The declaration exposes these methods.
+
+| Method   | Summary                                                                             |
+| -------- | ----------------------------------------------------------------------------------- |
+| `append` | Appends one validated row after reserving its complete serialized size.             |
+| `close`  | Closes admission and synchronizes all admitted writes without inventing completion. |
+
+#### `StudyOllamaReplay`
+
+The declaration exposes these methods.
+
+| Method  | Summary                                                                    |
+| ------- | -------------------------------------------------------------------------- |
+| `check` | Refuses a mismatch, an unread response or an incompletely consumed prefix. |
+| `close` | Closes admission and cancels retained replay responses.                    |
+
+#### `StudyOllamaReplayInterface`
+
+The declaration exposes these methods.
+
+| Method  | Summary                                                                             |
+| ------- | ----------------------------------------------------------------------------------- |
+| `check` | Refuses a latched mismatch, an unread response, or an incompletely consumed prefix. |
+| `close` | Closes admission and cancels or drains owned response readers.                      |
 
 #### `StudyResultStoreInterface`
 
 The declaration exposes these methods.
 
-| Method   | Summary                                                                       |
-| -------- | ----------------------------------------------------------------------------- |
-| `create` | Exclusively creates the result directory and initial manifest bytes.          |
-| `finish` | Retains the terminal record for one scheduled trial.                          |
-| `seal`   | Seals a complete terminal population with its exact execution-byte inventory. |
-| `start`  | Opens append-only evidence custody for one scheduled trial.                   |
+| Method      | Summary                                                                                    |
+| ----------- | ------------------------------------------------------------------------------------------ |
+| `create`    | Exclusively creates the result directory and initial manifest bytes.                       |
+| `exchanges` | Reserves a declared trial's sidecar allowance and returns its exclusive write destination. |
+| `finish`    | Retains the terminal record for one scheduled trial.                                       |
+| `seal`      | Seals a complete terminal population with its exact execution-byte inventory.              |
+| `start`     | Opens append-only evidence custody for one scheduled trial.                                |
 
 #### `StudyScope`
 
@@ -917,7 +1184,7 @@ The declaration exposes these methods.
 | --------- | -------------------------------------------------------------- |
 | `execute` | Executes one validation or grading operation in a fresh child. |
 
-Task and trial children settle on their close event, which waits for inherited output handles. After a child's native exit those handles are destroyed once `STUDY_DRAIN_DURATION` (1 second) elapses, so a descendant that holds the output cannot leave the parent unsettled. A task still rejects for a missing complete response, and a session still rejects its start and fulfills its close. This releases only the parent's read handles: a descendant that survives an exited root is outside discoverable-tree cleanup and is neither found nor terminated. Linux behavior is unverified.
+Task and trial children settle on their close event, which waits for inherited output handles. After a child's native exit those handles are destroyed after `STUDY_DRAIN_DURATION` (1 second) elapses, so a descendant that holds the output cannot leave the parent unsettled. A task still rejects for a missing complete response, and a session still rejects its start and fulfills its close. This releases only the parent's read handles: a descendant that survives an exited root is outside discoverable-tree cleanup and is neither found nor terminated. Linux behavior is unverified.
 
 #### `StudyTaskWorker`
 
@@ -1293,7 +1560,7 @@ import { isStudyAdapter } from '@orkestrel/study/server'
 isStudyAdapter({}) // false
 ```
 
-### Fail an escaped request
+### Fail an admitted request
 
 Use the exported declaration with its documented arguments.
 
@@ -1716,6 +1983,34 @@ await trace.flush(sink) // appends one `note` row for the goal `count`
 trace.goal // undefined
 ```
 
+### Validate recorded admission
+
+Validate the owned recording group, then check its next model request before dispatch.
+
+```ts
+import type { StudyOllamaTransportOptions, StudyOllamaRequest } from '@orkestrel/study/server'
+import {
+	buildStudyOllamaBytes,
+	isStudyOllamaMetadata,
+	isStudyOllamaModel,
+	isStudyOllamaPolicy,
+	isStudyOllamaStep,
+	validateStudyOllamaRecording,
+	validateStudyOllamaStep,
+} from '@orkestrel/study/server'
+
+declare const configured: StudyOllamaTransportOptions
+declare const request: StudyOllamaRequest
+declare const body: string
+validateStudyOllamaRecording(configured)
+isStudyOllamaMetadata(configured.metadata)
+isStudyOllamaModel(configured.models.model)
+isStudyOllamaPolicy(configured.roles.agent)
+isStudyOllamaStep(configured.procedure?.[0])
+validateStudyOllamaStep(configured.procedure?.[0], 'write', request, body)
+buildStudyOllamaBytes(new TextEncoder().encode(body))
+```
+
 ### Own transport inputs
 
 Copy declared configuration and mutable request headers before asynchronous admission.
@@ -1806,6 +2101,53 @@ import { computeStudyOutputStop } from '@orkestrel/study'
 computeStudyOutputStop(2048, 1024, []) // { layer: 'scope', id: 'Goal bytes', max: 1024, consumed: 2048 }
 ```
 
+### Read a study declaration
+
+Read the selected declaration and its driver fixtures before selecting a profile.
+
+```ts
+import type { StudyDeclaration } from '@orkestrel/study/server'
+import { readStudyDeclaration } from '@orkestrel/study/server'
+
+declare const root: string
+const declaration: StudyDeclaration = await readStudyDeclaration(root, 'assessment')
+```
+
+### Read declaration bytes
+
+Pass an already resolved and contained declaration path.
+
+```ts
+import { readStudyDeclarationBytes } from '@orkestrel/study/server'
+
+declare const root: string
+declare const path: string
+await readStudyDeclarationBytes(root, path)
+```
+
+### Read the installed version
+
+Pass the installed executable entry to read its owning package's manifest.
+
+```ts
+import { readStudyVersion } from '@orkestrel/study/server'
+
+declare const entry: string
+readStudyVersion(entry)
+```
+
+### Match a system error
+
+Match a caught Error without accepting an unbranded record.
+
+```ts
+import { matchesSystemError } from '@orkestrel/study/server'
+
+const error = Object.assign(new Error('Missing declaration'), { code: 'ENOENT' })
+matchesSystemError(error, 'ENOENT') // true
+matchesSystemError({ code: 'ENOENT' }, 'ENOENT') // false
+```
+
 ### Helper calls
 
 Supply the argument tuple from each helper's signature.
@@ -1964,6 +2306,58 @@ declare const validateStudyRuntimeArguments: Parameters<typeof validateStudyRunt
 validateStudyRuntime(...validateStudyRuntimeArguments)
 ```
 
+### Call closure helpers
+
+Supply the declared selections, captured records, and physical paths.
+
+```ts
+import {
+	computeArtifactClosureDigest,
+	isArtifactClosure,
+	isArtifactKey,
+	isArtifactLoaderOptions,
+	isArtifactMember,
+	isStudyClosure,
+	matchesArtifactCredential,
+	readArtifactPhysical,
+	readStudyClosure,
+	relocateArtifactPath,
+	resolveArtifactBase,
+	resolveArtifactMember,
+	resolveStudyClosurePath,
+	verifyArtifactClosure,
+} from '@orkestrel/study/server'
+
+declare const digest: Parameters<typeof computeArtifactClosureDigest>
+computeArtifactClosureDigest(...digest)
+declare const closure: Parameters<typeof isArtifactClosure>
+isArtifactClosure(...closure)
+declare const key: Parameters<typeof isArtifactKey>
+isArtifactKey(...key)
+declare const options: Parameters<typeof isArtifactLoaderOptions>
+isArtifactLoaderOptions(...options)
+declare const member: Parameters<typeof isArtifactMember>
+isArtifactMember(...member)
+declare const publication: Parameters<typeof isStudyClosure>
+isStudyClosure(...publication)
+declare const credential: Parameters<typeof matchesArtifactCredential>
+matchesArtifactCredential(...credential)
+declare const physical: Parameters<typeof readArtifactPhysical>
+readArtifactPhysical(...physical)
+declare const reader: Parameters<typeof readStudyClosure>
+readStudyClosure(...reader)
+declare const relocation: Parameters<typeof relocateArtifactPath>
+relocateArtifactPath(...relocation)
+declare const base: Parameters<typeof resolveArtifactBase>
+resolveArtifactBase(...base)
+declare const target: Parameters<typeof resolveArtifactMember>
+resolveArtifactMember(...target)
+declare const selection: Parameters<typeof resolveStudyClosurePath>
+resolveStudyClosurePath(...selection)
+declare const verification: Parameters<typeof verifyArtifactClosure>
+verifyArtifactClosure(...verification)
+```
+
 ### Call ArtifactLoader methods
 
 Supply an instance of the declared contract.
@@ -1976,6 +2370,8 @@ declare const inspect: Parameters<ArtifactLoader['inspect']>
 instance.inspect(...inspect)
 declare const load: Parameters<ArtifactLoader['load']>
 instance.load(...load)
+declare const materialize: Parameters<ArtifactLoader['materialize']>
+instance.materialize(...materialize)
 declare const verify: Parameters<ArtifactLoader['verify']>
 instance.verify(...verify)
 ```
@@ -2460,6 +2856,8 @@ Supply an instance of the declared contract.
 import type { StudyResultStore } from '@orkestrel/study/server'
 
 declare const instance: StudyResultStore
+declare const exchanges: Parameters<StudyResultStore['exchanges']>
+instance.exchanges(...exchanges)
 declare const create: Parameters<StudyResultStore['create']>
 instance.create(...create)
 declare const finish: Parameters<StudyResultStore['finish']>
@@ -2478,6 +2876,8 @@ Supply an instance of the declared contract.
 import type { StudyResultStoreInterface } from '@orkestrel/study/server'
 
 declare const instance: StudyResultStoreInterface
+declare const exchanges: Parameters<StudyResultStoreInterface['exchanges']>
+instance.exchanges(...exchanges)
 declare const create: Parameters<StudyResultStoreInterface['create']>
 instance.create(...create)
 declare const finish: Parameters<StudyResultStoreInterface['finish']>
@@ -2626,8 +3026,158 @@ declare const execute: Parameters<StudyWorker['execute']>
 instance.execute(...execute)
 ```
 
+### Declare and compose daemon staging
+
+The command owns staging for ordinary execution. A custom execution host can compose the same session and preparation contracts.
+
+```ts
+import { isStudyDaemon } from '@orkestrel/study'
+import { StudyDaemonSession, StudyDaemonTrial } from '@orkestrel/study/server'
+import { createOllamaDaemon } from '@orkestrel/ollama/server'
+import type { StudyDaemonSessionOptions, StudyDaemonTrialOptions } from '@orkestrel/study/server'
+
+isStudyDaemon({ executable: 'ollama' }) // false
+declare const options: StudyDaemonSessionOptions
+const session = new StudyDaemonSession(options)
+declare const prepare: Parameters<StudyDaemonSession['prepare']>
+try {
+	await session.start()
+	await session.prepare(...prepare)
+} finally {
+	await session.stop()
+}
+
+declare const trialOptions: StudyDaemonTrialOptions
+const trial = new StudyDaemonTrial(trialOptions)
+declare const declaration: Parameters<typeof createOllamaDaemon>[0]
+const daemon = createOllamaDaemon({
+	...declaration,
+	fetch: (input, init) =>
+		new URL(new Request(input, init).url).pathname === '/api/generate'
+			? trial.fetch(input, init)
+			: globalThis.fetch(input, init),
+})
+try {
+	await daemon.start()
+	await trial.execute(daemon)
+} finally {
+	await daemon.destroy()
+}
+```
+
 ## Tests
 
+The staging proofs drive the real command and worker over a Node protocol daemon on an ephemeral loopback port. The daemon records whether each unload's attempt was already readable on disk. The source suite proves repeated maintenance prefixes, exact ordinal joins, offline replay without a daemon or request, and startup, trial, unload, and cancellation cleanup while an unrelated sentinel survives. Setup proofs validate fixture declarations without starting a child.
+
+### Call exchange and replay helpers
+
+Supply validated declarations, retained bytes, or a selected sealed result as each contract requires.
+
+```ts
+import { isStudyRecord } from '@orkestrel/study'
+import {
+	buildStudyExchangeSequence,
+	isStudyExchangeBytes,
+	isStudyExchangeDeclaration,
+	isStudyExchangeDestination,
+	isStudyExchangeHistory,
+	isStudyExchangeIdentity,
+	isStudyExchangeReply,
+	isStudyExchangeRow,
+	isStudyReplaySelection,
+	projectStudyExchangeIdentity,
+	readStudyExchangeRows,
+	readStudyExchanges,
+	readStudyPreparedDestination,
+	readStudyRecordingDeclaration,
+	readStudyReplayHistory,
+	readStudyTrialExchanges,
+	validateStudyExchangeEvidence,
+	validateStudyExchangeHistory,
+	validateStudyExchangeRequest,
+	validateStudyExchangeRows,
+} from '@orkestrel/study/server'
+
+declare const isStudyRecordArguments: Parameters<typeof isStudyRecord>
+isStudyRecord(...isStudyRecordArguments)
+declare const buildStudyExchangeSequenceArguments: Parameters<typeof buildStudyExchangeSequence>
+buildStudyExchangeSequence(...buildStudyExchangeSequenceArguments)
+declare const isStudyExchangeBytesArguments: Parameters<typeof isStudyExchangeBytes>
+isStudyExchangeBytes(...isStudyExchangeBytesArguments)
+declare const isStudyExchangeDeclarationArguments: Parameters<typeof isStudyExchangeDeclaration>
+isStudyExchangeDeclaration(...isStudyExchangeDeclarationArguments)
+declare const isStudyExchangeDestinationArguments: Parameters<typeof isStudyExchangeDestination>
+isStudyExchangeDestination(...isStudyExchangeDestinationArguments)
+declare const isStudyExchangeHistoryArguments: Parameters<typeof isStudyExchangeHistory>
+isStudyExchangeHistory(...isStudyExchangeHistoryArguments)
+declare const isStudyExchangeIdentityArguments: Parameters<typeof isStudyExchangeIdentity>
+isStudyExchangeIdentity(...isStudyExchangeIdentityArguments)
+declare const isStudyExchangeReplyArguments: Parameters<typeof isStudyExchangeReply>
+isStudyExchangeReply(...isStudyExchangeReplyArguments)
+declare const isStudyExchangeRowArguments: Parameters<typeof isStudyExchangeRow>
+isStudyExchangeRow(...isStudyExchangeRowArguments)
+declare const isStudyReplaySelectionArguments: Parameters<typeof isStudyReplaySelection>
+isStudyReplaySelection(...isStudyReplaySelectionArguments)
+declare const projectStudyExchangeIdentityArguments: Parameters<typeof projectStudyExchangeIdentity>
+projectStudyExchangeIdentity(...projectStudyExchangeIdentityArguments)
+declare const readStudyExchangeRowsArguments: Parameters<typeof readStudyExchangeRows>
+readStudyExchangeRows(...readStudyExchangeRowsArguments)
+declare const readStudyExchangesArguments: Parameters<typeof readStudyExchanges>
+readStudyExchanges(...readStudyExchangesArguments)
+declare const readStudyPreparedDestinationArguments: Parameters<typeof readStudyPreparedDestination>
+readStudyPreparedDestination(...readStudyPreparedDestinationArguments)
+declare const readStudyRecordingDeclarationArguments: Parameters<
+	typeof readStudyRecordingDeclaration
+>
+readStudyRecordingDeclaration(...readStudyRecordingDeclarationArguments)
+declare const readStudyReplayHistoryArguments: Parameters<typeof readStudyReplayHistory>
+readStudyReplayHistory(...readStudyReplayHistoryArguments)
+declare const readStudyTrialExchangesArguments: Parameters<typeof readStudyTrialExchanges>
+readStudyTrialExchanges(...readStudyTrialExchangesArguments)
+declare const validateStudyExchangeEvidenceArguments: Parameters<
+	typeof validateStudyExchangeEvidence
+>
+validateStudyExchangeEvidence(...validateStudyExchangeEvidenceArguments)
+declare const validateStudyExchangeHistoryArguments: Parameters<typeof validateStudyExchangeHistory>
+validateStudyExchangeHistory(...validateStudyExchangeHistoryArguments)
+declare const validateStudyExchangeRequestArguments: Parameters<typeof validateStudyExchangeRequest>
+validateStudyExchangeRequest(...validateStudyExchangeRequestArguments)
+declare const validateStudyExchangeRowsArguments: Parameters<typeof validateStudyExchangeRows>
+validateStudyExchangeRows(...validateStudyExchangeRowsArguments)
+```
+
+### Call exchange sink methods
+
+Supply the worker-owned sink or its declared interface.
+
+```ts
+import type { StudyExchangeSink, StudyExchangeSinkInterface } from '@orkestrel/study/server'
+
+declare const sink: StudyExchangeSink
+declare const append: Parameters<StudyExchangeSink['append']>
+sink.append(...append)
+sink.close()
+declare const contract: StudyExchangeSinkInterface
+declare const row: Parameters<StudyExchangeSinkInterface['append']>
+contract.append(...row)
+contract.close()
+```
+
+### Call replay methods
+
+Supply a replay over a completely verified selected history.
+
+```ts
+import type { StudyOllamaReplay, StudyOllamaReplayInterface } from '@orkestrel/study/server'
+
+declare const replay: StudyOllamaReplay
+replay.check()
+replay.close()
+declare const contract: StudyOllamaReplayInterface
+contract.check()
+contract.close()
+```
+
 See the behavioral proofs in the following directories.
 
 - [tests/src/core](../tests/src/core)