@documentation-robotics/cli 0.3.0 → 0.4.0

package/dist/mcp/tools/codebase-extract.js

@@ -0,0 +1,836 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { strictItem } from "../strict-schema.js";
+import { codeChangesSince, inDirs, scopeChanges } from "../../analyzers/code-changes.js";
+import { SOURCE_EXT, VENDOR_EXCLUDE } from "../../analyzers/cards/build.js";
+import { ExtractionTimeoutError } from "../../analyzers/cards/extract.js";
+import { attributeChangedLines, decisionKey, needsAttributesCard, planElements, planRelationships, sortUndecided, sourceSymbolOf } from "../../analyzers/extraction-plan.js";
+import { Changeset } from "../../core/changeset.js";
+import { ChangesetGraph } from "../../core/changeset-graph.js";
+import { Element } from "../../core/element.js";
+import { Layer } from "../../core/layer.js";
+import { setStagedSourceReference, stagedSourceReference } from "../../core/staged-source-reference.js";
+import { StagingAreaManager } from "../../core/staging-area.js";
+import { getAllLayerIds, isValidLayer } from "../../generated/layer-registry.js";
+import { getValidRelationships } from "../../generated/relationship-index.js";
+import { generateUUID } from "../../utils/id-generator.js";
+import { CLIError, ErrorCategory, formatValidOptions } from "../../utils/errors.js";
+import { FileLock } from "../../utils/file-lock.js";
+import { SchemaValidator } from "../../validators/schema-validator.js";
+import { compactJson, jsonResult, loadModel, reloadModel, rootPathSchema, runTool } from "./shared.js";
+import { changesetUnstageHandler } from "./changeset-editing.js";
+import { analyzerNotFoundError, canonicalRoots, defaultCodebaseToolDeps, describeIndex, requireFreshIndex } from "./codebase-shared.js";
+const DEFAULT_PAGE_SIZE = 25, MAX_PAGE_SIZE = 50, RESPONSE_BUDGET_BYTES = 28 * 1024, MAX_LISTED = 100, inputSchema = {
+  changeset: z.string().min(1).optional().describe("Name (or id) of the as-built changeset to stage into. Created when absent, reused when it is staged. Default: extract-<short git HEAD>, or extract-<since base>..<HEAD> with since."),
+  since: z.string().min(1).optional().describe("A git ref (branch, tag or commit). Extract only the files changed since its merge base with HEAD, plus uncommitted ones. To verify a branch's build, pass the branch it started from."),
+  layers: z.array(z.string()).optional().describe("Only these layers (canonical names). Default: every layer."),
+  pageSize: z.number().int().min(1).max(200).optional().describe(`Undecided cards per page (default ${DEFAULT_PAGE_SIZE}, at most ${MAX_PAGE_SIZE}). A page that would make the response larger than about ${RESPONSE_BUDGET_BYTES / 1024} KB has its cards shortened, and says so.`),
+  page: z.number().int().min(1).optional().describe("Page of undecided cards (default 1). Page 2 and later read the last run's cards, with its since and layers: nothing is extracted or staged."),
+  reject: z.array(strictItem("A reject[] item", {
+    card: z.string().min(1).describe("The card's cardId, its symbol (or file#symbol), or the id of an element this extraction staged."),
+    reason: z.string().min(1).describe("Why it is not a model element, in a few words.")
+  })).optional().describe("Code that is not a model element: a card of this extraction (cardId, or a symbol only one card has), a symbol it staged (Tier 0 decided it), or the id of an element staged from it. Recorded for the project until cleared, so later runs leave them out; an element still staged in the changeset for it is unstaged, with its relationships. A call with only reject or clearRejected records and runs nothing."),
+  clearRejected: z.union([z.literal(!0), z.array(z.string().min(1))]).optional().describe("Forget not-an-element decisions: true for all, or a list of symbols (or file#symbol) as notElements lists them."),
+  rootPath: rootPathSchema
+};
+function stagedAs(name, attributes) {
+  return { ...name ? { name } : {}, ...attributes && Object.keys(attributes).length ? { attributes: structuredClone(attributes) } : {} };
+}
+const DESCRIPTIONS_FILE = "descriptions.json", DECISIONS_FILE = "decisions.json", PENDING_FILE = "pending.json", KEEP_FILES = /* @__PURE__ */ new Set([DESCRIPTIONS_FILE, DECISIONS_FILE, PENDING_FILE]);
+function extractDir(projectRoot) {
+  return path.join(projectRoot, ".dr", "analyzers", "extract");
+}
+function cardsPath(projectRoot, changesetId) {
+  return path.join(extractDir(projectRoot), `${changesetId.replace(/[^\w.-]/g, "_")}.json`);
+}
+async function isExtractionChangeset(projectRoot, changesetId, changesetName) {
+  const stored = await readJson(cardsPath(projectRoot, changesetId));
+  if (stored && !stored.pending && stored.changesetId === changesetId)
+    return !0;
+  if (!changesetName)
+    return !1;
+  const pending = await readJson(path.join(extractDir(projectRoot), PENDING_FILE));
+  return !!pending?.pending && pending.changesetName === changesetName;
+}
+function hasTriple(id) {
+  const parts = id.split(".");
+  return parts.length !== 5 ? !1 : getValidRelationships(`${parts[0]}.${parts[1]}`, parts[2], `${parts[3]}.${parts[4]}`).length > 0;
+}
+function emptyChangeset() {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return new Changeset({ id: "extract-preview", name: "extract", created: now, modified: now, status: "staged", baseSnapshot: "", changes: [] });
+}
+function page(items, pageNumber, pageSize) {
+  const pages = Math.ceil(items.length / pageSize);
+  return {
+    total: items.length,
+    page: pageNumber,
+    pageSize,
+    pages,
+    items: items.slice((pageNumber - 1) * pageSize, pageNumber * pageSize)
+  };
+}
+function capped(items, limit = MAX_LISTED) {
+  return items.length > limit ? { total: items.length, items: items.slice(0, limit), truncated: !0 } : { total: items.length, items };
+}
+const GENERIC_REASON = /* @__PURE__ */ new Set(["no-rule", "narrowed"]);
+function clip(text, max) {
+  return text && (text.length > max ? `${text.slice(0, max - 3)}...` : text);
+}
+function cardAt(card, detail) {
+  if (detail === "full")
+    return card;
+  const { reason, docstring, signature, decorators, candidates, qualifiedName, ...rest } = card, open = candidates.length ? { candidates } : {};
+  return detail === "shortened" ? {
+    ...rest,
+    qualifiedName,
+    ...open,
+    ...signature ? { signature: clip(signature, 80) } : {},
+    ...docstring ? { docstring: clip(docstring, 120) } : {},
+    ...decorators ? { decorators } : {},
+    ...GENERIC_REASON.has(card.kind) ? {} : { reason }
+  } : { ...rest, ...open, ...card.kind === "ambiguous" || card.kind === "needs-attributes" ? { reason: clip(reason, 200) } : {} };
+}
+const PAGE_NOTES = {
+  shortened: "Docstrings and signatures are shortened, and empty candidates and reasons that only name the card's kind left out, to keep this response small.",
+  compact: "Docstrings, signatures, decorators, qualified names, empty candidates and most reasons are left out, to keep this response small."
+}, LIST_LIMITS = [MAX_LISTED, 20, 5, 0];
+function cutInstruction(p, shown) {
+  const next = (p.page - 1) * p.pageSize + shown;
+  return `call codebase_extract with page: ${Math.floor(next / shown) + 1} and pageSize: ${shown}${next % shown ? " (its first cards may repeat ones you have)" : ""}`;
+}
+function fitCards(cards, p, render) {
+  const fits = (result2) => Buffer.byteLength(compactJson(result2), "utf-8") <= RESPONSE_BUDGET_BYTES;
+  let lists = {}, listsFit = !1;
+  for (const limit of LIST_LIMITS)
+    if (lists = limit < MAX_LISTED ? { listLimit: limit } : {}, fits(render([], lists))) {
+      listsFit = !0;
+      break;
+    }
+  const compact = cards.map((c) => cardAt(c, "compact")), smallest = () => render(compact.slice(0, 1), {
+    ...lists,
+    ...cards.length ? { detail: "compact", note: PAGE_NOTES.compact } : {},
+    ...cards.length > 1 ? { shown: 1, readOn: cutInstruction(p, 1) } : {},
+    overBudget: !0
+  });
+  if (!listsFit)
+    return smallest();
+  let result = render(cards, lists);
+  if (fits(result))
+    return result;
+  for (const detail of ["shortened", "compact"])
+    if (result = render(cards.map((c) => cardAt(c, detail)), { ...lists, detail, note: PAGE_NOTES[detail] }), fits(result))
+      return result;
+  for (let shown = compact.length - 1; shown >= 1; shown--)
+    if (result = render(compact.slice(0, shown), { ...lists, detail: "compact", note: PAGE_NOTES.compact, shown, readOn: cutInstruction(p, shown) }), fits(result))
+      return result;
+  return smallest();
+}
+function fitNotes(fit) {
+  return {
+    ...fit.listLimit !== void 0 ? {
+      listsShortened: `candidateDeletes, staged.updated, retyped and notElements.recorded list at most ${fit.listLimit} item(s) here, to keep the response small; each total is the full count. Narrow the run with layers or since to list the rest.`
+    } : {},
+    ...fit.overBudget ? { overBudget: `Even shortened, this response is over about ${RESPONSE_BUDGET_BYTES / 1024} KB.` } : {}
+  };
+}
+function undecidedSection(p, items, fit, requestedPageSize, extra = {}) {
+  return {
+    ...p,
+    items,
+    ...extra,
+    ...requestedPageSize > p.pageSize ? { pageSizeCapped: `pageSize ${requestedPageSize} was capped at ${p.pageSize}; use page: 2 and on for more.` } : {},
+    ...fit.detail ? { detail: fit.detail, detailNote: `${fit.note} A smaller pageSize gives full cards.` } : {},
+    ...fit.shown !== void 0 ? { cut: `This page was cut to its first ${fit.shown} of ${p.items.length} cards to keep the response small. For the rest, ${fit.readOn}.` } : {}
+  };
+}
+function elementOfAdd(add, now) {
+  const element = new Element({
+    id: generateUUID(),
+    path: add.id,
+    spec_node_id: `${add.layer}.${add.type}`,
+    layer_id: add.layer,
+    type: add.type,
+    name: add.name,
+    description: add.description,
+    attributes: add.attributes,
+    metadata: { created_at: now, updated_at: now, version: 1 },
+    layer: add.layer
+  });
+  return add.sourceReference && element.setSourceReference(add.sourceReference), element;
+}
+async function validateAdds(adds, project, now, hunks) {
+  const valid = [], invalid = [], validator = new SchemaValidator(), byLayer2 = /* @__PURE__ */ new Map();
+  for (const add of adds)
+    (byLayer2.get(add.layer) ?? byLayer2.set(add.layer, []).get(add.layer)).push({ add, element: elementOfAdd(add, now) });
+  for (const [layerName, items] of byLayer2) {
+    const layer = new Layer(layerName);
+    for (const item of items)
+      layer.addElement(item.element);
+    const result = await validator.validateLayer(layer), errors = /* @__PURE__ */ new Map();
+    for (const e of result.errors)
+      e.elementId && (errors.get(e.elementId) ?? errors.set(e.elementId, []).get(e.elementId)).push(e.message);
+    for (const item of items) {
+      const errs = errors.get(item.add.id);
+      errs?.length ? invalid.push(needsAttributesCard(item.add, project, errs, hunks)) : valid.push(item);
+    }
+  }
+  return { valid, invalid };
+}
+async function currentSnapshot(model, graph, changeset, id, layer) {
+  const element = graph.getElement(id);
+  if (element && element.status !== "unchanged") {
+    const changes = changeset.changes.filter((c) => (c.type === "add" || c.type === "update") && c.after && graph.resolve(c.elementId) === id), last = changes[changes.length - 1];
+    if (last?.after)
+      return { snapshot: structuredClone(last.after), stagedAdd: element.status === "added" ? changes.find((c) => c.type === "add") : void 0 };
+  }
+  const base = (await model.getBaseLayer(layer))?.getElement(id);
+  return base ? { snapshot: structuredClone(base.toJSON()), stagedAdd: void 0 } : null;
+}
+function patched(snapshot, update, now) {
+  const after = structuredClone(snapshot);
+  for (const [field, value] of Object.entries(update.fields))
+    field === "source_reference" ? setStagedSourceReference(after, value) : field.startsWith("attributes.") ? after.attributes = { ...after.attributes ?? {}, [field.slice(11)]: value } : after[field] = value;
+  const metadata = after.metadata;
+  return metadata && (after.metadata = { ...metadata, updated_at: now }), after;
+}
+function relationshipChange(r) {
+  return {
+    type: "relationship-add",
+    elementId: `${r.source}::${r.predicate}::${r.target}`,
+    layerName: r.sourceLayer,
+    after: {
+      source: r.source,
+      target: r.target,
+      predicate: r.predicate,
+      layer: r.sourceLayer,
+      ...r.targetLayer !== r.sourceLayer ? { targetLayer: r.targetLayer } : {},
+      category: "structural"
+    }
+  };
+}
+function byLayer(adds, updates, relationships) {
+  const out = {}, at = (layer) => out[layer] ??= { adds: 0, updates: 0, relationships: 0 };
+  for (const a of adds)
+    at(a.layer).adds++;
+  for (const u of updates)
+    at(u.layer).updates++;
+  for (const r of relationships)
+    at(r.sourceLayer).relationships++;
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
+}
+function notElementsResult(decisions, skipped, recorded, cleared, listLimit = MAX_LISTED) {
+  const total = Object.keys(decisions.notElements).length;
+  return !total && !skipped && !recorded.length && !cleared ? {} : {
+    notElements: {
+      total,
+      skipped,
+      ...recorded.length ? { recorded: capped(recorded, listLimit) } : {},
+      ...cleared ? { cleared } : {},
+      note: "Symbols decided not to be elements (rejected, or unstaged after this tool staged them). Runs leave them out; clearRejected forgets them."
+    }
+  };
+}
+function verifyCardStep(undecidedPages, readOn) {
+  return `Stage the element cards with model_add, named after the card's symbol (the card's name when it has one), never the plan's element, and never copy plan elements here: a layer and type from its candidates or hint, sourceFile = file, sourceSymbol = symbol, sourceProvenance: "extracted". Ask the user about cards you can't place, in one short list. ${readFurther(undecidedPages, readOn)}`;
+}
+function verifyLandStep(plan, why = "") {
+  return `After verify, the plan '${plan.name}' lands (changeset_commit when the user asks), not this changeset: discard this one or keep it as a record. Landing it first drifts the plan's base, so the plan would need force. Call changeset_activate with "${plan.id}" to resume the plan${why}.`;
+}
+function verifyNothingSteps(plan, since) {
+  return [
+    `Nothing in the range since ${since} is observable to extraction or differs from the model, so no as-built changeset was created: there is none to verify against. '${plan.name}' is still active.`,
+    `Call changeset_verify with planned: "${plan.id}" and against: {base: true, extracted: true}: it compares the plan with the model, and what extraction can't see is unverifiable rather than missing.`
+  ];
+}
+function readFurther(undecidedPages, readOn) {
+  return readOn ? `This page was cut to keep the response small: for the cards after it, ${readOn}, and page on with that pageSize.` : `Read further pages with page: 2 and on (${undecidedPages} in all).`;
+}
+function nextSteps(changeset, previous, undecidedPages, plan, changedCards = 0, since, readOn) {
+  const steps = [
+    `The as-built changeset '${changeset.name}' is active: model_add, model_update, model_delete and relationship_add stage into it. Nothing reaches the base model until the user lands it.`
+  ];
+  changedCards > 0 && steps.push(`${changedCards} card(s) have changedInRange: their lines are new or changed in the range, so they come first. The rest are symbols in the same files that the range didn't touch.`);
+  const verify = !!since && !!previous, rerun = `codebase_extract again with changeset: "${changeset.name}"${since ? `, since: "${since}"` : ""}`;
+  return undecidedPages > 0 && steps.push(verify ? verifyCardStep(undecidedPages, readOn) : `Decide the undecided cards: for each one that is a model element, call model_add with a layer and type from its candidates (or its hint; spec_type says what a type needs), a name (the card's name when it has one), sourceFile = file, sourceSymbol = symbol and sourceProvenance: "extracted". ` + readFurther(undecidedPages, readOn), "For cards that are not elements, call codebase_extract with reject: [{card: cardId, reason}] so later runs leave them out.", verify ? `Call ${rerun} for their relationships.` : `Then call ${rerun} (it keeps that run's since and layers). It finds your elements by their source reference and stages the relationships the edge mapping gives them.`), plan.candidateDeletes.length && steps.push("Check candidateDeletes: call model_delete only for elements whose code is really gone (replacedBy names the element staged for a renamed file). reference-never-matched means the element's reference was wrong before the range: the range removed nothing, so fix or delete the element without blaming the range."), plan.retyped.length && steps.push("retyped lists elements whose type the rules now decide differently. Leave them unless the rule is right; changing a type means adding the new element and deleting the old."), verify ? (steps.push(`Then call changeset_verify with planned: "${previous.id}" and against: {changesetId: "${changeset.id}"}.`, verifyLandStep(previous)), steps) : (steps.push("Call changeset_brief to see what the changeset covers and its gaps, then review_open and give the user the link."), previous ? steps.push(`'${previous.name}' was active before this call. To check it against this build, call changeset_verify with planned: "${previous.id}" and against: {changesetId: "${changeset.id}"}. Call changeset_activate with "${previous.id}" to resume it.`) : steps.push("The user lands the changeset with changeset_commit (they confirm in a dialog) or in the viewer."), steps);
+}
+function pendingSteps(name, active, undecidedPages, plan, changedCards, since, readOn) {
+  const verify = !!since && !!active, steps = [
+    verify ? `Nothing was staged, so no as-built changeset was created and '${active.name}' is still active. Before you stage a card or delete a candidate, call changeset_create with name: "${name}" (it becomes active, so model_add and model_delete stage into it and not into the plan).` : `Nothing was staged, so no changeset was created or activated. Before you model a card or delete a candidate, call changeset_create with name: "${name}" (it becomes active, and model_add and model_delete stage into it); without it they would ${active ? `stage into '${active.name}'` : "write the base model"}.`
+  ];
+  return changedCards > 0 && steps.push(`${changedCards} card(s) have changedInRange: their lines are new or changed in the range, so they come first. The rest are symbols in the same files that the range didn't touch.`), undecidedPages > 0 && steps.push(verify ? verifyCardStep(undecidedPages, readOn) : `For each card that is a model element, call model_add (into that changeset) with a layer and type from its candidates (or its hint), a name (the card's name when it has one), sourceFile = file, sourceSymbol = symbol and sourceProvenance: "extracted". ${readFurther(undecidedPages, readOn)}`, "For cards that are not elements, call codebase_extract with reject: [{card: cardId, reason}] so later runs leave them out; that needs no changeset.", verify ? `Call codebase_extract again with changeset: "${name}", since: "${since}" for their relationships.` : `After adding elements, call codebase_extract with changeset: "${name}"${since ? `, since: "${since}"` : ""}: it keeps this run's since and layers, and stages the relationships the edge mapping gives them.`), plan.candidateDeletes.length && steps.push("Check candidateDeletes: call model_delete (into that changeset) only for elements whose code is really gone. reference-never-matched means the element's reference was wrong before the range: the range removed nothing."), verify ? (steps.push(`Then call changeset_verify with planned: "${active.id}" and against: {changesetId: "${name}"}.`, verifyLandStep(active, " (changeset_create deactivated it)"), `If no card is an element and nothing is deleted, there is no as-built changeset to verify against: call changeset_verify with planned: "${active.id}" and against: {base: true, extracted: true} instead.`), steps) : (steps.push("If none of these need modelling now, there is nothing to land and nothing to clean up."), steps);
+}
+const DEFAULT_BUDGET_MS = 1e5, NARROW = "Narrow the run with layers, or with since (a git ref), and call codebase_extract again";
+function sameLayers(a, b) {
+  return JSON.stringify([...a ?? []].sort()) === JSON.stringify([...b ?? []].sort());
+}
+async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+async function pruneCardFiles(projectRoot, manager) {
+  const dir = extractDir(projectRoot);
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  const staged = new Set((await manager.list()).filter((c) => c.status === "staged").map((c) => c.id));
+  for (const entry of entries) {
+    if (!entry.endsWith(".json") || KEEP_FILES.has(entry))
+      continue;
+    const stored = await readJson(path.join(dir, entry));
+    (!stored || !staged.has(stored.changesetId)) && await rm(path.join(dir, entry), { force: !0 });
+  }
+}
+async function runsAt(projectRoot, manager, head) {
+  let entries;
+  try {
+    entries = await readdir(extractDir(projectRoot));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json") || KEEP_FILES.has(entry))
+      continue;
+    const stored = await readJson(path.join(extractDir(projectRoot), entry));
+    if (!stored || stored.pending || stored.gitHead !== head || !stored.changesetId)
+      continue;
+    const changeset = await manager.load(stored.changesetId);
+    changeset?.status === "staged" && out.push(changeset);
+  }
+  return out;
+}
+async function readDecisions(projectRoot) {
+  const stored = await readJson(path.join(extractDir(projectRoot), DECISIONS_FILE));
+  return { version: 1, notElements: stored?.notElements && typeof stored.notElements == "object" ? stored.notElements : {} };
+}
+async function writeDecisions(projectRoot, decisions) {
+  await mkdir(extractDir(projectRoot), { recursive: !0 }), await writeFile(path.join(extractDir(projectRoot), DECISIONS_FILE), JSON.stringify(decisions, null, 2), "utf-8");
+}
+function normFile(file) {
+  return file ? file.replace(/\\/g, "/").replace(/^\.\//, "") : null;
+}
+function changesetRejectables(changeset, graph) {
+  const out = [];
+  for (const e of graph?.elements.values() ?? [])
+    if (!(e.status !== "added" || e.sourceReference?.provenance !== "extracted"))
+      for (const l of e.sourceReference.locations ?? [])
+        l.symbol && out.push({ file: normFile(l.file), symbol: l.symbol, elementId: e.id });
+  for (const t of changeset?.unstaged ?? []) {
+    if (t.rewritten || t.change.type !== "add")
+      continue;
+    const ref = stagedSourceReference(t.change.after);
+    if (ref?.provenance === "extracted")
+      for (const l of ref.locations ?? [])
+        l.symbol && out.push({ file: normFile(l.file), symbol: l.symbol, elementId: t.change.elementId });
+  }
+  return out;
+}
+function cardsToReject(stored, fromChangeset, changesetName, refs) {
+  const known = [
+    ...(stored?.cards ?? []).map((c) => ({ file: c.file, symbol: c.symbol, label: c.label, cardId: c.cardId, qualifiedName: c.qualifiedName })),
+    ...(stored?.earlierCards ?? []).map((c) => ({ file: c.file, symbol: c.symbol, label: c.label, cardId: c.cardId, qualifiedName: c.qualifiedName })),
+    ...(stored?.staged ?? []).map((s) => ({ file: s.file, symbol: s.symbol, label: s.label, elementId: s.id })),
+    ...fromChangeset
+  ];
+  if (!known.length)
+    throw new CLIError(`No cards recorded for '${changesetName}' to reject from`, ErrorCategory.USER, [
+      "Call codebase_extract first, then pass the cardId (or symbol) of each card that is not an element"
+    ]);
+  const found = [], unknown = [], ambiguous = [], distinctSymbols = (matches) => {
+    const bySymbol = /* @__PURE__ */ new Map();
+    for (const m of matches) {
+      const key = decisionKey(m.file, m.symbol), seen = bySymbol.get(key);
+      (!seen || !seen.label && m.label) && bySymbol.set(key, m);
+    }
+    return [...bySymbol.values()];
+  };
+  for (const ref of refs) {
+    const ofElement = known.filter((k) => k.elementId === ref.card);
+    if (ofElement.length) {
+      for (const d of distinctSymbols(ofElement))
+        found.push({ file: d.file, symbol: d.symbol, label: d.label, reason: ref.reason });
+      continue;
+    }
+    const byCard = known.filter((k) => k.cardId === ref.card), matches = byCard.length ? byCard : known.filter((k) => k.symbol === ref.card || `${k.file ?? ""}#${k.symbol}` === ref.card || k.qualifiedName === ref.card), distinct = distinctSymbols(matches);
+    distinct.length === 1 ? found.push({ file: distinct[0].file, symbol: distinct[0].symbol, label: distinct[0].label, reason: ref.reason }) : distinct.length > 1 ? ambiguous.push(`${ref.card} (${distinct.map((d) => d.cardId ?? `${d.file ?? ""}#${d.symbol}`).join(", ")})`) : unknown.push(ref.card);
+  }
+  if (unknown.length || ambiguous.length) {
+    const parts = [
+      ...unknown.length ? [`not among the cards or staged symbols of '${changesetName}': ${unknown.join(", ")}`] : [],
+      ...ambiguous.length ? [`names more than one card: ${ambiguous.join("; ")}`] : []
+    ];
+    throw new CLIError(`Can't reject: ${parts.join("; ")}. Nothing was recorded`, ErrorCategory.USER, [
+      "Pass the cardId (or file#symbol) of a card, or the id of an element this extraction staged"
+    ]);
+  }
+  return found;
+}
+function clearDecisions(decisions, which) {
+  let n = 0;
+  for (const [key, d] of Object.entries(decisions.notElements))
+    (which === !0 || which.some((w) => w === key || w === d.symbol || w === `${d.file ?? ""}#${d.symbol}`)) && (delete decisions.notElements[key], n++);
+  return n;
+}
+function createCodebaseExtractHandler(deps = defaultCodebaseToolDeps) {
+  return async function(args, context) {
+    return runTool(async () => {
+      const startedAt = Date.now(), deadline = startedAt + (deps.budgetMs ?? DEFAULT_BUDGET_MS), model = await loadModel(args.rootPath), { projectRoot, codebaseRoot } = await canonicalRoots(model), argLayers = args.layers?.length ? [...new Set(args.layers)] : void 0, unknownLayers = (argLayers ?? []).filter((l) => !isValidLayer(l));
+      if (unknownLayers.length)
+        throw new CLIError(`Unknown layer${unknownLayers.length > 1 ? "s" : ""}: ${unknownLayers.join(", ")}`, ErrorCategory.USER, [
+          `Use canonical layer names: ${formatValidOptions(getAllLayerIds())}`
+        ]);
+      const { analyzer, freshness, index: indexJudgement } = await requireFreshIndex(projectRoot, codebaseRoot, deps, "codebase_extract", {
+        uncommittedEdits: !0
+      }), head = freshness.currentGitHead, manager = new StagingAreaManager(model.rootPath, model), pageSize = args.pageSize ?? DEFAULT_PAGE_SIZE, effectivePageSize = Math.min(pageSize, MAX_PAGE_SIZE), baseModified = model.manifest.modified, paging = (args.page ?? 1) > 1, decisionsOnly = !paging && (!!args.reject?.length || args.clearRejected !== void 0);
+      let name = args.changeset ?? "", changeset = args.changeset ? await manager.load(args.changeset) : null;
+      if (!args.changeset && (paging || decisionsOnly)) {
+        const activeId = await manager.getActiveId(), active = activeId ? await manager.load(activeId) : null;
+        if (active?.status === "staged" && existsSync(cardsPath(projectRoot, active.id)))
+          changeset = active, name = active.name;
+        else {
+          const runs = await runsAt(projectRoot, manager, head);
+          if (runs.length === 1)
+            changeset = runs[0], name = runs[0].name;
+          else if (runs.length > 1)
+            throw new CLIError(`Several extraction changesets have runs at this commit (${runs.map((r) => `'${r.name}'`).sort().join(", ")}), and none is active`, ErrorCategory.USER, ["Pass changeset with the name of the one you mean"]);
+        }
+      }
+      const pendingRecord = await readJson(path.join(extractDir(projectRoot), PENDING_FILE)), pending = pendingRecord?.pending && pendingRecord.gitHead === head ? pendingRecord : null, stalePending = !!pendingRecord?.pending && pendingRecord.gitHead !== head, pendingFor = (n) => pending && n && pending.changesetName === n ? pending : null;
+      let stored = changeset ? await readJson(cardsPath(projectRoot, changeset.id)) : null;
+      if (stored ??= pendingFor(changeset?.name ?? args.changeset), !args.changeset && (paging || decisionsOnly) && pending && (!changeset || !stored || stored.createdAt < pending.createdAt)) {
+        const named = await manager.load(pending.changesetName);
+        changeset = named?.status === "staged" ? named : null, name = pending.changesetName, stored = pending;
+      }
+      let since = args.since, layers = argLayers;
+      if (stored && (changeset ? changeset.status === "staged" : stored.pending) && !decisionsOnly) {
+        const conflicts = [];
+        if (args.since !== void 0 && args.since !== (stored.since ?? void 0) && conflicts.push(`since: ${args.since} (its run had since: ${stored.since ?? "none"})`), argLayers && !sameLayers(stored.layers, argLayers) && conflicts.push(`layers: ${argLayers.join(", ")} (its run had layers: ${stored.layers?.join(", ") ?? "all"})`), conflicts.length)
+          throw new CLIError(`'${stored.changesetName}' holds another run's extraction: this call names ${conflicts.join(" and ")}`, ErrorCategory.USER, [
+            "Leave since and layers out to use that run's",
+            "Or pass another changeset name for a run with these arguments"
+          ]);
+        since = stored.since ?? void 0, layers = stored.layers ?? void 0;
+      }
+      let changes = null;
+      if (since && (!(paging || decisionsOnly) || !changeset && !stored) && (changes = await (deps.codeChanges ?? codeChangesSince)(codebaseRoot, since)), !changeset && !args.changeset && !stored?.pending) {
+        const defaultName = changes ? changes.base === head ? `extract-${head.slice(0, 7)}+worktree` : `extract-${changes.base.slice(0, 7)}..${head.slice(0, 7)}` : `extract-${head.slice(0, 7)}`;
+        name = defaultName, changeset = await manager.load(name);
+        for (let n = 2; changeset && changeset.status !== "staged"; n++)
+          name = `${defaultName}-${n}`, changeset = await manager.load(name);
+        stored = (changeset ? await readJson(cardsPath(projectRoot, changeset.id)) : null) ?? pendingFor(name);
+      }
+      if (changeset && changeset.status !== "staged")
+        throw new CLIError(`Changeset '${changeset.name}' is ${changeset.status} and can't take the extraction`, ErrorCategory.USER, [
+          "Pass another name in changeset"
+        ]);
+      const backend = paging || decisionsOnly ? null : await deps.getAnalyzer(analyzer);
+      if (!paging && !decisionsOnly) {
+        if (!backend)
+          throw analyzerNotFoundError(analyzer);
+        if (!backend.extract)
+          throw new CLIError(`The ${analyzer} analyzer can't extract (it has no Tier-0 rules)`, ErrorCategory.USER);
+      }
+      await mkdir(extractDir(projectRoot), { recursive: !0 });
+      const lock = new FileLock(path.join(extractDir(projectRoot), "run"));
+      try {
+        await lock.acquire({ timeout: 2e3, staleLockThreshold: (deps.budgetMs ?? DEFAULT_BUDGET_MS) + 6e4 });
+      } catch {
+        throw new CLIError("Another codebase_extract run is in progress for this project", ErrorCategory.USER, [
+          "Wait for it to finish, then call codebase_extract again"
+        ]);
+      }
+      try {
+        if (stalePending) {
+          const again = await readJson(path.join(extractDir(projectRoot), PENDING_FILE));
+          again?.pending && again.gitHead !== head && await rm(path.join(extractDir(projectRoot), PENDING_FILE), { force: !0 });
+        }
+        const decisions = await readDecisions(projectRoot), stagedIds = new Set((await manager.list()).filter((c) => c.status === "staged").map((c) => c.id));
+        let pruned = !1;
+        for (const [key, d] of Object.entries(decisions.notElements))
+          d.how === "unstaged" && !(d.changesetId && stagedIds.has(d.changesetId)) && (delete decisions.notElements[key], pruned = !0);
+        const recordedNow = [];
+        let cleared = 0;
+        args.clearRejected && (cleared = clearDecisions(decisions, args.clearRejected));
+        const toUnstage = /* @__PURE__ */ new Map(), inBase = [], keptElements = [];
+        if (args.reject?.length) {
+          const now2 = (/* @__PURE__ */ new Date()).toISOString(), extractionChangeset = changeset && stored ? changeset : null, graph = extractionChangeset ? await ChangesetGraph.build(model, extractionChangeset) : null, rejected = cardsToReject(stored, changesetRejectables(extractionChangeset, graph), changeset?.name ?? stored?.changesetName ?? name, args.reject), rejectedKeys = /* @__PURE__ */ new Map();
+          for (const card of rejected) {
+            const key = decisionKey(card.file, card.symbol);
+            rejectedKeys.set(key, card.symbol), decisions.notElements[key] = {
+              file: card.file,
+              symbol: card.symbol,
+              ...card.label ? { label: card.label } : {},
+              reason: card.reason,
+              how: "rejected",
+              changeset: changeset?.name ?? stored?.changesetName ?? name,
+              ...changeset ? { changesetId: changeset.id } : {},
+              at: now2
+            }, recordedNow.push({ symbol: card.symbol, file: card.file, how: "rejected" });
+          }
+          const stagedByExtraction = /* @__PURE__ */ new Map();
+          for (const st of stored?.staged ?? []) {
+            const key = decisionKey(st.file, st.symbol);
+            rejectedKeys.has(key) && stagedByExtraction.set(st.id, key);
+          }
+          for (const e of graph?.elements.values() ?? []) {
+            if (e.status === "deleted")
+              continue;
+            const keys = new Set((e.sourceReference?.locations ?? []).filter((l) => l.symbol).map((l) => decisionKey(normFile(l.file), l.symbol))), hit = stagedByExtraction.get(e.id) ?? [...keys].find((k) => rejectedKeys.has(k));
+            if (!hit || !stagedByExtraction.has(e.id) && e.sourceReference?.provenance !== "extracted")
+              continue;
+            if (e.status !== "added" || e.alreadyInBase) {
+              inBase.push(e.id);
+              continue;
+            }
+            const others = [...keys].filter((k) => !rejectedKeys.has(k));
+            others.length ? keptElements.push({ id: e.id, alsoNames: others }) : toUnstage.set(e.id, rejectedKeys.get(hit));
+          }
+        }
+        (pruned || cleared || recordedNow.length) && await writeDecisions(projectRoot, decisions);
+        const notElementKeys = new Set(Object.keys(decisions.notElements)), unstaged = [], unstageFailed = [];
+        for (const [id, symbol] of toUnstage) {
+          const result = await changesetUnstageHandler({ elementId: id, changesetId: changeset.id, rootPath: args.rootPath }), body = JSON.parse(result.content[0].text);
+          result.isError ? unstageFailed.push({ id, error: body.error ?? body.message ?? "unstage failed" }) : body.unstaged?.length && unstaged.push({ id, symbol, changes: body.unstaged.length });
+        }
+        if (unstaged.length && stored && changeset) {
+          const gone = new Set(unstaged.map((u) => u.id)), { pending: wasPending, ...rest } = stored, updated = (stored.updated ?? []).filter((u) => !gone.has(u.id));
+          stored = {
+            ...rest,
+            changesetId: changeset.id,
+            changesetName: changeset.name,
+            staged: (stored.staged ?? []).filter((s) => !gone.has(s.id)),
+            ...updated.length ? { updated } : { updated: void 0 }
+          }, await writeFile(cardsPath(projectRoot, changeset.id), JSON.stringify(stored), "utf-8"), wasPending && await rm(path.join(extractDir(projectRoot), PENDING_FILE), { force: !0 });
+        }
+        unstaged.length && await reloadModel(args.rootPath);
+        const rejectResult = {
+          ...unstaged.length ? {
+            unstaged: {
+              items: unstaged,
+              note: `Rejected while staged: unstaged from '${changeset.name}', with the relationships staged for them (changes counts both).`
+            }
+          } : {},
+          ...unstageFailed.length ? { unstageFailed } : {},
+          ...inBase.length ? { inModel: { ids: [...new Set(inBase)], note: "Already in the base model: rejecting doesn't remove them. model_delete them if they should go." } } : {},
+          ...keptElements.length ? {
+            kept: {
+              items: keptElements,
+              note: "Still staged: each also names code that wasn't rejected (alsoNames). Unstage it with changeset_unstage, or drop the rejected location with model_update, if it should change."
+            }
+          } : {}
+        };
+        if (decisionsOnly) {
+          const rerunName = changeset?.name ?? stored?.changesetName, rerun = rerunName ? `changeset: "${rerunName}"` : "the arguments of the last run";
+          return jsonResult({
+            changeset: changeset ? { id: changeset.id, name: changeset.name } : null,
+            ...notElementsResult(decisions, 0, recordedNow, cleared),
+            ...rejectResult,
+            message: unstaged.length ? `Recorded, and unstaged ${unstaged.length} element(s) it had staged; nothing was extracted.` : "Recorded; nothing was extracted or staged.",
+            next: [`Call codebase_extract with ${rerun} to refresh the cards: it leaves out what is recorded, and says how many.`]
+          }, { compact: !0 });
+        }
+        if (paging) {
+          if (!stored)
+            throw new CLIError(changeset ? `No cards recorded for '${changeset.name}'` : `No extraction changeset '${name}' yet`, ErrorCategory.USER, ["Call codebase_extract without page first"]);
+          const runName = changeset?.name ?? stored.changesetName;
+          if (stored.gitHead !== head)
+            throw new CLIError(`The cards for '${runName}' were read at ${stored.gitHead.slice(0, 7)}; the code is now at ${head.slice(0, 7)}`, ErrorCategory.USER, [
+              "Call codebase_extract without page to extract again"
+            ]);
+          const graph = await ChangesetGraph.build(model, changeset ?? emptyChangeset()), modelledAt = /* @__PURE__ */ new Map();
+          for (const e of graph.elements.values())
+            if (e.status !== "deleted")
+              for (const l of e.sourceReference?.locations ?? [])
+                l.symbol && modelledAt.set(`${l.file}#${l.symbol}`, e.id);
+          const cards2 = stored.cards.filter((c) => !notElementKeys.has(decisionKey(c.file, c.symbol))).map((c) => {
+            const modelled = c.file ? modelledAt.get(`${c.file}#${c.symbol}`) : void 0;
+            return modelled ? { ...c, modelled } : c;
+          }), p = page(cards2, args.page, effectivePageSize);
+          return jsonResult(fitCards(p.items, p, (items, fit) => ({
+            changeset: changeset ? { id: changeset.id, name: changeset.name } : null,
+            ...changeset ? {} : { pending: `No changeset yet: the run that read these cards staged nothing. Call changeset_create with name: "${runName}" before staging.` },
+            ...fitNotes(fit),
+            scope: { since: stored.since, layers: stored.layers ?? "all" },
+            undecided: undecidedSection(p, items, fit, pageSize),
+            ...notElementsResult(decisions, stored.cards.length - cards2.length, recordedNow, cleared, fit.listLimit),
+            ...rejectResult,
+            ...stored.baseModified !== baseModified ? { warning: "The base model changed since these cards were read; call codebase_extract without page to refresh them." } : {},
+            ...fit.readOn ? { next: `This page was cut to keep the response small: for the cards after it, ${fit.readOn}.` } : args.page < p.pages ? { next: `Call codebase_extract with page: ${args.page + 1} for the next cards.` } : {}
+          })), { compact: !0 });
+        }
+        const edited = indexJudgement.editedSince, before = await ChangesetGraph.build(model, changeset ?? emptyChangeset()), referenced = /* @__PURE__ */ new Set(), liveKeys = /* @__PURE__ */ new Set(), liveIds = /* @__PURE__ */ new Set(), addedAt = /* @__PURE__ */ new Map();
+        for (const e of before.elements.values())
+          if (e.status !== "deleted") {
+            liveIds.add(e.id);
+            for (const l of e.sourceReference?.locations ?? []) {
+              const file = l.file?.replace(/\\/g, "/").replace(/^\.\//, "");
+              if (file && referenced.add(file), !l.symbol)
+                continue;
+              const key = decisionKey(file || null, l.symbol);
+              liveKeys.add(key), e.status === "added" && !e.alreadyInBase && !addedAt.has(key) && addedAt.set(key, e.id);
+            }
+          }
+        const storedBefore = stored, unstagedAdds = new Set((changeset?.unstaged ?? []).filter((t) => !t.rewritten && t.change.type === "add").map((t) => t.change.elementId)), stillStaged = [];
+        for (const st of storedBefore?.staged ?? []) {
+          const key = decisionKey(st.file, st.symbol);
+          liveIds.has(st.id) || liveKeys.has(key) ? stillStaged.push(st) : unstagedAdds.has(st.id) && !decisions.notElements[key] && (decisions.notElements[key] = {
+            file: st.file,
+            symbol: st.symbol,
+            label: st.label,
+            reason: `${st.id} was staged by codebase_extract and then unstaged`,
+            how: "unstaged",
+            changeset: changeset.name,
+            changesetId: changeset.id,
+            at: (/* @__PURE__ */ new Date()).toISOString()
+          }, notElementKeys.add(key), recordedNow.push({ symbol: st.symbol, file: st.file, how: "unstaged" }));
+        }
+        const recorded = new Set(stillStaged.map((st) => `${st.id} ${decisionKey(st.file, st.symbol)}`));
+        for (const c of [...storedBefore?.cards ?? [], ...storedBefore?.earlierCards ?? []]) {
+          const key = decisionKey(c.file, c.symbol), id = addedAt.get(key);
+          if (!id || recorded.has(`${id} ${key}`))
+            continue;
+          recorded.add(`${id} ${key}`);
+          const element = before.getElement(id);
+          stillStaged.push({ id, file: c.file, symbol: c.symbol, label: c.label, ...stagedAs(element?.name, element?.attributes) });
+        }
+        if (recordedNow.some((r) => r.how === "unstaged") && await writeDecisions(projectRoot, decisions), changes) {
+          const drDirs = [path.join(projectRoot, "documentation-robotics"), path.join(projectRoot, ".dr")].map((d) => path.relative(codebaseRoot, d).split(path.sep).join("/")).filter((d) => d && !d.startsWith(".."));
+          changes = scopeChanges(changes, (f) => !inDirs(f, drDirs) && (SOURCE_EXT.test(f) && !VENDOR_EXCLUDE.test(f) || referenced.has(f)));
+        }
+        const checkFiles = /* @__PURE__ */ new Set();
+        for (const e of before.elements.values())
+          if (!(e.status === "deleted" || layers && !layers.includes(e.layer)))
+            for (const l of e.sourceReference?.locations ?? []) {
+              const file = l.file?.replace(/\\/g, "/").replace(/^\.\//, "");
+              file && l.symbol && (!changes || changes.changed.has(file)) && checkFiles.add(file);
+            }
+        let extraction;
+        try {
+          extraction = await backend.extract(projectRoot, {
+            codebaseRoot,
+            ...changes ? { files: changes.changed } : {},
+            checkFiles: [...checkFiles],
+            deadline
+          });
+        } catch (error) {
+          throw error instanceof ExtractionTimeoutError ? new CLIError(`codebase_extract ran past its ${Math.round((deadline - startedAt) / 1e3)} s budget ${error.stage}; nothing was staged`, ErrorCategory.USER, [NARROW]) : error;
+        }
+        const descriptionsFile = path.join(extractDir(projectRoot), DESCRIPTIONS_FILE), extractedDescriptions = await readJson(descriptionsFile) ?? {}, plan = planElements(extraction, before, {
+          layers,
+          changes,
+          extractedDescriptions,
+          notElements: notElementKeys,
+          fileExists: (file) => existsSync(path.join(codebaseRoot, file)),
+          fileText: (file) => {
+            try {
+              return readFileSync(path.join(codebaseRoot, file), "utf-8");
+            } catch {
+              return null;
+            }
+          }
+        }), now = (/* @__PURE__ */ new Date()).toISOString(), { valid, invalid } = await validateAdds(plan.adds, extraction.project, now, changes?.hunks), adds = valid.map((v) => v.add), undecided = sortUndecided(attributeChangedLines([...plan.undecided, ...invalid], changes?.hunks)), kept = new Set(adds);
+        for (const add of plan.adds)
+          kept.has(add) || (plan.elementOf.delete(add.symbol.qualifiedName), delete plan.descriptions[add.id]);
+        const elements = /* @__PURE__ */ new Map();
+        for (const e of before.elements.values())
+          e.status !== "deleted" && elements.set(e.id, { layer: e.layer, type: e.type });
+        for (const a of adds)
+          elements.set(a.id, { layer: a.layer, type: a.type });
+        const { relationships, alreadyPresent } = planRelationships(extraction, before, plan.elementOf, elements, hasTriple, layers), batch = [], rewrites = [];
+        for (const { add, element } of valid)
+          batch.push({ type: "add", elementId: add.id, layerName: add.layer, after: element.toJSON() });
+        const stagedUpdates = [];
+        for (const update of plan.updates) {
+          const current = await currentSnapshot(model, before, changeset ?? emptyChangeset(), update.id, update.layer);
+          if (!current)
+            continue;
+          const after = patched(current.snapshot, update, now);
+          current.stagedAdd ? rewrites.push({
+            elementId: current.stagedAdd.elementId,
+            change: {
+              type: "add",
+              elementId: current.stagedAdd.elementId,
+              layerName: current.stagedAdd.layerName,
+              ...current.stagedAdd.before !== void 0 ? { before: current.stagedAdd.before } : {},
+              after
+            }
+          }) : batch.push({ type: "update", elementId: update.id, layerName: update.layer, before: current.snapshot, after }), stagedUpdates.push(update);
+        }
+        for (const r of relationships)
+          batch.push(relationshipChange(r));
+        const summary = {
+          adds: adds.length,
+          updates: stagedUpdates.length,
+          relationships: relationships.length,
+          cards: undecided.length,
+          candidateDeletes: plan.candidateDeletes.length
+        };
+        if (Date.now() > deadline)
+          throw new CLIError(`codebase_extract ran past its ${Math.round((deadline - startedAt) / 1e3)} s budget before staging. It had planned ${summary.adds} adds, ${summary.updates} updates and ${summary.relationships} relationships, with ${summary.cards} cards; nothing was staged`, ErrorCategory.USER, [NARROW]);
+        if (context?.signal?.aborted)
+          throw new CLIError("codebase_extract was cancelled before staging; nothing was staged", ErrorCategory.USER);
+        const activeId = await manager.getActiveId();
+        let previousActive = null;
+        if (activeId && activeId !== changeset?.id) {
+          const prev = await manager.load(activeId);
+          previousActive = { id: activeId, name: prev?.name ?? activeId };
+        } else if (storedBefore?.previousActive) {
+          const prev = await manager.load(storedBefore.previousActive.id);
+          prev?.status === "staged" && (previousActive = { id: prev.id, name: prev.name });
+        }
+        let recordedPrevious = previousActive;
+        if (storedBefore?.previousActive && storedBefore.previousActive.id !== previousActive?.id) {
+          const first = await manager.load(storedBefore.previousActive.id);
+          first?.status === "staged" && (recordedPrevious = { id: first.id, name: first.name });
+        }
+        const stages = batch.length > 0 || rewrites.length > 0, hasWork = stages || undecided.length > 0 || plan.candidateDeletes.length > 0;
+        let created = !1, active = !!changeset && activeId === changeset.id;
+        if (changeset ? hasWork : stages) {
+          changeset || (changeset = await manager.create(name, `As-built extraction of the code at ${head.slice(0, 7)}${since ? `, files changed since ${since}` : ""}. Staged by codebase_extract.`), created = !0);
+          try {
+            await manager.stageMany(changeset.id, batch, rewrites);
+          } catch (error) {
+            throw created && await manager.delete(changeset.id).catch(() => {
+            }), error;
+          }
+          activeId !== changeset.id && await manager.setActive(changeset.id), active = !0, await reloadModel(args.rootPath), Object.keys(plan.descriptions).length && await writeFile(descriptionsFile, JSON.stringify({ ...extractedDescriptions, ...plan.descriptions }), "utf-8");
+        }
+        const nowCards = new Set(undecided.map((c) => c.cardId)), earlierCards = /* @__PURE__ */ new Map();
+        for (const c of [...storedBefore?.earlierCards ?? [], ...storedBefore?.cards ?? []])
+          nowCards.has(c.cardId) || earlierCards.set(c.cardId, c);
+        const updatedFields = /* @__PURE__ */ new Map();
+        for (const u of storedBefore?.updated ?? []) {
+          const status = before.getElement(u.id)?.status;
+          status !== "updated" && status !== "added" || updatedFields.set(u.id, new Map(u.fields.map((f) => [f, u.values && Object.prototype.hasOwnProperty.call(u.values, f) ? u.values[f] : void 0])));
+        }
+        for (const u of stagedUpdates) {
+          const fields = updatedFields.get(u.id) ?? updatedFields.set(u.id, /* @__PURE__ */ new Map()).get(u.id);
+          for (const [f, value] of Object.entries(u.fields))
+            fields.set(f, structuredClone(value));
+        }
+        const updatedRecord = [...updatedFields].map(([id, fields]) => {
+          const names = [...fields.keys()].sort(), values = Object.fromEntries(names.filter((f) => fields.get(f) !== void 0).map((f) => [f, fields.get(f)]));
+          return { id, fields: names, ...Object.keys(values).length ? { values } : {} };
+        }), candidateDeleteIds = [.../* @__PURE__ */ new Set([...storedBefore?.candidateDeletes ?? [], ...plan.candidateDeletes.map((d) => d.id)])], accumulated = {
+          ...updatedRecord.length ? { updated: updatedRecord } : {},
+          ...candidateDeleteIds.length ? { candidateDeletes: candidateDeleteIds } : {}
+        }, pendingPath = path.join(extractDir(projectRoot), PENDING_FILE);
+        if (changeset) {
+          const staged = [...stillStaged];
+          for (const a of adds)
+            staged.push({
+              id: a.id,
+              file: a.symbol.card.file_path,
+              symbol: sourceSymbolOf(a.symbol, extraction.project),
+              label: a.symbol.card.label,
+              ...stagedAs(a.name, a.attributes)
+            });
+          const record = {
+            changesetId: changeset.id,
+            changesetName: changeset.name,
+            gitHead: head,
+            since: since ?? null,
+            layers: layers ?? null,
+            baseModified,
+            previousActive: recordedPrevious,
+            createdAt: now,
+            cards: undecided,
+            staged,
+            ...earlierCards.size ? { earlierCards: [...earlierCards.values()] } : {},
+            ...accumulated
+          };
+          await writeFile(cardsPath(projectRoot, changeset.id), JSON.stringify(record), "utf-8"), pending?.changesetName === changeset.name && await rm(pendingPath, { force: !0 });
+        } else if (undecided.length || plan.candidateDeletes.length) {
+          const record = {
+            changesetId: "",
+            changesetName: name,
+            gitHead: head,
+            since: since ?? null,
+            layers: layers ?? null,
+            baseModified,
+            previousActive,
+            createdAt: now,
+            cards: undecided,
+            staged: [],
+            ...earlierCards.size ? { earlierCards: [...earlierCards.values()] } : {},
+            ...accumulated,
+            pending: !0
+          };
+          await writeFile(pendingPath, JSON.stringify(record), "utf-8");
+        } else pending?.changesetName === name && await rm(pendingPath, { force: !0 });
+        await pruneCardFiles(projectRoot, manager);
+        const cards = page(undecided, 1, effectivePageSize), changedCards = undecided.filter((c) => c.changedInRange).length, changesetRef = changeset ? { id: changeset.id, name: changeset.name } : null, verifyMode = !!since && !!recordedPrevious, message = hasWork ? changeset ? void 0 : `Nothing to stage, so no changeset was created or activated. ${undecided.length} card(s)${changedCards ? ` (${changedCards} changed in the range)` : ""} and ${plan.candidateDeletes.length} candidate delete(s) are left for you to decide; to stage any, first call changeset_create with name: "${name}".` : verifyMode && !changeset ? `Nothing to stage: nothing in the range is observable to extraction or differs from the model. No as-built changeset was created; ${previousActive ? `'${previousActive.name}' is still active.` : `the plan is '${recordedPrevious.name}'.`}` : changeset ? `Nothing more to stage: '${changeset.name}' already says what this code says.` : "Nothing to stage: the model already says what this code says. No changeset was created or activated.";
+        return jsonResult(fitCards(cards.items, cards, (items, fit) => ({
+          changeset: changesetRef ? { ...changesetRef, created, active } : null,
+          previousActive,
+          ...message ? { message } : {},
+          ...fitNotes(fit),
+          ...edited.length ? {
+            warning: `${edited.length} source file(s) have uncommitted edits made after the index was taken, which this run may not have seen (${edited.slice(0, 5).join(", ")}${edited.length > 5 ? ", ..." : ""}). Re-index with codebase_index, then call codebase_extract again.`
+          } : {},
+          ...changes?.hunksError ? {
+            hunksWarning: `The range's changed lines couldn't be read (${changes.hunksError}), so no card says changedInRange; the cards are those of every changed file.`
+          } : {},
+          analyzer,
+          // The shared judgement: `fresh-with-uncommitted-edits` when the warning above is given.
+          index: describeIndex(freshness, indexJudgement),
+          scope: {
+            since: since ?? null,
+            ...changes ? { base: changes.base, changedFiles: changes.changed.size, deletedFiles: changes.deleted.size } : { files: "all" },
+            layers: layers ?? "all"
+          },
+          cards: { ...extraction.summary, needsAttributes: invalid.length },
+          staged: {
+            adds: adds.length,
+            updates: stagedUpdates.length,
+            relationships: relationships.length,
+            byLayer: byLayer(adds, stagedUpdates, relationships),
+            ...stagedUpdates.length ? { updated: capped(stagedUpdates.map((u) => ({ id: u.id, fields: Object.keys(u.fields) })), fit.listLimit) } : {}
+          },
+          unchanged: {
+            elements: plan.unchanged,
+            modelled: plan.modelled,
+            relationships: alreadyPresent,
+            rejected: plan.rejected,
+            ...plan.outsideLayers ? { outsideLayers: plan.outsideLayers } : {}
+          },
+          candidateDeletes: {
+            ...capped(plan.candidateDeletes, fit.listLimit),
+            note: "Not staged: deleting is left to you. Each has its evidence."
+          },
+          ...plan.retyped.length ? { retyped: capped(plan.retyped, fit.listLimit) } : {},
+          ...notElementsResult(decisions, plan.skipped, recordedNow, cleared, fit.listLimit),
+          undecided: undecidedSection(cards, items, fit, pageSize, changes ? { changedInRange: changedCards } : {}),
+          tier1: "not wired: cards Tier 0 can't decide come to you (docs/EXTRACTION_STRATEGY.md, B6)",
+          durationMs: Date.now() - startedAt,
+          next: hasWork ? changesetRef ? nextSteps(changesetRef, recordedPrevious, cards.pages, plan, changedCards, since, fit.readOn) : pendingSteps(name, recordedPrevious, cards.pages, plan, changedCards, since, fit.readOn) : verifyMode ? changesetRef ? nextSteps(changesetRef, recordedPrevious, 0, plan, 0, since) : verifyNothingSteps(recordedPrevious, since) : []
+        })), { compact: !0 });
+      } finally {
+        await lock.release().catch(() => {
+        });
+      }
+    });
+  };
+}
+const codebaseExtractHandler = createCodebaseExtractHandler(), codebaseExtractTool = {
+  name: "codebase_extract",
+  description: "Model the indexed code as an as-built changeset: Tier-0 rules decide what they can and those elements and their relationships are staged; the rest come back as undecided cards (paged) for you to stage with model_add. Stages only what differs from the model (matched by source file and symbol): new symbols are adds, changed ones updates; elements whose code is gone are listed as candidateDeletes, not staged. since (a git ref) limits it to files changed since then, for verifying a branch; cards whose lines the range changed say changedInRange and come first. Code that is not an element goes in reject (with a reason): a card, or a symbol or element it staged, which is then unstaged; kept until clearRejected, later runs leave them out. An element it staged that you unstage from a changeset is also left out, but only while that changeset is staged: discarding or landing it forgets that. A run or page into an extraction changeset keeps that run's since and layers. The changeset (default extract-<sha>) is created and made active only when the run stages something; a run that only leaves cards or candidate deletes creates nothing and says which changeset to create first. previousActive is the one active before the first run. Needs a fresh index (codebase_index). Never writes the base model or commits.",
+  inputSchema,
+  handler: codebaseExtractHandler
+};
+export {
+  codebaseExtractHandler,
+  codebaseExtractTool,
+  createCodebaseExtractHandler,
+  isExtractionChangeset
+};
+//# sourceMappingURL=codebase-extract.js.map