@fern-api/replay 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -37,6 +37,31 @@ interface StoredPatch {
      * the generator will not start producing a file it never produced before.
      */
     user_owned?: boolean;
+    /**
+     * THEIRS snapshot — the post-customer-edit content of each file the patch
+     * touches. When present, replay's slow-path 3-way merge uses this directly
+     * as THEIRS, bypassing `applyPatchToContent(BASE, patch_content)`
+     * reconstruction.
+     *
+     * Why this exists: `patch_content` is a unified diff anchored to specific
+     * line numbers in BASE. When the generator structurally changes a file
+     * across regens (different types, dropped/added imports, etc.), those
+     * line anchors no longer survive — reconstruction fails or produces
+     * garbage, and the customer's customization gets lost. The snapshot
+     * stores the customer's intent at content level, not at line-anchor
+     * level. diff3 then operates on actual content (BASE vs OURS vs THEIRS)
+     * and naturally handles structural changes via merge semantics rather
+     * than line bookkeeping.
+     *
+     * Keys are post-rename paths (matching the `files` array). Files the
+     * patch deletes are omitted from the map; the `+++ /dev/null` marker
+     * in `patch_content` remains the canonical delete signal.
+     *
+     * Optional for backward compat. Existing lockfiles without this field
+     * auto-migrate on the first regen post-upgrade via
+     * `preGenerationRebase`'s migration pass.
+     */
+    theirs_snapshot?: Record<string, string>;
 }
 interface CustomizationsConfig {
     exclude?: string[];
@@ -199,14 +224,14 @@ declare class LockfileManager {
     save(): void;
     addGeneration(record: GenerationRecord): void;
     addPatch(patch: StoredPatch): void;
-    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status" | "user_owned">>): void;
+    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status" | "user_owned" | "theirs_snapshot">>): void;
     removePatch(patchId: string): void;
     clearPatches(): void;
     addForgottenHash(hash: string): void;
     getUnresolvedPatches(): StoredPatch[];
     getResolvingPatches(): StoredPatch[];
     markPatchUnresolved(patchId: string): void;
-    markPatchResolved(patchId: string, updates: Pick<StoredPatch, "patch_content" | "content_hash" | "base_generation" | "files">): void;
+    markPatchResolved(patchId: string, updates: Pick<StoredPatch, "patch_content" | "content_hash" | "base_generation" | "files" | "theirs_snapshot">): void;
     getPatches(): StoredPatch[];
     setReplaySkippedAt(timestamp: string): void;
     clearReplaySkippedAt(): void;
@@ -376,6 +401,26 @@ declare class ReplayApplicator {
      *     cross-patch context mismatch
      */
     private currentApplyMode;
+    /**
+     * Set of files that appear in 2+ patches in the current `applyPatches`
+     * invocation. Computed at the top of `applyPatches`. Read by `mergeFile`
+     * and `populateAccumulatorForPatch` to decide whether to use the patch's
+     * `theirs_snapshot` directly as THEIRS (snapshot-as-primary) or fall
+     * back to line-anchored reconstruction (FER-9525 cross-patch isolation).
+     *
+     * Snapshot-as-primary is correct when the patch owns its file (no other
+     * patch in this run touches it): the snapshot is what the customer
+     * intends for that file post-regen, regardless of generator structural
+     * changes that would invalidate the diff's line anchors.
+     *
+     * When a file IS shared, snapshots are CUMULATIVE across the patches
+     * touching it (each one's snapshot includes prior patches' contributions).
+     * Using a later patch's cumulative snapshot as its individual THEIRS
+     * would propagate prior patches' edits into the merge — surfacing nested
+     * conflicts at regions the patch alone never touched. Reconstruction
+     * via `applyPatchToContent` is required there.
+     */
+    private sharedFiles;
     constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
     /**
      * Resolve the GenerationRecord for a patch's base_generation.
@@ -680,6 +725,59 @@ declare class ReplayService {
      * Returns the number of patches rebased.
      */
     private rebasePatches;
+    /**
+     * Read THEIRS snapshot (post-customer-edit content) for a list of files
+     * from the working tree on disk. Used by `rebasePatches` after a clean
+     * apply — disk = correctly-merged customer state at the new generation.
+     * Skips binary files (matches `mergeFile`/`populateAccumulatorForPatch`
+     * policy — binary content as `utf-8` is lossy and snapshots of it would
+     * never be used during apply anyway).
+     */
+    private readSnapshotFromDisk;
+    /**
+     * FER-10203: returns true when a `[fern-autoversion]` commit between
+     * `fromSha` and `toSha` touched any of the patch's `files`. Re-classifies
+     * each grep match via `isGenerationCommit` so a customer commit that
+     * merely quotes the marker in its body doesn't false-positive.
+     */
+    private hasAutoversionContamination;
+    /**
+     * FER-10203: rebuild patch_content from `theirs_snapshot` (captured at
+     * detection time, predates pipeline content) rather than a HEAD-relative
+     * diff. Returns `null` when snapshot is missing or doesn't cover every
+     * file in `patch.files` — caller leaves the patch unchanged.
+     */
+    private computeSnapshotBasedPatchDiff;
+    /**
+     * Read THEIRS snapshot from a git tree-ish (commit, branch, or tree).
+     * Used when the diff that produced `patch_content` was relative to that
+     * tree (e.g., `git diff currentGen HEAD --` → snapshot from HEAD).
+     * Skips binary files.
+     */
+    private readSnapshotFromTree;
+    /**
+     * One-shot auto-migration: backfill `theirs_snapshot` on existing
+     * patches that predate the snapshot encoding. Computes the snapshot by
+     * applying the patch's `patch_content` to its `base_generation` tree —
+     * yielding the patch's INDIVIDUAL contribution.
+     *
+     * **Skips patches sharing files with other patches.** HEAD's content
+     * for a file shared by N patches is cumulative across all of them, so
+     * a HEAD-fallback would falsely encode other patches' contributions
+     * into one patch's snapshot — breaking FER-9525 cross-patch isolation
+     * if the snapshot fallback later fires. Per-patch snapshots only
+     * make sense when the patch owns its file. Multi-patch-same-file
+     * legacy lockfiles keep using line-anchored reconstruction (the
+     * existing path); they're no worse than pre-upgrade.
+     *
+     * **Does not fall back to HEAD when BASE-reconstruction fails.** Same
+     * reason — HEAD content can be cumulative. Patches whose
+     * reconstruction fails just don't get a snapshot; legacy paths
+     * (PR #73's by-association gate, accumulator fallback) handle them.
+     *
+     * Skips patches that already have a snapshot.
+     */
+    private migratePatchesToSnapshot;
     /**
      * Determine whether `file` is user-owned (never produced by the generator).
      *

package/dist/index.d.ts

@@ -37,6 +37,31 @@ interface StoredPatch {
      * the generator will not start producing a file it never produced before.
      */
     user_owned?: boolean;
+    /**
+     * THEIRS snapshot — the post-customer-edit content of each file the patch
+     * touches. When present, replay's slow-path 3-way merge uses this directly
+     * as THEIRS, bypassing `applyPatchToContent(BASE, patch_content)`
+     * reconstruction.
+     *
+     * Why this exists: `patch_content` is a unified diff anchored to specific
+     * line numbers in BASE. When the generator structurally changes a file
+     * across regens (different types, dropped/added imports, etc.), those
+     * line anchors no longer survive — reconstruction fails or produces
+     * garbage, and the customer's customization gets lost. The snapshot
+     * stores the customer's intent at content level, not at line-anchor
+     * level. diff3 then operates on actual content (BASE vs OURS vs THEIRS)
+     * and naturally handles structural changes via merge semantics rather
+     * than line bookkeeping.
+     *
+     * Keys are post-rename paths (matching the `files` array). Files the
+     * patch deletes are omitted from the map; the `+++ /dev/null` marker
+     * in `patch_content` remains the canonical delete signal.
+     *
+     * Optional for backward compat. Existing lockfiles without this field
+     * auto-migrate on the first regen post-upgrade via
+     * `preGenerationRebase`'s migration pass.
+     */
+    theirs_snapshot?: Record<string, string>;
 }
 interface CustomizationsConfig {
     exclude?: string[];
@@ -199,14 +224,14 @@ declare class LockfileManager {
     save(): void;
     addGeneration(record: GenerationRecord): void;
     addPatch(patch: StoredPatch): void;
-    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status" | "user_owned">>): void;
+    updatePatch(patchId: string, updates: Partial<Pick<StoredPatch, "base_generation" | "patch_content" | "content_hash" | "files" | "status" | "user_owned" | "theirs_snapshot">>): void;
     removePatch(patchId: string): void;
     clearPatches(): void;
     addForgottenHash(hash: string): void;
     getUnresolvedPatches(): StoredPatch[];
     getResolvingPatches(): StoredPatch[];
     markPatchUnresolved(patchId: string): void;
-    markPatchResolved(patchId: string, updates: Pick<StoredPatch, "patch_content" | "content_hash" | "base_generation" | "files">): void;
+    markPatchResolved(patchId: string, updates: Pick<StoredPatch, "patch_content" | "content_hash" | "base_generation" | "files" | "theirs_snapshot">): void;
     getPatches(): StoredPatch[];
     setReplaySkippedAt(timestamp: string): void;
     clearReplaySkippedAt(): void;
@@ -376,6 +401,26 @@ declare class ReplayApplicator {
      *     cross-patch context mismatch
      */
     private currentApplyMode;
+    /**
+     * Set of files that appear in 2+ patches in the current `applyPatches`
+     * invocation. Computed at the top of `applyPatches`. Read by `mergeFile`
+     * and `populateAccumulatorForPatch` to decide whether to use the patch's
+     * `theirs_snapshot` directly as THEIRS (snapshot-as-primary) or fall
+     * back to line-anchored reconstruction (FER-9525 cross-patch isolation).
+     *
+     * Snapshot-as-primary is correct when the patch owns its file (no other
+     * patch in this run touches it): the snapshot is what the customer
+     * intends for that file post-regen, regardless of generator structural
+     * changes that would invalidate the diff's line anchors.
+     *
+     * When a file IS shared, snapshots are CUMULATIVE across the patches
+     * touching it (each one's snapshot includes prior patches' contributions).
+     * Using a later patch's cumulative snapshot as its individual THEIRS
+     * would propagate prior patches' edits into the merge — surfacing nested
+     * conflicts at regions the patch alone never touched. Reconstruction
+     * via `applyPatchToContent` is required there.
+     */
+    private sharedFiles;
     constructor(git: GitClient, lockManager: LockfileManager, outputDir: string);
     /**
      * Resolve the GenerationRecord for a patch's base_generation.
@@ -680,6 +725,59 @@ declare class ReplayService {
      * Returns the number of patches rebased.
      */
     private rebasePatches;
+    /**
+     * Read THEIRS snapshot (post-customer-edit content) for a list of files
+     * from the working tree on disk. Used by `rebasePatches` after a clean
+     * apply — disk = correctly-merged customer state at the new generation.
+     * Skips binary files (matches `mergeFile`/`populateAccumulatorForPatch`
+     * policy — binary content as `utf-8` is lossy and snapshots of it would
+     * never be used during apply anyway).
+     */
+    private readSnapshotFromDisk;
+    /**
+     * FER-10203: returns true when a `[fern-autoversion]` commit between
+     * `fromSha` and `toSha` touched any of the patch's `files`. Re-classifies
+     * each grep match via `isGenerationCommit` so a customer commit that
+     * merely quotes the marker in its body doesn't false-positive.
+     */
+    private hasAutoversionContamination;
+    /**
+     * FER-10203: rebuild patch_content from `theirs_snapshot` (captured at
+     * detection time, predates pipeline content) rather than a HEAD-relative
+     * diff. Returns `null` when snapshot is missing or doesn't cover every
+     * file in `patch.files` — caller leaves the patch unchanged.
+     */
+    private computeSnapshotBasedPatchDiff;
+    /**
+     * Read THEIRS snapshot from a git tree-ish (commit, branch, or tree).
+     * Used when the diff that produced `patch_content` was relative to that
+     * tree (e.g., `git diff currentGen HEAD --` → snapshot from HEAD).
+     * Skips binary files.
+     */
+    private readSnapshotFromTree;
+    /**
+     * One-shot auto-migration: backfill `theirs_snapshot` on existing
+     * patches that predate the snapshot encoding. Computes the snapshot by
+     * applying the patch's `patch_content` to its `base_generation` tree —
+     * yielding the patch's INDIVIDUAL contribution.
+     *
+     * **Skips patches sharing files with other patches.** HEAD's content
+     * for a file shared by N patches is cumulative across all of them, so
+     * a HEAD-fallback would falsely encode other patches' contributions
+     * into one patch's snapshot — breaking FER-9525 cross-patch isolation
+     * if the snapshot fallback later fires. Per-patch snapshots only
+     * make sense when the patch owns its file. Multi-patch-same-file
+     * legacy lockfiles keep using line-anchored reconstruction (the
+     * existing path); they're no worse than pre-upgrade.
+     *
+     * **Does not fall back to HEAD when BASE-reconstruction fails.** Same
+     * reason — HEAD content can be cumulative. Patches whose
+     * reconstruction fails just don't get a snapshot; legacy paths
+     * (PR #73's by-association gate, accumulator fallback) handle them.
+     *
+     * Skips patches that already have a snapshot.
+     */
+    private migratePatchesToSnapshot;
     /**
      * Determine whether `file` is user-owned (never produced by the generator).
      *