@ricsam/r5d-worker 0.0.99 → 0.0.101

package/dist/types/main.d.ts

@@ -2,6 +2,7 @@
 import { Database } from "bun:sqlite";
 import type { WorkerGitIdentity } from "./git-identity";
 import { configureGitHubRegistryAuthFiles, type PreparedPrivateAuthFileGeneration } from "./registry-auth";
+import { type WorkspaceHydrationTransactionHooks } from "./workspace-git-sync";
 type WorkerProjectConfig = {
     projectId: string;
     checkoutPathSegments: [namespace: string, project: string];
@@ -23,6 +24,11 @@ type WorkerProjectConfig = {
         baseCommitHash: string;
     }>;
 };
+type WorkerAheadOfOriginBranch = {
+    projectId: string;
+    branchName: string;
+    ahead: number;
+};
 type WorkerLifecycleProgress = {
     phase: "starting" | "recovering" | "configuring" | "syncing" | "ready" | "failed";
     operationId: string;
@@ -39,9 +45,28 @@ declare function workerServerHeartbeatAction(input: {
     timeoutMs: number;
     watchdogSweepDelayed: boolean;
 }): "wait" | "start_probe" | "terminate";
+/**
+ * A hydration transaction blocks this event loop until it ends, so no pong,
+ * progress, or result can leave the process while it runs; on a slow disk
+ * that is hours. Declare a hydration heartbeat lease first: the server keeps
+ * the control socket open and defers the affected request deadlines while the
+ * lease is active instead of reading the silence as a dead worker, which is
+ * what turned one slow hydration into a mandatory canonical reset (incident
+ * 3bccab03). Bun writes the frame to the socket synchronously; the extra
+ * event-loop turn lets control messages that were already queued run before
+ * the busy observation that precedes the transaction body.
+ */
+declare function createWorkspaceHydrationLeaseHooks(send: (message: Extract<WorkerClientMessage, {
+    type: "heartbeat_lease";
+}>) => void, options?: {
+    yieldToEventLoop?: () => Promise<void>;
+    log?: (line: string) => void;
+    now?: () => number;
+}): WorkspaceHydrationTransactionHooks;
 export declare const workerLifecycleTestHarness: {
     boundedWorkerLifecycleProgress: typeof boundedWorkerLifecycleProgress;
     workerServerHeartbeatAction: typeof workerServerHeartbeatAction;
+    createWorkspaceHydrationLeaseHooks: typeof createWorkspaceHydrationLeaseHooks;
 };
 type WorkspaceSyncTrigger = {
     type: "connect" | "inbound_head" | "write" | "edit" | "shell_inline" | "process_terminal" | "process_cancel" | "periodic" | "manual" | "remediation" | "remediation_confirm" | "remediation_reset";
@@ -103,6 +128,144 @@ export type WorkerSessionTarget = {
     ownerUserId: string;
     rootProfile: "visible_projects" | "canonical_sync";
 };
+type WorkerClientMessage = {
+    type: "hello";
+    hostInfo?: Record<string, unknown>;
+    startupReady?: boolean;
+} | {
+    type: "worker_progress";
+    progress: WorkerLifecycleProgress;
+} | {
+    type: "heartbeat_lease";
+    operationId: string;
+    active: boolean;
+    /** A hydration transaction may block the worker for hours; the server bounds it separately from preparation leases. */
+    kind?: "hydration";
+} | {
+    type: "startup_ready";
+} | {
+    type: "active_processes";
+    processes: Array<{
+        runId: string;
+        target: WorkerSessionTarget;
+        sessionId: string;
+        platform: string;
+        arch: string;
+        mode: "foreground" | "detached";
+        pid?: number;
+        processGroupId?: number;
+        credentialId?: string;
+        argv: string[];
+        command: string;
+        cwd?: string;
+        startedAt: string;
+        interactive?: boolean;
+        workspaceEffect?: "none";
+    }>;
+} | {
+    type: "pty_opened";
+    requestId: string;
+    ptyId: string;
+} | {
+    type: "pty_output";
+    ptyId: string;
+    data: string;
+} | {
+    type: "pty_exit";
+    ptyId: string;
+    exitCode: number;
+    signal?: number | string;
+} | {
+    type: "pty_error";
+    ptyId: string;
+    requestId?: string;
+    error: string;
+} | {
+    type: "operation_result";
+    requestId: string;
+    result?: WorkerOperationResult;
+    error?: string;
+} | {
+    type: "exec_result";
+    requestId: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs?: number;
+    error?: string;
+} | {
+    type: "exec_accepted";
+    requestId: string;
+    runId: string;
+} | {
+    type: "exec_started";
+    requestId: string;
+    runId: string;
+    cwd: string;
+    pid?: number;
+    processGroupId?: number;
+} | {
+    type: "exec_start_error";
+    requestId: string;
+    runId: string;
+    error: string;
+} | {
+    type: "exec_output";
+    runId: string;
+    stream: "stdout" | "stderr";
+    data: string;
+} | {
+    type: "exec_exit";
+    runId: string;
+    exitCode: number;
+    durationMs?: number;
+    timedOut?: boolean;
+    workspaceEffect?: "none";
+    canonicalWorkspaceHead?: string;
+} | {
+    type: "exec_error";
+    runId: string;
+    error: string;
+    durationMs?: number;
+    workspaceEffect?: "none";
+    canonicalWorkspaceHead?: string;
+} | {
+    type: "cancel_result";
+    requestId: string;
+    runId: string;
+    cancelled: boolean;
+    message?: string;
+} | {
+    type: "pong";
+} | {
+    type: "workspace_configured";
+    requestId: string;
+    result: WorkspaceSyncResult;
+    pendingCheckouts: Array<{
+        projectId: string;
+        branchName: string;
+    }>;
+    aheadOfOriginBranches: WorkerAheadOfOriginBranch[];
+    deferredWorkspaceSyncForIncidentId?: string;
+} | {
+    type: "workspace_sync_started";
+    attemptId: string;
+} | {
+    type: "workspace_sync_result";
+    requestId?: string;
+    result: WorkspaceSyncResult;
+} | {
+    type: "session_artifacts_sync_result";
+    requestId: string;
+    sessionId: string;
+    error?: string;
+} | {
+    type: "update_clis_result";
+    requestId: string;
+    installedWorkerVersion?: string;
+    installedR5dctlVersion?: string;
+    error?: string;
+};
 type WorkerServerMessage = {
     type: "connected";
     label: string;
@@ -371,6 +534,23 @@ type WorkerViewFileBytesResult = {
     width: number;
     height: number;
 };
+type WorkerExecStdinAck = {
+    type: "exec_stdin";
+    runId: string;
+    bytesWritten: number;
+    eof: boolean;
+};
+type WorkerCreateProjectBranchResult = {
+    type: "create_project_branch";
+    branchId: string;
+    branchName: string;
+    baseCommitHash: string;
+};
+type WorkerDeleteProjectBranchResult = {
+    type: "delete_project_branch";
+    branchId: string;
+    branchName: string;
+};
 type WorkerCodeEntry = {
     name: string;
     type: "file" | "directory";
@@ -389,6 +569,7 @@ type WorkerCodeReadResult = {
     mtime: string;
     base64: string;
 };
+type WorkerOperationResult = WorkerReadFileResult | WorkerWriteFileResult | WorkerEditFileResult | WorkerGrepResult | WorkerFindResult | WorkerLsResult | WorkerViewFileBytesResult | WorkerExecStdinAck | WorkerCreateProjectBranchResult | WorkerDeleteProjectBranchResult | WorkerCodeListResult | WorkerCodeReadResult;
 declare class WorkspaceSyncAdmissionChangedError extends Error {
     readonly name = "WorkspaceSyncAdmissionChangedError";
 }

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

@@ -12,6 +12,44 @@ export type TreeEntry = {
     kind: "symlink";
     mode: number;
     target: string;
+}
+/**
+ * A submodule (D4): the enclosing repository records a commit at this path
+ * and never its contents. A leaf for every operation here: nothing beneath
+ * it is inspected, copied, captured, removed, or restored.
+ */
+ | {
+    kind: "gitlink";
+    objectId: string;
+};
+export type WorkingTreeGitlink = {
+    relativePath: string;
+    objectId: string;
+};
+/** One index record of a Git checkout, in the form `git update-index --index-info` accepts back. */
+export type WorkingTreeIndexRecord = {
+    mode: string;
+    objectId: string;
+    stage: number;
+    relativePath: string;
+};
+/**
+ * Index entries a Git-target mirror changes: the records it removes or
+ * overwrites (a restore puts them back) and the gitlinks it writes (a restore
+ * drops them first).
+ */
+export type WorkingTreeIndexChanges = {
+    removed: WorkingTreeIndexRecord[];
+    written: WorkingTreeGitlink[];
+};
+export type WorkingTreeInspectionOptions = {
+    /**
+     * Gitlinks the enclosing repository records under an all-mode root, keyed
+     * by relative path. Git checks a submodule out as an empty directory, so
+     * the filesystem alone cannot show one; the entry replaces whatever is on
+     * disk at that path. Ignored in Git mode, where the index is read directly.
+     */
+    gitlinks?: ReadonlyMap<string, string>;
 };
 /**
  * Destructive native-tree moves cannot silently apply the Git-target filter:
@@ -20,19 +58,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, 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 inspectWorkingTree(root: string, mode: WorkingTreeSourceMode, options?: WorkingTreeInspectionOptions): Map<string, TreeEntry>;
 export declare function mirrorWorkingTree(input: {
     sourceRoot: string;
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
+    /** Gitlinks the enclosing repository records for an all-mode source (see `inspectWorkingTree`). */
+    sourceGitlinks?: ReadonlyMap<string, string>;
     /**
      * Defer destination fsync only while building an unpublished private tree.
      * The caller must durably fsync that complete tree before publishing it or
@@ -41,20 +74,28 @@ export declare function mirrorWorkingTree(input: {
     durability?: WorkingTreeMirrorDurability;
 }): {
     paths: string[];
+    gitlinks: WorkingTreeGitlink[];
 };
 /** 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. */
+    /**
+     * Every target path the mirror creates, rewrites, or verifies, ancestor
+     * directories included. A gitlink is verified as a directory; paths a
+     * submodule directory on the target shields are left out.
+     */
     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.
+     * included; entries beneath it are folded into it. Never a gitlink: a
+     * submodule directory stays, and only its index entry can change.
      */
     replaced: Map<string, TreeEntry>;
     /** Desired paths that have no target entry yet. */
     absent: string[];
+    /** Index entries the mirror changes on a Git target; empty for any other target. */
+    index: WorkingTreeIndexChanges;
 };
 /**
  * Compute exactly which target entries `mirrorWorkingTree` would remove,
@@ -63,19 +104,23 @@ export type WorkingTreeMirrorPlan = {
  * 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.
+ * target's ignored trees appear only where a desired path lands on them, and
+ * its submodule directories only as index changes.
  */
 export declare function planWorkingTreeMirror(input: {
     sourceRoot: string;
     targetRoot: string;
     sourceMode: WorkingTreeSourceMode;
     deletionMode: WorkingTreeDeletionMode;
+    sourceGitlinks?: ReadonlyMap<string, string>;
 }): 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[];
+    /** Index entries the mirror changed on a Git target; a restore drops the written gitlinks and puts the removed records back. */
+    index?: WorkingTreeIndexChanges;
 };
 /**
  * Copy the entries a mirror plan replaces into `snapshotRoot` at their

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

@@ -1,4 +1,4 @@
-import { type WorkingTreeSourceMode } from "./working-tree-mirror";
+import { type WorkingTreeGitlink, type WorkingTreeSourceMode } from "./working-tree-mirror";
 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";
@@ -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;
@@ -134,9 +154,19 @@ export declare function ensureWorkspaceGitClone(input: {
     localHead: string | null;
     remoteHead: string | null;
 }>;
-declare function mirrorMountsToWorkspace(workspacePath: string, mounts: readonly WorkspaceGitMount[]): void;
+type ProjectedMountGitlinks = {
+    mount: WorkspaceGitMount;
+    gitlinks: WorkingTreeGitlink[];
+};
+/**
+ * Mirror each mount's visible tree into the outer worktree. A submodule
+ * 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[];
 export declare function hydrateWorkspaceGitMounts(workspacePath: string, mounts: readonly WorkspaceGitMount[], options?: {
     ignoreBusy?: boolean;
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     hydratedMountIds: string[];
     skippedMountIds: string[];
@@ -146,6 +176,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 +188,7 @@ export declare function resetWorkspaceGit(input: {
         email: string;
     };
     mounts: readonly WorkspaceGitMount[];
+    hydrationHooks?: WorkspaceHydrationTransactionHooks;
 }): Promise<{
     startingHead: string | null;
     localHead: string | null;
@@ -165,6 +197,12 @@ export declare function resetWorkspaceGit(input: {
     activeMountIds: string[];
     skippedMountIds: string[];
 }>;
+/**
+ * Bytes of the raw `git diff --binary` between two revisions, capped at
+ * `limit + 1`. `pathspecs` narrows what is measured; callers pass
+ * `:(exclude,literal)<path>` for paths whose text is not publication content,
+ * such as a subtree a gitlink replaces (see `pathsReplacedByGitlinks`).
+ */
 declare function diffSizeBytes(workspacePath: string, baseRevision: string | null, headRevision: string, limit: number, pathspecs?: readonly string[]): Promise<number>;
 export declare function synchronizeWorkspaceGit(input: {
     attemptId?: string;
@@ -194,6 +232,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.99",
+  "version": "0.0.101",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",