@opengsd/gsd-core 1.16.0 → 1.17.0

package/gsd-core/bin/lib/state.cjs

@@ -4513,7 +4513,98 @@ function computeChangedFrontmatterFields(snapshotFm, persistedFm, bodyDeltas) {
  *   (#3818's own direction), which is why keeping it as the candidate
  *   source was rejected (design doc, Rejected #1).
  */
-function reconcileReportedFields(statePath, preWriteState, reported, divergedFields) {
+/**
+ * ADR-4629 §8.2 (epic #4629, C2): the value a reported/asserted target
+ * resolves to in one document side. Lifted verbatim out of
+ * `reconcileReportedFields` (it was the private `valueOf` closure) so the C2
+ * verifying executor reads a target through the SAME resolution chain the
+ * measured-delta reporter uses — ADR-4629 Decision 4: extend the reporter,
+ * never build a second one.
+ *
+ * #3471 review (unchanged): body-FIRST, frontmatter-key-FLAT-fallback,
+ * dotted-PATH-fallback last. Body-first mirrors the actual write precedence
+ * `patchCore`/`updateCore` apply (#1162's fix — a lowercase body label that
+ * happens to case-exact-match a frontmatter key must still resolve against
+ * the body). `field` a literal flat key (even one containing a `.`) is tried
+ * before it is split and walked as a dotted path (test matrix row 26) —
+ * `resolveFrontmatterPath` pins that same order for the frontmatter side.
+ *
+ * `Current Position` is special-cased: it names the WHOLE `## Current
+ * Position` section, not a single `Label: value` line, so `stateExtractField`
+ * can never resolve it (the root cause of the "Current Position undercount" —
+ * a transform could correctly push `'Current Position'` into its own
+ * `updated` list and it was still silently dropped, because both sides
+ * resolved to `null` and `null === null` failed the old `intended !== null`
+ * guard). `sliceCurrentPositionSection` is the existing fence-aware section
+ * locator (state-transition.cts) — reused rather than re-derived.
+ *
+ * C2 generalizes that special case: a name in `sectionTargets` (a declared
+ * `target: 'section'` assertion) resolves to its whole section body through
+ * the markdown-sectionizer seam (ADR-1372), never a hand-rolled regex.
+ * Existing callers pass no `sectionTargets` and resolve exactly as before.
+ */
+function readStateTarget(fm, body, field, sectionTargets) {
+    if (field === 'Current Position') {
+        const section = stateTransitionMod.sliceCurrentPositionSection(body);
+        return section !== null ? section.trim() : null;
+    }
+    if (sectionTargets.has(field)) {
+        const section = (0, markdown_sectionizer_cjs_1.collectSection)(body, (h) => h.text === field);
+        return section !== null ? section.body.trim() : null;
+    }
+    const bodyValue = (0, state_document_cjs_1.stateExtractField)(body, field);
+    if (bodyValue !== null)
+        return bodyValue;
+    if (Object.prototype.hasOwnProperty.call(fm, field))
+        return String(fm[field]);
+    if (field.includes('.')) {
+        const resolved = resolveFrontmatterPath(fm, field);
+        if (resolved !== STATE_FIELD_ABSENT) {
+            return stateScalarString(resolved);
+        }
+    }
+    return null;
+}
+const NO_SECTION_TARGETS = new Set();
+/**
+ * ADR-4629 §8.2 (C2): did this target measurably change between the two
+ * document sides? Lifted verbatim out of `reconcileReportedFields` (the private
+ * `changed` closure) for the same one-rule reason as `readStateTarget`.
+ *
+ * A target can itself be a declared derived leaf (e.g. `plannedPhaseCore`
+ * pushing `'progress.total_plans'` — state-transition.cts). `readStateTarget`'s
+ * null-vs-string convention cannot tell "absent from the frontmatter" apart
+ * from "resolved to the literal string 'null'/''", so it cannot carry the same
+ * materialization rule `computeChangedFrontmatterFields` applies. Those targets
+ * route through the SAME primitives (`resolveFrontmatterPath` + the
+ * `STATE_FIELD_ABSENT` sentinel + `stateFieldValuesDiffer`) instead of a
+ * second, parallel absence convention — one rule, reused, not duplicated.
+ */
+function stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets) {
+    const isDeclaredDerivedLeaf = field.includes('.') && Object.prototype.hasOwnProperty.call(FIELD_CLASSIFICATION, field);
+    if (isDeclaredDerivedLeaf && !sectionTargets.has(field)) {
+        const before = resolveFrontmatterPath(snapshotFm, field);
+        const after = resolveFrontmatterPath(persistedFm, field);
+        // Same generalized provenance rule as computeChangedFrontmatterFields:
+        // absent-in-snapshot-materializing-in-persisted is the disk scan
+        // catching a never-synced document up, not this write's own action.
+        if (before === STATE_FIELD_ABSENT && after !== STATE_FIELD_ABSENT)
+            return false;
+        return stateFieldValuesDiffer(before, after);
+    }
+    const before = readStateTarget(snapshotFm, snapshotBody, field, sectionTargets);
+    const after = readStateTarget(persistedFm, persistedBody, field, sectionTargets);
+    if (before === null && after === null)
+        return false;
+    if (before === null || after === null)
+        return true;
+    return before.trim() !== after.trim();
+}
+function reconcileReportedFields(statePath, preWriteState, reported, divergedFields, 
+// ADR-4629 §8.2 / Decision 4 (C2): names in `reported` that are declared
+// `target: 'section'` assertions, measured as whole-section deltas. Omitted
+// by every pre-C2 caller, whose output is unchanged.
+sectionTargets = NO_SECTION_TARGETS) {
     void divergedFields; // ADR-3473 §8.7 D18: out-param only, not a candidate source here.
     if (preWriteState.fm === undefined || preWriteState.body === undefined)
         return [];
@@ -4522,71 +4613,7 @@ function reconcileReportedFields(statePath, preWriteState, reported, divergedFie
     const persistedBody = stripFrontmatter(persisted);
     const snapshotFm = preWriteState.fm;
     const snapshotBody = preWriteState.body;
-    // #3471 review (unchanged by this rewrite): body-FIRST, frontmatter-key-
-    // FLAT-fallback, dotted-PATH-fallback last. Body-first mirrors the actual
-    // write precedence `patchCore`/`updateCore` apply (#1162's fix — a
-    // lowercase body label that happens to case-exact-match a frontmatter key
-    // must still resolve against the body). `field` a literal flat key (even
-    // one containing a `.`) is tried before it is split and walked as a
-    // dotted path (test matrix row 26) — `resolveFrontmatterPath` pins that
-    // same order for the frontmatter side alone.
-    //
-    // `Current Position` is special-cased: it names the WHOLE `## Current
-    // Position` section, not a single `Label: value` line, so
-    // `stateExtractField` can never resolve it (this is the root cause of the
-    // "Current Position undercount" — a transform can correctly push
-    // `'Current Position'` into its own `updated` list, and this function
-    // still silently dropped it, because `valueOf` returned `null` for BOTH
-    // sides and `null === null` failed the old `intended !== null` guard).
-    // `sliceCurrentPositionSection` is the existing fence-aware section
-    // locator (state-transition.cts) — reused rather than re-derived.
-    const valueOf = (fm, body, field) => {
-        if (field === 'Current Position') {
-            const section = stateTransitionMod.sliceCurrentPositionSection(body);
-            return section !== null ? section.trim() : null;
-        }
-        const bodyValue = (0, state_document_cjs_1.stateExtractField)(body, field);
-        if (bodyValue !== null)
-            return bodyValue;
-        if (Object.prototype.hasOwnProperty.call(fm, field))
-            return String(fm[field]);
-        if (field.includes('.')) {
-            const resolved = resolveFrontmatterPath(fm, field);
-            if (resolved !== STATE_FIELD_ABSENT) {
-                return stateScalarString(resolved);
-            }
-        }
-        return null;
-    };
-    // A field in `reported` can itself be a declared derived leaf (e.g.
-    // `plannedPhaseCore` pushing `'progress.total_plans'` — state-
-    // transition.cts:1752). `valueOf`'s null-vs-string convention cannot tell
-    // "absent from the frontmatter" apart from "resolved to the literal string
-    // 'null'/''", so it cannot carry the same materialization rule
-    // `computeChangedFrontmatterFields` applies below. Route these fields
-    // through the SAME primitives (`resolveFrontmatterPath` + the
-    // `STATE_FIELD_ABSENT` sentinel + `stateFieldValuesDiffer`) instead of a
-    // second, parallel absence convention — one rule, reused, not duplicated.
-    const isDeclaredDerivedLeaf = (candidate) => candidate.includes('.') && Object.prototype.hasOwnProperty.call(FIELD_CLASSIFICATION, candidate);
-    const changed = (field) => {
-        if (isDeclaredDerivedLeaf(field)) {
-            const before = resolveFrontmatterPath(snapshotFm, field);
-            const after = resolveFrontmatterPath(persistedFm, field);
-            // Same generalized provenance rule as computeChangedFrontmatterFields:
-            // absent-in-snapshot-materializing-in-persisted is the disk scan
-            // catching a never-synced document up, not this write's own action.
-            if (before === STATE_FIELD_ABSENT && after !== STATE_FIELD_ABSENT)
-                return false;
-            return stateFieldValuesDiffer(before, after);
-        }
-        const before = valueOf(snapshotFm, snapshotBody, field);
-        const after = valueOf(persistedFm, persistedBody, field);
-        if (before === null && after === null)
-            return false;
-        if (before === null || after === null)
-            return true;
-        return before.trim() !== after.trim();
-    };
+    const changed = (field) => stateTargetChanged(snapshotFm, snapshotBody, persistedFm, persistedBody, field, sectionTargets);
     // Candidate set = `reported` ∪ every frontmatter key (dotted-leaf
     // granularity) whose persisted value differs from the snapshot, minus the
     // provenance exclusion. A frontmatter-diff-discovered field is mapped
@@ -4614,6 +4641,361 @@ function reconcileReportedFields(statePath, preWriteState, reported, divergedFie
     }
     return reconciled;
 }
+/** Why a verified write failed. A closed set, frozen like `ERROR_REASON`. */
+const STATE_WRITE_INTENT_FAILURE = Object.freeze({
+    /** §8.3: the delta reached a region outside the declared scope. */
+    OUT_OF_SCOPE: 'out_of_scope',
+    /** §8.2: a `required` assertion did not land. */
+    REQUIRED_ASSERTION_MISSED: 'required_assertion_missed',
+    /** §8.2: the re-read file is not the content that was verified and written. */
+    REREAD_MISMATCH: 'reread_mismatch',
+});
+/**
+ * Split a STATE.md body into leaf units for the §8.3 diff: the preamble before
+ * the first heading, then one unit per heading running to the NEXT heading of
+ * any level, in document order. Leaf granularity means a declared
+ * `## Accumulated Context` scope reaches its `### Decisions` child by heading
+ * level (`stateSectionScopeUnits`), while an undeclared sibling section stays a separate unit. Built on
+ * the markdown-sectionizer seam (ADR-1372), which is fence-aware, so a `#` line
+ * inside a code fence is not a heading. A repeated heading gets an occurrence
+ * suffix so neither shadows the other.
+ */
+function collectStateBodyUnits(body) {
+    const units = new Map();
+    const sections = (0, markdown_sectionizer_cjs_1.collectSections)(body, () => true);
+    const preambleEnd = sections.length > 0 ? sections[0].heading.offset : body.length;
+    units.set('(preamble)', { text: body.slice(0, preambleEnd).trim(), level: 0, region: { region: 'preamble', name: '' } });
+    const occurrences = new Map();
+    for (const section of sections) {
+        const { heading } = section;
+        const base = `${'#'.repeat(heading.level)} ${heading.text}`;
+        const n = (occurrences.get(base) ?? 0) + 1;
+        occurrences.set(base, n);
+        units.set(n === 1 ? base : `${base} (#${n})`, {
+            text: section.body.trim(),
+            level: heading.level,
+            region: { region: 'section', name: heading.text },
+        });
+    }
+    return units;
+}
+/** The raw frontmatter region (everything before the body), for the unparseable-block case. */
+function stateFrontmatterRegion(content) {
+    return content.slice(0, content.length - stripFrontmatter(content).length);
+}
+/**
+ * The unit a declared field lives in: the first unit, in document order, where
+ * `stateExtractField` resolves it. That mirrors `stateExtractField`'s own
+ * first-match reading of the whole body, so a declared `Status` covers the one
+ * line the seam treats as `Status`, and not a second `Status:` line elsewhere.
+ */
+function stateFieldOwnerUnit(units, field) {
+    for (const [key, unit] of units) {
+        if ((0, state_document_cjs_1.stateExtractField)(unit.text, field) !== null)
+            return key;
+    }
+    return null;
+}
+/**
+ * The units a declared section covers: the FIRST unit, in document order, whose
+ * heading text is the declared name (the occurrence `readStateTarget` reads,
+ * through `collectSection`'s first match), plus every following unit nested
+ * under it by heading level. The section analogue of `stateFieldOwnerUnit`: a
+ * repeated heading of the same name, and that occurrence's children, are not
+ * covered, even though they sit under a heading with the same text.
+ */
+function stateSectionScopeUnits(units, sectionTargets) {
+    const covered = new Set();
+    const entries = [...units];
+    for (const name of sectionTargets) {
+        const start = entries.findIndex(([, u]) => u.region.region === 'section' && u.region.name === name);
+        if (start < 0)
+            continue;
+        const ownerLevel = entries[start][1].level;
+        covered.add(entries[start][0]);
+        for (let i = start + 1; i < entries.length && entries[i][1].level > ownerLevel; i++)
+            covered.add(entries[i][0]);
+    }
+    return covered;
+}
+/**
+ * ADR-4629 §8.2 + §8.3: verify one write against its declared intent. PURE —
+ * it compares two document sides and never touches disk.
+ *
+ * Both sides are first passed through `normalizeContent`, the OS projection
+ * seam's own normalization (CRLF strip, blank-line-run collapse, one trailing
+ * newline). `platformWriteSync` applies it to every STATE.md write, on this
+ * path and the legacy one alike, so it is the seam's behavior, not the
+ * intent's delta. Without it, a CRLF file would read as every section changed.
+ *
+ * §8.2 (verified post-state): every `required` assertion must land. With a
+ * declared `value`, "landed" means the target reads that value afterwards (an
+ * idempotent write that re-asserts the current value passes). Without one,
+ * "landed" means the target is still present AND measurably changed
+ * (`stateTargetChanged`, the measured-delta test `updated[]` uses); a deleted
+ * target has not landed. Best-effort assertions are NOT judged: their report
+ * bucket is ADR-4629 §8.4, an open question for Phase 3, so this result
+ * deliberately carries no best-effort field for a later phase to be bound by.
+ *
+ * §8.3 (bounded mutation): the delta must stay inside the declared scope.
+ *  - Body: diffed per leaf unit (`collectStateBodyUnits`). A changed unit is in
+ *    scope when it is the first occurrence of a section a declared
+ *    `target: 'section'` assertion names, or nested under that occurrence
+ *    (`stateSectionScopeUnits`). Otherwise it is in scope only when replaying the
+ *    post-values of the declared fields THAT UNIT OWNS (`stateFieldOwnerUnit`)
+ *    onto its pre text reproduces its post text, so any other edit in the same
+ *    section, or the same label in another section, is caught. A change in
+ *    section ORDER is its own out-of-scope region.
+ *  - Frontmatter: keys with a body source (`getFrontmatterBodySource`) are
+ *    judged through that source, because `syncStateFrontmatter` re-derives them
+ *    from the body on every write. When the seam's `bodyDeltas` show the source
+ *    moved, the body check above already bounded that move. A mirrored key that
+ *    changed with no body move, or with no `bodyDeltas` to show one, must be
+ *    declared. Every other key goes through `computeChangedFrontmatterFields`
+ *    (the reporter's rule: `last_updated` provenance exclusion, declared-leaf
+ *    materialization). A schema-declared key (a `FIELD_CLASSIFICATION` row)
+ *    that is absent before and present after is the seam catching a document
+ *    up, not the caller's action, the same provenance rule the reporter
+ *    applies. A key already present that the seam re-derives to a new value
+ *    (for example `progress.*` under `resync`) IS counted: §8.3 bounds what the
+ *    write changed, whoever computed it.
+ *  - A frontmatter key is declared when an assertion names it exactly, or when
+ *    it is one of the schema-declared leaves (`declaredLeavesOf`) of a key an
+ *    assertion names. Declaring `progress` therefore covers the closed set of
+ *    `progress.*` rows `FIELD_CLASSIFICATION` lists, the frontmatter analogue of
+ *    a `target: 'section'` assertion covering its child sections. Nothing else
+ *    widens: a declared leaf (`progress.percent`) never covers a sibling leaf,
+ *    and a dotted key outside the schema's leaf set is never covered by its
+ *    prefix.
+ *  - `scope: 'broad'` puts the WHOLE frontmatter in scope. That is ADR-4629
+ *    §8.3's own worked case (`milestoneSwitch` declares a whole-frontmatter
+ *    scope). The body stays bounded: broad is audited, not exempted.
+ *  - `kind: 'rebuild'` (`cmdStateSync`, `REGENERATE_STATE`) is unbounded by
+ *    contract (ADR-3408 §8.3; ADR-4629 §8.3 names those two and no more), so
+ *    §8.3 is skipped for it. §8.2 still applies.
+ *
+ * `Current Position` is always read as a whole section, in §8.2 and §8.3 alike,
+ * matching `readStateTarget`'s long-standing special case.
+ */
+function verifyStateWriteIntent(intent, preContent, postContent, statePath, bodyDeltas) {
+    const pre = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, preContent).content;
+    const post = (0, shell_command_projection_cjs_1.normalizeContent)(statePath, postContent).content;
+    const preFm = extractFrontmatter(pre, statePath);
+    const postFm = extractFrontmatter(post, statePath);
+    const preBody = stripFrontmatter(pre);
+    const postBody = stripFrontmatter(post);
+    const isSection = (a) => a.target === 'section' || a.field === 'Current Position';
+    const sectionTargets = new Set();
+    const fieldTargets = new Set();
+    for (const a of intent.assertions) {
+        if (isSection(a))
+            sectionTargets.add(a.field);
+        else
+            fieldTargets.add(a.field);
+    }
+    // §8.2 — required assertions.
+    const missedRequired = [];
+    for (const a of intent.assertions) {
+        if (a.requirement !== 'required')
+            continue;
+        const targets = isSection(a) ? new Set([a.field]) : NO_SECTION_TARGETS;
+        const actual = readStateTarget(postFm, postBody, a.field, targets);
+        const landed = a.value !== undefined
+            ? actual !== null && actual.trim() === a.value.trim()
+            : actual !== null && stateTargetChanged(preFm, preBody, postFm, postBody, a.field, targets);
+        if (!landed)
+            missedRequired.push(a.field);
+    }
+    // §8.3 — bounded mutation.
+    const outOfScope = [];
+    if (intent.kind !== 'rebuild') {
+        if (intent.scope !== 'broad') {
+            const declared = (key) => {
+                if (fieldTargets.has(key))
+                    return true;
+                const dot = key.indexOf('.');
+                if (dot <= 0)
+                    return false;
+                const parent = key.slice(0, dot);
+                return fieldTargets.has(parent) && declaredLeavesOf(parent).includes(key);
+            };
+            if (isUnparseableFrontmatter(preFm) || isUnparseableFrontmatter(postFm)) {
+                // An unparseable block has no keys to diff; judge the raw region.
+                if (stateFrontmatterRegion(pre) !== stateFrontmatterRegion(post)) {
+                    outOfScope.push({ region: 'frontmatter', name: '(unparseable block)' });
+                }
+            }
+            else {
+                const schemaMaterialized = (key) => Object.prototype.hasOwnProperty.call(FIELD_CLASSIFICATION, key)
+                    && resolveFrontmatterPath(preFm, key) === STATE_FIELD_ABSENT
+                    && resolveFrontmatterPath(postFm, key) !== STATE_FIELD_ABSENT;
+                // Non-body-sourced keys: `computeChangedFrontmatterFields` skips body-sourced
+                // keys entirely when handed no `bodyDeltas`; those are judged just below.
+                for (const key of computeChangedFrontmatterFields(preFm, postFm, undefined)) {
+                    if (!declared(key) && !schemaMaterialized(key))
+                        outOfScope.push({ region: 'frontmatter', name: key });
+                }
+                const topKeys = new Set([...Object.keys(preFm), ...Object.keys(postFm)]);
+                for (const key of topKeys) {
+                    if (stateTransitionMod.getFrontmatterBodySource(key) === null)
+                        continue;
+                    const before = resolveFrontmatterPath(preFm, key);
+                    const after = resolveFrontmatterPath(postFm, key);
+                    if (!stateFieldValuesDiffer(before, after))
+                        continue;
+                    if (before === STATE_FIELD_ABSENT)
+                        continue; // back-fill (the #1264 case), not the caller's action
+                    const delta = bodyDeltas ? bodyDeltas[key] : undefined;
+                    const bodyMoved = delta !== undefined
+                        && stateFieldValuesDiffer(delta.pre ?? STATE_FIELD_ABSENT, delta.post ?? STATE_FIELD_ABSENT);
+                    if (bodyMoved || declared(key))
+                        continue;
+                    outOfScope.push({ region: 'frontmatter', name: key });
+                }
+            }
+        }
+        const preUnits = collectStateBodyUnits(preBody);
+        const postUnits = collectStateBodyUnits(postBody);
+        const owners = new Map();
+        for (const field of fieldTargets) {
+            const owner = stateFieldOwnerUnit(postUnits, field) ?? stateFieldOwnerUnit(preUnits, field);
+            if (owner !== null)
+                owners.set(owner, [...(owners.get(owner) ?? []), field]);
+        }
+        const sectionScope = new Set([
+            ...stateSectionScopeUnits(preUnits, sectionTargets),
+            ...stateSectionScopeUnits(postUnits, sectionTargets),
+        ]);
+        for (const key of new Set([...preUnits.keys(), ...postUnits.keys()])) {
+            const before = preUnits.get(key);
+            const after = postUnits.get(key);
+            if (before !== undefined && after !== undefined && before.text === after.text)
+                continue;
+            const unit = (after ?? before);
+            if (sectionScope.has(key))
+                continue;
+            if (before !== undefined && after !== undefined) {
+                let replayed = before.text;
+                for (const field of owners.get(key) ?? []) {
+                    const next = (0, state_document_cjs_1.stateExtractField)(after.text, field);
+                    if (next === null)
+                        continue;
+                    const applied = (0, state_document_cjs_1.stateReplaceField)(replayed, field, next);
+                    if (applied !== null)
+                        replayed = applied;
+                }
+                if (replayed.trim() === after.text)
+                    continue;
+            }
+            outOfScope.push(unit.region);
+        }
+        const preOrder = [...preUnits.keys()].filter((k) => postUnits.has(k));
+        const postOrder = [...postUnits.keys()].filter((k) => preUnits.has(k));
+        if (preOrder.join('\n') !== postOrder.join('\n'))
+            outOfScope.push({ region: 'order', name: '' });
+    }
+    const reasons = [];
+    if (outOfScope.length > 0)
+        reasons.push(STATE_WRITE_INTENT_FAILURE.OUT_OF_SCOPE);
+    if (missedRequired.length > 0)
+        reasons.push(STATE_WRITE_INTENT_FAILURE.REQUIRED_ASSERTION_MISSED);
+    return Object.freeze({
+        ok: reasons.length === 0,
+        reasons: Object.freeze(reasons),
+        outOfScope: Object.freeze(outOfScope.map((r) => Object.freeze({ ...r }))),
+        missedRequired: Object.freeze(missedRequired),
+    });
+}
+const NO_UPDATED_FIELDS = Object.freeze([]);
+/**
+ * ADR-4629 §8.2 + §8.3: apply a declared `StateWriteIntent` through the one
+ * write seam and fail loud instead of reporting success.
+ *
+ * Under ONE lock (the same `acquireStateLock` `readModifyWriteStateMd` holds):
+ *   read -> transform -> `syncAndPreserveStateMd` (the owned composition,
+ *   driven by the intent's own `resync` / `deriveProgressKeys` /
+ *   `explicitProgressField`) -> verify the would-be content -> write only if
+ *   it verified -> re-read -> confirm the re-read file is exactly the verified
+ *   content (§8.2 verifies against the re-read file) -> report `updated[]`
+ *   from the measured disk delta.
+ * A §8.2/§8.3 violation is refused BEFORE the write, so the file is left
+ * untouched. The re-read check is the one failure found AFTER the write: if
+ * the re-read does not match what was verified, the result is
+ * `reasons: ['reread_mismatch']` with `written: true`. The file is NOT restored
+ * on that arm: the write reached disk but is not verified, and the result says
+ * so rather than attempting a restore through a write path that would itself
+ * normalize the bytes. Its `outOfScope` / `missedRequired` are empty, because
+ * the candidate content itself verified; what failed is the disk round-trip.
+ *
+ * "Loud" means the result, not an exception: a verification failure is a
+ * frozen `ok: false` value naming each reason, never a success payload.
+ * Turning that into a non-zero exit is the CLI caller's job, which lands with
+ * the first migrated caller (C3+). Construction errors (no intent, a rebuild
+ * intent) throw, like `createStateTransaction`'s.
+ *
+ * A transform whose output is byte-identical to its input is the #948 no-op:
+ * nothing is written, but the intent is still verified, so a `required`
+ * assertion that expected a change reports as missed rather than passing.
+ *
+ * Scope fence (C2): open-kind intents only. The two `rebuild` writers stay on
+ * `writeStateMd`, the sanctioned exception path (ADR-3408 §8.3). The intent's
+ * `snapshot` is not compared against the file read under the lock;
+ * optimistic concurrency on the prior value is outside ADR-4629 §8 as written.
+ */
+function applyStateWriteIntent(statePath, intent, transformFn, cwd, options = {}, clock) {
+    // Checked on an `unknown` view: `Array.isArray` on the typed ReadonlyArray would narrow it to `any[]`.
+    if (intent === null || typeof intent !== 'object' || !Array.isArray(intent.assertions)) {
+        const err = new Error('applyStateWriteIntent: a StateWriteIntent is required (build it with createStateWriteIntent). ' +
+            'Per ADR-4629 §8.1, an absent intent is a construction failure, not an unverified write.');
+        err.code = 'STATE_WRITE_INTENT_REQUIRED';
+        throw err;
+    }
+    if (intent.kind === 'rebuild') {
+        const err = new Error('applyStateWriteIntent: a rebuild intent cannot travel the preservation seam. The two rebuild ' +
+            'writers (cmdStateSync, REGENERATE_STATE) stay on writeStateMd per ADR-3408 §8.3; ADR-4629 §8.3 ' +
+            'treats them as unbounded by contract.');
+        err.code = 'STATE_TRANSACTION_KIND_INVALID';
+        throw err;
+    }
+    const lockPath = acquireStateLock(statePath, clock);
+    try {
+        const pre = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
+        const transformed = transformFn(pre);
+        const unwritten = (verification) => Object.freeze({ ...verification, written: false, updated: NO_UPDATED_FIELDS });
+        if (transformed === pre) {
+            return unwritten(verifyStateWriteIntent(intent, pre, pre, statePath));
+        }
+        const preWriteState = {};
+        const candidate = syncAndPreserveStateMd(pre, transformed, statePath, cwd, {
+            resync: intent.resync,
+            deriveProgressKeys: intent.deriveProgressKeys,
+            explicitProgressField: intent.explicitProgressField,
+            authoritativeFm: options.authoritativeFm,
+            preWriteState,
+        });
+        const verification = verifyStateWriteIntent(intent, pre, candidate, statePath, preWriteState.bodyDeltas);
+        if (!verification.ok)
+            return unwritten(verification);
+        (0, shell_command_projection_cjs_1.platformWriteSync)(statePath, candidate);
+        const reread = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
+        if (reread !== (0, shell_command_projection_cjs_1.normalizeContent)(statePath, candidate).content) {
+            return Object.freeze({
+                ok: false,
+                reasons: Object.freeze([STATE_WRITE_INTENT_FAILURE.REREAD_MISMATCH]),
+                outOfScope: verification.outOfScope,
+                missedRequired: verification.missedRequired,
+                written: true,
+                updated: NO_UPDATED_FIELDS,
+            });
+        }
+        const sectionTargets = new Set(intent.assertions.filter((a) => a.target === 'section' || a.field === 'Current Position').map((a) => a.field));
+        const updated = reconcileReportedFields(statePath, preWriteState, intent.assertions.map((a) => a.field), [], sectionTargets);
+        return Object.freeze({ ...verification, written: true, updated: Object.freeze(updated) });
+    }
+    finally {
+        releaseStateLock(lockPath);
+    }
+}
 function cmdStateJson(cwd, raw) {
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
@@ -6348,6 +6730,12 @@ module.exports = {
     // pinning the table it reads (`_FRONTMATTER_KEY_TO_BODY_LABEL`) against
     // itself.
     _bodyLabelFor: bodyLabelFor,
+    // ADR-4629 §8.2/§8.3 (epic #4629, C2 #4866): the verifying executor and its
+    // pure verifier. No production caller constructs a StateWriteIntent yet (C3+),
+    // so these are reached only by their positive-control tests.
+    applyStateWriteIntent,
+    _verifyStateWriteIntent: verifyStateWriteIntent,
+    STATE_WRITE_INTENT_FAILURE,
     // Test seam (audit M1): inject a deterministic isPidAlive so the liveness-gated
     // steal decision is exercised without real pids. Mirrors capability-lock.cts.
     _setLockProbes(probes) {

package/gsd-core/bin/lib/update-context.cjs

@@ -147,7 +147,24 @@ function resolveGlobalCandidate(fs, env, home, preferred) {
 /**
  * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
  */
-function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
+function resolveUpdateContext(opts) {
+    const base = resolveBaseUpdateContext(opts);
+    if (base.runtime !== 'opencode' || !base.gsdDir)
+        return base;
+    // The install records which OpenCode generation it targets; surface it when present.
+    const raw = opts.fs.readFile(node_path_1.default.join(base.gsdDir, 'gsd-install-state.json'));
+    if (raw == null)
+        return base;
+    try {
+        const hg = JSON.parse(raw).hostGeneration;
+        if (hg && hg.runtime === 'opencode' && (hg.generation === 1 || hg.generation === 2)) {
+            return { ...base, hostGeneration: hg.generation };
+        }
+    }
+    catch { /* an unreadable state file contributes nothing */ }
+    return base;
+}
+function resolveBaseUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
     // Expand a leading `~/` before any probe.
     preferredConfigDir = expandHome(preferredConfigDir, home);
     const preferred = preferredRuntime || inferPreferredRuntime({ fs, env, preferredConfigDir });