@ricsam/r5d-worker 0.0.57 → 0.0.59

package/dist/mjs/package.json

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

package/dist/mjs/workspace-convergence.mjs

@@ -0,0 +1,275 @@
+import fs from "node:fs";
+import path from "node:path";
+const WORKSPACE_CHECKPOINT_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;
+  completedRevision = null;
+  begin(revision) {
+    if (!WORKSPACE_MANIFEST_REVISION_PATTERN.test(revision)) {
+      throw new Error("Workspace manifest revision must be a lowercase SHA-256 hash");
+    }
+    this.sequence += 1;
+    this.requestedRevision = revision;
+    this.completedRevision = null;
+    return { sequence: this.sequence, revision };
+  }
+  isCurrent(token) {
+    return token.sequence === this.sequence && token.revision === this.requestedRevision;
+  }
+  complete(token) {
+    if (!this.isCurrent(token)) return false;
+    this.completedRevision = token.revision;
+    return true;
+  }
+  readyRevision() {
+    return this.completedRevision === this.requestedRevision ? this.completedRevision : null;
+  }
+}
+function workspaceCheckpointTelemetry(input) {
+  return {
+    totalMs: Math.max(0, input.finishedAt - input.requestedAt),
+    queueMs: Math.max(0, input.prepareStartedAt - input.requestedAt),
+    prepareMs: Math.max(0, input.synchronizeStartedAt - input.prepareStartedAt),
+    synchronizeMs: Math.max(0, input.finishedAt - input.synchronizeStartedAt)
+  };
+}
+function workspaceCheckpointIncidentAction(requestId) {
+  return requestId ? "request_terminal_authority" : "defer_automatic";
+}
+class ExplicitWorkspaceCheckpointQueue {
+  scheduled;
+  queued = [];
+  schedule(checkpoint, pendingRequestId) {
+    if (pendingRequestId === checkpoint.requestId || this.scheduled?.requestId === checkpoint.requestId || this.queued.some((queued) => queued.requestId === checkpoint.requestId)) {
+      return false;
+    }
+    if (pendingRequestId || this.scheduled) {
+      this.queued.push(checkpoint);
+      return false;
+    }
+    this.scheduled = checkpoint;
+    return true;
+  }
+  hasScheduled() {
+    return this.scheduled !== void 0;
+  }
+  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)) {
+      return;
+    }
+    this.queued.push(checkpoint);
+  }
+  next() {
+    return this.queued.shift();
+  }
+}
+const EMPTY_STATE = {
+  localHead: null,
+  desiredCanonicalHead: null,
+  dirtyGeneration: 0,
+  publishedGeneration: 0
+};
+function validHead(value) {
+  return value === null || typeof value === "string" && /^[0-9a-f]{40,64}$/.test(value);
+}
+function validGeneration(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function readWorkspaceConvergenceState(statePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    if (!validHead(parsed.localHead) || !validHead(parsed.desiredCanonicalHead) || !validGeneration(parsed.dirtyGeneration) || !validGeneration(parsed.publishedGeneration) || parsed.publishedGeneration > parsed.dirtyGeneration) {
+      return { ...EMPTY_STATE };
+    }
+    return {
+      localHead: parsed.localHead,
+      desiredCanonicalHead: parsed.desiredCanonicalHead,
+      dirtyGeneration: parsed.dirtyGeneration,
+      publishedGeneration: parsed.publishedGeneration
+    };
+  } catch {
+    return { ...EMPTY_STATE };
+  }
+}
+class WorkspaceConvergenceState {
+  constructor(statePath) {
+    this.statePath = statePath;
+    this.state = readWorkspaceConvergenceState(statePath);
+    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  }
+  statePath;
+  state;
+  checkpointState;
+  snapshot() {
+    return { ...this.state, checkpointState: this.checkpointState };
+  }
+  setLocalHead(localHead) {
+    if (!validHead(localHead)) throw new Error("Invalid local workspace head");
+    this.state.localHead = localHead;
+    this.persist();
+  }
+  observeCanonicalHead(canonicalHead) {
+    if (!validHead(canonicalHead)) throw new Error("Invalid canonical workspace head");
+    if (this.state.desiredCanonicalHead === canonicalHead) return false;
+    this.state.desiredCanonicalHead = canonicalHead;
+    this.persist();
+    return true;
+  }
+  markDirty() {
+    this.state.dirtyGeneration += 1;
+    if (this.checkpointState === "idle") this.checkpointState = "scheduled";
+    this.persist();
+    return this.state.dirtyGeneration;
+  }
+  schedule() {
+    if (this.checkpointState === "idle") this.checkpointState = "scheduled";
+  }
+  beginPreparing() {
+    if (this.checkpointState === "preparing" || this.checkpointState === "submitting") {
+      throw new Error("A workspace checkpoint is already in flight");
+    }
+    this.checkpointState = "preparing";
+  }
+  beginSubmitting() {
+    if (this.checkpointState !== "preparing") throw new Error("Workspace checkpoint authority was not prepared");
+    this.checkpointState = "submitting";
+  }
+  defer() {
+    this.checkpointState = "scheduled";
+  }
+  block() {
+    this.checkpointState = "blocked";
+  }
+  releaseBlock() {
+    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  }
+  observeIncidentState(blocked) {
+    if (this.checkpointState === "preparing" || this.checkpointState === "submitting") return;
+    if (blocked) this.block();
+    else this.releaseBlock();
+  }
+  resetTransientCheckpointState() {
+    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  }
+  complete(input) {
+    if (!validGeneration(input.generation) || input.generation > this.state.dirtyGeneration) {
+      throw new Error("Invalid completed workspace generation");
+    }
+    if (!validHead(input.canonicalHead)) throw new Error("Invalid completed canonical workspace head");
+    if (input.published) {
+      this.state.publishedGeneration = Math.max(this.state.publishedGeneration, input.generation);
+      this.state.localHead = input.canonicalHead;
+      this.state.desiredCanonicalHead = input.canonicalHead;
+    }
+    this.checkpointState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+    this.persist();
+  }
+  persist() {
+    fs.mkdirSync(path.dirname(this.statePath), { recursive: true });
+    const temporaryPath = `${this.statePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(this.state)}
+`, { mode: 384 });
+    fs.renameSync(temporaryPath, this.statePath);
+  }
+}
+const PROCESS_WORKSPACE_CONVERGENCE_STATES = /* @__PURE__ */ new Map();
+function processWorkspaceConvergenceState(statePath) {
+  const key = path.resolve(statePath);
+  const existing = PROCESS_WORKSPACE_CONVERGENCE_STATES.get(key);
+  if (existing) return existing;
+  const created = new WorkspaceConvergenceState(key);
+  PROCESS_WORKSPACE_CONVERGENCE_STATES.set(key, created);
+  return created;
+}
+async function waitForWorkspaceCheckpointOnShutdown(input) {
+  input.forceCheckpoint();
+  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";
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+  }
+  return "timed_out";
+}
+export {
+  ExplicitWorkspaceCheckpointQueue,
+  WORKSPACE_CHECKPOINT_QUIET_MS,
+  WORKSPACE_IDLE_SAFETY_SCAN_MS,
+  WorkspaceConvergenceState,
+  WorkspaceFilesystemWriterGate,
+  WorkspaceManifestRevisionFence,
+  processWorkspaceConvergenceState,
+  processWorkspaceFilesystemWriterGate,
+  readWorkspaceConvergenceState,
+  waitForWorkspaceCheckpointOnShutdown,
+  workspaceCheckpointIncidentAction,
+  workspaceCheckpointTelemetry
+};

package/dist/mjs/workspace-incident-state.mjs

@@ -1,14 +1,42 @@
+const DEFAULT_TERMINAL_INCIDENT_HISTORY_LIMIT = 32;
+function isTerminalWorkspaceIncidentUpdate(update) {
+  return update.incidentId !== null && (update.status === "resolved" || update.status === "confirmed" || update.status === "reset");
+}
+class WorkspaceIncidentOrderingFence {
+  constructor(historyLimit = DEFAULT_TERMINAL_INCIDENT_HISTORY_LIMIT) {
+    this.historyLimit = historyLimit;
+    if (!Number.isSafeInteger(historyLimit) || historyLimit < 1) {
+      throw new Error("Workspace incident history limit must be a positive integer");
+    }
+  }
+  historyLimit;
+  terminalIncidentIds = /* @__PURE__ */ new Set();
+  terminalIncidentOrder = [];
+  observe(update) {
+    if (!isTerminalWorkspaceIncidentUpdate(update) || this.terminalIncidentIds.has(update.incidentId)) return;
+    this.terminalIncidentIds.add(update.incidentId);
+    this.terminalIncidentOrder.push(update.incidentId);
+    while (this.terminalIncidentOrder.length > this.historyLimit) {
+      const expired = this.terminalIncidentOrder.shift();
+      if (expired) this.terminalIncidentIds.delete(expired);
+    }
+  }
+  permitsBlockedResponse(incidentId) {
+    if (!incidentId) return false;
+    return !this.terminalIncidentIds.has(incidentId);
+  }
+}
 function applyWorkspaceIncidentUpdate(currentIncidentId, update) {
   if (update.status === "remediating" || update.status === "waiting_for_worker") return update.incidentId;
   if (currentIncidentId && update.incidentId && update.incidentId !== currentIncidentId) return currentIncidentId;
   return null;
 }
 function releasePendingWorkspaceHead(previousIncidentId, currentIncidentId, terminalIncidentId) {
-  if (!previousIncidentId || currentIncidentId) return { syncHead: null };
-  if (terminalIncidentId === previousIncidentId) return { syncHead: "authoritative" };
-  return { syncHead: null };
+  if (!previousIncidentId || currentIncidentId) return { fetchAuthoritativeHead: false };
+  return { fetchAuthoritativeHead: terminalIncidentId === previousIncidentId };
 }
 export {
+  WorkspaceIncidentOrderingFence,
   applyWorkspaceIncidentUpdate,
   releasePendingWorkspaceHead
 };

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

@@ -0,0 +1,35 @@
+import fs from "node:fs";
+import path from "node:path";
+import { legacyProjectSlug, managedProjectRoot } from "./managed-paths.mjs";
+function hasNormalGitDirectory(checkoutPath) {
+  const gitPath = path.join(checkoutPath, ".git");
+  return fs.existsSync(gitPath) && fs.statSync(gitPath).isDirectory();
+}
+function inspectWorkspaceManifestAdmission(input) {
+  const firstBootstrap = !hasNormalGitDirectory(input.workspaceShadowRoot);
+  const missingCheckouts = [];
+  const migratedProjectIds = [];
+  for (const project of input.projects) {
+    const projectRoot = managedProjectRoot(input.projectsRoot, project.checkoutPathSegments);
+    const legacyRoot = path.join(input.projectsRoot, legacyProjectSlug(project.projectPath, project.projectId));
+    if (fs.existsSync(legacyRoot)) migratedProjectIds.push(project.projectId);
+    for (const branchName of project.branches) {
+      if (!hasNormalGitDirectory(path.join(projectRoot, branchName))) {
+        missingCheckouts.push({ projectId: project.projectId, branchName });
+      }
+    }
+  }
+  return {
+    firstBootstrap,
+    missingCheckouts,
+    migratedProjectIds,
+    requiresVisibleLease: firstBootstrap || migratedProjectIds.length > 0
+  };
+}
+async function acquireWorkspaceManifestVisibleLease(gate, admission) {
+  return admission.requiresVisibleLease ? await gate.acquireCheckpoint() : void 0;
+}
+export {
+  acquireWorkspaceManifestVisibleLease,
+  inspectWorkspaceManifestAdmission
+};