@venturekit-pro/tenancy 0.0.0-dev.20260525024212 → 0.0.0-dev.20260602193331

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 /**
  * @venturekit-pro/tenancy
  *
- * Multi-tenant utilities for VentureKit.
+ * Multi-tenant utilities for VentureKit — context resolution,
+ * middleware, and tenant-lifecycle operations (suspend / archive /
+ * restore / hard-delete with auto-discovered FK-safe cascade).
+ *
  * Documentation: https://venturekit.dev
  */
 export * from './types/index.js';
 export { TenantContext, createTenantContext, getCurrentTenant, resolveTenant, } from './context/index.js';
 export * from './middleware/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';
 //# 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;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,GACd,MAAM,oBAAoB,CAAC;AAG5B,cAAc,uBAAuB,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,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"}

package/dist/index.js

@@ -1,7 +1,10 @@
 /**
  * @venturekit-pro/tenancy
  *
- * Multi-tenant utilities for VentureKit.
+ * Multi-tenant utilities for VentureKit — context resolution,
+ * middleware, and tenant-lifecycle operations (suspend / archive /
+ * restore / hard-delete with auto-discovered FK-safe cascade).
+ *
  * Documentation: https://venturekit.dev
  */
 // Types
@@ -10,4 +13,6 @@ export * from './types/index.js';
 export { createTenantContext, getCurrentTenant, resolveTenant, } from './context/index.js';
 // Middleware
 export * from './middleware/index.js';
+// Lifecycle (suspend / archive / restore / hard-delete + cascade walker)
+export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, planCascade, executeCascade, } 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;;;;;GAKG;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"}
+{"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,yEAAyE;AACzE,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,sBAAsB,CAAC"}

package/dist/lifecycle/cascade.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Cascade walker — finds every table in a schema with a `tenant_id`
+ * column and topologically deletes rows for one tenant, leaf tables
+ * first.
+ *
+ * Why introspect rather than enumerate?
+ *
+ *   Schemas evolve every release. Hard-coding a tenant-cascade list
+ *   guarantees it drifts. Introspecting against `information_schema`
+ *   means the walker stays correct as the app adds tables, and the
+ *   only invariant the app needs to maintain is "tenant-scoped
+ *   tables have a `tenant_id` column".
+ *
+ * Topological ordering:
+ *
+ *   The walker queries `pg_catalog` to build a directed graph of
+ *   foreign-key dependencies between the tenant-scoped tables, then
+ *   deletes leaves first so it never fights an FK constraint. Tables
+ *   that have a self-referential FK loop are detected and surfaced
+ *   as an error — the app must add the table to `skipTables` and
+ *   handle that case explicitly.
+ *
+ * Soft delete vs. hard delete:
+ *
+ *   - `suspendTenant` / `archiveTenant` only mutate `tenants.status`.
+ *     Children stay intact, ready for restore.
+ *   - `hardDeleteTenant` runs the cascade. Irreversible.
+ *
+ *   `tenants.status = 'archived'` is the public "this is going away"
+ *   signal. Operators typically wait 30-90 days before invoking the
+ *   hard delete; the package doesn't enforce that delay (compliance
+ *   regimes vary), but it's the recommended pattern.
+ */
+import type { Querier } from './types.js';
+export interface CascadePlanEntry {
+    /** Schema-qualified table name (`public.blog_posts`). */
+    tableName: string;
+    /** Topological depth — 0 = leaf (deleted first). */
+    depth: number;
+    /** Tables this table has FKs to among the tenant-scoped set. */
+    dependsOn: string[];
+}
+export interface CascadeResult {
+    /** Plan that was executed, in deletion order. */
+    plan: CascadePlanEntry[];
+    /** Per-table row counts deleted. */
+    counts: Record<string, number>;
+    /** Total wall-clock milliseconds. */
+    durationMs: number;
+}
+export interface CascadeOptions {
+    tenantId: string;
+    /**
+     * Schema to introspect. Defaults to `public` — the only schema
+     * most VentureKit apps use.
+     */
+    schema?: string;
+    /**
+     * Tables to skip even when they have a `tenant_id` column.
+     * Typical uses:
+     *   - Cross-tenant audit / billing tables where DELETE is REVOKE'd.
+     *   - The `tenants` table itself (handled separately at the end).
+     *   - Tables with self-referential FK cycles that need manual
+     *     handling.
+     *
+     * `tenants` is always implicitly skipped — the walker deletes the
+     * row at the end as a final step.
+     */
+    skipTables?: string[];
+}
+/**
+ * Plan the cascade WITHOUT executing it. Useful for dry-runs in the
+ * admin UI ("about to delete N rows from M tables — confirm?").
+ *
+ * The plan is deterministic given (schema, skipTables): re-running
+ * it returns the same order. Tables with a self-FK cycle inside the
+ * tenant-scoped set fail loud with a clear error.
+ */
+export declare function planCascade(querier: Querier, options?: Pick<CascadeOptions, 'schema' | 'skipTables'>): Promise<CascadePlanEntry[]>;
+/**
+ * Execute the cascade. Deletes rows for one tenant from every
+ * `tenant_id`-bearing table in `schema`, leaves first; finally
+ * deletes the row from `tenants` itself.
+ *
+ * **Destructive.** Caller must have DELETE privileges on every
+ * involved table. Apps typically wire this to a dedicated cron
+ * Lambda running under a privileged maintenance role.
+ *
+ * Transaction semantics:
+ *   - Each table's delete runs in its own transaction by default,
+ *     so a failure mid-cascade leaves the DB in a partially-cleaned
+ *     state (re-running the cascade is idempotent — rows already
+ *     deleted simply don't match the WHERE).
+ *   - Apps that want all-or-nothing semantics wrap the call in
+ *     their own `withTransaction()` and pass a transaction-bound
+ *     querier in.
+ */
+export declare function executeCascade(querier: Querier, options: CascadeOptions): Promise<CascadeResult>;
+//# sourceMappingURL=cascade.d.ts.map

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

@@ -0,0 +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"}

package/dist/lifecycle/cascade.js

@@ -0,0 +1,174 @@
+/**
+ * Cascade walker — finds every table in a schema with a `tenant_id`
+ * column and topologically deletes rows for one tenant, leaf tables
+ * first.
+ *
+ * Why introspect rather than enumerate?
+ *
+ *   Schemas evolve every release. Hard-coding a tenant-cascade list
+ *   guarantees it drifts. Introspecting against `information_schema`
+ *   means the walker stays correct as the app adds tables, and the
+ *   only invariant the app needs to maintain is "tenant-scoped
+ *   tables have a `tenant_id` column".
+ *
+ * Topological ordering:
+ *
+ *   The walker queries `pg_catalog` to build a directed graph of
+ *   foreign-key dependencies between the tenant-scoped tables, then
+ *   deletes leaves first so it never fights an FK constraint. Tables
+ *   that have a self-referential FK loop are detected and surfaced
+ *   as an error — the app must add the table to `skipTables` and
+ *   handle that case explicitly.
+ *
+ * Soft delete vs. hard delete:
+ *
+ *   - `suspendTenant` / `archiveTenant` only mutate `tenants.status`.
+ *     Children stay intact, ready for restore.
+ *   - `hardDeleteTenant` runs the cascade. Irreversible.
+ *
+ *   `tenants.status = 'archived'` is the public "this is going away"
+ *   signal. Operators typically wait 30-90 days before invoking the
+ *   hard delete; the package doesn't enforce that delay (compliance
+ *   regimes vary), but it's the recommended pattern.
+ */
+/**
+ * Plan the cascade WITHOUT executing it. Useful for dry-runs in the
+ * admin UI ("about to delete N rows from M tables — confirm?").
+ *
+ * The plan is deterministic given (schema, skipTables): re-running
+ * it returns the same order. Tables with a self-FK cycle inside the
+ * tenant-scoped set fail loud with a clear error.
+ */
+export async function planCascade(querier, options = {}) {
+    const schema = options.schema ?? 'public';
+    const skip = new Set([
+        // `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.
+        'tenants',
+        ...(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]);
+    const tenantTables = new Set(tables.map((t) => t.table_name).filter((name) => !skip.has(name)));
+    if (tenantTables.size === 0)
+        return [];
+    const fkEdges = await querier(`SELECT
+       cl.relname  AS "child_table",
+       pl.relname  AS "parent_table"
+     FROM pg_constraint c
+     JOIN pg_class cl ON cl.oid = c.conrelid
+     JOIN pg_class pl ON pl.oid = c.confrelid
+     JOIN pg_namespace n_child  ON n_child.oid  = cl.relnamespace
+     JOIN pg_namespace n_parent ON n_parent.oid = pl.relnamespace
+     WHERE c.contype = 'f'
+       AND n_child.nspname  = $1
+       AND n_parent.nspname = $1`, [schema]);
+    // Build two views of the FK graph:
+    //   - `parentToChildren` drives the topological walk. A "leaf" we can
+    //     safely delete first is a table with *no remaining children* (no
+    //     other tenant-scoped table holds an FK pointing at it).
+    //   - `dependsOn` is a static snapshot of each table's outgoing FK
+    //     targets, surfaced verbatim in the plan output.
+    //
+    // Inverting `parentToChildren` (rather than working from a `child →
+    // parents` map) matters here because deletion order is opposite to
+    // declaration order: rows in a *child* table must be removed before
+    // the *parent* row they reference, or the FK constraint fires.
+    const parentToChildren = new Map();
+    const dependsOnSets = new Map();
+    for (const t of tenantTables) {
+        parentToChildren.set(t, new Set());
+        dependsOnSets.set(t, new Set());
+    }
+    for (const edge of fkEdges) {
+        if (tenantTables.has(edge.child_table) &&
+            tenantTables.has(edge.parent_table) &&
+            edge.child_table !== edge.parent_table) {
+            parentToChildren.get(edge.parent_table).add(edge.child_table);
+            // Sets dedupe the (rare) case of two FK columns on the same
+            // table pointing to the same parent (e.g. created_by + updated_by
+            // → users).
+            dependsOnSets.get(edge.child_table).add(edge.parent_table);
+        }
+    }
+    const dependsOn = new Map();
+    for (const [t, set] of dependsOnSets) {
+        dependsOn.set(t, Array.from(set).sort());
+    }
+    // Topological sort: pick tables that no other tenant-scoped table
+    // depends on (leaves — deleted first), record their depth, remove
+    // them from the graph, repeat.
+    const plan = [];
+    let depth = 0;
+    while (parentToChildren.size > 0) {
+        const leaves = [];
+        for (const [table, children] of parentToChildren) {
+            if (children.size === 0)
+                leaves.push(table);
+        }
+        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(', ')}]. ` +
+                `Add the offending tables to skipTables and delete them manually.`);
+        }
+        leaves.sort(); // deterministic order within a depth level
+        for (const t of leaves) {
+            plan.push({
+                tableName: `${schema}.${t}`,
+                depth,
+                dependsOn: dependsOn.get(t),
+            });
+            parentToChildren.delete(t);
+        }
+        // Strip the deleted leaves from every remaining table's children set.
+        for (const children of parentToChildren.values()) {
+            for (const leaf of leaves)
+                children.delete(leaf);
+        }
+        depth++;
+    }
+    return plan;
+}
+/**
+ * Execute the cascade. Deletes rows for one tenant from every
+ * `tenant_id`-bearing table in `schema`, leaves first; finally
+ * deletes the row from `tenants` itself.
+ *
+ * **Destructive.** Caller must have DELETE privileges on every
+ * involved table. Apps typically wire this to a dedicated cron
+ * Lambda running under a privileged maintenance role.
+ *
+ * Transaction semantics:
+ *   - Each table's delete runs in its own transaction by default,
+ *     so a failure mid-cascade leaves the DB in a partially-cleaned
+ *     state (re-running the cascade is idempotent — rows already
+ *     deleted simply don't match the WHERE).
+ *   - Apps that want all-or-nothing semantics wrap the call in
+ *     their own `withTransaction()` and pass a transaction-bound
+ *     querier in.
+ */
+export async function executeCascade(querier, options) {
+    const startedAt = Date.now();
+    const schema = options.schema ?? 'public';
+    const plan = await planCascade(querier, options);
+    const counts = {};
+    for (const entry of plan) {
+        // Use the schema-qualified name verbatim (it came from
+        // information_schema, no injection risk).
+        const rows = await querier(`DELETE FROM ${entry.tableName} WHERE tenant_id = $1 RETURNING 1 AS id`, [options.tenantId]);
+        counts[entry.tableName] = rows.length;
+    }
+    // Finally, delete the tenants row itself.
+    const tenantsTable = `${schema}.tenants`;
+    const rows = await querier(`DELETE FROM ${tenantsTable} WHERE id = $1 RETURNING 1 AS id`, [options.tenantId]);
+    counts[tenantsTable] = rows.length;
+    return {
+        plan,
+        counts,
+        durationMs: Date.now() - startedAt,
+    };
+}
+//# sourceMappingURL=cascade.js.map

package/dist/lifecycle/cascade.js.map

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

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tenant-lifecycle operations.
+ *
+ *   - `suspendTenant`     — soft, reversible.
+ *   - `archiveTenant`     — soft, reversible, hides from active UIs.
+ *   - `restoreTenant`     — flips back to `active`.
+ *   - `hardDeleteTenant`  — runs the cascade walker. Irreversible.
+ *
+ * Plus the cascade walker primitives for apps that want finer control:
+ *
+ *   - `planCascade(querier, opts)`    — preview the deletion plan.
+ *   - `executeCascade(querier, opts)` — run the cascade without
+ *                                       touching the `tenants` row
+ *                                       (called internally by
+ *                                       `hardDeleteTenant`).
+ */
+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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/lifecycle/index.js

@@ -0,0 +1,19 @@
+/**
+ * Tenant-lifecycle operations.
+ *
+ *   - `suspendTenant`     — soft, reversible.
+ *   - `archiveTenant`     — soft, reversible, hides from active UIs.
+ *   - `restoreTenant`     — flips back to `active`.
+ *   - `hardDeleteTenant`  — runs the cascade walker. Irreversible.
+ *
+ * Plus the cascade walker primitives for apps that want finer control:
+ *
+ *   - `planCascade(querier, opts)`    — preview the deletion plan.
+ *   - `executeCascade(querier, opts)` — run the cascade without
+ *                                       touching the `tenants` row
+ *                                       (called internally by
+ *                                       `hardDeleteTenant`).
+ */
+export { suspendTenant, archiveTenant, restoreTenant, hardDeleteTenant, } from './operations.js';
+export { planCascade, executeCascade, } from './cascade.js';
+//# sourceMappingURL=index.js.map

package/dist/lifecycle/index.js.map

@@ -0,0 +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"}

package/dist/lifecycle/operations.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Tenant-lifecycle operations.
+ *
+ *   - `suspendTenant`    — `status = 'suspended'`, reversible.
+ *   - `archiveTenant`    — `status = 'archived'`,  reversible (data
+ *                          still present, just hidden from active
+ *                          UIs).
+ *   - `restoreTenant`    — `status = 'active'`, reverses suspend or
+ *                          archive.
+ *   - `hardDeleteTenant` — runs the cascade walker + drops the
+ *                          `tenants` row. **Irreversible.**
+ *
+ * The package mutates `tenants.status` plus, optionally, a metadata
+ * column. It does NOT touch any other table — application children
+ * are left intact for the reversible operations, and only the
+ * cascade walker touches them for the hard-delete path.
+ *
+ * Audit hook:
+ *   - Every operation calls the supplied `audit` callback after
+ *     mutating the DB. Apps wire this to `@venturekit-pro/audit`'s
+ *     `record()` (or whatever audit sink they use).
+ *   - The hook receives a typed event — see `types.ts` for the
+ *     shape.
+ */
+import { type CascadeResult } from './cascade.js';
+import type { LifecycleArgs, LifecycleAuditSink, Querier } from './types.js';
+export interface LifecycleOperationArgs extends LifecycleArgs {
+    /** Optional audit sink invoked once per operation. */
+    audit?: LifecycleAuditSink;
+}
+export interface HardDeleteArgs extends LifecycleOperationArgs {
+    /** Schema to operate against. Default `public`. */
+    schema?: string;
+    /** Tables to exclude from the cascade (`tenants` is always implicit). */
+    skipTables?: string[];
+}
+/**
+ * Mark a tenant as `suspended`. Reversible via `restoreTenant`.
+ *
+ * Application code should refuse to serve requests for suspended
+ * tenants — typically a check in the tenancy middleware:
+ *   `if (tenant.status === 'suspended') throw 403`.
+ */
+export declare function suspendTenant(querier: Querier, args: LifecycleOperationArgs): Promise<void>;
+/**
+ * Mark a tenant as `archived`. Same reversibility as suspend; the
+ * intent is "this tenant is going away soon" so admin UIs hide it
+ * but data is preserved for compliance + potential restore.
+ */
+export declare function archiveTenant(querier: Querier, args: LifecycleOperationArgs): Promise<void>;
+/**
+ * Flip a `suspended` / `archived` tenant back to `active`.
+ */
+export declare function restoreTenant(querier: Querier, args: LifecycleOperationArgs): Promise<void>;
+/**
+ * Run the cascade walker + drop the `tenants` row. Irreversible.
+ *
+ * Caller must have DELETE privileges on every tenant-scoped table.
+ * Apps typically wire this to a dedicated cron Lambda running under
+ * a privileged maintenance role.
+ *
+ * Audit event includes the per-table row-deletion counts so the
+ * compliance log knows exactly what disappeared.
+ */
+export declare function hardDeleteTenant(querier: Querier, args: HardDeleteArgs): Promise<CascadeResult>;
+//# sourceMappingURL=operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/lifecycle/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EAClB,OAAO,EAER,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,sDAAsD;IACtD,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,cAAe,SAAQ,sBAAsB;IAC5D,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAID;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAID;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAUf;AAID;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,aAAa,CAAC,CAgBxB"}

package/dist/lifecycle/operations.js

@@ -0,0 +1,138 @@
+/**
+ * Tenant-lifecycle operations.
+ *
+ *   - `suspendTenant`    — `status = 'suspended'`, reversible.
+ *   - `archiveTenant`    — `status = 'archived'`,  reversible (data
+ *                          still present, just hidden from active
+ *                          UIs).
+ *   - `restoreTenant`    — `status = 'active'`, reverses suspend or
+ *                          archive.
+ *   - `hardDeleteTenant` — runs the cascade walker + drops the
+ *                          `tenants` row. **Irreversible.**
+ *
+ * The package mutates `tenants.status` plus, optionally, a metadata
+ * column. It does NOT touch any other table — application children
+ * are left intact for the reversible operations, and only the
+ * cascade walker touches them for the hard-delete path.
+ *
+ * Audit hook:
+ *   - Every operation calls the supplied `audit` callback after
+ *     mutating the DB. Apps wire this to `@venturekit-pro/audit`'s
+ *     `record()` (or whatever audit sink they use).
+ *   - The hook receives a typed event — see `types.ts` for the
+ *     shape.
+ */
+import { executeCascade } from './cascade.js';
+// ─── suspend ───────────────────────────────────────────────────────────
+/**
+ * Mark a tenant as `suspended`. Reversible via `restoreTenant`.
+ *
+ * Application code should refuse to serve requests for suspended
+ * tenants — typically a check in the tenancy middleware:
+ *   `if (tenant.status === 'suspended') throw 403`.
+ */
+export async function suspendTenant(querier, args) {
+    await mutateStatus(querier, args.tenantId, 'suspended', args.reason);
+    await emit(args.audit, {
+        kind: 'tenant.lifecycle',
+        action: 'suspend',
+        tenantId: args.tenantId,
+        actorUserId: args.actorUserId,
+        reason: args.reason,
+        occurredAt: new Date().toISOString(),
+    });
+}
+// ─── archive ──────────────────────────────────────────────────────────
+/**
+ * Mark a tenant as `archived`. Same reversibility as suspend; the
+ * intent is "this tenant is going away soon" so admin UIs hide it
+ * but data is preserved for compliance + potential restore.
+ */
+export async function archiveTenant(querier, args) {
+    await mutateStatus(querier, args.tenantId, 'archived', args.reason);
+    await emit(args.audit, {
+        kind: 'tenant.lifecycle',
+        action: 'archive',
+        tenantId: args.tenantId,
+        actorUserId: args.actorUserId,
+        reason: args.reason,
+        occurredAt: new Date().toISOString(),
+    });
+}
+// ─── restore ──────────────────────────────────────────────────────────
+/**
+ * Flip a `suspended` / `archived` tenant back to `active`.
+ */
+export async function restoreTenant(querier, args) {
+    await mutateStatus(querier, args.tenantId, 'active', args.reason);
+    await emit(args.audit, {
+        kind: 'tenant.lifecycle',
+        action: 'restore',
+        tenantId: args.tenantId,
+        actorUserId: args.actorUserId,
+        reason: args.reason,
+        occurredAt: new Date().toISOString(),
+    });
+}
+// ─── hard delete ──────────────────────────────────────────────────────
+/**
+ * Run the cascade walker + drop the `tenants` row. Irreversible.
+ *
+ * Caller must have DELETE privileges on every tenant-scoped table.
+ * Apps typically wire this to a dedicated cron Lambda running under
+ * a privileged maintenance role.
+ *
+ * Audit event includes the per-table row-deletion counts so the
+ * compliance log knows exactly what disappeared.
+ */
+export async function hardDeleteTenant(querier, args) {
+    const result = await executeCascade(querier, {
+        tenantId: args.tenantId,
+        schema: args.schema,
+        skipTables: args.skipTables,
+    });
+    await emit(args.audit, {
+        kind: 'tenant.lifecycle',
+        action: 'hard_delete',
+        tenantId: args.tenantId,
+        actorUserId: args.actorUserId,
+        reason: args.reason,
+        cascadeCounts: result.counts,
+        occurredAt: new Date().toISOString(),
+    });
+    return result;
+}
+// ─── Internal helpers ─────────────────────────────────────────────────
+async function mutateStatus(querier, tenantId, status, reason) {
+    // We update `status` directly. Reason flows into the optional
+    // `metadata` jsonb column when present; we use jsonb_set so apps
+    // that don't have that column simply don't define it (no-op).
+    //
+    // The UPDATE is intentionally narrow: only the columns we own. Any
+    // app-side derived state (e.g. cached counters) is the app's
+    // responsibility to refresh.
+    if (reason !== undefined && reason !== null) {
+        await querier(`UPDATE tenants
+          SET status = $2,
+              metadata = jsonb_set(
+                COALESCE(metadata, '{}'::jsonb),
+                '{lifecycleReason}',
+                to_jsonb($3::text),
+                true
+              ),
+              updated_at = now()
+        WHERE id = $1`, [tenantId, status, reason]);
+    }
+    else {
+        await querier(`UPDATE tenants
+          SET status = $2,
+              updated_at = now()
+        WHERE id = $1`, [tenantId, status]);
+    }
+}
+async function emit(sink, event) {
+    if (!sink)
+        return;
+    await sink(event);
+}
+//# sourceMappingURL=operations.js.map

package/dist/lifecycle/operations.js.map

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

package/dist/lifecycle/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Types for tenant-lifecycle operations.
+ *
+ * `Querier` is structurally compatible with `@venturekit/data`'s
+ * `Querier` and `@venturekit-pro/audit`'s `Querier`. We re-declare
+ * it locally rather than peer-depend so the package builds in
+ * isolation and works with any caller's pg-like driver adapter.
+ */
+export type Querier = <T = Record<string, unknown>[]>(sql: string, params?: unknown[]) => Promise<T>;
+/** Lifecycle status this package mutates `tenants.status` between. */
+export type TenantLifecycleStatus = 'active' | 'suspended' | 'archived';
+export interface LifecycleArgs {
+    tenantId: string;
+    /** Optional Cognito sub of the operator — surfaced in the audit hook below. */
+    actorUserId?: string;
+    /** Optional reason — written to `tenants.metadata.lifecycleReason` when set. */
+    reason?: string;
+}
+/**
+ * Audit hook: called with one event per lifecycle action. Apps
+ * forward this to `@venturekit-pro/audit`'s `record()` (or their
+ * own log). Optional — when omitted, lifecycle ops happen silently.
+ */
+export interface LifecycleAuditEvent {
+    /** Always `'tenant.lifecycle'`. */
+    kind: 'tenant.lifecycle';
+    /** Which lifecycle action fired. */
+    action: 'suspend' | 'archive' | 'restore' | 'hard_delete';
+    tenantId: string;
+    actorUserId?: string;
+    reason?: string;
+    /** For hard delete: the table name → number of rows removed. */
+    cascadeCounts?: Record<string, number>;
+    occurredAt: string;
+}
+export type LifecycleAuditSink = (event: LifecycleAuditEvent) => void | Promise<void>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAClD,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,CAAC,CAAC,CAAC;AAEhB,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAC;AAExE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,oCAAoC;IACpC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/lifecycle/types.js

@@ -0,0 +1,10 @@
+/**
+ * Types for tenant-lifecycle operations.
+ *
+ * `Querier` is structurally compatible with `@venturekit/data`'s
+ * `Querier` and `@venturekit-pro/audit`'s `Querier`. We re-declare
+ * it locally rather than peer-depend so the package builds in
+ * isolation and works with any caller's pg-like driver adapter.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lifecycle/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/migrations/0000_vk_tenancy_tenants.sql

@@ -0,0 +1,105 @@
+-- @venturekit-pro/tenancy — primordial `tenants` table.
+--
+-- # Why the `0000_` filename prefix
+--
+-- VentureKit's migration runner merges all .sql files from the
+-- project + every installed `@venturekit/*` / `@venturekit-pro/*`
+-- package into a single directory, then applies them in alphabetic
+-- order. The CMS (and every other VK app) ships migrations starting
+-- at `0001_*`, and most pro packages use the `vk_<pkg>_<NNNN>_*`
+-- naming convention — both of which sort *after* this file.
+--
+-- This migration ships the table every other migration references
+-- (`tenant_id REFERENCES tenants(id)`), so it MUST run first. The
+-- `0000_` prefix is a one-character departure from the standard
+-- `vk_<pkg>_*` convention, justified by primordial-parent status.
+--
+-- # What lives here vs in app-specific tables
+--
+-- The lean shape below is *only* what every multi-tenant VK app
+-- needs:
+--   - identity (`id`, `slug`, `display_name`)
+--   - lifecycle (`status` + `archive_*` + `suspend_*`)
+--   - routing (`primary_domain`)
+--   - timestamps
+--
+-- App-specific overlays — branding, editorial cadence, retention
+-- policies, etc. — live in *their own* table 1:1 by `tenant_id`
+-- (see e.g. `tenant_cms_settings` shipped by `@venturekit-cms`).
+-- This split keeps `tenants` writable from any app's tenancy-admin
+-- flow without inter-app schema collisions.
+--
+-- # No `created_by` / `updated_by` here
+--
+-- Audit of *who* mutated the tenant lives in `audit_events`
+-- (`@venturekit-pro/audit`). Storing FK references to a per-app
+-- `users` table on the tenancy-owned row would create cross-package
+-- FK coupling and a chicken-egg problem (the first user is created
+-- *after* the tenant). The audit ledger answers the "who" question
+-- without that coupling.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── Tenant lifecycle status ───────────────────────────────────────
+-- Mirror of `@venturekit-pro/tenancy`'s `TenantStatus` TS type at
+-- `src/types/tenant.ts`. The two MUST stay in lockstep — the runtime
+-- middleware (`tenant-middleware.ts`) drives 403 / 410 / 503
+-- responses off this column.
+
+CREATE TYPE tenant_status AS ENUM (
+  'pending',     -- pre-provisioning, no users yet
+  'active',      -- normal operation
+  'suspended',   -- read-only or hard-locked (see `suspend_reason`)
+  'archived',    -- soft-deleted; rows retained for the retention
+                 -- window per the lifecycle cascade
+  'deleted'      -- final tombstone; cascade has run
+);
+
+-- ─── tenants ───────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS tenants (
+  id                uuid          PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- URL-safe identifier. Used for sub-domains, log lines, S3
+  -- prefixes (`<slug>/...`), and the tenant-routing middleware.
+  slug              varchar(64)   NOT NULL,
+  -- Human-readable label rendered in admin UIs / billing portals.
+  display_name      text          NOT NULL,
+  -- Lifecycle gate consulted by every authed request.
+  status            tenant_status NOT NULL DEFAULT 'pending',
+  -- The host the tenant is reachable at. The tenancy middleware
+  -- looks up by this when routing `Host:` headers. Unique because
+  -- one tenant per host.
+  primary_domain    varchar(255),
+  -- Set when status flipped to 'suspended'. Surfaced in the 503
+  -- response body so support can tell the operator why.
+  suspended_at      timestamptz,
+  suspend_reason    text,
+  -- Set when status flipped to 'archived'. The lifecycle cascade
+  -- uses this to compute the deletion countdown (retention window
+  -- is per-app, stored in the app's own settings table).
+  archived_at       timestamptz,
+  archive_reason    text,
+  -- Free-form metadata bag for the operator. App-specific overlays
+  -- should live in their own table (e.g. `tenant_cms_settings`),
+  -- not here.
+  metadata          jsonb         NOT NULL DEFAULT '{}'::jsonb,
+  created_at        timestamptz   NOT NULL DEFAULT now(),
+  updated_at        timestamptz   NOT NULL DEFAULT now()
+);
+
+-- ─── Indexes ───────────────────────────────────────────────────────
+
+-- Slug is the editor-friendly id used in log lines and S3 prefixes.
+-- Unique on lower(slug) so `Demo` and `demo` collide.
+CREATE UNIQUE INDEX IF NOT EXISTS tenants_slug_unique
+  ON tenants (lower(slug));
+
+-- Primary-domain lookup is the hot path for the tenancy middleware
+-- (one query per request before any business logic runs).
+CREATE UNIQUE INDEX IF NOT EXISTS tenants_primary_domain_unique
+  ON tenants (lower(primary_domain))
+  WHERE primary_domain IS NOT NULL;
+
+-- Status filter for admin "active tenants" dashboards.
+CREATE INDEX IF NOT EXISTS tenants_status_idx
+  ON tenants (status);

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@venturekit-pro/tenancy",
-  "version": "0.0.0-dev.20260525024212",
+  "version": "0.0.0-dev.20260602193331",
   "description": "Multi-tenant utilities for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "src/migrations/*.sql"
   ],
+  "vk": {
+    "migrations": "src/migrations"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/venturekit-dev/venturekit.private.git",
@@ -26,10 +30,10 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260525024212"
+    "@venturekit/core": "0.0.0-dev.20260602193331"
   },
   "peerDependencies": {
-    "@venturekit/runtime": "0.0.0-dev.20260525024212"
+    "@venturekit/runtime": "0.0.0-dev.20260602193331"
   },
   "peerDependenciesMeta": {
     "@venturekit/runtime": {
@@ -38,11 +42,11 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
-    "@venturekit/runtime": "0.0.0-dev.20260525024212",
+    "@venturekit/runtime": "0.0.0-dev.20260602193331",
     "typescript": "^5.3.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"require('fs').cpSync('src/migrations','dist/migrations',{recursive:true})\"",
     "dev": "tsc --watch",
     "clean": "rm -rf dist"
   }

package/src/migrations/0000_vk_tenancy_tenants.sql

@@ -0,0 +1,105 @@
+-- @venturekit-pro/tenancy — primordial `tenants` table.
+--
+-- # Why the `0000_` filename prefix
+--
+-- VentureKit's migration runner merges all .sql files from the
+-- project + every installed `@venturekit/*` / `@venturekit-pro/*`
+-- package into a single directory, then applies them in alphabetic
+-- order. The CMS (and every other VK app) ships migrations starting
+-- at `0001_*`, and most pro packages use the `vk_<pkg>_<NNNN>_*`
+-- naming convention — both of which sort *after* this file.
+--
+-- This migration ships the table every other migration references
+-- (`tenant_id REFERENCES tenants(id)`), so it MUST run first. The
+-- `0000_` prefix is a one-character departure from the standard
+-- `vk_<pkg>_*` convention, justified by primordial-parent status.
+--
+-- # What lives here vs in app-specific tables
+--
+-- The lean shape below is *only* what every multi-tenant VK app
+-- needs:
+--   - identity (`id`, `slug`, `display_name`)
+--   - lifecycle (`status` + `archive_*` + `suspend_*`)
+--   - routing (`primary_domain`)
+--   - timestamps
+--
+-- App-specific overlays — branding, editorial cadence, retention
+-- policies, etc. — live in *their own* table 1:1 by `tenant_id`
+-- (see e.g. `tenant_cms_settings` shipped by `@venturekit-cms`).
+-- This split keeps `tenants` writable from any app's tenancy-admin
+-- flow without inter-app schema collisions.
+--
+-- # No `created_by` / `updated_by` here
+--
+-- Audit of *who* mutated the tenant lives in `audit_events`
+-- (`@venturekit-pro/audit`). Storing FK references to a per-app
+-- `users` table on the tenancy-owned row would create cross-package
+-- FK coupling and a chicken-egg problem (the first user is created
+-- *after* the tenant). The audit ledger answers the "who" question
+-- without that coupling.
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- ─── Tenant lifecycle status ───────────────────────────────────────
+-- Mirror of `@venturekit-pro/tenancy`'s `TenantStatus` TS type at
+-- `src/types/tenant.ts`. The two MUST stay in lockstep — the runtime
+-- middleware (`tenant-middleware.ts`) drives 403 / 410 / 503
+-- responses off this column.
+
+CREATE TYPE tenant_status AS ENUM (
+  'pending',     -- pre-provisioning, no users yet
+  'active',      -- normal operation
+  'suspended',   -- read-only or hard-locked (see `suspend_reason`)
+  'archived',    -- soft-deleted; rows retained for the retention
+                 -- window per the lifecycle cascade
+  'deleted'      -- final tombstone; cascade has run
+);
+
+-- ─── tenants ───────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS tenants (
+  id                uuid          PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- URL-safe identifier. Used for sub-domains, log lines, S3
+  -- prefixes (`<slug>/...`), and the tenant-routing middleware.
+  slug              varchar(64)   NOT NULL,
+  -- Human-readable label rendered in admin UIs / billing portals.
+  display_name      text          NOT NULL,
+  -- Lifecycle gate consulted by every authed request.
+  status            tenant_status NOT NULL DEFAULT 'pending',
+  -- The host the tenant is reachable at. The tenancy middleware
+  -- looks up by this when routing `Host:` headers. Unique because
+  -- one tenant per host.
+  primary_domain    varchar(255),
+  -- Set when status flipped to 'suspended'. Surfaced in the 503
+  -- response body so support can tell the operator why.
+  suspended_at      timestamptz,
+  suspend_reason    text,
+  -- Set when status flipped to 'archived'. The lifecycle cascade
+  -- uses this to compute the deletion countdown (retention window
+  -- is per-app, stored in the app's own settings table).
+  archived_at       timestamptz,
+  archive_reason    text,
+  -- Free-form metadata bag for the operator. App-specific overlays
+  -- should live in their own table (e.g. `tenant_cms_settings`),
+  -- not here.
+  metadata          jsonb         NOT NULL DEFAULT '{}'::jsonb,
+  created_at        timestamptz   NOT NULL DEFAULT now(),
+  updated_at        timestamptz   NOT NULL DEFAULT now()
+);
+
+-- ─── Indexes ───────────────────────────────────────────────────────
+
+-- Slug is the editor-friendly id used in log lines and S3 prefixes.
+-- Unique on lower(slug) so `Demo` and `demo` collide.
+CREATE UNIQUE INDEX IF NOT EXISTS tenants_slug_unique
+  ON tenants (lower(slug));
+
+-- Primary-domain lookup is the hot path for the tenancy middleware
+-- (one query per request before any business logic runs).
+CREATE UNIQUE INDEX IF NOT EXISTS tenants_primary_domain_unique
+  ON tenants (lower(primary_domain))
+  WHERE primary_domain IS NOT NULL;
+
+-- Status filter for admin "active tenants" dashboards.
+CREATE INDEX IF NOT EXISTS tenants_status_idx
+  ON tenants (status);