@topogram/cli 0.3.80 → 0.3.82

package/package.json

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

package/src/agent-ops/query-builders/common.js

@@ -15,6 +15,8 @@ export function summarizeDiffArtifact(diffArtifact) {
     review_boundary_change_count: (diffArtifact.review_boundary_changes || []).length,
     maintained_file_count: (diffArtifact.affected_maintained_surfaces?.maintained_files_in_scope || []).length,
     affected_verification_count: (diffArtifact.affected_verifications || []).length,
+    widget_migration_count: (diffArtifact.widget_contract_migration_plan?.widgets || []).length,
+    widget_migration_projection_count: (diffArtifact.widget_contract_migration_plan?.affected_projection_ids || []).length,
     affected_output_count: maintainedOutputs.length,
     affected_seam_count: maintainedSeams.length,
     highest_maintained_severity: highestMaintainedSeverity

package/src/cli/command-parsers/sdlc.js

@@ -19,6 +19,9 @@ export function parseSdlcCommandArgs(args) {
   if (args[0] === "sdlc" && args[1] === "prep" && args[2] === "commit") {
     return { sdlcCommand: "prep:commit", inputPath: commandPath(args, 3, ".") };
   }
+  if (args[0] === "sdlc" && args[1] === "audit") {
+    return { sdlcCommand: "audit", inputPath: commandPath(args, 2, ".") };
+  }
   if (args[0] === "sdlc" && args[1] === "link") {
     return {
       sdlcCommand: "link",

package/src/cli/commands/extractor.js

@@ -5,6 +5,7 @@ import path from "node:path";
 
 import { stableStringify } from "../../format.js";
 import { checkExtractorPack } from "../../extractor/check.js";
+import { FIRST_PARTY_EXTRACTOR_PACKAGES, firstPartyExtractorInfo } from "../../extractor/first-party.js";
 import {
   EXTRACTOR_MANIFESTS,
   getExtractorManifest,
@@ -23,6 +24,8 @@ import {
   writeExtractorPolicy
 } from "../../extractor-policy.js";
 
+const EXTRACTOR_TRACK_ORDER = ["db", "api", "ui", "cli", "workflows", "verification", "unknown"];
+
 export function printExtractorHelp() {
   console.log("Usage: topogram extractor list [--json]");
   console.log("   or: topogram extractor show <id-or-package> [--json]");
@@ -43,9 +46,11 @@ export function printExtractorHelp() {
   console.log("Examples:");
   console.log("  topogram extractor list");
   console.log("  topogram extractor show topogram/api-extractors");
+  console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
   console.log("  topogram extractor policy init");
   console.log("  topogram extractor policy pin @topogram/extractor-node-cli@1");
+  console.log("  topogram extract ./express-api --out ./imported-topogram --from api --extractor @topogram/extractor-express-api");
 }
 
 /**
@@ -78,27 +83,105 @@ function declaredExtractorPackages(cwd) {
   return [...packages].sort();
 }
 
+/**
+ * @param {string|null|undefined} packageName
+ * @param {string|null|undefined} version
+ * @returns {string|null}
+ */
+function extractorPolicyPinCommand(packageName, version) {
+  return packageName ? `topogram extractor policy pin ${packageName}@${version || "1"}` : null;
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @param {string[]} tracks
+ * @param {string|null|undefined} exampleSource
+ * @returns {string|null}
+ */
+function extractorRunCommand(packageName, tracks, exampleSource) {
+  if (!packageName) {
+    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}`;
+}
+
+/**
+ * @param {Record<string, any>} extractor
+ * @returns {{ id: string|null, package: string|null, label: string|null, source: string, installed: boolean, knownFirstParty: boolean, useWhen: string|null, extractCommand: string|null }}
+ */
+function groupExtractorEntry(extractor) {
+  return {
+    id: extractor.id || null,
+    package: extractor.package || null,
+    label: extractor.label || null,
+    source: extractor.source,
+    installed: Boolean(extractor.installed),
+    knownFirstParty: Boolean(extractor.knownFirstParty),
+    useWhen: extractor.useWhen || null,
+    extractCommand: extractor.extractCommand || null
+  };
+}
+
+/**
+ * @param {Record<string, any>[]} extractors
+ * @returns {Record<string, ReturnType<typeof groupExtractorEntry>[]>}
+ */
+function groupExtractorsByTrack(extractors) {
+  /** @type {Record<string, ReturnType<typeof groupExtractorEntry>[]>} */
+  const groups = {};
+  for (const track of EXTRACTOR_TRACK_ORDER) {
+    groups[track] = [];
+  }
+  for (const extractor of extractors) {
+    const tracks = Array.isArray(extractor.tracks) && extractor.tracks.length > 0 ? extractor.tracks : ["unknown"];
+    for (const track of tracks) {
+      if (!groups[track]) {
+        groups[track] = [];
+      }
+      groups[track].push(groupExtractorEntry(extractor));
+    }
+  }
+  for (const entries of Object.values(groups)) {
+    entries.sort((left, right) => String(left.label || left.id || left.package || "").localeCompare(String(right.label || right.id || right.package || "")));
+  }
+  return Object.fromEntries(Object.entries(groups).filter(([, entries]) => entries.length > 0));
+}
+
 /**
  * @param {any} manifest
  * @param {{ installed?: boolean, manifestPath?: string|null, packageRoot?: string|null, errors?: string[] }} [metadata]
  * @returns {Record<string, any>}
  */
 function extractorManifestSummary(manifest, metadata = {}) {
-  const installCommand = manifest.package ? packageExtractorInstallCommand(manifest.package) : null;
+  const firstParty = firstPartyExtractorInfo(manifest.package || manifest.id);
+  const packageName = manifest.package || null;
+  const tracks = manifest.tracks || [];
+  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 {
     id: manifest.id,
-    version: manifest.version,
-    tracks: manifest.tracks || [],
+    version,
+    label: firstParty?.label || null,
+    tracks,
     extractors: manifest.extractors || [],
     stack: manifest.stack || {},
     capabilities: manifest.capabilities || {},
     candidateKinds: manifest.candidateKinds || [],
     evidenceTypes: manifest.evidenceTypes || [],
+    useWhen: firstParty?.useWhen || null,
+    extracts: firstParty?.extracts || [],
+    knownFirstParty: Boolean(firstParty),
     source: manifest.source,
     loadsAdapter: false,
     executesPackageCode: false,
-    ...(manifest.package ? { package: manifest.package } : {}),
+    ...(packageName ? { package: packageName } : {}),
     ...(installCommand ? { installCommand } : {}),
+    ...(policyPinCommand ? { policyPinCommand } : {}),
+    ...(extractCommand ? { extractCommand } : {}),
+    ...(packageName ? { showCommand: `topogram extractor show ${packageName}` } : {}),
     installed: metadata.installed !== false,
     manifestPath: metadata.manifestPath || null,
     packageRoot: metadata.packageRoot || null,
@@ -106,25 +189,64 @@ function extractorManifestSummary(manifest, metadata = {}) {
   };
 }
 
+/**
+ * @param {typeof FIRST_PARTY_EXTRACTOR_PACKAGES[number]} info
+ * @returns {Record<string, any>}
+ */
+function firstPartyExtractorPlaceholder(info) {
+  return {
+    id: info.id,
+    version: info.version,
+    label: info.label,
+    tracks: info.tracks,
+    extractors: info.extractors,
+    stack: info.stack,
+    capabilities: info.capabilities,
+    candidateKinds: info.candidateKinds,
+    evidenceTypes: info.evidenceTypes,
+    useWhen: info.useWhen,
+    extracts: info.extracts,
+    knownFirstParty: true,
+    source: "package",
+    loadsAdapter: false,
+    executesPackageCode: false,
+    package: info.package,
+    installCommand: packageExtractorInstallCommand(info.package),
+    policyPinCommand: extractorPolicyPinCommand(info.package, info.version),
+    extractCommand: extractorRunCommand(info.package, info.tracks, info.exampleSource),
+    showCommand: `topogram extractor show ${info.package}`,
+    installed: false,
+    manifestPath: null,
+    packageRoot: null,
+    errors: []
+  };
+}
+
 /**
  * @param {string} cwd
- * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], summary: Record<string, number> }}
+ * @returns {{ ok: boolean, cwd: string, extractors: Record<string, any>[], groups: Record<string, ReturnType<typeof groupExtractorEntry>[]>, summary: Record<string, number> }}
  */
 export function buildExtractorListPayload(cwd) {
   const extractors = EXTRACTOR_MANIFESTS
     .map((manifest) => extractorManifestSummary(manifest))
     .sort((left, right) => left.id.localeCompare(right.id));
+  const seenPackages = new Set(extractors.map((extractor) => extractor.package).filter(Boolean));
+  const seenIds = new Set(extractors.map((extractor) => extractor.id).filter(Boolean));
   for (const packageName of declaredExtractorPackages(cwd)) {
     const loaded = loadPackageExtractorManifest(packageName, cwd);
     if (loaded.manifest) {
-      extractors.push(extractorManifestSummary(loaded.manifest, {
+      const summary = extractorManifestSummary(loaded.manifest, {
         installed: true,
         manifestPath: loaded.manifestPath,
         packageRoot: loaded.packageRoot,
         errors: loaded.errors
-      }));
+      });
+      extractors.push(summary);
+      if (summary.package) seenPackages.add(summary.package);
+      if (summary.id) seenIds.add(summary.id);
     } else {
-      extractors.push({
+      const firstParty = firstPartyExtractorInfo(packageName);
+      const fallback = firstParty ? firstPartyExtractorPlaceholder(firstParty) : {
         id: null,
         version: null,
         tracks: [],
@@ -133,26 +255,44 @@ export function buildExtractorListPayload(cwd) {
         capabilities: {},
         candidateKinds: [],
         evidenceTypes: [],
+        useWhen: null,
+        extracts: [],
+        knownFirstParty: false,
         source: "package",
         package: packageName,
         installCommand: packageExtractorInstallCommand(packageName),
+        policyPinCommand: null,
+        extractCommand: null,
+        showCommand: `topogram extractor show ${packageName}`,
         installed: false,
         manifestPath: loaded.manifestPath,
         packageRoot: loaded.packageRoot,
         errors: loaded.errors
-      });
+      };
+      extractors.push({ ...fallback, errors: loaded.errors });
+      seenPackages.add(packageName);
+      if (fallback.id) seenIds.add(fallback.id);
+    }
+  }
+  for (const firstParty of FIRST_PARTY_EXTRACTOR_PACKAGES) {
+    if (!seenPackages.has(firstParty.package) && !seenIds.has(firstParty.id)) {
+      extractors.push(firstPartyExtractorPlaceholder(firstParty));
     }
   }
   extractors.sort((left, right) => String(left.id || left.package || "").localeCompare(String(right.id || right.package || "")));
+  const groups = groupExtractorsByTrack(extractors);
   return {
     ok: extractors.every((extractor) => extractor.errors.length === 0),
     cwd,
     extractors,
+    groups,
     summary: {
       total: extractors.length,
       bundled: extractors.filter((extractor) => extractor.source === "bundled").length,
       package: extractors.filter((extractor) => extractor.source === "package").length,
-      installed: extractors.filter((extractor) => extractor.installed).length
+      installed: extractors.filter((extractor) => extractor.installed).length,
+      knownFirstParty: extractors.filter((extractor) => extractor.knownFirstParty).length,
+      missingFirstParty: extractors.filter((extractor) => extractor.knownFirstParty && !extractor.installed).length
     }
   };
 }
@@ -184,6 +324,10 @@ export function buildExtractorShowPayload(spec, cwd) {
       errors: []
     };
   }
+  const firstParty = firstPartyExtractorInfo(spec);
+  if (firstParty) {
+    return { ok: true, sourceSpec: spec, extractor: firstPartyExtractorPlaceholder(firstParty), errors: [] };
+  }
   return { ok: false, sourceSpec: spec, extractor: null, errors: loaded.errors };
 }
 
@@ -193,23 +337,36 @@ export function buildExtractorShowPayload(spec, cwd) {
  */
 export function printExtractorList(payload) {
   console.log("Topogram extractors");
-  console.log(`Bundled: ${payload.summary.bundled}; package-backed: ${payload.summary.package}; installed: ${payload.summary.installed}`);
+  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("");
-  for (const extractor of payload.extractors) {
-    const id = extractor.id || extractor.package || "unknown";
-    const status = extractor.errors.length > 0
-      ? "invalid"
-      : extractor.source === "package"
-        ? (extractor.installed ? "package installed" : "package missing")
-        : "bundled";
-    console.log(`- ${id}${extractor.version ? `@${extractor.version}` : ""} (${extractor.tracks.join(", ") || "unknown"}, ${status})`);
-    console.log(`  Source: ${extractor.source}`);
-    console.log("  Adapter loaded: no");
-    console.log("  Executes package code: no");
-    console.log(`  Extractors: ${extractor.extractors.join(", ") || "none"}`);
-    if (extractor.package) console.log(`  Package: ${extractor.package}`);
-    if (extractor.installCommand) console.log(`  Install: ${extractor.installCommand}`);
-    for (const error of extractor.errors || []) console.log(`  Error: ${error}`);
+  for (const track of EXTRACTOR_TRACK_ORDER) {
+    const entries = (payload.groups || {})[track] || [];
+    if (entries.length === 0) {
+      continue;
+    }
+    console.log(`${track}:`);
+    for (const entry of entries) {
+      const extractor = /** @type {Record<string, any>} */ (payload.extractors.find((item) => (entry.package && item.package === entry.package) || (entry.id && item.id === entry.id)) || entry);
+      const id = extractor.id || extractor.package || "unknown";
+      const status = extractor.errors.length > 0
+        ? "invalid"
+        : extractor.source === "package"
+          ? (extractor.installed ? "package installed" : "package missing")
+          : "bundled";
+      console.log(`- ${extractor.label ? `${extractor.label} ` : ""}${id}${extractor.version ? `@${extractor.version}` : ""} (${status})`);
+      if (extractor.useWhen) console.log(`  Use: ${extractor.useWhen}`);
+      console.log(`  Source: ${extractor.source}`);
+      console.log("  Adapter loaded: no");
+      console.log("  Executes package code: no");
+      console.log(`  Extractors: ${extractor.extractors.join(", ") || "none"}`);
+      if (extractor.package) console.log(`  Package: ${extractor.package}`);
+      if (extractor.installCommand) console.log(`  Install: ${extractor.installCommand}`);
+      if (extractor.policyPinCommand) console.log(`  Policy: ${extractor.policyPinCommand}`);
+      if (extractor.extractCommand) console.log(`  Extract: ${extractor.extractCommand}`);
+      for (const error of extractor.errors || []) console.log(`  Error: ${error}`);
+    }
+    console.log("");
   }
 }
 
@@ -229,8 +386,14 @@ export function printExtractorShow(payload) {
   console.log(`Source: ${extractor.source}`);
   console.log("Adapter loaded: no");
   console.log("Executes package code: no");
+  if (extractor.label) console.log(`Label: ${extractor.label}`);
+  if (extractor.useWhen) console.log(`Use: ${extractor.useWhen}`);
+  if (extractor.extracts?.length) console.log(`Extracts: ${extractor.extracts.join(", ")}`);
+  console.log(`Installed: ${extractor.installed ? "yes" : "no"}`);
   if (extractor.package) console.log(`Package: ${extractor.package}`);
   if (extractor.installCommand) console.log(`Install: ${extractor.installCommand}`);
+  if (extractor.policyPinCommand) console.log(`Policy: ${extractor.policyPinCommand}`);
+  if (extractor.extractCommand) console.log(`Extract: ${extractor.extractCommand}`);
   if (extractor.manifestPath) console.log(`Manifest: ${extractor.manifestPath}`);
   console.log(`Extractors: ${extractor.extractors.join(", ") || "none"}`);
   console.log(`Candidate kinds: ${extractor.candidateKinds.join(", ") || "none"}`);
@@ -282,6 +445,9 @@ export function buildExtractorPolicyStatusPayload(projectPath) {
       version,
       allowed: extractorPackageAllowed(policy, packageName),
       installed: Boolean(loaded.manifest),
+      knownFirstParty: Boolean(firstPartyExtractorInfo(packageName)),
+      installCommand: packageExtractorInstallCommand(packageName),
+      showCommand: `topogram extractor show ${packageName}`,
       manifestPath: loaded.manifestPath,
       packageRoot: loaded.packageRoot,
       errors: [...loaded.errors, ...diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.message)]
@@ -371,8 +537,12 @@ export function printExtractorPolicyStatus(payload) {
   console.log(`Policy file exists: ${payload.exists ? "yes" : "no"}`);
   console.log(`Default policy active: ${payload.defaulted ? "yes" : "no"}`);
   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.");
   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}`);
+    if (item.showCommand) console.log(`  Show: ${item.showCommand}`);
   }
   for (const diagnostic of payload.diagnostics) {
     console.log(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);

package/src/cli/commands/sdlc.js

@@ -220,6 +220,21 @@ export async function runSdlcCommand(context) {
     return result.ok ? 0 : 1;
   }
 
+  if (commandArgs.sdlcCommand === "audit") {
+    const { auditWorkspace } = await import("../../sdlc/audit.js");
+    const resolved = resolveSdlcWorkspace(sdlcRoot);
+    if (!resolved) {
+      return 1;
+    }
+    const result = auditWorkspace(sdlcRoot, resolved);
+    if (json) {
+      console.log(stableStringify(result));
+    } else {
+      printSdlcAudit(result);
+    }
+    return result.ok ? 0 : 1;
+  }
+
   if (commandArgs.sdlcCommand === "link") {
     const { linkSdlcRecord } = await import("../../sdlc/link.js");
     const result = linkSdlcRecord(sdlcRoot, commandArgs.sdlcFromId, commandArgs.sdlcToId, {
@@ -374,3 +389,30 @@ export async function runSdlcCommand(context) {
 
   throw new Error(`Unknown sdlc command '${commandArgs.sdlcCommand}'`);
 }
+
+/**
+ * @param {AnyRecord} result
+ */
+function printSdlcAudit(result) {
+  console.log("SDLC audit");
+  console.log(`Workspace: ${result.workspaceRoot}`);
+  console.log(`Draft requirements with completed task evidence: ${result.counts?.draftRequirementsWithCompletedTasks || 0}`);
+  console.log(`Draft acceptance criteria with completed task evidence: ${result.counts?.draftAcceptanceCriteriaWithCompletedTasks || 0}`);
+  console.log(`Approved acceptance criteria with draft parent requirements: ${result.counts?.approvedAcceptanceCriteriaWithDraftRequirements || 0}`);
+  console.log(`Done tasks with draft refs: ${result.counts?.doneTasksWithDraftReferences || 0}`);
+  console.log(`Remaining draft backlog: ${result.counts?.remainingDraftPitches || 0} pitch(es), ${result.counts?.remainingDraftRequirements || 0} requirement(s), ${result.counts?.remainingDraftAcceptanceCriteria || 0} acceptance criterion/criteria`);
+  const findings = [
+    ...(result.findings?.draftRequirementsWithCompletedTasks || []),
+    ...(result.findings?.draftAcceptanceCriteriaWithCompletedTasks || []),
+    ...(result.findings?.approvedAcceptanceCriteriaWithDraftRequirements || []),
+    ...(result.findings?.doneTasksWithDraftReferences || [])
+  ];
+  if (findings.length > 0) {
+    console.log("Actionable findings:");
+    for (const finding of findings.slice(0, 10)) {
+      console.log(`- ${finding.id}: ${finding.recommendedCommand || "review status"}`);
+    }
+  } else {
+    console.log("Actionable findings: none");
+  }
+}

package/src/cli/help.js

@@ -19,6 +19,7 @@ export function printUsage(options = {}) {
   console.log("   or: topogram sdlc policy init|check|explain [path] [--json]");
   console.log("   or: topogram sdlc gate [path] --base <ref> --head <ref> [--sdlc-id <id>] [--exemption <text>] [--require-adopted] [--json]");
   console.log("   or: topogram sdlc prep commit [path] [--base <ref> --head <ref>] [--json]");
+  console.log("   or: topogram sdlc audit [path] [--json]");
   console.log("   or: topogram sdlc link <from-id> <to-id> [path] [--write]");
   console.log("   or: topogram sdlc complete <task-id> [path] --verification <verification-id> [--dry-run|--write]");
   console.log("   or: topogram sdlc plan create <task-id> <slug> [path] [--write]");
@@ -94,6 +95,7 @@ export function printUsage(options = {}) {
   console.log("  topogram agent brief");
   console.log("  topogram agent brief --json");
   console.log("  topogram sdlc policy explain");
+  console.log("  topogram sdlc audit . --json");
   console.log("  topogram sdlc prep commit . --base origin/main --head HEAD");
   console.log("  topogram sdlc gate . --require-adopted");
   console.log("  topogram sdlc plan explain plan_example --json");
@@ -107,8 +109,10 @@ export function printUsage(options = {}) {
   console.log("  topogram generator check ./generator-package");
   console.log("  topogram generator policy check");
   console.log("  topogram extractor list");
+  console.log("  topogram extractor show @topogram/extractor-prisma-db");
   console.log("  topogram extractor check ./extractor-package");
   console.log("  topogram extractor policy check");
+  console.log("  topogram extract ./express-api --out ./extracted-topogram --from api --extractor @topogram/extractor-express-api");
   console.log("  topogram generate");
   console.log("  topogram extract ./existing-app --out ./extracted-topogram");
   console.log("  topogram extract diff ./extracted-topogram");

package/src/extractor/first-party.js

@@ -0,0 +1,93 @@
+// @ts-check
+
+export const FIRST_PARTY_EXTRACTOR_PACKAGES = [
+  {
+    package: "@topogram/extractor-prisma-db",
+    id: "@topogram/extractor-prisma-db",
+    version: "1",
+    label: "Prisma DB",
+    tracks: ["db"],
+    stack: { orm: "prisma", domain: "database" },
+    capabilities: { schema: true, migrations: true, maintainedSeams: true },
+    candidateKinds: ["entity", "enum", "relation", "index", "maintained_db_migration_seam"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["db.prisma"],
+    useWhen: "Use for Prisma schema.prisma models plus Prisma migration evidence.",
+    extracts: ["entities", "enums", "relations", "indexes", "maintained DB seam proposals"],
+    exampleSource: "./prisma-app"
+  },
+  {
+    package: "@topogram/extractor-express-api",
+    id: "@topogram/extractor-express-api",
+    version: "1",
+    label: "Express API",
+    tracks: ["api"],
+    stack: { runtime: "node", framework: "express" },
+    capabilities: { routes: true, parameters: true, authHints: true },
+    candidateKinds: ["capability", "route", "stack"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["api.express"],
+    useWhen: "Use for Express route files, routers, params, middleware, and auth hints.",
+    extracts: ["API route candidates", "capability suggestions", "parameter evidence", "auth hints", "stack evidence"],
+    exampleSource: "./express-api"
+  },
+  {
+    package: "@topogram/extractor-drizzle-db",
+    id: "@topogram/extractor-drizzle-db",
+    version: "1",
+    label: "Drizzle DB",
+    tracks: ["db"],
+    stack: { orm: "drizzle", domain: "database" },
+    capabilities: { schema: true, migrations: true, maintainedSeams: true },
+    candidateKinds: ["entity", "enum", "relation", "index", "maintained_db_migration_seam"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["db.drizzle"],
+    useWhen: "Use for Drizzle config, schema modules, table definitions, and migration output.",
+    extracts: ["entities", "relations", "indexes", "maintained DB seam proposals", "schema/migration evidence"],
+    exampleSource: "./drizzle-app"
+  },
+  {
+    package: "@topogram/extractor-node-cli",
+    id: "@topogram/extractor-node-cli",
+    version: "1",
+    label: "Node CLI",
+    tracks: ["cli"],
+    stack: { runtime: "node", domain: "cli" },
+    capabilities: { commands: true, options: true, effects: true },
+    candidateKinds: ["command", "capability", "cli_surface"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["cli.node-package"],
+    useWhen: "Use for Node package CLIs with bin entries, scripts, command modules, and help text.",
+    extracts: ["command candidates", "options", "effects", "CLI surface projections", "capability suggestions"],
+    exampleSource: "./existing-cli"
+  },
+  {
+    package: "@topogram/extractor-react-router",
+    id: "@topogram/extractor-react-router",
+    version: "1",
+    label: "React Router UI",
+    tracks: ["ui"],
+    stack: { framework: "react-router", domain: "ui" },
+    capabilities: { routes: true, screens: true, flows: true, widgets: true },
+    candidateKinds: ["screen", "route", "action", "flow", "widget", "shape", "stack"],
+    evidenceTypes: ["runtime_source", "parser_config"],
+    extractors: ["ui.react-router"],
+    useWhen: "Use for React Router route trees, route modules, screen hints, and non-resource UI flows.",
+    extracts: ["screens", "routes", "flow candidates", "widget evidence", "stack evidence"],
+    exampleSource: "./react-router-app"
+  }
+];
+
+export const FIRST_PARTY_EXTRACTORS_BY_PACKAGE = new Map(FIRST_PARTY_EXTRACTOR_PACKAGES.map((item) => [item.package, item]));
+export const FIRST_PARTY_EXTRACTORS_BY_ID = new Map(FIRST_PARTY_EXTRACTOR_PACKAGES.map((item) => [item.id, item]));
+
+/**
+ * @param {string|null|undefined} value
+ * @returns {typeof FIRST_PARTY_EXTRACTOR_PACKAGES[number]|null}
+ */
+export function firstPartyExtractorInfo(value) {
+  if (!value) {
+    return null;
+  }
+  return FIRST_PARTY_EXTRACTORS_BY_PACKAGE.get(value) || FIRST_PARTY_EXTRACTORS_BY_ID.get(value) || null;
+}

package/src/generator/context/diff.js

@@ -128,6 +128,101 @@ function collectAffectedProjectionIds(graph, baselineGraph, diff) {
   ]);
 }
 
+const WIDGET_CONTRACT_SECTIONS = [
+  "category",
+  "version",
+  "status",
+  "props",
+  "events",
+  "slots",
+  "behavior",
+  "behaviors",
+  "patterns",
+  "regions",
+  "approvals",
+  "lookups",
+  "dependencies"
+];
+
+function changedWidgetContractSections(entry) {
+  if (entry.classification === "additive") {
+    return WIDGET_CONTRACT_SECTIONS.filter((section) => entry.current?.[section] != null);
+  }
+  if (entry.classification === "removed") {
+    return WIDGET_CONTRACT_SECTIONS.filter((section) => entry.baseline?.[section] != null);
+  }
+  return WIDGET_CONTRACT_SECTIONS.filter((section) =>
+    JSON.stringify(entry.current?.[section] ?? null) !== JSON.stringify(entry.baseline?.[section] ?? null)
+  );
+}
+
+function affectedProjectionIdsForWidgetChange(graph, baselineGraph, entry) {
+  if (entry.classification === "additive") {
+    return relatedProjectionsForWidget(graph, entry.id);
+  }
+  if (entry.classification === "removed") {
+    return relatedProjectionsForWidget(baselineGraph, entry.id);
+  }
+  return stableSortedStrings([
+    ...relatedProjectionsForWidget(graph, entry.id),
+    ...relatedProjectionsForWidget(baselineGraph, entry.id)
+  ]);
+}
+
+function projectionMigrationCommands(widgetId, projectionId) {
+  return [
+    {
+      target: "ui-widget-contract",
+      command: `topogram emit ui-widget-contract ./topo --widget ${widgetId} --json`,
+      reason: `Refresh the normalized widget contract for ${widgetId}.`
+    },
+    {
+      target: "widget-conformance-report",
+      command: `topogram emit widget-conformance-report ./topo --projection ${projectionId} --json`,
+      reason: `Review projection ${projectionId} widget placement, required props, events, and region/pattern compatibility.`
+    },
+    {
+      target: "widget-behavior-report",
+      command: `topogram widget behavior ./topo --projection ${projectionId} --widget ${widgetId} --json`,
+      reason: `Review behavior data/event/action wiring for ${widgetId} on projection ${projectionId}.`
+    },
+    {
+      target: "ui-surface-contract",
+      command: `topogram emit ui-surface-contract ./topo --projection ${projectionId} --json`,
+      reason: `Refresh the surface contract consumed by stack generators for projection ${projectionId}.`
+    }
+  ];
+}
+
+function buildWidgetContractMigrationPlan(graph, baselineGraph, diff) {
+  const widgets = (diff.widgets || []).map((entry) => {
+    const affectedProjectionIds = affectedProjectionIdsForWidgetChange(graph, baselineGraph, entry);
+    return {
+      widget_id: entry.id,
+      classification: entry.classification,
+      changed_sections: changedWidgetContractSections(entry),
+      affected_projection_ids: affectedProjectionIds,
+      affected_projections: affectedProjectionIds
+        .map((id) => summarizeById(graph, id) || summarizeById(baselineGraph, id))
+        .filter(Boolean),
+      review_commands: affectedProjectionIds.flatMap((projectionId) => projectionMigrationCommands(entry.id, projectionId)),
+      migration_steps: [
+        "Review changed_sections to understand the semantic widget contract delta.",
+        "Refresh the widget contract and affected surface contracts.",
+        "Run conformance and behavior reports for every affected projection.",
+        "Regenerate generated-owned outputs or manually update maintained surfaces after review."
+      ]
+    };
+  });
+
+  return {
+    widgets,
+    affected_widget_ids: stableSortedStrings(widgets.map((entry) => entry.widget_id)),
+    affected_projection_ids: stableSortedStrings(widgets.flatMap((entry) => entry.affected_projection_ids)),
+    review_command_count: widgets.reduce((count, entry) => count + entry.review_commands.length, 0)
+  };
+}
+
 function collectAffectedCapabilityIds(graph, diff) {
   const changedCapabilities = stableSortedStrings((diff.capabilities || []).map((entry) => entry.id));
   const changedEntities = stableSortedStrings((diff.entities || []).map((entry) => entry.id));
@@ -213,6 +308,7 @@ export function generateContextDiff(graph, options = {}) {
   const affectedCapabilities = collectAffectedCapabilityIds(graph, diff);
   const affectedProjections = collectAffectedProjectionIds(graph, baselineGraph, diff);
   const affectedVerifications = collectAffectedVerificationIds(graph, diff);
+  const widgetContractMigrationPlan = buildWidgetContractMigrationPlan(graph, baselineGraph, diff);
   const changedSemanticIds = changedIdsForDiffSections(diff);
   const affectedMaintainedStories = maintainedProofMetadata(graph).filter((item) => {
     const emittedDependencies = item.emittedDependencies || [];
@@ -257,6 +353,7 @@ export function generateContextDiff(graph, options = {}) {
       }))
     },
     affected_verifications: affectedVerifications.map((id) => summarizeById(graph, id) || summarizeById(baselineGraph, id)).filter(Boolean),
+    widget_contract_migration_plan: widgetContractMigrationPlan,
     review_boundary_changes: reviewBoundaryChangeItems,
     sdlc: sdlcChanges
   };

package/src/generator/registry/index.js

@@ -6,7 +6,11 @@ import {
   packageInstallHint,
   resolvePackageManifestPath
 } from "../../package-adapters/index.js";
-import { UI_GENERATOR_RENDERED_COMPONENT_PATTERNS } from "../../ui/taxonomy.js";
+import {
+  UI_GENERATOR_RENDERED_COMPONENT_PATTERNS,
+  UI_PATTERN_KINDS,
+  WIDGET_BEHAVIOR_KINDS
+} from "../../ui/taxonomy.js";
 
 /**
  * @typedef {Object} GeneratorManifest
@@ -193,6 +197,18 @@ function isStringArray(value, nonEmpty = false) {
     value.every((entry) => typeof entry === "string" && entry.length > 0);
 }
 
+/**
+ * @param {any} value
+ * @param {Set<string>} allowed
+ * @returns {string[]}
+ */
+function unsupportedStringValues(value, allowed) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((entry) => typeof entry === "string" && !allowed.has(entry));
+}
+
 /**
  * @param {string} oldName
  * @param {string} newName
@@ -377,9 +393,15 @@ export function validateGeneratorManifest(manifest) {
       if (manifest.widgetSupport.patterns != null && !isStringArray(manifest.widgetSupport.patterns)) {
         errors.push(`${label} widgetSupport.patterns must be a string array`);
       }
+      for (const pattern of unsupportedStringValues(manifest.widgetSupport.patterns, UI_PATTERN_KINDS)) {
+        errors.push(`${label} widgetSupport.patterns contains unsupported pattern '${pattern}'`);
+      }
       if (manifest.widgetSupport.behaviors != null && !isStringArray(manifest.widgetSupport.behaviors)) {
         errors.push(`${label} widgetSupport.behaviors must be a string array`);
       }
+      for (const behavior of unsupportedStringValues(manifest.widgetSupport.behaviors, WIDGET_BEHAVIOR_KINDS)) {
+        errors.push(`${label} widgetSupport.behaviors contains unsupported behavior '${behavior}'`);
+      }
       if (
         manifest.widgetSupport.unsupported != null &&
         !["error", "warning", "contract-only"].includes(manifest.widgetSupport.unsupported)

package/src/sdlc/audit.js

@@ -0,0 +1,205 @@
+// @ts-check
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+const DONE_TASK_STATUSES = new Set(["done"]);
+
+/**
+ * @param {unknown} refs
+ * @returns {string[]}
+ */
+function refIds(refs) {
+  if (!Array.isArray(refs)) {
+    return [];
+  }
+  return refs
+    .map((ref) => {
+      if (typeof ref === "string") {
+        return ref;
+      }
+      if (ref && typeof ref === "object" && "id" in ref) {
+        return String(ref.id);
+      }
+      return "";
+    })
+    .filter(Boolean);
+}
+
+/**
+ * @param {AnyRecord} statement
+ * @returns {{ id: string, name: string|null, status: string|null, file: string|null }}
+ */
+function summary(statement) {
+  return {
+    id: String(statement.id || ""),
+    name: typeof statement.name === "string" ? statement.name : null,
+    status: typeof statement.status === "string" ? statement.status : null,
+    file: typeof statement.loc?.file === "string" ? statement.loc.file : null
+  };
+}
+
+/**
+ * @param {Map<string, AnyRecord[]>} map
+ * @param {string} key
+ * @param {AnyRecord} value
+ */
+function pushMap(map, key, value) {
+  const values = map.get(key) || [];
+  values.push(value);
+  map.set(key, values);
+}
+
+/**
+ * @param {AnyRecord} graph
+ * @param {string} id
+ * @returns {AnyRecord|null}
+ */
+function byId(graph, id) {
+  const value = graph?.byId?.get ? graph.byId.get(id) : graph?.byId?.[id];
+  if (value && typeof value === "object") {
+    return value;
+  }
+  const byKind = graph?.byKind || {};
+  for (const statements of Object.values(byKind)) {
+    if (!Array.isArray(statements)) {
+      continue;
+    }
+    const found = statements.find((statement) => statement?.id === id);
+    if (found && typeof found === "object") {
+      return found;
+    }
+  }
+  return value && typeof value === "object" ? value : null;
+}
+
+/**
+ * Reports SDLC status hygiene issues that are easy to miss after implementation:
+ * draft requirements or acceptance criteria that already have completed task
+ * evidence, and approved acceptance criteria whose parent requirement is still
+ * draft. The audit is read-only.
+ *
+ * @param {string} workspaceRoot
+ * @param {AnyRecord} resolved
+ * @returns {AnyRecord}
+ */
+export function auditWorkspace(workspaceRoot, resolved) {
+  const graph = resolved.graph || {};
+  const byKind = graph.byKind || {};
+  /** @type {AnyRecord[]} */
+  const tasks = Array.isArray(byKind.task) ? byKind.task : [];
+  /** @type {AnyRecord[]} */
+  const requirements = Array.isArray(byKind.requirement) ? byKind.requirement : [];
+  /** @type {AnyRecord[]} */
+  const acceptanceCriteria = Array.isArray(byKind.acceptance_criterion) ? byKind.acceptance_criterion : [];
+  /** @type {AnyRecord[]} */
+  const pitches = Array.isArray(byKind.pitch) ? byKind.pitch : [];
+
+  const doneTasks = tasks.filter((task) => DONE_TASK_STATUSES.has(String(task.status || "")));
+  /** @type {Map<string, AnyRecord[]>} */
+  const doneTasksByRequirement = new Map();
+  /** @type {Map<string, AnyRecord[]>} */
+  const doneTasksByAcceptance = new Map();
+
+  for (const task of doneTasks) {
+    for (const id of refIds(task.satisfies)) {
+      pushMap(doneTasksByRequirement, id, task);
+    }
+    for (const id of refIds(task.acceptanceRefs)) {
+      pushMap(doneTasksByAcceptance, id, task);
+    }
+  }
+
+  const draftRequirementsWithCompletedTasks = requirements
+    .filter((requirement) => requirement.status === "draft" && doneTasksByRequirement.has(String(requirement.id || "")))
+    .map((requirement) => ({
+      ...summary(requirement),
+      completedTasks: (doneTasksByRequirement.get(String(requirement.id || "")) || []).map(summary),
+      recommendedCommand: `topogram sdlc transition ${requirement.id} in-review . --actor <actor> --note "<reason>"`
+    }));
+
+  const draftAcceptanceCriteriaWithCompletedTasks = acceptanceCriteria
+    .filter((criterion) => criterion.status === "draft" && doneTasksByAcceptance.has(String(criterion.id || "")))
+    .map((criterion) => ({
+      ...summary(criterion),
+      completedTasks: (doneTasksByAcceptance.get(String(criterion.id || "")) || []).map(summary),
+      recommendedCommand: `topogram sdlc transition ${criterion.id} approved . --actor <actor> --note "<reason>"`
+    }));
+
+  const approvedAcceptanceCriteriaWithDraftRequirements = acceptanceCriteria
+    .filter((criterion) => {
+      if (criterion.status !== "approved") {
+        return false;
+      }
+      const requirementId = criterion.requirement?.id || "";
+      const requirement = requirementId ? byId(graph, requirementId) : null;
+      return requirement?.status === "draft";
+    })
+    .map((criterion) => {
+      const requirement = byId(graph, criterion.requirement?.id || "");
+      return {
+        ...summary(criterion),
+        requirement: requirement ? summary(requirement) : null,
+        recommendedCommand: requirement
+          ? `topogram sdlc transition ${requirement.id} in-review . --actor <actor> --note "<reason>"`
+          : null
+      };
+    });
+
+  const doneTasksWithDraftReferences = doneTasks
+    .map((task) => {
+      const draftRequirements = refIds(task.satisfies)
+        .map((id) => byId(graph, id))
+        .filter((statement) => statement?.status === "draft")
+        .map((statement) => summary(/** @type {AnyRecord} */ (statement)));
+      const draftAcceptanceCriteria = refIds(task.acceptanceRefs)
+        .map((id) => byId(graph, id))
+        .filter((statement) => statement?.status === "draft")
+        .map((statement) => summary(/** @type {AnyRecord} */ (statement)));
+      return {
+        ...summary(task),
+        draftRequirements,
+        draftAcceptanceCriteria
+      };
+    })
+    .filter((task) => task.draftRequirements.length > 0 || task.draftAcceptanceCriteria.length > 0);
+
+  const counts = {
+    draftRequirementsWithCompletedTasks: draftRequirementsWithCompletedTasks.length,
+    draftAcceptanceCriteriaWithCompletedTasks: draftAcceptanceCriteriaWithCompletedTasks.length,
+    approvedAcceptanceCriteriaWithDraftRequirements: approvedAcceptanceCriteriaWithDraftRequirements.length,
+    doneTasksWithDraftReferences: doneTasksWithDraftReferences.length,
+    remainingDraftPitches: pitches.filter((pitch) => pitch.status === "draft").length,
+    remainingDraftRequirements: requirements.filter((requirement) => requirement.status === "draft").length,
+    remainingDraftAcceptanceCriteria: acceptanceCriteria.filter((criterion) => criterion.status === "draft").length
+  };
+  const actionableFindings =
+    counts.draftRequirementsWithCompletedTasks +
+    counts.draftAcceptanceCriteriaWithCompletedTasks +
+    counts.approvedAcceptanceCriteriaWithDraftRequirements +
+    counts.doneTasksWithDraftReferences;
+
+  return {
+    type: "sdlc_audit",
+    version: "1",
+    ok: actionableFindings === 0,
+    workspaceRoot,
+    counts,
+    findings: {
+      draftRequirementsWithCompletedTasks,
+      draftAcceptanceCriteriaWithCompletedTasks,
+      approvedAcceptanceCriteriaWithDraftRequirements,
+      doneTasksWithDraftReferences
+    },
+    remainingDrafts: {
+      pitches: pitches.filter((pitch) => pitch.status === "draft").map(summary),
+      requirements: requirements.filter((requirement) => requirement.status === "draft").map(summary),
+      acceptanceCriteria: acceptanceCriteria.filter((criterion) => criterion.status === "draft").map(summary)
+    },
+    nextCommands: [
+      "topogram sdlc check --strict",
+      "topogram sdlc prep commit . --json"
+    ]
+  };
+}

package/src/topogram-config.js

@@ -16,8 +16,17 @@ export const DEFAULT_FIRST_PARTY_GENERATOR_REPOS = [
   "topogram-generator-vanilla-web"
 ];
 
+export const DEFAULT_FIRST_PARTY_EXTRACTOR_REPOS = [
+  "topogram-extractor-node-cli",
+  "topogram-extractor-react-router",
+  "topogram-extractor-prisma-db",
+  "topogram-extractor-express-api",
+  "topogram-extractor-drizzle-db"
+];
+
 export const DEFAULT_RELEASE_CONSUMER_REPOS = [
   ...DEFAULT_FIRST_PARTY_GENERATOR_REPOS,
+  ...DEFAULT_FIRST_PARTY_EXTRACTOR_REPOS,
   "topogram-starters",
   "topogram-template-todo",
   "topogram-demo-todo",
@@ -34,6 +43,11 @@ export const DEFAULT_RELEASE_CONSUMER_WORKFLOWS = {
   "topogram-generator-sveltekit-web": "Generator Verification",
   "topogram-generator-swiftui-native": "Generator Verification",
   "topogram-generator-vanilla-web": "Generator Verification",
+  "topogram-extractor-node-cli": "Extractor Verification",
+  "topogram-extractor-react-router": "Extractor Verification",
+  "topogram-extractor-prisma-db": "Extractor Verification",
+  "topogram-extractor-express-api": "Extractor Verification",
+  "topogram-extractor-drizzle-db": "Extractor Verification",
   "topogram-starters": "Starter Verification",
   "topogram-template-todo": "Template Verification",
   "topogram-demo-todo": "Demo Verification",

package/src/ui/taxonomy.js

@@ -155,6 +155,51 @@ export const UI_GENERATOR_RENDERED_COMPONENT_PATTERNS = new Set([
   "data_grid_view"
 ]);
 
+export const WIDGET_CATEGORIES = new Set([
+  "collection",
+  "form",
+  "display",
+  "navigation",
+  "dialog",
+  "feedback",
+  "lookup",
+  "layout",
+  "service"
+]);
+
+export const WIDGET_BEHAVIOR_KINDS = new Set([
+  "selection",
+  "sorting",
+  "filtering",
+  "search",
+  "pagination",
+  "grouping",
+  "drag_drop",
+  "inline_edit",
+  "bulk_action",
+  "optimistic_update",
+  "realtime_update",
+  "keyboard_navigation"
+]);
+
+export const WIDGET_BEHAVIOR_DIRECTIVES = {
+  selection: new Set(["mode", "state", "emits"]),
+  sorting: new Set(["fields", "default"]),
+  filtering: new Set(["fields"]),
+  search: new Set(["fields"]),
+  pagination: new Set(["mode", "page_size"]),
+  grouping: new Set(["fields"]),
+  drag_drop: new Set(["axis", "reorder"]),
+  inline_edit: new Set(["fields", "submit", "emits"]),
+  bulk_action: new Set(["actions", "state", "emits"]),
+  optimistic_update: new Set(["actions", "rollback"]),
+  realtime_update: new Set(["source", "merge"]),
+  keyboard_navigation: new Set(["scope", "shortcuts"])
+};
+
+export const WIDGET_SELECTION_MODES = new Set(["single", "multi", "none"]);
+export const WIDGET_PAGINATION_MODES = new Set(["cursor", "paged", "infinite", "none"]);
+
 /**
  * @param {string[]} presentations
  * @returns {string}

package/src/validator/kinds.d.ts

@@ -47,4 +47,9 @@ export const UI_DESIGN_COLOR_ROLES: Set<string>;
 export const UI_DESIGN_TYPOGRAPHY_ROLES: Set<string>;
 export const UI_DESIGN_ACTION_ROLES: Set<string>;
 export const UI_DESIGN_ACCESSIBILITY_VALUES: Record<string, Set<string>>;
+export const WIDGET_CATEGORIES: Set<string>;
+export const WIDGET_BEHAVIOR_KINDS: Set<string>;
+export const WIDGET_BEHAVIOR_DIRECTIVES: Record<string, Set<string>>;
+export const WIDGET_SELECTION_MODES: Set<string>;
+export const WIDGET_PAGINATION_MODES: Set<string>;
 export const FIELD_SPECS: Record<string, { required: string[]; allowed: string[] }>;

package/src/validator/kinds.js

@@ -107,7 +107,12 @@ export {
   UI_DESIGN_COLOR_ROLES,
   UI_DESIGN_TYPOGRAPHY_ROLES,
   UI_DESIGN_ACTION_ROLES,
-  UI_DESIGN_ACCESSIBILITY_VALUES
+  UI_DESIGN_ACCESSIBILITY_VALUES,
+  WIDGET_CATEGORIES,
+  WIDGET_BEHAVIOR_KINDS,
+  WIDGET_BEHAVIOR_DIRECTIVES,
+  WIDGET_SELECTION_MODES,
+  WIDGET_PAGINATION_MODES
 } from "../ui/taxonomy.js";
 
 // Kinds that may carry an optional singular `domain dom_x` field. Keep this

package/src/validator/per-kind/widget.js

@@ -1,5 +1,10 @@
 // @ts-check
 import {
+  WIDGET_BEHAVIOR_DIRECTIVES,
+  WIDGET_BEHAVIOR_KINDS,
+  WIDGET_CATEGORIES,
+  WIDGET_PAGINATION_MODES,
+  WIDGET_SELECTION_MODES,
   UI_PATTERN_KINDS,
   UI_REGION_KINDS
 } from "../kinds.js";
@@ -10,49 +15,6 @@ import {
   symbolValues
 } from "../utils.js";
 
-const WIDGET_CATEGORIES = new Set([
-  "collection",
-  "form",
-  "display",
-  "navigation",
-  "dialog",
-  "feedback",
-  "lookup",
-  "layout",
-  "service"
-]);
-
-const WIDGET_BEHAVIOR_KINDS = new Set([
-  "selection",
-  "sorting",
-  "filtering",
-  "search",
-  "pagination",
-  "grouping",
-  "drag_drop",
-  "inline_edit",
-  "bulk_action",
-  "optimistic_update",
-  "realtime_update",
-  "keyboard_navigation"
-]);
-
-/** @type {Record<string, Set<string>>} */
-const WIDGET_BEHAVIOR_DIRECTIVES = {
-  selection: new Set(["mode", "state", "emits"]),
-  sorting: new Set(["fields", "default"]),
-  filtering: new Set(["fields"]),
-  search: new Set(["fields"]),
-  pagination: new Set(["mode", "page_size"]),
-  grouping: new Set(["fields"]),
-  drag_drop: new Set(["axis", "reorder"]),
-  inline_edit: new Set(["fields", "submit", "emits"]),
-  bulk_action: new Set(["actions", "state", "emits"]),
-  optimistic_update: new Set(["actions", "rollback"]),
-  realtime_update: new Set(["source", "merge"]),
-  keyboard_navigation: new Set(["scope", "shortcuts"])
-};
-
 /** @param {TopogramToken | null | undefined} token @returns {any} */
 function tokenValue(token) {
   return token?.value ?? null;
@@ -262,10 +224,10 @@ function validateWidgetBehaviors(errors, statement, fieldMap, registry) {
       if (directive === "actions" || directive === "submit") {
         validateBehaviorActionReferences(errors, statement, registry, kind, directive, valueToken, eventNames);
       }
-      if (kind === "selection" && directive === "mode" && !["single", "multi", "none"].includes(tokenValue(valueToken))) {
+      if (kind === "selection" && directive === "mode" && !WIDGET_SELECTION_MODES.has(tokenValue(valueToken))) {
         pushError(errors, `Widget ${statement.id} behavior 'selection' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
       }
-      if (kind === "pagination" && directive === "mode" && !["cursor", "paged", "infinite", "none"].includes(tokenValue(valueToken))) {
+      if (kind === "pagination" && directive === "mode" && !WIDGET_PAGINATION_MODES.has(tokenValue(valueToken))) {
         pushError(errors, `Widget ${statement.id} behavior 'pagination' has invalid mode '${tokenValue(valueToken)}'`, valueToken.loc);
       }
     }