@llblab/pi-actors 0.43.0 → 0.44.0

package/dist/lib/runs-control-delivery.js

@@ -6,9 +6,23 @@
 import { closeSync, constants, existsSync, openSync, statSync, writeSync, } from "node:fs";
 import { createConnection } from "node:net";
 import { join } from "node:path";
+import * as Control from "./control.js";
+import * as Limits from "./limits.js";
 import { appendRunControlInStateDir, updateRunControlStatusInStateDir, } from "./runs-controls.js";
 import { readJsonFileResilient } from "./state-readers.js";
-export const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+const PREFLIGHT_CONTROL_ID = "00000000-0000-4000-8000-000000000000";
+export function encodeRunControlWire(wire) {
+    const payload = `${JSON.stringify({
+        id: wire.id,
+        action: wire.action,
+        ...(wire.input !== undefined ? { input: wire.input } : {}),
+    })}\n`;
+    const bytes = Buffer.byteLength(payload);
+    if (bytes > Limits.CONTROL_WIRE_MAX_BYTES) {
+        throw new Error(`Run Control wire record exceeds the ${Limits.CONTROL_WIRE_MAX_BYTES}-byte portable bound`);
+    }
+    return { bytes, payload };
+}
 export function readRunControlEndpoint(stateDir, runInstanceId) {
     const endpoint = readJsonFileResilient(join(stateDir, "control-endpoint.json"), {}).value;
     if (endpoint.run_instance_id !== runInstanceId)
@@ -65,34 +79,43 @@ function sendToNamedPipe(endpoint, payload, send) {
     });
 }
 export async function deliverRunControl(run, stateDir, request, options = {}) {
-    const control = appendRunControlInStateDir(stateDir, request);
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined
+        ? undefined
+        : Control.normalizeControlInput(request.input);
+    const normalizedRequest = {
+        action,
+        ...(input !== undefined ? { input } : {}),
+        run_instance_id: request.run_instance_id,
+    };
+    encodeRunControlWire({
+        id: PREFLIGHT_CONTROL_ID,
+        action,
+        ...(input !== undefined ? { input } : {}),
+    });
+    const control = appendRunControlInStateDir(stateDir, normalizedRequest);
     const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
     if (!endpoint) {
         updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: "control endpoint is not ready for this Run generation" }, ["queued", "delivered"]);
         throw Object.assign(new Error("Run Control endpoint is not ready."), {
-            action: request.action,
+            action,
             control_id: control.id,
             reason: "endpoint_not_ready",
             run,
             run_instance_id: request.run_instance_id,
         });
     }
-    const wire = {
-        id: control.id,
-        action: request.action,
-        ...(request.input !== undefined ? { input: request.input } : {}),
-    };
-    const payload = `${JSON.stringify(wire)}\n`;
-    const bytes = Buffer.byteLength(payload);
     try {
+        const { bytes, payload } = encodeRunControlWire({
+            id: control.id,
+            action,
+            ...(input !== undefined ? { input } : {}),
+        });
         let written;
         if (endpoint.type === "fifo") {
             if ((options.platform ?? process.platform) === "win32") {
                 throw new Error("FIFO Control delivery is unsupported on native Windows");
             }
-            if (bytes > FIFO_ATOMIC_CONTROL_MAX_BYTES) {
-                throw new Error(`FIFO Control payload exceeds the ${FIFO_ATOMIC_CONTROL_MAX_BYTES}-byte portable atomic-write bound`);
-            }
             written = sendToFifo(endpoint, payload);
         }
         else {
@@ -103,7 +126,7 @@ export async function deliverRunControl(run, stateDir, request, options = {}) {
         }
         updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
         return {
-            action: request.action,
+            action,
             bytes,
             control_id: control.id,
             delivery: "delivered",
@@ -116,7 +139,7 @@ export async function deliverRunControl(run, stateDir, request, options = {}) {
         const reason = error instanceof Error ? error.message : String(error);
         updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: reason }, ["queued", "delivered"]);
         throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
-            action: request.action,
+            action,
             control_id: control.id,
             endpoint_type: endpoint.type,
             reason: "delivery_failed",

package/dist/lib/runs-controls.d.ts

@@ -1,10 +1,12 @@
 /**
  * Run Control journal.
- * Zones: durable Control records, claim locks, status transitions, bounded compaction
- * Owns Run-local Control persistence; owner/generation authorization and transport delivery stay in lifecycle adapters.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
  */
-export declare const RUN_CONTROL_TERMINAL_LIMIT = 128;
-export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+import { type RunControlStatus } from "./run-evidence-policy.ts";
+import type { JsonlReadResult } from "./state-readers.ts";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.ts";
+export type { RunControlStatus } from "./run-evidence-policy.ts";
 export interface RunControlRecord {
     id: string;
     run_instance_id: string;
@@ -24,6 +26,7 @@ export interface ProcessRunControlsResult {
     handled: number;
 }
 export declare function runControlsFile(stateDir: string): string;
+export declare function readRunControlJournalFromStateDir(stateDir: string): JsonlReadResult<unknown>;
 export declare function readRunControlsFromStateDir(stateDir: string): RunControlRecord[];
 export declare function appendRunControlInStateDir(stateDir: string, request: {
     run_instance_id: string;
@@ -32,4 +35,5 @@ export declare function appendRunControlInStateDir(stateDir: string, request: {
 }): RunControlRecord;
 export declare function updateRunControlStatusInStateDir(stateDir: string, id: string, nextStatus: RunControlStatus, metadata?: Pick<RunControlRecord, "error">, expectedStatuses?: readonly RunControlStatus[]): boolean;
 export declare function claimRunControlInStateDir(stateDir: string, runInstanceId: string): RunControlRecord | undefined;
+export declare function claimRunControlByIdInStateDir(stateDir: string, runInstanceId: string, controlId: string): RunControlRecord | undefined;
 export declare function processRunControlsInStateDir(stateDir: string, runInstanceId: string, handler: (control: RunControlRecord) => Promise<void> | void, limit?: number): Promise<ProcessRunControlsResult>;

package/dist/lib/runs-controls.js

@@ -1,67 +1,210 @@
 /**
  * Run Control journal.
- * Zones: durable Control records, claim locks, status transitions, bounded compaction
- * Owns Run-local Control persistence; owner/generation authorization and transport delivery stay in lifecycle adapters.
+ * Zones: durable records, atomic admission, claims, transitions, compaction
+ * Owns Run-local Control persistence; lifecycle authorization and transport stay in adapters.
  */
 import { randomUUID } from "node:crypto";
-import { writeFileSync } from "node:fs";
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
 import { join } from "node:path";
+import * as Control from "./control.js";
 import { acquireFileMutationLock, writeTextAtomic } from "./file-state.js";
-import { readJsonlFileResilient } from "./state-readers.js";
-export const RUN_CONTROL_TERMINAL_LIMIT = 128;
-const TERMINAL_STATUSES = new Set(["handled", "failed"]);
+import * as Limits from "./limits.js";
+import { classifyRunControlRecord, computeRunControlCapacity, decideRunControlAdmission, runControlStatusTimestamp, } from "./run-evidence-policy.js";
+export { RUN_CONTROL_TERMINAL_LIMIT } from "./limits.js";
+function admissionError(details) {
+    return Object.assign(new Error(details.reason === "control_backpressure"
+        ? `Run Control admission backpressured: pending=${details.pending}/${details.limit}`
+        : `Run Control journal integrity failed: ${details.integrity_reason ?? "unknown"}`), details);
+}
+const STATUSES = new Set([
+    "queued", "delivered", "claimed", "handled", "failed",
+]);
 export function runControlsFile(stateDir) {
     return join(stateDir, "controls.jsonl");
 }
+export function readRunControlJournalFromStateDir(stateDir) {
+    const path = runControlsFile(stateDir);
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { diagnostics: [], records: [] };
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    try {
+        const bytes = fstatSync(fd).size;
+        if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+            return { diagnostics: [{ message: "Run Control journal exceeds bounded read limit", path }], records: [] };
+        }
+        const buffer = Buffer.allocUnsafe(bytes);
+        let consumed = 0;
+        while (consumed < bytes) {
+            const count = readSync(fd, buffer, consumed, bytes - consumed, consumed);
+            if (count === 0)
+                return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+            consumed += count;
+        }
+        if (fstatSync(fd).size !== bytes)
+            return { diagnostics: [{ message: "Run Control journal changed during bounded read", path }], records: [] };
+        const records = [];
+        const diagnostics = [];
+        for (const [index, line] of buffer.toString("utf8").split("\n").entries()) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch (error) {
+                diagnostics.push({ line: index + 1, message: String(error), path });
+            }
+        }
+        return { diagnostics, records };
+    }
+    catch (error) {
+        return { diagnostics: [{ message: String(error), path }], records: [] };
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 export function readRunControlsFromStateDir(stateDir) {
-    return readJsonlFileResilient(runControlsFile(stateDir))
-        .records;
+    return readRunControlJournalFromStateDir(stateDir).records;
 }
 function acquireRunControlsLock(stateDir) {
     return acquireFileMutationLock(runControlsFile(stateDir));
 }
 function compactRunControls(records) {
-    const active = records.filter((record) => !TERMINAL_STATUSES.has(record.status));
-    const terminal = records
-        .filter((record) => TERMINAL_STATUSES.has(record.status))
-        .slice(-RUN_CONTROL_TERMINAL_LIMIT);
+    const active = records.filter((record) => classifyRunControlRecord(record) !== "terminal");
+    const terminal = records.filter((record) => classifyRunControlRecord(record) === "terminal")
+        .slice(-Limits.RUN_CONTROL_TERMINAL_LIMIT);
     const retained = new Set([...active, ...terminal]);
-    return records.filter((record) => retained.has(record));
+    return records.filter((record) => retained.has(record)).map((record) => typeof record.error === "string" && Buffer.byteLength(record.error) > Limits.RUN_CONTROL_ERROR_MAX_BYTES
+        ? { ...record, error: boundedControlError(record.error) } : record);
+}
+function encodeRunControls(records) {
+    return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
+}
+function boundedControlError(value) {
+    if (Buffer.byteLength(value) <= Limits.RUN_CONTROL_ERROR_MAX_BYTES)
+        return value;
+    const suffix = "… [truncated]";
+    const limit = Limits.RUN_CONTROL_ERROR_MAX_BYTES - Buffer.byteLength(suffix);
+    const bytes = Buffer.from(value);
+    let end = limit;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end -= 1;
+    return `${bytes.subarray(0, end).toString("utf8")}${suffix}`;
 }
 function writeRunControls(stateDir, records) {
-    const compacted = compactRunControls(records);
-    writeTextAtomic(runControlsFile(stateDir), compacted.length
-        ? `${compacted.map((record) => JSON.stringify(record)).join("\n")}\n`
-        : "");
+    const encoded = encodeRunControls(compactRunControls(records));
+    if (Buffer.byteLength(encoded) > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES) {
+        throw new Error("Run Control journal transition exceeds bounded byte limit");
+    }
+    writeTextAtomic(runControlsFile(stateDir), encoded);
+}
+function readMutableRunControls(stateDir, runInstanceId) {
+    const journal = readRunControlJournalFromStateDir(stateDir);
+    if (journal.diagnostics.length)
+        return undefined;
+    const records = journal.records;
+    if (runInstanceId && records.some((record) => controlIntegrity(record, runInstanceId) !== "valid"))
+        return undefined;
+    return records;
+}
+function controlIntegrity(value, runInstanceId) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "invalid_record";
+    const record = value;
+    if (typeof record.id !== "string" || !record.id ||
+        typeof record.run_instance_id !== "string" || !record.run_instance_id ||
+        typeof record.status !== "string" || !STATUSES.has(record.status) ||
+        (record.error !== undefined && typeof record.error !== "string"))
+        return "invalid_record";
+    try {
+        Control.normalizeControlAction(record.action);
+        if (record.input !== undefined)
+            Control.normalizeControlInput(record.input);
+    }
+    catch {
+        return "invalid_record";
+    }
+    const timestamp = runControlStatusTimestamp(record, record.status);
+    if (typeof timestamp !== "string" || !Number.isFinite(Date.parse(timestamp)))
+        return "invalid_status_timestamp";
+    if (classifyRunControlRecord(record) === "pending" &&
+        record.run_instance_id !== runInstanceId)
+        return "generation_mismatch";
+    return "valid";
 }
 export function appendRunControlInStateDir(stateDir, request) {
+    const action = Control.normalizeControlAction(request.action);
+    const input = request.input === undefined ? undefined : Control.normalizeControlInput(request.input);
     const record = {
         id: randomUUID(),
         run_instance_id: request.run_instance_id,
-        action: request.action,
-        ...(request.input !== undefined ? { input: request.input } : {}),
+        action,
+        ...(input !== undefined ? { input } : {}),
         status: "queued",
         queued_at: new Date().toISOString(),
     };
+    const encodedRecordBytes = Buffer.byteLength(`${JSON.stringify(record)}\n`);
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        writeFileSync(runControlsFile(stateDir), `${JSON.stringify(record)}\n`, {
-            flag: "a",
+        const path = runControlsFile(stateDir);
+        let bytes = 0;
+        try {
+            bytes = statSync(path).size;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                bytes = Number.MAX_SAFE_INTEGER;
+        }
+        const journal = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? { diagnostics: [], records: [] } : readRunControlJournalFromStateDir(stateDir);
+        let integrity = bytes > Limits.RUN_CONTROL_JOURNAL_MAX_BYTES
+            ? "journal_bytes"
+            : journal.diagnostics.some((item) => item.line !== undefined)
+                ? "malformed"
+                : journal.diagnostics.length ? "unreadable" : "valid";
+        for (const value of journal.records) {
+            if (integrity !== "valid")
+                break;
+            integrity = controlIntegrity(value, request.run_instance_id);
+        }
+        const records = journal.records;
+        const retained = encodeRunControls(compactRunControls(records));
+        const decision = decideRunControlAdmission({
+            integrity,
+            journalBytes: bytes,
+            newRecordBytes: encodedRecordBytes,
+            records,
+            retainedJournalBytes: Buffer.byteLength(retained),
+            runInstanceId: request.run_instance_id,
+            capacity: computeRunControlCapacity(records),
         });
+        if (!decision.admitted)
+            throw admissionError(decision.error);
+        writeTextAtomic(path, `${retained}${JSON.stringify(record)}\n`);
+        return record;
     }
     finally {
         releaseLock();
     }
-    return record;
 }
 export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metadata = {}, expectedStatuses) {
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        const records = readRunControlsFromStateDir(stateDir);
+        const records = readMutableRunControls(stateDir);
+        if (!records)
+            return false;
         const index = records.findIndex((record) => record.id === id);
         if (index < 0)
             return false;
         const record = records[index];
+        if (records.some((value) => controlIntegrity(value, record.run_instance_id) !== "valid"))
+            return false;
         if (expectedStatuses && !expectedStatuses.includes(record.status))
             return false;
         if (record.status === nextStatus)
@@ -70,28 +213,19 @@ export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metad
         if (nextStatus === "delivered") {
             if (record.delivered_at)
                 return false;
-            records[index] = {
-                ...record,
-                delivered_at: timestamp,
-                ...(record.status === "queued" ? { status: "delivered" } : {}),
-            };
+            records[index] = { ...record, delivered_at: timestamp,
+                ...(record.status === "queued" ? { status: "delivered" } : {}) };
         }
         else {
-            if (TERMINAL_STATUSES.has(record.status) || nextStatus === "queued")
+            if (classifyRunControlRecord(record) === "terminal" || nextStatus === "queued")
                 return false;
-            if ((nextStatus === "claimed" &&
-                record.status !== "queued" &&
+            if ((nextStatus === "claimed" && record.status !== "queued" &&
                 record.status !== "delivered") ||
-                (nextStatus === "handled" && record.status !== "claimed")) {
+                (nextStatus === "handled" && record.status !== "claimed"))
                 return false;
-            }
-            const timestampKey = `${nextStatus}_at`;
-            records[index] = {
-                ...record,
-                ...metadata,
-                [timestampKey]: timestamp,
-                status: nextStatus,
-            };
+            records[index] = { ...record,
+                ...(metadata.error !== undefined ? { error: boundedControlError(metadata.error) } : {}),
+                [`${nextStatus}_at`]: timestamp, status: nextStatus };
         }
         writeRunControls(stateDir, records);
         return true;
@@ -100,18 +234,19 @@ export function updateRunControlStatusInStateDir(stateDir, id, nextStatus, metad
         releaseLock();
     }
 }
-export function claimRunControlInStateDir(stateDir, runInstanceId) {
+function claimRunControl(stateDir, runInstanceId, controlId) {
     const releaseLock = acquireRunControlsLock(stateDir);
     try {
-        const records = readRunControlsFromStateDir(stateDir);
-        const index = records.findIndex((record) => record.run_instance_id === runInstanceId &&
+        const records = readMutableRunControls(stateDir, runInstanceId);
+        if (!records)
+            return undefined;
+        const index = records.findIndex((record) => (controlId === undefined || record.id === controlId) &&
+            record.run_instance_id === runInstanceId &&
             (record.status === "queued" || record.status === "delivered"));
         if (index < 0)
             return undefined;
         const claimed = {
-            ...records[index],
-            claimed_at: new Date().toISOString(),
-            status: "claimed",
+            ...records[index], claimed_at: new Date().toISOString(), status: "claimed"
         };
         records[index] = claimed;
         writeRunControls(stateDir, records);
@@ -121,6 +256,12 @@ export function claimRunControlInStateDir(stateDir, runInstanceId) {
         releaseLock();
     }
 }
+export function claimRunControlInStateDir(stateDir, runInstanceId) {
+    return claimRunControl(stateDir, runInstanceId);
+}
+export function claimRunControlByIdInStateDir(stateDir, runInstanceId, controlId) {
+    return claimRunControl(stateDir, runInstanceId, controlId);
+}
 export async function processRunControlsInStateDir(stateDir, runInstanceId, handler, limit = 1) {
     const result = { claimed: 0, failed: 0, handled: 0 };
     for (let index = 0; index < Math.max(1, limit); index += 1) {
@@ -130,14 +271,12 @@ export async function processRunControlsInStateDir(stateDir, runInstanceId, hand
         result.claimed += 1;
         try {
             await handler(control);
-            if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"])) {
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"]))
                 result.handled += 1;
-            }
         }
         catch (error) {
-            if (updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: error instanceof Error ? error.message : String(error) }, ["claimed"])) {
+            if (updateRunControlStatusInStateDir(stateDir, control.id, "failed", { error: error instanceof Error ? error.message : String(error) }, ["claimed"]))
                 result.failed += 1;
-            }
         }
     }
     return result;

package/dist/lib/runs-retention.js

@@ -3,9 +3,11 @@
  * Owns: terminal-run archive and prune filesystem behavior.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { acquireFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import { acquireFileMutationLock, writeJsonAtomic, writeTextAtomic } from "./file-state.js";
+import * as Limits from "./limits.js";
+import { readJsonlFileResilient } from "./state-readers.js";
 import { resolveArtifactManifest, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
@@ -13,26 +15,37 @@ export function appendRunRetentionEvidence(status, action, outcome, options = {}
     const stateDir = String(status.state_dir);
     const path = join(dirname(stateDir), "retention.jsonl");
     const id = options.id ?? randomUUID();
+    const record = {
+        action,
+        ...(options.error ? { error: options.error } : {}),
+        id,
+        outcome,
+        ...(options.result ? { result: options.result } : {}),
+        run: String(status.run ?? basename(stateDir)),
+        ...(typeof status.run_instance_id === "string" ? { run_instance_id: status.run_instance_id } : {}),
+        ts: new Date().toISOString(),
+    };
     const release = acquireFileMutationLock(path);
     try {
-        appendFileSync(path, `${JSON.stringify({
-            action,
-            ...(options.error ? { error: options.error } : {}),
-            id,
-            outcome,
-            ...(options.result ? { result: options.result } : {}),
-            run: String(status.run ?? basename(stateDir)),
-            ...(typeof status.run_instance_id === "string"
-                ? { run_instance_id: status.run_instance_id }
-                : {}),
-            ts: new Date().toISOString(),
-        })}\n`);
+        const records = [...readJsonlFileResilient(path).records, record]
+            .slice(-Limits.RUN_RETENTION_MAX_RECORDS);
+        let content = encodeRecords(records);
+        while (records.length && Buffer.byteLength(content) > Limits.RUN_RETENTION_MAX_BYTES) {
+            records.shift();
+            content = encodeRecords(records);
+        }
+        if (!records.includes(record))
+            throw new Error("Run retention record exceeds journal byte limit");
+        writeTextAtomic(path, content);
     }
     finally {
         release();
     }
     return id;
 }
+function encodeRecords(records) {
+    return records.length ? `${records.map((value) => JSON.stringify(value)).join("\n")}\n` : "";
+}
 function retainedArtifactFilename(name, path) {
     const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
     const identity = createHash("sha256")

package/dist/lib/runs-trace.d.ts

@@ -1,8 +1,9 @@
 /**
  * Run Trace event journal.
- * Zones: structured event validation, bounded append, resilient bounded reads
- * Owns Run-local semantic Trace events; lifecycle projection and owner attention delivery stay in adapters.
+ * Zones: structured event validation, bounded atomic retention, resilient reads
+ * Owns canonical Run-local Trace persistence; lifecycle projection and owner attention delivery stay in adapters.
  */
+import type { StateReadDiagnostic } from "./state-readers.ts";
 export interface TraceEvent {
     id: string;
     ts: string;
@@ -19,6 +20,29 @@ export interface AppendTraceEventInput {
     level?: TraceEvent["level"];
     attention?: TraceEvent["attention"];
 }
+export interface RunTraceReadEvent {
+    event: TraceEvent;
+    ordinal: number;
+}
+export interface RunTraceJournalRead {
+    diagnostics: StateReadDiagnostic[];
+    events: RunTraceReadEvent[];
+    fileBytes: number;
+    omittedPrefixBytes: number;
+    readBytes: number;
+}
+export interface RunTraceSummary {
+    compacted: boolean;
+    compactions_total: number;
+    dropped_bytes: number;
+    dropped_event_count_exact: boolean;
+    dropped_events: number;
+    history_complete: boolean;
+    retained_bytes: number;
+    retained_events: number;
+}
 export declare function runTraceFile(stateDir: string): string;
 export declare function appendRunTraceEvent(stateDir: string, input: AppendTraceEventInput): TraceEvent;
+export declare function readRunTraceJournal(stateDir: string): RunTraceJournalRead;
+export declare function summarizeRunTraceJournal(read: RunTraceJournalRead): RunTraceSummary;
 export declare function readRunTraceEvents(stateDir: string, limit?: number): TraceEvent[];