wingfoil 0.2.2 → 0.3.0

package/dist/core/memory-transition.js

@@ -1,31 +1,47 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WIP_REFS_SENTENCE = void 0;
 exports.prepareMemoryTransition = prepareMemoryTransition;
+exports.prepareMemoryTransitionAtRev = prepareMemoryTransitionAtRev;
+exports.requireWipSlot = requireWipSlot;
+exports.isMoreAdvancedState = isMoreAdvancedState;
+exports.beginMemoryTransition = beginMemoryTransition;
 exports.verifyCommittedScope = verifyCommittedScope;
+exports.checkMemoryTransition = checkMemoryTransition;
 exports.commitMemoryTransition = commitMemoryTransition;
 /**
  * The shared skeleton of every Memory state-transition verb (task-045-memory-submit; reused by
- * `memory approve`/`reject`/`deprecate`, task-046/047/048).
+ * `memory approve`/`reject`/`deprecate`, task-046/047/048, by `memory amend`, task-127, whose
+ * edge is the self-loop of the current state, and by `memory park`, task-180, which takes a declared
+ * `returns` edge).
  *
  * A transition verb always does the same two things around its own verb-specific rules:
  *
  * 1. {@link prepareMemoryTransition} — find the document by its bare id (spec-008-cli-grammar §7), read
- *    its declared `type` and current `status`, and resolve the legal target for the verb **against the
- *    `memory.yaml` committed at `HEAD`** (task-091, `bug-081`, `dl-080` (B)). Every expected
+ *    its declared `type` and current `status`, and resolve the legal target for the verb, **all at
+ *    `HEAD`**: the committed `memory.yaml` (task-091, `bug-081`, `dl-080` (B)) and the committed
+ *    document (task-247, `bug-187`); the working tree supplies the content to commit and is checked to
+ *    be the same element `HEAD` records. Every expected
  *    refusal is returned as a `CoreResult.error` (exit `1`), **before anything is written**, so "the
  *    state is unchanged" (P1.6 sc.2, REQ-STATE-01) holds by construction.
  * 2. {@link commitMemoryTransition} — write the new bytes and turn them into exactly one commit scoped
  *    to that one document.
  *
  * What happens in between (required-field checks, which fields change, the commit message) is the
- * verb's own business; see `memorySubmitFn` in `./index.ts`.
+ * verb's own business; see `memorySubmitFn` in `./index.ts`. One verb makes a second commit: an
+ * approve that fires the `supersedes:` trigger (task-162, `./memory-supersede.ts`) prepares the
+ * superseded element with {@link prepareMemoryTransitionAtRev} at the approve's own sha and runs
+ * {@link checkMemoryTransition} on both documents before either commit.
  */
+const fs_1 = require("fs");
 const path_1 = require("path");
 const memory_1 = require("../memory");
 const storage_1 = require("../storage");
 const validation_1 = require("../validation");
 const confinement_1 = require("./confinement");
+const git_identity_1 = require("./git-identity");
 const loaders_1 = require("./loaders");
+const revision_1 = require("./revision");
 const types_1 = require("./types");
 const write_guard_1 = require("./write-guard");
 /**
@@ -51,36 +67,137 @@ function uncommittedMachineNote(root) {
         `committed copy (dl-080); commit '${loaders_1.MEMORY_YAML_PATH}' first if this transition depends on that change`);
 }
 /**
- * Locate document `id` and resolve verb `op` on it, **against the `memory.yaml` committed at
- * `HEAD`** (`loadMemoryYamlAtHead`).
+ * A second sentence for `document not found` when the lookup at `HEAD` skipped documents it could not
+ * read (task-171): the id may be in one of them, so they are named as `HEAD:<path>`. Empty otherwise,
+ * so the pinned first sentence (P1.6 sc.3) is unchanged.
+ */
+function unreadableNote(unreadable) {
+    if (unreadable.length === 0)
+        return '';
+    const named = unreadable.map((diagnostic) => `HEAD:${diagnostic.file} (${diagnostic.message.slice(diagnostic.message.indexOf(': ') + 2)})`);
+    return ` — it may be in a Memory document committed at HEAD that could not be read: ${named.join('; ')}`;
+}
+/**
+ * The refusal of a transition whose element is written in a `format` newer than this build reads
+ * (`dl-149`, task-257, `bug-241`): `VALIDATION`, exit `1`, before anything is written, carrying the
+ * loader's own `E_INVALID_FORMAT format (<file>): … upgrade WingFoil` text and naming which copy said so —
+ * `HEAD`'s, which decides, or the working tree's, which the verb would commit. Anything other than that
+ * refusal is rethrown.
+ */
+function newerFormatRefusal(op, id, where, error) {
+    if (!(0, validation_1.isNewerFormatError)(error))
+        throw error;
+    return (0, types_1.coreErr)({
+        code: 'VALIDATION',
+        message: `refusing to ${op} ${id}: its document, as ${where} holds it, is written in a newer format: ${error.message}`,
+        details: { issues: error.issues },
+    });
+}
+/** Whether `full` names a directory entry at all — `lstat`, so a link is present even when dangling. */
+function isPresent(full) {
+    try {
+        (0, fs_1.lstatSync)(full);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The working-tree path of a document carrying frontmatter `id`, or `undefined` — read only to
+ * **explain** a refusal already decided at `HEAD`, never to decide one (the `command-baseline`
+ * directive: "the working tree may be read to explain a refusal, never to decide one"). A document
+ * elsewhere whose frontmatter does not parse is skipped by the scan (task-171), and any failure to
+ * walk the working tree yields `undefined`, so the refusal keeps its plain wording and no branch of
+ * this read can change an outcome.
+ */
+function uncommittedDocumentPath(root, memoryYaml, id) {
+    // `followSymlinks`: this read only words a refusal, so it may follow a link the deciding scan skips
+    // (task-171, `bug-189`), and the confinement guards then refuse the link by name.
+    try {
+        return (0, memory_1.findMemoryDocumentById)(root, memoryYaml, id, { followSymlinks: true })?.path;
+    }
+    catch {
+        // Explain-only: a working tree the walk cannot read (an unreadable directory, `EACCES`) leaves
+        // the refusal its plain wording rather than becoming the outcome (task-171 re-review A).
+        return undefined;
+    }
+}
+/**
+ * The frontmatter `id` commit `sha` records for `path`, or `undefined` when the commit does not hold
+ * the path, or holds it with frontmatter that does not parse (the scan at the same sha skipped it,
+ * task-171). Like {@link uncommittedDocumentPath}, it only words a refusal, so no branch of it can
+ * change an outcome.
+ */
+function recordedIdAt(root, sha, path) {
+    let id;
+    try {
+        id = (0, memory_1.loadMemoryDocumentSummaryAtRev)(root, sha, path)?.frontmatter.id;
+    }
+    catch {
+        // Explain-only: a document HEAD holds but cannot be read records no id to name.
+        return undefined;
+    }
+    return id === undefined ? undefined : String(id);
+}
+/**
+ * Locate document `id` and resolve verb `op` on it, **at `HEAD`**: the `memory.yaml`, the document
+ * the id names and its current `status` are all read from the one commit `HEAD` resolves to, once
+ * (`resolveRevision`, then `loadMemoryYamlAtRev` and `findMemoryDocumentByIdAtRev` at that sha).
+ *
+ * The baseline is the point (`spec-006-core-domain-api` §6 item 1, `dl-080` option (B)). This
+ * function takes no `MemoryYaml` and no document: a caller cannot hand it a working-tree machine or a
+ * working-tree `status` even by accident. Two defects motivated it. An uncommitted edit to a type's
+ * `sequence` used to decide the transition a verb performed (task-091, `bug-081`); and until task-247
+ * (`bug-187`) the id was looked up by scanning the working tree and `from` was the working-tree
+ * frontmatter's `status`, so an element already past `draft` at `HEAD` but edited back to `draft` on
+ * disk was submitted again, and a hand-made document no commit holds was transitioned as if `memory
+ * add` had registered it.
  *
- * The baseline is the point (task-091, `bug-081`, `dl-080` option (B)). This function takes no
- * `MemoryYaml`: a caller cannot hand it a working-tree machine even by accident, which is what makes
- * the committed baseline a property of the read itself rather than of a precondition someone must
- * remember to run. An uncommitted edit to a type's `sequence` used to decide both the transition a
- * verb performed and the `status` it committed — through `memory submit`, which requires no
- * authority — and stranded the element in a state the committed machine rejects.
+ * **Content from the working tree, state from `HEAD`.** The `content` and `frontmatter` this returns
+ * are the working tree's, because that is what `memory submit` and `memory amend` commit; `from`, the
+ * `type` and the target are `HEAD`'s. The working tree must still carry the same `id` and `type` the
+ * commit records — a verb decides on one element and writes that element.
  *
  * Refusals, all returned (never thrown) and all exit `1`:
  *
- * - `HEAD` holds no `memory.yaml` → `VALIDATION`, fail-closed: with no committed machine there is no
- *   `from → to` to record, and the only fail-open available is the working tree, which is the defect.
- *   `wingfoil init` commits the scaffold, so no legitimate flow reaches this;
+ * - `HEAD` holds no `memory.yaml` (or there is no commit) → `VALIDATION`, fail-closed: with no
+ *   committed machine there is no `from → to` to record, and the only fail-open available is the
+ *   working tree, which is the defect. `wingfoil init` commits the scaffold, so no legitimate flow
+ *   reaches this;
  * - the committed `memory.yaml` does not parse or validate → `VALIDATION`, same reasoning;
- * - no document carries that frontmatter `id` → `NOT_FOUND` `document not found: <id>` (P1.6 sc.3);
+ * - no document at `HEAD` carries that frontmatter `id` → `NOT_FOUND` `document not found: <id>`
+ *   (P1.6 sc.3); when a working-tree document carries it, the message says so and names `memory add`
+ *   (task-247), since a transition acts only on an element a commit records — or, when `HEAD` holds
+ *   that path under another id, `VALIDATION` naming the renamed `id` field;
+ * - `HEAD` holds the document but the working tree deleted it → `VALIDATION`, naming the path;
+ * - the working tree changes the document's `id` or `type` → `VALIDATION`;
  * - its `type` is not registered → `NOT_FOUND` with `memory add`'s unknown-type message;
- * - its `status` is not a state of the type → `VALIDATION` `invalid state '<s>' for type '<t>'`
- *   (task-036's `validateFrontmatterState`);
+ * - its committed `status` is not a state of the type → `VALIDATION` `invalid state '<s>' for type
+ *   '<t>'` (task-036's `validateFrontmatterState`);
  * - the verb is illegal from that state → `INVALID_TRANSITION` with the `dl-032` contract message
- *   (`resolveTypeTransition`), the engine's explanation in `details.issues[0].detail`.
+ *   (`resolveTypeTransition`), the engine's explanation in `details.issues[0].detail`. `amend`
+ *   (task-127) never takes this branch: its target is the current state.
+ * - the document, as `HEAD` records it or as the working tree would have it committed, declares a
+ *   `format` newer than this build reads → `VALIDATION` with the `dl-149` `E_INVALID_FORMAT` text, the
+ *   file named (task-257, `bug-241`);
+ * - the target state declares a WIP limit its holders have reached → `CONFLICT`
+ *   ({@link requireWipSlot}, task-180), the holders counted across every ref (task-274). Every
+ *   transition into a state goes through here, so the limit holds whichever verb or engine action
+ *   moves the element — except `reject` and `park`, which send it back along a reject or `returns`
+ *   edge and are exempt (`dl-156` Q2 (i)).
  *
- * The last four keep their pinned messages verbatim as the first sentence;
- * {@link uncommittedMachineNote} may append a second one.
+ * The unknown-type, invalid-state and illegal-transition refusals keep their pinned messages
+ * verbatim as the first sentence; {@link uncommittedMachineNote} may append a second one.
  */
 function prepareMemoryTransition(root, id, op) {
+    // Resolved ONCE: every read below is at this sha, so the machine and the document cannot come from
+    // two commits even if `HEAD` moves while the verb runs (task-137). No commit at all is the same
+    // answer as a commit without `memory.yaml`.
+    const sha = (0, revision_1.atHeadOr)(root, () => (0, revision_1.resolveRevision)(root, 'HEAD'), null);
     let memoryYaml;
     try {
-        memoryYaml = (0, loaders_1.loadMemoryYamlAtHead)(root);
+        memoryYaml = sha === null ? null : (0, loaders_1.loadMemoryYamlAtRev)(root, sha);
     }
     catch (error) {
         if (!(error instanceof validation_1.ValidationError))
@@ -93,18 +210,102 @@ function prepareMemoryTransition(root, id, op) {
             details: { issues: error.issues },
         });
     }
-    if (memoryYaml === null) {
+    if (sha === null || memoryYaml === null) {
         return (0, types_1.coreErr)({
             code: 'VALIDATION',
             message: `cannot resolve the state machine: '${loaders_1.MEMORY_YAML_PATH}' is not committed at HEAD. A transition is decided by ` +
                 `the machine the repository records, not by a working tree (dl-080); commit '${loaders_1.MEMORY_YAML_PATH}' first, then retry.`,
         });
     }
-    const found = (0, memory_1.findMemoryDocumentById)(root, memoryYaml, id);
+    return prepareMemoryTransitionAtRev(root, sha, memoryYaml, id, op);
+}
+/**
+ * The body of {@link prepareMemoryTransition}, at a sha and a committed `memory.yaml` the caller has
+ * already resolved: locate document `id` at `sha`, check the working tree carries the same element,
+ * and resolve `op` on its committed `status`. Every refusal {@link prepareMemoryTransition} documents
+ * past the `memory.yaml` read comes from here, unchanged.
+ *
+ * It exists so that a second decision in one command reads the same commit as the first: the
+ * `supersedes:` trigger (task-162) prepares the superseded element at the sha its superseding
+ * element's approve was decided at, with `op` `supersede`. With `expectedType`, a document of another
+ * type is refused (`VALIDATION`) before its own machine is consulted, since the caller's rule is about
+ * the type, not about that machine's states.
+ */
+function prepareMemoryTransitionAtRev(root, sha, memoryYaml, id, op, expectedType) {
+    // Tolerant (task-171, `bug-031`): a committed document the scan cannot read no longer refuses the
+    // transition of another element. It is skipped and reported; the verb's success carries it as a
+    // warning, and a miss names it, since the id may be in it.
+    const unreadable = [];
+    let found;
+    try {
+        found = (0, memory_1.findMemoryDocumentByIdAtRev)(root, sha, memoryYaml, id, { onDiagnostic: (diagnostic) => unreadable.push(diagnostic) });
+    }
+    catch (error) {
+        // The lookup throws only the `dl-149` refusal of the element it names (task-257, `bug-241`).
+        return newerFormatRefusal(op, id, 'HEAD', error);
+    }
     if (!found) {
-        return (0, types_1.coreErr)({ code: 'NOT_FOUND', message: `document not found: ${id}${uncommittedMachineNote(root)}` });
+        const onDisk = uncommittedDocumentPath(root, memoryYaml, id);
+        if (onDisk !== undefined) {
+            // A document reached through a symbolic link (its own name, or its type directory) is not a
+            // tree entry under the scan roots at HEAD, so the HEAD lookup cannot find it; the refusal is
+            // already decided, and the filesystem guard words it truthfully (bug-117, bug-120 D2).
+            const confined = (0, confinement_1.requireConfinedWriteTarget)(root, onDisk, 'write');
+            if (!confined.ok)
+                return confined;
+            const inspectable = (0, write_guard_1.requireInspectableTarget)(root, onDisk, TRANSITION_CONTRACT);
+            if (!inspectable.ok)
+                return inspectable;
+            const recorded = recordedIdAt(root, sha, onDisk);
+            if (recorded !== undefined) {
+                return (0, types_1.coreErr)({
+                    code: 'VALIDATION',
+                    message: `refusing to ${op} ${id}: the working tree changes frontmatter field 'id' of ${onDisk}, which HEAD records ` +
+                        `as '${recorded}'. A transition acts on the element the commit records; restore the id, then retry.`,
+                });
+            }
+            return (0, types_1.coreErr)({
+                code: 'NOT_FOUND',
+                message: `document not found: ${id} — ${onDisk} is not committed at HEAD, though it carries that id in the working tree. ` +
+                    'A transition is decided by the status the repository records (spec-006 §6 item 1, dl-080), so it acts only ' +
+                    'on a committed element; register a new element with `memory add`, then retry.',
+            });
+        }
+        return (0, types_1.coreErr)({
+            code: 'NOT_FOUND',
+            message: `document not found: ${id}${unreadableNote(unreadable)}${uncommittedMachineNote(root)}`,
+            ...(unreadable.length > 0 ? { details: { issues: unreadable } } : {}),
+        });
+    }
+    const path = found.path;
+    // `lstat`, which never follows a link: a symbolic link in place of the document is present even when
+    // it dangles. A live one reaches the write-side guards `commitMemoryTransition` runs (REQ-SEC-06,
+    // `bug-120`); a dangling one is refused here, because the content read below would fail on it first
+    // (task-247 review).
+    const present = isPresent((0, path_1.join)(root, path));
+    if (present && !(0, fs_1.existsSync)((0, path_1.join)(root, path))) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `refusing to ${op} ${id}: its document '${path}' is a symbolic link whose target does not exist in the working ` +
+                `tree. Restore the committed file (git restore --source=HEAD --staged --worktree -- ${path}) and retry.`,
+        });
+    }
+    if (!present) {
+        // `--source=HEAD --staged --worktree`: a plain `git restore -- <path>` restores from the index,
+        // which no longer holds the path after `git rm` or `git mv` (task-247 review).
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `refusing to ${op} ${id}: its document '${path}' is held by HEAD but deleted in the working tree. Restore it ` +
+                `(git restore --source=HEAD --staged --worktree -- ${path}) and retry.`,
+        });
     }
     const type = found.frontmatter.type;
+    if (expectedType !== undefined && type !== expectedType) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `${id}, which is of type '${String(type)}', not of type '${expectedType}': only an element of the same type can be ${op}d`,
+        });
+    }
     if (typeof type !== 'string' || memoryYaml.types[type] === undefined) {
         return (0, types_1.coreErr)({
             code: 'NOT_FOUND',
@@ -122,10 +323,66 @@ function prepareMemoryTransition(root, id, op) {
     // A missing or non-string `status` is reported as an invalid state, never as the text 'undefined'.
     const from = typeof status === 'string' ? status : String(status ?? '');
     try {
-        (0, memory_1.validateFrontmatterState)(machine, type, from, found.path);
-        const to = (0, memory_1.resolveTypeTransition)(memoryYaml, type, from, op, found.path);
-        const content = (0, storage_1.readDocument)((0, path_1.join)(root, found.path));
-        return (0, types_1.coreOk)({ memoryYaml, id, type, path: found.path, frontmatter: found.frontmatter, content, from, to });
+        (0, memory_1.validateFrontmatterState)(machine, type, from, path);
+        // `amend` moves no state (`dl-108`): its edge is the self-loop `[s → s]` in every state, so no
+        // machine lookup can refuse it. Whether the TYPE may be amended is the verb's own check.
+        const to = op === 'amend'
+            ? from
+            : op === 'supersede'
+                ? (0, memory_1.resolveSupersedeTarget)(memoryYaml, type, from, path)
+                : op === 'finalize'
+                    ? (0, memory_1.resolveWaitingTarget)(memoryYaml, type, from, path)
+                    : (0, memory_1.resolveTypeTransition)(memoryYaml, type, from, op, path);
+        // A self-loop (`amend`) enters no state, so it takes no slot. Nor does a return (`dl-156` Q2 (i),
+        // task-274): `reject` only ever takes a `gates.<from>.reject` edge and `park` only a
+        // `returns.<from>` edge (`resolveTransitionTarget`), and a reject or returns edge is exempt: the
+        // approver's verdict and a scheduling step are not capped by a capacity rule (a `bug`'s reject edges
+        // even lead forward, to `closed`). Keyed on the verb, not on the target, so an `approve` whose
+        // forward target equals the gate's reject target still takes the check. A `finalize` (task-217)
+        // enters a state like any forward move, so it takes the check too.
+        if (to !== from && op !== 'reject' && op !== 'park') {
+            const slot = requireWipSlot(root, sha, memoryYaml, type, to, id);
+            if (!slot.ok)
+                return slot;
+            // The documents the slot count could not read, if the lookup above has not already named them.
+            for (const diagnostic of slot.value) {
+                if (!unreadable.some((known) => known.file === diagnostic.file))
+                    unreadable.push(diagnostic);
+            }
+        }
+        // Content from the working tree: what `submit` and `amend` commit, and what the other verbs'
+        // unmodified-document guard compares with `HEAD`. A working-tree edit that declares a newer
+        // `format` is refused before it can be committed (task-257, `bug-241`).
+        let frontmatter;
+        try {
+            ({ frontmatter } = (0, memory_1.loadMemoryDocumentSummary)(root, path));
+        }
+        catch (error) {
+            return newerFormatRefusal(op, id, 'the working tree', error);
+        }
+        const changed = ['id', 'type'].filter((key) => frontmatter[key] !== found.frontmatter[key]);
+        if (changed.length > 0) {
+            return (0, types_1.coreErr)({
+                code: 'VALIDATION',
+                message: `refusing to ${op} ${id}: the working tree changes ${changed.map((key) => `frontmatter field '${key}'`).join(' and ')} ` +
+                    `of ${path}, which HEAD records as ${changed.map((key) => `'${String(found.frontmatter[key])}'`).join(' and ')}. ` +
+                    'A transition acts on the element the commit records; restore the recorded value, then retry.',
+            });
+        }
+        const content = (0, storage_1.readDocument)((0, path_1.join)(root, path));
+        return (0, types_1.coreOk)({
+            memoryYaml,
+            id,
+            type,
+            path,
+            frontmatter,
+            content,
+            from,
+            to,
+            sha,
+            committedFrontmatter: found.frontmatter,
+            warnings: unreadable.map(validation_1.formatDiagnostic),
+        });
     }
     catch (error) {
         if (!(error instanceof validation_1.ValidationError))
@@ -135,6 +392,148 @@ function prepareMemoryTransition(root, id, op) {
         return (0, types_1.coreErr)({ code, message, details: { issues: error.issues } });
     }
 }
+/**
+ * The sentence every WIP refusal ends with (`dl-156` Q1 (a), task-274): where the holders were counted,
+ * that a clone sees only the refs it has fetched, and where a holder recorded elsewhere is moved out.
+ */
+exports.WIP_REFS_SENTENCE = 'The holders are counted at HEAD and on every local and remote-tracking branch that changed them since it forked from HEAD, ' +
+    'so the count depends on which refs were last fetched; a holder another branch records is moved out on that branch.';
+/**
+ * Refuse to move an element into `state` when the type's machine declares a WIP limit there
+ * (`limits: { <state>: N }`, `spec-001`, `dl-110` P3 (a), task-180) and N elements of the type already
+ * hold it — `CONFLICT`, exit `1`, naming every holder in path order, before anything is written.
+ *
+ * The one shared check: {@link prepareMemoryTransitionAtRev} calls it for every transition into a new
+ * state except along a reject or `returns` edge (`submit`, `approve`, the `supersedes:` trigger, and
+ * any workflow emitter that prepares its transition there — not `reject` nor `park`, `dl-156` Q2 (i)),
+ * and `memory add` calls it for the initial state, since `add` is the verb that enters that state.
+ *
+ * **Where the holders are counted** (`dl-156` Q1 (a), task-274, as the approver ruled on 2026-10-11 at
+ * its review, option (a)): each element of the type counts in one state —
+ *
+ * - the state a ref records, when that ref **changed** the element since its merge-base with commit
+ *   `sha` (the one the transition is decided at, `dl-080`): its `status` differs from the merge-base
+ *   copy's, or the merge-base has no copy (an element added on the ref; a ref sharing no history with
+ *   `sha` counts every copy it holds). The refs are those {@link refBaselineCommits} lists for
+ *   `memory add`'s id counter (`dl-101` §2 (a)); a ref that is an ancestor of `sha` changed nothing.
+ *   When several refs changed it, the most advanced of their copies wins
+ *   ({@link isMoreAdvancedState}), the decided commit's copy not competing;
+ * - otherwise the state commit `sha` records.
+ *
+ * So a stale branch does not keep a parked holder counted, and an older copy elsewhere does not hide an
+ * element a reject moved back into the state. "Changed" compares `status`, not bytes: an edit that
+ * leaves the status alone (Execution Notes, an amend) is not a move. `exceptId`, the element being
+ * moved, is never its own holder. The refusal ends with {@link WIP_REFS_SENTENCE}. This read is wider
+ * than `HEAD`, which the `command-baseline` directive declares by name.
+ *
+ * Only the type's directory is read, every commit's listing and every distinct blob in one batch each,
+ * each blob parsed once (`loadTypeDocumentCopiesAtRevs`; task-274 review F2, the `bug-178` class);
+ * one `git merge-base` per ref. A document none of those reads can parse is not counted (task-171's
+ * tolerant scan) and is returned as a `W_MEMORY_UNREADABLE` diagnostic, once per file, which the
+ * caller's success carries as a warning and a refusal carries in `details.issues`, so a limit that may
+ * be undercounted says so. Without a declared limit nothing is read and nothing is returned.
+ */
+function requireWipSlot(root, sha, memoryYaml, type, state, exceptId) {
+    const machine = (0, memory_1.resolveStateMachine)(memoryYaml, type);
+    const limit = machine.limits?.[state];
+    if (limit === undefined)
+        return (0, types_1.coreOk)([]);
+    const decided = (0, revision_1.resolveRevision)(root, sha);
+    const refs = (0, memory_1.refBaselineCommits)(root).filter((commit) => commit !== decided);
+    const bases = (0, storage_1.mergeBasesWith)(root, decided, refs);
+    // A ref that is an ancestor of the decided commit changed nothing the decided commit lacks.
+    const moved = refs.map((ref, index) => ({ ref, base: bases[index] })).filter(({ ref, base }) => base !== ref);
+    const revs = [...new Set([decided, ...moved.map(({ ref }) => ref), ...moved.flatMap(({ base }) => (base === null ? [] : [base]))])];
+    const unreadable = [];
+    const onDiagnostic = (diagnostic) => {
+        if (!unreadable.some((known) => known.file === diagnostic.file))
+            unreadable.push(diagnostic);
+    };
+    const copiesAt = new Map();
+    (0, memory_1.loadTypeDocumentCopiesAtRevs)(root, revs, memoryYaml, type, { onDiagnostic }).forEach((copies, index) => {
+        const byKey = new Map();
+        for (const { frontmatter, path } of copies) {
+            // A copy with no string `status` holds no state, and is no move either.
+            if (typeof frontmatter.status !== 'string')
+                continue;
+            const id = frontmatter.id === undefined ? undefined : String(frontmatter.id);
+            byKey.set(id === undefined ? `path:${path}` : `id:${id}`, { name: id ?? path, path, state: frontmatter.status });
+        }
+        copiesAt.set(revs[index], byKey);
+    });
+    // The decided commit's copy, unless a ref changed the element since the fork.
+    const elements = new Map(copiesAt.get(decided));
+    const changed = new Map();
+    for (const { ref, base } of moved) {
+        const atBase = base === null ? new Map() : copiesAt.get(base);
+        for (const [key, copy] of copiesAt.get(ref)) {
+            if (atBase.get(key)?.state === copy.state)
+                continue;
+            const known = changed.get(key);
+            if (known === undefined || isMoreAdvancedState(machine, copy.state, known.state))
+                changed.set(key, copy);
+        }
+    }
+    for (const [key, copy] of changed)
+        elements.set(key, copy);
+    // Path order, then the element key (unique), as one string each: the default sort is by UTF-16 code
+    // units, independent of locale and of the order the commits were read in (REQ-SYS-07).
+    const named = new Map();
+    for (const [key, element] of elements) {
+        if (element.state === state && element.name !== exceptId)
+            named.set(`${element.path}\u0000${key}`, element.name);
+    }
+    const holders = [...named.keys()].sort().map((order) => named.get(order));
+    if (holders.length < limit)
+        return (0, types_1.coreOk)(unreadable);
+    return (0, types_1.coreErr)({
+        code: 'CONFLICT',
+        message: `WIP limit reached for '${state}' on type '${type}' (limit ${limit}): held by ${holders.join(', ')}. ` +
+            `Move one of them out of '${state}', then retry. ${exports.WIP_REFS_SENTENCE}`,
+        ...(unreadable.length > 0 ? { details: { issues: unreadable } } : {}),
+    });
+}
+/**
+ * Whether state `a` is further along `machine` than state `b` — the rule that picks the one state an
+ * element counts in when the refs disagree (`dl-156` Q1 (a): "the most advanced state wins"). A
+ * `sequence` state ranks by its position; a state outside `sequence` (an off-chain `gates` reject
+ * target, `deprecated`, or a value the machine does not declare) ranks after every `sequence` state,
+ * since the element has left the chain, and `deprecated` ranks last of all. Equal ranks are ordered by
+ * name, so the answer never depends on the order the commits were read in (REQ-SYS-07). Pure.
+ */
+function isMoreAdvancedState(machine, a, b) {
+    const rank = (state) => {
+        if (state === memory_1.DEPRECATED_STATE)
+            return machine.sequence.length + 1;
+        const index = machine.sequence.indexOf(state);
+        return index === -1 ? machine.sequence.length : index;
+    };
+    const ra = rank(a);
+    const rb = rank(b);
+    return ra !== rb ? ra > rb : a > b;
+}
+/**
+ * The shared preamble of every state-moving `memory` verb — `submit`, `approve`, `reject`,
+ * `deprecate`, `amend` — written once (task-132, `bug-142`): resolve the git identity
+ * (`requireGitIdentity`, REQ-SEC-01, exit `1`), then locate the document and resolve verb `op` on it
+ * ({@link prepareMemoryTransition}, exit `1`). The first refusal is returned unchanged; nothing is
+ * written either way.
+ *
+ * The identity is read here ONCE and rides the result, so no verb reads it again (the structural test
+ * `test/core/memory-transition-preamble.test.ts` holds every registered transition verb to that).
+ * The order matches `spec-006` §7: a verb's usage checks run before it calls this (task-125,
+ * `bug-172`), and an approver-gated verb's authority check runs after it, because that check's
+ * message names the document's type, which only this step knows.
+ */
+function beginMemoryTransition(root, id, op) {
+    const identity = (0, git_identity_1.requireGitIdentity)(root);
+    if (!identity.ok)
+        return identity;
+    const prepared = prepareMemoryTransition(root, id, op);
+    if (!prepared.ok)
+        return prepared;
+    return (0, types_1.coreOk)({ ...prepared.value, identity: identity.value });
+}
 /**
  * Refuse, before anything is written, a document that already carries modifications this transition
  * does not own (task-088, `bug-076`; AC2 option (b)).
@@ -148,10 +547,10 @@ function prepareMemoryTransition(root, id, op) {
  *
  * **Why refusing rather than committing only the status hunk.** Partial staging is undefined here
  * before it is difficult: there are two candidate baselines on disk (the index and the working tree)
- * and they can disagree, so "only the status hunk" does not say onto which text. Worse, the verb reads
- * `status` itself from the working tree, so a hand-edited-but-uncommitted `status` would have the
- * commit record `draft → approved` under a subject declaring `pending → approved` — the audit trail
- * asserting something that did not happen, which is the defect, not a fix for it. And the edits a
+ * and they can disagree, so "only the status hunk" does not say onto which text. Worse, a
+ * hand-edited-but-uncommitted `status` riding along would have the commit record `draft → approved`
+ * under a subject declaring `pending → approved` (the subject's `from` is `HEAD`'s since task-247) —
+ * the audit trail asserting something that did not happen, which is the defect, not a fix for it. And the edits a
  * partial commit left behind would be invisible, deferred, and swept into whatever commits next. A
  * refusal costs the user two commands, now, on a document this function has provably not touched.
  *
@@ -193,11 +592,41 @@ function verifyCommittedScope(root, sha, path, expected, scope) {
         return [...problems, `it does not contain '${path}'`];
     return [...problems, ...(0, memory_1.verifyDocumentEdit)((0, storage_1.readPathAtRev)(root, parent, path) ?? '', after, expected, scope)];
 }
+/**
+ * The pre-write half of {@link commitMemoryTransition} — its checks 1 to 3 (confinement, an
+ * unmodified working tree under `declared-fields-only` or no divergent stage under
+ * `carries-content`, and the rendering's post-condition), with nothing written. A command that makes
+ * more than one commit runs it on every document first, so a refusal of any of them leaves the
+ * repository as it was (the `supersedes:` trigger, task-162). {@link commitMemoryTransition} runs it
+ * again before its own write, so calling it first is never required for safety.
+ */
+function checkMemoryTransition(root, prepared, content, expected = {}, scope = 'declared-fields-only') {
+    const owned = { status: prepared.to, ...expected };
+    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, prepared.path, 'write');
+    if (!confined.ok)
+        return confined;
+    const unmodified = scope === 'declared-fields-only'
+        ? requireUnmodifiedDocument(root, prepared)
+        : (0, write_guard_1.requireNoDivergentStage)(root, prepared.path, TRANSITION_CONTRACT);
+    if (!unmodified.ok)
+        return unmodified;
+    const problems = (0, memory_1.verifyDocumentEdit)(prepared.content, content, owned, 'declared-fields-only');
+    if (problems.length > 0) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `refusing to write ${prepared.path}: the rendered document failed its post-condition: ${problems.join('; ')}`,
+        });
+    }
+    return (0, types_1.coreOk)(undefined);
+}
 /**
  * Write `content` over the prepared document and commit exactly that one path with `message`,
  * returning the new commit's sha (`commitPaths`, task-018; scoped to that path even when other changes
- * are staged, bug-027). Callers must have run the git-identity pre-flight (REQ-SEC-01) and every refusal
- * check first; this step is the only write.
+ * are staged, bug-027). The commit's author is pinned to `prepared.identity` — the identity the
+ * pre-flight checked, and the one any `Approver:` line names — so git's own author resolution cannot
+ * substitute another (task-132, `bug-149`). `prepared` comes from {@link beginMemoryTransition}, which
+ * is how the git-identity pre-flight (REQ-SEC-01) is guaranteed to have run; callers run every other
+ * refusal check first, and this step is the only write.
  *
  * Four checks bound what reaches the repository, in this order — they are not redundant, they catch
  * different defects:
@@ -216,7 +645,10 @@ function verifyCommittedScope(root, sha, path, expected, scope) {
  *    --porcelain` reports a path beyond a symbolic link as clean, which is `bug-118`).
  * 2. **The working tree is unmodified** ({@link requireUnmodifiedDocument}, `declared-fields-only`
  *    only) — catches a wrong *baseline*: content that was already on disk before the verb ran
- *    (`bug-076`).
+ *    (`bug-076`). Under `carries-content` the working tree IS the content, so the check narrows to
+ *    `requireNoDivergentStage`: a staged version differing from both `HEAD` and the working tree,
+ *    which `git add` would silently discard, is refused (task-131, `bug-182`). Both shapes first
+ *    refuse a document behind a symlinked directory, which git cannot report on (`bug-118`).
  * 3. **The rendering is in scope** ({@link verifyDocumentEdit} against the prepared document) —
  *    catches a defect in the *editor*: `status` must be the prepared target, every field in `expected`
  *    must have its value (`undefined` = absent), and no other field and no byte of the body may have
@@ -229,34 +661,23 @@ function verifyCommittedScope(root, sha, path, expected, scope) {
  * Checks 1–3 report a `VALIDATION` error (exit 1) with nothing written or committed. Check 4 can
  * only report; see {@link verifyCommittedScope}.
  *
- * Check 1 resolves on the **working tree**, not at `HEAD`, which departs from `command-baseline`'s
- * rule for a gating read. The argument is `task-102`'s, recorded in
- * `dl-086-a-guard-over-a-filesystem-effect-resolves-on-the-filesystem` (`in-discussion`) and cited
- * rather than re-made: it predicts where `writeDocument` will land, and that follows the symlinks on
- * disk rather than the ones a commit records.
+ * Check 1 resolves on the **working tree**, not at `HEAD`: it is the filesystem-effect read
+ * `command-baseline` and `spec-006-core-domain-api` §6 declare, ratified in
+ * `dl-086-a-guard-over-a-filesystem-effect-resolves-on-the-filesystem` from `task-102`'s argument,
+ * which is cited rather than re-made: it predicts where `writeDocument` will land, and that follows
+ * the symlinks on disk rather than the ones a commit records.
  *
  * @param scope - How much of the document this operation owns; defaults to the strict
  *   `declared-fields-only`, so a new verb is guarded unless it opts out deliberately.
+ * @param warnings - The success warnings the verb will report, handed to the commit primitive so a dry
+ *   run carries them (task-210 review, F4); defaults to the lookup's own, `prepared.warnings`.
  */
-function commitMemoryTransition(root, prepared, content, message, expected = {}, scope = 'declared-fields-only') {
+function commitMemoryTransition(root, prepared, content, message, expected = {}, scope = 'declared-fields-only', warnings = prepared.warnings) {
+    const checked = checkMemoryTransition(root, prepared, content, expected, scope);
+    if (!checked.ok)
+        return checked;
     const owned = { status: prepared.to, ...expected };
-    const confined = (0, confinement_1.requireConfinedWriteTarget)(root, prepared.path, 'write');
-    if (!confined.ok)
-        return confined;
-    if (scope === 'declared-fields-only') {
-        const unmodified = requireUnmodifiedDocument(root, prepared);
-        if (!unmodified.ok)
-            return unmodified;
-    }
-    const problems = (0, memory_1.verifyDocumentEdit)(prepared.content, content, owned, 'declared-fields-only');
-    if (problems.length > 0) {
-        return (0, types_1.coreErr)({
-            code: 'VALIDATION',
-            message: `refusing to write ${prepared.path}: the rendered document failed its post-condition: ${problems.join('; ')}`,
-        });
-    }
-    (0, storage_1.writeDocument)((0, path_1.join)(root, prepared.path), content);
-    const sha = (0, storage_1.commitPaths)(root, [prepared.path], message);
+    const sha = (0, storage_1.writeAndCommit)(root, [{ path: prepared.path, content }], message, { author: prepared.identity, warnings });
     const leaked = verifyCommittedScope(root, sha, prepared.path, owned, scope);
     if (leaked.length > 0) {
         return (0, types_1.coreErr)({