@topogram/cli 0.3.85 → 0.3.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topogram/cli",
-  "version": "0.3.85",
+  "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/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