oh-my-super-agent 0.1.0

package/dist/src/audit/run-ledger.d.ts

@@ -0,0 +1,183 @@
+import { type CanonicalRunCertificationReference, type RunCertificationAuthorityReference, type RunCertificationAuthorityResolver } from "../outbox/store.js";
+import { type RecoveredLock } from "../runtime/lock.js";
+declare const RUN_LEDGER: unique symbol;
+declare const AUDIT_RUN_TERMINAL_WRITER: unique symbol;
+declare const LIVE_RUN_WRITER: unique symbol;
+declare const RUN_CERTIFICATION_SNAPSHOT: unique symbol;
+export type RunKind = "12h" | "24h" | "until-empty";
+export type RunClockClass = "live" | "synthetic";
+export type RunProvenanceClass = "audit" | "trusted-live";
+export type RunEntryKind = "run-started" | "heartbeat" | "session-started" | "session-stopped" | "session-stalled" | "process-restarted" | "ticket-transition" | "quota-parked" | "quota-resumed" | "lease-recovered" | "controller-lock-recovered" | "outbox-lock-recovered" | "live-call-observed" | "run-completed" | "run-aborted";
+export interface RunLedgerEntry {
+    readonly schema_version: 1;
+    readonly entry_id: string;
+    readonly run_id: string;
+    readonly sequence: number;
+    readonly entry_kind: RunEntryKind;
+    readonly run_kind: RunKind;
+    readonly operation_id: string;
+    readonly operation_sha256: string;
+    readonly policy_sha256: string;
+    readonly clock_class: RunClockClass;
+    readonly provenance_class: RunProvenanceClass;
+    readonly recorded_at: string;
+    readonly monotonic_ns: string;
+    readonly process_id: number;
+    readonly process_instance_id: string;
+    readonly boot_id: string;
+    readonly previous_entry_sha256: string | null;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+export interface RunLedgerEntryReference {
+    readonly entry_id: string;
+    readonly run_id: string;
+    readonly sequence: number;
+    readonly sha256: string;
+    readonly file_name: string;
+}
+export interface StartRunInput {
+    readonly operationId: string;
+    readonly runKind: RunKind;
+    readonly policyDigest: string;
+    readonly ticketSetDigest: string;
+    readonly servicePlanDigest: string;
+}
+export interface AppendRunEntryInput {
+    readonly runId: string;
+    readonly operationId: string;
+    readonly entryKind: Exclude<RunEntryKind, "run-started">;
+    readonly payload: Record<string, unknown>;
+}
+export interface AppendRunEntryAtHeadInput extends AppendRunEntryInput {
+    readonly expectedHeadSha256: string;
+}
+export interface RunLedgerWriteResult {
+    readonly status: "created" | "replayed";
+    readonly ref: RunLedgerEntryReference;
+    readonly entry: RunLedgerEntry;
+}
+export interface RunLedgerMetrics {
+    readonly run_id: string;
+    readonly run_kind: RunKind;
+    readonly policy_sha256: string;
+    readonly clock_class: RunClockClass;
+    readonly certifying: boolean;
+    readonly status: "running" | "completed" | "aborted";
+    readonly started_at: string;
+    readonly ended_at: string | null;
+    readonly elapsed_ms: number;
+    readonly monotonic_elapsed_ms: number;
+    readonly entry_count: number;
+    readonly heartbeat_count: number;
+    readonly max_heartbeat_gap_ms: number;
+    readonly recovery_count: number;
+    readonly quota_park_count: number;
+    readonly quota_resume_count: number;
+    readonly restart_count: number;
+    readonly restart_continuity_valid: boolean;
+    readonly metrics_sha256: string;
+    readonly process_instance_ids: readonly string[];
+    readonly ticket_set_digest: string;
+    readonly service_plan_digest: string;
+    readonly head: RunLedgerEntryReference;
+}
+export interface RunLedgerStore {
+    readonly [RUN_LEDGER]: true;
+    start(input: StartRunInput): RunLedgerWriteResult;
+    append(input: AppendRunEntryInput): RunLedgerWriteResult;
+    appendAtHead(input: AppendRunEntryAtHeadInput): RunLedgerWriteResult;
+    read(ref: RunLedgerEntryReference): RunLedgerEntry;
+    list(runId: string): readonly RunLedgerEntry[];
+    listRunIds(): readonly string[];
+    head(runId: string): RunLedgerEntryReference | undefined;
+    deriveMetrics(head: RunLedgerEntryReference): RunLedgerMetrics;
+}
+export interface AuditRunTerminalWriter {
+    readonly [AUDIT_RUN_TERMINAL_WRITER]: true;
+    appendAtHead(input: AppendRunEntryAtHeadInput & {
+        readonly entryKind: "run-completed" | "run-aborted";
+    }): RunLedgerWriteResult;
+}
+export interface RunCertificationReference extends CanonicalRunCertificationReference {
+    readonly run_id: string;
+    readonly head: RunLedgerEntryReference;
+    readonly metrics_sha256: string;
+}
+export interface StartLiveRunInput extends StartRunInput {
+    readonly source: RunCertificationAuthorityReference;
+    readonly previousCanary: RunCertificationReference | null;
+}
+export interface LiveRunEventInput {
+    readonly runId: string;
+    readonly operationId: string;
+    readonly source: RunCertificationAuthorityReference;
+}
+export interface CompleteLiveRunInput extends LiveRunEventInput {
+    readonly expectedRunKind: "12h" | "24h";
+}
+export interface LiveRunWriter {
+    readonly [LIVE_RUN_WRITER]: true;
+    start(input: StartLiveRunInput): RunLedgerWriteResult;
+    heartbeat(input: LiveRunEventInput): RunLedgerWriteResult;
+    recordProcessRestart(input: LiveRunEventInput): RunLedgerWriteResult;
+    recordLockRecovery(input: {
+        readonly runId: string;
+        readonly operationId: string;
+        readonly recovery: RecoveredLock;
+    }): RunLedgerWriteResult;
+    complete(input: CompleteLiveRunInput): RunCertificationSnapshot;
+    certify(head: RunLedgerEntryReference): RunCertificationSnapshot;
+}
+export interface RunCertificationSnapshot {
+    readonly [RUN_CERTIFICATION_SNAPSHOT]: true;
+    readonly reference: RunCertificationReference;
+    readonly entry: RunLedgerEntry;
+    readonly metrics: RunLedgerMetrics;
+}
+export interface NonCertifyingClock {
+    sample(): {
+        wallTime: string;
+        monotonicNs: bigint;
+    };
+}
+export interface RunContinuitySample {
+    readonly entryKind: RunEntryKind;
+    readonly recordedAt: string;
+    readonly monotonicNs: string;
+    readonly processInstanceId: string;
+    readonly bootId: string;
+}
+export interface RunContinuityAnalysis {
+    readonly elapsedMs: number;
+    readonly monotonicElapsedMs: number;
+    readonly restartCount: number;
+    readonly restartContinuityValid: boolean;
+    readonly processInstanceIds: readonly string[];
+}
+export declare class RunLedgerConflictError extends Error {
+    constructor(operationId: string);
+}
+export declare function createLiveRunLedger(options: {
+    ledgerRoot: string;
+    locksRoot: string;
+    packageRoot?: string;
+}): RunLedgerStore;
+export declare function createNonCertifyingRunLedger(options: {
+    ledgerRoot: string;
+    locksRoot: string;
+    clock: NonCertifyingClock;
+    packageRoot?: string;
+}): RunLedgerStore;
+export declare function assertRunLedger(value: unknown): asserts value is RunLedgerStore;
+export declare function createAuditRunTerminalWriter(ledger: RunLedgerStore): AuditRunTerminalWriter;
+export declare function assertAuditRunTerminalWriter(value: unknown): asserts value is AuditRunTerminalWriter;
+/** Generic ledgers are deliberately audit-only, including live-clock ledgers. */
+export declare function assertCertifyingRunLedger(_value: unknown, _head: RunLedgerEntryReference): never;
+export declare function createLiveRunWriter(options: {
+    ledger: RunLedgerStore;
+    authority: RunCertificationAuthorityResolver;
+}): LiveRunWriter;
+export declare function assertLiveRunWriter(value: unknown): asserts value is LiveRunWriter;
+export declare function assertRunCertificationSnapshot(value: unknown): asserts value is RunCertificationSnapshot;
+export declare function analyzeRunContinuity(samples: readonly RunContinuitySample[]): RunContinuityAnalysis;
+export {};