readme.hints.md

Internal development notes for @push.rocks/smartmigration. This file is not published to npm.

Architecture

The ledger is the source of truth. Two backends: mongo (a single document in smartdata's SmartdataEasyStore collection) and S3 (via bucket.fastPut/fastGet).
Step execution is sequential and registration-ordered. The from/to fields exist for chain validation, not for DAG resolution.
Drivers (mongodb.Db, S3Client) are exposed via ctx, not wrapped. smartmigration writes no SQL or S3 wrappers of its own.

The mongo lock uses atomic findOneAndUpdate / updateOne operations against the SmartdataEasyStore collection and a background heartbeat that extends lock.expiresAt while steps are running.
The S3 lock is best-effort (S3 has no conditional writes without versioning). S3-only deployments should not run multiple instances against the same ledger without external coordination.

The collection already exists in the smartdata ecosystem and is a natural fit for singleton blobs keyed by nameId.
Reusing it avoids introducing a second smartmigration-specific collection just to store one document per ledger.
The lock path talks directly to the collection for atomic updates; the persisted document shape still mirrors EasyStore's { nameId, data } layout.
See /mnt/data/lossless/push.rocks/smartdata/ts/classes.easystore.ts for the reference document shape.

plan() / dryRun resolve the same fresh-install shortcut as run(), so their currentVersionAfter value is predictive rather than just echoing the current ledger version.
Successful resumable steps clear checkpoints[stepId]; failed steps leave checkpoints intact so the next run can resume.

Use @push.rocks/smartmongo's SmartMongo.createAndStart() for an in-memory replica set.
After createAndStart(), call getMongoDescriptor() and feed the result to new SmartdataDb(...).
Always call db.close() and smartMongo.stop() in test cleanup.