@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/task.js

@@ -1,108 +1,12 @@
-import { existsSync, lstatSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+/* IMPORTED UNDER THE OLD NAMES rather than re-exported straight through,
+   because this module CALLS them as well as publishing them. A bare
+   `export ... from` publishes without binding, so the internal call sites below
+   would not resolve and the only signal would be a build error. */
+import { classifyPathEntry as classifyEntry, readRegularPathIfPresent as readRegularFileIfPresent, refuseOpenPathForWrite as refuseOpenForWrite, } from "./fleet.js";
 import { leaseStatus } from "./lock.js";
-function describeType(stats) {
-    if (stats.isDirectory()) {
-        return "a directory";
-    }
-    if (stats.isFIFO()) {
-        return "a named pipe";
-    }
-    if (stats.isSocket()) {
-        return "a socket";
-    }
-    if (stats.isCharacterDevice()) {
-        return "a character device";
-    }
-    if (stats.isBlockDevice()) {
-        return "a block device";
-    }
-    return "an entry of an unrecognized type";
-}
-/**
- * THE ONE ANSWER TO "may this path be opened". Every reader and every
- * writer of a path this kernel does not itself guarantee to be a regular
- * file goes through this, so there is one implementation of the question
- * and not one per call site.
- */
-export function classifyEntry(path) {
-    try {
-        lstatSync(path);
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { kind: "absent" };
-        }
-        return {
-            kind: "unexaminable",
-            reason: `${path} could not be examined: ${String(error)}`,
-        };
-    }
-    let stats;
-    try {
-        stats = statSync(path);
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { kind: "dangling" };
-        }
-        return {
-            kind: "unexaminable",
-            reason: `${path} could not be examined: ${String(error)}`,
-        };
-    }
-    if (stats.isFile()) {
-        return { kind: "regular" };
-    }
-    return {
-        kind: "irregular",
-        reason: `${path} is ${describeType(stats)}, not a regular file, so it was not opened`,
-    };
-}
-/**
- * Refuse an open-for-WRITE of a path that is not a regular file. The
- * hazard is symmetric: open(2) for writing on a FIFO with no reader blocks
- * exactly as reading one with no writer does, so a staged write and an
- * append are as dangerous as a read. Returns the reason, or undefined when
- * the path may be opened (absent included: creating it is the point).
- */
-export function refuseOpenForWrite(path) {
-    const entry = classifyEntry(path);
-    if (entry.kind === "irregular" || entry.kind === "unexaminable") {
-        return entry.reason;
-    }
-    return undefined;
-}
-/**
- * THE ONE READ of a file that might not be there and might not be a file.
- * src/task.ts, src/liveness.ts, src/watcher.ts and src/commands/doctor.ts
- * all read fleet state through this, so "probe before open" is a property
- * of the read and cannot be forgotten by a new caller.
- */
-export function readRegularFileIfPresent(path) {
-    const entry = classifyEntry(path);
-    if (entry.kind === "absent" || entry.kind === "dangling") {
-        return { kind: "absent" };
-    }
-    if (entry.kind === "irregular" || entry.kind === "unexaminable") {
-        return { kind: "refused", reason: entry.reason };
-    }
-    let body;
-    try {
-        body = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            // Removed between the probe and the read.
-            return { kind: "absent" };
-        }
-        return {
-            kind: "refused",
-            reason: `${path} could not be read: ${String(error)}`,
-        };
-    }
-    return { kind: "read", body };
-}
+export { classifyEntry, readRegularFileIfPresent, refuseOpenForWrite };
 export const TASK_SHAPES = ["ship", "scout"];
 export function taskDir(fleet, taskId) {
     return join(fleet.tasksDir, taskId);
@@ -129,10 +33,33 @@ export function renderTaskMeta(meta) {
 export function writeTaskMeta(fleet, meta) {
     writeFileSync(metaPath(fleet, meta.id), renderTaskMeta(meta));
 }
+/** Which required field first failed, or undefined when all of them hold. */
+function firstBadMetaField(candidate) {
+    if (typeof candidate.id !== "string")
+        return "id (a string)";
+    if (typeof candidate.project !== "string")
+        return "project (a string)";
+    if (candidate.shape !== "ship" && candidate.shape !== "scout") {
+        return 'shape (either "ship" or "scout")';
+    }
+    if (typeof candidate.branch !== "string")
+        return "branch (a string)";
+    if (typeof candidate.worktree !== "string")
+        return "worktree (a string)";
+    if (typeof candidate.baseSha !== "string")
+        return "baseSha (a string)";
+    if (typeof candidate.baseOffline !== "boolean")
+        return "baseOffline (a boolean)";
+    if (candidate.status !== "open" && candidate.status !== "closed") {
+        return 'status (either "open" or "closed")';
+    }
+    if (typeof candidate.createdAt !== "string")
+        return "createdAt (a string)";
+    return undefined;
+}
 /**
- * Read meta.json, or undefined when it is absent, is not a regular file,
- * or does not parse. All three mean the same thing to every caller: this
- * is not a readable record, and it is not evidence that the task finished.
+ * THE ONE READ of a task record, and the one that says WHICH of the four
+ * outcomes happened.
  *
  * The type probe is INSIDE this function and not in front of one of its
  * callers (CR-520, CR-521). There is exactly one implementation of "read a
@@ -140,32 +67,71 @@ export function writeTaskMeta(fleet, meta) {
  * cannot reopen the hole: src/teardown.ts reaches this directly, without
  * going through the liveness classifier, and a named pipe here used to
  * hang it forever.
+ *
+ * WHY THIS IS A SEPARATE FUNCTION FROM `readTaskMeta` RATHER THAN ITS NEW
+ * SIGNATURE, declared rather than left to be inferred. Widening the return
+ * type of `readTaskMeta` is the shape this repair wants, and it is a
+ * compile-time break in four modules that this fix round's file list does not
+ * own (src/pool.ts, src/liveness.ts, src/teardown.ts, src/commands/next.ts).
+ * The distinction is therefore made AVAILABLE upstream of all of them here,
+ * `readTaskMeta` is documented as the deliberate NARROWING of it, and the
+ * sites that still collapse are named in the fix round's work history rather
+ * than quietly left.
  */
-export function readTaskMeta(fleet, taskId) {
-    const read = readRegularFileIfPresent(metaPath(fleet, taskId));
-    if (read.kind !== "read") {
-        return undefined;
+export function classifyTaskMeta(fleet, taskId) {
+    const path = metaPath(fleet, taskId);
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (read.kind === "refused") {
+        return { kind: "unreadable", reason: read.reason };
     }
     let parsed;
     try {
         parsed = JSON.parse(read.body);
     }
-    catch {
-        return undefined;
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            kind: "unparsable",
+            reason: `${path} is present (${read.body.length} byte(s)) and does not parse as ` +
+                `JSON (${detail}), which is what a task record killed mid-write looks ` +
+                `like; it is not evidence that there is no task here`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            kind: "malformed",
+            reason: `${path} parses as JSON but not as an object, so it is not a task record`,
+        };
     }
     const candidate = parsed;
-    if (typeof candidate.id !== "string" ||
-        typeof candidate.project !== "string" ||
-        (candidate.shape !== "ship" && candidate.shape !== "scout") ||
-        typeof candidate.branch !== "string" ||
-        typeof candidate.worktree !== "string" ||
-        typeof candidate.baseSha !== "string" ||
-        typeof candidate.baseOffline !== "boolean" ||
-        (candidate.status !== "open" && candidate.status !== "closed") ||
-        typeof candidate.createdAt !== "string") {
-        return undefined;
+    const bad = firstBadMetaField(candidate);
+    if (bad !== undefined) {
+        return {
+            kind: "malformed",
+            reason: `${path} parses as JSON but is not a task record: it needs ${bad}; it is ` +
+                `not evidence that there is no task here`,
+        };
     }
-    return candidate;
+    return { kind: "read", meta: candidate };
+}
+/**
+ * Read meta.json, or undefined when it is absent, is not a regular file,
+ * does not parse, or parses and is not a task record.
+ *
+ * THIS IS A DELIBERATE NARROWING OF `classifyTaskMeta` AND THE COLLAPSE IS THE
+ * WHOLE OF CR-F02. `undefined` answers "is there a readable record" and it
+ * cannot answer "is there a task here", because it is returned both when the
+ * kernel looked and found nothing and when it found something it could not
+ * read. A caller that reports an absence, skips an entry, or decides nothing
+ * is in flight must call `classifyTaskMeta` instead; a caller that REFUSES on
+ * every one of the four (teardown does) loses nothing by using this.
+ */
+export function readTaskMeta(fleet, taskId) {
+    const read = classifyTaskMeta(fleet, taskId);
+    return read.kind === "read" ? read.meta : undefined;
 }
 /** Set meta.json status (teardown's last step; C-1's state authority). */
 export function setTaskStatus(fleet, meta, status) {
@@ -303,3 +269,39 @@ export function runStep(what, step) {
         return { ok: false, reason: `${what} failed: ${detail}` };
     }
 }
+/**
+ * runStep's shape for a step that returns a PROMISE (M4-P2 step 2).
+ *
+ * This is a PROMOTION, not a new function. It lived module-private in
+ * src/watcher.ts, where its own comment said "src/task.ts covers the sync
+ * one"; spawn's launch call site needs the same shape now that
+ * `ExecutorAdapter.launch` returns a promise, and T-005's one-mechanism
+ * rule makes copying it a third time the wrong answer. The promotion was
+ * measured before it was made: the two functions were run side by side over
+ * six `what`/thrown-error pairs covering an ordinary Error, an Error with an
+ * empty message, a thrown string, a thrown object with a custom toString, an
+ * Error subclass and a multi-line pair, and their reason strings were
+ * compared as buffers. All six were byte-identical, so no watcher message
+ * changes on any of those six. The capture is in the M4-P2 work history
+ * under `delivery/work-history/m4-p2.md`.
+ *
+ * WHY A SEPARATE FUNCTION RATHER THAN WIDENING runStep. `runStep` returns
+ * `{ok: true, value}` the instant its callback returns, and a callback that
+ * returns a promise returns one IMMEDIATELY. So `runStep` over an async
+ * step is not merely imprecise: its `ok: true` is a claim that the step
+ * SUCCEEDED when nothing has run yet, and a later rejection escapes the
+ * result type entirely as an unhandled rejection. That is the exact defect
+ * this phase's criterion 4 witness reddens against.
+ *
+ * It never swallows, on the same terms as the sync one: the caller gets a
+ * reason naming the step and still decides what to do about it.
+ */
+export async function runStepAsync(what, step) {
+    try {
+        return { ok: true, value: await step() };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, reason: `${what} failed: ${detail}` };
+    }
+}

package/dist/src/teardown.d.ts

@@ -28,5 +28,12 @@ export declare function landedness(contextDir: string, branchRef: string, defaul
 export interface TeardownOptions {
     taskId: string;
     salvage: boolean;
+    /**
+     * Proceed on a pool record RECONSTRUCTED from tasks/<id>/meta.json and
+     * git, when worktrees/<id>.pool.json did not survive a reclaim
+     * (M4-P19, M4-D-12). See the FROM-RECONSTRUCTED header below for what
+     * this flag does and, more importantly, what it does NOT do.
+     */
+    fromReconstructed: boolean;
 }
 export declare function teardownTask(fleet: Fleet, options: TeardownOptions): Promise<TeardownResult>;

package/dist/src/teardown.js

@@ -1,7 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { MACHINE_IDENTITY_EMAIL, MACHINE_IDENTITY_NAME } from "./commands/init.js";
-import { poolDestroy, readPoolRecord, worktreePath } from "./pool.js";
+import { guardSharedRegister } from "./exclusion.js";
+import { poolDestroy, readPoolRecord, reconstructPoolRecord, worktreePath, } from "./pool.js";
 import { checkHoldership, metaPath, readTaskMeta, reportPath, runStep, setTaskStatus, singleLine, } from "./task.js";
 /**
  * Local git runner. It is deliberately not the pool's: src/pool.ts is
@@ -80,7 +81,7 @@ export function landedness(contextDir, branchRef, defaultRef) {
  * Read-only with respect to the task: the fetch updates only the
  * project's remote-tracking ref.
  */
-function resolveContext(fleet, taskId) {
+function resolveContext(fleet, taskId, fromReconstructed) {
     const meta = readTaskMeta(fleet, taskId);
     if (meta === undefined) {
         return {
@@ -88,13 +89,45 @@ function resolveContext(fleet, taskId) {
             reason: `no readable task meta for task id ${taskId}; teardown needs tasks/${taskId}/meta.json`,
         };
     }
-    const record = readPoolRecord(fleet, taskId);
+    let record = readPoolRecord(fleet, taskId);
+    let reconstructed = false;
     if (record === undefined) {
-        return {
-            ok: false,
-            reason: `no readable pool record for task id ${taskId}; teardown needs it for the ` +
-                `project remote and default branch, and refuses rather than guessing them`,
-        };
+        if (!fromReconstructed) {
+            return {
+                ok: false,
+                reason: `no readable pool record for task id ${taskId}; teardown needs it for the ` +
+                    `project remote and default branch, and refuses rather than guessing them; ` +
+                    `pass --from-reconstructed to rebuild them from tasks/${taskId}/meta.json ` +
+                    `and git, which keeps every other refusal in force`,
+            };
+        }
+        // NETWORK ALLOWED here and nowhere else in this kernel's
+        // reconstruction (M4-P19 fix round). Teardown is a command the
+        // operator invoked in order to destroy something, it is about to
+        // fetch from this remote on the next line regardless, and it is
+        // allowed to take as long as that fetch takes. `pool list` and
+        // doctor are not, and they pass `{ network: false }`.
+        const rebuilt = reconstructPoolRecord(fleet, taskId, { network: true });
+        if (rebuilt.kind === "absent") {
+            return {
+                ok: false,
+                reason: `cannot reconstruct the pool record for task id ${taskId}: ${rebuilt.reason}`,
+            };
+        }
+        if (rebuilt.kind === "incomplete") {
+            // The missing FIELD is named, not merely the failure, because the
+            // remedy differs per field: `remote` is a git configuration repair
+            // in the clone, `branch` is usually an origin/HEAD that was never
+            // set or a remote that cannot be reached to advertise it.
+            return {
+                ok: false,
+                reason: `cannot reconstruct the pool record for task id ${taskId}: unresolved ` +
+                    `field(s) ${rebuilt.unresolved.join(", ")} (${rebuilt.detail}); teardown ` +
+                    `refuses rather than guessing them`,
+            };
+        }
+        record = rebuilt.record;
+        reconstructed = true;
     }
     const worktree = worktreePath(fleet, taskId);
     const defaultRef = `refs/remotes/${record.remote}/${record.branch}`;
@@ -111,7 +144,7 @@ function resolveContext(fleet, taskId) {
                 `be judged against fresh remote state: ${singleLine(fetched.stderr)}`,
         };
     }
-    return { ok: true, value: { meta, record, worktree, defaultRef } };
+    return { ok: true, value: { meta, record, reconstructed, worktree, defaultRef } };
 }
 /** Uncommitted changes or untracked files in the task worktree. */
 function worktreeDirty(worktree) {
@@ -171,6 +204,11 @@ async function finish(fleet, context, options) {
         taskId: context.meta.id,
         discard: options.discard,
         deleteBranchForce: options.deleteBranchForce,
+        // M4-P19: in memory only, and only when the record was rebuilt. This
+        // makes the destroy's own base-sha gate ABLE to judge instead of
+        // abstaining with its "pool record missing" refusal; it does not
+        // create a file and it does not relax a gate.
+        ...(context.reconstructed ? { reconstructed: context.record } : {}),
     });
     if (!destroyed.ok) {
         // The destroy's own reason distinguishes a stage-2 refusal (a true
@@ -213,13 +251,69 @@ export async function teardownTask(fleet, options) {
     if (!holdership.ok) {
         return { ok: false, reason: holdership.reason };
     }
-    const resolved = resolveContext(fleet, options.taskId);
+    /* THE CROSS-ENVIRONMENT HALF (M4-P22 criterion 3), rule 0's second limb.
+       `checkHoldership` above returns OK when this environment holds the local
+       lease, and the local lease is evidence about this filesystem alone
+       (src/lock.ts:63). With the shared register naming another environment,
+       the old guard is green and teardown would remove a worktree the other
+       orchestrator is working in. One reason line, nonzero exit, and NOTHING
+       REMOVED: it runs before `resolveContext`, so no pool record is read, no
+       worktree is probed and no branch is deleted. A teardown that refuses
+       after deleting something has failed in the way that matters. */
+    const sharedGuard = guardSharedRegister(fleet.root, "teardown");
+    if (sharedGuard.kind === "refused") {
+        return { ok: false, reason: sharedGuard.reason };
+    }
+    const resolved = resolveContext(fleet, options.taskId, options.fromReconstructed);
     if (!resolved.ok) {
         return resolved;
     }
     const context = resolved.value;
     const { meta, record, worktree } = context;
     if (meta.shape === "scout") {
+        // M4-P19 FIX ROUND, finding F-5. THE RECONSTRUCTED PATH IS STRICTER
+        // THAN THE WITH-RECORD PATH FOR A SCOUT, DELIBERATELY.
+        //
+        // The scout arm below discards a dirty scratch tree by design
+        // (PR-010: a scout is judged by its report and never pushes), and it
+        // reaches `finish` without ever probing cleanliness. That was
+        // reachable only by an operator who had the pool record in front of
+        // them. This phase made it reachable from a RECLAIM, where the
+        // record is the one thing that did not survive, and measured at head
+        // abde402: `teardown --task s1 --from-reconstructed` against a scout
+        // worktree holding ` M readme.md` and `?? important.md` exited 0 and
+        // removed the worktree, where the same fixture on the phase base
+        // exited 1 and left it standing. Plan criterion 4 states the refusal
+        // with no shape qualifier, so the plan is what is followed here.
+        //
+        // WHY NOT INSTEAD MAKE THE WITH-RECORD SCOUT PATH REFUSE TOO. That
+        // is a change to a decided scout policy (PR-010) which this phase
+        // does not own and which the plan does not ask for. The asymmetry is
+        // therefore REAL and is stated rather than smoothed over: the
+        // difference in force is the difference in what the operator knows.
+        // With the record present they are tearing down a scout they are
+        // tracking; arriving here from a reclaim they are recovering a fleet
+        // whose bookkeeping is already known to be incomplete, and the
+        // leavings in that tree may be the only copy.
+        //
+        // --salvage is NOT the escape, because salvage pushes (PR-010: a
+        // scout never pushes), so the remedy named is the one that works.
+        if (context.reconstructed) {
+            const scoutDirty = worktreeDirty(worktree);
+            if (!scoutDirty.ok) {
+                return { ok: false, reason: scoutDirty.reason };
+            }
+            if (scoutDirty.dirty) {
+                return {
+                    ok: false,
+                    reason: `scout worktree ${worktree} has uncommitted changes or untracked ` +
+                        `files and its pool record did not survive, so teardown is running ` +
+                        `on a reconstruction and refuses to discard them: copy anything ` +
+                        `worth keeping out of ${worktree}, then re-run once ` +
+                        `"git -C ${worktree} status --porcelain" is empty`,
+                };
+            }
+        }
         // (a) A scout is judged by its report, never by its scratch tree.
         if (!existsSync(reportPath(fleet, options.taskId))) {
             return {
@@ -287,10 +381,24 @@ export async function teardownTask(fleet, options) {
         };
     }
     if (landed.kind === "unlanded") {
+        // M4-P19 criterion 5: the refusal NAMES THE TIP. That sha is the
+        // operator's recovery handle, exactly as the deleted-branch sha is on
+        // the success path (V-1), and it is the one fact that makes this
+        // refusal actionable: it says which commit is at risk, not merely
+        // that something is. It is named on every unlanded refusal rather
+        // than only the reconstructed one, so there is one message and not
+        // two that can drift apart.
+        const tip = runGit(record.project, [
+            "rev-parse",
+            "--verify",
+            "--quiet",
+            `${branchRef}^{commit}`,
+        ]);
+        const tipSha = tip.status === 0 ? tip.stdout.trim() : "unresolvable";
         return {
             ok: false,
-            reason: `branch ${record.branchName} is not landed on ${record.remote}/${record.branch}; ` +
-                `land it before tearing the task down` +
+            reason: `branch ${record.branchName} (tip ${tipSha}) is not landed on ` +
+                `${record.remote}/${record.branch}; land it before tearing the task down` +
                 (options.salvage ? " (--salvage rescues leavings, it never lands work)" : ""),
         };
     }

package/dist/src/validate.d.ts

@@ -23,11 +23,22 @@
  * 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).
+ * whose Ajv error reaches `renderAjvError` and matches no `case` of that
+ * function's switch falls to its `default:` arm, which 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).
+ *
+ * THIS PARAGRAPH NAMED THE WRONG MECHANISM UNTIL THE DR-0047 SWEEP (CR-VS-004).
+ * It said the refusal came from a `MESSAGE_BY_KEYWORD` set. That set existed,
+ * nothing ever read it (three references: its own declaration and two comments
+ * saying it was the contract), and its contents disagreed with
+ * `AUTHORING_VOCABULARY` in BOTH directions: `$ref`, `items`, `properties` and
+ * `then` were in the vocabulary and not in the set, `minimum`, `maximum` and
+ * `maxItems` were in the set and not in the vocabulary. A dead constant that a
+ * file's own documentation calls the contract is how the next reader edits the
+ * thing that does nothing, so it is deleted and this sentence now names the
+ * switch, which is what actually refuses.
  *
  * YAML IS INPUT DECODING AND IS A SEPARATE STAGE (DR-0013 YAML clause 3).
  * `decodeDocument` decodes; `validateInstance` validates an already-decoded
@@ -50,12 +61,34 @@ export interface Diagnostic {
     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`.
+ * THE DECLARED AUTHORING VOCABULARY (DR-0013 clause 7). THIS LIST IS THE SOURCE
+ * OF TRUTH. Ajv supplies Draft 2020-12 entire; this 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), asserted by `test/schemas.test.ts`, which DERIVES its cases
+ * from this array rather than from a hand-written list.
+ *
+ * `schemas/README.md` RENDERS THIS LIST FOR A HUMAN READER AND IS NOT ITSELF
+ * THE CONTRACT, and the distinction was paid for (CR-VS-004, FIND-02 of the
+ * DR-0047 sweep). The sentence here used to say the vocabulary IS "documented
+ * in `schemas/README.md`", which reads as a guarantee that the two agree.
+ * Measured at the swept head they did not: this array holds sixteen keywords
+ * and that document's table declared fifteen, `uniqueItems` being the missing
+ * row, since the day M3-P1 wrote both. Nothing asserted the relation, so no gate
+ * could see it.
+ *
+ * THE DRIFT IS NOW CLOSED, AND BY THE TEST RATHER THAN BY THE ROW (DR-0047
+ * sweep round 2). The row was added to `schemas/README.md`, which closes the one
+ * instance; what closes the MECHANISM is that test/schemas.test.ts:340 parses
+ * that document's keyword column and compares it to this array, so the two
+ * halves can no longer disagree silently. The document still does not DECIDE
+ * anything: this array is the contract and that one renders it, which is why
+ * the comparison is written as an assertion about the document rather than as a
+ * generator.
+ *
+ * AND THE SECOND HALF OF THAT SENTENCE IS GONE. It said every entry "therefore
+ * also has an entry in `MESSAGE_BY_KEYWORD`", which was false in both
+ * directions and about a constant nothing read; see the module header.
  */
 export declare const AUTHORING_VOCABULARY: readonly string[];
 /** Annotations that carry no constraint and are permitted everywhere. */

package/dist/src/validate.js

@@ -23,11 +23,22 @@
  * 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).
+ * whose Ajv error reaches `renderAjvError` and matches no `case` of that
+ * function's switch falls to its `default:` arm, which 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).
+ *
+ * THIS PARAGRAPH NAMED THE WRONG MECHANISM UNTIL THE DR-0047 SWEEP (CR-VS-004).
+ * It said the refusal came from a `MESSAGE_BY_KEYWORD` set. That set existed,
+ * nothing ever read it (three references: its own declaration and two comments
+ * saying it was the contract), and its contents disagreed with
+ * `AUTHORING_VOCABULARY` in BOTH directions: `$ref`, `items`, `properties` and
+ * `then` were in the vocabulary and not in the set, `minimum`, `maximum` and
+ * `maxItems` were in the set and not in the vocabulary. A dead constant that a
+ * file's own documentation calls the contract is how the next reader edits the
+ * thing that does nothing, so it is deleted and this sentence now names the
+ * switch, which is what actually refuses.
  *
  * YAML IS INPUT DECODING AND IS A SEPARATE STAGE (DR-0013 YAML clause 3).
  * `decodeDocument` decodes; `validateInstance` validates an already-decoded
@@ -76,12 +87,34 @@ export const TIPHYS_DIALECT = "https://json-schema.org/draft/2020-12/schema";
 /** The document root, in RFC 6901 URI-fragment form. */
 export const ROOT_POINTER = "#";
 /**
- * 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`.
+ * THE DECLARED AUTHORING VOCABULARY (DR-0013 clause 7). THIS LIST IS THE SOURCE
+ * OF TRUTH. Ajv supplies Draft 2020-12 entire; this 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), asserted by `test/schemas.test.ts`, which DERIVES its cases
+ * from this array rather than from a hand-written list.
+ *
+ * `schemas/README.md` RENDERS THIS LIST FOR A HUMAN READER AND IS NOT ITSELF
+ * THE CONTRACT, and the distinction was paid for (CR-VS-004, FIND-02 of the
+ * DR-0047 sweep). The sentence here used to say the vocabulary IS "documented
+ * in `schemas/README.md`", which reads as a guarantee that the two agree.
+ * Measured at the swept head they did not: this array holds sixteen keywords
+ * and that document's table declared fifteen, `uniqueItems` being the missing
+ * row, since the day M3-P1 wrote both. Nothing asserted the relation, so no gate
+ * could see it.
+ *
+ * THE DRIFT IS NOW CLOSED, AND BY THE TEST RATHER THAN BY THE ROW (DR-0047
+ * sweep round 2). The row was added to `schemas/README.md`, which closes the one
+ * instance; what closes the MECHANISM is that test/schemas.test.ts:340 parses
+ * that document's keyword column and compares it to this array, so the two
+ * halves can no longer disagree silently. The document still does not DECIDE
+ * anything: this array is the contract and that one renders it, which is why
+ * the comparison is written as an assertion about the document rather than as a
+ * generator.
+ *
+ * AND THE SECOND HALF OF THAT SENTENCE IS GONE. It said every entry "therefore
+ * also has an entry in `MESSAGE_BY_KEYWORD`", which was false in both
+ * directions and about a constant nothing read; see the module header.
  */
 export const AUTHORING_VOCABULARY = [
     "$ref",
@@ -252,29 +285,6 @@ function valueAt(instance, instancePath) {
     }
     return node;
 }
-/**
- * Ajv keywords this engine translates. A keyword absent from this map is a
- * defect and says so: see the module header. The map's KEY SET is also the
- * mechanical half of "every keyword in the declared vocabulary has a
- * diagnostic", asserted in `test/schemas.test.ts`.
- */
-const MESSAGE_BY_KEYWORD = new Set([
-    "type",
-    "required",
-    "additionalProperties",
-    "enum",
-    "const",
-    "minimum",
-    "maximum",
-    "minItems",
-    "maxItems",
-    "minLength",
-    "pattern",
-    "uniqueItems",
-    "contains",
-    "oneOf",
-    "if",
-]);
 /**
  * Translate ONE Ajv error into the Tiphys contract. `undefined` means the
  * error carries no independent information for a reader (Ajv reports a