@polydeukes/core 0.5.0 → 0.6.0

package/dist/telemetry.js

@@ -1,12 +1,19 @@
 /**
  * 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.
  */
 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',
@@ -36,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$/, '');
@@ -60,15 +99,27 @@ 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.

package/dist/transcript.d.ts

@@ -6,11 +6,7 @@
  * 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.
  *
@@ -43,8 +39,6 @@ export type TranscriptToolCall = {
  * 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. */
@@ -59,8 +53,7 @@ export declare const noopTranscript: CanonicalTranscript;
 /**
  * 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.

package/dist/transcript.js

@@ -12,15 +12,13 @@
  * so does a precedent consumer (no evidence, gate stays shut).
  */
 export const noopTranscript = {
-    findSubagentInvocations: () => [],
     findUserMessages: () => [],
     findToolCalls: () => [],
 };
 /**
  * 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.
@@ -32,9 +30,6 @@ export const noopTranscript = {
  */
 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.5.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",

package/schema/algebra-declaration.schema.json

@@ -0,0 +1,402 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/huskyhoochu/polydeukes/schema/algebra-declaration.schema.json",
+  "title": "Polydeukes algebra declaration",
+  "description": "One algebra declaration: five blocks, a relation position closed to seven names, a binary combinator position closed to three, and an open unary extraction vocabulary. Reference resolution, relate-entry id uniqueness, and cycle detection are validator-only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["discipline", "mechanism", "extract", "relate"],
+  "properties": {
+    "discipline": {
+      "type": "string",
+      "minLength": 1
+    },
+    "mechanism": {
+      "type": "string",
+      "enum": [
+        "pairing",
+        "companion",
+        "monotonic-order",
+        "fingerprint-sync",
+        "producer-owned",
+        "self-absolution-ban",
+        "actor-scope",
+        "precedent",
+        "phase-order",
+        "turn-locality",
+        "stated-ground",
+        "controlled-vocabulary",
+        "naming",
+        "added-only",
+        "one-way-marker",
+        "scoped-valve",
+        "forbidden-command"
+      ]
+    },
+    "scope": {
+      "$ref": "#/$defs/scope"
+    },
+    "sources": {
+      "$ref": "#/$defs/sources"
+    },
+    "supply": {
+      "$ref": "#/$defs/supply"
+    },
+    "extract": {
+      "$ref": "#/$defs/extract"
+    },
+    "relate": {
+      "$ref": "#/$defs/relate"
+    },
+    "witness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["relate"],
+      "properties": {
+        "extract": {
+          "$ref": "#/$defs/extract"
+        },
+        "relate": {
+          "$ref": "#/$defs/relate"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "extractName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "not": { "enum": ["changes", "state", "actor"] }
+        },
+        "include": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "regex"
+          }
+        },
+        "exclude": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "regex"
+          }
+        },
+        "excludeIgnoreCase": {
+          "type": "boolean"
+        }
+      }
+    },
+    "sources": {
+      "description": "What each name outside the target stands for, under the name a declaration reads it by. The kind position is closed to 'file', 'sidecar' and 'transcript', exactly one per entry: a file path is repo-relative, so a leading '/' and a '..' segment are refused, and a sidecar channel's or a transcript's value is the marker true because its location is the host's fact.",
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "not": {
+          "enum": ["target.path", "pre", "post", "state", "changes", "command", "actor"]
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "oneOf": [
+          {
+            "additionalProperties": false,
+            "required": ["file"],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!/)(?!(.*/)?\\.\\.(/|$))"
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "required": ["sidecar"],
+            "properties": {
+              "sidecar": {
+                "const": true
+              }
+            }
+          },
+          {
+            "additionalProperties": false,
+            "required": ["transcript"],
+            "properties": {
+              "transcript": {
+                "const": true
+              }
+            }
+          }
+        ]
+      }
+    },
+    "supply": {
+      "type": "object",
+      "properties": {
+        "state": {
+          "enum": ["error", "pass"]
+        }
+      },
+      "additionalProperties": {
+        "enum": ["error", "pass", "empty"]
+      }
+    },
+    "extract": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/$defs/pipeline"
+      }
+    },
+    "pipeline": {
+      "description": "A combinator stands only as the first step: prefixItems governs position 0, items governs the rest.",
+      "type": "array",
+      "minItems": 1,
+      "prefixItems": [
+        {
+          "$ref": "#/$defs/step"
+        }
+      ],
+      "items": {
+        "$ref": "#/$defs/unaryStep"
+      }
+    },
+    "step": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/combinatorStep"
+        },
+        {
+          "$ref": "#/$defs/unaryStep"
+        }
+      ]
+    },
+    "combinatorStep": {
+      "type": "object",
+      "required": ["op"],
+      "properties": {
+        "op": {
+          "enum": ["union", "onlyIn", "intersect"]
+        }
+      },
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "required": ["op", "of"],
+          "properties": {
+            "op": {
+              "enum": ["union", "intersect"]
+            },
+            "of": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "items": {
+                "$ref": "#/$defs/extractName"
+              },
+              "uniqueItems": true
+            }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "of", "notIn"],
+          "properties": {
+            "op": {
+              "const": "onlyIn"
+            },
+            "of": {
+              "$ref": "#/$defs/extractName"
+            },
+            "notIn": {
+              "$ref": "#/$defs/extractName"
+            }
+          }
+        }
+      ]
+    },
+    "unaryStep": {
+      "description": "Open vocabulary: any name outside the three combinators, arguments unconstrained — except that referencing two extractions (an array `of`, or a `notIn`) makes the step a combinator by shape.",
+      "type": "object",
+      "required": ["op"],
+      "properties": {
+        "op": {
+          "type": "string",
+          "minLength": 1,
+          "not": {
+            "enum": ["union", "onlyIn", "intersect"]
+          }
+        },
+        "of": {
+          "not": {
+            "type": "array"
+          }
+        }
+      },
+      "not": {
+        "required": ["notIn"]
+      }
+    },
+    "relate": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/relateEntry"
+      }
+    },
+    "relateEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "relation"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "relation": {
+          "$ref": "#/$defs/relation"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "messageBySide": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["left", "right"],
+          "properties": {
+            "left": {
+              "type": "string",
+              "minLength": 1
+            },
+            "right": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      },
+      "oneOf": [
+        {
+          "description": "A plain message, on any relation.",
+          "required": ["message"],
+          "not": {
+            "required": ["messageBySide"]
+          }
+        },
+        {
+          "description": "Side-keyed messages, only on Equal — the one relation with two sides.",
+          "required": ["messageBySide"],
+          "not": {
+            "required": ["message"]
+          },
+          "properties": {
+            "relation": {
+              "properties": {
+                "op": {
+                  "const": "equal"
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "relation": {
+      "type": "object",
+      "required": ["op"],
+      "properties": {
+        "op": {
+          "enum": ["empty", "nonEmpty", "equal", "subset", "implies", "ordered", "unchanged"]
+        }
+      },
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "required": ["op", "of"],
+          "properties": {
+            "op": {
+              "enum": ["empty", "nonEmpty", "unchanged"]
+            },
+            "of": {
+              "$ref": "#/$defs/extractName"
+            }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "of"],
+          "properties": {
+            "op": {
+              "const": "equal"
+            },
+            "of": {
+              "type": "array",
+              "minItems": 2,
+              "maxItems": 2,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/extractName"
+              }
+            }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "of", "in"],
+          "properties": {
+            "op": {
+              "const": "subset"
+            },
+            "of": {
+              "$ref": "#/$defs/extractName"
+            },
+            "in": {
+              "$ref": "#/$defs/extractName"
+            }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "of", "requires"],
+          "properties": {
+            "op": {
+              "const": "implies"
+            },
+            "of": {
+              "$ref": "#/$defs/extractName"
+            },
+            "requires": {
+              "$ref": "#/$defs/extractName"
+            }
+          }
+        },
+        {
+          "additionalProperties": false,
+          "required": ["op", "of"],
+          "properties": {
+            "op": {
+              "const": "ordered"
+            },
+            "of": {
+              "$ref": "#/$defs/extractName"
+            },
+            "strict": {
+              "type": "boolean"
+            }
+          }
+        }
+      ]
+    }
+  }
+}