@ricsam/r5d-worker 0.0.58 → 0.0.60

package/dist/mjs/package.json

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

package/dist/mjs/workspace-convergence.mjs

@@ -0,0 +1,213 @@
+import fs from "node:fs";
+import path from "node:path";
+const WORKSPACE_PUBLICATION_QUIET_MS = 5e3;
+const WORKSPACE_IDLE_SAFETY_SCAN_MS = 6e4;
+const WORKSPACE_MANIFEST_REVISION_PATTERN = /^[0-9a-f]{64}$/;
+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 workspacePublicationTelemetry(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 workspacePublicationIncidentAction(requestId) {
+  return requestId ? "request_terminal_authority" : "defer_automatic";
+}
+class ExplicitWorkspacePublicationQueue {
+  scheduled;
+  queued = [];
+  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(publication);
+      return false;
+    }
+    this.scheduled = publication;
+    return true;
+  }
+  hasScheduled() {
+    return this.scheduled !== void 0;
+  }
+  consumeScheduled(requestId) {
+    if (this.scheduled?.requestId === requestId) this.scheduled = void 0;
+  }
+  enqueue(publication, pendingRequestId) {
+    if (pendingRequestId === publication.requestId || this.scheduled?.requestId === publication.requestId || this.queued.some((queued) => queued.requestId === publication.requestId)) {
+      return;
+    }
+    this.queued.push(publication);
+  }
+  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.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  }
+  statePath;
+  state;
+  publicationState;
+  snapshot() {
+    return { ...this.state, publicationState: this.publicationState };
+  }
+  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.publicationState === "idle") this.publicationState = "scheduled";
+    this.persist();
+    return this.state.dirtyGeneration;
+  }
+  schedule() {
+    if (this.publicationState === "idle") this.publicationState = "scheduled";
+  }
+  beginPreparing() {
+    if (this.publicationState === "preparing" || this.publicationState === "submitting") {
+      throw new Error("A workspace publication is already in flight");
+    }
+    this.publicationState = "preparing";
+  }
+  beginSubmitting() {
+    if (this.publicationState !== "preparing") throw new Error("Workspace publication authority was not prepared");
+    this.publicationState = "submitting";
+  }
+  defer() {
+    this.publicationState = "scheduled";
+  }
+  block() {
+    this.publicationState = "blocked";
+  }
+  releaseBlock() {
+    this.publicationState = this.state.dirtyGeneration > this.state.publishedGeneration ? "scheduled" : "idle";
+  }
+  observeIncidentState(blocked) {
+    if (this.publicationState === "preparing" || this.publicationState === "submitting") return;
+    if (blocked) this.block();
+    else this.releaseBlock();
+  }
+  resetTransientPublicationState() {
+    this.publicationState = 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.publicationState = 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 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.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 {
+  ExplicitWorkspacePublicationQueue,
+  WORKSPACE_IDLE_SAFETY_SCAN_MS,
+  WORKSPACE_PUBLICATION_QUIET_MS,
+  WorkspaceConvergenceState,
+  WorkspaceManifestRevisionFence,
+  processWorkspaceConvergenceState,
+  readWorkspaceConvergenceState,
+  waitForWorkspacePublicationOnShutdown,
+  workspacePublicationIncidentAction,
+  workspacePublicationTelemetry
+};

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,30 @@
+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 inspectWorkspaceManifestFilesystem(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
+  };
+}
+export {
+  inspectWorkspaceManifestFilesystem
+};

package/dist/mjs/workspace-sync.mjs

@@ -5,8 +5,8 @@ import { managedBranchPath } from "./managed-paths.mjs";
 import { WorkspaceMutationGate } from "./workspace-mutation-gate.mjs";
 const WORKSPACE_BRANCH = "main";
 const WORKSPACE_INTENT_REF_PREFIX = "refs/r5d/workspace-intents/";
+const WORKSPACE_PUBLICATION_REF_PREFIX = "refs/r5d/workspace-publications/";
 const MAX_WORKSPACE_SYNC_DIFF_BYTES = 5 * 1024 * 1024;
-const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5e3;
 const MAX_REPORTED_WORKSPACE_PATHS = 2e3;
 const MAX_REPORTED_WORKSPACE_STATUS_BYTES = 256 * 1024;
 const MAX_MIRROR_COMPARISON_CACHE_ENTRIES = 2e5;
@@ -1705,9 +1705,10 @@ function commitMessage(input) {
   });
 }
 function assertWorkspaceQuarantineRef(quarantineRef) {
-  const suffix = quarantineRef.slice(WORKSPACE_INTENT_REF_PREFIX.length);
-  if (!quarantineRef.startsWith(WORKSPACE_INTENT_REF_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_INTENT_REF_PREFIX}`);
+  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}`);
   }
   const result = Bun.spawnSync(["git", "check-ref-format", quarantineRef], {
     stdout: "pipe",
@@ -1827,6 +1828,36 @@ function preserveWorkspaceConflictCandidate(input, observed, options) {
     };
   }
 }
+function preserveLargeDiffCandidate(input, observed, error) {
+  try {
+    if (stagedPaths(input).length > 0) {
+      runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit blocked workspace candidate");
+    }
+    const candidateHead = revParse(input, "HEAD");
+    if (!candidateHead) throw new Error("the blocked workspace candidate does not have a commit");
+    assertUnscopedCanonicalCheckoutSubtreesMatchRemote(input, candidateHead);
+    const upload = uploadWorkspaceCandidate(input, candidateHead);
+    if (upload.exitCode !== 0) {
+      throw new Error(upload.stderr || upload.stdout || "blocked workspace candidate upload failed");
+    }
+    return {
+      ...observed,
+      outcome: "large_diff_blocked",
+      expectedHead: revParse(input, `origin/${WORKSPACE_BRANCH}`),
+      candidateHead,
+      quarantineRef: input.quarantineRef,
+      error,
+      gitStatus: gitStatus(input)
+    };
+  } catch (candidateError) {
+    return {
+      ...observed,
+      outcome: "failed",
+      error: `Workspace safety guard blocked publication but could not preserve a durable candidate: ${candidateError instanceof Error ? candidateError.message : String(candidateError)}`,
+      gitStatus: gitStatus(input)
+    };
+  }
+}
 async function synchronizeWorkspace(rawInput) {
   let input = { ...rawInput, attemptId: rawInput.attemptId ?? crypto.randomUUID() };
   try {
@@ -1838,6 +1869,15 @@ async function synchronizeWorkspace(rawInput) {
     let hydrationPreimages = input.skipVisibleMirror ? hydrationPreimagesFromShadowRevision(input, shadowWasCreated ? null : revParse(input, "HEAD")) : /* @__PURE__ */ new Map();
     const remoteHeadAtStart = revParse(input, `origin/${WORKSPACE_BRANCH}`);
     const result = baseResult(input, remoteHeadAtStart);
+    if (input.expectedCanonicalHead !== void 0 && remoteHeadAtStart !== input.expectedCanonicalHead) {
+      return {
+        ...result,
+        outcome: "failed",
+        expectedHead: input.expectedCanonicalHead,
+        publishedHead: remoteHeadAtStart ?? void 0,
+        error: `canonical_head_advanced: expected ${input.expectedCanonicalHead ?? "unborn"}, fetched ${remoteHeadAtStart ?? "unborn"}`
+      };
+    }
     const inboundConflictsAtStart = input.skipVisibleMirror && !isCanonicalRemediationSync && remoteHeadAtStart ? visibleHydrationConflictPaths(input, hydrationPreimages, `origin/${WORKSPACE_BRANCH}`) : [];
     if (input.resetToCanonical) {
       if (input.trigger.canonicalCheckoutOnly) {
@@ -1886,18 +1926,14 @@ 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 {
-        ...observed,
-        outcome: "large_diff_blocked",
-        error: `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 {
-        ...observed,
-        outcome: "large_diff_blocked",
-        error: `Workspace safety guard blocked a ${diffSizeBytes}-byte diff above the ${MAX_WORKSPACE_SYNC_DIFF_BYTES}-byte automatic publication limit.`
-      };
+      return preserveLargeDiffCandidate(
+        input,
+        observed,
+        `Workspace safety guard blocked a ${diffSizeBytes}-byte diff above the ${MAX_WORKSPACE_SYNC_DIFF_BYTES}-byte automatic publication limit.`
+      );
     }
     if (stagedWorkingPaths.length > 0) {
       runGit(input, input.shadowRoot, ["commit", "-m", commitMessage(input)], "commit workspace changes");
@@ -2062,6 +2098,79 @@ async function synchronizeWorkspace(rawInput) {
     };
   }
 }
+async function convergeWorkspaceHead(rawInput, options) {
+  const input = {
+    ...rawInput,
+    projects: workspaceProjectsForSync(rawInput.projects, rawInput.trigger)
+  };
+  if (input.trigger.canonicalCheckoutOnly) {
+    throw new Error("Ordinary inbound convergence cannot target a canonical resolver checkout");
+  }
+  ensureShadowWorkspace(input);
+  const fetchedLocalHead = revParse(input, "HEAD");
+  const fetchedCanonicalHead = revParse(input, `origin/${WORKSPACE_BRANCH}`);
+  if (!options.hydrateVisible) {
+    return {
+      localHead: fetchedLocalHead,
+      canonicalHead: fetchedCanonicalHead,
+      localChanges: false,
+      hydrated: false,
+      hydrationConflicts: []
+    };
+  }
+  resetUncommittedShadowSnapshot(input);
+  restoreUnscopedCanonicalCheckoutSubtrees(input);
+  const localHead = fetchedLocalHead;
+  const canonicalHead = fetchedCanonicalHead;
+  const projection = mirrorVisibleWorkspaceToShadow(input);
+  runGit(
+    input,
+    input.shadowRoot,
+    ["add", "-A", "--", ".", ...projection.opaqueRoots.map((root) => `:(exclude,literal)${root}`)],
+    "stage inbound workspace observation"
+  );
+  forceStageCanonicalCheckoutFiles(input, projection.entries, projection.opaqueRoots);
+  const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write inbound workspace observation tree");
+  const headTree = localHead ? revParse(input, `${localHead}^{tree}`) : null;
+  const localChanges = stagedTree !== headTree;
+  if (!options.hydrateVisible || localChanges || !canonicalHead || localHead === canonicalHead) {
+    resetUncommittedShadowSnapshot(input);
+    return { localHead, canonicalHead, localChanges, hydrated: false, hydrationConflicts: [] };
+  }
+  const preimages = projection.visiblePreimages ?? hydrationPreimagesFromShadowRevision(input, localHead);
+  const hydrationConflicts = localHead ? hydrationConflictPaths(input, preimages, localHead, canonicalHead) : [];
+  if (hydrationConflicts.length > 0) {
+    resetUncommittedShadowSnapshot(input);
+    return { localHead, canonicalHead, localChanges: true, hydrated: false, hydrationConflicts };
+  }
+  runGit(input, input.shadowRoot, ["reset", "--hard", canonicalHead], "fast-forward workspace to available canonical head");
+  runGit(input, input.shadowRoot, ["clean", "-fd"], "clean fast-forwarded workspace");
+  mirrorShadowWorkspaceToVisible(input, projection.opaqueRoots, preimages);
+  return { localHead: canonicalHead, canonicalHead, localChanges: false, hydrated: true, hydrationConflicts: [] };
+}
+function calculateWorkspaceLocalDiffFingerprint(rawInput) {
+  const input = {
+    ...rawInput,
+    projects: workspaceProjectsForSync(rawInput.projects, rawInput.trigger)
+  };
+  if (!fs.existsSync(path.join(input.shadowRoot, ".git"))) {
+    throw new Error("Cannot inspect local workspace changes before first bootstrap");
+  }
+  resetUncommittedShadowSnapshot(input);
+  restoreUnscopedCanonicalCheckoutSubtrees(input);
+  const projection = mirrorVisibleWorkspaceToShadow(input);
+  runGit(
+    input,
+    input.shadowRoot,
+    ["add", "-A", "--", ".", ...projection.opaqueRoots.map((root) => `:(exclude,literal)${root}`)],
+    "stage local workspace fingerprint"
+  );
+  forceStageCanonicalCheckoutFiles(input, projection.entries, projection.opaqueRoots);
+  const stagedTree = runGit(input, input.shadowRoot, ["write-tree"], "write local workspace fingerprint tree");
+  const headTree = revParse(input, "HEAD^{tree}");
+  resetUncommittedShadowSnapshot(input);
+  return stagedTree === headTree ? createHash("sha256").update("").digest("hex") : createHash("sha256").update(stagedTree).digest("hex");
+}
 function calculateWorkspaceDiffFingerprint(rawInput) {
   const input = {
     ...rawInput,
@@ -2133,11 +2242,13 @@ export {
   WORKSPACE_BRANCH,
   WORKSPACE_INTENT_REF_PREFIX,
   WORKSPACE_NATIVE_PLANS_RELATIVE_PATH,
-  WORKSPACE_PERIODIC_SCAN_INTERVAL_MS,
+  WORKSPACE_PUBLICATION_REF_PREFIX,
   WorkspaceSyncSingleFlight,
   assertCanonicalCheckoutIndexMatchesWorktree,
   assertWorkspaceQuarantineRef,
   calculateWorkspaceDiffFingerprint,
+  calculateWorkspaceLocalDiffFingerprint,
+  convergeWorkspaceHead,
   encodeWorkspaceBranch,
   mirrorShadowWorkspaceToVisible,
   mirrorVisibleWorkspaceToShadow,

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

@@ -0,0 +1,82 @@
+export declare const WORKSPACE_PUBLICATION_QUIET_MS = 5000;
+export declare const WORKSPACE_IDLE_SAFETY_SCAN_MS = 60000;
+export type WorkspacePublicationState = "idle" | "scheduled" | "preparing" | "submitting" | "blocked";
+export type WorkspaceConvergenceSnapshot = {
+    localHead: string | null;
+    desiredCanonicalHead: string | null;
+    dirtyGeneration: number;
+    publishedGeneration: number;
+    publicationState: WorkspacePublicationState;
+};
+export type ExplicitWorkspacePublication<TTrigger> = {
+    requestId: string;
+    trigger: TTrigger;
+};
+export type WorkspaceManifestRevisionToken = {
+    sequence: number;
+    revision: string;
+};
+export declare class WorkspaceManifestRevisionFence {
+    private sequence;
+    private requestedRevision;
+    private completedRevision;
+    begin(revision: string): WorkspaceManifestRevisionToken;
+    isCurrent(token: WorkspaceManifestRevisionToken): boolean;
+    complete(token: WorkspaceManifestRevisionToken): boolean;
+    readyRevision(): string | null;
+}
+export declare function workspacePublicationTelemetry(input: {
+    requestedAt: number;
+    prepareStartedAt: number;
+    synchronizeStartedAt: number;
+    finishedAt: number;
+}): {
+    totalMs: number;
+    queueMs: number;
+    prepareMs: number;
+    synchronizeMs: number;
+};
+export declare function workspacePublicationIncidentAction(requestId: string | undefined): "defer_automatic" | "request_terminal_authority";
+export declare class ExplicitWorkspacePublicationQueue<TTrigger> {
+    private scheduled;
+    private readonly queued;
+    schedule(publication: ExplicitWorkspacePublication<TTrigger>, pendingRequestId?: string): boolean;
+    hasScheduled(): boolean;
+    consumeScheduled(requestId: string): void;
+    enqueue(publication: ExplicitWorkspacePublication<TTrigger>, pendingRequestId?: string): void;
+    next(): ExplicitWorkspacePublication<TTrigger> | undefined;
+}
+type PersistedWorkspaceConvergenceState = Omit<WorkspaceConvergenceSnapshot, "publicationState">;
+export declare function readWorkspaceConvergenceState(statePath: string): PersistedWorkspaceConvergenceState;
+export declare class WorkspaceConvergenceState {
+    private readonly statePath;
+    private state;
+    private publicationState;
+    constructor(statePath: string);
+    snapshot(): WorkspaceConvergenceSnapshot;
+    setLocalHead(localHead: string | null): void;
+    observeCanonicalHead(canonicalHead: string | null): boolean;
+    markDirty(): number;
+    schedule(): void;
+    beginPreparing(): void;
+    beginSubmitting(): void;
+    defer(): void;
+    block(): void;
+    releaseBlock(): void;
+    observeIncidentState(blocked: boolean): void;
+    resetTransientPublicationState(): void;
+    complete(input: {
+        generation: number;
+        canonicalHead: string | null;
+        published: boolean;
+    }): void;
+    private persist;
+}
+export declare function processWorkspaceConvergenceState(statePath: string): WorkspaceConvergenceState;
+export declare function waitForWorkspacePublicationOnShutdown(input: {
+    snapshot: () => WorkspaceConvergenceSnapshot;
+    forcePublication: () => void;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<"settled" | "blocked" | "timed_out">;
+export {};

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

@@ -2,7 +2,21 @@ export type WorkspaceIncidentUpdate = {
     incidentId: string | null;
     status: "remediating" | "waiting_for_worker" | "resolved" | "confirmed" | "reset" | null;
 };
+/**
+ * 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 publication response cannot
+ * resurrect a barrier that this connection has already observed as terminal.
+ */
+export declare class WorkspaceIncidentOrderingFence {
+    private readonly historyLimit;
+    private readonly terminalIncidentIds;
+    private readonly terminalIncidentOrder;
+    constructor(historyLimit?: number);
+    observe(update: WorkspaceIncidentUpdate): void;
+    permitsBlockedResponse(incidentId: string | null | undefined): boolean;
+}
 export declare function applyWorkspaceIncidentUpdate(currentIncidentId: string | null, update: WorkspaceIncidentUpdate): string | null;
 export declare function releasePendingWorkspaceHead(previousIncidentId: string | null, currentIncidentId: string | null, terminalIncidentId?: string | null): {
-    syncHead: string | null;
+    fetchAuthoritativeHead: boolean;
 };

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

@@ -0,0 +1,24 @@
+export type WorkspaceManifestCheckout = {
+    projectId: string;
+    projectPath: string;
+    checkoutPathSegments: [namespace: string, project: string];
+    branches: string[];
+};
+export type WorkspaceManifestFilesystemState = {
+    firstBootstrap: boolean;
+    missingCheckouts: Array<{
+        projectId: string;
+        branchName: string;
+    }>;
+    migratedProjectIds: string[];
+};
+/**
+ * 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 inspectWorkspaceManifestFilesystem(input: {
+    projectsRoot: string;
+    workspaceShadowRoot: string;
+    projects: WorkspaceManifestCheckout[];
+}): WorkspaceManifestFilesystemState;