feat(planner): add bridge target version strategy for auto-stamping ledger to app versions

ts/interfaces.ts

@@ -1,5 +1,5 @@
 import type * as plugins from './plugins.js';
-import type { TLedgerBackend, TMigrationStatus } from './types.js';
+import type { TLedgerBackend, TMigrationStatus, TTargetVersionStrategy } from './types.js';
 
 /**
  * Constructor options for SmartMigration.
@@ -42,6 +42,16 @@ export interface ISmartMigrationOptions {
   /** If true, run() returns the plan without executing anything. Default false. */
   dryRun?: boolean;
 
+  /**
+   * Controls whether the registered chain must end exactly at targetVersion.
+   *
+   * - 'strict' (default): require a real registered step ending at targetVersion.
+   * - 'bridge': append an internal no-op bridge to targetVersion when the
+   *   registered chain ends before it. Useful when targetVersion follows the
+   *   application/package version but migrations are only added for schema changes.
+   */
+  targetVersionStrategy?: TTargetVersionStrategy;
+
   /** Custom logger. Defaults to module logger. */
   logger?: plugins.smartlog.Smartlog;
 }
@@ -151,6 +161,8 @@ export interface IMigrationStepDefinition {
   toVersion: string;
   description?: string;
   isResumable: boolean;
+  /** Internal virtual steps are generated by smartmigration and have no user handler effects. */
+  isVirtual?: boolean;
   handler: (ctx: IMigrationContext) => Promise<void>;
 }