@anweat/dsh-browser 0.1.15 → 0.2.0-rc.1

package/lib/automation-assets.d.ts

@@ -1,11 +1,58 @@
 /** Bounded, local automation-asset lifecycle and retrieval. */
-import type { BrowserRecipeStep } from './automation.ts';
+import { type AnyRecipeStep, type BrowserRecipeStep, type RecipeExecutionStatus, type RecipeValidationStatus } from './automation.ts';
+import { type InputSpec, type OutputSpec, type PendingDisambiguation, type Postcondition } from './automation-v2.ts';
 export declare const ASSET_PERSISTENCE_MODES: readonly ["off", "manual", "suggest", "auto-draft"];
 export type AssetPersistenceMode = typeof ASSET_PERSISTENCE_MODES[number];
 export declare const ASSET_ACTIVATION_MODES: readonly ["manual", "auto-tested"];
 export type AssetActivationMode = typeof ASSET_ACTIVATION_MODES[number];
 export type AutomationAssetKind = 'recipe' | 'userscript';
 export type AutomationAssetStatus = 'draft' | 'active' | 'archived';
+/**
+ * How strongly the last passing test confirmed the result. `verified`: a recipe
+ * with assert steps ran and every one held. `legacy-unverified`: the steps ran
+ * without raising, but nothing checked the outcome (recipes without an assert
+ * step, UserScripts, and every asset saved before B2). A missing value on stored
+ * data means `legacy-unverified`.
+ */
+export type EvidenceLevel = 'verified' | 'legacy-unverified';
+/** Recipe/UserScript test credentials kept per asset unless `maxTestCredentials` says otherwise. */
+export declare const DEFAULT_TEST_CREDENTIALS = 5;
+/**
+ * What one runtime test proved, bound to the exact content it ran against. Activation trusts
+ * only a credential whose revision and contentHash match the asset as it is now.
+ * Inputs are kept as a digest, never as values.
+ */
+export interface TestCredential {
+    revision: number;
+    /** {@link computeContentHash} of the content that was tested. */
+    contentHash: string;
+    /** sha256 of the typed inputSchema (or of the declared input names for v1 and UserScripts). */
+    inputSchemaHash: string;
+    schemaVersion: 1 | 2;
+    testedAt: string;
+    /** Truncated sha256 of the canonical inputs the test ran with. */
+    inputsDigest: string;
+    executionStatus: RecipeExecutionStatus;
+    validationStatus: RecipeValidationStatus;
+    evidenceLevel: EvidenceLevel;
+    /** The test counted as passed: it completed, nothing failed, and (v2) something verified the result. */
+    passed: boolean;
+    /** Synthesized when data written before B4 was loaded: `testStatus` was `passed` and nothing else is known. */
+    legacy?: true;
+    /** A test with several input sets (each in a fresh context): one entry per set that ran. Digests only. */
+    inputSets?: {
+        index: number;
+        inputsDigest: string;
+        passed: boolean;
+        executionStatus: RecipeExecutionStatus;
+        validationStatus: RecipeValidationStatus;
+        outputsDigest: string;
+    }[];
+    /** How many sets the test was asked to run (more than `inputSets.length` when a failing set stopped it). */
+    plannedSets?: number;
+    /** Cautions on a passing test, e.g. `PARAMETERIZATION_SUSPECT`: different inputs gave identical outputs. */
+    warnings?: string[];
+}
 export interface AutomationAssetPolicyInput {
     enabled?: boolean;
     directory?: string;
@@ -24,6 +71,13 @@ export interface AutomationAssetPolicyInput {
     catalogTokenBudget?: number;
     modelDevelopmentEnabled?: boolean;
     maxModelDraftWritesPerSession?: number;
+    /** How many test credentials each asset keeps (the most recent ones). Default 5. */
+    maxTestCredentials?: number;
+    /**
+     * How many input sets the passing test of an asset that declares inputs must have covered before it can be activated
+     * (1 to 5, default 2). Assets without inputs are not affected.
+     */
+    minInputSetsForActivation?: number;
 }
 export interface AutomationAssetPolicy {
     enabled: boolean;
@@ -43,6 +97,8 @@ export interface AutomationAssetPolicy {
     catalogTokenBudget: number;
     modelDevelopmentEnabled: boolean;
     maxModelDraftWritesPerSession: number;
+    maxTestCredentials: number;
+    minInputSetsForActivation: number;
 }
 export interface AutomationCandidate {
     id: string;
@@ -67,11 +123,45 @@ export interface AutomationAsset {
     domains: string[];
     tags: string[];
     inputNames: string[];
-    recipe?: BrowserRecipeStep[];
+    /** v1 steps (`selector`, first match) or, when `schemaVersion` is 2, {@link BrowserRecipeStepV2}. */
+    recipe?: AnyRecipeStep[];
     source?: string;
+    /** Recipe schema. Absent means 1: `.first()` locating and the v1 fill rule, unchanged. */
+    schemaVersion?: 1 | 2;
+    /** v2: typed inputs. When present they are validated and converted at run time. */
+    inputSchema?: InputSpec[];
+    /** v2: named, typed outputs of `extract` steps with `as`. */
+    outputSchema?: OutputSpec[];
+    /** v2: conditions that must hold after the steps for the result to count as verified. */
+    postconditions?: Postcondition[];
+    /** v2: recorded only; not enforced yet. */
+    requiredCapabilities?: string[];
+    /** v2 converted from v1: steps that still take the first match and should be made unique. Derived from the recipe on save. */
+    pendingDisambiguation?: PendingDisambiguation[];
+    /** Set when this draft was converted from another asset; the source is never modified. */
+    sourceAssetId?: string;
+    sourceRevision?: number;
+    /**
+     * Set on a draft built from an exploration journal (`draft_from_journal`). `unmapped` counts the journaled
+     * actions that could not become steps; while it is above zero the draft is a half-finished copy of the
+     * exploration and cannot be activated. Saving the draft again with an explicit recipe replaces it and drops this.
+     */
+    origin?: {
+        kind: 'journal';
+        fromSeq: number;
+        toSeq: number;
+        unmapped: number;
+    };
+    /** Bumped by every save, never reused. */
     revision: number;
+    /** sha256 over the recipe or source, schemaVersion, inputSchema, outputSchema, postconditions and domains. Derived; recomputed on load. */
+    contentHash?: string;
+    /** The most recent runtime tests, oldest first. Activation checks the one bound to the current revision. */
+    testCredentials?: TestCredential[];
     testStatus: 'untested' | 'passed' | 'failed';
     testMessage?: string;
+    /** Optional on stored data; absent means `legacy-unverified`. Set only by a passing runtime test. */
+    evidenceLevel?: EvidenceLevel;
     successCount: number;
     failureCount: number;
     createdAt: string;
@@ -87,6 +177,10 @@ export interface AutomationAssetSummary {
     domains: string[];
     tags: string[];
     inputNames: string[];
+    /** Only present for schema v2 assets. */
+    schemaVersion?: 2;
+    /** v2 assets: the typed inputs a caller must pass to automation.run. */
+    inputSchema?: InputSpec[];
     revision: number;
     testStatus: AutomationAsset['testStatus'];
     successCount: number;
@@ -113,8 +207,38 @@ export interface AutomationAssetSnapshot {
 }
 export declare function defaultAutomationAssetDirectory(): string;
 export declare function resolveAutomationAssetPolicy(input?: AutomationAssetPolicyInput): AutomationAssetPolicy;
+type HashedContent = Pick<AutomationAsset, 'kind' | 'recipe' | 'source' | 'schemaVersion' | 'inputSchema' | 'outputSchema' | 'postconditions' | 'domains'>;
+/**
+ * What a test vouches for: the steps or source, the schema version and the three v2 contracts, and the
+ * domains it may run on. Name, description, tags and counters are not content. Domains are a set.
+ */
+export declare function computeContentHash(asset: HashedContent): string;
+/** A digest of the inputs a test ran with. The values themselves are never stored. */
+export declare function digestInputs(inputs: unknown): string;
+/** Why an activation request was refused; the message says what to do. */
+export type ActivationRefusal = 'expected-revision-required' | 'revision-mismatch' | 'not-tested' | 'test-failed' | 'content-changed' | 'no-domain' | 'limit-reached' | 'incomplete-draft' | 'insufficient-input-sets';
+export declare class ActivationRefusedError extends Error {
+    readonly reason: ActivationRefusal;
+    constructor(reason: ActivationRefusal, message: string);
+}
 /** Remove concrete form values and non-semantic output from a successful recipe. */
 export declare function normalizeRecipeForCandidate(steps: BrowserRecipeStep[]): BrowserRecipeStep[];
+/** What a test reports besides pass/fail, for the credential it leaves. */
+export interface TestDetails {
+    /** The inputs the test ran with; only their digest is kept. */
+    inputs?: unknown;
+    executionStatus?: RecipeExecutionStatus;
+    validationStatus?: RecipeValidationStatus;
+    inputSchemaHash?: string;
+    /** The revision and content that were tested; defaults to the asset's current ones. */
+    tested?: {
+        revision: number;
+        contentHash: string;
+    };
+    inputSets?: NonNullable<TestCredential['inputSets']>;
+    plannedSets?: number;
+    warnings?: string[];
+}
 export declare class AutomationAssetStore {
     readonly policy: AutomationAssetPolicy;
     private readonly statePath;
@@ -126,14 +250,38 @@ export declare class AutomationAssetStore {
     summarizeCandidate(id: string): AutomationAsset;
     dismissCandidate(id: string): void;
     saveDraft(input: Partial<AutomationAsset> & Pick<AutomationAsset, 'kind' | 'name'>): AutomationAsset;
+    /** Validate the v2 steps and asset-level fields of a draft about to be saved. Throws RecipeValidationError. */
+    private checkV2;
     validate(id: string): AutomationAsset;
-    setStatus(id: string, status: AutomationAssetStatus): AutomationAsset;
+    /**
+     * Copy an asset into a NEW draft that remembers where it came from (`sourceAssetId`, `sourceRevision`).
+     * This is how an active asset is repaired: active assets cannot be edited, the copy can, and the source
+     * keeps running until the copy is tested and activated (which then archives the source).
+     */
+    fork(id: string): AutomationAsset;
+    /**
+     * Change an asset's status. Activation is the guarded one: the request must name the revision the caller
+     * looked at (`expectedRevision`), and that revision, as it is now, needs a passed test credential bound to
+     * its exact content. A draft that was forked from (or converted from) an active asset replaces it: the
+     * source is archived in the same write, so the repaired asset never runs next to the one it fixes.
+     */
+    setStatus(id: string, status: AutomationAssetStatus, options?: {
+        expectedRevision?: number;
+    }): AutomationAsset;
+    /** Throws {@link ActivationRefusedError} unless `asset` may become active; returns the active asset it replaces, if any. */
+    private checkActivation;
     search(query: string, domain?: string, status?: AutomationAssetStatus | 'all', kind?: AutomationAssetKind): AutomationAssetSummary[];
     noteRun(id: string, ok: boolean): void;
-    noteTestResult(id: string, ok: boolean, url: string): void;
+    /**
+     * Record one runtime test as a credential bound to the content that ran. The asset's own `testStatus`
+     * moves only if that content is still the asset's current content: a test that finishes after a newer
+     * save leaves a credential for the old revision and changes nothing else.
+     */
+    noteTestResult(id: string, ok: boolean, url: string, evidenceLevel?: EvidenceLevel, failureReason?: string, details?: TestDetails): void;
     assertTarget(asset: AutomationAsset, url: string): void;
     private requireAsset;
     private prune;
     private read;
     private write;
 }
+export {};

package/lib/automation-assets.js

@@ -3,9 +3,15 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { validateRecipeEnums } from "./automation.js";
+import { RecipeValidationError } from "./actions/errors.js";
+import { normalizeInputSchema, normalizeOutputSchema, normalizePostconditions, normalizeRequiredCapabilities, pendingDisambiguation, placeholderNames, validateRecipeV2, hostInDomains, } from "./automation-v2.js";
 import { validateUserscript } from "./scripts.js";
+import { INPUT_SET_MAX, inputSetShortfall } from "./activation-rules.js";
 export const ASSET_PERSISTENCE_MODES = ['off', 'manual', 'suggest', 'auto-draft'];
 export const ASSET_ACTIVATION_MODES = ['manual', 'auto-tested'];
+/** Recipe/UserScript test credentials kept per asset unless `maxTestCredentials` says otherwise. */
+export const DEFAULT_TEST_CREDENTIALS = 5;
 const DEFAULT_STATE = { version: 1, candidates: [], assets: [] };
 function boundedInteger(value, fallback, min, max) {
     return typeof value === 'number' && Number.isInteger(value) ? Math.min(Math.max(value, min), max) : fallback;
@@ -42,11 +48,52 @@ export function resolveAutomationAssetPolicy(input = {}) {
         catalogTokenBudget: boundedInteger(input.catalogTokenBudget, 800, 100, 4_000),
         modelDevelopmentEnabled: input.modelDevelopmentEnabled ?? true,
         maxModelDraftWritesPerSession: boundedInteger(input.maxModelDraftWritesPerSession, 3, 1, 20),
+        maxTestCredentials: boundedInteger(input.maxTestCredentials, DEFAULT_TEST_CREDENTIALS, 1, 20),
+        minInputSetsForActivation: boundedInteger(input.minInputSetsForActivation, 2, 1, 5),
     };
 }
 function nowIso(now = Date.now()) { return new Date(now).toISOString(); }
 function uid() { return crypto.randomUUID(); }
 function hash(value) { return crypto.createHash('sha256').update(value).digest('hex'); }
+/** JSON with sorted keys and no undefined members: the same value always gives the same text. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(entry => canonicalJson(entry)).join(',') + ']';
+    if (value && typeof value === 'object') {
+        const record = value;
+        return '{' + Object.keys(record).filter(key => record[key] !== undefined).sort().map(key => JSON.stringify(key) + ':' + canonicalJson(record[key])).join(',') + '}';
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * What a test vouches for: the steps or source, the schema version and the three v2 contracts, and the
+ * domains it may run on. Name, description, tags and counters are not content. Domains are a set.
+ */
+export function computeContentHash(asset) {
+    return hash(canonicalJson({
+        ...asset.kind === 'userscript' ? { source: asset.source ?? '' } : { recipe: asset.recipe ?? [] },
+        schemaVersion: asset.schemaVersion ?? 1,
+        inputSchema: asset.inputSchema ?? null,
+        outputSchema: asset.outputSchema ?? null,
+        postconditions: asset.postconditions ?? null,
+        domains: [...asset.domains].sort(),
+    }));
+}
+function computeInputSchemaHash(asset) {
+    return hash(canonicalJson(asset.inputSchema ?? { inputNames: [...asset.inputNames].sort() }));
+}
+/** A digest of the inputs a test ran with. The values themselves are never stored. */
+export function digestInputs(inputs) {
+    return hash(canonicalJson(inputs ?? {})).slice(0, 16);
+}
+export class ActivationRefusedError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'ActivationRefusedError';
+    }
+}
 function safeDomain(url) {
     const parsed = new URL(url);
     if (!['http:', 'https:'].includes(parsed.protocol))
@@ -99,7 +146,7 @@ function candidateFingerprint(domain, steps) {
 }
 function summary(asset) {
     const { id, kind, status, name, description, domains, tags, inputNames, revision, testStatus, successCount, failureCount, updatedAt, lastRunAt } = asset;
-    return { id, kind, status, name, description, domains: [...domains], tags: [...tags], inputNames: [...inputNames], revision, testStatus, successCount, failureCount, updatedAt, ...lastRunAt ? { lastRunAt } : {} };
+    return { id, kind, status, name, description, domains: [...domains], tags: [...tags], inputNames: [...inputNames], ...asset.schemaVersion === 2 ? { schemaVersion: 2, ...asset.inputSchema ? { inputSchema: structuredClone(asset.inputSchema) } : {} } : {}, revision, testStatus, successCount, failureCount, updatedAt, ...lastRunAt ? { lastRunAt } : {} };
 }
 function persistedState(value) {
     if (!value || typeof value !== 'object')
@@ -121,11 +168,33 @@ function persistedState(value) {
         || !Array.isArray(asset.tags) || asset.tags.length > 20 || !Array.isArray(asset.inputNames) || asset.inputNames.length > 20
         || (asset.kind === 'recipe' && (!Array.isArray(asset.recipe) || asset.recipe.length < 1 || asset.recipe.length > 25))
         || (asset.kind === 'userscript' && (typeof asset.source !== 'string' || Buffer.byteLength(asset.source, 'utf8') > 64 * 1024))
+        || (asset.schemaVersion !== undefined && ![1, 2].includes(asset.schemaVersion))
         || !Number.isInteger(asset.revision) || !Number.isFinite(Date.parse(asset.createdAt)) || !Number.isFinite(Date.parse(asset.updatedAt)));
     if (malformedCandidate || malformedAsset)
         throw new Error('persisted asset entries are malformed');
+    const malformedCredentials = state.assets.some(asset => asset.testCredentials !== undefined
+        && (!Array.isArray(asset.testCredentials) || asset.testCredentials.some(entry => !entry || typeof entry !== 'object' || !Number.isInteger(entry.revision) || typeof entry.contentHash !== 'string')));
+    if (malformedCredentials)
+        throw new Error('persisted test credentials are malformed');
+    for (const asset of state.assets)
+        upgradeLegacyAsset(asset);
     return { version: 1, candidates: state.candidates, assets: state.assets };
 }
+/**
+ * Fill in what data written before B4 lacks, without touching any existing field: the content hash is
+ * derived, and a `testStatus` of `passed` becomes a legacy credential bound to the current revision.
+ */
+function upgradeLegacyAsset(asset) {
+    asset.contentHash = computeContentHash(asset);
+    if (asset.testStatus === 'passed' && !asset.testCredentials?.some(entry => entry.revision === asset.revision)) {
+        const legacy = {
+            revision: asset.revision, contentHash: asset.contentHash, inputSchemaHash: computeInputSchemaHash(asset), schemaVersion: asset.schemaVersion ?? 1,
+            testedAt: asset.updatedAt, inputsDigest: 'legacy', executionStatus: 'completed',
+            validationStatus: asset.evidenceLevel === 'verified' ? 'passed' : 'not_checked', evidenceLevel: asset.evidenceLevel ?? 'legacy-unverified', passed: true, legacy: true,
+        };
+        asset.testCredentials = [...asset.testCredentials ?? [], legacy];
+    }
+}
 export class AutomationAssetStore {
     policy;
     statePath;
@@ -207,6 +276,7 @@ export class AutomationAssetStore {
             domains: [candidate.domain], tags: [`candidate:${candidate.id}`], inputNames: recipeInputNames(candidate.steps), recipe: structuredClone(candidate.steps), revision: 1,
             testStatus: 'untested', successCount: 0, failureCount: 0, createdAt: timestamp, updatedAt: timestamp,
         };
+        asset.contentHash = computeContentHash(asset);
         this.state.assets.push(asset);
         candidate.dismissedAt = timestamp;
         this.write();
@@ -232,23 +302,52 @@ export class AutomationAssetStore {
         if (!name)
             throw new Error('automation asset name is required');
         const kind = input.kind;
+        const schemaVersion = input.schemaVersion ?? existing?.schemaVersion ?? 1;
+        if (schemaVersion !== 1 && schemaVersion !== 2)
+            throw new RecipeValidationError('schemaVersion must be 1 or 2');
         const domains = [...new Set((input.domains ?? []).map(value => cap(String(value).toLowerCase(), 255)).filter(Boolean))].slice(0, 20);
         const tags = [...new Set((input.tags ?? []).map(value => cap(String(value), 40)).filter(Boolean))].slice(0, 20);
         const declaredInputNames = [...new Set((input.inputNames ?? []).map(value => cap(String(value), 40)).filter(value => /^[a-zA-Z][\w-]*$/.test(value)))].slice(0, 20);
         if (kind === 'recipe' && (!Array.isArray(input.recipe) || input.recipe.length < 1 || input.recipe.length > 25))
             throw new Error('recipe asset requires 1 to 25 steps');
+        const hasV2Fields = [input.inputSchema, input.outputSchema, input.postconditions, input.requiredCapabilities].some(value => value !== undefined);
+        if (kind === 'userscript' && (schemaVersion === 2 || hasV2Fields))
+            throw new RecipeValidationError('schemaVersion 2 and inputSchema/outputSchema/postconditions/requiredCapabilities apply to recipe assets only');
+        if (kind === 'recipe' && schemaVersion === 1 && hasV2Fields)
+            throw new RecipeValidationError('inputSchema, outputSchema, postconditions and requiredCapabilities need schemaVersion 2');
+        // Unknown extract modes and wait conditions never reach storage; assets already stored are not re-checked.
+        if (kind === 'recipe' && schemaVersion === 1)
+            validateRecipeEnums(input.recipe);
+        const v2 = kind === 'recipe' && schemaVersion === 2 ? this.checkV2(input, domains) : undefined;
         if (kind === 'userscript') {
             const validation = validateUserscript(String(input.source ?? ''));
             if (!validation.valid)
                 throw new Error('userscript is invalid: ' + validation.errors.join('; '));
         }
-        const inputNames = kind === 'recipe' ? recipeInputNames(input.recipe) : declaredInputNames;
+        const inputNames = v2 ? v2.inputNames : kind === 'recipe' ? recipeInputNames(input.recipe) : declaredInputNames;
+        const sourceAssetId = input.sourceAssetId ?? existing?.sourceAssetId;
+        const sourceRevision = input.sourceRevision ?? existing?.sourceRevision;
+        if (sourceAssetId !== undefined && (typeof sourceAssetId !== 'string' || sourceAssetId.length > 80 || !Number.isInteger(sourceRevision)))
+            throw new RecipeValidationError('sourceAssetId needs a string id and an integer sourceRevision');
         const asset = {
             id: existing?.id ?? uid(), kind, status: 'draft', name, description: cap(String(input.description ?? ''), 500), domains, tags, inputNames,
             ...kind === 'recipe' ? { recipe: structuredClone(input.recipe) } : { source: String(input.source) },
+            ...v2 ? {
+                schemaVersion: 2,
+                ...v2.inputSchema ? { inputSchema: v2.inputSchema } : {},
+                ...v2.outputSchema ? { outputSchema: v2.outputSchema } : {},
+                ...v2.postconditions ? { postconditions: v2.postconditions } : {},
+                ...v2.requiredCapabilities ? { requiredCapabilities: v2.requiredCapabilities } : {},
+                ...v2.pending.length ? { pendingDisambiguation: v2.pending } : {},
+            } : {},
+            ...sourceAssetId !== undefined ? { sourceAssetId, sourceRevision: sourceRevision } : {},
+            ...input.origin ? { origin: structuredClone(input.origin) } : {},
             revision: (existing?.revision ?? 0) + 1, testStatus: 'untested', successCount: existing?.successCount ?? 0, failureCount: existing?.failureCount ?? 0,
+            // Earlier credentials stay as history; each is bound to its own revision and never vouches for this one.
+            ...existing?.testCredentials?.length ? { testCredentials: existing.testCredentials.slice(-this.policy.maxTestCredentials) } : {},
             createdAt: existing?.createdAt ?? timestamp, updatedAt: timestamp, ...existing?.lastRunAt ? { lastRunAt: existing.lastRunAt } : {},
         };
+        asset.contentHash = computeContentHash(asset);
         if (existing)
             this.state.assets[this.state.assets.indexOf(existing)] = asset;
         else
@@ -256,11 +355,60 @@ export class AutomationAssetStore {
         this.write();
         return structuredClone(asset);
     }
+    /** Validate the v2 steps and asset-level fields of a draft about to be saved. Throws RecipeValidationError. */
+    checkV2(input, domains) {
+        try {
+            const steps = input.recipe;
+            validateRecipeV2(steps);
+            const gotos = steps.filter(step => step.type === 'goto');
+            if (gotos.length && domains.length === 0)
+                throw new Error('a recipe with goto steps must declare domains: goto may only go to the asset\'s domains');
+            for (const step of gotos) {
+                if (/\{\{/.test(step.url))
+                    continue; // a placeholder host is checked when the recipe runs
+                const host = new URL(step.url).hostname;
+                if (!hostInDomains(host, domains))
+                    throw new Error(`goto ${host} is not allowed on this asset: it is outside its domains (${domains.join(', ')})`);
+            }
+            const inputSchema = input.inputSchema !== undefined ? normalizeInputSchema(input.inputSchema) : undefined;
+            const outputSchema = input.outputSchema !== undefined ? normalizeOutputSchema(input.outputSchema, steps) : undefined;
+            const postconditions = input.postconditions !== undefined ? normalizePostconditions(input.postconditions, steps) : undefined;
+            const requiredCapabilities = input.requiredCapabilities !== undefined ? normalizeRequiredCapabilities(input.requiredCapabilities) : undefined;
+            const used = placeholderNames(steps, postconditions ?? []);
+            if (inputSchema) {
+                const declared = new Set(inputSchema.map(spec => spec.name));
+                const undeclared = used.filter(name => !declared.has(name));
+                if (undeclared.length)
+                    throw new Error(`the recipe uses {{${undeclared.join('}}, {{')}}} but inputSchema does not declare it`);
+            }
+            else if (used.length > 20)
+                throw new Error('recipe exceeds 20 reusable inputs');
+            return {
+                inputNames: inputSchema ? inputSchema.map(spec => spec.name) : used.slice(0, 20),
+                ...inputSchema ? { inputSchema } : {}, ...outputSchema ? { outputSchema } : {}, ...postconditions ? { postconditions } : {},
+                ...requiredCapabilities ? { requiredCapabilities } : {},
+                pending: pendingDisambiguation(steps),
+            };
+        }
+        catch (error) {
+            throw error instanceof RecipeValidationError ? error : new RecipeValidationError(error instanceof Error ? error.message : String(error));
+        }
+    }
     validate(id) {
         const asset = this.requireAsset(id);
         let message = 'Recipe structure is valid; runtime replay is still required.';
-        if (asset.kind === 'recipe')
-            normalizeRecipeForCandidate(asset.recipe ?? []);
+        if (asset.kind === 'recipe' && asset.schemaVersion === 2) {
+            this.checkV2(asset, asset.domains);
+            const hasAssert = asset.recipe.some(step => step.type === 'assert');
+            const notes = [];
+            if (asset.pendingDisambiguation?.length)
+                notes.push(`${asset.pendingDisambiguation.length} step(s) still take the first match (explicitFirst): make their locators unique`);
+            if (!hasAssert && !asset.postconditions?.length)
+                notes.push('no assert step or postcondition: a test cannot pass until one checks the result');
+            message = 'Recipe v2 structure is valid; runtime replay is still required.' + (notes.length ? ' ' + notes.join('; ') + '.' : '');
+        }
+        else if (asset.kind === 'recipe')
+            normalizeRecipeForCandidate((asset.recipe ?? []));
         else {
             const validation = validateUserscript(asset.source ?? '');
             if (!validation.valid)
@@ -269,23 +417,88 @@ export class AutomationAssetStore {
         }
         return { ...structuredClone(asset), testMessage: message };
     }
-    setStatus(id, status) {
+    /**
+     * Copy an asset into a NEW draft that remembers where it came from (`sourceAssetId`, `sourceRevision`).
+     * This is how an active asset is repaired: active assets cannot be edited, the copy can, and the source
+     * keeps running until the copy is tested and activated (which then archives the source).
+     */
+    fork(id) {
+        if (!this.policy.enabled || this.policy.persistenceMode === 'off')
+            throw new Error('automation asset persistence is disabled');
+        const source = this.requireAsset(id);
+        if (this.state.assets.filter(item => item.status === 'draft').length >= this.policy.maxDrafts)
+            throw new Error('automation draft limit reached');
+        const timestamp = nowIso();
+        const copy = structuredClone(source);
+        const draft = {
+            id: uid(), kind: copy.kind, status: 'draft', name: copy.name, description: copy.description, domains: copy.domains, tags: copy.tags, inputNames: copy.inputNames,
+            ...copy.recipe ? { recipe: copy.recipe } : {}, ...copy.source !== undefined ? { source: copy.source } : {},
+            ...copy.schemaVersion ? { schemaVersion: copy.schemaVersion } : {},
+            ...copy.inputSchema ? { inputSchema: copy.inputSchema } : {}, ...copy.outputSchema ? { outputSchema: copy.outputSchema } : {},
+            ...copy.postconditions ? { postconditions: copy.postconditions } : {}, ...copy.requiredCapabilities ? { requiredCapabilities: copy.requiredCapabilities } : {},
+            ...copy.pendingDisambiguation ? { pendingDisambiguation: copy.pendingDisambiguation } : {},
+            sourceAssetId: source.id, sourceRevision: source.revision,
+            revision: 1, testStatus: 'untested', successCount: 0, failureCount: 0, createdAt: timestamp, updatedAt: timestamp,
+        };
+        draft.contentHash = computeContentHash(draft);
+        this.state.assets.push(draft);
+        this.write();
+        return structuredClone(draft);
+    }
+    /**
+     * Change an asset's status. Activation is the guarded one: the request must name the revision the caller
+     * looked at (`expectedRevision`), and that revision, as it is now, needs a passed test credential bound to
+     * its exact content. A draft that was forked from (or converted from) an active asset replaces it: the
+     * source is archived in the same write, so the repaired asset never runs next to the one it fixes.
+     */
+    setStatus(id, status, options = {}) {
         const asset = this.requireAsset(id);
         if (!['draft', 'active', 'archived'].includes(status))
             throw new Error('invalid automation asset status');
+        let replaced;
         if (status === 'active') {
-            if (asset.testStatus !== 'passed')
-                throw new Error('automation asset must pass testing before activation');
-            if (asset.domains.length < 1)
-                throw new Error('automation asset must declare at least one domain before activation');
-            if (this.state.assets.filter(item => item.status === 'active' && item.id !== id).length >= this.policy.maxActiveAssets)
-                throw new Error('active automation asset limit reached');
+            replaced = this.checkActivation(asset, options.expectedRevision);
         }
+        const timestamp = nowIso();
         asset.status = status;
-        asset.updatedAt = nowIso();
+        asset.updatedAt = timestamp;
+        if (replaced) {
+            replaced.status = 'archived';
+            replaced.updatedAt = timestamp;
+        }
         this.write();
         return structuredClone(asset);
     }
+    /** Throws {@link ActivationRefusedError} unless `asset` may become active; returns the active asset it replaces, if any. */
+    checkActivation(asset, expectedRevision) {
+        if (!Number.isInteger(expectedRevision))
+            throw new ActivationRefusedError('expected-revision-required', 'activation requires expectedRevision: the revision you looked at and tested');
+        if (asset.revision !== expectedRevision) {
+            throw new ActivationRefusedError('revision-mismatch', `activation refused: expectedRevision ${expectedRevision} is not the current revision ${asset.revision}; the asset changed after you looked at it. Reload it, test that revision, then activate it`);
+        }
+        const credentials = (asset.testCredentials ?? []).filter(entry => entry.revision === asset.revision);
+        const latest = credentials.at(-1);
+        if (!latest)
+            throw new ActivationRefusedError('not-tested', `automation asset must pass testing before activation: revision ${asset.revision} has no test credential`);
+        if (!latest.passed || asset.testStatus !== 'passed')
+            throw new ActivationRefusedError('test-failed', `automation asset must pass testing before activation: the latest test of revision ${asset.revision} did not pass`);
+        if (latest.contentHash !== computeContentHash(asset)) {
+            throw new ActivationRefusedError('content-changed', `automation asset must pass testing before activation: the passed test of revision ${asset.revision} covered different content than the asset has now; save and test it again`);
+        }
+        const shortfall = inputSetShortfall(asset, latest, this.policy.minInputSetsForActivation);
+        if (shortfall) {
+            throw new ActivationRefusedError('insufficient-input-sets', `automation asset declares ${shortfall.declared} input(s), so its passing test must cover at least ${shortfall.required} different input sets (automationAssets.minInputSetsForActivation), but the test of revision ${asset.revision} covered ${shortfall.covered}. A recipe written against one input can hard-code it. Test again with ${shortfall.required} to ${INPUT_SET_MAX} different input objects (automation.develop test with inputSets, or a JSON array in the panel's test inputs)`);
+        }
+        if (asset.origin?.unmapped)
+            throw new ActivationRefusedError('incomplete-draft', `automation draft is incomplete: ${asset.origin.unmapped} action(s) of the exploration it was built from (journal seq ${asset.origin.fromSeq}-${asset.origin.toSeq}) could not become steps. Finish the recipe yourself and save it, test it, then activate`);
+        if (asset.domains.length < 1)
+            throw new ActivationRefusedError('no-domain', 'automation asset must declare at least one domain before activation');
+        const replaced = asset.sourceAssetId ? this.state.assets.find(item => item.id === asset.sourceAssetId && item.id !== asset.id && item.status === 'active') : undefined;
+        if (this.state.assets.filter(item => item.status === 'active' && item.id !== asset.id && item.id !== replaced?.id).length >= this.policy.maxActiveAssets) {
+            throw new ActivationRefusedError('limit-reached', 'active automation asset limit reached');
+        }
+        return replaced;
+    }
     search(query, domain, status = 'active', kind) {
         if (!query.trim())
             throw new Error('automation search requires explicit keywords');
@@ -326,13 +539,40 @@ export class AutomationAssetStore {
         asset.updatedAt = asset.lastRunAt;
         this.write();
     }
-    noteTestResult(id, ok, url) {
+    /**
+     * Record one runtime test as a credential bound to the content that ran. The asset's own `testStatus`
+     * moves only if that content is still the asset's current content: a test that finishes after a newer
+     * save leaves a credential for the old revision and changes nothing else.
+     */
+    noteTestResult(id, ok, url, evidenceLevel = 'legacy-unverified', failureReason, details = {}) {
         const asset = this.requireAsset(id);
         if (asset.status !== 'draft')
             throw new Error('only draft automation assets can record test results');
         const domain = safeDomain(url);
-        asset.testStatus = ok ? 'passed' : 'failed';
-        asset.testMessage = ok ? `Runtime replay passed on ${domain}.` : `Runtime replay failed on ${domain}.`;
+        const currentHash = computeContentHash(asset);
+        const tested = details.tested ?? { revision: asset.revision, contentHash: currentHash };
+        const credential = {
+            revision: tested.revision, contentHash: tested.contentHash, inputSchemaHash: details.inputSchemaHash ?? computeInputSchemaHash(asset), schemaVersion: asset.schemaVersion ?? 1,
+            testedAt: nowIso(), inputsDigest: digestInputs(details.inputs),
+            executionStatus: details.executionStatus ?? (ok ? 'completed' : 'failed'),
+            validationStatus: details.validationStatus ?? (ok && evidenceLevel === 'verified' ? 'passed' : 'not_checked'),
+            evidenceLevel: ok ? evidenceLevel : 'legacy-unverified', passed: ok,
+            ...details.inputSets ? { inputSets: details.inputSets, plannedSets: details.plannedSets ?? details.inputSets.length } : {},
+            ...details.warnings?.length ? { warnings: details.warnings } : {},
+        };
+        asset.testCredentials = [...asset.testCredentials ?? [], credential].slice(-this.policy.maxTestCredentials);
+        if (tested.revision === asset.revision && tested.contentHash === currentHash) {
+            asset.testStatus = ok ? 'passed' : 'failed';
+            if (ok)
+                asset.evidenceLevel = evidenceLevel;
+            else
+                delete asset.evidenceLevel;
+            asset.testMessage = !ok ? (failureReason ?? `Runtime replay failed on ${domain}.`)
+                : evidenceLevel === 'verified' ? `Runtime replay passed on ${domain}; every assert step held.`
+                    : `Runtime replay passed on ${domain}; no assert step checked the result (legacy-unverified).`;
+            if (ok && details.inputSets)
+                asset.testMessage += ` ${details.inputSets.length} input sets, each in a fresh context.${details.warnings?.length ? ' ' + details.warnings.join(', ') + ': different inputs gave identical outputs.' : ''}`;
+        }
         asset.updatedAt = nowIso();
         this.write();
     }