@polydeukes/core 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,68 +1,18 @@
 /**
  * @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).
+ * Alpha. Carries the covenant protocol, the ROI telemetry collector, and the config
+ * schema. Pure types and functions, except telemetry's confined I/O functions
+ * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-import { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD } from './exit-codes.js';
-import { isPlainObject } from './is-plain-object.js';
+export { BINARY_COMBINATOR_NAMES, RELATION_NAMES, SUPPLY_POLICIES, validateAlgebraDeclaration, } from './algebra.js';
+export { AXIS_NAMES, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, } from './catalogue.js';
 export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, defineConfig, } from './config.js';
 export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.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 { allFileChanges, parseInput, verdictToExitCode, } from './protocol.js';
+export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, parseRecordLine, readRecords, runGain, SKIP_REASONS, } from './telemetry.js';
 export { noopTranscript, transcriptFromInput, } from './transcript.js';
-/**
- * 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

@@ -1,6 +1,9 @@
 /**
  * `isPlainObject` — the workspace's single canonical plain-object predicate.
  *
- * Promoted by CORE-05 from per-package copies: typeof `object`, non-null, not an array.
+ * typeof `object`, non-null, not an array.
+ *
+ * Its own file because it is a public export the adapters and the umbrella import; the
+ * core-internal validation helpers live in `validation.ts` instead.
  */
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/is-plain-object.js

@@ -1,7 +1,10 @@
 /**
  * `isPlainObject` — the workspace's single canonical plain-object predicate.
  *
- * Promoted by CORE-05 from per-package copies: typeof `object`, non-null, not an array.
+ * typeof `object`, non-null, not an array.
+ *
+ * Its own file because it is a public export the adapters and the umbrella import; the
+ * core-internal validation helpers live in `validation.ts` instead.
  */
 export function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/protected-paths.d.ts

@@ -1,10 +1,10 @@
 /**
  * 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).
+ * path strings the dispatcher contract expects. Pure string transformation — zero file
+ * I/O, no glob expansion, no path resolution.
  */
 /**
- * Normalize the protection surface from a config-shaped spec (PRD §4.2).
+ * Normalize the protection surface from a config-shaped spec.
  *
  * Processing order: trim each entry → strip a leading `./` → strip a trailing `/` → drop
  * empty-equivalent entries → dedupe on the normalized value, keeping the first occurrence.

package/dist/protected-paths.js

@@ -1,10 +1,10 @@
 /**
  * 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).
+ * path strings the dispatcher contract expects. Pure string transformation — zero file
+ * I/O, no glob expansion, no path resolution.
  */
 /**
- * Normalize the protection surface from a config-shaped spec (PRD §4.2).
+ * Normalize the protection surface from a config-shaped spec.
  *
  * Processing order: trim each entry → strip a leading `./` → strip a trailing `/` → drop
  * empty-equivalent entries → dedupe on the normalized value, keeping the first occurrence.

package/dist/protocol.d.ts

@@ -0,0 +1,152 @@
+/**
+ * protocol — the covenant protocol: the input IR, the verdict, and the two directions
+ * (parse stdin-JSON in, map a verdict to an exit code out).
+ */
+import type { TelemetryEvent } from './telemetry.ts';
+/**
+ * `FileChange` — one file's mutation evidence around the judged call.
+ *
+ * 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;
+};
+/**
+ * `SourceReader` — a repo-relative path in, the text a surface observes there or absence out.
+ *
+ * The one signature the supply layer injects and every surface's reader implements. Absence
+ * is `undefined` and every other failure throws, so a permission refusal reaches the root's
+ * fail-closed path instead of passing for a file that is not there.
+ */
+export type SourceReader = (path: string) => string | undefined;
+/**
+ * `ChannelReader` — a channel kind in, the text the surface observes on that channel or
+ * absence out. Absence is `undefined`, same contract as {@link SourceReader}.
+ */
+export type ChannelReader = (kind: string) => string | undefined;
+/**
+ * `Actor` — who made the observation the judgment is about.
+ *
+ * `agentType` is the subagent kind the host names when the call comes from one. The empty
+ * object is a positive value: the host observed the actor and it is not a subagent.
+ */
+export type Actor = {
+    agentType?: string;
+};
+/**
+ * `CovenantInput` — the agent-neutral input IR a covenant judges.
+ *
+ * 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: `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;
+    }[];
+    /**
+     * The world axis: files a supply layer read for the judgment (key = repo-relative path,
+     * an absent key = an absent file, never `null` — that is `FileChange.pre`'s creation
+     * marker), the observation unit's change set when the host sees wider than the changes
+     * this input carries, and the channels a surface supplied — `sidecar` is the spawn-record
+     * list as JSON text, where `'[]'` says the channel observed no spawn and an absent key
+     * says there is no channel at all.
+     */
+    world?: {
+        files?: Record<string, string>;
+        changes?: string[];
+        channels?: {
+            sidecar?: string;
+        };
+    };
+    /**
+     * The observation's actor, when the host proves one. Absence means the host could not
+     * prove one and is never turned into `{}` — what an absent actor means is a
+     * declaration's own supply policy.
+     */
+    actor?: Actor;
+};
+/**
+ * `CovenantVerdict` — the result a covenant body produces.
+ *
+ * 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;
+};
+/**
+ * `DispatchOutcome` — the protocol-level result of one dispatch over many covenants.
+ *
+ * The blocking exit code plus one entry per judged covenant: `label` names which covenant
+ * produced the entry, and `event` is the telemetry word the wrapper already recorded for
+ * it. The event rides on the entry rather than being recomputed by a reader — the witness
+ * valve is impure, so recomputing would consult it a second time for one verdict.
+ */
+export type DispatchOutcome = {
+    exitCode: 0 | 2;
+    results: {
+        label: string;
+        exitCode: 0 | 2;
+        event: TelemetryEvent;
+    }[];
+};
+/**
+ * Deserialize stdin-JSON into a {@link CovenantInput} (the protocol's reverse direction).
+ *
+ * fail-closed: this never throws. Any failure — unparseable JSON, an empty
+ * payload, a parsed value that is not an object, a missing required collection, a
+ * malformed world axis, or a malformed actor — 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.
+ *
+ * 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: 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/protocol.js

@@ -0,0 +1,121 @@
+/**
+ * protocol — the covenant protocol: the input IR, the verdict, and the two directions
+ * (parse stdin-JSON in, map a verdict to an exit code out).
+ */
+import { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD } from './exit-codes.js';
+import { isPlainObject } from './is-plain-object.js';
+/** The channel kinds a world may carry, closed. A name outside it supplies nothing. */
+const CHANNEL_KINDS = new Set(['sidecar']);
+/**
+ * Whether a value is the world axis: a plain object carrying nothing but a `files` record
+ * of strings, a `changes` list of strings, and a `channels` record of channel texts.
+ *
+ * Closed at three fields, and all shape-checked: a supplier writing under a misspelt key
+ * supplies nothing while looking like a supply, and a `null` under a path or a channel kind
+ * would pass the engine's key-presence test as a supplied value whose text is missing.
+ */
+function isWorld(value) {
+    if (!isPlainObject(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (key !== 'files' && key !== 'changes' && key !== 'channels')
+            return false;
+    }
+    const { files, changes, channels } = value;
+    if (channels !== undefined) {
+        if (!isPlainObject(channels))
+            return false;
+        for (const [kind, text] of Object.entries(channels)) {
+            if (!CHANNEL_KINDS.has(kind))
+                return false;
+            if (typeof text !== 'string')
+                return false;
+        }
+    }
+    if (files !== undefined) {
+        if (!isPlainObject(files))
+            return false;
+        if (!Object.values(files).every((text) => typeof text === 'string'))
+            return false;
+    }
+    if (changes !== undefined) {
+        if (!Array.isArray(changes))
+            return false;
+        if (!changes.every((path) => typeof path === 'string'))
+            return false;
+    }
+    return true;
+}
+/**
+ * Whether a value is the actor: a plain object carrying nothing but a string `agentType`.
+ *
+ * Closed at one key, same reason as {@link isWorld}: a host writing its own payload
+ * spelling of the actor key under `actor` would supply nothing while looking like a supply,
+ * and a non-string `agentType` reaches a pattern step as a value no regex matches.
+ */
+function isActor(value) {
+    if (!isPlainObject(value))
+        return false;
+    for (const key of Object.keys(value)) {
+        if (key !== 'agentType')
+            return false;
+    }
+    return value.agentType === undefined || typeof value.agentType === 'string';
+}
+/**
+ * Deserialize stdin-JSON into a {@link CovenantInput} (the protocol's reverse direction).
+ *
+ * fail-closed: this never throws. Any failure — unparseable JSON, an empty
+ * payload, a parsed value that is not an object, a missing required collection, a
+ * malformed world axis, or a malformed actor — 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 };
+    }
+    if (candidate.world !== undefined && !isWorld(candidate.world)) {
+        return { ok: false, exitCode: EXIT_BREAK_BLOCKING };
+    }
+    if (candidate.actor !== undefined && !isActor(candidate.actor)) {
+        return { ok: false, exitCode: EXIT_BREAK_BLOCKING };
+    }
+    return { ok: true, value: candidate };
+}
+/**
+ * Flatten every call's evidence into one array in call order.
+ *
+ * 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: 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/source-names.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `source-names.ts` — the source names every world carries on its own.
+ *
+ * Both the declaration grammar and the mechanism catalogue read this list, so it lives
+ * apart from either: the grammar refuses a `sources` binding that shadows one of them, and
+ * the catalogue derives an axis from each — the change axis from the six that read the
+ * change, the actor axis from `actor`.
+ */
+/** The source names the world supplies on its own; a `sources` entry may not shadow one. */
+export declare const FIXED_SOURCE_NAMES: readonly ['target.path', 'pre', 'post', 'state', 'changes', 'command', 'actor'];

package/dist/source-names.js

@@ -0,0 +1,18 @@
+/**
+ * `source-names.ts` — the source names every world carries on its own.
+ *
+ * Both the declaration grammar and the mechanism catalogue read this list, so it lives
+ * apart from either: the grammar refuses a `sources` binding that shadows one of them, and
+ * the catalogue derives an axis from each — the change axis from the six that read the
+ * change, the actor axis from `actor`.
+ */
+/** The source names the world supplies on its own; a `sources` entry may not shadow one. */
+export const FIXED_SOURCE_NAMES = [
+    'target.path',
+    'pre',
+    'post',
+    'state',
+    'changes',
+    'command',
+    'actor',
+];

package/dist/telemetry.d.ts

@@ -1,11 +1,10 @@
 /**
- * ROI telemetry — the single shared collector and its `gain` aggregation (CORE-02).
+ * ROI telemetry — the single shared collector and its `gain` aggregation.
  *
- * 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.
+ * One record is one line of TSV — four fields, or five when a judgment names witnesses;
+ * one append is one write call. 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.
  */
 /**
  * The six telemetry events. `witnessed` is a first-class event, not a flag on `passed`:
@@ -21,16 +20,33 @@
  */
 export type TelemetryEvent = 'passed' | 'blocked' | 'witnessed' | 'advised' | 'skipped' | 'unattributed';
 /**
- * `TelemetryRecord` — one measured covenant outcome (PRD §4.1).
+ * Why a `skipped` row records no judgment, closed: the surface has no observation channel
+ * for what the entry reads, assembly could not compile the entry, or the declaration's own
+ * `supply: pass` let an absent source through.
+ */
+export declare const SKIP_REASONS: readonly ['no-observation', 'config-fault', 'supply-pass'];
+/** One of the three skip reasons — the closed vocabulary of the fifth field on a skip row. */
+export type SkipReason = (typeof SKIP_REASONS)[number];
+/**
+ * `TelemetryRecord` — one measured covenant outcome.
  *
  * `subject` is the judged target (a file path, etc.); `-` is the documented sentinel
  * for "no subject", carried round-trip like any other value.
+ *
+ * `witnesses` is the optional fifth field: an already-serialized JSON string naming what
+ * a judgment found broken. Only a judgment that produced witness elements carries it, so
+ * every other producer's row keeps its four fields.
+ *
+ * `reason` is the other reading of that fifth field, and only a `skipped` row takes it: a
+ * skip has no witness to name, so the two never contend for the slot.
  */
 export type TelemetryRecord = {
     timestamp: string;
     event: TelemetryEvent;
     label: string;
     subject: string;
+    witnesses?: string;
+    reason?: SkipReason;
 };
 /** Per-label event counts, keyed by label then event. */
 export type GainSummary = {
@@ -41,26 +57,35 @@ export type GainSummary = {
  * 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.
+ * writes it verbatim in a single call. The fifth field appears only when the record
+ * carries `witnesses` or a skip `reason`; a record without either writes the four-field
+ * line unchanged.
+ *
+ * Throws when a record claims the fifth field twice, or claims it as a reason on an event
+ * that is not `skipped`: both are assembly errors, and writing either one would produce a
+ * row no reader can take apart.
  */
 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 six 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`.
+ * `null` for a field count outside four (no fifth field) and five (with one), an event
+ * outside the six valid events, or an empty line — a malformed line is rejected, never
+ * coerced into a bogus record. The fifth field is read per event: on `skipped` it is a
+ * token of {@link SKIP_REASONS} and nothing else, on every other event a JSON array of
+ * witnesses. 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).
+ * Append one record to the log at `path` — the only write I/O.
  *
  * 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
+ * fail-open: 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.
@@ -69,16 +94,16 @@ export declare function appendRecord(path: string, record: TelemetryRecord): {
     ok: boolean;
 };
 /**
- * Append one telemetry record fail-open, timestamping it here (CORE-05).
+ * Append one telemetry record fail-open, timestamping it here.
  *
- * 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.
+ * {@link appendRecord} is deliberately mkdir-free — for it an absent directory is just a
+ * fail-open `{ ok: false }` — 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).
+ * Read every record from the log at `path` — the only read I/O.
  *
  * fail-open: an absent file or any read error returns `{ records: [], skipped: 0 }`
  * (an absent log means "nothing collected yet"), never throwing. Corrupt lines
@@ -90,14 +115,14 @@ export declare function readRecords(path: string): {
     skipped: number;
 };
 /**
- * Aggregate records into per-label event counts (PRD §4.4, pure).
+ * Aggregate records into per-label event counts (pure).
  *
  * Each label gets its own counter across all six 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).
+ * `gain` entry point — read the log at `path`, aggregate, and render.
  *
  * Composes {@link readRecords} + {@link aggregateGain} + a pure renderer. An absent or
  * empty log yields `no telemetry collected`; a corrupt line is skipped upstream, reported