@ricsam/r5d-worker 0.0.136 → 0.0.138

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

@@ -1,123 +0,0 @@
-import { type WorkspaceFilesystemJobInput, type WorkspaceFilesystemJobKind, type WorkspaceFilesystemJobProgress, type WorkspaceFilesystemJobResult } from "./workspace-filesystem-job-types";
-/**
- * Bounded executor for the worker's workspace filesystem transactions.
- *
- * One thread runs one job at a time; the control thread only ever awaits.
- * The point is the incident this was written for: a single `pread64` or
- * `pwrite64` blocked in the kernel on a stalled network disk used to freeze
- * the worker's only event loop for minutes, so no heartbeat, cancel or Stop
- * could run. On the executor thread that same blocked syscall stalls exactly
- * one job while the control thread keeps serving the socket.
- *
- * A thread rather than a helper process because a thread cannot outlive the
- * process: when the worker dies, its in-flight syscall completes and nothing
- * else is written afterwards, which is the crash model every recovery path
- * already handles. Nothing is ever abandoned: a running job's promise settles
- * only with the thread's reply or the thread's exit, so the gate its caller
- * holds is held for the job's true duration. Only jobs that have not started
- * can fail on the queue-wait bound.
- *
- * A thread that exits while a job is running leaves an unknown partial
- * mutation behind. The executor then fails closed: the job and everything
- * queued fail, no further job is accepted, and `onFailure` lets the worker
- * take its established restart path, whose startup recovery (manifests,
- * receipts, snapshot recovery) runs before any ordinary mutation. No
- * replacement thread is started over that state in this process.
- */
-export declare const WORKSPACE_FILESYSTEM_EXECUTOR_MAX_QUEUED = 32;
-export declare const WORKSPACE_FILESYSTEM_EXECUTOR_QUEUE_TIMEOUT_MS: number;
-export declare const WORKSPACE_FILESYSTEM_EXECUTOR_STALL_LOG_INTERVAL_MS = 30000;
-export declare class WorkspaceFilesystemExecutorError extends Error {
-    readonly name = "WorkspaceFilesystemExecutorError";
-}
-/** The executor thread exited (crashed or was terminated) while a job was running. */
-export declare class WorkspaceFilesystemExecutorThreadExitedError extends WorkspaceFilesystemExecutorError {
-    readonly exitCode: number | null;
-    readonly description: string;
-    constructor(exitCode: number | null, description: string, cause?: unknown);
-}
-export type WorkspaceFilesystemExecutorStatus = {
-    running: {
-        kind: WorkspaceFilesystemJobKind;
-        description: string;
-        startedAtMs: number;
-        ageMs: number;
-    } | null;
-    queued: number;
-    /** Set once the thread exited under a running job; every job is then rejected until the worker restarts. */
-    failed: string | null;
-};
-export type WorkspaceFilesystemExecutorOptions = {
-    /** Module the thread executes; must resolve next to the packaged executor module. */
-    threadModulePath: string;
-    log?: (line: string) => void;
-    now?: () => number;
-    maxQueued?: number;
-    queueTimeoutMs?: number;
-    stallLogIntervalMs?: number;
-};
-export declare class WorkspaceFilesystemExecutor {
-    private readonly threadModulePath;
-    private readonly log;
-    private readonly now;
-    private readonly maxQueued;
-    private readonly queueTimeoutMs;
-    private readonly stallLogIntervalMs;
-    private worker;
-    private readonly queue;
-    private running;
-    private nextJobId;
-    private failed;
-    private closed;
-    /** Invoked once when the executor fails closed (thread exit under a running job). */
-    onFailure: ((error: WorkspaceFilesystemExecutorThreadExitedError) => void) | undefined;
-    constructor(options: WorkspaceFilesystemExecutorOptions);
-    /**
-     * Run one job to completion on the executor thread. Resolves with the
-     * job's result; rejects with the job's own error (properties preserved),
-     * with a queue-wait or capacity error when the job never started, or with
-     * WorkspaceFilesystemExecutorThreadExitedError when the thread died under it.
-     */
-    run<K extends WorkspaceFilesystemJobKind>(kind: K, input: WorkspaceFilesystemJobInput<K>, options?: {
-        onProgress?: (progress: WorkspaceFilesystemJobProgress) => void;
-    }): Promise<WorkspaceFilesystemJobResult<K>>;
-    status(): WorkspaceFilesystemExecutorStatus;
-    /**
-     * Stop accepting jobs, fail everything still queued and ask the thread to
-     * stop. A running job settles when the thread actually exits; a thread
-     * blocked in the kernel only exits with the process, which is the point.
-     */
-    close(): void;
-    private describeRunning;
-    private expireQueued;
-    private dispatch;
-    private settleRunning;
-    private ensureWorker;
-    private lastThreadError;
-    private onReply;
-    private onExit;
-}
-/** The packaged thread module lives next to this module with the same extension (.ts in source, .cjs/.mjs in the package). */
-export declare function workspaceFilesystemExecutorThreadModulePath(): string;
-/** What the engine modules dispatch through; the thread executor in production. */
-export type WorkspaceFilesystemJobRunner = Pick<WorkspaceFilesystemExecutor, "run">;
-/**
- * The worker process's executor. Like the workspace mutation gate it is
- * process-global: in-process reconnects share it, so a job started by a
- * previous connection generation is still the one running when the next
- * generation's configuration queues behind it.
- */
-export declare function workspaceFilesystemExecutor(): WorkspaceFilesystemJobRunner;
-/** The worker runtime's fail-closed hook: installed once on the process executor (created if needed). */
-export declare function installWorkspaceFilesystemExecutorFailureHandler(handler: (error: WorkspaceFilesystemExecutorThreadExitedError) => void): void;
-/**
- * Test seam. Engine tests that inject faults or count syscalls by replacing
- * `node:fs` functions in their own thread cannot observe a body running on
- * the executor thread; inside `runJobsInline` the same operation table runs
- * on the calling thread instead. The boundary itself is tested with the real
- * thread in workspace-filesystem-executor.test.ts. Never used in production.
- */
-export declare const workspaceFilesystemExecutorTestHarness: {
-    runJobsInline<T>(body: () => Promise<T>): Promise<T>;
-    processExecutor(): WorkspaceFilesystemExecutor | null;
-};

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

@@ -1,288 +0,0 @@
-import type { ProjectWorktreeBranch, ProjectWorktreeSnapshot, ProjectWorktreeSnapshotProgress, ProjectWorktreeSnapshotScope, ProjectWorktreeWorkingTreeMode } from "./project-worktrees";
-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";
-/**
- * The closed set of filesystem transactions the worker runs on its executor
- * thread. Every input is plain data (paths, mount descriptors, receipts); the
- * busy predicates, mutation tokens, hooks and gates that decide *whether* a
- * job may run stay on the control thread. Every body is the synchronous code
- * that used to run on the control thread, unchanged in its write and fsync
- * ordering. A job kind outside this table is rejected by both threads.
- */
-export type WorkspaceFilesystemJobTable = {
-    /** `recoverWorkspaceCheckoutDurability`: rebuild an interrupted outer checkout boundary. */
-    checkout_durability_recovery: {
-        input: {
-            workspacePath: string;
-            preserveResolutionInProgress: boolean;
-        };
-        result: null;
-    };
-    /** Checkout durability recovery, pending hydration transaction restore/completion, basis-ref repair. */
-    hydration_recovery: {
-        input: {
-            workspacePath: string;
-            preserveResolutionInProgress: boolean;
-        };
-        result: null;
-    };
-    /** 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). */
-    hydration_raw: {
-        input: {
-            workspacePath: string;
-            mounts: WorkspaceGitMountData[];
-        };
-        result: {
-            hydratedMountIds: string[];
-        };
-    };
-    /** Recover the durable checkout boundary and record the transition that follows. */
-    checkout_transition_begin: {
-        input: {
-            workspacePath: string;
-        };
-        result: null;
-    };
-    /** Make the outer checkout durable and record its head as the durable boundary. */
-    checkout_transition_complete: {
-        input: {
-            workspacePath: string;
-        };
-        result: null;
-    };
-    /** Durability barrier over the outer checkout tree without changing the record. */
-    outer_checkout_fsync: {
-        input: {
-            workspacePath: string;
-        };
-        result: null;
-    };
-    /** Three-way merge projection of one stale mount (ours snapshot + merge-tree). */
-    projection_merge: {
-        input: {
-            workspacePath: string;
-            mount: WorkspaceMergeProjectionMount;
-            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. 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. */
-    projection_outer_apply: {
-        input: {
-            workspacePath: string;
-            removeMounts: WorkspaceGitMountData[];
-            materialize: Array<{
-                workspaceRelativePath: string;
-                resultTree: string;
-            }>;
-            restoreFromHead: WorkspaceGitMountData[];
-        };
-        result: null;
-    };
-    /** Persist projected visible mounts and publish the projection receipt. */
-    projection_receipt: {
-        input: {
-            workspacePath: string;
-            fsyncMounts: WorkspaceGitMountData[];
-            receipt: WorkspaceHydrationReceipt;
-        };
-        result: null;
-    };
-    /** `snapshotBranchTrees`: copy every checkout a reconciliation may rewrite. */
-    project_snapshot_create: {
-        input: {
-            projectRoot: string;
-            branches: ProjectWorktreeBranch[];
-            temporaryRoot: string;
-            scope: ProjectWorktreeSnapshotScope;
-            ownerSessionId: string;
-        };
-        result: ProjectWorktreeSnapshot;
-    };
-    /** Mirror captured checkouts back over the reconciled worktrees. */
-    project_snapshot_apply: {
-        input: {
-            mirrors: Array<{
-                snapshotPath: string;
-                targetPath: string;
-            }>;
-        };
-        result: null;
-    };
-    /** `persistReconciledProjectAndConsumeSnapshot`. */
-    project_snapshot_persist: {
-        input: {
-            snapshot: ProjectWorktreeSnapshot;
-            durabilityPaths: string[] | null;
-        };
-        result: null;
-    };
-    /** `rollbackProjectWorktreeSnapshot`. */
-    project_snapshot_rollback: {
-        input: {
-            snapshot: ProjectWorktreeSnapshot;
-        };
-        result: null;
-    };
-    /** `recoverStaleProjectWorktreeSnapshots` at startup. */
-    project_snapshots_recover: {
-        input: {
-            projectsRoot: string;
-            temporaryRoot: string;
-            currentProcessId: number;
-            currentOwnerSessionId: string;
-        };
-        result: {
-            restored: string[];
-            removed: string[];
-            failed: Array<{
-                path: string;
-                error: string;
-            }>;
-        };
-    };
-    /** `createLinkedProjectBranch`: branch ref, linked worktree, index seed and working-tree copy. */
-    project_branch_create: {
-        input: {
-            projectRoot: string;
-            sourceBranchName: string;
-            branchName: string;
-            workingTree: ProjectWorktreeWorkingTreeMode;
-        };
-        result: {
-            branchPath: string;
-            baseCommitHash: string;
-        };
-    };
-    /** `preserveProjectCheckoutPathMove`. */
-    project_checkout_path_move: {
-        input: {
-            oldProjectRoot: string;
-            newProjectRoot: string;
-            projectsDurabilityRoot: string;
-            outerWorkspaceRoot: string;
-            branches: ProjectCheckoutPathMoveBranch[];
-        };
-        result: {
-            preservedBranchNames: string[];
-        };
-    };
-};
-export type WorkspaceFilesystemJobKind = keyof WorkspaceFilesystemJobTable;
-export type WorkspaceFilesystemJobInput<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["input"];
-export type WorkspaceFilesystemJobResult<K extends WorkspaceFilesystemJobKind> = WorkspaceFilesystemJobTable[K]["result"];
-export type WorkspaceFilesystemJobProgress = ProjectWorktreeSnapshotProgress;
-export type WorkspaceFilesystemJobContext = {
-    progress: (progress: WorkspaceFilesystemJobProgress) => void;
-};
-export type WorkspaceFilesystemJobOperations = {
-    [K in WorkspaceFilesystemJobKind]: (input: WorkspaceFilesystemJobInput<K>, context: WorkspaceFilesystemJobContext) => WorkspaceFilesystemJobResult<K>;
-};
-export declare const WORKSPACE_FILESYSTEM_JOB_KINDS: readonly WorkspaceFilesystemJobKind[];
-export declare function isWorkspaceFilesystemJobKind(value: unknown): value is WorkspaceFilesystemJobKind;
-/** Short, path-bearing description used in stall diagnostics and errors. */
-export declare function describeWorkspaceFilesystemJob<K extends WorkspaceFilesystemJobKind>(kind: K, input: WorkspaceFilesystemJobInput<K>): string;
-/** Errors cross the thread boundary as data; the properties callers inspect are preserved. */
-export type WorkspaceFilesystemSerializedError = {
-    name: string;
-    message: string;
-    stack?: string;
-    code?: string;
-    branchMayExist?: true;
-    cleanupFailures?: string[];
-    hydrationRecovery?: WorkspaceHydrationRecoveryRequired;
-    errors?: WorkspaceFilesystemSerializedError[];
-    cause?: WorkspaceFilesystemSerializedError;
-};
-export declare function serializeWorkspaceFilesystemError(error: unknown, depth?: number): WorkspaceFilesystemSerializedError;
-export declare function restoreWorkspaceFilesystemError(serialized: WorkspaceFilesystemSerializedError): Error;
-/** Control thread → executor thread. */
-export type WorkspaceFilesystemThreadRequest = {
-    type: "run";
-    id: number;
-    kind: WorkspaceFilesystemJobKind;
-    input: unknown;
-    /** The control thread's environment at dispatch; the thread runs the job under exactly this. */
-    environment: Record<string, string>;
-};
-/** Executor thread → control thread. */
-export type WorkspaceFilesystemThreadReply = {
-    type: "progress";
-    id: number;
-    progress: WorkspaceFilesystemJobProgress;
-} | {
-    type: "result";
-    id: number;
-    result: unknown;
-} | {
-    type: "failure";
-    id: number;
-    error: WorkspaceFilesystemSerializedError;
-};

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

@@ -1,7 +0,0 @@
-import type { WorkspaceFilesystemJobOperations } from "./workspace-filesystem-job-types";
-/**
- * The operation table of the workspace filesystem executor thread. It is the
- * only thing the thread can run; every entry is an existing synchronous
- * transaction body. Imported by the thread entry module only.
- */
-export declare const workspaceFilesystemJobOperations: WorkspaceFilesystemJobOperations;