@int-loop/core 0.2.0 → 0.3.0

package/dist/controls.d.ts

@@ -0,0 +1,9 @@
+export type Control = {
+    id: string;
+    name: string;
+    implemented_by: string;
+    phase: 1 | 2 | 3;
+    retired?: true;
+};
+export declare const CONTROLS: readonly Control[];
+export declare const CONTROL_IDS: ReadonlySet<string>;

package/dist/controls.js

@@ -0,0 +1,19 @@
+// The control catalogue. IDs are permanent: a retired control keeps its ID and
+// gains `retired`. Packs may only reference controls listed here. Lives in core so
+// evidence reports can be rebuilt offline (DECISIONS.md, 2026-11-10).
+export const CONTROLS = [
+    { id: "CTL-OVERRIDE", name: "Every request can be denied, and approvers can attach conditions", implemented_by: "Request validation (exactly one deny), approve_with_conditions", phase: 1 },
+    { id: "CTL-MORE-INFO", name: "Approvers can ask for more information before deciding", implemented_by: "more_info flow", phase: 1 },
+    { id: "CTL-FACTS-FIRST", name: "Structured facts shown before the AI-written narrative, which is labelled", implemented_by: "Approval page", phase: 1 },
+    { id: "CTL-ATTENTION", name: "Time spent and context viewed are recorded; rubber-stamp patterns flagged", implemented_by: "Evidence capture; oversight reports (Phase 2)", phase: 1 },
+    { id: "CTL-RATIONALE", name: "Written rationale captured and bound to the decision", implemented_by: "L3", phase: 1 },
+    { id: "CTL-COMPREHENSION", name: "Deterministic comprehension question answered", implemented_by: "L4", phase: 2 },
+    { id: "CTL-IDENTITY", name: "Decision bound to a passkey held by a named, enrolled person", implemented_by: "L2+ binding", phase: 1 },
+    { id: "CTL-QUORUM-2", name: "At least two distinct qualified people decide", implemented_by: "Policy quorum, L4", phase: 1 },
+    { id: "CTL-SOD", name: "The agent's owner cannot approve its requests", implemented_by: "Policy engine", phase: 1 },
+    { id: "CTL-ATTR-REQUIRED", name: "Only approvers with the required authority and current training can decide", implemented_by: "Directory attributes, stage requires", phase: 1 },
+    { id: "CTL-LEDGER", name: "Tamper-evident record anyone can verify offline", implemented_by: "Ledger, int-loop-verify", phase: 1 },
+    { id: "CTL-RETENTION", name: "Records kept for at least the strictest active floor", implemented_by: "Retention rule", phase: 1 },
+    { id: "CTL-CONTEST", name: "People affected by a decision can ask for a human to review it", implemented_by: "Contest flow", phase: 3 },
+];
+export const CONTROL_IDS = new Set(CONTROLS.map((c) => c.id));

package/dist/index.d.ts

@@ -13,6 +13,8 @@ export * from "./x509.ts";
 export * from "./tsp.ts";
 export * from "./tsa-roots.ts";
 export * from "./anchor.ts";
+export * from "./controls.ts";
+export * from "./report.ts";
 export * from "./schema/common.ts";
 export * from "./schema/request.ts";
 export * from "./schema/directory.ts";

package/dist/index.js

@@ -13,6 +13,8 @@ export * from "./x509.js";
 export * from "./tsp.js";
 export * from "./tsa-roots.js";
 export * from "./anchor.js";
+export * from "./controls.js";
+export * from "./report.js";
 export * from "./schema/common.js";
 export * from "./schema/request.js";
 export * from "./schema/directory.js";

package/dist/report.d.ts

@@ -0,0 +1,92 @@
+import { type AssuranceLevel } from "./schema/common.ts";
+import type { LedgerEntry } from "./schema/ledger.ts";
+import { Pack, type Obligation } from "./schema/pack.ts";
+export declare const REPORT_FORMAT = "int-loop.oversight-report";
+export type ReportInput = {
+    /** The tenant's ledger from entry 1, in order. Entries after `throughSeq` are ignored. */
+    entries: readonly LedgerEntry[];
+    /** Texts by hash, as the evidence pack holds them; null for an erased text. */
+    texts: ReadonlyMap<string, string | null>;
+    /** The pack to report against, as `id@version`. It must have been activated in the ledger. */
+    packRef: string;
+    /** Inclusive UTC dates, YYYY-MM-DD. */
+    period: {
+        from: string;
+        to: string;
+    };
+    generatedAt: string;
+    /** The last entry the report considers. Default: the last entry given. */
+    throughSeq?: number;
+};
+export type ControlEvidence = {
+    id: string;
+    name: string;
+    status: "available" | "not_yet_available";
+    evidence: string[];
+};
+export type ObligationSection = Pick<Obligation, "id" | "citation" | "summary" | "applies_from" | "coverage" | "coverage_note"> & {
+    controls: ControlEvidence[];
+};
+export type ReportGap = {
+    kind: string;
+    message: string;
+    seqs: number[];
+};
+export type OversightReport = {
+    format: typeof REPORT_FORMAT;
+    format_version: 1;
+    scope_statement: string[];
+    tenant_id: string;
+    generated_at: string;
+    period: {
+        from: string;
+        to: string;
+    };
+    pack: Pick<Pack, "id" | "version" | "title" | "jurisdiction" | "status" | "review" | "sources"> & {
+        ref: string;
+        hash: string;
+    };
+    ledger: {
+        through_seq: number;
+        through_hash: string;
+        period_first_seq: number | null;
+        period_last_seq: number | null;
+        /** The first anchor recorded after the period that covers its last entry, as recorded. int-loop-verify checks the tokens. */
+        anchor: {
+            anchor_seq: number;
+            anchored_seq: number;
+            tsas: string[];
+            gen_times: string[];
+        } | null;
+    };
+    policy_hashes: string[];
+    summary: {
+        requests_in_scope: number;
+        decisions_in_scope: number;
+        distinct_approvers: number;
+        outcomes: Record<string, number>;
+        assurance: Record<AssuranceLevel, number>;
+        assurance_floor: AssuranceLevel | null;
+        decisions_at_or_above_floor: number;
+        training_floor: string[];
+        training_on_decision_day: {
+            met: number;
+            not_met: number;
+            unknown: number;
+        };
+        median_time_spent_ms: number | null;
+    };
+    obligations: {
+        in_force: ObligationSection[];
+        not_yet_in_force: ObligationSection[];
+        date_to_confirm: ObligationSection[];
+    };
+    gaps: ReportGap[];
+    out_of_scope: string[];
+    notes: string[];
+};
+export declare class ReportError extends Error {
+}
+export declare function buildOversightReport(input: ReportInput): Promise<OversightReport>;
+/** Plain text, for the terminal and for reading. The JSON is the record. */
+export declare function renderReportText(r: OversightReport): string;

package/dist/report.js

@@ -0,0 +1,443 @@
+// Evidence reports (CLAUDE.md, Regulation packs; DECISIONS.md, 2026-11-10): for one
+// regulation pack and one period, each obligation's controls and the evidence the ledger
+// holds for them, the gaps found, and the ledger range the report rests on.
+//
+// A pure function of the ledger and the texts it references, so the Worker and
+// int-loop-verify build byte-identical reports: anyone holding an evidence pack can
+// rebuild a report and check it was not edited. Hard rule 11 applies to every string
+// here: the report maps controls to obligations and never says anyone meets them.
+import { CONTROLS } from "./controls.js";
+import { sha256Hex, utf8 } from "./hash.js";
+import { assuranceRank } from "./schema/common.js";
+import { DecisionCastPayload } from "./schema/decision.js";
+import { Directory, hasCurrentTraining } from "./schema/directory.js";
+import { Pack } from "./schema/pack.js";
+export const REPORT_FORMAT = "int-loop.oversight-report";
+export class ReportError extends Error {
+}
+const LEVELS = ["L1", "L2", "L3", "L4"];
+const SCOPE_STATEMENT = [
+    "This report maps int-loop controls to the obligations in the regulation pack named below, and summarises the evidence int-loop's ledger holds for them over the period.",
+    "It is not legal advice, and it is not a finding that any organisation meets these obligations. Whether it does depends on much that int-loop does not see.",
+    "It covers int-loop's own records only. Obligations listed as out of scope are not addressed by int-loop at all.",
+    "Every figure can be rebuilt from an evidence pack with int-loop-verify, and the ledger range below ties it to records anyone can check.",
+];
+const NOTES = [
+    "Requests in scope: those routed in the period under a policy that named this pack. Decisions in scope: those cast in the period that recorded this pack.",
+    "Outcomes are as of the last entry the report considers, so a request routed late in the period may still be pending.",
+    "Training is checked against the directory in force when each decision was cast, on the UTC date of the decision. Training records are evidence the customer supplies; int-loop does not assess them.",
+    "Requests that failed routing are not yet recorded in the ledger, so they do not appear here.",
+];
+const str = (v) => (typeof v === "string" ? v : null);
+const num = (v) => (typeof v === "number" ? v : null);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const day = (iso) => iso.slice(0, 10);
+/** "1 decision", "2 decisions". */
+const n = (count, one, many = `${one}s`) => `${count} ${count === 1 ? one : many}`;
+export async function buildOversightReport(input) {
+    const { period } = input;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(period.from) || !/^\d{4}-\d{2}-\d{2}$/.test(period.to) || period.from > period.to) {
+        throw new ReportError("the period must be two dates, YYYY-MM-DD, the first no later than the second");
+    }
+    const throughSeq = input.throughSeq ?? input.entries.at(-1)?.seq ?? 0;
+    const entries = input.entries.filter((e) => e.seq <= throughSeq);
+    const through = entries.at(-1);
+    if (!through || through.seq !== throughSeq)
+        throw new ReportError(`the ledger does not reach entry ${throughSeq}`);
+    const readText = async (hash, what) => {
+        const body = input.texts.get(hash);
+        if (body === undefined || body === null)
+            return null;
+        if ((await sha256Hex(utf8(body))) !== hash)
+            throw new ReportError(`${what} does not match its hash`);
+        return body;
+    };
+    // The pack, as it was activated.
+    const activation = entries.filter((e) => e.type === "pack.activated" && e.payload["ref"] === input.packRef).at(-1);
+    if (!activation)
+        throw new ReportError(`${input.packRef} was never activated in this ledger`);
+    const packHash = str(activation.payload["hash"]) ?? "";
+    const packText = await readText(packHash, `pack ${input.packRef}`);
+    if (packText === null)
+        throw new ReportError(`the text of ${input.packRef} is not available; export a fresh evidence pack`);
+    const pack = Pack.parse(JSON.parse(packText));
+    const inPeriod = (e) => day(e.recorded_at) >= period.from && day(e.recorded_at) <= period.to;
+    const periodEntries = entries.filter(inPeriod);
+    const floor = pack.floors.assurance ?? null;
+    const trainingFloor = pack.floors.approver_requires?.training ?? [];
+    // One pass over the ledger: directories in force, decisions, request states.
+    const directories = [];
+    const decisionsBySeq = new Map();
+    const scopedRequests = new Map();
+    const stateOf = new Map();
+    const scopedDecisions = [];
+    const gaps = [];
+    const unreadable = [];
+    let infoRequested = 0;
+    for (const e of entries) {
+        const p = e.payload;
+        const requestId = str(p["request_id"]);
+        switch (e.type) {
+            case "directory.changed":
+                directories.push({ seq: e.seq, hash: str(p["hash"]) ?? "" });
+                break;
+            case "request.created":
+                if (requestId)
+                    stateOf.set(requestId, { state: "pending", decisionsOnVersion: 0 });
+                break;
+            case "request.routed":
+                if (requestId && inPeriod(e) && arr(p["packs"]).includes(input.packRef)) {
+                    const r = scopedRequests.get(requestId) ?? { routed: [] };
+                    r.routed.push(p);
+                    scopedRequests.set(requestId, r);
+                }
+                break;
+            case "decision.cast": {
+                const parsed = DecisionCastPayload.safeParse(p);
+                if (!parsed.success) {
+                    if (inPeriod(e))
+                        unreadable.push(e.seq);
+                    break;
+                }
+                decisionsBySeq.set(e.seq, { approver_id: parsed.data.approver_id, request_id: parsed.data.request_id });
+                const s = stateOf.get(parsed.data.request_id);
+                if (s)
+                    s.decisionsOnVersion++;
+                if (inPeriod(e) && parsed.data.packs.includes(input.packRef))
+                    scopedDecisions.push({ entry: e, d: parsed.data });
+                break;
+            }
+            case "request.info_requested":
+                if (requestId)
+                    stateOf.set(requestId, { ...(stateOf.get(requestId) ?? { decisionsOnVersion: 0 }), state: "info_requested" });
+                if (requestId && inPeriod(e) && scopedRequests.has(requestId))
+                    infoRequested++;
+                break;
+            case "request.resolved":
+                if (requestId)
+                    stateOf.set(requestId, { ...(stateOf.get(requestId) ?? { decisionsOnVersion: 0 }), state: str(p["outcome"]) ?? "resolved" });
+                break;
+            case "request.expired":
+            case "request.cancelled":
+                if (requestId)
+                    stateOf.set(requestId, { ...(stateOf.get(requestId) ?? { decisionsOnVersion: 0 }), state: e.type === "request.expired" ? "expired" : "cancelled" });
+                break;
+        }
+    }
+    if (unreadable.length > 0)
+        gaps.push({ kind: "unreadable_decisions", message: `${n(unreadable.length, "decision entry", "decision entries")} in the period could not be read, so they are not counted.`, seqs: unreadable });
+    // Requests in scope, with their state as of the last entry considered.
+    const resolvedEntries = new Map();
+    for (const e of entries)
+        if (e.type === "request.resolved")
+            resolvedEntries.set(str(e.payload["request_id"]) ?? "", e.payload);
+    const outcomes = {};
+    let withConditions = 0;
+    let quorumTwo = 0;
+    let resolvedWithDecisions = 0;
+    let sodApplied = 0;
+    let sodWaived = 0;
+    const expiredUndecided = [];
+    const exclusions = new Map();
+    let minRetention = null;
+    const policyHashes = new Set();
+    const routedBelowFloor = [];
+    for (const [id, r] of scopedRequests) {
+        const s = stateOf.get(id) ?? { state: "pending", decisionsOnVersion: 0 };
+        outcomes[s.state] = (outcomes[s.state] ?? 0) + 1;
+        if (s.state === "expired" && s.decisionsOnVersion === 0)
+            expiredUndecided.push(id);
+        const resolved = resolvedEntries.get(id);
+        if (resolved && s.state !== "expired" && s.state !== "cancelled") {
+            if (arr(resolved["condition_hashes"]).length > 0)
+                withConditions++;
+            const deciders = new Set(arr(resolved["decision_seqs"]).map((seq) => decisionsBySeq.get(num(seq) ?? -1)?.approver_id).filter(Boolean));
+            if (deciders.size > 0)
+                resolvedWithDecisions++;
+            if (deciders.size >= 2)
+                quorumTwo++;
+        }
+        const last = r.routed.at(-1);
+        if (last["separation_of_duties"] === true)
+            sodApplied++;
+        if (arr(last["separation_of_duties_waived_by"]).length > 0)
+            sodWaived++;
+        for (const routed of r.routed) {
+            const ph = str(routed["policy_hash"]);
+            if (ph)
+                policyHashes.add(ph);
+            const retention = num(routed["retention_days"]);
+            if (retention !== null)
+                minRetention = minRetention === null ? retention : Math.min(minRetention, retention);
+            const level = str(routed["assurance"]);
+            if (floor && level && LEVELS.includes(level) && assuranceRank(level) < assuranceRank(floor))
+                routedBelowFloor.push(id);
+        }
+        for (const stage of arr(last["stages"])) {
+            for (const ex of arr(stage["excluded"])) {
+                for (const reason of arr(ex["reasons"]))
+                    if (typeof reason === "string")
+                        exclusions.set(reason, (exclusions.get(reason) ?? 0) + 1);
+            }
+        }
+    }
+    // Decisions in scope.
+    const assurance = Object.fromEntries(LEVELS.map((l) => [l, 0]));
+    const belowFloor = [];
+    const training = { met: 0, not_met: 0, unknown: 0 };
+    const trainingNotMet = [];
+    const trainingUnknown = [];
+    const directoryCache = new Map();
+    const times = [];
+    let rationale = 0;
+    let pasted = 0;
+    let comprehension = 0;
+    let comprehensionCorrect = 0;
+    let passkey = 0;
+    let documentDecisions = 0;
+    let documentEndSeen = 0;
+    const approvers = new Set();
+    for (const { entry, d } of scopedDecisions) {
+        approvers.add(d.approver_id);
+        assurance[d.assurance]++;
+        if (floor && assuranceRank(d.assurance) < assuranceRank(floor))
+            belowFloor.push(entry.seq);
+        if (d.webauthn !== null)
+            passkey++;
+        if (d.rationale !== null) {
+            rationale++;
+            if (d.rationale.paste_detected)
+                pasted++;
+        }
+        if (d.comprehension !== null) {
+            comprehension++;
+            if (d.comprehension.correct)
+                comprehensionCorrect++;
+        }
+        if (d.attention.time_spent_ms !== null)
+            times.push(d.attention.time_spent_ms);
+        if (d.attention.document_end_seen !== undefined) {
+            documentDecisions++;
+            if (d.attention.document_end_seen)
+                documentEndSeen++;
+        }
+        if (trainingFloor.length > 0) {
+            const dirRef = directories.filter((x) => x.seq < entry.seq).at(-1);
+            let dir = null;
+            if (dirRef) {
+                if (!directoryCache.has(dirRef.hash)) {
+                    const body = await readText(dirRef.hash, `directory at entry ${dirRef.seq}`);
+                    const parsed = body === null ? null : Directory.safeParse(JSON.parse(body));
+                    directoryCache.set(dirRef.hash, parsed?.success ? parsed.data : null);
+                }
+                dir = directoryCache.get(dirRef.hash) ?? null;
+            }
+            const person = dir?.people[d.approver_id];
+            if (!person) {
+                training.unknown++;
+                trainingUnknown.push(entry.seq);
+            }
+            else if (trainingFloor.every((t) => hasCurrentTraining(person, t, day(d.attention.decided_at)))) {
+                training.met++;
+            }
+            else {
+                training.not_met++;
+                trainingNotMet.push(entry.seq);
+            }
+        }
+    }
+    times.sort((a, b) => a - b);
+    const median = times.length === 0 ? null : times.length % 2 === 1 ? times[(times.length - 1) / 2] : Math.round((times[times.length / 2 - 1] + times[times.length / 2]) / 2);
+    // Gaps.
+    if (belowFloor.length > 0)
+        gaps.push({ kind: "below_assurance_floor", message: `${n(belowFloor.length, "decision")} in scope ${belowFloor.length === 1 ? "was" : "were"} made below the pack's assurance floor of ${floor}.`, seqs: belowFloor });
+    if (routedBelowFloor.length > 0)
+        gaps.push({ kind: "routed_below_floor", message: `${n(routedBelowFloor.length, "request")} in scope ${routedBelowFloor.length === 1 ? "was" : "were"} routed below the pack's assurance floor of ${floor}: ${routedBelowFloor.join(", ")}.`, seqs: [] });
+    if (trainingNotMet.length > 0)
+        gaps.push({ kind: "training_not_current", message: `In ${n(trainingNotMet.length, "decision")} in scope, the approver did not hold current ${trainingFloor.join(", ")} training on the day of the decision.`, seqs: trainingNotMet });
+    if (trainingUnknown.length > 0)
+        gaps.push({ kind: "training_unknown", message: `For ${n(trainingUnknown.length, "decision")} in scope, training could not be checked: the directory in force is erased, missing, or does not list the approver.`, seqs: trainingUnknown });
+    if (expiredUndecided.length > 0)
+        gaps.push({ kind: "expired_undecided", message: `${n(expiredUndecided.length, "request")} in scope expired before anyone decided: ${expiredUndecided.join(", ")}.`, seqs: [] });
+    const retentionFloor = pack.floors.retention_days ?? null;
+    if (retentionFloor !== null && minRetention !== null && minRetention < retentionFloor) {
+        gaps.push({ kind: "retention_below_floor", message: `Some requests in scope were routed with ${minRetention} days' retention, below the pack's floor of ${retentionFloor}.`, seqs: [] });
+    }
+    if (exclusions.size > 0) {
+        const total = [...exclusions.values()].reduce((a, b) => a + b, 0);
+        gaps.push({ kind: "approvers_excluded", message: `Approvers were excluded at routing ${n(total, "time")}. Reasons: ${[...exclusions].sort(([a], [b]) => (a < b ? -1 : 1)).map(([r, n]) => `${r} (${n})`).join("; ")}.`, seqs: [] });
+    }
+    // The anchor covering the end of the period, as recorded.
+    const lastInPeriod = periodEntries.at(-1) ?? null;
+    let anchor = null;
+    if (lastInPeriod) {
+        for (const e of entries) {
+            if (e.type !== "anchor.created" || e.seq <= lastInPeriod.seq)
+                continue;
+            const anchoredSeq = num(e.payload["anchored"]?.["seq"]);
+            if (anchoredSeq === null || anchoredSeq < lastInPeriod.seq)
+                continue;
+            const ts = arr(e.payload["timestamps"]);
+            anchor = { anchor_seq: e.seq, anchored_seq: anchoredSeq, tsas: ts.map((t) => str(t["tsa"]) ?? "?"), gen_times: ts.map((t) => str(t["gen_time"]) ?? "?") };
+            break;
+        }
+    }
+    const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+    const R = scopedRequests.size;
+    const D = scopedDecisions.length;
+    const evidenceFor = (c) => {
+        switch (c.id) {
+            case "CTL-OVERRIDE":
+                return [`Every request offers a deny option; requests without one are rejected.`, `Of ${n(R, "request")} in scope: ${outcomes["denied"] ?? 0} denied, ${withConditions} approved with conditions.`];
+            case "CTL-MORE-INFO":
+                return [`Approvers asked for more information ${n(infoRequested, "time")} on requests in scope.`];
+            case "CTL-FACTS-FIRST":
+                return ["The approval page shows the structured facts before the AI-written narrative, which is labelled as AI-written.", D === 1 ? "The decision in scope records a hash of exactly what the page displayed." : `All ${D} decisions in scope record a hash of exactly what the page displayed.`];
+            case "CTL-ATTENTION":
+                return [
+                    times.length === 0 ? "No time on page was recorded for decisions in scope." : `Time on page recorded for ${times.length} of ${n(D, "decision")}: median ${seconds(median)}, shortest ${seconds(times[0])}.`,
+                    ...(documentDecisions > 0 ? [`${documentEndSeen} of ${n(documentDecisions, "decision")} on a document recorded the end of it as seen.`] : []),
+                    "Flags for patterns that suggest rubber-stamping are not yet available.",
+                ];
+            case "CTL-RATIONALE":
+                return [`${rationale} of ${n(D, "decision")} ${D === 1 ? "carries" : "carry"} a written rationale, bound to the decision; a paste was detected in ${pasted}.`];
+            case "CTL-COMPREHENSION":
+                return [`${comprehension} of ${n(D, "decision")} answered a comprehension question built from the facts; ${comprehensionCorrect} answered correctly.`];
+            case "CTL-IDENTITY":
+                return [`${passkey} of ${n(D, "decision")} ${D === 1 ? "is" : "are"} bound to a passkey held by a named, enrolled approver.`];
+            case "CTL-QUORUM-2":
+                return [`${quorumTwo} of ${n(resolvedWithDecisions, "request")} in scope resolved by approvers ${quorumTwo === 1 ? "was" : "were"} decided by two or more distinct people.`];
+            case "CTL-SOD":
+                return [`Separation of duties applied to ${sodApplied} of ${n(R, "request")} in scope${sodWaived > 0 ? `; waived by policy for ${sodWaived}` : ""}.`];
+            case "CTL-ATTR-REQUIRED":
+                return [
+                    trainingFloor.length === 0
+                        ? "This pack sets no training requirement."
+                        : `${training.met} of ${n(D, "decision")}: the approver held current ${trainingFloor.join(", ")} training on the day. ${training.not_met} did not; ${training.unknown} could not be checked.`,
+                    `Approvers lacking a stage's required authority, spend limit or training are excluded at routing (${n([...exclusions.values()].reduce((a, b) => a + b, 0), "exclusion")} in scope).`,
+                ];
+            case "CTL-LEDGER":
+                return [
+                    lastInPeriod ? `Ledger entries ${periodEntries[0].seq} to ${lastInPeriod.seq} fall in the period, in a hash chain checked through entry ${through.seq} (${through.entry_hash}).` : "No ledger entries fall in the period.",
+                    anchor ? `Entry ${anchor.anchored_seq} is covered by the timestamp anchor at entry ${anchor.anchor_seq} (${anchor.tsas.join(", ")}).` : "No timestamp anchor yet covers the end of the period.",
+                ];
+            case "CTL-RETENTION":
+                return [
+                    `Records are kept for at least ${minRetention ?? pack.floors.retention_days ?? "the tenant's configured number of"} days${retentionFloor !== null ? `; this pack's floor is ${retentionFloor}` : ""}.`,
+                    `The ledger begins at ${day(entries[0].recorded_at)}.`,
+                ];
+            default:
+                return [];
+        }
+    };
+    const control = (id) => {
+        const c = CONTROLS.find((x) => x.id === id);
+        if (!c)
+            throw new ReportError(`${input.packRef} references an unknown control ${id}`);
+        const available = c.phase <= 2 && !c.retired;
+        return { id: c.id, name: c.name, status: available ? "available" : "not_yet_available", evidence: available ? evidenceFor(c) : ["Not yet available in int-loop."] };
+    };
+    const section = (o) => ({
+        id: o.id,
+        citation: o.citation,
+        summary: o.summary,
+        applies_from: o.applies_from,
+        coverage: o.coverage,
+        ...(o.coverage_note !== undefined ? { coverage_note: o.coverage_note } : {}),
+        controls: o.controls.map(control),
+    });
+    const obligations = { in_force: [], not_yet_in_force: [], date_to_confirm: [] };
+    for (const o of pack.obligations) {
+        const s = section(o);
+        if (o.applies_from === "confirm")
+            obligations.date_to_confirm.push(s);
+        else if (o.applies_from === "in-force" || o.applies_from <= period.to)
+            obligations.in_force.push(s);
+        else
+            obligations.not_yet_in_force.push(s);
+    }
+    for (const s of obligations.in_force) {
+        const missing = s.controls.filter((c) => c.status === "not_yet_available").map((c) => c.id);
+        if (missing.length > 0)
+            gaps.push({ kind: "control_not_available", message: `${s.citation}: ${missing.join(", ")} not yet available.`, seqs: [] });
+    }
+    return {
+        format: REPORT_FORMAT,
+        format_version: 1,
+        scope_statement: [...SCOPE_STATEMENT, ...(pack.status === "draft" ? ["This pack is a draft: its citations, dates and coverage have not been reviewed."] : [])],
+        tenant_id: through.tenant_id,
+        generated_at: input.generatedAt,
+        period: { from: period.from, to: period.to },
+        pack: { ref: input.packRef, hash: packHash, id: pack.id, version: pack.version, title: pack.title, jurisdiction: pack.jurisdiction, status: pack.status, review: pack.review, sources: pack.sources },
+        ledger: { through_seq: through.seq, through_hash: through.entry_hash, period_first_seq: periodEntries[0]?.seq ?? null, period_last_seq: lastInPeriod?.seq ?? null, anchor },
+        policy_hashes: [...policyHashes].sort(),
+        summary: {
+            requests_in_scope: R,
+            decisions_in_scope: D,
+            distinct_approvers: approvers.size,
+            outcomes: Object.fromEntries(Object.entries(outcomes).sort(([a], [b]) => (a < b ? -1 : 1))),
+            assurance,
+            assurance_floor: floor,
+            decisions_at_or_above_floor: D - belowFloor.length,
+            training_floor: trainingFloor,
+            training_on_decision_day: training,
+            median_time_spent_ms: median,
+        },
+        obligations,
+        gaps,
+        out_of_scope: pack.out_of_scope,
+        notes: NOTES,
+    };
+}
+/** Plain text, for the terminal and for reading. The JSON is the record. */
+export function renderReportText(r) {
+    const out = [];
+    const s = r.summary;
+    out.push(`int-loop evidence report: ${r.pack.title}`, `Pack ${r.pack.ref} (${r.pack.status}), period ${r.period.from} to ${r.period.to}, generated ${r.generated_at}`, "");
+    for (const line of r.scope_statement)
+        out.push(line);
+    out.push("", "SUMMARY");
+    out.push(`  Requests in scope: ${s.requests_in_scope}. Decisions in scope: ${s.decisions_in_scope}, by ${n(s.distinct_approvers, "approver")}.`);
+    out.push(`  Outcomes: ${Object.entries(s.outcomes).map(([k, v]) => `${k} ${v}`).join(", ") || "none"}.`);
+    out.push(`  Assurance: ${LEVELS.map((l) => `${l} ${s.assurance[l]}`).join(", ")}.${s.assurance_floor ? ` At or above the pack floor of ${s.assurance_floor}: ${s.decisions_at_or_above_floor} of ${s.decisions_in_scope}.` : ""}`);
+    if (s.training_floor.length > 0)
+        out.push(`  Current ${s.training_floor.join(", ")} training on the day: ${s.training_on_decision_day.met} met, ${s.training_on_decision_day.not_met} not met, ${s.training_on_decision_day.unknown} unknown.`);
+    if (s.median_time_spent_ms !== null)
+        out.push(`  Median time on page: ${(s.median_time_spent_ms / 1000).toFixed(1)}s.`);
+    const sections = [
+        ["OBLIGATIONS IN FORCE", r.obligations.in_force],
+        ["OBLIGATIONS NOT YET IN FORCE", r.obligations.not_yet_in_force],
+        ["OBLIGATIONS WITH A DATE TO CONFIRM", r.obligations.date_to_confirm],
+    ];
+    for (const [title, list] of sections) {
+        if (list.length === 0)
+            continue;
+        out.push("", title);
+        for (const o of list) {
+            out.push(`  ${o.citation} (${o.applies_from === "in-force" ? "already in force" : o.applies_from === "confirm" ? "date to confirm" : `applies from ${o.applies_from}`}; coverage: ${o.coverage}${o.coverage_note ? `, ${o.coverage_note}` : ""})`, `    ${o.summary}`);
+            for (const c of o.controls) {
+                out.push(`    ${c.id}: ${c.name}${c.status === "not_yet_available" ? " [not yet available]" : ""}`);
+                for (const e of c.evidence)
+                    out.push(`      - ${e}`);
+            }
+        }
+    }
+    out.push("", "GAPS FOUND");
+    if (r.gaps.length === 0)
+        out.push("  None found in the records for this period.");
+    for (const g of r.gaps)
+        out.push(`  - ${g.message}${g.seqs.length > 0 ? ` Ledger entries: ${g.seqs.join(", ")}.` : ""}`);
+    out.push("", "OUT OF SCOPE");
+    for (const o of r.out_of_scope)
+        out.push(`  - ${o}`);
+    out.push("", "RECORDS");
+    out.push(`  Ledger checked through entry ${r.ledger.through_seq}, hash ${r.ledger.through_hash}.`);
+    out.push(r.ledger.period_first_seq === null ? "  No entries in the period." : `  Entries in the period: ${r.ledger.period_first_seq} to ${r.ledger.period_last_seq}.`);
+    if (r.ledger.anchor)
+        out.push(`  Anchored: entry ${r.ledger.anchor.anchored_seq}, by ${r.ledger.anchor.tsas.join(", ")} at ${r.ledger.anchor.gen_times.join(", ")} (anchor entry ${r.ledger.anchor.anchor_seq}).`);
+    out.push(`  Policy versions: ${r.policy_hashes.join(", ") || "none"}.`, `  Pack hash: ${r.pack.hash}.`);
+    out.push("", "NOTES");
+    for (const n of r.notes)
+        out.push(`  - ${n}`);
+    return out.join("\n") + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@int-loop/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Schemas, canonicalisation, hashing, passkey binding and ledger and receipt verification shared by the int-loop service and int-loop-verify.",
   "license": "Apache-2.0",
   "homepage": "https://int-loop.com",