@ricsam/r5d-worker 0.0.131 → 0.0.133

package/dist/types/workspace-command-targets.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Declared additional targets of a command, PTY or one-shot exec.
+ *
+ * A server that forwards a session's live `checkout` claims attaches the
+ * claimed sibling checkouts as `additionalTargets`. The worker treats every
+ * listed project branch exactly like the command's own target for admission
+ * (every mount is reserved and waits on the hold fence), busy detection and
+ * mutation tokens, for the whole lifetime of the process: the list is fixed
+ * when the command is admitted and only the process exit removes it. The
+ * primary target alone keeps environment attribution, the plans-mount
+ * predicate and credential-bearing process-group ownership.
+ */
+export type WorkspaceCommandProjectTarget = {
+    type: "project";
+    projectId: string;
+    branchName: string;
+};
+export type WorkspaceCommandAnyTarget = WorkspaceCommandProjectTarget | {
+    type: "workspace";
+    ownerUserId: string;
+    rootProfile: "visible_projects" | "canonical_sync";
+};
+export type WorkspaceCommandTargetValidators = {
+    validateProjectId: (projectId: string) => void;
+    validateBranchName: (branchName: string) => void;
+};
+/**
+ * The additional targets a message declares, checked and deduplicated: only
+ * project branches, each structurally valid, none equal to the primary
+ * target. A malformed entry is a protocol violation and fails the command
+ * before admission rather than silently narrowing its fence.
+ */
+export declare function normalizeCommandAdditionalTargets(primary: WorkspaceCommandAnyTarget, additional: unknown, validators: WorkspaceCommandTargetValidators): WorkspaceCommandProjectTarget[];
+/** Every target a command fences, primary first. */
+export declare function commandTargets<T extends WorkspaceCommandAnyTarget>(primary: T, additional: readonly WorkspaceCommandProjectTarget[]): Array<T | WorkspaceCommandProjectTarget>;
+/** Log suffix naming the additional checkouts a command fences; empty when there are none. */
+export declare function describeCommandAdditionalTargets(additional: readonly WorkspaceCommandProjectTarget[]): string;

package/dist/types/workspace-filesystem-job-types.d.ts

@@ -1,6 +1,7 @@
 import type { ProjectWorktreeBranch, ProjectWorktreeSnapshot, ProjectWorktreeSnapshotProgress, ProjectWorktreeSnapshotScope, ProjectWorktreeWorkingTreeMode } from "./project-worktrees";
-import type { WorkingTreeGitlink } from "./working-tree-mirror";
-import type { WorkspaceGitMountData, WorkspaceHydrationReceipt } from "./workspace-git-sync";
+import type { ProjectedWorkingTreeEntry, WorkingTreeGitlink } from "./working-tree-mirror";
+import type { WorkspaceGitMountData, WorkspaceHydrationReceipt, WorkspaceHydrationRecoveryRequired, WorkspaceHydrationPreservationResult, WorkspaceHydrationMountSkip } from "./workspace-git-sync";
+import type { WorkspaceHydrationMergeBasis } from "./workspace-hydration-merge";
 import type { WorkspaceMergeProjectionMount, WorkspaceMergeProjectionResult } from "./workspace-merge-projection";
 import type { ProjectCheckoutPathMoveBranch } from "./workspace-path-move";
 /**
@@ -28,16 +29,43 @@ export type WorkspaceFilesystemJobTable = {
         };
         result: null;
     };
-    /** The complete hydration transaction: snapshot, hydrate, fsync, commit marker, receipt; restore on failure. */
+    /** Read-only pending guarded transaction evidence for configuration admission. */
+    hydration_recovery_inspect: {
+        input: {
+            workspacePath: string;
+        };
+        result: WorkspaceHydrationRecoveryRequired | null;
+    };
+    /** Explicit exact-identity recovery: preserve visible data and archive all interrupted guarded transaction evidence. */
+    hydration_preserve_interrupted: {
+        input: {
+            workspacePath: string;
+            expectedTransactionId: string;
+        };
+        result: WorkspaceHydrationPreservationResult;
+    };
+    /**
+     * The complete hydration transaction: snapshot, hydrate, fsync, commit
+     * marker, receipt; restore on failure. A mount listed in `mergeBases` is
+     * merge-hydrated (docs/merge-hydration-design.md): files changed in the
+     * checkout since the projection read are three-way merged instead of
+     * overwritten, and a conflict or a write racing the hydration pins the
+     * mount at its previous receipt entry (`skippedMounts`) instead of
+     * failing the transaction.
+     */
     hydration_transaction: {
         input: {
             workspacePath: string;
             hydrationMounts: WorkspaceGitMountData[];
             advancedDurabilityMounts: WorkspaceGitMountData[];
             targetReceipt: WorkspaceHydrationReceipt | null;
+            mergeBases?: Record<string, WorkspaceHydrationMergeBasis>;
         };
         result: {
             hydratedMountIds: string[];
+            skippedMounts: WorkspaceHydrationMountSkip[];
+            /** Per merge-hydrated mount, the blob each replaced path held before hydration (the stale-rewrite detector's input). */
+            hydratedPreBlobs: Record<string, Record<string, string>>;
         };
     };
     /** Pre-clone hydration of visible mounts without a transaction (no outer Git directory yet). */
@@ -79,17 +107,30 @@ export type WorkspaceFilesystemJobTable = {
             basisHead: string;
             currentHead: string;
             attemptId: string;
+            /** Blob ids the last merge hydration replaced, by mount-relative path; a changed file hashing to one is a stale rewrite. */
+            staleRewriteBlobs?: Record<string, string>;
         };
         result: WorkspaceMergeProjectionResult;
     };
-    /** Byte mirror of one visible mount into the outer checkout. */
+    /**
+     * Byte mirror of one visible mount into the outer checkout. Returns what it
+     * read for every file (merge hydration's stat basis), or the paths that
+     * hold a stale rewrite, in which case nothing was mirrored.
+     */
     projection_mirror: {
         input: {
             workspacePath: string;
             mount: WorkspaceGitMountData;
+            staleRewriteBlobs?: Record<string, string>;
         };
         result: {
             gitlinks: WorkingTreeGitlink[];
+            projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
+            /** Wall-clock time the mirror finished reading; projected stats younger than this minus a window are not trusted. */
+            readAtMs: number;
+            staleRewritePaths: string[];
+            /** Ledger paths whose checkout content moved on from both the replaced and the hydrated bytes. */
+            staleRewriteCleared: string[];
         };
     };
     /** Outer-tree edits after the mirrors: tombstone removal, merged subtree materialization, deferred restores. */
@@ -216,6 +257,7 @@ export type WorkspaceFilesystemSerializedError = {
     code?: string;
     branchMayExist?: true;
     cleanupFailures?: string[];
+    hydrationRecovery?: WorkspaceHydrationRecoveryRequired;
     errors?: WorkspaceFilesystemSerializedError[];
     cause?: WorkspaceFilesystemSerializedError;
 };

package/dist/types/workspace-git-sync.d.ts

@@ -1,10 +1,26 @@
-import { type WorkingTreeGitlink, type WorkingTreeSourceMode } from "./working-tree-mirror";
+import { type PreparedWorkingTreeMirror, type ProjectedWorkingTreeEntry, type WorkingTreeGitlink, type WorkingTreeMirrorPlan, type WorkingTreeMirrorScope, type WorkingTreeSourceMode } from "./working-tree-mirror";
+import { type WorkspaceHydrationMergeBasis, type WorkspaceHydrationMergeDecision, type WorkspaceHydrationMountSkip as WorkspaceHydrationMountSkipBase } from "./workspace-hydration-merge";
+import { WorkspaceHydrationPreBlobLedger } from "./workspace-hydration-ledger";
 export declare const WORKSPACE_GIT_BRANCH = "main";
 export declare const MAX_WORKSPACE_GIT_DIFF_BYTES: number;
 export declare const WORKSPACE_GIT_CONFIRMED_LARGE_DIFF_PUSH_OPTION = "r5d-confirm-large-diff-v1";
 export declare const WORKSPACE_GIT_HYDRATED_RECEIPT = "r5d/workspace-hydrated-head";
 export declare const WORKSPACE_GIT_HYDRATION_TRANSACTION = "r5d/workspace-hydration-transaction";
+export declare const WORKSPACE_GIT_HYDRATION_RECOVERIES = "r5d/workspace-hydration-recoveries";
 export declare const WORKSPACE_GIT_CHECKOUT_DURABILITY = "r5d/workspace-checkout-durability";
+/** `R5D_MERGE_HYDRATION=0` restores the plain byte mirror for post-publication hydration (docs/merge-hydration-design.md §4). */
+export declare const WORKSPACE_MERGE_HYDRATION_SWITCH = "R5D_MERGE_HYDRATION";
+declare function hydrationPreBlobLedger(workspacePath: string): WorkspaceHydrationPreBlobLedger;
+export type WorkspaceHydrationMountSkip = WorkspaceHydrationMountSkipBase & {
+    retainedPaths?: string[];
+};
+export type WorkspaceMountSkipReason = WorkspaceHydrationMountSkip["reason"] | "stale_rewrite_detected";
+/** Why a mount was left at its recorded basis this cycle, with the paths involved; a diagnostic beside `skippedMountIds`. */
+export type WorkspaceMountSkipReasons = Record<string, {
+    reason: WorkspaceMountSkipReason;
+    paths: string[];
+    retainedPaths?: string[];
+}>;
 type WorkspaceHydrationMountBasis = {
     id: string;
     incarnationKey: string;
@@ -26,6 +42,57 @@ export type WorkspaceHydrationReceipt = {
     /** Non-enumerable read-compat marker used only to finish a v1/v2 crash transition. */
     legacyHead?: string;
 };
+type WorkspaceHydrationTransactionManifest = {
+    /** Version 5 makes guarded recovery explicit before any visible mutation. */
+    version: 3 | 4 | 5;
+    transactionId?: string;
+    targetReceipt: WorkspaceHydrationReceipt | null;
+    receiptBefore: WorkspaceHydrationReceipt | null;
+    mounts: Array<{
+        id: string;
+        incarnationKey: string;
+        sourcePath: string;
+        durabilityRootPath: string;
+        workspaceRelativePath: string;
+        existed: boolean;
+        snapshotName: string;
+        /**
+         * Present when the snapshot holds only the entries hydration replaces or
+         * removes, with the paths it creates listed. Without it the snapshot is a
+         * complete copy of the mount.
+         */
+        scope?: WorkingTreeMirrorScope;
+        /** Required in v5: guarded mounts never enter unguarded snapshot restore. */
+        recovery?: "snapshot" | "guarded";
+    }>;
+    /** Settled rollback scopes remain evidence; they are never restored again. */
+    preservedMounts?: WorkspaceHydrationTransactionManifest["mounts"];
+};
+export type WorkspaceHydrationRecoveryRequired = {
+    transactionId: string;
+    transactionPath: string;
+    mounts: Array<Pick<WorkspaceHydrationTransactionManifest["mounts"][number], "id" | "incarnationKey" | "sourcePath" | "durabilityRootPath" | "workspaceRelativePath"> & {
+        retainedPaths?: string[];
+    }>;
+    receiptBefore: WorkspaceHydrationReceipt | null;
+};
+export declare class WorkspaceHydrationRecoveryRequiredError extends Error {
+    readonly hydrationRecovery: WorkspaceHydrationRecoveryRequired;
+    readonly code = "hydration_recovery_required";
+    constructor(hydrationRecovery: WorkspaceHydrationRecoveryRequired, options?: ErrorOptions);
+}
+export type WorkspaceHydrationPreservationResult = {
+    transactionId: string;
+    archivePath: string;
+    receiptBefore: WorkspaceHydrationReceipt | null;
+    preservedMountIds: string[];
+    alreadyPreserved: boolean;
+    retainedEntries?: Array<{
+        mountId: string;
+        sourcePath: string;
+        archivePath: string;
+    }>;
+};
 export type WorkspaceGitMount = {
     id: string;
     /** Durable logical incarnation (for example the project-branch row id). */
@@ -57,6 +124,8 @@ export type WorkspaceGitMount = {
     /** Remove the outer-workspace subtree when the mounted source was intentionally deleted. */
     deleteWhenSourceMissing?: boolean;
     busy?: () => boolean;
+    /** Control-thread diagnostics only; never sent to a filesystem job. */
+    describeHolders?: () => string;
     /** Monotonic/opaque visible-mutation token used to catch short writes that begin and end between busy checks. */
     mutationToken?: () => string;
     /**
@@ -130,6 +199,14 @@ export type WorkspaceGitSyncResult = {
     affectedPaths: string[];
     activeMountIds: string[];
     skippedMountIds: string[];
+    /**
+     * Mounts merge hydration pinned this cycle (a conflict between a write
+     * that landed after the projection read and the inbound change, or a write
+     * racing the hydration) and mounts the stale-rewrite detector refused to
+     * project, each with the paths involved. Worker-internal until the server
+     * contract carries it.
+     */
+    mountSkipReasons?: WorkspaceMountSkipReasons;
     /** Token each active mount carried when this cycle projected it; recorded by the caller to skip unchanged mounts later. */
     projectedMutationTokens?: Record<string, string>;
     /** Creator-local mounts whose first outer publication was measured against their source subtree. */
@@ -179,6 +256,40 @@ export declare function runCheckoutDurabilityRecoveryJob(input: {
 export declare function runOuterCheckoutFsyncJob(input: {
     workspacePath: string;
 }): null;
+/** Read-only admission inspection, including before incident configuration fast paths. */
+export declare function runHydrationRecoveryInspectJob(input: {
+    workspacePath: string;
+}): WorkspaceHydrationRecoveryRequired | null;
+/**
+ * Explicitly preserve an interrupted guarded transaction. The caller owns
+ * workspace admission/exclusion. No visible file is restored or deleted and
+ * no mount is receipted at the partially applied target head. The entire
+ * transaction directory is archived atomically, including snapshots and any
+ * interrupted manifest writes, before ordinary merge projection may resume.
+ */
+export declare function runHydrationPreserveInterruptedJob(input: {
+    workspacePath: string;
+    expectedTransactionId: string;
+}): WorkspaceHydrationPreservationResult;
+/** Everything the apply phase needs for a merge-hydrated mount, decided before the manifest was written. */
+type WorkspaceHydrationMergePlan = {
+    prepared: PreparedWorkingTreeMirror;
+    decision: Extract<WorkspaceHydrationMergeDecision, {
+        kind: "apply";
+    }>;
+    plan: WorkingTreeMirrorPlan;
+    /** The mount's snapshot directory once the transaction directory is published. */
+    snapshotPath: string;
+    basis: WorkspaceHydrationMergeBasis;
+};
+declare function beginHydrationTransaction(workspacePath: string, mounts: readonly WorkspaceGitMount[], targetReceipt: WorkspaceHydrationReceipt | null, mergeBases?: Readonly<Record<string, WorkspaceHydrationMergeBasis>>): {
+    manifest: WorkspaceHydrationTransactionManifest;
+    durabilityScopes: Map<string, readonly string[]>;
+    mergePlans: Map<string, WorkspaceHydrationMergePlan>;
+    /** Mounts merge hydration decided not to touch; they have no snapshot, no manifest entry and keep their receipt entry. */
+    skippedMounts: WorkspaceHydrationMountSkip[];
+    targetReceipt: WorkspaceHydrationReceipt | null;
+};
 declare function configureWorkspaceRepository(input: {
     workspacePath: string;
     remoteUrl: string;
@@ -231,7 +342,7 @@ type ProjectedMountGitlinks = {
  * arrives as an empty directory plus a gitlink the caller must stage with
  * `stageWorkspaceGitlinks` before `git add -A`, which can never create one.
  */
-declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): ProjectedMountGitlinks[];
+declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[], projectedFiles?: Map<string, ProjectedWorkingTreeEntry>): ProjectedMountGitlinks[];
 /**
  * Executor job body: the complete hydration transaction. Snapshot exactly
  * what hydration replaces, hydrate, cross the durability barrier, write the
@@ -244,8 +355,11 @@ export declare function runHydrationTransactionJob(input: {
     hydrationMounts: readonly WorkspaceGitMountData[];
     advancedDurabilityMounts: readonly WorkspaceGitMountData[];
     targetReceipt: WorkspaceHydrationReceipt | null;
+    mergeBases?: Readonly<Record<string, WorkspaceHydrationMergeBasis>>;
 }): {
     hydratedMountIds: string[];
+    skippedMounts: WorkspaceHydrationMountSkip[];
+    hydratedPreBlobs: Record<string, Record<string, string>>;
 };
 /** Executor job body: hydrate visible mounts before an outer clone exists (no transaction to record). */
 export declare function runHydrationRawJob(input: {
@@ -340,12 +454,17 @@ export type SynchronizeWorkspaceGitInput = {
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
 };
 export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
-/** Executor job body: byte-mirror one visible mount into the outer checkout. */
+/** Executor job body: byte-mirror one visible mount into the outer checkout, recording what it read. */
 export declare function runProjectionMirrorJob(input: {
     workspacePath: string;
     mount: WorkspaceGitMountData;
+    staleRewriteBlobs?: Record<string, string>;
 }): {
     gitlinks: WorkingTreeGitlink[];
+    projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
+    readAtMs: number;
+    staleRewritePaths: string[];
+    staleRewriteCleared: string[];
 };
 /** Executor job body: outer-tree edits that follow the mirrors, in the cycle's order. */
 export declare function runProjectionOuterApplyJob(input: {
@@ -364,10 +483,13 @@ export declare function runProjectionReceiptJob(input: {
     receipt: WorkspaceHydrationReceipt;
 }): null;
 export declare const workspaceGitSyncTestHarness: {
+    beginHydrationTransaction: typeof beginHydrationTransaction;
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;
     configureWorkspaceRepository: typeof configureWorkspaceRepository;
     mirrorMountsToWorkspace: typeof mirrorMountsToWorkspace;
     hydrateMountsFromWorkspace: typeof hydrateWorkspaceGitMounts;
+    hydrationPreBlobLedger: typeof hydrationPreBlobLedger;
+    resetHydrationPreBlobLedgers(): void;
 };
 export {};

package/dist/types/workspace-hydration-ledger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Blob ids of the bytes merge hydration replaced in a checkout, kept in
+ * memory per mount incarnation until a later hydration of the same path
+ * replaces them or the mount is hydrated outside a cycle (recovery, reset,
+ * configuration), which rewrites the checkout without recording anything.
+ *
+ * The projection reads it as the stale-rewrite detector
+ * (docs/merge-hydration-design.md §3.3): a process that read a file before a
+ * hydration and re-emits the same bytes afterwards would otherwise publish a
+ * revert of the inbound change as an ordinary local edit. A changed file whose
+ * content hashes to the blob hydration replaced is exactly that, so the mount
+ * is pinned instead of published, loudly.
+ *
+ * Deliberately not persisted: a restart loses the entries and the detector is
+ * best effort. Phase 2 of the design turns this into a durable ledger if
+ * telemetry warrants it.
+ */
+export declare class WorkspaceHydrationPreBlobLedger {
+    private readonly mounts;
+    private static key;
+    /** Blob ids by mount-relative path for the mount, or an empty map. */
+    preBlobs(mount: {
+        id: string;
+        hydrationIncarnationKey: string;
+    }): ReadonlyMap<string, string>;
+    /** Record the pre-hydration blob of every path a merge hydration replaced; earlier entries for other paths are kept. */
+    record(mount: {
+        id: string;
+        hydrationIncarnationKey: string;
+    }, preBlobs: ReadonlyMap<string, string> | Readonly<Record<string, string>>): void;
+    /** Forget the mount: its checkout was rewritten by something this ledger did not observe. */
+    clearMount(mount: {
+        id: string;
+        hydrationIncarnationKey: string;
+    }): void;
+    /** Forget paths whose checkout content moved on from the hydrated bytes: a later return to the old bytes is a deliberate edit. */
+    forget(mount: {
+        id: string;
+        hydrationIncarnationKey: string;
+    }, paths: readonly string[]): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/types/workspace-hydration-merge.d.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import { type PreparedWorkingTreeMirror, type ProjectedWorkingTreeEntry, type WorkingTreeMirrorOverride, type WorkingTreeMirrorSelection } from "./working-tree-mirror";
+/**
+ * Where a mount's bytes were read this cycle (docs/merge-hydration-design.md
+ * §2.1). `projectedCommit` is the commit whose subtree at the mount path is
+ * exactly what projection read: the projected head for a mirrored mount, the
+ * synthesized ours commit for a merge-projected one. `projectedFiles` is
+ * what the mirror or synthesis saw for each entry, or null when the mount was
+ * not read this cycle (its token was unchanged), in which case a changed
+ * file is recognized by hashing it against the projected blob.
+ */
+export type WorkspaceHydrationMergeBasis = {
+    projectedCommit: string;
+    projectedFiles: Record<string, ProjectedWorkingTreeEntry> | null;
+    /**
+     * Wall-clock time the projection finished reading. A projected stat whose
+     * timestamps fall within `RACY_PROJECTION_WINDOW_MS` of it is not trusted
+     * to prove the file unchanged (git's racy-clean rule: a rewrite of the
+     * same size in the same coarse timestamp tick leaves the stat intact), so
+     * such a file is hashed against the projected blob instead.
+     */
+    readAtMs?: number;
+};
+export declare const RACY_PROJECTION_WINDOW_MS = 2000;
+export type WorkspaceHydrationSkipReason = "hydration_merge_conflict" | "hydration_target_changed";
+/** A mount merge hydration left at its previous receipt entry, and why. */
+export type WorkspaceHydrationMountSkip = {
+    mountId: string;
+    reason: WorkspaceHydrationSkipReason;
+    paths: string[];
+};
+/** One path whose blob differs between the projected subtree (base) and the hydration head's subtree (theirs). */
+export type WorkspaceSubtreeChange = {
+    base: {
+        mode: string;
+        objectId: string;
+    } | null;
+    theirs: {
+        mode: string;
+        objectId: string;
+    } | null;
+};
+export type WorkspaceHydrationMergeDecision = {
+    kind: "conflict";
+    paths: string[];
+} | {
+    kind: "target_changed";
+    paths: string[];
+} | {
+    kind: "apply";
+    selection: WorkingTreeMirrorSelection;
+    overrides: Map<string, WorkingTreeMirrorOverride>;
+    /** The target `lstat` (or absence) every mutated path must still show when it is mutated. */
+    expectations: Map<string, fs.Stats | null>;
+    /** Blob of the bytes each written or removed path held before hydration; the stale-rewrite detector's input. */
+    preBlobs: Map<string, string>;
+    /** Paths whose content was three-way merged. */
+    mergedPaths: string[];
+    /** Paths the checkout changed since projection that hydration leaves as they are. */
+    keptPaths: string[];
+};
+/**
+ * Decide, per path the hydration head changed relative to what projection
+ * read, whether hydration writes theirs (the checkout is unchanged there),
+ * leaves the checkout alone (theirs did not change there), writes a
+ * three-way merge, or cannot proceed (docs/merge-hydration-design.md §2.2,
+ * §2.6). Every path the checkout changed since projection that the head did
+ * not change survives untouched, including files created since. Nothing is
+ * written here; the result drives `applyWorkingTreeMirror` under guards that
+ * re-check each path's `lstat` immediately before mutating it.
+ */
+export declare function decideWorkspaceHydrationMerge(input: {
+    prepared: PreparedWorkingTreeMirror;
+    changes: ReadonlyMap<string, WorkspaceSubtreeChange>;
+    projectedFiles: Readonly<Record<string, ProjectedWorkingTreeEntry>> | null;
+    readAtMs?: number;
+    /** Blob contents by object id, in one batch. */
+    readBaseBlobs: (objectIds: readonly string[]) => Map<string, Buffer>;
+    /** Paths marked -diff on either side must never enter the text merger. */
+    readBinaryPaths?: (relativePaths: readonly string[]) => ReadonlySet<string>;
+}): WorkspaceHydrationMergeDecision;
+/** Batch attribute reads, with NUL delimiters so arbitrary Git filenames stay intact. */
+export declare function readHydrationBinaryPaths(input: {
+    checkoutRoot: string;
+    outerRoot: string;
+    relativePaths: readonly string[];
+}): Set<string>;
+/**
+ * Parse `git diff-tree -r -z --no-renames --raw <base tree> <theirs tree>`
+ * output into per-path changes. Records come in pairs: the status line
+ * (`:<base mode> <theirs mode> <base id> <theirs id> <status>`) and the path.
+ */
+export declare function parseWorkspaceSubtreeChanges(raw: Buffer): Map<string, WorkspaceSubtreeChange>;
+/** The mount-relative path of a checkout entry as its absolute path, for diagnostics. */
+export declare function describeHydrationSkipPaths(mountSourcePath: string, paths: readonly string[]): string;

package/dist/types/workspace-hydration-recovery-state.d.ts

@@ -0,0 +1,10 @@
+/** Wire evidence owned by the standalone worker package; no API runtime dependency. */
+export type WorkerHydrationRecovery = {
+    transactionId: string;
+    transactionPath: string;
+    mountIds: string[];
+    previousHeads: Record<string, string>;
+    retainedPaths?: string[];
+};
+/** Extract durable recovery evidence even through executor/AggregateError wrapping. */
+export declare function findHydrationRecovery(error: unknown): WorkerHydrationRecovery | undefined;

package/dist/types/workspace-merge-projection.d.ts

@@ -1,4 +1,4 @@
-import { type WorkingTreeSourceMode } from "./working-tree-mirror";
+import { type ProjectedWorkingTreeEntry, type WorkingTreeSourceMode } from "./working-tree-mirror";
 export type WorkspaceMergeProjectionSupport = {
     supported: true;
 } | {
@@ -11,15 +11,32 @@ export type WorkspaceMergeProjectionMount = {
     workspaceRelativePath: string;
     sourceMode: WorkingTreeSourceMode;
 };
+/**
+ * `projectedFiles` records what the synthesis read for every visible entry
+ * (merge hydration's basis for "changed since projection"). A `stale_rewrite`
+ * result means the checkout holds, at the listed paths, exactly the bytes the
+ * last hydration replaced; nothing was merged and the mount must stay pinned.
+ */
 export type WorkspaceMergeProjectionResult = {
     kind: "clean";
     resultTree: string;
     oursCommit: string;
+    projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
+    readAtMs: number;
+    /** Ledger paths whose checkout content moved on from both the replaced and the basis bytes (or that are gone). */
+    staleRewriteCleared: string[];
 } | {
     kind: "conflict";
     oursCommit: string;
     conflictPaths: string[];
     error: string;
+    projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
+    readAtMs: number;
+    staleRewriteCleared: string[];
+} | {
+    kind: "stale_rewrite";
+    paths: string[];
+    staleRewriteCleared: string[];
 };
 declare function gitVersionIsSupported(version: string): boolean;
 export declare function workspaceMergeProjectionSupport(): WorkspaceMergeProjectionSupport;
@@ -29,6 +46,7 @@ export declare function mergeWorkspaceProjectionMount(input: {
     basisHead: string;
     currentHead: string;
     attemptId: string;
+    staleRewriteBlobs?: Readonly<Record<string, string>>;
 }): WorkspaceMergeProjectionResult;
 export declare function materializeWorkspaceProjectionTree(input: {
     workspacePath: string;

package/dist/types/workspace-project-config-policy.d.ts

@@ -10,25 +10,39 @@ type ProjectConfiguration = {
     projectId: string;
 };
 type ProjectConfigurationWithBranches = ProjectConfiguration & {
+    executionDisabled?: boolean;
     branches: readonly {
         branchName: string;
     }[];
 };
+/**
+ * Every executable checkout of a configuration whose reconciliation did not
+ * run. Frozen projects expose neither ready nor pending execution targets, so
+ * the report stays inside the server's executable checkout ledger.
+ */
 export declare function deferredProjectConfigurationPendingBranches(projects: readonly ProjectConfigurationWithBranches[]): Array<{
     projectId: string;
     branchName: string;
 }>;
+export type BusyProjectConfigurationChangeReason = "added" | "removed" | "initializing" | "changed";
+export type BusyProjectConfigurationChange = {
+    projectId: string;
+    reason: BusyProjectConfigurationChangeReason;
+};
 /**
  * Identify configuration changes that would touch a project while visible
  * checkout activity is active or reserved. A visible-projects target covers
- * every project; canonical-sync activity is isolated in the outer clone.
+ * every project; canonical-sync activity is isolated in the outer clone. The
+ * reason names why the busy project cannot take the configuration now, so a
+ * deferral can be diagnosed without reconstructing both generations.
  */
-export declare function busyProjectConfigurationChangeIds<TProject extends ProjectConfiguration>(input: {
+export declare function busyProjectConfigurationChanges<TProject extends ProjectConfiguration>(input: {
     currentProjects: readonly TProject[];
     incomingProjects: readonly TProject[];
     activeTargets: Iterable<ProjectTarget | WorkspaceTarget>;
     currentFingerprint: (project: TProject) => string;
     incomingFingerprint: (project: TProject) => string;
     currentProjectReady: (project: TProject) => boolean;
-}): string[];
+}): BusyProjectConfigurationChange[];
+export declare function describeBusyProjectConfigurationChanges(changes: readonly BusyProjectConfigurationChange[]): string;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.131",
+  "version": "0.0.133",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",
@@ -21,7 +21,7 @@
     "r5d-worker": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.131",
+    "@ricsam/r5d-api": "^0.0.133",
     "node-pty": "^1.1.0",
     "picomatch": "^4.0.3"
   },