@maycombhq/atticus 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/chunk-MZGRDONP.js

@@ -0,0 +1,916 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  estateFreshness
+} from "./chunk-LWDNKE4X.js";
+import "./chunk-4FOAYLI4.js";
+import {
+  writeRepoSpecs
+} from "./chunk-GX74YWR7.js";
+import "./chunk-G6IQYM25.js";
+import {
+  linkEvidenceAbout,
+  linkEvidenceLines,
+  loadLinkEvidence,
+  writeRepoContracts
+} from "./chunk-LPV6T362.js";
+import {
+  repoTypeOf
+} from "./chunk-GIFMBCTW.js";
+import {
+  readPlanProgress
+} from "./chunk-MD7KUEJ3.js";
+import {
+  checkoutOf
+} from "./chunk-Q46QDDMF.js";
+import "./chunk-TGVVUKTG.js";
+import "./chunk-TQ4TG57V.js";
+import {
+  diffLines
+} from "./chunk-NCB6656Z.js";
+import {
+  askHosts
+} from "./chunk-TYD6I4CZ.js";
+import "./chunk-YWAKDNMH.js";
+import "./chunk-3G4YI4ZU.js";
+import "./chunk-3AQ2R5NL.js";
+import "./chunk-VOGCSYOI.js";
+import "./chunk-K332XW7K.js";
+import "./chunk-HSZMPH5T.js";
+import "./chunk-D2WSW4GU.js";
+import "./chunk-4KNOJC6J.js";
+import {
+  TARGETS_STEP,
+  answerReconfirmed,
+  answerRuleOffers,
+  answeredQuestionOfCall,
+  catalogWithFacts,
+  diffCatalogs,
+  diffIsEmpty,
+  estateFacts,
+  estateRepos,
+  groupedTargetDrafts,
+  isPrototypeRepo,
+  pairsOfRepo,
+  prototypeLeftOut,
+  readCatalog,
+  ruledTargets,
+  splitTargetGroups,
+  staleTargetQuestions,
+  targetQuestionFor,
+  targetsFromAnswers,
+  topicQuestionDrafts,
+  writeCatalog
+} from "./chunk-4SLBCEPD.js";
+import "./chunk-64AADMTW.js";
+import {
+  codeLinkerFor,
+  frameworkFacts,
+  frameworkGaps,
+  renderMap,
+  trustOf
+} from "./chunk-JYMIB5XY.js";
+import "./chunk-CPK7QSBG.js";
+import "./chunk-YO2PKTXT.js";
+import "./chunk-TWQRPM76.js";
+import "./chunk-VUVGX5L2.js";
+import {
+  baseClonePath,
+  isInPlace,
+  loadRepos
+} from "./chunk-XOL3GFW2.js";
+import "./chunk-QHJJMZLX.js";
+import "./chunk-7AB6OWTV.js";
+import {
+  CALL_SECURITY_CHECK,
+  SPEC_HEADER_SCHEMA_VERSION,
+  TERM_STEP,
+  TOPICS_STEP_ID,
+  callSecurityParams,
+  catalogDirOf,
+  checkCallSecurity,
+  factIdPart,
+  factsDirOf,
+  factsRelOf,
+  flowFiles,
+  isAdopted,
+  isGuessedJoin,
+  joinFlagsOf,
+  listQuestions,
+  loadOrgPack,
+  mapDirOf,
+  mapRelOf,
+  orgPackDirOf,
+  parseFacts,
+  parseRecord,
+  questionId,
+  questionsRelOf,
+  raiseQuestions,
+  readRepoSpec,
+  readSharedMaps,
+  removeFlow,
+  reopenQuestion,
+  require_dist,
+  retireQuestion,
+  specFileHash,
+  specRelOf,
+  termOfQuestion,
+  termQuestionDrafts,
+  writeFlow,
+  writeSpecHeader
+} from "./chunk-PAINMSID.js";
+import {
+  LockHeldError,
+  acquireLock,
+  writeFileAtomic
+} from "./chunk-ODMBPDDV.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/cli/dist/map-render-commands.js
+var import_yaml = __toESM(require_dist(), 1);
+import { existsSync } from "node:fs";
+import { readFile, readdir, rm } from "node:fs/promises";
+import { join as join2, relative, sep } from "node:path";
+
+// packages/cli/dist/answer-reopen.js
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+function repoOfTarget(op, target) {
+  const t = factIdPart(target);
+  const r = estateRepos(op).find((x) => factIdPart(x.id) === t || x.component !== void 0 && factIdPart(x.component) === t || (x.modules ?? []).some((m) => factIdPart(m.component) === t));
+  return r?.id ?? target;
+}
+var mtimeOf = async (path) => (await stat(path).catch(() => void 0))?.mtimeMs;
+async function readNotSettled(root, repo, o = {}) {
+  const plan = await readPlanProgress(root, repo);
+  if (plan && (plan.stale || plan.done < plan.total))
+    return plan.stale ? `its read plan is of another commit (${plan.commit})` : `${plan.total - plan.done} of the ${plan.total} parts of its read plan are not read yet`;
+  const dir = factsDirOf(root);
+  const gaps = await mtimeOf(join(dir, `${repo}.gaps.md`));
+  const facts = await mtimeOf(join(dir, `${repo}.jsonl`));
+  if (gaps !== void 0 && (facts === void 0 || gaps >= facts))
+    return `its second pass (atticus map ${repo} --gaps) is planned and not read yet`;
+  const fresh = (await estateFreshness(root, { repos: [repo], ...o.git ? { git: o.git } : {} })).repos[0];
+  if (!fresh || fresh.state !== "fresh" && fresh.state !== "rules-changed")
+    return `its facts aren't fresh (atticus estate fresh says ${fresh?.state ?? "not-read"})`;
+  return void 0;
+}
+
+// packages/cli/dist/term-lines.js
+async function termsWrite(root, repo, o) {
+  const lines = [];
+  const raised = [];
+  const t = o.terms;
+  if (t) {
+    for (const a of t.access) {
+      const mine = a.repo === repo || (a.reason === "listed-no-call" ? a.owner.repo : a.call.repo) === repo;
+      if (!mine)
+        continue;
+      lines.push(a.reason === "caller-not-listed" ? `Access: ${a.message}. Add it to the list, or say why it calls (a finding for ${ownerOf(o.op, a.call.repo)}).` : a.reason === "caller-no-id" ? `Access (a note): ${a.message}; whether it is listed is unknown until a fact of ${a.call.repo} names its own id.` : `Access (a note): ${a.message}.`);
+    }
+    for (const p of t.possible) {
+      if (!p.seen.some((s) => s.repo === repo))
+        continue;
+      lines.push(`Possible link (a guess, ${p.flag}): ${p.value} is written in ${[...new Set(p.seen.map((s) => `${s.repo} (${s.at})`))].join(", ")}; a note on the repo type saying what it means links them.`);
+    }
+    const types = /* @__PURE__ */ new Map();
+    for (const r of new Set(t.terms.map((x) => x.repo)))
+      types.set(r, (await repoTypeOf(o.op, r, await o.dirOf(r)))?.id);
+    const all = termQuestionDrafts(t, (r) => types.get(r));
+    const drafts = all.filter((d) => d.terms.some((x) => x.repo === repo));
+    const asked = /* @__PURE__ */ new Map();
+    for (const d of drafts) {
+      const r = await raiseQuestions(root, [d.draft], {
+        step: TERM_STEP,
+        repo: d.repo,
+        command: o.command,
+        rerun: o.rerun,
+        at: o.at
+      });
+      const q0 = r.of[0];
+      if (q0)
+        asked.set(`${d.repo}\0${d.term}\0${d.file}`, q0.id);
+      for (const q of r.raised) {
+        raised.push(q);
+        lines.push(`A term nothing says the meaning of: asked ${q.id}: ${q.question} Answer it: atticus questions answer ${q.id} --option <n>${d.repoType ? `, and save the answer as a note on ${d.repoType} with atticus repo-type note ${d.repoType} --add "..."` : ""}; then ${o.rerun}.`);
+      }
+    }
+    for (const q of (await listQuestions(root, { step: TERM_STEP })).questions) {
+      if (q.state !== "open")
+        continue;
+      const about = termOfQuestion(q.question);
+      if (!about)
+        continue;
+      const k = `${q.repo}\0${about.term}\0${about.file}`;
+      const now = asked.get(k);
+      if (now === q.id)
+        continue;
+      const inGroup = all.find((d) => d.repo === q.repo && d.term === about.term && d.file === about.file);
+      if (q.repo !== repo && !(inGroup && inGroup.terms.some((x) => x.repo === repo)))
+        continue;
+      const why = now ? "the same term is asked across a changed set of repos" : "the facts now give every value it asked about a role";
+      await retireQuestion(root, q.id, { why, at: o.at, ...now ? { replacedBy: [now] } : {} });
+      lines.push(`Retired ${q.id}: ${why}.`);
+    }
+  }
+  if (o.join)
+    for (const pack of o.op.checklists)
+      for (const rule of pack.rules) {
+        if (rule.status !== "active")
+          continue;
+        if (rule.check.type !== "deterministic" || rule.check.check !== CALL_SECURITY_CHECK)
+          continue;
+        const params = callSecurityParams(rule.check.params);
+        if ("problem" in params) {
+          lines.push(`Rule ${rule.id} (${pack.name}) can't be checked: ${params.problem}.`);
+          continue;
+        }
+        for (const r of checkCallSecurity(params, {
+          repos: o.repos,
+          join: o.join,
+          systems: o.op.profiles.flatMap((p) => p.profile?.systems ?? [])
+        }))
+          if (r.call.repo === repo || r.callers.some((c) => c.repo === repo))
+            lines.push(ruleLine(rule.id, r, o.op));
+      }
+  return { lines, raised };
+}
+function ownerOf(op, repo) {
+  const owner = estateRepos(op).find((r) => r.id === repo)?.owner;
+  return owner ? `${repo}'s owner, ${owner}` : `${repo}'s owner`;
+}
+function ruleLine(rule, r, op) {
+  switch (r.outcome) {
+    case "pass":
+      return `Rule ${rule}: passes, ${r.message}.`;
+    case "declared":
+      return `Rule ${rule}: declared, ${r.message}.`;
+    case "finding":
+      return `Rule ${rule}: a finding for ${ownerOf(op, r.call.repo)}: ${r.message}.`;
+  }
+}
+
+// packages/cli/dist/map-render-commands.js
+var FACTS_TEMPLATE = "facts@1";
+var posix = (p) => p.split(sep).join("/");
+var HOW_WORDS = {
+  answer: "a person's answer",
+  named: "name",
+  repo: "the repo's name",
+  host: "host",
+  path: "path",
+  topic: "topic"
+};
+function linkChanges(repo, join3, before, after) {
+  const mine = (xs) => (xs ?? []).filter((x) => x.call.repo === repo);
+  const joined = mine(join3?.joins);
+  const joinsOf = /* @__PURE__ */ new Map();
+  for (const j of [...joined, ...(join3?.joins ?? []).filter((x) => !joined.includes(x))])
+    joinsOf.set(j.interface, [...joinsOf.get(j.interface) ?? [], j]);
+  const howOf = (r) => {
+    const all = joinsOf.get(r.id) ?? [];
+    const own = all.filter((j) => joined.includes(j));
+    const best = own.find((j) => !isGuessedJoin(j)) ?? own[0] ?? all[0];
+    if (!best)
+      return void 0;
+    const byOther = r.confidence === "verified" && own.length > 0 && isGuessedJoin(best);
+    return { how: best.how, ...byOther ? { byOther, guesses: joinFlagsOf(best) } : {} };
+  };
+  const ifaces = (rs) => new Map(rs.filter((r) => r.kind === "Interface").map((r) => [r.id, r]));
+  const was = ifaces(before);
+  const now = ifaces(after);
+  const linked = new Set([...now.values()].flatMap((r) => r.evidence.filter((e) => e.side !== "callee").map((e) => `${e.repo}|${e.path}:${e.line}`)));
+  const line = (r, found) => {
+    const h = found ? howOf(r) : void 0;
+    return {
+      id: r.id,
+      from: r.from,
+      to: r.to,
+      ...r.method ? { method: r.method } : {},
+      path: r.normalizedPath,
+      confidence: r.confidence,
+      ...h ? { how: h.how } : {},
+      ...r.flags?.length ? { flags: [...r.flags] } : {},
+      ...h?.byOther ? { byOther: true, guesses: h.guesses } : {}
+    };
+  };
+  const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  const flagsOf = (r) => [...r.flags ?? []].sort().join(",");
+  const changed = [];
+  for (const [id, r] of now) {
+    const old = was.get(id);
+    if (!old || old.confidence === r.confidence && flagsOf(old) === flagsOf(r))
+      continue;
+    changed.push({
+      ...line(r, true),
+      was: {
+        confidence: old.confidence,
+        ...old.flags?.length ? { flags: [...old.flags] } : {}
+      }
+    });
+  }
+  return {
+    calls: {
+      joined: joined.length,
+      inferred: joined.filter(isGuessedJoin).length,
+      asked: mine(join3?.asks).filter((a) => !linked.has(`${a.call.repo}|${a.call.at}`)).length,
+      outside: mine(join3?.outside).length,
+      missed: mine(join3?.misses).length
+    },
+    added: [...now.values()].filter((r) => !was.has(r.id)).map((r) => line(r, true)).sort(byId),
+    removed: [...was.values()].filter((r) => !now.has(r.id)).map((r) => line(r, false)).sort(byId),
+    changed: changed.sort(byId)
+  };
+}
+var LINKS_SHOWN = 5;
+function linkLines(l, report, o = {}) {
+  const c = l.calls;
+  const calls = `${c.joined} call${c.joined === 1 ? "" : "s"} joined${c.inferred ? ` (${c.inferred} inferred)` : ""}, ${c.asked} asked, ${c.outside} outside the estate, ${c.missed} not joined`;
+  const counts = [
+    l.added.length ? `+${l.added.length}` : "",
+    l.removed.length ? `-${l.removed.length}` : "",
+    l.changed.length ? `~${l.changed.length}` : ""
+  ].filter(Boolean);
+  if (!counts.length)
+    return [`  Links: ${calls}; no Interface added or removed.`];
+  const out = [`  Links: ${calls}; Interfaces ${counts.join(" ")} (all under links in ${report}).`];
+  const text = (sign, x) => {
+    const what = [x.method, x.path].filter(Boolean).join(" ");
+    const conf = x.was ? `${x.confidence}, was ${x.was.confidence}` : x.confidence;
+    if (x.byOther && x.how) {
+      const g = x.guesses?.join(", ");
+      const was = x.was ? `, was ${x.was.confidence}` : "";
+      return `    ${sign} ${x.from} \u2192 ${x.to} ${what} (${x.confidence} by another call${was}; this one by ${HOW_WORDS[x.how]}${g ? `: ${g}` : ""})`;
+    }
+    const flags = x.flags?.join(", ");
+    const found = x.how ? `found by ${HOW_WORDS[x.how]}${flags ? `: ${flags}` : ""}` : flags ?? "";
+    return `    ${sign} ${x.from} \u2192 ${x.to} ${what} (${conf}${found ? `; ${found}` : ""})`;
+  };
+  const all = [
+    ...l.added.map((x) => text("+", x)),
+    ...l.removed.map((x) => text("-", x)),
+    ...l.changed.map((x) => text("~", x))
+  ];
+  const shown = o.verbose ? all : all.slice(0, LINKS_SHOWN);
+  out.push(...shown);
+  if (shown.length < all.length)
+    out.push(`    ... and ${all.length - shown.length} more (links in ${report})`);
+  return out;
+}
+async function writeLinksIntoReport(root, repo, links, exposure = [], evidence, shared) {
+  const file = join2(factsDirOf(root), `${repo}.verify.yaml`);
+  const text = await readFile(file, "utf8").catch(() => void 0);
+  if (text === void 0)
+    return;
+  let report;
+  try {
+    report = (0, import_yaml.parse)(text);
+  } catch {
+    return;
+  }
+  if (!report || typeof report !== "object" || Array.isArray(report))
+    return;
+  const { exposure: _old, contracts: _c, traffic: _t, shared: _s, ...rest } = report;
+  const c = evidence?.contracts;
+  const t = evidence?.traffic;
+  await writeFileAtomic(file, (0, import_yaml.stringify)({
+    ...rest,
+    links,
+    ...exposure.length ? {
+      exposure: exposure.map((x) => ({
+        reason: x.reason,
+        fact: x.exposure.fact,
+        at: x.exposure.at,
+        message: x.message
+      }))
+    } : {},
+    ...c && (c.confirmed.length || c.findings.length) ? { contracts: c } : {},
+    ...t && (t.seen.length || t.findings.length || t.unknownApps.length) ? { traffic: t } : {},
+    ...shared && (shared.joined.length || shared.unmatched.length || shared.asked.length) ? { shared } : {}
+  }));
+}
+function sharedReport(r, maps) {
+  const commit = (team) => maps.find((m) => m.team === team)?.commit ?? "";
+  return {
+    joined: r.matches.map((m) => ({
+      call: m.call.fact,
+      at: m.call.at,
+      team: m.team,
+      commit: commit(m.team),
+      repo: m.entry.repo,
+      entry: m.entry.fact,
+      entryAt: m.entry.at
+    })),
+    unmatched: r.gaps.map((g) => ({
+      call: g.call.fact,
+      at: g.call.at,
+      team: g.team,
+      commit: commit(g.team),
+      message: g.message
+    })),
+    asked: r.asks.map((a) => ({
+      call: a.call.fact,
+      at: a.call.at,
+      team: a.team,
+      question: a.question
+    }))
+  };
+}
+function sharedLines(repo, s, verbose) {
+  const out = [];
+  const teams = [...new Set([...s.joined, ...s.unmatched, ...s.asked].map((x) => x.team))].sort();
+  for (const team of teams) {
+    const j = s.joined.filter((x) => x.team === team);
+    const u = s.unmatched.filter((x) => x.team === team);
+    const a = s.asked.filter((x) => x.team === team);
+    const c = (j[0] ?? u[0])?.commit.slice(0, 7);
+    out.push(`Shared map: ${j.length} of ${repo}'s calls joined to ${team}'s map${c ? ` (their commit ${c})` : ""}, each citing their entry; ${u.length} it has no entry for${a.length ? `; ${a.length} two of its entries answer` : ""}. Their entries are theirs: a wrong one is theirs to correct.`);
+    for (const x of verbose ? j : [])
+      out.push(`  ${x.at} \u2192 ${x.repo} ${x.entryAt} (${x.entry})`);
+    for (const x of verbose ? u : u.slice(0, 5))
+      out.push(`  ${x.at}: ${x.message}`);
+    for (const x of a)
+      out.push(`  ${x.at}: ${x.question}`);
+  }
+  return out;
+}
+function countByKind(d) {
+  const out = {};
+  const of = (k) => out[k] ??= { added: 0, changed: 0, removed: 0 };
+  for (const r of d.added)
+    of(r.kind).added++;
+  for (const r of [...d.changed, ...d.evidenceOnly])
+    of(r.kind).changed++;
+  for (const r of d.removed)
+    of(r.kind).removed++;
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a < b ? -1 : 1));
+}
+function kindLine(byKind) {
+  const parts = Object.entries(byKind).map(([kind, c]) => [
+    kind,
+    c.added ? `+${c.added}` : "",
+    c.changed ? `~${c.changed}` : "",
+    c.removed ? `-${c.removed}` : ""
+  ].filter(Boolean).join(" "));
+  return parts.join(", ");
+}
+async function projectFactsIntoCatalog(root, repo, facts, given = {}) {
+  const op = given.op ?? await loadOrgPack(orgPackDirOf(root));
+  const cacheOpts = given.cache === false ? {} : { cacheRoot: root };
+  const existing = given.existing ?? (await readCatalog(join2(catalogDirOf(root), "generated"), cacheOpts)).records;
+  const curated = await readCatalog(join2(catalogDirOf(root), "curated"), cacheOpts);
+  const everyTarget = (await listQuestions(root, { step: TARGETS_STEP })).questions;
+  const answered = everyTarget.filter((q) => q.repo === repo);
+  const repoType = estateRepos(op).find((r) => r.id === repo)?.type;
+  const targetsOpts = repoType ? { repoType } : {};
+  const aiTargets = {};
+  const targets = targetsFromAnswers(repo, facts, everyTarget, { ...targetsOpts, ai: aiTargets });
+  const ruled = ruledTargets(repo, facts, everyTarget, targetsOpts);
+  const estate = await estateFacts(root, op, repo);
+  const onFile = await loadLinkEvidence(root);
+  const evidence = given.contracts ? {
+    ...onFile,
+    contracts: [
+      ...onFile.contracts.filter((c) => c.repo !== repo),
+      ...given.contracts.entries.length ? [given.contracts] : []
+      // In the companions' file order, as `loadLinkEvidence` reads them.
+    ].sort((a, b) => {
+      const [x, y] = [`${a.repo}.contracts.yaml`, `${b.repo}.contracts.yaml`];
+      return x < y ? -1 : x > y ? 1 : 0;
+    })
+  } : onFile;
+  const shared = await readSharedMaps(root);
+  const result = catalogWithFacts({
+    repo,
+    facts,
+    existing: [...existing],
+    op,
+    decisions: curated.records,
+    targets,
+    estate: estate.repos,
+    estateTargets: estate.targets,
+    // G1 (ADR 0174): the pairings people made on the canvas, this repo's and the others'.
+    pairs: { ...await pairsOfRepo(root, repo, facts), ...given.extraPairs },
+    estatePairs: estate.pairs,
+    aiTargets,
+    estateAiTargets: estate.aiTargets,
+    linkEvidence: { contracts: evidence.contracts, traffic: evidence.traffic },
+    ...shared.maps.length ? { shared: shared.maps } : {}
+  });
+  const diff = diffCatalogs([...existing], result.records);
+  const links = linkChanges(repo, result.join, existing, result.records);
+  return {
+    op,
+    existing,
+    answered,
+    everyTarget,
+    targets,
+    ruled,
+    estate,
+    result,
+    diff,
+    links,
+    evidenceProblems: [...evidence.problems, ...shared.problems.map((p) => p.message)],
+    sharedMaps: shared.maps
+  };
+}
+async function writeFactsIntoCatalog(root, repo, facts, o, io) {
+  let lock;
+  try {
+    lock = await acquireLock(root, "scan", o.command);
+  } catch (e) {
+    if (e instanceof LockHeldError) {
+      io.err(e.message);
+      return void 0;
+    }
+    throw e;
+  }
+  try {
+    const op = await loadOrgPack(orgPackDirOf(root));
+    const generated = join2(catalogDirOf(root), "generated");
+    const existing = await readCatalog(generated, { cacheRoot: root });
+    if (isPrototypeRepo(op, repo)) {
+      for (const n of prototypeLeftOut({ repo, facts, existing: [], op, decisions: [] }).notes)
+        io.out(n);
+      const none = diffCatalogs(existing.records, existing.records);
+      return {
+        written: { written: 0, unchanged: 0, removed: 0 },
+        flows: [],
+        questions: [],
+        map: [],
+        changes: { ...none, byKind: {} },
+        links: {
+          calls: { joined: 0, inferred: 0, asked: 0, outside: 0, missed: 0 },
+          added: [],
+          removed: [],
+          changed: []
+        }
+      };
+    }
+    const rerun = `atticus verify ${repo} --write`;
+    await writeRepoContracts(root, repo, o.dir, facts, (n) => io.err(n));
+    await writeRepoSpecs(root, repo, o.dir, facts, (n) => io.err(n));
+    const { answered, everyTarget, targets, ruled, estate, result, diff, links, evidenceProblems, sharedMaps } = await projectFactsIntoCatalog(root, repo, facts, { op, existing: existing.records });
+    for (const p of evidenceProblems)
+      io.err(p);
+    for (const i of result.invalid)
+      io.err(`A merged record isn't valid C1 (a bug): ${i.issues.map((x) => `${x.path}: ${x.message}`).join("; ")}`);
+    const written = await writeCatalog(generated, result.records);
+    const flows = result.flows.filter((f) => {
+      const p = parseRecord(f);
+      if (p.ok)
+        return true;
+      io.err(`The flow ${f.id} isn't written to ${specRelOf(root, repo)}/: ${p.issues.map((i) => `${i.path}: ${i.message}`).join("; ")}. Have your assistant fix its flow fact (each call-out step's ref names the call it makes), then run ${rerun}.`);
+      return false;
+    });
+    const spec = await readRepoSpec(root, repo, { cacheRoot: root });
+    const ids = new Set(flows.map((f) => f.id));
+    for (const f of spec.flows)
+      if (f.template === FACTS_TEMPLATE && !ids.has(f.id))
+        await removeFlow(root, repo, f.id);
+    const flowPaths = [];
+    for (const f of flows)
+      flowPaths.push(await writeFlow(root, repo, f));
+    const files = {};
+    for (const f of flows)
+      for (const p of flowFiles(f)) {
+        const text = await readFile(join2(o.dir, ...p.split("/")), "utf8").catch(() => void 0);
+        if (text !== void 0)
+          files[p] = specFileHash(text);
+      }
+    const commit = facts.map((f) => f.commit).sort()[0];
+    const kept = spec.flows.filter((f) => f.template !== FACTS_TEMPLATE).map((f) => f.id);
+    const header = spec.header;
+    await writeSpecHeader(root, {
+      schemaVersion: SPEC_HEADER_SCHEMA_VERSION,
+      repo,
+      template: header?.template ?? FACTS_TEMPLATE,
+      templateReviewed: header?.templateReviewed ?? false,
+      ...commit ? { commit } : {},
+      ...header?.drafted ? { drafted: header.drafted } : {},
+      flows: [.../* @__PURE__ */ new Set([...kept, ...ids])].sort(),
+      files: Object.fromEntries(Object.entries({ ...header?.files ?? {}, ...files }).sort(([a], [b]) => a < b ? -1 : 1)),
+      questions: header?.questions ?? []
+    });
+    const at = (o.now ?? /* @__PURE__ */ new Date()).toISOString();
+    const hosts = await askHosts(root, result.records, { command: o.command, rerun, now: o.now });
+    const loose = new Set(result.unresolved.map((u) => u.factId));
+    const ambiguous = new Set((result.join?.asks ?? []).filter((a) => a.reason === "ambiguous" && a.call.repo === repo).map((a) => a.call.fact));
+    const named = new Set(facts.filter((f) => f.kind === "call" && f.to).map((f) => f.id));
+    const raised = [...hosts.raised];
+    const lines = [...hosts.lines];
+    const asked = new Set([...loose, ...ambiguous].filter((id) => targets[id] === void 0 && !answered.some((q) => q.state === "answered" && q.id === targetId(facts, repo, id))));
+    const drafted = groupedTargetDrafts(facts, result.records, op, result.join?.asks, {
+      ask: asked,
+      split: splitTargetGroups(answered),
+      // ADR 0162 (F8): the suggestions read the estate's facts and the earlier answers.
+      estate: estate.repos,
+      questions: everyTarget
+    });
+    const refreshed = [];
+    for (const t of drafted) {
+      const r = await raiseQuestions(root, [t.draft], { step: TARGETS_STEP, repo, command: o.command, rerun, at }, { refresh: true });
+      refreshed.push(...r.refreshed);
+      for (const q of r.raised) {
+        raised.push(q);
+        lines.push(t.factIds.length > 1 ? `${t.factIds.length} calls go the same way and name no target the estate has: asked once, ${q.id}: ${q.question} One answer names the target of all of them. Answer it: atticus questions answer ${q.id} --option <n>, then ${rerun}.` : named.has(t.factId) ? `A call names a target the estate doesn't have, and more than one entry serves it: asked ${q.id}: ${q.question} Answer it: atticus questions answer ${q.id} --option <n>, then ${rerun}.` : `A call names no target: asked ${q.id}: ${q.question} Answer it: atticus questions answer ${q.id} --option <n>, then ${rerun}.`);
+      }
+    }
+    if (refreshed.length)
+      lines.push(`Refreshed ${refreshed.length === 1 ? "1 open question" : `${refreshed.length} open questions`} asked before (${refreshed.map((q) => q.id).join(", ")}): the same id, with today's options, ranked by the estate as read now, each saying why it is suggested.`);
+    for (const t of topicQuestionDrafts(repo, result.records)) {
+      const r = await raiseQuestions(root, [t.draft], {
+        step: TOPICS_STEP_ID,
+        repo,
+        command: o.command,
+        rerun,
+        at
+      });
+      for (const q of r.raised) {
+        raised.push(q);
+        lines.push(`No repo of the estate serves the other side of ${t.topic}: asked ${q.id}: ${q.question} If another team or a vendor owns it, name them: atticus questions answer ${q.id} --target <system or team id> (it goes under the system's topics in the profile, for review), then ${rerun}.`);
+      }
+    }
+    for (const s of staleTargetQuestions({
+      repo,
+      facts,
+      open: answered.filter((q) => q.state === "open"),
+      drafted,
+      asked,
+      ruled,
+      ...result.join ? { join: result.join } : {}
+    })) {
+      await retireQuestion(root, s.id, {
+        why: s.why,
+        at,
+        ...s.replacedBy ? { replacedBy: s.replacedBy } : {}
+      });
+      lines.push(`Retired ${s.id}: ${s.why}.`);
+    }
+    const reopened = /* @__PURE__ */ new Set();
+    const unsettled = /* @__PURE__ */ new Map();
+    for (const m of result.answerMisses ?? []) {
+      const callerFacts = m.call.repo === repo ? facts : estate.repos.find((x) => x.repo === m.call.repo)?.facts;
+      const q = callerFacts ? answeredQuestionOfCall(m.call.repo, callerFacts, everyTarget, m.call.fact) : void 0;
+      if (!q || reopened.has(q.id))
+        continue;
+      if (answerReconfirmed(q))
+        continue;
+      const named2 = repoOfTarget(op, m.target);
+      if (!unsettled.has(named2))
+        unsettled.set(named2, await readNotSettled(root, named2));
+      const notYet = unsettled.get(named2);
+      if (notYet) {
+        lines.push(`${m.target} is read, but ${notYet}: ${q.id}'s answer is checked against it once the read is whole and fresh.`);
+        continue;
+      }
+      reopened.add(q.id);
+      const why = `${m.target} is read now, and no route of it serves the call: ${m.message} (${m.call.at})`;
+      await reopenQuestion(root, q.id, { why, at });
+      lines.push(`Asked again ${q.id}: ${why}. Answer it again: atticus questions answer ${q.id} --option <n> | --target <id>, then atticus verify ${m.call.repo} --write.`);
+    }
+    const typeOf = new Map(estateRepos(op).map((r) => [r.id, r.type]));
+    for (const offer of answerRuleOffers({
+      repos: [{ repo, facts }, ...estate.repos].map((r) => ({
+        ...r,
+        ...typeOf.get(r.repo) ? { type: typeOf.get(r.repo) } : {}
+      })),
+      questions: everyTarget.filter((q) => !reopened.has(q.id))
+    }))
+      if (offer.repos.includes(repo))
+        lines.push(offer.line);
+    const termed = await termsWrite(root, repo, {
+      op,
+      terms: result.terms,
+      repos: [{ repo, facts }, ...estate.repos],
+      join: result.join,
+      command: o.command,
+      rerun,
+      at,
+      dirOf: (r) => r === repo ? Promise.resolve(o.dir) : checkoutOf(root, r)
+    });
+    raised.push(...termed.raised);
+    lines.push(...termed.lines);
+    const byKind = countByKind(diff);
+    io.out(`Wrote the catalog for ${repo}: ${written.written} files written, ${written.removed} removed, ${written.unchanged} unchanged.`);
+    io.out(diffIsEmpty(diff) ? "  No catalog changes." : `  Records: ${kindLine(byKind)}.`);
+    if (o.verbose)
+      for (const l of diffLines(diff).slice(1))
+        io.out(`    ${l}`);
+    const specsRel = specRelOf(root, repo);
+    io.out(`  Flows: ${flowPaths.length} in ${specsRel}/.`);
+    if (o.verbose)
+      for (const p of flowPaths)
+        io.out(`    ${p}`);
+    else if (!diffIsEmpty(diff) || flowPaths.length)
+      io.out(`  atticus verify ${repo} --write --verbose lists each record and flow.`);
+    for (const p of result.curated.problems)
+      io.out(`Curated decision ${p.decision} no longer applies: ${p.message}`);
+    for (const p of result.projectionIssues)
+      io.out(`  ${p.code}: ${p.message}`);
+    for (const l of joinLines(repo, result.join, estate.notes, { verbose: o.verbose === true }))
+      io.out(l);
+    for (const l of linkLines(links, `${factsRelOf(root)}/${repo}.verify.yaml`, {
+      verbose: o.verbose === true
+    }))
+      io.out(l);
+    const about = result.linkEvidence ? linkEvidenceAbout(repo, result.linkEvidence, result.join) : void 0;
+    if (about)
+      for (const l of linkEvidenceLines(about, `${factsRelOf(root)}/${repo}.verify.yaml`, {
+        verbose: o.verbose === true
+      }))
+        io.out(l);
+    const sharedAbout = result.shared ? sharedReport(result.shared, sharedMaps) : void 0;
+    if (sharedAbout)
+      for (const l of sharedLines(repo, sharedAbout, o.verbose === true))
+        io.out(l);
+    await writeLinksIntoReport(root, repo, links, result.join?.exposure, about, sharedAbout);
+    for (const l of lines)
+      io.out(l);
+    const map = await renderRepoMap(root, repo, io);
+    return {
+      written,
+      flows: flowPaths,
+      questions: raised.map((q) => q.id),
+      map: map ?? [],
+      changes: { ...diff, byKind },
+      links
+    };
+  } finally {
+    await lock.release();
+  }
+}
+function targetId(facts, repo, id) {
+  const f = facts.find((x) => x.id === id);
+  const q = f ? targetQuestionFor(f) : void 0;
+  return q ? questionId({ step: TARGETS_STEP, repo, ...q }) : void 0;
+}
+function joinLines(repo, join3, notes = [], o = {}) {
+  if (!join3)
+    return [...notes];
+  const out = [...notes];
+  const mine = join3.joins.filter((j) => j.call.repo === repo && j.call.repo !== j.entry.repo);
+  const into = join3.joins.filter((j) => j.entry.repo === repo && j.call.repo !== repo);
+  if (mine.length || into.length)
+    out.push(`Joined across repos: ${mine.length} of ${repo}'s calls to the entries that serve them, ${into.length} calls of other repos into ${repo}, each citing both ends.`);
+  const guessed = join3.joins.filter((j) => j.call.repo === repo && j.inferred);
+  if (guessed.length) {
+    const own = guessed.filter((j) => j.inferred.within === "repo").length;
+    const where = [
+      own ? `${own} in ${repo} itself` : "",
+      guessed.length - own ? `${guessed.length - own} in another repo${guessed.length - own === 1 ? "" : "s"}` : ""
+    ].filter(Boolean).join(", ");
+    out.push(`Joined by method and path, inferred: ${guessed.length} of ${repo}'s calls name no target the estate has, so each joined the one entry that serves it (${where}).`);
+    if (o.verbose)
+      for (const j of guessed) {
+        const what = j.method ? `${j.method} ${j.path}` : j.path;
+        const named = j.inferred.named ? ` (named ${j.inferred.named})` : "";
+        const there = j.entry.repo === repo ? "" : ` (${j.entry.repo})`;
+        out.push(`  ${j.call.at} ${what}${named} \u2192 ${j.entry.component}${there}`);
+      }
+  }
+  for (const m of join3.misses)
+    out.push(`Not joined: ${m.message} (${m.call.at}).`);
+  for (const x of join3.exposure ?? [])
+    out.push(`Exposure: ${x.message}.`);
+  for (const g of join3.gaps.slice(0, 10))
+    out.push(`Field gap: ${g.message}.`);
+  return out;
+}
+async function renderRepoMap(root, repo, io) {
+  const records = (await readCatalog(join2(catalogDirOf(root), "generated"), { cacheRoot: root })).records;
+  const spec = await readRepoSpec(root, repo, { cacheRoot: root });
+  const ofRepo = records.some((r) => r.kind === "Component" && r.repo === repo);
+  if (!ofRepo && spec.flows.length === 0) {
+    io.err(`Nothing of ${repo} is in the catalog yet. Have your assistant read it (/atticus map), then run atticus verify ${repo} --write.`);
+    return void 0;
+  }
+  let trust;
+  const report = join2(factsDirOf(root), `${repo}.verify.yaml`);
+  if (existsSync(report)) {
+    try {
+      trust = trustOf((0, import_yaml.parse)(await readFile(report, "utf8")));
+    } catch {
+      trust = void 0;
+    }
+  }
+  const open = (await listQuestions(root, { state: "open", repo })).questions;
+  const manifest = (await loadRepos(root).catch(() => [])).find((r) => r.id === repo);
+  const adopted = isAdopted(root);
+  const url = manifest?.url && !isInPlace(manifest.url) ? manifest.url : void 0;
+  const codeLink = codeLinkerFor(url ? { url } : { dir: adopted ? "" : posix(relative(root, baseClonePath(root, repo))) });
+  const rel = `${mapRelOf(root)}/${repo}`;
+  const kept = await factsOf(root, repo);
+  const files = renderMap({
+    repo,
+    records,
+    flows: spec.flows,
+    ...trust ? { trust } : {},
+    // What a person says the repo is (ADR 0128), above the trust line.
+    ...manifest?.description ? {
+      about: {
+        text: manifest.description.text,
+        trust: manifest.description.trust,
+        ...manifest.description.by ? { by: manifest.description.by } : {}
+      }
+    } : {},
+    // What the repo is built on (ADR 0124 addendum A-framework): read from the facts, since no
+    // catalog record holds a framework.
+    ...builtOnOf(kept),
+    // ADR 0163: the organisation's terms it writes, read from the facts as the frameworks are.
+    ...termsOfFacts(kept),
+    questions: open.map((q) => ({ id: q.id, question: q.question, evidence: q.evidence })),
+    paths: { map: rel, questions: questionsRelOf(root), specs: specRelOf(root, repo) },
+    codeLink
+  });
+  const dir = join2(mapDirOf(root), repo);
+  for (const old of await listFiles(dir))
+    if (!(old in files))
+      await rm(join2(dir, ...old.split("/")), { force: true });
+  for (const [path, text] of Object.entries(files)) {
+    const full = join2(dir, ...path.split("/"));
+    const now = await readFile(full, "utf8").catch(() => void 0);
+    if (now !== text)
+      await writeFileAtomic(full, text);
+  }
+  const paths = Object.keys(files).map((p) => `${rel}/${p}`);
+  io.out(`Map: ${rel}/map.md (${Object.keys(files).length} files; review them in the PR).`);
+  return paths;
+}
+async function factsOf(root, repo) {
+  const text = await readFile(join2(factsDirOf(root), `${repo}.jsonl`), "utf8").catch(() => void 0);
+  if (text === void 0)
+    return [];
+  const p = parseFacts(text);
+  return p.ok ? p.facts : [];
+}
+function builtOnOf(facts) {
+  const built = frameworkFacts(facts).map((f) => ({
+    name: f.name,
+    ...f.version ? { version: f.version } : {},
+    ...f.component ? { component: f.component } : {},
+    cite: { path: f.cite.file, line: f.cite.line, commit: f.commit }
+  }));
+  if (!built.length)
+    return {};
+  const gaps = frameworkGaps(facts).map((g) => ({ framework: g.framework, question: g.question }));
+  return { frameworks: { built, ...gaps.length ? { gaps } : {} } };
+}
+function termsOfFacts(facts) {
+  const terms = facts.flatMap((f) => f.kind === "term" ? [
+    {
+      term: f.term,
+      value: f.value,
+      role: f.role,
+      cite: { path: f.cite.file, line: f.cite.line, commit: f.commit },
+      ...f.meaning ? { meaning: { path: f.meaning.file, line: f.meaning.line, commit: f.commit } } : {}
+    }
+  ] : []);
+  return terms.length ? { terms } : {};
+}
+async function listFiles(dir) {
+  const out = [];
+  const walk = async (d, prefix) => {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries)
+      if (e.isDirectory())
+        await walk(join2(d, e.name), `${prefix}${e.name}/`);
+      else
+        out.push(`${prefix}${e.name}`);
+  };
+  await walk(dir, "");
+  return out.sort();
+}
+async function mapRenderCommand(root, repo, o, io) {
+  const quiet = o.json ? { ...io, out: () => void 0 } : io;
+  const written = await renderRepoMap(root, repo, quiet);
+  if (!written)
+    return 2;
+  if (o.json)
+    io.out(JSON.stringify({ repo, files: written }, null, 2));
+  return 0;
+}
+export {
+  builtOnOf,
+  countByKind,
+  joinLines,
+  kindLine,
+  linkChanges,
+  linkLines,
+  mapRenderCommand,
+  projectFactsIntoCatalog,
+  sharedLines,
+  sharedReport,
+  termsOfFacts,
+  writeFactsIntoCatalog
+};