Context
The historical split was:
awa-model/migrations/v*.sql owns the canonical awa.* namespace.
QueueStorage::prepare_schema() owns {queue_storage_schema}.* because the queue-storage schema name was dynamic.
That boundary made sense while queue storage was clearly separate / dynamic, but the 0.6 default queue-storage schema is now awa. In the default path, prepare_schema() is creating first-class awa.* objects after awa migrate has already reported the schema as current.
Why this matters before 0.6
The current split leaks into operator and release behavior:
awa migrate can leave the default queue-storage substrate absent, so a fresh install relies on the first worker doing DDL.
awa migrate --sql / --extract-to cannot reproduce the full default runtime schema if queue-storage substrate DDL only lives in Rust prepare_schema().
- Recent migrations already need defensive boot-window logic when a queue-storage table such as
queue_terminal_live_counts might not exist yet.
awa storage prepare-queue-storage-schema --schema awa --reset currently means DROP SCHEMA IF EXISTS awa CASCADE, which is dangerous now that the default queue-storage schema is also the canonical schema.
Proposed direction
Before shipping 0.6, make the default contract explicit:
awa migrate owns the default awa install: canonical schema plus the default queue-storage substrate.
awa migrate remains activation-neutral: it should create the objects, but not flip routing / storage-transition state by itself.
QueueStorage::prepare_schema() remains idempotent for custom queue-storage schemas, repair, tests, and worker safety, but it is no longer the normal source of default awa.* object creation.
- Extracted migration SQL must include the default queue-storage install story, either as generated SQL or a SQL helper, so external migration tooling is not incomplete.
- Destructive reset paths must be guarded for
schema == 'awa' or made to rerun canonical migrations consistently.
Acceptance criteria
- Fresh
awa migrate creates all default queue-storage objects needed by 0.6 queue-storage runtime startup, including the job id sequence, hot tables, partitions, helper functions, and live terminal counter/indexes.
- Fresh
awa migrate does not activate queue storage by itself; existing fresh-install auto-finalize / worker startup semantics remain deliberate.
awa migrate --sql and awa migrate --extract-to include enough SQL for an external migration system to produce the same default schema as awa migrate.
- Custom
queue_storage_schema deployments still work via explicit schema preparation.
prepare-queue-storage-schema --schema awa --reset / Python reset paths cannot accidentally drop the canonical schema without restoring it, or are rejected with a clear error.
- Docs describe the final ownership boundary: migrations own default
awa.*; explicit schema preparation owns non-default queue-storage schemas.
Context
The historical split was:
awa-model/migrations/v*.sqlowns the canonicalawa.*namespace.QueueStorage::prepare_schema()owns{queue_storage_schema}.*because the queue-storage schema name was dynamic.That boundary made sense while queue storage was clearly separate / dynamic, but the 0.6 default queue-storage schema is now
awa. In the default path,prepare_schema()is creating first-classawa.*objects afterawa migratehas already reported the schema as current.Why this matters before 0.6
The current split leaks into operator and release behavior:
awa migratecan leave the default queue-storage substrate absent, so a fresh install relies on the first worker doing DDL.awa migrate --sql/--extract-tocannot reproduce the full default runtime schema if queue-storage substrate DDL only lives in Rustprepare_schema().queue_terminal_live_countsmight not exist yet.awa storage prepare-queue-storage-schema --schema awa --resetcurrently meansDROP SCHEMA IF EXISTS awa CASCADE, which is dangerous now that the default queue-storage schema is also the canonical schema.Proposed direction
Before shipping 0.6, make the default contract explicit:
awa migrateowns the defaultawainstall: canonical schema plus the default queue-storage substrate.awa migrateremains activation-neutral: it should create the objects, but not flip routing / storage-transition state by itself.QueueStorage::prepare_schema()remains idempotent for custom queue-storage schemas, repair, tests, and worker safety, but it is no longer the normal source of defaultawa.*object creation.schema == 'awa'or made to rerun canonical migrations consistently.Acceptance criteria
awa migratecreates all default queue-storage objects needed by 0.6 queue-storage runtime startup, including the job id sequence, hot tables, partitions, helper functions, and live terminal counter/indexes.awa migratedoes not activate queue storage by itself; existing fresh-install auto-finalize / worker startup semantics remain deliberate.awa migrate --sqlandawa migrate --extract-toinclude enough SQL for an external migration system to produce the same default schema asawa migrate.queue_storage_schemadeployments still work via explicit schema preparation.prepare-queue-storage-schema --schema awa --reset/ Python reset paths cannot accidentally drop the canonical schema without restoring it, or are rejected with a clear error.awa.*; explicit schema preparation owns non-default queue-storage schemas.