@astram/identity 0.5.0 → 0.6.0

package/dist/features/company/company-hierarchy.service.d.ts

@@ -10,7 +10,10 @@
  *   - move: the node is in the actor's subtree, is NOT the actor's own root node (a sub-admin can
  *     never re-home its whole tenant), and the new parent is in the actor's subtree and non-null
  *     (only root creates or promotes top-level tenants). A cycle → ScopeCycleError (409).
- *   - delete: the caller (CompanyService) has already read the node through the subtree wall.
+ *   - delete: the caller (CompanyService) has already read the node through the subtree wall; the
+ *     node is not the actor's own root; the actor dominates every member and may administer every
+ *     service account of the company (Phase 8 #3). The delete disables those agents, revokes their
+ *     keys, drops the node from other agents' scopes and revokes cross-tenant grants naming it.
  *
  * Move and delete are audited ON their own transaction (a failed audit rolls them back). Names,
  * never ids, in the audit detail (ADR-0012).
@@ -22,12 +25,28 @@ import { ScopeClosureService } from '../scope/scope-closure.service.js';
 export interface HierarchyQueryable {
     query(sql: string, params?: readonly unknown[]): Promise<unknown>;
 }
+/**
+ * The authority checks a company delete needs — over each member and each of the company's own
+ * service accounts. `GrantCeiling` satisfies it.
+ */
+export interface MemberDominance {
+    assertDominates(actor: Principal, targetUserId: string): Promise<void>;
+    assertMayRetireServiceAccounts(actor: Principal, accounts: ReadonlyArray<{
+        readonly tenantId: string;
+        readonly scopeSubtreeNodeIds: readonly string[];
+        readonly roleIds: readonly string[];
+    }>): Promise<void>;
+}
 export declare class CompanyHierarchyService {
     private readonly pool;
     private readonly closure;
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    private readonly ceiling;
     private readonly audit?;
     private readonly now;
-    constructor(pool: HierarchyQueryable, closure: ScopeClosureService, audit?: AuditPort | undefined, now?: () => number);
+    constructor(pool: HierarchyQueryable, closure: ScopeClosureService, 
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    ceiling: MemberDominance, audit?: AuditPort | undefined, now?: () => number);
     /** The actor's own root node (the active node its subtree hangs from). */
     private ownRoot;
     /** Names of the given companies (unknown → absent). */
@@ -37,9 +56,52 @@ export declare class CompanyHierarchyService {
     move(actor: Principal, nodeUuid: string, newParentUuid: string | null): Promise<void>;
     /**
      * Delete a company through `deleteNode` (refuses a node with children; closure rows + ancestor
-     * bump in one transaction). The caller has already checked reach (walled read).
+     * and own-node bump in one transaction). The caller has already checked reach (walled read).
+     *
+     * Phase 8 #3: the delete cascades every membership and posting of the company, stripping its
+     * members' authority there, so a non-root actor must DOMINATE every member (the actor itself is
+     * skipped). Inside the delete's transaction and tree lock, before anything is deleted: lock the
+     * company row (a new membership's FK check waits on it), read the members with a locking read
+     * (latest committed rows, no insert into the range until commit), then `assertDominates` each.
+     * Any refusal rolls the whole delete back (403). Root bypasses the dominance check.
+     *
+     * Phase 8 #3 (continued): nothing in the database ties a service account or a cross-tenant grant
+     * to its company (no FK), so, still before the company row goes and on the same transaction,
+     * {@link retireDependents} disables the company's agents and revokes their keys, removes the
+     * company from other agents' scopes, and revokes every cross-tenant grant naming it — audited on
+     * that transaction. One transaction: a failure anywhere leaves the company and everything
+     * depending on it as they were; a commit leaves a deleted company with no live agent or grant.
      */
     remove(actor: Principal, nodeUuid: string): Promise<void>;
+    /**
+     * Retire what depends on a company being deleted (Phase 8 #3), on the delete's transaction after
+     * the company row lock and the member check, BEFORE the company row is deleted. Returns the
+     * tenants whose agents changed (the delete bumps them with the node and its ancestors).
+     *
+     *  1. Agents (`shield_app.service_account`) bound to the company, or whose scope names it, are
+     *     read with a locking read.
+     *  2. The company's OWN agents: a non-root actor must be able to administer every one of them
+     *     (`assertMayRetireServiceAccounts`, the ADR-0029 ceiling: scope and roles within its own) or
+     *     the whole delete is refused (403). Then each is disabled and its keys revoked (the same
+     *     `sak_revoked_at_ms` stamp `MariaDbApiKeyStore.revoke` writes, here on this transaction).
+     *  3. Other tenants' agents lose the company from their scope (reach over a deleted node only;
+     *     the actor dominates that node). An agent whose ENTIRE scope was the company is disabled and
+     *     its keys revoked instead — an empty scope would make the API-key path fall back to the
+     *     agent's own tenant, a widening — and its scope is left as it was (a dead reference, never
+     *     wider). These need no further authority check: they lose only reach over the deleted node.
+     *  4. Cross-tenant grants (`shield_authz.cross_tenant_grant`) where the company is the owning or
+     *     the grantee tenant and that are not yet revoked are revoked exactly as
+     *     `CrossTenantGrantWriter.revoke` does (status + `ctg_revoked_at`), and audited under both
+     *     tenants. The writer itself cannot join this transaction (it writes on its own pool, and
+     *     audits best-effort after the write); either side may revoke (ADR-0009), and the actor's
+     *     authority over the deleted side is the delete itself.
+     * Every change is audited on this transaction (names; ids only in structured attributes).
+     */
+    private retireDependents;
+    /** Step 4 of {@link retireDependents}: revoke and audit the grants naming the company. */
+    private revokeGrantsNaming;
+    /** Lock the company, then require dominance over each of its members (see `remove`). */
+    private assertMayDeleteMembers;
     /** A company was just created: give it closure rows now and bump its ancestors (D5). */
     attached(nodeUuid: string): Promise<void>;
 }

package/dist/features/company/company-hierarchy.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"company-hierarchy.service.d.ts","sourceRoot":"","sources":["../../../src/features/company/company-hierarchy.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAkB,MAAM,mCAAmC,CAAC;AAUxF,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAHH,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,mBAAmB,EAC5B,KAAK,CAAC,EAAE,SAAS,YAAA,EACjB,GAAG,GAAE,MAAM,MAAiB;IAG/C,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAIf,uDAAuD;YACzC,KAAK;YAUL,WAAW;IAoBzB,iGAAiG;IAC3F,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD3F;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc/D,wFAAwF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}
+{"version":3,"file":"company-hierarchy.service.d.ts","sourceRoot":"","sources":["../../../src/features/company/company-hierarchy.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAkB,MAAM,mCAAmC,CAAC;AAUxF,6FAA6F;AAC7F,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnE;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,8BAA8B,CAC5B,KAAK,EAAE,SAAS,EAChB,QAAQ,EAAE,aAAa,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;QAChD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;KACrC,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAuCD,qBAAa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBALH,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,mBAAmB;IAC7C,2FAA2F;IAC1E,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,SAAS,YAAA,EACjB,GAAG,GAAE,MAAM,MAAiB;IAG/C,0EAA0E;IAC1E,OAAO,CAAC,OAAO;IAIf,uDAAuD;YACzC,KAAK;YAUL,WAAW;IAqBzB,iGAAiG;IAC3F,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD3F;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;YACW,gBAAgB;IA6E9B,0FAA0F;YAC5E,kBAAkB;IAmDhC,wFAAwF;YAC1E,sBAAsB;IA+BpC,wFAAwF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGhD"}

package/dist/features/company/company-hierarchy.service.js

@@ -4,14 +4,32 @@ exports.CompanyHierarchyService = void 0;
 const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
 const identity_errors_js_1 = require("../shared/identity-errors.js");
 const APP = 'shield_app';
+const AUTHZ = 'shield_authz';
+/** A JSON-array column (the driver returns an array OR a string) → its string items; else []. */
+function jsonIdArray(v) {
+    let arr = v;
+    if (typeof v === 'string') {
+        try {
+            arr = JSON.parse(v);
+        }
+        catch {
+            arr = [];
+        }
+    }
+    return Array.isArray(arr) ? arr.filter((x) => typeof x === 'string') : [];
+}
 class CompanyHierarchyService {
     pool;
     closure;
+    ceiling;
     audit;
     now;
-    constructor(pool, closure, audit, now = Date.now) {
+    constructor(pool, closure, 
+    /** Phase 8 #3: required — a company delete must dominate every member (no silent skip). */
+    ceiling, audit, now = Date.now) {
         this.pool = pool;
         this.closure = closure;
+        this.ceiling = ceiling;
         this.audit = audit;
         this.now = now;
     }
@@ -27,14 +45,14 @@ class CompanyHierarchyService {
         const rows = (await q.query(`SELECT c_uuid, c_name FROM \`${APP}\`.\`companies\` WHERE c_uuid IN (${unique.map(() => '?').join(', ')})`, unique));
         return new Map(rows.map((r) => [r.c_uuid, r.c_name]));
     }
-    async recordAudit(conn, actor, action, attributes) {
+    async recordAudit(conn, actor, action, attributes, tenantId = actor.tenantId) {
         if (!this.audit)
             return;
         await this.audit.record({
             type: 'admin_action',
             occurredAtMs: this.now(),
             actorId: actor.id,
-            tenantId: actor.tenantId,
+            tenantId,
             action: { key: action },
             attributes: { eventType: 'company_hierarchy', ...attributes },
         }, (sql, params) => conn.query(sql, params));
@@ -81,7 +99,21 @@ class CompanyHierarchyService {
     }
     /**
      * Delete a company through `deleteNode` (refuses a node with children; closure rows + ancestor
-     * bump in one transaction). The caller has already checked reach (walled read).
+     * and own-node bump in one transaction). The caller has already checked reach (walled read).
+     *
+     * Phase 8 #3: the delete cascades every membership and posting of the company, stripping its
+     * members' authority there, so a non-root actor must DOMINATE every member (the actor itself is
+     * skipped). Inside the delete's transaction and tree lock, before anything is deleted: lock the
+     * company row (a new membership's FK check waits on it), read the members with a locking read
+     * (latest committed rows, no insert into the range until commit), then `assertDominates` each.
+     * Any refusal rolls the whole delete back (403). Root bypasses the dominance check.
+     *
+     * Phase 8 #3 (continued): nothing in the database ties a service account or a cross-tenant grant
+     * to its company (no FK), so, still before the company row goes and on the same transaction,
+     * {@link retireDependents} disables the company's agents and revokes their keys, removes the
+     * company from other agents' scopes, and revokes every cross-tenant grant naming it — audited on
+     * that transaction. One transaction: a failure anywhere leaves the company and everything
+     * depending on it as they were; a commit leaves a deleted company with no live agent or grant.
      */
     async remove(actor, nodeUuid) {
         // Security review F6: the same own-root guard as `move` — a sub-admin never deletes the
@@ -89,8 +121,153 @@ class CompanyHierarchyService {
         if (actor.isRoot !== true && nodeUuid === this.ownRoot(actor)) {
             throw new identity_errors_js_1.IdentityForbiddenError('You cannot delete the organisation your access is rooted at.');
         }
-        const name = (await this.names(this.pool, [nodeUuid])).get(nodeUuid);
-        await this.closure.deleteNode(nodeUuid, (conn) => this.recordAudit(conn, actor, 'company.deleted', { company: name ?? '(unknown)' }));
+        const name = (await this.names(this.pool, [nodeUuid])).get(nodeUuid) ?? '(unknown)';
+        await this.closure.deleteNode(nodeUuid, (conn) => this.recordAudit(conn, actor, 'company.deleted', { company: name }), async (conn) => {
+            await this.assertMayDeleteMembers(conn, actor, nodeUuid);
+            return this.retireDependents(conn, actor, nodeUuid, name);
+        });
+    }
+    /**
+     * Retire what depends on a company being deleted (Phase 8 #3), on the delete's transaction after
+     * the company row lock and the member check, BEFORE the company row is deleted. Returns the
+     * tenants whose agents changed (the delete bumps them with the node and its ancestors).
+     *
+     *  1. Agents (`shield_app.service_account`) bound to the company, or whose scope names it, are
+     *     read with a locking read.
+     *  2. The company's OWN agents: a non-root actor must be able to administer every one of them
+     *     (`assertMayRetireServiceAccounts`, the ADR-0029 ceiling: scope and roles within its own) or
+     *     the whole delete is refused (403). Then each is disabled and its keys revoked (the same
+     *     `sak_revoked_at_ms` stamp `MariaDbApiKeyStore.revoke` writes, here on this transaction).
+     *  3. Other tenants' agents lose the company from their scope (reach over a deleted node only;
+     *     the actor dominates that node). An agent whose ENTIRE scope was the company is disabled and
+     *     its keys revoked instead — an empty scope would make the API-key path fall back to the
+     *     agent's own tenant, a widening — and its scope is left as it was (a dead reference, never
+     *     wider). These need no further authority check: they lose only reach over the deleted node.
+     *  4. Cross-tenant grants (`shield_authz.cross_tenant_grant`) where the company is the owning or
+     *     the grantee tenant and that are not yet revoked are revoked exactly as
+     *     `CrossTenantGrantWriter.revoke` does (status + `ctg_revoked_at`), and audited under both
+     *     tenants. The writer itself cannot join this transaction (it writes on its own pool, and
+     *     audits best-effort after the write); either side may revoke (ADR-0009), and the actor's
+     *     authority over the deleted side is the delete itself.
+     * Every change is audited on this transaction (names; ids only in structured attributes).
+     */
+    async retireDependents(conn, actor, nodeUuid, companyName) {
+        const agents = (await conn.query(`SELECT sa_id, sa_tenant_id, sa_label, sa_scope_subtree, sa_role_ids, sa_updated_at_ms
+         FROM \`${APP}\`.\`service_account\`
+        WHERE sa_tenant_id = ? OR JSON_CONTAINS(sa_scope_subtree, JSON_QUOTE(?))
+        ORDER BY sa_id
+        FOR UPDATE`, [nodeUuid, nodeUuid]));
+        const own = agents.filter((a) => a.sa_tenant_id === nodeUuid);
+        const others = agents.filter((a) => a.sa_tenant_id !== nodeUuid);
+        // Root bypasses inside; a refusal (403, names no agent) rolls the whole delete back.
+        await this.ceiling.assertMayRetireServiceAccounts(actor, own.map((a) => ({
+            tenantId: a.sa_tenant_id,
+            scopeSubtreeNodeIds: jsonIdArray(a.sa_scope_subtree),
+            roleIds: jsonIdArray(a.sa_role_ids),
+        })));
+        const nowMs = this.now();
+        const touched = new Set();
+        const editStamp = (a) => Math.max(nowMs, (a.sa_updated_at_ms == null ? 0 : Number(a.sa_updated_at_ms)) + 1);
+        const retire = async (a, reason) => {
+            await conn.query(`UPDATE \`${APP}\`.\`service_account\` SET sa_status = 'disabled', sa_updated_at_ms = ? WHERE sa_id = ?`, [editStamp(a), a.sa_id]);
+            const res = (await conn.query(`UPDATE \`${AUTHZ}\`.\`service_account_key\`
+            SET sak_revoked_at_ms = ?
+          WHERE sak_account_id = ? AND sak_revoked_at_ms IS NULL`, [nowMs, a.sa_id]));
+            touched.add(a.sa_tenant_id);
+            await this.recordAudit(conn, actor, 'service_account.disabled', {
+                eventType: 'service_account',
+                accountId: a.sa_id,
+                account: a.sa_label,
+                company: companyName,
+                reason,
+                keysRevoked: Number(res?.affectedRows ?? 0),
+            });
+        };
+        for (const a of own)
+            await retire(a, 'company_deleted');
+        for (const a of others) {
+            const remaining = jsonIdArray(a.sa_scope_subtree).filter((n) => n !== nodeUuid);
+            if (remaining.length === 0) {
+                await retire(a, 'scope_company_deleted');
+                continue;
+            }
+            await conn.query(`UPDATE \`${APP}\`.\`service_account\` SET sa_scope_subtree = ?, sa_updated_at_ms = ? WHERE sa_id = ?`, [JSON.stringify(remaining), editStamp(a), a.sa_id]);
+            touched.add(a.sa_tenant_id);
+            await this.recordAudit(conn, actor, 'service_account.updated', {
+                eventType: 'service_account',
+                accountId: a.sa_id,
+                account: a.sa_label,
+                fields: ['scopeSubtreeNodeIds'],
+                scopeRemoved: [companyName],
+                reason: 'company_deleted',
+            });
+        }
+        await this.revokeGrantsNaming(conn, actor, nodeUuid, companyName);
+        return [...touched];
+    }
+    /** Step 4 of {@link retireDependents}: revoke and audit the grants naming the company. */
+    async revokeGrantsNaming(conn, actor, nodeUuid, companyName) {
+        const grants = (await conn.query(`SELECT ctg_uuid, ctg_owning_tenant_uuid, ctg_grantee_tenant_uuid, ctg_grantee_kind,
+              ctg_grantee_uuid, ctg_type_key, ctg_scope, ctg_allowed_actions
+         FROM \`${AUTHZ}\`.\`cross_tenant_grant\`
+        WHERE (ctg_owning_tenant_uuid = ? OR ctg_grantee_tenant_uuid = ?)
+          AND ctg_status <> 'revoked'
+        ORDER BY ctg_uuid
+        FOR UPDATE`, [nodeUuid, nodeUuid]));
+        if (grants.length === 0)
+            return;
+        const revokedAt = new Date(this.now());
+        const otherSides = grants.map((g) => g.ctg_owning_tenant_uuid === nodeUuid ? g.ctg_grantee_tenant_uuid : g.ctg_owning_tenant_uuid);
+        const names = await this.names(conn, otherSides);
+        for (const [i, g] of grants.entries()) {
+            await conn.query(`UPDATE \`${AUTHZ}\`.\`cross_tenant_grant\`
+            SET ctg_status = 'revoked', ctg_revoked_at = ?
+          WHERE ctg_uuid = ? AND ctg_status <> 'revoked'`, [revokedAt, g.ctg_uuid]);
+            const other = otherSides[i];
+            const attributes = {
+                eventType: 'cross_tenant_grant',
+                grantUuid: g.ctg_uuid,
+                typeKey: g.ctg_type_key,
+                scope: g.ctg_scope === 'record' ? 'record' : 'object_type',
+                granteeKind: g.ctg_grantee_kind === 'role' ? 'role' : 'user',
+                granteeUuid: g.ctg_grantee_uuid,
+                allowedActions: jsonIdArray(g.ctg_allowed_actions),
+                owningTenantId: g.ctg_owning_tenant_uuid,
+                granteeTenantId: g.ctg_grantee_tenant_uuid,
+                reason: 'company_deleted',
+                company: companyName,
+                otherCompany: names.get(other) ?? '(deleted organisation)',
+            };
+            // Audit on BOTH tenants (ADR-0009), one row each, as the writer's audit bridge files it.
+            for (const tenantId of new Set([g.ctg_owning_tenant_uuid, g.ctg_grantee_tenant_uuid])) {
+                await this.recordAudit(conn, actor, 'grant.revoked', attributes, tenantId);
+            }
+        }
+    }
+    /** Lock the company, then require dominance over each of its members (see `remove`). */
+    async assertMayDeleteMembers(conn, actor, nodeUuid) {
+        await conn.query(`SELECT c_uuid FROM \`${APP}\`.\`companies\` WHERE c_uuid = ? FOR UPDATE`, [
+            nodeUuid,
+        ]);
+        if (actor.isRoot === true)
+            return;
+        const rows = (await conn.query(`SELECT cm_user_uuid AS member FROM \`${APP}\`.\`company_membership\`
+        WHERE cm_company_uuid = ? FOR UPDATE`, [nodeUuid]));
+        const members = [...new Set(rows.map((r) => r.member))].sort();
+        for (const member of members) {
+            if (member === actor.id)
+                continue; // leaving your own membership behind stays allowed
+            try {
+                await this.ceiling.assertDominates(actor, member);
+            }
+            catch (cause) {
+                if (cause instanceof identity_errors_js_1.IdentityForbiddenError || cause instanceof identity_errors_js_1.IdentityNotFoundError) {
+                    // Names no member (who belongs to the company is not the caller's to learn from a refusal).
+                    throw new identity_errors_js_1.IdentityForbiddenError('You cannot delete this company: one of its members is outside your authority.');
+                }
+                throw cause;
+            }
+        }
     }
     /** A company was just created: give it closure rows now and bump its ancestors (D5). */
     async attached(nodeUuid) {

package/dist/features/identity-feature.module.d.ts

@@ -25,6 +25,8 @@ export declare class IdentityFeatureModule {
      *   the framework identity types, so a consumer's own OWNED type (e.g. `note`) is NOT
      *   policy-authorable and NOT shareable ("type '…' is not registered — cannot share").
      *   Passing them here lets an owner share their own records + author policies over them.
+     *   Phase 8 #4: if the action keys of these objects differ from the ones given to
+     *   `buildIdentityRecordAuthorization`, the boot fails with `IdentityRegistryMismatchError`.
      */
     static forRoot({ rootIds, extraObjects, }?: {
         rootIds?: readonly string[];

package/dist/features/identity-feature.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAYL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA6FxB;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,GAClB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACtC,GAAG,aAAa;CAscvB"}
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAYL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA8FxB;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,GAClB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACtC,GAAG,aAAa;CA8cvB"}

package/dist/features/identity-feature.module.js

@@ -97,8 +97,18 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
      *   the framework identity types, so a consumer's own OWNED type (e.g. `note`) is NOT
      *   policy-authorable and NOT shareable ("type '…' is not registered — cannot share").
      *   Passing them here lets an owner share their own records + author policies over them.
+     *   Phase 8 #4: if the action keys of these objects differ from the ones given to
+     *   `buildIdentityRecordAuthorization`, the boot fails with `IdentityRegistryMismatchError`.
      */
     static forRoot({ rootIds, extraObjects = [], } = {}) {
+        // The ceiling's key universe includes the consumer's `extraObjects` (the SAME registry shape
+        // `buildIdentityRecordAuthorization(pool, extraObjects)` gives the decision path): otherwise a
+        // role holding a consumer-type key could never be assigned or granted by a non-root admin who
+        // holds that key (review M5) — the security-hardening role-assignment ceiling makes that
+        // reachable from every posting edit. Phase 8 #4: the two registries must have the SAME action
+        // keys — checked here, before anything is opened; a mismatch fails the boot.
+        const ceilingRegistry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects, ...extraObjects]);
+        (0, record_authorization_js_1.noteIdentityCeilingRegistry)(ceilingRegistry);
         // ONE shared shield_authz pool for the whole grant-admin stack (ADR-0011): the
         // permission-version bumper, the AccessBundleStore, the GrantAdminService, and the two
         // reconcile jobs all run over this single pool (don't open several). Opened once at
@@ -109,6 +119,8 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
             bumpTenant: (tenantUuid) => bumper.bumpForTenant(tenantUuid, authzPool),
             // A user disabled/re-enabled: every membership tenant (autocommit pool → published at once).
             bumpForUser: (userUuid) => bumper.bumpForUser(userUuid, authzPool),
+            // A role delete (Phase 8 #2): its holder tenants, read before the delete cascades postings.
+            tenantsForRole: (roleUuid) => bumper.tenantsForRole(roleUuid, authzPool),
         };
         // The core ModuleRegistry the catalog reconcile job needs, built from the identity
         // object registrations (guard's bridge reflects decorated classes → registry). Built BEFORE
@@ -120,12 +132,8 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // resolved over the SAME authz pool + registry the object-type gate uses (one source of
         // truth for "what a principal holds"). ALWAYS wired here, so production always enforces.
         const accessBundleStore = new access_bundle_store_js_1.AccessBundleStore(authzPool);
-        // The ceiling's key universe includes the consumer's `extraObjects` (the SAME registry shape
-        // `buildIdentityRecordAuthorization(pool, extraObjects)` gives the decision path): otherwise a
-        // role holding a consumer-type key could never be assigned or granted by a non-root admin who
-        // holds that key (review M5) — the security-hardening role-assignment ceiling makes that
-        // reachable from every posting edit. `rootIds` marks platform roots as never dominated.
-        const ceilingRegistry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects, ...extraObjects]);
+        // (`ceilingRegistry` is built and parity-checked at the top of forRoot.) `rootIds` marks
+        // platform roots as never dominated.
         // rootIds is passed EXPLICITLY (review F5): `null` states "not configured". The dominance
         // check still refuses any user flagged `u_is_platform_superuser`, so an unconfigured list
         // never lets a sub-admin take over a platform administrator.
@@ -146,7 +154,8 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         const scopeClosureService = new scope_closure_service_js_1.ScopeClosureService(authzPool, bumper);
         // Company hierarchy (security hardening #2): the ONLY path that moves/deletes/attaches a company
         // node — through the closure service above — audited on the move/delete transaction.
-        const companyHierarchyService = new company_hierarchy_service_js_1.CompanyHierarchyService(authzPool, scopeClosureService, new engine_1.MariaDbAuditSink({}));
+        const companyHierarchyService = new company_hierarchy_service_js_1.CompanyHierarchyService(authzPool, scopeClosureService, grantCeiling, // Phase 8 #3: a company delete must dominate every member
+        new engine_1.MariaDbAuditSink({}));
         // Audit viewer (Phase 5): the AuditReader + LabelResolver over the SAME shared authzPool
         // (the reader queries shield_audit + the resolver/actor-lookup query shield_app, both
         // reachable by that pool). `auditNameToId` is the actor-name -> uuid reverse lookup for the
@@ -165,7 +174,8 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // authz.module, the anti-pattern this replaces). A SECOND DecisionAuthority is built over the
         // same record-authorization inputs (matches astram3): the route guard's own decide() is the
         // first; this one backs the writer's server-side re-verification.
-        const crossTenantAuthority = (0, guard_1.buildRecordAuthorization)((0, record_authorization_js_1.buildIdentityRecordAuthorization)(authzPool));
+        // (The non-recording builder: these internal authorities are not the consumer's decision path.)
+        const crossTenantAuthority = (0, guard_1.buildRecordAuthorization)((0, record_authorization_js_1.buildRecordAuthorizationInputs)(authzPool));
         // Record-level LIST SCOPE (Task 3.1, Invariant #8): the engine-facing fn the engine's
         // `list()` ANDs into BOTH the data SELECT and the COUNT — the in-query visible-set filter.
         // Built HERE, over the SAME shared authzPool (guard constructs the un-overridable scope
@@ -173,7 +183,7 @@ let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModul
         // out-of-the-box into `EngineModule.forRoot({ listScope })` below (ADR-0003 injection seam —
         // the engine never imports guard). Fail-closed: a store outage propagates and `list()` fails
         // rather than returning unscoped rows.
-        const listScope = (0, guard_1.buildListScopeFn)((0, record_authorization_js_1.buildIdentityRecordAuthorization)(authzPool));
+        const listScope = (0, guard_1.buildListScopeFn)((0, record_authorization_js_1.buildRecordAuthorizationInputs)(authzPool));
         // The writer's `GrantAuthorizeFn`: decide()-backed, fail-closed (no try/catch — a throw
         // propagates and the writer maps it to a retryable 503). isRoot ← the SAME rootIds the
         // consumer passes to ShieldModule.forRoot (root-correctness for control-plane grants).

package/dist/features/membership/posting-version-bump.d.ts

@@ -10,6 +10,13 @@ export interface PostingVersionBump {
      * the account itself was disabled or re-enabled. Returns the bumped tenants; throws on failure.
      */
     bumpForUser?(userUuid: string): Promise<string[]>;
+    /**
+     * OPTIONAL (Phase 8 #2): the tenants whose cached grants change when the role goes away — every
+     * tenant where it is actively posted, plus every service account's tenant holding it. Read
+     * BEFORE a role delete (the delete cascades the postings); bump each with `bumpTenant` after the
+     * commit. Throws on failure.
+     */
+    tenantsForRole?(roleUuid: string): Promise<string[]>;
 }
 export declare const POSTING_VERSION_BUMP: unique symbol;
 //# sourceMappingURL=posting-version-bump.d.ts.map

package/dist/features/membership/posting-version-bump.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posting-version-bump.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting-version-bump.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;OAGG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED,eAAO,MAAM,oBAAoB,eAAiC,CAAC"}
+{"version":3,"file":"posting-version-bump.d.ts","sourceRoot":"","sources":["../../../src/features/membership/posting-version-bump.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;;OAGG;IACH,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD;;;;;OAKG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACtD;AAED,eAAO,MAAM,oBAAoB,eAAiC,CAAC"}

package/dist/features/role/role.service.d.ts

@@ -2,6 +2,8 @@ import { RecordsService, type RecordId } from '@astram/engine';
 import type { Principal } from '@astram/core';
 import { type ListParams } from '../shared/list-query.js';
 import { GrantCeiling } from '../authz/grant-ceiling.js';
+import { GrantAdminService } from '../authz/grant-admin.service.js';
+import { type PostingVersionBump } from '../membership/posting-version-bump.js';
 /**
  * RoleService — role CRUD on the paved road, via the framework's RecordsService
  * facade. The facade supplies the acting identity (the request principal) for the pipe;
@@ -15,7 +17,9 @@ import { GrantCeiling } from '../authz/grant-ceiling.js';
 export declare class RoleService {
     private readonly records;
     private readonly ceiling;
-    constructor(records: RecordsService, ceiling: GrantCeiling);
+    private readonly versionBump?;
+    private readonly grants?;
+    constructor(records: RecordsService, ceiling: GrantCeiling, versionBump?: (PostingVersionBump | null) | undefined, grants?: (GrantAdminService | null) | undefined);
     /** Create a role. */
     createRole(name: string): Promise<RecordId>;
     /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
@@ -26,7 +30,26 @@ export declare class RoleService {
     updateRole(actor: Principal, uuid: string, patch: {
         name?: unknown;
     }): Promise<void>;
-    /** Delete a role — only a role the actor may administer (binding rule). */
+    /**
+     * Delete a role — only a role the actor may administer (binding rule) AND whose every holder the
+     * actor dominates (Phase 8 #2: the delete cascades the holders' postings, stripping their
+     * authority). In ONE transaction: lock the role row (the posting and grant paths lock the same
+     * row first), re-check the binding rule and holder dominance against what is committed now, read
+     * the holder tenants (before the cascade removes the postings), then delete. After the commit,
+     * every holder tenant's permission version is bumped so cached roles drop at the next request.
+     * The bump runs after the commit, never before: an earlier bump would let a session reload the
+     * pre-delete roles under the new version. A bump failure throws (503) rather than leave holders'
+     * cached grants silently stale.
+     *
+     * The role's `role_permission` rows (shield_authz, no FK) and its place in every service
+     * account's `sa_role_ids` (read live by the API-key store) do not cascade, so before the delete,
+     * still under the role lock, `GrantAdminService.purgeRole` removes both in its own committed
+     * authz transaction — checking first that the actor may change each holding account, and
+     * bumping every tenant that used the role (account tenants included). Order is fail-closed: a
+     * failure after the purge leaves a role with no grants and no agents, never live grants or an
+     * agent carrying a deleted role. A re-created role gets a fresh uuid (the engine mints it), so
+     * it can never pick up anything left behind.
+     */
     deleteRole(actor: Principal, uuid: string): Promise<void>;
 }
 //# sourceMappingURL=role.service.d.ts.map

package/dist/features/role/role.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAKzD;;;;;;;;;GASG;AACH,qBACa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY;IAGxC,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,8FAA8F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F,2EAA2E;IACrE,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIhE"}
+{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAK/C;;;;;;;;;GASG;AACH,qBACa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAKxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAK7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAXP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EAKrB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA,EAKvC,MAAM,CAAC,GAAE,iBAAiB,GAAG,IAAI,aAAA;IAGpD,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,8FAA8F;IACxF,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1F;;;;;;;;;;;;;;;;;;;OAmBG;IACG,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAoBhE"}

package/dist/features/role/role.service.js

@@ -8,12 +8,18 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RoleService = void 0;
 const common_1 = require("@nestjs/common");
 const engine_1 = require("@astram/engine");
+const core_1 = require("@astram/core");
 const list_query_js_1 = require("../shared/list-query.js");
 const grant_ceiling_js_1 = require("../authz/grant-ceiling.js");
+const grant_admin_service_js_1 = require("../authz/grant-admin.service.js");
+const posting_version_bump_js_1 = require("../membership/posting-version-bump.js");
 const ROLE_SEARCH_FIELDS = ['name'];
 const ROLE_SORT_FIELDS = ['name', 'createdAt'];
 /**
@@ -29,9 +35,13 @@ const ROLE_SORT_FIELDS = ['name', 'createdAt'];
 let RoleService = class RoleService {
     records;
     ceiling;
-    constructor(records, ceiling) {
+    versionBump;
+    grants;
+    constructor(records, ceiling, versionBump, grants) {
         this.records = records;
         this.ceiling = ceiling;
+        this.versionBump = versionBump;
+        this.grants = grants;
     }
     /** Create a role. */
     createRole(name) {
@@ -53,15 +63,58 @@ let RoleService = class RoleService {
             fields.name = patch.name;
         await this.records.update('role', uuid, { fields });
     }
-    /** Delete a role — only a role the actor may administer (binding rule). */
+    /**
+     * Delete a role — only a role the actor may administer (binding rule) AND whose every holder the
+     * actor dominates (Phase 8 #2: the delete cascades the holders' postings, stripping their
+     * authority). In ONE transaction: lock the role row (the posting and grant paths lock the same
+     * row first), re-check the binding rule and holder dominance against what is committed now, read
+     * the holder tenants (before the cascade removes the postings), then delete. After the commit,
+     * every holder tenant's permission version is bumped so cached roles drop at the next request.
+     * The bump runs after the commit, never before: an earlier bump would let a session reload the
+     * pre-delete roles under the new version. A bump failure throws (503) rather than leave holders'
+     * cached grants silently stale.
+     *
+     * The role's `role_permission` rows (shield_authz, no FK) and its place in every service
+     * account's `sa_role_ids` (read live by the API-key store) do not cascade, so before the delete,
+     * still under the role lock, `GrantAdminService.purgeRole` removes both in its own committed
+     * authz transaction — checking first that the actor may change each holding account, and
+     * bumping every tenant that used the role (account tenants included). Order is fail-closed: a
+     * failure after the purge leaves a role with no grants and no agents, never live grants or an
+     * agent carrying a deleted role. A re-created role gets a fresh uuid (the engine mints it), so
+     * it can never pick up anything left behind.
+     */
     async deleteRole(actor, uuid) {
         await this.ceiling.assertRoleAdministrable(actor, uuid);
-        await this.records.delete('role', uuid);
+        const grants = this.grants;
+        if (!grants)
+            throw new core_1.AuthorizationUnavailableError('role grant purge is not configured');
+        const tenants = await this.records.transaction(async (tx) => {
+            await tx.lockForUpdate('role', uuid);
+            await this.ceiling.assertRoleAdministrable(actor, uuid);
+            await this.ceiling.assertDominatesRoleHolders(actor, uuid);
+            const affected = (await this.versionBump?.tenantsForRole?.(uuid)) ?? [];
+            await grants.purgeRole(uuid, actor);
+            await tx.delete('role', uuid);
+            return affected;
+        });
+        if (!this.versionBump)
+            return;
+        try {
+            for (const tenant of tenants)
+                await this.versionBump.bumpTenant(tenant);
+        }
+        catch (cause) {
+            throw new core_1.AuthorizationUnavailableError('permission version bump failed', cause);
+        }
     }
 };
 exports.RoleService = RoleService;
 exports.RoleService = RoleService = __decorate([
     (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Optional)()),
+    __param(2, (0, common_1.Inject)(posting_version_bump_js_1.POSTING_VERSION_BUMP)),
+    __param(3, (0, common_1.Optional)()),
+    __param(3, (0, common_1.Inject)(grant_admin_service_js_1.GrantAdminService)),
     __metadata("design:paramtypes", [engine_1.RecordsService,
-        grant_ceiling_js_1.GrantCeiling])
+        grant_ceiling_js_1.GrantCeiling, Object, Object])
 ], RoleService);

package/dist/features/scope/scope-closure.service.d.ts

@@ -88,6 +88,10 @@ export declare class ScopeClosureService {
      * subtree, so those admins' cached session subtrees are stale (they'd keep the deleted node in
      * their set) — bump them so they re-derive at the next refresh (same discipline as moveNode's
      * former-parent bump; without it, a parent admin's list/decide would reference a gone node).
+     * Also bumps the deleted node's own tenant (Phase 8 #3). `beforeDelete` runs first, on the same
+     * transaction, so a caller can lock the node and refuse (rollback) before anything changes; it
+     * may also retire rows that depend on the node and return the tenants those changes touched,
+     * which are bumped with the rest.
      *
      * v1 SCOPE NOTE: this refuses a node with CHILDREN. Broader resource-orphan cleanup (rows in
      * the many tenant-scoped app tables that reference the deleted node) is out of scope for v1 and
@@ -95,7 +99,13 @@ export declare class ScopeClosureService {
      */
     deleteNode(nodeUuid: string, 
     /** Runs on the delete's transaction after the bump (e.g. the audit row) — a throw rolls back. */
-    inTransaction?: (conn: ScopeConn) => Promise<void>): Promise<void>;
+    inTransaction?: (conn: ScopeConn) => Promise<void>, 
+    /**
+     * Runs on the delete's transaction BEFORE anything is deleted (Phase 8 #3: lock the node, check
+     * authority over its members and agents, retire its agents and cross-tenant grants) — a throw
+     * rolls back and nothing is deleted or bumped. Returned tenant ids are bumped too.
+     */
+    beforeDelete?: (conn: ScopeConn) => Promise<void | readonly string[]>): Promise<void>;
     /** Read the node forest's parent edges (`c_uuid` → `c_parent_uuid`) as `ScopeEdge[]`. */
     private readEdges;
     /**