@warlock.js/ai 4.1.1

package/skills/embed-text/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: embed-text
+description: 'Text-to-vector via sdk.embedder({...}) — embed(string) for single, embedMany(string[]) for batch. Peer primitive on the SDK adapter, not wired into agents. Compose into RAG tools, workflow run steps, or ai.middleware.semanticCache. Triggers: `sdk.embedder`, `EmbedderContract`, `embedder.embed`, `embedder.embedMany`, `EmbeddingResult`, `EmbeddingBatchResult`, `dimensions`; ''embed text'', ''build RAG tool'', ''populate vector store'', ''embedding batch''; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: cache similarity — `@warlock.js/cache/use-cache-similarity/SKILL.md`; pgvector queries — `@warlock.js/cascade/search-by-vector/SKILL.md`; competing libs `langchain` embeddings, raw `openai.embeddings.create`.'
+---
+
+# Embeddings — peer primitive on the SDK adapter
+
+`EmbedderContract` is a sibling of `ModelContract` on `SDKAdapterContract`, not part of the agent loop. Text-in / vector-out. No streaming, no tools, no relationship to chat completions.
+
+## Contract
+
+```ts
+interface EmbedderContract {
+  readonly name: string;
+  readonly provider: string;
+  readonly dimensions: number;       // 0 until first call when no override given
+
+  embed(input: string): Promise<EmbeddingResult>;
+  embedMany(inputs: string[]): Promise<EmbeddingBatchResult>;
+}
+```
+
+Single and batch are deliberately split — different cost profiles, different per-request token caps, different failure modes.
+
+The `embedder()` method is **optional** on `SDKAdapterContract` — not every provider supports embeddings:
+
+```ts
+if (typeof sdk.embedder === "function") {
+  const embedder = sdk.embedder({ name: "text-embedding-3-small" });
+}
+```
+
+## OpenAI adapter — first implementation
+
+```ts
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const embedder = openai.embedder({ name: "text-embedding-3-small" });
+
+const one = await embedder.embed("Hello, world.");
+// { vector: number[], dimensions: number, usage: { promptTokens, totalTokens } }
+
+const many = await embedder.embedMany(["foo", "bar", "baz"]);
+// { vectors: number[][], dimensions: number, usage: { promptTokens, totalTokens } }
+```
+
+## Not wired into the agent loop
+
+Embeddings are deliberately not automatic. Consumers obtain an embedder from the adapter and call it directly. Composes into:
+
+- **Retrieval tools** the agent can call (RAG pattern).
+- **`run` steps** in a workflow (vector ingest, catalog item embedding).
+- **Query vectors** for `ai.middleware.semanticCache` — see [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md).
+- **Cascade vector columns** for native pgvector search — see [`@warlock.js/cascade/search-by-vector/SKILL.md`](@warlock.js/cascade/search-by-vector/SKILL.md).
+- **Cache similarity retrieval** via `cache.set({ vector })` + `cache.similar(...)` — see [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md).
+
+## Usage example — workflow `run` step
+
+```ts
+ai.step({
+  name: "embed",
+  run: async (ctx) => {
+    const text = `${ctx.steps.extract.output.name} ${ctx.steps.extract.output.description}`;
+    const { vector } = await embedder.embed(text);
+    ctx.state.embedding = vector;
+  },
+  output: { extract: (ctx) => ({ dims: (ctx.state.embedding as number[]).length }) },
+});
+```
+
+## Pattern — RAG tool
+
+```ts
+import { v } from "@warlock.js/seal";
+
+const searchKb = ai.tool({
+  name: "searchKb",
+  description: "Search the knowledge base for relevant passages.",
+  input: v.object({ query: v.string(), k: v.number().optional() }),
+  execute: async ({ query, k }) => {
+    const { vector } = await embedder.embed(query);
+    const hits = await vectorStore.query(vector, { topK: k ?? 5 });
+    return hits.map((h) => ({ text: h.text, score: h.score, source: h.source }));
+  },
+});
+
+ai.agent({ model, tools: [searchKb] });
+```
+
+## Dimensions
+
+`embedder.dimensions` is `0` on a fresh embedder when no override is given — populated from the first embed call's response. Pre-seed via the adapter's `dimensions` config option when you need the value before the first call (e.g. to size a vector column in a migration schema).
+
+## Retrieval is app-level
+
+No built-in vector store. Bring your own (pgvector / Qdrant / Pinecone / Chroma / cache's `similar()`) and wrap it in an `ai.tool({...})`.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — composing embedders into tools
+- [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — embeddings inside `run` steps
+- [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) — performance guidance on vector storage
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — cache as a vector store
+- [`@warlock.js/cascade/search-by-vector/SKILL.md`](@warlock.js/cascade/search-by-vector/SKILL.md) — cascade `similarTo` query method

package/skills/handle-ai-errors/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: handle-ai-errors
+description: 'Typed AIError hierarchy with stable code strings + coarse category for retry-policy dispatch. execute() never throws — errors surface via result.error. Triggers: `AIError`, `ProviderRateLimitError`, `ProviderAuthError`, `ContextLengthExceededError`, `ContentFilterError`, `SchemaValidationError`, `ToolExecutionError`, `WorkflowDriftError`, `BudgetExceededError`, `GuardrailViolationError`, `error.code`, `error.category`; ''handle ai error'', ''retry on rate limit'', ''branch on error code'', ''build fallback ladder''; typical import `import { AIError } from "@warlock.js/ai"`. Skip: log surfacing — `@warlock.js/ai/log-ai-calls/SKILL.md`; native `try / catch` on raw `openai`.'
+---
+
+# Typed errors — `AIError` hierarchy
+
+Every error surfaced by `@warlock.js/ai` and every adapter package is an `AIError` subclass with a stable `code`. The base extends platform `Error`; it does NOT extend `HttpError`. Plain `Error` never leaks.
+
+## Two invariants
+
+1. **`execute()` never throws.** Every `agent.execute()` / `workflow.execute()` resolves with a well-formed result. Failures funnel into `result.error`. Same for `stream.result`.
+2. **Every error is an `AIError`.** Both core and adapter packages funnel everything through `AIError` subclasses. Branch on `error.code` (stable string) or `instanceof`.
+
+## Dispatch pattern
+
+```ts
+import {
+  AIError,
+  ProviderRateLimitError,
+  ProviderAuthError,
+  ContextLengthExceededError,
+  ContentFilterError,
+  SchemaValidationError,
+  ToolExecutionError,
+  WorkflowDriftError,
+  // ...
+} from "@warlock.js/ai";
+
+const result = await agent.execute(input);
+
+if (!result.error) return result.data;
+
+if (result.error instanceof ProviderRateLimitError) {
+  await sleep(result.error.retryAfter ?? 1000);
+  return retry();
+}
+
+if (result.error instanceof ContextLengthExceededError) {
+  return truncateAndRetry(result.error);
+}
+
+// Or branch on stable code string (good for persisted logs / metrics)
+switch (result.error.code) {
+  case "PROVIDER_RATE_LIMIT": /* ... */ break;
+  case "CONTENT_FILTER":      /* ... */ break;
+  case "WORKFLOW_DRIFT":      /* ... */ break;
+}
+```
+
+Codes are the public contract — class names may evolve; codes stay.
+
+## Coarse dispatch via `error.category`
+
+Too granular to dashboard on `code` — every `AIError` carries a coarser `category`:
+
+```ts
+type ErrorCategory =
+  | "auth" | "rate-limit" | "timeout" | "validation" | "content-filter"
+  | "provider" | "tool" | "cancelled" | "max-trips" | "max-iterations"
+  | "max-steps" | "schema" | "drift" | "routing" | "guardrail"
+  | "budget" | "quota" | "context-length" | "unknown";
+
+switch (result.error.category) {
+  case "rate-limit":     return retryWithBackoff();
+  case "timeout":        return retryOnce();
+  case "auth":           return escalate();              // not retryable
+  case "content-filter": return policyMessage();          // not retryable
+  case "schema":         return repair();                 // use agent `repair`
+}
+
+metrics.increment("ai.error", { category: result.error.category });
+```
+
+Each typed subclass declares its `static defaultCategory`. The 4th-arg category override exists only on the base `AIError` for direct `new AIError(...)` usage.
+
+## Hierarchy
+
+```
+AIError  (base — code, category, message, cause?, context?)
+├── AgentExecutionError          AGENT_EXEC_FAILED
+│   ├── AgentCancelledError      AGENT_CANCELLED            { cancelledAt?, reason? } — caller pulled the plug
+│   └── AgentMaxTripsError       AGENT_MAX_TRIPS            { maxTrips } — runaway tool loop hit the cap
+├── SchemaValidationError        SCHEMA_VALIDATION_FAILED   { issues? }
+├── ToolExecutionError           TOOL_EXEC_FAILED           { toolName, tripIndex? }
+├── WorkflowError                WORKFLOW_ERROR  (base)
+│   ├── StepFailedError          STEP_FAILED                { stepName, attempts }
+│   ├── WorkflowDriftError       WORKFLOW_DRIFT             { savedSignature, currentSignature, runId }
+│   ├── WorkflowCancelledError   WORKFLOW_CANCELLED         { cancelledAt, reason }
+│   ├── MaxStepsExceededError    WORKFLOW_MAX_STEPS         { maxSteps }
+│   └── RoutingError             WORKFLOW_INVALID_GOTO      { stepName, targetName }
+├── SupervisorFailedError        SUPERVISOR_FAILED  (base + authoring/runtime)
+│   ├── MaxIterationsError       SUPERVISOR_MAX_ITERATIONS  { maxIterations }
+│   ├── SupervisorRoutingError   SUPERVISOR_INVALID_ROUTE
+│   ├── SupervisorCancelledError SUPERVISOR_CANCELLED       { cancelledAt, reason }
+│   └── SupervisorDriftError     SUPERVISOR_DRIFT           { savedSignature, currentSignature, runId }
+├── ProviderError                PROVIDER_ERROR  (base + catch-all)
+│   ├── ProviderRateLimitError   PROVIDER_RATE_LIMIT        { retryAfter? } — transient
+│   ├── QuotaExceededError       PROVIDER_QUOTA_EXCEEDED    — NOT retryable (billing cap)
+│   ├── ProviderTimeoutError     PROVIDER_TIMEOUT
+│   ├── ContextLengthExceededError CONTEXT_LENGTH_EXCEEDED  { limit?, actual?, modelName? }
+│   ├── ContentFilterError       CONTENT_FILTER             { reason?, categories? }
+│   ├── InvalidRequestError      PROVIDER_INVALID_REQUEST
+│   └── ProviderAuthError        PROVIDER_AUTH
+├── BudgetExceededError          BUDGET_EXCEEDED            { limit, actual, unit } — from ai.middleware.budget
+└── GuardrailViolationError      GUARDRAIL_VIOLATION        { phase, reason } — from ai.middleware.guardrail
+```
+
+> `SupervisorFailedError` doubles as the base for the supervisor family **and** the authoring-time error for bad config (e.g. `route` + `router` both set). It carries extra `SUPERVISOR_INTENT_*` / `SUPERVISOR_DISPATCH_CYCLE` codes for specific intent-validation failures.
+
+## Error fields
+
+- `code` — stable `AIErrorCode` string.
+- `category` — coarse `ErrorCategory`.
+- `message` — human-readable.
+- `cause?` — root error (often a provider SDK error).
+- `context?` — `Record<string, unknown>` for provider-raw diagnostics (`status`, `requestId`, `headers`).
+
+Typed fields (`retryAfter`, `toolName`, `issues`, `stepName`, …) are first-class consumer surface.
+
+## Retry strategy
+
+| Error family | Retryable? |
+| --- | --- |
+| `ProviderRateLimitError` | Yes — back off by `retryAfter` ms |
+| `ProviderTimeoutError` | Yes — short delay |
+| `ProviderError` (generic) | Maybe — depends on cause |
+| `QuotaExceededError` | **No** — needs human intervention |
+| `ProviderAuthError` | **No** — fix config / rotate key |
+| `ContextLengthExceededError` | Only after truncating input |
+| `ContentFilterError` | Usually **no** — the prompt itself is the issue |
+| `SchemaValidationError` | Use agent `repair: { maxAttempts }` instead |
+| `ToolExecutionError` | Depends on `cause` |
+| `WorkflowDriftError` | **No** — manual migration or `force: true` |
+| `WorkflowCancelledError` | **No** — caller-driven cancel |
+| `MaxStepsExceededError` / `RoutingError` | **No** — programmer error |
+| `BudgetExceededError` | **No** — raise the cap, split the workload |
+| `GuardrailViolationError` (`phase: "input"`) | **No** — block / sanitize at product layer |
+| `GuardrailViolationError` (`phase: "output"`) | Sometimes — re-prompt with adjusted system message |
+
+## Why extend `Error`, not `HttpError`
+
+- `@warlock.js/ai` is a standalone product — used from CLIs / workers / scripts as often as HTTP handlers.
+- Coupling to a web framework pulls HTTP into every consumer.
+- AI errors aren't HTTP errors anyway — "rate limit" is a 429 the *upstream provider* returned, not one the server returns.
+
+The **consumer app** layer (`src/app/ai/`) wraps framework errors with its own `AIError` subclass that extends `HttpError`. See `domains/ai/conventions/errors.md`.
+
+## OpenAI adapter — status + code dispatch
+
+The OpenAI wrapper categorizes via `APIError.status + code` combined:
+
+- `APIError.code` is semantically stable (`context_length_exceeded`, `content_filter`, `invalid_api_key`, etc.) across SDK versions; message strings are not.
+- Status alone collapses three distinct failure modes into one bucket (`400` = context-length OR content-filter OR bad-model-name).
+- When `code` is missing (proxied deployments), fall back to `status`.
+- Name-based detection catches `APIConnectionTimeoutError` and Node-level `ETIMEDOUT` / `ECONNABORTED`.
+
+## Pattern — full fallback ladder
+
+```ts
+async function runWithFallbacks(input: string) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const { data, error } = await myAgent.execute(input);
+
+    if (!error) return data;
+
+    if (error instanceof ProviderRateLimitError) {
+      await sleep(error.retryAfter ?? 2000);
+      continue;
+    }
+
+    if (error instanceof ContextLengthExceededError) {
+      input = truncate(input, error.limit ?? 4000);
+      continue;
+    }
+
+    if (error instanceof QuotaExceededError || error instanceof ProviderAuthError) {
+      throw error;   // not retryable
+    }
+
+    throw error;     // unknown — give up
+  }
+
+  throw new Error("exhausted retries");
+}
+```
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — `AgentResult.error`
+- [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `WorkflowError` subclasses
+- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — `ToolExecutionError` wrapping
+- [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md) — error logging
+- `domains/ai/conventions/errors.md` — framework vs app error convention

package/skills/log-ai-calls/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: log-ai-calls
+description: 'Framework logging delegated to @warlock.js/logger — every primitive emits via the log singleton, configure channels / levels / redaction once at boot. Four-arg call convention (module, action, message, context). Triggers: `log.configure`, `log.setMinLevel`, `log.setChannels`, `ConsoleLog`, `FileLog`, `LogChannel`, `redact.paths`, `ai.agent.<name>` / `ai.workflow.<name>` / `ai.supervisor.<name>` modules; ''configure ai logging'', ''mask prompts in logs'', ''silence logs in tests'', ''capture log entries''; typical import `import { log } from "@warlock.js/logger"`. Skip: error hierarchy — `@warlock.js/ai/handle-ai-errors/SKILL.md`; competing libs `pino`, `winston`, `console.log`.'
+---
+
+# Logging — `log` from `@warlock.js/logger`
+
+`@warlock.js/ai` does not own a logger contract. Every primitive imports the `log` singleton from [`@warlock.js/logger`](@warlock.js/logger/logger-basics/SKILL.md) directly and emits structured entries through it. Configuration — channels, levels, redaction — lives entirely on the logger.
+
+**No `ai.config({ logger })`. No per-primitive `logger:` override.** Configure once at app boot; the framework picks it up.
+
+## Installation — configure at boot
+
+```ts
+import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
+
+log.configure({
+  channels: [
+    new ConsoleLog(),
+    new FileLog({ chunk: "daily" }),
+  ],
+  autoFlushOn: ["SIGINT", "SIGTERM", "beforeExit"],
+});
+
+log.setMinLevel("info");
+```
+
+That's it. Every agent / workflow / supervisor running in the process emits to the configured channels.
+
+## Call convention — four positional args
+
+Every framework log call uses the 4-arg positional form:
+
+```ts
+log.info("ai.agent", "trip.started", "agent starting trip", { tripIndex, model });
+```
+
+- **`module`** — emitting primitive, name-suffixed (`"ai.agent.<name>"`, `"ai.workflow.<name>"`, `"ai.supervisor.<name>"`); provider adapters use `"ai.openai"` etc.
+- **`action`** — mirrors event names without the primitive prefix (`"trip.started"`, `"tool.called"`).
+- **`message`** — human-readable summary.
+- **`context`** — structured bag of diagnostic fields.
+
+`action` strips the prefix of the corresponding event (`agent.trip.started` → `trip.started`) so grep filters and event handlers share vocabulary.
+
+## Level mapping
+
+| Level | Framework usage |
+| --- | --- |
+| `debug` | Internals (request/response bodies, token counts per trip) |
+| `info` | Milestones (agent starting, agent completed) |
+| `warn` | Retries, repair attempts, recoverable tool failures |
+| `error` | Terminal failures surfaced via `result.error` |
+| `success` | Tool-call success |
+
+Streaming deltas are intentionally **not** logged at token granularity — trip boundaries carry the same information at readable volume.
+
+## What gets logged
+
+### Agent
+
+| Action | Level | Context |
+|---|---|---|
+| `agent.starting` | `info` | inputLength, model, maxTrips |
+| `trip.started` | `debug` | tripIndex |
+| `tool.calling` | `debug` | tool name, action, tripIndex |
+| `tool.called` | `success` | tool name, duration, tripIndex |
+| `tool.failed` | `warn` | tool name, error code, tripIndex |
+| `repair.attempting` | `warn` | tripIndex, validation issues |
+| `agent.completed` | `info` | totalUsage, totalDuration, trip count |
+| `agent.error` | `error` | error code, message, stack |
+
+### Workflow
+
+`workflow.starting` / `step.starting` / `step.completed` / `step.failed` / `workflow.completed` / `workflow.error`. Module is `ai.workflow.<name>`.
+
+### Supervisor
+
+`supervisor.starting` / `iteration.starting` / `router.deciding` / `router.decided` / `agent.starting` (per dispatched agent) / `iteration.completed` / `evaluate.verdict` / `supervisor.completed`. Module is `ai.supervisor.<name>`.
+
+### Provider adapter
+
+`ai.openai` (and future adapters) emit `request` (debug) and `response` (debug) per call, plus `error` on the wrapped `AIError`.
+
+## Redaction
+
+Redaction is a `@warlock.js/logger` feature — configure once on the logger, applies to every framework log automatically.
+
+```ts
+log.configure({
+  redact: {
+    paths: [
+      "context.messages",          // prompts
+      "context.input",              // user input
+      "context.apiKey",             // never log this anyway, but defense-in-depth
+    ],
+  },
+});
+```
+
+See [`@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md) for the full redaction surface.
+
+## Events vs. logs — two channels, one source
+
+- **Events** are push-model (subscribers), typed payloads, per-execution lifetime — ideal for UI streaming, SSE, metrics.
+- **Logs** are pull-model (written to channels), structured-string + context, persistent — ideal for grep, post-mortem.
+
+Both fire from the same internal emit so every event produces both.
+
+## Patterns
+
+### Silence everything in tests
+
+```ts
+import { log } from "@warlock.js/logger";
+
+beforeAll(() => log.setChannels([]));
+```
+
+### Capture all framework log entries in a test
+
+```ts
+import { log, LogChannel } from "@warlock.js/logger";
+
+class Capture extends LogChannel {
+  public name = "capture";
+  public entries: any[] = [];
+  public log(data) { this.entries.push(data); }
+}
+
+const capture = new Capture();
+log.setChannels([capture]);
+```
+
+See [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-logging-code/SKILL.md) for the test patterns.
+
+## See also
+
+- [`@warlock.js/logger/logger-basics/SKILL.md`](@warlock.js/logger/logger-basics/SKILL.md) — logger foundations
+- [`@warlock.js/logger/configure-logger/SKILL.md`](@warlock.js/logger/configure-logger/SKILL.md) — startup setup
+- [`@warlock.js/logger/redact-sensitive-log-fields/SKILL.md`](@warlock.js/logger/redact-sensitive-log-fields/SKILL.md) — redaction
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — what lands on the `error` channel

package/skills/persist-ai-data/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: persist-ai-data
+description: 'Persistence delegated to @warlock.js/cache — workflow + supervisor snapshot resume via snapshotStore, semantic cache via vector-capable CacheDriver, global default via ai.config({defaultStore}). Covers drift detection + three recovery paths. Triggers: `ai.config`, `defaultStore`, `snapshotStore`, `wf.resume`, `supervisor.resume`, `WorkflowSnapshot`, `SupervisorSnapshot`, `WorkflowDriftError`, `SupervisorDriftError`, `force: true`; ''resume a workflow run'', ''configure snapshot store'', ''handle signature drift'', ''wire pg vector cache''; typical import `import { ai } from "@warlock.js/ai"`. Skip: cache driver catalog — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `temporal`, `inngest`.'
+---
+
+# Persistence — `@warlock.js/cache` everywhere
+
+`@warlock.js/ai` owns no persistence primitives. Anything that needs durable state — supervisor / workflow snapshot resume, semantic cache, future memory — accepts a `CacheDriver` from `@warlock.js/cache`. The cache package ships memory / lru-memory / file / redis / pg drivers; pg adds optional `pgvector` for similarity retrieval.
+
+## The big picture
+
+```
+┌──────────────┐        ┌─────────────────────────┐
+│  ai.config   │  ───▶  │  @warlock.js/cache      │
+│ defaultStore │        │  CacheDriver            │
+└──────────────┘        │  (memory|redis|pg|...)  │
+                        └────────────▲────────────┘
+                                     │
+       ┌─────────────────────────────┼─────────────────────────────┐
+┌──────────────┐         ┌────────────────────┐         ┌──────────────────┐
+│ supervisor   │         │   workflow         │         │  semanticCache   │
+│ snapshotStore│         │  snapshotStore     │         │  store (vector)  │
+└──────────────┘         └────────────────────┘         └──────────────────┘
+```
+
+## Resolution order
+
+```
+options.store ?? ai.config({ defaultStore }) ?? undefined
+```
+
+When neither is set:
+- **Snapshot consumers** silently skip writes and throw on `resume()`.
+- **Semantic cache** throws at construction.
+
+## `ai.config({ defaultStore })` — set once at boot
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { cache } from "@warlock.js/cache";
+
+ai.config({
+  defaultStore: cache.driver("redis", { client: redisClient }),
+});
+```
+
+Every consumer that doesn't supply its own `store` / `snapshotStore` picks this up. Per-declaration overrides win.
+
+## Picking a driver
+
+| Driver | KV | TTL | Tags | `similar()` | Fits |
+|---|---|---|---|---|---|
+| `memory` / `lru-memory` | ✅ | ✅ | ✅ | ✅ (brute force) | Dev / tests |
+| `file` | ✅ | ✅ | ✅ | ❌ | Single-process persistence |
+| `null` | no-op | no-op | no-op | `[]` | Test isolation |
+| `redis` | ✅ | ✅ | ✅ | (RediSearch, separate phase) | Production KV + future similarity |
+| `pg` | ✅ | ✅ | ✅ | ✅ (pgvector) | Production semantic cache |
+
+Brute-force memory drivers carry an `O(N)` similarity scan — fine up to a few thousand entries.
+
+## Snapshot resume — workflow + supervisor
+
+### Wiring
+
+```ts
+ai.config({ defaultStore: cache.driver("redis", { client }) });
+
+const wf = ai.workflow({
+  name: "ticket-processor",
+  steps: [...],
+  // snapshotStore optional — falls back to defaultStore
+});
+
+const sup = ai.supervisor({
+  name: "support-team",
+  router: routerAgent,
+  intents: { triage, billing, resolver },
+  // explicit override when this primitive needs a different driver
+  snapshotStore: cache.driver("pg", { client: pgPool, table: "support_runs" }),
+});
+```
+
+### Snapshot shapes
+
+```ts
+type WorkflowSnapshot = {
+  runId: string;
+  workflowName: string;
+  signature: string;             // structural fingerprint
+  version?: string;
+  input: unknown;
+  state: Record<string, unknown>;
+  steps: Record<string, StepSnapshot>;
+  next: string | null;
+  status: "running" | "completed" | "failed" | "cancelled";
+  startedAt: string;
+  savedAt: string;
+};
+
+type SupervisorSnapshot = {
+  runId: string;
+  supervisorName: string;
+  signature: string;
+  input: string | Record<string, unknown>;   // SupervisorInput
+  iteration: number;                          // last *completed* iteration; -1 before any settle
+  snapshots: IterationSnapshot[];
+  status: "running" | "completed" | "failed" | "cancelled";
+  startedAt: string;
+  savedAt: string;
+};
+```
+
+### Checkpoint rules
+
+- Workflow: snapshot after every step settles. Parallel groups checkpoint atomically.
+- Supervisor: snapshot after every iteration. Plus once on final completion / cancel / fail.
+- Mid-step / mid-iteration crash resumes from the last completed checkpoint — partial work is **not** persisted.
+- **Idempotency is the user's responsibility.** Steps and agents may re-run on resume.
+
+## Fresh run vs. resume
+
+```ts
+const result = await wf.execute({ input, runId: "ticket-123" });
+const result = await wf.resume("ticket-123");
+
+await sup.execute("urgent", { runId: "support-7" });
+await sup.resume("support-7");
+```
+
+Resume reads the snapshot, rehydrates state, continues from the snapshot's `next`.
+
+## Signature drift detection
+
+`signature` is a structural fingerprint computed at construction. On `resume()`, current signature is compared to the snapshot's. Mismatch throws `WorkflowDriftError` / `SupervisorDriftError` **without executing**:
+
+```ts
+{
+  code: "WORKFLOW_DRIFT",
+  savedSignature: "abc123…",
+  currentSignature: "def456…",
+  runId: "ticket-123",
+  completedSteps: ["fetch", "extract"],
+  pendingStep: "classify",
+}
+```
+
+## Recovery paths
+
+Three choices when drift is detected:
+
+1. **Discard** — safest when the shape genuinely changed:
+
+   ```ts
+   await store.remove("ticket-123");
+   await wf.execute({ input, runId: "ticket-123" });
+   ```
+
+2. **Force resume** — escape hatch for trivial edits you know are safe:
+
+   ```ts
+   await wf.resume("ticket-123", { force: true });
+   ```
+
+3. **Manual migration** — for changes you can mechanically translate:
+
+   ```ts
+   const snapshot = await store.get<WorkflowSnapshot>("ticket-123");
+   if (snapshot) {
+     snapshot.steps.newName = snapshot.steps.oldName;
+     delete snapshot.steps.oldName;
+     snapshot.signature = wf.signature;
+     await store.set("ticket-123", snapshot);
+     await wf.resume("ticket-123");
+   }
+   ```
+
+## Semantic cache
+
+```ts
+ai.config({
+  defaultStore: cache.driver("pg", {
+    client: pgPool,
+    vector: { dimensions: 1536, index: "hnsw" },
+  }),
+});
+
+const myAgent = ai.agent({
+  model,
+  middleware: [
+    ai.middleware.semanticCache({
+      embedder: openai.embedder({ name: "text-embedding-3-small" }),
+      threshold: 0.95,
+      ttlMs: 60 * 60 * 1000,
+    }),
+  ],
+});
+```
+
+The driver must support `similar()`. Without similarity → `CacheUnsupportedError`. See [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `snapshotStore` + `resume()`
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — same on supervisor
+- [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — `semanticCache` middleware
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — drift errors
+- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — driver catalog