pincer-workflow 0.4.1 → 0.6.0

package/template/scripts/pincer-runtime/transaction.cjs

@@ -0,0 +1,200 @@
+'use strict';
+// PINCER runtime — transactions (docs/runtime-contracts.md, "Transactions and
+// recovery"). Every write of a change record, agreement snapshot, selection,
+// evaluation locator or migration goes through `run`: the worktree lock is held
+// for the whole validate-and-write operation, the caller's function computes the
+// outcome in memory, the new files are staged under the journal, a manifest is
+// written last as the commit point, and the staged files are renamed onto their
+// targets. A process killed before the manifest leaves the old state; killed
+// after it, the next transaction or `recover` completes the renames. A
+// projection is therefore never observable without its event.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const state = require('./state.cjs');
+const { nowIso, readJson } = require('./fsutil.cjs');
+
+const MANIFEST_SCHEMA = 1;
+const TXN_PREFIX = 'txn-';
+const MAX_TEXT = 2000;
+const SAFE_RELATIVE = /^(?!\/)(?!.*(^|\/)\.\.(\/|$))[^\0]+$/;
+
+class Refusal extends Error {
+  constructor(code, message, extra = {}) { super(message); this.code = code; this.refusal = true; Object.assign(this, extra); }
+}
+const refuse = (code, message, extra) => { throw new Refusal(code, message, extra); };
+
+const journalDir = root => state.paths(root).journal;
+const compact = () => nowIso().replace(/[-:]/g, '');
+const serialize = content => (typeof content === 'string' || Buffer.isBuffer(content) ? content : `${JSON.stringify(content, null, 2)}\n`);
+
+// --- Pending transactions (read-only) -------------------------------------------
+// A staging directory with a manifest is a committed transaction that was not
+// fully applied; one without a manifest is uncommitted staging. Never writes.
+function pending(root) {
+  const dir = journalDir(root);
+  if (!fs.existsSync(dir)) return { committed: [], uncommitted: [] };
+  const committed = [], uncommitted = [];
+  for (const name of fs.readdirSync(dir).sort()) {
+    if (!name.startsWith(TXN_PREFIX)) continue;
+    const staging = path.join(dir, name);
+    let stat = null;
+    try { stat = fs.statSync(staging); } catch { continue; }
+    if (!stat.isDirectory()) continue;
+    const read = readJson(path.join(staging, 'manifest.json'));
+    if (read.error === 'missing') { uncommitted.push({ id: name, dir: `${state.RUNTIME_DIR}/journal/${name}` }); continue; }
+    if (read.error || !validManifest(read.data)) { committed.push({ id: name, dir: `${state.RUNTIME_DIR}/journal/${name}`, manifest: null, problem: read.error || 'malformed manifest' }); continue; }
+    committed.push({ id: name, dir: `${state.RUNTIME_DIR}/journal/${name}`, manifest: read.data, command: read.data.command, started: read.data.started });
+  }
+  return { committed, uncommitted };
+}
+function validManifest(m) {
+  return m && typeof m === 'object' && !Array.isArray(m) && m.schema === MANIFEST_SCHEMA && typeof m.id === 'string' && typeof m.command === 'string'
+    && typeof m.started === 'string' && Array.isArray(m.writes)
+    && m.writes.every(w => w && typeof w === 'object' && typeof w.target === 'string' && SAFE_RELATIVE.test(w.target) && typeof w.staged === 'string' && /^[0-9]{2,}-[^/\0]+$/.test(w.staged));
+}
+
+// --- Recovery (caller holds the lock) -------------------------------------------
+// Complete every committed transaction (each rename is idempotent: a staged file
+// that is already gone was renamed before the crash) and discard uncommitted
+// staging. Returns what was done. A manifest that cannot be read is left in place
+// and reported: completing it would mean guessing its targets.
+function recoverPending(root) {
+  const report = { completed: [], discarded: [], unreadable: [] };
+  const found = pending(root);
+  for (const t of found.committed) {
+    if (!t.manifest) { report.unreadable.push({ id: t.id, problem: t.problem }); continue; }
+    applyManifest(root, path.join(root, t.dir), t.manifest);
+    report.completed.push({ id: t.id, command: t.manifest.command, targets: t.manifest.writes.map(w => w.target) });
+  }
+  for (const t of found.uncommitted) {
+    fs.rmSync(path.join(root, t.dir), { recursive: true, force: true });
+    report.discarded.push({ id: t.id });
+  }
+  return report;
+}
+function applyManifest(root, staging, manifest, hooks = null) {
+  manifest.writes.forEach((w, i) => {
+    const staged = path.join(staging, w.staged);
+    const target = path.join(root, w.target);
+    if (fs.existsSync(staged)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.renameSync(staged, target);
+    }
+    if (hooks) hooks(`rename:${i}`);
+  });
+  fs.rmSync(path.join(staging, 'manifest.json'), { force: true });
+  if (hooks) hooks('cleanup');
+  fs.rmSync(staging, { recursive: true, force: true });
+}
+
+// --- Running attempts of a change ---------------------------------------------
+// Attempts listed as running in the index whose context names the change. The
+// owner's liveness is reported so callers can name `recover` as the next step
+// for a dead owner; the transaction never terminates an attempt itself.
+function runningAttempts(root, changeId) {
+  if (!state.exists(root)) return [];
+  const read = state.readIndex(root);
+  if (read.error) refuse('INPUT_INVALID', read.error);
+  const out = [];
+  for (const id of read.index.running) {
+    const attempt = state.readAttempt(root, id).attempt;
+    if (!attempt || attempt.outcome !== 'running') continue;
+    if (!attempt.context || attempt.context.change !== changeId) continue;
+    const owner = attempt.owner || {};
+    out.push({ id, context: attempt.context, owner, alive: owner.host === os.hostname() ? state.isAlive(owner.pid) : null });
+  }
+  return out;
+}
+function requireIdle(root, changeId) {
+  const running = runningAttempts(root, changeId);
+  if (!running.length) return;
+  const a = running[0];
+  const hint = a.alive === false ? ' (its owner is no longer running: run recover first)' : a.alive === true ? ` (pid ${a.owner.pid} is still running)` : ` (owned by ${a.owner.host || 'another host'})`;
+  refuse('ATTEMPT_RUNNING', `attempt ${a.id} of change ${changeId} is running${hint}; the transition is refused and the attempt is not terminated`, { attempt: a.id });
+}
+
+// --- The transaction --------------------------------------------------------------
+// run(root, { command, waitMs, hooks }, fn): fn receives a context and returns
+// the result to hand back. Inside fn, ctx.read(rel) reads a repository-relative
+// JSON file (null when missing), ctx.text(rel) a text file, ctx.write(rel,
+// content) stages a write, ctx.expect(rel, key, value) refuses STATE_CHANGED when
+// the file's field differs from what the caller prepared against, ctx.idle(id)
+// refuses ATTEMPT_RUNNING for a change with a running attempt, ctx.refuse(code,
+// message) aborts with nothing written. `hooks(point)` is a test seam invoked at
+// 'validated', 'staged', 'manifest', 'rename:<i>' and 'cleanup'.
+function run(root, { command = 'transaction', waitMs, hooks = null, log } = {}, fn) {
+  return state.withLock(root, () => {
+    // Before anything else: finish what a killed writer committed and drop what
+    // it only staged, so every reader inside the lock sees consistent state.
+    recoverPending(root);
+    const writes = [];
+    const targets = new Set();
+    const ctx = {
+      root,
+      read(rel) {
+        assertRelative(rel);
+        const read = readJson(path.join(root, rel));
+        if (read.error === 'missing') return null;
+        if (read.error) refuse('MALFORMED', `${rel}: ${read.error}`);
+        return read.data;
+      },
+      text(rel) {
+        assertRelative(rel);
+        try { return fs.readFileSync(path.join(root, rel), 'utf8'); } catch (error) { return error.code === 'ENOENT' ? null : refuse('INPUT_INVALID', `${rel}: ${error.message}`); }
+      },
+      exists(rel) { assertRelative(rel); return fs.existsSync(path.join(root, rel)); },
+      expect(rel, key, value) {
+        const doc = ctx.read(rel);
+        const actual = doc ? doc[key] : null;
+        if (actual !== value) refuse('STATE_CHANGED', `${rel}: ${key} is ${JSON.stringify(actual)}, expected ${JSON.stringify(value)}; the record changed since the operation was prepared — inspect it and repeat the command against the current state`);
+        return doc;
+      },
+      idle(changeId) { requireIdle(root, changeId); },
+      running(changeId) { return runningAttempts(root, changeId); },
+      refuse,
+      write(rel, content) {
+        assertRelative(rel);
+        if (rel.startsWith(`${state.RUNTIME_DIR}/journal/`) || rel.startsWith(`${state.RUNTIME_DIR}/lock`)) refuse('INPUT_INVALID', `${rel}: the journal and the lock are not transaction targets`);
+        if (targets.has(rel)) refuse('INPUT_INVALID', `${rel}: written twice in one transaction`);
+        targets.add(rel);
+        writes.push({ target: rel, content: serialize(content) });
+      },
+      now: nowIso(),
+    };
+    const result = fn(ctx);
+    if (hooks) hooks('validated');
+    if (!writes.length) return { result, writes: [], id: null };
+    const id = `${TXN_PREFIX}${compact()}-${crypto.randomBytes(3).toString('hex')}`;
+    const staging = path.join(journalDir(root), id);
+    fs.mkdirSync(staging, { recursive: true });
+    const manifest = { schema: MANIFEST_SCHEMA, id, command, started: ctx.now, writes: [] };
+    writes.forEach((w, i) => {
+      const staged = `${String(i + 1).padStart(2, '0')}-${path.basename(w.target)}`;
+      fs.writeFileSync(path.join(staging, staged), w.content);
+      manifest.writes.push({ target: w.target, staged });
+    });
+    if (hooks) hooks('staged');
+    // The manifest is the commit point: written to a temporary name and renamed.
+    const temp = path.join(staging, `.manifest.${process.pid}.tmp`);
+    fs.writeFileSync(temp, `${JSON.stringify(manifest, null, 2)}\n`);
+    fs.renameSync(temp, path.join(staging, 'manifest.json'));
+    if (hooks) hooks('manifest');
+    applyManifest(root, staging, manifest, hooks);
+    return { result, writes: manifest.writes.map(w => w.target), id };
+  }, { command, waitMs, log });
+}
+function assertRelative(rel) {
+  if (typeof rel !== 'string' || !SAFE_RELATIVE.test(rel) || path.isAbsolute(rel)) refuse('INPUT_INVALID', `${rel}: paths must be repository-relative without ".."`);
+}
+
+// Bounded text arguments stored verbatim in records (reasons, notes, references…).
+function boundedText(value, name, { required = true } = {}) {
+  if (value === undefined || value === null) { if (required) refuse('INPUT_INVALID', `--${name} is required`); return null; }
+  if (typeof value !== 'string' || (required && !value.trim())) refuse('INPUT_INVALID', `--${name} must be a nonempty string`);
+  if (value.length > MAX_TEXT) refuse('INPUT_INVALID', `--${name} is longer than ${MAX_TEXT} characters; store a reference, not a transcript`);
+  return value;
+}
+
+module.exports = { Refusal, refuse, run, pending, recoverPending, runningAttempts, requireIdle, boundedText, MANIFEST_SCHEMA, MAX_TEXT, TXN_PREFIX };

package/template/scripts/pincer-runtime/transitions.cjs

@@ -0,0 +1,134 @@
+'use strict';
+// PINCER runtime — change lifecycle transitions (docs/runtime-contracts.md,
+// "Lifecycle"). planned → active → paused/completed → …, cancelled and
+// superseded as terminal states, each transition one transaction that checks the
+// whole precondition set under the lock, appends exactly one event and rewrites
+// the projection; an invalid transition writes nothing; requesting the state a
+// record already has writes no event. Running attempts are never terminated
+// here: pause, complete, cancel and supersede refuse while one runs.
+const transaction = require('./transaction.cjs');
+const agreement = require('./agreement.cjs');
+const { inlineSecretLine } = require('./sanitize.cjs');
+
+const OPS = ['activate', 'pause', 'resume', 'complete', 'reopen', 'cancel', 'supersede'];
+const NEEDS_SELECTION = ['activate', 'pause', 'resume', 'complete', 'reopen'];
+const NEEDS_IDLE = ['pause', 'complete', 'cancel', 'supersede'];
+const ACTIVATION = ['activate', 'resume', 'reopen'];
+const DECISION_ID = /^D-[0-9]{2,6}$/;
+
+function text(value, name, options) {
+  const v = transaction.boundedText(value, name, options);
+  if (v !== null && inlineSecretLine([v])) transaction.refuse('INPUT_INVALID', `--${name} assigns a secret-like literal; reference secrets by name, never by value`);
+  return v;
+}
+// The operations the table permits from a state (for refusal messages).
+function permitted(changes, state) {
+  return OPS.filter(op => changes.LIFECYCLE_KINDS[op][0].includes(state));
+}
+
+// transition(root, id, op, opts): opts = { reason, note, decision, with, expect, hooks }.
+// Returns { action: 'transitioned' | 'unchanged', record, from, to, event } or { code, problem }.
+function transition(root, id, op, opts = {}) {
+  const changes = require('./changes.cjs');
+  const authorization = require('./authorization.cjs');
+  const statusModule = require('./status.cjs');
+  if (!OPS.includes(op)) return { code: 'INPUT_INVALID', problem: `unknown lifecycle operation ${op}` };
+  const [froms, to] = changes.LIFECYCLE_KINDS[op];
+  try {
+    const out = transaction.run(root, { command: `change ${op} ${id}`, hooks: opts.hooks || null }, ctx => {
+      const resolved = changes.resolveSelected(root, { change: id });
+      if (resolved.code) ctx.refuse(resolved.code, resolved.problem);
+      if (opts.expect !== undefined && opts.expect !== null) ctx.expect(resolved.file, 'sequence', opts.expect);
+      const record = resolved.record;
+      const from = record.lifecycle.state;
+      // Idempotence: the requested state is already the state (same replacement for supersede).
+      if (from === to && (op !== 'supersede' || record.lifecycle.superseded_by === opts.with)) return { action: 'unchanged', record, from, to };
+      if (changes.TERMINAL.includes(from)) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} is ${from}${record.lifecycle.superseded_by ? ` by ${record.lifecycle.superseded_by}` : ''}; its history is inspectable (change show ${id}) but it cannot be ${op}d — register a new change and reference this record`);
+      if (!froms.includes(from)) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} is ${from}; ${op} applies to ${froms.join(' or ')} changes — permitted now: ${permitted(changes, from).map(o => `change ${o}`).join(', ')}`);
+      if (NEEDS_SELECTION.includes(op)) {
+        if (!resolved.selection) ctx.refuse('SELECTION_REQUIRED', `${op} needs the change selected in this worktree: node scripts/pincer-runtime.cjs change select ${id}`);
+        if (resolved.selection.change !== id) ctx.refuse('WRONG_CHANGE', `the selected change is ${resolved.selection.change}, not ${id}; select it first: node scripts/pincer-runtime.cjs change select ${id}`);
+      }
+      const reason = ['pause', 'reopen', 'cancel'].includes(op) ? text(opts.reason, 'reason') : null;
+      const note = op === 'pause' ? text(opts.note, 'note', { required: false }) : null;
+      let decision = null;
+      if (['cancel', 'supersede'].includes(op)) {
+        if (typeof opts.decision !== 'string' || !DECISION_ID.test(opts.decision)) ctx.refuse('INPUT_INVALID', `${op} requires --decision D-NN, the user's recorded decision (change decide ${id} --summary … then --resolve)`);
+        const d = record.decisions.find(x => x.id === opts.decision);
+        if (!d) ctx.refuse('INPUT_INVALID', `--decision ${opts.decision} is not a decision of change ${id} (recorded: ${record.decisions.map(x => x.id).join(', ') || 'none'})`);
+        if (d.status !== 'resolved') ctx.refuse('DECISION_REQUIRED', `decision ${d.id} is still open; record the user's decision first: node scripts/pincer-runtime.cjs change decide ${id} --resolve ${d.id} --reference <text> --excerpt <text>`);
+        decision = d.id;
+      }
+      let replacement = null;
+      if (op === 'supersede') {
+        const w = opts.with;
+        if (typeof w !== 'string' || !changes.CHANGE_ID.test(w)) ctx.refuse('INPUT_INVALID', 'supersede requires --with <replacement change id>');
+        if (w === id) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} cannot supersede itself`);
+        if (!resolved.loaded.records.has(w)) ctx.refuse('INPUT_INVALID', `replacement change "${w}" is not a retained record (retained: ${[...resolved.loaded.records.keys()].join(', ')}); register it first`);
+        // The replacement must not be (transitively) superseded by this record.
+        let cursor = resolved.loaded.records.get(w).record.lifecycle.superseded_by;
+        const seen = new Set([w]);
+        while (cursor) {
+          if (cursor === id) ctx.refuse('LIFECYCLE_BLOCKED', `change "${w}" is already superseded by ${[...seen].join(' → ')} → ${id}; superseding ${id} with it would form a cycle`);
+          if (seen.has(cursor)) break;
+          seen.add(cursor);
+          const next = resolved.loaded.records.get(cursor);
+          cursor = next ? next.record.lifecycle.superseded_by : null;
+        }
+        replacement = w;
+      }
+      if (NEEDS_IDLE.includes(op)) ctx.idle(id);
+      let authorized = null, agreementId = null, verdict = null;
+      if (ACTIVATION.includes(op) || op === 'complete') {
+        const v = changes.view(root, record);
+        if (v.problems.length) ctx.refuse(v.problems[0].code, v.problems[0].detail);
+        const computed = agreement.compute(root, record);
+        if (computed.code) ctx.refuse(computed.code, computed.problem);
+        verdict = authorization.verdict(root, record, computed);
+        if (verdict.verdict !== 'current') ctx.refuse(verdict.verdict, verdict.detail);
+        authorized = verdict.authorized.id; agreementId = verdict.authorized.agreement;
+        if (ACTIVATION.includes(op)) {
+          for (const [otherId, e] of resolved.loaded.records) {
+            if (otherId !== id && e.record.lifecycle.state === 'active') ctx.refuse('LIFECYCLE_BLOCKED', `change ${otherId} is active in this tree; pause or complete it before activating ${id} (at most one active change)`);
+          }
+        }
+      }
+      if (op === 'complete') {
+        const st = statusModule.render(root, { change: id });
+        const g = st.gathered;
+        if (!g || !g.tickets) ctx.refuse('INPUT_INVALID', st.text.trim().split('\n').find(l => l.startsWith('WARN')) || 'the change cannot be inspected');
+        if (g.unresolved > 0) ctx.refuse('INPUT_INVALID', 'a ticket has an unresolved PRD association; repair it before completing');
+        if (!g.tickets.length) ctx.refuse('LIFECYCLE_BLOCKED', `change ${id} has no tickets; a change completes only with a verified breakdown`);
+        // Strict coverage (docs/runtime-contracts.md, "Phase-specific coverage"): structural
+        // completeness — every scenario linked or authorized as not delivered, nothing
+        // missing from the baseline — precedes the ticket readiness gate below; a
+        // candidate is never demanded here.
+        if (changes.isStrict(record)) {
+          const report = require('./phases.cjs').compute(root, record, { gathered: g, verdict });
+          const blocker = require('./phases.cjs').firstBlocker(report, 'structure');
+          if (blocker) ctx.refuse(blocker.code, `${blocker.detail} — complete needs structural coverage: every scenario linked or dispositioned, every ticket classified, every disposition authorized`);
+        }
+        for (const t of g.tickets) {
+          const tid = t.fields.ticket;
+          if (t.fields.status !== 'done') ctx.refuse('LIFECYCLE_BLOCKED', `${tid} is ${t.fields.status}, not done; finish every ticket before completing ${id}`);
+          const r = g.computeReadiness(t);
+          if (!r.ready) ctx.refuse(r.reasons[0].code, `${tid}: ${r.reasons[0].detail} — ${r.reasons[0].next}`);
+        }
+      }
+      const sequence = record.sequence + 1;
+      const event = { sequence, kind: op, from, to, at: ctx.now, reason, agreement: agreementId, authorization: authorized, decision, replacement, note };
+      record.events.push(event);
+      record.sequence = sequence;
+      record.lifecycle = { state: to, since: ctx.now, reason, note, superseded_by: replacement };
+      ctx.write(resolved.file, record);
+      return { action: 'transitioned', record, from, to, event };
+    });
+    return out.result;
+  } catch (error) {
+    if (error.refusal) return { code: error.code, problem: error.message };
+    if (error.code === 'STATE_BUSY') return { code: 'STATE_BUSY', problem: error.message };
+    throw error;
+  }
+}
+
+module.exports = { OPS, transition, permitted };