@ricsam/r5d-worker 0.0.58 → 0.0.60

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

@@ -2,8 +2,8 @@ import { type CheckoutPathSegments } from "./managed-paths";
 import { type WorkspaceMutationLease } from "./workspace-mutation-gate";
 export declare const WORKSPACE_BRANCH = "main";
 export declare const WORKSPACE_INTENT_REF_PREFIX = "refs/r5d/workspace-intents/";
+export declare const WORKSPACE_PUBLICATION_REF_PREFIX = "refs/r5d/workspace-publications/";
 export declare const MAX_WORKSPACE_SYNC_DIFF_BYTES: number;
-export declare const WORKSPACE_PERIODIC_SCAN_INTERVAL_MS = 5000;
 export type WorkspaceProjectManifestEntry = {
     projectId: string;
     checkoutPathSegments: CheckoutPathSegments;
@@ -51,17 +51,13 @@ export type WorkspaceSyncResult = {
     affectedPaths: string[];
     discardedPaths: string[];
     localChangesDiscarded: boolean;
+    dirtyGeneration?: number;
     sampledCanonicalCheckoutTreeHash?: string;
     telemetry?: {
         totalMs: number;
         queueMs: number;
         prepareMs: number;
         synchronizeMs: number;
-        fastPath: {
-            hit: boolean;
-            reason: string;
-            proofAgeMs?: number;
-        };
     };
     error?: string;
 };
@@ -80,6 +76,8 @@ export type WorkspaceSyncInput = {
      * Workers never publish the canonical workspace branch directly.
      */
     quarantineRef?: string;
+    /** Exact canonical head fenced by publication authority. */
+    expectedCanonicalHead?: string | null;
     confirmedLargeDiff?: boolean;
     confirmationReason?: string;
     resetToCanonical?: boolean;
@@ -124,6 +122,25 @@ export declare function mirrorVisibleWorkspaceToShadow(input: WorkspaceSyncInput
 export declare function mirrorShadowWorkspaceToVisible(input: WorkspaceSyncInput, opaqueWorkspaceRoots?: readonly string[], hydrationPreimages?: VisibleHydrationPreimages): void;
 export declare function assertWorkspaceQuarantineRef(quarantineRef: string): void;
 export declare function synchronizeWorkspace(rawInput: WorkspaceSyncInput): Promise<WorkspaceSyncResult>;
+export type WorkspaceHeadConvergenceResult = {
+    localHead: string | null;
+    canonicalHead: string | null;
+    localChanges: boolean;
+    hydrated: boolean;
+    hydrationConflicts: string[];
+};
+/**
+ * Fetches the newest canonical head without treating an inbound overlap as an
+ * incident. A busy caller passes hydrateVisible=false, which updates only the
+ * remote-tracking ref. An idle caller may hydrate only after proving that its
+ * visible tree still matches the local workspace head.
+ */
+export declare function convergeWorkspaceHead(rawInput: WorkspaceSyncInput, options: {
+    hydrateVisible: boolean;
+}): Promise<WorkspaceHeadConvergenceResult>;
+/** Returns a local-only fingerprint. Unlike the legacy periodic observation it
+ * deliberately ignores whether origin/main has advanced. */
+export declare function calculateWorkspaceLocalDiffFingerprint(rawInput: WorkspaceSyncInput): string;
 export declare function calculateWorkspaceDiffFingerprint(rawInput: WorkspaceSyncInput): string;
 export declare class WorkspaceSyncSingleFlight {
     private readonly mutationGate;

package/package.json

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

package/dist/cjs/workspace-sync-fast-path.cjs

@@ -1,108 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var workspace_sync_fast_path_exports = {};
-__export(workspace_sync_fast_path_exports, {
-  RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS: () => RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS,
-  RecentWorkspaceSyncProofCache: () => RecentWorkspaceSyncProofCache,
-  readShadowWorkspaceCanonicalHead: () => readShadowWorkspaceCanonicalHead,
-  workspaceSyncScopeKey: () => workspaceSyncScopeKey
-});
-module.exports = __toCommonJS(workspace_sync_fast_path_exports);
-var import_node_crypto = require("node:crypto");
-const RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS = 15e3;
-function stableProjectShape(project) {
-  return {
-    projectId: project.projectId,
-    checkoutPathSegments: [...project.checkoutPathSegments],
-    projectPath: project.projectPath,
-    repoHttpUrl: project.repoHttpUrl,
-    defaultBranch: project.defaultBranch,
-    branches: [...project.branches].sort(),
-    canonicalCheckouts: [...project.canonicalCheckouts].sort(
-      (left, right) => left.branchName.localeCompare(right.branchName) || left.scaffoldCommitHash.localeCompare(right.scaffoldCommitHash)
-    )
-  };
-}
-function workspaceSyncScopeKey(remoteUrl, projects) {
-  const stableProjects = [...projects].map(stableProjectShape).sort((left, right) => left.projectId.localeCompare(right.projectId) || left.projectPath.localeCompare(right.projectPath));
-  return (0, import_node_crypto.createHash)("sha256").update(JSON.stringify({ remoteUrl, projects: stableProjects })).digest("hex");
-}
-function readShadowWorkspaceCanonicalHead(shadowRoot) {
-  const result = Bun.spawnSync(["git", "rev-parse", "--verify", "HEAD"], {
-    cwd: shadowRoot,
-    stdout: "pipe",
-    stderr: "ignore"
-  });
-  if (result.exitCode !== 0) return null;
-  const head = result.stdout.toString().trim();
-  return /^[0-9a-f]{40,64}$/.test(head) ? head : null;
-}
-class RecentWorkspaceSyncProofCache {
-  constructor(maxAgeMs = RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS) {
-    this.maxAgeMs = maxAgeMs;
-  }
-  maxAgeMs;
-  generation = 0;
-  proof = null;
-  beginObservation() {
-    return this.generation;
-  }
-  invalidate() {
-    this.generation += 1;
-  }
-  recordStable(input) {
-    if (input.observationGeneration !== this.generation || input.workerBusy || !input.canonicalHead || !/^[0-9a-f]{40,64}$/.test(input.canonicalHead)) {
-      return false;
-    }
-    this.proof = {
-      canonicalHead: input.canonicalHead,
-      scopeKey: input.scopeKey,
-      observedAtMs: input.observedAtMs,
-      generation: this.generation
-    };
-    return true;
-  }
-  evaluate(input) {
-    if (!input.allowRecentNoChangeFastPath || input.trigger.type !== "inbound_head") {
-      return { hit: false, reason: "unsupported_trigger" };
-    }
-    if (input.trigger.canonicalCheckoutOnly) return { hit: false, reason: "canonical_checkout" };
-    if (input.skipVisibleMirror) return { hit: false, reason: "visible_mirror_skipped" };
-    if (input.resetToCanonical) return { hit: false, reason: "reset_requested" };
-    if (input.incidentActive) return { hit: false, reason: "incident_active" };
-    if (input.workerBusy) return { hit: false, reason: "worker_busy" };
-    if (input.pendingCheckouts) return { hit: false, reason: "pending_checkouts" };
-    if (!input.canonicalHead) return { hit: false, reason: "canonical_head_missing" };
-    const proof = this.proof;
-    if (!proof) return { hit: false, reason: "no_recent_proof" };
-    if (proof.generation !== this.generation) return { hit: false, reason: "proof_invalidated" };
-    const proofAgeMs = Math.max(0, input.nowMs - proof.observedAtMs);
-    if (proofAgeMs > this.maxAgeMs) return { hit: false, reason: "proof_expired" };
-    if (proof.scopeKey !== input.scopeKey) return { hit: false, reason: "scope_changed" };
-    if (proof.canonicalHead !== input.canonicalHead) return { hit: false, reason: "canonical_head_changed" };
-    return { hit: true, reason: "recent_stable_no_change", canonicalHead: proof.canonicalHead, proofAgeMs };
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS,
-  RecentWorkspaceSyncProofCache,
-  readShadowWorkspaceCanonicalHead,
-  workspaceSyncScopeKey
-});

package/dist/mjs/workspace-sync-fast-path.mjs

@@ -1,81 +0,0 @@
-import { createHash } from "node:crypto";
-const RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS = 15e3;
-function stableProjectShape(project) {
-  return {
-    projectId: project.projectId,
-    checkoutPathSegments: [...project.checkoutPathSegments],
-    projectPath: project.projectPath,
-    repoHttpUrl: project.repoHttpUrl,
-    defaultBranch: project.defaultBranch,
-    branches: [...project.branches].sort(),
-    canonicalCheckouts: [...project.canonicalCheckouts].sort(
-      (left, right) => left.branchName.localeCompare(right.branchName) || left.scaffoldCommitHash.localeCompare(right.scaffoldCommitHash)
-    )
-  };
-}
-function workspaceSyncScopeKey(remoteUrl, projects) {
-  const stableProjects = [...projects].map(stableProjectShape).sort((left, right) => left.projectId.localeCompare(right.projectId) || left.projectPath.localeCompare(right.projectPath));
-  return createHash("sha256").update(JSON.stringify({ remoteUrl, projects: stableProjects })).digest("hex");
-}
-function readShadowWorkspaceCanonicalHead(shadowRoot) {
-  const result = Bun.spawnSync(["git", "rev-parse", "--verify", "HEAD"], {
-    cwd: shadowRoot,
-    stdout: "pipe",
-    stderr: "ignore"
-  });
-  if (result.exitCode !== 0) return null;
-  const head = result.stdout.toString().trim();
-  return /^[0-9a-f]{40,64}$/.test(head) ? head : null;
-}
-class RecentWorkspaceSyncProofCache {
-  constructor(maxAgeMs = RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS) {
-    this.maxAgeMs = maxAgeMs;
-  }
-  maxAgeMs;
-  generation = 0;
-  proof = null;
-  beginObservation() {
-    return this.generation;
-  }
-  invalidate() {
-    this.generation += 1;
-  }
-  recordStable(input) {
-    if (input.observationGeneration !== this.generation || input.workerBusy || !input.canonicalHead || !/^[0-9a-f]{40,64}$/.test(input.canonicalHead)) {
-      return false;
-    }
-    this.proof = {
-      canonicalHead: input.canonicalHead,
-      scopeKey: input.scopeKey,
-      observedAtMs: input.observedAtMs,
-      generation: this.generation
-    };
-    return true;
-  }
-  evaluate(input) {
-    if (!input.allowRecentNoChangeFastPath || input.trigger.type !== "inbound_head") {
-      return { hit: false, reason: "unsupported_trigger" };
-    }
-    if (input.trigger.canonicalCheckoutOnly) return { hit: false, reason: "canonical_checkout" };
-    if (input.skipVisibleMirror) return { hit: false, reason: "visible_mirror_skipped" };
-    if (input.resetToCanonical) return { hit: false, reason: "reset_requested" };
-    if (input.incidentActive) return { hit: false, reason: "incident_active" };
-    if (input.workerBusy) return { hit: false, reason: "worker_busy" };
-    if (input.pendingCheckouts) return { hit: false, reason: "pending_checkouts" };
-    if (!input.canonicalHead) return { hit: false, reason: "canonical_head_missing" };
-    const proof = this.proof;
-    if (!proof) return { hit: false, reason: "no_recent_proof" };
-    if (proof.generation !== this.generation) return { hit: false, reason: "proof_invalidated" };
-    const proofAgeMs = Math.max(0, input.nowMs - proof.observedAtMs);
-    if (proofAgeMs > this.maxAgeMs) return { hit: false, reason: "proof_expired" };
-    if (proof.scopeKey !== input.scopeKey) return { hit: false, reason: "scope_changed" };
-    if (proof.canonicalHead !== input.canonicalHead) return { hit: false, reason: "canonical_head_changed" };
-    return { hit: true, reason: "recent_stable_no_change", canonicalHead: proof.canonicalHead, proofAgeMs };
-  }
-}
-export {
-  RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS,
-  RecentWorkspaceSyncProofCache,
-  readShadowWorkspaceCanonicalHead,
-  workspaceSyncScopeKey
-};

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

@@ -1,69 +0,0 @@
-export declare const RECENT_WORKSPACE_SYNC_PROOF_MAX_AGE_MS = 15000;
-export type WorkspaceSyncFastPathMissReason = "unsupported_trigger" | "canonical_checkout" | "visible_mirror_skipped" | "reset_requested" | "incident_active" | "worker_busy" | "pending_checkouts" | "canonical_head_missing" | "no_recent_proof" | "proof_invalidated" | "proof_expired" | "scope_changed" | "canonical_head_changed";
-export type WorkspaceSyncFastPathDecision = {
-    hit: true;
-    reason: "recent_stable_no_change";
-    canonicalHead: string;
-    proofAgeMs: number;
-} | {
-    hit: false;
-    reason: WorkspaceSyncFastPathMissReason;
-};
-type WorkspaceSyncScopeProject = {
-    projectId: string;
-    checkoutPathSegments: readonly string[];
-    projectPath: string;
-    repoHttpUrl: string | null;
-    defaultBranch: string;
-    branches: readonly string[];
-    canonicalCheckouts: ReadonlyArray<{
-        branchName: string;
-        scaffoldCommitHash: string;
-    }>;
-};
-type WorkspaceSyncFastPathInput = {
-    trigger: {
-        type: string;
-        canonicalCheckoutOnly?: boolean;
-    };
-    allowRecentNoChangeFastPath: boolean;
-    canonicalHead?: string | null;
-    scopeKey: string;
-    nowMs: number;
-    skipVisibleMirror?: boolean;
-    resetToCanonical?: boolean;
-    incidentActive: boolean;
-    workerBusy: boolean;
-    pendingCheckouts: boolean;
-};
-/**
- * Fingerprints the inputs that determine which visible paths participate in a
- * generic workspace scan. Authentication headers are deliberately excluded.
- */
-export declare function workspaceSyncScopeKey(remoteUrl: string, projects: readonly WorkspaceSyncScopeProject[]): string;
-export declare function readShadowWorkspaceCanonicalHead(shadowRoot: string): string | null;
-/**
- * A short-lived proof cache for the duplicate scan between the worker's
- * periodic stable-fingerprint pass and an immediately following agent start.
- *
- * The proof is process/connection local. Callers invalidate it before every
- * known local mutation and retain an observation generation while a scan is
- * running, so a mutation racing the scan cannot publish a usable proof.
- */
-export declare class RecentWorkspaceSyncProofCache {
-    private readonly maxAgeMs;
-    private generation;
-    private proof;
-    constructor(maxAgeMs?: number);
-    beginObservation(): number;
-    invalidate(): void;
-    recordStable(input: {
-        observationGeneration: number;
-        canonicalHead: string | null;
-        scopeKey: string;
-        observedAtMs: number;
-        workerBusy: boolean;
-    }): boolean;
-    evaluate(input: WorkspaceSyncFastPathInput): WorkspaceSyncFastPathDecision;
-}
-export {};