@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/validate.d.ts

@@ -0,0 +1,121 @@
+/**
+ * THE MINIMAL IN-REPO SCHEMA VALIDATOR (kernel plan M2, M2-P1 step 4;
+ * M2-D-04; DR-0013 clause 6).
+ *
+ * M1 shipped zero runtime dependencies. DR-0013 decided the library
+ * question for M3 (Ajv 8.20.0 exact, Draft 2020-12) and made THIS module the
+ * seam: M3-P1 retires the engine below and keeps the boundary. That promise
+ * is only keepable if two things are true here, and both are enforced by
+ * this module's tests rather than asserted in prose:
+ *
+ *   1. THE DIAGNOSTIC CONTRACT IS `INVALID <json-pointer> <message>`, one
+ *      line per failure, in a deterministic order. That string is this
+ *      module's public output. Everything else about how a failure was
+ *      found is an implementation detail and no test may assert on it.
+ *   2. THE MESSAGE TEXTS BELOW ARE THE CONTRACT, not this engine's wording.
+ *      They are listed in `DIAGNOSTIC_MESSAGES` so a future engine has one
+ *      table to map onto instead of a search through call sites.
+ *
+ * Without those two, DR-0013's "all existing M2 validation tests are re-run
+ * against it" would be a rewrite of the tests rather than an engine swap,
+ * and "the module boundary is preserved" would be false at the moment it was
+ * acted on.
+ *
+ * DETERMINISTIC ORDERING, stated so a replacement engine can reproduce it:
+ * every diagnostic is collected during a traversal that visits object
+ * properties in sorted key order and array items in index order, and the
+ * collected list is then sorted by (pointer, message) with ASCII
+ * lexicographic comparison. The final sort is what makes the order a
+ * property of the CONTRACT rather than of the traversal, so an engine that
+ * walks differently still emits the same lines in the same order.
+ *
+ * THE CLOSED KEYWORD SET, AND WHY IT IS LOUD (M2-D-04). Ten validation
+ * keywords plus local `$ref`. A schema document containing any other
+ * keyword is a LOAD ERROR naming the keyword and its location. It is never
+ * ignored, because a validator that silently skips `oneOf` reports a
+ * document valid while never having checked the constraint that mattered,
+ * which is the same shape as "green by omission" one layer down. The set is
+ * deliberately NOT grown to anticipate M3's five artifact schemas; DR-0013
+ * decided that question against extension.
+ */
+/** The ten validation keywords plus local `$ref`. Nothing else validates. */
+export declare const VALIDATION_KEYWORDS: readonly string[];
+/**
+ * Keys that carry no constraint and are permitted for documentation and for
+ * holding subschemas. They are listed separately from the validation
+ * keywords on purpose: a reader must be able to see that permitting
+ * `description` is a decision about annotations and not a hole in the closed
+ * set.
+ */
+export declare const ANNOTATION_KEYS: readonly string[];
+export interface Diagnostic {
+    pointer: string;
+    message: string;
+}
+/**
+ * `INVALID <json-pointer> <message>`. The module's public contract.
+ *
+ * Pointers are JSON Pointers in RFC 6901 URI-fragment form, so the document
+ * root is `#` and a nested location is `#/gates/0/id`. The fragment form is
+ * chosen over the bare form for one mechanical reason: the bare pointer to
+ * the root is the EMPTY STRING, which would render this line with two
+ * consecutive spaces and make the three fields ambiguous to split. A
+ * diagnostic is reported at the pointer of the OFFENDING LOCATION, not of
+ * its parent, so a missing required property points at the property that
+ * should have been there.
+ */
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+export declare function formatDiagnostics(diagnostics: Diagnostic[]): string[];
+/**
+ * THE MESSAGE CONTRACT. One entry per way a value can fail. A replacement
+ * engine maps its own errors onto these; a test asserts on these and never
+ * on anything else.
+ */
+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;
+    /**
+     * Authored by src/gates/manifest.ts, which cannot express "keyed by name"
+     * in the closed keyword set. It lives in THIS table anyway (CR-811): the
+     * table's stated purpose is to give a future engine one place to map onto
+     * instead of a search through call sites, and a message that sits outside
+     * it defeats that purpose whatever module emits it.
+     */
+    duplicateId: (id: string) => string;
+    /** A $ref chain that returns to itself without consuming an instance. */
+    cyclicRef: (reference: string) => string;
+    unresolvedRef: (reference: string) => string;
+};
+export type SchemaDocument = Record<string, unknown>;
+export type SchemaLoad = {
+    ok: true;
+    schema: SchemaDocument;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The document root, in URI-fragment form. */
+export declare const ROOT_POINTER = "#";
+/** The JSON type name of a value, as the `type` keyword uses it. */
+export declare function jsonTypeOf(value: unknown): string;
+/**
+ * Load a schema document, refusing loudly on any keyword outside the closed
+ * set. `name` appears in the reason so a caller with several documents knows
+ * which one failed.
+ */
+export declare function loadSchema(document: unknown, name: string): SchemaLoad;
+/**
+ * Validate an instance against a loaded schema. The returned list is sorted
+ * by (pointer, message), which is the deterministic order the contract
+ * promises and which is now produced by `sortDiagnostics` in the shared
+ * engine so the two modules cannot drift on it.
+ */
+export declare function validate(schema: SchemaDocument, instance: unknown): Diagnostic[];
+/** Validate and format in one step: the shape most callers want. */
+export declare function validateToLines(schema: SchemaDocument, instance: unknown): string[];

package/dist/src/gates/validate.js

@@ -0,0 +1,414 @@
+/**
+ * THE MINIMAL IN-REPO SCHEMA VALIDATOR (kernel plan M2, M2-P1 step 4;
+ * M2-D-04; DR-0013 clause 6).
+ *
+ * M1 shipped zero runtime dependencies. DR-0013 decided the library
+ * question for M3 (Ajv 8.20.0 exact, Draft 2020-12) and made THIS module the
+ * seam: M3-P1 retires the engine below and keeps the boundary. That promise
+ * is only keepable if two things are true here, and both are enforced by
+ * this module's tests rather than asserted in prose:
+ *
+ *   1. THE DIAGNOSTIC CONTRACT IS `INVALID <json-pointer> <message>`, one
+ *      line per failure, in a deterministic order. That string is this
+ *      module's public output. Everything else about how a failure was
+ *      found is an implementation detail and no test may assert on it.
+ *   2. THE MESSAGE TEXTS BELOW ARE THE CONTRACT, not this engine's wording.
+ *      They are listed in `DIAGNOSTIC_MESSAGES` so a future engine has one
+ *      table to map onto instead of a search through call sites.
+ *
+ * Without those two, DR-0013's "all existing M2 validation tests are re-run
+ * against it" would be a rewrite of the tests rather than an engine swap,
+ * and "the module boundary is preserved" would be false at the moment it was
+ * acted on.
+ *
+ * DETERMINISTIC ORDERING, stated so a replacement engine can reproduce it:
+ * every diagnostic is collected during a traversal that visits object
+ * properties in sorted key order and array items in index order, and the
+ * collected list is then sorted by (pointer, message) with ASCII
+ * lexicographic comparison. The final sort is what makes the order a
+ * property of the CONTRACT rather than of the traversal, so an engine that
+ * walks differently still emits the same lines in the same order.
+ *
+ * THE CLOSED KEYWORD SET, AND WHY IT IS LOUD (M2-D-04). Ten validation
+ * keywords plus local `$ref`. A schema document containing any other
+ * keyword is a LOAD ERROR naming the keyword and its location. It is never
+ * ignored, because a validator that silently skips `oneOf` reports a
+ * document valid while never having checked the constraint that mattered,
+ * which is the same shape as "green by omission" one layer down. The set is
+ * deliberately NOT grown to anticipate M3's five artifact schemas; DR-0013
+ * decided that question against extension.
+ */
+import { sortDiagnostics, validateInstance, } from "../validate.js";
+/** The ten validation keywords plus local `$ref`. Nothing else validates. */
+export const VALIDATION_KEYWORDS = [
+    "type",
+    "required",
+    "properties",
+    "additionalProperties",
+    "enum",
+    "items",
+    "minimum",
+    "minItems",
+    "pattern",
+    "const",
+    "$ref",
+];
+/**
+ * Keys that carry no constraint and are permitted for documentation and for
+ * holding subschemas. They are listed separately from the validation
+ * keywords on purpose: a reader must be able to see that permitting
+ * `description` is a decision about annotations and not a hole in the closed
+ * set.
+ */
+export const ANNOTATION_KEYS = [
+    "$schema",
+    "$id",
+    "title",
+    "description",
+    "$defs",
+];
+/**
+ * `INVALID <json-pointer> <message>`. The module's public contract.
+ *
+ * Pointers are JSON Pointers in RFC 6901 URI-fragment form, so the document
+ * root is `#` and a nested location is `#/gates/0/id`. The fragment form is
+ * chosen over the bare form for one mechanical reason: the bare pointer to
+ * the root is the EMPTY STRING, which would render this line with two
+ * consecutive spaces and make the three fields ambiguous to split. A
+ * diagnostic is reported at the pointer of the OFFENDING LOCATION, not of
+ * its parent, so a missing required property points at the property that
+ * should have been there.
+ */
+export function formatDiagnostic(diagnostic) {
+    return `INVALID ${diagnostic.pointer} ${diagnostic.message}`;
+}
+export function formatDiagnostics(diagnostics) {
+    return diagnostics.map(formatDiagnostic);
+}
+/**
+ * THE MESSAGE CONTRACT. One entry per way a value can fail. A replacement
+ * engine maps its own errors onto these; a test asserts on these and never
+ * on anything else.
+ */
+export const DIAGNOSTIC_MESSAGES = {
+    type: (expected, observed) => `expected type ${expected} but found ${observed}`,
+    required: (name) => `required property ${name} is missing`,
+    additionalProperties: (name) => `property ${name} is not permitted here`,
+    enum: (value, permitted) => `value ${value} is not one of the permitted values ${permitted}`,
+    const: (value, required) => `value ${value} does not equal the required constant ${required}`,
+    minimum: (value, minimum) => `value ${value} is below the minimum ${minimum}`,
+    minItems: (count, minimum) => `array has ${count} items, fewer than the required minimum ${minimum}`,
+    pattern: (value, pattern) => `value ${value} does not match the required pattern ${pattern}`,
+    /**
+     * Authored by src/gates/manifest.ts, which cannot express "keyed by name"
+     * in the closed keyword set. It lives in THIS table anyway (CR-811): the
+     * table's stated purpose is to give a future engine one place to map onto
+     * instead of a search through call sites, and a message that sits outside
+     * it defeats that purpose whatever module emits it.
+     */
+    duplicateId: (id) => `gate id ${id} is declared more than once`,
+    /** A $ref chain that returns to itself without consuming an instance. */
+    cyclicRef: (reference) => `schema reference ${reference} is cyclic`,
+    unresolvedRef: (reference) => `schema reference ${reference} does not resolve`,
+};
+/**
+ * Own-property test. `properties["__proto__"]` resolves through the prototype
+ * chain to `Object.prototype`, which is an object, so a naive lookup treats
+ * `__proto__` as a DECLARED property and lets it through
+ * `additionalProperties: false` (CR-808). Ajv rejects it, so this was also a
+ * seam divergence.
+ */
+function ownProperty(container, name) {
+    return Object.prototype.hasOwnProperty.call(container, name)
+        ? container[name]
+        : undefined;
+}
+function pointerSegment(segment) {
+    return segment.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function childPointer(pointer, segment) {
+    return `${pointer}/${pointerSegment(segment)}`;
+}
+/** The document root, in URI-fragment form. */
+export const ROOT_POINTER = "#";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The JSON type name of a value, as the `type` keyword uses it. */
+export function jsonTypeOf(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    const primitive = typeof value;
+    if (primitive === "number") {
+        return Number.isInteger(value) ? "integer" : "number";
+    }
+    if (primitive === "boolean") {
+        return "boolean";
+    }
+    if (primitive === "string") {
+        return "string";
+    }
+    return "object";
+}
+const PERMITTED_TYPES = [
+    "object",
+    "array",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+];
+/**
+ * Walk a schema document and refuse anything outside the closed set. The
+ * walk knows WHERE subschemas live (`properties/*`, `items`, `$defs/*` and
+ * the root), so a property literally named "oneOf" inside `properties` is a
+ * property name and not a keyword, and is not confused for one.
+ */
+function checkSchemaNode(node, pointer, problems) {
+    if (!isPlainObject(node)) {
+        problems.push(`${pointer} is not a schema object`);
+        return;
+    }
+    for (const key of Object.keys(node).sort()) {
+        if (VALIDATION_KEYWORDS.includes(key) || ANNOTATION_KEYS.includes(key)) {
+            continue;
+        }
+        problems.push(`unsupported schema keyword ${key} at ${pointer}`);
+    }
+    const type = node["type"];
+    if (type !== undefined) {
+        if (typeof type !== "string" || !PERMITTED_TYPES.includes(type)) {
+            problems.push(`unsupported type value at ${pointer}: this validator accepts a single type name from ${PERMITTED_TYPES.join(", ")}`);
+        }
+    }
+    const additional = node["additionalProperties"];
+    if (additional !== undefined && typeof additional !== "boolean") {
+        problems.push(`unsupported additionalProperties at ${pointer}: this validator accepts a boolean only`);
+    }
+    const required = node["required"];
+    if (required !== undefined && !Array.isArray(required)) {
+        problems.push(`required at ${pointer} is not an array`);
+    }
+    const enumeration = node["enum"];
+    if (enumeration !== undefined && !Array.isArray(enumeration)) {
+        problems.push(`enum at ${pointer} is not an array`);
+    }
+    const reference = node["$ref"];
+    if (reference !== undefined && typeof reference !== "string") {
+        problems.push(`$ref at ${pointer} is not a string`);
+    }
+    if (reference !== undefined) {
+        // CR-802. JSON Schema 2020-12 APPLIES keywords sitting beside `$ref`,
+        // and Ajv does too. This engine followed the reference and returned,
+        // dropping every sibling without a word: a KNOWN keyword in a position
+        // the validator silently ignores, which is the harder half of the
+        // attack the closed keyword set exists to stop, and a verdict change at
+        // the exact seam DR-0013 clause 6 promises M3-P1 can swap across.
+        //
+        // Refusing at load rather than implementing sibling application is the
+        // choice this module's philosophy already made everywhere else: a
+        // schema this engine cannot evaluate the way the specification says is
+        // rejected, never partially honoured. A schema that never uses the
+        // construct behaves identically under both engines.
+        const siblings = Object.keys(node)
+            .filter((key) => key !== "$ref" && VALIDATION_KEYWORDS.includes(key))
+            .sort();
+        if (siblings.length > 0) {
+            problems.push(`$ref at ${pointer} has sibling keyword(s) ${siblings.join(", ")}: ` +
+                "this validator does not apply keywords beside a $ref, and " +
+                "silently ignoring them would validate less than the schema says");
+        }
+    }
+    const properties = node["properties"];
+    if (properties !== undefined) {
+        if (!isPlainObject(properties)) {
+            problems.push(`properties at ${pointer} is not an object`);
+        }
+        else {
+            for (const name of Object.keys(properties).sort()) {
+                checkSchemaNode(ownProperty(properties, name), `${childPointer(pointer, "properties")}/${pointerSegment(name)}`, problems);
+            }
+        }
+    }
+    const defs = node["$defs"];
+    if (defs !== undefined) {
+        if (!isPlainObject(defs)) {
+            problems.push(`$defs at ${pointer} is not an object`);
+        }
+        else {
+            for (const name of Object.keys(defs).sort()) {
+                checkSchemaNode(ownProperty(defs, name), `${childPointer(pointer, "$defs")}/${pointerSegment(name)}`, problems);
+            }
+        }
+    }
+    const patternSource = node["pattern"];
+    if (patternSource !== undefined) {
+        if (typeof patternSource !== "string") {
+            problems.push(`pattern at ${pointer} is not a string`);
+        }
+        else {
+            // Compiled HERE so an unusable pattern is a load failure with a
+            // reason, not a throw escaping mid-validation. CR-801's derivation
+            // named this exact asymmetry: `new RegExp` on a CALLER-supplied
+            // pattern was guarded and `new RegExp` on a SCHEMA-supplied one was
+            // not, same call, same failure, one guarded.
+            try {
+                new RegExp(patternSource);
+            }
+            catch (error) {
+                problems.push(`pattern at ${pointer} is not a valid expression: ${error.message}`);
+            }
+        }
+    }
+    const items = node["items"];
+    if (items !== undefined) {
+        checkSchemaNode(items, childPointer(pointer, "items"), problems);
+    }
+}
+/**
+ * Load a schema document, refusing loudly on any keyword outside the closed
+ * set. `name` appears in the reason so a caller with several documents knows
+ * which one failed.
+ */
+export function loadSchema(document, name) {
+    const problems = [];
+    checkSchemaNode(document, ROOT_POINTER, problems);
+    if (problems.length > 0) {
+        return {
+            ok: false,
+            reason: `${name}: ${problems.sort().join("; ")}`,
+        };
+    }
+    return { ok: true, schema: document };
+}
+function resolveRef(root, reference) {
+    // `#` is the whole document, which is how a recursive schema is normally
+    // written. It was unhandled until a control in test/gates.test.ts exercised
+    // a legitimate recursive schema and got "does not resolve"; the cycle fix
+    // that motivated the control would otherwise have shipped beside a gap
+    // that made every recursive schema unusable.
+    if (reference === "#") {
+        return root;
+    }
+    if (!reference.startsWith("#/")) {
+        return undefined;
+    }
+    let node = root;
+    for (const raw of reference.slice(2).split("/")) {
+        const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!isPlainObject(node)) {
+            return undefined;
+        }
+        node = ownProperty(node, segment);
+    }
+    return isPlainObject(node) ? node : undefined;
+}
+/* ------------------------------------------------------------------ */
+/* THE ENGINE, RETIRED (DR-0013 clause 6, M3-P1 step 8).                */
+/* ------------------------------------------------------------------ */
+/**
+ * WHAT WAS RETIRED AND WHAT WAS KEPT, stated because the distinction is the
+ * whole of DR-0013 clause 6.
+ *
+ * RETIRED: keyword SEMANTICS. `type`, `required`, `properties`,
+ * `additionalProperties`, `enum`, `items`, `minimum`, `minItems`, `pattern`
+ * and `const` are no longer evaluated here. `validate` hands the schema and
+ * the instance to `src/validate.ts`, which is Ajv 8.20.0 under the policies
+ * DR-0013 clause 4 fixed. Two engines with potentially different semantics
+ * are not maintained.
+ *
+ * KEPT, and each for a reason DR-0013 names:
+ *
+ *   1. THE MODULE BOUNDARY. `loadSchema`, `validate`, `validateToLines`,
+ *      `formatDiagnostic`, `formatDiagnostics` and `DIAGNOSTIC_MESSAGES` are
+ *      unchanged in name, signature and meaning, so every M2 caller and every
+ *      M2 test is untouched.
+ *   2. THE CLOSED KEYWORD SET, as a POLICY LINTER. `loadSchema` still refuses
+ *      a gate schema containing a keyword outside M2-D-04's set. DR-0013
+ *      clause 7 says this explicitly: prohibiting otherwise-valid but
+ *      unapproved keywords "is a small schema-aware POLICY LINTER, never a
+ *      reimplementation of keyword semantics". Under Ajv `oneOf` compiles
+ *      fine, so without this linter M2's gate schemas would silently acquire
+ *      a vocabulary nobody approved.
+ *   3. THE REFERENCE POLICY. Measured 2026-08-08 with the pinned Ajv:
+ *      compiling `{type:"object",properties:{x:{$ref:"#/$defs/a"}},
+ *      $defs:{a:{$ref:"#/$defs/a"}}}` raises
+ *      `RangeError: Maximum call stack size exceeded`. That is CR-807's
+ *      failure wearing a different engine's clothes, so the cycle and
+ *      unresolved-reference analysis stays HERE, in front of the engine,
+ *      where it produces a diagnostic instead of a stack overflow. It
+ *      evaluates no other keyword.
+ */
+/**
+ * Reference-only joint walk. Follows `$ref` and descends `properties` and
+ * `items`, and does nothing else. `refChain` holds the references followed
+ * since the last INSTANCE node was consumed, so a legitimate recursive schema
+ * (which always consumes an instance node between two follows) is not
+ * mistaken for a cycle. This is the same rule the retired engine used and the
+ * same diagnostics, because both are contract.
+ */
+function collectReferenceDiagnostics(root, schema, instance, pointer, into, refChain, seenNodes) {
+    const reference = schema["$ref"];
+    if (typeof reference === "string") {
+        if (refChain.includes(reference)) {
+            into.push({ pointer, message: DIAGNOSTIC_MESSAGES.cyclicRef(reference) });
+            return;
+        }
+        const target = resolveRef(root, reference);
+        if (target === undefined) {
+            into.push({
+                pointer,
+                message: DIAGNOSTIC_MESSAGES.unresolvedRef(reference),
+            });
+            return;
+        }
+        collectReferenceDiagnostics(root, target, instance, pointer, into, [...refChain, reference], seenNodes);
+        return;
+    }
+    if (Array.isArray(instance)) {
+        const items = schema["items"];
+        if (isPlainObject(items)) {
+            for (let index = 0; index < instance.length; index += 1) {
+                collectReferenceDiagnostics(root, items, instance[index], `${pointer}/${index}`, into, [], seenNodes);
+            }
+        }
+        return;
+    }
+    if (isPlainObject(instance)) {
+        const properties = isPlainObject(schema["properties"])
+            ? schema["properties"]
+            : {};
+        for (const name of Object.keys(instance).sort()) {
+            const subschema = ownProperty(properties, name);
+            if (isPlainObject(subschema)) {
+                collectReferenceDiagnostics(root, subschema, ownProperty(instance, name), childPointer(pointer, name), into, [], seenNodes);
+            }
+        }
+    }
+}
+/**
+ * Validate an instance against a loaded schema. The returned list is sorted
+ * by (pointer, message), which is the deterministic order the contract
+ * promises and which is now produced by `sortDiagnostics` in the shared
+ * engine so the two modules cannot drift on it.
+ */
+export function validate(schema, instance) {
+    const referenceProblems = [];
+    collectReferenceDiagnostics(schema, schema, instance, ROOT_POINTER, referenceProblems, [], new Set());
+    if (referenceProblems.length > 0) {
+        // A schema whose references do not resolve, or loop, cannot be compiled
+        // at all: the engine would throw. Report and stop, exactly as the retired
+        // engine returned at the offending reference node.
+        return sortDiagnostics(referenceProblems);
+    }
+    return validateInstance(schema, instance);
+}
+/** Validate and format in one step: the shape most callers want. */
+export function validateToLines(schema, instance) {
+    return formatDiagnostics(validate(schema, instance));
+}

package/dist/src/hooks.d.ts

@@ -0,0 +1,84 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * Turn-end hook (kernel plan v1, M1-P4 step 3; R-082b, PR-209).
+ *
+ * The hook is a generated script in the TASK directory (never inside the
+ * worktree, FM-059) that the executor invokes when the payload command
+ * exits. It writes tasks/<id>/turn-end as JSON:
+ *
+ *   {"endedAt": "<ISO-8601>", "exitCode": <number>}
+ *
+ * That file is the M1-P5 watcher's wake signal. It is a notification,
+ * not the task's state: meta.json status plus this exit code together
+ * are the single current-state authority (plan constraint C-1), and a
+ * MISSING turn-end file never means success (tuition T-002: an agent
+ * that dies quietly leaves no turn-end and a dirty worktree).
+ *
+ * The hook takes the payload's exit code as its single argument, so any
+ * adapter (the M1 subprocess adapter, and the window or cloud-session
+ * adapters of the M4 era) can invoke it without knowing anything else
+ * about the task. It is written with the .mjs extension so it parses as
+ * ESM regardless of the nearest package.json, since it runs inside the
+ * fleet home rather than inside this package.
+ */
+/** The generated hook script for a task. */
+export declare function turnEndHookPath(fleet: Fleet, taskId: string): string;
+/**
+ * Generate the hook script. The turn-end path is baked in as a literal,
+ * so the hook needs no fleet resolution.
+ *
+ * THE CHILD-OBSERVED POINTER RECORD (CR-B-001, the half that closes the hole
+ * rather than the half that stops mis-asserting it).
+ *
+ * `observeNames`, when given, is baked in as a literal array and the hook
+ * writes an `env` object holding what each of those names ACTUALLY IS in the
+ * environment the hook was launched with, or `null` where the name is unset.
+ * The kernel compares those against the harness-owned paths it handed over.
+ *
+ * WHY THIS IS STRONGER THAN AN ADAPTER'S REPORT AND WHY IT IS NOT PROOF.
+ * This script is written BY THE KERNEL and, for every adapter that honours
+ * the documented contract, runs in the SAME environment as the payload (the
+ * built-in adapter spreads the same `request.env` into both spawnSync calls,
+ * and M2R-004 edit 4 is the record of why a second unscrubbed launch is
+ * itself the leak). Against an adapter that does not invoke this script at
+ * all it proves nothing, and the record no longer says otherwise.
+ *
+ * THE COST SENTENCE THAT STOOD HERE IS WITHDRAWN, BECAUSE IT WAS REFUTED BY
+ * MEASUREMENT (CR-F-CRED-001, MEDIUM).
+ *
+ * It read: an adapter that quietly reverted `HOME` for the payload "has to
+ * revert it for the payload and NOT for the hook, which means launching two
+ * children with two different environments and is a substantially different
+ * act from passing a mutated copy once". Two children is one way to do it and
+ * it is not the cheap way. The cheap way is ONE child with the mutated
+ * environment plus a single `writeFileSync` of the turn-end path, which is
+ * STRICTLY LESS work than the honest path, because the honest path also
+ * spawns the hook. The turn-end path is handed to the adapter beside
+ * `hookPath`, and this generated script names it as a literal, so an adapter
+ * that never runs it can still produce a byte-identical record.
+ *
+ * WHY A NONCE DOES NOT CLOSE THIS, stated because it is the obvious repair and
+ * it was considered and refused rather than overlooked. Baking a per-task
+ * secret into this script and requiring it in the record moves the forgery
+ * from "know the path" to "read the file", and the adapter is HANDED the path
+ * of this file: it runs at the same uid, on the same filesystem, in a
+ * directory it must be able to read to invoke the hook at all. A guard whose
+ * condition the adversary can satisfy by reading one file is green and
+ * worthless, which is this repository's own recorded shape (T-008's
+ * postscript, the red-witness rule one level up). No artifact this script can
+ * write is unforgeable by a party that can read this script.
+ *
+ * So the repair is on the RECORD rather than on the check: the value is
+ * `turn-end-record`, it names the artifact the values were read from, and
+ * `CredentialHandoverRecord` (src/task.ts) says the artifact is
+ * adapter-reachable. A dishonest adapter is still not caught here, and that
+ * residue is declared at delivery/work-history/m4-p8.md item 3; what changed
+ * is that `meta.json` no longer positively asserts a child-side observation
+ * that no child made.
+ *
+ * The hook still reads no environment it was not told to read, and a hook
+ * generated with no `observeNames` behaves exactly as it did before.
+ */
+export declare function renderTurnEndHook(turnEndFile: string, observeNames?: readonly string[]): string;
+/** Write the hook for a task and return its path. */
+export declare function writeTurnEndHook(fleet: Fleet, taskId: string, observeNames?: readonly string[]): string;