@fern-api/replay 0.13.0 → 0.14.1

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[];
@@ -69,6 +94,15 @@ interface FileResult {
     conflicts?: ConflictRegion[];
     conflictReason?: ConflictReason;
     conflictMetadata?: ConflictMetadata;
+    /**
+     * Lines that appeared as unchanged context in the customer's THEIRS (also
+     * present in BASE) but were absent from the merged output because OURS
+     * deleted them. diff3 sides with the deletion correctly, but the customer
+     * may not have realized those lines depended on the generator never
+     * removing them. Surfaced as a warning so the customer can re-add them
+     * if needed. Empty/undefined when no such lines exist.
+     */
+    droppedContextLines?: string[];
 }
 interface ConflictRegion {
     startLine: number;
@@ -80,6 +114,14 @@ interface MergeResult {
     content: string;
     hasConflicts: boolean;
     conflicts: ConflictRegion[];
+    /**
+     * Lines present in BOTH base and theirs but absent from the merged output.
+     * These are lines the customer's THEIRS treated as context; OURS deleted
+     * them; diff3 sided with the deletion. Empty when no such lines exist.
+     * Only populated when `hasConflicts` is false — when conflicts surface,
+     * the customer already knows something needs review.
+     */
+    droppedContextLines?: string[];
 }
 interface CommitInfo {
     sha: string;
@@ -182,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;
@@ -346,6 +388,39 @@ declare class ReplayApplicator {
     private renameCache;
     private treeExistsCache;
     private fileTheirsAccumulator;
+    /**
+     * Apply mode for the current `applyPatches` invocation. Set at the start
+     * of `applyPatches`, read by `mergeFile` to decide:
+     *   - whether to skip the intra-loop marker strip (kept in `applyPatches`)
+     *   - whether to populate the accumulator after a conflicted merge
+     *     (resolve mode populates so subsequent patches on the same file
+     *     can use patch A's THEIRS as a structurally-correct merge base
+     *     when their diff was authored against post-A structure)
+     *   - whether to retry THEIRS reconstruction against the accumulator
+     *     when the BASE-relative reconstruction produced markers from a
+     *     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.
@@ -369,9 +444,31 @@ declare class ReplayApplicator {
     /**
      * Apply all patches, returning results for each.
      * Skips patches that match exclude patterns in replay.yml
+     *
+     * `applyMode` controls the post-conflict marker strategy:
+     *   - `"replay"` (default): strip conflict markers from disk between
+     *     iterations whenever a later patch touches the same file. Lets the
+     *     follow-up patch's `git apply --3way` see clean OURS content,
+     *     which is what the silent-loss fix (PR #73) relies on. The replay
+     *     pipeline calls `revertConflictingFiles` after the loop to clean
+     *     any markers that survive.
+     *   - `"resolve"`: keep markers on disk. The resolve command needs the
+     *     customer to see them. Slow-path 3-way merge naturally preserves
+     *     A's markers and B's clean writes when their regions don't overlap;
+     *     when they do overlap, the customer gets nested markers and
+     *     resolves manually. Either way they aren't silently dropped.
+     */
+    applyPatches(patches: StoredPatch[], opts?: {
+        applyMode?: "replay" | "resolve";
+    }): Promise<ReplayResult[]>;
+    /**
+     * Populate accumulator after git apply succeeds, AND collect per-file
+     * results including any "dropped context lines" — lines that were
+     * present in BASE and THEIRS (unchanged context) but absent from the
+     * final on-disk state because OURS deleted them. This is the fast-path
+     * counterpart to ThreeWayMerge.computeDroppedContextLines used by the
+     * 3-way slow path; both must surface the same warning.
      */
-    applyPatches(patches: StoredPatch[]): Promise<ReplayResult[]>;
-    /** Populate accumulator after git apply succeeds. */
     private populateAccumulatorForPatch;
     private applyPatchWithFallback;
     private applyWithThreeWayMerge;
@@ -403,7 +500,13 @@ declare class ReplayCommitter {
     private outputDir;
     constructor(git: GitClient, outputDir: string);
     commitGeneration(message: string, options?: CommitOptions): Promise<string>;
-    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string): Promise<string>;
+    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string, options?: {
+        buckets?: {
+            applied: StoredPatch[];
+            unresolved: StoredPatch[];
+            absorbed: StoredPatch[];
+        };
+    }): Promise<string>;
     createGenerationRecord(options?: CommitOptions): Promise<GenerationRecord>;
     stageAll(): Promise<void>;
     hasStagedChanges(): Promise<boolean>;
@@ -622,6 +725,45 @@ 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;
+    /**
+     * 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).
      *
@@ -668,6 +810,15 @@ declare class ReplayService {
      * Called BEFORE commitGeneration() while HEAD has customer code.
      */
     private preGenerationRebase;
+    /**
+     * After applyPatches(), surface a warning for each (patch × file) where
+     * diff3 silently dropped lines that were unchanged context in the
+     * customer's THEIRS. The deletion stays on disk (correct diff3 outcome),
+     * but the customer must learn so they can re-add the lines if they
+     * relied on them. This is the "surface or preserve, never silently drop"
+     * contract for legitimate-deletion cases.
+     */
+    private recordDroppedContextLineWarnings;
     /**
      * After applyPatches(), strip conflict markers from conflicting files
      * so only clean content is committed. Keeps the Generated (OURS) side.
@@ -839,6 +990,8 @@ interface ResolveResult {
     patchesApplied?: number;
     /** Number of patches resolved and committed (phase 2) */
     patchesResolved?: number;
+    /** Non-fatal diagnostic messages (e.g., per-patch fallbacks) */
+    warnings?: string[];
 }
 declare function resolve(outputDir: string, options?: ResolveOptions): Promise<ResolveResult>;
 

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[];
@@ -69,6 +94,15 @@ interface FileResult {
     conflicts?: ConflictRegion[];
     conflictReason?: ConflictReason;
     conflictMetadata?: ConflictMetadata;
+    /**
+     * Lines that appeared as unchanged context in the customer's THEIRS (also
+     * present in BASE) but were absent from the merged output because OURS
+     * deleted them. diff3 sides with the deletion correctly, but the customer
+     * may not have realized those lines depended on the generator never
+     * removing them. Surfaced as a warning so the customer can re-add them
+     * if needed. Empty/undefined when no such lines exist.
+     */
+    droppedContextLines?: string[];
 }
 interface ConflictRegion {
     startLine: number;
@@ -80,6 +114,14 @@ interface MergeResult {
     content: string;
     hasConflicts: boolean;
     conflicts: ConflictRegion[];
+    /**
+     * Lines present in BOTH base and theirs but absent from the merged output.
+     * These are lines the customer's THEIRS treated as context; OURS deleted
+     * them; diff3 sided with the deletion. Empty when no such lines exist.
+     * Only populated when `hasConflicts` is false — when conflicts surface,
+     * the customer already knows something needs review.
+     */
+    droppedContextLines?: string[];
 }
 interface CommitInfo {
     sha: string;
@@ -182,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;
@@ -346,6 +388,39 @@ declare class ReplayApplicator {
     private renameCache;
     private treeExistsCache;
     private fileTheirsAccumulator;
+    /**
+     * Apply mode for the current `applyPatches` invocation. Set at the start
+     * of `applyPatches`, read by `mergeFile` to decide:
+     *   - whether to skip the intra-loop marker strip (kept in `applyPatches`)
+     *   - whether to populate the accumulator after a conflicted merge
+     *     (resolve mode populates so subsequent patches on the same file
+     *     can use patch A's THEIRS as a structurally-correct merge base
+     *     when their diff was authored against post-A structure)
+     *   - whether to retry THEIRS reconstruction against the accumulator
+     *     when the BASE-relative reconstruction produced markers from a
+     *     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.
@@ -369,9 +444,31 @@ declare class ReplayApplicator {
     /**
      * Apply all patches, returning results for each.
      * Skips patches that match exclude patterns in replay.yml
+     *
+     * `applyMode` controls the post-conflict marker strategy:
+     *   - `"replay"` (default): strip conflict markers from disk between
+     *     iterations whenever a later patch touches the same file. Lets the
+     *     follow-up patch's `git apply --3way` see clean OURS content,
+     *     which is what the silent-loss fix (PR #73) relies on. The replay
+     *     pipeline calls `revertConflictingFiles` after the loop to clean
+     *     any markers that survive.
+     *   - `"resolve"`: keep markers on disk. The resolve command needs the
+     *     customer to see them. Slow-path 3-way merge naturally preserves
+     *     A's markers and B's clean writes when their regions don't overlap;
+     *     when they do overlap, the customer gets nested markers and
+     *     resolves manually. Either way they aren't silently dropped.
+     */
+    applyPatches(patches: StoredPatch[], opts?: {
+        applyMode?: "replay" | "resolve";
+    }): Promise<ReplayResult[]>;
+    /**
+     * Populate accumulator after git apply succeeds, AND collect per-file
+     * results including any "dropped context lines" — lines that were
+     * present in BASE and THEIRS (unchanged context) but absent from the
+     * final on-disk state because OURS deleted them. This is the fast-path
+     * counterpart to ThreeWayMerge.computeDroppedContextLines used by the
+     * 3-way slow path; both must surface the same warning.
      */
-    applyPatches(patches: StoredPatch[]): Promise<ReplayResult[]>;
-    /** Populate accumulator after git apply succeeds. */
     private populateAccumulatorForPatch;
     private applyPatchWithFallback;
     private applyWithThreeWayMerge;
@@ -403,7 +500,13 @@ declare class ReplayCommitter {
     private outputDir;
     constructor(git: GitClient, outputDir: string);
     commitGeneration(message: string, options?: CommitOptions): Promise<string>;
-    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string): Promise<string>;
+    commitReplay(_patchCount: number, patches?: StoredPatch[], message?: string, options?: {
+        buckets?: {
+            applied: StoredPatch[];
+            unresolved: StoredPatch[];
+            absorbed: StoredPatch[];
+        };
+    }): Promise<string>;
     createGenerationRecord(options?: CommitOptions): Promise<GenerationRecord>;
     stageAll(): Promise<void>;
     hasStagedChanges(): Promise<boolean>;
@@ -622,6 +725,45 @@ 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;
+    /**
+     * 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).
      *
@@ -668,6 +810,15 @@ declare class ReplayService {
      * Called BEFORE commitGeneration() while HEAD has customer code.
      */
     private preGenerationRebase;
+    /**
+     * After applyPatches(), surface a warning for each (patch × file) where
+     * diff3 silently dropped lines that were unchanged context in the
+     * customer's THEIRS. The deletion stays on disk (correct diff3 outcome),
+     * but the customer must learn so they can re-add the lines if they
+     * relied on them. This is the "surface or preserve, never silently drop"
+     * contract for legitimate-deletion cases.
+     */
+    private recordDroppedContextLineWarnings;
     /**
      * After applyPatches(), strip conflict markers from conflicting files
      * so only clean content is committed. Keeps the Generated (OURS) side.
@@ -839,6 +990,8 @@ interface ResolveResult {
     patchesApplied?: number;
     /** Number of patches resolved and committed (phase 2) */
     patchesResolved?: number;
+    /** Non-fatal diagnostic messages (e.g., per-patch fallbacks) */
+    warnings?: string[];
 }
 declare function resolve(outputDir: string, options?: ResolveOptions): Promise<ResolveResult>;