@cleocode/core 2026.6.11 → 2026.6.13

package/dist/selfimprove/envelope-diff.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Envelope normalization + structural diff vs a golden (T11889-B).
+ *
+ * The self-improvement loop replays a scenario (see {@link "./replay.js"}) and
+ * diffs each captured envelope against the golden expected envelope. This module:
+ *
+ *   1. {@link normalizeEnvelope} — strips the VOLATILE `meta` fields so only
+ *      deterministic structure is compared. Two classes are stripped:
+ *      timing/trace fields (`timestamp`, `requestId`, `duration_ms` /
+ *      `durationMs`) AND the per-run session-lineage UUIDs (`sessionId`,
+ *      `originSessionId`, `executionSessionId`). The latter are non-deterministic:
+ *      the live `Dispatcher` defaults `executionSessionId`/`originSessionId` to a
+ *      fresh `randomUUID()` per request
+ *      (`ensureRequestSessionLineage`), then stamps all three onto `response.meta`
+ *      — so a real envelope carries UUIDs the hand-authored golden cannot know.
+ *      Stripping them prevents a permanent phantom DHQ that self-fires on every
+ *      clean run. (The runtime field is `meta` with snake_case `duration_ms`; the
+ *      spec wording uses `_meta`/`durationMs`, so both spellings and both
+ *      container keys are stripped defensively.)
+ *   2. {@link diffEnvelopes} — structurally compares the normalized envelope set
+ *      against the golden, producing `{ regressions: DiffEntry[] }`. Zero
+ *      regressions on a golden match; N on injected divergence. The `meta`
+ *      container is compared as a SUBSET (only golden-declared meta keys are
+ *      asserted) so deterministic-but-golden-absent infra keys
+ *      (`specVersion`, `schemaVersion`, `transport`, `mvi`, `contextVersion`,
+ *      `strict`, `x-cleo-transport`, …) stamped by the runtime are NOT phantom
+ *      regressions. The semantic payload (`data`/`error`) is still compared by
+ *      full key-union — a missing or extra payload key IS a regression.
+ *   3. {@link computeQuestionHash} — sha256 of the normalized regression
+ *      signature (op coordinates + diff path set) so the SAME regression maps to
+ *      the SAME open DHQ row (the idempotency partial-UNIQUE index in T11889-A).
+ *
+ * `extractFieldFromResult` from `@cleocode/lafs` is reused for targeted-field
+ * asserts where a full structural compare would be too brittle.
+ *
+ * This module is PURE — no DB, no native handle, no `cleo` mutation.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/envelope-diff
+ * @epic T11889
+ * @task T11912
+ */
+import type { ReplayEnvelope } from './replay.js';
+import type { GoldenEntry, ScenarioOp } from './scenario.js';
+/**
+ * A normalized envelope: the replayed envelope with volatile `meta` fields removed.
+ *
+ * Structurally identical to {@link ReplayEnvelope} except every volatile
+ * meta field is absent. Stored as a plain JSON-serializable record so it can be
+ * compared deeply and hashed deterministically.
+ */
+export type NormalizedEnvelope = Record<string, unknown>;
+/**
+ * A single structural difference between a normalized envelope and its golden.
+ */
+export interface DiffEntry {
+    /** Zero-based index of the op in the scenario whose envelope diverged. */
+    opIndex: number;
+    /** The op coordinate (`domain.operation`) for the diverging op. */
+    opCoord: string;
+    /** JSON-pointer-ish path to the diverging value (e.g. `data/tasks/0/id`). */
+    path: string;
+    /** The value found in the replayed (actual) normalized envelope. */
+    actual: unknown;
+    /** The value found in the golden (expected) envelope. */
+    expected: unknown;
+}
+/** The result of diffing a replayed envelope set against a golden. */
+export interface EnvelopeDiffResult {
+    /** All structural regressions; empty ⇒ the replay matched the golden. */
+    regressions: DiffEntry[];
+}
+/**
+ * Strip the volatile `meta`/`_meta` fields from an envelope.
+ *
+ * Returns a NEW object; the input is not mutated. The volatile timing/trace fields
+ * AND the per-run session-lineage UUIDs (`sessionId`, `originSessionId`,
+ * `executionSessionId`) are removed — see {@link VOLATILE_META_FIELDS}. The stable
+ * meta remnant (`gateway`, `domain`, `operation`, `source`, …) is preserved so
+ * structural identity (which operation produced the envelope) still compares.
+ *
+ * Note: deterministic-but-golden-absent infra meta keys (`specVersion`,
+ * `transport`, …) are NOT stripped here — they are tolerated by the SUBSET compare
+ * in {@link diffEnvelopes} instead, so the strip set stays exactly the volatile
+ * fields and nothing semantic.
+ *
+ * @param envelope - The replayed envelope to normalize.
+ * @returns The normalized envelope with volatile meta fields removed.
+ *
+ * @example
+ * ```ts
+ * const norm = normalizeEnvelope(envelope);
+ * // norm.meta has no timestamp / requestId / duration_ms / *SessionId
+ * ```
+ */
+export declare function normalizeEnvelope(envelope: ReplayEnvelope): NormalizedEnvelope;
+/**
+ * Diff a set of replayed envelopes against the golden envelope set.
+ *
+ * Normalizes each replayed envelope (volatile meta stripped) and structurally
+ * compares it against the positionally-aligned golden entry. The op coordinate
+ * for each `DiffEntry` is taken from `ops[opIndex]`. Callers MUST pass aligned
+ * arrays (`ops.length === replayed.length === golden.length`); the function
+ * diffs up to the shortest length and reports an extra regression for any length
+ * mismatch.
+ *
+ * The `meta` container is compared as a SUBSET (only golden-declared meta keys are
+ * asserted) so deterministic-but-golden-absent infra keys the runtime stamps
+ * (`specVersion`, `transport`, …) are not phantom regressions; the semantic
+ * payload (`data`/`error`) keeps a full key-union compare where an extra or
+ * missing key IS a regression. Together with the volatile-lineage strip in
+ * {@link normalizeEnvelope}, a real live envelope that matches the golden body
+ * yields ZERO regressions.
+ *
+ * @param ops - The scenario ops (for op-coordinate labelling).
+ * @param replayed - The captured envelopes, one per op (replay order).
+ * @param golden - The golden expected entries, positionally aligned with `ops`.
+ * @returns `{ regressions }` — empty when the replay matches the golden.
+ *
+ * @example
+ * ```ts
+ * const { regressions } = diffEnvelopes(scenario.ops, replayed, golden.envelopes);
+ * if (regressions.length === 0) { /* happy path — no DHQ, no PR *\/ }
+ * ```
+ */
+export declare function diffEnvelopes(ops: ScenarioOp[], replayed: ReplayEnvelope[], golden: GoldenEntry[]): EnvelopeDiffResult;
+/**
+ * Extract a targeted field from a normalized envelope's `data` payload.
+ *
+ * Reuses the LAFS `--field` extractor (`extractFieldFromResult`) for cases where
+ * a full structural diff is too brittle and only a specific field's value matters
+ * (e.g. assert `data.tasks[0].id` without comparing the whole envelope).
+ *
+ * @param normalized - A normalized envelope (from {@link normalizeEnvelope}).
+ * @param field - The field name to extract from the envelope's `data` payload.
+ * @returns The extracted value, or `undefined` when absent.
+ *
+ * @example
+ * ```ts
+ * const id = extractTargetedField(normalizeEnvelope(env), 'id');
+ * ```
+ */
+export declare function extractTargetedField(normalized: NormalizedEnvelope, field: string): unknown;
+/**
+ * Compute the sha256 `question_hash` of a diff result's normalized signature.
+ *
+ * The hash is over the {@link regressionSignature} (op coordinates + diff path
+ * set), so it is stable across runs of the SAME regression and feeds the
+ * idempotency partial-UNIQUE index (`ux_selfimprove_dhq_open`, T11889-A): one
+ * open DHQ row per `question_hash`. An empty regression set hashes the empty
+ * signature deterministically (callers should not persist on the happy path).
+ *
+ * @param result - The diff result whose regressions are hashed.
+ * @returns The lowercase hex sha256 of the regression signature.
+ *
+ * @example
+ * ```ts
+ * const hash = computeQuestionHash(diffEnvelopes(ops, replayed, golden));
+ * ```
+ */
+export declare function computeQuestionHash(result: EnvelopeDiffResult): string;
+//# sourceMappingURL=envelope-diff.d.ts.map

package/dist/selfimprove/envelope-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-diff.d.ts","sourceRoot":"","sources":["../../src/selfimprove/envelope-diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAmD7D;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,WAAW,EAAE,SAAS,EAAE,CAAC;CAC1B;AAeD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAY9E;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,EAAE,EACjB,QAAQ,EAAE,cAAc,EAAE,EAC1B,MAAM,EAAE,WAAW,EAAE,GACpB,kBAAkB,CAqCpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAO3F;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAGtE"}

package/dist/selfimprove/envelope-diff.js

@@ -0,0 +1,321 @@
+/**
+ * Envelope normalization + structural diff vs a golden (T11889-B).
+ *
+ * The self-improvement loop replays a scenario (see {@link "./replay.js"}) and
+ * diffs each captured envelope against the golden expected envelope. This module:
+ *
+ *   1. {@link normalizeEnvelope} — strips the VOLATILE `meta` fields so only
+ *      deterministic structure is compared. Two classes are stripped:
+ *      timing/trace fields (`timestamp`, `requestId`, `duration_ms` /
+ *      `durationMs`) AND the per-run session-lineage UUIDs (`sessionId`,
+ *      `originSessionId`, `executionSessionId`). The latter are non-deterministic:
+ *      the live `Dispatcher` defaults `executionSessionId`/`originSessionId` to a
+ *      fresh `randomUUID()` per request
+ *      (`ensureRequestSessionLineage`), then stamps all three onto `response.meta`
+ *      — so a real envelope carries UUIDs the hand-authored golden cannot know.
+ *      Stripping them prevents a permanent phantom DHQ that self-fires on every
+ *      clean run. (The runtime field is `meta` with snake_case `duration_ms`; the
+ *      spec wording uses `_meta`/`durationMs`, so both spellings and both
+ *      container keys are stripped defensively.)
+ *   2. {@link diffEnvelopes} — structurally compares the normalized envelope set
+ *      against the golden, producing `{ regressions: DiffEntry[] }`. Zero
+ *      regressions on a golden match; N on injected divergence. The `meta`
+ *      container is compared as a SUBSET (only golden-declared meta keys are
+ *      asserted) so deterministic-but-golden-absent infra keys
+ *      (`specVersion`, `schemaVersion`, `transport`, `mvi`, `contextVersion`,
+ *      `strict`, `x-cleo-transport`, …) stamped by the runtime are NOT phantom
+ *      regressions. The semantic payload (`data`/`error`) is still compared by
+ *      full key-union — a missing or extra payload key IS a regression.
+ *   3. {@link computeQuestionHash} — sha256 of the normalized regression
+ *      signature (op coordinates + diff path set) so the SAME regression maps to
+ *      the SAME open DHQ row (the idempotency partial-UNIQUE index in T11889-A).
+ *
+ * `extractFieldFromResult` from `@cleocode/lafs` is reused for targeted-field
+ * asserts where a full structural compare would be too brittle.
+ *
+ * This module is PURE — no DB, no native handle, no `cleo` mutation.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/envelope-diff
+ * @epic T11889
+ * @task T11912
+ */
+import { createHash } from 'node:crypto';
+import { extractFieldFromResult } from '@cleocode/lafs';
+/**
+ * Volatile envelope-meta field names stripped before diffing.
+ *
+ * Two classes, both non-deterministic per run:
+ *
+ *   - Timing / trace: `timestamp`, `requestId`, `duration_ms` (the runtime
+ *     canonical, snake_case) and `durationMs` (the spec wording — stripped so a
+ *     golden authored either way normalizes identically).
+ *   - Session lineage: `sessionId`, `originSessionId`, `executionSessionId`. The
+ *     live `Dispatcher` stamps these onto `response.meta`
+ *     after defaulting `executionSessionId`/`originSessionId` to a fresh
+ *     `randomUUID()` per request (`ensureRequestSessionLineage`). They are
+ *     per-run UUIDs the hand-authored golden cannot encode; leaving them in would
+ *     make every clean replay emit a phantom regression at
+ *     `meta/executionSessionId` and `meta/originSessionId`, and because the
+ *     regression signature hashes only `opCoord@path` (constant), the resulting
+ *     `question_hash` would be STABLE — a permanent self-firing DHQ. Stripping
+ *     them keeps an identical-but-for-lineage envelope a non-regression.
+ */
+const VOLATILE_META_FIELDS = [
+    'timestamp',
+    'requestId',
+    'duration_ms',
+    'durationMs',
+    'sessionId',
+    'originSessionId',
+    'executionSessionId',
+];
+/**
+ * Meta container keys whose volatile fields are stripped, and whose remaining
+ * keys are compared as a SUBSET (see {@link diffEnvelopes}).
+ *
+ * Runtime envelopes use `meta`; `_meta` is stripped too for defensive parity with
+ * the gateway envelope shape.
+ */
+const META_CONTAINER_KEYS = ['meta', '_meta'];
+/**
+ * Top-level envelope keys whose value is a meta container.
+ *
+ * The structural diff treats these containers as a SUBSET compare (golden-declared
+ * keys only) so deterministic-but-golden-absent infra keys the runtime stamps
+ * (`specVersion`, `schemaVersion`, `transport`, `mvi`, `contextVersion`, `strict`,
+ * `x-cleo-transport`, …) are not phantom regressions. Everything else (`data`,
+ * `error`, …) keeps a full key-union compare.
+ */
+const SUBSET_COMPARE_KEYS = new Set(META_CONTAINER_KEYS);
+/**
+ * Deep-clone a JSON-serializable value via structured round-trip.
+ *
+ * Replay envelopes are JSON-shaped (they round-trip through transports), so a
+ * JSON clone is safe and avoids mutating the caller's object during normalization.
+ *
+ * @param value - The value to clone.
+ * @returns A deep copy.
+ */
+function jsonClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Strip the volatile `meta`/`_meta` fields from an envelope.
+ *
+ * Returns a NEW object; the input is not mutated. The volatile timing/trace fields
+ * AND the per-run session-lineage UUIDs (`sessionId`, `originSessionId`,
+ * `executionSessionId`) are removed — see {@link VOLATILE_META_FIELDS}. The stable
+ * meta remnant (`gateway`, `domain`, `operation`, `source`, …) is preserved so
+ * structural identity (which operation produced the envelope) still compares.
+ *
+ * Note: deterministic-but-golden-absent infra meta keys (`specVersion`,
+ * `transport`, …) are NOT stripped here — they are tolerated by the SUBSET compare
+ * in {@link diffEnvelopes} instead, so the strip set stays exactly the volatile
+ * fields and nothing semantic.
+ *
+ * @param envelope - The replayed envelope to normalize.
+ * @returns The normalized envelope with volatile meta fields removed.
+ *
+ * @example
+ * ```ts
+ * const norm = normalizeEnvelope(envelope);
+ * // norm.meta has no timestamp / requestId / duration_ms / *SessionId
+ * ```
+ */
+export function normalizeEnvelope(envelope) {
+    const cloned = jsonClone(envelope);
+    for (const containerKey of META_CONTAINER_KEYS) {
+        const container = cloned[containerKey];
+        if (container !== null && typeof container === 'object' && !Array.isArray(container)) {
+            const meta = container;
+            for (const field of VOLATILE_META_FIELDS) {
+                delete meta[field];
+            }
+        }
+    }
+    return cloned;
+}
+/**
+ * Recursively collect structural differences between two JSON values.
+ *
+ * Walks both trees in parallel, recording a `{ path, actual, expected }` for each
+ * leaf-level divergence. Object key sets and array lengths are compared; the path
+ * uses `/`-delimited segments.
+ *
+ * Key-set semantics depend on the container:
+ *   - **Subset** (`subset === true`): only the EXPECTED (golden) object's keys are
+ *     compared. Extra keys present in `actual` but absent from the golden are
+ *     ignored. Applied to the `meta` container (see {@link SUBSET_COMPARE_KEYS}) so
+ *     deterministic infra meta keys the runtime stamps but the golden omits are not
+ *     phantom regressions.
+ *   - **Full union** (`subset === false`, the default): keys from BOTH objects are
+ *     compared, so an extra OR missing key is a regression. Applied to the semantic
+ *     payload (`data`/`error`).
+ *
+ * A child whose top-level key is in {@link SUBSET_COMPARE_KEYS} (i.e. `meta`)
+ * switches its subtree into subset mode.
+ *
+ * @param actual - The actual (normalized replay) value.
+ * @param expected - The expected (golden) value.
+ * @param path - Accumulated path prefix.
+ * @param out - Mutable accumulator of `{ path, actual, expected }` tuples.
+ * @param subset - When `true`, compare only the golden-declared keys at this node.
+ */
+function collectStructuralDiffs(actual, expected, path, out, subset = false) {
+    if (actual === expected)
+        return;
+    const bothObjects = actual !== null &&
+        expected !== null &&
+        typeof actual === 'object' &&
+        typeof expected === 'object' &&
+        Array.isArray(actual) === Array.isArray(expected);
+    if (!bothObjects) {
+        out.push({ path, actual, expected });
+        return;
+    }
+    const actualRec = actual;
+    const expectedRec = expected;
+    // Subset mode (meta container): compare ONLY the golden's keys, so extra
+    // deterministic runtime meta keys are not regressions. Full mode: union both
+    // key sets, so an extra OR missing payload key IS a regression.
+    const keys = subset
+        ? new Set(Object.keys(expectedRec))
+        : new Set([...Object.keys(actualRec), ...Object.keys(expectedRec)]);
+    for (const key of keys) {
+        const childPath = path === '' ? key : `${path}/${key}`;
+        // A `meta`/`_meta` container's subtree is compared as a subset; never widen
+        // back to full-union once inside a subset container.
+        const childSubset = subset || SUBSET_COMPARE_KEYS.has(key);
+        collectStructuralDiffs(actualRec[key], expectedRec[key], childPath, out, childSubset);
+    }
+}
+/**
+ * Diff a set of replayed envelopes against the golden envelope set.
+ *
+ * Normalizes each replayed envelope (volatile meta stripped) and structurally
+ * compares it against the positionally-aligned golden entry. The op coordinate
+ * for each `DiffEntry` is taken from `ops[opIndex]`. Callers MUST pass aligned
+ * arrays (`ops.length === replayed.length === golden.length`); the function
+ * diffs up to the shortest length and reports an extra regression for any length
+ * mismatch.
+ *
+ * The `meta` container is compared as a SUBSET (only golden-declared meta keys are
+ * asserted) so deterministic-but-golden-absent infra keys the runtime stamps
+ * (`specVersion`, `transport`, …) are not phantom regressions; the semantic
+ * payload (`data`/`error`) keeps a full key-union compare where an extra or
+ * missing key IS a regression. Together with the volatile-lineage strip in
+ * {@link normalizeEnvelope}, a real live envelope that matches the golden body
+ * yields ZERO regressions.
+ *
+ * @param ops - The scenario ops (for op-coordinate labelling).
+ * @param replayed - The captured envelopes, one per op (replay order).
+ * @param golden - The golden expected entries, positionally aligned with `ops`.
+ * @returns `{ regressions }` — empty when the replay matches the golden.
+ *
+ * @example
+ * ```ts
+ * const { regressions } = diffEnvelopes(scenario.ops, replayed, golden.envelopes);
+ * if (regressions.length === 0) { /* happy path — no DHQ, no PR *\/ }
+ * ```
+ */
+export function diffEnvelopes(ops, replayed, golden) {
+    const regressions = [];
+    const n = Math.min(ops.length, replayed.length, golden.length);
+    for (let i = 0; i < n; i++) {
+        const op = ops[i];
+        const replayEnvelope = replayed[i];
+        const goldenEntry = golden[i];
+        if (op === undefined || replayEnvelope === undefined || goldenEntry === undefined)
+            continue;
+        const opCoord = `${op.domain}.${op.operation}`;
+        const normalized = normalizeEnvelope(replayEnvelope);
+        const leafDiffs = [];
+        collectStructuralDiffs(normalized, goldenEntry, '', leafDiffs);
+        for (const d of leafDiffs) {
+            regressions.push({
+                opIndex: i,
+                opCoord,
+                path: d.path,
+                actual: d.actual,
+                expected: d.expected,
+            });
+        }
+    }
+    if (replayed.length !== golden.length) {
+        regressions.push({
+            opIndex: -1,
+            opCoord: '<count>',
+            path: 'envelopes/length',
+            actual: replayed.length,
+            expected: golden.length,
+        });
+    }
+    return { regressions };
+}
+/**
+ * Extract a targeted field from a normalized envelope's `data` payload.
+ *
+ * Reuses the LAFS `--field` extractor (`extractFieldFromResult`) for cases where
+ * a full structural diff is too brittle and only a specific field's value matters
+ * (e.g. assert `data.tasks[0].id` without comparing the whole envelope).
+ *
+ * @param normalized - A normalized envelope (from {@link normalizeEnvelope}).
+ * @param field - The field name to extract from the envelope's `data` payload.
+ * @returns The extracted value, or `undefined` when absent.
+ *
+ * @example
+ * ```ts
+ * const id = extractTargetedField(normalizeEnvelope(env), 'id');
+ * ```
+ */
+export function extractTargetedField(normalized, field) {
+    const data = normalized.data;
+    if (data === undefined || data === null)
+        return undefined;
+    // The LAFS extractor operates on a result value (object | array | null); the
+    // dispatch envelope's `data` is the equivalent payload.
+    if (typeof data !== 'object')
+        return undefined;
+    return extractFieldFromResult(data, field);
+}
+/**
+ * Build the deterministic regression signature for a diff result.
+ *
+ * The signature is the SORTED set of `{ opCoord, path }` pairs from the
+ * regressions — NOT the values. Two runs that diverge at the same op coordinates
+ * on the same paths produce the same signature (and thus the same
+ * {@link computeQuestionHash}), so a repeated regression maps to ONE open DHQ row
+ * rather than spamming duplicates. Actual/expected values are intentionally
+ * excluded so transient value noise does not fork the hash.
+ *
+ * @param regressions - The diff regressions.
+ * @returns A stable, sorted signature string.
+ */
+function regressionSignature(regressions) {
+    const pairs = regressions.map((r) => `${r.opCoord}@${r.path}`);
+    pairs.sort();
+    return pairs.join('\n');
+}
+/**
+ * Compute the sha256 `question_hash` of a diff result's normalized signature.
+ *
+ * The hash is over the {@link regressionSignature} (op coordinates + diff path
+ * set), so it is stable across runs of the SAME regression and feeds the
+ * idempotency partial-UNIQUE index (`ux_selfimprove_dhq_open`, T11889-A): one
+ * open DHQ row per `question_hash`. An empty regression set hashes the empty
+ * signature deterministically (callers should not persist on the happy path).
+ *
+ * @param result - The diff result whose regressions are hashed.
+ * @returns The lowercase hex sha256 of the regression signature.
+ *
+ * @example
+ * ```ts
+ * const hash = computeQuestionHash(diffEnvelopes(ops, replayed, golden));
+ * ```
+ */
+export function computeQuestionHash(result) {
+    const signature = regressionSignature(result.regressions);
+    return createHash('sha256').update(signature, 'utf-8').digest('hex');
+}
+//# sourceMappingURL=envelope-diff.js.map

package/dist/selfimprove/envelope-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-diff.js","sourceRoot":"","sources":["../../src/selfimprove/envelope-diff.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/replay.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Self-improvement scenario replay via an injected dispatch port (T11889-B).
+ *
+ * `replayScenario` replays a scenario's ordered ops through an injected
+ * {@link ReplayDispatch} port — it captures ONE LAFS envelope per op. CORE owns
+ * the PORT TYPE only; the real adapter (a thin closure over the cleo-resident
+ * `Dispatcher`) is supplied by `packages/cleo` at the call site (dependency
+ * inversion — `core` MUST NOT import the cleo dispatcher, and `dispatchFromCore`
+ * does not exist; see the P5 self-improvement spec §B.0.1).
+ *
+ * This module is PURE — no DB, no native handle, no `cleo` mutation. Tests inject
+ * a mocked `ReplayDispatch`. Import-time side-effect-free: the logger is resolved
+ * lazily on first use.
+ *
+ * Read-only guarantee: in the in-process fallback (no VM isolation) a `mutate` op
+ * could touch a live handle, so {@link replayScenario} HARD-REJECTS any
+ * `gateway:'mutate'` op when `allowMutate` is not explicitly set, throwing
+ * {@link MutateInFallbackError} (code `E_SELFIMPROVE_MUTATE_IN_FALLBACK`). The
+ * canned dogfood scenario is `query`-only, so the default replay never mutates.
+ *
+ * @module @cleocode/core/selfimprove/replay
+ * @epic T11889
+ * @task T11912
+ */
+import type { DispatchResponse } from '@cleocode/contracts/gateway';
+import type { Scenario, ScenarioOp } from './scenario.js';
+/**
+ * The captured envelope shape per replayed op.
+ *
+ * This is the canonical {@link DispatchResponse} the cleo-side `Dispatcher`
+ * returns (a `meta` block + `success` + optional `data`/`error`/`page`/`partial`).
+ * The diff layer (see {@link "./envelope-diff.js"}) normalizes this by stripping
+ * the volatile `meta` fields before comparing against the golden.
+ */
+export type ReplayEnvelope = DispatchResponse;
+/**
+ * Narrow dispatch port the replay engine calls — CORE owns this TYPE, NOT the impl.
+ *
+ * The cleo dispatch handler supplies the concrete adapter by closing over its
+ * already-instantiated `Dispatcher` (`dispatcher.dispatch({ gateway, domain,
+ * operation, params, source, requestId })`, where `source` is a valid
+ * `GatewaySource` — e.g. `'rpc'`) and returning the resulting envelope. Injecting
+ * the port keeps the engine + diff + budget logic
+ * in `core` while the dispatcher binding lives in `cleo` (CORE-first, no
+ * package-boundary inversion).
+ */
+/**
+ * The dispatch coordinate handed to a {@link ReplayDispatch} port for one op.
+ */
+export interface ReplayDispatchOp {
+    /** CQRS gateway. */
+    gateway: ScenarioOp['gateway'];
+    /** Registered domain handler key (plural, e.g. `'tasks'`). */
+    domain: string;
+    /** Operation name within the domain. */
+    operation: string;
+    /** Optional operation parameters. */
+    params?: Record<string, unknown>;
+}
+/**
+ * Dispatch a single op and return its captured envelope.
+ *
+ * @param op - The dispatch coordinate (gateway, domain, operation, params).
+ * @returns The captured {@link ReplayEnvelope}.
+ */
+export type ReplayDispatch = (op: ReplayDispatchOp) => Promise<ReplayEnvelope>;
+/** Options controlling a replay run. */
+export interface ReplayOptions {
+    /**
+     * When `true`, permit `gateway:'mutate'` ops (VM-isolated execution path).
+     *
+     * Defaults to `false`: in the in-process fallback there is no VM boundary, so a
+     * mutate op is HARD-REJECTED with {@link MutateInFallbackError}. The canned
+     * dogfood scenario is `query`-only and never sets this.
+     *
+     * @defaultValue false
+     */
+    allowMutate?: boolean;
+}
+/**
+ * Thrown when a `gateway:'mutate'` op is replayed without `allowMutate`.
+ *
+ * In the in-process fallback the replay runs in the host process, which DOES hold
+ * live-DB handles; a mutate op there could corrupt a live `tasks.db`/`brain.db`
+ * (the T5158 vector). The hard guard ensures no mutate path can fire without an
+ * explicit VM-isolation opt-in.
+ */
+export declare class MutateInFallbackError extends Error {
+    /** Stable machine-readable error code. */
+    readonly code: "E_SELFIMPROVE_MUTATE_IN_FALLBACK";
+    /** The op coordinate (`domain.operation`) that was rejected. */
+    readonly opCoord: string;
+    /**
+     * @param op - The rejected mutate op.
+     */
+    constructor(op: ScenarioOp);
+}
+/**
+ * Replay a scenario's ordered ops through the injected dispatch port.
+ *
+ * Captures ONE envelope per op, in op order. Read-only by default: every
+ * `gateway:'mutate'` op is HARD-REJECTED with {@link MutateInFallbackError}
+ * unless `options.allowMutate` is set (the VM-isolation path).
+ *
+ * PURE — no DB, no mutation. The `dispatch` port is the only external dependency;
+ * tests inject a mock.
+ *
+ * @param scenario - The validated scenario whose ops are replayed.
+ * @param dispatch - The injected dispatch port (cleo supplies the real adapter).
+ * @param options - Replay options; see {@link ReplayOptions}.
+ * @returns The captured envelopes, one per op, in scenario order.
+ * @throws {@link MutateInFallbackError} On a `mutate` op without `allowMutate`.
+ *
+ * @example
+ * ```ts
+ * const envelopes = await replayScenario(scenario, dispatch);
+ * // envelopes.length === scenario.ops.length
+ * ```
+ */
+export declare function replayScenario(scenario: Scenario, dispatch: ReplayDispatch, options?: ReplayOptions): Promise<ReplayEnvelope[]>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/selfimprove/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/selfimprove/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAE9C;;;;;;;;;;GAUG;AACH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oBAAoB;IACpB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IAC/B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,gBAAgB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAE/E,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,0CAA0C;IAC1C,SAAgB,IAAI,EAAG,kCAAkC,CAAU;IAEnE,gEAAgE;IAChE,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEhC;;OAEG;gBACS,EAAE,EAAE,UAAU;CAS3B;AAuBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,cAAc,EAAE,CAAC,CAwB3B"}