feat(smartmigration): add initial smartmigration package with MongoDB and S3 migration runner

ts/ledgers/classes.ledger.ts

@@ -0,0 +1,41 @@
+import type {
+  ISmartMigrationLedgerData,
+} from '../interfaces.js';
+
+/**
+ * Abstract ledger interface — both MongoLedger and S3Ledger implement this.
+ *
+ * Lifecycle:
+ *   1. `init()` — open the underlying store, create empty document if needed
+ *   2. `read()` — return the current ledger data
+ *   3. `write(data)` — overwrite the ledger with the given data
+ *   4. `acquireLock(holderId, ttlMs)` — best-effort lock; returns true on success
+ *   5. `releaseLock(holderId)` — clear the lock if we still hold it
+ *   6. `close()` — release any resources
+ *
+ * The ledger data is a single self-contained JSON-serializable object.
+ * Both backends store it as a single document (mongo via EasyStore, s3 via
+ * a single sidecar object).
+ */
+export abstract class Ledger {
+  public abstract init(): Promise<void>;
+  public abstract read(): Promise<ISmartMigrationLedgerData>;
+  public abstract write(data: ISmartMigrationLedgerData): Promise<void>;
+  public abstract acquireLock(holderId: string, ttlMs: number): Promise<boolean>;
+  public abstract releaseLock(holderId: string): Promise<void>;
+  public abstract close(): Promise<void>;
+}
+
+/** Build a fresh, empty ledger document. */
+export function emptyLedgerData(): ISmartMigrationLedgerData {
+  return {
+    currentVersion: null,
+    steps: {},
+    lock: {
+      holder: null,
+      acquiredAt: null,
+      expiresAt: null,
+    },
+    checkpoints: {},
+  };
+}