@cleocode/core 2026.6.12 → 2026.6.14

package/dist/selfimprove/draft-pr.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Draft-PR egress for the self-improvement loop (T11889 · T11889-C).
+ *
+ * On a detected regression the loop's ONLY outbound action is to open ONE DRAFT
+ * PR against the cleocode repo (ADR-065 — PRs target `main` via the Merge Queue;
+ * NEVER a direct push to `main`, NEVER an auto-merge, NEVER a publish). This module
+ * is the egress primitive, modeled on `propose-patch.ts` (the closest "agent
+ * proposes a fix PR" exemplar) with three self-dogfooding hardenings:
+ *
+ *   1. **`--draft` is ALWAYS appended** to `gh pr create` — the PR is never
+ *      ready-for-merge; a human reviews and undrafts it.
+ *   2. **Dry-run is the DEFAULT.** `openDraftPr` returns the planned `steps[]`
+ *      WITHOUT invoking git/gh unless `execute: true` is passed. So the loop is
+ *      side-effect-free at egress by default.
+ *   3. **Branch `feat/T11889-selfimprove-<scenario>-<ts>`** — a feature branch
+ *      (ADR-065); no main mutation path exists in this module.
+ *
+ * The live path wraps the git/gh shell-out in
+ * {@link "../sentient/skill-provenance.js".withProvenance}`('pr-generator', …)`
+ * (the established legal PR-cutting origin — the `SkillWriteOrigin` union is
+ * closed) and returns the `gh`-emitted PR URL so the caller can record it back
+ * into `selfimprove_dhq.pr_url` via the leased adapter.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/draft-pr
+ * @epic T11889
+ * @task T11913
+ */
+/**
+ * Pluggable command runner. Returns stdout as UTF-8 text or throws on non-zero
+ * exit. Production default wraps `child_process.execFileSync` with piped stdio.
+ */
+export type CommandRunner = (file: string, args: readonly string[]) => string;
+/** Failure codes from {@link openDraftPr}. */
+export type DraftPrErrorCode = 
+/** Patch file does not exist on disk. */
+'E_NOT_FOUND'
+/** Patch file exists but is empty. */
+ | 'E_PATCH_EMPTY'
+/** `gh` CLI missing / not authenticated. */
+ | 'E_GH_UNAVAILABLE'
+/** Shell-out failure during the live PR cut. */
+ | 'E_DRAFT_PR_FAILED';
+/** Args for {@link openDraftPr}. */
+export interface OpenDraftPrArgs {
+    /** The scenario name whose regression this PR addresses (branch slug). */
+    readonly scenario: string;
+    /** Path to a unified-diff file with the proposed fix. Resolved against {@link cwd}. */
+    readonly diffPath: string;
+    /** PR title. */
+    readonly title: string;
+    /** PR body markdown (the trailer is appended automatically). */
+    readonly body: string;
+    /**
+     * When `true`, actually cut the branch + open the draft PR. DEFAULT `false`
+     * (dry-run) — the loop is side-effect-free at egress unless `--execute` flows
+     * through to here.
+     *
+     * @defaultValue false
+     */
+    readonly execute?: boolean;
+    /** Working directory for path resolution + git ops. Defaults to {@link process.cwd}. */
+    readonly cwd?: string;
+    /** Injectable command runner (tests capture the shell-out). Defaults to {@link execFileSync}. */
+    readonly run?: CommandRunner;
+    /** Injectable timestamp source for the branch suffix (tests pin it). Defaults to now. */
+    readonly timestamp?: () => string;
+}
+/** Dry-run result — the planned steps, no side effects. */
+export interface DraftPrDryRun {
+    readonly kind: 'dry-run';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The planned shell steps; the `gh pr create` step includes `--draft`. */
+    readonly steps: readonly string[];
+}
+/** Live result — the opened draft PR. */
+export interface DraftPrOk {
+    readonly kind: 'ok';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The draft PR URL emitted by `gh pr create --draft`. */
+    readonly prUrl: string;
+}
+/** Failure result. */
+export interface DraftPrFailure {
+    readonly kind: 'error';
+    readonly code: DraftPrErrorCode;
+    readonly message: string;
+}
+/** Discriminated-union result of {@link openDraftPr}. */
+export type DraftPrResult = DraftPrDryRun | DraftPrOk | DraftPrFailure;
+/**
+ * Compute the feature branch name for a scenario's draft PR (ADR-065 feature
+ * branch — `feat/T11889-selfimprove-<scenario>-<ts>`). The timestamp is
+ * colon/dot-sanitized so it is a valid git ref.
+ *
+ * @param scenario - The scenario name.
+ * @param ts - The ISO timestamp string.
+ * @returns The branch name.
+ */
+export declare function draftPrBranchName(scenario: string, ts: string): string;
+/**
+ * Open ONE DRAFT PR carrying a proposed self-improvement fix.
+ *
+ * DRY-RUN by default ({@link OpenDraftPrArgs.execute} falsey): returns the planned
+ * `steps[]` (the `gh pr create` step ALWAYS carries `--draft`) WITHOUT touching
+ * git/gh — so the loop is egress-side-effect-free unless `--execute` is threaded
+ * through. The live path (`execute: true`) cuts the feature branch, applies the
+ * diff, commits, pushes the FEATURE branch (NEVER `main`), and runs
+ * `gh pr create --base main --head <branch> --draft`, returning the PR URL.
+ *
+ * NEVER pushes `main`, NEVER auto-merges, NEVER publishes — the only egress is a
+ * draft PR against a feature branch.
+ *
+ * @param args - See {@link OpenDraftPrArgs}.
+ * @returns A {@link DraftPrResult} describing the outcome.
+ *
+ * @example
+ * ```ts
+ * // dry-run (default): no side effects, steps include `--draft`
+ * const plan = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body });
+ * // live: cuts branch + opens draft PR
+ * const res = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body, execute: true });
+ * ```
+ */
+export declare function openDraftPr(args: OpenDraftPrArgs): Promise<DraftPrResult>;
+//# sourceMappingURL=draft-pr.d.ts.map

package/dist/selfimprove/draft-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-pr.d.ts","sourceRoot":"","sources":["../../src/selfimprove/draft-pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAM9E,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB;AAC1B,yCAAyC;AACvC,aAAa;AACf,sCAAsC;GACpC,eAAe;AACjB,4CAA4C;GAC1C,kBAAkB;AACpB,gDAAgD;GAC9C,mBAAmB,CAAC;AAExB,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CACnC;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sBAAsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAItE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAgF/E"}

package/dist/selfimprove/draft-pr.js

@@ -0,0 +1,158 @@
+/**
+ * Draft-PR egress for the self-improvement loop (T11889 · T11889-C).
+ *
+ * On a detected regression the loop's ONLY outbound action is to open ONE DRAFT
+ * PR against the cleocode repo (ADR-065 — PRs target `main` via the Merge Queue;
+ * NEVER a direct push to `main`, NEVER an auto-merge, NEVER a publish). This module
+ * is the egress primitive, modeled on `propose-patch.ts` (the closest "agent
+ * proposes a fix PR" exemplar) with three self-dogfooding hardenings:
+ *
+ *   1. **`--draft` is ALWAYS appended** to `gh pr create` — the PR is never
+ *      ready-for-merge; a human reviews and undrafts it.
+ *   2. **Dry-run is the DEFAULT.** `openDraftPr` returns the planned `steps[]`
+ *      WITHOUT invoking git/gh unless `execute: true` is passed. So the loop is
+ *      side-effect-free at egress by default.
+ *   3. **Branch `feat/T11889-selfimprove-<scenario>-<ts>`** — a feature branch
+ *      (ADR-065); no main mutation path exists in this module.
+ *
+ * The live path wraps the git/gh shell-out in
+ * {@link "../sentient/skill-provenance.js".withProvenance}`('pr-generator', …)`
+ * (the established legal PR-cutting origin — the `SkillWriteOrigin` union is
+ * closed) and returns the `gh`-emitted PR URL so the caller can record it back
+ * into `selfimprove_dhq.pr_url` via the leased adapter.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/draft-pr
+ * @epic T11889
+ * @task T11913
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { cwd as processCwd } from 'node:process';
+import { withProvenance } from '../sentient/skill-provenance.js';
+/**
+ * The required Claude Code trailer every self-improvement PR body ends with.
+ * Matches the project PR-body convention.
+ */
+const PR_BODY_TRAILER = '\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)';
+/** Default command runner — wraps `execFileSync` with stdout-piped semantics. */
+const defaultRun = (file, args) => execFileSync(file, [...args], { stdio: 'pipe' }).toString('utf8');
+/**
+ * Compute the feature branch name for a scenario's draft PR (ADR-065 feature
+ * branch — `feat/T11889-selfimprove-<scenario>-<ts>`). The timestamp is
+ * colon/dot-sanitized so it is a valid git ref.
+ *
+ * @param scenario - The scenario name.
+ * @param ts - The ISO timestamp string.
+ * @returns The branch name.
+ */
+export function draftPrBranchName(scenario, ts) {
+    const safeScenario = scenario.replace(/[^a-z0-9-]/gi, '-');
+    const safeTs = ts.replace(/[:.]/g, '-');
+    return `feat/T11889-selfimprove-${safeScenario}-${safeTs}`;
+}
+/**
+ * Open ONE DRAFT PR carrying a proposed self-improvement fix.
+ *
+ * DRY-RUN by default ({@link OpenDraftPrArgs.execute} falsey): returns the planned
+ * `steps[]` (the `gh pr create` step ALWAYS carries `--draft`) WITHOUT touching
+ * git/gh — so the loop is egress-side-effect-free unless `--execute` is threaded
+ * through. The live path (`execute: true`) cuts the feature branch, applies the
+ * diff, commits, pushes the FEATURE branch (NEVER `main`), and runs
+ * `gh pr create --base main --head <branch> --draft`, returning the PR URL.
+ *
+ * NEVER pushes `main`, NEVER auto-merges, NEVER publishes — the only egress is a
+ * draft PR against a feature branch.
+ *
+ * @param args - See {@link OpenDraftPrArgs}.
+ * @returns A {@link DraftPrResult} describing the outcome.
+ *
+ * @example
+ * ```ts
+ * // dry-run (default): no side effects, steps include `--draft`
+ * const plan = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body });
+ * // live: cuts branch + opens draft PR
+ * const res = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body, execute: true });
+ * ```
+ */
+export async function openDraftPr(args) {
+    const cwd = args.cwd ?? processCwd();
+    const run = args.run ?? defaultRun;
+    const execute = args.execute === true;
+    const isoNow = (args.timestamp ?? (() => new Date().toISOString()))();
+    const base = 'main';
+    const body = `${args.body}${PR_BODY_TRAILER}`;
+    const resolvedDiff = resolvePath(cwd, args.diffPath);
+    if (!existsSync(resolvedDiff)) {
+        return {
+            kind: 'error',
+            code: 'E_NOT_FOUND',
+            message: `Patch file not found at '${resolvedDiff}'`,
+        };
+    }
+    const diffBytes = readFileSync(resolvedDiff, 'utf8');
+    if (diffBytes.length === 0) {
+        return {
+            kind: 'error',
+            code: 'E_PATCH_EMPTY',
+            message: `Patch file '${resolvedDiff}' is empty`,
+        };
+    }
+    if (execute) {
+        try {
+            run('gh', ['--version']);
+        }
+        catch {
+            return {
+                kind: 'error',
+                code: 'E_GH_UNAVAILABLE',
+                message: 'gh CLI not found or not authenticated — install gh and run `gh auth login`',
+            };
+        }
+    }
+    const branchName = draftPrBranchName(args.scenario, isoNow);
+    const steps = [
+        `git checkout -b ${branchName}`,
+        `git apply ${resolvedDiff}`,
+        'git add -A',
+        `git commit -m "fix(selfimprove): ${args.scenario} regression"`,
+        `git push -u origin ${branchName}`,
+        `gh pr create --base ${base} --head ${branchName} --draft --title "${args.title}" --body <stdin>`,
+    ];
+    if (!execute) {
+        return { kind: 'dry-run', scenario: args.scenario, branchName, steps };
+    }
+    try {
+        const prUrl = await withProvenance('pr-generator', () => {
+            run('git', ['checkout', '-b', branchName]);
+            run('git', ['apply', resolvedDiff]);
+            run('git', ['add', '-A']);
+            run('git', ['commit', '-m', `fix(selfimprove): ${args.scenario} regression`]);
+            run('git', ['push', '-u', 'origin', branchName]);
+            return run('gh', [
+                'pr',
+                'create',
+                '--base',
+                base,
+                '--head',
+                branchName,
+                '--draft',
+                '--title',
+                args.title,
+                '--body',
+                body,
+            ]).trim();
+        });
+        return { kind: 'ok', scenario: args.scenario, branchName, prUrl };
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            code: 'E_DRAFT_PR_FAILED',
+            message: `draft-pr failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=draft-pr.js.map

package/dist/selfimprove/draft-pr.js.map

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

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"}