@irisrun/audit 0.1.0

package/dist/audit.d.ts

@@ -0,0 +1,37 @@
+import type { StateStore, RecordKind, EffectKind, Json } from "@irisrun/core";
+import type { ApprovalAuditEntry } from "@irisrun/auth";
+/** One journal record, audit-projected. A superset of inspect's InspectedRecord:
+ *  effect entries carry typed `effectKind`/`effectId`/`outcome` so a compliance
+ *  reader sees what each effect was, while `detail` retains the raw payload. */
+export type AuditEntry = {
+    seq: number;
+    ts: number;
+    defDigest: string;
+    kind: RecordKind;
+    effectKind?: EffectKind;
+    effectId?: string;
+    outcome?: "ok" | "error";
+    summary: string;
+    detail: Json;
+};
+export type SessionAudit = {
+    sessionId: string;
+    governingDigest: string | null;
+    terminal: "finished" | "parked" | "open";
+    complete: boolean;
+    firstRetainedSeq: number;
+    truncatedBefore: number | null;
+    snapshotUpTo: number | null;
+    records: AuditEntry[];
+    approvals: ApprovalAuditEntry[];
+    counts: {
+        effects: number;
+        results: number;
+        markers: number;
+        decisions: number;
+    };
+};
+/** Audit a recorded session over its FULL retained journal. Pure read; never writes. */
+export declare function auditSession(store: StateStore, sessionId: string): Promise<SessionAudit>;
+/** Deterministic, human-first compliance report over a SessionAudit. */
+export declare function renderAudit(audit: SessionAudit): string;

package/dist/audit.js

@@ -0,0 +1,132 @@
+// auditSession (roadmap P2-8): a whole-session, compliance-grade audit. UNLIKE
+// `inspectSession` (which reads only the POST-snapshot tail), this reads the FULL
+// retained journal from seq 0 — every effect intent/result, every marker — plus the
+// governed approval trail (via @irisrun/auth's `auditApprovals`, also full-journal).
+//
+// COMPLETENESS (the load-bearing property, LRN:gotcha d8ddf8a1): the engine snapshots
+// and TRUNCATES the journal past each boundary unless a turn ran with `keepHistory:true`.
+// A truncated session keeps only the surviving tail — so a compliance trail must report
+// `complete:false` LOUDLY (with `truncatedBefore`) rather than silently dropping
+// pre-snapshot events. `complete` ⇔ the retained journal still starts at seq 0.
+//
+// Pure over the journal bytes ⇒ re-auditing the same store is byte-identical.
+import { decode } from "@irisrun/core";
+import { auditApprovals, renderApprovalAudit } from "@irisrun/auth";
+// Deterministic one-line summary per record (mirrors @irisrun/inspect's private summarize
+// so audit and inspect renderings read alike).
+function summarize(rec) {
+    switch (rec.kind) {
+        case "effect_intent": {
+            const p = rec.payload;
+            return `effect ${p.effectKind} (intent ${p.effectId}${p.retrySafe ? "" : ", retry-unsafe"})`;
+        }
+        case "effect_result": {
+            const p = rec.payload;
+            return `result ${p.effectId} → ${p.outcome.ok ? "ok" : `error: ${p.outcome.error.message}`}`;
+        }
+        case "decision": {
+            const p = rec.payload;
+            return `decision ${p.seam} → ${p.tacticId}`;
+        }
+        case "marker": {
+            const p = rec.payload;
+            if (p.marker === "wait")
+                return `marker wait (${p.wait.kind}${p.wait.kind === "signal" ? `:${p.wait.name}` : ""})`;
+            if (p.marker === "finish")
+                return "marker finish";
+            if (p.marker === "upgraded")
+                return `marker upgraded ${p.from}→${p.to} @${p.atTurn}`;
+            if (p.marker === "snapshot")
+                return `marker snapshot upTo ${p.upToSeq}`;
+            return `marker ${p.marker}`;
+        }
+        default:
+            return rec.kind;
+    }
+}
+function toEntry(rec) {
+    const base = {
+        seq: rec.seq,
+        ts: rec.ts,
+        defDigest: rec.defDigest,
+        kind: rec.kind,
+        summary: summarize(rec),
+        detail: rec.payload,
+    };
+    if (rec.kind === "effect_intent") {
+        const p = rec.payload;
+        base.effectKind = p.effectKind;
+        base.effectId = p.effectId;
+    }
+    else if (rec.kind === "effect_result") {
+        const p = rec.payload;
+        base.effectId = p.effectId;
+        base.outcome = p.outcome.ok ? "ok" : "error";
+    }
+    return base;
+}
+function terminalOf(records) {
+    for (let i = records.length - 1; i >= 0; i--) {
+        const r = records[i];
+        if (r.kind !== "marker")
+            continue;
+        const m = r.detail.marker;
+        if (m === "finish")
+            return "finished";
+        if (m === "wait")
+            return "parked";
+    }
+    return "open";
+}
+/** Audit a recorded session over its FULL retained journal. Pure read; never writes. */
+export async function auditSession(store, sessionId) {
+    const rows = await store.readJournal(sessionId, 0); // FULL retained journal — NOT inspectSession's tail
+    const snap = await store.readLatestSnapshot(sessionId);
+    const snapshotUpTo = snap ? snap.upToSeq : null;
+    const records = rows.map((row) => toEntry(decode(row.bytes)));
+    // completeness: the retained journal still starts at seq 0 (or nothing was ever
+    // recorded). A snapshot+truncate leaves the surviving tail starting at boundary+1.
+    const firstRetainedSeq = rows.length ? rows[0].seq : snap ? snap.upToSeq + 1 : 0;
+    const complete = rows.length === 0 ? snap === null : rows[0].seq === 0;
+    const truncatedBefore = complete ? null : firstRetainedSeq;
+    const counts = { effects: 0, results: 0, markers: 0, decisions: 0 };
+    for (const r of records) {
+        if (r.kind === "effect_intent")
+            counts.effects += 1;
+        else if (r.kind === "effect_result")
+            counts.results += 1;
+        else if (r.kind === "marker")
+            counts.markers += 1;
+        else if (r.kind === "decision")
+            counts.decisions += 1;
+    }
+    const governingDigest = records.length ? records[records.length - 1].defDigest : null;
+    const approvals = await auditApprovals(store, sessionId); // full-journal approval trail
+    return {
+        sessionId,
+        governingDigest,
+        terminal: terminalOf(records),
+        complete,
+        firstRetainedSeq,
+        truncatedBefore,
+        snapshotUpTo,
+        records,
+        approvals,
+        counts,
+    };
+}
+/** Deterministic, human-first compliance report over a SessionAudit. */
+export function renderAudit(audit) {
+    const completeness = audit.complete
+        ? "COMPLETE"
+        : `PARTIAL (truncated before #${audit.firstRetainedSeq}; re-run with keepHistory:true for a complete trail)`;
+    const header = `session ${audit.sessionId} | digest ${audit.governingDigest ?? "—"} | ` +
+        `terminal ${audit.terminal} | snapshot ${audit.snapshotUpTo ?? "—"} | ` +
+        `${audit.records.length} record(s) | ${completeness} | ${audit.approvals.length} approval(s)`;
+    const lines = audit.records.map((r) => `  #${r.seq} ${r.kind} ${r.summary}`);
+    const approvalsBlock = renderApprovalAudit(audit.approvals)
+        .split("\n")
+        .map((l) => `  ${l}`)
+        .join("\n");
+    return [header, ...lines, "approvals:", approvalsBlock].join("\n");
+}

package/dist/fnv.d.ts

@@ -0,0 +1 @@
+export declare function fnv1a32hex(s: string): string;

package/dist/fnv.js

@@ -0,0 +1,11 @@
+// A tiny, pure FNV-1a (32-bit) hex hash. Used as a SHORT, deterministic fingerprint
+// for cross-host state/journal comparison — NOT a security hash. Pure (no node:crypto)
+// so @irisrun/audit stays Node-free and the digest stays compact (8 hex chars).
+export function fnv1a32hex(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return (h >>> 0).toString(16).padStart(8, "0");
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export declare const PACKAGE = "@irisrun/audit";
+export { auditSession, renderAudit } from "./audit.js";
+export type { AuditEntry, SessionAudit } from "./audit.js";
+export { verifyReplay, verifySession } from "./verify.js";
+export type { VerifyResult } from "./verify.js";
+export { fnv1a32hex } from "./fnv.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// @irisrun/audit — the audit & reproducible-eval product surface (roadmap P2-8).
+// Pure read-only projections over the existing journal; zero kernel change.
+export const PACKAGE = "@irisrun/audit";
+export { auditSession, renderAudit } from "./audit.js";
+export { verifyReplay, verifySession } from "./verify.js";
+export { fnv1a32hex } from "./fnv.js";

package/dist/verify.d.ts

@@ -0,0 +1,30 @@
+import type { Reducer, JournalRecord, StateStore, Json } from "@irisrun/core";
+export type VerifyResult = {
+    ok: boolean;
+    wellFormed: boolean;
+    replayDeterministic: boolean;
+    total: boolean;
+    finalStateDigest: string | null;
+    retainedRange: {
+        from: number;
+        to: number;
+    } | null;
+    complete: boolean;
+    issues: string[];
+};
+/** Pure verification of a fold over `startState`. `records` is the retained tail to
+ *  fold; `reducer` MUST match how the session was recorded (caller's responsibility).
+ *  `opts.rowSeqs` are the store row positions for the self-seq integrity check. */
+export declare function verifyReplay<S extends Json>(reducer: Reducer<S>, records: JournalRecord[], startState: S, opts?: {
+    complete?: boolean;
+    firstSeq?: number;
+    rowSeqs?: number[];
+}): VerifyResult;
+/** Verify a recorded session from a StateStore. Mirrors the engine's live replay
+ *  window (snapshot state + post-snapshot tail). The CALLER supplies the reducer
+ *  matching the recording config (and, for a no-snapshot session, the program
+ *  initial as `opts.startState`). */
+export declare function verifySession<S extends Json>(store: StateStore, sessionId: string, reducer: Reducer<S>, opts?: {
+    startState?: S;
+    complete?: boolean;
+}): Promise<VerifyResult>;

package/dist/verify.js

@@ -0,0 +1,104 @@
+// verifyReplay/verifySession (roadmap P2-8): offline, compliance-grade verification
+// of a recorded session. THREE SOUND GUARANTEES (and no more — honesty matters):
+//  1. structural integrity (reducer-free, the strongest claim): dense monotonic seq;
+//     each record's self-reported seq matches its store row position (corruption/
+//     desync catch); ≤1 effect_result per effectId; and — only when the journal is
+//     COMPLETE — every effect_result joins a prior effect_intent. (When the prefix
+//     was truncated, an orphan result is legitimate and NOT flagged.)
+//  2. in-process replay-determinism: fold the retained records twice and compare via
+//     canonicalEqual. This proves the reducer is a pure function of its inputs IN
+//     THIS PROCESS (catches mutable-shared-state / iteration-order bugs). It does NOT
+//     prove the reducer never read a clock/RNG at record time — that is the ONLINE
+//     `assertReplayConsistency` (engine.ts), run on every live step.
+//  3. totality: replay does not throw.
+// It deliberately does NOT claim snapshot-fidelity (that needs the original input,
+// which is not journaled for no-snapshot sessions — see the initiative decisions).
+import { replay, canonicalize, canonicalEqual, decode } from "@irisrun/core";
+import { fnv1a32hex } from "./fnv.js";
+/** Pure verification of a fold over `startState`. `records` is the retained tail to
+ *  fold; `reducer` MUST match how the session was recorded (caller's responsibility).
+ *  `opts.rowSeqs` are the store row positions for the self-seq integrity check. */
+export function verifyReplay(reducer, records, startState, opts = {}) {
+    const complete = opts.complete ?? true;
+    const structural = [];
+    const retainedRange = records.length ? { from: records[0].seq, to: records[records.length - 1].seq } : null;
+    // (a) dense, monotonic seq within the retained range
+    for (let i = 1; i < records.length; i++) {
+        if (records[i].seq !== records[i - 1].seq + 1) {
+            structural.push(`seq not dense at index ${i}: #${records[i - 1].seq} → #${records[i].seq}`);
+        }
+    }
+    // (b) each record's self-reported seq matches its store row position
+    if (opts.rowSeqs) {
+        for (let i = 0; i < records.length; i++) {
+            if (opts.rowSeqs[i] !== records[i].seq) {
+                structural.push(`self-seq mismatch at index ${i}: record #${records[i].seq} stored at row position ${opts.rowSeqs[i]}`);
+            }
+        }
+    }
+    // (c) ≤1 effect_result per effectId; (d) when complete, every result joins a prior intent
+    const seenResult = new Set();
+    const intentIds = new Set();
+    for (const r of records) {
+        if (r.kind === "effect_intent") {
+            intentIds.add(r.payload.effectId);
+        }
+        else if (r.kind === "effect_result") {
+            const id = r.payload.effectId;
+            if (seenResult.has(id))
+                structural.push(`duplicate effect_result for effectId ${id} (#${r.seq})`);
+            seenResult.add(id);
+            if (complete && !intentIds.has(id)) {
+                structural.push(`effect_result for effectId ${id} (#${r.seq}) has no prior effect_intent`);
+            }
+        }
+    }
+    const wellFormed = structural.length === 0;
+    const issues = [...structural];
+    // replay: in-process determinism (fold twice) + totality
+    let total = true;
+    let replayDeterministic = false;
+    let finalStateDigest = null;
+    try {
+        const a = replay(startState, records, reducer);
+        const b = replay(startState, records, reducer);
+        replayDeterministic = canonicalEqual(a, b);
+        if (!replayDeterministic) {
+            issues.push("replay is not deterministic: two folds of the same records produced different state (in-process reducer nondeterminism)");
+        }
+        finalStateDigest = fnv1a32hex(canonicalize(a));
+    }
+    catch (e) {
+        total = false;
+        replayDeterministic = false;
+        issues.push(`replay threw (not total): ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return {
+        ok: wellFormed && replayDeterministic && total,
+        wellFormed,
+        replayDeterministic,
+        total,
+        finalStateDigest,
+        retainedRange,
+        complete,
+        issues,
+    };
+}
+/** Verify a recorded session from a StateStore. Mirrors the engine's live replay
+ *  window (snapshot state + post-snapshot tail). The CALLER supplies the reducer
+ *  matching the recording config (and, for a no-snapshot session, the program
+ *  initial as `opts.startState`). */
+export async function verifySession(store, sessionId, reducer, opts = {}) {
+    const snap = await store.readLatestSnapshot(sessionId);
+    const snapUpTo = snap ? snap.upToSeq : -1;
+    const tailRows = await store.readJournal(sessionId, snapUpTo + 1);
+    const tail = tailRows.map((r) => decode(r.bytes));
+    const start = opts.startState ?? (snap ? decode(snap.bytes) : null);
+    let complete = opts.complete;
+    if (complete === undefined) {
+        const full = await store.readJournal(sessionId, 0);
+        complete = full.length === 0 ? snap === null : full[0].seq === 0;
+    }
+    const firstSeq = tailRows.length ? tailRows[0].seq : snapUpTo + 1;
+    return verifyReplay(reducer, tail, start, { complete, firstSeq, rowSeqs: tailRows.map((r) => r.seq) });
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@irisrun/audit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Iris audit & reproducible-eval product surface — whole-session, compliance-grade audit over the FULL retained journal (every effect/marker/approval, with completeness) plus offline replay-verification (structural integrity + in-process replay-determinism + totality). Pure: a read-only projection over the existing journal, zero kernel change. Deps @irisrun/core + @irisrun/auth only.",
+  "exports": {
+    ".": {
+      "iris-src": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@irisrun/core": "^0.1.0",
+    "@irisrun/auth": "^0.1.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xoai/iris.git",
+    "directory": "packages/audit"
+  },
+  "homepage": "https://github.com/xoai/iris#readme",
+  "files": [
+    "dist"
+  ]
+}