@topogram/cli 0.3.84 → 0.3.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.84",
+  "version": "0.3.86",
   "description": "Topogram CLI for checking Topogram workspaces and generating app bundles.",
   "license": "Apache-2.0",
   "repository": {

package/src/cli/commands/extractor.js

@@ -44,6 +44,7 @@ export function printExtractorHelp() {
   console.log("  - extractor packages execute only during `topogram extract` or `topogram extractor check`.");
   console.log("  - extractor packages emit review-only candidates; core owns persistence, reconcile, and adoption.");
   console.log(`  - package-backed extractors are governed by ${EXTRACTOR_POLICY_FILE}; bundled topogram/* extractors are allowed.`);
+  console.log("  - safe loop: list/show -> install -> policy pin -> check -> extract -> plan/list -> adopt --dry-run -> adopt --write.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram extractor list");
@@ -121,17 +122,110 @@ function extractorPolicyPinCommand(packageName, version) {
 }
 
 /**
- * @param {string|null|undefined} packageName
+ * @param {string|null|undefined} extractorRef
  * @param {string[]} tracks
  * @param {string|null|undefined} exampleSource
  * @returns {string|null}
  */
-function extractorRunCommand(packageName, tracks, exampleSource) {
-  if (!packageName) {
+function extractorRunCommand(extractorRef, tracks, exampleSource) {
+  if (!extractorRef) {
     return null;
   }
   const trackList = tracks.length > 0 ? tracks.join(",") : "db,api,ui,cli";
-  return `topogram extract ${exampleSource || "./existing-app"} --out ./imported-topogram --from ${trackList} --extractor ${packageName}`;
+  return `topogram extract ${exampleSource || "./existing-app"} --out ./imported-topogram --from ${trackList} --extractor ${extractorRef}`;
+}
+
+/**
+ * @param {Record<string, any>|null|undefined} extractor
+ * @returns {Record<string, any>}
+ */
+function buildExtractorReviewWorkflow(extractor = null) {
+  const packageName = extractor?.package || extractor?.packageName || null;
+  const extractorRef = packageName || extractor?.id || "<extractor>";
+  const tracks = Array.isArray(extractor?.tracks) ? extractor.tracks : [];
+  const version = extractor?.version || "1";
+  const bundledExtractor = extractor?.source === "bundled" && !packageName;
+  const installCommand = extractor?.installCommand || (packageName ? packageExtractorInstallCommand(packageName) : null);
+  const policyPinCommand = extractor?.policyPinCommand || (packageName ? extractorPolicyPinCommand(packageName, version) : null);
+  const extractCommand = extractor?.extractCommand || extractorRunCommand(extractorRef, tracks, extractor?.exampleSource);
+  return {
+    type: "extractor_review_workflow",
+    packageCodeExecution: {
+      list: false,
+      show: false,
+      policy: false,
+      check: true,
+      extract: true
+    },
+    steps: [
+      {
+        id: "discover",
+        command: "topogram extractor list",
+        packageCodeExecution: false,
+        purpose: "Find bundled and first-party package-backed extractors by track."
+      },
+      {
+        id: "inspect",
+        command: `topogram extractor show ${extractorRef}`,
+        packageCodeExecution: false,
+        purpose: "Read manifest purpose, tracks, install command, policy pin command, and extract command."
+      },
+      ...(installCommand ? [{
+        id: "install",
+        command: installCommand,
+        packageCodeExecution: false,
+        purpose: "Install the extractor package explicitly; Topogram does not install it during extraction."
+      }] : []),
+      ...(policyPinCommand ? [{
+        id: "pin_policy",
+        command: policyPinCommand,
+        packageCodeExecution: false,
+        purpose: "Allow and pin the extractor manifest version before execution."
+      }] : []),
+      ...(!bundledExtractor ? [{
+        id: "check",
+        command: `topogram extractor check ${extractorRef}`,
+        packageCodeExecution: true,
+        purpose: "Load the adapter and run a minimal smoke extraction against a synthetic fixture."
+      }] : []),
+      ...(extractCommand ? [{
+        id: "extract",
+        command: extractCommand,
+        packageCodeExecution: true,
+        purpose: "Read brownfield source and write review-only candidates plus extraction provenance."
+      }] : []),
+      {
+        id: "review_plan",
+        command: "topogram extract plan ./imported-topogram",
+        packageCodeExecution: false,
+        purpose: "Review bundles, extractor provenance, candidate counts, and safety notes."
+      },
+      {
+        id: "list_selectors",
+        command: "topogram adopt --list ./imported-topogram",
+        packageCodeExecution: false,
+        purpose: "Choose an explicit adoption selector."
+      },
+      {
+        id: "dry_run_adoption",
+        command: "topogram adopt <selector> ./imported-topogram --dry-run",
+        packageCodeExecution: false,
+        purpose: "Preview canonical topo writes before changing project-owned records."
+      },
+      {
+        id: "write_reviewed_adoption",
+        command: "topogram adopt <selector> ./imported-topogram --write",
+        packageCodeExecution: false,
+        purpose: "Write only reviewed canonical records; extractor packages never own adoption semantics."
+      }
+    ],
+    safetyNotes: [
+      "topogram extractor list/show/policy do not load package adapter code.",
+      "topogram extractor check and topogram extract load package adapter code.",
+      "Extractor packages emit review-only candidates; core owns persistence, reconcile, adoption, and canonical topo writes.",
+      "Run dry-run adoption before --write."
+    ]
+  };
 }
 
 /**
@@ -188,8 +282,8 @@ function extractorManifestSummary(manifest, metadata = {}) {
   const version = manifest.version || firstParty?.version || "1";
   const installCommand = packageName ? packageExtractorInstallCommand(packageName) : null;
   const policyPinCommand = extractorPolicyPinCommand(packageName, version);
-  const extractCommand = extractorRunCommand(packageName, tracks, firstParty?.exampleSource);
-  return {
+  const extractCommand = extractorRunCommand(packageName || manifest.id, tracks, firstParty?.exampleSource);
+  const summary = {
     id: manifest.id,
     version,
     label: firstParty?.label || null,
@@ -215,6 +309,10 @@ function extractorManifestSummary(manifest, metadata = {}) {
     packageRoot: metadata.packageRoot || null,
     errors: metadata.errors || []
   };
+  return {
+    ...summary,
+    reviewWorkflow: buildExtractorReviewWorkflow(summary)
+  };
 }
 
 /**
@@ -222,7 +320,7 @@ function extractorManifestSummary(manifest, metadata = {}) {
  * @returns {Record<string, any>}
  */
 function firstPartyExtractorPlaceholder(info) {
-  return {
+  const summary = {
     id: info.id,
     version: info.version,
     label: info.label,
@@ -248,11 +346,15 @@ function firstPartyExtractorPlaceholder(info) {
     packageRoot: null,
     errors: []
   };
+  return {
+    ...summary,
+    reviewWorkflow: buildExtractorReviewWorkflow(summary)
+  };
 }
 
 /**
  * @param {string} cwd
- * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], groups: Record<string, ReturnType<typeof groupExtractorEntry>[]>, summary: Record<string, number> }}
+ * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], groups: Record<string, ReturnType<typeof groupExtractorEntry>[]>, reviewWorkflow: Record<string, any>, summary: Record<string, number> }}
  */
 export function buildExtractorListPayload(cwd) {
   const extractors = EXTRACTOR_MANIFESTS
@@ -314,6 +416,7 @@ export function buildExtractorListPayload(cwd) {
     cwd,
     extractors,
     groups,
+    reviewWorkflow: buildExtractorReviewWorkflow(),
     summary: {
       total: extractors.length,
       bundled: extractors.filter((extractor) => extractor.source === "bundled").length,
@@ -367,6 +470,7 @@ export function printExtractorList(payload) {
   console.log("Topogram extractors");
   console.log(`Bundled: ${payload.summary.bundled}; package-backed: ${payload.summary.package}; installed: ${payload.summary.installed}; first-party missing: ${payload.summary.missingFirstParty || 0}`);
   console.log("Package-backed extractors are listed for discovery even before they are installed.");
+  console.log("Selection loop: list/show (no package code) -> install -> policy pin -> extractor check (loads adapter) -> extract -> extract plan/adopt --list -> adopt --dry-run -> adopt --write.");
   console.log("");
   for (const track of EXTRACTOR_TRACK_ORDER) {
     const entries = (payload.groups || {})[track] || [];
@@ -426,10 +530,18 @@ export function printExtractorShow(payload) {
   console.log(`Extractors: ${extractor.extractors.join(", ") || "none"}`);
   console.log(`Candidate kinds: ${extractor.candidateKinds.join(", ") || "none"}`);
   console.log(`Evidence types: ${extractor.evidenceTypes.join(", ") || "none"}`);
+  if (extractor.reviewWorkflow?.steps?.length) {
+    console.log("");
+    console.log("Review loop:");
+    for (const step of extractor.reviewWorkflow.steps) {
+      console.log(`- ${step.id}: ${step.command}`);
+      console.log(`  ${step.purpose}`);
+    }
+  }
 }
 
 /**
- * @param {ReturnType<typeof checkExtractorPack>} payload
+ * @param {ReturnType<typeof checkExtractorPack> & { reviewWorkflow?: Record<string, any> }} payload
  * @returns {void}
  */
 export function printExtractorCheck(payload) {
@@ -453,12 +565,19 @@ export function printExtractorCheck(payload) {
     console.log("");
     console.log(`Smoke output: ${payload.smoke.extractors} extractor(s), ${payload.smoke.findings} finding(s), ${payload.smoke.candidateKeys} candidate bucket(s), ${payload.smoke.diagnostics} diagnostic(s)`);
   }
+  if (payload.reviewWorkflow?.steps?.length) {
+    console.log("");
+    console.log("Next review loop:");
+    for (const step of payload.reviewWorkflow.steps.filter((/** @type {Record<string, any>} */ step) => ["extract", "review_plan", "list_selectors", "dry_run_adoption", "write_reviewed_adoption"].includes(step.id))) {
+      console.log(`- ${step.command}`);
+    }
+  }
   for (const error of payload.errors || []) console.log(`Error: ${error}`);
 }
 
 /**
  * @param {string} projectPath
- * @returns {{ ok: boolean, path: string, exists: boolean, policy: any, defaulted: boolean, packages: any[], diagnostics: any[], errors: string[], summary: Record<string, number> }}
+ * @returns {{ ok: boolean, path: string, exists: boolean, policy: any, defaulted: boolean, packages: any[], diagnostics: any[], errors: string[], reviewWorkflow: Record<string, any>, summary: Record<string, number> }}
  */
 export function buildExtractorPolicyStatusPayload(projectPath) {
   const root = path.resolve(projectPath || ".");
@@ -504,6 +623,7 @@ export function buildExtractorPolicyStatusPayload(projectPath) {
     packages,
     diagnostics,
     errors,
+    reviewWorkflow: buildExtractorReviewWorkflow(packages[0] || null),
     summary: {
       enabledPackages: policy.enabledPackages.length,
       installed: packages.filter((item) => item.installed).length,
@@ -567,6 +687,7 @@ export function printExtractorPolicyStatus(payload) {
   console.log(`Enabled packages: ${payload.summary.enabledPackages}`);
   console.log("Default allowlist: bundled topogram/* extractors and first-party @topogram/extractor-* packages.");
   console.log("Install behavior: Topogram does not install extractor packages automatically.");
+  console.log("Review loop: install package -> pin policy -> extractor check -> extract -> extract plan/adopt --list -> adopt --dry-run -> adopt --write.");
   for (const item of payload.packages) {
     console.log(`- ${item.packageName}@${item.version}: ${item.installed ? "installed" : "missing"}, ${item.allowed ? "allowed" : "denied"}`);
     if (!item.installed && item.installCommand) console.log(`  Install: ${item.installCommand}`);
@@ -611,9 +732,25 @@ export function runExtractorCommand(context) {
   const { commandArgs, inputPath, json, cwd } = context;
   if (commandArgs.extractorCommand === "check") {
     const payload = checkExtractorPack(inputPath || "", { cwd });
-    if (json) console.log(stableStringify(payload));
-    else printExtractorCheck(payload);
-    return payload.ok ? 0 : 1;
+    const summary = payload.manifest
+      ? extractorManifestSummary(payload.manifest, {
+          installed: Boolean(payload.manifest),
+          manifestPath: payload.manifestPath,
+          packageRoot: payload.packageRoot,
+          errors: payload.errors
+        })
+      : null;
+    const augmentedPayload = /** @type {ReturnType<typeof checkExtractorPack> & { reviewWorkflow?: Record<string, any> }} */ (payload);
+    augmentedPayload.reviewWorkflow = buildExtractorReviewWorkflow(summary || {
+      id: inputPath || "<extractor>",
+      package: payload.packageName || null,
+      packageName: payload.packageName || null,
+      tracks: payload.manifest?.tracks || [],
+      version: payload.manifest?.version || "1"
+    });
+    if (json) console.log(stableStringify(augmentedPayload));
+    else printExtractorCheck(augmentedPayload);
+    return augmentedPayload.ok ? 0 : 1;
   }
   if (commandArgs.extractorCommand === "scaffold") {
     const payload = scaffoldExtractorPack(inputPath || "", {

package/src/cli/commands/import/plan.js

@@ -3,6 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { readExtractionContext } from "../../../extraction-context.js";
 import { runWorkflow } from "../../../workflows.js";
 import {
   countByField,
@@ -60,6 +61,73 @@ export const BROWNFIELD_BROAD_ADOPT_SELECTORS = [
   }
 ];
 
+/**
+ * @param {AnyRecord|null|undefined} extractionContext
+ * @param {AnyRecord[]} bundleSurfaces
+ * @param {string} bundleSlug
+ * @returns {string[]}
+ */
+function tracksForBundle(extractionContext, bundleSurfaces, bundleSlug) {
+  const tracks = new Set(bundleSurfaces.map((surface) => surface.track).filter(Boolean));
+  if (bundleSlug === "database" || bundleSlug.includes("db")) tracks.add("db");
+  if (bundleSlug === "cli") tracks.add("cli");
+  if (bundleSlug === "ui") tracks.add("ui");
+  if (bundleSlug.includes("api")) tracks.add("api");
+  const knownTracks = new Set(Array.isArray(extractionContext?.tracks) ? extractionContext.tracks : []);
+  return [...tracks].filter((track) => knownTracks.size === 0 || knownTracks.has(track)).sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * @param {AnyRecord} extractor
+ * @param {Set<string>} tracks
+ * @returns {boolean}
+ */
+function extractorMatchesTracks(extractor, tracks) {
+  const extractorTracks = Array.isArray(extractor.tracks) ? extractor.tracks : [];
+  return tracks.size === 0 || extractorTracks.length === 0 || extractorTracks.some((track) => tracks.has(track));
+}
+
+/**
+ * @param {AnyRecord|null|undefined} extractionContext
+ * @param {AnyRecord[]} bundleSurfaces
+ * @param {string} bundleSlug
+ * @returns {AnyRecord|null}
+ */
+function extractorContextForBundle(extractionContext, bundleSurfaces, bundleSlug) {
+  if (!extractionContext) {
+    return null;
+  }
+  const tracks = tracksForBundle(extractionContext, bundleSurfaces, bundleSlug);
+  const trackSet = new Set(tracks);
+  const packageBackedExtractors = (extractionContext.package_backed_extractors || [])
+    .filter((/** @type {AnyRecord} */ extractor) => extractorMatchesTracks(extractor, trackSet))
+    .map((/** @type {AnyRecord} */ extractor) => ({
+      id: extractor.id || null,
+      version: extractor.version || null,
+      packageName: extractor.packageName || null,
+      extractors: Array.isArray(extractor.extractors) ? extractor.extractors : [],
+      tracks: Array.isArray(extractor.tracks) ? extractor.tracks : []
+    }));
+  const bundledExtractors = (extractionContext.bundled_extractors || [])
+    .filter((/** @type {AnyRecord} */ extractor) => extractorMatchesTracks(extractor, trackSet))
+    .map((/** @type {AnyRecord} */ extractor) => ({
+      id: extractor.id || null,
+      version: extractor.version || null,
+      extractors: Array.isArray(extractor.extractors) ? extractor.extractors : [],
+      tracks: Array.isArray(extractor.tracks) ? extractor.tracks : []
+    }));
+  if (packageBackedExtractors.length === 0 && bundledExtractors.length === 0) {
+    return null;
+  }
+  return {
+    tracks,
+    packageBackedExtractors,
+    bundledExtractors,
+    candidateCounts: extractionContext.candidate_counts || {},
+    safetyNotes: extractionContext.safety_notes || []
+  };
+}
+
 /**
  * @param {string} inputPath
  * @returns {AnyRecord}
@@ -84,7 +152,8 @@ export function readImportAdoptionArtifacts(inputPath) {
     paths,
     adoptionPlan: JSON.parse(fs.readFileSync(paths.adoptionPlanAgent, "utf8")),
     adoptionStatus: readJsonIfExists(paths.adoptionStatus),
-    reconcileReport: readJsonIfExists(paths.reconcileReport)
+    reconcileReport: readJsonIfExists(paths.reconcileReport),
+    extractionContext: readExtractionContext(topogramRoot)
   };
 }
 
@@ -118,9 +187,10 @@ export function buildBrownfieldBroadAdoptSelectors(projectRoot, adoptionPlan) {
  * @param {AnyRecord} adoptionPlan
  * @param {AnyRecord} adoptionStatus
  * @param {string} projectRoot
+ * @param {AnyRecord|null|undefined} extractionContext
  * @returns {AnyRecord}
  */
-export function summarizeImportAdoption(adoptionPlan, adoptionStatus, projectRoot) {
+export function summarizeImportAdoption(adoptionPlan, adoptionStatus, projectRoot, extractionContext = null) {
   const surfaces = adoptionPlan.imported_proposal_surfaces || [];
   /** @type {string[]} */
   const slugs = [];
@@ -162,7 +232,8 @@ export function summarizeImportAdoption(adoptionPlan, adoptionStatus, projectRoo
       complete: Boolean(priority?.is_complete) || (pendingItems.length === 0 && blockedItems.length === 0 && appliedItems.length > 0),
       evidenceScore: priority?.evidence_score || 0,
       why: priority?.operator_summary?.whyThisBundle || null,
-      nextCommand: importAdoptCommand(projectRoot, `bundle:${slug}`, false)
+      nextCommand: importAdoptCommand(projectRoot, `bundle:${slug}`, false),
+      extractorContext: extractorContextForBundle(extractionContext, bundleSurfaces, slug)
     };
   });
   const nextBundle = bundles.find((bundle) => !bundle.complete && bundle.pendingItemCount > 0) || bundles.find((bundle) => !bundle.complete) || bundles[0] || null;
@@ -196,7 +267,7 @@ export function summarizeImportAdoption(adoptionPlan, adoptionStatus, projectRoo
 export function buildBrownfieldImportPlanPayload(inputPath) {
   const artifacts = readImportAdoptionArtifacts(inputPath);
   const adoptionStatus = runWorkflow("adoption-status", artifacts.projectRoot).summary || artifacts.adoptionStatus || {};
-  const adoption = summarizeImportAdoption(artifacts.adoptionPlan, adoptionStatus, artifacts.projectRoot);
+  const adoption = summarizeImportAdoption(artifacts.adoptionPlan, adoptionStatus, artifacts.projectRoot, artifacts.extractionContext);
   return {
     ok: true,
     projectRoot: artifacts.projectRoot,
@@ -207,6 +278,14 @@ export function buildBrownfieldImportPlanPayload(inputPath) {
       adoptionStatus: artifacts.paths.adoptionStatus,
       reconcileReport: artifacts.paths.reconcileReport
     },
+    extractorContext: artifacts.extractionContext ? {
+      provenancePath: artifacts.extractionContext.provenance_path,
+      packageBackedExtractors: artifacts.extractionContext.package_backed_extractors,
+      bundledExtractors: artifacts.extractionContext.bundled_extractors,
+      candidateCounts: artifacts.extractionContext.candidate_counts,
+      safetyNotes: artifacts.extractionContext.safety_notes,
+      summary: artifacts.extractionContext.summary
+    } : null,
     ...adoption,
     commands: {
       check: `topogram extract check ${importProjectCommandPath(artifacts.projectRoot)}`,
@@ -229,6 +308,14 @@ export function printBrownfieldImportPlan(payload) {
     if (bundle.why) {
       console.log(`  ${bundle.why}`);
     }
+    if (bundle.extractorContext?.packageBackedExtractors?.length > 0) {
+      const names = bundle.extractorContext.packageBackedExtractors
+        .map((/** @type {AnyRecord} */ extractor) => extractor.packageName || extractor.id)
+        .filter(Boolean)
+        .join(", ");
+      console.log(`  Extractors: ${names}`);
+      console.log("  Safety: package-backed extractor candidates are review-only; run dry-run adoption before --write.");
+    }
     console.log(`  Preview: ${bundle.nextCommand}`);
   }
   if (payload.risks.length > 0) {
@@ -257,6 +344,7 @@ export function buildBrownfieldImportAdoptListPayload(inputPath) {
     appliedItemCount: bundle.appliedItemCount,
     blockedItemCount: bundle.blockedItemCount,
     complete: bundle.complete,
+    extractorContext: bundle.extractorContext || null,
     previewCommand: importAdoptCommand(plan.projectRoot, `bundle:${bundle.bundle}`, false),
     writeCommand: importAdoptCommand(plan.projectRoot, `bundle:${bundle.bundle}`, true)
   }));
@@ -270,6 +358,7 @@ export function buildBrownfieldImportAdoptListPayload(inputPath) {
     selectors,
     broadSelectorCount: broadSelectors.length,
     broadSelectors,
+    extractorContext: plan.extractorContext,
     nextCommand: selectors.find((/** @type {AnyRecord} */ selector) => !selector.complete)?.previewCommand || plan.commands.status
   };
 }
@@ -286,6 +375,14 @@ export function printBrownfieldImportAdoptList(payload) {
   }
   for (const selector of payload.selectors) {
     console.log(`- ${selector.selector}: ${selector.itemCount} item(s), ${selector.pendingItemCount} pending, ${selector.appliedItemCount} applied`);
+    if (selector.extractorContext?.packageBackedExtractors?.length > 0) {
+      const names = selector.extractorContext.packageBackedExtractors
+        .map((/** @type {AnyRecord} */ extractor) => extractor.packageName || extractor.id)
+        .filter(Boolean)
+        .join(", ");
+      console.log(`  Extractors: ${names}`);
+      console.log("  Safety: package-backed extractor candidates are review-only; run dry-run adoption before --write.");
+    }
     console.log(`  Preview: ${selector.previewCommand}`);
     console.log(`  Write: ${selector.writeCommand}`);
   }

package/src/cli/commands/query/workspace.js

@@ -4,9 +4,9 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { generateWorkspace } from "../../../generator.js";
-import { TOPOGRAM_IMPORT_FILE } from "../../../import/provenance.js";
 import { formatValidationErrors } from "../../../validator.js";
 import { buildChangePlanPayload } from "../../../agent-ops/query-builders.js";
+import { buildExtractionContext, readExtractionContext } from "../../../extraction-context.js";
 import { resolveTopoRoot } from "../../../workspace-paths.js";
 
 /**
@@ -197,72 +197,7 @@ export function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, "utf8"));
 }
 
-/**
- * @param {AnyRecord} record
- * @param {string} provenancePath
- * @returns {AnyRecord}
- */
-export function buildExtractionContext(record, provenancePath) {
-  const extractorPackages = /** @type {AnyRecord[]} */ (Array.isArray(record.extract?.extractorPackages)
-    ? record.extract.extractorPackages
-    : []);
-  const packageBackedExtractors = extractorPackages
-    .filter((entry) => entry?.source === "package")
-    .map((entry) => ({
-      id: entry.id || null,
-      version: entry.version || null,
-      packageName: entry.packageName || null,
-      extractors: Array.isArray(entry.extractors) ? entry.extractors : [],
-      manifestPath: entry.manifestPath || null
-    }));
-  const bundledExtractors = extractorPackages
-    .filter((entry) => entry?.source === "bundled")
-    .map((entry) => ({
-      id: entry.id || null,
-      version: entry.version || null,
-      extractors: Array.isArray(entry.extractors) ? entry.extractors : []
-    }));
-  return {
-    type: "extraction_context",
-    provenance_path: provenancePath,
-    kind: record.kind || null,
-    extracted_at: record.extractedAt || null,
-    refreshed_at: record.refreshedAt || null,
-    source_path: record.source?.path || null,
-    tracks: Array.isArray(record.extract?.tracks) ? record.extract.tracks : [],
-    findings_count: record.extract?.findingsCount || 0,
-    candidate_counts: record.extract?.candidateCounts || {},
-    package_backed_extractors: packageBackedExtractors,
-    bundled_extractors: bundledExtractors,
-    summary: {
-      package_backed_extractor_count: packageBackedExtractors.length,
-      bundled_extractor_count: bundledExtractors.length,
-      source_file_count: Array.isArray(record.files) ? record.files.length : 0
-    },
-    next_commands: [
-      "topogram extract check",
-      "topogram extract plan",
-      "topogram adopt --list",
-      "topogram adopt <selector> --dry-run"
-    ],
-    safety_notes: [
-      "Extractor packages are evidence producers only; review candidates before canonical adoption.",
-      "Use dry-run adoption before --write, especially when package-backed extractors contributed candidates."
-    ]
-  };
-}
-
-/**
- * @param {string} topogramRoot
- * @returns {AnyRecord|null}
- */
-export function readExtractionContext(topogramRoot) {
-  const provenancePath = path.join(path.dirname(topogramRoot), TOPOGRAM_IMPORT_FILE);
-  if (!fs.existsSync(provenancePath)) {
-    return null;
-  }
-  return buildExtractionContext(readJson(provenancePath), provenancePath);
-}
+export { buildExtractionContext, readExtractionContext };
 
 /**
  * @param {AnyRecord} options

package/src/extraction-context.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { TOPOGRAM_IMPORT_FILE } from "./import/provenance.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} record
+ * @param {string} provenancePath
+ * @returns {AnyRecord}
+ */
+export function buildExtractionContext(record, provenancePath) {
+  const extractorPackages = /** @type {AnyRecord[]} */ (Array.isArray(record.extract?.extractorPackages)
+    ? record.extract.extractorPackages
+    : []);
+  const packageBackedExtractors = extractorPackages
+    .filter((entry) => entry?.source === "package")
+    .map((entry) => ({
+      id: entry.id || null,
+      version: entry.version || null,
+      packageName: entry.packageName || null,
+      extractors: Array.isArray(entry.extractors) ? entry.extractors : [],
+      tracks: Array.isArray(entry.tracks) ? entry.tracks : [],
+      manifestPath: entry.manifestPath || null
+    }));
+  const bundledExtractors = extractorPackages
+    .filter((entry) => entry?.source === "bundled")
+    .map((entry) => ({
+      id: entry.id || null,
+      version: entry.version || null,
+      extractors: Array.isArray(entry.extractors) ? entry.extractors : [],
+      tracks: Array.isArray(entry.tracks) ? entry.tracks : []
+    }));
+  return {
+    type: "extraction_context",
+    provenance_path: provenancePath,
+    kind: record.kind || null,
+    extracted_at: record.extractedAt || null,
+    refreshed_at: record.refreshedAt || null,
+    source_path: record.source?.path || null,
+    tracks: Array.isArray(record.extract?.tracks) ? record.extract.tracks : [],
+    findings_count: record.extract?.findingsCount || 0,
+    candidate_counts: record.extract?.candidateCounts || {},
+    package_backed_extractors: packageBackedExtractors,
+    bundled_extractors: bundledExtractors,
+    summary: {
+      package_backed_extractor_count: packageBackedExtractors.length,
+      bundled_extractor_count: bundledExtractors.length,
+      source_file_count: Array.isArray(record.files) ? record.files.length : 0
+    },
+    next_commands: [
+      "topogram extract check",
+      "topogram extract plan",
+      "topogram adopt --list",
+      "topogram adopt <selector> --dry-run"
+    ],
+    safety_notes: [
+      "Extractor packages are evidence producers only; review candidates before canonical adoption.",
+      "Use dry-run adoption before --write, especially when package-backed extractors contributed candidates."
+    ]
+  };
+}
+
+/**
+ * @param {string} topogramRoot
+ * @returns {AnyRecord|null}
+ */
+export function readExtractionContext(topogramRoot) {
+  const provenancePath = path.join(path.dirname(topogramRoot), TOPOGRAM_IMPORT_FILE);
+  if (!fs.existsSync(provenancePath)) {
+    return null;
+  }
+  return buildExtractionContext(JSON.parse(fs.readFileSync(provenancePath, "utf8")), provenancePath);
+}

package/src/extractor/check.js

@@ -5,6 +5,7 @@ import {
   loadExtractorPackageAdapterForSpec,
   validateExtractorAdapter
 } from "./packages.js";
+import { validateExtractorResult } from "./output.js";
 
 /**
  * @typedef {import("./registry.js").ExtractorManifest} ExtractorManifest
@@ -25,39 +26,6 @@ import {
  * @property {boolean} executesPackageCode
  */
 
-/**
- * @param {any} result
- * @returns {{ ok: boolean, message: string, smoke: { findings: number, candidateKeys: number, diagnostics: number }|null }}
- */
-function validateExtractResult(result) {
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    return { ok: false, message: "extract(context) must return an object", smoke: null };
-  }
-  if (result.findings != null && !Array.isArray(result.findings)) {
-    return { ok: false, message: "extract(context) findings must be an array when present", smoke: null };
-  }
-  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
-    return { ok: false, message: "extract(context) diagnostics must be an array when present", smoke: null };
-  }
-  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
-    return { ok: false, message: "extract(context) result must include a candidates object", smoke: null };
-  }
-  for (const [key, value] of Object.entries(result.candidates)) {
-    if (!Array.isArray(value)) {
-      return { ok: false, message: `extract(context) candidates.${key} must be an array`, smoke: null };
-    }
-  }
-  return {
-    ok: true,
-    message: `extract(context) returned ${Object.keys(result.candidates).length} candidate bucket(s)`,
-    smoke: {
-      findings: Array.isArray(result.findings) ? result.findings.length : 0,
-      candidateKeys: Object.keys(result.candidates).length,
-      diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
-    }
-  };
-}
-
 /**
  * @param {string} sourceSpec
  * @param {{ cwd?: string }} [options]
@@ -126,9 +94,9 @@ export function checkExtractorPack(sourceSpec, options = {}) {
         continue;
       }
       const result = extractor.extract(context) || { findings: [], candidates: {} };
-      const validation = validateExtractResult(result);
+      const validation = validateExtractorResult(result, { track: extractor.track, strictCandidates: true });
       if (!validation.ok || !validation.smoke) {
-        payload.errors.push(`Extractor '${extractor.id}' ${validation.message}.`);
+        payload.errors.push(...validation.errors.map((message) => `Extractor '${extractor.id}' ${message}.`));
         continue;
       }
       totalFindings += validation.smoke.findings;
@@ -152,4 +120,3 @@ export function checkExtractorPack(sourceSpec, options = {}) {
   payload.ok = payload.errors.length === 0;
   return payload;
 }
-

package/src/extractor/output.js

@@ -0,0 +1,220 @@
+// @ts-check
+
+/**
+ * @typedef {Object} ExtractorResultValidationOptions
+ * @property {string} [track]
+ * @property {boolean} [strictCandidates]
+ */
+
+/**
+ * @typedef {Object} ExtractorResultValidation
+ * @property {boolean} ok
+ * @property {string[]} errors
+ * @property {{ findings: number, candidateKeys: number, diagnostics: number }|null} smoke
+ */
+
+/** @type {Record<string, Set<string>>} */
+const TRACK_CANDIDATE_BUCKETS = {
+  db: new Set(["entities", "enums", "relations", "indexes", "maintained_seams"]),
+  api: new Set(["capabilities", "routes", "stacks"]),
+  ui: new Set(["screens", "routes", "actions", "flows", "widgets", "shapes", "stacks"]),
+  cli: new Set(["commands", "capabilities", "surfaces"]),
+  workflows: new Set(["workflows", "workflow_states", "workflow_transitions"]),
+  verification: new Set(["verifications", "scenarios", "frameworks", "scripts"])
+};
+
+const DISALLOWED_BUCKETS = new Set([
+  "adoption",
+  "adoption_plan",
+  "adoptionPlan",
+  "canonical",
+  "canonical_files",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "project_config",
+  "projectConfig",
+  "topo",
+  "topogram",
+  "topogram_project",
+  "topogramProject",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+const DISALLOWED_RECORD_KEYS = new Set([
+  "adoption",
+  "adoptionPlan",
+  "canonical",
+  "canonicalFiles",
+  "files",
+  "patches",
+  "receipt",
+  "topo",
+  "topogram",
+  "write",
+  "writeFiles",
+  "writes",
+  "writtenFiles"
+]);
+
+/**
+ * Keys that carry local source/package file references. Deliberately excludes
+ * command/route `path` and config target dotted `path` values.
+ */
+const PATH_KEYS = new Set([
+  "configFile",
+  "configPath",
+  "file",
+  "filePath",
+  "migrationPath",
+  "migrationsPath",
+  "schemaPath",
+  "snapshotPath",
+  "sourceFile",
+  "sourcePath",
+  "source_path",
+  "targetFile",
+  "targetPath"
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {string} candidatePath
+ * @returns {boolean}
+ */
+function isUnsafeRelativePath(candidatePath) {
+  return candidatePath.startsWith("/") || candidatePath === ".." || candidatePath.startsWith("../") || candidatePath.includes("/../");
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @returns {string[]}
+ */
+function identityFieldsForBucket(bucket, candidate) {
+  if (bucket === "commands") return ["command_id", "id_hint"];
+  if (bucket === "routes") {
+    if (typeof candidate.method === "string" && typeof candidate.path === "string") {
+      return [];
+    }
+    return ["id_hint", "id"];
+  }
+  return ["id_hint", "id", "name"];
+}
+
+/**
+ * @param {string} bucket
+ * @param {Record<string, unknown>} candidate
+ * @param {string} pathLabel
+ * @returns {string[]}
+ */
+function validateCandidateIdentity(bucket, candidate, pathLabel) {
+  const fields = identityFieldsForBucket(bucket, candidate);
+  if (fields.length === 0) return [];
+  if (fields.some((field) => typeof candidate[field] === "string" && String(candidate[field]).trim().length > 0)) {
+    return [];
+  }
+  return [`${pathLabel} must include an identity field: ${fields.join(" or ")}`];
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} pathLabel
+ * @param {string[]} errors
+ * @returns {void}
+ */
+function validateNoUnsafeRecords(value, pathLabel, errors) {
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      validateNoUnsafeRecords(value[index], `${pathLabel}[${index}]`, errors);
+    }
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const childPath = `${pathLabel}.${key}`;
+    if (DISALLOWED_RECORD_KEYS.has(key)) {
+      errors.push(`${childPath} is not allowed in extractor candidate output; extractors emit review candidates, not adoption plans or files.`);
+      continue;
+    }
+    if (PATH_KEYS.has(key) && typeof child === "string" && isUnsafeRelativePath(child)) {
+      errors.push(`${childPath} must be a safe project-relative path.`);
+      continue;
+    }
+    validateNoUnsafeRecords(child, childPath, errors);
+  }
+}
+
+/**
+ * @param {unknown} result
+ * @param {ExtractorResultValidationOptions} [options]
+ * @returns {ExtractorResultValidation}
+ */
+export function validateExtractorResult(result, options = {}) {
+  const errors = [];
+  if (!isPlainObject(result)) {
+    return { ok: false, errors: ["extract(context) must return an object"], smoke: null };
+  }
+  if (result.findings != null && !Array.isArray(result.findings)) {
+    errors.push("extract(context) findings must be an array when present");
+  }
+  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
+    errors.push("extract(context) diagnostics must be an array when present");
+  }
+  if (!isPlainObject(result.candidates)) {
+    errors.push("extract(context) result must include a candidates object");
+    return { ok: false, errors, smoke: null };
+  }
+
+  const allowedBuckets = options.track ? TRACK_CANDIDATE_BUCKETS[options.track] : null;
+  const candidateKeys = Object.keys(result.candidates);
+  for (const [bucket, value] of Object.entries(result.candidates)) {
+    const bucketLabel = `extract(context) candidates.${bucket}`;
+    if (DISALLOWED_BUCKETS.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed; extractors must not return adoption plans, canonical files, patches, or topo writes.`);
+      continue;
+    }
+    if (options.strictCandidates && allowedBuckets && !allowedBuckets.has(bucket)) {
+      errors.push(`${bucketLabel} is not allowed for track '${options.track}'.`);
+      continue;
+    }
+    if (!Array.isArray(value)) {
+      errors.push(`${bucketLabel} must be an array`);
+      continue;
+    }
+    if (!options.strictCandidates) continue;
+    for (let index = 0; index < value.length; index += 1) {
+      const candidate = value[index];
+      const candidateLabel = `${bucketLabel}[${index}]`;
+      if (!isPlainObject(candidate)) {
+        errors.push(`${candidateLabel} must be an object.`);
+        continue;
+      }
+      errors.push(...validateCandidateIdentity(bucket, candidate, candidateLabel));
+      validateNoUnsafeRecords(candidate, candidateLabel, errors);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    smoke: errors.length === 0
+      ? {
+          findings: Array.isArray(result.findings) ? result.findings.length : 0,
+          candidateKeys: candidateKeys.length,
+          diagnostics: Array.isArray(result.diagnostics) ? result.diagnostics.length : 0
+        }
+      : null
+  };
+}
+
+export { TRACK_CANDIDATE_BUCKETS };

package/src/extractor/packages.js

@@ -228,13 +228,19 @@ export function packageExtractorsForContext(context) {
     const bundledPack = getBundledExtractorPack(spec);
     if (bundledPack) {
       extractors.push(...bundledPack.extractors);
-      provenance.push({ source: "bundled", id: bundledPack.manifest.id, version: bundledPack.manifest.version, extractors: bundledPack.manifest.extractors });
+      provenance.push({
+        source: "bundled",
+        id: bundledPack.manifest.id,
+        version: bundledPack.manifest.version,
+        tracks: bundledPack.manifest.tracks || [],
+        extractors: bundledPack.manifest.extractors
+      });
       continue;
     }
     const bundledExtractor = getBundledExtractorById(spec);
     if (bundledExtractor) {
       extractors.push(bundledExtractor);
-      provenance.push({ source: "bundled", id: bundledExtractor.id, version: "1", extractors: [bundledExtractor.id] });
+      provenance.push({ source: "bundled", id: bundledExtractor.id, version: "1", tracks: bundledExtractor.track ? [bundledExtractor.track] : [], extractors: [bundledExtractor.id] });
       continue;
     }
     const packageManifest = loadExtractorPackageManifestForSpec(spec, { cwd });
@@ -273,6 +279,7 @@ export function packageExtractorsForContext(context) {
       id: packageManifest.manifest.id,
       version: packageManifest.manifest.version,
       packageName,
+      tracks: packageManifest.manifest.tracks || [],
       manifestPath: packageManifest.manifestPath,
       packageRoot: packageManifest.packageRoot,
       extractors: packageManifest.manifest.extractors

package/src/extractor/scaffold.js

@@ -457,6 +457,11 @@ npm run check
 Replace the scaffold adapter in \`index.cjs\` with precise, read-only source evidence.
 Extractor packages must not mutate source files, write canonical \`topo/**\`, install
 packages, perform network access, or define adoption semantics.
+
+Candidate output is validated by track. Return only review candidate buckets for
+the declared track, give each candidate a stable identity, keep file evidence
+project-relative, and never return files, patches, adoption plans, or write
+instructions.
 `
   };
   for (const [relative, contents] of Object.entries(defaults.fixtureFiles)) {

package/src/import/core/runner/tracks.js

@@ -3,6 +3,7 @@
 import { getEnrichersForTrack, getExtractorsForTrack } from "../registry.js";
 import { normalizeCandidatesForTrack } from "./candidates.js";
 import { packageExtractorsForContext } from "../../../extractor/packages.js";
+import { validateExtractorResult } from "../../../extractor/output.js";
 
 /**
  * @param {any} context
@@ -140,25 +141,12 @@ function initialCandidatesForTrack(track) {
  */
 function assertExtractorResultShape(extractor, result) {
   const label = extractor?.id || "unknown";
-  if (!result || typeof result !== "object" || Array.isArray(result)) {
-    throw new Error(`Extractor '${label}' extract(context) must return an object.`);
-  }
-  if (result.findings != null && !Array.isArray(result.findings)) {
-    throw new Error(`Extractor '${label}' extract(context) findings must be an array when present.`);
-  }
-  if (result.diagnostics != null && !Array.isArray(result.diagnostics)) {
-    throw new Error(`Extractor '${label}' extract(context) diagnostics must be an array when present.`);
-  }
-  if (result.candidates == null) {
-    result.candidates = {};
-  }
-  if (!result.candidates || typeof result.candidates !== "object" || Array.isArray(result.candidates)) {
-    throw new Error(`Extractor '${label}' extract(context) candidates must be an object.`);
-  }
-  for (const [key, value] of Object.entries(result.candidates)) {
-    if (!Array.isArray(value)) {
-      throw new Error(`Extractor '${label}' extract(context) candidates.${key} must be an array.`);
-    }
+  const validation = validateExtractorResult(result, {
+    track: extractor?.track,
+    strictCandidates: extractor?.source === "package"
+  });
+  if (!validation.ok) {
+    throw new Error(validation.errors.map((message) => `Extractor '${label}' ${message}.`).join("\n"));
   }
 }