@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/tuition.js

@@ -0,0 +1,311 @@
+/**
+ * THE TUITION FEED AND THE MECHANISM INDEX (kernel plan M3, M3-P8; R-091).
+ *
+ * A tuition entry records one failure mode a delivery paid for. The MECHANISM
+ * INDEX is a PROJECTION of the `mechanisms[]` field of every entry in the
+ * feed, keyed by mechanism, and it is generated rather than authored. T-005 is
+ * why both halves exist and why they are one artifact rather than two: a rule
+ * M1-P3 paid for did not reach M1-P5, which reimplemented the same claim-file
+ * mechanism silently and produced the most severe defect found in M1, and a
+ * second hand-maintained copy of a rule is the state that produced it.
+ *
+ * THE TWO LAYERS ARE STRUCTURALLY DISTINCT, which is the plan's compaction
+ * model (step 2c). The index is the READ layer: dense, consulted at every
+ * dispatch under the `mechanism-lookup` obligation. The entries are the
+ * ARCHIVE layer: longer, read when a rule is disputed. `tuition index --check`
+ * is what keeps the first honest about the second.
+ *
+ * PATHS THIS MODULE READS ARE NOT ITS OWN (D-M3-27, the mechanism index's own
+ * row "Reading a path whose type is not established"). Every read goes through
+ * `readOperatorPath`, so a named pipe at an entry path is refused with the
+ * observed entry type instead of blocking the command forever.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { classifyContextDirectory, decodeDocument, formatDiagnostics, readOperatorPath, validateInstance, } from "./validate.js";
+import { loadTypeSchema } from "./commands/validate.js";
+/** The generated index, relative to a tuition directory. */
+export const MECHANISM_INDEX_FILE = "mechanism-index.yaml";
+/**
+ * THE KEY IS DERIVED FROM THE NAME, NEVER INVENTED: lowercase, every run of
+ * characters outside [a-z0-9] collapsed to one hyphen, ends trimmed. The same
+ * derivation `schemas/mechanism-index.schema.json` documents and M3-P6's
+ * registered test applies, stated once in code so the generator and the check
+ * cannot disagree about it.
+ */
+export function mechanismKey(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Every tuition ENTRY file in a directory, sorted by name.
+ *
+ * The generated index lives in the same directory and is EXCLUDED BY NAME: it
+ * is the projection's output, and a projection that reads its own output is a
+ * loop rather than a check. Anything that is not a `.yaml` file is ignored, so
+ * a README beside the feed is not an entry.
+ */
+export function listEntryFiles(directory) {
+    const problem = classifyContextDirectory(directory);
+    if (problem !== undefined) {
+        return { ok: false, reason: problem };
+    }
+    let names;
+    try {
+        names = readdirSync(directory);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `${directory} could not be listed: ${String(error)}`,
+        };
+    }
+    const paths = names
+        .filter((name) => name.endsWith(".yaml") && name !== MECHANISM_INDEX_FILE)
+        .sort()
+        .map((name) => join(directory, name));
+    return { ok: true, paths };
+}
+/**
+ * Read, decode and schema-validate one tuition entry.
+ *
+ * THE RAW BYTES COME BACK WITH THE ENTRY, and that is not a convenience. An
+ * earlier version had `tuition add` call this and then read the same path a
+ * second time for the bytes to write. Two reads meant two independent
+ * refusals of a non-regular path, and a refusal that another refusal shadows
+ * cannot be witnessed: mutating either left the other rejecting the same
+ * input, which is exactly the shape T-018 records. One read, one
+ * classification, one guard.
+ */
+export function loadEntry(path) {
+    const read = readOperatorPath(path);
+    if (!read.ok) {
+        return { ok: false, reason: read.reason, diagnostics: [] };
+    }
+    const decoded = decodeDocument(read.body, path);
+    if (!decoded.ok) {
+        return { ok: false, reason: decoded.reason, diagnostics: [] };
+    }
+    const diagnostics = formatDiagnostics(validateInstance(loadTypeSchema("tuition"), decoded.value));
+    if (diagnostics.length > 0) {
+        return {
+            ok: false,
+            reason: `${path} is not a valid tuition entry`,
+            diagnostics,
+        };
+    }
+    return { ok: true, entry: decoded.value, body: read.body };
+}
+/**
+ * Project the mechanism index out of a set of entries, sorted by key.
+ *
+ * A KEY CLAIMED BY TWO ENTRIES IS AN ERROR NAMING BOTH, never a silent
+ * first-wins. Two entries stating the same mechanism differently is exactly
+ * the divergence this document exists to prevent, and the projection cannot
+ * decide which of the two rules the project actually learned. The resolution
+ * is an editorial one: merge the two entries' rules by hand into whichever one
+ * owns the mechanism.
+ */
+export function projectIndex(entries) {
+    const byKey = new Map();
+    for (const entry of entries) {
+        for (const declaration of entry.mechanisms ?? []) {
+            const key = mechanismKey(declaration.mechanism);
+            if (key === "") {
+                return {
+                    ok: false,
+                    reason: `${entry.id} declares mechanism ${JSON.stringify(declaration.mechanism)}, whose derived key is empty`,
+                };
+            }
+            const existing = byKey.get(key);
+            if (existing !== undefined) {
+                return {
+                    ok: false,
+                    reason: `mechanism ${key} is declared by both ${existing.source} and ${entry.id}; one entry owns a mechanism`,
+                };
+            }
+            const row = {
+                key,
+                name: declaration.mechanism,
+                rule: declaration.rule,
+                evidence: [...declaration.evidence],
+                source: entry.id,
+            };
+            if (declaration.siblings !== undefined) {
+                row.siblings = [...declaration.siblings];
+            }
+            const machine = declaration["machine-readable-form"];
+            if (machine !== undefined) {
+                row["machine-readable-form"] = { path: machine.path, key: machine.key };
+            }
+            byKey.set(key, row);
+        }
+    }
+    const rows = [...byKey.values()].sort((a, b) => (a.key < b.key ? -1 : 1));
+    return { ok: true, rows };
+}
+/* ------------------------------------------------------------------ */
+/* Rendering                                                            */
+/* ------------------------------------------------------------------ */
+/**
+ * Emit a YAML scalar, quoting only when a plain one would not round trip.
+ *
+ * THE CONDITION IS THE POINT: this generator's output is re-read by
+ * `--check`, so a scalar that YAML would decode as something other than the
+ * string handed in makes the projection disagree with itself. The reserved
+ * leading indicators, an embedded `: ` or ` #`, and a trailing colon are the
+ * cases; everything else is emitted plain, which is what keeps the document
+ * readable.
+ */
+export function yamlScalar(value) {
+    const risky = value === "" ||
+        /^[-?:,[\]{}#&*!|>'"%@`]/.test(value) ||
+        value.includes(": ") ||
+        value.includes(" #") ||
+        value.endsWith(":") ||
+        value.includes("\n") ||
+        value.trim() !== value;
+    return risky ? JSON.stringify(value) : value;
+}
+/** Fold one paragraph to a width, at spaces, with a fixed indent. */
+function foldedBlock(text, indent, width) {
+    const words = text.split(/\s+/).filter((word) => word !== "");
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current === "") {
+            current = word;
+            continue;
+        }
+        if (`${current} ${word}`.length + indent.length > width) {
+            lines.push(`${indent}${current}`);
+            current = word;
+            continue;
+        }
+        current = `${current} ${word}`;
+    }
+    if (current !== "") {
+        lines.push(`${indent}${current}`);
+    }
+    return lines;
+}
+const HEADER = `# THE MECHANISM INDEX (kernel plan M3; T-005, D-M3-23).
+#
+# GENERATED BY \`tiphys tuition index\`. DO NOT EDIT THIS FILE. It is a
+# PROJECTION of the \`mechanisms[]\` field of every entry in the tuition feed
+# beside it, so a rule is recorded once, in the entry that paid for it, and
+# read from here. \`tiphys tuition index --check\` compares this file against a
+# fresh projection and exits nonzero on any drift, which is what stops the two
+# from becoming two sources.
+#
+# READ THE ROW BEFORE YOU USE THE MECHANISM. Every rule here was paid for with
+# a defect, a fix round, or an investigation, which is why \`evidence\` is a
+# required field with at least one entry: a rule with no citation is not a
+# rule.
+#
+# WHY THIS FILE EXISTS AT ALL. T-005 records a rule M1-P3 paid for in a
+# multi-hour investigation that did not reach M1-P5, which reimplemented the
+# same claim-file mechanism silently and produced the most severe defect found
+# in that milestone. The implementer there had read the plan, the agent-rules
+# file, the constraint list, the accumulated environment warnings and three
+# work histories. None of them carried the rule, because a rule about a
+# MECHANISM has no home in a set of documents organised by phase. This is that
+# home, and the obligation to consult it is the \`mechanism-lookup\` clause in
+# roles/implementer.md.
+#
+# \`key\` IS DERIVED FROM \`name\`, NOT INVENTED: lowercase, every run of
+# characters outside [a-z0-9] collapsed to one hyphen, ends trimmed.
+`;
+/** Render the index document. The bytes are what `--check` compares. */
+export function renderIndex(rows) {
+    const lines = [HEADER, "kind: mechanism-index", "version: 1", "", "mechanisms:"];
+    for (const row of rows) {
+        lines.push(`  - key: ${row.key}`);
+        lines.push(`    name: ${yamlScalar(row.name)}`);
+        lines.push("    rule: >-");
+        lines.push(...foldedBlock(row.rule, "      ", 78));
+        if (row.siblings !== undefined) {
+            if (row.siblings.length === 0) {
+                lines.push("    siblings: []");
+            }
+            else {
+                lines.push("    siblings:");
+                for (const sibling of row.siblings) {
+                    lines.push(`      - ${yamlScalar(sibling)}`);
+                }
+            }
+        }
+        const machine = row["machine-readable-form"];
+        if (machine !== undefined) {
+            lines.push("    machine-readable-form:");
+            lines.push(`      path: ${yamlScalar(machine.path)}`);
+            lines.push(`      key: ${yamlScalar(machine.key)}`);
+        }
+        lines.push("    evidence:");
+        for (const item of row.evidence) {
+            lines.push(`      - ${yamlScalar(item)}`);
+        }
+        lines.push("");
+    }
+    /* One trailing newline, never two: the last row already pushed a blank. */
+    return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+}
+/**
+ * Compare a committed index document against a fresh projection.
+ *
+ * NAMES THE MECHANISM AND THE ENTRY IT CAME FROM, which is the criterion's
+ * letter (4): a reader of a red `--check` must be able to go straight to the
+ * file that changed. Both directions are reported, because a row DELETED from
+ * the feed and a row ADDED to it are different faults with the same symptom.
+ *
+ * The field comparison is over the DECODED values rather than the bytes, so a
+ * rewrap of a folded scalar is not reported as a rule change; a byte
+ * comparison is done by the caller afterwards and reported as formatting,
+ * which keeps "the rule changed" and "the file was hand-edited" apart.
+ */
+export function driftLines(committed, rows) {
+    const problems = [];
+    const document = committed;
+    const committedRows = Array.isArray(document?.mechanisms)
+        ? document.mechanisms
+        : [];
+    const committedByKey = new Map();
+    for (const row of committedRows) {
+        if (typeof row?.key === "string") {
+            committedByKey.set(row.key, row);
+        }
+    }
+    for (const row of rows) {
+        const found = committedByKey.get(row.key);
+        if (found === undefined) {
+            problems.push(`mechanism ${row.key} is declared by tuition entry ${row.source} and is missing from the committed index`);
+            continue;
+        }
+        const expected = JSON.stringify({
+            name: row.name,
+            rule: row.rule,
+            siblings: row.siblings ?? null,
+            machine: row["machine-readable-form"] ?? null,
+            evidence: row.evidence,
+        });
+        const actual = JSON.stringify({
+            name: found.name,
+            rule: typeof found.rule === "string" ? found.rule.trim() : found.rule,
+            siblings: found.siblings ?? null,
+            machine: found["machine-readable-form"] ?? null,
+            evidence: found.evidence,
+        });
+        if (expected !== actual) {
+            problems.push(`mechanism ${row.key} differs from the projection of tuition entry ${row.source}`);
+        }
+    }
+    const projected = new Set(rows.map((row) => row.key));
+    for (const key of [...committedByKey.keys()].sort()) {
+        if (!projected.has(key)) {
+            problems.push(`mechanism ${key} is in the committed index and no tuition entry declares it`);
+        }
+    }
+    return problems;
+}

package/dist/src/validate.d.ts

@@ -0,0 +1,230 @@
+/**
+ * THE KERNEL'S SCHEMA VALIDATION ENGINE (kernel plan M3, M3-P1 step 8;
+ * DR-0013).
+ *
+ * DR-0013 decided this module's substance and it is not a set of defaults to
+ * be revisited casually. Ajv 8.20.0 exact, JSON Schema Draft 2020-12, strict
+ * mode, all errors, schema and meta-schema validation, and NO coercion, NO
+ * inserted defaults, NO removal of additional properties, NO mutation of the
+ * validated input and NO automatic loading of remote schemas. Unknown or
+ * invalidly combined keywords fail schema COMPILATION, before any instance is
+ * examined.
+ *
+ * AJV IS AN INTERNAL IMPLEMENTATION DETAIL (DR-0013 clause 5). Its wording is
+ * never a public contract. Every Ajv error is mapped, by keyword, into the
+ * Tiphys diagnostic contract
+ *
+ *   INVALID <json-pointer> <message>
+ *
+ * with a deterministic order. The order is a FINAL SORT by (pointer, message)
+ * applied to the collected list, not a property of the traversal, so a future
+ * engine that walks differently still emits the same lines in the same order.
+ * That is the same rule src/gates/validate.ts stated for M2 and it is
+ * deliberately identical: the two modules now share this one engine.
+ *
+ * THE MESSAGE TABLE IS THE CONTRACT, not Ajv's `message` field. A keyword
+ * whose Ajv error reaches `renderAjvError` without an entry in
+ * `MESSAGE_BY_KEYWORD` is a Tiphys DEFECT and is reported as one, naming the
+ * keyword, rather than being papered over with Ajv's own sentence. That
+ * refusal is what stops Ajv wording leaking into a public contract by
+ * omission (DR-0013 criterion 8).
+ *
+ * YAML IS INPUT DECODING AND IS A SEPARATE STAGE (DR-0013 YAML clause 3).
+ * `decodeDocument` decodes; `validateInstance` validates an already-decoded
+ * value. A decode failure and a validation failure are distinguishable in the
+ * diagnostic and neither produces a stack trace on any stream.
+ *
+ * PATHS THIS MODULE READS ARE NOT ITS OWN (D-M3-27, and the mechanism index's
+ * row `reading-a-path-whose-type-is-not-established`). Every read goes through
+ * `classifyEntry`, so a named pipe handed to `tiphys validate` is refused
+ * with the observed entry type instead of blocking the command forever.
+ */
+import type { Ajv2020 } from "ajv/dist/2020.js";
+import type { ValidateFunction } from "ajv/dist/2020.js";
+/** The dialect every Tiphys schema declares (DR-0013 clause 3). */
+export declare const TIPHYS_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/** The document root, in RFC 6901 URI-fragment form. */
+export declare const ROOT_POINTER = "#";
+export interface Diagnostic {
+    pointer: string;
+    message: string;
+}
+/**
+ * THE DECLARED AUTHORING VOCABULARY (DR-0013 clause 7), documented in
+ * `schemas/README.md` and asserted by `test/schemas.test.ts`. Ajv supplies
+ * Draft 2020-12 entire; this list is what Tiphys schemas are ALLOWED to use,
+ * so a keyword outside it is a deliberate expansion rather than an accident.
+ * Every entry has both a positive and a negative test (validator criterion 2)
+ * and therefore also has an entry in `MESSAGE_BY_KEYWORD`.
+ */
+export declare const AUTHORING_VOCABULARY: readonly string[];
+/** Annotations that carry no constraint and are permitted everywhere. */
+export declare const ANNOTATION_KEYS: readonly string[];
+/** Render a value the way every diagnostic in this contract renders one. */
+export declare function render(value: unknown): string;
+/** The JSON type name of a value, as the `type` keyword uses it. */
+export declare function jsonTypeOf(value: unknown): string;
+/**
+ * THE MESSAGE CONTRACT. One entry per way a value can fail. The first eight
+ * entries are M2's, copied verbatim from `src/gates/validate.ts`'s
+ * `DIAGNOSTIC_MESSAGES` because DR-0013 clause 6 retires that ENGINE while
+ * preserving its diagnostic contract: an M2 test asserting
+ * `required property id is missing` must still read exactly that after the
+ * swap, and that is checked by re-running M2's tests unchanged rather than by
+ * this comment.
+ */
+export declare const DIAGNOSTIC_MESSAGES: {
+    type: (expected: string, observed: string) => string;
+    required: (name: string) => string;
+    additionalProperties: (name: string) => string;
+    enum: (value: string, permitted: string) => string;
+    const: (value: string, required: string) => string;
+    minimum: (value: string, minimum: string) => string;
+    minItems: (count: string, minimum: string) => string;
+    pattern: (value: string, pattern: string) => string;
+    minLength: (value: string, minimum: string) => string;
+    uniqueItems: (first: string, second: string) => string;
+    contains: (minimum: string) => string;
+    containsValue: (value: string, minimum: string) => string;
+    oneOf: () => string;
+    ifThen: () => string;
+    maximum: (value: string, maximum: string) => string;
+    maxItems: (count: string, maximum: string) => string;
+    cyclicRef: (reference: string) => string;
+    unresolvedRef: (reference: string) => string;
+    unknownKeyword: (keyword: string) => string;
+    strictPolicyUntyped: (keyword: string, expected: string) => string;
+    strictPolicy: () => string;
+    remoteRef: (reference: string) => string;
+    invalidSchemaDocument: () => string;
+    patternUncompilable: () => string;
+    cyclicCompilation: () => string;
+    /** Nothing above matched. Deliberately carries no Ajv text at all. */
+    uncompilable: () => string;
+    /** A keyword Ajv reported that this table does not translate. */
+    untranslated: (keyword: string) => string;
+};
+/**
+ * `INVALID <json-pointer> <message>`. The public contract, shared with
+ * `src/gates/validate.ts`.
+ *
+ * Pointers are RFC 6901 JSON Pointers in URI-fragment form, so the document
+ * root is `#` and a nested location is `#/gates/0/id`. The fragment form is
+ * chosen because the bare pointer to the root is the EMPTY STRING, which
+ * would render this line with two consecutive spaces.
+ */
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): string[];
+/** The contract's deterministic order: by pointer, then by message, ASCII. */
+export declare function sortDiagnostics(diagnostics: Diagnostic[]): Diagnostic[];
+export type SchemaDocument = Record<string, unknown>;
+/**
+ * A fresh Ajv, configured EXACTLY as DR-0013 clause 4 lists. Each policy is
+ * named so a diff that removes one is visible as the removal of a decided
+ * policy rather than as a formatting change.
+ */
+export declare function makeAjv(): Ajv2020;
+/** A compiled validator, or the reason the schema could not be compiled. */
+export type Compilation = {
+    ok: true;
+    validator: ValidateFunction;
+}
+/**
+ * `diagnostics` is the contract; `reason` is the same thing rendered as one
+ * line, kept because callers that only want to print something want a
+ * string. Both are Tiphys-owned: no Ajv sentence reaches either.
+ */
+ | {
+    ok: false;
+    diagnostics: Diagnostic[];
+    reason: string;
+};
+/**
+ * Compile a schema. Cached by schema OBJECT IDENTITY, because a fresh Ajv per
+ * call is both slow and wrong: two schemas carrying the same `$id` cannot
+ * share one Ajv instance, so each schema gets its own.
+ *
+ * IDENTITY, NOT CONTENT, and it has one observable consequence worth stating
+ * rather than discovering. A caller that MUTATES a schema object in place
+ * after compiling it keeps the old validator, because the WeakMap key is
+ * unchanged. That is correct for how schemas are used here (documents read
+ * from disk and never edited), and it was measured: the first attempt at
+ * criterion 4's red witness defanged a keyword in place and the diagnostics
+ * did not move, which read exactly like a schema whose keyword was doing
+ * nothing. The witness was redone with a schema re-read from disk per arm.
+ * Any future caller that wants to compile a modified schema must hand over a
+ * NEW object.
+ *
+ * The cache is keyed by the schema object AND by the COMPANION LIST, also by
+ * identity: the same document compiled with and without a companion is two
+ * different compilations, and returning the first for the second would be the
+ * quiet wrong answer. Companion lists here are one or zero long, so the scan
+ * is a scan of a one-element array.
+ */
+export declare function compileSchema(schema: SchemaDocument, companions?: readonly SchemaDocument[]): Compilation;
+/**
+ * Translate a COMPILATION failure into the Tiphys diagnostic contract.
+ *
+ * The classification reads Ajv's exception only to EXTRACT IDENTIFIERS from
+ * it; nothing Ajv wrote is passed through. An unrecognised shape becomes the
+ * bare `schema could not be compiled`, which loses detail deliberately:
+ * losing detail is recoverable, and leaking a third party's wording into a
+ * contract nine phases are written against is not.
+ */
+export declare function compilationDiagnostics(error: unknown, ajv: Ajv2020, schema: SchemaDocument): Diagnostic[];
+/**
+ * Validate an already-decoded instance against a schema document.
+ *
+ * Returns diagnostics in the contract's deterministic order. A schema that
+ * cannot be compiled yields ONE root diagnostic rather than a throw: this
+ * function is called from a CLI whose ordinary input is hand-authored, and a
+ * thrown compile error there is the stack trace step 8b exists to prevent.
+ */
+export declare function validateInstance(schema: SchemaDocument, instance: unknown, companions?: readonly SchemaDocument[]): Diagnostic[];
+/** Validate and format in one step. */
+export declare function validateToLines(schema: SchemaDocument, instance: unknown, companions?: readonly SchemaDocument[]): string[];
+/**
+ * A decode outcome. A DECODE failure and a VALIDATION failure are different
+ * things and the caller can tell which it has, which is the separation
+ * DR-0013 YAML clause 3 requires.
+ */
+export type DecodeResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decode YAML (or JSON, which YAML 1.2 is a superset of) into a plain value.
+ *
+ * A parse failure returns a reason, never a throw and never a stack trace.
+ * `yaml` reports position information; it is collapsed to one line because
+ * the contract is one diagnostic line per failure.
+ */
+export declare function decodeDocument(text: string, label: string): DecodeResult;
+/** What a guarded read of an operator-supplied path produced. */
+export type GuardedRead = {
+    ok: true;
+    body: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * READ A PATH THIS PROGRAM DID NOT CREATE (D-M3-27).
+ *
+ * `tiphys validate <file>` takes an operator-supplied path, so the path may
+ * be a FIFO, a directory, a socket or a dangling symlink. Opening a FIFO with
+ * no writer blocks forever and the command never returns, which is the M1-P5
+ * class (CR-520). The type is established with `classifyEntry` BEFORE the
+ * open, and an irregular entry is refused naming the path and the observed
+ * type.
+ */
+export declare function readOperatorPath(path: string): GuardedRead;
+/**
+ * Establish that a path is a DIRECTORY before walking it. Same hazard, same
+ * rule: `--context` is operator-supplied and a FIFO there would block the
+ * walk exactly as it blocks a read.
+ */
+export declare function classifyContextDirectory(path: string): string | undefined;