@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/lib/specs/usecase-registry.js

@@ -1,237 +0,0 @@
-/**
- * usecase-registry.js — atomic, cross-worktree UC-{nn} number allocation.
- *
- * Two parallel worktrees planning at the same time each read the acervo
- * (`.morph/specs/usecases/`) plus their OWN feature's `2-plan/usecases/`, take
- * the max `UC-{nn}` and add one — but a worktree only ever sees its OWN tree.
- * Sibling features' use cases live in SIBLING worktrees (feature.json and every
- * UC file travel on the branch, not through any shared filesystem). Two
- * worktrees both computing max+1 from the same stale max both mint `UC-07` —
- * and at promotion time `usecase-promoter.js` overwrites by ID: the SECOND
- * feature to close silently destroys the FIRST one's use case. A user lost
- * work this way in production.
- *
- * This module closes the gap the same way `env-allocator.js` (port blocks) and
- * `claim-registry.js` (feature ownership) already do: a registry file under the
- * git COMMON dir, the one location every linked worktree of a repo shares —
- * `<git-common-dir>/morph-spec/uc-registry.json`. Writes are tmp+rename; a
- * corrupt registry reads as empty (fail-open — the cost is a re-seed from disk,
- * never a crash).
- *
- * Unlike the other two registries, correctness here cannot be advisory: the
- * whole point is that two concurrent callers must never receive the same
- * number. `env-allocator`/`claim-registry` key by FEATURE, so two different
- * features racing never contend for the same key; two worktrees reserving UC
- * numbers race for the SAME counter. So allocation runs inside a real mutual
- * exclusion lock (`uc-registry.lock`, `open(..., 'wx')` — atomic create-if-absent
- * on every platform Node targets, including Windows) instead of the bare
- * read-modify-write the other two registries use.
- *
- * No git (no common dir resolvable): falls back to a project-local registry
- * under `.morph/logs/` (already gitignored) — this still prevents a single
- * session from reserving the same number twice across repeated calls, but
- * carries none of the cross-worktree guarantee. Callers must surface that
- * degradation to the user.
- */
-
-import {
-  closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync,
-  renameSync, statSync, unlinkSync, writeFileSync,
-} from 'fs';
-import { join } from 'path';
-
-// From acervo-format.js, not usecase-promoter.js: the promoter depends on THIS
-// module (to look up who reserved a number), and a two-way import is circular.
-import { useCaseId } from './acervo-format.js';
-
-/** `UC-7` (or any width) -> `UC-07` — the archive's zero-padded convention. */
-function formatUcId(n) {
-  return `UC-${String(n).padStart(2, '0')}`;
-}
-
-/** Directory holding both the registry file and its lock. */
-export function registryDir({ gitCommonDir, cwd }) {
-  return gitCommonDir ? join(gitCommonDir, 'morph-spec') : join(cwd, '.morph', 'logs');
-}
-
-/** Registry file path — shared (git common dir) or local-fallback (no git). */
-export function ucRegistryPath({ gitCommonDir, cwd }) {
-  return join(registryDir({ gitCommonDir, cwd }), 'uc-registry.json');
-}
-
-function readRegistry(path) {
-  try {
-    const raw = readFileSync(path, 'utf8').replace(/^/, '');
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed.reservations === 'object' && parsed.reservations !== null) {
-      return {
-        version: 1,
-        counter: Number.isInteger(parsed.counter) ? parsed.counter : 0,
-        reservations: parsed.reservations,
-      };
-    }
-  } catch { /* fail-open: absent or corrupt registry restarts empty */ }
-  return { version: 1, counter: 0, reservations: {} };
-}
-
-function writeRegistry(path, registry) {
-  mkdirSync(join(path, '..'), { recursive: true });
-  const tmp = `${path}.tmp.${process.pid}`;
-  writeFileSync(tmp, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
-  renameSync(tmp, path);
-}
-
-/** Synchronous sleep — Node (unlike browsers) allows `Atomics.wait` on the main thread. */
-function sleepSync(ms) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-
-/**
- * Run `fn` while holding an exclusive filesystem lock at `lockPath`.
- *
- * `openSync(path, 'wx')` is `O_CREAT | O_EXCL` — atomic create-or-fail, the
- * only primitive this needs and one that behaves identically on POSIX and
- * Windows. A lock file whose mtime is older than `staleMs` is assumed to be
- * left behind by a crashed process and is force-recovered — an orphaned lock
- * must never strand every future reservation.
- *
- * @param {string} lockPath
- * @param {() => T} fn
- * @returns {T}
- * @template T
- */
-function withLock(lockPath, fn, { timeoutMs = 5000, pollMs = 20, staleMs = 15000 } = {}) {
-  mkdirSync(join(lockPath, '..'), { recursive: true });
-  const deadline = Date.now() + timeoutMs;
-  for (;;) {
-    let fd;
-    try {
-      fd = openSync(lockPath, 'wx');
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      try {
-        const st = statSync(lockPath);
-        if (Date.now() - st.mtimeMs > staleMs) {
-          try { unlinkSync(lockPath); } catch { /* raced someone else's cleanup */ }
-          continue; // retry immediately — the stale lock is (probably) gone now
-        }
-      } catch { continue; } // lock vanished between openSync and statSync — retry
-      if (Date.now() >= deadline) {
-        throw new Error(`usecase-registry: could not acquire lock at ${lockPath} within ${timeoutMs}ms`);
-      }
-      sleepSync(pollMs);
-      continue;
-    }
-    try {
-      closeSync(fd);
-      return fn();
-    } finally {
-      try { unlinkSync(lockPath); } catch { /* best-effort */ }
-    }
-  }
-}
-
-/** Highest `UC-{nn}` number found among files matching the pattern in `dir`. 0 if none/unreadable. */
-function maxUcNumberInDir(dir) {
-  let max = 0;
-  try {
-    if (!existsSync(dir)) return 0;
-    for (const name of readdirSync(dir)) {
-      // Any `UC-{nn}-` prefix counts, canonical or not: a number already on disk is never handed out again.
-      const id = useCaseId(name);
-      if (!id) continue;
-      const n = parseInt(id.slice('UC-'.length), 10);
-      if (Number.isFinite(n) && n > max) max = n;
-    }
-  } catch { /* unreadable dir — treat as empty, never fatal */ }
-  return max;
-}
-
-/** Highest UC number across every feature's `2-plan/usecases/`, under both `.morph/features/` and `.morph/archive/`, in THIS tree. */
-function maxUcNumberLocalTree(cwd) {
-  let max = 0;
-  for (const bucket of ['features', 'archive']) {
-    const bucketDir = join(cwd, '.morph', bucket);
-    try {
-      if (!existsSync(bucketDir)) continue;
-      for (const entry of readdirSync(bucketDir, { withFileTypes: true })) {
-        if (!entry.isDirectory()) continue;
-        max = Math.max(max, maxUcNumberInDir(join(bucketDir, entry.name, '2-plan', 'usecases')));
-      }
-    } catch { /* unreadable bucket — treat as empty */ }
-  }
-  return max;
-}
-
-/**
- * The highest UC number this project tree can see right now: the permanent
- * acervo, plus every feature (active OR archived-but-not-yet-promoted, see
- * `usecase-promoter.js`'s refusal path) in THIS tree. Exported for tests and
- * for callers that want to preview the seed without reserving anything.
- *
- * @param {string} cwd
- * @returns {number}
- */
-export function scanLocalMax(cwd) {
-  const acervoMax = maxUcNumberInDir(join(cwd, '.morph', 'specs', 'usecases'));
-  return Math.max(acervoMax, maxUcNumberLocalTree(cwd));
-}
-
-/**
- * Atomically reserve the next `count` UC numbers, shared across every worktree
- * of this repo when a git common dir is resolvable.
- *
- * The seed is recomputed on EVERY call as `max(registry.counter, scanLocalMax(cwd))`
- * — monotonic by construction (a max can only grow), so this doubles as both
- * "seed the counter on the first-ever reservation" and "never regress even if
- * the registry were somehow behind disk" without needing a separate seeded flag.
- *
- * @param {string} cwd
- * @param {{ feature?: string|null, count?: number, gitCommonDir?: string|null }} opts
- * @returns {{ numbers: string[], base: number, count: number, shared: boolean, registryPath: string }}
- */
-export function reserveUseCases(cwd, { feature = null, count = 1, gitCommonDir = null } = {}) {
-  const n = Number.isInteger(count) && count > 0 ? count : 1;
-  const dir = registryDir({ gitCommonDir, cwd });
-  const path = ucRegistryPath({ gitCommonDir, cwd });
-  mkdirSync(dir, { recursive: true });
-
-  return withLock(join(dir, 'uc-registry.lock'), () => {
-    const registry = readRegistry(path);
-    const base = Math.max(registry.counter || 0, scanLocalMax(cwd));
-
-    // Test-only: widen the critical section so a concurrency test can prove
-    // two REAL processes racing for this lock actually serialize, instead of
-    // just happening not to overlap. Mirrors `finish.js`'s MORPH_GH_BIN test
-    // injection. Unset in every real invocation.
-    const testDelay = Number.parseInt(process.env.MORPH_UC_RESERVE_TEST_DELAY_MS, 10);
-    if (Number.isFinite(testDelay) && testDelay > 0) sleepSync(testDelay);
-
-    const numbers = [];
-    const now = new Date().toISOString();
-    for (let i = 1; i <= n; i += 1) {
-      const id = formatUcId(base + i);
-      numbers.push(id);
-      registry.reservations[id] = { feature: feature || null, reservedAt: now };
-    }
-    registry.counter = base + n;
-    writeRegistry(path, registry);
-
-    return { numbers, base, count: n, shared: !!gitCommonDir, registryPath: path };
-  });
-}
-
-/**
- * Which feature (if any) holds the reservation for a given `UC-{nn}` id.
- * Read-only — no lock, a slightly stale read is harmless for this use (the
- * promoter's collision backstop, never the allocation itself).
- *
- * @param {string} id - e.g. "UC-07"
- * @param {{ cwd: string, gitCommonDir?: string|null }} opts
- * @returns {string|null}
- */
-export function reservationOwner(id, { cwd, gitCommonDir = null }) {
-  const path = ucRegistryPath({ gitCommonDir, cwd });
-  const registry = readRegistry(path);
-  return registry.reservations?.[id]?.feature ?? null;
-}

package/src/lib/tasks/dispatch-planner.js

@@ -1,319 +0,0 @@
-/**
- * dispatch-planner.js — effort-weighted sequential vs parallel decision for a
- * feature's tasks.json DAG.
- *
- * Encodes the dispatch rules from morph-apply §2 ("Análise de DAG") so the
- * decision is deterministic and CLI-driven (`morph-spec dag <feature>`)
- * instead of re-derived by the LLM each session:
- *
- *   1. <= 3 tasks total → sequential (dispatch overhead beats the work).
- *   2. >= 2 independent group flows with enough weight → one agent per flow.
- *   3. >= 3 independent roots with effort M or heavier → parallel root batch.
- *   4. otherwise → sequential with auto-advance.
- *
- * Effort weighting: S=1, M=2, L=4, XL=8. S-only roots and light flows never
- * earn their own agent — they are returned as `inline` (the orchestrator runs
- * them in the sequential lane, or folds them into a single grouped agent), so
- * dispatch overhead never exceeds the work being dispatched.
- *
- * Pure module — operates on a parsed tasks.json document, no I/O.
- */
-
-export const EFFORT_WEIGHT = { S: 1, M: 2, L: 4, XL: 8 };
-
-/** A root must weigh at least this (effort M) to earn its own agent. */
-export const ROOT_DISPATCH_MIN_WEIGHT = 2;
-
-/** A flow must weigh at least this (an L, or 2×M…) to earn its own agent. */
-export const FLOW_DISPATCH_MIN_WEIGHT = 4;
-
-/** Mirror of the morph-apply cap on simultaneous agents. */
-export const MAX_PARALLEL_AGENTS = 4;
-
-function weightOf(task) {
-  return EFFORT_WEIGHT[task.effort] ?? EFFORT_WEIGHT.M;
-}
-
-function groupOf(task) {
-  // Same fallback as groupTasks() in tasks-json-parser.js
-  return task.group || 'backend';
-}
-
-/**
- * Normalize a planned output path for collision comparison: forward slashes,
- * collapsed repeated slashes, no leading `./` or `/`, no trailing slash,
- * lowercased (Windows/macOS filesystems are case-insensitive). Returns '' for
- * empty/nullish input. `..`/`.` segments are left as-is on purpose (resolving
- * them would risk false-positives; two genuinely different relative spellings
- * stay distinct).
- */
-export function normalizeOutputPath(p) {
-  return String(p ?? '')
-    .trim()
-    .replace(/\\/g, '/')
-    .replace(/\/{2,}/g, '/')
-    .replace(/^\.\//, '')
-    .replace(/^\/+/, '')
-    .replace(/\/+$/, '')
-    .toLowerCase();
-}
-
-/**
- * Two normalized paths "overlap" if they are equal, or one is a directory
- * ancestor of the other — boundary-aware so `src/a` contains `src/a/b` but
- * NOT `src/ab`. Empty paths never overlap.
- */
-export function pathsOverlap(a, b) {
-  if (!a || !b) return false;
-  if (a === b) return true;
-  const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
-  return longer.startsWith(`${shorter}/`);
-}
-
-/**
- * Decide whether a parallel batch's units would write to overlapping paths,
- * and therefore whether each agent should run in its own git worktree
- * (`isolation: "worktree"`, per morph-apply §3b-w) instead of the shared
- * working tree.
- *
- * A *unit* is the set of task ids a single agent owns (one flow, or one batch
- * root). Tasks WITHIN a unit run serially under that agent, so their outputs
- * never race — only CROSS-unit overlaps matter. The recommendation is global
- * per batch: any collision → isolate the whole batch. Units whose tasks
- * declare no `outputs` are an *unknown footprint* — they do NOT force
- * isolation (fail-open) but are flagged so the caller knows the dag can't
- * prove the batch is collision-free.
- *
- * @param {Array<{ key: string, taskIds: string[] }>} units
- * @param {Map<string, object>} tasksById
- * @returns {{ recommended: 'none'|'worktree', collisions: Array<{path: string, units: string[], tasks: string[]}>, unknownFootprint: string[], reason: string }}
- */
-export function buildIsolation(units, tasksById) {
-  const unknownFootprint = [];
-  const unitOutputs = units.map(unit => {
-    const outs = [];
-    for (const id of unit.taskIds) {
-      const task = tasksById.get(id);
-      const declared = Array.isArray(task?.outputs) ? task.outputs : [];
-      let validForTask = 0;
-      for (const raw of declared) {
-        const path = normalizeOutputPath(raw);
-        if (path) { outs.push({ path, task: id }); validForTask += 1; }
-      }
-      // No usable output paths (none declared, or all normalize to '') → the
-      // dag can't prove this task's footprint. Flag it (fail-open).
-      if (validForTask === 0) unknownFootprint.push(id);
-    }
-    return { key: unit.key, outs };
-  });
-
-  const collisions = [];
-  for (let i = 0; i < unitOutputs.length; i++) {
-    for (let j = i + 1; j < unitOutputs.length; j++) {
-      for (const a of unitOutputs[i].outs) {
-        for (const b of unitOutputs[j].outs) {
-          if (pathsOverlap(a.path, b.path)) {
-            collisions.push({
-              path: a.path === b.path ? a.path : `${a.path} ∩ ${b.path}`,
-              units: [unitOutputs[i].key, unitOutputs[j].key],
-              tasks: [a.task, b.task],
-            });
-          }
-        }
-      }
-    }
-  }
-
-  const recommended = collisions.length > 0 ? 'worktree' : 'none';
-  let reason;
-  if (collisions.length > 0) {
-    reason =
-      `${collisions.length} colisão(ões) de outputs entre unidades paralelas — ` +
-      `isole cada agente num worktree (morph-apply §3b-w)`;
-  } else if (unknownFootprint.length > 0) {
-    reason =
-      `sem colisão detectada, mas ${unknownFootprint.length} task(s) paralela(s) sem ` +
-      `outputs declarados (footprint desconhecido) — o dag não garante ausência de colisão`;
-  } else {
-    reason = 'nenhuma colisão de outputs entre unidades paralelas — batch na working tree compartilhada';
-  }
-
-  return { recommended, collisions, unknownFootprint, reason };
-}
-
-/**
- * Ids of tasks whose dependency chain crosses group boundaries — integration
- * tasks and everything downstream of them. These never belong to a flow: they
- * run in the sequential lane after the parallel batch converges.
- */
-function crossGroupTaskIds(tasks) {
-  const byId = new Map(tasks.map(t => [t.id, t]));
-  const cross = new Set();
-
-  for (const task of tasks) {
-    for (const dep of task.dependencies) {
-      const depTask = byId.get(dep);
-      if (depTask && groupOf(depTask) !== groupOf(task)) {
-        cross.add(task.id);
-        break;
-      }
-    }
-  }
-
-  // Propagate downstream: a task depending (transitively) on a cross-group
-  // task cannot run inside a single-group flow either.
-  let changed = true;
-  while (changed) {
-    changed = false;
-    for (const task of tasks) {
-      if (cross.has(task.id)) continue;
-      if (task.dependencies.some(dep => cross.has(dep))) {
-        cross.add(task.id);
-        changed = true;
-      }
-    }
-  }
-
-  return cross;
-}
-
-function buildStats(tasks, pending) {
-  const groups = {};
-  const weights = {};
-  for (const task of pending) {
-    const g = groupOf(task);
-    groups[g] = (groups[g] || 0) + 1;
-    weights[g] = (weights[g] || 0) + weightOf(task);
-  }
-  return { total: tasks.length, pending: pending.length, groups, weights };
-}
-
-/**
- * Decide how to execute the remaining tasks of a parsed tasks.json document.
- *
- * @param {object} data - parsed tasks.json ({ version, feature, tasks[] })
- * @returns {{
- *   mode: 'sequential' | 'parallel-flows' | 'parallel-roots',
- *   reason: string,
- *   stats: { total: number, pending: number, groups: object, weights: object },
- *   flows: Array<{ group: string, taskIds: string[], weight: number }>,
- *   batch: string[],
- *   inline: string[],
- *   sequentialRemainder: string[],
- *   isolation: { recommended: 'none'|'worktree', collisions: Array<{path: string, units: string[], tasks: string[]}>, unknownFootprint: string[], reason: string }
- * }}
- */
-export function planDispatch(data) {
-  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
-  const pending = tasks.filter(t => t.status === 'pending');
-  const stats = buildStats(tasks, pending);
-  const empty = { flows: [], batch: [], inline: [] };
-  const tasksById = new Map(tasks.map(t => [t.id, t]));
-  // A batch with no parallel units can't have concurrent-write collisions.
-  const noIsolation = buildIsolation([], tasksById);
-
-  if (pending.length === 0) {
-    return {
-      mode: 'sequential',
-      reason: 'nenhuma task pendente — nada a despachar',
-      stats, ...empty, sequentialRemainder: [], isolation: noIsolation,
-    };
-  }
-
-  // Rule 1 — tiny plans never pay for dispatch.
-  if (tasks.length <= 3) {
-    return {
-      mode: 'sequential',
-      reason: `${tasks.length} task(s) no total (<= 3) — overhead de Agent dispatch não compensa`,
-      stats, ...empty, sequentialRemainder: pending.map(t => t.id), isolation: noIsolation,
-    };
-  }
-
-  // Rule 2 — independent domain flows (backend ‖ frontend …).
-  const cross = crossGroupTaskIds(tasks);
-  const flowsMap = new Map();
-  for (const task of pending) {
-    if (cross.has(task.id)) continue;
-    const g = groupOf(task);
-    if (!flowsMap.has(g)) flowsMap.set(g, { group: g, taskIds: [], weight: 0 });
-    const flow = flowsMap.get(g);
-    flow.taskIds.push(task.id);
-    flow.weight += weightOf(task);
-  }
-  const allFlows = [...flowsMap.values()];
-  const worthyFlows = allFlows
-    .filter(f => f.weight >= FLOW_DISPATCH_MIN_WEIGHT)
-    .sort((a, b) => b.weight - a.weight);
-  const lightFlows = allFlows.filter(f => f.weight < FLOW_DISPATCH_MIN_WEIGHT);
-
-  if (worthyFlows.length >= 2) {
-    const flows = worthyFlows.slice(0, MAX_PARALLEL_AGENTS);
-    const overflow = worthyFlows.slice(MAX_PARALLEL_AGENTS);
-    const inline = [
-      ...lightFlows.flatMap(f => f.taskIds),
-      ...overflow.flatMap(f => f.taskIds),
-    ];
-    const sequentialRemainder = pending
-      .filter(t => cross.has(t.id))
-      .map(t => t.id);
-
-    const flowDesc = flows.map(f => `${f.group}:${f.taskIds.length} (peso ${f.weight})`).join(' ‖ ');
-    return {
-      mode: 'parallel-flows',
-      reason:
-        `${flows.length} fluxos de domínio independentes com peso suficiente — ${flowDesc} → ` +
-        `1 agente por fluxo` +
-        (inline.length ? `; ${inline.length} task(s) leve(s) inline (sem dispatch próprio)` : '') +
-        (sequentialRemainder.length ? `; integração cross-group sequencial no fim (${sequentialRemainder.join(', ')})` : ''),
-      stats, flows, batch: [], inline, sequentialRemainder,
-      // Units = the dispatched flows (one agent each). Inline/overflow/cross-
-      // group remainder run in the sequential lane, never concurrently.
-      isolation: buildIsolation(
-        flows.map(f => ({ key: f.group, taskIds: f.taskIds })),
-        tasksById,
-      ),
-    };
-  }
-
-  // Rule 3 — root fan-out, weighted by effort (S roots never earn an agent).
-  const roots = pending.filter(t => t.dependencies.length === 0);
-  const weightedRoots = roots
-    .filter(t => weightOf(t) >= ROOT_DISPATCH_MIN_WEIGHT)
-    .sort((a, b) => weightOf(b) - weightOf(a));
-  const sRoots = roots.filter(t => weightOf(t) < ROOT_DISPATCH_MIN_WEIGHT);
-
-  if (weightedRoots.length >= 3) {
-    const batch = weightedRoots.slice(0, MAX_PARALLEL_AGENTS).map(t => t.id);
-    const inline = sRoots.map(t => t.id);
-    const sequentialRemainder = pending
-      .filter(t => !batch.includes(t.id) && !inline.includes(t.id))
-      .map(t => t.id);
-
-    return {
-      mode: 'parallel-roots',
-      reason:
-        `${weightedRoots.length} raízes independentes com effort M+ → batch paralelo (${batch.join(', ')})` +
-        (inline.length ? `; raízes S inline — não ganham dispatch próprio (${inline.join(', ')})` : '') +
-        `; restante sequencial`,
-      stats, flows: [], batch, inline, sequentialRemainder,
-      // Units = each batch root (one agent each); inline S-roots and the
-      // sequential remainder don't run concurrently with the batch.
-      isolation: buildIsolation(
-        batch.map(id => ({ key: id, taskIds: [id] })),
-        tasksById,
-      ),
-    };
-  }
-
-  // Rule 4 — sequential.
-  const reason = roots.length >= 3
-    ? `${roots.length} raízes independentes, mas apenas ${weightedRoots.length} com effort M+ ` +
-      `(raízes S não ganham dispatch próprio — overhead > trabalho) → sequencial com auto-advance`
-    : 'sem fluxos ou raízes independentes suficientes → sequencial com auto-advance';
-
-  return {
-    mode: 'sequential',
-    reason,
-    stats, ...empty, sequentialRemainder: pending.map(t => t.id), isolation: noIsolation,
-  };
-}