@deftai/directive-core 0.70.0 → 0.71.1

package/dist/eval/report.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolveEvalPath } from "../layout/resolve.js";
+import { GOLDEN_RUNS_HISTORY_REL } from "./run.js";
+export const REPORT_SCHEMA_VERSION = 1;
+function readGoldenRuns(projectRoot) {
+    const path = resolveEvalPath(projectRoot, GOLDEN_RUNS_HISTORY_REL);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const lines = readFileSync(path, "utf8")
+        .split("\n")
+        .filter((line) => line.trim().length > 0);
+    const records = [];
+    for (const line of lines) {
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            // Skip malformed ledger rows.
+        }
+    }
+    return records;
+}
+/** Pick the latest run for a directive version and model. */
+export function findLatestGoldenRun(records, directiveVersion, model) {
+    const matches = records.filter((r) => r.directiveVersion === directiveVersion && r.model === model);
+    if (matches.length === 0) {
+        return null;
+    }
+    return matches.reduce((latest, current) => current.recordedAt >= latest.recordedAt ? current : latest);
+}
+function countPasses(results) {
+    return {
+        passed: results.filter((r) => r.passed).length,
+        total: results.length,
+    };
+}
+/** Two-proportion z-test (normal approximation). */
+export function twoProportionZTest(passedA, totalA, passedB, totalB) {
+    if (totalA === 0 || totalB === 0) {
+        return { zScore: null, pValue: null };
+    }
+    const p1 = passedA / totalA;
+    const p2 = passedB / totalB;
+    const pooled = (passedA + passedB) / (totalA + totalB);
+    const se = Math.sqrt(pooled * (1 - pooled) * (1 / totalA + 1 / totalB));
+    if (se === 0) {
+        return { zScore: null, pValue: null };
+    }
+    const z = (p2 - p1) / se;
+    const pValue = 2 * (1 - normalCdf(Math.abs(z)));
+    return { zScore: z, pValue };
+}
+function normalCdf(x) {
+    return 0.5 * (1 + erf(x / Math.SQRT2));
+}
+function erf(x) {
+    const sign = x < 0 ? -1 : 1;
+    const ax = Math.abs(x);
+    const t = 1 / (1 + 0.3275911 * ax);
+    const y = 1 -
+        ((((1.061405429 * t - 1.453152027) * t + 1.421413741) * t - 0.284496736) * t + 0.254829592) *
+            t *
+            Math.exp(-ax * ax);
+    return sign * y;
+}
+function metricDelta(metric, championRate, challengerRate, championPassed, championTotal, challengerPassed, challengerTotal) {
+    const { zScore, pValue } = twoProportionZTest(championPassed, championTotal, challengerPassed, challengerTotal);
+    return {
+        metric,
+        champion: championRate,
+        challenger: challengerRate,
+        delta: challengerRate - championRate,
+        zScore,
+        pValue,
+        significantAt05: pValue !== null && pValue < 0.05,
+    };
+}
+/** Detect holdout tripwire: primary improves while holdout regresses (#1703). */
+export function evaluateHoldoutTripwire(champion, challenger) {
+    const primaryDelta = challenger.summary.primaryPassRate - champion.summary.primaryPassRate;
+    const holdoutDelta = challenger.summary.holdoutPassRate - champion.summary.holdoutPassRate;
+    const triggered = primaryDelta > 0.05 && holdoutDelta < -0.05;
+    const summary = triggered
+        ? "Holdout tripwire: challenger improved primary metrics but holdout regressed -- possible tuning to gated corpus."
+        : "Holdout tripwire clear.";
+    return { triggered, summary, primaryDelta, holdoutDelta };
+}
+function formatPercent(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+/** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
+export function reportGoldenEval(options) {
+    if (!options.championVersion.trim() || !options.challengerVersion.trim()) {
+        return {
+            code: 2,
+            report: null,
+            message: "eval:report: --champion and --challenger are required",
+        };
+    }
+    if (!options.model.trim()) {
+        return { code: 2, report: null, message: "eval:report: --model is required" };
+    }
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const records = readGoldenRuns(projectRoot);
+    const champion = findLatestGoldenRun(records, options.championVersion, options.model);
+    const challenger = findLatestGoldenRun(records, options.challengerVersion, options.model);
+    if (champion === null) {
+        return {
+            code: 1,
+            report: null,
+            message: `eval:report: no golden run found for champion v${options.championVersion} model=${options.model}`,
+        };
+    }
+    if (challenger === null) {
+        return {
+            code: 1,
+            report: null,
+            message: `eval:report: no golden run found for challenger v${options.challengerVersion} model=${options.model}`,
+        };
+    }
+    const championPrimary = champion.results.filter((r) => !r.holdout);
+    const challengerPrimary = challenger.results.filter((r) => !r.holdout);
+    const championHoldout = champion.results.filter((r) => r.holdout);
+    const challengerHoldout = challenger.results.filter((r) => r.holdout);
+    const championPrimaryCount = countPasses(championPrimary);
+    const challengerPrimaryCount = countPasses(challengerPrimary);
+    const championHoldoutCount = countPasses(championHoldout);
+    const challengerHoldoutCount = countPasses(challengerHoldout);
+    const deltas = [
+        metricDelta("primaryPassRate", champion.summary.primaryPassRate, challenger.summary.primaryPassRate, championPrimaryCount.passed, championPrimaryCount.total, challengerPrimaryCount.passed, challengerPrimaryCount.total),
+        metricDelta("holdoutPassRate", champion.summary.holdoutPassRate, challenger.summary.holdoutPassRate, championHoldoutCount.passed, championHoldoutCount.total, challengerHoldoutCount.passed, challengerHoldoutCount.total),
+        metricDelta("overallPassRate", champion.summary.passRate, challenger.summary.passRate, countPasses(champion.results).passed, countPasses(champion.results).total, countPasses(challenger.results).passed, countPasses(challenger.results).total),
+    ];
+    const holdoutTripwire = evaluateHoldoutTripwire(champion, challenger);
+    const report = {
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        championVersion: options.championVersion,
+        challengerVersion: options.challengerVersion,
+        model: options.model,
+        championRunId: champion.runId,
+        challengerRunId: challenger.runId,
+        deltas,
+        holdoutTripwire,
+    };
+    const lines = [
+        `eval:report champion=v${options.championVersion} challenger=v${options.challengerVersion} model=${options.model}`,
+        ...deltas.map((d) => {
+            const sig = d.pValue === null
+                ? "n/a"
+                : d.significantAt05
+                    ? `p=${d.pValue.toFixed(4)} *`
+                    : `p=${d.pValue.toFixed(4)}`;
+            return `  ${d.metric}: ${formatPercent(d.champion)} -> ${formatPercent(d.challenger)} (delta ${(d.delta * 100).toFixed(1)}pp, ${sig})`;
+        }),
+        `  ${holdoutTripwire.summary}`,
+    ];
+    const code = holdoutTripwire.triggered ? 1 : 0;
+    return { code, report, message: lines.join("\n") };
+}
+//# sourceMappingURL=report.js.map

package/dist/eval/run.d.ts

@@ -0,0 +1,79 @@
+export declare const GOLDEN_RUNS_HISTORY_REL = "results/golden-runs.jsonl";
+export declare const GOLDEN_RUN_SCHEMA_VERSION: 1;
+export declare const GOLDEN_CORPUS_VERSION = "2026-07-05-tier2-fixture-v1";
+/** One synthetic golden-task definition with an objective grader. */
+export interface GoldenTaskDefinition {
+    readonly id: string;
+    readonly title: string;
+    readonly holdout: boolean;
+    readonly grade: (context: GoldenTaskContext) => GoldenTaskGrade;
+}
+/** Runtime context passed to golden-task graders. */
+export interface GoldenTaskContext {
+    readonly tempDir: string;
+    readonly seed: number;
+    readonly directiveVersion: string;
+    readonly model: string;
+}
+/** Objective grader output for a single task × seed. */
+export interface GoldenTaskGrade {
+    readonly passed: boolean;
+    readonly metrics: Readonly<Record<string, number | boolean>>;
+}
+/** One graded task outcome within a golden run. */
+export interface GoldenTaskResult {
+    readonly taskId: string;
+    readonly seed: number;
+    readonly passed: boolean;
+    readonly holdout: boolean;
+    readonly metrics: Readonly<Record<string, number | boolean>>;
+}
+/** Versioned golden-run record persisted to the `.eval` ledger (#1703 Tier 2). */
+export interface GoldenRunRecord {
+    readonly schemaVersion: typeof GOLDEN_RUN_SCHEMA_VERSION;
+    readonly runId: string;
+    readonly directiveVersion: string;
+    readonly model: string;
+    readonly harness: string;
+    readonly seeds: readonly number[];
+    readonly corpusVersion: string;
+    readonly recordedAt: string;
+    readonly results: readonly GoldenTaskResult[];
+    readonly summary: GoldenRunSummary;
+}
+/** Aggregate metrics for one golden run. */
+export interface GoldenRunSummary {
+    readonly primaryPassRate: number;
+    readonly holdoutPassRate: number;
+    readonly passRate: number;
+    readonly primaryTotal: number;
+    readonly holdoutTotal: number;
+}
+export interface RunGoldenEvalOptions {
+    readonly projectRoot?: string;
+    readonly model: string;
+    readonly seeds?: readonly number[];
+    readonly directiveVersion?: string;
+    readonly harness?: string;
+    readonly persist?: boolean;
+    readonly now?: () => Date;
+    readonly mkTempDir?: () => string;
+}
+export interface RunGoldenEvalResult {
+    readonly code: 0 | 1 | 2;
+    readonly record: GoldenRunRecord | null;
+    readonly message: string;
+}
+/** Fixed golden corpus with objective graders (#1703 Tier 2). */
+export declare const GOLDEN_CORPUS: readonly GoldenTaskDefinition[];
+/** Absolute path to the golden-run results ledger. */
+export declare function goldenRunsHistoryPath(projectRoot: string): string;
+/** Append one golden run to the versioned ledger (#1703 Tier 2). */
+export declare function persistGoldenRun(projectRoot: string, record: GoldenRunRecord): void;
+/** Stable hash for rotating holdout selection (#1703 Goodhart mitigation). */
+export declare function holdoutRotationIndex(directiveVersion: string, model: string, holdoutCount: number): number;
+/** Select the active holdout task for this version × model tuple. */
+export declare function selectRotatingHoldoutTask(directiveVersion: string, model: string): GoldenTaskDefinition | null;
+/** Execute the golden corpus for one model × seed set and optionally persist (#1703 Tier 2). */
+export declare function runGoldenEval(options: RunGoldenEvalOptions): RunGoldenEvalResult;
+//# sourceMappingURL=run.d.ts.map

package/dist/eval/run.js

@@ -0,0 +1,309 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { resolveEvalPath } from "../layout/resolve.js";
+import { BYTE_DIFF_WHOLE_FILE_THRESHOLD, InstrumentedVbriefCrud } from "./crud-telemetry.js";
+import { evaluateHealth } from "./health.js";
+export const GOLDEN_RUNS_HISTORY_REL = "results/golden-runs.jsonl";
+export const GOLDEN_RUN_SCHEMA_VERSION = 1;
+export const GOLDEN_CORPUS_VERSION = "2026-07-05-tier2-fixture-v1";
+const VALID_VBRIEF = `{
+  "vBRIEFInfo": { "version": "0.6", "description": "golden fixture" },
+  "plan": {
+    "id": "golden-fixture",
+    "title": "Golden fixture",
+    "status": "pending",
+    "narratives": { "Description": "Valid golden corpus document." },
+    "items": [
+      {
+        "id": "golden-a1",
+        "title": "Item",
+        "status": "pending",
+        "narrative": { "Acceptance": "Schema valid." }
+      }
+    ]
+  }
+}`;
+const INVENTED_KEY_VBRIEF = VALID_VBRIEF.replace('"items": [', '"agentInventedField": "bad",\n    "items": [');
+function passRate(results, holdout) {
+    const subset = results.filter((r) => r.holdout === holdout);
+    if (subset.length === 0) {
+        return 0;
+    }
+    return subset.filter((r) => r.passed).length / subset.length;
+}
+function summarizeResults(results) {
+    const primary = results.filter((r) => !r.holdout);
+    const holdout = results.filter((r) => r.holdout);
+    const primaryPassRate = passRate(results, false);
+    const holdoutPassRate = passRate(results, true);
+    return {
+        primaryPassRate,
+        holdoutPassRate,
+        passRate: results.length === 0 ? 0 : results.filter((r) => r.passed).length / results.length,
+        primaryTotal: primary.length,
+        holdoutTotal: holdout.length,
+    };
+}
+function gradeCrudValidCreate(context) {
+    const path = join(context.tempDir, "create.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    const result = crud.create(path, VALID_VBRIEF);
+    const metric = crud.getMetrics()[0];
+    return {
+        passed: result.ok && metric?.schemaValid === true,
+        metrics: {
+            schemaValid: metric?.schemaValid === true,
+            fieldInventionCount: metric?.fieldInventionCount ?? -1,
+        },
+    };
+}
+function gradeCrudRejectInvention(context) {
+    const path = join(context.tempDir, "invented.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, INVENTED_KEY_VBRIEF);
+    const metric = crud.getMetrics()[0];
+    const inventedKeys = metric?.inventedKeys.length ?? 0;
+    return {
+        passed: metric?.schemaValid === true && inventedKeys > 0 && (metric?.fieldInventionCount ?? 0) > 0,
+        metrics: {
+            detectedInvention: inventedKeys > 0,
+            fieldInventionCount: metric?.fieldInventionCount ?? -1,
+        },
+    };
+}
+function gradeCrudSurgicalUpdate(context) {
+    const path = join(context.tempDir, "update.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const updated = VALID_VBRIEF.replace('"pending"', '"running"');
+    crud.update(path, updated);
+    const updateMetric = crud.getMetrics().find((m) => m.operation === "update");
+    return {
+        passed: updateMetric?.schemaValid === true &&
+            updateMetric.byteDiffMinimality === "surgical" &&
+            (updateMetric.byteDiffChangedRatio ?? 1) < BYTE_DIFF_WHOLE_FILE_THRESHOLD,
+        metrics: {
+            schemaValid: updateMetric?.schemaValid === true,
+            byteDiffMinimalitySurgical: updateMetric?.byteDiffMinimality === "surgical",
+            changedRatio: updateMetric?.byteDiffChangedRatio ?? -1,
+        },
+    };
+}
+function seedHealthFixture(tempDir) {
+    writeFileSync(join(tempDir, "xbrief", "PROJECT-DEFINITION.xbrief.json"), JSON.stringify({
+        xBRIEFInfo: { version: "0.6" },
+        plan: {
+            title: "Golden health fixture",
+            status: "running",
+            items: [],
+            "x-directive/policy": { triageScope: [{ rule: "all-open" }] },
+        },
+    }), "utf8");
+    writeFileSync(join(tempDir, "AGENTS.md"), "<!-- deft:managed-section v3 -->\n<!-- /deft:managed-section -->\n", "utf8");
+}
+function gradeHealthFixture(context) {
+    seedHealthFixture(context.tempDir);
+    const health = evaluateHealth({
+        projectRoot: context.tempDir,
+        persist: false,
+        frameworkSource: false,
+    });
+    return {
+        passed: health.report !== null && typeof health.report.score === "number",
+        metrics: {
+            score: health.report?.score ?? -1,
+            gateCount: health.report?.gates.length ?? -1,
+        },
+    };
+}
+function gradeHoldoutSchemaRoundtrip(context) {
+    const path = join(context.tempDir, "roundtrip.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const read = crud.read(path);
+    const roundtripOk = read.ok && read.content === VALID_VBRIEF;
+    const noise = (context.seed % 997) / 997;
+    return {
+        passed: roundtripOk && noise < 0.99,
+        metrics: { roundtripOk, seedNoise: noise },
+    };
+}
+function gradeHoldoutByteDiffTripwire(context) {
+    const path = join(context.tempDir, "rewrite.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const rewritten = JSON.stringify(JSON.parse(VALID_VBRIEF), null, 2);
+    crud.update(path, rewritten);
+    const updateMetric = crud.getMetrics().find((m) => m.operation === "update");
+    const detectedRewrite = updateMetric?.byteDiffMinimality === "whole-file-rewrite";
+    const tripwire = (context.seed % 991) / 991;
+    return {
+        passed: detectedRewrite && tripwire < 0.99,
+        metrics: {
+            detectedRewrite,
+            tripwire,
+        },
+    };
+}
+/** Fixed golden corpus with objective graders (#1703 Tier 2). */
+export const GOLDEN_CORPUS = [
+    {
+        id: "crud-valid-create",
+        title: "Instrumented create accepts valid vBRIEF",
+        holdout: false,
+        grade: gradeCrudValidCreate,
+    },
+    {
+        id: "crud-reject-invention",
+        title: "Instrumented create rejects invented keys",
+        holdout: false,
+        grade: gradeCrudRejectInvention,
+    },
+    {
+        id: "crud-surgical-update",
+        title: "Instrumented update classifies surgical edits",
+        holdout: false,
+        grade: gradeCrudSurgicalUpdate,
+    },
+    {
+        id: "health-fixture-score",
+        title: "Tier-0 health eval runs on fixture repo",
+        holdout: false,
+        grade: gradeHealthFixture,
+    },
+    {
+        id: "holdout-schema-roundtrip",
+        title: "Holdout: read-after-create roundtrip",
+        holdout: true,
+        grade: gradeHoldoutSchemaRoundtrip,
+    },
+    {
+        id: "holdout-byte-diff-tripwire",
+        title: "Holdout: whole-file rewrite detection tripwire",
+        holdout: true,
+        grade: gradeHoldoutByteDiffTripwire,
+    },
+];
+/** Absolute path to the golden-run results ledger. */
+export function goldenRunsHistoryPath(projectRoot) {
+    return resolveEvalPath(projectRoot, GOLDEN_RUNS_HISTORY_REL);
+}
+/** Append one golden run to the versioned ledger (#1703 Tier 2). */
+export function persistGoldenRun(projectRoot, record) {
+    const path = goldenRunsHistoryPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+/** Stable hash for rotating holdout selection (#1703 Goodhart mitigation). */
+export function holdoutRotationIndex(directiveVersion, model, holdoutCount) {
+    if (holdoutCount <= 0) {
+        return 0;
+    }
+    const digest = createHash("sha256")
+        .update(`${directiveVersion}\0${model}\0${GOLDEN_CORPUS_VERSION}`)
+        .digest("hex");
+    return Number.parseInt(digest.slice(0, 8), 16) % holdoutCount;
+}
+/** Select the active holdout task for this version × model tuple. */
+export function selectRotatingHoldoutTask(directiveVersion, model) {
+    const holdouts = GOLDEN_CORPUS.filter((task) => task.holdout);
+    if (holdouts.length === 0) {
+        return null;
+    }
+    return holdouts[holdoutRotationIndex(directiveVersion, model, holdouts.length)] ?? null;
+}
+function seedTempDir(taskId, seed) {
+    const base = mkdtempSync(join(tmpdir(), `deft-golden-${taskId}-seed-${seed}-`));
+    mkdirSync(join(base, "xbrief"), { recursive: true });
+    return base;
+}
+function runIdFor(directiveVersion, model, harness, seeds) {
+    const digest = createHash("sha256")
+        .update(`${directiveVersion}\0${model}\0${harness}\0${seeds.join(",")}\0${GOLDEN_CORPUS_VERSION}`)
+        .digest("hex");
+    return digest.slice(0, 12);
+}
+/** Execute the golden corpus for one model × seed set and optionally persist (#1703 Tier 2). */
+export function runGoldenEval(options) {
+    if (!options.model.trim()) {
+        return { code: 2, record: null, message: "eval:run: --model is required" };
+    }
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const directiveVersion = options.directiveVersion ?? readCorePackageVersion();
+    const harness = options.harness ?? "deterministic-fixture";
+    const seeds = options.seeds ?? [1, 2, 3];
+    const now = options.now ?? (() => new Date());
+    const persist = options.persist ?? true;
+    if (seeds.length === 0) {
+        return { code: 2, record: null, message: "eval:run: at least one seed is required" };
+    }
+    const primaryTasks = GOLDEN_CORPUS.filter((task) => !task.holdout);
+    const rotatingHoldout = selectRotatingHoldoutTask(directiveVersion, options.model);
+    const tasksToRun = [...primaryTasks];
+    if (rotatingHoldout !== null) {
+        tasksToRun.push(rotatingHoldout);
+    }
+    const results = [];
+    const scratchDirs = [];
+    for (const task of tasksToRun) {
+        for (const seed of seeds) {
+            const tempDir = seedTempDir(task.id, seed);
+            scratchDirs.push(tempDir);
+            const grade = task.grade({
+                tempDir,
+                seed,
+                directiveVersion,
+                model: options.model,
+            });
+            results.push({
+                taskId: task.id,
+                seed,
+                passed: grade.passed,
+                holdout: task.holdout,
+                metrics: grade.metrics,
+            });
+        }
+    }
+    for (const dir of scratchDirs) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    const summary = summarizeResults(results);
+    const record = {
+        schemaVersion: GOLDEN_RUN_SCHEMA_VERSION,
+        runId: runIdFor(directiveVersion, options.model, harness, seeds),
+        directiveVersion,
+        model: options.model,
+        harness,
+        seeds,
+        corpusVersion: GOLDEN_CORPUS_VERSION,
+        recordedAt: now()
+            .toISOString()
+            .replace(/\.\d{3}Z$/, "Z"),
+        results,
+        summary,
+    };
+    if (persist) {
+        try {
+            persistGoldenRun(projectRoot, record);
+        }
+        catch (err) {
+            return {
+                code: 2,
+                record,
+                message: `eval:run: failed to persist golden run: ${String(err)}`,
+            };
+        }
+    }
+    const lines = [
+        `eval:run v${record.directiveVersion} model=${record.model} harness=${record.harness} seeds=[${record.seeds.join(",")}]`,
+        `  primary pass rate: ${(summary.primaryPassRate * 100).toFixed(1)}% (${summary.primaryTotal} trials)`,
+        `  holdout pass rate: ${(summary.holdoutPassRate * 100).toFixed(1)}% (${summary.holdoutTotal} trials)`,
+        `  rotating holdout task: ${rotatingHoldout?.id ?? "none"}`,
+        `  runId=${record.runId}`,
+    ];
+    return { code: 0, record, message: lines.join("\n") };
+}
+//# sourceMappingURL=run.js.map

package/dist/events/attribution-constants.d.ts

@@ -0,0 +1,13 @@
+/** Canonical behavioral event names for the attribution ledger (#1709). */
+export declare const ATTRIBUTION_EVENT_NAMES: {
+    readonly valueGateCatch: "value:gate-catch";
+    readonly valueWipCapProtect: "value:wip-cap-protect";
+    readonly bypassOffFlow: "bypass:off-flow";
+    readonly adoptionUnusedCapability: "adoption:unused-capability";
+    readonly frictionDirectiveGap: "friction:directive-gap";
+};
+export type AttributionEventName = (typeof ATTRIBUTION_EVENT_NAMES)[keyof typeof ATTRIBUTION_EVENT_NAMES];
+/** Required payload keys per attribution event (merged into lifecycle/events). */
+export declare const ATTRIBUTION_REQUIRED_PAYLOAD: Readonly<Record<string, readonly string[]>>;
+export declare const ALL_ATTRIBUTION_EVENT_NAMES: ("value:gate-catch" | "value:wip-cap-protect" | "bypass:off-flow" | "adoption:unused-capability" | "friction:directive-gap")[];
+//# sourceMappingURL=attribution-constants.d.ts.map

package/dist/events/attribution-constants.js

@@ -0,0 +1,18 @@
+/** Canonical behavioral event names for the attribution ledger (#1709). */
+export const ATTRIBUTION_EVENT_NAMES = {
+    valueGateCatch: "value:gate-catch",
+    valueWipCapProtect: "value:wip-cap-protect",
+    bypassOffFlow: "bypass:off-flow",
+    adoptionUnusedCapability: "adoption:unused-capability",
+    frictionDirectiveGap: "friction:directive-gap",
+};
+/** Required payload keys per attribution event (merged into lifecycle/events). */
+export const ATTRIBUTION_REQUIRED_PAYLOAD = {
+    [ATTRIBUTION_EVENT_NAMES.valueGateCatch]: ["signal_class", "source"],
+    [ATTRIBUTION_EVENT_NAMES.valueWipCapProtect]: ["signal_class", "source", "count", "cap"],
+    [ATTRIBUTION_EVENT_NAMES.bypassOffFlow]: ["signal_class", "source"],
+    [ATTRIBUTION_EVENT_NAMES.adoptionUnusedCapability]: ["signal_class", "source", "capability"],
+    [ATTRIBUTION_EVENT_NAMES.frictionDirectiveGap]: ["signal_class", "source"],
+};
+export const ALL_ATTRIBUTION_EVENT_NAMES = Object.values(ATTRIBUTION_EVENT_NAMES);
+//# sourceMappingURL=attribution-constants.js.map

package/dist/events/attribution-ledger.d.ts

@@ -0,0 +1,43 @@
+import { type BehavioralEventRecord } from "../lifecycle/events.js";
+import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+import { type AttributionEventName } from "./attribution-constants.js";
+export { ALL_ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_REQUIRED_PAYLOAD, type AttributionEventName, } from "./attribution-constants.js";
+/** Four value-attribution signal classes (#1709 RFC). */
+export type SignalClass = "value" | "bypass" | "adoption" | "friction";
+export interface EmitAttributionOptions {
+    readonly projectRoot: string;
+    readonly logPath?: string | null;
+    /** Test hook: skip disk policy read. */
+    readonly policyOverride?: ValueFeedbackResolved;
+}
+/**
+ * Append an attribution ledger entry when valueFeedback emitEvents is allowed.
+ * Returns null when gated OFF (no disk write).
+ */
+export declare function emitAttributionSignal(name: AttributionEventName, payload: Record<string, unknown>, options: EmitAttributionOptions): BehavioralEventRecord | null;
+/** Record a detection-bound gate catch (value class). */
+export declare function recordGateCatch(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a WIP-cap protect refusal (value class). */
+export declare function recordWipCapProtect(projectRoot: string, count: number, cap: number, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a bypass/off-flow signal. */
+export declare function recordBypassSignal(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record an adoption/unused-capability signal. */
+export declare function recordAdoptionSignal(projectRoot: string, capability: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a friction/directive-gap signal. */
+export declare function recordFrictionSignal(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+//# sourceMappingURL=attribution-ledger.d.ts.map