rcf-lite 0.0.1 → 0.7.1

package/src/query/trace.js

@@ -0,0 +1,345 @@
+// Pure trace compute. Given a walker-produced TreeModel + a pivot id,
+// walk the graph in one or both directions.
+//
+// Phase 5 §D8 trace-back: cross-links are NOT traversed by --back.
+// From an AC, back walks the parent-child edge to US (not the
+// `fbsByAcId` cross-link). This keeps --back unambiguous and
+// terminating; cross-link fan-out is what `impact` is for.
+//
+// Phase 5 §D9 --both output shape: {pivot, ancestors, descendants} -
+// two arrays around a single pivot id; not one merged graph. The
+// pivot appears in neither array (it's the anchor).
+//
+// Phase 5 §4.2 test surface documents the expected node/edge shape:
+//   - Forward from PRD returns full descendant tree down to TCs.
+//   - Forward from AC follows all cross-links (tsByAcId, tcsByAcId,
+//     fbsByAcId) - but a delivering FBS is a cross-link LEAF: trace
+//     never traverses through the FBS layer (AC-402-3). The FBS
+//     dependency fan-out is impact's business (expandFbsDependents).
+//   - Back from TC walks TC -> TS -> AC -> US -> REQ -> PRD (AC noted
+//     via testCases[].acId; back-walk continues through parentByChild).
+
+/**
+ * @typedef {import('#core/store/walker.js').TreeModel} TreeModel
+ */
+
+/**
+ * @typedef {'forward' | 'back' | 'both'} TraceDirection
+ */
+
+/**
+ * @typedef {object} TraceNode
+ * @property {string} id
+ * @property {string} kind
+ * @property {number} depth - 0 for pivot; positive for descendants; negative for ancestors
+ */
+
+/**
+ * @typedef {object} TraceEdge
+ * @property {string} from
+ * @property {string} to
+ * @property {'parentChild' | 'crossLink'} kind
+ */
+
+/**
+ * @typedef {object} TraceResult
+ * @property {string} pivot - the id queried
+ * @property {TraceDirection} direction
+ * @property {boolean} found - false when the pivot id is unknown
+ * @property {TraceNode[]} [nodes] - direction forward | back
+ * @property {TraceEdge[]} [edges] - direction forward | back
+ * @property {TraceNode[]} [ancestors] - direction both
+ * @property {TraceNode[]} [descendants] - direction both
+ */
+
+const INLINE_AC_RE = /^AC-/;
+const INLINE_TC_RE = /^TC-/;
+
+/**
+ * Return the effective kind of an id. `tree.kindById` covers every
+ * standalone doc; inline AC / TC ids are inferred from the id prefix.
+ *
+ * @param {TreeModel} tree
+ * @param {string} id
+ * @returns {string | null}
+ */
+export function kindOf(tree, id) {
+  const k = tree.kindById.get(id);
+  if (k) return k;
+  if (INLINE_AC_RE.test(id)) return tree.parentByChild.has(id) ? 'ac' : null;
+  if (INLINE_TC_RE.test(id)) return tree.parentByChild.has(id) ? 'tc' : null;
+  return null;
+}
+
+/**
+ * Compute a trace from `id` in the requested direction. Unknown pivot
+ * returns `{found: false}`; the handler layer converts this to exit 2.
+ *
+ * @param {TreeModel} tree
+ * @param {object} opts
+ * @param {string} opts.id
+ * @param {TraceDirection} [opts.direction]
+ * @param {boolean} [opts.includeCode] - Phase 10: extend the forward fan-out
+ *   into Code Nodes (AC -> implementing CN -> transitive dependents). Opt-in
+ *   so spec-only queries stay byte-identical (spec D9).
+ * @param {boolean} [opts.expandFbsDependents] - opt-in (impact only): expand
+ *   an FBS node's dependency fan-out (dependentsByFbsId). Default OFF: trace
+ *   is the intent-chain walk, and per AC-402-3 a delivering FBS appears as a
+ *   cross-link LEAF - trace never traverses through the FBS layer. Impact is
+ *   the blast-radius question, so `computeImpact` opts in (D7: a dependent of
+ *   an affected FBS needs re-execution).
+ * @returns {TraceResult}
+ */
+export function computeTrace(tree, {
+  id, direction = 'forward', includeCode = false, expandFbsDependents = false,
+}) {
+  const kind = kindOf(tree, id);
+  if (!kind) {
+    return { pivot: id, direction, found: false };
+  }
+  if (direction === 'forward') {
+    const { nodes, edges } = walkForward(tree, id, kind, includeCode, expandFbsDependents);
+    return { pivot: id, direction, found: true, nodes, edges };
+  }
+  if (direction === 'back') {
+    const { nodes, edges } = walkBack(tree, id, kind);
+    return { pivot: id, direction, found: true, nodes, edges };
+  }
+  // both
+  const back = walkBack(tree, id, kind);
+  const fwd = walkForward(tree, id, kind, includeCode, expandFbsDependents);
+  // Both arrays exclude the pivot; pivot is the anchor between them
+  // (spec §D9: two arrays around a single pivot id).
+  return {
+    pivot: id,
+    direction: 'both',
+    found: true,
+    ancestors: back.nodes.filter((n) => n.id !== id),
+    descendants: fwd.nodes.filter((n) => n.id !== id),
+  };
+}
+
+/**
+ * Forward walk from pivot. BFS over structural children + cross-link
+ * children. Each visited id becomes a node; each traversal step
+ * becomes an edge (parentChild or crossLink).
+ *
+ * @param {TreeModel} tree
+ * @param {string} pivot
+ * @param {string} pivotKind
+ * @param {boolean} [includeCode] - Phase 10 opt-in for the code layer.
+ * @param {boolean} [expandFbsDependents] - impact-only opt-in; see
+ *   `computeTrace`. When off, FBS nodes are leaves (AC-402-3).
+ * @returns {{nodes: TraceNode[], edges: TraceEdge[]}}
+ */
+function walkForward(tree, pivot, pivotKind, includeCode = false, expandFbsDependents = false) {
+  /** @type {TraceNode[]} */
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  /** @type {TraceEdge[]} */
+  const edges = [];
+  const seen = new Set([pivot]);
+  const depthById = new Map([[pivot, 0]]);
+  /** @type {string[]} */
+  const queue = [pivot];
+
+  while (queue.length > 0) {
+    const cur = queue.shift();
+    if (!cur) break;
+    const curDepth = depthById.get(cur) ?? 0;
+    const children = forwardChildrenOf(tree, cur, includeCode, expandFbsDependents);
+    for (const child of children) {
+      // Always emit the edge (even if child already visited via a
+      // different parent) so the graph is complete; only enqueue and
+      // add-as-node the first time.
+      edges.push({ from: cur, to: child.id, kind: child.edgeKind });
+      if (seen.has(child.id)) continue;
+      seen.add(child.id);
+      const childKind = kindOf(tree, child.id);
+      if (!childKind) continue;
+      const nextDepth = curDepth + 1;
+      depthById.set(child.id, nextDepth);
+      nodes.push({ id: child.id, kind: childKind, depth: nextDepth });
+      queue.push(child.id);
+    }
+  }
+  return { nodes, edges };
+}
+
+/**
+ * Back walk from pivot. Follows `parentByChild` up to the root.
+ * D8: cross-links are NOT traversed. Special case for TC: also
+ * include the referenced AC (from tc.acId) between TS and US so the
+ * back-trace surfaces the AC the TC exercises (§4.2 test surface).
+ *
+ * @param {TreeModel} tree
+ * @param {string} pivot
+ * @param {string} pivotKind
+ * @returns {{nodes: TraceNode[], edges: TraceEdge[]}}
+ */
+function walkBack(tree, pivot, pivotKind) {
+  /** @type {TraceNode[]} */
+  const nodes = [{ id: pivot, kind: pivotKind, depth: 0 }];
+  /** @type {TraceEdge[]} */
+  const edges = [];
+  const seen = new Set([pivot]);
+
+  const addStep = (fromId, toId, edgeKind, depth) => {
+    if (!toId || seen.has(toId)) return;
+    const k = kindOf(tree, toId);
+    if (!k) return;
+    seen.add(toId);
+    nodes.push({ id: toId, kind: k, depth });
+    edges.push({ from: fromId, to: toId, kind: edgeKind });
+  };
+
+  // TC special-case: insert AC (via testCases[].acId cross-link) between
+  // TS and US in the back trace. Every other segment follows parentByChild.
+  if (pivotKind === 'tc') {
+    const tsId = tree.parentByChild.get(pivot);
+    if (tsId) {
+      addStep(pivot, tsId, 'parentChild', -1);
+      const ts = tree.byId.get(tsId);
+      const tc = ts?.testCases?.find((t) => t.id === pivot);
+      const acId = tc?.acId;
+      if (acId && !seen.has(acId)) {
+        addStep(tsId, acId, 'crossLink', -2);
+        // Continue from AC upward via parentByChild.
+        let cur = acId;
+        let depth = -3;
+        while (cur) {
+          const parent = tree.parentByChild.get(cur);
+          if (!parent) break;
+          addStep(cur, parent, 'parentChild', depth);
+          cur = parent;
+          depth -= 1;
+        }
+        return { nodes, edges };
+      }
+      // Fall through to plain TS -> US -> REQ -> PRD walk.
+      let cur = tsId;
+      let depth = -2;
+      while (cur) {
+        const parent = tree.parentByChild.get(cur);
+        if (!parent) break;
+        addStep(cur, parent, 'parentChild', depth);
+        cur = parent;
+        depth -= 1;
+      }
+      return { nodes, edges };
+    }
+  }
+
+  // Phase 10 (X2 CodeNode bridge): CN special-case. A code node's parents
+  // are the ACs it implements (a cross-link, not a parent-child edge).
+  // Insert each AC below its US, then continue up via parentByChild
+  // (AC -> US -> REQ -> PRD). This is exactly the `rcf trace <path>`
+  // backward query: from a source location up to every requirement that
+  // location serves.
+  if (pivotKind === 'codeNode') {
+    const cn = tree.byId.get(pivot);
+    let depth = -1;
+    for (const acId of cn?.implementsAcIds ?? []) {
+      if (seen.has(acId)) continue;
+      addStep(pivot, acId, 'crossLink', depth);
+      let cur = acId;
+      let up = depth - 1;
+      while (cur) {
+        const parent = tree.parentByChild.get(cur);
+        if (!parent || seen.has(parent)) break;
+        addStep(cur, parent, 'parentChild', up);
+        cur = parent;
+        up -= 1;
+      }
+    }
+    return { nodes, edges };
+  }
+
+  let cur = pivot;
+  let depth = -1;
+  while (cur) {
+    const parent = tree.parentByChild.get(cur);
+    if (!parent) break;
+    addStep(cur, parent, 'parentChild', depth);
+    cur = parent;
+    depth -= 1;
+  }
+  return { nodes, edges };
+}
+
+/**
+ * Enumerate forward children of `id`. Combines:
+ *   - parent-child edges via `childrenByParent`
+ *   - inline AC ids for US pivots
+ *   - inline TC ids for TS pivots
+ *   - cross-links: tsByAcId + fbsByAcId + tcsByAcId for AC pivots
+ *   - cross-links: usByTacId + FBS-context-refs for TAC pivots
+ *   - cross-links: FBS-context-refs for ADR pivots
+ *   - cross-links: dependentsByFbsId for FBS pivots
+ *
+ * @param {TreeModel} tree
+ * @param {string} id
+ * @param {boolean} [includeCode] - Phase 10 opt-in for the code layer.
+ * @param {boolean} [expandFbsDependents] - impact-only opt-in; see
+ *   `computeTrace`. When off (trace), an FBS enumerates no children:
+ *   it is a cross-link leaf per AC-402-3.
+ * @returns {{id: string, edgeKind: 'parentChild' | 'crossLink'}[]}
+ */
+function forwardChildrenOf(tree, id, includeCode = false, expandFbsDependents = false) {
+  const kind = kindOf(tree, id);
+  const doc = tree.byId.get(id);
+  /** @type {{id: string, edgeKind: 'parentChild' | 'crossLink'}[]} */
+  const out = [];
+  const seen = new Set();
+  const push = (childId, edgeKind) => {
+    if (!childId || seen.has(childId)) return;
+    seen.add(childId);
+    out.push({ id: childId, edgeKind });
+  };
+
+  // Parent-child edges (standalone kids).
+  for (const c of tree.childrenByParent.get(id) ?? []) push(c, 'parentChild');
+
+  // Inline children.
+  if (kind === 'userStory' && doc) {
+    for (const ac of doc.acceptanceCriteria ?? []) push(ac?.id, 'parentChild');
+  }
+  if (kind === 'testSuite' && doc) {
+    for (const tc of doc.testCases ?? []) push(tc?.id, 'parentChild');
+  }
+
+  // Cross-links.
+  if (kind === 'ac') {
+    for (const tsId of tree.tsByAcId.get(id) ?? []) push(tsId, 'crossLink');
+    for (const entry of tree.tcsByAcId.get(id) ?? []) push(entry.tcId, 'crossLink');
+    for (const fbsId of tree.fbsByAcId.get(id) ?? []) push(fbsId, 'crossLink');
+    // Phase 10 (X2 CodeNode bridge): AC -> implementing Code Nodes. This is
+    // the seam that carries a forward trace/impact from spec into source.
+    // Opt-in (includeCode) so spec-only queries stay byte-identical.
+    if (includeCode) {
+      for (const cnId of tree.cnByAcId?.get(id) ?? []) push(cnId, 'crossLink');
+    }
+  }
+  // Phase 10: CN -> dependent Code Nodes. Forward from a code node is the
+  // blast radius: everything that declares this node in its dependencies[].
+  if (kind === 'codeNode' && includeCode) {
+    for (const depId of tree.dependentsByCnId?.get(id) ?? []) push(depId, 'crossLink');
+  }
+  if (kind === 'tac') {
+    for (const usId of tree.usByTacId.get(id) ?? []) push(usId, 'crossLink');
+    for (const fbs of tree.fbsItems) {
+      if ((fbs.contextRequirements?.tacIds ?? []).includes(id)) push(fbs.fbsId, 'crossLink');
+    }
+  }
+  if (kind === 'adr') {
+    for (const fbs of tree.fbsItems) {
+      if ((fbs.contextRequirements?.adrIds ?? []).includes(id)) push(fbs.fbsId, 'crossLink');
+    }
+  }
+  // AC-402-3: in a trace, the FBS layer is never traversed through - a
+  // delivering FBS is a cross-link leaf. Impact opts in to the dependency
+  // fan-out (D7: dependents of an affected FBS need re-execution).
+  if (kind === 'fbs' && expandFbsDependents) {
+    for (const depId of tree.dependentsByFbsId.get(id) ?? []) push(depId, 'crossLink');
+  }
+  return out;
+}

package/src/register-canary/fixture-loader.js

@@ -0,0 +1,87 @@
+// Fixture-pack loader for the register canary (spec §7.3).
+//
+// The fixture pack ships in `#core/fixtures/register-canary`.
+// This loader reads each file by id, verifies the shape the runner
+// consumes, and returns the pack in canonical order. Operators can
+// extend the pack via a local `fixtures/register-canary/*.json` in
+// their own project; the loader accepts an override directory for that.
+
+import { readFile, readdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Canonical fixture ids that ship in the core pack (spec §7.3). */
+export const DEFAULT_FIXTURE_IDS = Object.freeze([
+  'canary-prompt-01',
+  'canary-prompt-02',
+  'canary-prompt-03',
+]);
+
+/**
+ * Locate the core fixture directory. Post-0.7.1 consolidation the core src
+ * lives inline under `src/core/`, so the loader (which sits at
+ * `src/register-canary/`) can reach the fixture pack via a single relative
+ * walk. `RCF_CANARY_FIXTURE_DIR` still overrides for tests and operators.
+ *
+ * @returns {string}
+ */
+export function defaultFixtureDir() {
+  // src/register-canary/ -> up one -> src/ -> core/fixtures/register-canary.
+  // Same relative shape in dev and inside the published tarball because the
+  // umbrella ships src/ verbatim (no build step). See package.json `files`.
+  const fixtureCandidate = join(here, '..', 'core', 'fixtures', 'register-canary');
+  return process.env.RCF_CANARY_FIXTURE_DIR ?? fixtureCandidate;
+}
+
+/**
+ * @typedef {object} CanaryFixture
+ * @property {string} id
+ * @property {string} operatorPrompt
+ * @property {Array<{ path: string, content: string }>} [supportingArtefacts]
+ * @property {string[]} grantedPermissions
+ * @property {number} wordCountBudget
+ * @property {string} [notes]
+ */
+
+/**
+ * Load a fixture pack from a directory. Reads every *.json file in
+ * canonical order; the ids must be unique. Overrides via env
+ * `RCF_CANARY_FIXTURE_DIR` (used by tests).
+ *
+ * @param {string} [dir]
+ * @returns {Promise<CanaryFixture[]>}
+ */
+export async function loadFixturePack(dir = defaultFixtureDir()) {
+  const files = (await readdir(dir))
+    .filter((n) => n.endsWith('.json'))
+    .sort();
+  const fixtures = [];
+  const ids = new Set();
+  for (const name of files) {
+    const abs = join(dir, name);
+    const raw = await readFile(abs, 'utf8');
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`register-canary fixture ${name}: JSON parse failed: ${err.message}`);
+    }
+    if (typeof parsed?.id !== 'string' || parsed.id.length === 0) {
+      throw new Error(`register-canary fixture ${name}: missing id`);
+    }
+    if (ids.has(parsed.id)) {
+      throw new Error(`register-canary fixture ${name}: duplicate id ${parsed.id}`);
+    }
+    ids.add(parsed.id);
+    if (typeof parsed?.operatorPrompt !== 'string' || parsed.operatorPrompt.length === 0) {
+      throw new Error(`register-canary fixture ${parsed.id}: missing operatorPrompt`);
+    }
+    if (!Array.isArray(parsed?.grantedPermissions)) {
+      throw new Error(`register-canary fixture ${parsed.id}: grantedPermissions must be an array`);
+    }
+    fixtures.push(parsed);
+  }
+  return fixtures;
+}

package/src/register-canary/index.js

@@ -0,0 +1,10 @@
+// Public surface for the register-canary runner (spec §7).
+
+export { loadFixturePack, DEFAULT_FIXTURE_IDS } from './fixture-loader.js';
+export {
+  composeCanaryRecord,
+  writeCanaryManifest,
+  readCanaryManifest,
+  DEFAULT_CANARY_MANIFEST_PATH,
+} from './record-writer.js';
+export { runCanaryAgainstFixture, runCanaryPack, MOCK_SUBAGENT } from './runner.js';

package/src/register-canary/record-writer.js

@@ -0,0 +1,132 @@
+// Canary record composer + fixture-manifest writer (spec §3.5, §7.4).
+//
+// Records land on a fixture manifest (not a real chain manifest) at
+// packages/rcf-lite/fixtures/canary-manifest.json. Consumers grep the top
+// record's verdict to decide whether to gate a release; a
+// ship-despite-fail record carries `shipDespiteFailReason` so the
+// operator's ruling is durable and greppable.
+
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Location of the fixture manifest that carries the canary history. */
+export const DEFAULT_CANARY_MANIFEST_PATH = resolve(here, '..', '..', 'fixtures', 'canary-manifest.json');
+
+const ID_RE = /^rc-\d{4}-\d{2}-\d{2}-(\d{3})$/;
+
+function nextCanaryId(records, now = new Date()) {
+  const yyyy = now.getUTCFullYear().toString().padStart(4, '0');
+  const mm = (now.getUTCMonth() + 1).toString().padStart(2, '0');
+  const dd = now.getUTCDate().toString().padStart(2, '0');
+  const prefix = `rc-${yyyy}-${mm}-${dd}-`;
+  let maxN = 0;
+  for (const r of records) {
+    if (typeof r?.id !== 'string' || !r.id.startsWith(prefix)) continue;
+    const m = r.id.match(ID_RE);
+    if (m) {
+      const n = Number.parseInt(m[1], 10);
+      if (Number.isFinite(n) && n > maxN) maxN = n;
+    }
+  }
+  return `${prefix}${(maxN + 1).toString().padStart(3, '0')}`;
+}
+
+/**
+ * Compose a registerCanary[] record for one fixture run.
+ *
+ * @param {object} args
+ * @param {object[]} args.existingRecords
+ * @param {string} args.buildVersion
+ * @param {string} args.fixturePromptId
+ * @param {string} args.responseBody
+ * @param {{ verdict: 'pass'|'fail', grades: object }} args.grade
+ * @param {string} [args.shipDespiteFailReason]
+ * @param {Date} [args.now]
+ * @returns {object}
+ */
+export function composeCanaryRecord({ existingRecords, buildVersion, fixturePromptId, responseBody, grade, shipDespiteFailReason, now = new Date() }) {
+  const isoNow = now.toISOString();
+  const record = {
+    id: nextCanaryId(existingRecords, now),
+    createdAt: isoNow,
+    buildVersion,
+    fixturePromptId,
+    responseWordCount: countWords(responseBody),
+    grades: grade.grades,
+    verdict: grade.verdict,
+  };
+  if (typeof shipDespiteFailReason === 'string' && shipDespiteFailReason.length > 0) {
+    record.shipDespiteFailReason = shipDespiteFailReason;
+  }
+  return record;
+}
+
+function countWords(text) {
+  const stripped = String(text ?? '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`\n]*`/g, ' ')
+    .trim();
+  if (stripped.length === 0) return 0;
+  return stripped.split(/\s+/).length;
+}
+
+/**
+ * Read the fixture manifest (or return an empty seed when missing).
+ *
+ * @param {string} [path]
+ * @returns {Promise<{ registerCanary: object[] }>}
+ */
+export async function readCanaryManifest(path = DEFAULT_CANARY_MANIFEST_PATH) {
+  try {
+    const raw = await readFile(path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed?.registerCanary)) {
+      return { ...parsed, registerCanary: [] };
+    }
+    return parsed;
+  } catch (err) {
+    if (err.code === 'ENOENT') return { registerCanary: [] };
+    throw err;
+  }
+}
+
+/**
+ * Write the fixture manifest atomically. `records` is the full array
+ * (append-only usage: read, append the new record, write the result).
+ *
+ * @param {object} args
+ * @param {object[]} args.records
+ * @param {string} [args.path]
+ * @returns {Promise<void>}
+ */
+export async function writeCanaryManifest({ records, path = DEFAULT_CANARY_MANIFEST_PATH }) {
+  const abs = path;
+  await mkdir(dirname(abs), { recursive: true });
+  const tmp = `${abs}.tmp`;
+  const body = { registerCanary: records };
+  await writeFile(tmp, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+  try {
+    await rename(tmp, abs);
+  } catch (err) {
+    try { await unlink(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * Convenience: append one record to the fixture manifest and write back.
+ *
+ * @param {object} args
+ * @param {object} args.record
+ * @param {string} [args.path]
+ * @returns {Promise<{ records: object[] }>}
+ */
+export async function appendCanaryRecord({ record, path = DEFAULT_CANARY_MANIFEST_PATH }) {
+  const manifest = await readCanaryManifest(path);
+  const records = [...(manifest.registerCanary ?? []), record];
+  await writeCanaryManifest({ records, path });
+  return { records };
+}