@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/dist/chunk-4US4SYJ4.js

@@ -0,0 +1,569 @@
+import {
+  StaleVersionError
+} from "./chunk-TDSEX5CF.js";
+import {
+  loadMachineId,
+  readMachineIdIfPresent,
+  shortMachineId
+} from "./chunk-7KBEOPVB.js";
+import {
+  evaluateStaleReclaim
+} from "./chunk-P7CQGPLS.js";
+
+// src/planning/coordination/backend.ts
+import { randomUUID } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+// src/planning/coordination/cas.ts
+function checkVersion(entityId, currentVersion, expectedVersion) {
+  if (currentVersion !== expectedVersion) {
+    throw new StaleVersionError(currentVersion, expectedVersion, entityId);
+  }
+}
+
+// src/planning/coordination/backend.ts
+var DEFAULT_STALE_LOCK_MS = 30 * 60 * 1e3;
+var DEFAULT_PUBLISH_LOCK_DELAYS_MS = [0, 100, 200, 400, 800, 1600, 2400, 2500];
+var LocalFileBackend = class {
+  locksDir;
+  kvDir;
+  publishLockDelaysMs;
+  /**
+   * @param stateDir - Root directory for coordination state.
+   *   Subdirectories `locks/` and `kv/` will be created as needed.
+   * @param opts - Optional backend options (e.g. publishLockDelaysMs for tests).
+   */
+  constructor(stateDir, opts) {
+    this.locksDir = path.join(stateDir, "locks");
+    this.kvDir = path.join(stateDir, "kv");
+    this.publishLockDelaysMs = opts?.publishLockDelaysMs ?? DEFAULT_PUBLISH_LOCK_DELAYS_MS;
+  }
+  /** Ensure the required subdirectories exist. */
+  ensureDirs() {
+    fs.mkdirSync(this.locksDir, { recursive: true });
+    fs.mkdirSync(this.kvDir, { recursive: true });
+  }
+  /** Derive the filesystem path for a lock file from its logical name. */
+  lockFilePath(lockName) {
+    const safe = lockName.replace(/[/\\]/g, "_");
+    return path.join(this.locksDir, `${safe}.lock`);
+  }
+  /** Derive the filesystem path for a kv record. */
+  kvFilePath(key) {
+    const safe = key.replace(/[/\\]/g, "_");
+    return path.join(this.kvDir, `${safe}.json`);
+  }
+  /** Build a lock handle after successful exclusive creation. */
+  lockHandle(lockPath, ownerToken, lockFd) {
+    const stat = fs.fstatSync(lockFd);
+    return { lockPath, ownerToken, lockFd, lockDev: stat.dev, lockIno: stat.ino };
+  }
+  createLockFile(lockPath, lockContent, ownerToken) {
+    const lockFd = fs.openSync(lockPath, "wx");
+    try {
+      fs.writeFileSync(lockFd, lockContent, { encoding: "utf8" });
+      return this.lockHandle(lockPath, ownerToken, lockFd);
+    } catch (error) {
+      try {
+        fs.closeSync(lockFd);
+      } catch {
+      }
+      try {
+        fs.unlinkSync(lockPath);
+      } catch {
+      }
+      throw error;
+    }
+  }
+  closeLockHandle(handle) {
+    if (handle.lockFd === void 0) {
+      return;
+    }
+    try {
+      fs.closeSync(handle.lockFd);
+    } catch {
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Lock operations
+  // -------------------------------------------------------------------------
+  async acquireLock(lockName, opts) {
+    if (lockName.startsWith("kv--")) {
+      throw new Error(
+        `acquireLock: lock name "${lockName}" uses the reserved "kv--" prefix. This namespace is reserved for internal publish() serialization locks. Choose a lock name that does not start with "kv--".`
+      );
+    }
+    return this._acquireLockUnchecked(lockName, opts);
+  }
+  /**
+   * Internal lock acquisition that bypasses the 'kv--' reservation check.
+   * Used exclusively by publish() for internal kv serialization locks.
+   */
+  async _acquireLockUnchecked(lockName, opts) {
+    this.ensureDirs();
+    const lockPath = this.lockFilePath(lockName);
+    const staleMs = opts?.staleMs ?? DEFAULT_STALE_LOCK_MS;
+    const ownerToken = randomUUID();
+    const lockContent = JSON.stringify({
+      pid: process.pid,
+      machineId: loadMachineId(),
+      ownerToken,
+      acquiredAt: (/* @__PURE__ */ new Date()).toISOString(),
+      actor: opts?.actor ?? null
+    });
+    try {
+      return this.createLockFile(lockPath, lockContent, ownerToken);
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw new Error(
+          `Failed to acquire lock ${lockName} at ${lockPath}: ${error.message}`
+        );
+      }
+    }
+    if (await this.tryBreakStaleLock(lockPath, staleMs)) {
+      try {
+        return this.createLockFile(lockPath, lockContent, ownerToken);
+      } catch (retryError) {
+        if (retryError.code === "EEXIST") {
+          return null;
+        }
+        throw new Error(
+          `Failed to acquire lock ${lockName} after stale break: ${retryError.message}`
+        );
+      }
+    }
+    return null;
+  }
+  /**
+   * Read a lock file's holder into the shared-policy observation shape.
+   *
+   * Returns null when the payload is missing, unparseable, or carries no usable
+   * pid — the shared policy treats that as a corrupt payload. A missing or
+   * legacy machineId yields `sameHost: false`, which under the backend's
+   * `foreignHost: 'never'` policy means the lock is never auto-broken. PID
+   * liveness uses signal 0; EPERM (exists but un-signalable) counts as alive.
+   */
+  readLockHolderFromContent(rawContent) {
+    let lockData;
+    try {
+      lockData = JSON.parse(rawContent);
+    } catch {
+      return null;
+    }
+    const pid = lockData.pid;
+    if (typeof pid !== "number") {
+      return null;
+    }
+    const sameHost = typeof lockData.machineId === "string" && lockData.machineId === loadMachineId();
+    let pidAlive = false;
+    if (sameHost) {
+      try {
+        process.kill(pid, 0);
+        pidAlive = true;
+      } catch (killError) {
+        pidAlive = killError.code !== "ESRCH";
+      }
+    }
+    return { sameHost, pidAlive };
+  }
+  readLockSnapshot(lockPath, stat) {
+    try {
+      return {
+        dev: stat.dev,
+        ino: stat.ino,
+        rawContent: fs.readFileSync(lockPath, "utf8")
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return "missing";
+      }
+      return "unreadable";
+    }
+  }
+  unlinkLockIfSnapshotMatches(lockPath, snapshot) {
+    let currentStat;
+    let currentRawContent;
+    try {
+      currentStat = fs.statSync(lockPath);
+      currentRawContent = fs.readFileSync(lockPath, "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return true;
+      }
+      return false;
+    }
+    if (currentStat.dev !== snapshot.dev || currentStat.ino !== snapshot.ino || currentRawContent !== snapshot.rawContent) {
+      return false;
+    }
+    fs.unlinkSync(lockPath);
+    return true;
+  }
+  /**
+   * Attempt to break a stale lock file.
+   *
+   * Returns true if the lock file was removed (all conditions met).
+   * Returns false if the lock is still live, cross-machine, or the payload is
+   * missing/unparseable.
+   *
+   * The reclaim/hold decision is delegated to the shared stale-lock policy with
+   * backend semantics: corrupt payloads are held, and foreign-machine locks are
+   * NEVER auto-broken (cross-machine pids cannot be verified, so a dead pid
+   * locally does not imply the remote owner is gone).
+   */
+  async tryBreakStaleLock(lockPath, staleMs) {
+    let stat;
+    try {
+      stat = fs.statSync(lockPath);
+    } catch {
+      return true;
+    }
+    const snapshot = this.readLockSnapshot(lockPath, stat);
+    if (snapshot === "missing") {
+      return true;
+    }
+    if (snapshot === "unreadable") {
+      return false;
+    }
+    const decision = evaluateStaleReclaim(
+      {
+        ageMs: Date.now() - stat.mtimeMs,
+        holder: this.readLockHolderFromContent(snapshot.rawContent)
+      },
+      // Original backend boundary: reclaim eligible at age >= staleMs.
+      { staleMs, corruptPayload: "hold", foreignHost: { kind: "never" }, ageBoundary: "gte" }
+    );
+    if (decision === "hold") {
+      return false;
+    }
+    try {
+      return this.unlinkLockIfSnapshotMatches(lockPath, snapshot);
+    } catch (unlinkError) {
+      if (unlinkError.code === "ENOENT") {
+        return true;
+      }
+      throw new Error(
+        `Failed to remove stale lock at ${lockPath}: ${unlinkError.message}`
+      );
+    }
+  }
+  async releaseLock(handle) {
+    try {
+      if (handle.lockFd !== void 0) {
+        let acquiredStat;
+        try {
+          acquiredStat = fs.fstatSync(handle.lockFd);
+        } catch {
+          return;
+        }
+        try {
+          const currentStat = fs.statSync(handle.lockPath);
+          if (currentStat.dev !== acquiredStat.dev || currentStat.ino !== acquiredStat.ino) {
+            return;
+          }
+        } catch (error) {
+          if (error.code === "ENOENT") {
+            return;
+          }
+          return;
+        }
+      } else if (handle.lockDev !== void 0 && handle.lockIno !== void 0) {
+        try {
+          const currentStat = fs.statSync(handle.lockPath);
+          if (currentStat.dev !== handle.lockDev || currentStat.ino !== handle.lockIno) {
+            return;
+          }
+        } catch (error) {
+          if (error.code === "ENOENT") {
+            return;
+          }
+          return;
+        }
+      }
+      if (handle.ownerToken) {
+        let currentOwnerToken = null;
+        try {
+          const current = JSON.parse(fs.readFileSync(handle.lockPath, "utf8"));
+          currentOwnerToken = typeof current.ownerToken === "string" && current.ownerToken.length > 0 ? current.ownerToken : null;
+        } catch (error) {
+          if (error.code === "ENOENT") {
+            return;
+          }
+          return;
+        }
+        if (currentOwnerToken !== handle.ownerToken) {
+          return;
+        }
+      }
+      try {
+        fs.unlinkSync(handle.lockPath);
+      } catch (error) {
+        if (error.code === "ENOENT") {
+          return;
+        }
+        throw new Error(
+          `Failed to release lock at ${handle.lockPath}: ${error.message}`
+        );
+      }
+    } finally {
+      this.closeLockHandle(handle);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Key-value operations
+  // -------------------------------------------------------------------------
+  async read(key) {
+    this.ensureDirs();
+    const filePath = this.kvFilePath(key);
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const envelope = JSON.parse(raw);
+      return { content: envelope.content, version: envelope.version };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return null;
+      }
+      throw new Error(`Failed to read key ${key} from ${filePath}: ${error.message}`);
+    }
+  }
+  /**
+   * Derive the internal lock name for a kv key.
+   *
+   * The reserved 'kv--' prefix keeps these locks apart from public lock names,
+   * so publish() under a caller-held public lock always orders caller lock ->
+   * kv lock (no deadlock).
+   */
+  kvLockName(key) {
+    return `kv--${key}`;
+  }
+  /**
+   * Atomically compare-and-publish a new content value for a key.
+   *
+   * Cross-process serialization: acquires an internal kv lock (named 'kv--<key>')
+   * around the read-CAS-rename sequence. This prevents two concurrent processes
+   * from both passing the CAS check and both publishing (last-writer-wins silent
+   * data loss). The kv lock uses the same retry/backoff as withEntityLock in
+   * issue-manager. Lock ordering: claim mutex -> kv lock (consistent everywhere,
+   * no deadlock).
+   *
+   * @throws {StaleVersionError} When the stored version does not match expectedVersion.
+   * @throws {Error} After bounded retries if the kv lock cannot be acquired.
+   */
+  async publish(key, content, opts) {
+    this.ensureDirs();
+    const delaysMs = this.publishLockDelaysMs;
+    let kvHandle = null;
+    for (let attempt = 0; attempt < delaysMs.length; attempt++) {
+      const delay = delaysMs[attempt] ?? 0;
+      if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+      kvHandle = await this._acquireLockUnchecked(this.kvLockName(key));
+      if (kvHandle !== null) break;
+    }
+    if (kvHandle === null) {
+      const lockPath = this.lockFilePath(this.kvLockName(key));
+      throw new Error(
+        `Could not acquire internal kv lock for key ${key} after retries. Lock path: ${lockPath}. Another process may be publishing to this key.`
+      );
+    }
+    try {
+      return this._publishUnderLock(key, content, opts);
+    } finally {
+      await this.releaseLock(kvHandle);
+    }
+  }
+  /** Execute the read-CAS-rename sequence. Must be called with the kv lock held. */
+  _publishUnderLock(key, content, opts) {
+    const filePath = this.kvFilePath(key);
+    let currentVersion = 0;
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const envelope2 = JSON.parse(raw);
+      currentVersion = envelope2.version;
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw new Error(`Failed to read key ${key} before publish: ${error.message}`);
+      }
+    }
+    checkVersion(key, currentVersion, opts.expectedVersion);
+    const newVersion = currentVersion + 1;
+    const envelope = { version: newVersion, content };
+    const envelopeJson = JSON.stringify(envelope);
+    const tmpPath = path.join(path.dirname(filePath), `.tmp-${randomUUID()}`);
+    try {
+      fs.writeFileSync(tmpPath, envelopeJson, "utf8");
+    } catch (writeError) {
+      throw new Error(`Failed to write temp file for key ${key}: ${writeError.message}`);
+    }
+    try {
+      fs.renameSync(tmpPath, filePath);
+    } catch (renameError) {
+      try {
+        fs.unlinkSync(tmpPath);
+      } catch {
+      }
+      throw new Error(`Failed to atomically publish key ${key}: ${renameError.message}`);
+    }
+    return { version: newVersion };
+  }
+};
+function kvLockNameForKey(key) {
+  return `kv--${key}`;
+}
+function isPidAliveDefault(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (killError) {
+    if (killError.code === "ESRCH") {
+      return false;
+    }
+    return true;
+  }
+}
+function classifyCoordinationLockFile(lockPath, opts = {}) {
+  const name = path.basename(lockPath, ".lock");
+  const thisMachineId = opts.machineId ?? readMachineIdIfPresent(opts.machineIdPath);
+  const isPidAlive = opts.isPidAlive ?? isPidAliveDefault;
+  let ageMs = 0;
+  try {
+    const stat = fs.statSync(lockPath);
+    ageMs = Date.now() - stat.mtimeMs;
+  } catch {
+    return {
+      name,
+      lockPath,
+      ageMs: 0,
+      pid: null,
+      machineIdShort: null,
+      classification: "unreadable"
+    };
+  }
+  let lockData;
+  try {
+    const raw = fs.readFileSync(lockPath, "utf8");
+    lockData = JSON.parse(raw);
+  } catch {
+    return {
+      name,
+      lockPath,
+      ageMs,
+      pid: null,
+      machineIdShort: null,
+      classification: "unreadable"
+    };
+  }
+  const pid = lockData.pid;
+  if (typeof pid !== "number") {
+    return {
+      name,
+      lockPath,
+      ageMs,
+      pid: null,
+      machineIdShort: null,
+      classification: "unreadable"
+    };
+  }
+  const payloadMachineId = typeof lockData.machineId === "string" ? lockData.machineId : null;
+  const machineIdShort = payloadMachineId ? shortMachineId(payloadMachineId) : null;
+  if (payloadMachineId !== null) {
+    if (thisMachineId === null) {
+      return {
+        name,
+        lockPath,
+        ageMs,
+        pid,
+        machineIdShort,
+        classification: "unreadable"
+      };
+    }
+    if (payloadMachineId !== thisMachineId) {
+      return {
+        name,
+        lockPath,
+        ageMs,
+        pid,
+        machineIdShort,
+        classification: "foreign-machine"
+      };
+    }
+  }
+  if (payloadMachineId === null) {
+    if (isPidAlive(pid)) {
+      return {
+        name,
+        lockPath,
+        ageMs,
+        pid,
+        machineIdShort: null,
+        classification: "live"
+      };
+    }
+    return {
+      name,
+      lockPath,
+      ageMs,
+      pid,
+      machineIdShort: null,
+      classification: "unreadable"
+    };
+  }
+  if (isPidAlive(pid)) {
+    return {
+      name,
+      lockPath,
+      ageMs,
+      pid,
+      machineIdShort,
+      classification: "live"
+    };
+  }
+  return {
+    name,
+    lockPath,
+    ageMs,
+    pid,
+    machineIdShort,
+    classification: "stale-same-machine"
+  };
+}
+function diagnoseCoordinationLocks(locksDir, opts = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(locksDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const diagnostics = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".lock")) {
+      continue;
+    }
+    const lockPath = path.join(locksDir, entry);
+    try {
+      const stat = fs.statSync(lockPath);
+      if (!stat.isFile()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    diagnostics.push(classifyCoordinationLockFile(lockPath, opts));
+  }
+  diagnostics.sort((a, b) => a.name.localeCompare(b.name));
+  return diagnostics;
+}
+
+export {
+  checkVersion,
+  DEFAULT_STALE_LOCK_MS,
+  LocalFileBackend,
+  kvLockNameForKey,
+  classifyCoordinationLockFile,
+  diagnoseCoordinationLocks
+};
+//# sourceMappingURL=chunk-4US4SYJ4.js.map