@astram/identity 0.12.0 → 0.14.0

package/dist/features/org-bootstrap/run-org-bootstrap.js

@@ -0,0 +1,688 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrgBootstrapError = void 0;
+exports.runOrgBootstrap = runOrgBootstrap;
+/**
+ * G-009 T10: the org bootstrap runner (SPEC R2, R3, R5-R11, R13; ADR-0042).
+ *
+ * `runOrgBootstrap(app, opts)` applies a declarative org file against the consumer's own application
+ * context, through the framework's existing services, never raw SQL (the exceptions are the role-owner
+ * claim and the root flag, both under the run lock and audited). Each step runs as its own principal,
+ * bound to the declared operation `shield:org-bootstrap` (Shield #9): control-plane steps root-flagged,
+ * people steps non-root and anchored at one company. The principal reaches the request-scoped services
+ * through `registerRequestByContextId`, so no service signature changes.
+ *
+ * Sequence (apply): parse -> operator/ttl checks -> GET_LOCK on a dedicated connection -> read state and
+ * plan under the lock -> plan-dependent refusals -> writes in R10 order -> links -> RELEASE_LOCK.
+ * A dry run takes no lock and writes nothing.
+ */
+const node_fs_1 = require("node:fs");
+const core_1 = require("@nestjs/core");
+const engine_1 = require("@astram/engine");
+const internal_1 = require("@astram/engine/internal");
+const guard_1 = require("@astram/guard");
+const grant_admin_service_js_1 = require("../authz/grant-admin.service.js");
+const company_service_js_1 = require("../company/company.service.js");
+const framework_schemas_token_js_1 = require("../framework-schemas.token.js");
+const membership_service_js_1 = require("../membership/membership.service.js");
+const posting_service_js_1 = require("../membership/posting.service.js");
+const org_catalog_service_js_1 = require("../org-structure/org-catalog.service.js");
+const role_owner_transition_js_1 = require("../role/role-owner-transition.js");
+const role_service_js_1 = require("../role/role.service.js");
+const credential_provisioner_token_js_1 = require("../user/credential-provisioner.token.js");
+const user_service_js_1 = require("../user/user.service.js");
+const org_bootstrap_file_js_1 = require("./org-bootstrap-file.js");
+const org_bootstrap_error_js_1 = require("./org-bootstrap-error.js");
+const org_bootstrap_plan_js_1 = require("./org-bootstrap-plan.js");
+const org_bootstrap_manifest_js_1 = require("./org-bootstrap.manifest.js");
+const org_bootstrap_tokens_js_1 = require("./org-bootstrap.tokens.js");
+const org_names_js_1 = require("./org-names.js");
+const org_state_reader_js_1 = require("./org-state.reader.js");
+const root_password_source_js_1 = require("./root-password-source.js");
+const set_password_links_js_1 = require("./set-password-links.js");
+var org_bootstrap_error_js_2 = require("./org-bootstrap-error.js");
+Object.defineProperty(exports, "OrgBootstrapError", { enumerable: true, get: function () { return org_bootstrap_error_js_2.OrgBootstrapError; } });
+const STEP = {
+    tenants: 'tenants',
+    companies: 'companies',
+    orgUnits: 'org-units',
+    roles: 'roles',
+    users: 'users',
+    postings: 'postings',
+};
+// ---------------------------------------------------------------------------------------------
+function loadFile(file) {
+    if (typeof file !== 'string')
+        return file;
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    catch {
+        // Never echo the path content or the parser message: it can quote the file.
+        throw new org_bootstrap_file_js_1.OrgBootstrapFileError([
+            { path: '(file)', message: 'cannot be read or is not valid JSON' },
+        ]);
+    }
+}
+function flatten(file) {
+    const companies = [];
+    const walk = (c, parent, tenant) => {
+        const path = parent === undefined ? c.name : `${parent}/${c.name}`;
+        companies.push({ path, parentPath: parent, tenant, node: c });
+        for (const child of c.children ?? [])
+            walk(child, path, tenant);
+    };
+    for (const t of file.tenants)
+        walk(t, undefined, t.name);
+    const users = [];
+    for (const c of companies) {
+        for (const u of c.node.users ?? []) {
+            users.push({
+                username: u.username,
+                email: u.email,
+                company: u.company === undefined ? c.path : `${c.tenant}/${u.company}`,
+                tenant: c.tenant,
+                postings: u.postings ?? [],
+            });
+        }
+    }
+    return { companies, users };
+}
+const postingPath = (user, company, p) => `user:${user}@${company} role:${p.role}${p.department ? ` dept:${p.department}` : ''}${p.branch ? ` branch:${p.branch}` : ''}`;
+function printPlan(plan, out) {
+    for (const e of plan.entries) {
+        out(`${e.status.padEnd(11)} ${e.kind} ${e.path}${e.detail === undefined ? '' : ` - ${e.detail}`}`);
+    }
+}
+// ---------------------------------------------------------------------------------------------
+async function runOrgBootstrap(app, opts) {
+    const env = opts.env ?? process.env;
+    const out = opts.out ?? ((line) => void process.stdout.write(`${line}\n`));
+    const apply = opts.apply === true;
+    await app.init();
+    let pool;
+    let schemas;
+    let provisioner;
+    let grantAdmin;
+    let tokenStore;
+    try {
+        pool = app.get(org_bootstrap_tokens_js_1.IDENTITY_AUTHZ_POOL, { strict: false });
+        schemas = app.get(framework_schemas_token_js_1.IDENTITY_FRAMEWORK_SCHEMAS, { strict: false });
+        provisioner = app.get(credential_provisioner_token_js_1.IDENTITY_CREDENTIAL_PROVISIONER, {
+            strict: false,
+        });
+        grantAdmin = app.get(grant_admin_service_js_1.GrantAdminService, { strict: false });
+        if (apply)
+            tokenStore = app.get(guard_1.SHIELD_RESET_TOKEN_STORE, { strict: false });
+    }
+    catch {
+        throw new org_bootstrap_error_js_1.OrgBootstrapError('not_wired', 'IdentityFeatureModule is not available in this application: wire IdentityFeatureModule.forRoot(...) and ShieldModule (auth enabled) into the AppModule this script creates.');
+    }
+    const catalog = await grantAdmin.listCatalog();
+    const file = (0, org_bootstrap_file_js_1.parseOrgBootstrapFile)(loadFile(opts.file), {
+        grantableKeys: new Set([...catalog.catalog.map((r) => r.key), ...catalog.wildcards]),
+    });
+    const readState = () => new org_state_reader_js_1.OrgStateReader({
+        query: async (sql, params) => (await pool.query(sql, params)),
+        schemas,
+    }).read(file);
+    const planFor = (state) => (0, org_bootstrap_plan_js_1.planOrgBootstrap)(file, state, { claimUnownedRoles: opts.claimUnownedRoles === true });
+    // ---- dry run: plan only, no lock, no write ----
+    if (!apply) {
+        const state = await readState();
+        const plan = planFor(state);
+        printPlan(plan, out);
+        const ids = new Ids(pool, schemas);
+        const rootIds = [];
+        for (const r of file.roots) {
+            if (!state.users.some((u) => (0, org_names_js_1.nameKey)(u.username) === (0, org_names_js_1.nameKey)(r.username)))
+                continue;
+            const id = await ids.user(r.username).catch(() => undefined);
+            if (id !== undefined)
+                rootIds.push(id);
+        }
+        return { applied: false, plan, written: {}, links: 0, rootIds };
+    }
+    // ---- checks that need no state ----
+    const operator = (opts.operator ?? '').trim() || (env.ASTRAM_BOOTSTRAP_OPERATOR ?? '').trim();
+    if (operator === '') {
+        throw new org_bootstrap_error_js_1.OrgBootstrapError('operator_required', '--apply needs the human operator: pass the operator or set ASTRAM_BOOTSTRAP_OPERATOR.');
+    }
+    const ttlHours = (0, set_password_links_js_1.validateLinkTtlHours)(opts.linkTtlHours ?? set_password_links_js_1.DEFAULT_LINK_TTL_HOURS);
+    // R1-13: two roots on one password variable would share a password; refused before any write.
+    (0, root_password_source_js_1.assertDistinctRootPasswordVariables)(file.roots.map((r) => r.username));
+    // ---- the run lock, on a dedicated connection ----
+    const lockName = `astram_org_bootstrap:${schemas.app}`;
+    const lockConn = await pool.getConnection();
+    try {
+        const got = (await lockConn.query('SELECT GET_LOCK(?, ?) AS acquired', [
+            lockName,
+            opts.lockTimeoutSeconds ?? 30,
+        ]));
+        if (Number(got[0]?.acquired) !== 1) {
+            throw new org_bootstrap_error_js_1.OrgBootstrapError('lock_not_acquired', 'Another org bootstrap run holds the lock; nothing was written. Retry when it finishes.');
+        }
+        try {
+            return await applyUnderLock();
+        }
+        finally {
+            try {
+                await lockConn.query('SELECT RELEASE_LOCK(?) AS released', [lockName]);
+            }
+            catch {
+                // The lock is session-scoped: it ends with the connection. Never mask the run's outcome.
+            }
+        }
+    }
+    finally {
+        await lockConn.release();
+    }
+    // ===========================================================================================
+    async function applyUnderLock() {
+        const state = await readState();
+        const plan = planFor(state);
+        printPlan(plan, out);
+        const status = new Map();
+        for (const e of plan.entries)
+            status.set(`${e.kind}\u0000${e.path}`, e.status);
+        const st = (kind, path) => status.get(`${kind}\u0000${path}`);
+        // ---- refusals that need the plan ----
+        if (plan.conflicts.length > 0) {
+            throw new org_bootstrap_error_js_1.OrgBootstrapError('plan_conflict', `The plan has ${plan.conflicts.length} conflict(s); nothing was written: ${plan.conflicts
+                .map((c) => c.detail ?? c.path)
+                .join('; ')}`);
+        }
+        const rootNames = new Set(file.roots.map((r) => (0, org_names_js_1.nameKey)(r.username)));
+        const isRootName = (username) => rootNames.has((0, org_names_js_1.nameKey)(username));
+        const rootsNeedingPassword = file.roots
+            .filter((r) => st('credential', `user:${r.username}`) === 'create')
+            .map((r) => r.username);
+        const passwords = await (0, root_password_source_js_1.resolveRootPasswords)(rootsNeedingPassword, env, opts.promptRootPassword);
+        // R1-1: a re-issued link is a credential-recovery path, so only for a user with no membership
+        // outside the file's tenants (never another tenant's account). N6: and only when the stored email
+        // still equals the file's (a drifted email is reported, OD-5, and gets no link either).
+        const lockedInState = (username) => state.users.some((u) => (0, org_names_js_1.nameKey)(u.username) === (0, org_names_js_1.nameKey)(username) &&
+            u.credential === 'locked' &&
+            !u.membershipsOutside &&
+            (0, org_names_js_1.nameKey)(u.email) === (0, org_names_js_1.nameKey)(fileEmailOf(username) ?? ''));
+        // R1-6: an existing user's login hint is the STORED email, never the file's spelling of it.
+        const hintFor = (username, fileEmail) => {
+            const stored = state.users.find((u) => (0, org_names_js_1.nameKey)(u.username) === (0, org_names_js_1.nameKey)(username));
+            if (stored === undefined)
+                return (0, guard_1.canonicalEmail)(fileEmail);
+            if ((0, org_names_js_1.nameKey)(stored.email) !== (0, org_names_js_1.nameKey)(fileEmail)) {
+                // The planner makes this a conflict; assert it so a credential is never minted for another email.
+                throw new Error('stored email differs from the file');
+            }
+            return (0, guard_1.canonicalEmail)(stored.email);
+        };
+        const declaredUsernames = [...file.roots.map((r) => r.username)];
+        const flat = flatten(file);
+        for (const u of flat.users)
+            declaredUsernames.push(u.username);
+        function fileEmailOf(username) {
+            const key = (0, org_names_js_1.nameKey)(username);
+            return (file.roots.find((r) => (0, org_names_js_1.nameKey)(r.username) === key)?.email ??
+                flat.users.find((u) => (0, org_names_js_1.nameKey)(u.username) === key)?.email);
+        }
+        const mayIssueLinks = plan.entries.some((e) => e.status === 'create' &&
+            (e.kind === 'user' || e.kind === 'credential') &&
+            !isRootName(e.path.slice('user:'.length))) ||
+            (opts.reissueLinks === true && declaredUsernames.some((u) => lockedInState(u)));
+        let linkBase = '';
+        if (mayIssueLinks) {
+            linkBase = (0, set_password_links_js_1.resolveSetPasswordBase)(env);
+            if (opts.isTTY === undefined ? process.stdout.isTTY !== true : !opts.isTTY) {
+                if (opts.linksToStdout !== true) {
+                    throw new org_bootstrap_error_js_1.OrgBootstrapError('links_need_terminal', 'Set-password links are printed only to a terminal; pass --links-to-stdout to print them anyway.');
+                }
+            }
+        }
+        // ---- writes ----
+        const written = {};
+        const count = (kind, n = 1) => {
+            written[kind] = (written[kind] ?? 0) + n;
+        };
+        const ids = new Ids(pool, schemas);
+        const sink = new engine_1.MariaDbAuditSink({ schema: schemas.audit });
+        const operationAttributes = (stepKey) => ({
+            operation: org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_OPERATION,
+            step: stepKey,
+            onBehalfOf: operator,
+        });
+        const auditOn = (query, tenantId, actionKey, stepKey, attributes) => sink.record({
+            type: 'admin_action',
+            occurredAtMs: Date.now(),
+            actorId: org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_PRINCIPAL_ID,
+            tenantId,
+            action: { key: actionKey },
+            attributes: { ...attributes, ...operationAttributes(stepKey) },
+        }, query);
+        const principal = (stepKey, anchor, subtree, isRoot) => (0, internal_1.bindOperation)({
+            kind: 'user',
+            id: org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_PRINCIPAL_ID,
+            tenantId: anchor,
+            activeScopeNodeId: anchor,
+            scopeSubtreeNodeIds: [...subtree],
+            roleIds: [],
+            isRoot,
+        }, { operationKey: org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_OPERATION, stepKey, onBehalfOf: operator });
+        const service = async (token, as) => {
+            const contextId = core_1.ContextIdFactory.create();
+            app.registerRequestByContextId({ principal: as }, contextId);
+            return app.resolve(token, contextId, { strict: false });
+        };
+        /** Non-root people principal anchored at a company (its file subtree). */
+        const anchoredAt = async (stepKey, companyPath, withDescendants = true) => {
+            const anchor = await ids.company(companyPath);
+            // A company being created is not in its parent's subtree yet: its creator sees the parent only.
+            const under = withDescendants
+                ? flat.companies
+                    .filter((c) => (0, org_names_js_1.pathKey)(c.path).startsWith(`${(0, org_names_js_1.pathKey)(companyPath)}/`))
+                    .map((c) => ids.company(c.path))
+                : [];
+            return principal(stepKey, anchor, [anchor, ...(await Promise.all(under))], false);
+        };
+        const rootAt = async (stepKey, tenantName) => {
+            const anchor = await ids.company(tenantName);
+            return principal(stepKey, anchor, [anchor], true);
+        };
+        const step = async (stepKey, work) => {
+            try {
+                await work();
+            }
+            catch (cause) {
+                if (cause instanceof org_bootstrap_error_js_1.OrgBootstrapError)
+                    throw cause;
+                // Step key and error class only: a driver message can quote values or secrets.
+                const kind = cause instanceof Error ? cause.name : 'error';
+                throw new org_bootstrap_error_js_1.OrgBootstrapError('step_failed', `Step "${stepKey}" failed (${kind}); the run stopped. Re-running converges onto what was written.`, { step: stepKey, written: { ...written } });
+            }
+        };
+        const lockedNow = new Map();
+        // 1. companies: top-level by a root-flagged `tenants` principal, children by a non-root
+        //    principal anchored at the parent (createCompany stamps the parent: D5).
+        await step(STEP.tenants, async () => {
+            for (const c of flat.companies) {
+                if (st('company', c.path) !== 'create')
+                    continue;
+                if (c.parentPath === undefined) {
+                    const actor = principal(STEP.tenants, org_bootstrap_manifest_js_1.ORG_BOOTSTRAP_PRINCIPAL_ID, [], true);
+                    const companies = await service(company_service_js_1.CompanyService, actor);
+                    const tenantId = String(await companies.createCompany(actor, c.node.name));
+                    ids.set('company', c.path, tenantId);
+                    // R1-10: the tenant's own audit view shows its creation (the service audits under the
+                    // reserved operation id, which no tenant can read).
+                    await auditOn((sql, params) => pool.query(sql, params), tenantId, 'company.created', STEP.tenants, { companyUuid: tenantId, name: c.node.name });
+                }
+                else {
+                    const actor = await anchoredAt(STEP.companies, c.parentPath, false);
+                    const companies = await service(company_service_js_1.CompanyService, actor);
+                    ids.set('company', c.path, String(await companies.createCompany(actor, c.node.name)));
+                }
+                count('company');
+            }
+        });
+        // 2. org units: catalog rows, then the company junctions
+        await step(STEP.orgUnits, async () => {
+            const seenDept = new Set();
+            const seenBranch = new Set();
+            for (const c of flat.companies) {
+                const actor = await rootAt(STEP.orgUnits, c.tenant);
+                const catalogSvc = await service(org_catalog_service_js_1.OrgCatalogService, actor);
+                for (const d of c.node.departments ?? []) {
+                    if (seenDept.has((0, org_names_js_1.nameKey)(d)))
+                        continue;
+                    seenDept.add((0, org_names_js_1.nameKey)(d));
+                    if (st('department', `dept:${d}`) !== 'create')
+                        continue;
+                    ids.set('department', d, String(await catalogSvc.ensureDepartment(d)));
+                    count('department');
+                }
+                for (const b of c.node.branches ?? []) {
+                    if (seenBranch.has((0, org_names_js_1.nameKey)(b)))
+                        continue;
+                    seenBranch.add((0, org_names_js_1.nameKey)(b));
+                    if (st('branch', `branch:${b}`) !== 'create')
+                        continue;
+                    ids.set('branch', b, String(await catalogSvc.ensureBranch(b)));
+                    count('branch');
+                }
+            }
+            for (const c of flat.companies) {
+                const actor = await rootAt(STEP.orgUnits, c.tenant);
+                const catalogSvc = await service(org_catalog_service_js_1.OrgCatalogService, actor);
+                for (const d of c.node.departments ?? []) {
+                    if (st('company_department', `${c.path}#dept:${d}`) !== 'create')
+                        continue;
+                    await catalogSvc.attachDepartment(await ids.company(c.path), await ids.department(d));
+                    count('company_department');
+                }
+                for (const b of c.node.branches ?? []) {
+                    if (st('company_branch', `${c.path}#branch:${b}`) !== 'create')
+                        continue;
+                    await catalogSvc.attachBranch(await ids.company(c.path), await ids.branch(b));
+                    count('company_branch');
+                }
+            }
+        });
+        // 3. roles (owner stamped by RoleService), owner claims, then grants through GrantAdminService
+        await step(STEP.roles, async () => {
+            for (const tenant of file.tenants) {
+                const actor = await rootAt(STEP.roles, tenant.name);
+                const roles = await service(role_service_js_1.RoleService, actor);
+                const declared = [];
+                const seen = new Set();
+                for (const c of flat.companies.filter((x) => x.tenant === tenant.name)) {
+                    for (const r of c.node.roles ?? []) {
+                        if (seen.has((0, org_names_js_1.nameKey)(r.name)))
+                            continue;
+                        seen.add((0, org_names_js_1.nameKey)(r.name));
+                        declared.push(r);
+                    }
+                }
+                for (const r of declared) {
+                    if (st('role', `role:${r.name}`) !== 'create')
+                        continue;
+                    ids.set('role', r.name, String(await roles.createRole(r.name, actor)));
+                    count('role');
+                }
+                for (const r of declared) {
+                    if (st('role_claim', `role:${r.name}`) !== 'create')
+                        continue;
+                    await claimRole(await ids.role(r.name), await ids.company(tenant.name));
+                    count('role_claim');
+                }
+                for (const r of declared) {
+                    for (const key of r.permissions) {
+                        if (st('grant', `role:${r.name}#${key}`) !== 'create')
+                            continue;
+                        await grantAdmin.grant(await ids.role(r.name), key, actor);
+                        count('grant');
+                    }
+                }
+            }
+        });
+        // 4. users: roots (root-flagged, no company: root holds no membership), then non-root users
+        //    anchored at their company; a new user's locked credential is created inside the call.
+        await step(STEP.users, async () => {
+            for (const r of file.roots) {
+                if (st('user', `user:${r.username}`) !== 'create')
+                    continue;
+                const home = await ids.company(r.homeCompany);
+                const actor = principal(STEP.users, home, [home], true);
+                const users = await service(user_service_js_1.UserService, actor);
+                const created = await users.createUserWithCredential(actor, {
+                    username: r.username,
+                    email: r.email,
+                });
+                ids.set('user', r.username, String(created.id));
+                count('user');
+            }
+            for (const u of flat.users) {
+                if (st('user', `user:${u.username}`) !== 'create')
+                    continue;
+                const actor = await anchoredAt(STEP.users, u.company);
+                const users = await service(user_service_js_1.UserService, actor);
+                const companyUuid = await ids.company(u.company);
+                const created = await users.createUserWithCredential(actor, {
+                    username: u.username,
+                    email: u.email,
+                    companyUuid,
+                });
+                ids.set('user', u.username, String(created.id));
+                count('user');
+                if (created.credential === 'locked') {
+                    lockedNow.set((0, org_names_js_1.nameKey)(u.username), {
+                        principalId: String(created.id),
+                        tenantId: companyUuid,
+                    });
+                }
+            }
+            // memberships of EXISTING users in a company of the file: created active, never activated
+            for (const u of flat.users) {
+                if (st('membership', `user:${u.username}@${u.company}`) !== 'create')
+                    continue;
+                // Anchored at the file's tenant (its whole subtree), not the target company: an existing user
+                // is visible only where they already hold a membership, e.g. a parent of the target company.
+                // Still one tenant; the engine's create wall keeps the new membership inside that subtree.
+                const actor = await anchoredAt(STEP.users, u.tenant);
+                const memberships = await service(membership_service_js_1.MembershipService, actor);
+                const userUuid = await ids.user(u.username);
+                const companyUuid = await ids.company(u.company);
+                ids.set('membership', `${userUuid}@${companyUuid}`, String(await memberships.addActiveMembership(actor, userUuid, companyUuid)));
+                count('membership');
+            }
+        });
+        // 5. postings: add-only, as the anchored non-root principal, with the roles the file declares
+        //    for this tenant (and no other tenant's) as `operationRoleIds`.
+        await step(STEP.postings, async () => {
+            for (const u of flat.users) {
+                const toAdd = u.postings.filter((p) => st('posting', postingPath(u.username, u.company, p)) === 'create');
+                if (toAdd.length === 0)
+                    continue;
+                const actor = await anchoredAt(STEP.postings, u.company);
+                const userUuid = await ids.user(u.username);
+                const companyUuid = await ids.company(u.company);
+                // A read-only lookup, not `listMemberships`: list SQL scoping does not consult gate 7, so an
+                // operation-bound non-root principal could see no rows there (spec P1 "Matching").
+                const membershipUuid = await ids.membership(userUuid, companyUuid);
+                // R1-7: the roles declared on THIS company and its ancestors in the file (the resolution the
+                // file parser uses for postings), not every role of the tenant.
+                const operationRoleIds = new Set();
+                const here = (0, org_names_js_1.pathKey)(u.company);
+                for (const c of flat.companies) {
+                    const there = (0, org_names_js_1.pathKey)(c.path);
+                    if (here !== there && !here.startsWith(`${there}/`))
+                        continue;
+                    for (const r of c.node.roles ?? [])
+                        operationRoleIds.add(await ids.role(r.name));
+                }
+                const inputs = [];
+                for (const p of toAdd) {
+                    inputs.push({
+                        roleUuid: await ids.role(p.role),
+                        ...(p.department ? { departmentUuid: await ids.department(p.department) } : {}),
+                        ...(p.branch ? { branchUuid: await ids.branch(p.branch) } : {}),
+                    });
+                }
+                const postings = await service(posting_service_js_1.PostingService, actor);
+                await postings.addPostings(actor, membershipUuid, inputs, { operationRoleIds });
+                count('posting', toAdd.length);
+            }
+        });
+        // 6. credentials of roots and of existing users that have none, then the root flag
+        await step(STEP.users, async () => {
+            for (const r of file.roots) {
+                if (st('credential', `user:${r.username}`) !== 'create')
+                    continue;
+                const principalId = await ids.user(r.username);
+                const tenantId = await ids.company(r.homeCompany);
+                const hint = hintFor(r.username, r.email);
+                // R1-5: the credential and its audit row commit together or not at all.
+                await inTransaction(async (conn) => {
+                    const q = (sql, params) => conn.query(sql, params);
+                    await provisioner.provisionPassword({ principalId, hint, tenantId, password: passwords.get(r.username) }, q);
+                    // AC-6 / R6: the credential the run created is attributable; never the password or hash.
+                    await auditOn(q, tenantId, 'credential.provisioned', STEP.users, {
+                        userUuid: principalId,
+                        kind: 'password',
+                    });
+                });
+                count('credential');
+            }
+            for (const u of flat.users) {
+                if (st('credential', `user:${u.username}`) !== 'create')
+                    continue;
+                const principalId = await ids.user(u.username);
+                const tenantId = await ids.company(u.company);
+                const hint = hintFor(u.username, u.email);
+                await inTransaction(async (conn) => {
+                    const q = (sql, params) => conn.query(sql, params);
+                    await provisioner.provisionLocked({ principalId, hint, tenantId }, q);
+                    await auditOn(q, tenantId, 'credential.provisioned', STEP.users, {
+                        userUuid: principalId,
+                        kind: 'locked',
+                    });
+                });
+                lockedNow.set((0, org_names_js_1.nameKey)(u.username), { principalId, tenantId });
+                count('credential');
+            }
+            for (const r of file.roots) {
+                if (st('root_flag', `user:${r.username}`) !== 'create')
+                    continue;
+                await setPlatformSuperuser(await ids.user(r.username), await ids.company(r.homeCompany));
+                count('root_flag');
+            }
+        });
+        // 7. set-password links, after every other write
+        let links = 0;
+        if (mayIssueLinks) {
+            await step(STEP.users, async () => {
+                const targets = [];
+                const consider = async (username, companyPath) => {
+                    const fresh = lockedNow.get((0, org_names_js_1.nameKey)(username));
+                    if (fresh !== undefined) {
+                        targets.push({ username, ...fresh, invalidateFirst: false });
+                    }
+                    else if (opts.reissueLinks === true && lockedInState(username)) {
+                        targets.push({
+                            username,
+                            principalId: await ids.user(username),
+                            tenantId: await ids.company(companyPath),
+                            invalidateFirst: true,
+                        });
+                    }
+                };
+                for (const r of file.roots)
+                    await consider(r.username, r.homeCompany);
+                for (const u of flat.users)
+                    await consider(u.username, u.company);
+                links = await (0, set_password_links_js_1.issueSetPasswordLinks)({
+                    store: tokenStore,
+                    targets,
+                    base: linkBase,
+                    ttlHours,
+                    out,
+                    audit: (target, expiresAtMs) => auditOn((sql, params) => pool.query(sql, params), target.tenantId, 'credential.setup_link_issued', STEP.users, { userUuid: target.principalId, expiresAtMs }),
+                });
+            });
+        }
+        // 8. root wiring (R9): print each root's uuid and the line to set
+        const rootIds = [];
+        for (const r of file.roots) {
+            const id = await ids.user(r.username).catch(() => undefined);
+            if (id === undefined)
+                continue;
+            rootIds.push(id);
+            out(`root ${r.username}: ${id}`);
+        }
+        if (rootIds.length > 0)
+            out(`SHIELD_ROOT_IDS=${rootIds.join(',')}`);
+        return { applied: true, plan, written, links, rootIds };
+        // ----- raw writes allowed by the spec (R5, R13), both under the run lock and audited -----
+        async function inTransaction(work) {
+            const conn = await pool.getConnection();
+            try {
+                await conn.beginTransaction();
+                try {
+                    await work(conn);
+                    await conn.commit();
+                }
+                catch (cause) {
+                    await conn.rollback();
+                    throw cause;
+                }
+            }
+            finally {
+                await conn.release();
+            }
+        }
+        async function claimRole(roleUuid, tenantUuid) {
+            const tenantUuids = await Promise.all(file.tenants.map((t) => ids.company(t.name)));
+            await inTransaction(async (conn) => {
+                // R1-8: serialise on the role row, then re-check inside the transaction that nobody outside the
+                // file's tenants holds it (the plan-time read is not enough: it ran before other writers).
+                await conn.query(`SELECT r_uuid FROM \`${schemas.app}\`.\`roles\` WHERE r_uuid = ? FOR UPDATE`, [roleUuid]);
+                const held = (await conn.query(`SELECT 1 AS held FROM \`${schemas.app}\`.\`membership_posting\` mp ` +
+                    `JOIN \`${schemas.app}\`.\`company_membership\` cm ON cm.cm_uuid = mp.mp_membership_uuid ` +
+                    `WHERE mp.mp_role_uuid = ? AND cm.cm_company_uuid NOT IN (` +
+                    `SELECT sc.descendant_uuid FROM \`${schemas.authz}\`.\`scope_closure\` sc WHERE sc.ancestor_uuid IN (${tenantUuids.map(() => '?').join(', ')})) LIMIT 1`, [roleUuid, ...tenantUuids]));
+                if (held.length > 0) {
+                    const refusal = new Error('role is held outside the file tenants');
+                    refusal.name = 'RoleHeldOutsideError';
+                    throw refusal;
+                }
+                await (0, role_owner_transition_js_1.transitionRoleOwner)((sql, params) => conn.query(sql, params), roleUuid, null, tenantUuid, (action, attributes, query) => auditOn(query, tenantUuid, action, 'roles-claim', { ...attributes }), schemas);
+            });
+        }
+        async function setPlatformSuperuser(userUuid, tenantUuid) {
+            await inTransaction(async (conn) => {
+                await conn.query(`UPDATE \`${schemas.app}\`.\`users\` SET u_is_platform_superuser = 1 WHERE u_uuid = ?`, [userUuid]);
+                await auditOn((sql, params) => conn.query(sql, params), tenantUuid, 'user.platform_superuser_set', STEP.users, { userUuid });
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------
+/**
+ * Ids of the rows the run touches: filled from service return values for what the run creates, read
+ * with parameterised SELECTs over the authz pool for what already exists (names matched by the
+ * column collation). A name that resolves to nothing throws (a plan/state mismatch), never guesses.
+ */
+class Ids {
+    pool;
+    schemas;
+    known = new Map();
+    constructor(pool, schemas) {
+        this.pool = pool;
+        this.schemas = schemas;
+    }
+    key(kind, name) {
+        return `${kind}\u0000${kind === 'company' ? (0, org_names_js_1.pathKey)(name) : kind === 'membership' ? name : (0, org_names_js_1.nameKey)(name)}`;
+    }
+    set(kind, name, id) {
+        this.known.set(this.key(kind, name), id);
+    }
+    peek(kind, name) {
+        return this.known.get(this.key(kind, name));
+    }
+    async lookup(kind, name, sql, params, column) {
+        const cached = this.peek(kind, name);
+        if (cached !== undefined)
+            return cached;
+        const rows = (await this.pool.query(sql, params));
+        // LIMIT 2: a second row means the natural key is ambiguous; never pick one (R1-3).
+        if (rows.length > 1)
+            throw new Error(`${kind} is ambiguous`);
+        const id = rows[0]?.[column];
+        if (typeof id !== 'string' || id === '')
+            throw new Error(`${kind} not found`);
+        this.set(kind, name, id);
+        return id;
+    }
+    async company(path) {
+        const cached = this.peek('company', path);
+        if (cached !== undefined)
+            return cached;
+        const segments = path.split('/');
+        const name = segments[segments.length - 1];
+        const parent = segments.length > 1 ? await this.company(segments.slice(0, -1).join('/')) : null;
+        return this.lookup('company', path, `SELECT c_uuid FROM \`${this.schemas.app}\`.\`companies\` WHERE c_name = ? AND c_parent_uuid <=> ? LIMIT 2`, [name, parent], 'c_uuid');
+    }
+    department(name) {
+        return this.lookup('department', name, `SELECT d_uuid FROM \`${this.schemas.app}\`.\`departments\` WHERE d_name = ? LIMIT 2`, [name], 'd_uuid');
+    }
+    branch(name) {
+        return this.lookup('branch', name, `SELECT b_uuid FROM \`${this.schemas.app}\`.\`branches\` WHERE b_name = ? LIMIT 2`, [name], 'b_uuid');
+    }
+    role(name) {
+        return this.lookup('role', name, `SELECT r_uuid FROM \`${this.schemas.app}\`.\`roles\` WHERE r_name = ? LIMIT 2`, [name], 'r_uuid');
+    }
+    user(username) {
+        return this.lookup('user', username, `SELECT u_uuid FROM \`${this.schemas.app}\`.\`users\` WHERE u_username = ? LIMIT 2`, [username], 'u_uuid');
+    }
+    membership(userUuid, companyUuid) {
+        return this.lookup('membership', `${userUuid}@${companyUuid}`, `SELECT cm_uuid FROM \`${this.schemas.app}\`.\`company_membership\` WHERE cm_user_uuid = ? AND cm_company_uuid = ? LIMIT 2`, [userUuid, companyUuid], 'cm_uuid');
+    }
+}