@topogram/cli 0.3.78 → 0.3.80

package/src/cli/help.js

@@ -35,17 +35,18 @@ export function printUsage(options = {}) {
   console.log("   or: topogram catalog show <id> [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram catalog doctor [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram catalog check <path-or-url> [--json]");
-  console.log("   or: topogram catalog copy <id> <target> [--version <version>] [--json] [--catalog <path-or-source>]");
   console.log("   or: topogram package update-cli <version|--latest> [--json]");
-  console.log("   or: topogram import <app-path> --out <target> [--from <track[,track]>] [--json]");
-  console.log("   or: topogram import refresh [path] [--from <app-path>] [--dry-run] [--json]");
-  console.log("   or: topogram import diff [path] [--json]");
-  console.log("   or: topogram import check [path] [--json]");
-  console.log("   or: topogram import plan [path] [--json]");
-  console.log("   or: topogram import adopt --list [path] [--json]");
-  console.log("   or: topogram import adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
-  console.log("   or: topogram import status [path] [--json]");
-  console.log("   or: topogram import history [path] [--verify] [--json]");
+  console.log("   or: topogram copy <source> <target> [--version <version>] [--catalog <path-or-source>] [--json]");
+  console.log("   or: topogram copy --list [--json] [--catalog <path-or-source>]");
+  console.log("   or: topogram extract <app-path> --out <target> [--from <track[,track]>] [--extractor <id-or-package-or-path>] [--json]");
+  console.log("   or: topogram extract refresh [path] [--from <app-path>] [--dry-run] [--json]");
+  console.log("   or: topogram extract diff [path] [--json]");
+  console.log("   or: topogram extract check [path] [--json]");
+  console.log("   or: topogram extract plan [path] [--json]");
+  console.log("   or: topogram adopt --list [path] [--json]");
+  console.log("   or: topogram adopt <selector> [path] [--dry-run|--write] [--force --reason <text>] [--json]");
+  console.log("   or: topogram extract status [path] [--json]");
+  console.log("   or: topogram extract history [path] [--verify] [--json]");
   console.log("   or: topogram source status [path] [--local|--remote] [--json]");
   console.log("   or: topogram template list [--json]");
   console.log("   or: topogram template explain [path] [--json]");
@@ -66,9 +67,15 @@ export function printUsage(options = {}) {
   console.log("   or: topogram generator policy check [path] [--json]");
   console.log("   or: topogram generator policy explain [path] [--json]");
   console.log("   or: topogram generator policy pin [package@version] [path] [--json]");
-  console.log("   or: topogram new <path> [--template hello-web|todo|./local-template|@scope/template]");
-  console.log("   or: topogram new <path> --template <package> --allow-local-npmrc");
-  console.log("   or: topogram new --list-templates [--json] [--catalog <path-or-source>]");
+  console.log("   or: topogram extractor list [--json]");
+  console.log("   or: topogram extractor show <id-or-package> [--json]");
+  console.log("   or: topogram extractor check <path-or-package> [--json]");
+  console.log("   or: topogram extractor policy init [path] [--json]");
+  console.log("   or: topogram extractor policy status [path] [--json]");
+  console.log("   or: topogram extractor policy check [path] [--json]");
+  console.log("   or: topogram extractor policy explain [path] [--json]");
+  console.log("   or: topogram extractor policy pin [package@version] [path] [--json]");
+  console.log("   or: topogram init [path] [--with-sdlc] [--json]");
   console.log("");
   console.log("Common commands:");
   console.log("  topogram version");
@@ -76,9 +83,10 @@ export function printUsage(options = {}) {
   console.log("  topogram setup package-auth");
   console.log("  topogram release status");
   console.log("  topogram release roll-consumers --latest");
-  console.log("  topogram new ./my-app");
-  console.log("  topogram new --list-templates");
-  console.log("  topogram new ./my-app --template todo");
+  console.log("  topogram init .");
+  console.log("  topogram copy --list");
+  console.log("  topogram copy hello-web ./my-app");
+  console.log("  topogram copy todo ./todo-app");
   console.log("  topogram check");
   console.log("  topogram check --json");
   console.log("  topogram widget check --projection proj_web_surface");
@@ -98,22 +106,26 @@ export function printUsage(options = {}) {
   console.log("  topogram generator show @topogram/generator-react-web");
   console.log("  topogram generator check ./generator-package");
   console.log("  topogram generator policy check");
+  console.log("  topogram extractor list");
+  console.log("  topogram extractor check ./extractor-package");
+  console.log("  topogram extractor policy check");
   console.log("  topogram generate");
-  console.log("  topogram import ./existing-app --out ./imported-topogram");
-  console.log("  topogram import diff ./imported-topogram");
-  console.log("  topogram import refresh ./imported-topogram --from ./existing-app --dry-run");
-  console.log("  topogram import check ./imported-topogram");
-  console.log("  topogram import plan ./imported-topogram");
-  console.log("  topogram import adopt --list ./imported-topogram");
-  console.log("  topogram import adopt bundle:task ./imported-topogram --dry-run");
-  console.log("  topogram import status ./imported-topogram");
-  console.log("  topogram import history ./imported-topogram --verify");
+  console.log("  topogram extract ./existing-app --out ./extracted-topogram");
+  console.log("  topogram extract diff ./extracted-topogram");
+  console.log("  topogram extract refresh ./extracted-topogram --from ./existing-app --dry-run");
+  console.log("  topogram extract check ./extracted-topogram");
+  console.log("  topogram extract plan ./extracted-topogram");
+  console.log("  topogram adopt --list ./extracted-topogram");
+  console.log("  topogram adopt bundle:task ./extracted-topogram --dry-run");
+  console.log("  topogram extract status ./extracted-topogram");
+  console.log("  topogram extract history ./extracted-topogram --verify");
   console.log("");
   console.log("Fresh install:");
   console.log("  npm install --save-dev @topogram/cli");
   console.log("  npx topogram doctor");
   console.log("  npx topogram template list");
-  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("  npx topogram init .");
+  console.log("  npx topogram copy hello-web ./my-app");
   console.log("  cd ./my-app && npm install && npm run check && npm run generate");
   console.log("  npm --prefix app run compile");
   console.log("");
@@ -123,7 +135,7 @@ export function printUsage(options = {}) {
   console.log("  topogram catalog show todo");
   console.log("  topogram catalog doctor");
   console.log("  topogram catalog check topograms.catalog.json");
-  console.log("  topogram catalog copy hello ./hello-topogram");
+  console.log("  topogram copy hello ./hello-topogram");
   console.log("  topogram source status --local");
   console.log("  topogram source status --remote");
   console.log("");
@@ -149,7 +161,7 @@ export function printUsage(options = {}) {
   console.log("  topogram template update --apply");
   console.log("");
   console.log("Defaults: check/generate use ./topo, and generate writes ./app.");
-  console.log("Default starter: hello-web from the catalog. Run `topogram template list` for catalog aliases.");
+  console.log("Default starter: hello-web from the catalog. Run `topogram copy --list` for catalog aliases.");
   console.log("Generated app commands are emitted into the output package.json.");
   console.log("Run `topogram help <command>` for command-specific help.");
   console.log("Run `topogram help all` for legacy and agent-facing commands.");
@@ -157,16 +169,12 @@ export function printUsage(options = {}) {
     return;
   }
   console.log("");
-  console.log("Legacy and internal commands:");
-  console.log("Usage: topogram create <path> [--template hello-web|todo|./local-template|@scope/template]");
+  console.log("Internal commands:");
   console.log("   or: topogram template show <id> [--json] [--catalog <path-or-source>]");
-  console.log("   or: topogram import app <path> [--from <track[,track]>] [--write]");
   console.log("   or: topogram validate <path>");
-  console.log("   or: node ./src/cli.js query work-packet <path> --mode import-adopt --lane <id>");
+  console.log("   or: node ./src/cli.js query work-packet <path> --mode extract-adopt --lane <id>");
   console.log("   or: node ./src/cli.js <path> [--json] [--validate] [--resolve] [--workflow <name>] [--mode <id>] [--from <track[,track]>] [--adopt <selector>] [--refresh-adopted] [--shape <id>] [--capability <id>] [--widget <id>] [--projection <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--task <id>] [--profile <id>] [--from-snapshot <path>] [--from-topogram <path>] [--write] [--out-dir <path>]");
   console.log("   or: node ./src/cli.js emit <target> [path] [--json] [--write] [--out-dir <path>]");
-  console.log("   or: node ./src/cli.js import app <path> [--from <track[,track]>] [--write]");
-  console.log("   or: node ./src/cli.js import docs <path> [--write]");
   console.log("   or: node ./src/cli.js generate journeys <path> [--write]");
   console.log("   or: node ./src/cli.js report gaps <path> [--write]");
   console.log("   or: node ./src/cli.js query task-mode <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--from-topogram <path>]");
@@ -184,56 +192,75 @@ export function printUsage(options = {}) {
   console.log("   or: node ./src/cli.js query verification-targets <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query widget-behavior <path> [--projection <id>] [--widget <id>] [--json]");
   console.log("   or: node ./src/cli.js query change-plan <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
-  console.log("   or: node ./src/cli.js query import-plan <path>");
+  console.log("   or: node ./src/cli.js query extract-plan <path>");
   console.log("   or: node ./src/cli.js query risk-summary <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query canonical-writes <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query proceed-decision <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query review-packet <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query next-action <path> [--mode <id>] [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query single-agent-plan <path> --mode <id> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--task <id>] [--plan <id>] [--bug <id>] [--from-topogram <path>]");
-  console.log("   or: node ./src/cli.js query multi-agent-plan <path> --mode import-adopt");
+  console.log("   or: node ./src/cli.js query multi-agent-plan <path> --mode extract-adopt");
   console.log("   or: node ./src/cli.js query resolved-workflow-context <path> --mode <id> [--capability <id>] [--workflow <id>] [--projection <id>] [--widget <id>] [--entity <id>] [--journey <id>] [--surface <id>] [--provider <id>] [--preset <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query workflow-preset-activation <path> --mode <id> [--provider <id>] [--preset <id>] [--from-topogram <path>]");
   console.log("   or: node ./src/cli.js query workflow-preset-diff <path> --provider <id> [--preset <id>]");
   console.log("   or: node ./src/cli.js query workflow-preset-customization <path> --provider <id> --preset <id>");
   console.log("   or: node ./src/cli.js workflow-preset customize <path> --provider <id> --preset <id> [--out <path>] [--write]");
-  console.log("   or: node ./src/cli.js query lane-status <path> --mode import-adopt");
-  console.log("   or: node ./src/cli.js query handoff-status <path> --mode import-adopt");
+  console.log("   or: node ./src/cli.js query lane-status <path> --mode extract-adopt");
+  console.log("   or: node ./src/cli.js query handoff-status <path> --mode extract-adopt");
   console.log("   or: node ./src/cli.js query auth-hints <path>");
   console.log("   or: node ./src/cli.js query auth-review-packet <path> --bundle <slug>");
   console.log("   or: node ./src/cli.js reconcile <path> [--write]");
   console.log("   or: node ./src/cli.js reconcile adopt <selector> <path> [--refresh-adopted] [--write]");
   console.log("   or: node ./src/cli.js adoption status <path> [--write]");
   console.log("Targets: json-schema, docs, docs-index, verification-plan, verification-checklist, shape-transform-graph, shape-transform-debug, api-contract-graph, api-contract-debug, ui-contract-graph, ui-contract-debug, ui-widget-contract, widget-conformance-report, widget-behavior-report, ui-surface-contract, ui-surface-debug, sveltekit-app, swiftui-app, db-contract-graph, db-contract-debug, db-schema-snapshot, db-migration-plan, db-lifecycle-plan, db-lifecycle-bundle, environment-plan, environment-bundle, deployment-plan, deployment-bundle, runtime-smoke-plan, runtime-smoke-bundle, runtime-check-plan, runtime-check-bundle, compile-check-plan, compile-check-bundle, app-bundle-plan, app-bundle, native-parity-plan, native-parity-bundle, sql-migration, sql-schema, prisma-schema, drizzle-schema, persistence-scaffold, server-contract, hono-server, openapi, context-digest, context-diff, context-slice, context-bundle, context-report, context-task-mode");
-  console.log("Workflows: import-app, scan-docs, reconcile, adoption-status, generate-docs, generate-journeys, refresh-docs, report-gaps");
-  console.log("Import tracks: db, api, ui, workflows, verification");
+  console.log("Workflows: scan-docs, reconcile, adoption-status, generate-docs, generate-journeys, refresh-docs, report-gaps");
+  console.log("Extract tracks: db, api, ui, cli, workflows, verification");
   console.log("Reconcile adopt selectors: from-plan, actors, roles, enums, shapes, entities, capabilities, widgets, docs, journeys, workflows, ui, bundle:<slug>, projection-review:<id>, ui-review:<id>, workflow-review:<id>, bundle-review:<slug>");
 }
 
 /**
  * @returns {void}
  */
-export function printNewHelp() {
-  console.log("Usage: topogram new <path> [--template <alias|package|path>] [--catalog <path-or-source>]");
-  console.log("   or: topogram new --list-templates [--json] [--catalog <path-or-source>]");
+export function printCopyHelp() {
+  console.log("Usage: topogram copy <source> <target> [--version <version>] [--catalog <path-or-source>] [--json]");
+  console.log("   or: topogram copy --list [--json] [--catalog <path-or-source>]");
   console.log("");
-  console.log("Creates a new editable Topogram workspace from a template package or local template path.");
+  console.log("Copies a catalog template, template package/path, or pure Topogram source into a new project directory.");
   console.log("");
   console.log("Fresh install flow:");
   console.log("  npm install --save-dev @topogram/cli");
-  console.log("  npx topogram template list");
-  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("  npx topogram copy --list");
+  console.log("  npx topogram copy hello-web ./my-app");
   console.log("  cd ./my-app && npm install && npm run check && npm run generate");
   console.log("  npm --prefix app run compile");
   console.log("");
   console.log("Examples:");
-  console.log("  topogram new ./my-app");
-  console.log("  topogram new --list-templates");
-  console.log("  topogram new ./my-app --template hello-web");
-  console.log("  topogram new ./my-app --template ./local-template");
-  console.log("  topogram new ./my-app --template @scope/topogram-template");
+  console.log("  topogram copy --list");
+  console.log("  topogram copy hello-web ./my-app");
+  console.log("  topogram copy todo ./todo-app");
+  console.log("  topogram copy ./local-template ./my-app");
+  console.log("  topogram copy @scope/topogram-template ./my-app");
+  console.log("");
+  console.log("Template entries create starter projects. Topogram entries copy editable topo/ source.");
+}
+
+/**
+ * @returns {void}
+ */
+export function printInitHelp() {
+  console.log("Usage: topogram init [path] [--with-sdlc] [--json]");
+  console.log("");
+  console.log("Initializes an empty Topogram workspace in an existing or new repository without copying a template.");
   console.log("");
-  console.log("Default template: hello-web from the configured catalog.");
+  console.log("Defaults: path is the current directory. Init creates topo/, topogram.project.json, and starter guidance files only when they are missing.");
+  console.log("The default output is maintained ownership for '.', so Topogram will not overwrite app source.");
+  console.log("--with-sdlc also writes topogram.sdlc-policy.json with adopted/enforced defaults.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram init");
+  console.log("  topogram init . --with-sdlc");
+  console.log("  topogram init . --json");
+  console.log("  topogram init ./existing-app");
 }
 
 /**

package/src/cli/migration-guidance.js

@@ -30,6 +30,15 @@ export function cliMigrationError(args) {
   if (args[0] === "component") {
     return "Command 'topogram component' was renamed to 'topogram widget'.";
   }
+  if (args[0] === "new" || args[0] === "create") {
+    return "Command 'topogram new' was replaced by 'topogram copy <source> <target>'. For example: topogram copy hello-web ./my-app.";
+  }
+  if (args[0] === "import") {
+    return "Command 'topogram import' was replaced by 'topogram extract' and top-level 'topogram adopt'.";
+  }
+  if (args[0] === "catalog" && args[1] === "copy") {
+    return "Command 'topogram catalog copy' was replaced by 'topogram copy <source> <target>'.";
+  }
   if (args[0] === "migrate") {
     return "Command 'topogram migrate workspace-folder' was removed. Use topo/ workspaces or configure topogram.project.json workspace to a non-legacy relative path.";
   }

package/src/cli/options.js

@@ -22,6 +22,21 @@ export function optionValueIfPresent(args, flag) {
   return value && !value.startsWith("-") ? value : null;
 }
 
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @returns {string[]}
+ */
+export function optionValues(args, flag) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1] && !args[index + 1].startsWith("-")) {
+      values.push(args[index + 1]);
+    }
+  }
+  return values;
+}
+
 /**
  * @param {string[]} args
  * @param {string} flag
@@ -51,6 +66,8 @@ export function parseCliOptions(args, commandArgs) {
     workflowName: commandArgs?.workflowName || (!generateTarget && workflowFlagValue ? workflowFlagValue : null),
     workflowId: generateTarget ? workflowFlagValue : null,
     fromValue: optionValue(args, "--from"),
+    extractorSpecs: optionValues(args, "--extractor"),
+    extractorPolicyPath: optionValueIfPresent(args, "--extractor-policy"),
     adoptValue: commandArgs?.adoptValue || optionValue(args, "--adopt"),
     reasonValue: optionValueIfPresent(args, "--reason"),
     modeId: optionValue(args, "--mode"),

package/src/extractor/check.js

@@ -0,0 +1,155 @@
+// @ts-check
+
+import {
+  createExtractorSmokeContext,
+  loadExtractorPackageAdapterForSpec,
+  validateExtractorAdapter
+} from "./packages.js";
+
+/**
+ * @typedef {import("./registry.js").ExtractorManifest} ExtractorManifest
+ */
+
+/**
+ * @typedef {Object} ExtractorCheckResult
+ * @property {boolean} ok
+ * @property {string} sourceSpec
+ * @property {"path"|"package"} source
+ * @property {string|null} packageName
+ * @property {string|null} packageRoot
+ * @property {string|null} manifestPath
+ * @property {ExtractorManifest|null} manifest
+ * @property {Array<{ name: string, ok: boolean, message: string }>} checks
+ * @property {string[]} errors
+ * @property {{ extractors: number, findings: number, candidateKeys: number, diagnostics: number }|null} smoke
+ * @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]
+ * @returns {ExtractorCheckResult}
+ */
+export function checkExtractorPack(sourceSpec, options = {}) {
+  /** @type {ExtractorCheckResult} */
+  const payload = {
+    ok: false,
+    sourceSpec,
+    source: "package",
+    packageName: null,
+    packageRoot: null,
+    manifestPath: null,
+    manifest: null,
+    checks: [],
+    errors: [],
+    smoke: null,
+    executesPackageCode: true
+  };
+  if (!sourceSpec || sourceSpec.startsWith("-")) {
+    payload.errors.push("Usage: topogram extractor check <path-or-package>");
+    payload.checks.push({ name: "source", ok: false, message: payload.errors[0] });
+    return payload;
+  }
+
+  const loaded = loadExtractorPackageAdapterForSpec(sourceSpec, options);
+  payload.source = loaded.source;
+  payload.packageName = loaded.packageName;
+  payload.packageRoot = loaded.packageRoot;
+  payload.manifestPath = loaded.manifestPath;
+  payload.manifest = loaded.manifest;
+  if (!loaded.manifest) {
+    payload.errors.push(...loaded.errors);
+    payload.checks.push({ name: "manifest-load", ok: false, message: loaded.errors.join(" ") || "Could not load extractor manifest." });
+    return payload;
+  }
+  payload.checks.push({ name: "manifest-load", ok: true, message: loaded.manifestPath || sourceSpec });
+  if (!loaded.adapter || loaded.errors.length > 0) {
+    payload.errors.push(...loaded.errors);
+    payload.checks.push({ name: "adapter-load", ok: false, message: loaded.errors.join(" ") || "Could not load extractor adapter." });
+    return payload;
+  }
+  payload.checks.push({ name: "adapter-load", ok: true, message: "Adapter export loaded." });
+
+  const adapterValidation = validateExtractorAdapter(loaded.adapter, loaded.manifest);
+  payload.checks.push({
+    name: "adapter-shape",
+    ok: adapterValidation.errors.length === 0,
+    message: adapterValidation.errors.length === 0 ? "Adapter shape is valid." : adapterValidation.errors.join(" ")
+  });
+  if (adapterValidation.errors.length > 0) {
+    payload.errors.push(...adapterValidation.errors);
+    return payload;
+  }
+
+  const context = createExtractorSmokeContext();
+  let totalFindings = 0;
+  let totalCandidateKeys = 0;
+  let totalDiagnostics = 0;
+  for (const extractor of adapterValidation.extractors) {
+    try {
+      const detection = extractor.detect(context) || { score: 0, reasons: [] };
+      if (!detection || typeof detection !== "object" || typeof detection.score !== "number") {
+        payload.errors.push(`Extractor '${extractor.id}' detect(context) must return { score, reasons }.`);
+        continue;
+      }
+      const result = extractor.extract(context) || { findings: [], candidates: {} };
+      const validation = validateExtractResult(result);
+      if (!validation.ok || !validation.smoke) {
+        payload.errors.push(`Extractor '${extractor.id}' ${validation.message}.`);
+        continue;
+      }
+      totalFindings += validation.smoke.findings;
+      totalCandidateKeys += validation.smoke.candidateKeys;
+      totalDiagnostics += validation.smoke.diagnostics;
+    } catch (error) {
+      payload.errors.push(`Extractor '${extractor.id}' smoke failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  payload.checks.push({
+    name: "smoke-extract",
+    ok: payload.errors.length === 0,
+    message: payload.errors.length === 0 ? `Ran ${adapterValidation.extractors.length} extractor smoke check(s).` : payload.errors.join(" ")
+  });
+  payload.smoke = {
+    extractors: adapterValidation.extractors.length,
+    findings: totalFindings,
+    candidateKeys: totalCandidateKeys,
+    diagnostics: totalDiagnostics
+  };
+  payload.ok = payload.errors.length === 0;
+  return payload;
+}
+