wingfoil 0.2.2 → 0.3.0

package/dist/core/memory-supersede.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPERSEDES_FIELD = void 0;
+exports.prepareSupersede = prepareSupersede;
+exports.supersedeReason = supersedeReason;
+/**
+ * The `supersedes:` engine trigger (task-162; `dl-065` Q1.1; `spec-001` § `StateMachine`, `spec-010`
+ * § Field-write ownership, `spec-008` §2's `finalize` row).
+ *
+ * `superseded` is the last state of the `adr` and `tech-spec` machines, behind a `waiting` state, so
+ * no verb drives the edge into it. It fires when an element whose `supersedes:` names another element
+ * of its type is **approved into** that `waiting` state: `memory approve adr-B` (`pending → accepted`)
+ * moves the `adr-A` that `adr-B`'s `supersedes:` names `accepted → superseded`.
+ *
+ * The move is its own commit, because `memory history` reads a document's record by its path: one
+ * commit moving both documents under the `approve` subject would put an approval, with the approver's
+ * identity and the wrong bracket, into `adr-A`'s history. The engine-driven `set_state` into the last
+ * state of a `sequence` emits `finalize` (`spec-008` §2), so the commit is
+ * `wf({type}): finalize {A} [{state} → superseded]`, with no `Approver:` line (the decision is the
+ * approve's) and a `Reason:` that names the superseding element and cites the approve commit.
+ *
+ * The decision is taken at `HEAD`, at the same sha the approve was decided at: the `supersedes:` value
+ * as that commit records it, the named element's type and `status` as that commit records them
+ * (task-247, `command-baseline` 1.4). Every refusal is returned before either commit is written.
+ */
+const memory_1 = require("../memory");
+const memory_transition_1 = require("./memory-transition");
+const types_1 = require("./types");
+/** The frontmatter field that names the element an approval supersedes (`spec-010`). */
+exports.SUPERSEDES_FIELD = 'supersedes';
+/**
+ * Resolve the `supersedes:` trigger for an approval already prepared and authorized: `null` when it
+ * does not fire, the superseded element's prepared transition when it does, or a refusal.
+ *
+ * It fires only when the approve's target is a `waiting` state whose forward edge leads to
+ * `superseded` ({@link supersedesEdgeFrom}) and the approved element's committed `supersedes:` is a
+ * non-empty string. On any other approval the field is not read: a type without that edge has nothing
+ * for it to trigger. Refusals (exit `1`), each worded `cannot approve <B>: its supersedes: field names
+ * …`:
+ *
+ * - a value that is not a string → `VALIDATION`;
+ * - no element at `HEAD` carries that id → `NOT_FOUND`;
+ * - an element of another type → `VALIDATION`;
+ * - an element not in the approve's target state, the approved element itself included (it is in its
+ *   gate state at `HEAD`) → `INVALID_TRANSITION`, `illegal transition <s> -> superseded for type '<t>'`;
+ * - every working-tree refusal a transition target meets (`prepareMemoryTransitionAtRev`).
+ *
+ * The caller still runs `checkMemoryTransition` on the result before writing anything, which adds the
+ * unmodified-document and confinement guards.
+ */
+function prepareSupersede(root, approved) {
+    const machine = (0, memory_1.resolveStateMachine)(approved.memoryYaml, approved.type);
+    if (!(0, memory_1.supersedesEdgeFrom)(machine, approved.to))
+        return (0, types_1.coreOk)(null);
+    const value = approved.committedFrontmatter[exports.SUPERSEDES_FIELD];
+    if (value === undefined || value === null || (typeof value === 'string' && value.trim() === ''))
+        return (0, types_1.coreOk)(null);
+    const prefix = `cannot approve ${approved.id}: its ${exports.SUPERSEDES_FIELD}: field names `;
+    if (typeof value !== 'string') {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `${prefix}${JSON.stringify(value)}, but it must be a single element id (a string)`,
+        });
+    }
+    const target = value.trim();
+    const prepared = (0, memory_transition_1.prepareMemoryTransitionAtRev)(root, approved.sha, approved.memoryYaml, target, 'supersede', approved.type);
+    if (!prepared.ok) {
+        const message = prepared.error.message.startsWith(`${target},`)
+            ? `${prefix}${prepared.error.message}`
+            : `${prefix}${target}, which cannot be superseded: ${prepared.error.message}`;
+        return (0, types_1.coreErr)({ ...prepared.error, message });
+    }
+    return (0, types_1.coreOk)({ ...prepared.value, identity: approved.identity });
+}
+/** The `Reason:` of the trigger's `finalize` commit: what superseded the element, and where it was approved. */
+function supersedeReason(approvedId, approveSha) {
+    return `superseded by ${approvedId} (its ${exports.SUPERSEDES_FIELD}: field), approved in ${approveSha}.`;
+}
+//# sourceMappingURL=memory-supersede.js.map

package/dist/core/memory-supersede.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-supersede.js","sourceRoot":"","sources":["../../src/core/memory-supersede.ts"],"names":[],"mappings":";;;AAgDA,4CA0BC;AAGD,0CAEC;AA/ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sCAAoE;AAEpE,2DAA+F;AAC/F,mCAA2D;AAE3D,wFAAwF;AAC3E,QAAA,gBAAgB,GAAG,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAgB,gBAAgB,CAC9B,IAAY,EACZ,QAA+B;IAE/B,MAAM,OAAO,GAAG,IAAA,4BAAmB,EAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IACxE,IAAI,CAAC,IAAA,2BAAkB,EAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,IAAA,cAAM,EAAC,IAAI,CAAC,CAAC;IAEnE,MAAM,KAAK,GAAG,QAAQ,CAAC,oBAAoB,CAAC,wBAAgB,CAAC,CAAC;IAC9D,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;QAAE,OAAO,IAAA,cAAM,EAAC,IAAI,CAAC,CAAC;IAErH,MAAM,MAAM,GAAG,kBAAkB,QAAQ,CAAC,EAAE,SAAS,wBAAgB,gBAAgB,CAAC;IACtF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAO,EAAC;YACb,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,iDAAiD;SAC5F,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,IAAA,gDAA4B,EAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3H,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC;YAC7D,CAAC,CAAC,GAAG,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE;YACtC,CAAC,CAAC,GAAG,MAAM,GAAG,MAAM,iCAAiC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAChF,OAAO,IAAA,eAAO,EAAC,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,IAAA,cAAM,EAAC,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,gHAAgH;AAChH,SAAgB,eAAe,CAAC,UAAkB,EAAE,UAAkB;IACpE,OAAO,iBAAiB,UAAU,SAAS,wBAAgB,yBAAyB,UAAU,GAAG,CAAC;AACpG,CAAC"}

package/dist/core/memory-transition.d.ts

@@ -1,4 +1,6 @@
-import type { DocumentScope, MemoryYaml, TransitionOp } from '../memory';
+import type { DocumentScope, MemoryYaml, StateMachine, TransitionOp } from '../memory';
+import { type Diagnostic } from '../validation';
+import { type GitIdentity } from './git-identity';
 import { type CoreResult } from './types';
 /** A document located and cleared for one transition — everything the verb needs to finish it. */
 export interface PreparedMemoryTransition {
@@ -14,41 +16,182 @@ export interface PreparedMemoryTransition {
     readonly type: string;
     /** Root-relative POSIX path of the document. */
     readonly path: string;
-    /** The document's parsed frontmatter as read (not schema-validated). */
+    /**
+     * The document's parsed frontmatter **in the working tree** (not schema-validated) — the content a
+     * verb checks and commits. Its `id` and `type` equal `HEAD`'s; its `status` may not, and never
+     * decides anything: `from` is the committed one (task-247).
+     */
     readonly frontmatter: Readonly<Record<string, unknown>>;
-    /** The full current file content, the base for the verb's edit. */
+    /** The full working-tree file content, the base for the verb's edit. */
     readonly content: string;
     readonly from: string;
     readonly to: string;
+    /**
+     * The commit `HEAD` resolved to when this transition was decided — the one sha the machine, the
+     * document and `from` were read at. A follow-up decision in the same command (the `supersedes:`
+     * trigger, task-162) reads at this sha too, so the two cannot come from two commits.
+     */
+    readonly sha: string;
+    /**
+     * The document's frontmatter **as `HEAD` records it** — the copy a decision reads (task-247,
+     * `command-baseline` 1.4), where {@link frontmatter} is the working tree's content to commit.
+     */
+    readonly committedFrontmatter: Readonly<Record<string, unknown>>;
+    /**
+     * The committed documents the lookup could not read on its way to this one (task-171, `bug-031`), as
+     * `W_MEMORY_UNREADABLE` warning lines (`formatDiagnostic`). A verb's success carries them.
+     */
+    readonly warnings: readonly string[];
 }
 /**
- * Locate document `id` and resolve verb `op` on it, **against the `memory.yaml` committed at
- * `HEAD`** (`loadMemoryYamlAtHead`).
+ * What a transition is resolved for: a verb, `amend` (the self-loop of the current state, task-127),
+ * or `supersede` — the `supersedes:` engine trigger, which is not a verb and whose only target is
+ * `superseded` (`resolveSupersedeTarget`, task-162).; or `finalize` — the forward `waiting` edge no verb drives,
+ * which `workflow end` takes to close a plan, `active → done` (`resolveWaitingTarget`, task-217).
+ */
+export type TransitionResolution = TransitionOp | 'amend' | 'supersede' | 'finalize';
+/**
+ * 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 unknown-type, invalid-state and illegal-transition refusals keep their pinned messages
+ * verbatim as the first sentence; {@link uncommittedMachineNote} may append a second one.
+ */
+export declare function prepareMemoryTransition(root: string, id: string, op: TransitionOp | 'amend' | 'finalize'): CoreResult<PreparedMemoryTransition>;
+/**
+ * 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.
  *
- * The last four keep their pinned messages verbatim as the first sentence;
- * {@link uncommittedMachineNote} may append a second one.
+ * 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.
  */
-export declare function prepareMemoryTransition(root: string, id: string, op: TransitionOp): CoreResult<PreparedMemoryTransition>;
+export declare function prepareMemoryTransitionAtRev(root: string, sha: string, memoryYaml: MemoryYaml, id: string, op: TransitionResolution, expectedType?: string): CoreResult<PreparedMemoryTransition>;
+/**
+ * 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.
+ */
+export declare const WIP_REFS_SENTENCE: string;
+/**
+ * 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.
+ */
+export declare function requireWipSlot(root: string, sha: string, memoryYaml: MemoryYaml, type: string, state: string, exceptId?: string): CoreResult<readonly Diagnostic[]>;
+/**
+ * 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.
+ */
+export declare function isMoreAdvancedState(machine: StateMachine, a: string, b: string): boolean;
+/**
+ * A {@link PreparedMemoryTransition} together with the git identity that will carry it out — the
+ * result of {@link beginMemoryTransition}, and the only thing {@link commitMemoryTransition} accepts,
+ * so a transition cannot be committed under an identity other than the one its pre-flight checked.
+ */
+export interface BegunMemoryTransition extends PreparedMemoryTransition {
+    /**
+     * The identity `requireGitIdentity` resolved and validated (REQ-SEC-01). The one "who" of the whole
+     * operation: the authority check takes it (REQ-SEC-03), the `Approver:` line is built from it, and
+     * {@link commitMemoryTransition} pins it as the commit's `--author` (`dl-064` B.1, task-132,
+     * `bug-149`).
+     */
+    readonly identity: GitIdentity;
+}
+/**
+ * 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.
+ */
+export declare function beginMemoryTransition(root: string, id: string, op: TransitionOp | 'amend' | 'finalize'): CoreResult<BegunMemoryTransition>;
 /**
  * Verify what the new commit **contains**, by diffing it against its own parent (task-088, AC3).
  *
@@ -62,11 +205,23 @@ export declare function prepareMemoryTransition(root: string, id: string, op: Tr
  * {@link requireUnmodifiedDocument} in place it should be unreachable, which is the point.
  */
 export declare function verifyCommittedScope(root: string, sha: string, path: string, expected: Readonly<Record<string, string | undefined>>, scope: DocumentScope): string[];
+/**
+ * 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.
+ */
+export declare function checkMemoryTransition(root: string, prepared: PreparedMemoryTransition, content: string, expected?: Readonly<Record<string, string | undefined>>, scope?: DocumentScope): CoreResult<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:
@@ -85,7 +240,10 @@ export declare function verifyCommittedScope(root: string, sha: string, path: st
  *    --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
@@ -98,14 +256,16 @@ export declare function verifyCommittedScope(root: string, sha: string, path: st
  * 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`.
  */
-export declare function commitMemoryTransition(root: string, prepared: PreparedMemoryTransition, content: string, message: string, expected?: Readonly<Record<string, string | undefined>>, scope?: DocumentScope): CoreResult<string>;
+export declare function commitMemoryTransition(root: string, prepared: BegunMemoryTransition, content: string, message: string, expected?: Readonly<Record<string, string | undefined>>, scope?: DocumentScope, warnings?: readonly string[]): CoreResult<string>;
 //# sourceMappingURL=memory-transition.d.ts.map

package/dist/core/memory-transition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-transition.d.ts","sourceRoot":"","sources":["../../src/core/memory-transition.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAgB,YAAY,EAAE,MAAM,WAAW,CAAC;AAMvF,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAG3D,kGAAkG;AAClG,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,GAAG,UAAU,CAAC,wBAAwB,CAAC,CA2DxH;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACtD,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAQV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAM,EAC3D,KAAK,GAAE,aAAsC,GAC5C,UAAU,CAAC,MAAM,CAAC,CA2BpB"}
+{"version":3,"file":"memory-transition.d.ts","sourceRoot":"","sources":["../../src/core/memory-transition.ts"],"names":[],"mappings":"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"}