harnery 0.34.1 → 0.36.0

package/dist/core/semantic/service.js

@@ -0,0 +1,559 @@
+import { spawn } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import { appendFileSync, chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, watch, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { coordEnv } from "../../lib/env.js";
+import { readEventV3ControlState, readLedgerV3Since, } from "../events/v3/index.js";
+import { eventV3ActiveWatchPath } from "../events/v3/reader.js";
+import { closeProcessLoggers, encodeBoundedLogObjectArray, legacyLogFields, processLogger, } from "../storage/logger.js";
+import { runSemanticOnce } from "./once.js";
+import { semanticPendingPassDue } from "./scheduler.js";
+import { readSemanticServiceStatus, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, } from "./service-status.js";
+import { semanticSoakReadings } from "./soak.js";
+import { listSemanticAgentDocuments, readSemanticManifest, semanticPaths, writeSemanticManifest, } from "./storage.js";
+import { aggregateSemanticUsage, emptySemanticUsageAggregate, mergeSemanticUsageAggregates, } from "./usage.js";
+export { readSemanticServiceStatus, SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION, } from "./service-status.js";
+export const SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS = 5_000;
+export const SEMANTIC_SERVICE_DEFAULT_WAKE_MS = 1_000;
+export const SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS = 5_000;
+const FOREIGN_STATUS_STALE_MS = 2 * 60_000;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_LOG_BYTES = 512 * 1024;
+const REPEATED_ERROR_LOG_INTERVAL_MS = 60_000;
+const SEMANTIC_READINGS_FIELD_MAX_BYTES = 4_096;
+const SEMANTIC_READING_FIELDS = [
+    "subject_id",
+    "generated_at",
+    "source_harness",
+    "configured_model",
+    "resolved_model_id",
+    "model_attestation",
+    "origin",
+    "phase",
+    "phase_confidence",
+    "expression_cue",
+    "expression_confidence",
+];
+export async function spawnSemanticService(coordRootRaw, options = {}) {
+    const coordRoot = resolve(coordRootRaw);
+    const current = readSemanticServiceStatus(coordRoot);
+    if (current.running) {
+        throw new Error(`semantic service is already running under pid ${current.record?.pid}`);
+    }
+    const paths = semanticPaths(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
+    const logFd = sharedLogs ? undefined : openSync(paths.log, "a", 0o600);
+    if (logFd !== undefined)
+        chmodSync(paths.log, 0o600);
+    const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+    if (!existsSync(harnBin)) {
+        if (logFd !== undefined)
+            closeSync(logFd);
+        throw new Error(`cannot find harn executable at ${harnBin}`);
+    }
+    const args = ["semantic", "service", "daemon", "--root", coordRoot];
+    if (options.callsPerHour !== undefined) {
+        args.push("--calls-per-hour", String(options.callsPerHour));
+    }
+    let spawnError;
+    const child = spawn(harnBin, args, {
+        cwd: coordRoot,
+        detached: true,
+        stdio: logFd === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", logFd, logFd],
+        env: {
+            ...process.env,
+            HARNERY_COORD_ROOT_OVERRIDE: coordRoot,
+            HARNERY_OUTPUT_SESSION_TEE: "0",
+        },
+    });
+    child.once("error", (error) => {
+        spawnError = error;
+    });
+    if (logFd !== undefined)
+        closeSync(logFd);
+    child.unref();
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        await delay(50);
+        if (spawnError)
+            throw spawnError;
+        const status = readSemanticServiceStatus(coordRoot);
+        if (status.running && status.record?.pid === child.pid)
+            return status;
+        if (child.exitCode !== null)
+            break;
+    }
+    const diagnosticPath = sharedLogs
+        ? join(coordRoot, ".harnery", "logs", "semantic-service", "active.jsonl")
+        : paths.log;
+    throw new Error(`semantic service failed to start; inspect ${diagnosticPath}`);
+}
+/**
+ * Start semantic reading when V3 is active, unless an operator paused it.
+ *
+ * Dashboard hosts call this before launching their web process. A failed
+ * semantic launch is reported as data instead of throwing so the read-only
+ * dashboard remains available.
+ */
+export async function ensureSemanticServiceRunning(coordRootRaw, overrides = {}) {
+    const coordRoot = resolve(coordRootRaw);
+    const dependencies = {
+        readStatus: readSemanticServiceStatus,
+        start: spawnSemanticService,
+        isPaused: (root) => existsSync(semanticPaths(root).stop),
+        isActive: (root) => readEventV3ControlState(root).state === "active",
+        ...overrides,
+    };
+    const status = dependencies.readStatus(coordRoot);
+    if (status.running)
+        return { state: "running", status };
+    if (dependencies.isPaused(coordRoot))
+        return { state: "paused", status };
+    if (!dependencies.isActive(coordRoot))
+        return { state: "inactive", status };
+    try {
+        return { state: "started", status: await dependencies.start(coordRoot) };
+    }
+    catch (error) {
+        return {
+            state: "unavailable",
+            status: dependencies.readStatus(coordRoot),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function requestSemanticServiceStop(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const status = readSemanticServiceStatus(coordRoot);
+    mkdirSync(semanticPaths(coordRoot).root, { recursive: true, mode: 0o700 });
+    writePrivateJsonAtomic(semanticPaths(coordRoot).stop, {
+        requested_at: new Date().toISOString(),
+        requested_by_pid: process.pid,
+    });
+    if (status.running && status.record?.host === hostname()) {
+        try {
+            process.kill(status.record.pid, "SIGTERM");
+        }
+        catch {
+            // The durable stop request remains for a racing or restarted daemon.
+        }
+    }
+    return readSemanticServiceStatus(coordRoot);
+}
+export async function runSemanticServiceDaemon(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const paths = semanticPaths(coordRoot);
+    const release = acquireSemanticServiceLease(coordRoot);
+    rmSync(paths.stop, { force: true });
+    const now = input.now ?? (() => new Date());
+    const debounceMs = Math.max(0, input.debounceMs ?? SEMANTIC_SERVICE_DEFAULT_DEBOUNCE_MS);
+    const wakeIntervalMs = positiveInterval(input.wakeIntervalMs ?? SEMANTIC_SERVICE_DEFAULT_WAKE_MS, "wake interval");
+    const heartbeatIntervalMs = positiveInterval(input.heartbeatIntervalMs ?? SEMANTIC_SERVICE_DEFAULT_HEARTBEAT_MS, "heartbeat interval");
+    const readSince = input.readSince ?? readLedgerV3Since;
+    const runOnce = input.runOnce ??
+        (async (options) => await runSemanticOnce({
+            coordRoot: options.coordRoot,
+            callsPerHour: options.callsPerHour,
+            debounceMs: options.debounceMs,
+            shouldStop: options.shouldStop,
+        }));
+    const startedAt = now().toISOString();
+    const status = {
+        schema_version: SEMANTIC_SERVICE_STATUS_SCHEMA_VERSION,
+        pid: process.pid,
+        host: hostname(),
+        nonce: randomUUID(),
+        state: "starting",
+        started_at: startedAt,
+        heartbeat_at: startedAt,
+        ...(input.callsPerHour !== undefined ? { calls_per_hour: input.callsPerHour } : {}),
+        sweep_count: 0,
+        pass_count: 0,
+        model_calls: 0,
+        cache_hits: 0,
+        process_usage: emptySemanticUsageAggregate(),
+    };
+    let stopRequested = false;
+    let dirtySince;
+    let lastLoggedErrorCode;
+    let lastLoggedErrorAt = Number.NEGATIVE_INFINITY;
+    const writeStatus = () => {
+        status.heartbeat_at = now().toISOString();
+        writePrivateJsonAtomic(paths.service, status);
+    };
+    const requestStop = () => {
+        stopRequested = true;
+        status.state = "stopping";
+        writeStatus();
+    };
+    process.on("SIGINT", requestStop);
+    process.on("SIGTERM", requestStop);
+    status.state = "running";
+    writeStatus();
+    appendSemanticServiceDiagnostic(coordRoot, { event: "service_started" });
+    const heartbeat = setInterval(() => {
+        try {
+            writeStatus();
+        }
+        catch {
+            // A later sweep or status read will expose the stopped or stale process.
+        }
+    }, heartbeatIntervalMs);
+    try {
+        while (!stopRequested && !existsSync(paths.stop)) {
+            const sweepAt = now();
+            status.sweep_count += 1;
+            try {
+                const before = safeManifest(coordRoot);
+                let read = readSince(coordRoot, before?.cursor, { authority: "active" });
+                if (read.reset_required) {
+                    read = readSince(coordRoot, undefined, { authority: "active" });
+                }
+                requireCompleteLedger(read);
+                if (read.events.length > 0 || !before?.cursor) {
+                    dirtySince ??= sweepAt.getTime();
+                }
+                const hasPendingPassDue = before
+                    ? semanticPendingPassDue({
+                        pending: before.pending,
+                        callHistory: before.call_history,
+                        nowMs: sweepAt.getTime(),
+                        debounceMs,
+                        ...(input.callsPerHour !== undefined ? { callsPerHour: input.callsPerHour } : {}),
+                    })
+                    : false;
+                const hasEligibleDeferred = listSemanticAgentDocuments(coordRoot).some((document) => document.reader_outcome === "deferred" &&
+                    Date.parse(document.receipt.eligible_after) <= sweepAt.getTime());
+                if (hasPendingPassDue ||
+                    hasEligibleDeferred ||
+                    (dirtySince !== undefined && sweepAt.getTime() - dirtySince >= debounceMs)) {
+                    const report = await runOnce({
+                        coordRoot,
+                        ...(input.callsPerHour !== undefined ? { callsPerHour: input.callsPerHour } : {}),
+                        debounceMs,
+                        shouldStop: () => stopRequested || existsSync(paths.stop),
+                    });
+                    status.pass_count += 1;
+                    status.model_calls += report.model_calls;
+                    status.cache_hits += report.cache_hits;
+                    status.process_usage = mergeSemanticUsageAggregates(status.process_usage ?? emptySemanticUsageAggregate(), aggregateSemanticUsage(report.outcomes));
+                    status.last_pass_at = report.completed_at;
+                    status.last_error_code = undefined;
+                    lastLoggedErrorCode = undefined;
+                    const after = safeManifest(coordRoot);
+                    if (after && read.cursor) {
+                        after.cursor = read.cursor;
+                        writeSemanticManifest(coordRoot, after);
+                    }
+                    dirtySince = undefined;
+                    const logEntry = {
+                        event: "pass",
+                        evidence_count: report.evidence_count,
+                        evidence_by_harness: report.evidence_by_harness,
+                        model_calls: report.model_calls,
+                        cache_hits: report.cache_hits,
+                        accepted: report.outcomes.filter((outcome) => outcome.action === "accepted").length,
+                        unavailable: report.outcomes.filter((outcome) => outcome.action === "unavailable")
+                            .length,
+                        invalid: report.outcomes.filter((outcome) => outcome.action === "invalid").length,
+                        deferred: report.outcomes.filter((outcome) => outcome.action === "deferred").length,
+                        harness_metrics: semanticHarnessMetrics(report),
+                        usage: aggregateSemanticUsage(report.outcomes),
+                        semantic_readings: semanticSoakReadings(coordRoot, report.outcomes),
+                    };
+                    if (report.model_calls > 0 || report.cache_hits > 0 || logEntry.unavailable > 0) {
+                        appendSemanticServiceDiagnostic(coordRoot, logEntry);
+                    }
+                }
+            }
+            catch (error) {
+                status.last_error_code = serviceErrorCode(error);
+                if (status.last_error_code !== lastLoggedErrorCode ||
+                    sweepAt.getTime() - lastLoggedErrorAt >= REPEATED_ERROR_LOG_INTERVAL_MS) {
+                    appendSemanticServiceDiagnostic(coordRoot, {
+                        event: "sweep_error",
+                        reason_code: status.last_error_code,
+                    });
+                    lastLoggedErrorCode = status.last_error_code;
+                    lastLoggedErrorAt = sweepAt.getTime();
+                }
+            }
+            status.last_sweep_at = now().toISOString();
+            writeStatus();
+            if (input.maxSweeps !== undefined && status.sweep_count >= input.maxSweeps)
+                break;
+            if (!stopRequested && !existsSync(paths.stop)) {
+                if (input.waitForWake)
+                    await input.waitForWake(wakeIntervalMs);
+                else
+                    await waitForLedgerWake(eventV3ActiveWatchPath(coordRoot), wakeIntervalMs);
+            }
+        }
+    }
+    finally {
+        clearInterval(heartbeat);
+        process.off("SIGINT", requestStop);
+        process.off("SIGTERM", requestStop);
+        status.state = "stopped";
+        status.stopped_at = now().toISOString();
+        writeStatus();
+        appendSemanticServiceDiagnostic(coordRoot, {
+            event: "service_stopped",
+            sweeps: status.sweep_count,
+            passes: status.pass_count,
+            model_calls: status.model_calls,
+            usage: status.process_usage,
+        });
+        try {
+            await closeProcessLoggers();
+        }
+        finally {
+            release();
+        }
+    }
+    return status;
+}
+export function acquireSemanticServiceLease(coordRootRaw) {
+    const path = semanticPaths(coordRootRaw).lease;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const owner = {
+        pid: process.pid,
+        host: hostname(),
+        nonce: randomUUID(),
+        created_at: new Date().toISOString(),
+    };
+    const acquire = () => {
+        try {
+            const fd = openSync(path, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            return false;
+        }
+    };
+    if (!acquire()) {
+        const existing = readLease(path);
+        if (existing && leaseOwnerIsLive(existing)) {
+            throw new Error(`semantic service is already running under pid ${existing.pid}`);
+        }
+        unlinkSync(path);
+        if (!acquire())
+            throw new Error("semantic service lease raced with another process");
+    }
+    return () => {
+        try {
+            const existing = readLease(path);
+            if (existing?.nonce === owner.nonce)
+                unlinkSync(path);
+        }
+        catch {
+            // A later explicit start can recover a stale private lease.
+        }
+    };
+}
+function semanticHarnessMetrics(report) {
+    const metrics = {
+        "claude-code": emptyHarnessMetrics(report.evidence_by_harness["claude-code"]),
+        codex: emptyHarnessMetrics(report.evidence_by_harness.codex),
+        cursor: emptyHarnessMetrics(report.evidence_by_harness.cursor),
+    };
+    for (const outcome of report.outcomes) {
+        const harness = metrics[outcome.source_harness];
+        if (outcome.model_call)
+            harness.model_calls += 1;
+        if (outcome.action === "cached")
+            harness.cache_hits += 1;
+        if (outcome.action === "accepted")
+            harness.accepted += 1;
+        if (outcome.action === "unavailable")
+            harness.unavailable += 1;
+        if (outcome.action === "invalid")
+            harness.invalid += 1;
+        if (outcome.action === "deferred")
+            harness.deferred += 1;
+        if (outcome.duration_ms !== undefined)
+            harness.duration_ms.push(outcome.duration_ms);
+        if (outcome.input_bytes !== undefined)
+            harness.input_bytes.push(outcome.input_bytes);
+        if (outcome.output_bytes !== undefined)
+            harness.output_bytes.push(outcome.output_bytes);
+    }
+    return metrics;
+}
+function emptyHarnessMetrics(evidenceCount) {
+    return {
+        evidence_count: evidenceCount,
+        model_calls: 0,
+        cache_hits: 0,
+        accepted: 0,
+        unavailable: 0,
+        invalid: 0,
+        deferred: 0,
+        duration_ms: [],
+        input_bytes: [],
+        output_bytes: [],
+    };
+}
+function requireCompleteLedger(read) {
+    if (!read.complete || read.diagnostics.length > 0)
+        throw new Error("ledger_unavailable");
+}
+function serviceErrorCode(error) {
+    return error instanceof Error && error.message === "ledger_unavailable"
+        ? "ledger_unavailable"
+        : "semantic_pass_failed";
+}
+function safeManifest(coordRoot) {
+    try {
+        return readSemanticManifest(coordRoot);
+    }
+    catch {
+        return undefined;
+    }
+}
+function readLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (!Number.isSafeInteger(value.pid) ||
+            (value.pid ?? 0) < 1 ||
+            typeof value.host !== "string" ||
+            typeof value.nonce !== "string" ||
+            !validTimestamp(value.created_at)) {
+            return undefined;
+        }
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseOwnerIsLive(lease) {
+    if (lease.host !== hostname()) {
+        const age = Date.now() - Date.parse(lease.created_at);
+        return Number.isFinite(age) && age < FOREIGN_STATUS_STALE_MS;
+    }
+    return pidAlive(lease.pid);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function waitForLedgerWake(path, milliseconds) {
+    await new Promise((done) => {
+        let settled = false;
+        let watcher;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            watcher?.close();
+            done();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        try {
+            watcher = watch(path, { persistent: false }, finish);
+        }
+        catch {
+            // The timer is the polling fallback when the active file does not exist yet.
+        }
+    });
+}
+export function appendSemanticServiceDiagnostic(coordRoot, entry) {
+    const prepared = prepareSemanticServiceDiagnostic(entry);
+    if (coordEnv("SHARED_LOGS") !== "0") {
+        try {
+            const logger = processLogger(coordRoot, "semantic-service");
+            if (prepared.event.includes("error")) {
+                logger.error(prepared.event, legacyLogFields(prepared.fields));
+            }
+            else
+                logger.info(prepared.event, legacyLogFields(prepared.fields));
+            return "shared";
+        }
+        catch {
+            // Bootstrap failures retain the bounded legacy writer as the process fallback.
+        }
+    }
+    appendSemanticServiceLegacyLog(coordRoot, prepared.legacyEntry);
+    return "legacy";
+}
+function prepareSemanticServiceDiagnostic(entry) {
+    const event = typeof entry.event === "string" ? entry.event : "service_event";
+    const fields = { ...entry };
+    delete fields.event;
+    const legacyEntry = { ...entry, event };
+    const semanticReadings = fields.semantic_readings;
+    if (semanticReadings === undefined)
+        return { event, fields, legacyEntry };
+    if (!Array.isArray(semanticReadings))
+        throw new Error("semantic_readings must be an array");
+    const bounded = encodeBoundedLogObjectArray(semanticReadings, {
+        max_bytes: SEMANTIC_READINGS_FIELD_MAX_BYTES,
+        allowed_fields: SEMANTIC_READING_FIELDS,
+    });
+    fields.semantic_readings = bounded.json;
+    fields.semantic_readings_count = bounded.included;
+    legacyEntry.semantic_readings = JSON.parse(bounded.json);
+    legacyEntry.semantic_readings_count = bounded.included;
+    if (bounded.truncated) {
+        fields.semantic_readings_truncated = true;
+        fields.semantic_readings_omitted = bounded.omitted;
+        legacyEntry.semantic_readings_truncated = true;
+        legacyEntry.semantic_readings_omitted = bounded.omitted;
+    }
+    return { event, fields, legacyEntry };
+}
+function appendSemanticServiceLegacyLog(coordRoot, entry) {
+    const path = semanticPaths(coordRoot).log;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    appendFileSync(path, `${JSON.stringify({ schema_version: 1, ts: new Date().toISOString(), ...entry })}\n`, { encoding: "utf8", mode: 0o600 });
+    chmodSync(path, 0o600);
+    if (statSync(path).size <= MAX_LOG_BYTES)
+        return;
+    const buffer = readFileSync(path);
+    const tail = buffer.subarray(Math.max(0, buffer.length - Math.floor(MAX_LOG_BYTES / 2)));
+    const newline = tail.indexOf(10);
+    const body = newline >= 0 ? tail.subarray(newline + 1) : tail;
+    const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+    writeFileSync(temporary, body, { flag: "wx", mode: 0o600 });
+    renameSync(temporary, path);
+}
+function writePrivateJsonAtomic(path, value) {
+    const body = `${JSON.stringify(value, null, 2)}\n`;
+    if (Buffer.byteLength(body) > MAX_FILE_BYTES) {
+        throw new Error(`semantic service file exceeds ${MAX_FILE_BYTES} bytes`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(dirname(path), 0o700);
+    const temporary = `${path}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
+    writeFileSync(temporary, body, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    renameSync(temporary, path);
+    chmodSync(path, 0o600);
+}
+function validTimestamp(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function positiveInterval(value, label) {
+    if (!Number.isFinite(value) || value < 1)
+        throw new Error(`${label} must be positive`);
+    return Math.floor(value);
+}
+function delay(milliseconds) {
+    return new Promise((done) => setTimeout(done, milliseconds));
+}

package/dist/core/semantic/soak.d.ts

@@ -0,0 +1,75 @@
+import { type SemanticConfidence, type SemanticConfiguredModel, type SemanticExpressionCue, type SemanticHarness, type SemanticPhase } from "./contract.js";
+import type { SemanticOnceOutcome } from "./once.js";
+import { type SemanticUsageAggregate } from "./usage.js";
+export declare const SEMANTIC_SOAK_SCHEMA_VERSION: 1;
+export declare const SEMANTIC_SOAK_DEFAULT_MINUTES = 60;
+export declare const SEMANTIC_SOAK_REVERSAL_WINDOW_MS: number;
+export interface SemanticSoakReadingV1 {
+    subject_id: string;
+    generated_at: string;
+    source_harness: SemanticHarness;
+    configured_model: SemanticConfiguredModel;
+    resolved_model_id?: string;
+    model_attestation?: "verified" | "requested-only";
+    origin: "model-call" | "cache";
+    phase: SemanticPhase;
+    phase_confidence: SemanticConfidence;
+    expression_cue?: SemanticExpressionCue;
+    expression_confidence?: SemanticConfidence;
+}
+export interface SemanticSoakReportV1 {
+    schema_version: typeof SEMANTIC_SOAK_SCHEMA_VERSION;
+    generated_at: string;
+    window: {
+        requested_minutes: number;
+        requested_start_at: string;
+        ended_at: string;
+        available_from?: string;
+        available_through?: string;
+        window_complete: boolean;
+    };
+    service: {
+        running: boolean;
+        stale: boolean;
+    };
+    coverage: {
+        pass_count: number;
+        instrumented_pass_count: number;
+        legacy_pass_count: number;
+        accepted_reading_count: number;
+        cached_reading_count: number;
+    };
+    outcomes: SemanticUsageAggregate["outcomes"];
+    usage: SemanticUsageAggregate;
+    readings: {
+        phase_counts: Partial<Record<SemanticPhase, number>>;
+        expression_counts: Partial<Record<SemanticExpressionCue | "abstained", number>>;
+        expression_confidence_counts: Partial<Record<SemanticConfidence, number>>;
+        by_harness: Partial<Record<SemanticHarness, number>>;
+    };
+    stability: {
+        subject_count: number;
+        subjects_with_repeat_observations: number;
+        adjacent_comparisons: number;
+        unchanged_cues: number;
+        cue_changes: number;
+        rapid_reversals: number;
+        stable_repeat_rate?: number;
+        transitions: Array<{
+            from: SemanticExpressionCue | "abstained";
+            to: SemanticExpressionCue | "abstained";
+            count: number;
+        }>;
+    };
+    limitations: string[];
+}
+/**
+ * Project accepted pass outcomes into bounded log tokens. No task text, model
+ * prose, event IDs, instance IDs, or generation IDs cross this boundary.
+ */
+export declare function semanticSoakReadings(coordRootRaw: string, outcomes: readonly SemanticOnceOutcome[]): SemanticSoakReadingV1[];
+export declare function readSemanticSoakReport(coordRootRaw: string, options?: {
+    minutes?: number;
+    now?: Date;
+}): SemanticSoakReportV1;
+//# sourceMappingURL=soak.d.ts.map

package/dist/core/semantic/soak.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soak.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/soak.ts"],"names":[],"mappings":"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"}