@polydeukes/core 0.4.0 → 0.6.0

package/dist/telemetry.js

@@ -1,14 +1,19 @@
 /**
- * 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.
  */
 import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+/**
+ * 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 const SKIP_REASONS = ['no-observation', 'config-fault', 'supply-pass'];
 const TAB = '\t';
 const VALID_EVENTS = [
     'passed',
@@ -22,15 +27,15 @@ const VALID_EVENTS = [
  * 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.
+ * A log written before the rename still carries the old name, and rejecting those rows as
+ * corrupt would discard the measurement rather than migrate it. Compatibility runs one way —
+ * {@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).
+ * Replace tab/newline/carriage-return with single spaces.
  *
  * Without this, a tab or newline inside a field would fabricate extra TSV fields or
  * extra lines — a record is always exactly one line.
@@ -38,23 +43,55 @@ const LEGACY_WITNESSED_EVENT = 'bypassed';
 function sanitize(value) {
     return value.replace(/[\t\n\r]/g, ' ');
 }
+/** True when `text` parses as a JSON array — the only shape the fifth field takes. */
+function isJsonArray(text) {
+    try {
+        return Array.isArray(JSON.parse(text));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * 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 function formatRecordLine(record) {
+    if (record.reason !== undefined) {
+        if (record.event !== 'skipped') {
+            throw new Error(`a skip reason belongs to a skipped row, not to '${record.event}'`);
+        }
+        if (record.witnesses !== undefined) {
+            throw new Error('a record carries either witnesses or a skip reason, never both');
+        }
+    }
     const fields = [record.timestamp, record.event, sanitize(record.label), sanitize(record.subject)];
+    if (record.witnesses !== undefined) {
+        fields.push(sanitize(record.witnesses));
+    }
+    else if (record.reason !== undefined) {
+        fields.push(record.reason);
+    }
     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 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 function parseRecordLine(line) {
     const trimmed = line.replace(/\n$/, '');
@@ -62,24 +99,36 @@ export function parseRecordLine(line) {
         return null;
     }
     const fields = trimmed.split(TAB);
-    if (fields.length !== 4) {
+    if (fields.length !== 4 && fields.length !== 5) {
         return null;
     }
-    const [timestamp, event, label, subject] = fields;
+    const [timestamp, event, label, subject, fifth] = fields;
     const resolved = event === LEGACY_WITNESSED_EVENT ? 'witnessed' : event;
     if (!VALID_EVENTS.includes(resolved)) {
         return null;
     }
-    return { timestamp, event: resolved, label, subject };
+    const record = { timestamp, event: resolved, label, subject };
+    if (fifth === undefined) {
+        return record;
+    }
+    if (resolved === 'skipped') {
+        // A skip carries no witness, so a JSON array here is as corrupt as a near-miss token.
+        return SKIP_REASONS.includes(fifth)
+            ? { ...record, reason: fifth }
+            : null;
+    }
+    // The fifth field is a JSON array or the line is corrupt: a stray tab inside a subject
+    // would otherwise read as a record with the wrong subject and no witnesses.
+    return isJsonArray(fifth) ? { ...record, witnesses: fifth } : 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.
@@ -94,12 +143,12 @@ export function appendRecord(path, record) {
     }
 }
 /**
- * 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 function appendRecordFailOpen(telemetryPath, record) {
     try {
@@ -111,7 +160,7 @@ export function appendRecordFailOpen(telemetryPath, record) {
     }
 }
 /**
- * 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
@@ -143,7 +192,7 @@ export function readRecords(path) {
     return { records, skipped };
 }
 /**
- * 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.
@@ -169,7 +218,7 @@ export function aggregateGain(records) {
  * Render a {@link GainSummary} into human-readable lines (pure).
  *
  * Each label is mentioned with its passed/blocked/witnessed/advised/skipped/unattributed
- * counts; each is a distinct column, never folded into another (PRD §4.4). A non-zero
+ * counts; each is a distinct column, never folded into another. A non-zero
  * corrupt-line count is reported rather than hidden — silent skipping would mask log
  * corruption.
  *
@@ -191,7 +240,7 @@ function renderGain(summary, skipped) {
     return lines.join('\n');
 }
 /**
- * `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

package/dist/transcript.d.ts

@@ -1,19 +1,14 @@
 /**
- * `CanonicalTranscript` — the agent-neutral session-query seam (CORE-04).
+ * `CanonicalTranscript` — the agent-neutral session-query seam.
  *
- * 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.
+ * This seam does not replace `CovenantInput`. The IR is the *data* a covenant judges;
+ * `CanonicalTranscript` is the *behavioral seam* that queries session data, 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;
-};
+import type { CovenantInput } from './protocol.ts';
 /**
- * One user message observed in the session (PRD §4.1).
+ * One user message observed in the session.
  *
  * `timestampMs` is epoch milliseconds. Its absence means the source cannot prove
  * freshness — the fail-closed signal a witness consumer must treat as "not fresh".
@@ -23,10 +18,10 @@ export type TranscriptUserMessage = {
     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.
+ * One tool call observed in the session. `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,
+ * `succeeded` is three-valued: `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.
@@ -37,40 +32,35 @@ export type TranscriptToolCall = {
     succeeded?: boolean;
 };
 /**
- * `CanonicalTranscript` — what a covenant may ask about the session (PRD §4.1).
+ * `CanonicalTranscript` — what a covenant may ask about the session.
  *
  * 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".
+ * The injection-absent default: 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).
+ * Wrap a {@link CovenantInput} as a {@link CanonicalTranscript}.
  *
- * Exposes `subagentSpawns` as invocations (filtered when a kind is given) and
- * `userMessages` with `timestampMs` omitted — the bare IR cannot prove freshness,
+ * Exposes `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).
+ * `findToolCalls` projects each call down to `{ name, args }` only: a call element also
+ * carries `fileChange` evidence, and evidence is judgment input, not session history — the
+ * two vocabularies stay separate. `succeeded` stays absent because these calls are the ones
+ * being judged right now: they have not run, and a call can never be its own precedent.
  */
 export declare function transcriptFromInput(input: CovenantInput): CanonicalTranscript;

package/dist/transcript.js

@@ -1,43 +1,35 @@
 /**
- * `CanonicalTranscript` — the agent-neutral session-query seam (CORE-04).
+ * `CanonicalTranscript` — the agent-neutral session-query seam.
  *
- * 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.
+ * This seam does not replace `CovenantInput`. The IR is the *data* a covenant judges;
+ * `CanonicalTranscript` is the *behavioral seam* that queries session data, 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.
  */
 /**
- * The injection-absent default (PRD §4.2): every query answers "nothing happened".
+ * The injection-absent default: 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 const noopTranscript = {
-    findSubagentInvocations: () => [],
     findUserMessages: () => [],
     findToolCalls: () => [],
 };
 /**
- * Wrap a {@link CovenantInput} as a {@link CanonicalTranscript} (PRD §4.2).
+ * Wrap a {@link CovenantInput} as a {@link CanonicalTranscript}.
  *
- * Exposes `subagentSpawns` as invocations (filtered when a kind is given) and
- * `userMessages` with `timestampMs` omitted — the bare IR cannot prove freshness,
+ * Exposes `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).
+ * `findToolCalls` projects each call down to `{ name, args }` only: a call element also
+ * carries `fileChange` evidence, and evidence is judgment input, not session history — the
+ * two vocabularies stay separate. `succeeded` stays absent because these calls are the ones
+ * being judged right now: they have not run, and a call can never be its own precedent.
  */
 export function transcriptFromInput(input) {
     return {
-        findSubagentInvocations: (kind) => input.subagentSpawns
-            .filter((spawn) => kind === undefined || spawn.kind === kind)
-            .map((spawn) => ({ kind: spawn.kind })),
         findUserMessages: () => input.userMessages.map((message) => ({ text: message.text })),
         findToolCalls: (name) => input.toolCalls
             .filter((call) => name === undefined || call.name === name)

package/dist/validation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `validation.ts` — the shape-checking primitives the core's validators share.
+ *
+ * Internal to the core: `config.ts` and `algebra.ts` both build on these, and neither
+ * owns them. Not a public export — `isPlainObject` has its own file because it *is* one.
+ */
+/**
+ * `ConfigValidationError` — raised when a config fails structural validation.
+ *
+ * The message names the offending field path so the developer sees exactly what is wrong.
+ * This throw is a developer-time error (config authoring), a different axis from the
+ * covenant runtime's fail-closed exit code — a bad config should fail loud and early.
+ */
+export declare class ConfigValidationError extends Error {
+    constructor(message: string);
+}
+/** Throw on the first key outside the allowed vocabulary, naming the key and its location. */
+export declare function rejectUnknownKeys(record: Record<string, unknown>, allowed: ReadonlySet<string>, location: string): void;
+/** True when the value is a string with at least one character. */
+export declare function isNonEmptyString(value: unknown): value is string;
+/** True when the value is an array whose every element is a string. */
+export declare function isStringArray(value: unknown): value is string[];
+/** Throw unless the pattern string compiles with `new RegExp` — compilability only, never run. */
+export declare function rejectUncompilableRegex(pattern: string, location: string): void;

package/dist/validation.js

@@ -0,0 +1,44 @@
+/**
+ * `validation.ts` — the shape-checking primitives the core's validators share.
+ *
+ * Internal to the core: `config.ts` and `algebra.ts` both build on these, and neither
+ * owns them. Not a public export — `isPlainObject` has its own file because it *is* one.
+ */
+/**
+ * `ConfigValidationError` — raised when a config fails structural validation.
+ *
+ * The message names the offending field path so the developer sees exactly what is wrong.
+ * This throw is a developer-time error (config authoring), a different axis from the
+ * covenant runtime's fail-closed exit code — a bad config should fail loud and early.
+ */
+export class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+/** Throw on the first key outside the allowed vocabulary, naming the key and its location. */
+export function rejectUnknownKeys(record, allowed, location) {
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw new ConfigValidationError(`unknown key '${key}' in ${location}`);
+        }
+    }
+}
+/** True when the value is a string with at least one character. */
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** True when the value is an array whose every element is a string. */
+export function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+/** Throw unless the pattern string compiles with `new RegExp` — compilability only, never run. */
+export function rejectUncompilableRegex(pattern, location) {
+    try {
+        new RegExp(pattern);
+    }
+    catch {
+        throw new ConfigValidationError(`${location} must be a compilable regular expression`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polydeukes/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Polydeukes core — covenant protocol, config loader, and transcript interface. Domain- and agent-agnostic. Alpha.",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,8 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./schema.json": "./schema/polydeukes.schema.json"
+    "./schema.json": "./schema/polydeukes.schema.json",
+    "./algebra-declaration.schema.json": "./schema/algebra-declaration.schema.json"
   },
   "files": [
     "dist",