@venturekit-pro/tenancy 0.0.39 → 0.0.41

package/README.md

@@ -77,6 +77,42 @@ const tenant = getCurrentTenant(ctx);
 // { id: 'acme', slug: 'acme', metadata: { ... } }
 ```
 
+## Hierarchy
+
+Tenants form trees — a group and its schools, a franchise and its stores. The tree is
+`vk_tenants.parent_id` plus `vk_tenant_closure` (every ancestor→descendant path with its
+depth, migration `0000_vk_tenancy_tree`), maintained in code and read in one statement:
+
+```typescript
+import { createTenantTree, unpackTenantRoles } from '@venturekit-pro/tenancy';
+import { query } from '@venturekit/data';
+
+const tree = createTenantTree(); // or { tenants: 'platform.tenant_ref', closure: 'platform.tenant_closure' } on a projection
+await tree.setParent(query, schoolId, groupId); // rewrites the subtree's closure; refuses a cycle
+await tree.descendantsOf(query, groupId);         // [{ tenantId, depth }], shallowest first
+await tree.ancestorsOf(query, schoolId);          // nearest first
+```
+
+A role held in a parent counts in its descendants — a group's owner is the owner of each
+of its schools without a membership row in any. The rules are pure (`inheritedTenantRole`,
+`reachableTenants`), and the tree feeds them:
+
+```typescript
+const pack = unpackTenantRoles(ctx.user.claims['custom:tenantRoles']);
+const isSystemRole = (role: string) => role in SYSTEM_ROLES; // custom roles are rows of the tenant that defined them
+
+// a request naming another tenant: may this session act as it, and as what?
+const held = await tree.roleIn(query, pack, requestedTenantId, { inherits: isSystemRole });
+if (!held) throw new ForbiddenError('This session may not act as that tenant');
+
+// a session description / tenant switcher: every tenant this user may act as
+const sites = await tree.reach(query, pack, { inherits: isSystemRole });
+```
+
+An explicit membership in a child always wins over an inherited one, and a nearer
+ancestor over a farther one. The store is read only when the memberships alone do not
+settle the question.
+
 ## Erasure and export
 
 The cascade walker that backs `hardDeleteTenant` also serves the two

package/dist/hierarchy/index.d.ts

@@ -0,0 +1,5 @@
+export { inheritedTenantRole, reachableTenants } from './reach.js';
+export type { HeldTenantRole, HierarchyOptions, TenantDescendant, TenantMembership } from './reach.js';
+export { createTenantTree, TenantTreeCycleError, TenantTreeDepthError, TENANT_TREE_MAX_DEPTH, VK_TENANT_TREE } from './tree.js';
+export type { TenantAncestor, TenantTree, TenantTreeTables, TreeQuerier } from './tree.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hierarchy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hierarchy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChI,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/hierarchy/index.js

@@ -0,0 +1,3 @@
+export { inheritedTenantRole, reachableTenants } from './reach.js';
+export { createTenantTree, TenantTreeCycleError, TenantTreeDepthError, TENANT_TREE_MAX_DEPTH, VK_TENANT_TREE } from './tree.js';
+//# sourceMappingURL=index.js.map

package/dist/hierarchy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hierarchy/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/hierarchy/reach.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Tenant hierarchy — what a role in a parent tenant is worth in its children.
+ *
+ * Multi-tenant products grow trees: a school group and its schools, a franchise
+ * and its stores, an agency and its clients' workspaces. The membership model
+ * stays flat (one row per user × tenant, the `TenantUser` shape the scopes
+ * middleware reads), and the tree adds ONE rule on top: **a role held in a
+ * parent is held in every descendant, unless the app says that role does not
+ * travel.** A group's owner is the owner of each school without a membership row
+ * in any of them; an explicit membership in a child always wins over the
+ * inherited one; a nearer ancestor wins over a farther one.
+ *
+ * These are the rules, pure, over what the caller supplies: the memberships
+ * (typically the packed `custom:tenantRoles` claim, see `unpackTenantRoles`) and
+ * the tenant's ancestors or a membership tenant's descendants. The store that
+ * answers those — `vk_tenants.parent_id` and `vk_tenant_closure`, or a projection's
+ * own pair — is `./tree.ts`, whose `roleIn` / `reach` feed these two functions.
+ * Two questions, two functions:
+ *
+ *   - {@link inheritedTenantRole} — "may this caller act as tenant X, and as
+ *     what?" — for a request that names a tenant other than its own.
+ *   - {@link reachableTenants} — "which tenants may this caller act as at all?"
+ *     — for a session description or a tenant switcher.
+ *
+ * Which roles travel is the app's call ({@link HierarchyOptions.inherits}). The
+ * default is that every role does; an app whose custom roles are rows of the
+ * tenant that defined them (their scopes mean nothing in a child) passes a
+ * predicate that keeps inheritance to its system roles.
+ */
+/** One membership: which role the caller holds in which tenant. Same shape as a packed claim entry. */
+export interface TenantMembership {
+    tenantId: string;
+    role: string;
+}
+export interface HierarchyOptions {
+    /**
+     * Whether a role held in a parent counts in its descendants. Default: every
+     * role does. Return `false` for roles whose meaning is bound to the tenant
+     * that defined them (custom roles keyed by a per-tenant id, for instance).
+     */
+    inherits?: (role: string, tenantId: string) => boolean;
+}
+/** How a caller comes to hold a role in a tenant. */
+export interface HeldTenantRole {
+    tenantId: string;
+    role: string;
+    /** The tenant the membership is actually in: the tenant itself, or the ancestor the role came from. */
+    via: string;
+    /** Hops from `via` down to `tenantId`; `0` is the caller's own membership. */
+    depth: number;
+}
+/**
+ * The role a caller holds in `tenantId`, and through which tenant — or `null`
+ * when it has no business there.
+ *
+ * The caller's own membership in the tenant wins outright, whatever the role.
+ * Otherwise `ancestors` is walked **nearest first** (the app reads them from
+ * its tree: parent, grandparent, …) and the first ancestor the caller holds an
+ * inheritable role in decides. Roles the app marks as non-inheriting are
+ * skipped, not refused — a farther ancestor with a system role still counts.
+ *
+ * @example
+ * ```ts
+ * const pack = unpackTenantRoles(claims['custom:tenantRoles']);
+ * const ancestors = await closure.ancestorsOf(requestedTenantId); // nearest first
+ * const held = inheritedTenantRole(pack, requestedTenantId, ancestors, {
+ *   inherits: (role) => isSystemRole(role),
+ * });
+ * if (!held) throw new ForbiddenError('This session may not act as that tenant');
+ * ```
+ */
+export declare function inheritedTenantRole(memberships: ReadonlyMap<string, string> | readonly TenantMembership[], tenantId: string, ancestors: readonly string[], options?: HierarchyOptions): HeldTenantRole | null;
+/** A descendant of a tenant, as the app's tree reports it. */
+export interface TenantDescendant {
+    tenantId: string;
+    /** Hops down from the ancestor asked about: a child is `1`. */
+    depth: number;
+}
+/**
+ * Every tenant a caller may act as: each membership's own tenant, plus — for a
+ * membership whose role inherits — every descendant of that tenant, carrying the
+ * role. A tenant reached more than once keeps the **nearest** claim to it: an
+ * explicit membership (depth 0) over any inherited one, a parent's role over a
+ * grandparent's. `descendantsOf` is asked once per membership whose role
+ * inherits, so a caller with only leaf memberships costs no tree read at all.
+ *
+ * The result is unordered; the app joins names and sorts for display.
+ */
+export declare function reachableTenants(memberships: ReadonlyMap<string, string> | readonly TenantMembership[], descendantsOf: (tenantId: string) => readonly TenantDescendant[], options?: HierarchyOptions): HeldTenantRole[];
+//# sourceMappingURL=reach.d.ts.map

package/dist/hierarchy/reach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.d.ts","sourceRoot":"","sources":["../../src/hierarchy/reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACxD;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;CACf;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,gBAAgB,EAAE,EACtE,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,OAAO,GAAE,gBAAqB,GAC7B,cAAc,GAAG,IAAI,CAYvB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,gBAAgB,EAAE,EACtE,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,gBAAgB,EAAE,EAChE,OAAO,GAAE,gBAAqB,GAC7B,cAAc,EAAE,CAiBlB"}

package/dist/hierarchy/reach.js

@@ -0,0 +1,106 @@
+/**
+ * Tenant hierarchy — what a role in a parent tenant is worth in its children.
+ *
+ * Multi-tenant products grow trees: a school group and its schools, a franchise
+ * and its stores, an agency and its clients' workspaces. The membership model
+ * stays flat (one row per user × tenant, the `TenantUser` shape the scopes
+ * middleware reads), and the tree adds ONE rule on top: **a role held in a
+ * parent is held in every descendant, unless the app says that role does not
+ * travel.** A group's owner is the owner of each school without a membership row
+ * in any of them; an explicit membership in a child always wins over the
+ * inherited one; a nearer ancestor wins over a farther one.
+ *
+ * These are the rules, pure, over what the caller supplies: the memberships
+ * (typically the packed `custom:tenantRoles` claim, see `unpackTenantRoles`) and
+ * the tenant's ancestors or a membership tenant's descendants. The store that
+ * answers those — `vk_tenants.parent_id` and `vk_tenant_closure`, or a projection's
+ * own pair — is `./tree.ts`, whose `roleIn` / `reach` feed these two functions.
+ * Two questions, two functions:
+ *
+ *   - {@link inheritedTenantRole} — "may this caller act as tenant X, and as
+ *     what?" — for a request that names a tenant other than its own.
+ *   - {@link reachableTenants} — "which tenants may this caller act as at all?"
+ *     — for a session description or a tenant switcher.
+ *
+ * Which roles travel is the app's call ({@link HierarchyOptions.inherits}). The
+ * default is that every role does; an app whose custom roles are rows of the
+ * tenant that defined them (their scopes mean nothing in a child) passes a
+ * predicate that keeps inheritance to its system roles.
+ */
+const ALL_ROLES_INHERIT = () => true;
+function asMap(memberships) {
+    if (memberships instanceof Map)
+        return memberships;
+    const out = new Map();
+    for (const { tenantId, role } of memberships) {
+        if (!out.has(tenantId))
+            out.set(tenantId, role);
+    }
+    return out;
+}
+/**
+ * The role a caller holds in `tenantId`, and through which tenant — or `null`
+ * when it has no business there.
+ *
+ * The caller's own membership in the tenant wins outright, whatever the role.
+ * Otherwise `ancestors` is walked **nearest first** (the app reads them from
+ * its tree: parent, grandparent, …) and the first ancestor the caller holds an
+ * inheritable role in decides. Roles the app marks as non-inheriting are
+ * skipped, not refused — a farther ancestor with a system role still counts.
+ *
+ * @example
+ * ```ts
+ * const pack = unpackTenantRoles(claims['custom:tenantRoles']);
+ * const ancestors = await closure.ancestorsOf(requestedTenantId); // nearest first
+ * const held = inheritedTenantRole(pack, requestedTenantId, ancestors, {
+ *   inherits: (role) => isSystemRole(role),
+ * });
+ * if (!held) throw new ForbiddenError('This session may not act as that tenant');
+ * ```
+ */
+export function inheritedTenantRole(memberships, tenantId, ancestors, options = {}) {
+    const held = asMap(memberships);
+    const inherits = options.inherits ?? ALL_ROLES_INHERIT;
+    const own = held.get(tenantId);
+    if (own !== undefined)
+        return { tenantId, role: own, via: tenantId, depth: 0 };
+    for (const [index, ancestor] of ancestors.entries()) {
+        const role = held.get(ancestor);
+        if (role !== undefined && inherits(role, ancestor)) {
+            return { tenantId, role, via: ancestor, depth: index + 1 };
+        }
+    }
+    return null;
+}
+/**
+ * Every tenant a caller may act as: each membership's own tenant, plus — for a
+ * membership whose role inherits — every descendant of that tenant, carrying the
+ * role. A tenant reached more than once keeps the **nearest** claim to it: an
+ * explicit membership (depth 0) over any inherited one, a parent's role over a
+ * grandparent's. `descendantsOf` is asked once per membership whose role
+ * inherits, so a caller with only leaf memberships costs no tree read at all.
+ *
+ * The result is unordered; the app joins names and sorts for display.
+ */
+export function reachableTenants(memberships, descendantsOf, options = {}) {
+    const held = asMap(memberships);
+    const inherits = options.inherits ?? ALL_ROLES_INHERIT;
+    const best = new Map();
+    const offer = (candidate) => {
+        const current = best.get(candidate.tenantId);
+        if (!current || candidate.depth < current.depth)
+            best.set(candidate.tenantId, candidate);
+    };
+    for (const [tenantId, role] of held) {
+        offer({ tenantId, role, via: tenantId, depth: 0 });
+        if (!inherits(role, tenantId))
+            continue;
+        for (const { tenantId: descendant, depth } of descendantsOf(tenantId)) {
+            if (depth < 1)
+                continue;
+            offer({ tenantId: descendant, role, via: tenantId, depth });
+        }
+    }
+    return [...best.values()];
+}
+//# sourceMappingURL=reach.js.map

package/dist/hierarchy/reach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reach.js","sourceRoot":"","sources":["../../src/hierarchy/reach.ts"],"names":[],"mappings":"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"}

package/dist/hierarchy/tree.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The tenant tree in the store: the parent edge on the tenants table and the
+ * closure table beside it (`0000_vk_tenancy_tree.sql`), read and maintained here.
+ *
+ * Two structures, one owner. `parent_id` is the fact; `vk_tenant_closure` is the
+ * fact unrolled — every ancestor→descendant path with its depth, the self-row
+ * at 0 — so the questions a request asks ("the tenants under X", "the ancestors
+ * of Y") are one indexed read each. Both are written **only** through
+ * {@link TenantTree.setParent} / {@link TenantTree.rebuildClosure}, which
+ * rebuild the closure wholesale for the tenant and its whole subtree: the
+ * graphs are small and shallow, and wholesale is easier to prove right than
+ * incremental edits. No trigger does it — a rule in a trigger runs where the
+ * tests do not look.
+ *
+ * The table names are configurable ({@link TenantTreeTables}) because a service
+ * that only *projects* tenants from another system keeps the same two structures
+ * under its own names (a `tenant_ref` with a `parent_id`, a closure beside it)
+ * and wants the same maintenance code rather than a copy.
+ *
+ * The hierarchy *rules* — what a role in a parent is worth in a child — are
+ * `./reach.ts`, pure; {@link TenantTree.reach} and {@link TenantTree.roleIn} are
+ * those rules fed from this store.
+ *
+ * @example
+ * ```ts
+ * const tree = createTenantTree();               // vk_tenants / vk_tenant_closure
+ * await tree.setParent(query, schoolId, groupId); // refuses a cycle
+ * const sites = await tree.reach(query, unpackTenantRoles(claims['custom:tenantRoles']), { inherits: isSystemRole });
+ * ```
+ */
+import type { HeldTenantRole, HierarchyOptions, TenantDescendant, TenantMembership } from './reach.js';
+/**
+ * Any querier that runs SQL with positional parameters and resolves to the rows —
+ * `@venturekit/data`'s `query`, a transaction's `query`, a `pg` client wrapped.
+ * Row columns are read under the aliases the statements give them, so a client
+ * that maps snake_case to camelCase and one that does not both work.
+ */
+export type TreeQuerier = (sql: string, params?: unknown[]) => Promise<unknown>;
+/** Where the tree lives. Defaults are the package's own tables. */
+export interface TenantTreeTables {
+    /** The tenants table; must have `id` and the parent column. */
+    tenants: string;
+    /** The parent edge column on {@link tenants}. */
+    parentColumn: string;
+    /** The closure table: `ancestor_id`, `descendant_id`, `depth`. */
+    closure: string;
+}
+export declare const VK_TENANT_TREE: TenantTreeTables;
+/** How deep a tree may go — a guard against a runaway walk, not a product limit anyone should meet. */
+export declare const TENANT_TREE_MAX_DEPTH = 16;
+/** A tenant's place relative to another: how many hops away. */
+export interface TenantAncestor {
+    tenantId: string;
+    /** Hops up from the tenant asked about: the parent is `1`. */
+    depth: number;
+}
+export interface TenantTree {
+    readonly tables: TenantTreeTables;
+    /**
+     * Make `parentId` the parent of `tenantId` (or `null` to make it a root) and
+     * rebuild the closure for the tenant and everything under it. Refuses a tenant
+     * as its own ancestor ({@link TenantTreeCycleError}) and a tree deeper than
+     * {@link TENANT_TREE_MAX_DEPTH} ({@link TenantTreeDepthError}). Idempotent for
+     * an unchanged parent — safe to call right after inserting the tenant row.
+     */
+    setParent(q: TreeQuerier, tenantId: string, parentId: string | null): Promise<void>;
+    /**
+     * Rewrite the closure rows of `tenantId` and its whole subtree from the parent
+     * column as it stands — for a row whose parent was written by other means (a
+     * projection, a backfill). What `setParent` calls after writing the edge.
+     */
+    rebuildClosure(q: TreeQuerier, tenantId: string): Promise<void>;
+    /** The ancestors of a tenant, nearest first; empty for a root. */
+    ancestorsOf(q: TreeQuerier, tenantId: string): Promise<TenantAncestor[]>;
+    /** Every tenant under a tenant, shallowest first; empty for a leaf. */
+    descendantsOf(q: TreeQuerier, tenantId: string): Promise<TenantDescendant[]>;
+    /** The descendants of several tenants in one read, keyed by the tenant asked about (absent = none). */
+    descendantsOfAll(q: TreeQuerier, tenantIds: readonly string[]): Promise<Map<string, TenantDescendant[]>>;
+    /** `reachableTenants` over this tree: every tenant a caller with these memberships may act as. One read, for the inheriting memberships only. */
+    reach(q: TreeQuerier, memberships: ReadonlyMap<string, string> | readonly TenantMembership[], options?: HierarchyOptions): Promise<HeldTenantRole[]>;
+    /** `inheritedTenantRole` over this tree: the role held in `tenantId`, or `null`. The store is read only when the memberships alone do not settle it. */
+    roleIn(q: TreeQuerier, memberships: ReadonlyMap<string, string> | readonly TenantMembership[], tenantId: string, options?: HierarchyOptions): Promise<HeldTenantRole | null>;
+}
+export declare class TenantTreeCycleError extends Error {
+    constructor(tenantId: string, parentId: string);
+}
+export declare class TenantTreeDepthError extends Error {
+    constructor(tenantId: string, depth: number);
+}
+export declare function createTenantTree(tables?: Partial<TenantTreeTables>): TenantTree;
+//# sourceMappingURL=tree.d.ts.map

package/dist/hierarchy/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/hierarchy/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhF,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,cAAc,EAAE,gBAI5B,CAAC;AAEF,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpF;;;;OAIG;IACH,cAAc,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,kEAAkE;IAClE,WAAW,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACzE,uEAAuE;IACvE,aAAa,CAAC,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC7E,uGAAuG;IACvG,gBAAgB,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACzG,iJAAiJ;IACjJ,KAAK,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,gBAAgB,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACrJ,wJAAwJ;IACxJ,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,gBAAgB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CAC9K;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAI/C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAI5C;AAgBD,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,OAAO,CAAC,gBAAgB,CAAM,GAAG,UAAU,CAoGnF"}

package/dist/hierarchy/tree.js

@@ -0,0 +1,149 @@
+/**
+ * The tenant tree in the store: the parent edge on the tenants table and the
+ * closure table beside it (`0000_vk_tenancy_tree.sql`), read and maintained here.
+ *
+ * Two structures, one owner. `parent_id` is the fact; `vk_tenant_closure` is the
+ * fact unrolled — every ancestor→descendant path with its depth, the self-row
+ * at 0 — so the questions a request asks ("the tenants under X", "the ancestors
+ * of Y") are one indexed read each. Both are written **only** through
+ * {@link TenantTree.setParent} / {@link TenantTree.rebuildClosure}, which
+ * rebuild the closure wholesale for the tenant and its whole subtree: the
+ * graphs are small and shallow, and wholesale is easier to prove right than
+ * incremental edits. No trigger does it — a rule in a trigger runs where the
+ * tests do not look.
+ *
+ * The table names are configurable ({@link TenantTreeTables}) because a service
+ * that only *projects* tenants from another system keeps the same two structures
+ * under its own names (a `tenant_ref` with a `parent_id`, a closure beside it)
+ * and wants the same maintenance code rather than a copy.
+ *
+ * The hierarchy *rules* — what a role in a parent is worth in a child — are
+ * `./reach.ts`, pure; {@link TenantTree.reach} and {@link TenantTree.roleIn} are
+ * those rules fed from this store.
+ *
+ * @example
+ * ```ts
+ * const tree = createTenantTree();               // vk_tenants / vk_tenant_closure
+ * await tree.setParent(query, schoolId, groupId); // refuses a cycle
+ * const sites = await tree.reach(query, unpackTenantRoles(claims['custom:tenantRoles']), { inherits: isSystemRole });
+ * ```
+ */
+import { inheritedTenantRole, reachableTenants } from './reach.js';
+export const VK_TENANT_TREE = {
+    tenants: 'vk_tenants',
+    parentColumn: 'parent_id',
+    closure: 'vk_tenant_closure',
+};
+/** How deep a tree may go — a guard against a runaway walk, not a product limit anyone should meet. */
+export const TENANT_TREE_MAX_DEPTH = 16;
+export class TenantTreeCycleError extends Error {
+    constructor(tenantId, parentId) {
+        super(`Tenant ${tenantId} cannot have ${parentId} as its parent: that tenant is beneath it`);
+        this.name = 'TenantTreeCycleError';
+    }
+}
+export class TenantTreeDepthError extends Error {
+    constructor(tenantId, depth) {
+        super(`Tenant ${tenantId} would sit ${depth} levels deep; the tree stops at ${TENANT_TREE_MAX_DEPTH}`);
+        this.name = 'TenantTreeDepthError';
+    }
+}
+/* SQL identifiers come from code, never from a request — but a typo must not become SQL. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?$/;
+function identifier(value, what) {
+    if (!IDENTIFIER.test(value))
+        throw new Error(`createTenantTree: ${what} '${value}' is not a plain SQL identifier`);
+    return value;
+}
+function asMemberships(memberships) {
+    return memberships instanceof Map
+        ? [...memberships].map(([tenantId, role]) => ({ tenantId, role }))
+        : [...memberships];
+}
+export function createTenantTree(tables = {}) {
+    const T = identifier(tables.tenants ?? VK_TENANT_TREE.tenants, 'tenants table');
+    const P = identifier(tables.parentColumn ?? VK_TENANT_TREE.parentColumn, 'parent column');
+    const C = identifier(tables.closure ?? VK_TENANT_TREE.closure, 'closure table');
+    const rows = async (q, sql, params) => (await q(sql, params));
+    /* the tenant and everything under it, walking the parent column (the closure may be what is being repaired) */
+    const subtree = `
+    with recursive sub as (
+      select id, 0 as depth from ${T} where id = $1::uuid
+      union all
+      select t.id, s.depth + 1 from ${T} t join sub s on t.${P} = s.id where s.depth < ${TENANT_TREE_MAX_DEPTH}
+    )`;
+    const tree = {
+        tables: { tenants: T, parentColumn: P, closure: C },
+        async setParent(q, tenantId, parentId) {
+            if (parentId !== null) {
+                if (parentId === tenantId)
+                    throw new TenantTreeCycleError(tenantId, parentId);
+                /* the new parent's ancestry, by the parent column: the tenant must not be in it, and the depth must fit */
+                const up = await rows(q, `with recursive up as (
+             select id as "tenantId", 0 as depth, ${P} as parent_id from ${T} where id = $1::uuid
+             union all
+             select t.id, up.depth + 1, t.${P} from ${T} t join up on t.id = up.parent_id where up.depth < ${TENANT_TREE_MAX_DEPTH + 1}
+           )
+           select "tenantId", depth from up`, [parentId]);
+                if (up.some((a) => a.tenantId === tenantId))
+                    throw new TenantTreeCycleError(tenantId, parentId);
+                const parentDepth = up.length; // the parent's own row counts: a root parent puts the tenant at depth 1
+                const below = await rows(q, `${subtree} select coalesce(max(depth), 0)::int as n from sub`, [tenantId]);
+                const deepest = parentDepth + Number(below[0]?.n ?? 0);
+                if (deepest > TENANT_TREE_MAX_DEPTH)
+                    throw new TenantTreeDepthError(tenantId, deepest);
+            }
+            await q(`update ${T} set ${P} = $2::uuid where id = $1::uuid`, [tenantId, parentId]);
+            await tree.rebuildClosure(q, tenantId);
+        },
+        async rebuildClosure(q, tenantId) {
+            await q(`${subtree} delete from ${C} where descendant_id in (select id from sub)`, [tenantId]);
+            await q(`${subtree},
+         up as (
+           select s.id as descendant_id, s.id as ancestor_id, 0 as depth, t.${P} as parent_id
+             from sub s join ${T} t on t.id = s.id
+           union all
+           select up.descendant_id, t.id, up.depth + 1, t.${P}
+             from up join ${T} t on t.id = up.parent_id
+            where up.depth < ${TENANT_TREE_MAX_DEPTH}
+         )
+         insert into ${C} (ancestor_id, descendant_id, depth)
+         select ancestor_id, descendant_id, depth from up`, [tenantId]);
+        },
+        async ancestorsOf(q, tenantId) {
+            return rows(q, `select ancestor_id as "tenantId", depth from ${C} where descendant_id = $1::uuid and depth > 0 order by depth`, [tenantId]);
+        },
+        async descendantsOf(q, tenantId) {
+            return rows(q, `select descendant_id as "tenantId", depth from ${C} where ancestor_id = $1::uuid and depth > 0 order by depth`, [tenantId]);
+        },
+        async descendantsOfAll(q, tenantIds) {
+            const out = new Map();
+            if (tenantIds.length === 0)
+                return out;
+            const found = await rows(q, `select ancestor_id as "rootId", descendant_id as "tenantId", depth from ${C} where ancestor_id = any($1::uuid[]) and depth > 0 order by depth`, [[...tenantIds]]);
+            for (const { rootId, tenantId, depth } of found) {
+                const list = out.get(rootId) ?? [];
+                list.push({ tenantId, depth: Number(depth) });
+                out.set(rootId, list);
+            }
+            return out;
+        },
+        async reach(q, memberships, options = {}) {
+            const held = asMemberships(memberships);
+            const inherits = options.inherits ?? (() => true);
+            const roots = held.filter((m) => inherits(m.role, m.tenantId)).map((m) => m.tenantId);
+            const below = await tree.descendantsOfAll(q, roots);
+            return reachableTenants(held, (tenantId) => below.get(tenantId) ?? [], options);
+        },
+        async roleIn(q, memberships, tenantId, options = {}) {
+            const held = asMemberships(memberships);
+            const direct = inheritedTenantRole(held, tenantId, [], options);
+            if (direct || held.length === 0)
+                return direct;
+            const ancestors = await tree.ancestorsOf(q, tenantId);
+            return inheritedTenantRole(held, tenantId, ancestors.map((a) => a.tenantId), options);
+        },
+    };
+    return tree;
+}
+//# sourceMappingURL=tree.js.map

package/dist/hierarchy/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/hierarchy/tree.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { TenantContext, createTenantContext, getCurrentTenant, resolveTenant, }
 export * from './middleware/index.js';
 export { listTenants, getTenantById, getTenantBySlug, getTenantByPrimaryDomain, createTenant, updateTenant, setTenantStatus, isUniqueViolation as isTenantUniqueViolation, } from './crud/index.js';
 export type { TenantRecord, TenantWriteFields, TenantStatus as TenantDbStatus, } from './crud/index.js';
+export * from './hierarchy/index.js';
 export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, planCascade, executeCascade, planUserErasure, executeUserErasure, exportUserData, } from './lifecycle/index.js';
 export type { TenantLifecycleStatus, LifecycleArgs, LifecycleOperationArgs, HardDeleteArgs, LifecycleAuditEvent, LifecycleAuditSink, CascadePlanEntry, CascadeOptions, CascadeResult, UserDataOptions, UserDataExport, } from './lifecycle/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAG5B,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,iBAAiB,IAAI,uBAAuB,GAC7C,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,YAAY,EACZ,iBAAiB,EAGjB,YAAY,IAAI,cAAc,GAC/B,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAG5B,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,iBAAiB,IAAI,uBAAuB,GAC7C,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,YAAY,EACZ,iBAAiB,EAGjB,YAAY,IAAI,cAAc,GAC/B,MAAM,iBAAiB,CAAC;AAMzB,cAAc,sBAAsB,CAAC;AASrC,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -15,6 +15,11 @@ export { createTenantContext, getCurrentTenant, resolveTenant, } from './context
 export * from './middleware/index.js';
 // Bare vk_tenants CRUD (column-agnostic create / read / update)
 export { listTenants, getTenantById, getTenantBySlug, getTenantByPrimaryDomain, createTenant, updateTenant, setTenantStatus, isUniqueViolation as isTenantUniqueViolation, } from './crud/index.js';
+// Hierarchy: the tree in the store (`createTenantTree` — `vk_tenants.parent_id` +
+// `vk_tenant_closure`, or a projection's own pair) and the rules over it (a role in a
+// parent tenant, held in its descendants: `inheritedTenantRole` for a request naming
+// another tenant, `reachableTenants` for a session's tenant switcher)
+export * from './hierarchy/index.js';
 // Role → scopes mapping lives in @venturekit/auth (vk_role_scopes +
 // createRoleScopesResolver) — baseline authorization, useful without
 // tenancy. The scopes middleware consumes it through the structural

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,UAAU;AACV,OAAO,EAEL,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,gEAAgE;AAChE,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,iBAAiB,IAAI,uBAAuB,GAC7C,MAAM,iBAAiB,CAAC;AASzB,oEAAoE;AACpE,qEAAqE;AACrE,oEAAoE;AACpE,gEAAgE;AAEhE,yEAAyE;AACzE,6BAA6B;AAC7B,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,UAAU;AACV,OAAO,EAEL,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAE5B,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,gEAAgE;AAChE,OAAO,EACL,WAAW,EACX,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,iBAAiB,IAAI,uBAAuB,GAC7C,MAAM,iBAAiB,CAAC;AASzB,kFAAkF;AAClF,sFAAsF;AACtF,qFAAqF;AACrF,sEAAsE;AACtE,cAAc,sBAAsB,CAAC;AAErC,oEAAoE;AACpE,qEAAqE;AACrE,oEAAoE;AACpE,gEAAgE;AAEhE,yEAAyE;AACzE,6BAA6B;AAC7B,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,sBAAsB,CAAC"}

package/dist/migrations/0000_vk_tenancy_tree.sql

@@ -0,0 +1,44 @@
+-- @venturekit-pro/tenancy — the tenant tree.
+--
+-- Multi-tenant products grow hierarchies: a group and its schools, a franchise
+-- and its stores, an agency and its clients' workspaces. Two structures carry it:
+--
+--   - `vk_tenants.parent_id` — the edge, one per tenant, NULL at a root.
+--   - `vk_tenant_closure`   — every ancestor→descendant path, the self-row at
+--     depth 0 included, so "the tenants under X" and "the ancestors of Y" are one
+--     indexed read each rather than a recursive walk per request.
+--
+-- The closure is maintained in CODE (`createTenantTree().setParent` /
+-- `rebuildClosure`), wholesale for the re-parented tenant's whole subtree —
+-- small, shallow graphs, and wholesale is easier to prove right than incremental
+-- edits. No trigger: a rule in a trigger runs where tests do not look.
+--
+-- Named to sort right after `0000_vk_tenancy_tenants.sql` and before any
+-- project migration, so a project's own backfill (copying a parent column of
+-- its overlay table into `parent_id`, say) can rely on both structures.
+
+ALTER TABLE vk_tenants
+  ADD COLUMN IF NOT EXISTS parent_id uuid REFERENCES vk_tenants (id) ON DELETE RESTRICT;
+
+-- a tenant is never its own parent; deeper cycles are refused in code (`setParent`)
+ALTER TABLE vk_tenants
+  DROP CONSTRAINT IF EXISTS vk_tenants_no_self_parent;
+ALTER TABLE vk_tenants
+  ADD CONSTRAINT vk_tenants_no_self_parent CHECK (parent_id IS NULL OR parent_id <> id);
+
+CREATE INDEX IF NOT EXISTS vk_tenants_parent_idx ON vk_tenants (parent_id) WHERE parent_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS vk_tenant_closure (
+  ancestor_id   uuid    NOT NULL REFERENCES vk_tenants (id) ON DELETE CASCADE,
+  descendant_id uuid    NOT NULL REFERENCES vk_tenants (id) ON DELETE CASCADE,
+  -- 0 is the tenant itself; a child is 1
+  depth         integer NOT NULL CHECK (depth >= 0),
+  PRIMARY KEY (ancestor_id, descendant_id)
+);
+
+CREATE INDEX IF NOT EXISTS vk_tenant_closure_descendant_idx ON vk_tenant_closure (descendant_id);
+
+-- every existing tenant is a root until told otherwise: its self-row
+INSERT INTO vk_tenant_closure (ancestor_id, descendant_id, depth)
+SELECT id, id, 0 FROM vk_tenants
+ON CONFLICT DO NOTHING;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit-pro/tenancy",
-  "version": "0.0.39",
+  "version": "0.0.41",
   "description": "Multi-tenant utilities for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,11 +30,11 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.39"
+    "@venturekit/core": "0.0.41"
   },
   "peerDependencies": {
-    "@venturekit/data": "0.0.39",
-    "@venturekit/runtime": "0.0.39"
+    "@venturekit/data": "0.0.41",
+    "@venturekit/runtime": "0.0.41"
   },
   "peerDependenciesMeta": {
     "@venturekit/data": {
@@ -46,8 +46,8 @@
   },
   "devDependencies": {
     "@types/node": "^26.5.1",
-    "@venturekit/data": "0.0.39",
-    "@venturekit/runtime": "0.0.39",
+    "@venturekit/data": "0.0.41",
+    "@venturekit/runtime": "0.0.41",
     "typescript": "^5.3.0"
   },
   "scripts": {

package/src/migrations/0000_vk_tenancy_tree.sql

@@ -0,0 +1,44 @@
+-- @venturekit-pro/tenancy — the tenant tree.
+--
+-- Multi-tenant products grow hierarchies: a group and its schools, a franchise
+-- and its stores, an agency and its clients' workspaces. Two structures carry it:
+--
+--   - `vk_tenants.parent_id` — the edge, one per tenant, NULL at a root.
+--   - `vk_tenant_closure`   — every ancestor→descendant path, the self-row at
+--     depth 0 included, so "the tenants under X" and "the ancestors of Y" are one
+--     indexed read each rather than a recursive walk per request.
+--
+-- The closure is maintained in CODE (`createTenantTree().setParent` /
+-- `rebuildClosure`), wholesale for the re-parented tenant's whole subtree —
+-- small, shallow graphs, and wholesale is easier to prove right than incremental
+-- edits. No trigger: a rule in a trigger runs where tests do not look.
+--
+-- Named to sort right after `0000_vk_tenancy_tenants.sql` and before any
+-- project migration, so a project's own backfill (copying a parent column of
+-- its overlay table into `parent_id`, say) can rely on both structures.
+
+ALTER TABLE vk_tenants
+  ADD COLUMN IF NOT EXISTS parent_id uuid REFERENCES vk_tenants (id) ON DELETE RESTRICT;
+
+-- a tenant is never its own parent; deeper cycles are refused in code (`setParent`)
+ALTER TABLE vk_tenants
+  DROP CONSTRAINT IF EXISTS vk_tenants_no_self_parent;
+ALTER TABLE vk_tenants
+  ADD CONSTRAINT vk_tenants_no_self_parent CHECK (parent_id IS NULL OR parent_id <> id);
+
+CREATE INDEX IF NOT EXISTS vk_tenants_parent_idx ON vk_tenants (parent_id) WHERE parent_id IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS vk_tenant_closure (
+  ancestor_id   uuid    NOT NULL REFERENCES vk_tenants (id) ON DELETE CASCADE,
+  descendant_id uuid    NOT NULL REFERENCES vk_tenants (id) ON DELETE CASCADE,
+  -- 0 is the tenant itself; a child is 1
+  depth         integer NOT NULL CHECK (depth >= 0),
+  PRIMARY KEY (ancestor_id, descendant_id)
+);
+
+CREATE INDEX IF NOT EXISTS vk_tenant_closure_descendant_idx ON vk_tenant_closure (descendant_id);
+
+-- every existing tenant is a root until told otherwise: its self-row
+INSERT INTO vk_tenant_closure (ancestor_id, descendant_id, depth)
+SELECT id, id, 0 FROM vk_tenants
+ON CONFLICT DO NOTHING;