@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/lock.js

@@ -1,7 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { linkSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
 import { hostname } from "node:os";
 import { setTimeout as sleep } from "node:timers/promises";
+import { buildRegisterDocument, casFailureLine, casWrite, ensureEnvironmentId, fleetRootForLockPath, preflightShared, readSharedExclusion, } from "./exclusion.js";
+import { readRegularPathIfPresent } from "./fleet.js";
 /**
  * Lease-based session lock (kernel plan v1, M1-P3 step 1; DR-0007; plan
  * constraint C-2). One orchestrator per fleet: the lock file at
@@ -55,9 +57,19 @@ import { setTimeout as sleep } from "node:timers/promises";
  *
  * Exclusion domain (PR-201, DR-0007 stated honestly): the lease excludes
  * within one filesystem and one clock, the fleet home the lock file lives
- * in. Cross-environment exclusion for a fleet shared through a git remote
- * is M4 residue and is not claimed here. Mutations of the lock file made
- * outside this module (manual edits) are not covered by the contract.
+ * in. Mutations of the lock file made outside this module (manual edits)
+ * are not covered by the contract.
+ *
+ * CROSS-ENVIRONMENT EXCLUSION IS A SECOND LAYER ABOVE THIS ONE (M4-P21),
+ * and it is OFF unless the fleet home declares it. When the fleet's own
+ * `package.json` carries `tiphys.sharedExclusion`, every mutation below
+ * first asks `src/exclusion.ts` for a verdict from the shared register on
+ * the fleet's git remote, and only a won verdict reaches the local lease.
+ * With the field ABSENT, `readSharedExclusion` returns before spawning
+ * anything and every path in this module behaves exactly as it did, which
+ * is the property M4-P21 criterion 1 asserts. The refusal never touches the
+ * lock file, which is what makes the fail-closed behaviour on an
+ * unreachable register observable (criterion 7): no local lease appears.
  *
  * Renewal discipline (PR-203): the default lease lasts 900 seconds and
  * the holder renews at or before half-life (renewByMs). Holdership on
@@ -92,37 +104,68 @@ function parseLease(raw) {
 export function renderLease(lease) {
     return `${JSON.stringify(lease, null, 2)}\n`;
 }
-/** Read the current lock file state: absent, or present with raw bytes. */
+/**
+ * Read the current lock file state: absent, or present with raw bytes.
+ *
+ * THE ENTRY TYPE IS ESTABLISHED BEFORE THE OPEN (T-008's shape in shipped
+ * code). A bare `readFileSync` here blocked FOREVER with zero output on a
+ * named pipe at the lease path, and took `lock status`, `lock acquire`,
+ * `lock renew` and `lock release` with it, while `tiphys doctor` returned in
+ * the same second against the same FIFO with "is a named pipe, not a regular
+ * file, so it was not opened". Two readers of one path, one of which
+ * established the type; this is now the same reader.
+ *
+ * A refusal THROWS rather than returning a fourth `ObservedLease` variant.
+ * The function already threw on every non-ENOENT error, so the contract its
+ * callers were written against is unchanged, and bin/tiphys.ts turns the
+ * throw into one diagnostic line and a nonzero exit.
+ */
 export function observeLease(lockPath) {
-    let raw;
-    try {
-        raw = readFileSync(lockPath, "utf8");
+    const read = readRegularPathIfPresent(lockPath);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
     }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { kind: "absent" };
-        }
-        throw error;
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
     }
-    return { kind: "present", raw, lease: parseLease(raw) };
+    return { kind: "present", raw: read.body, lease: parseLease(read.body) };
+}
+/**
+ * THE ONE EXPIRY COMPARISON IN THE KERNEL (M4-P17 criterion 2).
+ *
+ * `isExpired` below needs a whole `Lease`, and doctor's lock check does not
+ * have one: it reads the lease file defensively and holds only `holderId` and
+ * `expiresAt`, because a lease file that fails `parseLease` must still produce
+ * a diagnosis rather than nothing. Before this phase that forced doctor to
+ * carry its own `Date.parse(...) <= Date.now()`, which is a SECOND comparison
+ * of the same property, free to drift from this one. The boundary is where
+ * that drift shows: `<=` makes expiry INCLUSIVE, so a lease whose `expiresAt`
+ * is exactly the current millisecond is expired, and a second copy written
+ * with `<` disagrees for exactly one millisecond and agrees everywhere else.
+ * A disagreement that narrow is not something a reviewer finds by reading.
+ *
+ * So the comparison lives here once and both callers reach it.
+ */
+export function expiryHasPassed(expiresAt, nowMs) {
+    return Date.parse(expiresAt) <= nowMs;
 }
 export function isExpired(lease, nowMs) {
-    return Date.parse(lease.expiresAt) <= nowMs;
+    return expiryHasPassed(lease.expiresAt, nowMs);
 }
 /** The renew-by deadline (half-life of the current term), for holders. */
 export function renewByMs(lease) {
     return Date.parse(lease.expiresAt) - (lease.durationSeconds * 1000) / 2;
 }
+/** The same guarded read as observeLease, for the inside of the claim. */
 function readCurrent(lockPath) {
-    try {
-        return { present: true, raw: readFileSync(lockPath, "utf8") };
+    const read = readRegularPathIfPresent(lockPath);
+    if (read.kind === "absent") {
+        return { present: false, raw: "" };
     }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { present: false, raw: "" };
-        }
-        throw error;
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
     }
+    return { present: true, raw: read.body };
 }
 /**
  * Re-read the lock file and re-compare it against the state a mutation
@@ -265,6 +308,16 @@ export async function applyLeaseMutation(lockPath, observed, next, token) {
             // lock path use the same discipline, which is the asymmetry the
             // module previously left unjustified.
             const stagePath = stagePathFor(lockPath);
+            /* THE STAGE IS OPENED FOR WRITING and is NOT guarded here, which is a
+               measurement rather than an oversight. open(2) for writing on a FIFO
+               blocks exactly as reading one does, so this looked like a member of
+               the class this round closed. It is not: the claim-held sweep above
+               (CR-202) unlinks `<lock>.stage` UNCONDITIONALLY before either branch
+               writes it, so a planted FIFO is gone by the time this line runs.
+               Measured at this head with a real mkfifo at
+               `state/orchestrator.lock.stage`: `tiphys lock acquire` exits 0 in
+               under a second and the lease is taken. A guard here would therefore
+               be code no witness can redden. */
             writeFileSync(stagePath, next);
             try {
                 linkSync(stagePath, lockPath);
@@ -299,6 +352,16 @@ export async function applyLeaseMutation(lockPath, observed, next, token) {
             // confirmation read both still happen inside the claim, and the
             // rename remains atomic within one directory.
             const stagePath = stagePathFor(lockPath);
+            /* THE STAGE IS OPENED FOR WRITING and is NOT guarded here, which is a
+               measurement rather than an oversight. open(2) for writing on a FIFO
+               blocks exactly as reading one does, so this looked like a member of
+               the class this round closed. It is not: the claim-held sweep above
+               (CR-202) unlinks `<lock>.stage` UNCONDITIONALLY before either branch
+               writes it, so a planted FIFO is gone by the time this line runs.
+               Measured at this head with a real mkfifo at
+               `state/orchestrator.lock.stage`: `tiphys lock acquire` exits 0 in
+               under a second and the lease is taken. A guard here would therefore
+               be code no witness can redden. */
             writeFileSync(stagePath, next);
             try {
                 renameSync(stagePath, lockPath);
@@ -343,6 +406,100 @@ export async function applyLeaseMutation(lockPath, observed, next, token) {
         }
     }
 }
+/**
+ * Resolve the fleet home's declaration. The ONLY entry into the shared
+ * layer, and the only place a fleet root is derived: a lock path is
+ * `<root>/state/orchestrator.lock` (src/fleet.ts:37), so the root is two
+ * directories up unless a caller names it. A declaration that is present
+ * and unusable is reported rather than treated as absent, because reading a
+ * typo as "off" is the failure that would make this layer green everywhere.
+ */
+function sharedGate(lockPath, fleetRoot) {
+    const root = fleetRoot ?? fleetRootForLockPath(lockPath);
+    const declaration = readSharedExclusion(root);
+    if (declaration.kind === "absent") {
+        return { kind: "off" };
+    }
+    if (declaration.kind === "invalid") {
+        return { kind: "invalid", reason: declaration.reason };
+    }
+    const identity = ensureEnvironmentId(root);
+    return {
+        kind: "on",
+        ctx: { config: declaration.config, envId: identity.envId, fleetRoot: root },
+    };
+}
+function invalidDeclarationOutcome(reason) {
+    return {
+        ok: false,
+        reason: `shared exclusion is declared and unusable, refusing rather than running ` +
+            `local-only: ${reason}`,
+    };
+}
+/** Ask the shared register for a verdict, without touching anything. */
+function sharedPreflight(ctx, intent, takeover, nowMs) {
+    return preflightShared({
+        fleetRoot: ctx.fleetRoot,
+        config: ctx.config,
+        envId: ctx.envId,
+        intent,
+        takeover,
+        nowMs,
+    });
+}
+function sharedNote(ctx, preflight) {
+    return { line: preflight.line, envId: ctx.envId };
+}
+/**
+ * Publish the won verdict to the register. Called only AFTER the local
+ * mutation succeeded, so the two layers agree or the local one is rolled
+ * back by the caller: a register entry with no local lease behind it would
+ * exclude every environment including the one that wrote it.
+ */
+function sharedCommit(ctx, preflight, state, nowMs, durationSeconds) {
+    const document = buildRegisterDocument({
+        state,
+        envId: ctx.envId,
+        counter: preflight.nextCounter,
+        nowMs,
+        durationSeconds,
+        ref: ctx.config.ref,
+        ...(preflight.current !== undefined && state === "held" && !preflight.takingOver
+            ? { acquiredAt: preflight.current.acquiredAt }
+            : {}),
+    });
+    const outcome = casWrite(ctx.fleetRoot, ctx.config, preflight.expectedSha, document);
+    if (outcome.kind === "won") {
+        return { ok: true, sha: outcome.sha };
+    }
+    return { ok: false, reason: casFailureLine(ctx.config.ref, outcome) };
+}
+/**
+ * UNDO A LOCAL LEASE MUTATION WHOSE REGISTER PUBLISH LOST.
+ *
+ * `current` is what the lock file holds NOW (the state this mutation left),
+ * and `restore` is the observation the mutation was decided against, whose
+ * raw bytes are written back verbatim so the restored file is BYTE-IDENTICAL
+ * to the one the command claimed not to have changed.
+ *
+ * The token handed to the primitive is the RESTORED lease's own token, not a
+ * fresh one: the primitive confirms an application by re-reading the token in
+ * the file it just wrote, and a fresh token would fail that confirmation
+ * against bytes that carry the old one.
+ *
+ * Returns the sentence appended to the failure line. A rollback that ITSELF
+ * loses is stated rather than swallowed, because "the local lease was
+ * restored" is a claim a later reader will act on.
+ */
+async function restoreLocal(lockPath, current, restore) {
+    if (restore.lease === undefined) {
+        return "; the local lease could NOT be restored: the observed lease does not parse";
+    }
+    const undone = await applyLeaseMutation(lockPath, current, restore.raw, restore.lease.token);
+    return undone.won
+        ? "; the local lease was restored"
+        : `; the local lease could NOT be restored (${undone.reason}), so ${lockPath} and the register now disagree`;
+}
 function buildLease(nowMs, durationSeconds) {
     return {
         holderId: randomUUID(),
@@ -361,6 +518,27 @@ function buildLease(nowMs, durationSeconds) {
 export async function acquireLease(lockPath, options = {}) {
     const nowMs = options.nowMs ?? Date.now();
     const durationSeconds = options.durationSeconds ?? DEFAULT_LEASE_DURATION_SECONDS;
+    /* THE SHARED LAYER RUNS FIRST AND MUTATES NOTHING (M4-P21 criteria 1 and
+       7). Off unless declared, so the read below is the whole cost for every
+       fleet that has not opted in. A refusal returns here, before the local
+       lease file can be created, which is the fail-closed property: an
+       unreachable register leaves no local lock behind to be mistaken for
+       exclusion that is not there. */
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        preflight = sharedPreflight(gate.ctx, "acquire", options.takeover === true, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
     const observed = options.observed ?? observeLease(lockPath);
     if (observed.kind === "present") {
         if (observed.lease === undefined) {
@@ -397,6 +575,31 @@ export async function acquireLease(lockPath, options = {}) {
         }
         return { ok: false, reason: `lock held (${result.reason})` };
     }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        const published = sharedCommit(gate.ctx, preflight, "held", nowMs, durationSeconds);
+        if (!published.ok) {
+            /* The register refused after the local lease was written, so the local
+               lease is rolled back through the SAME mutation primitive. Leaving it
+               would make this environment believe it holds a fleet another
+               environment holds, which is the exact state this layer exists to
+               prevent. */
+            await applyLeaseMutation(lockPath, { kind: "present", raw: renderLease(lease), lease }, null, randomUUID());
+            const line = `shared exclusion refused acquire: ${published.reason}; the local lease was rolled back`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
     return { ok: true, lease };
 }
 /**
@@ -408,6 +611,21 @@ export async function acquireLease(lockPath, options = {}) {
  */
 export async function renewLease(lockPath, holderId, options = {}) {
     const nowMs = options.nowMs ?? Date.now();
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        preflight = sharedPreflight(gate.ctx, "renew", false, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
     const observed = options.observed ?? observeLease(lockPath);
     if (observed.kind === "absent") {
         return { ok: false, reason: "renew refused: no lease present" };
@@ -446,6 +664,36 @@ export async function renewLease(lockPath, holderId, options = {}) {
         }
         return { ok: false, reason: `renew ${result.reason}` };
     }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        /* A RENEW ADVANCES THE FENCING COUNTER, and that is the whole of what
+           makes another environment's staleness judgement safe under clock skew
+           (criterion 5). The observer sees an increment, never a timestamp. */
+        const published = sharedCommit(gate.ctx, preflight, "held", nowMs, durationSeconds);
+        if (!published.ok) {
+            /* THE LOCAL LAYER IS ROLLED BACK, exactly as acquire's failure arm
+               does it and through the SAME primitive. src/lock.ts:537 states the
+               invariant: the two layers agree, or the local one is undone by the
+               caller. Until this round `acquireLease` was the only one of the
+               three publishing callers that honoured it, so a failed renew
+               reported failure while the lease file had ALREADY been extended
+               under a new token, and a failed release reported failure while the
+               lease file had already been DELETED. */
+            const line = `shared exclusion refused renew: ${published.reason}${await restoreLocal(lockPath, { kind: "present", raw: renderLease(lease), lease }, observed)}`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
     return { ok: true, lease };
 }
 /**
@@ -456,6 +704,27 @@ export async function renewLease(lockPath, holderId, options = {}) {
  * staged before a takeover completes loses to it.
  */
 export async function releaseLease(lockPath, holderId, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        /* CRITERION 8. A release by a non-holder is refused HERE, before any
+           write, so the register sha is byte-identical before and after. The
+           refusal is the register's own comparison, not a local one: a clone
+           whose local lease says it holds the fleet still loses to a register
+           that names another environment. */
+        preflight = sharedPreflight(gate.ctx, "release", false, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
     const observed = options.observed ?? observeLease(lockPath);
     if (observed.kind === "absent") {
         return { ok: false, reason: "release refused: no lease present" };
@@ -479,6 +748,29 @@ export async function releaseLease(lockPath, holderId, options = {}) {
         }
         return { ok: false, reason: `release ${result.reason}` };
     }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        const published = sharedCommit(gate.ctx, preflight, "free", nowMs, observed.lease.durationSeconds);
+        if (!published.ok) {
+            /* See renewLease above: the local lease was REMOVED before this
+               publish was attempted, and the holdership guard keys on that file's
+               PRESENCE, so leaving it removed reopens the dual-writer window
+               M1-P4 criterion 12 closed. */
+            const line = `shared exclusion could not publish the release: ${published.reason}${await restoreLocal(lockPath, { kind: "absent" }, observed)}`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease: null,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
     return { ok: true, lease: null };
 }
 /** Report the lock state; reading only, never mutating (always safe). */

package/dist/src/model-resolution.d.ts

@@ -0,0 +1,159 @@
+import type { Fleet } from "./fleet.ts";
+/**
+ * THE MODEL-RESOLUTION RECORD, KERNEL SIDE (kernel plan M4, M4-P7;
+ * delivery/plan/kernel-plan-m4.md:1018, discharging M4-D-06's four parts at
+ * delivery/plan/m4-intake.md:732).
+ *
+ * WHAT THIS MODULE IS AND, MORE IMPORTANTLY, WHAT IT IS NOT. It READS a
+ * record a harness adapter wrote. It holds NO vocabulary: no tier-to-model
+ * table, no model-to-family table, and no vendor name of any kind. The whole
+ * vocabulary lives in the plugin (plugin/src/vocabulary.ts) and this module
+ * dereferences a vocabulary's IDENTITY and never its CONTENT. That single
+ * property is what makes a second harness plugin possible at all: a mapping
+ * here would close off every harness that is not the one it names
+ * (delivery/plan/m4-intake.md:377), and `test/schemas.test.ts` already asserts
+ * the absence over the whole shipped surface rather than trusting this
+ * paragraph.
+ *
+ * THE ORDER OF THE CHECKS IS PART OF THE CONTRACT, and it is the release
+ * record's order (src/gates/release.ts): the SUBJECT ECHO is compared field by
+ * field BEFORE anything reads the resolved identity. A record about another
+ * task is not a record with a wrong answer, it is a record about something
+ * else, and reading its answer first is how a misattributed family token
+ * reaches a decorrelation check as though it belonged there.
+ *
+ * WHY `observed` IS NOT `attested`, stated here because the vocabulary is the
+ * thing most likely to be widened later by someone who did not read M4-P1.
+ * The probe measured that the observation channel is harness-written, that it
+ * can be EMPTY at hook time under load, and that a process at the agent's own
+ * uid can rewrite it in place so the result is byte-shaped exactly like the
+ * truth (delivery/verification/m4-prototype-probes.md:410). So `observed`
+ * ranks above `self-reported`, which costs nothing to forge, and below any
+ * notion of attestation, which would need a signer this environment has not
+ * been shown to have.
+ */
+/** The record's file name inside the task directory. */
+export declare const MODEL_RESOLUTION_RECORD_NAME = "model-resolution.json";
+/** The contract versions this kernel accepts. */
+export declare const MODEL_RESOLUTION_CONTRACT_VERSIONS: readonly string[];
+/**
+ * Where the record lives: `tasks/<id>/model-resolution.json`, NEVER inside the
+ * worktree (M4-P7 criterion 5, src/task.ts:31 and FM-059). The task directory
+ * sits outside the worktree precisely so the pool's dirty check needs no
+ * exemption list for the kernel's own injected files, and a record written
+ * into the worktree would be indistinguishable from the agent's own work.
+ */
+export declare function modelResolutionPath(fleet: Fleet, taskId: string): string;
+/** The launch request fields the record's subject echo is compared against. */
+export interface ModelResolutionSubject {
+    taskId: string;
+    role: string;
+    requestedTier: string;
+}
+export interface VocabularyIdentity {
+    id: string;
+    version: number;
+}
+/** What one read of the record produced. */
+export type ModelResolutionRead = {
+    kind: "read";
+    record: Record<string, unknown>;
+} | {
+    kind: "error";
+    reason: string;
+};
+/** What one acceptance decision produced. */
+export type ModelResolutionAcceptance = {
+    kind: "accepted";
+    family: string | undefined;
+    provenance: string;
+} | {
+    kind: "refused";
+    reason: string;
+};
+/** What one cross-record family comparison produced. */
+export type FamilyComparison = {
+    kind: "compared";
+    differ: boolean;
+    families: [string, string];
+} | {
+    kind: "refused";
+    reason: string;
+};
+/**
+ * Read the record for a task.
+ *
+ * AN ABSENT RECORD IS AN ERROR AND IS NEVER GREEN AND NEVER NOT-APPLICABLE
+ * (M4-P7 criterion 5). This is not a new rule and deliberately not a second
+ * implementation of one: src/gates/release.ts:609 already produces the
+ * sentence for the same hazard on the release seam, and the wording is kept
+ * in the same shape so that a reader who has met one meets the other.
+ * `test/model-resolution.test.ts` drives the real release gate to capture that
+ * sentence and derives its assertion from the capture, rather than pinning a
+ * hand-written copy of it.
+ *
+ * THE READ GOES THROUGH `readRegularFileIfPresent`, which is M2-C-6 and the
+ * mechanism-index row `reading-a-path-whose-type-is-not-established`: a named
+ * pipe at this path is a REPORTED refusal, never a blocked open.
+ */
+export declare function readModelResolutionRecord(path: string, writerExitCode: number): ModelResolutionRead;
+/**
+ * The vocabulary IDENTITY of a record, and nothing else about the vocabulary.
+ *
+ * TWO FIELDS ARE READ AND THEY ARE NAMED HERE RATHER THAN SPREAD, which is
+ * the whole of criterion 4's mechanical half. A spread, an `Object.keys`, a
+ * `JSON.stringify` or a `structuredClone` of the vocabulary object would
+ * ENUMERATE it, and enumeration is dereferencing the content whatever the
+ * intent. `test/model-resolution.test.ts` hands this function a Proxy that
+ * records every property read and asserts the recorded set against these two
+ * names, so a later edit that reaches for a third reddens.
+ */
+export declare function vocabularyIdentity(record: Record<string, unknown>): VocabularyIdentity | undefined;
+/**
+ * Accept or refuse one record against the launch request the kernel holds.
+ *
+ * FOUR REFUSALS, IN THIS ORDER, and the order is the point.
+ *
+ * 1. THE CONTRACT VERSION, because a record written to a contract this kernel
+ *    does not know is not a record this kernel can read fields out of.
+ * 2. THE SUBJECT ECHO, FIELD BY FIELD, BEFORE THE OUTCOME IS READ. This is
+ *    src/gates/schemas/release-record.schema.json:26's misattribution guard.
+ * 3. THE VOCABULARY IDENTITY, because a family token with no vocabulary is a
+ *    token nobody can say the meaning of.
+ * 4. THE PROVENANCE, which is M4-P7 criterion 6 member TWO. Member one (a
+ *    record claiming `observed` with no observation at all) is the schema's
+ *    and is a missing field. THIS is the present-but-inconsistent half, and a
+ *    schema-only guard passes it green: an observation about another task, or
+ *    naming a model other than the one the record claims, is a self-report
+ *    with a decoration on it.
+ */
+export declare function acceptModelResolution(record: Record<string, unknown>, subject: ModelResolutionSubject): ModelResolutionAcceptance;
+/**
+ * Compare two accepted records' family tokens (M4-P7 criterion 3).
+ *
+ * TWO VOCABULARIES ARE NOT COMPARABLE AND THE REFUSAL NAMES BOTH IDS. A family
+ * token means whatever the vocabulary that minted it says it means, so
+ * comparing a token from one against a token from another is comparing two
+ * strings and calling the result a fact about models. That comparison is what
+ * `check-dual-review`'s decorrelation assertion rests on, and DR-0038 exists
+ * for exactly the environment where the two reviews come from different
+ * places, so a silent cross-vocabulary compare would make the assertion
+ * meaningless precisely where it is load-bearing.
+ *
+ * ONLY `id` IS READ HERE. The version is part of the identity a reader may
+ * print and is deliberately NOT part of the comparison: a vocabulary that
+ * added a family in v2 did not change what its v1 tokens mean, and refusing
+ * on version would turn a routine vocabulary revision into an outage.
+ */
+export declare function compareResolvedFamilies(left: Record<string, unknown>, right: Record<string, unknown>): FamilyComparison;
+/**
+ * The value closeout copies into a verdict's `produced-by` (M4-P7 criterion 8).
+ *
+ * VERBATIM, AND THE FUNCTION EXISTS SO THAT "VERBATIM" IS TESTABLE. DR-0031
+ * requires a pull request to carry all its own evidence, so the family token
+ * has to reach the verdict document rather than being left in a task
+ * directory that no reviewer of the pull request can see. A copy that
+ * normalised, lowercased or prefixed the token would satisfy every reading of
+ * that sentence and would break the one comparison the token exists for.
+ */
+export declare function producedByFromRecord(record: Record<string, unknown>): string | undefined;