@ricsam/r5d-worker 0.0.101 → 0.0.103

package/dist/types/project-mirror-fetch-policy.d.ts

@@ -1,20 +1,28 @@
 /**
- * Decides whether a periodic observation must fetch a project's hidden mirror
- * or may reuse the locally cached mirror refs. The server advertises a
- * content-derived token per project (hash of the exact ref namespaces the
- * observation fetch would transfer); when the advertised token equals the
- * token the local refs already cover, the fetch would be a no-op.
+ * Decides which part of a project's hidden mirror a periodic observation must
+ * fetch, from the tokens the server advertises and the tokens the worker's
+ * own mirror refs cover (both computed with `project-mirror-refs-token.ts`).
  *
- * Skipping is fail-open: any missing or mismatched information fetches. The
- * backstop bounds the damage of a server-side token bug (for example a token
- * computed against the wrong repository path) to one interval; every
- * git-transport writer is observed by the server's on-disk recompute, so the
- * backstop is insurance against bugs, not against known unobserved writers.
+ * Skipping is fail-open: any missing or mismatched information fetches.
+ *
+ * There is deliberately no timed backstop refetch for matching tokens. The
+ * server recomputes every advertised token from the canonical repository on
+ * disk on each heartbeat sweep, so a matching token is a fresh statement that
+ * the fetch would transfer nothing, whoever moved the refs. The worker
+ * records the tokens it covers from its own refs after every fetch and lease
+ * push, with the same shared formula, so a skip can only be stale if the
+ * canonical repository moved after the sweep that produced the advertisement
+ * — which the next sweep corrects, exactly like a tip that lands mid-cycle —
+ * or if the formula itself were wrong, which the shared module and its locked
+ * vectors guard and a periodic blind fetch would only hide. A project or
+ * mount the server advertises no token for fetches every cycle, as before
+ * tokens existed.
  */
-export declare const PROJECT_MIRROR_FETCH_BACKSTOP_MS: number;
+/** Why a fetch runs. `fail_closed` is never decided here: reset and remediation observation bypasses the gate. */
+export type ProjectMirrorFetchReason = "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "fail_closed";
 export type ProjectMirrorFetchDecision = {
     fetch: true;
-    reason: "skipping_disabled" | "no_advertised_token" | "never_fetched" | "token_changed" | "backstop_elapsed";
+    reason: ProjectMirrorFetchReason;
 } | {
     fetch: false;
     reason: "token_match";
@@ -22,8 +30,55 @@ export type ProjectMirrorFetchDecision = {
 export declare function projectMirrorFetchDecision(input: {
     advertisedToken: string | undefined;
     fetchedToken: string | undefined;
-    lastFetchAtMs: number | undefined;
-    nowMs: number;
     skippingEnabled: boolean;
-    backstopMs?: number;
 }): ProjectMirrorFetchDecision;
+export type ProjectMirrorObservationFetchPlan = 
+/** Fetch every canonical ref of the project, as observation always did before per-mount tokens. */
+{
+    scope: "project";
+    reason: ProjectMirrorFetchReason;
+}
+/** Fetch only the named mounts' branch heads and handoff refs. */
+ | {
+    scope: "mounts";
+    mounts: Array<{
+        branchName: string;
+        reason: ProjectMirrorFetchReason;
+    }>;
+}
+/** Every token the observation depends on matches; reuse the local refs. */
+ | {
+    scope: "none";
+};
+/**
+ * Plan one project's observation fetch. With per-mount tokens advertised for
+ * the project, each mount decides for itself and only changed mounts fetch;
+ * without them (an older server) the project token decides for the whole
+ * mirror.
+ */
+export declare function planProjectMirrorObservationFetch(input: {
+    branchNames: readonly string[];
+    advertisedProjectToken: string | undefined;
+    /** Per-mount tokens for this project, keyed by branch name; undefined when the server advertised none. */
+    advertisedMountTokens: ReadonlyMap<string, string> | undefined;
+    fetchedProjectToken: string | undefined;
+    fetchedMountTokens: ReadonlyMap<string, string>;
+    skippingEnabled: boolean;
+}): ProjectMirrorObservationFetchPlan;
+export type ProjectMirrorRefsTokensAdvertisement = {
+    /** One token per project id. */
+    projectTokens: Map<string, string>;
+    /** Per-mount tokens keyed by project id then branch name; a project is present only when the server advertised mount tokens for it. */
+    mountTokens: Map<string, Map<string, string>>;
+    /** Current head of the user's hidden workspace repository, when advertised. */
+    workspaceHead: string | undefined;
+};
+/**
+ * Read a `project_mirror_refs_tokens` message. Older servers send only
+ * `tokens`; malformed entries are dropped, which fails open into fetching.
+ */
+export declare function parseProjectMirrorRefsTokensMessage(message: {
+    tokens?: unknown;
+    mountTokens?: unknown;
+    workspaceHead?: unknown;
+}): ProjectMirrorRefsTokensAdvertisement;

package/dist/types/project-mirror-refs-token.d.ts

@@ -1,15 +1,40 @@
+/** Canonical namespaces the token hashes; also the observation fetch's sources. */
+export declare const PROJECT_MIRROR_REFS_TOKEN_NAMESPACES: readonly ["refs/heads/", "refs/r5d/server-synced/"];
+/** Worker-local copy of a canonical `refs/heads/*` ref. */
 export declare const PROJECT_MIRROR_REF_PREFIX = "refs/r5d/mirror/";
 export declare const PROJECT_SERVER_SYNCED_REF_PREFIX = "refs/r5d/server-synced/";
+/** `git for-each-ref` format both sides list refs with; see parseProjectMirrorRefListing. */
+export declare const PROJECT_MIRROR_REF_LISTING_FORMAT = "--format=%(objectname) %(refname)";
 export type ProjectMirrorRef = {
     refname: string;
     objectName: string;
 };
+/** One checked-out project branch, identified by its durable incarnation id. */
+export type ProjectMirrorMount = {
+    branchName: string;
+    branchId: string;
+};
+export type ProjectMirrorRefsTokens = {
+    /** Hash over every ref in the observed namespaces. */
+    project: string;
+    /** Hash over one mount's branch head plus its handoff refs, keyed by branch name. */
+    mounts: Map<string, string>;
+};
 /**
  * Hash a ref listing into a mirror-refs token. Both sides sort here rather
  * than trusting git's listing order: renaming `refs/r5d/mirror/*` back to
  * `refs/heads/*` changes sort neighborhoods.
  */
 export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): string;
+/**
+ * Parse `git for-each-ref` output produced with
+ * PROJECT_MIRROR_REF_LISTING_FORMAT. Malformed rows throw rather than being
+ * dropped: a caller that cannot trust its listing must not produce a token.
+ * With `namespaces`, rows outside them throw too.
+ */
+export declare function parseProjectMirrorRefListing(output: string, options?: {
+    namespaces?: readonly string[];
+}): ProjectMirrorRef[];
 /**
  * Rename locally fetched mirror refs into the namespaces the server hashes.
  * Rows outside the two observed namespaces are dropped; the caller lists only
@@ -17,3 +42,12 @@ export declare function hashProjectMirrorRefs(refs: readonly ProjectMirrorRef[])
  * it can only make tokens differ — which fails open into a fetch.
  */
 export declare function canonicalizeLocalProjectMirrorRefs(refs: readonly ProjectMirrorRef[]): ProjectMirrorRef[];
+/** The canonical refs one mount's token covers: its branch head and its server-synced handoff refs. */
+export declare function projectMirrorMountRefs(refs: readonly ProjectMirrorRef[], mount: ProjectMirrorMount): ProjectMirrorRef[];
+/**
+ * Compute the project token and one token per mount from one canonical ref
+ * listing. A mount's token is the project formula applied to the mount's own
+ * refs, so a mount whose branch is the only ref of its project has the same
+ * token as the project.
+ */
+export declare function projectMirrorRefsTokens(refs: readonly ProjectMirrorRef[], mounts: readonly ProjectMirrorMount[]): ProjectMirrorRefsTokens;

package/dist/types/project-worktrees.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectMirrorMount, type ProjectMirrorRefsTokens } from "./project-mirror-refs-token";
 export declare const PROJECT_WORKTREE_SNAPSHOT_PREFIX = "r5d-project-worktrees-";
 declare const PROJECT_WORKTREE_SNAPSHOT_MANIFEST_VERSION: 1;
 type ProjectWorktreeSnapshotManifest = {
@@ -124,10 +125,17 @@ export declare function ensureProjectWorktrees(input: {
     onSnapshotProgress?: (progress: ProjectWorktreeSnapshotProgress) => void;
 }): Promise<ProjectWorktreeState[]>;
 export declare function projectWorktreeOperationInProgress(checkoutPath: string): boolean;
+/**
+ * How a new linked worktree's working tree starts. `carry` materializes the
+ * source checkout's Git-visible working state, uncommitted changes included;
+ * `clean` checks out the source branch's current commit and nothing else.
+ */
+export type ProjectWorktreeWorkingTreeMode = "carry" | "clean";
 export declare function createLinkedProjectBranch(input: {
     projectRoot: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
 }): {
     branchPath: string;
     baseCommitHash: string;
@@ -143,6 +151,7 @@ export declare function createOrRetryLinkedProjectBranch(input: {
     primaryBranchName: string;
     sourceBranchName: string;
     branchName: string;
+    workingTree: ProjectWorktreeWorkingTreeMode;
     pendingRetry: boolean;
 }): {
     branchPath: string;
@@ -225,19 +234,28 @@ export declare function observeProjectMirrorHeads(input: Omit<ProjectMirrorHeadU
     allowNonFastForward: boolean;
     branchIds?: ReadonlyMap<string, string>;
     refreshRemote?: boolean;
+    /**
+     * Fetch only these mounts' branch heads and handoff refs, because
+     * per-mount token gating found every other mount current. Undefined
+     * fetches the whole mirror; an empty set fetches nothing, exactly like
+     * `refreshRemote: false`.
+     */
+    fetchOnlyBranches?: ReadonlySet<string>;
 }): Promise<ProjectMirrorHeadObservation[]>;
 /**
- * Compute the mirror-refs token for the locally cached mirror state — the
- * token the server will advertise once it hashes the same refs. After a
- * successful lease push (which updates `refs/r5d/mirror/*` above), this
- * matches the server's next advertisement unless something else also moved
- * the canonical repository, in which case the mismatch fails open into a
- * fetch. Formula twin: `server/git/project-mirror-refs-token.ts`.
+ * Compute the tokens the locally cached mirror state covers — the project
+ * token and one token per mount — from one listing of `refs/r5d/mirror/*` and
+ * `refs/r5d/server-synced/*`, with the formula shared with the server. After a
+ * fetch these name exactly the canonical state the fetch transferred; after a
+ * successful lease push (which updates `refs/r5d/mirror/*` above) they predict
+ * the server's next advertisement unless something else also moved the
+ * canonical repository, in which case the mismatch fails open into a fetch.
  */
-export declare function computeLocalProjectMirrorRefsToken(input: {
+export declare function computeLocalProjectMirrorRefsTokens(input: {
     projectRoot: string;
     primaryBranchName: string;
-}): Promise<string>;
+    mounts: readonly ProjectMirrorMount[];
+}): Promise<ProjectMirrorRefsTokens>;
 /** Apply only previously observed object ids; this function never refetches. */
 export declare function applyObservedProjectMirrorHeads(input: {
     projectRoot: string;

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

@@ -38,6 +38,14 @@ export type WorkspaceGitMount = {
     busy?: () => boolean;
     /** Monotonic/opaque visible-mutation token used to catch short writes that begin and end between busy checks. */
     mutationToken?: () => string;
+    /**
+     * The token a completed cycle observed when it last projected this mount.
+     * While the current token still equals it and the mount's hydration basis
+     * is the outer HEAD being projected, the outer subtree already carries the
+     * visible bytes and the mirror copy is skipped. This is a cross-cycle skip
+     * only; the per-cycle busy and token re-checks are unchanged.
+     */
+    lastProjectedMutationToken?: string;
     /** Activity-only fence used before checkout readiness is established on reconnect. */
     busyForRecovery?: () => boolean;
 };
@@ -86,8 +94,12 @@ export type WorkspaceGitSyncResult = {
     affectedPaths: string[];
     activeMountIds: string[];
     skippedMountIds: string[];
+    /** 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. */
     initialPublicationMountIds?: string[];
+    /** Network fetches of the outer workspace head this cycle ran; zero when the advertised head proved them unnecessary. */
+    remoteHeadFetches?: number;
     conflictPaths?: string[];
     conflictSnapshotRefs?: {
         local: string;
@@ -150,9 +162,12 @@ export declare function ensureWorkspaceGitClone(input: {
         email: string;
     };
     preserveResolutionInProgress?: boolean;
+    /** Server-advertised head of the workspace remote; see resolveWorkspaceRemoteHead. */
+    advertisedRemoteHead?: string | null;
 }): Promise<{
     localHead: string | null;
     remoteHead: string | null;
+    remoteHeadFetched: boolean;
 }>;
 type ProjectedMountGitlinks = {
     mount: WorkspaceGitMount;
@@ -204,7 +219,7 @@ export declare function resetWorkspaceGit(input: {
  * 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: {
+export type SynchronizeWorkspaceGitInput = {
     attemptId?: string;
     workerLabel: string;
     workspacePath: string;
@@ -224,6 +239,12 @@ export declare function synchronizeWorkspaceGit(input: {
     skipMountMirror?: boolean;
     /** Positive ancestry proof required before a remediation may integrate, publish, or hydrate. */
     requiredAncestorHeads?: readonly string[];
+    /**
+     * Head of the workspace remote as the server last read it from disk. Equal
+     * to the local remote-tracking ref, it lets the cycle skip its workspace
+     * head fetches; see resolveWorkspaceRemoteHead. Omit to always fetch.
+     */
+    advertisedRemoteHead?: string | null;
     /** Revalidate the worker/config/incident generation after every async boundary. */
     assertStillAdmitted?: () => void;
     /** Test seam for exercising an incident transition during asynchronous diff measurement. */
@@ -234,7 +255,8 @@ export declare function synchronizeWorkspaceGit(input: {
     }) => void | Promise<void>;
     /** Announces each synchronous hydration transaction of this cycle; see WorkspaceHydrationTransactionHooks. */
     hydrationHooks?: WorkspaceHydrationTransactionHooks;
-}): Promise<WorkspaceGitSyncResult>;
+};
+export declare function synchronizeWorkspaceGit(input: SynchronizeWorkspaceGitInput): Promise<WorkspaceGitSyncResult>;
 export declare const workspaceGitSyncTestHarness: {
     commandArgs: typeof gitCommandArgs;
     workspaceCloneCommandArgs: typeof workspaceCloneCommandArgs;

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.103",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",