@polydeukes/core 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @polydeukes/core — the thin, domain- and agent-agnostic core.
+ *
+ * Pre-alpha. The covenant protocol (CORE-01) landed first, then the ROI telemetry
+ * collector (CORE-02) and the config loader (CONFIG-01). Pure types and functions,
+ * except telemetry's confined I/O functions (appendRecord / readRecords /
+ * appendRecordFailOpen — the fail-open wrapper promoted by CORE-05).
+ * See https://github.com/huskyhoochu/polydeukes
+ */
+export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, type DisciplineEntry, type DisciplineForbid, defineConfig, type LanguageProfile, type PolydeukesConfig, type ResolvedConfig, type ResolvedLanguageProfile, } from './config.js';
+export { type FailMode, type FailureKind, failModeToExitCode, resolveFailMode, } from './fail-policy.js';
+export { isPlainObject } from './is-plain-object.js';
+export { normalizeProtectedPaths } from './protected-paths.js';
+export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, type GainSummary, parseRecordLine, readRecords, runGain, type TelemetryEvent, type TelemetryRecord, } from './telemetry.js';
+export { type CanonicalTranscript, noopTranscript, type SubagentInvocation, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, } from './transcript.js';
+/**
+ * exit-code semantics of the covenant protocol (PRD §4.1).
+ *
+ * The three codes are distinct and ordered by severity. The covenant *body* only
+ * ever emits `0` (uphold) or `1` (break, non-blocking); translating a break into the
+ * blocking `2` is the wrapper's job (COVENANT-01), never the core's. The sole place
+ * the core itself reaches for `2` is the fail-closed parse path below.
+ */
+/** Promise upheld — no violation, the edit/push passes. */
+export declare const EXIT_UPHOLD = 0;
+/** Violation reported as a non-blocking signal. The covenant body's break code. */
+export declare const EXIT_BREAK_NON_BLOCKING = 1;
+/** Violation blocked — the edit/push is refused. Reserved for the wrapper / fail-closed. */
+export declare const EXIT_BREAK_BLOCKING = 2;
+/**
+ * `FileChange` — one file's mutation evidence around the judged call (CORE-06 §4.1).
+ *
+ * Agent-neutral, discriminated by `kind`: a deletion is first-class evidence rather
+ * than an unrepresentable case, and impossible states (a deletion with resulting
+ * content, a creation with a baseline) cannot be written down. Adapters fill this from
+ * their own sources (virtual apply, git blobs) — the core only transports it.
+ * `delete.pre` is the readable text baseline when one exists — absent for a binary
+ * blob, because a deletion needs no content to be judged.
+ */
+export type FileChange = {
+    kind: 'create';
+    path: string;
+    post: string;
+} | {
+    kind: 'modify';
+    path: string;
+    pre: string;
+    post: string;
+} | {
+    kind: 'delete';
+    path: string;
+    pre?: string;
+};
+/**
+ * `CovenantInput` — the agent-neutral input IR a covenant judges (PRD §4.2).
+ *
+ * Adapters up-translate their own agent payloads into this shape and pipe it as
+ * stdin-JSON. The vocabulary carries no agent/tool literals; concrete tool or
+ * subagent names are *values* an adapter fills in, never part of the core's type.
+ * Evidence has exactly one home — the call element it belongs to (CORE-06 §4.1):
+ * `fileChange` absent means "this call is unproven", and no sibling call's evidence
+ * can stand in for it.
+ */
+export type CovenantInput = {
+    toolCalls: {
+        name: string;
+        args?: Record<string, unknown>;
+        fileChange?: FileChange;
+    }[];
+    subagentSpawns: {
+        kind: string;
+    }[];
+    userMessages: {
+        text: string;
+    }[];
+};
+/**
+ * `CovenantVerdict` — the result a covenant body produces (PRD §4.3).
+ *
+ * Either the promise was upheld, or it was broken with a human-readable reason.
+ * Maps to an exit code via {@link verdictToExitCode}.
+ */
+export type CovenantVerdict = {
+    upheld: true;
+} | {
+    upheld: false;
+    reason: string;
+};
+/**
+ * Deserialize stdin-JSON into a {@link CovenantInput} (the protocol's reverse direction).
+ *
+ * fail-closed (PRD §5.2): this never throws. Any failure — unparseable JSON, an empty
+ * payload, a parsed value that is not an object, or a missing required collection —
+ * resolves to a blocking `{ ok: false, exitCode: 2 }`. "Cannot judge" means block,
+ * so an unjudgeable input can never be mistaken for a valid one.
+ */
+export declare function parseInput(stdinJson: string): {
+    ok: true;
+    value: CovenantInput;
+} | {
+    ok: false;
+    exitCode: 2;
+};
+/**
+ * Flatten every call's evidence into one array in call order (CORE-06 §4.1).
+ *
+ * The one traversal for consumers that need no attribution (discipline scope, delta
+ * judging): calls without evidence are skipped, never substituted for.
+ */
+export declare function allFileChanges(input: CovenantInput): FileChange[];
+/**
+ * Map a {@link CovenantVerdict} to an exit code (the protocol's forward direction).
+ *
+ * Responsibility boundary (PRD §4.1): the body emits `0` when upheld and `1` when
+ * broken — never the blocking `2`. Translating `1` into `2` is the wrapper's policy.
+ */
+export declare function verdictToExitCode(verdict: CovenantVerdict): 0 | 1;

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * @polydeukes/core — the thin, domain- and agent-agnostic core.
+ *
+ * Pre-alpha. The covenant protocol (CORE-01) landed first, then the ROI telemetry
+ * collector (CORE-02) and the config loader (CONFIG-01). Pure types and functions,
+ * except telemetry's confined I/O functions (appendRecord / readRecords /
+ * appendRecordFailOpen — the fail-open wrapper promoted by CORE-05).
+ * See https://github.com/huskyhoochu/polydeukes
+ */
+import { isPlainObject } from './is-plain-object.js';
+export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, defineConfig, } from './config.js';
+export { failModeToExitCode, resolveFailMode, } from './fail-policy.js';
+export { isPlainObject } from './is-plain-object.js';
+export { normalizeProtectedPaths } from './protected-paths.js';
+export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, parseRecordLine, readRecords, runGain, } from './telemetry.js';
+export { noopTranscript, transcriptFromInput, } from './transcript.js';
+/**
+ * exit-code semantics of the covenant protocol (PRD §4.1).
+ *
+ * The three codes are distinct and ordered by severity. The covenant *body* only
+ * ever emits `0` (uphold) or `1` (break, non-blocking); translating a break into the
+ * blocking `2` is the wrapper's job (COVENANT-01), never the core's. The sole place
+ * the core itself reaches for `2` is the fail-closed parse path below.
+ */
+/** Promise upheld — no violation, the edit/push passes. */
+export const EXIT_UPHOLD = 0;
+/** Violation reported as a non-blocking signal. The covenant body's break code. */
+export const EXIT_BREAK_NON_BLOCKING = 1;
+/** Violation blocked — the edit/push is refused. Reserved for the wrapper / fail-closed. */
+export const EXIT_BREAK_BLOCKING = 2;
+/**
+ * Deserialize stdin-JSON into a {@link CovenantInput} (the protocol's reverse direction).
+ *
+ * fail-closed (PRD §5.2): this never throws. Any failure — unparseable JSON, an empty
+ * payload, a parsed value that is not an object, or a missing required collection —
+ * resolves to a blocking `{ ok: false, exitCode: 2 }`. "Cannot judge" means block,
+ * so an unjudgeable input can never be mistaken for a valid one.
+ */
+export function parseInput(stdinJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdinJson);
+    }
+    catch {
+        return { ok: false, exitCode: EXIT_BREAK_BLOCKING };
+    }
+    if (!isPlainObject(parsed)) {
+        return { ok: false, exitCode: EXIT_BREAK_BLOCKING };
+    }
+    const candidate = parsed;
+    if (!Array.isArray(candidate.toolCalls) ||
+        !Array.isArray(candidate.subagentSpawns) ||
+        !Array.isArray(candidate.userMessages)) {
+        return { ok: false, exitCode: EXIT_BREAK_BLOCKING };
+    }
+    return { ok: true, value: candidate };
+}
+/**
+ * Flatten every call's evidence into one array in call order (CORE-06 §4.1).
+ *
+ * The one traversal for consumers that need no attribution (discipline scope, delta
+ * judging): calls without evidence are skipped, never substituted for.
+ */
+export function allFileChanges(input) {
+    const changes = [];
+    for (const call of input.toolCalls) {
+        if (call.fileChange !== undefined)
+            changes.push(call.fileChange);
+    }
+    return changes;
+}
+/**
+ * Map a {@link CovenantVerdict} to an exit code (the protocol's forward direction).
+ *
+ * Responsibility boundary (PRD §4.1): the body emits `0` when upheld and `1` when
+ * broken — never the blocking `2`. Translating `1` into `2` is the wrapper's policy.
+ */
+export function verdictToExitCode(verdict) {
+    return verdict.upheld ? EXIT_UPHOLD : EXIT_BREAK_NON_BLOCKING;
+}

package/dist/is-plain-object.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `isPlainObject` — the workspace's single canonical plain-object predicate.
+ *
+ * Promoted by CORE-05 from per-package copies: typeof `object`, non-null, not an array.
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/is-plain-object.js

@@ -0,0 +1,8 @@
+/**
+ * `isPlainObject` — the workspace's single canonical plain-object predicate.
+ *
+ * Promoted by CORE-05 from per-package copies: typeof `object`, non-null, not an array.
+ */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/protected-paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Protected-path normalization — the `protectedPaths` list normalized into the literal
+ * path strings the dispatcher contract expects (CONFIG-02). Pure string transformation —
+ * zero file I/O, no glob expansion, no path resolution (PRD §4.2).
+ */
+/**
+ * Normalize the protection surface from a config-shaped spec (PRD §4.2).
+ *
+ * Processing order: trim each entry → strip a leading `./` → strip a trailing `/` → drop
+ * empty-equivalent entries → dedupe on the normalized value, keeping the first occurrence.
+ * A `ResolvedConfig` can be passed directly. An absent or empty `protectedPaths` yields
+ * `[]` — its meaning is the dispatcher's call.
+ */
+export declare function normalizeProtectedPaths(spec: {
+    protectedPaths?: string[];
+}): string[];

package/dist/protected-paths.js

@@ -0,0 +1,36 @@
+/**
+ * Protected-path normalization — the `protectedPaths` list normalized into the literal
+ * path strings the dispatcher contract expects (CONFIG-02). Pure string transformation —
+ * zero file I/O, no glob expansion, no path resolution (PRD §4.2).
+ */
+/**
+ * Normalize the protection surface from a config-shaped spec (PRD §4.2).
+ *
+ * Processing order: trim each entry → strip a leading `./` → strip a trailing `/` → drop
+ * empty-equivalent entries → dedupe on the normalized value, keeping the first occurrence.
+ * A `ResolvedConfig` can be passed directly. An absent or empty `protectedPaths` yields
+ * `[]` — its meaning is the dispatcher's call.
+ */
+export function normalizeProtectedPaths(spec) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of spec.protectedPaths ?? []) {
+        let path = entry.trim();
+        // Strip to a fixpoint: a single pass would leave residues on repeated prefixes or
+        // suffixes ('././x', 'x//'), and a residual './' or '/' silently matches nothing
+        // downstream — the fail-open narrowing the contract forbids. Interior segments and
+        // absolute paths are path *resolution*, deliberately out of scope.
+        while (path.startsWith('./')) {
+            path = path.slice(2);
+        }
+        while (path.endsWith('/')) {
+            path = path.slice(0, -1);
+        }
+        if (path.length === 0 || seen.has(path)) {
+            continue;
+        }
+        seen.add(path);
+        result.push(path);
+    }
+    return result;
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ROI telemetry — the single shared collector and its `gain` aggregation (CORE-02).
+ *
+ * One record is one line of 4-field TSV (PRD §4.1); one append is one write call
+ * (PRD §4.2). I/O is confined to exactly two functions — {@link appendRecord} (the
+ * only write) and {@link readRecords} (the only read). Formatting, parsing, and
+ * aggregation are pure. This is the sole collector: later work calls this API rather
+ * than building its own logger.
+ */
+/**
+ * The five telemetry events. `witnessed` is a first-class event, not a flag on `passed`:
+ * a break a human stood behind by supplying the pass condition themselves. `advised` is a
+ * violation verdict an advise-level observer recorded but let through; `skipped` is a
+ * discipline a surface could not judge at all (no evidence channel) — a no-op that shows
+ * up in the data instead of vanishing.
+ */
+export type TelemetryEvent = 'passed' | 'blocked' | 'witnessed' | 'advised' | 'skipped';
+/**
+ * `TelemetryRecord` — one measured covenant outcome (PRD §4.1).
+ *
+ * `subject` is the judged target (a file path, etc.); `-` is the documented sentinel
+ * for "no subject", carried round-trip like any other value.
+ */
+export type TelemetryRecord = {
+    timestamp: string;
+    event: TelemetryEvent;
+    label: string;
+    subject: string;
+};
+/** Per-label event counts, keyed by label then event. */
+export type GainSummary = {
+    total: number;
+    counts: Record<string, Record<TelemetryEvent, number>>;
+};
+/**
+ * Serialize a {@link TelemetryRecord} into one newline-terminated TSV line (pure).
+ *
+ * The returned string already includes the trailing `\n`, so {@link appendRecord}
+ * writes it verbatim in a single call.
+ */
+export declare function formatRecordLine(record: TelemetryRecord): string;
+/**
+ * Parse one TSV line back into a {@link TelemetryRecord}, or `null` if malformed (pure).
+ *
+ * Tolerates a trailing newline (so it round-trips {@link formatRecordLine}). Returns
+ * `null` for the wrong field count, an event outside the five valid events, or an
+ * empty line — a malformed line is rejected, never coerced into a bogus record. The one
+ * exception is {@link LEGACY_WITNESSED_EVENT}, which reads back as `witnessed`.
+ */
+export declare function parseRecordLine(line: string): TelemetryRecord | null;
+/**
+ * Append one record to the log at `path` — the only write I/O (PRD §4.2).
+ *
+ * Exactly one {@link appendFileSync} call per record, writing {@link formatRecordLine}
+ * verbatim. Relying on POSIX `O_APPEND` single-write semantics, concurrent appends do
+ * not interleave lines.
+ *
+ * fail-open (PRD §4.3): any fs failure — bad path, permissions, disk — returns
+ * `{ ok: false }` and never throws. This is deliberately the opposite direction of the
+ * covenant path's fail-closed: the worst outcome of telemetry is a missing datum, never
+ * a blocked workflow.
+ */
+export declare function appendRecord(path: string, record: TelemetryRecord): {
+    ok: boolean;
+};
+/**
+ * Append one telemetry record fail-open, timestamping it here (CORE-05).
+ *
+ * This layer lives above the deliberately mkdir-free {@link appendRecord} (COVENANT-01b:
+ * an absent directory is a fail-open `{ ok: false }` for `appendRecord` itself), so this
+ * wrapper carries the parent-directory guarantee. The mkdir and the append share one try
+ * block, and a failure of either never alters the caller's verdict and never propagates.
+ */
+export declare function appendRecordFailOpen(telemetryPath: string, record: Omit<TelemetryRecord, 'timestamp'>): void;
+/**
+ * Read every record from the log at `path` — the only read I/O (PRD §4.4).
+ *
+ * fail-open: an absent file or any read error returns `{ records: [], skipped: 0 }`
+ * (an absent log means "nothing collected yet"), never throwing. Corrupt lines
+ * ({@link parseRecordLine} → `null`) are skipped and counted; the blank trailing line
+ * from the final `\n` is not counted as skipped.
+ */
+export declare function readRecords(path: string): {
+    records: TelemetryRecord[];
+    skipped: number;
+};
+/**
+ * Aggregate records into per-label event counts (PRD §4.4, pure).
+ *
+ * Each label gets its own counter across all five events, so a corrupt or missing
+ * event never bleeds counts between labels.
+ */
+export declare function aggregateGain(records: TelemetryRecord[]): GainSummary;
+/**
+ * `gain` entry point — read the log at `path`, aggregate, and render (PRD §4.4).
+ *
+ * Composes {@link readRecords} + {@link aggregateGain} + a pure renderer. An absent or
+ * empty log yields `no telemetry collected`; a corrupt line is skipped upstream, reported
+ * in the output, and does not abort the report.
+ */
+export declare function runGain(path: string): string;

package/dist/telemetry.js

@@ -0,0 +1,194 @@
+/**
+ * ROI telemetry — the single shared collector and its `gain` aggregation (CORE-02).
+ *
+ * One record is one line of 4-field TSV (PRD §4.1); one append is one write call
+ * (PRD §4.2). I/O is confined to exactly two functions — {@link appendRecord} (the
+ * only write) and {@link readRecords} (the only read). Formatting, parsing, and
+ * aggregation are pure. This is the sole collector: later work calls this API rather
+ * than building its own logger.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+const TAB = '\t';
+const VALID_EVENTS = [
+    'passed',
+    'blocked',
+    'witnessed',
+    'advised',
+    'skipped',
+];
+/**
+ * The event name `witnessed` was written under before the rename — a read-only migration
+ * seam, never a value this module emits.
+ *
+ * It exists because the collected log predates the rename: those rows are the sample the
+ * milestone journal round argues from, and dropping them as corrupt would delete the
+ * measurement instead of migrating it. Compatibility runs one way only — {@link
+ * formatRecordLine} has no path back to this name — and the match is the exact literal, so
+ * a genuinely corrupt field is still rejected rather than coerced into a fabricated record.
+ */
+const LEGACY_WITNESSED_EVENT = 'bypassed';
+/**
+ * Replace tab/newline/carriage-return with single spaces (PRD §4.1 line integrity).
+ *
+ * Without this, a tab or newline inside a field would fabricate extra TSV fields or
+ * extra lines — a record is always exactly one line.
+ */
+function sanitize(value) {
+    return value.replace(/[\t\n\r]/g, ' ');
+}
+/**
+ * Serialize a {@link TelemetryRecord} into one newline-terminated TSV line (pure).
+ *
+ * The returned string already includes the trailing `\n`, so {@link appendRecord}
+ * writes it verbatim in a single call.
+ */
+export function formatRecordLine(record) {
+    const fields = [record.timestamp, record.event, sanitize(record.label), sanitize(record.subject)];
+    return `${fields.join(TAB)}\n`;
+}
+/**
+ * Parse one TSV line back into a {@link TelemetryRecord}, or `null` if malformed (pure).
+ *
+ * Tolerates a trailing newline (so it round-trips {@link formatRecordLine}). Returns
+ * `null` for the wrong field count, an event outside the five valid events, or an
+ * empty line — a malformed line is rejected, never coerced into a bogus record. The one
+ * exception is {@link LEGACY_WITNESSED_EVENT}, which reads back as `witnessed`.
+ */
+export function parseRecordLine(line) {
+    const trimmed = line.replace(/\n$/, '');
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const fields = trimmed.split(TAB);
+    if (fields.length !== 4) {
+        return null;
+    }
+    const [timestamp, event, label, subject] = fields;
+    const resolved = event === LEGACY_WITNESSED_EVENT ? 'witnessed' : event;
+    if (!VALID_EVENTS.includes(resolved)) {
+        return null;
+    }
+    return { timestamp, event: resolved, label, subject };
+}
+/**
+ * Append one record to the log at `path` — the only write I/O (PRD §4.2).
+ *
+ * Exactly one {@link appendFileSync} call per record, writing {@link formatRecordLine}
+ * verbatim. Relying on POSIX `O_APPEND` single-write semantics, concurrent appends do
+ * not interleave lines.
+ *
+ * fail-open (PRD §4.3): any fs failure — bad path, permissions, disk — returns
+ * `{ ok: false }` and never throws. This is deliberately the opposite direction of the
+ * covenant path's fail-closed: the worst outcome of telemetry is a missing datum, never
+ * a blocked workflow.
+ */
+export function appendRecord(path, record) {
+    try {
+        appendFileSync(path, formatRecordLine(record));
+        return { ok: true };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+/**
+ * Append one telemetry record fail-open, timestamping it here (CORE-05).
+ *
+ * This layer lives above the deliberately mkdir-free {@link appendRecord} (COVENANT-01b:
+ * an absent directory is a fail-open `{ ok: false }` for `appendRecord` itself), so this
+ * wrapper carries the parent-directory guarantee. The mkdir and the append share one try
+ * block, and a failure of either never alters the caller's verdict and never propagates.
+ */
+export function appendRecordFailOpen(telemetryPath, record) {
+    try {
+        mkdirSync(dirname(telemetryPath), { recursive: true });
+        appendRecord(telemetryPath, { timestamp: new Date().toISOString(), ...record });
+    }
+    catch {
+        // fail-open: a logging problem must not alter the verdict or propagate.
+    }
+}
+/**
+ * Read every record from the log at `path` — the only read I/O (PRD §4.4).
+ *
+ * fail-open: an absent file or any read error returns `{ records: [], skipped: 0 }`
+ * (an absent log means "nothing collected yet"), never throwing. Corrupt lines
+ * ({@link parseRecordLine} → `null`) are skipped and counted; the blank trailing line
+ * from the final `\n` is not counted as skipped.
+ */
+export function readRecords(path) {
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return { records: [], skipped: 0 };
+    }
+    const records = [];
+    let skipped = 0;
+    for (const line of content.split('\n')) {
+        if (line.length === 0) {
+            continue;
+        }
+        const parsed = parseRecordLine(line);
+        if (parsed === null) {
+            skipped += 1;
+        }
+        else {
+            records.push(parsed);
+        }
+    }
+    return { records, skipped };
+}
+/**
+ * Aggregate records into per-label event counts (PRD §4.4, pure).
+ *
+ * Each label gets its own counter across all five events, so a corrupt or missing
+ * event never bleeds counts between labels.
+ */
+export function aggregateGain(records) {
+    const counts = {};
+    for (const record of records) {
+        if (!(record.label in counts)) {
+            counts[record.label] = { passed: 0, blocked: 0, witnessed: 0, advised: 0, skipped: 0 };
+        }
+        counts[record.label][record.event] += 1;
+    }
+    return { total: records.length, counts };
+}
+/**
+ * Render a {@link GainSummary} into human-readable lines (pure).
+ *
+ * Each label is mentioned with its passed/blocked/witnessed/advised/skipped counts; each
+ * is a distinct column, never folded into another (PRD §4.4). A non-zero corrupt-line
+ * count is reported rather than hidden — silent skipping would mask log corruption.
+ *
+ * Two different meanings share the word `skipped`: the per-label EVENT column above,
+ * and the unparseable-line count below. They are rendered on separate lines and never
+ * summed — `corrupt lines skipped=N` names its own subject so neither reads as the other.
+ */
+function renderGain(summary, skipped) {
+    if (summary.total === 0 && skipped === 0) {
+        return 'no telemetry collected';
+    }
+    const lines = [`total ${summary.total}`];
+    for (const [label, counts] of Object.entries(summary.counts)) {
+        lines.push(`${label}: passed=${counts.passed} blocked=${counts.blocked} witnessed=${counts.witnessed} advised=${counts.advised} skipped=${counts.skipped}`);
+    }
+    if (skipped > 0) {
+        lines.push(`corrupt lines skipped=${skipped}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * `gain` entry point — read the log at `path`, aggregate, and render (PRD §4.4).
+ *
+ * Composes {@link readRecords} + {@link aggregateGain} + a pure renderer. An absent or
+ * empty log yields `no telemetry collected`; a corrupt line is skipped upstream, reported
+ * in the output, and does not abort the report.
+ */
+export function runGain(path) {
+    const { records, skipped } = readRecords(path);
+    return renderGain(aggregateGain(records), skipped);
+}

package/dist/transcript.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `CanonicalTranscript` — the agent-neutral session-query seam (CORE-04).
+ *
+ * Layering (PRD §1): this seam does not replace `CovenantInput`. The IR (CORE-01) is
+ * the *data* a covenant judges; `CanonicalTranscript` is the *behavioral seam* that
+ * queries session data — CORE-04 sits on top of CORE-01, and the IR is one source it
+ * can wrap. Concrete transcript formats stay in adapters; the core knows only the
+ * query vocabulary. Pure types and functions, zero I/O.
+ */
+import type { CovenantInput } from './index.js';
+/** One subagent invocation observed in the session. `kind` is an adapter-supplied value. */
+export type SubagentInvocation = {
+    kind: string;
+};
+/**
+ * One user message observed in the session (PRD §4.1).
+ *
+ * `timestampMs` is epoch milliseconds. Its absence means the source cannot prove
+ * freshness — the fail-closed signal a witness consumer must treat as "not fresh".
+ */
+export type TranscriptUserMessage = {
+    text: string;
+    timestampMs?: number;
+};
+/**
+ * One tool call observed in the session (COVENANT-13 §4.2). `name` and `args` are
+ * adapter-supplied values — the core knows the query vocabulary, never a tool's name.
+ *
+ * `succeeded` is three-valued (COVENANT-13b §4.1): `true` = it ran and reported success,
+ * `false` = it ran and reported an error, was blocked, or was refused, and absent = the
+ * provider cannot observe results at all. A consumer that treats the call as evidence
+ * accepts only `true`, so the latter two share a disposition while staying diagnosable.
+ */
+export type TranscriptToolCall = {
+    name: string;
+    args: Record<string, unknown>;
+    succeeded?: boolean;
+};
+/**
+ * `CanonicalTranscript` — what a covenant may ask about the session (PRD §4.1).
+ *
+ * Synchronous by design (covenant bodies are short-lived CLI processes) and
+ * verdict-free: the seam carries facts only; TTL filtering and token matching belong
+ * to the consumer.
+ */
+export type CanonicalTranscript = {
+    /** Invocations of the given kind, or all of them when omitted. Observation order preserved. */
+    findSubagentInvocations(kind?: string): SubagentInvocation[];
+    /** Every user message, observation order preserved. Missing timestampMs = freshness unprovable. */
+    findUserMessages(): TranscriptUserMessage[];
+    /** Tool calls with the given name, or all when omitted. Observation order preserved. */
+    findToolCalls(name?: string): TranscriptToolCall[];
+};
+/**
+ * The injection-absent default (PRD §4.2): every query answers "nothing happened".
+ * A witness consumer naturally converges to fail-closed — no evidence, no skip — and
+ * so does a precedent consumer (no evidence, gate stays shut).
+ */
+export declare const noopTranscript: CanonicalTranscript;
+/**
+ * Wrap a {@link CovenantInput} as a {@link CanonicalTranscript} (PRD §4.2).
+ *
+ * Exposes `subagentSpawns` as invocations (filtered when a kind is given) and
+ * `userMessages` with `timestampMs` omitted — the bare IR cannot prove freshness,
+ * and that absence is the *correct* fail-closed signal for a witness consumer.
+ * Order preserved; the input is never mutated, and every query returns fresh
+ * objects so consumers never hold live aliases into the shared IR.
+ *
+ * `findToolCalls` projects each call down to `{ name, args }` only: since CORE-06 a
+ * call element also carries `fileChange` evidence, and evidence is judgment input, not
+ * session history — the two vocabularies stay separate (COVENANT-13 §4.2). `succeeded`
+ * stays absent for the same reason it is left three-valued: these calls are the ones
+ * being judged right now, so they have not run, and a call can never be its own
+ * precedent (COVENANT-13b §4.1).
+ */
+export declare function transcriptFromInput(input: CovenantInput): CanonicalTranscript;