@deftai/directive-core 0.100.0 → 0.102.0

package/dist/run-summary/emit.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Fail-open run-summary JSONL emitter (#3282).
+ *
+ * Emission never changes exit codes, never throws to callers, and prints at
+ * most one warning when an *explicit* DEFT_RUN_SUMMARY_PATH write fails.
+ * Symlink destinations are refused (no-follow / containment) — fail-open.
+ */
+import { type ResolveRunSummaryDestinationOptions } from "./path.js";
+import { type AcceptanceRunSummaryPayload, type AcceptanceStampRunSummaryPayload, type CheckInvocationRunSummaryPayload, type DialEscalationEvaluationRunSummaryPayload, type DialTransitionRunSummaryPayload, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload, type ToolTurnDenominatorRunSummaryPayload, type VerificationRunSummaryPayload } from "./types.js";
+export interface RunSummaryEmitterOptions extends ResolveRunSummaryDestinationOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly frameworkVersion?: string;
+    /** Clock seam for tests. */
+    readonly now?: () => Date;
+    /** Destination override (tests). */
+    readonly destination?: RunSummaryDestination;
+    /** stdout/stderr seams (tests). */
+    readonly writeStdout?: (line: string) => void;
+    readonly writeStderr?: (line: string) => void;
+}
+export interface EmitRunSummaryResult {
+    readonly emitted: boolean;
+    readonly destination: RunSummaryDestination;
+    readonly line: RunSummaryLine | null;
+    readonly warning: boolean;
+}
+/**
+ * Stateful emitter: one instance per session tracks seq and write-warning once.
+ */
+export declare class RunSummaryEmitter {
+    private seq;
+    private warned;
+    private readonly projectRoot;
+    private readonly sessionId;
+    private readonly frameworkVersion;
+    private readonly now;
+    private readonly destination;
+    private readonly env;
+    private readonly writeStdout;
+    private readonly writeStderr;
+    constructor(options: RunSummaryEmitterOptions);
+    getDestination(): RunSummaryDestination;
+    emit(event: RunSummaryEventKind, payload: RunSummaryPayload): EmitRunSummaryResult;
+    emitSessionStart(payload: SessionStartRunSummaryPayload): EmitRunSummaryResult;
+    emitDialTransition(payload: DialTransitionRunSummaryPayload): EmitRunSummaryResult;
+    emitDialEscalationEvaluation(payload: DialEscalationEvaluationRunSummaryPayload): EmitRunSummaryResult;
+    emitCheckInvocation(payload: CheckInvocationRunSummaryPayload): EmitRunSummaryResult;
+    emitToolTurnDenominator(payload: ToolTurnDenominatorRunSummaryPayload): EmitRunSummaryResult;
+    emitVerification(payload: VerificationRunSummaryPayload): EmitRunSummaryResult;
+    emitAcceptance(payload: AcceptanceRunSummaryPayload): EmitRunSummaryResult;
+    emitAcceptanceStamp(payload: AcceptanceStampRunSummaryPayload): EmitRunSummaryResult;
+    /** Emit the harness-supplied denominator when DEFT_TOTAL_TOOL_TURNS is set. */
+    emitKnownToolTurnDenominator(): EmitRunSummaryResult;
+}
+/** Parse harness-supplied DEFT_TOTAL_TOOL_TURNS (integer > 0). Invalid/unset → omit. */
+export declare function readEnvToolTurnDenominator(env: NodeJS.ProcessEnv): number | undefined;
+/**
+ * One-shot helper for call sites that do not hold an emitter (e.g. dial escalate).
+ * Still fail-open; creates a fresh seq=1 emitter unless `seqSeed` is passed via reuse.
+ */
+export declare function emitRunSummaryEvent(options: RunSummaryEmitterOptions & {
+    readonly event: RunSummaryEventKind;
+    readonly payload: RunSummaryPayload;
+}): EmitRunSummaryResult;
+//# sourceMappingURL=emit.d.ts.map

package/dist/run-summary/emit.js

@@ -0,0 +1,217 @@
+/**
+ * Fail-open run-summary JSONL emitter (#3282).
+ *
+ * Emission never changes exit codes, never throws to callers, and prints at
+ * most one warning when an *explicit* DEFT_RUN_SUMMARY_PATH write fails.
+ * Symlink destinations are refused (no-follow / containment) — fail-open.
+ */
+import { mkdirSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { resolveRunSummaryDestination } from "./path.js";
+import { ENV_TOTAL_TOOL_TURNS, RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeysDeep);
+    }
+    if (value !== null && typeof value === "object") {
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortKeysDeep(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+function lineToJson(line) {
+    return JSON.stringify(sortKeysDeep(line));
+}
+function isNestedUnder(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+ * Post-write realpath check: refuse parent-component TOCTOU where a parent was
+ * replaced with a symlink between validation and open (#3282 Greptile residual).
+ */
+function assertRealpathStillContained(root, targetAbs) {
+    const realRoot = realpathSync(resolve(root));
+    const realTarget = realpathSync(targetAbs);
+    const prefix = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
+    if (realTarget !== realRoot && !realTarget.startsWith(prefix)) {
+        throw new Error(`run-summary write refused: realpath escaped containment (${realTarget} not under ${realRoot})`);
+    }
+    // Re-assert path components are not symlinks after the write.
+    assertWriteTargetSafe(realRoot, realTarget);
+}
+/**
+ * Append (or replace) a run-summary line with symlink refusal + containment.
+ * Mirrors lifecycle/events.ts appendEventLogLine (#2766 / #2951 / #3282 Greptile P1).
+ * Post-write realpath re-check closes parent-replacement TOCTOU window.
+ */
+function writeRunSummaryLine(projectRoot, targetPath, textLine, mode) {
+    const targetAbs = resolve(targetPath);
+    const data = `${textLine}\n`;
+    if (isNestedUnder(projectRoot, targetAbs)) {
+        const rootAbs = resolve(projectRoot);
+        assertWriteTargetSafe(rootAbs, targetAbs);
+        containedWrite({
+            root: rootAbs,
+            target: targetAbs,
+            data,
+            mode,
+        });
+        assertRealpathStillContained(rootAbs, targetAbs);
+        return;
+    }
+    // Explicit path outside project: contain under the log parent (no symlink follow).
+    const parent = dirname(targetAbs);
+    mkdirSync(parent, { recursive: true });
+    const parentAbs = resolve(parent);
+    assertWriteTargetSafe(parentAbs, targetAbs);
+    containedWrite({
+        root: parentAbs,
+        target: basename(targetAbs),
+        data,
+        mode,
+    });
+    assertRealpathStillContained(parentAbs, targetAbs);
+}
+/**
+ * Stateful emitter: one instance per session tracks seq and write-warning once.
+ */
+export class RunSummaryEmitter {
+    seq = 0;
+    warned = false;
+    projectRoot;
+    sessionId;
+    frameworkVersion;
+    now;
+    destination;
+    env;
+    writeStdout;
+    writeStderr;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.sessionId = options.sessionId;
+        this.frameworkVersion = options.frameworkVersion ?? readCorePackageVersion();
+        this.now = options.now ?? (() => new Date());
+        this.env = options.env ?? process.env;
+        this.destination =
+            options.destination ??
+                resolveRunSummaryDestination(options.projectRoot, {
+                    env: this.env,
+                    gitignoreCovers: options.gitignoreCovers,
+                });
+        this.writeStdout = options.writeStdout ?? ((line) => process.stdout.write(`${line}\n`));
+        this.writeStderr = options.writeStderr ?? ((line) => process.stderr.write(`${line}\n`));
+    }
+    getDestination() {
+        return this.destination;
+    }
+    emit(event, payload) {
+        try {
+            if (this.destination.kind === "silent") {
+                return { emitted: false, destination: this.destination, line: null, warning: false };
+            }
+            this.seq += 1;
+            const denominator = readPayloadToolTurnDenominator(payload) ?? readEnvToolTurnDenominator(this.env);
+            const line = {
+                schema_version: RUN_SUMMARY_SCHEMA_VERSION,
+                session_id: this.sessionId,
+                framework_version: this.frameworkVersion,
+                seq: this.seq,
+                ts: this.now().toISOString(),
+                event,
+                payload,
+                ...(denominator !== undefined ? { total_tool_turns: denominator } : {}),
+            };
+            const text = lineToJson(line);
+            if (this.destination.kind === "stdout") {
+                this.writeStdout(`${RUN_SUMMARY_STDOUT_PREFIX}${text}`);
+                return { emitted: true, destination: this.destination, line, warning: false };
+            }
+            // file destination — no-follow containment (#3282 Greptile P1 security)
+            const { path, truncateOnSessionStart, explicit } = this.destination;
+            try {
+                const mode = event === "session_start" && truncateOnSessionStart ? "replace" : "append";
+                writeRunSummaryLine(this.projectRoot, path, text, mode);
+                return { emitted: true, destination: this.destination, line, warning: false };
+            }
+            catch {
+                // Symlink / containment refusal and I/O both fail-open.
+                if (explicit && !this.warned) {
+                    this.warned = true;
+                    this.writeStderr(RUN_SUMMARY_WRITE_WARNING);
+                    return { emitted: false, destination: this.destination, line, warning: true };
+                }
+                return { emitted: false, destination: this.destination, line, warning: false };
+            }
+        }
+        catch {
+            return { emitted: false, destination: this.destination, line: null, warning: false };
+        }
+    }
+    emitSessionStart(payload) {
+        return this.emit("session_start", payload);
+    }
+    emitDialTransition(payload) {
+        return this.emit("dial_transition", payload);
+    }
+    emitDialEscalationEvaluation(payload) {
+        return this.emit("dial_escalation_evaluation", payload);
+    }
+    emitCheckInvocation(payload) {
+        return this.emit("check_invocation", payload);
+    }
+    emitToolTurnDenominator(payload) {
+        return this.emit("tool_turn_denominator", payload);
+    }
+    emitVerification(payload) {
+        return this.emit("verification", payload);
+    }
+    emitAcceptance(payload) {
+        return this.emit("acceptance", payload);
+    }
+    emitAcceptanceStamp(payload) {
+        return this.emit("acceptance_stamp", payload);
+    }
+    /** Emit the harness-supplied denominator when DEFT_TOTAL_TOOL_TURNS is set. */
+    emitKnownToolTurnDenominator() {
+        const n = readEnvToolTurnDenominator(this.env);
+        if (n === undefined) {
+            return { emitted: false, destination: this.destination, line: null, warning: false };
+        }
+        return this.emitToolTurnDenominator({ total_tool_turns: n });
+    }
+}
+function readPayloadToolTurnDenominator(payload) {
+    if (!("total_tool_turns" in payload)) {
+        return undefined;
+    }
+    const value = payload.total_tool_turns;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Parse harness-supplied DEFT_TOTAL_TOOL_TURNS (integer > 0). Invalid/unset → omit. */
+export function readEnvToolTurnDenominator(env) {
+    const raw = env[ENV_TOTAL_TOOL_TURNS];
+    if (raw === undefined || raw.trim().length === 0) {
+        return undefined;
+    }
+    const n = Number(raw.trim());
+    if (!Number.isInteger(n) || !Number.isFinite(n) || n <= 0) {
+        return undefined;
+    }
+    return n;
+}
+/**
+ * One-shot helper for call sites that do not hold an emitter (e.g. dial escalate).
+ * Still fail-open; creates a fresh seq=1 emitter unless `seqSeed` is passed via reuse.
+ */
+export function emitRunSummaryEvent(options) {
+    const emitter = new RunSummaryEmitter(options);
+    return emitter.emit(options.event, options.payload);
+}
+//# sourceMappingURL=emit.js.map

package/dist/run-summary/index.d.ts

@@ -0,0 +1,5 @@
+export { type EmitRunSummaryResult, emitRunSummaryEvent, RunSummaryEmitter, type RunSummaryEmitterOptions, } from "./emit.js";
+export { gitignoreCoversRunSummary, type ResolveRunSummaryDestinationOptions, resolveRunSummaryDestination, } from "./path.js";
+export { computeRitualGateShare, parseRunSummaryJsonl, type RitualGateShare, readToolTurnDenominator, } from "./share.js";
+export { type AcceptanceClauseOutcomeRow, type AcceptanceRunSummaryOutcome, type AcceptanceRunSummaryPayload, type AcceptanceStampRunSummaryPayload, type CheckGateOutcome, type CheckInvocationRunSummaryPayload, DEFAULT_RUN_SUMMARY_BASENAME, type DialEscalationEvaluationOutcome, type DialEscalationEvaluationRunSummaryPayload, type DialTransitionRunSummaryPayload, ENV_RUN_SUMMARY_PATH, ENV_TOTAL_TOOL_TURNS, RUN_SUMMARY_EVENT_KINDS, RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, type RunSummaryBaseFields, type RunSummaryDestination, type RunSummaryEventKind, type RunSummaryLine, type RunSummaryPayload, type SessionStartRunSummaryPayload, type ToolTurnDenominatorRunSummaryPayload, type VerificationOutcome, type VerificationRunSummaryPayload, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/run-summary/index.js

@@ -0,0 +1,5 @@
+export { emitRunSummaryEvent, RunSummaryEmitter, } from "./emit.js";
+export { gitignoreCoversRunSummary, resolveRunSummaryDestination, } from "./path.js";
+export { computeRitualGateShare, parseRunSummaryJsonl, readToolTurnDenominator, } from "./share.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, ENV_TOTAL_TOOL_TURNS, RUN_SUMMARY_EVENT_KINDS, RUN_SUMMARY_SCHEMA_VERSION, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/run-summary/path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { type RunSummaryDestination } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, ENV_TOTAL_TOOL_TURNS, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export declare function gitignoreCoversRunSummary(projectRoot: string, basename?: string): boolean;
+export interface ResolveRunSummaryDestinationOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Test seam for gitignore coverage. */
+    readonly gitignoreCovers?: (projectRoot: string) => boolean;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export declare function resolveRunSummaryDestination(projectRoot: string, options?: ResolveRunSummaryDestinationOptions): RunSummaryDestination;
+//# sourceMappingURL=path.d.ts.map

package/dist/run-summary/path.js

@@ -0,0 +1,78 @@
+/**
+ * Resolve where run-summary JSONL should go (#3282 emission matrix).
+ *
+ * - `DEFT_RUN_SUMMARY_PATH=<path>` → append JSONL there (explicit; warn once on write fail)
+ * - `DEFT_RUN_SUMMARY_PATH=-` → stdout lines prefixed `DEFT-TLM:`
+ * - unset → repo-root `.deft-run-summary.json` only when .gitignore covers it; else silent
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, } from "./types.js";
+export { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH, ENV_TOTAL_TOOL_TURNS, RUN_SUMMARY_STDOUT_PREFIX, RUN_SUMMARY_WRITE_WARNING, } from "./types.js";
+/**
+ * True when a .gitignore line covers the default run-summary basename.
+ * Matches exact line or trailing slash variants; ignores comments.
+ */
+export function gitignoreCoversRunSummary(projectRoot, basename = DEFAULT_RUN_SUMMARY_BASENAME) {
+    const giPath = join(projectRoot, ".gitignore");
+    if (!existsSync(giPath)) {
+        return false;
+    }
+    let text;
+    try {
+        text = readFileSync(giPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const targets = new Set([basename, basename.replace(/^\.\//, "")]);
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        // Strip trailing inline comments carefully (space + #).
+        const bare = line.replace(/\s+#.*$/, "").trim();
+        if (targets.has(bare) || targets.has(bare.replace(/^\//, ""))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Resolve emission destination for the run-summary matrix (#3282).
+ * Never throws — fail-open consumers treat resolution errors as silent.
+ */
+export function resolveRunSummaryDestination(projectRoot, options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const raw = env[ENV_RUN_SUMMARY_PATH];
+        if (raw !== undefined && raw.trim() === "-") {
+            return { kind: "stdout" };
+        }
+        if (raw !== undefined && raw.trim().length > 0) {
+            const trimmed = raw.trim();
+            const path = isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+            return {
+                kind: "file",
+                path,
+                truncateOnSessionStart: false,
+                explicit: true,
+            };
+        }
+        // Unset: default path only with gitignore coverage.
+        const covers = options.gitignoreCovers?.(projectRoot) ?? gitignoreCoversRunSummary(projectRoot);
+        if (!covers) {
+            return { kind: "silent" };
+        }
+        return {
+            kind: "file",
+            path: resolve(projectRoot, DEFAULT_RUN_SUMMARY_BASENAME),
+            truncateOnSessionStart: true,
+            explicit: false,
+        };
+    }
+    catch {
+        return { kind: "silent" };
+    }
+}
+//# sourceMappingURL=path.js.map

package/dist/run-summary/share.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Ritual+gate share from a #3282 run-summary stream (#3320).
+ *
+ * Share is ritual+gate invocations over the emitted tool/turn denominator.
+ * Absence of the denominator is unevaluable — never invent a share from counts.
+ */
+import { type RunSummaryLine } from "./types.js";
+export interface RitualGateShare {
+    readonly evaluable: boolean;
+    readonly ritualGateCount: number;
+    readonly totalToolTurns: number | null;
+    readonly share: number | null;
+}
+/** True when n is a finite integer usable as a share denominator. */
+export declare function isValidToolTurnDenominator(value: unknown): value is number;
+/** Read total_tool_turns from a line (top-level field or payload). */
+export declare function readToolTurnDenominator(line: unknown): number | undefined;
+/** Parse JSONL (or DEFT-TLM: prefixed stdout capture) into run-summary lines. */
+export declare function parseRunSummaryJsonl(text: string): RunSummaryLine[];
+/**
+ * Compute ritual+gate share from summary lines alone.
+ * Uses the latest session in the stream. Missing/invalid denominator → unevaluable.
+ */
+export declare function computeRitualGateShare(lines: readonly RunSummaryLine[]): RitualGateShare;
+//# sourceMappingURL=share.d.ts.map

package/dist/run-summary/share.js

@@ -0,0 +1,106 @@
+/**
+ * Ritual+gate share from a #3282 run-summary stream (#3320).
+ *
+ * Share is ritual+gate invocations over the emitted tool/turn denominator.
+ * Absence of the denominator is unevaluable — never invent a share from counts.
+ */
+import { RUN_SUMMARY_STDOUT_PREFIX } from "./types.js";
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+/** True when n is a finite integer usable as a share denominator. */
+export function isValidToolTurnDenominator(value) {
+    return (typeof value === "number" && Number.isInteger(value) && Number.isFinite(value) && value > 0);
+}
+/** Read total_tool_turns from a line (top-level field or payload). */
+export function readToolTurnDenominator(line) {
+    const rec = asRecord(line);
+    if (rec === null) {
+        return undefined;
+    }
+    if (isValidToolTurnDenominator(rec.total_tool_turns)) {
+        return rec.total_tool_turns;
+    }
+    const payload = asRecord(rec.payload);
+    if (payload !== null && isValidToolTurnDenominator(payload.total_tool_turns)) {
+        return payload.total_tool_turns;
+    }
+    return undefined;
+}
+function parseLine(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const body = trimmed.startsWith(RUN_SUMMARY_STDOUT_PREFIX)
+        ? trimmed.slice(RUN_SUMMARY_STDOUT_PREFIX.length)
+        : trimmed;
+    try {
+        const parsed = JSON.parse(body);
+        const rec = asRecord(parsed);
+        if (rec === null) {
+            return null;
+        }
+        if (typeof rec.event !== "string" || typeof rec.session_id !== "string") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse JSONL (or DEFT-TLM: prefixed stdout capture) into run-summary lines. */
+export function parseRunSummaryJsonl(text) {
+    const lines = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const line = parseLine(raw);
+        if (line !== null) {
+            lines.push(line);
+        }
+    }
+    return lines;
+}
+function lastSessionId(lines) {
+    let lastStart = null;
+    let lastAny = null;
+    for (const line of lines) {
+        lastAny = line.session_id;
+        if (line.event === "session_start") {
+            lastStart = line.session_id;
+        }
+    }
+    return lastStart ?? lastAny;
+}
+/**
+ * Compute ritual+gate share from summary lines alone.
+ * Uses the latest session in the stream. Missing/invalid denominator → unevaluable.
+ */
+export function computeRitualGateShare(lines) {
+    const sessionId = lastSessionId(lines);
+    const sessionLines = sessionId === null ? [] : lines.filter((line) => line.session_id === sessionId);
+    let ritualGateCount = 0;
+    let totalToolTurns = null;
+    for (const line of sessionLines) {
+        if (line.event === "check_invocation") {
+            ritualGateCount += 1;
+        }
+        const denom = readToolTurnDenominator(line);
+        if (denom !== undefined) {
+            totalToolTurns = denom;
+        }
+    }
+    if (totalToolTurns === null) {
+        return { evaluable: false, ritualGateCount, totalToolTurns: null, share: null };
+    }
+    return {
+        evaluable: true,
+        ritualGateCount,
+        totalToolTurns,
+        share: ritualGateCount / totalToolTurns,
+    };
+}
+//# sourceMappingURL=share.js.map

package/dist/run-summary/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export declare const RUN_SUMMARY_SCHEMA_VERSION: 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Harness-supplied session tool/turn total stamped onto run-summary lines (#3320). */
+export declare const ENV_TOTAL_TOOL_TURNS = "DEFT_TOTAL_TOOL_TURNS";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export declare const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export declare const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export declare const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export declare const RUN_SUMMARY_EVENT_KINDS: readonly ["session_start", "dial_transition", "dial_escalation_evaluation", "check_invocation", "tool_turn_denominator", "verification", "acceptance", "acceptance_stamp"];
+export type RunSummaryEventKind = (typeof RUN_SUMMARY_EVENT_KINDS)[number];
+export interface RunSummaryBaseFields {
+    readonly schema_version: typeof RUN_SUMMARY_SCHEMA_VERSION;
+    readonly session_id: string;
+    readonly framework_version: string;
+    /** Monotonic per-emitter sequence (1-based). */
+    readonly seq: number;
+    readonly ts: string;
+    readonly event: RunSummaryEventKind;
+    /**
+     * Session total tool/turn count (#3320). Present so ritual+gate share is
+     * computable from the summary alone. Absence means the #3286 trigger is unevaluable.
+     */
+    readonly total_tool_turns?: number;
+}
+export interface SessionStartRunSummaryPayload {
+    readonly ceremony_dial?: Record<string, unknown>;
+    readonly preflight?: Record<string, unknown>;
+    readonly ceremony_tier?: string;
+    readonly ready?: boolean;
+    readonly exit_code?: number;
+    /** #3286: orientation surfaces composed into session:start (graduation trigger). */
+    readonly orientation_call_count?: number;
+    readonly orientation_compact?: boolean;
+    readonly deposit_sha?: string;
+    readonly orientation_later_status?: string;
+    readonly orientation_sections?: readonly Record<string, unknown>[];
+}
+export interface DialTransitionRunSummaryPayload {
+    readonly from: string | null;
+    readonly to: string;
+    readonly reason: string;
+    readonly evidence?: string;
+}
+/** One evaluation of escalate-on-evidence (#3319). Absence of this event ≠ declined. */
+export type DialEscalationEvaluationOutcome = "escalated" | "declined";
+export interface DialEscalationEvaluationRunSummaryPayload {
+    /** Ceremony depth considered (the start/current tier under evaluation). */
+    readonly tier: string;
+    readonly outcome: DialEscalationEvaluationOutcome;
+    readonly reason: string;
+}
+export interface CheckGateOutcome {
+    readonly id: string;
+    readonly status: "run" | "skipped" | "failed";
+    readonly exit_code?: number;
+    readonly cause?: string;
+    readonly remedy?: string;
+    readonly from_cache?: boolean;
+}
+/** Per-clause coverage row carried on verify:ac telemetry (#3323). */
+export interface AcceptanceClauseOutcomeRow {
+    readonly id: number;
+    readonly outcome: "verified" | "unverifiable" | "failed";
+}
+export interface CheckInvocationRunSummaryPayload {
+    readonly target: string;
+    readonly exit_code: number;
+    readonly degraded?: boolean;
+    readonly gates: readonly CheckGateOutcome[];
+    /** Additive verify:ac fields (#3323). Consumers ignore unknown keys. */
+    readonly source_rung?: string;
+    readonly none_stated?: boolean;
+    readonly clause_outcomes?: readonly AcceptanceClauseOutcomeRow[];
+}
+/** Total tool/turn count for the session (#3320). */
+export interface ToolTurnDenominatorRunSummaryPayload {
+    readonly total_tool_turns: number;
+}
+/** Product-oracle attempt (#3322). Same emitter as #3319 / #3320. */
+export type VerificationOutcome = "pass" | "fail";
+/** verify:ac resolution telemetry (#3334). Distinct from verification pass/fail. */
+export type AcceptanceRunSummaryOutcome = "verified-pass" | "empty-pass" | "soft_empty" | "fail";
+export interface AcceptanceRunSummaryPayload {
+    readonly resolved_command_count: number;
+    readonly outcome: AcceptanceRunSummaryOutcome;
+    readonly source_rung?: string;
+    readonly none_stated?: boolean;
+    readonly clause_count?: number;
+    readonly clause_outcomes?: readonly AcceptanceClauseOutcomeRow[];
+}
+/** Intake-time stamp: which rung locked, whether commands were stated, counts (#3323). */
+export interface AcceptanceStampRunSummaryPayload {
+    readonly rung: string;
+    readonly none_stated: boolean;
+    readonly command_count: number;
+    readonly clause_count: number;
+}
+export interface VerificationRunSummaryPayload {
+    readonly check_id: string;
+    readonly method_fingerprint: string;
+    readonly outcome: VerificationOutcome;
+    /**
+     * True when both sides of the comparison were rebuilt from scratch by a
+     * different method than the one that failed. Required to resolve
+     * fail → method-change → pass (#3322).
+     */
+    readonly independent_rederivation?: boolean;
+}
+export type RunSummaryPayload = SessionStartRunSummaryPayload | DialTransitionRunSummaryPayload | DialEscalationEvaluationRunSummaryPayload | CheckInvocationRunSummaryPayload | ToolTurnDenominatorRunSummaryPayload | VerificationRunSummaryPayload | AcceptanceRunSummaryPayload | AcceptanceStampRunSummaryPayload;
+export type RunSummaryLine = RunSummaryBaseFields & {
+    readonly payload: RunSummaryPayload;
+};
+export type RunSummaryDestination = {
+    readonly kind: "silent";
+} | {
+    readonly kind: "stdout";
+} | {
+    readonly kind: "file";
+    readonly path: string;
+    /** Truncate default-path file on session_start only. */
+    readonly truncateOnSessionStart: boolean;
+    /** Explicit path (env set) vs default gitignored path. */
+    readonly explicit: boolean;
+};
+//# sourceMappingURL=types.d.ts.map