existing storage migrations #

core implementations live under src/albedo/daemon/migrations/; extension implementations live under their own migrations/ directories and contribute MigrationPlugin values. the host applies them, without importing extension-specific migration modules.

startup order #

runtime.start installs the extension registry before server.prepare_storage. for each installed extension, extension.install first calls its table initialiser, then applies its contributed SchemaMigration callbacks on the store-owned SQLite connection, in plugin order. work contributes cwd.apply; paperclips contributes title.apply, scope.apply, and reply.apply. their ledgers create tables but do not run upgrades themselves. all installed owners upgrade, even when disabled for sessions; session selection and live reload never rerun migrations.

server.prepare_storage then runs before sessions start:

1. conversation.initialise creates the core tables, then calls conversation_columns.apply: the existing session columns first, transcript columns second. it then runs its existing domain-local session recovery (missing activity/title from transcript), then creates sessions_activity.
2. quota, mail, and family initialise their tables, unchanged.
3. migrations.run(ledger, backup) runs the core image_store.run, which first externalizes legacy transcript images, then converts image-table TEXT data to decoded BLOB. It then runs transcript_classes.run to classify old transcript rows. runtime.migrate(host, backup) then collects installed extensions' DataMigration callbacks in registry/plugin order and applies them with the same backup path. python contributes cell_images.run, which requires the core image and marker tables. callbacks report named row counts; the server logs nonzero extension results as migration <name>: <n> rows. a failed callback stops startup and prevents later migrations from running.
4. the existing best-effort filesystem credential migration runs; then provider assignment from legacy configuration runs, unchanged.

schema creation is still owned by each subsystem. work/migrations/cwd.apply checks PRAGMA table_info(work), adds the existing reserved __albedo_legacy__ cwd default when absent, then creates work_cwd_id; paperclips/migrations/title.apply adds the existing non-null empty-default title column, paperclips/migrations/scope.apply drops the now-unused workspace index left from the cwd-scoped vent era, and paperclips/migrations/reply.apply adds the non-null empty-default reply column that makes a /paperclips answer durable. these upgrades run immediately after their owner's table creation, so later extension initialisers can use the upgraded schema. embedding hosts call runtime.migrate after preparing core storage and before opening sessions.

compatibility and interruption #

• conversation_columns.apply adds nullable transcript.row_class, checked against user, image_fit, and other. Live writes set it in the same transaction as the payload; forks copy it with the retained prefix. transcript_classes.run classifies only NULL rows in 128-row transactions. An invalid payload fails the current batch and startup; completed batches survive interruption. The backfill neither rewrites payloads nor adds a migration marker. It runs after the image migration.
• transcript_pending_class indexes unclassified sequence IDs. transcript_users indexes (session,seq) for user and image-fit rows; transcript_fits indexes (session,seq) for image-fit rows alone. Completed databases have no pending entries, so subsequent startups do not decode transcript payloads for classification.
• the existing migrations(name,applied_at) table remains unchanged. the exact markers are image_store and cell_images, recorded with unixepoch(). transcript migration skips when its marker exists; cell migration skips when its marker exists, and does nothing without a cells table.
• TEXT-to-BLOB migration deliberately has no marker. it checks typeof(data)='text' on every run and converts pending rows, even when the image_store marker already exists. invalid legacy base64 fails without replacing that row.
• transcript and cell scans retain their original cursor order and 16-row pages; BLOB conversion retains its 16-row limit. each page uses the existing transaction helper. there is no new all-migrations transaction or transaction policy change. markers are written at the original completion points, and interrupted runs recheck remaining rows.
• core backup.gleam and python's cell migration preserve the two existing backup call patterns: transcript and BLOB migration check for an existing file before directory creation and VACUUM INTO, retaining the image store backup failed: error prefix; cell migration ensures the directory first and copies on the first page containing inline images, outside its transaction. the server still supplies one shared home/backups/albedo-before-image-store-<timestamp>.sqlite path. no backup is overwritten and backup triggering is unchanged (the transcript candidate check can include tool outputs without inline images).
• live writes and transcript migration share image_payloads.insert, the unchanged decoded-BLOB insertion helper. image hashes, serialized formats, image validation, and legacy inline fallback reads are unchanged. the existing Erlang conversion and cell packing functions remain the FFI implementation.

migration inventory #

previous implementation	current implementation
conversation.initialise: session/transcript add_columns	migrations/conversation_columns.apply
transcript row classification	migrations/transcript_classes.run, after core image upgrades
images.migrate / migrate_legacy / transcript pages	migrations/image_store.run / migrate_legacy / transcript pages
images.migrate_blobs / BLOB pages	migrations/image_store.migrate_blobs / BLOB pages
images.backup_before_migration	migrations/backup.image_store
python/cells.migrate_images / cell pages	python/migrations/cell_images.run / cell pages
python/cells.backup_before_migration	python/migrations/cell_images.backup_before_migration
work/ledger.initialise: cwd alteration and index	work/migrations/cwd.apply, contributed by work
paperclips/ledger.initialise: title addition	paperclips/migrations/title.apply, contributed by paperclips
paperclips/ledger.initialise: paperclips_cwd index creation	dropped from the schema; paperclips/migrations/scope.apply removes it from existing stores
paperclips/ledger.initialise: reply column	paperclips/migrations/reply.apply, added with the global ledger

images.migrate and cells.migrate_images are removed rather than wrapped: the migration implementations are separate from the live domain readers and writers. startup discovers extension upgrades through plugins, not direct calls to their implementation modules.

intentionally not extracted #

• session recovery stays in conversation: it uses the domain's transcript decoding/title helpers and still runs at exactly the same point. core schema bootstrap and index creation remain with their owners.
• rolling compaction's legacy item-count-to-user-cut conversion remains lazy in rolling/extension.resume. it needs the current prepared history and source, validates the old fingerprint (including legacy image payload fingerprints), and only writes a cut when the history matches and its tail begins with a user message. treating this as an unconditional startup migration would change its timing and semantics; its projections are untouched.
• credentials migration is filesystem/auth, not SQLite. legacy configuration's provider assignment likewise remains in the existing server startup path.
• no zstd, compression, schema-version, offline storage upgrade, new dependency, or unrelated transaction fix is part of this refactor.