@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/adoption/plan.js

@@ -0,0 +1,192 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { adoptionTargets, qualifiedName } from "./target.js";
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+/** `"schema"."table"`, quoted for the SQL the CLI prints and runs. */
+export const quotedTable = (target) => `${identifier(target.schema)}.${identifier(target.table)}`;
+/** The index columns a scoped statement leads with: `routing_key` first when the runtime writes the table. */
+export const ownerIndexColumns = (target) => [
+    ...(target.access === "write" ? ["routing_key"] : []),
+    target.tenantColumn,
+    target.actorColumn,
+];
+/** The statement that adds an index leading with the mapped columns. */
+export const ownerIndexSql = (target) => `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${identifier(`${target.table}_durable_owner`)} ON ${quotedTable(target)} (${ownerIndexColumns(target).map(identifier).join(", ")})`;
+/**
+ * The problems that stop a table from being adopted as declared: it must
+ * exist, its mapped columns must exist, and they must be text, varchar, or uuid
+ * with a deterministic collation. Shared by `plan` and `observe`.
+ */
+export const mappingProblems = Effect.fnUntraced(function* (target) {
+    const sql = yield* SqlClient.SqlClient;
+    const exists = yield* sql `SELECT 1 FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = ${target.schema} AND c.relname = ${target.table} AND c.relkind IN ('r', 'p')`;
+    if (exists.length === 0)
+        return [`${qualifiedName(target)} does not exist`];
+    const columns = yield* sql `
+    SELECT a.attname AS name, t.typname AS type, co.collisdeterministic AS deterministic,
+      a.attnotnull AS not_null
+    FROM pg_attribute a
+    JOIN pg_class c ON c.oid = a.attrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_type t ON t.oid = a.atttypid
+    LEFT JOIN pg_collation co ON co.oid = a.attcollation AND a.attcollation <> 0
+    WHERE n.nspname = ${target.schema} AND c.relname = ${target.table}
+      AND a.attnum > 0 AND NOT a.attisdropped
+      AND a.attname IN (${target.tenantColumn}, ${target.actorColumn})`;
+    const problems = [];
+    for (const [role, name, kind] of [
+        ["tenant", target.tenantColumn, target.tenantKind],
+        ["actor", target.actorColumn, target.actorKind],
+    ]) {
+        const column = columns.find((candidate) => candidate.name === name);
+        if (column === undefined) {
+            problems.push(`${role} column ${name} does not exist in ${qualifiedName(target)}`);
+            continue;
+        }
+        if (column.type === "citext" || !["text", "varchar", "uuid"].includes(column.type)) {
+            problems.push(`${role} column ${name} is ${column.type}; only text, varchar, and uuid columns can be mapped`);
+            continue;
+        }
+        if ((column.type === "uuid") !== (kind === "uuid"))
+            problems.push(`${role} column ${name} is ${column.type} but is declared as a ${kind} column`);
+        if (column.deterministic === false)
+            problems.push(`${role} column ${name} has a nondeterministic collation`);
+    }
+    return problems;
+});
+const tableOid = (target) => `(SELECT c.oid FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = '${target.schema.replaceAll("'", "''")}' AND c.relname = '${target.table.replaceAll("'", "''")}')`;
+const hasOwnerIndex = Effect.fnUntraced(function* (target) {
+    const sql = yield* SqlClient.SqlClient;
+    const expected = ownerIndexColumns(target);
+    const leading = yield* sql.unsafe(`SELECT array_agg(a.attname ORDER BY k.ord) AS columns
+     FROM pg_index i
+     JOIN pg_class ic ON ic.oid = i.indexrelid
+     JOIN pg_am am ON am.oid = ic.relam AND am.amname = 'btree'
+     CROSS JOIN LATERAL unnest(i.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord)
+     JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum
+     WHERE i.indrelid = ${tableOid(target)} AND i.indpred IS NULL AND i.indexprs IS NULL
+       AND k.ord <= ${expected.length}
+     GROUP BY i.indexrelid`);
+    return leading.some((index) => index.columns.length === expected.length && index.columns.join() === expected.join());
+});
+/** True when an index leading with the mapped columns exists, so scoped statements do not scan the table. */
+export const ownerIndexExists = hasOwnerIndex;
+/**
+ * Reads the catalog for every adopted table of `actors` and reports what
+ * adoption would meet, and the SQL each step would run. Changes nothing.
+ */
+export const planAdoption = Effect.fnUntraced(function* (actors, only) {
+    const sql = yield* SqlClient.SqlClient;
+    const plans = [];
+    for (const target of yield* adoptionTargets(actors, only)) {
+        const name = qualifiedName(target);
+        const problems = [...(yield* mappingProblems(target))];
+        const warnings = [];
+        const exists = !problems.some((problem) => problem.endsWith("does not exist"));
+        if (!exists) {
+            plans.push({
+                table: name,
+                actor: target.actor,
+                access: target.access,
+                problems,
+                warnings,
+                foreignKeys: [],
+                triggers: [],
+                rules: [],
+                views: [],
+                owner: "",
+                writers: [],
+                indexSql: undefined,
+                steps: [],
+            });
+            continue;
+        }
+        const oid = tableOid(target);
+        const foreign = yield* sql.unsafe(`SELECT con.conname AS name, pg_get_constraintdef(con.oid) AS definition,
+         con.confrelid = ${oid} AS incoming, con.confdeltype AS delete_action
+       FROM pg_constraint con
+       WHERE con.contype = 'f' AND (con.conrelid = ${oid} OR con.confrelid = ${oid})
+       ORDER BY con.conname`);
+        const triggers = yield* sql.unsafe(`SELECT tgname AS name FROM pg_trigger
+       WHERE tgrelid = ${oid} AND NOT tgisinternal AND tgname NOT LIKE 'actor\\_adoption\\_%'
+       ORDER BY tgname`);
+        const rules = yield* sql.unsafe(`SELECT rulename AS name FROM pg_rules
+       WHERE schemaname = '${target.schema.replaceAll("'", "''")}'
+         AND tablename = '${target.table.replaceAll("'", "''")}'
+       ORDER BY rulename`);
+        const views = yield* sql.unsafe(`SELECT DISTINCT vn.nspname || '.' || v.relname AS name
+       FROM pg_depend d
+       JOIN pg_rewrite r ON r.oid = d.objid
+       JOIN pg_class v ON v.oid = r.ev_class AND v.relkind = 'v'
+       JOIN pg_namespace vn ON vn.oid = v.relnamespace
+       WHERE d.refobjid = ${oid} AND d.classid = 'pg_rewrite'::regclass
+       ORDER BY 1`);
+        const owner = (yield* sql.unsafe(`SELECT r.rolname AS name FROM pg_class c JOIN pg_roles r ON r.oid = c.relowner
+       WHERE c.oid = ${oid}`))[0].name;
+        const writers = yield* sql.unsafe(`SELECT r.rolname AS name FROM pg_roles r
+       WHERE r.rolname !~ '^pg_' AND has_table_privilege(r.oid, ${oid}, 'INSERT, UPDATE, DELETE, TRUNCATE')
+       ORDER BY r.rolname`);
+        const keyless = target.primaryKey.length === 0 && target.access === "write";
+        if (keyless)
+            problems.push(`${name} has no primary key, which upserts and backfill need`);
+        for (const column of [target.tenantColumn, target.actorColumn]) {
+            const notNull = yield* sql.unsafe(`SELECT attnotnull AS not_null FROM pg_attribute
+         WHERE attrelid = ${oid} AND attname = '${column.replaceAll("'", "''")}'`);
+            if (notNull[0]?.not_null === false)
+                warnings.push(`${column} is nullable; enforce adds a check constraint and refuses rows with NULL`);
+        }
+        for (const key of foreign) {
+            if (key.incoming)
+                continue;
+            if (target.access === "write")
+                warnings.push(`foreign key ${key.name} from ${name} to a shared parent adds multixact contention on a high-volume actor table`);
+            if (key.delete_action === "c" || key.delete_action === "n")
+                warnings.push(`foreign key ${key.name} of ${name} has ${key.delete_action === "c" ? "ON DELETE CASCADE" : "ON DELETE SET NULL"} on its parent, so a parent delete would change this table as its owner; enforce refuses until it is resolved`);
+        }
+        const indexed = yield* hasOwnerIndex(target);
+        const index = indexed ? undefined : ownerIndexSql(target);
+        if (index !== undefined)
+            warnings.push(`no index leads with (${ownerIndexColumns(target).join(", ")}); every scoped statement scans the table and startup refuses`);
+        const quoted = quotedTable(target);
+        const indexSteps = index === undefined ? [] : [index];
+        const steps = target.access === "read"
+            ? indexSteps
+            : [
+                ...indexSteps,
+                `ALTER TABLE ${quoted} ADD COLUMN IF NOT EXISTS routing_key bigint`,
+                `CREATE TRIGGER actor_adoption_observe_insert AFTER INSERT ON ${quoted} REFERENCING NEW TABLE AS new_rows FOR EACH STATEMENT EXECUTE FUNCTION actor_adoption_observe()`,
+                `CREATE TRIGGER actor_adoption_observe_update AFTER UPDATE ON ${quoted} REFERENCING OLD TABLE AS old_rows NEW TABLE AS new_rows FOR EACH STATEMENT EXECUTE FUNCTION actor_adoption_observe()`,
+                `CREATE TRIGGER actor_adoption_observe_delete AFTER DELETE ON ${quoted} REFERENCING OLD TABLE AS old_rows FOR EACH STATEMENT EXECUTE FUNCTION actor_adoption_observe()`,
+                `CREATE TRIGGER actor_adoption_observe_truncate AFTER TRUNCATE ON ${quoted} FOR EACH STATEMENT EXECUTE FUNCTION actor_adoption_observe()`,
+            ];
+        plans.push({
+            table: name,
+            actor: target.actor,
+            access: target.access,
+            problems,
+            warnings,
+            foreignKeys: foreign.map((key) => `${key.name}: ${key.definition}`),
+            triggers: triggers.map(({ name }) => name),
+            rules: rules.map(({ name }) => name),
+            views: views.map(({ name }) => name),
+            owner,
+            writers: writers.map(({ name }) => name),
+            indexSql: index,
+            steps,
+        });
+    }
+    return plans;
+});
+/** What `plan` prints: one block per table. */
+export const formatAdoptionPlan = (plan) => [
+    `${plan.table} (${plan.actor}, ${plan.access === "read" ? "read only" : "writable"})`,
+    ...plan.problems.map((problem) => `  problem: ${problem}`),
+    ...plan.warnings.map((warning) => `  warning: ${warning}`),
+    ...(plan.owner === "" ? [] : [`  owner: ${plan.owner}`]),
+    ...(plan.writers.length === 0 ? [] : [`  roles that can write: ${plan.writers.join(", ")}`]),
+    ...plan.foreignKeys.map((key) => `  foreign key ${key}`),
+    ...plan.triggers.map((trigger) => `  existing trigger ${trigger}`),
+    ...plan.rules.map((rule) => `  existing rule ${rule}`),
+    ...plan.views.map((view) => `  view over the table: ${view}`),
+    ...plan.steps.map((step) => `  ${step};`),
+].join("\n");

package/dist/runtime/adoption/startup.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { AdoptionTarget } from "./target.ts";
+/**
+ * Refuses an enforced table whose protection was changed behind the
+ * runtime's back. `refuse` names the table and the fix. The guard triggers
+ * must exist, be enabled always, and carry exactly the recorded writer,
+ * allowed roles, columns, and actor type; no role but the writer and the
+ * allowed ones may hold a write privilege, so a grant added later is caught
+ * here and by the trigger.
+ */
+export declare const checkEnforcedTable: (args_0: {
+    readonly target: Pick<AdoptionTarget, "schema" | "table" | "tenantColumn" | "actorColumn" | "actor">;
+    readonly writerRole: string;
+    readonly allowedRoles: ReadonlyArray<string>;
+    readonly runtimeRole: string | undefined;
+    readonly refuse: (message: string) => Effect.Effect<never>;
+}) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Refuses a writer role a turn cannot run as: it must exist, this login must
+ * be able to take it, and it must read and write every framework table and
+ * every table in `tables` without owning one, because the whole turn runs as
+ * the writer.
+ */
+export declare const checkWriterRole: (args_0: {
+    readonly role: string;
+    readonly tables: ReadonlyArray<{
+        readonly schema: string;
+        readonly table: string;
+    }>;
+    readonly refuse: (message: string) => Effect.Effect<never>;
+}) => Effect.Effect<undefined, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;

package/dist/runtime/adoption/startup.js

@@ -0,0 +1,76 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { guardArguments, writeGrants } from "./enforce.js";
+const GUARD_ROW_TYPE = 31;
+const GUARD_TRUNCATE_TYPE = 34;
+/**
+ * Refuses an enforced table whose protection was changed behind the
+ * runtime's back. `refuse` names the table and the fix. The guard triggers
+ * must exist, be enabled always, and carry exactly the recorded writer,
+ * allowed roles, columns, and actor type; no role but the writer and the
+ * allowed ones may hold a write privilege, so a grant added later is caught
+ * here and by the trigger.
+ */
+export const checkEnforcedTable = Effect.fnUntraced(function* ({ target, writerRole, allowedRoles, runtimeRole, refuse, }) {
+    const sql = yield* SqlClient.SqlClient;
+    if (runtimeRole === undefined)
+        return yield* refuse(`is enforced for writer role ${writerRole}; start the runtime with adoption: { role: "${writerRole}" }`);
+    if (runtimeRole !== writerRole)
+        return yield* refuse(`is enforced for writer role ${writerRole}, but the runtime takes ${runtimeRole}; set adoption.role to ${writerRole}`);
+    const triggers = yield* sql `
+    SELECT t.tgname AS name, t.tgenabled AS enabled, t.tgtype::int AS type,
+      p.proname AS function, encode(t.tgargs, 'escape') AS arguments
+    FROM pg_trigger t
+    JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_proc p ON p.oid = t.tgfoid
+    WHERE n.nspname = ${target.schema} AND c.relname = ${target.table} AND NOT t.tgisinternal
+      AND t.tgname IN ('actor_adoption_guard', 'actor_adoption_guard_truncate')`;
+    const expected = guardArguments({ target, writerRole, allowedRoles });
+    for (const [name, type] of [
+        ["actor_adoption_guard", GUARD_ROW_TYPE],
+        ["actor_adoption_guard_truncate", GUARD_TRUNCATE_TYPE],
+    ]) {
+        const found = triggers.find((trigger) => trigger.name === name);
+        if (found === undefined)
+            return yield* refuse(`is enforced but its guard trigger ${name} is missing; run durable adopt release ${target.table} --to observe and enforce it again`);
+        if (found.enabled !== "A")
+            return yield* refuse(`is enforced but its guard trigger ${name} is not enabled always; run ALTER TABLE ${target.table} ENABLE ALWAYS TRIGGER ${name}`);
+        if (found.function !== "actor_adoption_guard" || found.type !== type)
+            return yield* refuse(`is enforced but its trigger ${name} is not the framework guard`);
+        if (found.arguments !== `${expected.join("\\000")}\\000`)
+            return yield* refuse(`is enforced but its guard trigger ${name} does not carry the recorded writer, allowed roles, and columns`);
+    }
+    const stray = (yield* writeGrants(target)).filter((grant) => grant.grantee !== writerRole && !allowedRoles.includes(grant.grantee));
+    if (stray.length > 0)
+        return yield* refuse(`is enforced but ${[...new Set(stray.map((grant) => grant.grantee))].join(", ")} hold write privileges again; revoke them (REVOKE INSERT, UPDATE, DELETE, TRUNCATE ON ${target.table} FROM …)`);
+});
+/**
+ * Refuses a writer role a turn cannot run as: it must exist, this login must
+ * be able to take it, and it must read and write every framework table and
+ * every table in `tables` without owning one, because the whole turn runs as
+ * the writer.
+ */
+export const checkWriterRole = Effect.fnUntraced(function* ({ role, tables, refuse, }) {
+    const sql = yield* SqlClient.SqlClient;
+    const [found] = yield* sql `
+    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = ${role}) AS exists`;
+    if (found?.exists !== true)
+        return yield* refuse(`writer role ${role} does not exist`);
+    yield* sql `SELECT set_config('role', ${role}, true)`.pipe(sql.withTransaction, Effect.catch(() => refuse(`this login cannot SET ROLE ${role}`)));
+    const owned = yield* sql `
+    SELECT n.nspname AS schema, c.relname AS table,
+      pg_has_role(${role}, c.relowner, 'USAGE') AS owned,
+      has_table_privilege(${role}, c.oid, 'SELECT') AND has_table_privilege(${role}, c.oid, 'INSERT')
+        AND has_table_privilege(${role}, c.oid, 'UPDATE') AND has_table_privilege(${role}, c.oid, 'DELETE') AS usable
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE c.relkind = 'r' AND (
+      (n.oid = current_schema()::regnamespace AND (c.relname LIKE 'actor\\_%' OR c.relname LIKE 'tenant\\_content%'))
+      OR (n.nspname, c.relname) IN (${sql.csv(tables.map(({ schema, table }) => sql `(${schema}, ${table})`))}))
+    ORDER BY 1, 2`;
+    for (const table of owned) {
+        if (table.owned)
+            return yield* refuse(`writer role ${role} owns ${table.schema}.${table.table}; the writer must not own a table it is guarded on`);
+        if (!table.usable)
+            return yield* refuse(`writer role ${role} cannot read and write ${table.schema}.${table.table}; grant it SELECT, INSERT, UPDATE, and DELETE`);
+    }
+});

package/dist/runtime/adoption/status.d.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/** One adopted table as `durable adopt status` reports it. */
+export interface AdoptionStatus {
+    readonly table: string;
+    readonly actor: string;
+    readonly mode: "observe" | "enforce";
+    /** Rows still without a `routing_key`; enforcement needs none. */
+    readonly unbackfilled: number;
+    /** The last write neither the runtime nor an allowed role made, in epoch milliseconds. */
+    readonly lastLegacyWriteMs: number | undefined;
+    readonly writerRole: string | undefined;
+    /** Roles that may still write the table directly; adoption is complete when this is empty. */
+    readonly allowedRoles: ReadonlyArray<string>;
+}
+/**
+ * Every recorded adoption in the database, with its unbackfilled row count
+ * and its last legacy write. Reads only the catalog and the recorded writes,
+ * so it needs no actor definitions.
+ */
+export declare const adoptionStatus: Effect.Effect<AdoptionStatus[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** One line per adopted table. */
+export declare const formatAdoptionStatus: (status: AdoptionStatus) => string;

package/dist/runtime/adoption/status.js

@@ -0,0 +1,47 @@
+import { DateTime, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+/**
+ * Every recorded adoption in the database, with its unbackfilled row count
+ * and its last legacy write. Reads only the catalog and the recorded writes,
+ * so it needs no actor definitions.
+ */
+export const adoptionStatus = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const adoptions = yield* sql `SELECT table_schema, table_name, actor_type, mode, writer_role, allowed_roles
+    FROM actor_adoptions ORDER BY table_schema, table_name`;
+    const statuses = [];
+    for (const adoption of adoptions) {
+        const table = `"${adoption.table_schema.replaceAll('"', '""')}"."${adoption.table_name.replaceAll('"', '""')}"`;
+        const [counted] = yield* sql.unsafe(`SELECT count(*)::text AS unbackfilled FROM ${table} WHERE routing_key IS NULL`);
+        const [last] = yield* sql `
+      SELECT max(observed_at_ms)::text AS last FROM actor_adoption_writes
+      WHERE table_schema = ${adoption.table_schema} AND table_name = ${adoption.table_name}
+        AND NOT in_turn AND NOT allowed`;
+        statuses.push({
+            table: `${adoption.table_schema}.${adoption.table_name}`,
+            actor: adoption.actor_type,
+            mode: adoption.mode,
+            unbackfilled: Number(counted.unbackfilled),
+            lastLegacyWriteMs: last?.last == null ? undefined : Number(last.last),
+            writerRole: adoption.writer_role ?? undefined,
+            allowedRoles: adoption.allowed_roles,
+        });
+    }
+    return statuses;
+});
+/** One line per adopted table. */
+export const formatAdoptionStatus = (status) => [
+    `${status.table}  ${status.actor}  ${status.mode}`,
+    `${status.unbackfilled} rows without routing_key`,
+    status.lastLegacyWriteMs === undefined
+        ? "no legacy write recorded"
+        : `last legacy write ${DateTime.formatIso(DateTime.makeUnsafe(status.lastLegacyWriteMs))}`,
+    ...(status.mode === "enforce"
+        ? [
+            `writer ${status.writerRole}`,
+            status.allowedRoles.length === 0
+                ? "no allowed roles: adoption is complete"
+                : `allowed roles ${status.allowedRoles.join(", ")}`,
+        ]
+        : []),
+].join("  ");

package/dist/runtime/adoption/target.d.ts

@@ -0,0 +1,33 @@
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { type AdoptionAccess, type MappedKind } from "../../tables/owned.ts";
+import type { Placement } from "../storage/codec.ts";
+declare const AdoptionRefused_base: Schema.Class<AdoptionRefused, Schema.TaggedStruct<"AdoptionRefused", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** A command's precondition failed; the message names the table and the fix. */
+export declare class AdoptionRefused extends AdoptionRefused_base {
+}
+/** One existing table an actor type declares with `Actor.table(existing, { owner })`. */
+export interface AdoptionTarget {
+    readonly actor: string;
+    readonly placement: Placement;
+    readonly access: AdoptionAccess;
+    readonly schema: string;
+    readonly table: string;
+    readonly tenantColumn: string;
+    readonly actorColumn: string;
+    readonly tenantKind: MappedKind;
+    readonly actorKind: MappedKind;
+    /** SQL names of the primary key columns, in key order. */
+    readonly primaryKey: ReadonlyArray<string>;
+}
+/** The table's name as `schema.table`, which the CLI and every report print. */
+export declare const qualifiedName: (target: Pick<AdoptionTarget, "schema" | "table">) => string;
+/**
+ * The adopted tables of `actors`, resolved against the connection's current
+ * schema. `only` is a table name or `schema.table`; naming a table no actor
+ * adopts is refused, so a typo never silently does nothing.
+ */
+export declare const adoptionTargets: (actors: readonly WeakKey[], only?: string | undefined) => Effect.Effect<AdoptionTarget[], AdoptionRefused | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+export {};

package/dist/runtime/adoption/target.js

@@ -0,0 +1,49 @@
+import { getTableColumns } from "drizzle-orm";
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { descriptorOf } from "../../actor/descriptor.js";
+import { ownership } from "../../tables/owned.js";
+/** A command's precondition failed; the message names the table and the fix. */
+export class AdoptionRefused extends Schema.TaggedError()("AdoptionRefused", {
+    message: Schema.String,
+}) {
+}
+/** The table's name as `schema.table`, which the CLI and every report print. */
+export const qualifiedName = (target) => `${target.schema}.${target.table}`;
+/**
+ * The adopted tables of `actors`, resolved against the connection's current
+ * schema. `only` is a table name or `schema.table`; naming a table no actor
+ * adopts is refused, so a typo never silently does nothing.
+ */
+export const adoptionTargets = Effect.fnUntraced(function* (actors, only) {
+    const sql = yield* SqlClient.SqlClient;
+    const current = (yield* sql `SELECT current_schema() AS schema`)[0].schema;
+    const targets = [];
+    for (const actor of actors) {
+        const declared = descriptorOf(actor);
+        for (const table of declared?.tables ?? []) {
+            const info = ownership(table);
+            if (!info.adopted)
+                continue;
+            const columns = getTableColumns(table);
+            targets.push({
+                actor: declared.name,
+                placement: declared.placement,
+                access: info.access,
+                schema: info.schema ?? current,
+                table: info.table,
+                tenantColumn: columns[info.tenantKey].name,
+                actorColumn: columns[info.actorKey].name,
+                tenantKind: info.tenantKind,
+                actorKind: info.actorKind,
+                primaryKey: info.primaryKey.map((key) => columns[key].name),
+            });
+        }
+    }
+    if (only === undefined)
+        return targets;
+    const named = targets.filter((target) => target.table === only || qualifiedName(target) === only);
+    if (named.length === 0)
+        return yield* AdoptionRefused.make({ message: `No actor type adopts a table named ${only}` });
+    return named;
+});