@venturekit-pro/tenancy 0.0.38 → 0.0.40

package/README.md

@@ -77,6 +77,65 @@ 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
+per-user obligations (GDPR art. 17 / art. 20). Both key on the column that
+marks a row as the user's — `user_id` by default — and introspect the schema,
+so a new table is covered the day it is added.
+
+```typescript
+import { exportUserData, executeUserErasure, planUserErasure } from '@venturekit-pro/tenancy';
+
+// Portability: every row of the user, per table, ready to redact and hand over
+const dump = await exportUserData(query, { userId, skipTables: ['audit_events'] });
+
+// Erasure: dry-run first, then delete FK children before parents
+const plan = await planUserErasure(query, { column: 'member_id' });
+await withTransaction((tx) => executeUserErasure(tx.query, { userId, column: 'member_id', skipTables: ['audit_events'] }));
+// …then adminDeleteUser() from @venturekit/auth/server for the Cognito account.
+```
+
+Rows keyed by another column (`author_id`, `created_by`) need one call per
+column; tables in `skipTables` (an append-only ledger you must keep) are the
+ones to anonymise instead.
+
 ## API Reference
 
 See the [API reference](https://venturekit.dev/api-reference/tenancy) for full documentation.

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 { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, planCascade, executeCascade, } from './lifecycle/index.js';
-export type { TenantLifecycleStatus, LifecycleArgs, LifecycleOperationArgs, HardDeleteArgs, LifecycleAuditEvent, LifecycleAuditSink, CascadePlanEntry, CascadeOptions, CascadeResult, } from './lifecycle/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;AAQzB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,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,GACd,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,10 +15,16 @@ 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
 // `RoleScopesLookup` type (re-exported via ./middleware above).
-// Lifecycle (suspend / archive / restore / hard-delete + cascade walker)
-export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, planCascade, executeCascade, } from './lifecycle/index.js';
+// Lifecycle (suspend / archive / restore / hard-delete + cascade walker,
+// per-user erasure & export)
+export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, planCascade, executeCascade, planUserErasure, executeUserErasure, exportUserData, } from './lifecycle/index.js';
 //# sourceMappingURL=index.js.map

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,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,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/lifecycle/cascade.d.ts

@@ -96,4 +96,55 @@ export declare function planCascade(querier: Querier, options?: Pick<CascadeOpti
  *     querier in.
  */
 export declare function executeCascade(querier: Querier, options: CascadeOptions): Promise<CascadeResult>;
+export interface UserDataOptions {
+    /** The user's id as stored in `column` (a Cognito sub, a members.id, …). */
+    userId: string;
+    /**
+     * Column that marks a row as belonging to the user. Default `user_id`.
+     * Apps whose ownership column differs (`member_id`, `created_by`) name
+     * it here; call once per column if several apply.
+     */
+    column?: string;
+    /** Schema to introspect. Default `public`. */
+    schema?: string;
+    /**
+     * Tables to leave alone even though they carry the column — e.g. an
+     * append-only audit log the regime requires you to KEEP, or a billing
+     * ledger. For erasure these are the tables you anonymise instead.
+     */
+    skipTables?: string[];
+}
+export interface UserDataExport {
+    userId: string;
+    column: string;
+    /** Rows per schema-qualified table, in introspection order. */
+    tables: Record<string, Record<string, unknown>[]>;
+    /** Tables that were listed but skipped. */
+    skipped: string[];
+    exportedAt: string;
+}
+/**
+ * Plan a per-user erasure: every table in `schema` with `column`,
+ * children before parents. Same guarantees as {@link planCascade}.
+ */
+export declare function planUserErasure(querier: Querier, options?: Omit<UserDataOptions, 'userId'>): Promise<CascadePlanEntry[]>;
+/**
+ * Erase one user's rows from every `column`-bearing table, leaves first.
+ * The user's Cognito account and any row keyed by a DIFFERENT column
+ * (e.g. `author_id`) are the caller's responsibility — run this once per
+ * ownership column, then `adminDeleteUser`.
+ *
+ * **Destructive.** Wrap in `withTransaction()` and pass `tx.query` for
+ * all-or-nothing semantics; otherwise re-running is idempotent.
+ */
+export declare function executeUserErasure(querier: Querier, options: UserDataOptions): Promise<CascadeResult>;
+/**
+ * Export one user's rows from every `column`-bearing table — the raw
+ * material for a data-portability response. Rows come back as stored
+ * (`SELECT *`); the app decides which columns to redact (other people's
+ * identifiers, internal flags) before handing the file over.
+ *
+ * Read-only; safe to run against a replica.
+ */
+export declare function exportUserData(querier: Querier, options: UserDataOptions): Promise<UserDataExport>;
 //# sourceMappingURL=cascade.d.ts.map

package/dist/lifecycle/cascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/lifecycle/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAYD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,YAAY,CAAM,GAC1D,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2G7B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA8BxB"}
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/lifecycle/cascade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AA4BD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,YAAY,CAAM,GAC1D,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAS7B;AAmHD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAMD,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAClD,2CAA2C;IAC3C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAM,GAC5C,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAM7B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAiCzB"}

package/dist/lifecycle/cascade.js

@@ -31,6 +31,18 @@
  *   hard delete; the package doesn't enforce that delay (compliance
  *   regimes vary), but it's the recommended pattern.
  */
+/**
+ * The column a cascade / export keys on is interpolated into SQL (it is a
+ * schema identifier, not a value). Restrict it to plain unquoted
+ * identifiers so a caller can never smuggle anything else in.
+ */
+const SAFE_IDENTIFIER = /^[a-z_][a-z0-9_]{0,62}$/;
+function assertColumnName(column) {
+    if (!SAFE_IDENTIFIER.test(column)) {
+        throw new Error(`[tenancy/cascade] column must be a plain lowercase identifier (got ${JSON.stringify(column)})`);
+    }
+    return column;
+}
 /**
  * Plan the cascade WITHOUT executing it. Useful for dry-runs in the
  * admin UI ("about to delete N rows from M tables — confirm?").
@@ -40,18 +52,29 @@
  * tenant-scoped set fail loud with a clear error.
  */
 export async function planCascade(querier, options = {}) {
-    const schema = options.schema ?? 'public';
-    const skip = new Set([
+    return planColumnCascade(querier, {
+        column: 'tenant_id',
+        schema: options.schema,
         // `vk_tenants` is the root we're collapsing into; the helper deletes
         // it separately at the very end. Including it in the cascade
         // would cause a "depends on itself" cycle.
-        'vk_tenants',
-        ...(options.skipTables ?? []),
-    ]);
+        skipTables: ['vk_tenants', ...(options.skipTables ?? [])],
+    });
+}
+/**
+ * Shared walker: every table in `schema` with a column named `column`,
+ * ordered so that FK children come before their parents. `planCascade`
+ * (tenant erasure) and `planUserErasure` (per-user erasure) are both
+ * thin wrappers over it.
+ */
+async function planColumnCascade(querier, options) {
+    const schema = options.schema ?? 'public';
+    const column = assertColumnName(options.column);
+    const skip = new Set(options.skipTables ?? []);
     const tables = await querier(`SELECT table_schema AS "schema_name", table_name
        FROM information_schema.columns
       WHERE table_schema = $1
-        AND column_name  = 'tenant_id'`, [schema]);
+        AND column_name  = $2`, [schema, column]);
     const tenantTables = new Set(tables.map((t) => t.table_name).filter((name) => !skip.has(name)));
     if (tenantTables.size === 0)
         return [];
@@ -111,7 +134,7 @@ export async function planCascade(querier, options = {}) {
         }
         if (leaves.length === 0) {
             const remaining = Array.from(parentToChildren.keys()).sort();
-            throw new Error(`[tenancy/cascade] FK cycle detected among tenant-scoped tables: [${remaining.join(', ')}]. ` +
+            throw new Error(`[tenancy/cascade] FK cycle detected among ${column}-scoped tables: [${remaining.join(', ')}]. ` +
                 `Add the offending tables to skipTables and delete them manually.`);
         }
         leaves.sort(); // deterministic order within a depth level
@@ -171,4 +194,69 @@ export async function executeCascade(querier, options) {
         durationMs: Date.now() - startedAt,
     };
 }
+/**
+ * Plan a per-user erasure: every table in `schema` with `column`,
+ * children before parents. Same guarantees as {@link planCascade}.
+ */
+export async function planUserErasure(querier, options = {}) {
+    return planColumnCascade(querier, {
+        column: options.column ?? 'user_id',
+        schema: options.schema,
+        skipTables: options.skipTables,
+    });
+}
+/**
+ * Erase one user's rows from every `column`-bearing table, leaves first.
+ * The user's Cognito account and any row keyed by a DIFFERENT column
+ * (e.g. `author_id`) are the caller's responsibility — run this once per
+ * ownership column, then `adminDeleteUser`.
+ *
+ * **Destructive.** Wrap in `withTransaction()` and pass `tx.query` for
+ * all-or-nothing semantics; otherwise re-running is idempotent.
+ */
+export async function executeUserErasure(querier, options) {
+    const startedAt = Date.now();
+    const column = assertColumnName(options.column ?? 'user_id');
+    const plan = await planUserErasure(querier, { ...options, column });
+    const counts = {};
+    for (const entry of plan) {
+        const rows = await querier(`DELETE FROM ${entry.tableName} WHERE ${column} = $1 RETURNING 1 AS id`, [options.userId]);
+        counts[entry.tableName] = rows.length;
+    }
+    return { plan, counts, durationMs: Date.now() - startedAt };
+}
+/**
+ * Export one user's rows from every `column`-bearing table — the raw
+ * material for a data-portability response. Rows come back as stored
+ * (`SELECT *`); the app decides which columns to redact (other people's
+ * identifiers, internal flags) before handing the file over.
+ *
+ * Read-only; safe to run against a replica.
+ */
+export async function exportUserData(querier, options) {
+    const schema = options.schema ?? 'public';
+    const column = assertColumnName(options.column ?? 'user_id');
+    const skip = new Set(options.skipTables ?? []);
+    const tables = await querier(`SELECT table_schema AS "schema_name", table_name
+       FROM information_schema.columns
+      WHERE table_schema = $1
+        AND column_name  = $2
+      ORDER BY table_name`, [schema, column]);
+    const out = {
+        userId: options.userId,
+        column,
+        tables: {},
+        skipped: [],
+        exportedAt: new Date().toISOString(),
+    };
+    for (const t of tables) {
+        const qualified = `${schema}.${t.table_name}`;
+        if (skip.has(t.table_name)) {
+            out.skipped.push(qualified);
+            continue;
+        }
+        out.tables[qualified] = await querier(`SELECT * FROM ${qualified} WHERE ${column} = $1`, [options.userId]);
+    }
+    return out;
+}
 //# sourceMappingURL=cascade.js.map

package/dist/lifecycle/cascade.js.map

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

package/dist/lifecycle/index.d.ts

@@ -17,6 +17,6 @@
 export type { Querier, TenantLifecycleStatus, LifecycleArgs, LifecycleAuditEvent, LifecycleAuditSink, } from './types.js';
 export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, } from './operations.js';
 export type { LifecycleOperationArgs, HardDeleteArgs } from './operations.js';
-export { planCascade, executeCascade, } from './cascade.js';
-export type { CascadePlanEntry, CascadeOptions, CascadeResult, } from './cascade.js';
+export { planCascade, executeCascade, planUserErasure, executeUserErasure, exportUserData, } from './cascade.js';
+export type { CascadePlanEntry, CascadeOptions, CascadeResult, UserDataOptions, UserDataExport, } from './cascade.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EACV,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,GACd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EACV,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EACL,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/lifecycle/index.js

@@ -15,5 +15,5 @@
  *                                       `hardDeleteTenant`).
  */
 export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, } from './operations.js';
-export { planCascade, executeCascade, } from './cascade.js';
+export { planCascade, executeCascade, planUserErasure, executeUserErasure, exportUserData, } from './cascade.js';
 //# sourceMappingURL=index.js.map

package/dist/lifecycle/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,cAAc,GACf,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC"}

package/dist/middleware/runtime-tenant-middleware.d.ts

@@ -88,9 +88,17 @@ export interface HostPrefixDomainResolverOptions<T extends TenantContext> {
      */
     lookup: (domain: string, ctx: RequestContext) => Promise<T | null> | T | null;
     /**
-     * Dev-only overrides honored when `process.env.STAGE === 'dev'`.
-     * Lets `vk dev` serve tenanted routes from `localhost:3001` by
-     * accepting an explicit slug from a header or query param.
+     * Dev-only overrides honored when `process.env.VENTURE_LOCAL === 'true'`
+     * — the marker `vk dev` injects and nothing deployed ever carries
+     * (the same switch the repo's other dev-only surfaces key on). Lets
+     * `vk dev` serve tenanted routes from `localhost:3001` by accepting an
+     * explicit slug from a header or query param.
+     *
+     * Deliberately NOT keyed on a stage name: `dev` is a deployable stage,
+     * and a deployed API that let any caller pick the tenant with a header
+     * would be a cross-tenant read. (Historically this read `STAGE=dev`,
+     * which no deploy path set — the override was dead locally and one
+     * `STAGE=dev` env var away from live in the cloud.)
      *
      * Defaults: header `X-Tenant-Slug`, query `tenant`. Set to `false`
      * to disable.

package/dist/middleware/runtime-tenant-middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-tenant-middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/runtime-tenant-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIrF,MAAM,WAAW,qBAAqB;IACpC,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,aAAa,GAAG,IAAI,CAAC;CAC7E;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;OAOG;IACH,QAAQ,EAAE,qBAAqB,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,UAAU,CAAC,cAAc,CAAC,CAiB5B;AAED,MAAM,WAAW,+BAA+B,CAAC,CAAC,SAAS,aAAa;IACtE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAClC;;;;;;;OAOG;IACH,YAAY,CAAC,EACT,KAAK,GACL;QACE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;KACnC,CAAC;CACP;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,aAAa,EAC9D,OAAO,EAAE,+BAA+B,CAAC,CAAC,CAAC,GAC1C,qBAAqB,CAgCvB"}
+{"version":3,"file":"runtime-tenant-middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/runtime-tenant-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIrF,MAAM,WAAW,qBAAqB;IACpC,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,aAAa,GAAG,IAAI,CAAC;CAC7E;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;;;;OAOG;IACH,QAAQ,EAAE,qBAAqB,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,UAAU,CAAC,cAAc,CAAC,CAiB5B;AAED,MAAM,WAAW,+BAA+B,CAAC,CAAC,SAAS,aAAa;IACtE;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,MAAM,EAAE,CACN,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAClC;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EACT,KAAK,GACL;QACE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,CACZ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;KACnC,CAAC;CACP;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,aAAa,EAC9D,OAAO,EAAE,+BAA+B,CAAC,CAAC,CAAC,GAC1C,qBAAqB,CAgCvB"}

package/dist/middleware/runtime-tenant-middleware.js

@@ -58,7 +58,7 @@ export function hostPrefixDomainResolver(options) {
     const dev = options.devOverrides;
     return async (ctx) => {
         const headers = ctx.rawEvent.headers ?? {};
-        if (process.env.STAGE === 'dev' && dev !== false) {
+        if (process.env.VENTURE_LOCAL === 'true' && dev !== false) {
             const headerName = (dev?.headerName ?? 'x-tenant-slug').toLowerCase();
             const queryName = dev?.queryName ?? 'tenant';
             const headerValue = headers[headerName] ??

package/dist/middleware/runtime-tenant-middleware.js.map

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

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.38",
+  "version": "0.0.40",
   "description": "Multi-tenant utilities for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,11 +30,11 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.38"
+    "@venturekit/core": "0.0.40"
   },
   "peerDependencies": {
-    "@venturekit/data": "0.0.38",
-    "@venturekit/runtime": "0.0.38"
+    "@venturekit/data": "0.0.40",
+    "@venturekit/runtime": "0.0.40"
   },
   "peerDependenciesMeta": {
     "@venturekit/data": {
@@ -46,8 +46,8 @@
   },
   "devDependencies": {
     "@types/node": "^26.5.1",
-    "@venturekit/data": "0.0.38",
-    "@venturekit/runtime": "0.0.38",
+    "@venturekit/data": "0.0.40",
+    "@venturekit/runtime": "0.0.40",
     "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;