@ricsam/r5d-worker 0.0.137 → 0.0.139

package/dist/types/workspace-hydration-merge.d.ts

@@ -1,103 +0,0 @@
-import fs from "node:fs";
-import { type PreparedWorkingTreeMirror, type ProjectedWorkingTreeEntry, type WorkingTreeMirrorOverride, type WorkingTreeMirrorSelection } from "./working-tree-mirror";
-/**
- * Where a mount's bytes were read this cycle (docs/merge-hydration-design.md
- * §2.1). `projectedCommit` is the commit whose subtree at the mount path is
- * exactly what projection read: the projected head for a mirrored mount, the
- * synthesized ours commit for a merge-projected one. `projectedFiles` is
- * what the mirror or synthesis saw for each entry, or null when the mount was
- * not read this cycle (its token was unchanged), in which case a changed
- * file is recognized by hashing it against the projected blob.
- */
-export type WorkspaceHydrationMergeBasis = {
-    projectedCommit: string;
-    projectedFiles: Record<string, ProjectedWorkingTreeEntry> | null;
-    /**
-     * Wall-clock time the projection finished reading. A projected stat whose
-     * timestamps fall within `RACY_PROJECTION_WINDOW_MS` of it is not trusted
-     * to prove the file unchanged (git's racy-clean rule: a rewrite of the
-     * same size in the same coarse timestamp tick leaves the stat intact), so
-     * such a file is hashed against the projected blob instead.
-     */
-    readAtMs?: number;
-};
-export declare const RACY_PROJECTION_WINDOW_MS = 2000;
-export type WorkspaceHydrationSkipReason = "hydration_merge_conflict" | "hydration_target_changed";
-/** A mount merge hydration left at its previous receipt entry, and why. */
-export type WorkspaceHydrationMountSkip = {
-    mountId: string;
-    reason: WorkspaceHydrationSkipReason;
-    paths: string[];
-};
-/** One path whose blob differs between the projected subtree (base) and the hydration head's subtree (theirs). */
-export type WorkspaceSubtreeChange = {
-    base: {
-        mode: string;
-        objectId: string;
-    } | null;
-    theirs: {
-        mode: string;
-        objectId: string;
-    } | null;
-};
-export type WorkspaceHydrationMergeDecision = {
-    kind: "conflict";
-    paths: string[];
-} | {
-    kind: "target_changed";
-    paths: string[];
-} | {
-    kind: "apply";
-    selection: WorkingTreeMirrorSelection;
-    overrides: Map<string, WorkingTreeMirrorOverride>;
-    /** The target `lstat` (or absence) every mutated path must still show when it is mutated. */
-    expectations: Map<string, fs.Stats | null>;
-    /** Blob of the bytes each written or removed path held before hydration; the stale-rewrite detector's input. */
-    preBlobs: Map<string, string>;
-    /** Blob each path in `preBlobs` holds after hydration (null: removed); with `preBlobs`, the hydration ledger's record. */
-    postBlobs: Map<string, string | null>;
-    /**
-     * Bytes the ledger names that no commit holds (a merged file's previous
-     * and merged content), keyed by blob id, for the job to write into the
-     * clone's object store so a later projection can read them back.
-     */
-    blobsToStore: Map<string, Buffer>;
-    /** Paths whose content was three-way merged. */
-    mergedPaths: string[];
-    /** Paths the checkout changed since projection that hydration leaves as they are. */
-    keptPaths: string[];
-};
-/**
- * Decide, per path the hydration head changed relative to what projection
- * read, whether hydration writes theirs (the checkout is unchanged there),
- * leaves the checkout alone (theirs did not change there), writes a
- * three-way merge, or cannot proceed (docs/merge-hydration-design.md §2.2,
- * §2.6). Every path the checkout changed since projection that the head did
- * not change survives untouched, including files created since. Nothing is
- * written here; the result drives `applyWorkingTreeMirror` under guards that
- * re-check each path's `lstat` immediately before mutating it.
- */
-export declare function decideWorkspaceHydrationMerge(input: {
-    prepared: PreparedWorkingTreeMirror;
-    changes: ReadonlyMap<string, WorkspaceSubtreeChange>;
-    projectedFiles: Readonly<Record<string, ProjectedWorkingTreeEntry>> | null;
-    readAtMs?: number;
-    /** Blob contents by object id, in one batch. */
-    readBaseBlobs: (objectIds: readonly string[]) => Map<string, Buffer>;
-    /** Paths marked -diff on either side must never enter the text merger. */
-    readBinaryPaths?: (relativePaths: readonly string[]) => ReadonlySet<string>;
-}): WorkspaceHydrationMergeDecision;
-/** Batch attribute reads, with NUL delimiters so arbitrary Git filenames stay intact. */
-export declare function readHydrationBinaryPaths(input: {
-    checkoutRoot: string;
-    outerRoot: string;
-    relativePaths: readonly string[];
-}): Set<string>;
-/**
- * Parse `git diff-tree -r -z --no-renames --raw <base tree> <theirs tree>`
- * output into per-path changes. Records come in pairs: the status line
- * (`:<base mode> <theirs mode> <base id> <theirs id> <status>`) and the path.
- */
-export declare function parseWorkspaceSubtreeChanges(raw: Buffer): Map<string, WorkspaceSubtreeChange>;
-/** The mount-relative path of a checkout entry as its absolute path, for diagnostics. */
-export declare function describeHydrationSkipPaths(mountSourcePath: string, paths: readonly string[]): string;

package/dist/types/workspace-hydration-recovery-state.d.ts

@@ -1,10 +0,0 @@
-/** Wire evidence owned by the standalone worker package; no API runtime dependency. */
-export type WorkerHydrationRecovery = {
-    transactionId: string;
-    transactionPath: string;
-    mountIds: string[];
-    previousHeads: Record<string, string>;
-    retainedPaths?: string[];
-};
-/** Extract durable recovery evidence even through executor/AggregateError wrapping. */
-export declare function findHydrationRecovery(error: unknown): WorkerHydrationRecovery | undefined;

package/dist/types/workspace-incident-state.d.ts

@@ -1,19 +0,0 @@
-export type WorkspaceIncidentUpdate = {
-    incidentId: string | null;
-    status: "remediating" | "waiting_for_worker" | "resolved" | "confirmed" | "reset" | null;
-};
-export declare function applyWorkspaceIncidentUpdate(currentIncidentId: string | null, update: WorkspaceIncidentUpdate): string | null;
-/**
- * Whether an incoming `workspace_config` is the full configuration a terminal
- * incident update promised: the worker still holds an incident-deferred
- * configuration, no incident is active any more, and the server did not ask
- * for another deferral. Arrival of that configuration disarms the refresh
- * watchdog; from then on the configuration's own generation checks and its
- * failure close govern, so a legitimately long full configuration is never
- * cut off mid-flight by the arrival timer.
- */
-export declare function workspaceConfigurationRefreshesDeferredConfiguration(input: {
-    deferredIncidentId: string | null;
-    activeIncidentId: string | null;
-    requestedDeferredIncidentId: string | undefined;
-}): boolean;

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

@@ -1,69 +0,0 @@
-import { type ProjectedWorkingTreeEntry, type WorkingTreeSourceMode } from "./working-tree-mirror";
-import type { WorkspaceHydrationLedgerEntry } from "./workspace-hydration-ledger";
-export type WorkspaceMergeProjectionSupport = {
-    supported: true;
-} | {
-    supported: false;
-    error: string;
-};
-export type WorkspaceMergeProjectionMount = {
-    id: string;
-    sourcePath: string;
-    workspaceRelativePath: string;
-    sourceMode: WorkingTreeSourceMode;
-};
-/**
- * `projectedFiles` records what the synthesis read for every visible entry
- * (merge hydration's basis for "changed since projection"). A `stale_rewrite`
- * result means the checkout holds, at the listed paths, exactly the bytes the
- * last hydration replaced; nothing was merged and the mount must stay pinned.
- */
-export type WorkspaceMergeProjectionResult = {
-    kind: "clean";
-    resultTree: string;
-    oursCommit: string;
-    projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
-    readAtMs: number;
-    /** Ledger paths whose checkout content moved on from both the replaced and the basis bytes (or that are gone). */
-    staleRewriteCleared: string[];
-    /**
-     * Ledger paths a process alive across their hydration rewrote, merged
-     * here against what that process read (docs/merge-hydration-design.md
-     * §3.1): the checkout still holds the process's bytes, so the mount must
-     * be hydrated from the merged result even where its receipt is current.
-     */
-    ledgerMergedPaths: string[];
-} | {
-    kind: "conflict";
-    oursCommit: string;
-    conflictPaths: string[];
-    error: string;
-    projectedFiles: Record<string, ProjectedWorkingTreeEntry>;
-    readAtMs: number;
-    staleRewriteCleared: string[];
-    ledgerMergedPaths: string[];
-} | {
-    kind: "stale_rewrite";
-    paths: string[];
-    staleRewriteCleared: string[];
-};
-declare function gitVersionIsSupported(version: string): boolean;
-export declare function workspaceMergeProjectionSupport(): WorkspaceMergeProjectionSupport;
-export declare function mergeWorkspaceProjectionMount(input: {
-    workspacePath: string;
-    mount: WorkspaceMergeProjectionMount;
-    basisHead: string;
-    currentHead: string;
-    attemptId: string;
-    hydrationLedger?: Readonly<Record<string, WorkspaceHydrationLedgerEntry>>;
-}): WorkspaceMergeProjectionResult;
-export declare function materializeWorkspaceProjectionTree(input: {
-    workspacePath: string;
-    workspaceRelativePath: string;
-    resultTree: string;
-}): void;
-export declare const workspaceMergeProjectionTestHarness: {
-    gitVersionIsSupported: typeof gitVersionIsSupported;
-    resetSupportProbe(): void;
-};
-export {};

package/dist/types/workspace-mount-boundary.d.ts

@@ -1,10 +0,0 @@
-/**
- * Validate every existing path component from a trusted root to a managed
- * directory without following symlinks. Missing suffixes are allowed because
- * hydration and path moves create them after this check.
- */
-export declare function assertManagedDirectoryPath(input: {
-    trustedRoot: string;
-    candidate: string;
-    label: string;
-}): void;

package/dist/types/workspace-mount-hold-fence.d.ts

@@ -1,42 +0,0 @@
-/**
- * Tracks the mounts whose bytes a workspace filesystem job is reading or
- * writing on the executor thread. The sync engine takes a hold immediately
- * after the busy observation that selected a mount, in the same synchronous
- * stretch, and releases it when the job's result or failure arrives. Command
- * admission waits on the fence before reserving a mount, so no tracked
- * process, PTY or file operation can start in a mount while a job owns it,
- * and no job can start on a mount a command already reserved (that mount was
- * busy at the observation). Holds are counted per mount; overlapping holds
- * (a recovery pass and a projection of the same mount cannot overlap under the
- * mutation gate, but counting keeps the fence correct regardless) release in
- * any order.
- */
-export type WorkspaceMountHoldRelease = () => void;
-export declare class WorkspaceMountHoldAbortedError extends Error {
-    constructor(reason: string);
-}
-export declare class WorkspaceMountHoldFence {
-    private readonly holds;
-    private readonly waiters;
-    private readonly now;
-    constructor(options?: {
-        now?: () => number;
-    });
-    /** Take one hold on every listed mount; the returned release is idempotent. */
-    hold(mountIds: readonly string[], description: string): WorkspaceMountHoldRelease;
-    isHeld(mountIds: readonly string[]): boolean;
-    /** Human-readable holder of the first held mount among `mountIds`, for diagnostics. */
-    describeHold(mountIds: readonly string[]): string | null;
-    /** Every held mount id, sorted, for status reporting. */
-    heldMountIds(): string[];
-    /**
-     * Resolves in the same turn as the release that leaves none of `mountIds`
-     * held, so the caller can re-check and reserve without an interleaving
-     * hold. Resolves immediately when nothing is held. Rejects with
-     * WorkspaceMountHoldAbortedError when `signal` aborts first.
-     */
-    waitForRelease(mountIds: readonly string[], options?: {
-        signal?: AbortSignal;
-    }): Promise<void>;
-    private wake;
-}

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

@@ -1,42 +0,0 @@
-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 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 {
-    private activeMutations;
-    private syncActive;
-    private readonly waiters;
-    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-path-move.d.ts

@@ -1,21 +0,0 @@
-export type ProjectCheckoutPathMoveBranch = {
-    branchName: string;
-    outerWorkspaceRelativePath: string;
-};
-export declare function checkoutPathMovePublicationComplete(requiredMountIds: readonly string[], activeMountIds: ReadonlySet<string>): boolean;
-/**
- * Move the project checkout location without making its old root the only copy
- * of dirty or ignored working state. The canonical outer tree receives the
- * Git-visible projection, while the new root receives every non-.git byte so
- * repository activation can reconstruct Git metadata without losing local
- * files. Both copies are stable before the obsolete worktree root is removed.
- */
-export declare function preserveProjectCheckoutPathMove(input: {
-    oldProjectRoot: string;
-    newProjectRoot: string;
-    projectsDurabilityRoot: string;
-    outerWorkspaceRoot: string;
-    branches: readonly ProjectCheckoutPathMoveBranch[];
-}): {
-    preservedBranchNames: string[];
-};

package/dist/types/workspace-preserve-only-policy.d.ts

@@ -1,15 +0,0 @@
-export type WorkerProjectBranchDisposition = "active" | "creator_local" | "preserve_only";
-/** Name equality never grants creator authority across branch incarnations. */
-export declare function creatorLocalProjectBranchIsAuthorized(input: {
-    pendingBranchId: string | undefined;
-    preserveOnlyBranchId: string | undefined;
-}): boolean;
-/**
- * A globally pending branch is executable only on the worker that durably
- * recorded its local creation. Every other worker treats the same protocol
- * entry as preservation metadata, never as a checkout target.
- */
-export declare function workerProjectBranchDisposition(input: {
-    activeConfigured: boolean;
-    locallyPendingCreated: boolean;
-}): WorkerProjectBranchDisposition;

package/dist/types/workspace-project-config-policy.d.ts

@@ -1,48 +0,0 @@
-type ProjectTarget = {
-    type: "project";
-    projectId: string;
-};
-type WorkspaceTarget = {
-    type: "workspace";
-    rootProfile: "visible_projects" | "canonical_sync";
-};
-type ProjectConfiguration = {
-    projectId: string;
-};
-type ProjectConfigurationWithBranches = ProjectConfiguration & {
-    executionDisabled?: boolean;
-    branches: readonly {
-        branchName: string;
-    }[];
-};
-/**
- * Every executable checkout of a configuration whose reconciliation did not
- * run. Frozen projects expose neither ready nor pending execution targets, so
- * the report stays inside the server's executable checkout ledger.
- */
-export declare function deferredProjectConfigurationPendingBranches(projects: readonly ProjectConfigurationWithBranches[]): Array<{
-    projectId: string;
-    branchName: string;
-}>;
-export type BusyProjectConfigurationChangeReason = "added" | "removed" | "initializing" | "changed";
-export type BusyProjectConfigurationChange = {
-    projectId: string;
-    reason: BusyProjectConfigurationChangeReason;
-};
-/**
- * Identify configuration changes that would touch a project while visible
- * checkout activity is active or reserved. A visible-projects target covers
- * every project; canonical-sync activity is isolated in the outer clone. The
- * reason names why the busy project cannot take the configuration now, so a
- * deferral can be diagnosed without reconstructing both generations.
- */
-export declare function busyProjectConfigurationChanges<TProject extends ProjectConfiguration>(input: {
-    currentProjects: readonly TProject[];
-    incomingProjects: readonly TProject[];
-    activeTargets: Iterable<ProjectTarget | WorkspaceTarget>;
-    currentFingerprint: (project: TProject) => string;
-    incomingFingerprint: (project: TProject) => string;
-    currentProjectReady: (project: TProject) => boolean;
-}): BusyProjectConfigurationChange[];
-export declare function describeBusyProjectConfigurationChanges(changes: readonly BusyProjectConfigurationChange[]): string;
-export {};

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

@@ -1,59 +0,0 @@
-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-publication-evidence.d.ts

@@ -1,17 +0,0 @@
-export type ProjectBranchPublicationEvidence = {
-    branchId: string;
-    projectId: string;
-    branchName: string;
-};
-/** Select only branch mounts that completed this synchronization cycle. */
-export declare function activeProjectBranchNames(projectId: string, branchNames: readonly string[], activeMountIds: readonly string[]): string[];
-/** Bind physical active mounts to the exact configured branch-row snapshot. */
-export declare function activeProjectBranchPublicationEvidence(projects: readonly {
-    projectId: string;
-    executionDisabled?: boolean;
-    mirrorWritesDisabled?: boolean;
-    branches: readonly {
-        branchId: string;
-        branchName: string;
-    }[];
-}[], activeMountIds: readonly string[]): ProjectBranchPublicationEvidence[];

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

@@ -1,28 +0,0 @@
-/**
- * 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>;
-}