@topogram/cli 0.3.74 → 0.3.76

package/package.json

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

package/src/adoption/plan/index.js

@@ -637,6 +637,7 @@ function mappingSuggestionsForItem(item) {
 }
 
 export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact = null) {
+  const importedMaintainedDbSeams = [...(adoptionPlan?.imported_maintained_db_seams || [])];
   const items = (adoptionPlan?.items || []).map((item) => {
     const currentState = inferCurrentAdoptionState(item);
     const maintainedSeamCandidates = inferMaintainedSeamCandidates({
@@ -656,6 +657,9 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       ui_impacts: [...(item.ui_impacts || [])],
       workflow_impacts: [...(item.workflow_impacts || [])]
     }, maintainedBoundaryArtifact);
+    const importedDbSeamCandidates = ["entity", "enum", "index", "relation", "db"].includes(item.kind) || item.track === "db"
+      ? importedMaintainedDbSeams
+      : [];
     return {
       id: adoptionItemKey(item),
       bundle: item.bundle,
@@ -691,11 +695,57 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       projection_impacts: [...(item.projection_impacts || [])],
       ui_impacts: [...(item.ui_impacts || [])],
       workflow_impacts: [...(item.workflow_impacts || [])],
-      maintained_seam_candidates: maintainedSeamCandidates,
+      maintained_seam_candidates: [...maintainedSeamCandidates, ...importedDbSeamCandidates],
       mapping_suggestions: mappingSuggestionsForItem(item),
       available_actions: ADOPTION_STATE_VOCABULARY
     };
   });
+  const importedDbSeamSurfaces = importedMaintainedDbSeams.map((seam) => ({
+    id: seam.id_hint || seam.seam_id,
+    bundle: "database",
+    item: seam.id_hint || seam.seam_id,
+    kind: seam.kind || "maintained_db_migration_seam",
+    track: "db",
+    source_kind: seam.source_kind || "migration_strategy_inference",
+    source_path: "candidates/app/db/candidates.json",
+    canonical_rel_path: null,
+    related_shapes: [],
+    review_boundary: {
+      automation_class: "review_required",
+      reasons: [
+        "manual_project_config_review",
+        "proposal_only_maintained_db_migration_seam"
+      ]
+    },
+    current_state: "stage",
+    recommended_state: "customize",
+    supported_states: ADOPTION_STATE_VOCABULARY,
+    human_review_required: true,
+    provenance: {
+      bundle: "database",
+      source_path: "candidates/app/db/candidates.json",
+      canonical_rel_path: null
+    },
+    requirements: {
+      related_docs: [],
+      related_capabilities: [],
+      related_shapes: [],
+      related_rules: [],
+      related_workflows: [],
+      blocking_dependencies: []
+    },
+    projection_impacts: [],
+    ui_impacts: [],
+    workflow_impacts: [],
+    maintained_seam_candidates: [seam],
+    mapping_suggestions: [{
+      type: "manual_project_config_review",
+      id: seam.id_hint || seam.seam_id,
+      reason: "Review the inferred database migration strategy before editing topogram.project.json."
+    }],
+    available_actions: ADOPTION_STATE_VOCABULARY
+  }));
+  const proposalSurfaces = [...items, ...importedDbSeamSurfaces];
 
   return {
     type: "agent_adoption_plan",
@@ -708,10 +758,11 @@ export function buildAgentAdoptionPlan(adoptionPlan, maintainedBoundaryArtifact
       non_canonical_adoption_state: "stage"
     },
     approved_review_groups: [...new Set(adoptionPlan?.approved_review_groups || [])].sort(),
-    imported_proposal_surfaces: items,
-    staged_items: items.filter((item) => item.current_state === "stage").map((item) => item.id),
-    accepted_items: items.filter((item) => item.current_state === "accept").map((item) => item.id),
-    rejected_items: items.filter((item) => item.current_state === "reject").map((item) => item.id),
-    requires_human_review: items.filter((item) => item.human_review_required).map((item) => item.id)
+    imported_maintained_db_seam_candidates: importedMaintainedDbSeams,
+    imported_proposal_surfaces: proposalSurfaces,
+    staged_items: proposalSurfaces.filter((item) => item.current_state === "stage").map((item) => item.id),
+    accepted_items: proposalSurfaces.filter((item) => item.current_state === "accept").map((item) => item.id),
+    rejected_items: proposalSurfaces.filter((item) => item.current_state === "reject").map((item) => item.id),
+    requires_human_review: proposalSurfaces.filter((item) => item.human_review_required).map((item) => item.id)
   };
 }

package/src/agent-brief.js

@@ -31,7 +31,8 @@ import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot, resolveWorkspaceContext } fr
  * @typedef {{ command: string, reason: string, phase: string }} AgentBriefCommand
  * @typedef {{ path: string, ownership: string, rule: string }} AgentBriefOutputBoundary
  * @typedef {{ id: string, title: string, commands: string[], rule: string }} AgentBriefWorkflow
- * @typedef {{ id: string, kind: string, projection: string|null, generator: string|null, uses_api: string|null, uses_database: string|null }} AgentBriefRuntime
+ * @typedef {{ ownership: string|null, tool: string|null, apply: string|null, statePath: string|null, snapshotPath: string|null, schemaPath: string|null, migrationsPath: string|null }} AgentBriefMigration
+ * @typedef {{ id: string, kind: string, projection: string|null, generator: string|null, uses_api: string|null, uses_database: string|null, migration: AgentBriefMigration|null }} AgentBriefRuntime
  * @typedef {{ path: string, workspaceRoot: string, source: string|null, tracks: string[], candidateCounts: Record<string, any>, ownership: string|null }} AgentBriefImport
  * @typedef {{ ok: true, payload: Record<string, any> } | { ok: false, kind: "topogram", validation: any } | { ok: false, kind: "project", validation: any, configPath: string }} AgentBriefResult
  */
@@ -103,7 +104,18 @@ function summarizeRuntimes(config) {
     projection: typeof runtime.projection === "string" ? runtime.projection : null,
     generator: typeof runtime.generator?.id === "string" ? runtime.generator.id : null,
     uses_api: typeof runtime.uses_api === "string" ? runtime.uses_api : null,
-    uses_database: typeof runtime.uses_database === "string" ? runtime.uses_database : null
+    uses_database: typeof runtime.uses_database === "string" ? runtime.uses_database : null,
+    migration: runtime.kind === "database" && runtime.migration
+      ? {
+          ownership: typeof runtime.migration.ownership === "string" ? runtime.migration.ownership : null,
+          tool: typeof runtime.migration.tool === "string" ? runtime.migration.tool : null,
+          apply: typeof runtime.migration.apply === "string" ? runtime.migration.apply : null,
+          statePath: typeof runtime.migration.statePath === "string" ? runtime.migration.statePath : null,
+          snapshotPath: typeof runtime.migration.snapshotPath === "string" ? runtime.migration.snapshotPath : null,
+          schemaPath: typeof runtime.migration.schemaPath === "string" ? runtime.migration.schemaPath : null,
+          migrationsPath: typeof runtime.migration.migrationsPath === "string" ? runtime.migration.migrationsPath : null
+        }
+      : null
   }));
 }
 
@@ -495,7 +507,10 @@ export function formatAgentBrief(brief) {
       runtime.uses_api ? `uses_api=${runtime.uses_api}` : null,
       runtime.uses_database ? `uses_database=${runtime.uses_database}` : null
     ].filter(Boolean).join(", ");
-    lines.push(`  - ${runtime.id}: ${runtime.kind}${runtime.projection ? ` -> ${runtime.projection}` : ""}${runtime.generator ? ` via ${runtime.generator}` : ""}${edges ? ` (${edges})` : ""}`);
+    const migration = runtime.migration
+      ? ` migration=${runtime.migration.ownership}/${runtime.migration.tool} apply=${runtime.migration.apply}`
+      : "";
+    lines.push(`  - ${runtime.id}: ${runtime.kind}${runtime.projection ? ` -> ${runtime.projection}` : ""}${runtime.generator ? ` via ${runtime.generator}` : ""}${edges ? ` (${edges})` : ""}${migration}`);
   }
   if ((brief.topology?.runtimes || []).length === 0) {
     lines.push("  - No topology runtimes configured.");

package/src/cli/commands/check.js

@@ -80,6 +80,17 @@ function summarizeProjectTopology(config) {
         version: component.generator?.version || null
       },
       port: topologyComponentPort(component),
+      migration: component.kind === "database" && component.migration
+        ? {
+            ownership: component.migration.ownership || null,
+            tool: component.migration.tool || null,
+            apply: component.migration.apply || null,
+            statePath: component.migration.statePath || null,
+            snapshotPath: component.migration.snapshotPath || null,
+            schemaPath: component.migration.schemaPath || null,
+            migrationsPath: component.migration.migrationsPath || null
+          }
+        : null,
       references: topologyComponentReferences(component)
     }))
     .sort((left, right) => left.id.localeCompare(right.id));
@@ -136,7 +147,10 @@ function formatTopologyComponent(component) {
     .filter(([, value]) => Boolean(value))
     .map(([key, value]) => `${key} ${value}`);
   const suffix = refs.length ? ` -> ${refs.join(", ")}` : "";
-  return `  - ${component.id}: ${component.kind} ${component.projection} via ${generator} (${port})${suffix}`;
+  const migration = component.migration
+    ? ` [migration ${component.migration.ownership}/${component.migration.tool}, apply=${component.migration.apply}]`
+    : "";
+  return `  - ${component.id}: ${component.kind} ${component.projection} via ${generator} (${port})${suffix}${migration}`;
 }
 
 /**

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

@@ -110,6 +110,7 @@ export function importCandidateCounts(summary) {
   return {
     dbEntities: candidates.db?.entities?.length || 0,
     dbEnums: candidates.db?.enums?.length || 0,
+    dbMaintainedSeams: candidates.db?.maintained_seams?.length || 0,
     apiCapabilities: candidates.api?.capabilities?.length || 0,
     apiRoutes: candidates.api?.routes?.length || 0,
     uiScreens: candidates.ui?.screens?.length || 0,

package/src/generator/adapters.js

@@ -177,7 +177,7 @@ function buildContractsForContext(context) {
   if (surface === "database") {
     return {
       db: generateDbContractGraph(context.graph, { ...(context.options || {}), projectionId }),
-      lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId })
+      lifecyclePlan: generateDbLifecyclePlan(context.graph, { ...(context.options || {}), projectionId, runtime, component: runtime, topology: context.topology })
     };
   }
   if (surface === "native" || surface === "ios_surface" || surface === "android_surface") {

package/src/generator/runtime/app-bundle.js

@@ -48,7 +48,7 @@ function buildAppBundlePlan(graph, options = {}) {
   const runtimeReference = runtimeReferenceFor(graph, options);
   const topology = resolveRuntimeTopology(graph, options);
   const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id }) : null;
+  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id, runtime: topology.primaryDb || undefined }) : null;
   const environmentProfile = options.profileId || "local_process";
   const deployProfile = options.deployProfileId || "fly_io";
   const smokeVerification = buildVerificationSummary(graph, ["smoke", "journey"]);
@@ -77,7 +77,8 @@ function buildAppBundlePlan(graph, options = {}) {
         generator: runtime.generator,
         port: runtime.port ?? null,
         uses_api: runtime.api || null,
-        uses_database: runtime.database || null
+        uses_database: runtime.database || null,
+        ...(runtime.kind === "database" && runtime.migration ? { migration: runtime.migration } : {})
       }))
     },
     runtimeReference,

package/src/generator/runtime/environment/index.js

@@ -43,7 +43,7 @@ function buildEnvironmentPlan(graph, options = {}) {
   const runtimeReference = runtimeReferenceFor(graph, options);
   const topology = resolveRuntimeTopology(graph, options);
   const { apiProjection, uiProjection, dbProjection } = getDefaultEnvironmentProjections(graph, options);
-  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id }) : null;
+  const dbLifecycle = dbProjection ? generateDbLifecyclePlan(graph, { ...options, projectionId: dbProjection.id, runtime: topology.primaryDb || undefined }) : null;
   const dbEngine = dbLifecycle?.engine || null;
   const profile = options.profileId || (dbEngine === "sqlite" || !dbProjection ? "local_process" : "local_docker");
   const usesDocker = profile === "local_docker";
@@ -67,7 +67,8 @@ function buildEnvironmentPlan(graph, options = {}) {
         generator: runtime.generator,
         port: runtime.port ?? null,
         uses_api: runtime.api || null,
-        uses_database: runtime.database || null
+        uses_database: runtime.database || null,
+        ...(runtime.kind === "database" && runtime.migration ? { migration: runtime.migration } : {})
       }))
     },
     projections: {
@@ -145,7 +146,8 @@ function buildEnvironmentPlan(graph, options = {}) {
         engine: component.id === topology.primaryDb?.id ? dbEngine : null,
         port: component.port,
         dir: topology.dbDir(component),
-        env: dbEnvVarsForComponent(component, { primary: component.id === topology.primaryDb?.id })
+        env: dbEnvVarsForComponent(component, { primary: component.id === topology.primaryDb?.id }),
+        ...(component.migration ? { migration: component.migration } : {})
       }))
     },
     ports: {
@@ -329,7 +331,8 @@ ${dockerSection}
 - ${hasWeb && hasApi ? "The generated web app talks to `PUBLIC_TOPOGRAM_API_BASE_URL`." : hasWeb ? "The generated web app is standalone." : "No web surface is generated."}
 - ${hasNative ? "Native app scaffolds use the same UI surface contracts as web surfaces." : "No native surface is generated."}
 - If \`.env\` is missing, generated scripts fall back to \`.env.example\`.
-- The DB lifecycle scripts remain the source of truth for greenfield bootstrap and brownfield migration.
+- Generated-owned DB lifecycle scripts remain the source of truth for greenfield bootstrap and generated migrations.
+- Maintained DB lifecycle scripts emit proposals only and never apply migrations.
 `;
 }
 
@@ -349,6 +352,10 @@ function renderEnvironmentBootstrapDbScript(plan) {
     return `(cd "$ROOT_DIR/${component.dir}" && TOPOGRAM_ENV_FILE=/dev/null ${assignments} bash ./scripts/db-bootstrap-or-migrate.sh)`;
   });
   const primaryApi = plan.runtimes.apis[0];
+  const primaryApiDatabase = primaryApi?.uses_database
+    ? plan.runtimes.databases.find((component) => component.id === primaryApi.uses_database)
+    : null;
+  const seedAllowed = Boolean(primaryApi?.uses_database) && primaryApiDatabase?.migration?.ownership !== "maintained";
   if (plan.runtimes.databases.length === 0) {
     return renderEnvAwareShellScript([
       'echo "No database runtimes are configured; skipping DB bootstrap."'
@@ -366,9 +373,11 @@ function renderEnvironmentBootstrapDbScript(plan) {
     ...dbBootstrapLines,
     'if [[ "${TOPOGRAM_SEED_DEMO:-true}" != "false" ]]; then',
     ...apiDatabaseExportLines(primaryApi),
-    ...(primaryApi?.uses_database
+    ...(seedAllowed
       ? [`(cd "$ROOT_DIR/${primaryApi.dir}" && npm install && npm exec -- prisma generate --schema prisma/schema.prisma && npm exec -- prisma db push --schema prisma/schema.prisma --skip-generate && npm run seed:demo)`]
-      : ['echo "No DB-backed API component is configured; skipping demo seed."']),
+      : [primaryApi?.uses_database
+        ? 'echo "Primary API uses a maintained database runtime; skipping generated demo seed."'
+        : 'echo "No DB-backed API component is configured; skipping demo seed."']),
     "fi"
   ]);
 }

package/src/generator/runtime/shared/index.js

@@ -27,6 +27,7 @@ import { defaultProjectConfigForGraph, validateProjectConfig } from "../../../pr
  * @property {string|null} [api]
  * @property {string|null} [database]
  * @property {Record<string, string>} [env]
+ * @property {import("../../../project-config.js").RuntimeMigrationStrategy} [migration]
  * @property {RuntimeComponent|null} [apiRuntime]
  * @property {RuntimeComponent|null} [databaseRuntime]
  * @property {RuntimeComponent|null} [apiComponent] Legacy adapter alias for apiRuntime.

package/src/generator/surfaces/databases/lifecycle-shared.js

@@ -17,11 +17,65 @@ function defaultInputPathForGraph(graph, options = {}) {
   return ".";
 }
 
+function runtimeMigrationStrategyForProjection(projection, options = {}) {
+  const projectionId = projection?.id || options.projectionId || null;
+  const runtime = options.runtime || options.component || null;
+  if (runtime?.kind === "database" && runtime?.migration && (!projectionId || runtime.projection?.id === projectionId || runtime.projection === projectionId)) {
+    return runtime.migration;
+  }
+
+  const topologyRuntime = (options.topology?.dbRuntimes || options.topology?.runtimes || [])
+    .find((entry) => entry?.kind === "database" && entry?.migration && (entry.projection?.id === projectionId || entry.projection === projectionId));
+  if (topologyRuntime?.migration) {
+    return topologyRuntime.migration;
+  }
+
+  const configRuntime = (options.projectConfig?.topology?.runtimes || [])
+    .find((entry) => entry?.kind === "database" && entry?.migration && entry.projection === projectionId);
+  return configRuntime?.migration || null;
+}
+
+function normalizeMigrationStrategy(strategy) {
+  if (!strategy) {
+    return {
+      ownership: "generated",
+      tool: "sql",
+      apply: "script",
+      statePath: null,
+      snapshotPath: null,
+      schemaPath: null,
+      migrationsPath: null,
+      defaulted: true
+    };
+  }
+  return {
+    ownership: strategy.ownership || "generated",
+    tool: strategy.tool || "sql",
+    apply: strategy.apply || (strategy.ownership === "maintained" ? "never" : "script"),
+    statePath: strategy.statePath || null,
+    snapshotPath: strategy.snapshotPath || null,
+    schemaPath: strategy.schemaPath || null,
+    migrationsPath: strategy.migrationsPath || null,
+    defaulted: false
+  };
+}
+
+function pathJoinPosix(...parts) {
+  return parts.filter(Boolean).join("/").replace(/\/+/g, "/");
+}
+
 function dbLifecyclePlan(graph, projection, options = {}) {
   const contract = buildDbProjectionContract(graph, projection);
   const snapshot = normalizeDbSchemaSnapshot(contract);
   const engine = snapshot.engine;
   const ormProfiles = engine === "postgres" ? ["prisma", "drizzle"] : ["prisma"];
+  const migrationStrategy = normalizeMigrationStrategy(runtimeMigrationStrategyForProjection(projection, options));
+  const generatedStateRoot = migrationStrategy.statePath || "state";
+  const proposalStateRoot = "state";
+  const stateRoot = migrationStrategy.ownership === "generated" ? generatedStateRoot : proposalStateRoot;
+  const currentSnapshot = migrationStrategy.ownership === "maintained" && migrationStrategy.snapshotPath
+    ? migrationStrategy.snapshotPath
+    : pathJoinPosix(stateRoot, "current.snapshot.json");
 
   return {
     type: "db_lifecycle_plan",
@@ -31,19 +85,26 @@ function dbLifecyclePlan(graph, projection, options = {}) {
     ormProfiles,
     runtimeProfile: ormProfiles.includes("prisma") ? "prisma" : null,
     inputPath: defaultInputPathForGraph(graph, options),
+    migrationStrategy,
     state: {
-      currentSnapshot: "state/current.snapshot.json",
-      desiredSnapshot: "state/desired.snapshot.json",
-      migrationPlan: "state/migration.plan.json",
-      migrationSql: "state/migration.sql"
+      root: stateRoot,
+      currentSnapshot,
+      desiredSnapshot: pathJoinPosix(stateRoot, "desired.snapshot.json"),
+      migrationPlan: pathJoinPosix(stateRoot, "migration.plan.json"),
+      migrationSql: pathJoinPosix(stateRoot, "migration.sql")
     },
     bundle: {
       emptySnapshot: "snapshots/empty.snapshot.json",
       prismaSchema: ormProfiles.includes("prisma") ? "prisma/schema.prisma" : null,
       drizzleSchema: engine === "postgres" ? "drizzle/schema.ts" : null
     },
+    proposals: {
+      schemaPath: migrationStrategy.schemaPath,
+      migrationsPath: migrationStrategy.migrationsPath,
+      snapshotPath: migrationStrategy.snapshotPath
+    },
     environment: {
-      required: ["DATABASE_URL"],
+      required: migrationStrategy.ownership === "maintained" ? [] : ["DATABASE_URL"],
       optional:
         engine === "postgres"
           ? ["DATABASE_ADMIN_URL", "TOPOGRAM_BIN", "TOPOGRAM_INPUT_PATH", "TOPOGRAM_DB_STATE_DIR"]
@@ -75,6 +136,14 @@ function dbLifecyclePlan(graph, projection, options = {}) {
         "persist desired snapshot as current"
       ],
       safety: "manual migration required plans are never auto-applied"
+    },
+    behavior: {
+      ownership: migrationStrategy.ownership,
+      tool: migrationStrategy.tool,
+      apply: migrationStrategy.apply,
+      appliesMigrations: migrationStrategy.ownership === "generated" && migrationStrategy.apply === "script",
+      writesGeneratedState: migrationStrategy.ownership === "generated",
+      proposalOnly: migrationStrategy.ownership === "maintained"
     }
   };
 }
@@ -108,10 +177,28 @@ function renderDbLifecycleEnvExample(projection, plan) {
 }
 
 function renderDbLifecycleReadme(plan) {
+  const proposalLines = [
+    plan.proposals.snapshotPath ? `- Current snapshot source: \`${plan.proposals.snapshotPath}\`` : null,
+    plan.proposals.schemaPath ? `- Maintained schema path: \`${plan.proposals.schemaPath}\`` : null,
+    plan.proposals.migrationsPath ? `- Maintained migrations path: \`${plan.proposals.migrationsPath}\`` : null
+  ].filter(Boolean).join("\n");
+  const modeText = plan.behavior.proposalOnly
+    ? `Maintained proposal mode. Topogram emits desired snapshots, migration plans, SQL proposals, and schema proposals, but these scripts do not apply migrations to the database. A human or agent must adapt accepted proposals into the maintained migration system.`
+    : `Generated apply mode. Topogram owns this lifecycle bundle and scripts may apply supported generated SQL migrations. Unsupported or destructive migration plans stop for manual review.`;
   return `# ${plan.projection.name} Lifecycle
 
 This bundle gives agents a repeatable database workflow for projection \`${plan.projection.id}\`.
 
+## Migration Strategy
+
+- Ownership: \`${plan.migrationStrategy.ownership}\`
+- Tool: \`${plan.migrationStrategy.tool}\`
+- Apply: \`${plan.migrationStrategy.apply}\`
+- Defaulted: \`${plan.migrationStrategy.defaulted ? "yes" : "no"}\`
+
+${modeText}
+${proposalLines ? `\n${proposalLines}\n` : ""}
+
 ## Modes
 
 - Greenfield: run \`./scripts/db-bootstrap-or-migrate.sh\` with no current snapshot
@@ -143,6 +230,12 @@ ${plan.environment.optional.map((name) => `- \`${name}\``).join("\n")}
 
 function renderDbLifecycleCommonScript(plan) {
   const engine = plan.engine;
+  const configuredStatePath = plan.migrationStrategy.ownership === "generated" && plan.migrationStrategy.statePath
+    ? plan.migrationStrategy.statePath
+    : "";
+  const configuredSnapshotPath = plan.migrationStrategy.ownership === "maintained" && plan.migrationStrategy.snapshotPath
+    ? plan.migrationStrategy.snapshotPath
+    : "";
   return `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -219,9 +312,24 @@ discover_input_path() {
 }
 TOPOGRAM_BIN="$(find_topogram_bin)"
 INPUT_PATH="$(discover_input_path)"
+if [[ -f "$INPUT_PATH/topogram.project.json" ]]; then
+  PROJECT_ROOT="$INPUT_PATH"
+else
+  PROJECT_ROOT="$(cd "$INPUT_PATH/.." && pwd)"
+fi
 PROJECTION_ID="${plan.projection.id}"
-STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$BUNDLE_DIR/state}"
-CURRENT_SNAPSHOT="$STATE_DIR/current.snapshot.json"
+CONFIGURED_STATE_PATH=${JSON.stringify(configuredStatePath)}
+CONFIGURED_SNAPSHOT_PATH=${JSON.stringify(configuredSnapshotPath)}
+if [[ -n "$CONFIGURED_STATE_PATH" ]]; then
+  STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$PROJECT_ROOT/$CONFIGURED_STATE_PATH}"
+else
+  STATE_DIR="\${TOPOGRAM_DB_STATE_DIR:-$BUNDLE_DIR/state}"
+fi
+if [[ -n "$CONFIGURED_SNAPSHOT_PATH" ]]; then
+  CURRENT_SNAPSHOT="$PROJECT_ROOT/$CONFIGURED_SNAPSHOT_PATH"
+else
+  CURRENT_SNAPSHOT="$STATE_DIR/current.snapshot.json"
+fi
 DESIRED_SNAPSHOT="$STATE_DIR/desired.snapshot.json"
 PLAN_JSON="$STATE_DIR/migration.plan.json"
 MIGRATION_SQL="$STATE_DIR/migration.sql"
@@ -429,7 +537,7 @@ ${engine === "sqlite" ? `  normalize_sqlite_database_url
 `;
 }
 
-function renderDbStatusScript() {
+function renderDbStatusScript(plan) {
   return `#!/usr/bin/env bash
 set -euo pipefail
 . "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
@@ -440,11 +548,26 @@ if [[ -f "$CURRENT_SNAPSHOT" ]]; then
   generate_migration_plan "$CURRENT_SNAPSHOT"
   cat "$PLAN_JSON"
 else
-  echo '{"mode":"greenfield","currentSnapshot":null}'
+  echo ${JSON.stringify(plan.behavior.proposalOnly ? '{"mode":"maintained_proposal","currentSnapshot":null}' : '{"mode":"greenfield","currentSnapshot":null}')}
 fi
 `;
 }
 
+function renderMaintainedDbBootstrapScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+. "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
+
+generate_desired_snapshot
+generate_sql_migration "$EMPTY_SNAPSHOT"
+
+echo "Maintained database runtime: bootstrap is proposal-only."
+echo "Desired snapshot: $DESIRED_SNAPSHOT"
+echo "SQL proposal: $MIGRATION_SQL"
+echo "No migration was applied. Review and adapt the proposal into the maintained database migration system."
+`;
+}
+
 function renderDbBootstrapScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -489,6 +612,30 @@ echo "Greenfield bootstrap complete."
 `;
 }
 
+function renderMaintainedDbMigrateScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+. "$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)/db-common.sh"
+
+generate_desired_snapshot
+
+if [[ ! -f "$CURRENT_SNAPSHOT" ]]; then
+  echo "Maintained database runtime: current snapshot not found at $CURRENT_SNAPSHOT." >&2
+  echo "Create the reviewed snapshot first, then rerun this proposal command." >&2
+  exit 1
+fi
+
+generate_migration_plan "$CURRENT_SNAPSHOT"
+ensure_supported_plan
+generate_sql_migration "$CURRENT_SNAPSHOT"
+
+echo "Maintained database runtime: migration proposal generated."
+echo "Migration plan: $PLAN_JSON"
+echo "SQL proposal: $MIGRATION_SQL"
+echo "No migration was applied. Review and adapt the proposal into the maintained database migration system."
+`;
+}
+
 function renderDbMigrateScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -524,6 +671,21 @@ echo "Brownfield migration complete."
 `;
 }
 
+function renderMaintainedDbBootstrapOrMigrateScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+. "$SCRIPT_DIR/db-common.sh"
+
+if [[ -f "$CURRENT_SNAPSHOT" ]]; then
+  exec bash "$SCRIPT_DIR/db-migrate.sh"
+fi
+
+exec bash "$SCRIPT_DIR/db-bootstrap.sh"
+`;
+}
+
 function renderDbBootstrapOrMigrateScript() {
   return `#!/usr/bin/env bash
 set -euo pipefail
@@ -571,10 +733,10 @@ function generateDbLifecycleBundle(graph, projection, options = {}) {
     "README.md": renderDbLifecycleReadme(plan),
     ".env.example": renderDbLifecycleEnvExample(projection, plan),
     "scripts/db-common.sh": renderDbLifecycleCommonScript(plan),
-    "scripts/db-status.sh": renderDbStatusScript(),
-    "scripts/db-bootstrap.sh": renderDbBootstrapScript(),
-    "scripts/db-migrate.sh": renderDbMigrateScript(),
-    "scripts/db-bootstrap-or-migrate.sh": renderDbBootstrapOrMigrateScript(),
+    "scripts/db-status.sh": renderDbStatusScript(plan),
+    "scripts/db-bootstrap.sh": plan.behavior.proposalOnly ? renderMaintainedDbBootstrapScript() : renderDbBootstrapScript(),
+    "scripts/db-migrate.sh": plan.behavior.proposalOnly ? renderMaintainedDbMigrateScript() : renderDbMigrateScript(),
+    "scripts/db-bootstrap-or-migrate.sh": plan.behavior.proposalOnly ? renderMaintainedDbBootstrapOrMigrateScript() : renderDbBootstrapOrMigrateScript(),
     "snapshots/empty.snapshot.json": `${JSON.stringify(renderEmptySnapshotForProjection(projection), null, 2)}\n`,
     "state/.gitkeep": ""
   };

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

@@ -261,7 +261,8 @@ export function normalizeCandidatesForTrack(track, candidates) {
       entities: dedupeCandidateRecords(candidates.entities || [], idHint),
       enums: dedupeCandidateRecords(candidates.enums || [], idHint),
       relations: dedupeCandidateRecords(candidates.relations || [], idHint),
-      indexes: dedupeCandidateRecords(candidates.indexes || [], idHint)
+      indexes: dedupeCandidateRecords(candidates.indexes || [], idHint),
+      maintained_seams: dedupeCandidateRecords(candidates.maintained_seams || [], idHint)
     };
   }
   if (track === "api") {

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

@@ -10,8 +10,11 @@ import { uiWidgetCandidates } from "./candidates.js";
  */
 export function reportMarkdown(track, candidates) {
   if (track === "db") {
+    const seamLines = (candidates.maintained_seams || []).map((/** @type {any} */ seam) =>
+      `- \`${seam.id_hint}\` tool \`${seam.tool}\` confidence ${seam.confidence || "unknown"} schema \`${seam.schemaPath || "none"}\` migrations \`${seam.migrationsPath || "review-required"}\` missing decisions ${(seam.missing_decisions || []).length}`
+    );
     return ensureTrailingNewline(
-      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n`
+      `# DB Import Report\n\n- Entities: ${candidates.entities.length}\n- Enums: ${candidates.enums.length}\n- Relations: ${candidates.relations.length}\n- Indexes: ${candidates.indexes.length}\n- Maintained DB migration seams: ${(candidates.maintained_seams || []).length}\n\n## Maintained DB Migration Seam Candidates\n\n${seamLines.length ? seamLines.join("\n") : "- none"}\n`
     );
   }
   if (track === "api") {
@@ -54,6 +57,6 @@ export function reportMarkdown(track, candidates) {
  */
 export function appReportMarkdown(candidates, tracks) {
   return ensureTrailingNewline(
-    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
+    `# App Import Report\n\nTracks: ${tracks.join(", ")}\n\n## DB\n\n- Entities: ${candidates.db?.entities?.length || 0}\n- Enums: ${candidates.db?.enums?.length || 0}\n- Relations: ${candidates.db?.relations?.length || 0}\n- Maintained DB migration seams: ${candidates.db?.maintained_seams?.length || 0}\n\n## API\n\n- Capabilities: ${candidates.api?.capabilities?.length || 0}\n- Routes: ${candidates.api?.routes?.length || 0}\n- Stacks: ${candidates.api?.stacks?.length ? candidates.api.stacks.join(", ") : "none"}\n\n## UI\n\n- Screens: ${candidates.ui?.screens?.length || 0}\n- Routes: ${candidates.ui?.routes?.length || 0}\n- Actions: ${candidates.ui?.actions?.length || 0}\n- Widgets: ${uiWidgetCandidates(candidates.ui).length}\n- Event payload shapes: ${candidates.ui?.shapes?.length || 0}\n- Stacks: ${candidates.ui?.stacks?.length ? candidates.ui.stacks.join(", ") : "none"}\n\n## CLI\n\n- Commands: ${candidates.cli?.commands?.length || 0}\n- Capabilities: ${candidates.cli?.capabilities?.length || 0}\n- CLI surfaces: ${candidates.cli?.surfaces?.length || 0}\n\n## Workflows\n\n- Workflows: ${candidates.workflows?.workflows?.length || 0}\n- States: ${candidates.workflows?.workflow_states?.length || 0}\n- Transitions: ${candidates.workflows?.workflow_transitions?.length || 0}\n\n## Verification\n\n- Verifications: ${candidates.verification?.verifications?.length || 0}\n- Scenarios: ${candidates.verification?.scenarios?.length || 0}\n- Frameworks: ${candidates.verification?.frameworks?.length ? candidates.verification.frameworks.join(", ") : "none"}\n- Scripts: ${candidates.verification?.scripts?.length || 0}\n`
   );
 }

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

@@ -96,7 +96,7 @@ function selectDetectionsForTrack(track, detections) {
  */
 function initialCandidatesForTrack(track) {
   if (track === "db") {
-    return { entities: [], enums: [], relations: [], indexes: [] };
+    return { entities: [], enums: [], relations: [], indexes: [], maintained_seams: [] };
   }
   if (track === "api") {
     return { capabilities: [], routes: [], stacks: [] };