@ricsam/r5d-worker 0.0.59 → 0.0.61

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "type": "module"
 }

package/dist/mjs/workspace-convergence.mjs

@@ -1,68 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
-const WORKSPACE_CHECKPOINT_QUIET_MS = 5e3;
+const WORKSPACE_PUBLICATION_QUIET_MS = 5e3;
 const WORKSPACE_IDLE_SAFETY_SCAN_MS = 6e4;
 const WORKSPACE_MANIFEST_REVISION_PATTERN = /^[0-9a-f]{64}$/;
-class WorkspaceFilesystemWriterGate {
-  activeWriters = 0;
-  checkpointActive = false;
-  waitingWriters = [];
-  waitingCheckpoints = [];
-  acquireWriter() {
-    if (!this.checkpointActive && this.waitingCheckpoints.length === 0) {
-      this.activeWriters += 1;
-      return Promise.resolve(this.writerRelease());
-    }
-    return new Promise((resolve) => this.waitingWriters.push(resolve));
-  }
-  tryAcquireCheckpoint() {
-    if (this.checkpointActive || this.activeWriters > 0 || this.waitingCheckpoints.length > 0) return null;
-    this.checkpointActive = true;
-    return this.checkpointRelease();
-  }
-  acquireCheckpoint() {
-    const immediate = this.tryAcquireCheckpoint();
-    if (immediate) return Promise.resolve(immediate);
-    return new Promise((resolve) => this.waitingCheckpoints.push(resolve));
-  }
-  checkpointRelease() {
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      this.checkpointActive = false;
-      this.drain();
-    };
-  }
-  writerRelease() {
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      this.activeWriters -= 1;
-      this.drain();
-    };
-  }
-  drain() {
-    if (this.checkpointActive || this.activeWriters > 0) return;
-    const checkpoint = this.waitingCheckpoints.shift();
-    if (checkpoint) {
-      this.checkpointActive = true;
-      checkpoint(this.checkpointRelease());
-      return;
-    }
-    while (this.waitingWriters.length > 0) {
-      const resolve = this.waitingWriters.shift();
-      if (!resolve) continue;
-      this.activeWriters += 1;
-      resolve(this.writerRelease());
-    }
-  }
-}
-const PROCESS_WORKSPACE_FILESYSTEM_WRITERS = new WorkspaceFilesystemWriterGate();
-function processWorkspaceFilesystemWriterGate() {
-  return PROCESS_WORKSPACE_FILESYSTEM_WRITERS;
-}
 class WorkspaceManifestRevisionFence {
   sequence = 0;
   requestedRevision = null;
@@ -88,7 +28,7 @@ class WorkspaceManifestRevisionFence {
     return this.completedRevision === this.requestedRevision ? this.completedRevision : null;
   }
 }
-function workspaceCheckpointTelemetry(input) {
+function workspacePublicationTelemetry(input) {
   return {
     totalMs: Math.max(0, input.finishedAt - input.requestedAt),
     queueMs: Math.max(0, input.prepareStartedAt - input.requestedAt),
@@ -96,21 +36,21 @@ function workspaceCheckpointTelemetry(input) {
     synchronizeMs: Math.max(0, input.finishedAt - input.synchronizeStartedAt)
   };
 }
-function workspaceCheckpointIncidentAction(requestId) {
+function workspacePublicationIncidentAction(requestId) {
   return requestId ? "request_terminal_authority" : "defer_automatic";
 }
-class ExplicitWorkspaceCheckpointQueue {
+class ExplicitWorkspacePublicationQueue {
   scheduled;
   queued = [];
-  schedule(checkpoint, pendingRequestId) {
-    if (pendingRequestId === checkpoint.requestId || this.scheduled?.requestId === checkpoint.requestId || this.queued.some((queued) => queued.requestId === checkpoint.requestId)) {
+  schedule(publication, pendingRequestId) {
+    if (pendingRequestId === publication.requestId || this.scheduled?.requestId === publication.requestId || this.queued.some((queued) => queued.requestId === publication.requestId)) {
       return false;
     }
     if (pendingRequestId || this.scheduled) {
-      this.queued.push(checkpoint);
+      this.queued.push(publication);
       return false;
     }
-    this.scheduled = checkpoint;
+    this.scheduled = publication;
     return true;
   }
   hasScheduled() {
@@ -119,11 +59,11 @@ class ExplicitWorkspaceCheckpointQueue {
   consumeScheduled(requestId) {
     if (this.scheduled?.requestId === requestId) this.scheduled = void 0;
   }
-  enqueue(checkpoint, pendingRequestId) {
-    if (pendingRequestId === checkpoint.requestId || this.scheduled?.requestId === checkpoint.requestId || this.queued.some((queued) => queued.requestId === checkpoint.requestId)) {
+  enqueue(publication, pendingRequestId) {
+    if (pendingRequestId === publication.requestId || this.scheduled?.requestId === publication.requestId || this.queued.some((queued) => queued.requestId === publication.requestId)) {
       return;
     }
-    this.queued.push(checkpoint);
+    this.queued.push(publication);
   }
   next() {
     return this.queued.shift();
@@ -161,13 +101,13 @@ class WorkspaceConvergenceState {
   constructor(statePath) {
     this.statePath = statePath;
     this.state = readWorkspaceConvergenceState(statePath);
-    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+    this.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
   }
   statePath;
   state;
-  checkpointState;
+  publicationState;
   snapshot() {
-    return { ...this.state, checkpointState: this.checkpointState };
+    return { ...this.state, publicationState: this.publicationState };
   }
   setLocalHead(localHead) {
     if (!validHead(localHead)) throw new Error("Invalid local workspace head");
@@ -183,39 +123,39 @@ class WorkspaceConvergenceState {
   }
   markDirty() {
     this.state.dirtyGeneration += 1;
-    if (this.checkpointState === "idle") this.checkpointState = "scheduled";
+    if (this.publicationState === "idle") this.publicationState = "scheduled";
     this.persist();
     return this.state.dirtyGeneration;
   }
   schedule() {
-    if (this.checkpointState === "idle") this.checkpointState = "scheduled";
+    if (this.publicationState === "idle") this.publicationState = "scheduled";
   }
   beginPreparing() {
-    if (this.checkpointState === "preparing" || this.checkpointState === "submitting") {
-      throw new Error("A workspace checkpoint is already in flight");
+    if (this.publicationState === "preparing" || this.publicationState === "submitting") {
+      throw new Error("A workspace publication is already in flight");
     }
-    this.checkpointState = "preparing";
+    this.publicationState = "preparing";
   }
   beginSubmitting() {
-    if (this.checkpointState !== "preparing") throw new Error("Workspace checkpoint authority was not prepared");
-    this.checkpointState = "submitting";
+    if (this.publicationState !== "preparing") throw new Error("Workspace publication authority was not prepared");
+    this.publicationState = "submitting";
   }
   defer() {
-    this.checkpointState = "scheduled";
+    this.publicationState = "scheduled";
   }
   block() {
-    this.checkpointState = "blocked";
+    this.publicationState = "blocked";
   }
   releaseBlock() {
-    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+    this.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
   }
   observeIncidentState(blocked) {
-    if (this.checkpointState === "preparing" || this.checkpointState === "submitting") return;
+    if (this.publicationState === "preparing" || this.publicationState === "submitting") return;
     if (blocked) this.block();
     else this.releaseBlock();
   }
-  resetTransientCheckpointState() {
-    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  resetTransientPublicationState() {
+    this.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
   }
   complete(input) {
     if (!validGeneration(input.generation) || input.generation > this.state.dirtyGeneration) {
@@ -227,7 +167,7 @@ class WorkspaceConvergenceState {
       this.state.localHead = input.canonicalHead;
       this.state.desiredCanonicalHead = input.canonicalHead;
     }
-    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+    this.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
     this.persist();
   }
   persist() {
@@ -247,29 +187,27 @@ function processWorkspaceConvergenceState(statePath) {
   PROCESS_WORKSPACE_CONVERGENCE_STATES.set(key, created);
   return created;
 }
-async function waitForWorkspaceCheckpointOnShutdown(input) {
-  input.forceCheckpoint();
+async function waitForWorkspacePublicationOnShutdown(input) {
+  input.forcePublication();
   const deadline = Date.now() + (input.timeoutMs ?? 1e4);
   const pollMs = input.pollMs ?? 50;
   while (Date.now() < deadline) {
     const snapshot = input.snapshot();
-    if (snapshot.checkpointState === "blocked") return "blocked";
-    if (snapshot.checkpointState === "idle" && snapshot.publishedGeneration >= snapshot.dirtyGeneration) return "settled";
+    if (snapshot.publicationState === "blocked") return "blocked";
+    if (snapshot.publicationState === "idle" && snapshot.publishedGeneration >= snapshot.dirtyGeneration) return "settled";
     await new Promise((resolve) => setTimeout(resolve, pollMs));
   }
   return "timed_out";
 }
 export {
-  ExplicitWorkspaceCheckpointQueue,
-  WORKSPACE_CHECKPOINT_QUIET_MS,
+  ExplicitWorkspacePublicationQueue,
   WORKSPACE_IDLE_SAFETY_SCAN_MS,
+  WORKSPACE_PUBLICATION_QUIET_MS,
   WorkspaceConvergenceState,
-  WorkspaceFilesystemWriterGate,
   WorkspaceManifestRevisionFence,
   processWorkspaceConvergenceState,
-  processWorkspaceFilesystemWriterGate,
   readWorkspaceConvergenceState,
-  waitForWorkspaceCheckpointOnShutdown,
-  workspaceCheckpointIncidentAction,
-  workspaceCheckpointTelemetry
+  waitForWorkspacePublicationOnShutdown,
+  workspacePublicationIncidentAction,
+  workspacePublicationTelemetry
 };

package/dist/mjs/workspace-manifest-admission.mjs

@@ -5,7 +5,7 @@ function hasNormalGitDirectory(checkoutPath) {
   const gitPath = path.join(checkoutPath, ".git");
   return fs.existsSync(gitPath) && fs.statSync(gitPath).isDirectory();
 }
-function inspectWorkspaceManifestAdmission(input) {
+function inspectWorkspaceManifestFilesystem(input) {
   const firstBootstrap = !hasNormalGitDirectory(input.workspaceShadowRoot);
   const missingCheckouts = [];
   const migratedProjectIds = [];
@@ -22,14 +22,9 @@ function inspectWorkspaceManifestAdmission(input) {
   return {
     firstBootstrap,
     missingCheckouts,
-    migratedProjectIds,
-    requiresVisibleLease: firstBootstrap || migratedProjectIds.length > 0
+    migratedProjectIds
   };
 }
-async function acquireWorkspaceManifestVisibleLease(gate, admission) {
-  return admission.requiresVisibleLease ? await gate.acquireCheckpoint() : void 0;
-}
 export {
-  acquireWorkspaceManifestVisibleLease,
-  inspectWorkspaceManifestAdmission
+  inspectWorkspaceManifestFilesystem
 };

package/dist/mjs/workspace-sync.mjs

@@ -1708,9 +1708,7 @@ function assertWorkspaceQuarantineRef(quarantineRef) {
   const prefix = quarantineRef.startsWith(WORKSPACE_PUBLICATION_REF_PREFIX) ? WORKSPACE_PUBLICATION_REF_PREFIX : WORKSPACE_INTENT_REF_PREFIX;
   const suffix = quarantineRef.slice(prefix.length);
   if (!quarantineRef.startsWith(prefix) || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(suffix)) {
-    throw new Error(
-      `Workspace candidate ref must be below ${WORKSPACE_PUBLICATION_REF_PREFIX} or ${WORKSPACE_INTENT_REF_PREFIX}`
-    );
+    throw new Error(`Workspace candidate ref must be below ${WORKSPACE_PUBLICATION_REF_PREFIX} or ${WORKSPACE_INTENT_REF_PREFIX}`);
   }
   const result = Bun.spawnSync(["git", "check-ref-format", quarantineRef], {
     stdout: "pipe",
@@ -1928,11 +1926,7 @@ async function synchronizeWorkspace(rawInput) {
     const destructiveReductions = destructiveCheckoutReductions(input, baseRevision);
     if (destructiveReductions.length > 0 && !input.confirmedLargeDiff) {
       const summary = destructiveReductions.map(({ root, trackedBefore, trackedAfter }) => `${root} (${trackedBefore} -> ${trackedAfter} tracked files)`).join(", ");
-      return preserveLargeDiffCandidate(
-        input,
-        observed,
-        `Workspace safety guard blocked a destructive checkout reduction: ${summary}`
-      );
+      return preserveLargeDiffCandidate(input, observed, `Workspace safety guard blocked a destructive checkout reduction: ${summary}`);
     }
     if (paths.length > 0 && diffSizeBytes > MAX_WORKSPACE_SYNC_DIFF_BYTES && !input.confirmedLargeDiff && !input.trigger.canonicalCheckoutOnly) {
       return preserveLargeDiffCandidate(

package/dist/types/workspace-convergence.d.ts

@@ -1,14 +1,14 @@
-export declare const WORKSPACE_CHECKPOINT_QUIET_MS = 5000;
+export declare const WORKSPACE_PUBLICATION_QUIET_MS = 5000;
 export declare const WORKSPACE_IDLE_SAFETY_SCAN_MS = 60000;
-export type WorkspaceCheckpointState = "idle" | "scheduled" | "preparing" | "submitting" | "blocked";
+export type WorkspacePublicationState = "idle" | "scheduled" | "preparing" | "submitting" | "blocked";
 export type WorkspaceConvergenceSnapshot = {
     localHead: string | null;
     desiredCanonicalHead: string | null;
     dirtyGeneration: number;
     publishedGeneration: number;
-    checkpointState: WorkspaceCheckpointState;
+    publicationState: WorkspacePublicationState;
 };
-export type ExplicitWorkspaceCheckpoint<TTrigger> = {
+export type ExplicitWorkspacePublication<TTrigger> = {
     requestId: string;
     trigger: TTrigger;
 };
@@ -16,26 +16,6 @@ export type WorkspaceManifestRevisionToken = {
     sequence: number;
     revision: string;
 };
-export type WorkspaceWriterLease = () => void;
-/**
- * Makes checkpoint admission atomic with command startup. Once a checkpoint
- * lease is admitted, later writers wait; once a writer lease is admitted, a
- * checkpoint must defer. Writer acquisition increments synchronously before
- * its promise resolves, covering asynchronous environment setup and spawn.
- */
-export declare class WorkspaceFilesystemWriterGate {
-    private activeWriters;
-    private checkpointActive;
-    private readonly waitingWriters;
-    private readonly waitingCheckpoints;
-    acquireWriter(): Promise<WorkspaceWriterLease>;
-    tryAcquireCheckpoint(): WorkspaceWriterLease | null;
-    acquireCheckpoint(): Promise<WorkspaceWriterLease>;
-    private checkpointRelease;
-    private writerRelease;
-    private drain;
-}
-export declare function processWorkspaceFilesystemWriterGate(): WorkspaceFilesystemWriterGate;
 export declare class WorkspaceManifestRevisionFence {
     private sequence;
     private requestedRevision;
@@ -45,7 +25,7 @@ export declare class WorkspaceManifestRevisionFence {
     complete(token: WorkspaceManifestRevisionToken): boolean;
     readyRevision(): string | null;
 }
-export declare function workspaceCheckpointTelemetry(input: {
+export declare function workspacePublicationTelemetry(input: {
     requestedAt: number;
     prepareStartedAt: number;
     synchronizeStartedAt: number;
@@ -56,22 +36,22 @@ export declare function workspaceCheckpointTelemetry(input: {
     prepareMs: number;
     synchronizeMs: number;
 };
-export declare function workspaceCheckpointIncidentAction(requestId: string | undefined): "defer_automatic" | "request_terminal_authority";
-export declare class ExplicitWorkspaceCheckpointQueue<TTrigger> {
+export declare function workspacePublicationIncidentAction(requestId: string | undefined): "defer_automatic" | "request_terminal_authority";
+export declare class ExplicitWorkspacePublicationQueue<TTrigger> {
     private scheduled;
     private readonly queued;
-    schedule(checkpoint: ExplicitWorkspaceCheckpoint<TTrigger>, pendingRequestId?: string): boolean;
+    schedule(publication: ExplicitWorkspacePublication<TTrigger>, pendingRequestId?: string): boolean;
     hasScheduled(): boolean;
     consumeScheduled(requestId: string): void;
-    enqueue(checkpoint: ExplicitWorkspaceCheckpoint<TTrigger>, pendingRequestId?: string): void;
-    next(): ExplicitWorkspaceCheckpoint<TTrigger> | undefined;
+    enqueue(publication: ExplicitWorkspacePublication<TTrigger>, pendingRequestId?: string): void;
+    next(): ExplicitWorkspacePublication<TTrigger> | undefined;
 }
-type PersistedWorkspaceConvergenceState = Omit<WorkspaceConvergenceSnapshot, "checkpointState">;
+type PersistedWorkspaceConvergenceState = Omit<WorkspaceConvergenceSnapshot, "publicationState">;
 export declare function readWorkspaceConvergenceState(statePath: string): PersistedWorkspaceConvergenceState;
 export declare class WorkspaceConvergenceState {
     private readonly statePath;
     private state;
-    private checkpointState;
+    private publicationState;
     constructor(statePath: string);
     snapshot(): WorkspaceConvergenceSnapshot;
     setLocalHead(localHead: string | null): void;
@@ -84,7 +64,7 @@ export declare class WorkspaceConvergenceState {
     block(): void;
     releaseBlock(): void;
     observeIncidentState(blocked: boolean): void;
-    resetTransientCheckpointState(): void;
+    resetTransientPublicationState(): void;
     complete(input: {
         generation: number;
         canonicalHead: string | null;
@@ -93,9 +73,9 @@ export declare class WorkspaceConvergenceState {
     private persist;
 }
 export declare function processWorkspaceConvergenceState(statePath: string): WorkspaceConvergenceState;
-export declare function waitForWorkspaceCheckpointOnShutdown(input: {
+export declare function waitForWorkspacePublicationOnShutdown(input: {
     snapshot: () => WorkspaceConvergenceSnapshot;
-    forceCheckpoint: () => void;
+    forcePublication: () => void;
     timeoutMs?: number;
     pollMs?: number;
 }): Promise<"settled" | "blocked" | "timed_out">;

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

@@ -5,7 +5,7 @@ export type WorkspaceIncidentUpdate = {
 /**
  * WebSocket writes are ordered, but independent server handlers can decide an
  * incident state under the user lock and write their messages after releasing
- * it. Remember terminal incident IDs so a delayed checkpoint response cannot
+ * it. Remember terminal incident IDs so a delayed publication response cannot
  * resurrect a barrier that this connection has already observed as terminal.
  */
 export declare class WorkspaceIncidentOrderingFence {

package/dist/types/workspace-manifest-admission.d.ts

@@ -1,27 +1,24 @@
-import type { WorkspaceFilesystemWriterGate, WorkspaceWriterLease } from "./workspace-convergence";
 export type WorkspaceManifestCheckout = {
     projectId: string;
     projectPath: string;
     checkoutPathSegments: [namespace: string, project: string];
     branches: string[];
 };
-export type WorkspaceManifestAdmission = {
+export type WorkspaceManifestFilesystemState = {
     firstBootstrap: boolean;
     missingCheckouts: Array<{
         projectId: string;
         branchName: string;
     }>;
     migratedProjectIds: string[];
-    requiresVisibleLease: boolean;
 };
 /**
- * Inspects only the paths that make manifest acknowledgement mutate existing
- * visible state. Missing checkouts are reported as target-specific pending
- * work and hydrated opportunistically; they must not delay unrelated targets.
+ * Inspects manifest-related filesystem state without reserving visible paths.
+ * Missing checkouts are target-specific pending work and hydrate
+ * opportunistically without delaying unrelated targets or running commands.
  */
-export declare function inspectWorkspaceManifestAdmission(input: {
+export declare function inspectWorkspaceManifestFilesystem(input: {
     projectsRoot: string;
     workspaceShadowRoot: string;
     projects: WorkspaceManifestCheckout[];
-}): WorkspaceManifestAdmission;
-export declare function acquireWorkspaceManifestVisibleLease(gate: WorkspaceFilesystemWriterGate, admission: WorkspaceManifestAdmission): Promise<WorkspaceWriterLease | undefined>;
+}): WorkspaceManifestFilesystemState;

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

@@ -76,7 +76,7 @@ export type WorkspaceSyncInput = {
      * Workers never publish the canonical workspace branch directly.
      */
     quarantineRef?: string;
-    /** Exact canonical head fenced by checkpoint authority. */
+    /** Exact canonical head fenced by publication authority. */
     expectedCanonicalHead?: string | null;
     confirmedLargeDiff?: boolean;
     confirmationReason?: string;

package/package.json

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