@arnilo/prism 0.0.5 → 0.0.7

package/docs/use-case-model-selection.md

@@ -0,0 +1,109 @@
+# Use-case model selection
+
+## What it does
+
+Prism separates the **session chat model** (`AgentConfig.model` / `RunOptions.model`) from **use-case models** used by background or adjacent LLM jobs (observational memory workers, LLM compaction summarizers, declarative agents, supervisor children, evals). Hosts bind `{ model?, provider?, providerOptions?, thinkingLevel? }` per use case. When the use-case omits `model`, resolution falls back to the active session model. Workers never write `model_change` session entries for their own jobs.
+
+## When to use it
+
+- Observational memory should run a cheaper/faster model than the chat session (or inherit the session model when unset).
+- LLM compaction should summarize with an explicit `summaryModel`, falling back to a host-supplied session `model`.
+- Declarative agents, supervisor children, evals, and RPC/CLI runs already own their models — document them as use-case sites that stay separate from a parent session.
+- Memory/RAG `Embedder` selection is related but **not** a chat `ModelConfig` binding.
+
+## Contract
+
+| Layer | Surface |
+| --- | --- |
+| Binding | `UseCaseModelBinding`: `{ model?, provider?, providerOptions?, thinkingLevel?, requireExplicitModel? }` |
+| Resolver | `resolveUseCaseModel({ configured, sessionModel, requireExplicitModel?, … })` → `{ model, source }` or `undefined` |
+| Binding helper | `resolveUseCaseModelBinding(binding, sessionModel)` |
+| Credential id | `useCaseCredentialProviderId(resolved, binding?)` — always the **resolved** `model.provider` |
+| Escape hatch | `requireExplicitModel: true` skips session fallback (OM historical `missing_model`) |
+
+```ts
+import { resolveUseCaseModel, applyThinkingLevel, thinkingFamilyForModel } from "@arnilo/prism";
+
+// Prefer an explicit worker; otherwise inherit the session/agent model.
+const resolved = resolveUseCaseModel({
+  configured: settings.workerModel,       // optional use-case ModelConfig
+  sessionModel: agent.config.model,       // host-supplied; AgentSession does not expose agent
+  thinkingLevel: settings.thinkingLevel,
+});
+if (!resolved) {
+  // skip — neither configured nor session model (or requireExplicitModel)
+}
+
+const family = thinkingFamilyForModel(resolved.model);
+const providerOptions = resolved.thinkingLevel
+  ? applyThinkingLevel(resolved.providerOptions, resolved.thinkingLevel, family === "noop" ? "reasoning_effort" : family)
+  : resolved.providerOptions;
+```
+
+### Precedence
+
+1. `configured` / `binding.model` → `source: "configured"`
+2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+3. Else `undefined` (package skips or throws)
+
+Resolution is O(1) and network-free. It does not mutate session history.
+
+## Binding sites
+
+| Site | How hosts bind | Session fallback |
+| --- | --- | --- |
+| Observational memory | `workerModel` / settings `workerModel` + runtime `sessionModel` | Yes — pass `sessionModel: agent.config.model`; `requireExplicitModel` restores skip |
+| LLM compaction | `summaryModel` with `model` as fallback slot | Yes — `resolveUseCaseModel({ configured: summaryModel, sessionModel: model })` |
+| `RunOptions.model` | Per-run override on the **session** | N/A — this *is* the session/run model (writes `model_change`) |
+| Declarative `AgentDefinition` | Definition `model` / registry resolve | Definition-scoped (independent agent) |
+| Supervisor children | Child `createSession` / child `AgentConfig.model` | Independent child session |
+| Evals / workflows / RPC / CLI | Caller `runOptions.model` | Caller-owned |
+| Structured output | Reuses session/run model | Same as run |
+| Memory / RAG | Host `Embedder` | Not a chat model — see [Working and semantic memory](working-and-semantic-memory.md) |
+
+## Observational memory
+
+```ts
+createObservationalMemoryRuntime({
+  session,
+  appendEntry: (entry) => store.append(entry),
+  workerProvider,
+  sessionModel: agent.config.model, // enables fallback when workerModel unset
+  // workerModel: { provider: "neuralwatt", model: "glm-5.2-fast" }, // optional override
+  overrides: { thinkingLevel: "low", observeAfterTokens: 1 },
+});
+```
+
+- Default: no `workerModel` + `sessionModel` set → workers use the session model.
+- Explicit `workerModel` (or settings `workerModel`) always wins.
+- `requireExplicitModel: true` (runtime or settings) → `skipped: "missing_model"` when no worker model, even if `sessionModel` is set.
+- Neither worker nor session model → `skipped: "missing_model"`.
+- Default credential request uses the **resolved** model's `provider` id.
+
+## LLM compaction
+
+```ts
+createLlmCompactionStrategy({
+  provider: summaryProvider,
+  summaryModel: { provider: "example", model: "cheap-summary" }, // optional
+  model: agent.config.model, // session fallback when summaryModel omitted
+  thinkingLevel: "low",
+});
+```
+
+`summaryModel` wins; otherwise `model` is required. Thinking maps into `compat` via `applyThinkingLevel` ([Thinking and reasoning](thinking-and-reasoning.md)).
+
+## Security
+
+- Credential requests for worker calls must target the **resolved** model’s provider — not ambient session credentials for a different provider unless the host wires that explicitly.
+- Pass known secrets into worker/compaction options so prompts, ledger custom entries, and errors stay redacted.
+- Background workers must not append `model_change` entries or otherwise rewrite the chat session’s model timeline.
+
+## Related pages
+
+- [Thinking and reasoning](thinking-and-reasoning.md) — per-turn `thinkingLevel` → `compat`
+- [Observational memory compaction package](compaction-observational-memory.md)
+- [LLM compaction package](compaction-llm.md)
+- [Agent/session runtime](agent-session-runtime.md) — `RunOptions.model` / `model_change`
+- [Working and semantic memory](working-and-semantic-memory.md) — `Embedder` (non-chat)
+- Evidence matrix: [Review coverage (2026-07-17 provider validation)](review-coverage-2026-07-17-provider-validation.md)

package/docs/workflow-orchestration-primitives.md

@@ -387,6 +387,7 @@ const review = functionNode({ execute: async (ctx) => lint(ctx.upstream.draft) }
 
 const workflow = defineWorkflow({
   id: "research-draft-review",
+  revision: "2026-07-19.1",
   nodes: { research, draft, review },
   edges: [
     ["research", "draft"],

package/docs/workflows.md

@@ -29,29 +29,32 @@ Use `createWorkflowCoordinator()` when multiple processes share SQLite/PostgreSQ
 
 ## Inputs / request
 
-`defineWorkflow({ id, nodes, edges, limits? })`:
+`defineWorkflow({ id, revision, nodes, edges, limits? })`:
 
 | Field | Notes |
 | --- | --- |
 | `id` | Stable workflow id (required) |
+| `revision` | Non-empty host-authored definition revision (required); parent and nested revisions enter `definitionHash` |
 | `nodes` | Record of node definitions (`kind` + typed fields) |
 | `edges` | `[from, to]` pairs; must be acyclic; unknown ids rejected |
-| `limits.maxNodes` | Default 1000 |
-| `limits.maxFanOut` | Default 64 |
-| `limits.maxConcurrency` | Default 8 |
-| `limits.maxNodeOutputBytes` | Default 4 MiB |
-| `limits.maxCheckpointBytes` | Default 1 MiB |
+| `limits.maxNodes` | Default 1,000 / hard cap 10,000 |
+| `limits.maxFanOut` | Default 64 / hard cap 1,024 |
+| `limits.maxConcurrency` | Default 8 / hard cap 256 |
+| `limits.maxNodeOutputBytes` | Default 4 MiB / hard cap 16 MiB |
+| `limits.maxCheckpointBytes` | Default 1 MiB / hard cap 8 MiB |
 | `limits.maxNestedDepth` / hard cap | 8 / 32; inherited by child workflows |
 | `limits.maxStateBytes` / hard cap | 64 KiB / 512 KiB |
 | `limits.maxStateHistory` / hard cap | 32 / 128 state snapshots; updates stop before evidence would be discarded |
 | `limits.maxReplayDepth` / hard cap | 8 / 32 lineage generations |
 | `state.initial` / `state.schema` | Initial shared JSON object and optional host-validated schema |
 
+All workflow limits and runtime `concurrency` reject non-safe integers, zero, negatives, NaN, `Infinity`, and values above the named hard cap. Node retries allow 0–100; an explicit node timeout allows 1–86,400,000 ms. Omitting `timeoutMs` remains an explicit host choice.
+
 `runWorkflow(workflow, input, options?)`:
 
 | Option | Notes |
 | --- | --- |
-| `concurrency` | Worker pool size (capped by workflow/global limits) |
+| `concurrency` | Worker pool size; positive safe integer, hard cap 256, and capped by the workflow limit |
 | `checkpoints` | `WorkflowCheckpointAdapter` for save/load/list |
 | `agentFactory` | `(agentName) => AgentSession` for agent nodes |
 | `tools` | Tool registry/lookup for tool nodes |
@@ -100,6 +103,7 @@ Package-local `WorkflowEvent` types: `workflow_started`, `workflow_suspended`, `
 ```json
 {
   "id": "research-draft",
+  "revision": "2026-07-19.1",
   "nodes": ["research", "draft"],
   "edges": [["research", "draft"]],
   "limits": { "maxNodes": 256, "maxFanOut": 32, "maxConcurrency": 4 }
@@ -159,6 +163,7 @@ const publish = functionNode({
 
 const workflow = defineWorkflow({
   id: "research-draft",
+  revision: "2026-07-19.1",
   nodes: { research, draft, publish },
   edges: [["research", "draft"], ["draft", "publish"]],
   limits: { maxNodes: 256, maxFanOut: 32, maxConcurrency: 4 },
@@ -209,6 +214,7 @@ if (result.status === "suspended") {
 await cancelWorkflowRun({
   workflowId: workflow.id,
   runId: result.runId,
+  workflow,
   checkpoints,
   ownership: { tenantId: "t1" },
 });
@@ -258,15 +264,16 @@ runRpcServer({
 
 ## Security and performance notes
 
-- Definitions fail closed on cycles, unknown edges, self-edges, and `maxNodes` overflow.
-- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`.
+- Definitions require a non-empty host-authored `revision` and fail closed on cycles, unknown edges, self-edges, invalid limits, and `maxNodes` overflow. Revision and every nested revision enter the deterministic definition hash; hosts must bump revision when function/tool behavior changes.
+- Fan-out length is bounded by `maxFanOut`; concurrency by `maxConcurrency`; every count/byte/runtime option has a finite hard cap.
 - Node outputs, shared state/history, schedule input/records, and checkpoints are byte/count/depth bounded. Checkpoint size remains the final aggregate ceiling.
 - Event buses use a bounded buffer (default 2048) with `close` / `drop_oldest` / `drop_newest` overflow.
 - Checkpoints redact suspension/resume payloads via `SecretRedactor` / `secrets` before save; resume rejects tenant, schema, definition-hash, and expected-version mismatch.
 - Suspension requires a checkpoint adapter, consumes no worker/polling slot, and is ignored by distributed coordinators until explicit resume.
 - Concurrent resumes race on checkpoint CAS before node execution; one wins and stale/duplicate reviewers fail closed. Approved tool nodes then re-run current `ExecutionPolicy`, so durable approval cannot grant stale permissions.
 - `toolNode({ approval: { reason, data?, resumeSchema? } })` suspends before tool execution. Denial is terminal `denied`; no tool side effect occurs.
-- `cancelWorkflowRun` aborts local runs immediately and writes a durable cancellation request for a remotely leased run; workers check it during lease renewal.
+- `cancelWorkflowRun` requires the current workflow definition and exact tenant/account/user ownership. It verifies recursive definition hash before abort/mutation, then aborts local runs or writes a durable cancellation request for remotely leased work. Tenant-only or missing ownership cannot cancel a more-specific owned run.
+- Active registry identity includes workflow ID, run ID, and exact ownership. Exact duplicates fail instead of overwriting; distinct owners remain isolated in lookup/list/cancel/unregister.
 - Tool nodes attach `workflowId` / `nodeId` on `ExecutionAction.metadata` for approval/audit context.
 - Nested workflows inherit host registries/policies and cannot inject broader tools, agents, ownership, or credentials. Nested depth is inherited; child suspension bubbles to the parent review cursor.
 - Replay source ownership/hash/status/node eligibility are checked before a new checkpoint is created. Source records are immutable, lineage is bounded, and copied approval-bearing paths are rejected.
@@ -281,6 +288,7 @@ Use workflows for known, durable, replayable graphs. Use optional supervisor del
 - Examples: `examples/workflow-research-and-review.ts`, `examples/workflow-parallel-research.ts`, `examples/workflow-tool-approval.ts`, `examples/workflow-multimodal-document.ts`, `examples/workflow-sqlite-resume.ts`, `examples/workflow-postgres-resume.ts`, `examples/workflow-event-sink.ts`, `examples/workflow-rpc-cancel.ts`, `examples/workflow-distributed-coordinator.ts` — offline runnable demos; PostgreSQL safely skips unless `PRISM_TEST_POSTGRES_URL` is set.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): Task 0–1 inventory and locked adapter contracts
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.run()`/`stream()`, abort, subscribe
+- [Guardrails](guardrails.md): `RunWorkflowOptions.guardrails` routes tool nodes through core dispatch before policy and side effects.
 - [Supervisor delegation](supervisors.md): bounded dynamic child selection.
 - [Agent events](agent-events.md): core `AgentEvent` wrapped by `agent_event`
 - [Session stores and branching](session-stores-and-branching.md): session `leafId` reuse on resume

package/docs/working-and-semantic-memory.md

@@ -152,6 +152,7 @@ await runMemoryConformance(() => ({
 - Configure `secrets` / `redactor` so memory text and metadata cannot persist or inject raw canaries.
 - Injected context is inert text — it cannot grant tools or permissions.
 - Hard caps: top-K ≤ 32, messageRange ≤ 4, embed batch ≤ 128, injected tokens ≤ 8000, payload/working-memory byte limits enforced.
+- Every embedding is a non-empty finite number vector. `embedBatched()`, in-memory `VectorStore` upserts/queries, and PostgreSQL/pgvector parameters reject NaN, ±Infinity, non-numbers, and wrong configured dimensions before similarity scoring or SQL. Custom adapters can call `assertFiniteVector(vector, label, expectedLength?)` at their trust boundary.
 - Default `remember()` does not block agent completion; pass `{ wait: true }` when indexing must finish first.
 - PostgreSQL live suite is gated by `PRISM_TEST_POSTGRES_URL` and requires the `vector` extension.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -92,7 +92,7 @@
     }
   },
   "bin": {
-    "prism": "./dist/cli.js"
+    "prism": "dist/cli.js"
   },
   "files": [
     "dist",