ai-runtime-engine 2.9.0 → 3.0.1

package/dist/runtime/runtime.js

@@ -55,6 +55,9 @@ import { ExecutionStore } from '../executions/store.js';
 import { RESUMABLE, TERMINAL } from '../executions/execution.js';
 import { captureCheckpoint, reconcile } from '../executions/checkpoint.js';
 import { AGENT_TERMINAL, AGENT_RESUMABLE, agentTaskView } from '../agents/task.js';
+import { synthesizeAgents } from '../agents/synthesize.js';
+import { isDerivedAgentId } from '../agents/roles.js';
+import { resolveConflicts } from '../agents/finding.js';
 import { parseAgentTasks } from '../executions/agentTasks.js';
 import { stepIdentity } from '../agents/worker.js';
 import { hashOf } from '../util/hash.js';
@@ -91,7 +94,7 @@ import { loadModelProfile, resolveModelDirective, directiveToOverrides } from '.
 import { HashEmbedder } from '../memory/embedders/hash.js';
 import { HttpEmbedder } from '../memory/embedders/http.js';
 import { Credential } from '../security/credentials.js';
-import { makeCodec, deriveKey } from '../store/crypto.js';
+import { makeCodec } from '../store/crypto.js';
 import { AIError } from '../core/fallback/errors.js';
 import { tokenize } from '../memory/bm25.js';
 let runCounter = 0;
@@ -211,7 +214,7 @@ export class Runtime {
         });
         this._modelProfile = loadModelProfile(root); // models.md (per-mode/task routing); undefined if absent
         this._memory = new MemoryStore(this._store, clock, this.buildEmbedder(options.ai?.fetchImpl));
-        this._conversations = new ConversationStore(this._store.conversations(), clock);
+        this._conversations = new ConversationStore(this._store.conversations(), clock, { withLock: (fn) => this._store.withLock(fn) });
         this._executions = new ExecutionStore(this._store.executions(), { clock });
         this._artifacts = new ArtifactStore(this._store.artifacts(), clock);
         this._learning = new LearningStore(this._store.learning());
@@ -288,7 +291,9 @@ export class Runtime {
         const key = new Credential(cfg.keyEnv, this.env).use();
         if (!key)
             throw new AIError(`storage encryption is enabled but the key env var ${cfg.keyEnv} is not set`, { category: 'CONFIG' });
-        return makeCodec(deriveKey(key));
+        // Pass the SECRET (not a pre-derived key) so the codec uses the v2 scrypt scheme; it still reads any
+        // legacy aienc1 records transparently and upgrades them to aienc2 as they are rewritten.
+        return makeCodec(key);
     }
     /** Build a Runtime from a workspace: load config (.ai-runtime/config.yaml > root fallback), detect workspace. */
     static async load(options = {}) {
@@ -460,6 +465,12 @@ export class Runtime {
     registerAgent(id, def) {
         if (!/^[a-z0-9][a-z0-9_-]{0,32}$/.test(id))
             throw new AIError(`invalid agent id '${id}' — use lowercase letters, digits, '_' or '-' (max 33 chars)`, { category: 'CONFIG' });
+        // The same reservation the config schema enforces. Without it here, a host could register
+        // `auto_investigate` and — with decompose on — produce two catalog rows with one id, where the
+        // derived one wins both lookups and the SAME step resolves to a different envelope depending on a
+        // flag. Reserving a namespace in only one of its two doors reserves nothing.
+        if (isDerivedAgentId(id))
+            throw new AIError(`agent id '${id}' uses the reserved 'auto_' prefix — that namespace belongs to agents the runtime derives`, { category: 'CONFIG' });
         this.agentDefs.set(id, def);
         return this;
     }
@@ -471,13 +482,34 @@ export class Runtime {
      * This run's agent envelopes. THE ONLY call site of `narrowEnvelope` — never re-derive an inner
      * catalog, a permission clamp, or a reservation anywhere else (see the header of agents/envelope.ts).
      */
-    agentEnvelopes(policy) {
-        if (!this.agentsEnabled || this.agentDefs.size === 0)
+    /**
+     * Agents synthesized from the registry for this goal (Phase 3.7). Empty unless
+     * `runtime.agents.decompose` is on — so with the flag off nothing about planning changes.
+     *
+     * Deterministic and offline: no model call, no clock, no randomness. That is a requirement, not a
+     * preference — a derived definition is hashed into `agentDefHash`, and a resume that synthesized
+     * even slightly differently would discard every persisted inner plan as stale.
+     */
+    derivedAgents() {
+        if (!this.agentsEnabled || this.settingsValue.agents?.decompose !== true)
+            return [];
+        const capabilities = this._capabilities.list().map((c) => ({ id: c.id, effects: c.effects, providers: this._capabilities.providersOf(c.id).map((p) => p.providerId) }));
+        return synthesizeAgents({ capabilities, parentTools: this._tools.ids() });
+    }
+    agentEnvelopes(policy, derived = []) {
+        // Derived definitions are passed IN and never stored: `agentDefs` lives for the process, so writing
+        // a per-goal agent into it would leak that agent into every later run on this Runtime.
+        const entries = [
+            ...[...this.agentDefs].map(([id, d]) => [id, d, 'authored']),
+            ...derived.map((d) => [d.id, d.definition, 'derived']),
+        ];
+        if (!this.agentsEnabled || entries.length === 0)
             return [];
         const routing = this.effectiveRouting();
-        return [...this.agentDefs].map(([id, definition]) => narrowEnvelope({
+        return entries.map(([id, definition, provenance]) => narrowEnvelope({
             agentId: id,
             definition,
+            provenance,
             parentTools: this._tools.ids(),
             parentSkills: this.skills().map((sk) => ({ id: sk.id, ...(sk.tools ? { tools: sk.tools } : {}) })),
             parentPermissions: policy.permissions,
@@ -594,11 +626,13 @@ export class Runtime {
         return [...this.mcpWarnings, ...this._mcp.warningsList()];
     }
     /**
-     * Release long-lived resources — today: MCP stdio child processes. A one-shot CLI command and the REPL
-     * both call this on completion/exit; without it a spawned server keeps the event loop alive.
+     * Release long-lived resources: MCP stdio child processes, and any batching telemetry sink (so a
+     * short-lived run does not drop OTLP events buffered below the batch threshold). A one-shot CLI command
+     * and the REPL both call this on completion/exit.
      */
     async close() {
         await this._mcp.close();
+        await this._ai.close();
     }
     /** Skills whose required tools are all registered. */
     skills() {
@@ -621,9 +655,9 @@ export class Runtime {
         if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(manifest.id))
             throw new AIError(`unsafe skill id: ${JSON.stringify(manifest.id)}`, { category: 'CONFIG' });
         const dir = join(this.workspaceRoot, '.ai-runtime', 'skills');
-        mkdirSync(dir, { recursive: true });
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
         const path = join(dir, `${manifest.id}.skill.yaml`);
-        writeFileSync(path, stringifyYaml(manifest));
+        writeFileSync(path, stringifyYaml(manifest), { mode: 0o600 });
         return path;
     }
     /** The ACTION-capability registry (Phase 3.1): what this runtime can DO, and who provides it. */
@@ -800,6 +834,12 @@ export class Runtime {
                 streamedText += chunk;
                 this.emitter.emit({ type: 'response.delta', runId, text: chunk });
             };
+            // A failed streamed attempt's partial text is discarded: reset the accumulator so the survivor's
+            // stream is what `streamed` is compared against, and tell the host to clear the abandoned segment.
+            runRequest.onStreamAbandoned = ({ providerId, model }) => {
+                streamedText = '';
+                this.emitter.emit({ type: 'response.stream_abandoned', runId, providerId, model });
+            };
         }
         const runResult = await this._ai.run(runRequest);
         this.calibrate(runRequest.system, text, runResult);
@@ -1028,6 +1068,10 @@ export class Runtime {
                     exec.completedSteps = [...exec.completedSteps, record.stepId];
                     checkpointIfMoved();
                 }
+                // A finished task is the only moment new findings can appear, so it is the only moment two of
+                // them can start disagreeing.
+                if (AGENT_TERMINAL.has(record.state))
+                    this.resolveFindingConflicts(exec);
                 commit();
             },
             /**
@@ -1070,9 +1114,10 @@ export class Runtime {
             ...(routing ? { routing } : {}),
             ...(partial ? { partial: true } : {}),
             ...(this.approval ? { approval: this.approval } : {}),
-            // Phase 3.1: the capability snapshot is opt-in (`runtime.capabilities.catalog`); the gap resolver is
-            // always on but only fires on a validation failure, adding metadata to an unchanged error.
-            ...(this.settingsValue.capabilities?.catalog ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
+            // Phase 3.1, ON by default from 3.0.0 (`runtime.capabilities.catalog: false` removes it); the gap
+            // resolver is always on but only fires on a validation failure, adding metadata to an unchanged error.
+            // 3.0.0: ON by default. `catalog: false` removes it — the only way to get the 2.9.0 prompt back.
+            ...(this.settingsValue.capabilities?.catalog !== false ? { capabilityCatalog: this.capabilityCatalogText() } : {}),
             // Phase 3.3: the derived-requirement block (opt-in, pre-rendered + clamped). Absent ⇒ the
             // OrchestrateInput/PlannerInput objects are key-identical to 2.5.1.
             ...(requiredCapabilities ? { requiredCapabilities } : {}),
@@ -1102,11 +1147,19 @@ export class Runtime {
         this._learning.record({ goalType: this.goalType(goal), mode, ok: outcome.status === 'completed', skills: this.planSkillRefs(outcome.plan) });
     }
     /**
-     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1, opt-in). Untrusted
-     * sources (anything not an in-tree builtin) have their descriptions fenced, and the block is bounded so
-     * a large catalog can never dominate the prompt.
+     * A capped, FENCED action-capability snapshot for the planner prompt (Phase 3.1; ON by default from
+     * 3.0.0 — set `runtime.capabilities.catalog: false` to remove it).
+     *
+     * The fence is real as of 3.0.0 and was not before: this block carries ids that come from MCP servers
+     * and third-party skills, and it renders them as trusted-looking prompt structure on every planning
+     * iteration of every run. Flattening (`promptSafe`) bounds their shape but says nothing about their
+     * provenance, so the whole block is wrapped as untrusted data. Three comments claimed "fenced" while
+     * no fence existed; shipping that ON by default would have made a false safety claim load-bearing.
+     *
+     * Both halves are bounded. The blocked-skill list had no cap at all — measured at ~24k characters
+     * with 300 blocked skills, silently, in every prompt.
      */
-    capabilityCatalogText(maxEntries = 40) {
+    capabilityCatalogText(maxEntries = 40, maxBlocked = 15) {
         const caps = this._capabilities.list();
         if (caps.length === 0)
             return '';
@@ -1116,17 +1169,21 @@ export class Runtime {
                 .providersOf(c.id)
                 .map((p) => `${promptSafe(p.providerId)}${p.availability === 'available' ? '' : ` (${p.availability})`}`)
                 .join(', ');
-            lines.push(`  - capability "${promptSafe(c.id)}" [${c.effects.join('/')}] → ${promptSafe(providers, 200)}`);
+            // Every segment is clamped, `effects` included: it is an array off a declaration, so a hostile or
+            // simply careless source can make one row arbitrarily long.
+            lines.push(`  - capability "${promptSafe(c.id)}" [${promptSafe(c.effects.join('/'), 40)}] → ${promptSafe(providers, 200)}`);
         }
         const more = caps.length > maxEntries ? `\n  …and ${caps.length - maxEntries} more (see /capabilities)` : '';
         // Skills hidden by a missing tool — the "why can't you do this" answer the planner needs.
         const usable = new Set(this.skills().map((sk) => sk.id));
-        const blocked = this._skills
-            .list()
-            .filter((sk) => !usable.has(sk.id))
+        const blockedAll = this._skills.list().filter((sk) => !usable.has(sk.id));
+        const blocked = blockedAll
+            .slice(0, maxBlocked)
             .map((sk) => `  - skill "${promptSafe(sk.id)}" needs tool(s) ${promptSafe((sk.tools ?? []).filter((t) => !this._tools.ids().includes(t)).join(', '), 200)} (not registered)`);
-        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}` : '';
-        return `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`;
+        const blockedMore = blockedAll.length > maxBlocked ? `\n  …and ${blockedAll.length - maxBlocked} more` : '';
+        const unavailable = blocked.length ? `\nUnavailable (do not use):\n${blocked.join('\n')}${blockedMore}` : '';
+        // The ids inside come from MCP servers and third-party skills. Fenced as data, not structure.
+        return wrapUntrusted('capability-catalog', `Action capabilities:\n${lines.join('\n')}${more}${unavailable}`);
     }
     /** Any call/cost ceiling declared in the config file's `budget:` block (router-level, not policy). */
     configBudget() {
@@ -1503,8 +1560,12 @@ export class Runtime {
      */
     orchestrateRunners(policy, opts) {
         const { runId, signal, provenance, onRecord, agentResume } = opts;
-        const envelopes = policy ? this.agentEnvelopes(policy) : [];
+        const derived = this.derivedAgents();
+        const envelopes = policy ? this.agentEnvelopes(policy, derived) : [];
         const byId = new Map(envelopes.map((e) => [e.agentId, e]));
+        // Definitions come from a LOCAL map, not the process-lifetime field: a derived agent exists for
+        // this run only, and must not be findable by any later one.
+        const defsById = new Map([...this.agentDefs, ...derived.map((d) => [d.id, d.definition])]);
         return {
             runSkill: (skillId, input) => this.runSkill(skillId, input).then((o) => ({ result: o.result, validation: o.validation })),
             runTool: (toolId, input) => this.runTool(toolId, input),
@@ -1514,13 +1575,14 @@ export class Runtime {
                     reserve: (step) => (step.agent ? byId.get(step.agent)?.reservation ?? 1 : 0),
                     runAgent: async (step, ctx) => {
                         const envelope = byId.get(step.agent ?? '');
-                        const definition = this.agentDefs.get(step.agent ?? '');
+                        const definition = defsById.get(step.agent ?? '');
                         if (!envelope || !definition)
                             return { stepId: step.id, ok: false, code: 'agent-not-enabled', error: `no agent definition '${step.agent ?? ''}'` };
                         const innerSkills = this._skills.list().filter((sk) => envelope.skills.includes(sk.id));
                         // Phase 3.5: continue a persisted task for THIS step, if one exists.
                         const prior = agentResume?.(step);
                         const out = await runAgentTask(step, envelope, definition, {
+                            ...(derived.some((d) => d.id === step.agent) ? { derived: true } : {}),
                             ...(prior?.record ? { resume: prior.record } : {}),
                             ...(prior?.answer ? { resumeAnswer: prior.answer } : {}),
                             ai: this._ai,
@@ -1579,6 +1641,52 @@ export class Runtime {
                 : {}),
         };
     }
+    /**
+     * Reconcile findings that contradict each other, across ALL of this execution's agent tasks
+     * (Phase 3.7).
+     *
+     * `resolveConflicts` has existed since 3.4 with no caller, so two agents reaching opposite
+     * conclusions about the same subject both stayed `active` — and both were rendered into the next
+     * planning prompt, as if the runtime had no opinion about which was better supported. It does: it
+     * weighs evidence-based `confidence`, with `executionCoverage` only as a tiebreak.
+     *
+     * Runs at the ONE point new findings can appear — a task reaching a terminal state — and writes the
+     * outcome back onto the owning records, so a supersession survives a restart rather than being
+     * recomputed (and possibly recomputed differently) on every read.
+     *
+     * EVERY finding is passed in, not just the active ones. Resolving over the active subset makes the
+     * result depend on the order tasks happen to finish: a finding that beat a weak rival in wave 1 can
+     * itself lose in wave 2, and the wave-1 loser is then left pointing at a superseded finding — a
+     * broken chain nothing heals. Re-resolving the whole set each round is order-independent and gives
+     * the same answer as one pass over the final set.
+     */
+    resolveFindingConflicts(exec) {
+        const { tasks } = parseAgentTasks(exec);
+        const all = tasks.flatMap((t) => t.findings);
+        if (all.length < 2)
+            return;
+        const resolved = new Map(resolveConflicts(all).map((f) => [f.id, f]));
+        let changed = false;
+        const next = tasks.map((t) => {
+            const findings = t.findings.map((f) => {
+                const r = resolved.get(f.id);
+                if (!r || (r.status === f.status && r.supersededBy === f.supersededBy))
+                    return f;
+                changed = true;
+                const next = { ...f, status: r.status };
+                if (r.supersededBy)
+                    next.supersededBy = r.supersededBy;
+                else
+                    delete next.supersededBy;
+                return next;
+            });
+            return changed ? { ...t, findings } : t;
+        });
+        if (!changed)
+            return;
+        const byId = new Map(next.map((t) => [t.agentTaskId, t]));
+        exec.agentTasks = (exec.agentTasks ?? []).map((entry) => byId.get(entry.agentTaskId ?? '') ?? entry);
+    }
     /**
      * A bounded, fenced brief of what the agents have already established (Phase 3.5).
      *

package/dist/runtime/types.d.ts

@@ -90,7 +90,8 @@ export interface RuntimeSettings {
         encrypt: boolean;
         keyEnv: string;
     };
-    /** Action capabilities (Phase 3.1/3.3). `catalog` enriches the planner catalog (default off);
+    /** Action capabilities (Phase 3.1/3.3). `catalog` enriches the planner catalog (default ON since 3.0.0;
+     *  set `catalog: false` to remove the block);
      *  `planning` (3.3, default OFF) derives the capabilities a goal needs BEFORE planning — offline BM25
      *  first, one model call only when that finds nothing AND no call budget is set AND this is not a dry
      *  run — resolves them against the run's permissions, and reports gaps. ADVISORY: it never blocks a
@@ -120,6 +121,12 @@ export interface RuntimeSettings {
      *  the worker's hard inner-model-call ceiling. */
     agents?: {
         enabled?: boolean;
+        /** Phase 3.7, default OFF: offer the goal a bounded, read-shaped agent per shipped ROLE, with no
+         *  operator-authored definition. The roles and their objectives are in-tree; nothing the model
+         *  writes becomes an objective, a tool id or a permission.
+         *
+         *  REQUIRES `enabled: true` — on its own this does nothing, because agent execution is off. */
+        decompose?: boolean;
         maxToolCalls?: number;
         maxDurationMs?: number;
         maxInnerCalls?: number;

package/dist/store/area.d.ts

@@ -5,7 +5,7 @@
  */
 export interface IntegrityIssue {
     file: string;
-    problem: 'unreadable' | 'checksum-mismatch' | 'invalid-json';
+    problem: 'unreadable' | 'checksum-mismatch' | 'invalid-json' | 'decrypt-auth-failed' | 'unsupported-version';
     detail?: string;
 }
 /**

package/dist/store/area.js

@@ -6,8 +6,19 @@
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { StoreDecryptError } from './errors.js';
 const STORE_VERSION = 1;
 const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+/** Classify a caught read error into an IntegrityIssue problem code (decrypt errors are distinguished). */
+function classifyProblem(err) {
+    if (err instanceof StoreDecryptError) {
+        if (err.code === 'AUTH_FAILED')
+            return 'decrypt-auth-failed';
+        if (err.code === 'UNSUPPORTED_VERSION')
+            return 'unsupported-version';
+    }
+    return 'invalid-json';
+}
 /** Matches an orphaned atomic-write temp file: `<id>.json.tmp-<pid>-<n>` / `<id>.jsonl.tmp-…`. */
 const TEMP_RE = /\.(?:json|jsonl)\.tmp-/;
 function assertId(id) {
@@ -37,7 +48,9 @@ export class FileArea {
     }
     ensure() {
         if (!this.ensured) {
-            mkdirSync(this.dir, { recursive: true });
+            // 0700: store dirs hold conversation/memory/execution/agent records — owner-only on shared hosts.
+            // (mode applies only to dirs this call creates; POSIX-only, a no-op on Windows.)
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
             this.ensured = true;
         }
     }
@@ -51,7 +64,8 @@ export class FileArea {
         this.ensure();
         this.counter += 1;
         const tmp = `${path}.tmp-${process.pid}-${this.counter}`;
-        writeFileSync(tmp, this.encode(contents));
+        // 0600: rename preserves the tmp file's mode, so the final record is owner-only too.
+        writeFileSync(tmp, this.encode(contents), { mode: 0o600 });
         renameSync(tmp, path);
     }
     readJson(id) {
@@ -68,8 +82,14 @@ export class FileArea {
         try {
             return this.readJson(id);
         }
-        catch {
-            return undefined; // a corrupt record must not brick bulk listing/search
+        catch (err) {
+            // A wrong key makes EVERY encrypted record fail — soft-skipping it would present the whole store as
+            // empty, a silent data-loss illusion. Rethrow AUTH_FAILED so the caller sees a real error; genuine
+            // per-record corruption (checksum/JSON/unsupported-version) still soft-skips so one bad record can't
+            // brick bulk listing/search.
+            if (err instanceof StoreDecryptError && err.code === 'AUTH_FAILED')
+                throw err;
+            return undefined;
         }
     }
     writeJson(id, data) {
@@ -96,7 +116,8 @@ export class FileArea {
         assertId(id);
         this.ensure();
         // Each JSONL line is encrypted independently (its own IV), so appends stay append-only.
-        appendFileSync(this.logPath(id), this.encode(JSON.stringify(obj)) + '\n');
+        // 0600 applies when the file is first created; an existing file keeps its mode (append doesn't chmod).
+        appendFileSync(this.logPath(id), this.encode(JSON.stringify(obj)) + '\n', { mode: 0o600 });
     }
     readLines(id) {
         assertId(id);
@@ -110,8 +131,11 @@ export class FileArea {
             try {
                 out.push(JSON.parse(this.decode(line)));
             }
-            catch {
-                /* skip a corrupt/undecryptable line rather than failing the whole log (surfaced by check()) */
+            catch (err) {
+                // Wrong key fails every line — surface it rather than returning a silently-empty log; a single
+                // corrupt line is still skipped (surfaced by check()).
+                if (err instanceof StoreDecryptError && err.code === 'AUTH_FAILED')
+                    throw err;
             }
         }
         return out;
@@ -133,7 +157,7 @@ export class FileArea {
                         issues.push({ file: path, problem: 'checksum-mismatch' });
                 }
                 catch (err) {
-                    issues.push({ file: path, problem: 'invalid-json', detail: err instanceof Error ? err.message : String(err) });
+                    issues.push({ file: path, problem: classifyProblem(err), detail: err instanceof Error ? err.message : String(err) });
                 }
             }
             else if (f.endsWith('.jsonl')) {
@@ -142,8 +166,8 @@ export class FileArea {
                     try {
                         JSON.parse(this.decode(line));
                     }
-                    catch {
-                        issues.push({ file: path, problem: 'invalid-json', detail: `line ${i + 1}` });
+                    catch (err) {
+                        issues.push({ file: path, problem: classifyProblem(err), detail: `line ${i + 1}` });
                     }
                 });
             }

package/dist/store/crypto.d.ts

@@ -1,21 +1,35 @@
 /**
- * Transparent encryption at rest (Phase 18) — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
- * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope
- * `aienc1:<base64(iv|tag|ciphertext)>`; `decode` reverses it. `decode` is deliberately lenient on the way IN —
- * a string WITHOUT the `aienc1:` prefix is returned unchanged, so a store that predates encryption keeps
- * reading after it is enabled (new writes are always encrypted). A wrong key / tampered payload makes `decode`
- * THROW, which the store maps onto its existing corruption path (soft-skip in bulk reads, reported by check()).
+ * Transparent encryption at rest — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
+ * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope,
+ * `decode` reverses it. `decode` is lenient on the way IN — a string WITHOUT a known envelope prefix is
+ * returned unchanged, so a store that predates encryption keeps reading after it is enabled.
  *
- * SECURITY: the derived key is a Buffer held only inside the codec closure; it is never serialized, logged, or
- * placed in an error. The AES key is sha256(secret), so the raw secret length is irrelevant.
+ * TWO envelope versions coexist:
+ *   - `aienc1:` (v1, legacy) — key = sha256(secret). Still READ transparently; never written by 3.0.1+.
+ *   - `aienc2:` (v2, current) — key = scrypt(secret, per-record salt). A proper KDF (memory-hard) so a
+ *     weak/passphrase secret is not brute-forceable at raw-hash speed. Records upgrade to v2 lazily as
+ *     they are rewritten (no bulk migration). The scrypt key is CACHED per salt inside the codec, so a
+ *     bulk read does not pay a fresh derivation per record.
+ *
+ * A decrypt failure throws a typed `StoreDecryptError` (AUTH_FAILED / UNSUPPORTED_VERSION / CORRUPT) —
+ * honest about the fact that a GCM auth failure is wrong-key OR tampering OR corruption, not certainly a
+ * wrong key. SECURITY: derived keys are Buffers held only inside the codec closure; never serialized,
+ * logged, or placed in an error.
  */
 import type { ContentCodec } from './area.js';
 export declare const ENVELOPE_PREFIX = "aienc1:";
-/** Derive the 32-byte AES-256 key from an arbitrary secret (sha256 → fixed length, secret length irrelevant). */
+export declare const ENVELOPE_PREFIX_V2 = "aienc2:";
+/** Derive the 32-byte v1 AES key (sha256 → fixed length). Retained for reading legacy `aienc1:` records. */
 export declare function deriveKey(secret: string): Buffer;
-/** Encrypt a UTF-8 string into the self-identifying `aienc1:` envelope. A fresh random IV per call. */
+/** v1 encrypt into the `aienc1:` envelope (legacy; retained for the exported API and Buffer-key codec). */
 export declare function encryptString(plain: string, key: Buffer): string;
-/** Decrypt an `aienc1:` envelope; a string without the prefix is returned unchanged (mixed/legacy store). */
+/** v1 decrypt of an `aienc1:` envelope; a non-envelope string passes through (mixed/legacy store). */
 export declare function decryptString(stored: string, key: Buffer): string;
-/** Build the codec `FileArea` uses to encrypt/decrypt its file contents. */
-export declare function makeCodec(key: Buffer): ContentCodec;
+/** v2 encrypt into the `aienc2:` envelope (salt‖iv‖tag‖ciphertext). */
+export declare function encryptStringV2(plain: string, key: Buffer, salt: Buffer): string;
+/**
+ * Build the codec `FileArea` uses. A **secret string** yields the current v2 codec (scrypt; writes
+ * `aienc2:`, reads every version). A **Buffer** yields the legacy v1 codec (sha256; writes `aienc1:`) —
+ * retained so existing `makeCodec(deriveKey(secret))` callers behave exactly as before.
+ */
+export declare function makeCodec(keyOrSecret: Buffer | string): ContentCodec;

package/dist/store/crypto.js

@@ -1,23 +1,53 @@
 /**
- * Transparent encryption at rest (Phase 18) — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
- * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope
- * `aienc1:<base64(iv|tag|ciphertext)>`; `decode` reverses it. `decode` is deliberately lenient on the way IN —
- * a string WITHOUT the `aienc1:` prefix is returned unchanged, so a store that predates encryption keeps
- * reading after it is enabled (new writes are always encrypted). A wrong key / tampered payload makes `decode`
- * THROW, which the store maps onto its existing corruption path (soft-skip in bulk reads, reported by check()).
+ * Transparent encryption at rest — AES-256-GCM via `node:crypto` (zero new deps). A `ContentCodec`
+ * transforms the STORED STRING of a store file: `encode` wraps plaintext as a self-identifying envelope,
+ * `decode` reverses it. `decode` is lenient on the way IN — a string WITHOUT a known envelope prefix is
+ * returned unchanged, so a store that predates encryption keeps reading after it is enabled.
  *
- * SECURITY: the derived key is a Buffer held only inside the codec closure; it is never serialized, logged, or
- * placed in an error. The AES key is sha256(secret), so the raw secret length is irrelevant.
+ * TWO envelope versions coexist:
+ *   - `aienc1:` (v1, legacy) — key = sha256(secret). Still READ transparently; never written by 3.0.1+.
+ *   - `aienc2:` (v2, current) — key = scrypt(secret, per-record salt). A proper KDF (memory-hard) so a
+ *     weak/passphrase secret is not brute-forceable at raw-hash speed. Records upgrade to v2 lazily as
+ *     they are rewritten (no bulk migration). The scrypt key is CACHED per salt inside the codec, so a
+ *     bulk read does not pay a fresh derivation per record.
+ *
+ * A decrypt failure throws a typed `StoreDecryptError` (AUTH_FAILED / UNSUPPORTED_VERSION / CORRUPT) —
+ * honest about the fact that a GCM auth failure is wrong-key OR tampering OR corruption, not certainly a
+ * wrong key. SECURITY: derived keys are Buffers held only inside the codec closure; never serialized,
+ * logged, or placed in an error.
  */
-import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
-export const ENVELOPE_PREFIX = 'aienc1:';
+import { createHash, randomBytes, createCipheriv, createDecipheriv, scryptSync } from 'node:crypto';
+import { StoreDecryptError } from './errors.js';
+export const ENVELOPE_PREFIX = 'aienc1:'; // v1 (legacy)
+export const ENVELOPE_PREFIX_V2 = 'aienc2:'; // v2 (current)
 const IV_LEN = 12; // GCM standard nonce
 const TAG_LEN = 16; // GCM auth tag
-/** Derive the 32-byte AES-256 key from an arbitrary secret (sha256 → fixed length, secret length irrelevant). */
+const SALT_LEN = 16; // per-record scrypt salt (v2)
+const KEY_LEN = 32; // AES-256
+// scrypt cost: N=2^14, r=8, p=1 → ~16 MiB working set (under node's 32 MiB default maxmem), ~tens of ms.
+// A change to these parameters requires a new envelope version (aienc3), since the salt alone does not
+// record them.
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+/** Derive the 32-byte v1 AES key (sha256 → fixed length). Retained for reading legacy `aienc1:` records. */
 export function deriveKey(secret) {
     return createHash('sha256').update(secret).digest();
 }
-/** Encrypt a UTF-8 string into the self-identifying `aienc1:` envelope. A fresh random IV per call. */
+/** Derive the 32-byte v2 AES key via scrypt over (secret, salt). Memory-hard — resists brute force. */
+function deriveKeyScrypt(secret, salt) {
+    return scryptSync(secret, salt, KEY_LEN, SCRYPT_PARAMS);
+}
+/** GCM-decrypt; a failed auth tag becomes a typed AUTH_FAILED (wrong key OR tampering OR corruption). */
+function gcmDecrypt(key, iv, tag, ct) {
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+    }
+    catch {
+        throw new StoreDecryptError('AUTH_FAILED', 'store record failed authentication (wrong key, tampering, or corruption)');
+    }
+}
+/** v1 encrypt into the `aienc1:` envelope (legacy; retained for the exported API and Buffer-key codec). */
 export function encryptString(plain, key) {
     const iv = randomBytes(IV_LEN);
     const cipher = createCipheriv('aes-256-gcm', key, iv);
@@ -25,25 +55,73 @@ export function encryptString(plain, key) {
     const tag = cipher.getAuthTag();
     return ENVELOPE_PREFIX + Buffer.concat([iv, tag, ct]).toString('base64');
 }
-/** Decrypt an `aienc1:` envelope; a string without the prefix is returned unchanged (mixed/legacy store). */
+/** v1 decrypt of an `aienc1:` envelope; a non-envelope string passes through (mixed/legacy store). */
 export function decryptString(stored, key) {
     if (!stored.startsWith(ENVELOPE_PREFIX))
-        return stored; // plaintext (pre-encryption) record — read as-is
+        return stored;
     const buf = Buffer.from(stored.slice(ENVELOPE_PREFIX.length), 'base64');
     if (buf.length < IV_LEN + TAG_LEN)
-        throw new Error('encrypted record is truncated');
+        throw new StoreDecryptError('CORRUPT', 'encrypted record is truncated');
     const iv = buf.subarray(0, IV_LEN);
     const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
     const ct = buf.subarray(IV_LEN + TAG_LEN);
-    const decipher = createDecipheriv('aes-256-gcm', key, iv);
-    decipher.setAuthTag(tag);
-    // GCM `final()` throws on a wrong key or tampered ciphertext — surfaces as store corruption to the caller.
-    return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8');
+    return gcmDecrypt(key, iv, tag, ct);
+}
+/** v2 encrypt into the `aienc2:` envelope (salt‖iv‖tag‖ciphertext). */
+export function encryptStringV2(plain, key, salt) {
+    const iv = randomBytes(IV_LEN);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    const ct = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return ENVELOPE_PREFIX_V2 + Buffer.concat([salt, iv, tag, ct]).toString('base64');
 }
-/** Build the codec `FileArea` uses to encrypt/decrypt its file contents. */
-export function makeCodec(key) {
+/**
+ * Decrypt ANY known envelope with the given secret: v2 (scrypt per embedded salt), v1 (sha256), or
+ * plaintext passthrough. An `aiencN:` prefix this build does not know is UNSUPPORTED_VERSION. `keyFor`
+ * supplies (and caches) the scrypt key for a v2 salt.
+ */
+function decryptEnvelope(stored, secret, keyFor) {
+    if (stored.startsWith(ENVELOPE_PREFIX_V2)) {
+        const buf = Buffer.from(stored.slice(ENVELOPE_PREFIX_V2.length), 'base64');
+        if (buf.length < SALT_LEN + IV_LEN + TAG_LEN)
+            throw new StoreDecryptError('CORRUPT', 'encrypted record is truncated');
+        const salt = buf.subarray(0, SALT_LEN);
+        const iv = buf.subarray(SALT_LEN, SALT_LEN + IV_LEN);
+        const tag = buf.subarray(SALT_LEN + IV_LEN, SALT_LEN + IV_LEN + TAG_LEN);
+        const ct = buf.subarray(SALT_LEN + IV_LEN + TAG_LEN);
+        return gcmDecrypt(keyFor(salt), iv, tag, ct);
+    }
+    if (stored.startsWith(ENVELOPE_PREFIX))
+        return decryptString(stored, deriveKey(secret)); // v1 legacy
+    const m = stored.match(/^aienc(\d+):/);
+    if (m)
+        throw new StoreDecryptError('UNSUPPORTED_VERSION', `store record uses an unsupported envelope version 'aienc${m[1]}'`);
+    return stored; // plaintext (pre-encryption) record — read as-is
+}
+/**
+ * Build the codec `FileArea` uses. A **secret string** yields the current v2 codec (scrypt; writes
+ * `aienc2:`, reads every version). A **Buffer** yields the legacy v1 codec (sha256; writes `aienc1:`) —
+ * retained so existing `makeCodec(deriveKey(secret))` callers behave exactly as before.
+ */
+export function makeCodec(keyOrSecret) {
+    if (Buffer.isBuffer(keyOrSecret)) {
+        const key = keyOrSecret;
+        return { encode: (plain) => encryptString(plain, key), decode: (stored) => decryptString(stored, key) };
+    }
+    const secret = keyOrSecret;
+    const encodeSalt = randomBytes(SALT_LEN); // one salt per codec instance → writes share one derivation
+    const keyCache = new Map();
+    const keyFor = (salt) => {
+        const h = salt.toString('hex');
+        let k = keyCache.get(h);
+        if (!k) {
+            k = deriveKeyScrypt(secret, salt);
+            keyCache.set(h, k);
+        }
+        return k;
+    };
     return {
-        encode: (plain) => encryptString(plain, key),
-        decode: (stored) => decryptString(stored, key),
+        encode: (plain) => encryptStringV2(plain, keyFor(encodeSalt), encodeSalt),
+        decode: (stored) => decryptEnvelope(stored, secret, keyFor),
     };
 }

package/dist/store/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Typed store-layer errors. Decryption failures carry an HONEST code: an AEAD (GCM) authentication
+ * failure does NOT prove the key is wrong — it means wrong key OR tampering OR corruption, and the code
+ * says exactly that. Higher layers may infer "likely key mismatch" only from AGGREGATE evidence (most/
+ * all encrypted records failing at once), never from a single record.
+ */
+export type StoreDecryptCode = 'AUTH_FAILED' | 'UNSUPPORTED_VERSION' | 'CORRUPT';
+export declare class StoreDecryptError extends Error {
+    readonly code: StoreDecryptCode;
+    constructor(code: StoreDecryptCode, message: string);
+}