harnery 0.33.0 → 0.34.0

package/dist/core/guard/config.js

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { coordRunQualityConfigSource } from "../config.js";
+export const DEFAULT_RUN_QUALITY_CONFIG = {
+    mode: "off",
+    evaluation_interval_seconds: 30,
+    snapshot_ttl_seconds: 120,
+    max_tail_bytes: 2 * 1024 * 1024,
+    evaluation_timeout_seconds: 30,
+    lock_stale_seconds: 60,
+    supervised_roots_per_sweep: 8,
+    thresholds: {
+        repeated_tool_calls: 8,
+        consecutive_failures: 5,
+        context_growth_per_minute: 60_000,
+        compaction_grace_seconds: 300,
+        no_progress_evaluations: 2,
+    },
+};
+const RANGES = {
+    evaluation_interval_seconds: [5, 3600],
+    snapshot_ttl_seconds: [10, 86_400],
+    max_tail_bytes: [64 * 1024, 64 * 1024 * 1024],
+    evaluation_timeout_seconds: [1, 30],
+    lock_stale_seconds: [5, 3600],
+    supervised_roots_per_sweep: [1, 100],
+    repeated_tool_calls: [2, 10_000],
+    consecutive_failures: [1, 10_000],
+    context_growth_per_minute: [1, 10_000_000],
+    compaction_grace_seconds: [0, 86_400],
+    no_progress_evaluations: [1, 10_000],
+};
+/** Read and validate the project-owned coord.run_quality object as one unit. */
+export function readRunQualityConfig(coordRoot) {
+    const source = coordRunQualityConfigSource(coordRoot);
+    if (source.invalid)
+        return invalid(source.digest_seed, "config_json_invalid", "off");
+    const value = source.value;
+    if (value === undefined)
+        return result(DEFAULT_RUN_QUALITY_CONFIG, true, []);
+    const rq = record(value);
+    const mode = modeOf(rq?.mode);
+    if (!rq || !mode)
+        return invalid(value, "run_quality_object_invalid", mode ?? "off");
+    const config = {
+        mode,
+        evaluation_interval_seconds: numberOrDefault(rq.evaluation_interval_seconds, DEFAULT_RUN_QUALITY_CONFIG.evaluation_interval_seconds),
+        snapshot_ttl_seconds: numberOrDefault(rq.snapshot_ttl_seconds, DEFAULT_RUN_QUALITY_CONFIG.snapshot_ttl_seconds),
+        max_tail_bytes: numberOrDefault(rq.max_tail_bytes, DEFAULT_RUN_QUALITY_CONFIG.max_tail_bytes),
+        evaluation_timeout_seconds: numberOrDefault(rq.evaluation_timeout_seconds, DEFAULT_RUN_QUALITY_CONFIG.evaluation_timeout_seconds),
+        lock_stale_seconds: numberOrDefault(rq.lock_stale_seconds, DEFAULT_RUN_QUALITY_CONFIG.lock_stale_seconds),
+        supervised_roots_per_sweep: numberOrDefault(rq.supervised_roots_per_sweep, DEFAULT_RUN_QUALITY_CONFIG.supervised_roots_per_sweep),
+        thresholds: {
+            repeated_tool_calls: numberOrDefault(record(rq.thresholds)?.repeated_tool_calls, DEFAULT_RUN_QUALITY_CONFIG.thresholds.repeated_tool_calls),
+            consecutive_failures: numberOrDefault(record(rq.thresholds)?.consecutive_failures, DEFAULT_RUN_QUALITY_CONFIG.thresholds.consecutive_failures),
+            context_growth_per_minute: numberOrDefault(record(rq.thresholds)?.context_growth_per_minute, DEFAULT_RUN_QUALITY_CONFIG.thresholds.context_growth_per_minute),
+            compaction_grace_seconds: numberOrDefault(record(rq.thresholds)?.compaction_grace_seconds, DEFAULT_RUN_QUALITY_CONFIG.thresholds.compaction_grace_seconds),
+            no_progress_evaluations: numberOrDefault(record(rq.thresholds)?.no_progress_evaluations, DEFAULT_RUN_QUALITY_CONFIG.thresholds.no_progress_evaluations),
+        },
+    };
+    const reasons = validate(config, rq);
+    return reasons.length > 0 ? invalid(value, reasons, mode) : result(config, true, []);
+}
+function validate(config, raw) {
+    const reasons = [];
+    const allowedTop = new Set([
+        "mode",
+        "evaluation_interval_seconds",
+        "snapshot_ttl_seconds",
+        "max_tail_bytes",
+        "evaluation_timeout_seconds",
+        "lock_stale_seconds",
+        "supervised_roots_per_sweep",
+        "thresholds",
+    ]);
+    if (Object.keys(raw).some((key) => !allowedTop.has(key)))
+        reasons.push("unknown_field");
+    const top = [
+        "evaluation_interval_seconds",
+        "snapshot_ttl_seconds",
+        "max_tail_bytes",
+        "evaluation_timeout_seconds",
+        "lock_stale_seconds",
+        "supervised_roots_per_sweep",
+    ];
+    for (const key of top)
+        validateInteger(key, config[key], raw[key], reasons);
+    if (config.lock_stale_seconds <= config.evaluation_timeout_seconds) {
+        reasons.push("lock_stale_not_above_timeout");
+    }
+    if (config.snapshot_ttl_seconds < config.evaluation_interval_seconds) {
+        reasons.push("snapshot_ttl_below_interval");
+    }
+    const thresholds = record(raw.thresholds);
+    if (raw.thresholds !== undefined && !thresholds)
+        reasons.push("thresholds_invalid");
+    const allowedThresholds = new Set(Object.keys(config.thresholds));
+    if (thresholds && Object.keys(thresholds).some((key) => !allowedThresholds.has(key))) {
+        reasons.push("thresholds_unknown_field");
+    }
+    for (const key of Object.keys(config.thresholds)) {
+        validateInteger(key, config.thresholds[key], thresholds?.[key], reasons);
+    }
+    return reasons;
+}
+function validateInteger(key, value, supplied, reasons) {
+    if (supplied !== undefined && (!Number.isSafeInteger(supplied) || supplied !== value)) {
+        reasons.push(`${key}_not_integer`);
+        return;
+    }
+    const [min, max] = RANGES[key];
+    if (value < min || value > max)
+        reasons.push(`${key}_out_of_range`);
+}
+function numberOrDefault(value, fallback) {
+    return typeof value === "number" ? value : fallback;
+}
+function modeOf(value) {
+    return value === "off" || value === "shadow" || value === "report" ? value : null;
+}
+function result(config, valid, reasonCodes) {
+    return {
+        config,
+        digest: digest(config),
+        valid,
+        requested_mode: config.mode,
+        reason_codes: reasonCodes,
+    };
+}
+function invalid(value, reasons, mode) {
+    return {
+        config: null,
+        digest: digest(value),
+        valid: false,
+        requested_mode: mode,
+        reason_codes: Array.isArray(reasons) ? reasons : [reasons],
+    };
+}
+function digest(value) {
+    const body = typeof value === "string" ? value : stableJson(value);
+    return createHash("sha256").update(body).digest("hex");
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/core/guard/coordinator.d.ts

@@ -0,0 +1,14 @@
+import type { RunQualityConfigResult, RunQualitySnapshot } from "./types.js";
+export interface RunQualityEvaluationResult {
+    config: RunQualityConfigResult;
+    evaluated: boolean;
+    busy: boolean;
+    timed_out: boolean;
+    snapshot: RunQualitySnapshot | null;
+}
+/**
+ * Lazy, root-scoped evaluator. Its due check is config/cursor-only; ledger I/O
+ * begins only after the non-blocking writer lock is acquired.
+ */
+export declare function evaluateRunQualityIfDue(coordRoot: string, now?: Date, instanceId?: string): RunQualityEvaluationResult;
+//# sourceMappingURL=coordinator.d.ts.map

package/dist/core/guard/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/guard/coordinator.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAE7E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,0BAA0B,CA+E5B"}

package/dist/core/guard/coordinator.js

@@ -0,0 +1,173 @@
+import { mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readEventV3ControlState } from "../events/v3/control.js";
+import { liveInstanceIdV3 } from "../events/v3/live-routing.js";
+import { readRunQualityConfig } from "./config.js";
+import { evaluateRunQuality } from "./evaluator.js";
+import { readRunQualityLiveSourceV3 } from "./live-source-v3.js";
+import { acquireEvaluationLock, cleanupOrphanSnapshots, evaluationLockOwned, guardDir, readGuardCursor, readRunQualitySnapshot, releaseEvaluationLock, writeAtomicJson, writeGuardCursor, writeRunQualitySnapshot, } from "./storage.js";
+/**
+ * Lazy, root-scoped evaluator. Its due check is config/cursor-only; ledger I/O
+ * begins only after the non-blocking writer lock is acquired.
+ */
+export function evaluateRunQualityIfDue(coordRoot, now = new Date(), instanceId) {
+    const configResult = readRunQualityConfig(coordRoot);
+    const canonicalInstanceId = instanceId ? liveInstanceIdV3(instanceId) : undefined;
+    const previousForCaller = canonicalInstanceId
+        ? readRunQualitySnapshot(coordRoot, canonicalInstanceId)
+        : null;
+    if (!configResult.valid || !configResult.config) {
+        maybeEmitInvalidConfig(coordRoot, configResult, now);
+        return {
+            config: configResult,
+            evaluated: false,
+            busy: false,
+            timed_out: false,
+            snapshot: null,
+        };
+    }
+    const config = configResult.config;
+    if (config.mode === "off") {
+        return {
+            config: configResult,
+            evaluated: false,
+            busy: false,
+            timed_out: false,
+            snapshot: previousForCaller,
+        };
+    }
+    const cursor = readGuardCursor(coordRoot);
+    if (cursor?.config_digest === configResult.digest &&
+        Date.parse(cursor.next_eligible_at) > now.getTime()) {
+        return {
+            config: configResult,
+            evaluated: false,
+            busy: false,
+            timed_out: false,
+            snapshot: previousForCaller,
+        };
+    }
+    const lock = acquireEvaluationLock(coordRoot, now, config.lock_stale_seconds);
+    if (!lock) {
+        return {
+            config: configResult,
+            evaluated: false,
+            busy: true,
+            timed_out: false,
+            snapshot: previousForCaller,
+        };
+    }
+    const deadline = Date.now() + config.evaluation_timeout_seconds * 1000;
+    let timedOut = false;
+    try {
+        const control = readEventV3ControlState(coordRoot);
+        if (control.state !== "candidate" && control.state !== "active") {
+            throw new Error(`run_quality_v3_control_${control.state}`);
+        }
+        return evaluateRunQualityV3({
+            coordRoot,
+            now,
+            instanceId: canonicalInstanceId,
+            configResult,
+            deadline,
+            lockNonce: lock.nonce,
+        });
+    }
+    catch (error) {
+        timedOut = error.message === "run_quality_evaluation_timeout";
+        return {
+            config: configResult,
+            evaluated: false,
+            busy: false,
+            timed_out: timedOut,
+            snapshot: previousForCaller,
+        };
+    }
+    finally {
+        releaseEvaluationLock(coordRoot, lock.nonce);
+    }
+}
+function evaluateRunQualityV3(input) {
+    const config = input.configResult.config;
+    if (!config)
+        throw new Error("run_quality_v3_config_unavailable");
+    const source = readRunQualityLiveSourceV3(input.coordRoot, input.now);
+    const snapshots = [];
+    for (const generation of source.generations) {
+        const previous = readRunQualitySnapshot(input.coordRoot, generation.instance_id) ?? undefined;
+        const previousIndex = previous?.evidence.last_event_id
+            ? generation.events.findIndex((event) => event.event_id === previous.evidence.last_event_id)
+            : -1;
+        const events = previousIndex >= 0 ? generation.events.slice(previousIndex + 1) : generation.events;
+        const snapshot = evaluateRunQuality({
+            instance_id: generation.instance_id,
+            session_id: generation.session_id,
+            session_generation: generation.generation_id,
+            adapter: generation.adapter,
+            now: input.now.toISOString(),
+            config,
+            config_digest: input.configResult.digest,
+            events,
+            previous,
+            role_wait: generation.role_wait,
+            evidence: generation.evidence,
+            sufficient_history: generation.sufficient_history &&
+                (!previous ||
+                    previous.session_generation !== generation.generation_id ||
+                    previousIndex >= 0),
+            live: true,
+        });
+        snapshots.push(snapshot);
+    }
+    assertCanPublish(input.coordRoot, input.lockNonce, input.deadline);
+    const liveIds = new Set(snapshots.map((snapshot) => snapshot.instance_id));
+    for (const snapshot of snapshots) {
+        assertCanPublish(input.coordRoot, input.lockNonce, input.deadline);
+        writeRunQualitySnapshot(input.coordRoot, snapshot, input.lockNonce);
+    }
+    cleanupOrphanSnapshots(input.coordRoot, liveIds);
+    const last = source.generations
+        .flatMap((generation) => generation.events)
+        .sort((left, right) => left.ts.localeCompare(right.ts) || left.event_id.localeCompare(right.event_id))
+        .at(-1);
+    writeGuardCursor(input.coordRoot, {
+        schema_version: 1,
+        segment: last ? `v3:${source.genesis_id}` : `v3:${source.genesis_id}:empty`,
+        last_event_id: last?.event_id,
+        next_eligible_at: new Date(input.now.getTime() + config.evaluation_interval_seconds * 1000).toISOString(),
+        config_digest: input.configResult.digest,
+        updated_at: input.now.toISOString(),
+    }, input.lockNonce);
+    return {
+        config: input.configResult,
+        evaluated: true,
+        busy: false,
+        timed_out: false,
+        snapshot: input.instanceId
+            ? (snapshots.find((snapshot) => snapshot.instance_id === input.instanceId) ?? null)
+            : null,
+    };
+}
+function maybeEmitInvalidConfig(coordRoot, config, now) {
+    if (config.valid)
+        return;
+    const dir = guardDir(coordRoot);
+    const markerPath = join(dir, "config-invalid.json");
+    let previousDigest;
+    try {
+        previousDigest = JSON.parse(readFileSync(markerPath, "utf8")).digest;
+    }
+    catch {
+        // First invalid observation.
+    }
+    if (previousDigest === config.digest)
+        return;
+    mkdirSync(dir, { recursive: true });
+    writeAtomicJson(markerPath, { digest: config.digest, emitted_at: now.toISOString() }, config.digest);
+}
+function assertCanPublish(coordRoot, nonce, deadline) {
+    if (Date.now() > deadline)
+        throw new Error("run_quality_evaluation_timeout");
+    if (!evaluationLockOwned(coordRoot, nonce))
+        throw new Error("run_quality_lock_stolen");
+}

package/dist/core/guard/evaluator.d.ts

@@ -0,0 +1,4 @@
+import type { EvaluateRunQualityInput, RunQualitySnapshot } from "./types.js";
+/** Pure report-only transition. It has no filesystem, process, or verdict dependencies. */
+export declare function evaluateRunQuality(input: EvaluateRunQualityInput): RunQualitySnapshot;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/core/guard/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../src/core/guard/evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EAIvB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AAKpB,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,kBAAkB,CAiFrF"}

package/dist/core/guard/evaluator.js

@@ -0,0 +1,242 @@
+import { RUN_QUALITY_SCHEMA_VERSION } from "./types.js";
+const LEVELS = ["unknown", "healthy", "attention", "critical"];
+/** Pure report-only transition. It has no filesystem, process, or verdict dependencies. */
+export function evaluateRunQuality(input) {
+    const configChanged = !!input.previous && input.previous.config_digest !== input.config_digest;
+    const sameGeneration = !input.previous || input.previous.session_generation === input.session_generation;
+    const priorState = !configChanged && sameGeneration ? input.previous?.state : undefined;
+    const state = cloneState(priorState);
+    const events = [...input.events].sort(compareEvidence);
+    let progressSeen = false;
+    let newEvidence = false;
+    for (const event of events) {
+        if (input.previous?.evidence.last_event_id === event.event_id)
+            continue;
+        newEvidence = true;
+        progressSeen = applyEvidence(state, event, input) || progressSeen;
+    }
+    const legitimateWait = input.role_wait.fresh && input.role_wait.wait_kind !== "none";
+    const deadlineEpoch = !newEvidence && input.live && !legitimateWait;
+    const epoch = newEvidence ? "evidence" : deadlineEpoch ? "deadline" : "read";
+    const inGrace = graceActive(state, input.now);
+    const signals = buildSignals(state, input, inGrace);
+    const precursorFamilies = new Set(signals
+        .filter((signal) => signal.state === "active" &&
+        signal.id !== "no_progress" &&
+        signal.id !== "compaction_grace")
+        .map((signal) => signal.id === "repeated_tool_calls" || signal.id === "target_stagnation"
+        ? "tool_behavior"
+        : signal.id)).size;
+    if (progressSeen) {
+        state.no_progress_epochs = 0;
+        state.no_progress_deadline_epochs = 0;
+    }
+    else if (precursorFamilies >= 2 && (newEvidence || deadlineEpoch)) {
+        state.no_progress_epochs++;
+        if (deadlineEpoch)
+            state.no_progress_deadline_epochs++;
+    }
+    replaceSignal(signals, noProgressSignal(state, input, inGrace, legitimateWait));
+    let desired = desiredStatus(signals, input.sufficient_history, input.evidence.truncated);
+    if (progressSeen && desired === "critical")
+        desired = "attention";
+    const previousStatus = input.previous?.status ?? "unknown";
+    const transitionBase = configChanged || !sameGeneration ? "unknown" : previousStatus;
+    const status = stepOneLevel(transitionBase, desired);
+    const evaluatedAt = input.now;
+    const nextEligibleAt = addSeconds(evaluatedAt, input.config.evaluation_interval_seconds);
+    const expiresAt = addSeconds(evaluatedAt, input.config.snapshot_ttl_seconds);
+    return {
+        schema_version: RUN_QUALITY_SCHEMA_VERSION,
+        instance_id: input.instance_id,
+        session_id: input.session_id,
+        session_generation: input.session_generation,
+        adapter: input.adapter,
+        config_digest: input.config_digest,
+        mode: input.config.mode === "report" ? "report" : "shadow",
+        status,
+        previous_status: previousStatus,
+        evaluated_at: evaluatedAt,
+        next_eligible_at: nextEligibleAt,
+        expires_at: expiresAt,
+        evidence: input.evidence,
+        signals,
+        role_wait: input.role_wait,
+        state,
+        epoch,
+        reason: configChanged
+            ? "config_changed"
+            : !input.sufficient_history || input.evidence.truncated
+                ? "insufficient_evidence"
+                : deadlineEpoch
+                    ? "deadline"
+                    : "evidence",
+    };
+}
+function applyEvidence(state, event, input) {
+    switch (event.kind) {
+        case "tool_call":
+            state.work_since_progress++;
+            if (event.target_hash) {
+                state.target_hash_seen = true;
+                if (state.target_hash === event.target_hash)
+                    state.target_streak++;
+                else {
+                    state.target_hash = event.target_hash;
+                    state.target_streak = 1;
+                }
+            }
+            if (!event.input_hash) {
+                state.missing_hash_seen = true;
+                return false;
+            }
+            state.exact_hash_seen = true;
+            if (state.repeated_hash === event.input_hash)
+                state.repeated_count++;
+            else {
+                state.repeated_hash = event.input_hash;
+                state.repeated_count = 1;
+            }
+            return false;
+        case "tool_success":
+            state.failure_streak = 0;
+            return false;
+        case "tool_failure":
+            state.failure_streak++;
+            return false;
+        case "progress":
+            state.work_since_progress = 0;
+            state.target_streak = 0;
+            return true;
+        case "context_sample":
+            applyContextSample(state, event, input.adapter);
+            return false;
+        case "compaction_started":
+            state.compaction_grace_until = addSeconds(event.ts, input.config.thresholds.compaction_grace_seconds);
+            return false;
+        case "compaction_completed":
+            state.compaction_grace_until = addSeconds(event.ts, input.config.thresholds.compaction_grace_seconds);
+            return true;
+        case "tool_pairing_incomplete":
+        case "command_pairing_incomplete":
+        case "recovered_terminal":
+            return false;
+    }
+}
+function applyContextSample(state, event, adapter) {
+    if (event.used_tokens === undefined ||
+        !Number.isFinite(event.used_tokens) ||
+        !attestedContextSource(adapter, event.telemetry_source, event.confidence)) {
+        return;
+    }
+    const previous = state.last_context;
+    if (previous) {
+        const minutes = (Date.parse(event.ts) - Date.parse(previous.ts)) / 60_000;
+        if (Number.isFinite(minutes) && minutes > 0) {
+            state.context_growth_per_minute = (event.used_tokens - previous.used_tokens) / minutes;
+        }
+    }
+    state.last_context = { used_tokens: event.used_tokens, ts: event.ts };
+}
+function attestedContextSource(adapter, source, confidence) {
+    if (confidence !== "exact" && confidence !== "reported")
+        return false;
+    const allowed = {
+        "claude-code": ["hook", "native_event", "result"],
+        codex: ["native_event", "result", "transcript"],
+        cursor: ["native_event"],
+    };
+    return !!source && (allowed[adapter] ?? []).includes(source);
+}
+function buildSignals(state, input, inGrace) {
+    const t = input.config.thresholds;
+    return [
+        thresholdSignal("repeated_tool_calls", state.repeated_count, t.repeated_tool_calls, state.exact_hash_seen ? "exact_input_hash" : "exact_input_hash_unavailable", !state.exact_hash_seen && state.missing_hash_seen),
+        thresholdSignal("consecutive_failures", state.failure_streak, t.consecutive_failures, "consecutive_outcomes", false),
+        inGrace
+            ? signal("context_growth", "suppressed", "none", 0, "compaction_grace")
+            : state.context_growth_per_minute === undefined
+                ? signal("context_growth", "unknown", "none", 0, "attested_samples_unavailable")
+                : thresholdSignal("context_growth", Math.max(0, Math.round(state.context_growth_per_minute)), t.context_growth_per_minute, "attested_context_velocity", false),
+        thresholdSignal("target_stagnation", state.target_streak, t.repeated_tool_calls, "same_target_without_progress_event", !state.target_hash_seen),
+        signal("no_progress", "inactive", "none", state.no_progress_epochs, "not_corroborated"),
+        inGrace
+            ? signal("compaction_grace", "active", "none", 1, "within_grace_deadline")
+            : signal("compaction_grace", "inactive", "none", 0, "outside_grace_deadline"),
+    ];
+}
+function noProgressSignal(state, input, inGrace, legitimateWait) {
+    if (inGrace)
+        return signal("no_progress", "suppressed", "none", 0, "compaction_grace");
+    if (legitimateWait)
+        return signal("no_progress", "suppressed", "none", 0, "legitimate_wait");
+    if (state.no_progress_deadline_epochs < 1) {
+        return signal("no_progress", "inactive", "none", state.no_progress_epochs, "deadline_epoch_required");
+    }
+    return thresholdSignal("no_progress", state.no_progress_epochs, input.config.thresholds.no_progress_evaluations, "corroborated_epochs", false);
+}
+function thresholdSignal(id, count, threshold, reason, unknown) {
+    if (unknown)
+        return signal(id, "unknown", "none", count, reason);
+    if (count >= threshold * 2)
+        return signal(id, "active", "critical", count, reason);
+    if (count >= threshold)
+        return signal(id, "active", "attention", count, reason);
+    return signal(id, "inactive", "none", count, reason);
+}
+function signal(id, state, severity, count, reason_code) {
+    return { id, state, severity, count, reason_code };
+}
+function replaceSignal(signals, next) {
+    const index = signals.findIndex((signal) => signal.id === next.id);
+    if (index >= 0)
+        signals[index] = next;
+}
+function desiredStatus(signals, sufficientHistory, truncated) {
+    if (!sufficientHistory || truncated)
+        return "unknown";
+    if (signals.some((signal) => signal.state === "active" && signal.severity === "critical")) {
+        return "critical";
+    }
+    if (signals.some((signal) => signal.state === "active" && signal.severity === "attention")) {
+        return "attention";
+    }
+    return "healthy";
+}
+function stepOneLevel(previous, desired) {
+    if (previous === desired)
+        return previous;
+    if (previous === "unknown")
+        return desired === "critical" ? "attention" : desired;
+    if (desired === "unknown")
+        return "unknown";
+    const from = LEVELS.indexOf(previous);
+    const to = LEVELS.indexOf(desired);
+    return LEVELS[from + Math.sign(to - from)] ?? desired;
+}
+function graceActive(state, now) {
+    if (!state.compaction_grace_until)
+        return false;
+    return Date.parse(now) < Date.parse(state.compaction_grace_until);
+}
+function cloneState(previous) {
+    return previous
+        ? structuredClone(previous)
+        : {
+            repeated_count: 0,
+            exact_hash_seen: false,
+            missing_hash_seen: false,
+            target_streak: 0,
+            target_hash_seen: false,
+            failure_streak: 0,
+            work_since_progress: 0,
+            no_progress_epochs: 0,
+            no_progress_deadline_epochs: 0,
+        };
+}
+function compareEvidence(a, b) {
+    return a.event_id.localeCompare(b.event_id) || a.ts.localeCompare(b.ts);
+}
+function addSeconds(iso, seconds) {
+    return new Date(Date.parse(iso) + seconds * 1000).toISOString();
+}

package/dist/core/guard/evidence-v3.d.ts

@@ -0,0 +1,15 @@
+import { type EventV3 } from "../events/v3/index.js";
+import type { RunQualityCorpusCategoryV3, RunQualityEvidenceEvent } from "./types.js";
+/**
+ * Convert one validated V3 row into the evaluator's privacy-safe evidence.
+ * Both the live guard and offline corpus use this exact adapter.
+ */
+export declare function normalizeRunQualityEventV3(event: EventV3, priorEvents?: ReadonlyMap<string, EventV3>): RunQualityEvidenceEvent[];
+/**
+ * Derive generation-level pairing markers from validated events. The markers
+ * are audit metadata, not behavioral guard evidence: callers keep them in a
+ * separate corpus-category dimension.
+ */
+export declare function normalizeRunQualityPairingV3(events: readonly EventV3[]): RunQualityEvidenceEvent[];
+export declare function isRunQualityCorpusCategoryV3(kind: RunQualityEvidenceEvent["kind"]): kind is RunQualityCorpusCategoryV3;
+//# sourceMappingURL=evidence-v3.d.ts.map

package/dist/core/guard/evidence-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-v3.d.ts","sourceRoot":"","sources":["../../../src/core/guard/evidence-v3.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,KAAK,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAetF;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,WAAW,GAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAa,GACpD,uBAAuB,EAAE,CAkD3B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,uBAAuB,EAAE,CAsD3B;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,uBAAuB,CAAC,MAAM,CAAC,GACpC,IAAI,IAAI,0BAA0B,CAMpC"}