@orkestrel/scaffold 0.0.125 → 0.0.127

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 (35) hide show
  1. package/dist/bin/main.js +50 -14
  2. package/dist/bin/main.js.map +1 -1
  3. package/dist/host/AGENTS.md +1 -1
  4. package/dist/host/agents/orchestration.md +5 -4
  5. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-harden/references/methods.md +2 -2
  7. package/dist/host/agents/skills/orkestrel-journey/SKILL.md +18 -19
  8. package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +2 -1
  9. package/dist/host/claude/AGENTS.md +2 -2
  10. package/dist/host/claude/agents/orkestrel.md +18 -18
  11. package/dist/host/claude/agents/planner.md +2 -2
  12. package/dist/host/claude/rules/quality.md +3 -0
  13. package/dist/host/claude/rules/tests.md +3 -0
  14. package/dist/host/claude/rules/workspace.md +11 -5
  15. package/dist/host/codex/agents/planner.toml +2 -2
  16. package/dist/host/guides/agent.md +285 -161
  17. package/dist/host/guides/capture.md +123 -123
  18. package/dist/host/guides/database.md +18 -7
  19. package/dist/host/guides/ndjson.md +4 -3
  20. package/dist/host/guides/ollama.md +2 -2
  21. package/dist/host/guides/program.md +3 -3
  22. package/dist/host/guides/qualifier.md +1 -1
  23. package/dist/host/guides/relation.md +71 -31
  24. package/dist/host/guides/scaffold.md +101 -64
  25. package/dist/host/guides/study.md +22 -12
  26. package/dist/host/guides/toolbox.md +9 -2
  27. package/dist/host/manifest.json +26 -26
  28. package/dist/host/tests/config.test.ts +24 -6
  29. package/dist/src/core/index.cjs +134 -79
  30. package/dist/src/core/index.cjs.map +1 -1
  31. package/dist/src/core/index.d.cts +30 -7
  32. package/dist/src/core/index.d.ts +30 -7
  33. package/dist/src/core/index.js +134 -80
  34. package/dist/src/core/index.js.map +1 -1
  35. package/package.json +4 -4
@@ -123,7 +123,11 @@ Call `gradeStudyEvidence` from an adapter's grade method to traverse the declare
123
123
 
124
124
  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.
125
125
 
126
- 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.
126
+ 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. The agent, summary, and judge roles declare their 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.
127
+
128
+ The `triage` role sends System One requests to `/v1/systemone`. Its `StudySystemOnePolicy` declares the pinned `model` and a positive safe `tokens` ceiling for the complete request. The transport reserves that ceiling, bounds request and response bytes and elapsed time, validates the complete JSON response through Agent's System One envelope guard, and charges the request once. Reported input and output usage stay known; absent readings stay unknown. Triage invents no generation options, finish reason, or Ollama timing. `isStudySystemOnePolicy` validates this policy independently of generation policies. A consumer passes `transport.fetch('triage', input, init)` as its System One judge's fetch collaborator.
129
+
130
+ A provider declares `triage` and `digest.triage` together. Both metadata passes verify the pin through tags and show, configuration identity retains it, and a declared daemon includes it in its verified maintenance population. A transport fault on this leg fails the trial even if the consumer catches it; it cannot produce successful recording completion. A well-transported answer the consumer semantically refuses remains the consumer's decision to refer onward. Study chooses no model name or probability cutoff.
127
131
 
128
132
  Recording reads version and optional procedure from the exchange sink's opening declaration. The transport refuses metadata or model pins that differ from that row. 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 the admitted execution sequence; a declared procedure also requires every step to finish. The parent composes the declaration, and the worker retains that row after verifying any maintenance prefix.
129
133
 
@@ -167,7 +171,7 @@ The `StudyAgentSummary` class measures one canonical array, the folded messages
167
171
 
168
172
  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.
169
173
 
170
- The `readStudyAgentMessages` function projects provider messages onto the role, content, and call fields a workload reads. The `buildStudyAgentAttempts` function projects a Ledger result's attempts 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.
174
+ The `readStudyAgentMessages` function projects provider messages onto the role, content, and call fields a workload reads. The `buildStudyAgentAttempts` function projects a Ledger result's attempts onto JSON. The `buildStudyOllamaModels` function pins the model and each declared judge or triage name and digest. The `buildStudyOllamaOptions` function projects a generation role policy onto provider options and adds `truncate` and `shift` as `false` only for a strict policy.
171
175
 
172
176
  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.
173
177
 
@@ -228,7 +232,7 @@ The `StudyOllamaReplay` class validates the complete retained history before con
228
232
 
229
233
  A live prefix must end between the end of preflight and the end of execution, inclusive; postflight runs live. An offline prefix must cover the complete history. Replay bounds come from the executing declaration: calls equal record calls plus metadata calls, bytes equal record bytes, and duration equals the profile's trial duration. The transport also enforces its executing recording bounds.
230
234
 
231
- Keyed replay selects `--replay <result> --roles <JSON roles> --offline <true|false>`, and `--roles` is exclusive with `--prefix` and `--extend`. The roles are a JSON list of distinct members of `agent`, `judge`, `summary`, and `metadata`. The `StudyOllamaKeyedReplay` class serves a listed role's request whose path, method, and body bytes equal a recorded attempt of that role in any trial of the sealed source, the first recorded when a request repeats, so every arm of a screen reads one draw for one request. The key holds the role, so an earlier attempt of another role hides no later one. A served reply marks its `wire` evidence row, a budget's `cut` row of it, and its usage `replayed`. The progress reader and the report count it under `replayed` and leave it out of what the execution spent: `prompt`, `cached`, `completion`, and `total` in progress, and every cost in the report. A served request still charges its enclosing budgets. Under `--offline false` every other request sends live, and `metadata` cannot be listed, because served inventory verifies the recording, not the daemon. Under `--offline true` every other request refuses before send, no daemon starts, and a replay no adapter reached refuses at close. An adapter passes the replay through the transport's `replay` option, which is how the transport knows what it served. A changed sealed source refuses with the `CUSTODY` code before any request or result directory. Keyed replay compares no runtime and no declaration, because the request's own bytes are the key, and it requires the source to declare the executing provider's model pins. The manifest and each sidecar declaration retain the source's result, seal, identity, roles, and offline behavior under `keyed`, and the report names them. The executing profile must declare recording.
235
+ Keyed replay selects `--replay <result> --roles <JSON roles> --offline <true|false>`, and `--roles` is exclusive with `--prefix` and `--extend`. The roles are a JSON list of distinct members of `agent`, `judge`, `triage`, `summary`, and `metadata`. The `StudyOllamaKeyedReplay` class serves a listed role's request whose path, method, and body bytes equal a recorded attempt of that role in any trial of the sealed source, the first recorded when a request repeats, so every arm of a screen reads one draw for one request. The key holds the role, so an earlier attempt of another role hides no later one. A served reply marks its `wire` evidence row, a budget's `cut` row of it, and its usage `replayed`. The progress reader and the report count it under `replayed` and leave it out of what the execution spent: `prompt`, `cached`, `completion`, and `total` in progress, and every cost in the report. A served request still charges its enclosing budgets. Under `--offline false` every other request sends live, and `metadata` cannot be listed, because served inventory verifies the recording, not the daemon. Under `--offline true` every other request refuses before send, no daemon starts, and a replay no adapter reached refuses at close. An adapter passes the replay through the transport's `replay` option, which is how the transport knows what it served. A changed sealed source refuses with the `CUSTODY` code before any request or result directory. Keyed replay compares no runtime and no declaration, because the request's own bytes are the key, and it requires the source to declare the executing provider's model pins. The manifest and each sidecar declaration retain the source's result, seal, identity, roles, and offline behavior under `keyed`, and the report names them. The executing profile must declare recording.
232
236
 
233
237
  The `StudyIdentity` interface retains location-independent runtime and content digests alongside the captured loading identities. Runtime binds the Node version, execution arguments, NODE_OPTIONS, platform, and architecture. Content binds admitted package names and versions, package manifests, dist files, source code files, selected entries, source root, and Study executable bytes, with paths relative to the admitted roots' common base. Fixture JSON and closure assets stay outside content. Replay requires equal runtime and permits different content; loading still uses the captured inventories and their existing custody checks.
234
238
 
@@ -240,6 +244,8 @@ The parent derives a live replay prefix ending immediately before each ancestor'
240
244
 
241
245
  The descendant retains a complete flat sidecar: its extended declaration and ancestor prefix, live maintenance, replayed request and response bytes with recorded chunk lengths, live execution, live postflight, and completion. Its manifest links the immediate ancestor, so a later segment needs only that complete descendant. Replayed goals emit their evidence again and count against recording calls; their send-to-settlement time follows the executing recording duration allowance.
242
246
 
247
+ Triage participates in open recording and in exact or capture procedures using its System One route and policy. Strict sidecar reading checks the same identity, ordering, receipts, and completion as for other roles. Prefix and keyed replay retain original response bytes and chunk lengths. An offline replay sends nothing, and a keyed triage miss cannot borrow another role's recorded answer. Replayed triage usage still charges admission budgets, while progress and reports attribute it to `triage`, count it as replayed, and exclude it from live spending. Continuation requires open recording, replays the ancestor goals, and sends only the grown horizon's suffix live. Keyed replay remains exclusive with `--extend`, and every keyed execution still requires recording.
248
+
243
249
  Check binds the ancestor's seal into the execution fingerprint and carries the resolved extension selector in its next argv. The launcher forwards that selector to both check and execute. Execute compares the same fingerprint before daemon startup. A frozen closure retains its ancestor-free fingerprint, so the grown study can be frozen independently before checking its continuation. The `StudyContinuation` record holds the admitted replay selection and immediate ancestor.
244
250
 
245
251
  Selection executes one segment of the declared population, and check and execute accept the same three selectors. `--trial <name>` keeps the one scheduled trial of that id. `--goals <first>..<last>` projects every scenario a selected trial names to the goals from first to last inclusive, by goal id. `--seed <result>:<trial>:<goal>` opens the selected trial from the `checkpoint` evidence row that a sealed result retained for that source trial and goal; the value splits at its last two colons, so the result can hold a drive letter, and a relative result must stay inside the consumer working directory. The manifest's scenarios and schedule hold the projection, and its `selection` record names the trial, the range, and the seed's source result, seal, trial, goal, and row digest beside the unchanged full-scenario fixture digest. Execute reads the seed through the source's custody checks and hands the row value to the driver's `open` method. A missing, unsealed, or changed source, a source trial outside its schedule, and a goal without exactly one row refuse with the `CUSTODY` code; `--seed` without `--trial` on a schedule of more than one trial, a trial outside the schedule, and a range that names an undeclared goal or ends before it starts refuse with the `CONFIG` code. Every selection refusal precedes any request and any result directory. Check binds the selection into the execution fingerprint and carries the selectors into its next argv, with the seed's result as a resolved directory, while a frozen closure keeps its selection-free fingerprint. The launcher forwards the selectors to both check and execute. Under a goal range, grade projects the rubric to the manifest's goals and retains the projection under its own digest; report names the selection, lists the dropped criterion ids under `unselected`, and covers only the arms and repetitions that hold a scheduled trial. A selector beside `--extend` refuses with the `CONFIG` code, and `--replay` requires the selection its source recorded.
@@ -294,7 +300,7 @@ isStudyExchangeAncestor(reference)
294
300
 
295
301
  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.
296
302
 
297
- 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.
303
+ 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, judge, and triage pins. Shared pins require 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.
298
304
 
299
305
  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.
300
306
 
@@ -308,7 +314,7 @@ The `matchesSystemError` predicate matches a system code only on an `Error` from
308
314
 
309
315
  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.
310
316
 
311
- 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.
317
+ 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 each judge or triage model together with its matching digest or omits both; declaring only one refuses the profile. A declared recap and a declared judge keep their finite bounds.
312
318
 
313
319
  A profile may carry an optional settings object of JSON values. The selected driver owns its interpretation; Study only validates the object, keeps an independent frozen copy, and refuses arrays, primitives, non-JSON values, and cycles. Settings are part of the resolved profile bytes, so changing one value changes the profile identity and the execution fingerprint. A profile without settings keeps the identity it had before the field existed.
314
320
 
@@ -510,8 +516,8 @@ The following declarations describe this concept.
510
516
  | `StudyOllamaModel` | interface | `{ name, digest }` | Pins one served model identity the inventory verifies. |
511
517
  | `StudyOllamaOptions` | type | `Pick<OllamaOptions, 'model' \| 'think' \| 'options' \| 'truncate' \| 'shift'>` | Holds the Ollama provider options one role's declared policy determines. |
512
518
  | `StudyOllamaPolicy` | interface | `{ model, options, think, strict, length }` | Declares one model role's exact wire policy. |
513
- | `StudyOllamaRequest` | interface | `{ role, path, model, output, bytes, options, strict, length }` | Holds validated wire dispatch facts without retaining payload text. |
514
- | `StudyOllamaRole` | type | `Extract<StudyRole, 'agent' \| 'summary' \| 'judge'>` | Names the model roles an Ollama study transport dispatches under a declared policy. |
519
+ | `StudyOllamaRequest` | interface | `{ tokens?, role, path, model, output, bytes, options, strict, length }` | Holds validated wire dispatch facts without retaining payload text. |
520
+ | `StudyOllamaRole` | type | `Extract<StudyRole, 'agent' \| 'summary' \| 'judge' \| 'triage'>` | Names the model roles an Ollama study transport dispatches under a declared policy. |
515
521
  | `StudyOllamaSnapshot` | interface | `{ url, init, dispatch }` | Holds one outbound request's facts as owned at admission. |
516
522
  | `StudyOllamaTerminal` | interface | `{ prompt, completion, reason }` | Holds a validated terminal's finish reason and actual usage, unknown when unreported. |
517
523
  | `StudyOllamaTransport` | class | `new (options: StudyOllamaTransportOptions) => StudyLatchInterface` | Admits and accounts Ollama wire requests under declared policies and latches failure. |
@@ -537,7 +543,7 @@ The following declarations describe this concept.
537
543
  | `StudyProgressTarget` | interface | `{ trial, goal, evidence }` | Holds one listed goal of a scheduled trial with exactly that goal's complete evidence rows. |
538
544
  | `StudyProgressTrial` | interface | `{ trial, horizon, ended, failure, goals }` | Holds the listed goals of one scheduled trial and whether its terminal record exists. |
539
545
  | `StudyProgressUsage` | interface | `{ role, calls, replayed, prompt, cached, completion, total, length }` | Holds one role's request readings over the `wire` evidence rows of one goal. |
540
- | `StudyProvider` | interface | `{ entry, url, model, judge, digest, daemon? }` | Holds caller-selected provider artifacts and model identities. |
546
+ | `StudyProvider` | interface | `{ entry, url, model, judge, triage?, digest, daemon? }` | Holds caller-selected provider artifacts and model identities. |
541
547
  | `StudyPurpose` | type | `'mechanism' \| 'quality' \| 'capacity'` | Names the evidence a study can establish. |
542
548
  | `StudyRange` | interface | `{ first, last }` | Holds an inclusive goal range named by its first and last goal ids. |
543
549
  | `StudyReference` | interface | `{ file, row? }` | Cites a retained trial file, or one evidence row of it by its zero-based position. |
@@ -555,7 +561,7 @@ The following declarations describe this concept.
555
561
  | `StudyResultStore` | class | `new (options: StudyResultStoreOptions) => StudyResultStoreInterface` | Owns append-only execution bytes and seals only a complete terminal population. |
556
562
  | `StudyResultStoreInterface` | interface | `{ create(), seal(), exchanges() }` | Owns execution custody from exclusive creation through complete sealing. |
557
563
  | `StudyResultStoreOptions` | interface | `{ directory, manifest }` | Holds the inert execution store configuration. |
558
- | `StudyRole` | type | `'agent' \| 'judge' \| 'summary' \| 'metadata' \| 'maintenance' \| 'tool'` | Names a request's measured responsibility. |
564
+ | `StudyRole` | type | `'agent' \| 'judge' \| 'triage' \| 'summary' \| 'metadata' \| 'maintenance' \| 'tool'` | Names a request's measured responsibility. |
559
565
  | `StudyRoom` | interface | `{ context, output, safety, recap, think }` | Holds the model context and generation allowance as separate measurements. |
560
566
  | `StudyRubric` | interface | `{ version, criteria }` | Holds a versioned grading declaration independently of execution. |
561
567
  | `StudyScenario` | interface | `{ id, goals }` | Holds ordered goals sharing state within an isolated trial. |
@@ -860,7 +866,7 @@ The following declarations describe this concept.
860
866
  | `StudyLabelSource` | interface | `{ trial, criterion }` | Names the source pair a neutral row stands for. |
861
867
  | `StudyOllamaKeyedReplay` | class | `new (options: StudyOllamaKeyedReplayOptions) => StudyOllamaReplayInterface` | Serves a listed role's request from the recorded exchange its role, path, method, and body bytes equal. |
862
868
  | `StudyOllamaKeyedReplayOptions` | interface | `{ histories, roles, url, signal, fetch? }` | Configures a keyed replay over verified histories. |
863
- | `StudyOllamaKeyedRole` | type | `Extract<StudyRole, 'agent' \| 'judge' \| 'summary' \| 'metadata'>` | Names the roles a keyed replay can serve. |
869
+ | `StudyOllamaKeyedRole` | type | `Extract<StudyRole, 'agent' \| 'judge' \| 'triage' \| 'summary' \| 'metadata'>` | Names the roles a keyed replay can serve. |
864
870
  | `StudyOllamaKeyedSelection` | interface | `{ result, roles, offline }` | Selects a sealed recording and the roles a keyed replay serves from it. |
865
871
  | `advanceStudyExchangeProgress` | function | `(progress: StudyExchangeProgress, row: StudyExchangeRow) => StudyExchangeProgress` | Validates the next row against the journal before it and derives the journal after it. |
866
872
  | `buildStudyExchangeProgress` | function | `(declaration: StudyExchangeDeclaration) => StudyExchangeProgress` | Builds the progress of a journal that holds only its declaration. |
@@ -911,6 +917,8 @@ The following declarations describe this concept.
911
917
  | `publishStudyBytes` | function | `(path: string, bytes: Uint8Array, part: string) => Promise<void>` | Publishes a record by writing it beside its path and renaming it there, so a reader of the path sees no partial bytes. |
912
918
  | `scanStudyJSONFaults` | function | `(value: unknown, path?: string) => readonly string[]` | Lists the members of a value that are not plain JSON data, by path, without reading an accessor. |
913
919
  | `studyVerdictShape` | const | `import("@orkestrel/contract").LiteralShape<readonly ["achieved", "unsuccessful", "unknown"]>` | Describes a verdict a judgment holds. |
920
+ | `StudySystemOnePolicy` | interface | `{ model, tokens }` | Declares the pinned System One model and the total token reservation for each request. |
921
+ | `isStudySystemOnePolicy` | function | `(value: unknown) => value is StudySystemOnePolicy` | Checks whether a value declares a pinned System One model and total token ceiling. |
914
922
 
915
923
  ## Methods
916
924
 
@@ -2261,6 +2269,7 @@ import {
2261
2269
  isStudyOllamaMetadata,
2262
2270
  isStudyOllamaModel,
2263
2271
  isStudyOllamaPolicy,
2272
+ isStudySystemOnePolicy,
2264
2273
  isStudyOllamaStep,
2265
2274
  validateStudyOllamaCapture,
2266
2275
  validateStudyOllamaStep,
@@ -2273,8 +2282,9 @@ validateStudyOllamaCapture(configured)
2273
2282
  isStudyOllamaMetadata(configured.metadata)
2274
2283
  isStudyOllamaModel(configured.models.model)
2275
2284
  isStudyOllamaPolicy(configured.roles.agent)
2276
- isStudyOllamaStep(configured.procedure?.[0])
2277
- validateStudyOllamaStep(configured.procedure?.[0], 'write', request, body)
2285
+ isStudySystemOnePolicy(configured.roles.triage)
2286
+ isStudyOllamaStep(configured.exchanges?.declaration?.procedure?.[0])
2287
+ validateStudyOllamaStep(configured.exchanges?.declaration?.procedure?.[0], 'write', request, body)
2278
2288
  buildStudyOllamaBytes(new TextEncoder().encode(body))
2279
2289
  ```
2280
2290
 
@@ -368,7 +368,7 @@ Before shape branching or property reads, the handler snapshots untrusted `args`
368
368
 
369
369
  22. **`createDatabaseTool` durability and ownership are narrower than they look.** A lazily re-minted database over the default in-memory driver yields an empty database — only the `DatabaseDefinition` schema persists in `store`, never rows; durable rows need a persistent driver factory registered in `DatabaseToolOptions.drivers`. A cached live database is never evolved in place. To adopt a new target `version`, create a new database id backed by a versioned persistent driver, or close the old tool lifecycle and construct a new tool whose stored definition carries the new schema metadata and stamp. `'destroy'` closes whatever handle is cached for the id, including an embedder-supplied `DatabaseToolOptions.databases` handle — the embedder relinquishes that handle's lifecycle to this tool for any id it wires in. `timeout`, when present, must be a nonnegative safe integer and is validated when the tool is constructed. Its fresh abort signal is passed only to `records`, `count`, `aggregate`, `add`, `set`, `update`, and `remove`, whose current table APIs accept operation options; it does not bound store resolution, construction, schema inspection, `get`, or `close`, and is not an outer deadline. The tool assumes the single-writer, non-reentrant model `@orkestrel/database` itself assumes — concurrent tool calls against one id are not serialized by this tool. Unlike `'records'` / `'find'` / `'links'`, `'get'` is uncapped by `DatabaseToolOptions.limit` (bounded only by the caller's `key` array size).
370
370
 
371
- 23. **`createEndpointTool` enforces its advertised inferred schema through the Tool door by default (`@orkestrel/contract`'s lenient `schemaToShape`), with an explicit `strict: false` opt-out.** `parameters` is inferred once at construction (`samplesToSchema` and `schemaToObject` over `definition.samples`, tuned by `EndpointToolOptions.format`/`enum`) — the door converts the same object-rooted schema on the first call and runs on every call's `args` before `definition.execute`. The parse coerces a scalar to its inferred type where the house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/`'false'`/`1`/`0`) — `definition.execute` receives the coerced values (for example `7` sent for a string slot arrives as `'7'`), not the raw call args. A call that carries a key the closed inferred schema does not declare, misses a required key, or holds a value not coercible to its slot's type throws a `ToolError` with code `ARGUMENTS` carrying `context.faults`, and `definition.execute` is never called. Beyond that coercion, enforcement is structural: required keys, `enum` membership, and numeric bounds — `format` annotations (`email`, `date-time`, `uuid`, `uri`, ...) are never asserted, mirroring `@orkestrel/contract`'s own widening-only law for `schemaToShape` (a `format: true`-tuned endpoint still accepts a non-conforming string in that slot). `EndpointToolOptions.strict: false` disables that enforcement: the tool's `execute` calls `definition.execute` with the model-supplied `args` exactly as received, never parsed, coerced, or checked against the advertised schema. Under the door `args` is a null-prototype record, on which `String(args)` and `args.hasOwnProperty()` throw, so a handler reads it with `Object.hasOwn`. The execution context the tool's `execute` receives reaches `definition.execute` unchanged whether or not that enforcement runs, so a handler that reads `context.signal` observes the caller's cancellation. `createInferTool`'s own call args are, as before, always validated against `inferToolShape` (a hand-written shape) regardless — it is the schema inference's caller, not an inferred schema's consumer. `createEndpointTool`'s and `createInferTool`'s inferred schemas surface sample-derived strings verbatim (property names, and enum entries when opted in), so treat sample data intended for schema inference as untrusted content whenever the resulting schema will be advertised to other agents. `createInferTool`'s optional `candidates` call arg is the opposite seam: it checks values against the same call's freshly inferred schema (compiled per-call, because the schema itself is derived from that call's `samples`) and returns a uniform `{ index, valid, coercible, faults? }` entry per candidate. `valid` is a strict `.is` guard verdict, not a normalizing `.parse` — `7` against an inferred string slot is invalid (no coercion), where the same value would be silently coerced to `'7'` by `createEndpointTool`'s enforcement. `coercible` (`checker.parse(candidate) !== undefined`) answers that separate question directly — would `createEndpointTool`'s default enforcement admit this value — and, by the house parse/guard round-trip, is always `true` on a `valid: true` entry. `faults` is `checker.audit(candidate)`, which reports against `.is`'s strictness, so a strictly-invalid but coercible candidate (`7` against a string slot) yields `{ valid: false, coercible: true, faults: [{ reason: 'type', ... }] }` and an undeclared key is a named `extra` fault: every invalid candidate names why. `checker.is` / `.parse` / `.audit` are total over JSON-safe input — a JSON-safe hostile candidate (a `__proto__`-carrying object, deep nesting) reaches each of them and yields a bounded, non-throwing per-candidate verdict; a non-JSON-safe candidate (a throwing-getter `Proxy`) never reaches the checker — the Tool door refuses the whole call with a `ToolError`, with no per-candidate verdict. `candidates` is uncapped in count (any array length is accepted), but each individual check is bounded (`.audit`'s fault list and the checker's own schema are both bounded by the inference limits already governing `samples`), so the total per-call cost is linear in `candidates.length`.
371
+ 23. **`createEndpointTool` enforces its advertised inferred schema through the Tool door by default (`@orkestrel/contract`'s lenient `schemaToShape`), with an explicit `strict: false` opt-out.** `parameters` is inferred once at construction (`samplesToSchema` and `schemaToObject` over `definition.samples`, tuned by `EndpointToolOptions.format`/`enum`) — the door converts the same object-rooted schema on the first call and runs on every call's `args` before `definition.execute`. Admission permits only lossless repairs: a numeric string whose trimmed text equals the parsed number's own text, the exact strings `'true'` and `'false'` for a boolean, a literal's trimmed text, and a finite number for a string slot. For example, `' 30 '` can become `30` and `7` can become `'7'`, but `'30.0'`, `'007'`, and `'0x10'` cannot become numbers, and `'1'`, `'0'`, `1`, and `0` cannot become booleans. The `definition.execute` handler receives the admitted value without another parse. A call that carries a key the closed inferred schema does not declare, misses a required key, or needs a repair that loses information or cannot parse throws a `ToolError` with code `ARGUMENTS` carrying `context.faults`, and `definition.execute` is never called. Beyond those repairs, enforcement is structural: required keys, `enum` membership, and numeric bounds — `format` annotations (`email`, `date-time`, `uuid`, `uri`, ...) are never asserted, mirroring `@orkestrel/contract`'s own widening-only law for `schemaToShape` (a `format: true`-tuned endpoint still accepts a non-conforming string in that slot). `EndpointToolOptions.strict: false` disables that enforcement: the tool's `execute` calls `definition.execute` with the model-supplied `args` exactly as received, never parsed, coerced, or checked against the advertised schema. Under the door `args` is a null-prototype record, on which `String(args)` and `args.hasOwnProperty()` throw, so a handler reads it with `Object.hasOwn`. The execution context the tool's `execute` receives reaches `definition.execute` unchanged whether or not that enforcement runs, so a handler that reads `context.signal` observes the caller's cancellation. `createInferTool`'s own call args are, as before, always validated against `inferToolShape` (a hand-written shape) regardless — it is the schema inference's caller, not an inferred schema's consumer. `createEndpointTool`'s and `createInferTool`'s inferred schemas surface sample-derived strings verbatim (property names, and enum entries when opted in), so treat sample data intended for schema inference as untrusted content whenever the resulting schema will be advertised to other agents. `createInferTool`'s optional `candidates` call arg is the opposite seam: it checks values against the same call's freshly inferred schema (compiled per-call, because the schema itself is derived from that call's `samples`) and returns a uniform `{ index, valid, coercible, faults? }` entry per candidate. `valid` is a strict `.is` guard verdict, not a normalizing `.parse` — `7` against an inferred string slot is invalid (no coercion), where the same value would be silently coerced to `'7'` by `createEndpointTool`'s enforcement. `coercible` (`checker.parse(candidate) !== undefined`) reports parser success, not endpoint admission, and is always `true` on a `valid: true` entry. A candidate can parse while requiring a lossy repair that the endpoint refuses. `faults` is `checker.audit(candidate)`, which reports against `.is`'s strictness, so a strictly-invalid but coercible candidate (`7` against a string slot) yields `{ valid: false, coercible: true, faults: [{ reason: 'type', ... }] }` and an undeclared key is a named `extra` fault: every invalid candidate names why. `checker.is` / `.parse` / `.audit` are total over JSON-safe input — a JSON-safe malformed candidate (a `__proto__`-carrying object, deep nesting) reaches each of them and yields a bounded, non-throwing per-candidate verdict; a non-JSON-safe candidate (a throwing-getter `Proxy`) never reaches the checker — the Tool door refuses the whole call with a `ToolError`, with no per-candidate verdict. `candidates` is uncapped in count (any array length is accepted), but each individual check is bounded (`.audit`'s fault list and the checker's own schema are both bounded by the inference limits already governing `samples`), so the total per-call cost is linear in `candidates.length`.
372
372
 
373
373
  24. **The terminal seam speaks whole forms, and `@orkestrel/form` owns their shape.** `promptToolShape` bounds a call to `{ to, schema }` and `answerToolShape`'s `'answer'` arm to `{ id, values }`, each of `schema` and `values` admitted only as exact JSON — Toolbox does not restate the form schema as a second contract. `createPromptTool` then hands `schema` to `parseForm`; a refusal (an unknown control, a duplicate field name, a `'select'` / `'checkbox'` field without usable choices, any other schema fault) throws a typed `TOOL` `ToolboxError` and nothing parks, so a malformed schema can never become a form nobody can answer. A parsed schema becomes a live form through `createForm` and is passed to `manager.ask(from, to, form)`, whose settled `FormValues` is the tool's return value — one record keyed by field name, however many fields the form declared. `createAnswerTool` narrows `values` with `isFormValues` before `manager.answer`, so a non-form payload is refused as `TOOL` rather than reaching the parked form. Expiry reaches one code from either side: a `TerminalError('EXPIRE')` from the broker and a `FormError('ABANDONED')` from the form itself both re-surface as `EXPIRE`, so a caller branches on Toolbox's own code and never on which layer timed the form out. A failed apply carries the manager's `TerminalAnswerError` through: `context.reason` is `'unknown'` / `'rejected'` / `'target'`, and a `'rejected'` apply also carries the per-field `errors` in `context.errors` so the asking side can name which field failed.
374
374
 
@@ -847,12 +847,19 @@ restored?.id // 'audit'
847
847
 
848
848
  Register a live relation manager and load a row with a nested dot-path `include` list:
849
849
 
850
+ The tool opens no transaction. `unlink` removes every matching junction row through the manager's
851
+ bound storage, one row at a time. Outside a transaction, a failed removal leaves earlier removals
852
+ committed and the pair linked; `links` still lists the target. Repeat `unlink` to complete removal.
853
+ For all-or-nothing removal, build the manager with `createRelationManager({ storage, relations })`
854
+ inside the host's `database.transaction(async (storage) => ...)` callback and use its tool only
855
+ within that scope. Let the failure propagate out of the callback so the transaction rolls back.
856
+
850
857
  ```ts
851
858
  import { createRelationTool } from '@orkestrel/toolbox'
852
859
  import { createToolManager } from '@orkestrel/tool'
853
860
  import type { RelationManagerInterface } from '@orkestrel/relation'
854
861
 
855
- declare const manager: RelationManagerInterface // built with createRelationManager({ database, relations: { ... } })
862
+ declare const manager: RelationManagerInterface // built with createRelationManager({ storage: database, relations: { ... } })
856
863
 
857
864
  const tool = createRelationTool({ managers: { shop: manager } }) // omit "manager" in a call when only one is registered
858
865