sentinelayer-cli 0.6.2 → 0.8.1

package/src/coord/index.js

@@ -0,0 +1,35 @@
+// Barrel export for the .sentinel cross-persona handshake (#A9, spec §5.6).
+// Callers should import from "src/coord" rather than reaching into individual
+// modules so we can reshape internals without rippling through the codebase.
+
+export {
+  DEFAULT_TTL_S,
+  LOCK_SCHEMA_VERSION,
+  MAX_TTL_S,
+  MIN_TTL_S,
+  PERSONA_PRIORITY,
+  checkLock,
+  detectDeadlock,
+  hashLockKey,
+  listActiveLocks,
+  listWaiters,
+  normalizeLockPath,
+  outranks,
+  priorityIndex,
+  releaseLock,
+  requestLock,
+} from "./handshake.js";
+
+export { appendEvent, readEvents, KNOWN_EVENT_TYPES } from "./events-log.js";
+
+export { findCycles, tarjanSCC } from "./tarjan.js";
+
+export { lowestPriorityAgent } from "./priority.js";
+
+export {
+  lockFileFor,
+  resolveEventsPath,
+  resolveLocksDir,
+  resolveSentinelDir,
+  resolveWaitsPath,
+} from "./paths.js";

package/src/coord/paths.js

@@ -0,0 +1,84 @@
+// Filesystem layout for the cross-persona LOCK/ACK/RELEASE handshake (#A9).
+//
+// All state lives under `.sentinel/` at the target repo root. This is
+// intentionally *not* `.sentinelayer/sessions/<id>/` (which scopes file locks
+// to a single Senti session) because the handshake is a cross-session
+// coordination primitive: when Omar Gate 2.0 verifies a PR, it reads the
+// same lock files the personas wrote without needing to know their session id.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import process from "node:process";
+
+const SENTINEL_ROOT = ".sentinel";
+const LOCKS_SUBDIR = "locks";
+const EVENTS_FILE = "events.jsonl";
+const WAITS_FILE = "waits.json";
+const MUTEX_LOCK = ".lock-mutex.lock";
+const EVENTS_LOCK = ".events.lock";
+const WAITS_LOCK = ".waits.lock";
+
+export function resolveSentinelDir({ targetPath = process.cwd() } = {}) {
+  return path.join(path.resolve(String(targetPath || ".")), SENTINEL_ROOT);
+}
+
+export function resolveLocksDir({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), LOCKS_SUBDIR);
+}
+
+export function resolveEventsPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), EVENTS_FILE);
+}
+
+export function resolveWaitsPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), WAITS_FILE);
+}
+
+export function resolveMutexLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), MUTEX_LOCK);
+}
+
+export function resolveEventsLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), EVENTS_LOCK);
+}
+
+export function resolveWaitsLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), WAITS_LOCK);
+}
+
+// Normalize the caller's intended file path into a stable, repo-relative,
+// posix-style string. Absolute paths are relativized against targetPath so
+// the same file produces the same hash across macOS/Linux/Windows workers.
+export function normalizeLockPath(filePath, { targetPath = process.cwd() } = {}) {
+  const raw = String(filePath || "").trim();
+  if (!raw) {
+    throw new Error("path is required.");
+  }
+  const resolvedTarget = path.resolve(String(targetPath || "."));
+  let normalized;
+  if (path.isAbsolute(raw)) {
+    normalized = path.relative(resolvedTarget, path.resolve(raw));
+  } else {
+    normalized = raw;
+  }
+  normalized = normalized.replace(/\\/g, "/").replace(/^\.\/+/, "");
+  if (!normalized || normalized === "." || normalized.startsWith("../")) {
+    throw new Error("path must be inside the target directory.");
+  }
+  return normalized;
+}
+
+export function hashLockKey(normalizedPath) {
+  const value = String(normalizedPath || "").trim();
+  if (!value) {
+    throw new Error("normalizedPath is required.");
+  }
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+export function lockFileFor(normalizedPath, { targetPath = process.cwd() } = {}) {
+  return path.join(
+    resolveLocksDir({ targetPath }),
+    `${hashLockKey(normalizedPath)}.lock.json`
+  );
+}

package/src/coord/priority.js

@@ -0,0 +1,62 @@
+// Persona priority ladder used by the LOCK/ACK/RELEASE handshake (#A9, spec §5.6).
+//
+// Lower index = higher priority. Architects hold the pen on shape decisions;
+// database / auth come next because they gate everything downstream; UI / docs
+// are at the tail because they are the easiest to redo if preempted.
+//
+// The ladder is closed: an unknown agent id sorts *below* every known persona
+// (priorityIndex returns PERSONA_PRIORITY.length) so stray callers cannot
+// accidentally preempt a real persona.
+
+export const PERSONA_PRIORITY = Object.freeze([
+  "architect",
+  "database",
+  "auth",
+  "backend",
+  "frontend",
+  "ui",
+  "payments",
+  "email",
+  "integrations",
+  "security",
+  "test",
+  "devops",
+  "docs",
+]);
+
+function normalizeAgent(agent) {
+  return String(agent || "").trim().toLowerCase();
+}
+
+export function priorityIndex(agent) {
+  const normalized = normalizeAgent(agent);
+  if (!normalized) {
+    return PERSONA_PRIORITY.length;
+  }
+  const idx = PERSONA_PRIORITY.indexOf(normalized);
+  return idx === -1 ? PERSONA_PRIORITY.length : idx;
+}
+
+// Returns true if `candidate` strictly outranks `incumbent` — i.e. candidate
+// may preempt incumbent's lock. Equal priorities never preempt (incumbent wins
+// ties to keep the system idempotent under retries).
+export function outranks(candidate, incumbent) {
+  return priorityIndex(candidate) < priorityIndex(incumbent);
+}
+
+// Given an iterable of agent ids, return the one with the lowest priority —
+// the deadlock-break "victim". Ties resolve by sort order so the choice is
+// deterministic across hosts.
+export function lowestPriorityAgent(agents) {
+  const list = Array.from(agents || []).map(normalizeAgent).filter(Boolean);
+  if (list.length === 0) {
+    return null;
+  }
+  return list.slice().sort((left, right) => {
+    const diff = priorityIndex(right) - priorityIndex(left);
+    if (diff !== 0) {
+      return diff;
+    }
+    return left < right ? -1 : left > right ? 1 : 0;
+  })[0];
+}

package/src/coord/tarjan.js

@@ -0,0 +1,157 @@
+// Iterative Tarjan strongly-connected components (#A9, spec §5.6).
+//
+// We use an explicit work stack instead of recursion because the wait graph
+// can, in theory, chain across all 13 personas and Node's default stack size
+// is fine but iterative keeps us honest for future growth (scaffold-before-
+// code may run many transient locks in flight).
+//
+// Input:  adjacency as { node: [neighbors...] } — missing keys are treated
+//         as leaves. Nodes referenced only as neighbors are picked up.
+// Output: list of SCCs, each an array of node ids. Size-1 SCCs without a
+//         self-loop are still returned so callers can filter.
+
+export function tarjanSCC(graph) {
+  const adjacency = normalizeGraph(graph);
+  const nodes = Array.from(adjacency.keys());
+
+  const index = new Map();
+  const lowlink = new Map();
+  const onStack = new Set();
+  const sccStack = [];
+  const result = [];
+
+  let counter = 0;
+
+  for (const root of nodes) {
+    if (index.has(root)) {
+      continue;
+    }
+
+    // Iterative DFS. Each frame tracks the node plus the index of the next
+    // neighbor to visit so we can resume after recursive descent.
+    const workStack = [{ node: root, neighborIdx: 0 }];
+    index.set(root, counter);
+    lowlink.set(root, counter);
+    counter += 1;
+    sccStack.push(root);
+    onStack.add(root);
+
+    while (workStack.length > 0) {
+      const frame = workStack[workStack.length - 1];
+      const neighbors = adjacency.get(frame.node) || [];
+
+      if (frame.neighborIdx < neighbors.length) {
+        const next = neighbors[frame.neighborIdx];
+        frame.neighborIdx += 1;
+
+        if (!index.has(next)) {
+          index.set(next, counter);
+          lowlink.set(next, counter);
+          counter += 1;
+          sccStack.push(next);
+          onStack.add(next);
+          workStack.push({ node: next, neighborIdx: 0 });
+        } else if (onStack.has(next)) {
+          lowlink.set(
+            frame.node,
+            Math.min(lowlink.get(frame.node), index.get(next))
+          );
+        }
+        continue;
+      }
+
+      // Exhausted neighbors — close the frame. If we're an SCC root, pop the
+      // component off the stack.
+      if (lowlink.get(frame.node) === index.get(frame.node)) {
+        const component = [];
+        while (sccStack.length > 0) {
+          const popped = sccStack.pop();
+          onStack.delete(popped);
+          component.push(popped);
+          if (popped === frame.node) {
+            break;
+          }
+        }
+        result.push(component);
+      }
+
+      workStack.pop();
+      if (workStack.length > 0) {
+        const parent = workStack[workStack.length - 1];
+        lowlink.set(
+          parent.node,
+          Math.min(lowlink.get(parent.node), lowlink.get(frame.node))
+        );
+      }
+    }
+  }
+
+  return result;
+}
+
+// Convenience: return only SCCs that represent actual cycles (size > 1, or
+// self-loops of size 1). Useful for the deadlock-detection branch which
+// should ignore every isolated node.
+export function findCycles(graph) {
+  const sccs = tarjanSCC(graph);
+  const source =
+    graph && typeof graph === "object" && !Array.isArray(graph) ? graph : {};
+  const cycles = [];
+  for (const component of sccs) {
+    if (component.length > 1) {
+      cycles.push(component);
+      continue;
+    }
+    const [only] = component;
+    const rawNeighbors = Array.isArray(source[only]) ? source[only] : [];
+    const normalizedNeighbors = rawNeighbors.map((value) =>
+      String(value || "").trim()
+    );
+    if (normalizedNeighbors.includes(only)) {
+      cycles.push(component);
+    }
+  }
+  return cycles;
+}
+
+function normalizeGraph(graph) {
+  const adjacency = new Map();
+  const source =
+    graph && typeof graph === "object" && !Array.isArray(graph) ? graph : {};
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const node = String(rawKey || "").trim();
+    if (!node) {
+      continue;
+    }
+    const list = Array.isArray(rawValue) ? rawValue : [];
+    const normalized = [];
+    for (const candidate of list) {
+      const neighbor = String(candidate || "").trim();
+      if (!neighbor) {
+        continue;
+      }
+      if (!normalized.includes(neighbor)) {
+        normalized.push(neighbor);
+      }
+    }
+    const existing = adjacency.get(node) || [];
+    for (const neighbor of normalized) {
+      if (!existing.includes(neighbor)) {
+        existing.push(neighbor);
+      }
+    }
+    adjacency.set(node, existing);
+  }
+
+  // Any node referenced as a neighbor but not as a key is a leaf — add it so
+  // the DFS visits it.
+  for (const neighbors of [...adjacency.values()]) {
+    for (const neighbor of neighbors) {
+      if (!adjacency.has(neighbor)) {
+        adjacency.set(neighbor, []);
+      }
+    }
+  }
+  return adjacency;
+}