@ricsam/r5d-worker 0.0.97 → 0.0.100

package/dist/types/working-tree-mirror.d.ts

@@ -20,7 +20,14 @@ export type TreeEntry = {
  * every portable alias must be remediated before the old tree is retired.
  */
 export declare function assertWorkingTreeHasNoPortableGitMetadataAliases(root: string): void;
-export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode): Map<string, TreeEntry>;
+export declare function inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: {
+    /**
+     * Leave an uninitialized submodule (index gitlink whose directory is
+     * empty) out of a Git-mode inspection. Its empty directory is what keeps
+     * `git status` clean, so a deletion set must never remove it.
+     */
+    omitUnpopulatedGitlinks?: boolean;
+}): Map<string, TreeEntry>;
 export declare function mirrorWorkingTree(input: {
     sourceRoot: string;
     targetRoot: string;
@@ -35,3 +42,75 @@ export declare function mirrorWorkingTree(input: {
 }): {
     paths: string[];
 };
+/** Canonical relative form used by mirror plans and scopes, or null when the value is unsafe. */
+export declare function normalizeWorkingTreeRelativePath(value: string): string | null;
+export type WorkingTreeMirrorPlan = {
+    /** Every target path the mirror creates, rewrites, or verifies, ancestor directories included. */
+    desired: Map<string, TreeEntry>;
+    /**
+     * Target entries the mirror removes or overwrites, as they are before it
+     * runs. A directory entry means the whole subtree goes, ignored files
+     * included; entries beneath it are folded into it.
+     */
+    replaced: Map<string, TreeEntry>;
+    /** Desired paths that have no target entry yet. */
+    absent: string[];
+};
+/**
+ * Compute exactly which target entries `mirrorWorkingTree` would remove,
+ * overwrite, or create for the same input, without changing anything. The
+ * removal set is the target's deletion-mode file set minus the desired paths.
+ * A desired path replaces its target entry when the kinds differ, a symlink
+ * points elsewhere, or a file's bytes or mode differ; an equal entry is left
+ * alone, so the plan covers only what the mirror actually touches. A Git
+ * target's ignored trees appear only where a desired path lands on them.
+ */
+export declare function planWorkingTreeMirror(input: {
+    sourceRoot: string;
+    targetRoot: string;
+    sourceMode: WorkingTreeSourceMode;
+    deletionMode: WorkingTreeDeletionMode;
+}): WorkingTreeMirrorPlan;
+export type WorkingTreeMirrorScope = {
+    /** Desired paths that did not exist before the mirror ran; a restore removes them. */
+    absent: string[];
+    /** Directories captured whole; a restore makes them identical to the snapshot again. */
+    trees: string[];
+};
+/**
+ * Copy the entries a mirror plan replaces into `snapshotRoot` at their
+ * target-relative paths, so that `restoreWorkingTreeMirrorScope` can undo the
+ * mirror. Files and symlinks are copied individually and a replaced directory
+ * is copied whole; ancestor directories appear only as containers. Returns
+ * the scope that must be kept beside the snapshot.
+ */
+export declare function captureWorkingTreeMirrorPlan(input: {
+    plan: WorkingTreeMirrorPlan;
+    targetRoot: string;
+    snapshotRoot: string;
+    durability?: WorkingTreeMirrorDurability;
+}): WorkingTreeMirrorScope;
+/**
+ * Undo a mirror whose plan was captured with `captureWorkingTreeMirrorPlan`:
+ * remove everything the mirror may have created, sweep its interrupted
+ * temporary files, and put every captured entry back. Entries the plan did
+ * not cover (a Git target's ignored files, for instance) are never read or
+ * written. Safe to repeat after a partial run. Returns the target-relative
+ * paths it removed or restored, for the caller's durability barrier.
+ */
+export declare function restoreWorkingTreeMirrorScope(input: {
+    snapshotRoot: string;
+    targetRoot: string;
+    scope: WorkingTreeMirrorScope;
+}): {
+    paths: string[];
+};
+/**
+ * Make the listed target-relative entries durable together with the directory
+ * entries that name them: every listed regular file and real directory is
+ * fsynced, and so is each listed path's parent directory and the root.
+ * Symlinks and missing paths contribute only their parent, which is what
+ * records their creation or removal. Ancestors are never followed through
+ * symlinks. Nothing outside the listed paths is read.
+ */
+export declare function fsyncWorkingTreePaths(root: string, relativePaths: Iterable<string>): void;

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

@@ -49,6 +49,26 @@ export type WorkspaceGitMount = {
  * unready state for concurrent visible work.
  */
 export declare function workspaceGitMountsForRemediation(mounts: readonly WorkspaceGitMount[]): WorkspaceGitMount[];
+export type WorkspaceHydrationTransactionContext = {
+    /** Unique per transaction; pairs the begin and end observations. */
+    transactionId: string;
+    workspacePath: string;
+    /** Mounts the transaction may hydrate or carry across the durability barrier. */
+    mountIds: string[];
+};
+/**
+ * Observes the synchronous body of a hydration transaction (snapshot,
+ * hydration pass, durability barrier, receipt). That body deliberately never
+ * yields, so the worker cannot answer control-socket messages while it runs,
+ * and on a slow disk it can run for hours. `beforeTransaction` is awaited
+ * after the last asynchronous precheck and before the final busy observation,
+ * so it may announce the operation and yield once; `afterTransaction` runs
+ * after the body committed or rolled back.
+ */
+export type WorkspaceHydrationTransactionHooks = {
+    beforeTransaction: (context: WorkspaceHydrationTransactionContext) => Promise<void> | void;
+    afterTransaction: (context: WorkspaceHydrationTransactionContext) => void;
+};
 export type WorkspaceGitSyncOutcome = "no_change" | "updated" | "pushed" | "large_diff_blocked" | "conflict_blocked";
 export type WorkspaceGitSyncResult = {
     outcome: WorkspaceGitSyncOutcome;
@@ -137,6 +157,7 @@ export declare function ensureWorkspaceGitClone(input: {
 declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     hydratedMountIds: string[];
     skippedMountIds: string[];
@@ -146,6 +167,7 @@ export declare function recoverWorkspaceGitHydration(workspacePath: string, moun
     deferMountIds?: ReadonlySet<string>;
     preserveResolutionInProgress?: boolean;
     preserveStaleBases?: boolean;
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<void>;
 export declare function resetWorkspaceGit(input: {
     workspacePath: string;
@@ -157,6 +179,7 @@ export declare function resetWorkspaceGit(input: {
         email: string;
     };
     mounts: readonly WorkspaceGitMount[];
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     startingHead: string | null;
     localHead: string | null;
@@ -194,6 +217,8 @@ export declare function synchronizeWorkspaceGit(input: {
         publishedHead: string;
         activeMountIds: string[];
     }) => void | Promise<void>;
+    /** Announces each synchronous hydration transaction of this cycle; see WorkspaceHydrationTransactionHooks. */
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<WorkspaceGitSyncResult>;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.97",
+  "version": "0.0.100",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",