@astram/identity 0.16.0 → 0.17.0

package/migrations/1710000000106-OwnRolesPerCompany.cjs

@@ -0,0 +1,622 @@
+/**
+ * Framework identity migration — each company OWNS its roles (G-013, spec §4).
+ *
+ * WHY: `roles` was a global catalog (`UNIQUE (r_name)`): one "Manager" row was posted in many
+ * companies and an edit reached all of them. After this migration a role belongs to exactly one
+ * company (`r_owner_company_uuid`, added by `...101`), is assigned only in that company, and its
+ * name is unique only within the company. Shared roles are split per using company with the same
+ * effective permissions, so nobody gains or loses access.
+ *
+ * "Using companies" of a role = the companies of the memberships whose postings name it plus the
+ * `sa_tenant_id` of the service accounts whose `sa_role_ids` contain it (only existing companies:
+ * the owner FK needs one). "C in the subtree of X" = a `scope_closure` row (ancestor X,
+ * descendant C); the closure holds the depth-0 self row.
+ *
+ * Steps (idempotent; a half-applied state is completed, a re-run changes nothing):
+ *   1. DROP the global unique `IDX_roles_name` when present (copies share the name).
+ *   2. KEEP a role with no using company, or whose owner is one of its using companies.
+ *      RE-OWN otherwise (owner NULL, or the `...101` top-level tenant while only child companies
+ *      use it): the original goes to the using company with the smallest `c_uuid` (compare-and-set
+ *      on the owner read, so a re-run never overwrites).
+ *   3. SPLIT: every other using company C gets a copy (an existing role C owns with the same name,
+ *      column collation, is reused, else one is inserted with `UUID()`, same name and created_at).
+ *      For the copy, creates before moves:
+ *      - every `role_permission` row (new `rp_uuid`, attribution columns copied);
+ *      - `record_permission_rule` rows whose subject is the original (kind `role`): copied when
+ *        `rpr_tenant_uuid` IS NULL or C is in its subtree. A policy group (`rpr_policy_uuid`) is
+ *        copied whole, in ONE statement, with one new policy uuid per (group, copy), and only when
+ *        every row of the group names the original and passes the predicate (a partial group
+ *        would drop an AND condition and widen the rule). Other subjects and `everyone` rows are
+ *        never copied;
+ *      - `record_share` (grantee kind `role`): copied when `rs_tenant_uuid` is in C's subtree;
+ *      - `cross_tenant_grant` (grantee kind `role`): copied when C is in the subtree of
+ *        `ctg_grantee_tenant_uuid` (owning tenant, scope, actions, status, expiry unchanged);
+ *      - `security_policy` (target kind `role`): copied when `sp_platform = 1` or C is in the
+ *        subtree of `sp_scope_node_uuid` (a copy's holders stay required to use 2FA);
+ *      each insert skips a row the copy already has, so a re-run adds nothing. Rows failing their
+ *      predicate are counted as skipped. Then C's twin postings already on the copy are removed
+ *      (resume safety, as `...105`), C's postings and C's service accounts' `sa_role_ids` move to
+ *      the copy, and the permission version of C and of the original's owner is incremented
+ *      (once per company per run; `PermissionVersionBumper`'s statement; Redis is not touched,
+ *      its copy expires within the TTL). A re-run finds no role used off its owner and does
+ *      nothing (no bump).
+ *   4. ADD UNIQUE `IDX_roles_owner_name (r_owner_company_uuid, r_name)` when absent; duplicates
+ *      fail with their names, nothing indexed. NULL owners do not collide (root-only legacy rows).
+ *   5. PRINT a summary per re-owned or split role: name, owner, each copy's owner company, counts
+ *      of postings and service accounts repointed and rows copied/skipped per table. Names and
+ *      counts only, no uuids. These writes bypass the engine and write no `audit_log` rows (the DDL
+ *      account has no audit path): keep this output with the upgrade record (runbook §6).
+ * Snapshots `identity_credential.ic_roles` and `service_account_key.sak_role_ids` are not rewritten.
+ *
+ * `down`: refuses (no change) while a role name is held by more than one role and the global
+ * unique is absent; otherwise drops the per-company unique and re-adds the global unique (IF
+ * [NOT] EXISTS each). Copies are not merged back and owners are not reverted.
+ *
+ * Names: databases from `ctx.schemas` (`frameworkSchemasForMigration`): app (roles, postings,
+ * memberships, service accounts, companies, security policies) and authz (role_permission, rules,
+ * shares, cross-tenant grants, closure, permission version), so the four-database, namespace and
+ * single layouts all work. Literal table/column/index names, every value `?`-bound, no hardcoded
+ * ids. Sorts after `...101` (owner column), `...104` (security_policy) and `...105` (the latest).
+ */
+
+const { frameworkSchemasForMigration } = require('@astram/core');
+
+const MIGRATION = '1710000000106-OwnRolesPerCompany';
+const GLOBAL_UNIQUE = 'IDX_roles_name';
+const COMPANY_UNIQUE = 'IDX_roles_owner_name';
+/** Duplicate groups listed in a failure message; the rest are counted. */
+const MAX_LISTED = 50;
+const TABLES = [
+  'role_permission',
+  'record_permission_rule',
+  'record_share',
+  'cross_tenant_grant',
+  'security_policy',
+];
+
+const rowsOf = (result) => (Array.isArray(result) ? result : []);
+const affected = (result) =>
+  result && typeof result === 'object' && !Array.isArray(result)
+    ? Number(result.affectedRows ?? 0)
+    : 0;
+const sameId = (a, b) =>
+  typeof a === 'string' && typeof b === 'string' && a.toLowerCase() === b.toLowerCase();
+const tbl = (db, table) => `\`${db}\`.\`${table}\``;
+
+const hasIndex = async (query, APP, index) =>
+  rowsOf(
+    await query(
+      `SELECT 1 AS n FROM information_schema.STATISTICS
+        WHERE TABLE_SCHEMA = ? AND TABLE_NAME = 'roles' AND INDEX_NAME = ? LIMIT 1`,
+      [APP, index],
+    ),
+  ).length > 0;
+
+/** One (role, company) row per using company, ordered by role then company (MIN first). */
+async function usages(query, N) {
+  return rowsOf(
+    await query(`SELECT u.role AS role, u.company AS company, r.r_name AS name,
+             r.r_owner_company_uuid AS owner
+        FROM (SELECT mp.mp_role_uuid AS role, cm.cm_company_uuid AS company
+                FROM ${N.MP} mp
+                JOIN ${N.CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+              UNION
+              SELECT sr.r_uuid AS role, sa.sa_tenant_id AS company
+                FROM ${N.SA} sa
+                JOIN ${N.COMPANIES} c ON c.c_uuid = sa.sa_tenant_id
+                JOIN ${N.ROLES} sr ON JSON_CONTAINS(sa.sa_role_ids, JSON_QUOTE(sr.r_uuid))) u
+        JOIN ${N.ROLES} r ON r.r_uuid = u.role
+       ORDER BY u.role, u.company`),
+  );
+}
+
+async function findOwned(query, N, company, name) {
+  const rows = rowsOf(
+    await query(
+      `SELECT r_uuid AS uuid FROM ${N.ROLES} WHERE r_owner_company_uuid = ? AND r_name = ? ORDER BY r_uuid LIMIT 1`,
+      [company, name],
+    ),
+  );
+  return rows.length > 0 ? String(rows[0].uuid) : null;
+}
+
+/** The copy of `role` owned by `company`: reused when present, else inserted. */
+async function ensureCopy(query, N, role, company, name) {
+  let copy = await findOwned(query, N, company, name);
+  if (copy !== null) return copy;
+  await query(
+    `INSERT INTO ${N.ROLES} (r_uuid, r_name, r_owner_company_uuid, r_created_at)
+     SELECT UUID(), src.r_name, ?, src.r_created_at FROM ${N.ROLES} src WHERE src.r_uuid = ?`,
+    [company, role],
+  );
+  copy = await findOwned(query, N, company, name);
+  if (copy === null) {
+    throw new Error(`${MIGRATION}: could not create a company-owned role copy; re-run.`);
+  }
+  return copy;
+}
+
+async function copyRolePermissions(query, N, role, copy) {
+  const result = await query(
+    `INSERT INTO ${N.RP} (rp_uuid, rp_role_uuid, rp_perm_key, rp_created_by, rp_created_at, rp_granted_by, rp_granted_at)
+     SELECT UUID(), ?, src.rp_perm_key, src.rp_created_by, src.rp_created_at, src.rp_granted_by, src.rp_granted_at
+       FROM ${N.RP} src
+      WHERE src.rp_role_uuid = ?
+        AND NOT EXISTS (SELECT 1 FROM ${N.RP} d WHERE d.rp_role_uuid = ? AND d.rp_perm_key = src.rp_perm_key)`,
+    [copy, role, copy],
+  );
+  return { copied: affected(result), skipped: 0 };
+}
+
+/** Rules naming `subject` (kind role), each with its predicate for `company` and group size. */
+async function rulesOf(query, N, subject, company) {
+  return rowsOf(
+    await query(
+      `SELECT src.rpr_uuid AS id, src.rpr_policy_uuid AS policy, src.rpr_tenant_uuid AS tenant,
+              src.rpr_type_key AS type_key, src.rpr_action AS action, src.rpr_effect AS effect,
+              src.rpr_field AS field, src.rpr_operator AS operator, src.rpr_value AS value,
+              CASE WHEN src.rpr_tenant_uuid IS NULL OR EXISTS (SELECT 1 FROM ${N.SC} sc
+                     WHERE sc.ancestor_uuid = src.rpr_tenant_uuid AND sc.descendant_uuid = ?)
+                   THEN 1 ELSE 0 END AS applies,
+              (SELECT COUNT(*) FROM ${N.RPR} g WHERE g.rpr_policy_uuid = src.rpr_policy_uuid) AS group_size
+         FROM ${N.RPR} src
+        WHERE src.rpr_subject_kind = 'role' AND src.rpr_subject_value = ?
+        ORDER BY src.rpr_policy_uuid, src.rpr_uuid`,
+      [company, subject],
+    ),
+  );
+}
+
+const ruleSig = (r) =>
+  JSON.stringify([
+    r.tenant ?? null,
+    r.type_key,
+    r.action,
+    r.effect,
+    r.field ?? null,
+    r.operator ?? null,
+    r.value ?? null,
+  ]);
+
+/** Group rules by policy uuid (ungrouped rows each their own unit); signature per unit. */
+function units(rows) {
+  const groups = new Map();
+  const singles = [];
+  for (const r of rows) {
+    if (r.policy === null || r.policy === undefined) {
+      singles.push({ rows: [r], sig: ruleSig(r) });
+      continue;
+    }
+    const key = String(r.policy);
+    const g = groups.get(key) ?? { policy: key, rows: [] };
+    g.rows.push(r);
+    groups.set(key, g);
+  }
+  const grouped = [...groups.values()].map((g) => ({
+    ...g,
+    sig: g.rows.map(ruleSig).sort().join('\n'),
+  }));
+  return { singles, grouped };
+}
+
+const take = (multiset, sig) => {
+  const n = multiset.get(sig) ?? 0;
+  if (n === 0) return false;
+  multiset.set(sig, n - 1);
+  return true;
+};
+const countSigs = (list) => {
+  const m = new Map();
+  for (const u of list) m.set(u.sig, (m.get(u.sig) ?? 0) + 1);
+  return m;
+};
+
+const RULE_COLUMNS = `rpr_uuid, rpr_policy_uuid, rpr_tenant_uuid, rpr_type_key, rpr_action, rpr_effect,
+       rpr_subject_kind, rpr_subject_value, rpr_field, rpr_operator, rpr_value, rpr_created_at`;
+const RULE_VALUES = `src.rpr_tenant_uuid, src.rpr_type_key, src.rpr_action, src.rpr_effect,
+       'role', ?, src.rpr_field, src.rpr_operator, src.rpr_value, src.rpr_created_at`;
+
+async function copyRules(query, N, role, copy, company) {
+  const source = units(await rulesOf(query, N, role, company));
+  const existing = units(await rulesOf(query, N, copy, company));
+  const haveSingles = countSigs(existing.singles);
+  const haveGroups = countSigs(existing.grouped);
+  let copied = 0;
+  let skipped = 0;
+
+  for (const u of source.singles) {
+    const r = u.rows[0];
+    if (Number(r.applies) !== 1) {
+      skipped += 1;
+      continue;
+    }
+    if (take(haveSingles, u.sig)) continue;
+    copied += affected(
+      await query(
+        `INSERT INTO ${N.RPR} (${RULE_COLUMNS})
+         SELECT UUID(), NULL, ${RULE_VALUES} FROM ${N.RPR} src WHERE src.rpr_uuid = ?`,
+        [copy, r.id],
+      ),
+    );
+  }
+
+  for (const g of source.grouped) {
+    const whole = g.rows.every(
+      (r) => Number(r.applies) === 1 && Number(r.group_size) === g.rows.length,
+    );
+    if (!whole) {
+      skipped += g.rows.length;
+      continue;
+    }
+    if (take(haveGroups, g.sig)) continue;
+    const fresh = rowsOf(await query('SELECT UUID() AS uuid'));
+    if (fresh.length === 0) throw new Error(`${MIGRATION}: UUID() returned no row.`);
+    copied += affected(
+      await query(
+        `INSERT INTO ${N.RPR} (${RULE_COLUMNS})
+         SELECT UUID(), ?, ${RULE_VALUES} FROM ${N.RPR} src
+          WHERE src.rpr_policy_uuid = ? AND src.rpr_subject_kind = 'role' AND src.rpr_subject_value = ?`,
+        [String(fresh[0].uuid), copy, g.policy, role],
+      ),
+    );
+  }
+  return { copied, skipped };
+}
+
+/**
+ * Tenant-scoped tables copied by one set-based statement each. `pred` holds one `?` (the copy's
+ * owner company); `dup` matches an equivalent row already naming the copy (`d`).
+ */
+const SCOPED = [
+  {
+    label: 'record_share',
+    table: (N) => N.RS,
+    kind: 'rs_grantee_kind',
+    value: 'rs_grantee_uuid',
+    pred: (N) =>
+      `EXISTS (SELECT 1 FROM ${N.SC} sc WHERE sc.ancestor_uuid = ? AND sc.descendant_uuid = src.rs_tenant_uuid)`,
+    columns: `rs_uuid, rs_tenant_uuid, rs_type_key, rs_record_uuid, rs_grantee_kind, rs_grantee_uuid,
+       rs_action, rs_granted_by, rs_created_at`,
+    values: `UUID(), src.rs_tenant_uuid, src.rs_type_key, src.rs_record_uuid, 'role', ?,
+       src.rs_action, src.rs_granted_by, src.rs_created_at`,
+    dup: `d.rs_tenant_uuid = src.rs_tenant_uuid AND d.rs_type_key = src.rs_type_key
+       AND d.rs_record_uuid = src.rs_record_uuid AND d.rs_action = src.rs_action`,
+  },
+  {
+    label: 'cross_tenant_grant',
+    table: (N) => N.CTG,
+    kind: 'ctg_grantee_kind',
+    value: 'ctg_grantee_uuid',
+    pred: (N) =>
+      `EXISTS (SELECT 1 FROM ${N.SC} sc WHERE sc.ancestor_uuid = src.ctg_grantee_tenant_uuid AND sc.descendant_uuid = ?)`,
+    columns: `ctg_uuid, ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid, ctg_grantee_kind,
+       ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_record_uuid, ctg_allowed_actions, ctg_status,
+       ctg_offered_by, ctg_expires_at_ms, ctg_created_at, ctg_accepted_at, ctg_revoked_at`,
+    values: `UUID(), src.ctg_owning_tenant_uuid, src.ctg_grantee_tenant_uuid, 'role',
+       ?, src.ctg_type_key, src.ctg_scope, src.ctg_record_uuid, src.ctg_allowed_actions, src.ctg_status,
+       src.ctg_offered_by, src.ctg_expires_at_ms, src.ctg_created_at, src.ctg_accepted_at, src.ctg_revoked_at`,
+    dup: `d.ctg_owning_tenant_uuid = src.ctg_owning_tenant_uuid
+       AND d.ctg_grantee_tenant_uuid = src.ctg_grantee_tenant_uuid AND d.ctg_type_key = src.ctg_type_key
+       AND d.ctg_scope = src.ctg_scope AND d.ctg_record_uuid <=> src.ctg_record_uuid
+       AND d.ctg_allowed_actions = src.ctg_allowed_actions AND d.ctg_status = src.ctg_status
+       AND d.ctg_offered_by = src.ctg_offered_by AND d.ctg_expires_at_ms = src.ctg_expires_at_ms`,
+  },
+  {
+    label: 'security_policy',
+    table: (N) => N.SP,
+    kind: 'sp_target_kind',
+    value: 'sp_target_value',
+    pred: (N) =>
+      `(src.sp_platform = 1 OR EXISTS (SELECT 1 FROM ${N.SC} sc WHERE sc.ancestor_uuid = src.sp_scope_node_uuid AND sc.descendant_uuid = ?))`,
+    columns: `sp_uuid, sp_scope_node_uuid, sp_platform, sp_target_kind, sp_target_value, sp_grace_days,
+       sp_created_at_node, sp_created_by, sp_created_at_ms, sp_updated_at_ms`,
+    values: `UUID(), src.sp_scope_node_uuid, src.sp_platform, 'role', ?, src.sp_grace_days,
+       src.sp_created_at_node, src.sp_created_by, src.sp_created_at_ms, src.sp_updated_at_ms`,
+    dup: `d.sp_scope_node_uuid <=> src.sp_scope_node_uuid AND d.sp_platform = src.sp_platform
+       AND d.sp_grace_days = src.sp_grace_days AND d.sp_created_by = src.sp_created_by
+       AND d.sp_created_at_ms = src.sp_created_at_ms`,
+  },
+];
+
+async function copyScoped(query, N, s, role, copy, company) {
+  const T = s.table(N);
+  const pred = s.pred(N);
+  const counts = rowsOf(
+    await query(
+      `SELECT COUNT(*) AS total, COALESCE(SUM(CASE WHEN ${pred} THEN 1 ELSE 0 END), 0) AS applies
+         FROM ${T} src WHERE src.${s.kind} = 'role' AND src.${s.value} = ?`,
+      [company, role],
+    ),
+  )[0] ?? { total: 0, applies: 0 };
+  const result = await query(
+    `INSERT INTO ${T} (${s.columns})
+     SELECT ${s.values}
+       FROM ${T} src
+      WHERE src.${s.kind} = 'role' AND src.${s.value} = ? AND ${pred}
+        AND NOT EXISTS (SELECT 1 FROM ${T} d
+                         WHERE d.${s.kind} = 'role' AND d.${s.value} = ? AND ${s.dup})`,
+    [copy, role, company, copy],
+  );
+  return {
+    copied: affected(result),
+    skipped: Number(counts.total ?? 0) - Number(counts.applies ?? 0),
+  };
+}
+
+function parseRoleIds(value) {
+  let v = value;
+  if (typeof v === 'string') {
+    try {
+      v = JSON.parse(v);
+    } catch {
+      v = null;
+    }
+  }
+  if (!Array.isArray(v)) {
+    throw new Error(
+      `${MIGRATION}: a service account's role list is not a JSON array; fix it and re-run.`,
+    );
+  }
+  return v;
+}
+
+/** Move `company`'s postings and service accounts from `role` to `copy`. */
+async function repoint(query, N, role, copy, company) {
+  // Resume safety (as `...105`): a membership may already hold the same posting on the copy
+  // (a partial earlier run, or the old app adding it again). Repointing its twin would break
+  // `IDX_mp_unique` (1062) and fail every re-run, so the twin on the original goes first; the
+  // posting on the copy keeps the assignment.
+  await query(
+    `DELETE mp FROM ${N.MP} mp
+       JOIN ${N.CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+       JOIN ${N.MP} twin ON twin.mp_membership_uuid = mp.mp_membership_uuid
+                        AND twin.mp_department_uuid <=> mp.mp_department_uuid
+                        AND twin.mp_branch_uuid <=> mp.mp_branch_uuid
+                        AND twin.mp_role_uuid = ?
+      WHERE mp.mp_role_uuid = ? AND cm.cm_company_uuid = ?`,
+    [copy, role, company],
+  );
+  const postings = affected(
+    await query(
+      `UPDATE ${N.MP} mp
+         JOIN ${N.CM} cm ON cm.cm_uuid = mp.mp_membership_uuid
+          SET mp.mp_role_uuid = ?
+        WHERE mp.mp_role_uuid = ? AND cm.cm_company_uuid = ?`,
+      [copy, role, company],
+    ),
+  );
+
+  const accounts = rowsOf(
+    await query(
+      `SELECT sa_id AS id, sa_role_ids AS roles FROM ${N.SA}
+        WHERE sa_tenant_id = ? AND JSON_CONTAINS(sa_role_ids, JSON_QUOTE(?)) ORDER BY sa_id`,
+      [company, role],
+    ),
+  );
+  let serviceAccounts = 0;
+  for (const a of accounts) {
+    const next = [];
+    for (const id of parseRoleIds(a.roles)) {
+      const mapped = id === role ? copy : id;
+      if (!next.includes(mapped)) next.push(mapped);
+    }
+    serviceAccounts += affected(
+      await query(
+        `UPDATE ${N.SA} SET sa_role_ids = ?
+          WHERE sa_id = ? AND JSON_CONTAINS(sa_role_ids, JSON_QUOTE(?))`,
+        [JSON.stringify(next), a.id, role],
+      ),
+    );
+  }
+  return { postings, serviceAccounts };
+}
+
+async function companyName(query, N, cache, uuid) {
+  if (cache.has(uuid)) return cache.get(uuid);
+  const rows = rowsOf(
+    await query(`SELECT c_name AS name FROM ${N.COMPANIES} WHERE c_uuid = ? LIMIT 1`, [uuid]),
+  );
+  const name = rows.length > 0 ? JSON.stringify(String(rows[0].name)) : 'an unnamed company';
+  cache.set(uuid, name);
+  return name;
+}
+
+/** Steps 2–3: keep / re-own / split every used role; returns the summary records. */
+async function ownAndSplit(query, N) {
+  const byRole = new Map();
+  for (const u of await usages(query, N)) {
+    const key = String(u.role);
+    const entry = byRole.get(key) ?? {
+      role: key,
+      name: String(u.name),
+      owner: u.owner ?? null,
+      companies: [],
+    };
+    if (!entry.companies.some((c) => sameId(c, u.company))) entry.companies.push(String(u.company));
+    byRole.set(key, entry);
+  }
+
+  const bumped = new Set();
+  const bump = async (company) => {
+    const key = company.toLowerCase();
+    if (bumped.has(key)) return;
+    await query(
+      `INSERT INTO ${N.APV} (apv_tenant_uuid, apv_version)
+         VALUES (?, 1)
+       ON DUPLICATE KEY UPDATE apv_version = apv_version + 1`,
+      [company],
+    );
+    bumped.add(key);
+  };
+
+  const report = [];
+  for (const e of byRole.values()) {
+    const before = e.owner;
+    let owner = before;
+    if (!e.companies.some((c) => sameId(c, owner))) {
+      owner = e.companies[0];
+      await query(
+        `UPDATE ${N.ROLES} SET r_owner_company_uuid = ? WHERE r_uuid = ? AND r_owner_company_uuid <=> ?`,
+        [owner, e.role, before],
+      );
+    }
+    const others = e.companies.filter((c) => !sameId(c, owner));
+    if (others.length === 0 && sameId(owner, before)) continue;
+
+    const entry = { name: e.name, before, owner, copies: [] };
+    for (const company of others) {
+      const copy = await ensureCopy(query, N, e.role, company, e.name);
+      const copied = {};
+      const skipped = {};
+      const rp = await copyRolePermissions(query, N, e.role, copy);
+      copied.role_permission = rp.copied;
+      skipped.role_permission = rp.skipped;
+      const rules = await copyRules(query, N, e.role, copy, company);
+      copied.record_permission_rule = rules.copied;
+      skipped.record_permission_rule = rules.skipped;
+      for (const s of SCOPED) {
+        const r = await copyScoped(query, N, s, e.role, copy, company);
+        copied[s.label] = r.copied;
+        skipped[s.label] = r.skipped;
+      }
+      const moved = await repoint(query, N, e.role, copy, company);
+      await bump(company);
+      await bump(owner);
+      entry.copies.push({ company, ...moved, copied, skipped });
+    }
+    report.push(entry);
+  }
+  return { report, bumped: bumped.size };
+}
+
+async function printSummary(query, N, { report, bumped }) {
+  const names = new Map();
+  if (report.length === 0) {
+    console.log(`${MIGRATION}: no role is used outside its owner company; nothing to re-own or split.`);
+    return;
+  }
+  let copies = 0;
+  for (const r of report) {
+    const owner = await companyName(query, N, names, r.owner);
+    const was = sameId(r.before, r.owner)
+      ? ''
+      : r.before === null
+        ? ' (was ownerless)'
+        : ` (re-owned from ${await companyName(query, N, names, r.before)})`;
+    const head =
+      r.copies.length === 0
+        ? `${MIGRATION}: role ${JSON.stringify(r.name)} now owned by ${owner}${was}.`
+        : `${MIGRATION}: role ${JSON.stringify(r.name)} split: original owned by ${owner}${was}; ${r.copies.length} copy(ies):`;
+    console.log(head);
+    for (const c of r.copies) {
+      copies += 1;
+      const tables = TABLES.map(
+        (t) => `${t} ${c.copied[t]} copied${t === 'role_permission' ? '' : `, ${c.skipped[t]} skipped`}`,
+      ).join('; ');
+      console.log(
+        `  - copy owned by ${await companyName(query, N, names, c.company)}: ` +
+          `${c.postings} posting(s), ${c.serviceAccounts} service account(s) repointed; ${tables}`,
+      );
+    }
+  }
+  console.log(
+    `${MIGRATION}: ${report.length} role(s) re-owned or split, ${copies} copy(ies) created or ` +
+      `completed; permission version incremented for ${bumped} compan(ies). Keep this output ` +
+      `with the upgrade record (runbook §6).`,
+  );
+}
+
+function duplicateError(APP, groups, scope, tail) {
+  const listed = groups.slice(0, MAX_LISTED).map((g) => `  - "${g.name}": ${g.n} rows`);
+  if (groups.length > MAX_LISTED) listed.push(`  - ... and ${groups.length - MAX_LISTED} more`);
+  return new Error(
+    `${MIGRATION}: ${groups.length} role name(s) occur more than once ${scope} in ${APP}.roles ` +
+      `(compared as the column collation does: case- and accent-insensitive):\n` +
+      `${listed.join('\n')}\n${tail}`,
+  );
+}
+
+/** Step 4: per-company unique when absent; duplicates fail with their names. */
+async function addCompanyUnique(query, N) {
+  if (await hasIndex(query, N.APP, COMPANY_UNIQUE)) return;
+  const groups = rowsOf(
+    await query(`SELECT MIN(r_name) AS name, COUNT(*) AS n
+        FROM ${N.ROLES}
+       WHERE r_owner_company_uuid IS NOT NULL
+       GROUP BY r_owner_company_uuid, r_name
+      HAVING COUNT(*) > 1
+       ORDER BY n DESC`),
+  );
+  if (groups.length > 0) {
+    throw duplicateError(
+      N.APP,
+      groups,
+      'within one company',
+      'No unique index was created. Rename or remove the duplicates, then re-run astram-migrate.',
+    );
+  }
+  await query(
+    `CREATE UNIQUE INDEX ${COMPANY_UNIQUE} ON ${N.ROLES} (r_owner_company_uuid, r_name)`,
+  );
+}
+
+function namesOf(ctx) {
+  const schemas = frameworkSchemasForMigration(ctx, process.env);
+  const APP = schemas.app;
+  const AUTHZ = schemas.authz;
+  return {
+    APP,
+    ROLES: tbl(APP, 'roles'),
+    COMPANIES: tbl(APP, 'companies'),
+    MP: tbl(APP, 'membership_posting'),
+    CM: tbl(APP, 'company_membership'),
+    SA: tbl(APP, 'service_account'),
+    SP: tbl(APP, 'security_policy'),
+    RP: tbl(AUTHZ, 'role_permission'),
+    RPR: tbl(AUTHZ, 'record_permission_rule'),
+    RS: tbl(AUTHZ, 'record_share'),
+    CTG: tbl(AUTHZ, 'cross_tenant_grant'),
+    SC: tbl(AUTHZ, 'scope_closure'),
+    APV: tbl(AUTHZ, 'authz_permission_version'),
+  };
+}
+
+async function up(ctx) {
+  const { query } = ctx;
+  const N = namesOf(ctx);
+  if (await hasIndex(query, N.APP, GLOBAL_UNIQUE)) {
+    await query(`DROP INDEX ${GLOBAL_UNIQUE} ON ${N.ROLES}`);
+  }
+  const result = await ownAndSplit(query, N);
+  await addCompanyUnique(query, N);
+  await printSummary(query, N, result);
+}
+
+async function down(ctx) {
+  const { query } = ctx;
+  const N = namesOf(ctx);
+  // Pre-check before any change: the global unique cannot come back while a name is held by more
+  // than one role (a split copy, or two companies' own roles).
+  if (!(await hasIndex(query, N.APP, GLOBAL_UNIQUE))) {
+    const groups = rowsOf(
+      await query(`SELECT MIN(r_name) AS name, COUNT(*) AS n
+          FROM ${N.ROLES}
+         GROUP BY r_name
+        HAVING COUNT(*) > 1
+         ORDER BY n DESC`),
+    );
+    if (groups.length > 0) {
+      throw duplicateError(
+        N.APP,
+        groups,
+        'across companies',
+        'Nothing was rolled back: the global unique name index cannot be restored while these ' +
+          'exist (split copies are not merged back). Rename or remove them first.',
+      );
+    }
+  }
+  await query(`DROP INDEX IF EXISTS ${COMPANY_UNIQUE} ON ${N.ROLES}`);
+  await query(`CREATE UNIQUE INDEX IF NOT EXISTS ${GLOBAL_UNIQUE} ON ${N.ROLES} (r_name)`);
+}
+
+module.exports = { up, down };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/identity",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "description": "Astram framework — the framework-owned identity + tenancy model. Hosts the identity @ObjectType classes (user, company, membership, posting), framework-authored identity migrations, and the identity resolver. Top of the dependency graph: depends on @astram/engine (for @ObjectType/@Field decorators) + @astram/guard / @astram/core (for the auth ports).",
   "type": "commonjs",
@@ -36,9 +36,9 @@
   },
   "dependencies": {
     "mariadb": "^3.5.4",
-    "@astram/core": "1.10.0",
-    "@astram/engine": "0.10.2",
-    "@astram/guard": "0.19.0"
+    "@astram/core": "1.11.0",
+    "@astram/guard": "0.20.0",
+    "@astram/engine": "0.11.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",