@topogram/cli 0.3.75 → 0.3.77

package/src/import/extractors/db/maintained-seams.js

@@ -0,0 +1,231 @@
+// @ts-check
+
+import path from "node:path";
+
+import { findImportFiles, isPrimaryImportSource, makeCandidateRecord, relativeTo } from "../../core/shared.js";
+
+/** @param {string} value @returns {string} */
+function toPosix(value) {
+  return String(value || "").replaceAll(path.sep, "/");
+}
+
+/** @param {any} context @param {string} filePath @returns {string} */
+function appRelativePath(context, filePath) {
+  return toPosix(relativeTo(context.paths.workspaceRoot, filePath));
+}
+
+/** @param {any} context @param {string} filePath @returns {string} */
+function evidencePath(context, filePath) {
+  return toPosix(relativeTo(context.paths.repoRoot, filePath));
+}
+
+/** @param {string} relativePath @param {string[]} segments @returns {string|null} */
+function prefixThroughSegments(relativePath, segments) {
+  const parts = toPosix(relativePath).split("/");
+  for (let index = 0; index <= parts.length - segments.length; index += 1) {
+    if (segments.every((segment, offset) => parts[index + offset] === segment)) {
+      return parts.slice(0, index + segments.length).join("/");
+    }
+  }
+  return null;
+}
+
+/** @param {string} relativePath @returns {string|null} */
+function migrationDirectoryFromRelativePath(relativePath) {
+  return prefixThroughSegments(relativePath, ["migrations"]) ||
+    prefixThroughSegments(relativePath, ["migration"]);
+}
+
+/** @param {any} context @param {string[]} files @param {string[][]} markers @returns {string|null} */
+function firstMarkedDirectory(context, files, markers) {
+  const directories = new Set();
+  for (const filePath of files) {
+    const relativePath = appRelativePath(context, filePath);
+    for (const marker of markers) {
+      const directory = prefixThroughSegments(relativePath, marker);
+      if (directory) {
+        directories.add(directory);
+      }
+    }
+  }
+  return [...directories].sort()[0] || null;
+}
+
+/** @param {any} context @param {string[]} configFiles @returns {string|null} */
+function drizzleOutPathFromConfig(context, configFiles) {
+  for (const configFile of configFiles.sort()) {
+    const configText = context.helpers.readTextIfExists(configFile) || "";
+    const outMatch = configText.match(/\bout\s*:\s*["'`]([^"'`]+)["'`]/);
+    if (!outMatch) {
+      continue;
+    }
+    const absoluteOut = path.resolve(path.dirname(configFile), outMatch[1]);
+    const relativeOut = appRelativePath(context, absoluteOut);
+    if (relativeOut && !relativeOut.startsWith("..")) {
+      return relativeOut;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {any} context
+ * @param {{ tool: "sql"|"prisma"|"drizzle", schemaPath?: string|null, migrationsPath?: string|null, evidence: string[], matchReasons: string[], missingDecisions: string[] }} options
+ * @returns {any}
+ */
+function maintainedDbSeamCandidate(context, options) {
+  const runtimeId = "app_db";
+  const projectionId = "proj_db";
+  const snapshotPath = `topo/state/db/${runtimeId}/current.snapshot.json`;
+  const proposedRuntimeMigration = {
+    ownership: "maintained",
+    tool: options.tool,
+    apply: "never",
+    snapshotPath,
+    ...(options.schemaPath ? { schemaPath: options.schemaPath } : {}),
+    ...(options.migrationsPath ? { migrationsPath: options.migrationsPath } : {})
+  };
+  const idHint = `seam_${options.tool}_db_migrations`;
+  const manualNextSteps = [
+    "Review evidence, match_reasons, and missing_decisions before accepting this seam.",
+    `Confirm database runtime '${runtimeId}' and projection '${projectionId}' are the right topology targets for the maintained app.`,
+    "If accepted, copy proposed_runtime_migration into the matching database runtime's migration block in topogram.project.json.",
+    "Keep ownership 'maintained' and apply 'never'; import must not apply migrations or patch maintained app files.",
+    "After editing topogram.project.json, run topogram check . --json and the maintained app's migration verification."
+  ];
+
+  return makeCandidateRecord({
+    kind: "maintained_db_migration_seam",
+    idHint,
+    label: `${options.tool.toUpperCase()} maintained database migrations`,
+    confidence: options.missingDecisions.length === 0 ? "high" : "medium",
+    sourceKind: "migration_strategy_inference",
+    sourceOfTruth: "candidate",
+    provenance: options.evidence,
+    track: "db",
+    seam_id: idHint,
+    output_id: "maintained_app",
+    ownership_class: "human_owned",
+    status: "review_required",
+    tool: options.tool,
+    ownership: "maintained",
+    apply: "never",
+    schemaPath: options.schemaPath || null,
+    migrationsPath: options.migrationsPath || null,
+    snapshotPath,
+    runtime_id_hint: runtimeId,
+    projection_id_hint: projectionId,
+    evidence: options.evidence,
+    match_reasons: options.matchReasons,
+    missing_decisions: options.missingDecisions,
+    proposed_runtime_migration: proposedRuntimeMigration,
+    manual_next_steps: manualNextSteps,
+    project_config_target: {
+      file: "topogram.project.json",
+      path: `topology.runtimes[id=${runtimeId}].migration`,
+      runtime_id: runtimeId,
+      projection_id: projectionId
+    },
+    maintained_modules: [options.schemaPath, options.migrationsPath].filter(Boolean),
+    emitted_dependencies: [snapshotPath, projectionId],
+    allowed_change_classes: ["proposal_only"],
+    drift_signals: ["schema_or_migration_changed", "migration_directory_changed"]
+  });
+}
+
+/** @param {any} context @param {string[]} prismaFiles @returns {any[]} */
+export function inferPrismaMaintainedDbSeams(context, prismaFiles) {
+  if (!prismaFiles.length) {
+    return [];
+  }
+  const schemaPath = appRelativePath(context, prismaFiles[0]);
+  const migrationFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    toPosix(filePath).includes("/prisma/migrations/") &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
+  const migrationsPath = firstMarkedDirectory(context, migrationFiles, [["prisma", "migrations"]]);
+  return [
+    maintainedDbSeamCandidate(context, {
+      tool: "prisma",
+      schemaPath,
+      migrationsPath,
+      evidence: [
+        ...prismaFiles.map((filePath) => evidencePath(context, filePath)),
+        ...migrationFiles.slice(0, 3).map(/** @param {string} filePath */ (filePath) => evidencePath(context, filePath))
+      ],
+      matchReasons: [
+        "found Prisma schema",
+        ...(migrationsPath ? ["found Prisma migrations directory"] : [])
+      ],
+      missingDecisions: migrationsPath ? [] : ["confirm Prisma migrationsPath before adding this strategy to topogram.project.json"]
+    })
+  ];
+}
+
+/** @param {any} context @param {string[]} schemaFiles @returns {any[]} */
+export function inferDrizzleMaintainedDbSeams(context, schemaFiles) {
+  if (!schemaFiles.length) {
+    return [];
+  }
+  const configFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    /drizzle\.config\.(ts|js|mjs|cjs)$/i.test(path.basename(filePath)) &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
+  const drizzleFiles = /** @type {string[]} */ (findImportFiles(context.paths, /** @param {string} filePath */ (filePath) =>
+    appRelativePath(context, filePath).startsWith("drizzle/") &&
+    isPrimaryImportSource(context.paths, filePath)
+  ));
+  const configuredOutPath = drizzleOutPathFromConfig(context, configFiles);
+  const migrationsPath = configuredOutPath ||
+    firstMarkedDirectory(context, drizzleFiles, [["drizzle"]]);
+  return [
+    maintainedDbSeamCandidate(context, {
+      tool: "drizzle",
+      schemaPath: appRelativePath(context, schemaFiles[0]),
+      migrationsPath,
+      evidence: [
+        ...schemaFiles.map((filePath) => evidencePath(context, filePath)),
+        ...configFiles.map(/** @param {string} filePath */ (filePath) => evidencePath(context, filePath)),
+        ...drizzleFiles.slice(0, 3).map(/** @param {string} filePath */ (filePath) => evidencePath(context, filePath))
+      ],
+      matchReasons: [
+        "found Drizzle schema source",
+        ...(configFiles.length ? ["found Drizzle config"] : []),
+        ...(migrationsPath ? ["found Drizzle migrations output"] : [])
+      ],
+      missingDecisions: migrationsPath ? [] : ["confirm Drizzle migrationsPath before adding this strategy to topogram.project.json"]
+    })
+  ];
+}
+
+/** @param {any} context @param {string[]} allSqlFiles @param {string[]} selectedSqlFiles @returns {any[]} */
+export function inferSqlMaintainedDbSeams(context, allSqlFiles, selectedSqlFiles) {
+  if (!allSqlFiles.length) {
+    return [];
+  }
+  const schemaFile = selectedSqlFiles.find((filePath) => !/migration/i.test(path.basename(filePath))) ||
+    allSqlFiles.find((filePath) => /schema/i.test(path.basename(filePath))) ||
+    null;
+  const migrationFiles = allSqlFiles.filter((filePath) => {
+    const relativePath = appRelativePath(context, filePath);
+    return Boolean(migrationDirectoryFromRelativePath(relativePath)) || /migration/i.test(path.basename(filePath));
+  });
+  const migrationsPath = firstMarkedDirectory(context, migrationFiles, [["migrations"], ["migration"]]) ||
+    (migrationFiles.length ? toPosix(path.dirname(appRelativePath(context, migrationFiles[0]))) : null);
+  return [
+    maintainedDbSeamCandidate(context, {
+      tool: "sql",
+      schemaPath: schemaFile ? appRelativePath(context, schemaFile) : null,
+      migrationsPath,
+      evidence: [
+        ...(schemaFile ? [evidencePath(context, schemaFile)] : []),
+        ...migrationFiles.slice(0, 3).map((filePath) => evidencePath(context, filePath))
+      ],
+      matchReasons: [
+        ...(schemaFile ? ["found SQL schema"] : []),
+        ...(migrationsPath ? ["found SQL migrations directory or migration file"] : [])
+      ],
+      missingDecisions: migrationsPath ? [] : ["confirm SQL migrationsPath before adding this strategy to topogram.project.json"]
+    })
+  ];
+}

package/src/import/extractors/db/prisma.js

@@ -1,5 +1,6 @@
 import {
   findImportFiles,
+  isPrimaryImportSource,
   makeCandidateRecord,
   normalizePrismaType,
   relativeTo,
@@ -8,6 +9,7 @@ import {
   titleCase,
   idHintify
 } from "../../core/shared.js";
+import { inferPrismaMaintainedDbSeams } from "./maintained-seams.js";
 
 function parsePrismaSchema(schemaText) {
   const enums = [];
@@ -112,7 +114,10 @@ export const prismaExtractor = {
   id: "db.prisma",
   track: "db",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma"));
+    const files = findImportFiles(context.paths, (filePath) =>
+      (filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")) &&
+      isPrimaryImportSource(context.paths, filePath)
+    );
     return {
       score: files.length > 0 ? 100 : 0,
       reasons: files.length > 0 ? ["Found Prisma schema"] : []
@@ -121,11 +126,14 @@ export const prismaExtractor = {
   extract(context) {
     const prismaFiles = selectPreferredImportFiles(
       context.paths,
-      findImportFiles(context.paths, (filePath) => filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")),
+      findImportFiles(context.paths, (filePath) =>
+        (filePath.endsWith("/prisma/schema.prisma") || filePath.endsWith("prisma/schema.prisma")) &&
+        isPrimaryImportSource(context.paths, filePath)
+      ),
       "prisma"
     );
     const findings = [];
-    const candidates = { entities: [], enums: [], relations: [], indexes: [] };
+    const candidates = { entities: [], enums: [], relations: [], indexes: [], maintained_seams: [] };
     for (const filePath of prismaFiles) {
       const parsed = parsePrismaSchema(context.helpers.readTextIfExists(filePath) || "");
       const provenance = relativeTo(context.paths.repoRoot, filePath);
@@ -179,7 +187,7 @@ export const prismaExtractor = {
         track: "db"
       })));
     }
+    candidates.maintained_seams = inferPrismaMaintainedDbSeams(context, prismaFiles);
     return { findings, candidates };
   }
 };
-

package/src/import/extractors/db/sql.js

@@ -1,4 +1,5 @@
-import { canonicalCandidateTerm, findImportFiles, makeCandidateRecord, relativeTo, selectPreferredImportFiles, slugify, titleCase, idHintify } from "../../core/shared.js";
+import { canonicalCandidateTerm, findImportFiles, isPrimaryImportSource, makeCandidateRecord, relativeTo, selectPreferredImportFiles, slugify, titleCase, idHintify } from "../../core/shared.js";
+import { inferSqlMaintainedDbSeams } from "./maintained-seams.js";
 
 function parseTableConstraint(line, tableName) {
   const normalized = line.replace(/,$/, "").trim();
@@ -104,14 +105,14 @@ export const sqlExtractor = {
   id: "db.sql",
   track: "db",
   detect(context) {
-    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql"));
+    const files = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql") && isPrimaryImportSource(context.paths, filePath));
     return {
       score: files.length > 0 ? 80 : 0,
       reasons: files.length > 0 ? ["Found SQL schema or migration files"] : []
     };
   },
   extract(context) {
-    const allSqlFiles = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql"));
+    const allSqlFiles = findImportFiles(context.paths, (filePath) => filePath.endsWith(".sql") && isPrimaryImportSource(context.paths, filePath));
     const schemaSqlFiles = allSqlFiles.filter((filePath) => !/migration/i.test(filePath) && !/\/src\/test\//i.test(filePath));
     const migrationSqlFiles = allSqlFiles.filter((filePath) => /migration/i.test(filePath));
     const sqlFiles =
@@ -119,7 +120,7 @@ export const sqlExtractor = {
         ? selectPreferredImportFiles(context.paths, schemaSqlFiles, "sql")
         : selectPreferredImportFiles(context.paths, migrationSqlFiles, "sql");
     const findings = [];
-    const candidates = { entities: [], enums: [], relations: [], indexes: [] };
+    const candidates = { entities: [], enums: [], relations: [], indexes: [], maintained_seams: [] };
     for (const filePath of sqlFiles) {
       const parsed = parseSqlSchema(context.helpers.readTextIfExists(filePath) || "");
       const provenance = relativeTo(context.paths.repoRoot, filePath);
@@ -175,6 +176,7 @@ export const sqlExtractor = {
         track: "db"
       })));
     }
+    candidates.maintained_seams = inferSqlMaintainedDbSeams(context, allSqlFiles, sqlFiles);
     return { findings, candidates };
   }
 };

package/src/import/extractors/ui/next-app-router.js

@@ -1,4 +1,4 @@
-import { dedupeCandidateRecords, inferNextAppRoutes, makeCandidateRecord, nextScreenIdForRoute, nextScreenKindForRoute, uiCapabilityHintsForNextRoute, entityIdForNextRoute, conceptIdForNextRoute, relativeTo, titleCase, idHintify } from "../../core/shared.js";
+import { dedupeCandidateRecords, inferNextAppRoutes, inferNonResourceUiFlow, makeCandidateRecord, nextScreenIdForRoute, nextScreenKindForRoute, proposedUiContractAdditionsForFlow, uiCapabilityHintsForNextRoute, entityIdForNextRoute, conceptIdForNextRoute, relativeTo, titleCase, idHintify, uiFlowIdForRoute } from "../../core/shared.js";
 
 export const nextAppRouterUiExtractor = {
   id: "ui.next-app-router",
@@ -13,7 +13,7 @@ export const nextAppRouterUiExtractor = {
   extract(context) {
     const routes = inferNextAppRoutes(context.paths.workspaceRoot, context.helpers);
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     if (routes.length > 0) {
       findings.push({
         kind: "next_app_routes",
@@ -26,9 +26,10 @@ export const nextAppRouterUiExtractor = {
         const provenance = `${relativeTo(context.paths.repoRoot, route.file)}#${route.path}`;
         const screenId = nextScreenIdForRoute(route.path);
         const screenKind = nextScreenKindForRoute(route.path);
-        const capabilityHints = uiCapabilityHintsForNextRoute(route.path);
-        const entityId = entityIdForNextRoute(route.path);
-        const conceptId = conceptIdForNextRoute(route.path);
+        const flow = inferNonResourceUiFlow(route.path);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForNextRoute(route.path);
+        const entityId = flow ? null : entityIdForNextRoute(route.path);
+        const conceptId = flow?.concept_id || conceptIdForNextRoute(route.path);
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
@@ -56,6 +57,25 @@ export const nextAppRouterUiExtractor = {
           concept_id: conceptId,
           path: route.path
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(route.path, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [route.path],
+            evidence: [provenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(route.path, screenId, screenKind)
+          }));
+        }
         if (capabilityHints.primary_action) {
           candidates.actions.push(makeCandidateRecord({
             kind: "ui_action",
@@ -77,6 +97,7 @@ export const nextAppRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/next-pages-router.js

@@ -3,9 +3,12 @@ import path from "node:path";
 import {
   dedupeCandidateRecords,
   findImportFiles,
+  inferNonResourceUiFlow,
   makeCandidateRecord,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   titleCase,
+  uiFlowIdForRoute,
   idHintify
 } from "../../core/shared.js";
 
@@ -70,7 +73,7 @@ export const nextPagesRouterUiExtractor = {
     const pageFiles = findImportFiles(context.paths, (filePath) => /src\/pages\/.+\.(tsx|ts|jsx|js|mdx)$/i.test(filePath))
       .filter((filePath) => !/\/api\//.test(filePath) && !/\/_(app|document|error)\./.test(filePath) && !/\/404\./.test(filePath));
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     if (pageFiles.length > 0) {
       const routes = [];
       for (const filePath of pageFiles) {
@@ -78,6 +81,7 @@ export const nextPagesRouterUiExtractor = {
         const text = context.helpers.readTextIfExists(filePath) || "";
         const hooks = inferTrpcHooks(text);
         const screen = screenFromRouteAndHooks(routePath, hooks);
+        const flow = inferNonResourceUiFlow(routePath);
         const provenance = `${relativeTo(context.paths.repoRoot, filePath)}#${routePath}`;
         routes.push(routePath);
         candidates.screens.push(makeCandidateRecord({
@@ -88,11 +92,11 @@ export const nextPagesRouterUiExtractor = {
           sourceKind: "route_code",
           provenance,
           track: "ui",
-          entity_id: screen.entity,
-          concept_id: screen.concept,
-          screen_kind: screen.kind,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
+          screen_kind: flow ? "flow" : screen.kind,
           route_path: routePath,
-          capability_hints: hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
+          capability_hints: flow ? [] : hooks.map((hook) => capabilityHint(hook.router, hook.procedure))
         }));
         candidates.routes.push(makeCandidateRecord({
           kind: "ui_route",
@@ -103,10 +107,29 @@ export const nextPagesRouterUiExtractor = {
           provenance,
           track: "ui",
           screen_id: screen.id,
-          entity_id: screen.entity,
-          concept_id: screen.concept,
+          entity_id: flow ? null : screen.entity,
+          concept_id: flow?.concept_id || screen.concept,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screen.id),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screen.id],
+            route_paths: [routePath],
+            evidence: [provenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screen.id, "flow")
+          }));
+        }
         for (const hook of hooks.filter((hook) => hook.hook === "Mutation")) {
           const capability = capabilityHint(hook.router, hook.procedure);
           candidates.actions.push(makeCandidateRecord({
@@ -135,6 +158,7 @@ export const nextPagesRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/react-router.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferReactRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase,
   idHintify
@@ -29,7 +32,7 @@ export const reactRouterUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web"),
       path.join(context.paths.workspaceRoot, "examples", "maintained", "proof-app")
@@ -75,16 +78,20 @@ export const reactRouterUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -95,12 +102,32 @@ export const reactRouterUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
         if (capabilityHints.primary_action) {
           candidates.actions.push(makeCandidateRecord({
             kind: "ui_action",
@@ -133,6 +160,7 @@ export const reactRouterUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }

package/src/import/extractors/ui/sveltekit.js

@@ -2,14 +2,17 @@ import {
   dedupeCandidateRecords,
   detectUiPresentationFeatures,
   entityIdForRoute,
+  inferNonResourceUiFlow,
   inferNavigationStructure,
   inferSvelteRoutes,
   makeCandidateRecord,
   navigationPatternsFromStructure,
+  proposedUiContractAdditionsForFlow,
   relativeTo,
   shellKindFromNavigation,
   screenIdForRoute,
   screenKindForRoute,
+  uiFlowIdForRoute,
   uiCapabilityHintsForRoute,
   titleCase
 } from "../../core/shared.js";
@@ -28,7 +31,7 @@ export const svelteKitUiExtractor = {
   },
   extract(context) {
     const findings = [];
-    const candidates = { screens: [], routes: [], actions: [], stacks: [] };
+    const candidates = { screens: [], routes: [], actions: [], flows: [], stacks: [] };
     const roots = [
       path.join(context.paths.workspaceRoot, "apps", "web-sveltekit"),
       path.join(context.paths.workspaceRoot, "apps", "local-stack", "web")
@@ -74,16 +77,20 @@ export const svelteKitUiExtractor = {
       for (const routePath of routes) {
         const screenId = screenIdForRoute(routePath);
         const screenKind = screenKindForRoute(routePath);
-        const capabilityHints = uiCapabilityHintsForRoute(routePath);
+        const flow = inferNonResourceUiFlow(routePath);
+        const capabilityHints = flow ? { load: null, submit: null, primary_action: null } : uiCapabilityHintsForRoute(routePath);
+        const entityId = flow ? null : entityIdForRoute(routePath);
+        const routeProvenance = `${provenance}#${routePath}`;
         candidates.screens.push(makeCandidateRecord({
           kind: "screen",
           idHint: screenId,
           label: titleCase(screenId),
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           screen_kind: screenKind,
           route_path: routePath,
           capability_hints: capabilityHints
@@ -94,12 +101,32 @@ export const svelteKitUiExtractor = {
           label: routePath,
           confidence: "medium",
           sourceKind: "route_code",
-          provenance: `${provenance}#${routePath}`,
+          provenance: routeProvenance,
           track: "ui",
           screen_id: screenId,
-          entity_id: entityIdForRoute(routePath),
+          entity_id: entityId,
+          concept_id: flow?.concept_id || entityId,
           path: routePath
         }));
+        if (flow) {
+          candidates.flows.push(makeCandidateRecord({
+            kind: "ui_flow",
+            idHint: uiFlowIdForRoute(routePath, screenId),
+            label: `${titleCase(flow.flow_type)} Flow`,
+            confidence: flow.confidence,
+            sourceKind: "route_code",
+            sourceOfTruth: "candidate",
+            provenance: routeProvenance,
+            track: "ui",
+            flow_type: flow.flow_type,
+            concept_id: flow.concept_id,
+            screen_ids: [screenId],
+            route_paths: [routePath],
+            evidence: [routeProvenance],
+            missing_decisions: flow.missing_decisions,
+            proposed_ui_contract_additions: proposedUiContractAdditionsForFlow(routePath, screenId, screenKind)
+          }));
+        }
       }
       for (const feature of features) {
         candidates.actions.push(makeCandidateRecord({
@@ -117,6 +144,7 @@ export const svelteKitUiExtractor = {
     candidates.screens = dedupeCandidateRecords(candidates.screens, (record) => record.id_hint);
     candidates.routes = dedupeCandidateRecords(candidates.routes, (record) => record.id_hint);
     candidates.actions = dedupeCandidateRecords(candidates.actions, (record) => record.id_hint);
+    candidates.flows = dedupeCandidateRecords(candidates.flows, (record) => record.id_hint);
     candidates.stacks = [...new Set(candidates.stacks)].sort();
     return { findings, candidates };
   }