@intentius/chant 0.124.13 → 0.124.15

package/dist/workspace/records.js

@@ -0,0 +1,1345 @@
+/**
+ * Records read through a record kind (#2524 D4), first-test slice (#2546).
+ *
+ * A record kind is data. It says where its records live, which JSON Schema
+ * they follow and which of their states are closed. This module reads every
+ * record a kind locates, parses its structured core (the front matter, as the
+ * JSON subset of YAML, or the whole file as one I-JSON object, ws-053),
+ * validates it against the kind's schema and derives supersession from the
+ * records' own `supersedes` links, and remediation from their `remediates`
+ * links (#2774): a later record fixing a closed one's consequence without
+ * replacing it, which leaves the closed record's status unchanged. It never
+ * writes a record; `records-write.ts` does, through the rules here (#2670).
+ *
+ * A record that fails any of that is still returned, with reason codes, and the
+ * read succeeds. Only a failure to read the kind, its schema or the revision is
+ * an error. A closed record of a kind that declares `seal` is checked against
+ * its whole-file seal ({@link recordSeal}, #2546); author and verdict seals
+ * are checked by `records-cli.ts` against the policy at base. Nothing here
+ * needs a `chant.workspace.json`.
+ *
+ * Everything under `workspace/` loads only when a `chant workspace` command
+ * runs. The level-0 goldens (#2526) fail if a level-0 command loads it.
+ */
+import { createHash } from "node:crypto";
+import { contentDigest, sha256Hex } from "../content-digest.js";
+import { canonicalJson } from "../effect-receipt.js";
+import { readFileSync, statSync } from "node:fs";
+import { dirname, posix, relative, resolve, sep } from "node:path";
+import yaml from "js-yaml";
+import { z } from "zod";
+import { importLexiconModule, registerLexiconDeclarations } from "../lexicon-module.js";
+import { checkPins, pinEntries } from "./record-assets.js";
+import { joinSessions } from "./record-sessions.js";
+import { sourceBlock, sourceBlockProblems, transcriptDrift } from "./source-block.js";
+// ── Reason codes ─────────────────────────────────────────────────────────────
+/**
+ * Why one record is not valid. The list is closed: a reader may switch on it,
+ * and a new code is a contract change (#2536).
+ */
+export const RECORD_REASON_CODES = [
+    /** No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name. */
+    "record-unparseable",
+    /** The record's front matter, or its JSON object, does not match the kind's schema. */
+    "record-schema-invalid",
+    /** Another record earlier in path order has the same id. */
+    "record-id-duplicate",
+    /** A `supersedes` link names an id no record has. */
+    "record-supersedes-unknown",
+    /** A second closed record supersedes a record another one already superseded. */
+    "record-supersedes-conflict",
+    /** A `remediates` link names an id no record has (#2774). */
+    "record-remediates-unknown",
+    /** A `remediates` link names a record that isn't closed: a record still open is amended instead (#2774). */
+    "record-remediates-not-closed",
+    /** A closed record's seal is not the whole-file seal of its text now: it changed after it closed (#2546, ws-063). */
+    "record-seal-mismatch",
+    /** A closed session's seal is not the digest of its text: it changed after it closed (#2673). */
+    "session-seal-mismatch",
+    /** A session's verdict names a record the kind's subject records do not have (#2673). */
+    "session-verdict-unknown-record",
+];
+/**
+ * Why a record carries a warning. Closed, like the reason codes. A warning
+ * never makes a record invalid, and `--current` still lists the record.
+ */
+export const RECORD_WARNING_CODES = [
+    /** A pinned file's bytes no longer hash to the pinned sha256 (#2549). */
+    "asset-drift",
+    /** A pinned file does not exist in the tree read (#2549). */
+    "asset-missing",
+    /**
+     * A pinned file is unchanged since a record this one supersedes pinned it at
+     * the same hash: the decision changed and the artifact did not follow (#2549).
+     */
+    "asset-stale",
+    /** A supersedes link from a record whose state is weaker than the one it names, so it has no effect yet (#2524 D4). */
+    "record-supersedes-pending",
+    /**
+     * The kind's pins field is an empty list: the record cites no evidence and
+     * pins no file. Information for a reviewer, such as a decision made in a
+     * product's own design flow with nothing to cite (#2654).
+     */
+    "record-no-evidence",
+    /**
+     * A verdict in the kind's reviews list names no `digest`, so it is not bound
+     * to the text it judged. It still counts toward the quorum, and an
+     * amendment does not stop it counting (#2672).
+     */
+    "review-undigested",
+    /**
+     * The kind's source block pins a transcript by hash, the file it names can
+     * be read here, and its bytes hash to something else: it is not the
+     * transcript the record means (#2708).
+     */
+    "source-transcript-drift",
+];
+/**
+ * Why a verdict does not count toward a record's quorum (#2671). Closed, like
+ * the reason codes. A verdict with none of these counts.
+ */
+export const REVIEW_REASON_CODES = [
+    /** The reviewer is the record's decider. */
+    "review-decider",
+    /** The reviewer holds the agent role in the trust policy at base. */
+    "review-agent",
+    /** A later verdict by the same principal, after normalising, replaces this one. */
+    "review-duplicate",
+    /** The verdict's digest is not the digest of the record's text now: the record changed after the verdict (#2672). */
+    "review-older-digest",
+    /**
+     * An attestation policy is active at base, and the verdict's seal does not
+     * verify for its reviewer: it has none, the reviewer has no key in the
+     * signers file, or the signature fails (#2687).
+     */
+    "review-unattested",
+];
+/**
+ * Why a seal is not attested: a verdict's (#2687), or a record's author seal
+ * (#2688). Closed, like the reason codes. Every verdict in the quorum, and
+ * every parsed record of a kind with a reviews list, carries one of these in
+ * its `attestation`, unless its seal verified.
+ */
+export const SEAL_REASON_CODES = [
+    /** The verdict or record carries no seal. */
+    "seal-missing",
+    /** The reviewer or author has no key in the signers file at base. */
+    "seal-signer-unlisted",
+    /** The seal is malformed, names another signer, or its signature does not verify over the verdict or record. */
+    "seal-signature-invalid",
+    /** Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed. */
+    "seal-unverifiable",
+];
+/**
+ * A warning about a record's own seal (#2688), raised by `records` with the
+ * policy at base, never by a write. Closed, like the reason codes.
+ */
+export const SEAL_WARNING_CODES = [
+    /**
+     * A signers file is active at base, the record names its author (the
+     * kind's `reviews.decider` field), and its seal does not verify for that
+     * author: it has none, the author has no key in the file, or the signature
+     * fails. The record is still read, and still valid.
+     */
+    "record-unattested",
+];
+/**
+ * The top-level field that holds a record's author seal (#2688), on a kind
+ * with a reviews list. Like the reviews block, the record's digest leaves it
+ * out, so sealing a record never moves its digest.
+ */
+export const RECORD_SEAL_FIELD = "seal";
+/**
+ * The top-level fields {@link recordTextDigest} leaves out for a kind: its
+ * reviews list and {@link RECORD_SEAL_FIELD} when it has a reviews list, and
+ * nothing when it has none (#2672, #2688). A kind that names a ratified
+ * state (`reviews.ratified`, #2873) leaves its state field out too, so
+ * moving a record to that state keeps the verdicts that ratified it
+ * counting.
+ */
+export function digestFields(kind) {
+    if (!kind.reviews)
+        return null;
+    const fields = [kind.reviews.field, RECORD_SEAL_FIELD];
+    if (kind.reviews.ratified !== undefined && kind.stateField !== undefined)
+        fields.push(kind.stateField);
+    // The whole-file seal is written when the record closes (#2546, ws-063), so
+    // the verdicts that ratified it keep counting on the sealed record.
+    if (kind.seal !== undefined)
+        fields.push(kind.seal.field);
+    return fields;
+}
+/** The field holding a closed record's whole-file seal: the kind's `seal.field`, or a session kind's `session.seal` (#2546, #2673). */
+export function sealFieldOf(kind) {
+    return kind.seal?.field ?? kind.session?.seal;
+}
+/**
+ * Why the read as a whole failed. Also closed. The command exits 1 with one of
+ * these and returns no records.
+ */
+export const READ_ERROR_CODES = [
+    /** The kind file is missing or could not be imported. */
+    "kind-unreadable",
+    /** The kind file exports no `recordKind`, or its shape is wrong. */
+    "kind-invalid",
+    /** The schema file the kind names is missing or is not JSON. */
+    "schema-unreadable",
+    /** The schema's `$id` differs from the id the kind names. */
+    "schema-id-mismatch",
+    /** The schema itself does not compile. */
+    "schema-invalid",
+    /** The records directory does not exist, in the tree or at the revision. */
+    "location-missing",
+    /** `--at` was given outside a git repository. */
+    "not-a-git-repository",
+    /** `--at` names no commit. */
+    "revision-unknown",
+];
+export class RecordReadError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RecordReadError";
+    }
+}
+// ── The kind ─────────────────────────────────────────────────────────────────
+const idPattern = /^[a-z][a-z0-9-]*$/;
+/** The formats a kind file may name. Closed. */
+export const RECORD_FORMATS = ["markdown-front-matter", "json"];
+/** The data a kind file exports as `recordKind`. */
+export const recordKindSchema = z
+    .object({
+    /** The kind's name, such as `decision`. */
+    name: z.string().regex(idPattern),
+    /** Where the records are, relative to the kind file's directory. */
+    location: z
+        .object({
+        dir: z.string().min(1),
+        /** A regular expression the file name must match. Only that directory is read; subdirectories are not. */
+        match: z.string().min(1),
+    })
+        .strict(),
+    /**
+     * How a file holds its record's structured core: `markdown-front-matter`,
+     * the YAML front matter of a Markdown file, or `json`, the whole file as
+     * one JSON object (ws-053).
+     */
+    format: z.enum(RECORD_FORMATS),
+    schema: z
+        .object({
+        /** The schema's `$id`. A schema file with a different `$id` is refused. */
+        id: z.string().min(1),
+        /** The schema file, relative to the kind file's directory. */
+        path: z.string().min(1),
+        /**
+         * Schema files the schema `$ref`s, each by its `$id` and path relative
+         * to the kind file's directory (ws-053). Each is checked for its `$id`
+         * and added to the validator before the schema compiles. Optional.
+         */
+        refs: z.array(z.object({ id: z.string().min(1), path: z.string().min(1) }).strict()).optional(),
+    })
+        .strict(),
+    /** The field holding the record's id. A kind has this or `idFrom`, never both. */
+    idField: z.string().min(1).optional(),
+    /**
+     * `sha256`: the record's id is the lowercase hex SHA-256 of the file's
+     * bytes, and the file name's stem (up to its first `.`) is the hash the
+     * name claims (ws-053). In place of `idField`.
+     */
+    idFrom: z.literal("sha256").optional(),
+    /**
+     * The field holding the record's state. `stateField`, `states` and
+     * `closedStates` are given together or not at all; a kind without them
+     * has no lifecycle, and its records have state null (ws-053).
+     */
+    stateField: z.string().min(1).optional(),
+    states: z.array(z.string().min(1)).min(1).optional(),
+    /** States whose records are final. A `supersedes` link takes effect only from a record in one of them. */
+    closedStates: z.array(z.string().min(1)).optional(),
+    /**
+     * The field of links to superseded records. With `key`, a list of objects
+     * whose `key` holds the target id; without it, one id or a list of ids
+     * (ws-053). Optional, and only on a kind with states.
+     */
+    supersedes: z.object({ field: z.string().min(1), key: z.string().min(1).optional() }).strict().optional(),
+    /**
+     * The field of links to records this one remediates: a later fix to a
+     * closed record's consequence, that leaves the closed record's status
+     * unchanged (#2774). Shaped like `supersedes`: with `key`, a list of
+     * objects whose `key` holds the target id; without it, one id or a list
+     * of ids. Optional, and only on a kind with states. A link is valid only
+     * when the target exists and is in one of `closedStates`; a target still
+     * open is amended instead, never remediated.
+     */
+    remediates: z.object({ field: z.string().min(1), key: z.string().min(1).optional() }).strict().optional(),
+    /**
+     * How strongly each state is approved (#2524 D4). With it, a supersedes
+     * link takes effect when the new record's rank is above 0 and at least the
+     * old record's, "under an equal or stricter approval rule". A state it
+     * leaves out ranks 0. Without it, a link takes effect only from a record
+     * in a closed state.
+     */
+    approval: z.record(z.string(), z.number().int().min(0)).optional(),
+    /**
+     * The front-matter list whose entries may pin a workspace file, as
+     * `{path, sha256}` (#2549). Optional: a kind without it pins nothing.
+     */
+    pins: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter list of what a record governs. Its `member:<name>` and
+     * `path:<path>` entries are the record's links in `chant workspace graph`
+     * (#2549). Optional.
+     */
+    constrains: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter list of workspace paths a record puts out of scope
+     * (#2773): a file or a directory, from the workspace root. `chant
+     * workspace check --changes` reports a change to one as
+     * `change-out-of-scope` when the record is in hand for the change, and
+     * the record does not cover it even where its constrains would.
+     * Optional.
+     */
+    outOfScope: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter list of review verdicts and the field naming the
+     * decider (#2671, #2672). With it, each record gets a digest of its text
+     * without that list, and `records --json` computes its quorum. Each
+     * entry holds `reviewer`, `verdict` (agree, dissent or abstain) and
+     * optionally `digest`, `note`, `proposes`, `addressed_by` and
+     * `withdrawn_on`. Optional.
+     *
+     * `ratified` names the state a record enters only once its quorum is met
+     * (#2873): `records new` and `records amend` refuse it below the quorum,
+     * with ratify-quorum-not-met. With it the digest leaves the state field
+     * out, so the move to that state keeps the verdicts counting. It must be
+     * one of `states`.
+     */
+    reviews: z.object({ field: z.string().min(1), decider: z.string().min(1), ratified: z.string().min(1).optional() }).strict().optional(),
+    /**
+     * The front-matter field a new record's proposer is named on, when the
+     * kind opts in (#2756). `records new --by` and the MCP `records-new`
+     * tool's `by` write it for a record that opens in the kind's first
+     * state — a proposal naming who proposed it — instead of
+     * `reviews.decider`'s field, which `by` fills only when a new record
+     * opens straight into another state. Requires `states`. Optional: a kind
+     * without it keeps `by` writing `reviews.decider` for every new record,
+     * as before #2756.
+     */
+    proposedBy: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The front-matter object that says where a record came from, opted in
+     * to the stored source block (#2708): `via`, `client`, `harness`,
+     * `model`, `session`, `turns` and `transcript`, beside the kind's own
+     * fields in the same object. With it, those fields are checked for their
+     * shapes, a write with `via: "harvest"` must open in the kind's first
+     * state, and `records` warns `source-transcript-drift`. Optional.
+     */
+    source: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * A review-session kind (#2673, #2650 C10): the front-matter list of the
+     * verdicts a session produced, the field that seals a closed session, and
+     * the records its verdicts name, as the kind file that locates them
+     * (relative to this kind file's directory), or as `kinds`, several kind
+     * files, when a session judges records of more than one kind, such as
+     * decisions and contracts (#3148, ws-082). The entries of each such
+     * kind's reviews list (its `reviews.field`, or `reviews`) name a session
+     * in `session`. Optional.
+     *
+     * `openedRev`, `closedRev` and `closedOn` (#2693) name the fields that
+     * hold the commit a session opened at, the commit it closed at, and when
+     * it closed. `records new` writes the first, `records close` the other
+     * two, and `records --since <session id>` reads the revisions. Each is
+     * optional: without it, nothing writes that field.
+     */
+    session: z
+        .object({
+        verdicts: z.string().min(1),
+        seal: z.string().min(1),
+        subjects: z.union([
+            z.object({ kind: z.string().min(1) }).strict(),
+            z
+                .object({ kinds: z.array(z.string().min(1)).min(1) })
+                .strict()
+                .refine((x) => new Set(x.kinds).size === x.kinds.length, { message: "session.subjects.kinds lists each kind file once", path: ["kinds"] }),
+        ]),
+        openedRev: z.string().min(1).optional(),
+        closedRev: z.string().min(1).optional(),
+        closedOn: z.string().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    /**
+     * A work kind (#2683): the front-matter lists of the work ids a record
+     * needs and the decision ids it implements, the decision kind file those
+     * ids name (relative to this kind file), the state a ready record is in,
+     * the state that satisfies a need, and the field holding the closing
+     * date. With it, `work.ts` gives each record `ready`, `blockedBy` and
+     * `implements`, and the read lists each decision with `implementedBy`.
+     * Optional.
+     *
+     * `acceptance` (#2772) names the front-matter list of a record's
+     * acceptance criteria, each an `id`, `text` and the `verification` it
+     * expects (`unit`, `integration`, `e2e`, `runtime` or `manual`), and the
+     * field naming the record's implementer, whose own `manual` verdict never
+     * counts. With it, each record gets `acceptance` (met and total), and a
+     * done record with a criterion that no passing evidence meets is warned
+     * `work-acceptance-unmet`, which `check` fails on (WSP117). Optional, and
+     * a record without the list is read as before.
+     *
+     * #3147 adds four, each optional:
+     *
+     * - `contract`: the front-matter field naming the contract record the
+     *   item builds, and the kind file of those records (relative to this
+     *   kind file). Each record gets `contract` with that record's state,
+     *   warned `work-contract-unknown` or `work-contract-undecided`.
+     * - `tier`: the field holding the item's builder tier, and the tiers the
+     *   workspace allows, declared once here. A tier outside them is warned
+     *   `work-tier-unknown`.
+     * - `attempts`: the field holding an item's own attempt limit, and the
+     *   default `max` for items without one. `work history` counts attempts
+     *   against it.
+     * - `answers`: the answer kind file (relative to this kind file) whose
+     *   records answer decision points about an item. Each record gets
+     *   `answers`, the answers whose `constrains` names its id, joined by id
+     *   rather than copied onto the item.
+     */
+    work: z
+        .object({
+        needs: z.string().min(1),
+        implements: z.string().min(1),
+        decisions: z.string().min(1),
+        open: z.string().min(1),
+        done: z.string().min(1),
+        closedOn: z.string().min(1),
+        acceptance: z.object({ field: z.string().min(1), implementer: z.string().min(1) }).strict().optional(),
+        contract: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict().optional(),
+        tier: z
+            .object({
+            field: z.string().min(1),
+            tiers: z.array(z.string().min(1)).min(1),
+            // What each tier may hold, for the slice-tier point's fits_<tier> inputs (#3150, work-size.ts).
+            limits: z.record(z.string().min(1), z.object({ criteria: z.number().int().min(0).optional(), files: z.number().int().min(0).optional(), words: z.number().int().min(0).optional() }).strict()).optional(),
+        })
+            .strict()
+            .refine((t) => new Set(t.tiers).size === t.tiers.length, { message: "work.tier.tiers lists each tier once", path: ["tiers"] })
+            .optional(),
+        attempts: z.object({ field: z.string().min(1), max: z.number().int().min(1) }).strict().optional(),
+        answers: z.string().min(1).optional(),
+    })
+        .strict()
+        .optional(),
+    /**
+     * An answer kind (ws-058, #2739): the decision points file its records
+     * answer, relative to this kind file. The records are written by `chant
+     * workspace points ask` and `points answer` in the shape of
+     * `point-answer.schema.json`, with an `id`, the states `escalated`,
+     * `proposed` and `answered`, and `answered` closed. With it, `records`
+     * warns about an answer whose point is gone or changed, `check` validates
+     * the points file (WSP116), and `points` lists the open questions.
+     * Optional.
+     */
+    answers: z.object({ points: z.string().min(1) }).strict().optional(),
+    /**
+     * The top-level field that holds a closed record's seal (#2546, ws-003,
+     * ws-063): {@link recordSeal}, the whole-file JCS/SHA-256 of the record
+     * without that field. `records amend` and `records new` write it when a
+     * record enters one of `closedStates`, and `records` reports a closed
+     * record whose seal does not match as `record-seal-mismatch`. Requires
+     * states. A session kind's `session.seal` names the same field for a
+     * session, and when both are given they must agree. Optional.
+     */
+    seal: z.object({ field: z.string().min(1) }).strict().optional(),
+    /**
+     * The kind's current records, with the files they pin, are part of the
+     * workspace's spec (#2524 D20): `chant workspace records --current
+     * --json` lists them under `spec`. Optional, and false when left out.
+     */
+    spec: z.boolean().optional(),
+})
+    .strict()
+    .refine((k) => k.states !== undefined || k.seal === undefined, {
+    message: "a kind without states cannot have seal: a record is sealed when it enters a closed state",
+    path: ["seal"],
+})
+    .refine((k) => k.seal === undefined || k.session === undefined || k.seal.field === k.session.seal, {
+    message: "seal.field and session.seal name the field that holds a closed session's seal, and must be the same",
+    path: ["seal"],
+})
+    .refine((k) => (k.idField === undefined) !== (k.idFrom === undefined), {
+    message: "a kind names its id with exactly one of idField and idFrom",
+    path: ["idField"],
+})
+    .refine((k) => new Set([k.stateField === undefined, k.states === undefined, k.closedStates === undefined]).size === 1, {
+    message: "stateField, states and closedStates are given together or not at all",
+    path: ["states"],
+})
+    .refine((k) => k.states !== undefined || k.supersedes === undefined, {
+    message: "a kind without states cannot have supersedes: a link takes effect only from a closed or ranked state",
+    path: ["supersedes"],
+})
+    .refine((k) => k.states !== undefined || k.remediates === undefined, {
+    message: "a kind without states cannot have remediates: a link only ever targets a record in a closed state",
+    path: ["remediates"],
+})
+    .refine((k) => k.states !== undefined || k.session === undefined, {
+    message: "a session kind must have states: a session is sealed when it reaches a closed state",
+    path: ["session"],
+})
+    .refine((k) => k.states !== undefined || k.approval === undefined, {
+    message: "a kind without states cannot have approval ranks",
+    path: ["approval"],
+})
+    .refine((k) => k.states !== undefined || k.proposedBy === undefined, {
+    message: "a kind without states cannot have proposedBy: there is no first state for a record to open in",
+    path: ["proposedBy"],
+})
+    .refine((k) => k.reviews?.ratified === undefined || (k.states ?? []).includes(k.reviews.ratified), {
+    message: "reviews.ratified must be one of states: it names the state a record enters once its quorum is met",
+    path: ["reviews", "ratified"],
+})
+    .refine((k) => (k.closedStates ?? []).every((s) => (k.states ?? []).includes(s)), {
+    message: "every closed state must be listed in states",
+    path: ["closedStates"],
+})
+    .refine((k) => Object.keys(k.approval ?? {}).every((s) => (k.states ?? []).includes(s)), {
+    message: "every state approval ranks must be listed in states",
+    path: ["approval"],
+})
+    .refine((k) => !k.work || (k.states !== undefined && k.states.includes(k.work.open) && k.states.includes(k.work.done)), {
+    message: "a work kind must have states, and its work open and done states must be listed in them",
+    path: ["work"],
+})
+    .refine((k) => !k.work?.acceptance || k.pins !== undefined, {
+    message: "a work kind with acceptance criteria must have pins: a criterion is met by the evidence in its pins field",
+    path: ["work", "acceptance"],
+})
+    .refine((k) => !k.answers ||
+    (k.format === "markdown-front-matter" &&
+        k.idField === "id" &&
+        k.stateField === "state" &&
+        ANSWER_STATES.every((s) => k.states?.includes(s)) &&
+        (k.closedStates ?? []).includes("answered")), {
+    message: 'an answer kind is markdown-front-matter with idField "id", stateField "state", the states escalated, proposed and answered, and answered closed',
+    path: ["answers"],
+});
+/** The states of an answer kind's records (ws-058): open for people, proposed by a model, answered by a table, people, or a confirmed proposal. */
+export const ANSWER_STATES = ["escalated", "proposed", "answered"];
+/** The kind files a session kind's verdicts name records of, relative to the session kind file: `subjects.kind`, or each of `subjects.kinds` (ws-082). */
+export function sessionSubjectKinds(session) {
+    return "kinds" in session.subjects ? session.subjects.kinds : [session.subjects.kind];
+}
+/**
+ * A session kind's subject records, each subject kind read from `source`
+ * (#2673, ws-082), for {@link readRecords}' `subjects`. Undefined for a kind
+ * that is not a session kind.
+ */
+export async function readSessionSubjects(loaded, root, source) {
+    if (!loaded.kind.session)
+        return undefined;
+    const out = [];
+    for (const file of sessionSubjectKinds(loaded.kind.session)) {
+        const subjectKind = await loadRecordKind(resolve(dirname(loaded.file), file), root);
+        out.push({ kind: file, records: (await readRecords(subjectKind, { root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" });
+    }
+    return out;
+}
+/**
+ * Import the kind file at `path` through the path loader lexicons use (#2520).
+ * The kind is registered under a name no lexicon package can have (npm names
+ * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
+ */
+export async function importKindModule(path) {
+    const name = `record-kind:${path}`;
+    registerLexiconDeclarations([{ name, module: path }], dirname(path));
+    try {
+        const mod = await importLexiconModule(name);
+        if (!mod)
+            throw new Error(`${path} was not registered`);
+        return mod;
+    }
+    finally {
+        registerLexiconDeclarations([name], dirname(path));
+    }
+}
+/** Load a kind file and the schema it names. `path` is resolved against `cwd`. */
+export async function loadRecordKind(path, cwd = process.cwd()) {
+    const file = resolve(cwd, path);
+    let mod;
+    try {
+        statSync(file);
+        mod = await importKindModule(file);
+    }
+    catch (err) {
+        throw new RecordReadError("kind-unreadable", `kind file ${path} could not be loaded: ${message(err)}`);
+    }
+    const parsed = recordKindSchema.safeParse(mod.recordKind);
+    if (!parsed.success) {
+        const detail = mod.recordKind === undefined
+            ? "it has no recordKind export"
+            : parsed.error.issues.map((i) => `${i.path.join(".") || "recordKind"}: ${i.message}`).join("; ");
+        throw new RecordReadError("kind-invalid", `kind file ${path} is not a record kind: ${detail}`);
+    }
+    const kind = parsed.data;
+    const base = dirname(file);
+    const schema = readSchemaFile(kind, base, path, kind.schema);
+    const refs = (kind.schema.refs ?? []).map((ref) => readSchemaFile(kind, base, path, ref));
+    return { kind, file, dir: resolve(base, kind.location.dir), schema, refs };
+}
+/** A schema file a kind names, refused when it can't be read or its `$id` is not the one the kind names. */
+function readSchemaFile(kind, base, kindPath, named) {
+    let schema;
+    try {
+        schema = JSON.parse(readFileSync(resolve(base, named.path), "utf-8"));
+    }
+    catch (err) {
+        throw new RecordReadError("schema-unreadable", `schema ${named.path} named by ${kindPath} could not be read: ${message(err)}`);
+    }
+    if (schema === null || typeof schema !== "object" || schema.$id !== named.id) {
+        throw new RecordReadError("schema-id-mismatch", `kind ${kind.name} names schema ${named.id}, but ${named.path} has $id ${JSON.stringify(schema?.$id)}`);
+    }
+    return schema;
+}
+/**
+ * The front matter of a Markdown file, limited to what YAML and JSON share
+ * (#2524 D4). Line endings are normalised first. Aliases, and any value JSON
+ * cannot hold, are refused, so the same text always reads as the same JSON.
+ */
+export function parseFrontMatter(text) {
+    const normalised = text.replace(/\r\n?/g, "\n");
+    const m = normalised.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+    if (!m)
+        return { ok: false, message: "no front matter: the file must start with a --- line and close it with another" };
+    let value;
+    try {
+        value = yaml.load(m[1], { schema: yaml.JSON_SCHEMA });
+    }
+    catch (err) {
+        return { ok: false, message: `front matter is not valid YAML: ${message(err).split("\n")[0]}` };
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, message: "front matter must be a mapping" };
+    }
+    const problem = nonJson(value, "", new Set());
+    if (problem)
+        return { ok: false, message: problem };
+    return { ok: true, value: value };
+}
+// ── JSON records ─────────────────────────────────────────────────────────────
+/**
+ * A JSON record: the whole file is one object, read as I-JSON (RFC 7493)
+ * requires on the two points JSON.parse lets through (ws-053). A top-level
+ * value other than an object is refused, and so is a member name that repeats
+ * within one object, at any depth, which JSON.parse accepts by keeping the
+ * last value. Names compare after their escapes are decoded, so `"a"` and
+ * `"\u0061"` are the same name. A number too large for a double is refused as
+ * front matter's is.
+ */
+export function parseJsonRecord(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, message: `not valid JSON: ${message(err).split("\n")[0]}` };
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, message: "a JSON record must be one object at the top level" };
+    }
+    const scan = scanJson(text);
+    if (scan.duplicate)
+        return { ok: false, message: `${scan.duplicate.at || "/"}: member name ${JSON.stringify(scan.duplicate.name)} repeats, which I-JSON refuses` };
+    const problem = nonJson(value, "", new Set());
+    if (problem)
+        return { ok: false, message: problem };
+    return { ok: true, value: value };
+}
+/** A record's structured core, parsed as the kind's format says. */
+export function parseRecord(format, text) {
+    return format === "json" ? parseJsonRecord(text) : parseFrontMatter(text);
+}
+/**
+ * One pass over text JSON.parse accepted: the top-level object's members, with
+ * where each starts and ends, and the first member name that repeats within
+ * one object at any depth.
+ */
+function scanJson(text) {
+    const members = [];
+    // One frame per open object or array: an object's names so far, or null for an array.
+    const stack = [];
+    let pendingTop;
+    let valueStart = -1;
+    const closeValue = (end) => {
+        // A value just ended at `end`; if it is a top-level member's value, record the member.
+        if (stack.length === 1 && pendingTop) {
+            members.push({ ...pendingTop, end });
+            pendingTop = undefined;
+        }
+    };
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === '"') {
+            let j = i + 1;
+            while (text[j] !== '"')
+                j += text[j] === "\\" ? 2 : 1;
+            const raw = text.slice(i, j + 1);
+            let k = j + 1;
+            while (k < text.length && /[ \t\n\r]/.test(text[k]))
+                k++;
+            const top = stack[stack.length - 1];
+            if (text[k] === ":" && top?.names) {
+                const name = JSON.parse(raw);
+                if (top.names.has(name))
+                    return { members, duplicate: { name, at: top.path } };
+                top.names.add(name);
+                top.key = name;
+                if (stack.length === 1)
+                    pendingTop = { name, start: i };
+                i = k + 1;
+                continue;
+            }
+            closeValue(j + 1);
+            i = j + 1;
+            continue;
+        }
+        if (c === "{" || c === "[") {
+            const parent = stack[stack.length - 1];
+            const at = parent ? `${parent.path}/${parent.names ? parent.key : parent.index}` : "";
+            stack.push({ names: c === "{" ? new Set() : null, path: at, index: 0 });
+            i++;
+            continue;
+        }
+        if (c === "}" || c === "]") {
+            stack.pop();
+            closeValue(i + 1);
+            i++;
+            continue;
+        }
+        if (c === ",") {
+            const top = stack[stack.length - 1];
+            if (top && !top.names)
+                top.index++;
+            i++;
+            continue;
+        }
+        if (/[ \t\n\r:]/.test(c)) {
+            i++;
+            continue;
+        }
+        // A number, true, false or null.
+        valueStart = i;
+        while (i < text.length && !/[ \t\n\r,\]}]/.test(text[i]))
+            i++;
+        if (valueStart < i)
+            closeValue(i);
+    }
+    return { members };
+}
+/** The first thing in `v` that JSON cannot say, or that only an alias can produce. */
+function nonJson(v, at, seen) {
+    if (v === null || typeof v === "string" || typeof v === "boolean")
+        return undefined;
+    if (typeof v === "number")
+        return Number.isFinite(v) ? undefined : `${at || "/"}: ${v} is not a JSON number`;
+    if (typeof v !== "object")
+        return `${at || "/"}: a ${typeof v} is not a JSON value`;
+    if (seen.has(v))
+        return `${at || "/"}: YAML aliases are not allowed`;
+    seen.add(v);
+    if (Array.isArray(v)) {
+        for (let i = 0; i < v.length; i++) {
+            const p = nonJson(v[i], `${at}/${i}`, seen);
+            if (p)
+                return p;
+        }
+        return undefined;
+    }
+    if (Object.getPrototypeOf(v) !== Object.prototype)
+        return `${at || "/"}: not a plain mapping`;
+    for (const [k, x] of Object.entries(v)) {
+        const p = nonJson(x, `${at}/${k}`, seen);
+        if (p)
+            return p;
+    }
+    return undefined;
+}
+// ── Record digest ────────────────────────────────────────────────────────────
+/**
+ * The digest a review verdict names: the lowercase hex SHA-256 of the record
+ * file's text with its reviews block taken out of the front matter (#2672), or
+ * for a JSON record its reviews member taken out of the object (ws-053).
+ * Adding, changing or removing a verdict leaves it as it was; any other edit
+ * to the file changes it, so a verdict given before an amendment stops
+ * counting.
+ *
+ * `field` names the top-level fields left out: one name, or a list. For a
+ * kind with a reviews list the list is the reviews field and `seal`, the
+ * record's author seal (#2688; {@link digestFields}), so sealing a record
+ * leaves its digest where it was too. A record with no `seal` hashes exactly
+ * as it did before author seals existed. A kind with `reviews.ratified` adds
+ * its state field (#2873), and a kind with `seal` its seal field (#2546), so
+ * the whole-file seal written at the close moves no digest. The digest is not
+ * that seal: {@link recordSeal} covers the whole record.
+ *
+ * The rule, which a hand-editor can follow with a text editor and
+ * `sha256sum`:
+ *
+ * 1. Line endings become LF (CRLF and a lone CR each become one LF).
+ * 2. When the text starts with a `---` line and a later line is exactly
+ *    `---`, the lines between them are the front matter. In it, each line
+ *    that starts, at column 0, with one of the keys (bare, or in single or
+ *    double quotes), optional spaces or tabs and a `:`, is removed, and so
+ *    is every line after it, up to the closing `---`, that is empty or
+ *    starts with a space, a tab, `#` or `-`. Removal stops at the first
+ *    other line. Everything else, the `---` lines and the body included, is
+ *    kept byte for byte. Which key is removed first makes no difference.
+ * 3. The digest is the SHA-256 of the result's UTF-8 bytes.
+ *
+ * Text with no front matter, or none of the keys, is hashed after step 1
+ * alone. A writer that adds a verdict must change only the reviews block: a
+ * reformatted front matter is a new digest, and every earlier verdict stops
+ * counting.
+ */
+export function recordTextDigest(text, field = "reviews", format = "markdown-front-matter") {
+    const lf = text.replace(/\r\n?/g, "\n");
+    const fields = field === null ? [] : typeof field === "string" ? [field] : field;
+    const kept = format === "json" ? fields.reduce(withoutMember, lf) : withoutBlocks(lf, fields);
+    return createHash("sha256").update(kept, "utf8").digest("hex");
+}
+// ── Record seal ──────────────────────────────────────────────────────────────
+/**
+ * The seal of a closed record (#2546, ws-003, ws-063): `sha256:` and the
+ * lowercase hex SHA-256 of the RFC 8785 (JCS) form of the whole record, with
+ * only the field that holds the seal left out. It is a separate hash from
+ * {@link recordTextDigest}, which a review verdict names: the digest leaves
+ * out the reviews, the author seal and the state so verdicts keep counting,
+ * and the seal covers all of them.
+ *
+ * 1. Line endings become LF (CRLF and a lone CR each become one LF).
+ * 2. The structured core is parsed as the kind's format says: the front
+ *    matter, as the JSON subset of YAML, or the whole JSON object. The
+ *    top-level member `field` is removed from it.
+ * 3. For a Markdown record the value hashed is the object
+ *    `{"body": <the text after the closing --- line>, "core": <the core>}`;
+ *    for a JSON record it is the core itself.
+ * 4. That value is written in JCS (keys sorted by UTF-16 code units, no
+ *    whitespace, ECMAScript number and string forms) and hashed as UTF-8.
+ *
+ * So every value in the record and every byte of its body is sealed, the
+ * reviews, the author seal and the state included, while the key order,
+ * quoting and indentation of the front matter are not: the same record
+ * written another way has the same seal. A YAML comment in the front matter
+ * is not part of the record, so it is not sealed either (#3066). Returns null when
+ * the core can't be parsed.
+ */
+export function recordSeal(text, field, format = "markdown-front-matter") {
+    const lf = text.replace(/\r\n?/g, "\n");
+    const parsed = parseRecord(format, lf);
+    if (!parsed.ok)
+        return null;
+    const core = { ...parsed.value };
+    delete core[field];
+    const sealed = format === "json" ? core : { body: bodyText(lf), core };
+    return contentDigest(canonicalJson(sealed));
+}
+/** The text below a Markdown file's front matter, with LF line endings: everything after the closing `---` line. */
+export function bodyText(text) {
+    const normalised = text.replace(/\r\n?/g, "\n");
+    const m = normalised.match(/^---\n[\s\S]*?\n---(?:\n|$)/);
+    return m ? normalised.slice(m[0].length) : "";
+}
+/**
+ * `text` with the top-level member `field` removed from a JSON record, by the
+ * rule a hand-editor follows for a JSON record (ws-053). With several fields
+ * (the reviews member, then `seal`, #2688) the rule is applied to each in
+ * turn, to the text the previous one left:
+ *
+ * 1. Line endings become LF, as for Markdown.
+ * 2. When the text is a JSON record (one object, no repeated member name) and
+ *    its top-level object has a member named `field`, that member is deleted:
+ *    the whitespace right before its name, the name, the colon, the value,
+ *    and one comma with the whitespace right before that comma. The comma is
+ *    the one after the value when another member follows, or else the one
+ *    before the member, when a member precedes it. Nothing else changes: other
+ *    members, their order, the indentation and the final newline stay byte
+ *    for byte.
+ * 3. The digest is the SHA-256 of the result's UTF-8 bytes.
+ *
+ * So in a pretty-printed file, deleting the `"reviews": [...]` lines and the
+ * comma that separated the member from its neighbour gives the text to hash.
+ * Text that is not a JSON record, or has no such member, is hashed after step 1
+ * alone. A writer that adds a verdict changes only that member's value.
+ */
+function withoutMember(text, field) {
+    const parsed = parseJsonRecord(text);
+    if (!parsed.ok)
+        return text;
+    const { members } = scanJson(text);
+    const at = members.findIndex((m) => m.name === field);
+    if (at < 0)
+        return text;
+    const m = members[at];
+    let start = m.start;
+    while (start > 0 && /[ \t\n]/.test(text[start - 1]))
+        start--;
+    let end = m.end;
+    if (at + 1 < members.length) {
+        // The comma after the value, and the whitespace before it.
+        let k = end;
+        while (/[ \t\n]/.test(text[k]))
+            k++;
+        end = k + 1;
+    }
+    else if (at > 0) {
+        // The comma before the member, and the whitespace between it and the previous value.
+        let k = start - 1;
+        while (k > 0 && text[k] !== ",")
+            k--;
+        while (k > 0 && /[ \t\n]/.test(text[k - 1]))
+            k--;
+        start = k;
+    }
+    return text.slice(0, start) + text.slice(end);
+}
+/** `text` with the top-level blocks of `fields` removed from its front matter, by the rule {@link recordTextDigest} states. */
+function withoutBlocks(text, fields) {
+    if (fields.length === 0)
+        return text;
+    const lines = text.split("\n");
+    if (lines[0] !== "---")
+        return text;
+    const close = lines.indexOf("---", 1);
+    if (close < 0)
+        return text;
+    const keys = fields.map((f) => f.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).map((k) => `${k}|"${k}"|'${k}'`);
+    const starts = new RegExp(`^(?:${keys.join("|")})[ \\t]*:(?:[ \\t]|$)`);
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (i > 0 && i < close && starts.test(lines[i])) {
+            while (i + 1 < close && /^(?:$|[ \t#-])/.test(lines[i + 1]))
+                i++;
+            continue;
+        }
+        out.push(lines[i]);
+    }
+    return out.join("\n");
+}
+// ── Quorum ───────────────────────────────────────────────────────────────────
+/** The quorum a workspace sets when its declaration names none: two verdicts besides the decider's (#2555). */
+export const DEFAULT_QUORUM = 2;
+/** A principal as the quorum compares it: NFKC, trimmed and lower-cased, so `alice` and `Alice ` are one reviewer (#2671). */
+export function normalisePrincipal(name) {
+    return name.normalize("NFKC").trim().toLowerCase();
+}
+/** The check used when {@link QuorumOptions.verifySeal} is not given. */
+function uncheckedSeal(attestation, v) {
+    if (v.seal === undefined || v.seal === null) {
+        return { attested: attestation ? false : null, code: "seal-missing", message: `the verdict by ${v.reviewer} carries no seal` };
+    }
+    return { attested: null, code: "seal-unverifiable", message: `the seal by ${v.reviewer} was not checked` };
+}
+const VERDICTS = new Set(["agree", "dissent", "abstain"]);
+/**
+ * The quorum of one record, read from its reviews list, or null when the
+ * kind has no reviews list or the front matter could not be read (#2671).
+ * Malformed entries are skipped; the schema reports them.
+ *
+ * A verdict is not counted when its reviewer is the decider, holds the agent
+ * role, names a digest other than the record's own now, or, under an active
+ * attestation policy, carries no seal that verifies for its reviewer (#2687),
+ * in that order. Of the rest, the latest verdict per principal counts and
+ * each earlier one is a duplicate. Every verdict reports its seal's check in
+ * `attested` and `attestation`, whether it counts or not.
+ */
+export function computeQuorum(kind, entry, options) {
+    if (!kind.reviews || entry.data === null)
+        return null;
+    const list = entry.data[kind.reviews.field];
+    const decidedBy = entry.data[kind.reviews.decider];
+    const decider = typeof decidedBy === "string" ? normalisePrincipal(decidedBy) : null;
+    const idValue = entry.id !== undefined ? entry.id : kind.idField !== undefined ? entry.data[kind.idField] : null;
+    const record = typeof idValue === "string" ? idValue : null;
+    const verdicts = [];
+    const openConcerns = [];
+    (Array.isArray(list) ? list : []).forEach((raw, index) => {
+        if (raw === null || typeof raw !== "object")
+            return;
+        const r = raw;
+        if (typeof r.reviewer !== "string" || typeof r.verdict !== "string" || !VERDICTS.has(r.verdict))
+            return;
+        const digest = typeof r.digest === "string" ? r.digest : null;
+        const input = { record, reviewer: r.reviewer, verdict: r.verdict, on: r.on, digest, seal: r.seal };
+        const { attested, ...attestation } = options.verifySeal ? options.verifySeal(input) : uncheckedSeal(options.attestation, input);
+        const v = {
+            index,
+            principal: normalisePrincipal(r.reviewer),
+            reviewer: r.reviewer,
+            verdict: r.verdict,
+            digest,
+            attested,
+            attestation,
+        };
+        if (v.principal === decider) {
+            v.reason = { code: "review-decider", message: `${v.reviewer} decided this record, and the quorum counts verdicts besides the decider's` };
+        }
+        else if (options.agents.has(v.principal)) {
+            v.reason = { code: "review-agent", message: `${v.reviewer} holds the agent role in the trust policy at base, and an agent's verdict does not count` };
+        }
+        else if (v.digest !== null && v.digest !== entry.digest) {
+            v.reason = { code: "review-older-digest", message: `${v.reviewer} judged the text at digest ${v.digest.slice(0, 12)}, and the record's text is now at ${entry.digest.slice(0, 12)}` };
+        }
+        else if (options.attestation && attested !== true) {
+            v.reason = { code: "review-unattested", message: `an attestation policy is active at base, and ${attestation.message}` };
+        }
+        verdicts.push(v);
+        if (v.verdict === "dissent" && r.addressed_by == null && r.withdrawn_on == null) {
+            openConcerns.push({
+                index,
+                principal: v.principal,
+                reviewer: v.reviewer,
+                note: typeof r.note === "string" ? r.note : null,
+                ...(typeof r.proposes === "string" ? { proposes: r.proposes } : {}),
+            });
+        }
+    });
+    // The latest verdict per principal stands; earlier ones are duplicates.
+    const latest = new Map();
+    for (const v of verdicts)
+        if (!v.reason)
+            latest.set(v.principal, v);
+    for (const v of verdicts) {
+        if (v.reason || latest.get(v.principal) === v)
+            continue;
+        const later = latest.get(v.principal);
+        v.reason = { code: "review-duplicate", message: `the later verdict by ${JSON.stringify(later.reviewer)} (entry ${later.index}) replaces this one, and a principal counts once` };
+    }
+    const counted = verdicts.filter((v) => !v.reason);
+    const agreed = counted.filter((v) => v.verdict === "agree").length;
+    const met = agreed >= options.need;
+    return {
+        need: options.need,
+        needFrom: options.needFrom,
+        agreed,
+        counted,
+        notCounted: verdicts.filter((v) => v.reason),
+        openConcerns,
+        met,
+        metWithObjections: met && openConcerns.length > 0,
+    };
+}
+/**
+ * ajv's errors as `<path> <message>` lines. A failed `if` whose `then` or
+ * `else` branch has a `description` is reported by that description alone, in
+ * place of the branch's own errors, with each `{field}` filled from the value
+ * the branch checked. The decision schema words its dissent rule this way, so
+ * the message names the reviewer (#2652). The schema stays plain JSON Schema,
+ * with no keyword a strict validator would refuse.
+ */
+function renderSchemaErrors(errors) {
+    const replaced = [];
+    const described = new Map();
+    for (const e of errors) {
+        const branch = e.keyword === "if" ? e.params?.failingKeyword : undefined;
+        const text = branch ? e.parentSchema?.[branch]?.description : undefined;
+        if (!branch || typeof text !== "string")
+            continue;
+        const at = e.data !== null && typeof e.data === "object" ? e.data : {};
+        described.set(e, text.replace(/\{([A-Za-z0-9_]+)\}/g, (all, key) => (typeof at[key] === "string" ? at[key] : all)));
+        replaced.push(`${e.schemaPath.replace(/\/if$/, "")}/${branch}/`);
+    }
+    return errors
+        .filter((e) => described.has(e) || !replaced.some((prefix) => e.schemaPath.startsWith(prefix)))
+        .map((e) => `${e.instancePath || "/"} ${described.get(e) ?? e.message ?? "is invalid"}`);
+}
+async function compileSchema(schema, refs = []) {
+    const mod = (await import("ajv"));
+    // ajv is CommonJS; its class is the default export, or that export's own default.
+    const Ajv = (mod.default.default ?? mod.default);
+    let validate;
+    try {
+        const ajv = new Ajv({ allErrors: true, strict: false, verbose: true });
+        // The files the schema $refs, registered by their $id first (ws-053).
+        for (const ref of refs)
+            ajv.addSchema(ref);
+        validate = ajv.compile(schema);
+    }
+    catch (err) {
+        throw new RecordReadError("schema-invalid", `the kind's schema does not compile: ${message(err)}`);
+    }
+    return (data) => (validate(data) ? { ok: true } : { ok: false, errors: renderSchemaErrors(validate.errors ?? []) });
+}
+/**
+ * The ids a record's supersedes field names (ws-053). With the kind's `key`,
+ * the field is a list of objects and each one's `key` holds an id; without
+ * it, the field holds one id or a list of ids. Anything else names none.
+ */
+export function supersedesTargets(kind, data) {
+    if (!kind.supersedes || data === null)
+        return [];
+    const { field, key } = kind.supersedes;
+    const value = data[field];
+    if (key === undefined && typeof value === "string")
+        return [value];
+    if (!Array.isArray(value))
+        return [];
+    const ids = key === undefined ? value : value.map((l) => (l !== null && typeof l === "object" ? l[key] : undefined));
+    return ids.filter((x) => typeof x === "string");
+}
+/**
+ * The ids a record's remediates field names (#2774), read the same way
+ * {@link supersedesTargets} reads `supersedes`.
+ */
+export function remediatesTargets(kind, data) {
+    if (!kind.remediates || data === null)
+        return [];
+    const { field, key } = kind.remediates;
+    const value = data[field];
+    if (key === undefined && typeof value === "string")
+        return [value];
+    if (!Array.isArray(value))
+        return [];
+    const ids = key === undefined ? value : value.map((l) => (l !== null && typeof l === "object" ? l[key] : undefined));
+    return ids.filter((x) => typeof x === "string");
+}
+/** The stem of a file name: the name up to its first `.`, the hash a content-addressed record's name claims (ws-053). */
+function nameStem(path) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    const dot = name.indexOf(".");
+    return dot < 0 ? name : name.slice(0, dot);
+}
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/** Read every record `loaded` locates, through `options.source`. */
+export async function readRecords(loaded, options) {
+    const { kind } = loaded;
+    const dirRel = toPosix(relative(options.root, loaded.dir)) || ".";
+    const names = options.source.list(dirRel);
+    if (names === undefined) {
+        throw new RecordReadError("location-missing", `records directory ${dirRel} does not exist${options.source.label}`);
+    }
+    const match = new RegExp(kind.location.match);
+    const validate = await compileSchema(loaded.schema, loaded.refs);
+    const workspaceRoot = options.workspaceRoot ?? ".";
+    // Where a relative transcript path resolves (#2708): the workspace root in the working tree.
+    const workspaceDir = workspaceRoot === "." ? options.root : resolve(options.root, ...workspaceRoot.split("/"));
+    const entries = [];
+    const texts = new Map();
+    for (const name of names.filter((n) => match.test(n)).sort()) {
+        const path = dirRel === "." ? name : `${dirRel}/${name}`;
+        const text = options.source.read(path);
+        const entry = {
+            id: null,
+            path,
+            state: null,
+            valid: true,
+            reasons: [],
+            supersededBy: null,
+            remediatedBy: [],
+            data: null,
+            assets: [],
+            warnings: [],
+            digest: recordTextDigest(text, digestFields(kind), kind.format),
+        };
+        entries.push(entry);
+        if (kind.session)
+            texts.set(path, text);
+        const fm = parseRecord(kind.format, text);
+        if (!fm.ok) {
+            entry.reasons.push({ code: "record-unparseable", message: fm.message });
+            continue;
+        }
+        entry.data = fm.value;
+        if (kind.idFrom === "sha256") {
+            // The id is the hash of the bytes; the name's stem is the hash it claims.
+            // A name that claims another is the record pinning itself, drifted (ws-053).
+            entry.id = sha256Hex(options.source.bytes(path));
+            const stem = nameStem(path);
+            if (stem !== entry.id) {
+                const self = workspaceRoot === "." ? path : path.startsWith(`${workspaceRoot}/`) ? path.slice(workspaceRoot.length + 1) : path;
+                if (SHA256_HEX.test(stem))
+                    entry.assets.push({ path: self, sha256: stem, actual: entry.id, state: "drifted" });
+                entry.warnings.push({
+                    code: "asset-drift",
+                    message: SHA256_HEX.test(stem)
+                        ? `${self} is named for sha256 ${stem.slice(0, 12)}, and its bytes${options.source.label} hash to ${entry.id.slice(0, 12)}`
+                        : `${self} is content-addressed, and its name claims no sha256: its bytes${options.source.label} hash to ${entry.id.slice(0, 12)}`,
+                });
+            }
+        }
+        else {
+            const id = fm.value[kind.idField];
+            if (typeof id === "string")
+                entry.id = id;
+        }
+        const state = kind.stateField === undefined ? undefined : fm.value[kind.stateField];
+        if (typeof state === "string")
+            entry.state = state;
+        const result = validate(fm.value);
+        if (!result.ok) {
+            entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
+        }
+        if (kind.source) {
+            // The stored source block (#2708): its proposal fields' shapes, and the transcript it pins.
+            const block = sourceBlock(fm.value, kind.source.field);
+            if (block) {
+                const problems = sourceBlockProblems(block, kind.source.field);
+                if (problems.length > 0)
+                    entry.reasons.push({ code: "record-schema-invalid", message: problems.join("; ") });
+                const drift = transcriptDrift(block, kind.source.field, workspaceDir);
+                if (drift)
+                    entry.warnings.push({ code: "source-transcript-drift", message: drift });
+            }
+        }
+        if (kind.seal && !kind.session && entry.state !== null && (kind.closedStates ?? []).includes(entry.state)) {
+            // A closed record's whole-file seal (#2546, ws-063). A session's is checked with its verdicts (#2673).
+            const seal = fm.value[kind.seal.field];
+            const actual = typeof seal === "string" ? recordSeal(text, kind.seal.field, kind.format) : null;
+            if (typeof seal === "string" && actual !== seal) {
+                entry.reasons.push({ code: "record-seal-mismatch", message: `${kind.seal.field} is ${seal}, but the record seals to ${actual}: it changed after it closed` });
+            }
+        }
+        if (kind.pins) {
+            const cited = fm.value[kind.pins.field];
+            if (Array.isArray(cited) && cited.length === 0) {
+                entry.warnings.push({ code: "record-no-evidence", message: `${kind.pins.field} is empty: the record cites nothing and pins no file` });
+            }
+            if (options.assets) {
+                const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
+                entry.assets.push(...checked.assets);
+                entry.warnings.push(...checked.warnings);
+            }
+        }
+        if (kind.reviews) {
+            const list = fm.value[kind.reviews.field];
+            const undigested = (Array.isArray(list) ? list : [])
+                .filter((r) => r !== null && typeof r === "object" && !Array.isArray(r) && r.digest === undefined)
+                .map((r) => (typeof r.reviewer === "string" ? r.reviewer : "an unnamed reviewer"));
+            if (undigested.length > 0) {
+                entry.warnings.push({
+                    code: "review-undigested",
+                    message: `the ${undigested.length === 1 ? "verdict" : "verdicts"} by ${undigested.join(", ")} name no digest: ${undigested.length === 1 ? "it counts" : "they count"}, and an amendment will not stop ${undigested.length === 1 ? "it" : "them"} counting`,
+                });
+            }
+        }
+    }
+    // Ids: the first file in path order keeps an id; later ones are flagged.
+    const byId = new Map();
+    for (const e of entries) {
+        if (e.id === null)
+            continue;
+        const first = byId.get(e.id);
+        if (first)
+            e.reasons.push({ code: "record-id-duplicate", message: `id ${e.id} is already used by ${first.path}` });
+        else
+            byId.set(e.id, e);
+    }
+    // Supersession comes from the new record's links, never from the old record.
+    // With approval ranks, a link takes effect under an equal or stricter
+    // approval rule: from a record ranked above 0 and at least as high as the
+    // one it names (#2524 D4). Without them, only from a closed record (#2555).
+    // A record is superseded at most once.
+    const closed = new Set(kind.closedStates ?? []);
+    const rank = (state) => (state === null ? 0 : (kind.approval?.[state] ?? 0));
+    const takesEffect = (from, to) => kind.approval ? rank(from.state) > 0 && rank(from.state) >= rank(to.state) : from.state !== null && closed.has(from.state);
+    for (const e of entries) {
+        for (const target of supersedesTargets(kind, e.data)) {
+            const old = byId.get(target);
+            if (!old) {
+                e.reasons.push({ code: "record-supersedes-unknown", message: `supersedes ${target}, which no record has` });
+                continue;
+            }
+            if (old === e)
+                continue;
+            if (!takesEffect(e, old)) {
+                if (kind.approval) {
+                    e.warnings.push({
+                        code: "record-supersedes-pending",
+                        message: `supersedes ${target}, which is ${old.state ?? "stateless"}; a ${e.state ?? "stateless"} record can't supersede it, so the link takes effect once this record is approved at least as strongly`,
+                    });
+                }
+                continue;
+            }
+            if (old.supersededBy !== null && old.supersededBy !== e.id) {
+                e.reasons.push({
+                    code: "record-supersedes-conflict",
+                    message: `supersedes ${target}, which ${old.supersededBy} already supersedes`,
+                });
+                continue;
+            }
+            old.supersededBy = e.id;
+        }
+    }
+    // Remediation (#2774): a later record fixes a consequence of a closed one
+    // without replacing it. The target's status, and its supersededBy, never
+    // change; several records may remediate the same one. Unlike supersedes,
+    // this needs no approval rank: the target is closed or it isn't, and a
+    // still-open target is amended instead of remediated.
+    for (const e of entries) {
+        for (const target of remediatesTargets(kind, e.data)) {
+            const old = byId.get(target);
+            if (!old) {
+                e.reasons.push({ code: "record-remediates-unknown", message: `remediates ${target}, which no record has` });
+                continue;
+            }
+            if (old === e)
+                continue;
+            if (old.state === null || !closed.has(old.state)) {
+                e.reasons.push({
+                    code: "record-remediates-not-closed",
+                    message: `remediates ${target}, which is ${old.state ?? "stateless"}, not closed; a record still open is amended instead`,
+                });
+                continue;
+            }
+            if (e.id !== null && !old.remediatedBy.includes(e.id))
+                old.remediatedBy.push(e.id);
+        }
+    }
+    // A pin that still matches, at the hash a record this one supersedes
+    // pinned, while the file has not changed since this record was recorded:
+    // the decision moved on and the artifact did not (#2549).
+    for (const e of entries) {
+        for (const a of e.assets) {
+            if (a.state !== "pinned")
+                continue;
+            const old = entries.find((o) => o.supersededBy !== null && o.supersededBy === e.id && o.assets.some((p) => p.path === a.path && p.sha256 === a.sha256));
+            if (!old)
+                continue;
+            const changed = options.history?.fileChanged(a.path) ?? null;
+            const recorded = options.history ? options.history.recorded(e.path) : null;
+            // A record not yet committed is recorded now, after every commit.
+            if (changed !== null && recorded !== null && changed > recorded)
+                continue;
+            a.state = "stale";
+            e.warnings.push({
+                code: "asset-stale",
+                message: `${a.path} is pinned at the hash ${old.id} pinned, and it has not changed since: ${e.id} supersedes ${old.id}, and the artifact did not follow`,
+            });
+        }
+    }
+    // A session's seal and its verdicts' records (#2673).
+    joinSessions(kind, entries, texts, options.subjects ?? null);
+    // A work kind's links, ready and blocked (#2683), from every record before --current.
+    const work = kind.work ? await (await import("./work.js")).applyWork(loaded, entries, options) : undefined;
+    // An answer kind's points (ws-058): an answer whose point is gone or changed is warned about.
+    if (kind.answers)
+        (await import("./points.js")).applyAnswers(loaded, entries, options);
+    for (const e of entries)
+        e.valid = e.reasons.length === 0;
+    const records = options.current ? entries.filter((e) => e.supersededBy === null) : entries;
+    return {
+        records,
+        summary: {
+            total: records.length,
+            valid: records.filter((e) => e.valid).length,
+            invalid: records.filter((e) => !e.valid).length,
+            superseded: entries.filter((e) => e.supersededBy !== null).length,
+        },
+        ...(work ? { decisions: work.decisions } : {}),
+    };
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join(posix.sep);
+}