@astram/identity 0.11.0 → 0.13.0

package/migrations/1710000000001-CreateIdentityOrgModel.cjs

@@ -14,8 +14,14 @@
  */
 const { Company, User, Role, Department, Branch } = require('@astram/identity');
 const { columnForRole, reflectObjectType } = require('@astram/engine');
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['027818f28b12088392ba5f2194a842ef36815aa34b9df7669683c9cdf24c316f'];
 
-const SCHEMA = 'shield_app';
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
 // Reflect the @ObjectType/@Field metadata off each decorated class into its registration
@@ -30,7 +36,9 @@ const BranchReg = reflectObjectType(Branch);
 // Resolve a column by role from a reflected object registration (single source of truth).
 const col = (reg, role) => columnForRole(reg, role);
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // companies (the tenant) — hierarchy + type + status.
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyReg.table}\` (
     ${col(CompanyReg, 'primaryKey')} VARCHAR(36)  NOT NULL,
@@ -89,7 +97,9 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // Reverse dependency order — membership tables (1710000000002) drop first via their
   // own down(); here drop the catalogs + principal + tenant.
   for (const t of [BranchReg.table, DepartmentReg.table, RoleReg.table, UserReg.table, CompanyReg.table]) {
@@ -97,4 +107,4 @@ async function down({ query }) {
   }
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000002-CreateMembershipAndPostings.cjs

@@ -15,8 +15,14 @@ const {
   CompanyMembership, MembershipPosting, CompanyDepartment, CompanyBranch,
 } = require('@astram/identity');
 const { columnForRole, reflectObjectType } = require('@astram/engine');
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['a214c2b29d1b21093851d3644581b17757a78e2341b50c67c7b9b3846c5dfc9e'];
 
-const SCHEMA = 'shield_app';
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
 // The decorated classes carry NO static `.table` — @ObjectType/@Field metadata is read
@@ -34,7 +40,9 @@ const CompanyDepartmentReg = reflectObjectType(CompanyDepartment);
 const CompanyBranchReg = reflectObjectType(CompanyBranch);
 const col = (reg, role) => columnForRole(reg, role);
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // company_membership — first-class membership + active-tenant pointer.
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`${CompanyMembershipReg.table}\` (
     ${col(CompanyMembershipReg, 'primaryKey')} VARCHAR(36) NOT NULL,
@@ -102,10 +110,12 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   for (const t of [MembershipPostingReg.table, CompanyBranchReg.table, CompanyDepartmentReg.table, CompanyMembershipReg.table]) {
     await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${t}\``);
   }
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000003-CreateIdentityCredential.cjs

@@ -25,9 +25,17 @@
  * Idempotent (CREATE TABLE IF NOT EXISTS).
  */
 
-const SCHEMA = 'shield_identity';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['440923cce54f25764ca53fd68d3e18d7069207b22c3f2afb5551469a0279a1aa'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   // identity_credential — one row per login principal. Resolved by
   // ic_identity_hint (username/email) at login. ic_password_hash is the
   // Argon2id encoded hash the engine verifies against. Whether the principal
@@ -51,8 +59,10 @@ async function up({ query }) {
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`identity_credential\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000004-CreateSessionTables.cjs

@@ -23,9 +23,17 @@
  * Idempotent (CREATE TABLE IF NOT EXISTS).
  */
 
-const SCHEMA = 'shield_identity';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['882c6700cb00a977a1dc5038de0a1e107a279a28312a44359f5c8f8efa595c83'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   // session — the authoritative session record (written at login; read/updated
   // at refresh + revocation). s_absolute_expires_at_ms anchors the ADR-0015
   // absolute cap (from login, never reset). Status ∈ active|rotated|revoked|expired.
@@ -70,10 +78,12 @@ async function up({ query }) {
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   // Child before parent — refresh_token FK-references session.
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`refresh_token\``);
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`session\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000005-CreateMfaAndTokenSurface.cjs

@@ -39,9 +39,17 @@
  * Idempotent (CREATE TABLE IF NOT EXISTS).
  */
 
-const SCHEMA = 'shield_identity';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['47015938e94c86373d0947828f6cb5019aff90d414391eccb8c52b40c81d7612'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   await query(
     `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`mfa_device\` (
       md_id              VARCHAR(36)  NOT NULL,
@@ -79,10 +87,12 @@ async function up({ query }) {
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   for (const t of ['mfa_recovery_code', 'password_reset_token', 'mfa_device']) {
     await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${t}\``);
   }
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000010-CreateAuditLog.cjs

@@ -13,9 +13,17 @@
  * server/migrations/1720000000002-CreateAuditLog.js. Idempotent.
  */
 
-const SCHEMA = 'shield_audit';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['da5fa4187db370cf9f70d97a94e27e54055bcb5bf9e8cfd6305a9bcfef748703'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).audit;
   await query(`CREATE SCHEMA IF NOT EXISTS \`${SCHEMA}\` DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`audit_log\` (
@@ -35,8 +43,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).audit;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`audit_log\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000011-CreateCrossTenantGrant.cjs

@@ -28,10 +28,19 @@
  * table. Timestamp 1710000000011 sorts after audit (...010) and before the dev seed (...099).
  */
 
-const SCHEMA = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['3672b420280dc95cf15faab0a0a75cf7cdbf7d4b63cd3634bbe1508bf48d93a4'];
+
 const TS = 'TIMESTAMP(0) NOT NULL DEFAULT CURRENT_TIMESTAMP';
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`cross_tenant_grant\` (
     ctg_uuid                VARCHAR(36)  NOT NULL,                 -- PK (grant uuid)
     ctg_owning_tenant_uuid  VARCHAR(36)  NOT NULL,                 -- tenant whose data is reached into / who consents
@@ -59,8 +68,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).authz;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`cross_tenant_grant\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000012-SeedCrossTenantGrantPerms.cjs

@@ -35,7 +35,14 @@
  * optional at grant-write time; `role_permission` has no FK to `permission`).
  */
 
-const AUTHZ = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['10cd7ad4323cc79408a0dab2334b76d0cae289c25a29838257515c776e0b04e6'];
+
 const MODULE = 'identity';
 const TYPE_KEY = 'cross_tenant_grant';
 const NEW_ACTIONS = ['share', 'accept', 'revoke'];
@@ -51,7 +58,9 @@ const OLD_ADMIN_KEYS = [
   'identity',
 ];
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const AUTHZ = frameworkSchemasForMigration(ctx, process.env).authz;
   // Every DISTINCT role currently holding ANY of the coarse identity-admin keys.
   const oldAdminKeyPlaceholders = OLD_ADMIN_KEYS.map(() => '?').join(', ');
   const adminRoles = await query(
@@ -75,7 +84,9 @@ async function up({ query }) {
   }
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const AUTHZ = frameworkSchemasForMigration(ctx, process.env).authz;
   const keyPlaceholders = NEW_KEYS.map(() => '?').join(', ');
   await query(
     `DELETE FROM \`${AUTHZ}\`.\`role_permission\` WHERE rp_perm_key IN (${keyPlaceholders})`,
@@ -83,4 +94,4 @@ async function down({ query }) {
   );
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000013-CreateSharedResource.cjs

@@ -11,9 +11,17 @@
  * only the table, not the schema. Idempotent (IF NOT EXISTS); down() drops the table.
  */
 
-const SCHEMA = 'shield_app';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['a7ae9649c125ecc1565363def7b0d0fc69a313230bec67bfc4025af80e898c04'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`shared_resource\` (
     sr_uuid      VARCHAR(36)  NOT NULL,
     sr_tenant_id VARCHAR(36)  NOT NULL,
@@ -23,8 +31,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`shared_resource\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000018-CreateServiceAccount.cjs

@@ -20,13 +20,20 @@
  */
 const { ServiceAccount } = require('@astram/identity');
 const { columnForRole, reflectObjectType } = require('@astram/engine');
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-const SCHEMA = 'shield_app';
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['848b0ff08ec31c851dec3c891e0c87920ba956c8ad2989ee03bc8509c2e28c20'];
 
 const SaReg = reflectObjectType(ServiceAccount);
 const col = (role) => columnForRole(SaReg, role);
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   // Only `primaryKey` + `status` are engine ROLES (single-sourced via col()); the other columns
   // carry no role, so they are named literally — matching their `@Field({ column })` on the object
   // (sa_tenant_id/sa_label/sa_created_at_ms) or are store-only (sa_scope_subtree/sa_role_ids/…).
@@ -46,8 +53,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`${SaReg.table}\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000019-AddSessionMustReenroll.cjs

@@ -19,17 +19,27 @@
  * change).
  */
 
-const SCHEMA = 'shield_identity';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['a734be029c84615378c41aca1b0dc0cfac00d4213c87f0ea11700902a8319c0d'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   await query(
     `ALTER TABLE \`${SCHEMA}\`.\`session\`
        ADD COLUMN IF NOT EXISTS \`s_must_reenroll\` TINYINT(1) NOT NULL DEFAULT 0`,
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   await query(`ALTER TABLE \`${SCHEMA}\`.\`session\` DROP COLUMN IF EXISTS \`s_must_reenroll\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000020-CreateEmailChangeToken.cjs

@@ -30,9 +30,17 @@
  * names. Idempotent (CREATE TABLE IF NOT EXISTS / DROP TABLE IF EXISTS).
  */
 
-const SCHEMA = 'shield_identity';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['978e80f32ad2103c6e298ed70fb8b73fab557448a376e80650f1d1c9f892aa39'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const { identity: SCHEMA, app: APP } = frameworkSchemasForMigration(ctx, process.env);
   await query(
     `CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`email_change_token\` (
       ect_token_hash     VARCHAR(64)  NOT NULL,
@@ -49,14 +57,16 @@ async function up({ query }) {
       INDEX idx_ect_principal (ect_principal_id),
       INDEX idx_ect_expires (ect_expires_at_ms),
       CONSTRAINT FK_email_change_token_user
-        FOREIGN KEY (ect_principal_id) REFERENCES \`shield_app\`.\`users\` (u_uuid)
+        FOREIGN KEY (ect_principal_id) REFERENCES \`${APP}\`.\`users\` (u_uuid)
         ON DELETE CASCADE
     ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`,
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).identity;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`email_change_token\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000021-AddUsersEmailUniqueIndex.cjs

@@ -38,7 +38,14 @@
  * (`...099`/`...100`, distinct addresses).
  */
 
-const SCHEMA = 'shield_app';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['a08085e726ff0c2ec24c069cf099097a0bdefd06d0cab22c7d528280753de3f0'];
+
 const TABLE = 'users';
 const COLUMN = 'u_email';
 const INDEX = 'uq_users_email';
@@ -47,7 +54,7 @@ const MIGRATION = '1710000000021-AddUsersEmailUniqueIndex';
 const MAX_LISTED_GROUPS = 50;
 const ER_DUP_ENTRY = 1062;
 
-/** Same rule as `@astram/guard` `maskEmail` (kept local: a migration loads no runtime package). */
+/** Same rule as `@astram/guard` `maskEmail` (kept local: the migration loads only `@astram/core`, which has no such helper). */
 function maskEmail(value) {
   const at = value.lastIndexOf('@');
   if (at <= 0 || at === value.length - 1) return '***';
@@ -55,7 +62,7 @@ function maskEmail(value) {
 }
 
 /** `null` = no index of that name; otherwise whether it is UNIQUE. */
-async function indexState(query) {
+async function indexState(query, SCHEMA) {
   const rows = await query(
     `SELECT NON_UNIQUE AS non_unique
        FROM information_schema.STATISTICS
@@ -68,7 +75,7 @@ async function indexState(query) {
 }
 
 /** Duplicate groups by the column collation: `[{ masked, count }]`, largest first. */
-async function duplicateGroups(query) {
+async function duplicateGroups(query, SCHEMA) {
   const rows = await query(
     `SELECT ${COLUMN} AS sample, COUNT(*) AS n
        FROM \`${SCHEMA}\`.\`${TABLE}\`
@@ -84,7 +91,7 @@ async function duplicateGroups(query) {
   }));
 }
 
-function duplicateError(groups, emptiesNormalised) {
+function duplicateError(groups, emptiesNormalised, SCHEMA) {
   const listed = groups.slice(0, MAX_LISTED_GROUPS).map((g) => `  - ${g.masked}: ${g.count} users`);
   if (groups.length > MAX_LISTED_GROUPS) {
     listed.push(`  - ... and ${groups.length - MAX_LISTED_GROUPS} more group(s)`);
@@ -104,8 +111,10 @@ function duplicateError(groups, emptiesNormalised) {
   );
 }
 
-async function up({ query }) {
-  const state = await indexState(query);
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
+  const state = await indexState(query, SCHEMA);
   if (state !== null) {
     if (state.unique) return; // already applied (idempotent re-run)
     throw new Error(
@@ -120,8 +129,8 @@ async function up({ query }) {
       WHERE ${COLUMN} IS NOT NULL AND ${COLUMN} REGEXP '^[[:space:]]*$'`,
   );
 
-  const groups = await duplicateGroups(query);
-  if (groups.length > 0) throw duplicateError(groups, false);
+  const groups = await duplicateGroups(query, SCHEMA);
+  if (groups.length > 0) throw duplicateError(groups, false, SCHEMA);
 
   try {
     await query(
@@ -130,16 +139,18 @@ async function up({ query }) {
   } catch (err) {
     if (err === null || typeof err !== 'object' || err.errno !== ER_DUP_ENTRY) throw err;
     // A duplicate was written after the pre-check. Never surface the driver message (full address).
-    const late = await duplicateGroups(query);
-    if (late.length > 0) throw duplicateError(late, true);
+    const late = await duplicateGroups(query, SCHEMA);
+    if (late.length > 0) throw duplicateError(late, true, SCHEMA);
     throw new Error(
       `${MIGRATION}: a duplicate ${COLUMN} was written while the index was built; re-run astram-migrate.`,
     );
   }
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`ALTER TABLE \`${SCHEMA}\`.\`${TABLE}\` DROP INDEX IF EXISTS \`${INDEX}\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000022-CreateStoredFile.cjs

@@ -16,9 +16,17 @@
  * No seed, no hard-coded ids.
  */
 
-const SCHEMA = 'shield_app';
+const { frameworkSchemasForMigration } = require('@astram/core');
 
-async function up({ query }) {
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['e2af5c4329d6b312ebbe1f8d61e8043ec578554e9ba59e18647ed7a8eb650d18'];
+
+async function up(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`CREATE TABLE IF NOT EXISTS \`${SCHEMA}\`.\`stored_file\` (
     sf_uuid          VARCHAR(36)     NOT NULL,
     sf_tenant_id     VARCHAR(36)     NOT NULL,
@@ -36,8 +44,10 @@ async function up({ query }) {
   ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci`);
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const SCHEMA = frameworkSchemasForMigration(ctx, process.env).app;
   await query(`DROP TABLE IF EXISTS \`${SCHEMA}\`.\`stored_file\``);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };

package/migrations/1710000000099-SeedDevIdentity.cjs

@@ -20,9 +20,13 @@
  * by business key). down() removes the chain by business key.
  */
 
-const APP = 'shield_app';
-const IDENT = 'shield_identity';
-const AUTHZ = 'shield_authz';
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+// Database names come from `ctx.schemas` (SHIELD_DB_NAMESPACE, ADR-0037); under an older
+// @astram/migrate without it, the default names apply only while the namespace is unset.
+// replacesChecksums: every checksum this file had in a published release (git release tags), so
+// an existing ledger row is accepted and updated, not reported as drift (ADR-0037).
+const replacesChecksums = ['9b8a1ed3b967b95ae784396d9f14ee87dfc64253f3389ca4d413ca16f4f229d9'];
 
 const COMPANY = 'Astram Dev Co';
 const USERNAME = 'admin';
@@ -38,7 +42,9 @@ function seedEnabled() {
   return process.env.NODE_ENV === 'development' || process.env.ASTRAM_SEED_DEV === '1';
 }
 
-async function up({ query }) {
+async function up(ctx) {
+  const { query } = ctx;
+  const { app: APP, identity: IDENT, authz: AUTHZ } = frameworkSchemasForMigration(ctx, process.env);
   if (!seedEnabled()) return; // production / non-dev → no-op
 
   // 1) company (tenant)
@@ -109,7 +115,9 @@ async function up({ query }) {
   );
 }
 
-async function down({ query }) {
+async function down(ctx) {
+  const { query } = ctx;
+  const { app: APP, identity: IDENT, authz: AUTHZ } = frameworkSchemasForMigration(ctx, process.env);
   // Remove by business key (safe whether or not seed ran). Order: dependents first.
   const [role] = await query(`SELECT r_uuid FROM \`${APP}\`.\`roles\` WHERE r_name = ? LIMIT 1`, [ROLE]);
   if (role) {
@@ -127,4 +135,4 @@ async function down({ query }) {
   await query(`DELETE FROM \`${APP}\`.\`companies\` WHERE c_name = ?`, [COMPANY]);
 }
 
-module.exports = { up, down };
+module.exports = { up, down, replacesChecksums };