@wtfalch/authz-store 0.2.0 → 0.3.0

package/dist/tree-writes.d.ts

@@ -0,0 +1,65 @@
+import type { StoreBinding } from './binding.js';
+import type { DbOrTx } from './scoped.js';
+import { type DerivedChange } from './tree.js';
+/**
+ * The write and inheritance-propagation half of the tenant tree (D19):
+ * `recomputeDerived`, and the two functions that call it, `attachInTx` and
+ * `detachInTx`. `./tree.js` holds the reads and the pure derivation rule
+ * this half writes out — read that file's header for the rule itself and
+ * why authority is materialised at write time rather than walked on read.
+ */
+/**
+ * A derived row would have had to carry a custom role, which D19 forbids
+ * ("a derived membership carries a system role, never a custom one"). Every
+ * caller checks `customRoleBlockers` (`./tree.js`) before writing, so
+ * reaching this means one of them did not: it throws inside the caller's
+ * transaction rather than writing a row the invariant says cannot exist.
+ */
+export declare class DerivedCustomRoleError extends Error {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly role: string;
+    constructor(tenantId: string, principalId: string, role: string);
+}
+/**
+ * Makes the derived rows in these tenants match the rule, and returns what it
+ * changed. The one writer: a grant, a role change, a removal, an attach and a
+ * detach all reduce to "these tenants may now hold different derived rows for
+ * these principals, work out which and write it".
+ *
+ * Three properties this holds, and the property tests pin (Tests 20):
+ *
+ * - A `direct` row is never read as a candidate and never written over. The
+ *   update and delete below both carry `source = 'inherited'` in their
+ *   predicate, so even a bug in the diff cannot reach one (M6).
+ * - A derived row never carries a custom role: it throws instead, because a
+ *   caller reaching that point skipped `customRoleBlockers` and the
+ *   transaction should fail rather than store a row the invariant forbids.
+ * - Running it twice changes nothing the second time, which is what lets the
+ *   reconciliation check compare against a fresh computation.
+ *
+ * Pass `principalIds` when the change is about particular people (a grant at
+ * a parent); leave it out when the shape of the tree itself moved (an attach
+ * or a detach) and every principal above is in question.
+ */
+export declare function recomputeDerived(tx: DbOrTx, binding: StoreBinding, tenantIds: readonly string[], principalIds?: readonly string[]): Promise<DerivedChange[]>;
+/**
+ * Writes the attachment and fills the derived rows, in the caller's
+ * transaction. The caller has already decided that this may happen
+ * (`attachProblem` returned null, the consent was given, the permission was
+ * held) and writes the audit rows; this is the two writes that make it true.
+ *
+ * The subtree, not just the child: attaching a child that already holds
+ * children of its own reaches all of them, which is why the depth rule is
+ * checked against the child's own height rather than against the child alone.
+ */
+export declare function attachInTx(tx: DbOrTx, binding: StoreBinding, parentId: string, childId: string): Promise<DerivedChange[]>;
+/**
+ * Clears the attachment and the derived rows it supported, in the caller's
+ * transaction. Order matters: the parent link is cleared first, so the
+ * recomputation that follows reads the tree as it now is and removes exactly
+ * the rows the link was holding up. Direct rows in the child are left
+ * standing (M6), which is the whole reason detach needs a report
+ * (`detachReport` in `./tree.js`).
+ */
+export declare function detachInTx(tx: DbOrTx, binding: StoreBinding, childId: string): Promise<DerivedChange[]>;

package/dist/tree-writes.js

@@ -0,0 +1,201 @@
+import { and, eq, inArray } from 'drizzle-orm';
+import { primaryRoleKey, writeParticipationPolicy, writePrimaryAssignment } from './assignments.js';
+import { policyAssignments } from './policy-schema.js';
+import { isCustomRoleKey } from './role-keys.js';
+import { roleDef } from './roles.js';
+import { memberships, tenants } from './schema.js';
+import { descendantsOf, expectedDerivedFor, nodeById, } from './tree.js';
+/**
+ * The write and inheritance-propagation half of the tenant tree (D19):
+ * `recomputeDerived`, and the two functions that call it, `attachInTx` and
+ * `detachInTx`. `./tree.js` holds the reads and the pure derivation rule
+ * this half writes out — read that file's header for the rule itself and
+ * why authority is materialised at write time rather than walked on read.
+ */
+/**
+ * A derived row would have had to carry a custom role, which D19 forbids
+ * ("a derived membership carries a system role, never a custom one"). Every
+ * caller checks `customRoleBlockers` (`./tree.js`) before writing, so
+ * reaching this means one of them did not: it throws inside the caller's
+ * transaction rather than writing a row the invariant says cannot exist.
+ */
+export class DerivedCustomRoleError extends Error {
+    tenantId;
+    principalId;
+    role;
+    constructor(tenantId, principalId, role) {
+        super(`a derived membership for ${principalId} in ${tenantId} would carry the custom role "${role}"`);
+        this.tenantId = tenantId;
+        this.principalId = principalId;
+        this.role = role;
+        this.name = 'DerivedCustomRoleError';
+    }
+}
+/**
+ * Makes the derived rows in these tenants match the rule, and returns what it
+ * changed. The one writer: a grant, a role change, a removal, an attach and a
+ * detach all reduce to "these tenants may now hold different derived rows for
+ * these principals, work out which and write it".
+ *
+ * Three properties this holds, and the property tests pin (Tests 20):
+ *
+ * - A `direct` row is never read as a candidate and never written over. The
+ *   update and delete below both carry `source = 'inherited'` in their
+ *   predicate, so even a bug in the diff cannot reach one (M6).
+ * - A derived row never carries a custom role: it throws instead, because a
+ *   caller reaching that point skipped `customRoleBlockers` and the
+ *   transaction should fail rather than store a row the invariant forbids.
+ * - Running it twice changes nothing the second time, which is what lets the
+ *   reconciliation check compare against a fresh computation.
+ *
+ * Pass `principalIds` when the change is about particular people (a grant at
+ * a parent); leave it out when the shape of the tree itself moved (an attach
+ * or a detach) and every principal above is in question.
+ */
+export async function recomputeDerived(tx, binding, tenantIds, principalIds) {
+    const changes = [];
+    const identity = (row) => `${row.principalClass}:${row.principalId}`;
+    for (const tenantId of tenantIds) {
+        const node = await nodeById(tx, tenantId);
+        if (!node)
+            continue;
+        const expected = await expectedDerivedFor(tx, binding, tenantId, principalIds);
+        for (const row of expected) {
+            if (isCustomRoleKey(row.role)) {
+                throw new DerivedCustomRoleError(tenantId, row.principalId, row.role);
+            }
+        }
+        const expectedById = new Map(expected.map((row) => [identity(row), row]));
+        const existingConditions = [
+            eq(memberships.tenantId, tenantId),
+            eq(memberships.source, 'inherited'),
+        ];
+        if (principalIds) {
+            if (principalIds.length === 0)
+                continue;
+            existingConditions.push(inArray(memberships.principalId, [...principalIds]));
+        }
+        const existing = await tx
+            .select({
+            principalId: memberships.principalId,
+            principalClass: memberships.principalClass,
+            role: primaryRoleKey(binding),
+            viaTenantId: memberships.viaTenantId,
+        })
+            .from(memberships)
+            .where(and(...existingConditions));
+        const existingById = new Map(existing.map((row) => [identity(row), row]));
+        for (const row of expected) {
+            const current = existingById.get(identity(row));
+            if (!current) {
+                // A direct row for this principal would have kept them out of
+                // `expected` entirely, so there is nothing here to collide with.
+                await tx.insert(memberships).values({
+                    tenantId,
+                    principalId: row.principalId,
+                    principalClass: row.principalClass,
+                    source: 'inherited',
+                    viaTenantId: row.viaTenantId,
+                    tenantName: node.name,
+                    grantedBy: row.grantedBy,
+                });
+                await syncInheritedAssignment(tx, binding, tenantId, row);
+                if (row.principalClass === 'human')
+                    await writeParticipationPolicy(tx, binding, tenantId, {
+                        id: row.principalId,
+                        class: 'human',
+                    });
+                changes.push({
+                    tenantId,
+                    principalId: row.principalId,
+                    kind: 'created',
+                    before: null,
+                    after: { role: row.role, viaTenantId: row.viaTenantId },
+                });
+                continue;
+            }
+            if (current.role === row.role && current.viaTenantId === row.viaTenantId)
+                continue;
+            await tx
+                .update(memberships)
+                .set({
+                viaTenantId: row.viaTenantId,
+                grantedBy: row.grantedBy,
+                updatedAt: new Date(),
+            })
+                .where(and(eq(memberships.tenantId, tenantId), eq(memberships.principalId, row.principalId), eq(memberships.principalClass, row.principalClass), eq(memberships.source, 'inherited')));
+            await syncInheritedAssignment(tx, binding, tenantId, row);
+            changes.push({
+                tenantId,
+                principalId: row.principalId,
+                kind: 'role_changed',
+                before: { role: current.role, viaTenantId: current.viaTenantId },
+                after: { role: row.role, viaTenantId: row.viaTenantId },
+            });
+        }
+        for (const current of existing) {
+            if (expectedById.has(identity(current)))
+                continue;
+            await tx
+                .delete(memberships)
+                .where(and(eq(memberships.tenantId, tenantId), eq(memberships.principalId, current.principalId), eq(memberships.principalClass, current.principalClass), eq(memberships.source, 'inherited')));
+            changes.push({
+                tenantId,
+                principalId: current.principalId,
+                kind: 'ended',
+                before: { role: current.role, viaTenantId: current.viaTenantId },
+                after: null,
+            });
+        }
+    }
+    return changes;
+}
+/**
+ * Writes the attachment and fills the derived rows, in the caller's
+ * transaction. The caller has already decided that this may happen
+ * (`attachProblem` returned null, the consent was given, the permission was
+ * held) and writes the audit rows; this is the two writes that make it true.
+ *
+ * The subtree, not just the child: attaching a child that already holds
+ * children of its own reaches all of them, which is why the depth rule is
+ * checked against the child's own height rather than against the child alone.
+ */
+export async function attachInTx(tx, binding, parentId, childId) {
+    await tx.update(tenants).set({ parentId, updatedAt: new Date() }).where(eq(tenants.id, childId));
+    const subtree = [childId, ...(await descendantsOf(tx, childId)).map((node) => node.id)];
+    return recomputeDerived(tx, binding, subtree);
+}
+/**
+ * Clears the attachment and the derived rows it supported, in the caller's
+ * transaction. Order matters: the parent link is cleared first, so the
+ * recomputation that follows reads the tree as it now is and removes exactly
+ * the rows the link was holding up. Direct rows in the child are left
+ * standing (M6), which is the whole reason detach needs a report
+ * (`detachReport` in `./tree.js`).
+ */
+export async function detachInTx(tx, binding, childId) {
+    const subtree = [childId, ...(await descendantsOf(tx, childId)).map((node) => node.id)];
+    await tx
+        .update(tenants)
+        .set({ parentId: null, updatedAt: new Date() })
+        .where(eq(tenants.id, childId));
+    return recomputeDerived(tx, binding, subtree);
+}
+async function syncInheritedAssignment(tx, binding, tenantId, row) {
+    const role = row.role ? await roleDef(tx, binding, { id: tenantId }, row.role) : null;
+    if (row.role && !role)
+        throw new Error('Missing destination built-in policy');
+    // `built_in` alone is not the right test any more: a starter role (ADR
+    // 0016) is a real, app-defined role that must still cross organisation
+    // boundaries, even though its row is `built_in: false` for a tenant
+    // created after that change. `isCustomRoleKey` is what actually
+    // distinguishes a tenant-authored role from one this app defines.
+    if (role && isCustomRoleKey(role.key))
+        throw new Error('Custom roles cannot cross organisation boundaries');
+    if (role)
+        await writePrimaryAssignment(tx, binding, role, { id: row.principalId, class: row.principalClass }, { source: 'inherited', viaTenantId: row.viaTenantId, createdBy: row.grantedBy });
+    else
+        await tx
+            .delete(policyAssignments)
+            .where(and(eq(policyAssignments.tenantId, tenantId), eq(policyAssignments.applicationId, binding.applicationId), eq(policyAssignments.platformId, binding.platformId), eq(policyAssignments.principalId, row.principalId), eq(policyAssignments.principalClass, row.principalClass), eq(policyAssignments.primary, true), eq(policyAssignments.source, 'inherited')));
+}

package/dist/tree.d.ts

@@ -0,0 +1,272 @@
+import type { EventName, TenantKind, TenantState } from '@wtfalch/authz';
+import type { StoreBinding } from './binding.js';
+import type { StorePolicy } from './policy.js';
+import type { DbOrTx } from './scoped.js';
+/**
+ * The tenant tree and the derived membership rows that hang off it (D19).
+ *
+ * This file is the read and query half: node lookups, ancestor/descendant
+ * walks, the attach-eligibility check, and the pure derivation rule that
+ * says what a tenant's derived rows *should* be. `./tree-writes.js` is the
+ * other half — `recomputeDerived` and the two functions that call it,
+ * `attachInTx`/`detachInTx` — split out because the two together ran past
+ * this package's review size. The policy is in the host's own `nesting.ts`
+ * (who may propose, accept, decline and detach), `memberships.ts`
+ * (propagation on a grant) and `tenants.ts` (ceilings, state and archiving).
+ * Everything here takes a transaction handle and writes no audit row of its
+ * own: the caller knows which actor is doing this and what to log, and every
+ * function below is meant to run inside the caller's single transaction,
+ * after it has locked the tenants involved with `lockTenantsForUpdate`.
+ *
+ * **Authority flows downhill, materialised at write time.** A membership at
+ * an ancestor is mirrored into real rows in every descendant, marked
+ * `source = 'inherited'` with `via_tenant_id` naming the ancestor it came
+ * from, rather than walked upward on the read path. That is what keeps
+ * `accessFor` a single indexed probe at any depth (D19: the alternative
+ * measured 450 times slower on the list shape), and it is why the four
+ * propagating writes (in `./tree-writes.js`) are the ones that pay the cost.
+ *
+ * **The derived rule, stated once, because everything here is that rule.**
+ * For a tenant T and a principal P:
+ *
+ * - If P holds a `direct` row in T, T's own row is what counts and nothing
+ *   here ever touches it (M6). Agency staff invited into a client before the
+ *   attach keep their direct role, and detach leaves it behind.
+ * - Otherwise P holds a derived row in T exactly when some ancestor of T has
+ *   a `direct` row for P, and the row mirrors the **nearest** such ancestor:
+ *   its role, with `via_tenant_id` naming it.
+ * - Except when P holds a membership in the operator tenant, in which case P
+ *   never holds a derived row anywhere (D8). An attachment is two customer
+ *   organisations consenting about each other, not about whoever runs the
+ *   console, and this is the one clause that keeps "an operator has no
+ *   standing reach into membership" true once tenants can hold tenants.
+ * - Otherwise P holds no row in T.
+ *
+ * Nearest wins because the rule has to be a pure function of the direct rows
+ * above T for the reconciliation check (D9) to mean anything: given the tree
+ * and its direct rows, exactly one derived set is correct, so a row that
+ * should have gone and did not, or never got written, is a difference anyone
+ * can compute. At a policy's `maxDepth` of 1 there is only ever one ancestor
+ * and the rule degenerates to "the parent's row"; it is written for depth N
+ * because a two-level host (lokessmie) runs the same code at depth 2.
+ *
+ * **Depth counts edges.** A policy's `maxDepth` bounds every traversal here,
+ * plus a hard cap besides, so malformed data throws rather than looping.
+ */
+/** What every tree read returns: the tenant fields nesting decisions are made from. */
+export interface TenantNode {
+    readonly id: string;
+    readonly kind: TenantKind;
+    readonly slug: string;
+    readonly name: string;
+    readonly state: TenantState;
+    readonly parentId: string | null;
+    readonly ceiling: readonly string[];
+    readonly selfDenied: readonly string[];
+}
+/**
+ * A parent chain that does not terminate, or is longer than any depth this
+ * app allows. Cycles are impossible through the functions in this file (an
+ * attach refuses one before it is written), so this is a corruption report,
+ * not a condition a caller handles: it throws rather than returning a
+ * refusal, and it fails the transaction it is in.
+ */
+export declare class TenantCycleError extends Error {
+    constructor(tenantId: string);
+}
+/** One tenant, or null. */
+export declare function nodeById(tx: DbOrTx, tenantId: string): Promise<TenantNode | null>;
+/**
+ * Locks the given tenants `FOR UPDATE`, always in ascending id order, and
+ * returns them keyed by id. The order is the point: an attach and a rename
+ * touching the same two rows from opposite ends would deadlock, and sorting
+ * the ids gives every transaction in this module the same lock sequence.
+ * Ids that name no row are simply absent from the map.
+ */
+export declare function lockTenantsForUpdate(tx: DbOrTx, tenantIds: readonly string[]): Promise<Map<string, TenantNode>>;
+/**
+ * Locks a tenant and everything below it, and keeps looking until the set
+ * stops growing.
+ *
+ * Reading the subtree and then locking what it found is not the same thing,
+ * and the difference is a live bug rather than a nicety: an attach that
+ * commits between the read and the lock adds a child the caller will never
+ * see, so a ceiling cascade skips it and an "are there children" check says
+ * no while a child is sitting right there.
+ *
+ * Locking downward in waves closes it. An attach of C under P must lock P,
+ * so once P is locked no new child of P can appear; reading P's children
+ * under that lock gives a set that cannot grow, and locking those children
+ * in turn freezes the next level. The loop runs at most `MAX_CHAIN` times
+ * and, at the depths a policy allows, two or three.
+ */
+export declare function lockSubtreeForUpdate(tx: DbOrTx, rootId: string): Promise<Map<string, TenantNode>>;
+/**
+ * Locks everything `attachProblem` is about to read: the child and its whole
+ * subtree, the proposed parent, and every ancestor above the parent.
+ *
+ * Locking only the two named tenants is not enough, because the depth rule
+ * counts rows neither of them is. Two attaches at opposite ends of one chain
+ * lock disjoint pairs, each reads a depth that is true at the time and stale
+ * by the time it commits, and together they build a tree deeper than
+ * `maxDepth` allows. That cannot happen at a policy depth of 1, where no
+ * chain is long enough to have two ends; it happens at a two-level host's
+ * depth of 2, which runs this same code.
+ */
+export declare function lockAttachScope(tx: DbOrTx, parentId: string, childId: string): Promise<void>;
+/**
+ * Every ancestor of this tenant, nearest first: its parent, then its
+ * parent's parent, and so on to the root. Empty for a tenant with no parent.
+ * Bounded by `MAX_CHAIN` and by a visited set, so a cycle in the data throws
+ * instead of hanging.
+ */
+export declare function ancestorsOf(tx: DbOrTx, tenantId: string): Promise<TenantNode[]>;
+/** The tenants whose `parent_id` is this one. */
+export declare function childrenOf(tx: DbOrTx, tenantId: string): Promise<TenantNode[]>;
+/**
+ * Every tenant below this one, breadth first, nearest level first. Excludes
+ * the tenant itself. One query per level rather than a recursive CTE: the
+ * depth is small, so this is two or three round trips with plainly
+ * readable SQL, and the loop is where the cycle guard lives.
+ */
+export declare function descendantsOf(tx: DbOrTx, tenantId: string): Promise<TenantNode[]>;
+/** How many edges sit above this tenant: 0 for a root, 1 for a child of a root. */
+export declare function depthAbove(tx: DbOrTx, tenantId: string): Promise<number>;
+/**
+ * How many edges sit below this tenant at its deepest: 0 for a leaf, 1 for a
+ * tenant whose children are all leaves. Computed from the subtree's own
+ * parent links rather than a second traversal per node.
+ */
+export declare function heightBelow(tx: DbOrTx, tenantId: string): Promise<number>;
+/** Why two tenants may not be attached, with a reason a host page can hand to a caller. */
+export interface AttachProblem {
+    readonly reason: string;
+    readonly message: string;
+    /** The permission strings a ceiling refusal names, so the page can list them. */
+    readonly offenders?: readonly string[];
+}
+/**
+ * Whether `childId` may be attached under `parentId`, checked against every
+ * cross-row rule D19 and D22 state. Called three times over the life of one
+ * attachment and deliberately so: by the host's `proposeAttach`, so a
+ * proposal that could never be accepted is refused when it is written; by
+ * `acceptAttach` inside the lock, which is the check that actually decides;
+ * and by the born-attached invitation path, where the proposal step never
+ * happened. Nothing is cached between them, because everything it reads can
+ * move while a proposal sits pending.
+ *
+ * Ceilings are the last check rather than the first because its refusal is
+ * the only one that names offenders, and a caller showing "narrow these two
+ * permissions first" should not be shown it about a pair that could never be
+ * attached anyway.
+ *
+ * `policy` carries `maxDepth` and `offered` (wave 3's `StorePolicy`) — the
+ * only two fields this function needs from it, not the role templates.
+ */
+export declare function attachProblem(tx: DbOrTx, policy: Pick<StorePolicy, 'maxDepth' | 'offered'>, parentId: string, childId: string): Promise<AttachProblem | null>;
+/** What the rule says a derived row in one tenant should hold. */
+export interface ExpectedDerived {
+    readonly principalId: string;
+    readonly principalClass: string;
+    readonly role: string;
+    readonly viaTenantId: string;
+    readonly grantedBy: string | null;
+}
+/**
+ * What derived rows tenant `tenantId` should hold, by the rule at the top of
+ * this file: the nearest ancestor's direct row for each principal, minus
+ * every principal who holds a direct row here. `principalIds` narrows the
+ * question to a few principals, which is what a single grant needs; without
+ * it the answer covers everyone the ancestry knows about, which is what an
+ * attach and the reconciliation check need.
+ *
+ * The one read every writer and the reconciliation check share, on purpose:
+ * reconciliation exists to catch a write that did not happen or a row that
+ * did not go, so it must ask the same question the writer answered. What
+ * catches the rule itself being wrong is the property tests, not a second
+ * copy of the rule that could be wrong in the same way.
+ */
+export declare function expectedDerivedFor(tx: DbOrTx, binding: StoreBinding, tenantId: string, principalIds?: readonly string[]): Promise<ExpectedDerived[]>;
+/** A principal whose derived row would have to carry a custom role, and where it would come from. */
+export interface CustomRoleBlocker {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly role: string;
+    readonly viaTenantId: string;
+}
+/**
+ * The custom roles standing in the way of writing derived rows for these
+ * tenants (D19: a derived membership carries a system role, never a custom
+ * one). Empty means the propagation may go ahead. Callers use this to refuse
+ * with the offenders named rather than propagating partially: the fix is to
+ * move those people to a system role at the parent, and only the parent can
+ * decide that.
+ */
+export declare function customRoleBlockers(tx: DbOrTx, binding: StoreBinding, tenantIds: readonly string[], principalIds?: readonly string[]): Promise<CustomRoleBlocker[]>;
+/**
+ * The same question `customRoleBlockers` answers, but about an attachment
+ * that has not happened yet: what custom roles would have to reach the
+ * child's subtree if `childId` were attached under `parentId`.
+ *
+ * This exists because the obvious call does not work. `customRoleBlockers`
+ * reads the ancestry a tenant has *now*, and a child being proposed to still
+ * has none, so asking it before the attach always answers "nothing" and the
+ * refusal D19 asks for could never fire. The two agents that hit this each
+ * worked around it by writing `parent_id` first and undoing the transaction
+ * when the check then fired, which works but makes a refusal cost a rollback
+ * and leaves every future caller to rediscover the trap.
+ *
+ * Call this BEFORE the attachment is written. Afterwards the ordinary
+ * `customRoleBlockers` is the right question, because by then the chain this
+ * one has to imagine is the chain that exists.
+ */
+export declare function attachCustomRoleBlockers(tx: DbOrTx, binding: StoreBinding, parentId: string, childId: string): Promise<CustomRoleBlocker[]>;
+/** What one `recomputeDerived` (`./tree-writes.js`) call changed, for the caller's audit rows and for the tests. */
+export interface DerivedChange {
+    readonly tenantId: string;
+    readonly principalId: string;
+    readonly kind: 'created' | 'role_changed' | 'ended';
+    readonly before: {
+        readonly role: string;
+        readonly viaTenantId: string | null;
+    } | null;
+    readonly after: {
+        readonly role: string;
+        readonly viaTenantId: string;
+    } | null;
+}
+/**
+ * The audit action one derived change writes as: the same three names a
+ * direct write uses. A derived row is a membership like any other, and the
+ * log says which ancestor it came from through `via_tenant_id` on the row
+ * rather than through a fourth action nobody would think to search for.
+ * Exported because every caller of `recomputeDerived` needs it, and three
+ * private copies of one switch is how the three drift apart.
+ */
+export declare function derivedEventAction(kind: DerivedChange['kind']): EventName;
+/**
+ * Every principal holding a direct row anywhere at or above this tenant: the
+ * set whose derived rows can move when the tree does. Used by
+ * `attachInTx`/`detachInTx` (`./tree-writes.js`), which change the shape
+ * rather than one person's role and so cannot narrow the recomputation to a
+ * principal they already know.
+ */
+export declare function principalsAtOrAbove(tx: DbOrTx, binding: StoreBinding, tenantId: string): Promise<string[]>;
+/** A direct membership in a detached child that a holder of a derived role granted while the link stood. */
+export interface DetachReportRow {
+    readonly principalId: string;
+    readonly role: string;
+    readonly grantedBy: string | null;
+    readonly createdAt: Date;
+}
+/**
+ * What a reseller's staff left behind: every direct membership in this child
+ * that was granted, while the link stood, by someone whose own authority
+ * there was derived from the parent (D19's sixth rule). Nothing is removed;
+ * the child's owner gets the list and decides.
+ *
+ * Read before `detachInTx` (`./tree-writes.js`), because it asks who
+ * currently holds a derived row, and detaching is what takes those rows
+ * away.
+ */
+export declare function detachReport(tx: DbOrTx, binding: StoreBinding, childId: string, since: Date): Promise<DetachReportRow[]>;