@rikalabs/akter 0.1.0-alpha.0

package/dist/runtime/adoption/enforce.js

@@ -0,0 +1,241 @@
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { installObserveTriggers } from "./observe.js";
+import { quotedTable } from "./plan.js";
+import { AdoptionRefused, adoptionTargets, qualifiedName } from "./target.js";
+/** The default window a table must have been observed and quiet for before it is enforced. */
+export const DEFAULT_QUIET_MS = 7 * 86_400_000;
+const WRITE_PRIVILEGES = ["INSERT", "UPDATE", "DELETE", "TRUNCATE"];
+const Revoked = Schema.Array(Schema.Struct({ grantee: Schema.String, privilege: Schema.String }));
+const RevokedJson = Schema.fromJsonString(Revoked);
+const decodeRevoked = Schema.decodeUnknownEffect(Revoked);
+const encodeRevoked = Schema.encodeEffect(RevokedJson);
+const identifier = (name) => `"${name.replaceAll('"', '""')}"`;
+const literal = (value) => `'${value.replaceAll("'", "''")}'`;
+/** The grantees holding a write privilege on `target`, with the privilege, as the catalog records them. */
+export const writeGrants = Effect.fnUntraced(function* (target) {
+    const sql = yield* SqlClient.SqlClient;
+    return yield* sql `
+    SELECT CASE WHEN a.grantee = 0 THEN 'PUBLIC' ELSE pg_get_userbyid(a.grantee) END AS grantee,
+      a.privilege_type AS privilege
+    FROM pg_class c
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    CROSS JOIN LATERAL aclexplode(coalesce(c.relacl, acldefault('r', c.relowner))) AS a
+    WHERE n.nspname = ${target.schema} AND c.relname = ${target.table}
+      AND a.privilege_type IN ${sql.in(WRITE_PRIVILEGES)}
+    ORDER BY 1, 2`;
+});
+/** The trigger arguments the guard is installed with, in the order `actor_adoption_guard()` reads them. */
+export const guardArguments = ({ target, writerRole, allowedRoles, }) => [writerRole, allowedRoles.join(","), target.tenantColumn, target.actorColumn, target.actor];
+const roleNamed = (name, flag) => {
+    if (name === "" || name.includes(",") || name.includes("'"))
+        return AdoptionRefused.make({ message: `${flag} names a role without commas or quotes` });
+    return undefined;
+};
+/**
+ * The reasons `target` cannot be enforced yet, each naming the fix. Reads
+ * only: a table is enforced when this is empty.
+ */
+const enforcementRefusals = Effect.fnUntraced(function* (target, options) {
+    const sql = yield* SqlClient.SqlClient;
+    const name = qualifiedName(target);
+    const table = quotedTable(target);
+    const refusals = [];
+    const allowed = [...options.allowedRoles];
+    const [adoption] = yield* sql `
+    SELECT changed_at_ms::text FROM actor_adoptions
+    WHERE table_schema = ${target.schema} AND table_name = ${target.table}`;
+    const observedFor = options.nowMs - Number(adoption.changed_at_ms);
+    if (observedFor < options.quietMs)
+        refusals.push(`${name} has been observed for ${Math.floor(observedFor / 1000)} s, less than the ${Math.floor(options.quietMs / 1000)} s quiet window (--quiet), so its silence proves nothing yet`);
+    const [counts] = yield* sql.unsafe(`SELECT count(*) FILTER (WHERE routing_key IS NULL)::text AS unfilled,
+       count(*) FILTER (WHERE ${identifier(target.tenantColumn)} IS NULL OR ${identifier(target.actorColumn)} IS NULL
+         OR ${identifier(target.tenantColumn)}::text = '' OR ${identifier(target.actorColumn)}::text = '')::text AS unowned
+     FROM ${table}`);
+    if (Number(counts.unfilled) > 0)
+        refusals.push(`${counts.unfilled} rows of ${name} have no routing_key; run durable adopt backfill ${target.table}`);
+    if (Number(counts.unowned) > 0)
+        refusals.push(`${counts.unowned} rows of ${name} have a NULL or empty ${target.tenantColumn} or ${target.actorColumn}, so no actor owns them`);
+    const recent = yield* sql `
+    SELECT session_user_name, application_name, operation, count(*)::text AS statements
+    FROM actor_adoption_writes
+    WHERE table_schema = ${target.schema} AND table_name = ${target.table}
+      AND observed_at_ms >= ${options.nowMs - options.quietMs}
+      AND NOT in_turn AND NOT allowed AND session_user_name NOT IN ${sql.in(["", ...allowed])}
+    GROUP BY session_user_name, application_name, operation
+    ORDER BY 1, 2, 3`;
+    for (const writer of recent)
+        refusals.push(`${writer.session_user_name} (${writer.application_name === "" ? "no application_name" : writer.application_name}) wrote ${name} with ${writer.statements} ${writer.operation} statements inside the quiet window; stop it, or route it through --allow`);
+    const both = yield* sql `
+    SELECT session_user_name FROM actor_adoption_writes
+    WHERE table_schema = ${target.schema} AND table_name = ${target.table}
+    GROUP BY session_user_name HAVING bool_or(in_turn) AND bool_or(NOT in_turn)`;
+    for (const shared of both)
+        refusals.push(`${shared.session_user_name} wrote ${name} both inside and outside runtime turns; a login that can act as the runtime can take the writer role, so give the application and the runtime separate logins`);
+    const [role] = yield* sql `
+    SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = ${options.writerRole}) AS exists`;
+    if (role.exists !== true)
+        refusals.push(`role ${options.writerRole} does not exist; create it and grant it the table`);
+    const [owner] = yield* sql `
+    SELECT r.rolname AS owner, r.rolname = ${options.writerRole} AS is_writer
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace JOIN pg_roles r ON r.oid = c.relowner
+    WHERE n.nspname = ${target.schema} AND c.relname = ${target.table}`;
+    if (owner.is_writer)
+        refusals.push(`${name} is owned by the writer role ${options.writerRole}; an owner can disable its triggers, so give the table to a role no login is a member of`);
+    const actingAsOwner = yield* sql `
+    SELECT l.rolname AS name FROM pg_roles l
+    WHERE l.rolcanlogin AND NOT l.rolsuper AND l.rolname <> session_user
+      AND pg_has_role(l.oid, (SELECT c.relowner FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = ${target.schema} AND c.relname = ${target.table}), 'USAGE')
+    ORDER BY 1`;
+    for (const login of actingAsOwner)
+        refusals.push(`login ${login.name} can act as ${name}'s owner ${owner.owner}, so it could disable the guard; give the table to a NOLOGIN role no login is a member of (ALTER TABLE ${table} OWNER TO …)`);
+    const runtimeLogins = yield* sql `
+    SELECT DISTINCT session_user_name FROM actor_adoption_writes
+    WHERE table_schema = ${target.schema} AND table_name = ${target.table} AND in_turn`;
+    const members = yield* sql `
+    SELECT l.rolname AS name FROM pg_roles l
+    WHERE l.rolcanlogin AND NOT l.rolsuper AND l.rolname <> session_user AND l.rolname <> ${options.writerRole}
+      AND EXISTS (SELECT 1 FROM pg_roles w WHERE w.rolname = ${options.writerRole}
+        AND pg_has_role(l.oid, w.oid, 'MEMBER'))
+    ORDER BY 1`;
+    for (const member of members)
+        if (!runtimeLogins.some((login) => login.session_user_name === member.name))
+            refusals.push(`login ${member.name} is a member of ${options.writerRole} but no runtime turn was recorded from it, so it could write the table as the runtime; revoke its membership, or let the runtime write the table once while observing`);
+    const cascades = yield* sql.unsafe(`SELECT con.conname AS name, con.confrelid::regclass::text AS parent,
+       CASE con.confdeltype WHEN 'c' THEN 'ON DELETE CASCADE' ELSE 'ON DELETE SET NULL' END AS action
+     FROM pg_constraint con
+     WHERE con.contype = 'f' AND con.conrelid = ${`${literal(quotedTable(target))}::regclass`}
+       AND con.confdeltype IN ('c', 'n')
+     ORDER BY 1`);
+    for (const cascade of cascades)
+        refusals.push(`foreign key ${cascade.name} of ${name} references ${cascade.parent} with ${cascade.action}; deleting a parent row would change this table as its owner and be rejected by the guard, so resolve it first`);
+    return refusals;
+});
+/**
+ * Enforces each named adopted table of `actors`, in one transaction under a
+ * `lock_timeout`. Nothing changes unless every check passes: the table has
+ * been observed for the whole quiet window, no legacy write outside `allow`
+ * roles fell inside it, no login wrote both in and out of turns, every row
+ * has its `routing_key` and owner columns, the owner is a role no login can
+ * act as, no other login can take the writer role, and no cascade reaches the
+ * table. It then revokes write privileges from every role but the writer and
+ * the allowed ones, adds the constraint that keeps `routing_key` and the
+ * mapped columns filled, and installs the guard triggers, always enabled.
+ */
+export const enforceAdoption = Effect.fnUntraced(function* (actors, options) {
+    const sql = yield* SqlClient.SqlClient;
+    const allowedRoles = options.allowedRoles ?? [];
+    for (const [role, flag] of [
+        [options.writerRole, "--writer-role"],
+        ...allowedRoles.map((allowed) => [allowed, "--allow"]),
+    ]) {
+        const bad = roleNamed(role, flag);
+        if (bad !== undefined)
+            return yield* bad;
+    }
+    if (allowedRoles.includes(options.writerRole))
+        return yield* AdoptionRefused.make({
+            message: "--allow cannot name the writer role, which already passes",
+        });
+    const results = [];
+    for (const target of yield* adoptionTargets(actors, options.only)) {
+        const name = qualifiedName(target);
+        if (target.access === "read")
+            return yield* AdoptionRefused.make({
+                message: `${name} is adopted for reading only and has no writers to enforce against`,
+            });
+        results.push(yield* Effect.gen(function* () {
+            yield* sql `SELECT set_config('lock_timeout', ${`${options.lockTimeoutMs ?? 5000}ms`}, true)`;
+            const [adoption] = yield* sql `
+          SELECT actor_type, mode FROM actor_adoptions
+          WHERE table_schema = ${target.schema} AND table_name = ${target.table} FOR UPDATE`;
+            if (adoption === undefined)
+                return yield* AdoptionRefused.make({
+                    message: `${name} is not observed; run durable adopt observe ${target.table} first`,
+                });
+            if (adoption.mode === "enforce")
+                return yield* AdoptionRefused.make({ message: `${name} is already enforced` });
+            const refusals = yield* enforcementRefusals(target, {
+                writerRole: options.writerRole,
+                allowedRoles,
+                quietMs: options.quietMs ?? DEFAULT_QUIET_MS,
+                nowMs: options.nowMs,
+            });
+            if (refusals.length > 0)
+                return yield* AdoptionRefused.make({
+                    message: `${name} cannot be enforced:\n${refusals.map((refusal) => `  - ${refusal}`).join("\n")}`,
+                });
+            const table = quotedTable(target);
+            const tenant = identifier(target.tenantColumn);
+            const actor = identifier(target.actorColumn);
+            yield* sql.unsafe(`ALTER TABLE ${table} ADD CONSTRAINT actor_adoption_owner CHECK (routing_key IS NOT NULL
+             AND ${tenant} IS NOT NULL AND ${actor} IS NOT NULL
+             AND ${tenant}::text <> '' AND ${actor}::text <> '') NOT VALID`);
+            yield* sql.unsafe(`ALTER TABLE ${table} VALIDATE CONSTRAINT actor_adoption_owner`);
+            const revoked = (yield* writeGrants(target)).filter((grant) => grant.grantee !== options.writerRole && !allowedRoles.includes(grant.grantee));
+            for (const grant of revoked)
+                yield* sql.unsafe(`REVOKE ${grant.privilege} ON ${table} FROM ${grant.grantee === "PUBLIC" ? "PUBLIC" : identifier(grant.grantee)}`);
+            const args = guardArguments({ target, writerRole: options.writerRole, allowedRoles })
+                .map(literal)
+                .join(", ");
+            const schema = (yield* sql `SELECT quote_ident(current_schema()) AS name`)[0].name;
+            yield* sql.unsafe(`CREATE TRIGGER actor_adoption_guard BEFORE INSERT OR UPDATE OR DELETE ON ${table}
+           FOR EACH ROW EXECUTE FUNCTION ${schema}.actor_adoption_guard(${args})`);
+            yield* sql.unsafe(`ALTER TABLE ${table} ENABLE ALWAYS TRIGGER actor_adoption_guard`);
+            yield* sql.unsafe(`CREATE TRIGGER actor_adoption_guard_truncate BEFORE TRUNCATE ON ${table}
+           FOR EACH STATEMENT EXECUTE FUNCTION ${schema}.actor_adoption_guard(${args})`);
+            yield* sql.unsafe(`ALTER TABLE ${table} ENABLE ALWAYS TRIGGER actor_adoption_guard_truncate`);
+            yield* installObserveTriggers(target, [options.writerRole, ...allowedRoles]);
+            const recorded = yield* encodeRevoked(revoked).pipe(Effect.orDie);
+            yield* sql `UPDATE actor_adoptions SET mode = 'enforce', writer_role = ${options.writerRole},
+            allowed_roles = coalesce(string_to_array(nullif(${allowedRoles.join(",")}, ''), ','), '{}'), revoked = ${recorded}::jsonb,
+            changed_at_ms = floor(extract(epoch FROM clock_timestamp()) * 1000), changed_by = session_user
+          WHERE table_schema = ${target.schema} AND table_name = ${target.table}`;
+            return {
+                table: name,
+                writerRole: options.writerRole,
+                allowedRoles,
+                revoked: revoked.length,
+            };
+        }).pipe(sql.withTransaction));
+    }
+    return results;
+});
+/**
+ * Returns `only` from enforced to observed: drops the guard and the
+ * constraint that legacy writers, which supply no `routing_key`, would
+ * violate, gives back the privileges `enforce` recorded, and reinstalls the
+ * plain observing triggers. It never removes `routing_key` or the record.
+ */
+export const releaseAdoption = Effect.fnUntraced(function* (actors, options) {
+    const sql = yield* SqlClient.SqlClient;
+    const released = [];
+    for (const target of yield* adoptionTargets(actors, options.only)) {
+        const name = qualifiedName(target);
+        yield* Effect.gen(function* () {
+            yield* sql `SELECT set_config('lock_timeout', ${`${options.lockTimeoutMs ?? 5000}ms`}, true)`;
+            const [adoption] = yield* sql `
+        SELECT mode, revoked FROM actor_adoptions
+        WHERE table_schema = ${target.schema} AND table_name = ${target.table} FOR UPDATE`;
+            if (adoption?.mode !== "enforce")
+                return yield* AdoptionRefused.make({ message: `${name} is not enforced` });
+            const table = quotedTable(target);
+            const grants = yield* decodeRevoked(adoption.revoked).pipe(Effect.orDie);
+            yield* sql.unsafe(`DROP TRIGGER IF EXISTS actor_adoption_guard ON ${table}`);
+            yield* sql.unsafe(`DROP TRIGGER IF EXISTS actor_adoption_guard_truncate ON ${table}`);
+            yield* sql.unsafe(`ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS actor_adoption_owner`);
+            for (const grant of grants)
+                yield* sql.unsafe(`GRANT ${grant.privilege} ON ${table} TO ${grant.grantee === "PUBLIC" ? "PUBLIC" : identifier(grant.grantee)}`);
+            yield* installObserveTriggers(target);
+            yield* sql `UPDATE actor_adoptions SET mode = 'observe', writer_role = NULL,
+          allowed_roles = '{}', revoked = '[]',
+          changed_at_ms = floor(extract(epoch FROM clock_timestamp()) * 1000), changed_by = session_user
+        WHERE table_schema = ${target.schema} AND table_name = ${target.table}`;
+        }).pipe(sql.withTransaction);
+        released.push(name);
+    }
+    return released;
+});
+/** One line per enforced table. */
+export const formatEnforce = (result) => `${result.table} is enforced: writer ${result.writerRole}, ${result.revoked} privileges revoked${result.allowedRoles.length === 0 ? "" : `, allowed roles ${result.allowedRoles.join(", ")}`}`;

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

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { AdoptionRefused, type AdoptionTarget } from "./target.ts";
+/** One legacy or runtime writer the observing trigger recorded, grouped as `observe --report` prints it. */
+export interface ObservedWriter {
+    readonly table: string;
+    readonly sessionUser: string;
+    readonly applicationName: string;
+    readonly operation: string;
+    /** True for statements a runtime turn made; the setting that marks them is forgeable, so it classifies and never authorizes. */
+    readonly inTurn: boolean;
+    readonly allowed: boolean;
+    readonly statements: number;
+    readonly rows: number;
+    readonly firstSeenMs: number;
+    readonly lastSeenMs: number;
+}
+/**
+ * Installs the four observing triggers on `target`, replacing any this module
+ * installed before. `arguments` is empty while observing, and names the writer
+ * and allowed roles once the table is enforced, so the trigger stays quiet for
+ * the runtime and marks allowed roles.
+ */
+export declare const installObserveTriggers: (target: AdoptionTarget, roles?: readonly string[] | undefined) => Effect.Effect<void, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * Moves each writable adopted table of `actors` into the observing state:
+ * adds the nullable `routing_key`, records the adoption, and installs the
+ * statement triggers that record every later write. Observing changes no
+ * outcome, and repeating it is safe. A table already enforced is refused.
+ */
+export declare const observeAdoption: (actors: readonly WeakKey[], only?: string | undefined, lockTimeoutMs?: any) => Effect.Effect<string[], AdoptionRefused | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * The writers recorded for the adopted tables of `actors` since `sinceMs`,
+ * grouped by table, login, application, and operation, with the runtime's own
+ * turns kept apart. `clear` deletes exactly the rows it reports.
+ */
+export declare const adoptionWriters: (actors: readonly WeakKey[], options: {
+    readonly only?: string | undefined;
+    readonly sinceMs?: number | undefined;
+    readonly clear?: boolean | undefined;
+}) => Effect.Effect<ObservedWriter[], AdoptionRefused | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** One line of `observe --report`: who wrote, how often, and whether the runtime's own turns did. */
+export declare const formatObservedWriter: (writer: ObservedWriter) => string;

package/dist/runtime/adoption/observe.js

@@ -0,0 +1,139 @@
+import { DateTime, Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { mappingProblems, quotedTable } from "./plan.js";
+import { AdoptionRefused, adoptionTargets, qualifiedName } from "./target.js";
+const observeFunction = Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return (yield* sql `SELECT quote_ident(current_schema()) AS name`)[0].name;
+});
+/**
+ * Installs the four observing triggers on `target`, replacing any this module
+ * installed before. `arguments` is empty while observing, and names the writer
+ * and allowed roles once the table is enforced, so the trigger stays quiet for
+ * the runtime and marks allowed roles.
+ */
+export const installObserveTriggers = Effect.fnUntraced(function* (target, roles = []) {
+    const sql = yield* SqlClient.SqlClient;
+    const schema = yield* observeFunction;
+    const table = quotedTable(target);
+    const literals = roles.map((role) => `'${role.replaceAll("'", "''")}'`).join(", ");
+    for (const event of ["insert", "update", "delete", "truncate"])
+        yield* sql.unsafe(`DROP TRIGGER IF EXISTS actor_adoption_observe_${event} ON ${table}`);
+    const trigger = `${schema}.actor_adoption_observe(${literals})`;
+    yield* sql.unsafe(`CREATE TRIGGER actor_adoption_observe_insert AFTER INSERT ON ${table}
+     REFERENCING NEW TABLE AS new_rows FOR EACH STATEMENT EXECUTE FUNCTION ${trigger}`);
+    yield* sql.unsafe(`CREATE TRIGGER actor_adoption_observe_update AFTER UPDATE ON ${table}
+     REFERENCING OLD TABLE AS old_rows NEW TABLE AS new_rows
+     FOR EACH STATEMENT EXECUTE FUNCTION ${trigger}`);
+    yield* sql.unsafe(`CREATE TRIGGER actor_adoption_observe_delete AFTER DELETE ON ${table}
+     REFERENCING OLD TABLE AS old_rows FOR EACH STATEMENT EXECUTE FUNCTION ${trigger}`);
+    yield* sql.unsafe(`CREATE TRIGGER actor_adoption_observe_truncate AFTER TRUNCATE ON ${table}
+     FOR EACH STATEMENT EXECUTE FUNCTION ${trigger}`);
+});
+/** Refuses a `--table` filter that names a table adopted for reading only, which has no observing state. */
+const writable = (targets, only) => {
+    const found = targets.filter((target) => target.access === "write");
+    if (found.length === 0 && only !== undefined)
+        return Effect.fail(AdoptionRefused.make({
+            message: `${only} is adopted for reading only: nothing writes it, so it has no observing state`,
+        }));
+    return Effect.succeed(found);
+};
+/**
+ * Moves each writable adopted table of `actors` into the observing state:
+ * adds the nullable `routing_key`, records the adoption, and installs the
+ * statement triggers that record every later write. Observing changes no
+ * outcome, and repeating it is safe. A table already enforced is refused.
+ */
+export const observeAdoption = Effect.fnUntraced(function* (actors, only, lockTimeoutMs = 5000) {
+    const sql = yield* SqlClient.SqlClient;
+    const done = [];
+    for (const target of yield* adoptionTargets(actors, only).pipe(Effect.flatMap((targets) => writable(targets, only)))) {
+        const name = qualifiedName(target);
+        const problems = yield* mappingProblems(target);
+        if (problems.length > 0)
+            return yield* AdoptionRefused.make({
+                message: `${name} cannot be adopted: ${problems.join("; ")}`,
+            });
+        yield* Effect.gen(function* () {
+            yield* sql `SELECT set_config('lock_timeout', ${`${lockTimeoutMs}ms`}, true)`;
+            const [existing] = yield* sql `
+        SELECT actor_type, mode FROM actor_adoptions
+        WHERE table_schema = ${target.schema} AND table_name = ${target.table} FOR UPDATE`;
+            if (existing !== undefined && existing.actor_type !== target.actor)
+                return yield* AdoptionRefused.make({
+                    message: `${name} is adopted by actor ${existing.actor_type}, not ${target.actor}`,
+                });
+            if (existing?.mode === "enforce")
+                return yield* AdoptionRefused.make({
+                    message: `${name} is enforced; run durable adopt release ${target.table} --to observe first`,
+                });
+            const [column] = yield* sql `
+        SELECT t.typname AS type 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
+        WHERE n.nspname = ${target.schema} AND c.relname = ${target.table}
+          AND a.attname = 'routing_key' AND NOT a.attisdropped`;
+            if (column !== undefined && column.type !== "int8")
+                return yield* AdoptionRefused.make({
+                    message: `${name} already has a routing_key column of type ${column.type}; it must be bigint`,
+                });
+            yield* sql.unsafe(`ALTER TABLE ${quotedTable(target)} ADD COLUMN IF NOT EXISTS routing_key bigint`);
+            yield* sql `INSERT INTO actor_adoptions (table_schema, table_name, actor_type, tenant_column,
+          actor_column, mode, changed_at_ms, changed_by)
+        VALUES (${target.schema}, ${target.table}, ${target.actor}, ${target.tenantColumn},
+          ${target.actorColumn}, 'observe', floor(extract(epoch FROM clock_timestamp()) * 1000),
+          session_user)
+        ON CONFLICT (table_schema, table_name) DO UPDATE SET
+          changed_at_ms = CASE WHEN actor_adoptions.tenant_column = EXCLUDED.tenant_column
+            AND actor_adoptions.actor_column = EXCLUDED.actor_column
+            THEN actor_adoptions.changed_at_ms ELSE EXCLUDED.changed_at_ms END,
+          tenant_column = EXCLUDED.tenant_column, actor_column = EXCLUDED.actor_column,
+          changed_by = EXCLUDED.changed_by`;
+            yield* installObserveTriggers(target);
+        }).pipe(sql.withTransaction);
+        done.push(name);
+    }
+    return done;
+});
+/**
+ * The writers recorded for the adopted tables of `actors` since `sinceMs`,
+ * grouped by table, login, application, and operation, with the runtime's own
+ * turns kept apart. `clear` deletes exactly the rows it reports.
+ */
+export const adoptionWriters = Effect.fnUntraced(function* (actors, options) {
+    const sql = yield* SqlClient.SqlClient;
+    const found = [];
+    for (const target of yield* adoptionTargets(actors, options.only).pipe(Effect.flatMap((targets) => writable(targets, options.only)))) {
+        const since = options.sinceMs ?? 0;
+        const rows = yield* sql `
+      SELECT session_user_name, application_name, operation, in_turn, allowed,
+        count(*)::text AS statements, sum(rows)::text AS rows,
+        min(observed_at_ms)::text AS first_seen, max(observed_at_ms)::text AS last_seen
+      FROM actor_adoption_writes
+      WHERE table_schema = ${target.schema} AND table_name = ${target.table}
+        AND observed_at_ms >= ${since}
+      GROUP BY session_user_name, application_name, operation, in_turn, allowed
+      ORDER BY in_turn, session_user_name, application_name, operation`;
+        for (const row of rows)
+            found.push({
+                table: qualifiedName(target),
+                sessionUser: row.session_user_name,
+                applicationName: row.application_name,
+                operation: row.operation,
+                inTurn: row.in_turn,
+                allowed: row.allowed,
+                statements: Number(row.statements),
+                rows: Number(row.rows),
+                firstSeenMs: Number(row.first_seen),
+                lastSeenMs: Number(row.last_seen),
+            });
+        if (options.clear === true)
+            yield* sql `DELETE FROM actor_adoption_writes
+        WHERE table_schema = ${target.schema} AND table_name = ${target.table}
+          AND observed_at_ms >= ${since}`;
+    }
+    return found;
+});
+/** One line of `observe --report`: who wrote, how often, and whether the runtime's own turns did. */
+export const formatObservedWriter = (writer) => `${writer.table}  ${writer.inTurn ? "turn " : writer.allowed ? "allow" : "legacy"}  ${writer.sessionUser}  ${writer.applicationName === "" ? "(no application_name)" : writer.applicationName}  ${writer.operation}  ${writer.statements} statements, ${writer.rows} rows  first ${DateTime.formatIso(DateTime.makeUnsafe(writer.firstSeenMs))}  last ${DateTime.formatIso(DateTime.makeUnsafe(writer.lastSeenMs))}`;

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

@@ -0,0 +1,45 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import { type AdoptionTarget } from "./target.ts";
+/** What `durable adopt plan` reports for one table; it changes nothing. */
+export interface AdoptionPlan {
+    readonly table: string;
+    readonly actor: string;
+    readonly access: "write" | "read";
+    /** Reasons the table cannot be adopted as declared; observe and enforce refuse while any remain. */
+    readonly problems: ReadonlyArray<string>;
+    /** Conditions the operator should know about that do not stop adoption. */
+    readonly warnings: ReadonlyArray<string>;
+    readonly foreignKeys: ReadonlyArray<string>;
+    readonly triggers: ReadonlyArray<string>;
+    readonly rules: ReadonlyArray<string>;
+    readonly views: ReadonlyArray<string>;
+    readonly owner: string;
+    /** Roles holding a write privilege, which `enforce` revokes except for the writer and `--allow` roles. */
+    readonly writers: ReadonlyArray<string>;
+    /** The statement that adds the index every scoped statement needs, or undefined when one exists. */
+    readonly indexSql: string | undefined;
+    /** The SQL each later step would run. */
+    readonly steps: ReadonlyArray<string>;
+}
+/** `"schema"."table"`, quoted for the SQL the CLI prints and runs. */
+export declare const quotedTable: (target: Pick<AdoptionTarget, "schema" | "table">) => string;
+/** The index columns a scoped statement leads with: `routing_key` first when the runtime writes the table. */
+export declare const ownerIndexColumns: (target: Pick<AdoptionTarget, "access" | "tenantColumn" | "actorColumn">) => string[];
+/** The statement that adds an index leading with the mapped columns. */
+export declare const ownerIndexSql: (target: Pick<AdoptionTarget, "schema" | "table" | "access" | "tenantColumn" | "actorColumn">) => string;
+/**
+ * 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 declare const mappingProblems: (target: AdoptionTarget) => Effect.Effect<string[], import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** True when an index leading with the mapped columns exists, so scoped statements do not scan the table. */
+export declare const ownerIndexExists: (target: Pick<AdoptionTarget, "access" | "actorColumn" | "schema" | "table" | "tenantColumn">) => Effect.Effect<boolean, import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/**
+ * 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 declare const planAdoption: (actors: readonly WeakKey[], only?: string | undefined) => Effect.Effect<AdoptionPlan[], import("./target.ts").AdoptionRefused | import("effect/sql/SqlError").SqlError, SqlClient.SqlClient>;
+/** What `plan` prints: one block per table. */
+export declare const formatAdoptionPlan: (plan: AdoptionPlan) => string;