@ricsam/r5d-worker 0.0.101 → 0.0.104

package/dist/types/workspace-mutation-gate.d.ts

@@ -3,9 +3,20 @@ export type WorkspaceMutationLease = () => void;
  * Coordinates project worktrees with the outer workspace Git clone.
  *
  * Ordinary worktree activity may overlap other ordinary activity, but a sync
- * gets exclusive access. Once a sync is queued, later mutations wait behind it
- * so a queued sync cannot be starved by later short mutations. Long-running
- * long-running project commands do not enter this gate; outer-workspace
+ * gets exclusive access. Once a sync is queued, later ordinary mutations wait
+ * behind it so a queued sync cannot be starved by later short mutations.
+ *
+ * Branch creation and deletion use their own lane: a branch mutation never
+ * waits behind a queued sync, only behind a sync that is already running.
+ * Every sync still gets exclusive access, so hydration cannot overlap a
+ * worktree being created or removed; the lane only decides ordering between
+ * cycles. Branch operations are short and rare, so the queued sync they
+ * step in front of waits at most their own duration. Without the lane a
+ * branch operation queued behind a backlog of syncs waited for every one of
+ * them, outlived the server's operation timeout, and then ran anyway against
+ * a request the server had already rolled back.
+ *
+ * Long-running project commands do not enter this gate; outer-workspace
  * remediation commands do because they operate on the sync clone itself.
  */
 export declare class WorkspaceMutationGate {
@@ -15,6 +26,16 @@ export declare class WorkspaceMutationGate {
     acquireMutation(): Promise<WorkspaceMutationLease>;
     runMutation<T>(operation: () => Promise<T> | T): Promise<T>;
     runSync<T>(operation: () => Promise<T> | T): Promise<T>;
+    /** A worktree create/delete lease; see the branch lane in the class comment. */
+    acquireBranchMutation(): Promise<WorkspaceMutationLease>;
+    runBranchMutation<T>(operation: () => Promise<T> | T): Promise<T>;
+    /**
+     * Operations a branch mutation requested now would wait for: the running
+     * sync, if any, plus branch mutations queued behind it. Zero means it runs
+     * at once. Ordinary waiters are not counted because the branch lane admits
+     * ahead of them.
+     */
+    branchMutationQueuePosition(): number;
     private drain;
     private releaseMutation;
     private releaseSync;

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

@@ -0,0 +1,59 @@
+export type WorkspaceProjectionLedgerMount = {
+    id: string;
+    /** Durable logical incarnation; a re-created branch never matches its predecessor's record. */
+    hydrationIncarnationKey: string;
+    mutationToken?: () => string;
+};
+/**
+ * Remembers, per mount incarnation, the visible-mutation token observed when
+ * the mount was last projected into the outer clone by a completed cycle,
+ * together with that cycle's result.
+ *
+ * Two decisions read it. A cycle skips mirroring a mount whose token is
+ * unchanged, because its outer subtree already carries those bytes. A
+ * request that targets a project checkout is answered with the previous
+ * cycle's result, without running a cycle, when no mount's token moved since
+ * that cycle. Both are cross-cycle skips only; the within-cycle busy and
+ * token re-checks in the sync engine stay as they are.
+ *
+ * The ledger is reset whenever something other than a recorded visible
+ * mutation can change checkout bytes: workspace configuration, canonical
+ * reset, outer remediation, branch creation or deletion, and any cycle that
+ * failed or ended in a conflict.
+ */
+export declare class WorkspaceProjectionLedger<Result extends {
+    outcome: string;
+}> {
+    private readonly projectedTokens;
+    private lastCycle;
+    private static recordKey;
+    get lastCycleResult(): Result | null;
+    lastProjectedToken(mount: {
+        id: string;
+        hydrationIncarnationKey: string;
+    }): string | undefined;
+    /**
+     * Record a completed cycle. `projectedMutationTokens` names the token each
+     * active mount carried when the cycle projected it; a mount absent from it
+     * keeps its earlier record. Any outcome that leaves the outer clone without
+     * a trustworthy projection clears the ledger.
+     */
+    recordCycle(input: {
+        result: Result;
+        mounts: readonly WorkspaceProjectionLedgerMount[];
+        projectedMutationTokens: Readonly<Record<string, string>> | undefined;
+    }): void;
+    reset(): void;
+    /**
+     * The previous cycle's result when every request targets a configured
+     * mount and no mount's token moved since its recorded projection. A request
+     * without a target (a workspace-rooted command may touch any checkout), a
+     * mount without a token (a pending deletion), or pending deletion work all
+     * require a real cycle.
+     */
+    answerFromLastCycle(input: {
+        targetMountIds: ReadonlyArray<string | null>;
+        mounts: readonly WorkspaceProjectionLedgerMount[];
+        pendingDeletions: boolean;
+    }): Result | null;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Batches ordinary workspace synchronization requests into one exclusive
+ * cycle each. A request that arrives while a batch is queued but not yet
+ * running joins that batch; a request that arrives while a batch is running
+ * opens the next one, because the running cycle may have selected its mounts
+ * before the request's command finished. Every request in a batch receives
+ * the same settlement, and the caller fans that out per attempt.
+ *
+ * Before this, every finished command queued its own full cycle behind every
+ * earlier one, so queue time grew without bound under a steady arrival rate
+ * even though each cycle finished in seconds.
+ */
+export declare class WorkspaceSyncCoalescer<Request, Settlement> {
+    private readonly options;
+    private pendingBatch;
+    private batchesStarted;
+    constructor(options: {
+        /** The exclusive sync lease; the batch body runs inside it. */
+        runExclusive: <T>(operation: () => Promise<T>) => Promise<T>;
+        /** Runs (or answers without running) one cycle for the whole batch. */
+        runBatch: (requests: readonly Request[]) => Promise<Settlement>;
+    });
+    /** Requests attached to the batch that has not started yet. */
+    get queuedRequestCount(): number;
+    /** Batches whose body has been entered, whether or not they ran a cycle. */
+    get startedBatchCount(): number;
+    request(request: Request): Promise<Settlement>;
+}

package/package.json

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