@polydeukes/core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -6,97 +6,13 @@
  * (appendRecord / readRecords / appendRecordFailOpen).
  * See https://github.com/huskyhoochu/polydeukes
  */
-export { ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, type DisciplineDraft, type DisciplineEntry, type DisciplineForbid, defineConfig, type EnforceLevel, type LanguageProfile, type PolydeukesConfig, type ResolvedConfig, type ResolvedLanguageProfile, } from './config.js';
-export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.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';
-/**
- * `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;
-};
-/**
- * `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;
-    }[];
-};
-/**
- * `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;
-};
-/**
- * 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, 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.
- *
- * 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;
+export { type AlgebraDeclaration, BINARY_COMBINATOR_NAMES, type BinaryStep, type ExtractBlock, type ExtractStep, RELATION_NAMES, type RelateEntry, type RelationDecl, type RelationName, type ScopeBlock, SUPPLY_POLICIES, type SupplyBlock, type UnaryStep, validateAlgebraDeclaration, type Witness, type WitnessBlock, type Witnesses, } from './algebra.ts';
+export { AXIS_NAMES, type Axis, type DerivableDeclaration, deriveShape, MECHANISM_NAMES, MECHANISM_SHAPES, type MechanismName, type MechanismShape, } from './catalogue.ts';
+export { type AlgebraDeclarationBody, ConfigValidationError, DEFAULT_TELEMETRY_LOG_PATH, type DisciplineDraft, type DisciplineEntry, defineConfig, type EnforceLevel, type LanguageProfile, type PolydeukesConfig, type ResolvedConfig, type ResolvedLanguageProfile, } from './config.ts';
+export { EXIT_BREAK_BLOCKING, EXIT_BREAK_NON_BLOCKING, EXIT_UPHOLD, } from './exit-codes.ts';
+export { type FailMode, type FailureKind, failModeToExitCode, resolveFailMode, } from './fail-policy.ts';
+export { isPlainObject } from './is-plain-object.ts';
+export { normalizeProtectedPaths } from './protected-paths.ts';
+export { allFileChanges, type ChannelReader, type CovenantInput, type CovenantVerdict, type DispatchOutcome, type FileChange, parseInput, type SourceReader, verdictToExitCode, } from './protocol.ts';
+export { aggregateGain, appendRecord, appendRecordFailOpen, formatRecordLine, type GainSummary, parseRecordLine, readRecords, runGain, SKIP_REASONS, type SkipReason, type TelemetryEvent, type TelemetryRecord, } from './telemetry.ts';
+export { type CanonicalTranscript, noopTranscript, type TranscriptToolCall, type TranscriptUserMessage, transcriptFromInput, } from './transcript.ts';

package/dist/index.js

@@ -6,62 +6,13 @@
  * (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: 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.
- *
- * 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/is-plain-object.d.ts

@@ -2,5 +2,8 @@
  * `isPlainObject` — the workspace's single canonical plain-object predicate.
  *
  * 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

@@ -2,6 +2,9 @@
  * `isPlainObject` — the workspace's single canonical plain-object predicate.
  *
  * 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/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,7 +1,8 @@
 /**
  * ROI telemetry — the single shared collector and its `gain` aggregation.
  *
- * One record is one line of 4-field TSV; one append is one write call. I/O is confined to
+ * 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.
  */
@@ -18,17 +19,34 @@
  * failure found after the fact — and it never blocks or passes a call.
  */
 export type TelemetryEvent = 'passed' | 'blocked' | 'witnessed' | 'advised' | 'skipped' | 'unattributed';
+/**
+ * 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 = {
@@ -39,16 +57,25 @@ 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;
 /**