@rikalabs/akter 0.1.0-alpha.0

package/dist/tables/fleet.d.ts

@@ -0,0 +1,170 @@
+import { Stream } from "effect";
+import { InternalActors } from "../runtime/actors.ts";
+import type { ActorError } from "../errors/actor.ts";
+import { customType, pgTable, type PgTableWithColumns } from "drizzle-orm/pg-core";
+import { OWNERSHIP, type AnyOwnedTable, type Filter, type Ownership } from "./owned.ts";
+/** The aggregate functions a fleet view may select. */
+export type AggregateKind = "count" | "sum" | "avg" | "min" | "max";
+/** One selected aggregate: `Fleet.count()` or a function of one source column. */
+export interface Aggregate<Kind extends AggregateKind = AggregateKind, Key extends string = string> {
+    readonly kind: Kind;
+    readonly column: Key | undefined;
+}
+type SourceColumns<T extends AnyOwnedTable> = Omit<T["_"]["columns"], (typeof OWNERSHIP)[number]>;
+type Business<T extends AnyOwnedTable> = keyof SourceColumns<T> & string;
+type NumericKey<T extends AnyOwnedTable> = {
+    [K in Business<T>]: SourceColumns<T>[K]["_"]["data"] extends number | bigint ? K : never;
+}[Business<T>];
+type ColumnData<T extends AnyOwnedTable, K extends string> = K extends Business<T> ? SourceColumns<T>[K]["_"]["data"] : never;
+type Builder<X> = ReturnType<ReturnType<typeof customType<{
+    data: X;
+    notNull: true;
+}>>>;
+type NullableBuilder<X> = ReturnType<ReturnType<typeof customType<{
+    data: X;
+}>>>;
+type AggregateBuilder<T extends AnyOwnedTable, A> = A extends Aggregate<"count" | "sum" | "avg", string> ? Builder<number> : A extends Aggregate<"min" | "max", infer K> ? NullableBuilder<ColumnData<T, K>> : never;
+/** The columns of a view's derived table, as Drizzle builders. */
+export type DerivedColumns<T extends AnyOwnedTable, G extends ReadonlyArray<string>, S extends Record<string, Aggregate>> = {
+    readonly tenant_id: Builder<string>;
+} & {
+    readonly [K in G[number]]: Builder<ColumnData<T, K>>;
+} & {
+    readonly [K in keyof S]: AggregateBuilder<T, S[K]>;
+} & {
+    readonly as_of: Builder<string>;
+};
+/** A view's derived table: `tenant_id`, the group columns, the aggregates, and `as_of`. */
+export type DerivedTable<Name extends string, T extends AnyOwnedTable, G extends ReadonlyArray<string>, S extends Record<string, Aggregate>> = PgTableWithColumns<{
+    name: Name;
+    schema: T["_"]["schema"];
+    columns: ReturnType<typeof pgTable<Name, DerivedColumns<T, G, S>>>["_"]["columns"];
+    dialect: "pg";
+    isAlias: false;
+}>;
+/** What the maintainer needs to know about one selected aggregate. */
+export interface SelectedAggregate {
+    readonly key: string;
+    readonly kind: AggregateKind;
+    /** The source column's SQL name, or undefined for `count`. */
+    readonly column: string | undefined;
+}
+/** A value as it travels in a fleet page's JSON: dates as ISO strings, bigints as numbers. */
+type JsonValue<X> = X extends Date ? string : X extends bigint ? number : X;
+type AggregateValue<T extends AnyOwnedTable, A> = A extends Aggregate<"count" | "sum" | "avg", string> ? number : A extends Aggregate<"min" | "max", infer K> ? JsonValue<ColumnData<T, K>> | null : never;
+/** One group of a fleet page: its group keys and its aggregates. */
+export type FleetRow<V extends AnyFleetView> = V extends FleetView<string, infer T, infer G, infer S> ? {
+    readonly [K in G[number]]: JsonValue<ColumnData<T, K>>;
+} & {
+    readonly [K in keyof S]: AggregateValue<T, S[K]>;
+} : never;
+/**
+ * One page of a fleet subscription: the caller's tenant's groups in
+ * group-key order, `asOf` the change-feed position the view has applied
+ * (comparable with a command's `durable-version`: once `asOf` is at least the
+ * token, the view has seen that command), and `stale` while the view is
+ * building or has stopped advancing.
+ */
+export interface FleetPage<Row> {
+    readonly asOf: string | null;
+    readonly stale: boolean;
+    readonly rows: ReadonlyArray<Row>;
+}
+/** Equality filters on a view's group keys. */
+export type FleetFilter<V extends AnyFleetView> = {
+    readonly [K in V["groupBy"][number]]?: string | number | boolean;
+};
+/** Options of one fleet subscription. */
+export interface FleetOptions {
+    /** The most groups a page holds: default 100, at most 1,000. */
+    readonly limit?: number;
+}
+/** A declared fleet view: one group-by over one owned table, kept in `table`. */
+export interface FleetView<Name extends string = string, T extends AnyOwnedTable = AnyOwnedTable, G extends ReadonlyArray<string> = ReadonlyArray<string>, S extends Record<string, Aggregate> = Record<string, Aggregate>> {
+    readonly name: Name;
+    readonly from: T;
+    readonly source: Ownership;
+    readonly where: Filter<T> | undefined;
+    /** Group column keys of `from`, in key order. */
+    readonly groupBy: G;
+    /** Group column SQL names, in key order. */
+    readonly groupColumns: ReadonlyArray<string>;
+    /** The source's SQL names of its tenant and routing key columns. */
+    readonly tenantColumn: string;
+    readonly routingColumn: string;
+    readonly select: S;
+    readonly aggregates: ReadonlyArray<SelectedAggregate>;
+    readonly table: DerivedTable<`fleet_${string}`, T, G, S>;
+    /** The derived table's name, qualified by its schema when it has one. */
+    readonly tableName: string;
+    /** Changes when anything that decides the view's rows changes. */
+    readonly definitionHash: string;
+}
+/** Any fleet view, whatever its source and selection. */
+export type AnyFleetView = FleetView<string, any, any, any>;
+/**
+ * Declares a fleet view: `groupBy` over the rows of one owned table that
+ * `where` admits, with `tenant_id` always the first group key, so a view
+ * never aggregates across tenants. The runtime maintains its rows in `table`,
+ * named `fleet_<snake_case name>` in the source's schema, which the application
+ * adds to its drizzle-kit schema like an owned table.
+ *
+ * Throws for a name that is not PascalCase, a source that is not an owned
+ * table, an unknown or nullable group column (a primary key cannot hold
+ * null), an ownership column, an empty or overlapping selection, `sum` over a
+ * non-integer column, and `avg` over a non-numeric one.
+ *
+ * @example
+ * const OrdersByStatus = Fleet.view("OrdersByStatus", {
+ *   from: OrderRows,
+ *   where: { archived: false },
+ *   groupBy: ["status"],
+ *   select: { orders: Fleet.count(), total: Fleet.sum("amountCents") },
+ * })
+ */
+declare const view: <const Name extends string, T extends AnyOwnedTable, const G extends ReadonlyArray<Business<T>>, const S extends Record<string, Aggregate<AggregateKind, Business<T>>>>(name: Name, definition: {
+    readonly from: T;
+    readonly where?: Filter<T>;
+    readonly groupBy: G;
+    readonly select: S & { readonly [K in keyof S]: S[K] extends Aggregate<"sum" | "avg", infer Key> ? Aggregate<S[K]["kind"], Key & NumericKey<T>> : S[K]; };
+}) => FleetView<Name, T, G, S>;
+/** Counts the group's rows. */
+declare const count: () => Aggregate<"count", never>;
+/** Sums an integer column into a bigint; a sum past its range poisons the view. */
+declare const sum: <const K extends string>(column: K) => Aggregate<"sum", K>;
+/** Averages a numeric column as double precision. */
+declare const avg: <const K extends string>(column: K) => Aggregate<"avg", K>;
+/** The smallest value of a column, in the column's own type. */
+declare const min: <const K extends string>(column: K) => Aggregate<"min", K>;
+/** The largest value of a column, in the column's own type. */
+declare const max: <const K extends string>(column: K) => Aggregate<"max", K>;
+/**
+ * Follows `view` for the ambient tenant as the ambient caller: its current
+ * page, then a page each time the view changed and the page differs. It is
+ * authorized like a served subscription, with `kind: "fleet"`, and ends
+ * `Unauthorized` once reauthorization is refused. It needs the runtime that
+ * registered the view.
+ */
+declare const subscribe: <V extends AnyFleetView>(view: V, filter?: FleetFilter<V>, options?: FleetOptions) => Stream.Stream<FleetPage<FleetRow<V>>, ActorError, InternalActors>;
+/**
+ * Fleet reads: declared views over one owned table of a tenant-placed actor
+ * type, grouped by tenant first and maintained from the change feed, outside
+ * every turn.
+ */
+export declare const Fleet: {
+    /** Follows a view for the ambient tenant; see `subscribe`. */
+    subscribe: typeof subscribe;
+    /** Declares a fleet view; see `view`. */
+    view: typeof view;
+    /** Counts a group's rows. */
+    count: typeof count;
+    /** Sums an integer column. */
+    sum: typeof sum;
+    /** Averages a numeric column. */
+    avg: typeof avg;
+    /** The smallest value of a column. */
+    min: typeof min;
+    /** The largest value of a column. */
+    max: typeof max;
+};
+export {};

package/dist/tables/fleet.js

@@ -0,0 +1,214 @@
+import { getTableColumns, sql } from "drizzle-orm";
+import { sha256Bytes } from "../identity/digest.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+import { Effect, Predicate, Schema, Stream } from "effect";
+import { FLEET_PAGE_DEFAULT, FleetPageJson, fleetFilterText } from "../client/fleet-page.js";
+import { InternalActors } from "../runtime/actors.js";
+import { CurrentCaller, Tenant } from "../identity/caller.js";
+import { bigint, customType, doublePrecision, numeric, pgPolicy, pgSchema, pgTable, primaryKey, text, } from "drizzle-orm/pg-core";
+import { OWNERSHIP, ownership } from "./owned.js";
+const decodeResult = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Struct({ value: FleetPageJson })));
+const INTEGER = new Set(["smallint", "integer", "bigint"]);
+const NUMERIC = new Set(["smallint", "integer", "bigint", "real", "double precision", "numeric"]);
+const NAME = /^[A-Z][A-Za-z0-9]{0,47}$/;
+const RESERVED = new Set(["tenant_id", "as_of"]);
+const snake = (name) => name.replace(/(?<!^)([A-Z])/g, "_$1").toLowerCase();
+/** Canonical JSON for the definition hash: sorted keys, and bigints and dates as tagged strings. */
+const canonical = (value) => {
+    if (Predicate.isBigInt(value))
+        return JSON.stringify(`${value}n`);
+    if (Predicate.isDate(value))
+        return JSON.stringify(`date:${value.toISOString()}`);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (Predicate.isObject(value))
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    return JSON.stringify(value ?? null);
+};
+const cloneColumn = (column, name) => customType({
+    dataType: () => column.getSQLType(),
+    fromDriver: (value) => column.mapFromDriverValue(value),
+    toDriver: (value) => column.mapToDriverValue(value),
+})(name);
+/**
+ * Declares a fleet view: `groupBy` over the rows of one owned table that
+ * `where` admits, with `tenant_id` always the first group key, so a view
+ * never aggregates across tenants. The runtime maintains its rows in `table`,
+ * named `fleet_<snake_case name>` in the source's schema, which the application
+ * adds to its drizzle-kit schema like an owned table.
+ *
+ * Throws for a name that is not PascalCase, a source that is not an owned
+ * table, an unknown or nullable group column (a primary key cannot hold
+ * null), an ownership column, an empty or overlapping selection, `sum` over a
+ * non-integer column, and `avg` over a non-numeric one.
+ *
+ * @example
+ * const OrdersByStatus = Fleet.view("OrdersByStatus", {
+ *   from: OrderRows,
+ *   where: { archived: false },
+ *   groupBy: ["status"],
+ *   select: { orders: Fleet.count(), total: Fleet.sum("amountCents") },
+ * })
+ */
+const view = (name, definition) => {
+    if (!NAME.test(name))
+        throw new Error(`Fleet view name ${name} is PascalCase, at most 48 characters`);
+    const source = ownership(definition.from);
+    if (source === undefined)
+        throw new Error(`Fleet view ${name} reads an Actor.table`);
+    const columns = getTableColumns(definition.from);
+    const reserved = OWNERSHIP;
+    const business = (key, role) => {
+        if (reserved.includes(key) || source.ownerKeys.includes(key) || !source.columns.includes(key))
+            throw new Error(`Fleet view ${name}: ${role} ${key} is not a business column of ${source.name}`);
+        return columns[key];
+    };
+    if (definition.groupBy.length === 0)
+        throw new Error(`Fleet view ${name} groups by at least one column`);
+    if (new Set(definition.groupBy).size !== definition.groupBy.length)
+        throw new Error(`Fleet view ${name} lists a group column twice`);
+    const groupColumns = definition.groupBy.map((key) => {
+        const column = business(key, "group column");
+        if (!column.notNull)
+            throw new Error(`Fleet view ${name}: group column ${key} must be NOT NULL`);
+        return column.name;
+    });
+    const selected = Object.entries(definition.select);
+    if (selected.length === 0)
+        throw new Error(`Fleet view ${name} selects at least one aggregate`);
+    const taken = new Set([...RESERVED, ...groupColumns, ...definition.groupBy]);
+    const aggregates = selected.map(([key, aggregate]) => {
+        if (taken.has(key) || !/^[a-z][a-z0-9_]*$/i.test(key))
+            throw new Error(`Fleet view ${name}: aggregate ${key} clashes with a column or is not a plain name`);
+        if (aggregate.kind === "count")
+            return { key, kind: "count", column: undefined };
+        const column = business(aggregate.column ?? "", `${aggregate.kind} column`);
+        const type = column.getSQLType().replace(/\(.*\)$/, "");
+        if (aggregate.kind === "sum" && !INTEGER.has(type))
+            throw new Error(`Fleet view ${name}: sum takes an integer column, not ${key} (${type})`);
+        if (aggregate.kind === "avg" && !NUMERIC.has(type))
+            throw new Error(`Fleet view ${name}: avg takes a numeric column, not ${key} (${type})`);
+        return { key, kind: aggregate.kind, column: column.name };
+    });
+    if (source.routingKey === undefined)
+        throw new Error(`Fleet view ${name} reads ${source.name}, adopted for reading only; a view recomputes by routing_key, so adopt it with access "write"`);
+    const tenantColumn = source.ownerColumns[source.ownerKeys.indexOf(source.tenantKey)];
+    const routingColumn = columns[source.routingKey].name;
+    const tableName = `fleet_${snake(name)}`;
+    const derived = {
+        tenant_id: text("tenant_id").notNull(),
+        ...Object.fromEntries(definition.groupBy.map((key, index) => [
+            key,
+            cloneColumn(columns[key], groupColumns[index]).notNull(),
+        ])),
+        ...Object.fromEntries(aggregates.map(({ key, kind, column }) => [
+            key,
+            kind === "count" || kind === "sum"
+                ? bigint(key, { mode: "number" }).notNull()
+                : kind === "avg"
+                    ? doublePrecision(key).notNull()
+                    : cloneColumn(columns[Object.keys(columns).find((k) => columns[k].name === column)], key),
+        ])),
+        as_of: numeric("as_of").notNull(),
+    };
+    const extra = (self) => {
+        const scoped = sql `tenant_id = current_setting('durable.tenant', true)`;
+        const [first, ...rest] = [self["tenant_id"], ...definition.groupBy.map((key) => self[key])];
+        return [
+            primaryKey({ columns: [first, ...rest] }),
+            pgPolicy("durable_tenant", { for: "all", using: scoped, withCheck: scoped }),
+        ];
+    };
+    const table = (source.schema === undefined
+        ? pgTable(tableName, derived, extra)
+        : pgSchema(source.schema).table(tableName, derived, extra));
+    const where = definition.where;
+    const definitionHash = bytesToHex(sha256Bytes(new TextEncoder().encode(canonical({
+        source: source.name,
+        owner: [routingColumn, tenantColumn],
+        where: (where ?? null),
+        groupBy: groupColumns,
+        select: aggregates.map(({ key, kind, column }) => ({ key, kind, column })),
+        table: tableName,
+    }))));
+    return {
+        name,
+        from: definition.from,
+        source,
+        where,
+        groupBy: definition.groupBy,
+        groupColumns,
+        tenantColumn,
+        routingColumn,
+        select: definition.select,
+        aggregates,
+        table,
+        tableName: source.schema === undefined ? tableName : `${source.schema}.${tableName}`,
+        definitionHash,
+    };
+};
+/** Counts the group's rows. */
+const count = () => ({ kind: "count", column: undefined });
+/** Sums an integer column into a bigint; a sum past its range poisons the view. */
+const sum = (column) => ({
+    kind: "sum",
+    column,
+});
+/** Averages a numeric column as double precision. */
+const avg = (column) => ({
+    kind: "avg",
+    column,
+});
+/** The smallest value of a column, in the column's own type. */
+const min = (column) => ({
+    kind: "min",
+    column,
+});
+/** The largest value of a column, in the column's own type. */
+const max = (column) => ({
+    kind: "max",
+    column,
+});
+/**
+ * Follows `view` for the ambient tenant as the ambient caller: its current
+ * page, then a page each time the view changed and the page differs. It is
+ * authorized like a served subscription, with `kind: "fleet"`, and ends
+ * `Unauthorized` once reauthorization is refused. It needs the runtime that
+ * registered the view.
+ */
+const subscribe = (view, filter = {}, options = {}) => Stream.unwrap(Effect.gen(function* () {
+    const actors = yield* InternalActors;
+    const results = yield* actors.fleet({
+        view: view.name,
+        caller: yield* CurrentCaller,
+        tenant: yield* Tenant,
+        filter: fleetFilterText(filter),
+        limit: options.limit ?? FLEET_PAGE_DEFAULT,
+        expiresAt: undefined,
+    });
+    return results.pipe(Stream.mapEffect(({ value }) => decodeResult(value).pipe(Effect.orDie, Effect.map(({ value: page }) => page))));
+}));
+/**
+ * Fleet reads: declared views over one owned table of a tenant-placed actor
+ * type, grouped by tenant first and maintained from the change feed, outside
+ * every turn.
+ */
+export const Fleet = {
+    /** Follows a view for the ambient tenant; see `subscribe`. */
+    subscribe,
+    /** Declares a fleet view; see `view`. */
+    view,
+    /** Counts a group's rows. */
+    count,
+    /** Sums an integer column. */
+    sum,
+    /** Averages a numeric column. */
+    avg,
+    /** The smallest value of a column. */
+    min,
+    /** The largest value of a column. */
+    max,
+};

package/dist/tables/owned.d.ts

@@ -0,0 +1,250 @@
+import { type InferInsertModel, type InferSelectModel } from "drizzle-orm";
+import { type AnyPgTable, type PgSelectConfig, type PgTableWithColumns } from "drizzle-orm/pg-core";
+import type { BuildColumns } from "drizzle-orm/column-builder";
+import type { RelationsOrder, TableFilter } from "drizzle-orm/relations";
+import type { EffectDrizzleQueryError } from "drizzle-orm/effect-core";
+import type { EffectPgDatabase } from "drizzle-orm/effect-postgres";
+import type { Effect, Option } from "effect";
+import type { ActorRef } from "../identity/caller.ts";
+import type { Placement } from "../runtime/storage/codec.ts";
+/** Ownership column keys, which are also their SQL names. */
+export declare const OWNERSHIP: readonly ["routing_key", "tenant_id", "actor_id"];
+type OwnershipKey = (typeof OWNERSHIP)[number];
+declare const ownershipColumns: () => {
+    routing_key: import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgBigInt64Builder>;
+    tenant_id: import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>;
+    actor_id: import("drizzle-orm/pg-core").SetNotNull<import("drizzle-orm/pg-core").PgTextBuilder<[string, ...string[]]>>;
+};
+type OwnershipColumns<Name extends string> = BuildColumns<Name, ReturnType<typeof ownershipColumns>, "pg">;
+declare const OwnedTypeId: unique symbol;
+declare const OwnedKeysId: unique symbol;
+declare const ReadOnlyId: unique symbol;
+declare const MappedColumnsId: unique symbol;
+/** How an actor type uses an owned table: `read` tables are never written by the runtime. */
+export type AdoptionAccess = "write" | "read";
+/** The column types an existing table's tenant and actor columns may have. */
+export type MappedKind = "text" | "uuid";
+/** What the framework knows about an owned table; aliases forward it. */
+export interface Ownership {
+    /** The table name, qualified by its schema when it has one. */
+    readonly name: string;
+    readonly schema: string | undefined;
+    readonly table: string;
+    /**
+     * The column keys of a row: business columns, and for an adopted table also
+     * its mapped tenant and actor columns, which are readable but never writable.
+     */
+    readonly columns: ReadonlyArray<string>;
+    /**
+     * Primary key column keys, in key order. An owned table's key excludes the
+     * ownership columns it is prefixed with; an adopted table's is the physical
+     * key as it already is.
+     */
+    readonly primaryKey: ReadonlyArray<string>;
+    /** The actor type listing this table; set once by `Actor.make`. */
+    owner: string | undefined;
+    /** True when the table existed before the framework and maps its own tenant and actor columns. */
+    readonly adopted: boolean;
+    readonly access: AdoptionAccess;
+    /** Drizzle keys of the ownership columns, which application code never reads or writes. */
+    readonly ownerKeys: ReadonlyArray<string>;
+    /** SQL names of the ownership columns, in the same order as `ownerKeys`. */
+    readonly ownerColumns: ReadonlyArray<string>;
+    /** The key of `routing_key`; a read-only adopted table has none. */
+    readonly routingKey: string | undefined;
+    readonly tenantKey: string;
+    readonly actorKey: string;
+    readonly tenantKind: MappedKind;
+    readonly actorKind: MappedKind;
+    /** The owning actor type's placement; set with `owner`. */
+    placement: Placement | undefined;
+}
+/**
+ * A Drizzle table owned by one actor type. Every row carries the trusted
+ * `routing_key`, `tenant_id`, and `actor_id` of the actor that wrote it, and
+ * every primary key, unique constraint, and index leads with them.
+ */
+export type OwnedTable<T extends AnyPgTable> = PgTableWithColumns<{
+    name: T["_"]["name"];
+    schema: T["_"]["schema"];
+    columns: T["_"]["columns"] & OwnershipColumns<T["_"]["name"]>;
+    dialect: "pg";
+    isAlias: false;
+}> & {
+    readonly [OwnedTypeId]: Ownership;
+    readonly [OwnedKeysId]: OwnershipKey;
+};
+/** The columns of an existing table that can name its owner: any column of `T`. */
+export interface OwnerColumns<T extends AnyPgTable> {
+    readonly tenant: T["_"]["columns"][keyof T["_"]["columns"]];
+    readonly actor: T["_"]["columns"][keyof T["_"]["columns"]];
+}
+declare const routingColumn: () => {
+    routing_key: import("drizzle-orm/pg-core").PgBigInt64Builder;
+};
+type RoutingColumn<Name extends string> = BuildColumns<Name, ReturnType<typeof routingColumn>, "pg">;
+/**
+ * An existing table an actor type owns rows of. Its keys, constraints, and
+ * indexes are untouched; it gains one nullable `routing_key`, and the mapped
+ * tenant and actor columns are ownership columns the turn supplies.
+ */
+export type AdoptedTable<T extends AnyPgTable, Mapped> = PgTableWithColumns<{
+    name: T["_"]["name"];
+    schema: T["_"]["schema"];
+    columns: T["_"]["columns"] & RoutingColumn<T["_"]["name"]>;
+    dialect: "pg";
+    isAlias: false;
+}> & {
+    readonly [OwnedTypeId]: Ownership;
+    readonly [OwnedKeysId]: "routing_key";
+    readonly [MappedColumnsId]: Mapped;
+};
+/** An existing table adopted for reading only: unchanged, with no mutation methods in any turn or query. */
+export type ReadAdoptedTable<T extends AnyPgTable, Mapped> = T & {
+    readonly [OwnedTypeId]: Ownership;
+    readonly [OwnedKeysId]: never;
+    readonly [MappedColumnsId]: Mapped;
+    readonly [ReadOnlyId]: true;
+};
+type Same<A, B> = (<X>() => X extends A ? 1 : 2) extends <X>() => (X extends B ? 1 : 2) ? true : false;
+/**
+ * The columns of an adopted table that look like a mapped column. Types
+ * cannot tell which property a column object came from, so a column shaped
+ * exactly like the tenant or actor column is treated as possibly mapped: its
+ * insert is optional in the type, and the database refuses a missing value.
+ */
+type MappedLookalikes<T extends AnyOwnedTable> = T extends {
+    readonly [MappedColumnsId]: infer M;
+} ? {
+    [K in keyof T["_"]["columns"] & string]: Same<T["_"]["columns"][K], M> extends true ? K : never;
+}[keyof T["_"]["columns"] & string] : never;
+/** Any owned table, whatever its columns. */
+export type AnyOwnedTable = AnyPgTable & {
+    readonly [OwnedTypeId]: Ownership;
+};
+type OwnedKeys<T extends AnyOwnedTable> = T extends {
+    readonly [OwnedKeysId]: infer K;
+} ? K & string : OwnershipKey;
+type BusinessColumns<T extends AnyOwnedTable> = Omit<T["_"]["columns"], OwnedKeys<T>>;
+/**
+ * A row as application code reads it: business columns only. An adopted
+ * table's row also carries its mapped tenant and actor columns, which are
+ * read-only.
+ */
+export type Row<T extends AnyOwnedTable> = Omit<InferSelectModel<T>, OwnedKeys<T>>;
+/**
+ * A row as application code writes it: business columns only. The mapped
+ * columns of an adopted table come from the turn and are rejected when set.
+ */
+export type Insert<T extends AnyOwnedTable> = Omit<InferInsertModel<T>, OwnedKeys<T> | MappedLookalikes<T>> & Partial<Pick<InferInsertModel<T>, MappedLookalikes<T> & keyof InferInsertModel<T>>>;
+/** What a turn's `rows` returns for `T`: rows of a read-adopted table have no mutation methods. */
+export type TurnRows<T extends AnyOwnedTable> = T extends {
+    readonly [ReadOnlyId]: true;
+} ? ScopedRead<T> : ScopedRows<T>;
+/** Drizzle's object filter over business columns; `RAW` SQL is not supported. */
+export type Filter<T extends AnyOwnedTable> = Omit<TableFilter<T, BusinessColumns<T>>, "RAW">;
+/** Drizzle's ordering over business columns. */
+export type Order<T extends AnyOwnedTable> = RelationsOrder<BusinessColumns<T>>;
+/** Options for reading one row: a filter and an ordering, both over business columns. */
+export interface ReadOptions<T extends AnyOwnedTable> {
+    readonly where?: Filter<T>;
+    readonly orderBy?: Order<T>;
+}
+/** Options for reading many rows: a filter, an ordering, and a page. */
+export interface ListOptions<T extends AnyOwnedTable> extends ReadOptions<T> {
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** Read-only access to the current actor's rows of one owned table. */
+export interface ScopedRead<T extends AnyOwnedTable> {
+    /** The first row matching `options`, or none. */
+    readonly one: (options?: ReadOptions<T>) => Effect.Effect<Option.Option<Row<T>>>;
+    /** Every matching row, at most `limit` after skipping `offset`. */
+    readonly all: (options?: ListOptions<T>) => Effect.Effect<ReadonlyArray<Row<T>>>;
+    /** The number of matching rows. */
+    readonly count: (options?: {
+        readonly where?: Filter<T>;
+    }) => Effect.Effect<number>;
+}
+/** A mutation that runs once it is given its filter; `{}` matches every row of the actor. */
+export interface Filtered<T extends AnyOwnedTable> {
+    readonly where: (filter: Filter<T>) => Effect.Effect<void>;
+}
+/** Turn-bound access to the current actor's rows; writes commit or roll back with the turn. */
+export interface ScopedRows<T extends AnyOwnedTable> extends ScopedRead<T> {
+    /** Inserts one row or a list of rows. */
+    readonly insert: (values: Insert<T> | ReadonlyArray<Insert<T>>) => Effect.Effect<void>;
+    /** Inserts, or on a primary key conflict updates the supplied non-key columns. */
+    readonly upsert: (values: Insert<T> | ReadonlyArray<Insert<T>>) => Effect.Effect<void>;
+    /** Sets `values` on the rows the returned filter matches. */
+    readonly update: (values: Partial<Insert<T>>) => Filtered<T>;
+    /** Deletes the rows the returned filter matches. */
+    readonly delete: () => Filtered<T>;
+}
+/** The read-only Drizzle surface a group query is built from. */
+export type GroupDatabase = Pick<EffectPgDatabase, "select" | "selectDistinct">;
+/**
+ * Read-only joins across the owned rows of every actor sharing this actor's
+ * placement group. The framework adds the group predicate to the base table
+ * and to every inner or left join.
+ */
+export type Group = <A>(build: (database: GroupDatabase) => Effect.Effect<A, EffectDrizzleQueryError>) => Effect.Effect<A>;
+/** Who the rows belong to and how long a bound capability lives. */
+export interface TableScope {
+    readonly ref: ActorRef;
+    readonly placement: Placement;
+    /** The tables the actor type declares; `rows` refuses any other. */
+    readonly tables: ReadonlyArray<AnyOwnedTable>;
+    /** Dies once the capability is used outside the turn or query that received it. */
+    readonly guard: Effect.Effect<void>;
+    /** Told the name of each table or blob a mutation of this turn changed, once it succeeds. */
+    readonly wrote?: ((name: string) => void) | undefined;
+}
+/** The table capabilities of one turn or query. */
+export interface TableAccess {
+    /** Turn-bound access returns the full `ScopedRows`; read access only `ScopedRead`. */
+    readonly rows: (table: AnyOwnedTable) => ScopedRead<AnyOwnedTable>;
+    readonly group: Group;
+}
+/** The ownership of `table`, or undefined when it is not an owned table. */
+export declare const ownership: (table: PgSelectConfig["table"]) => Ownership | undefined;
+/** Options that adopt an existing table: the columns holding the tenant and the actor's key. */
+export interface AdoptOptions<T extends AnyPgTable, O extends OwnerColumns<T>> {
+    readonly owner: O;
+    /** `"read"` adopts the table for reading only; the runtime then adds no column and no guard. */
+    readonly access?: AdoptionAccess;
+}
+/** What `Actor.table` returns: a new owned table, or the existing table adopted with `owner`. */
+export type Declared<T extends AnyPgTable, O extends OwnerColumns<T> | undefined, A extends AdoptionAccess | undefined> = O extends OwnerColumns<T> ? A extends "read" ? ReadAdoptedTable<T, O["tenant"] | O["actor"]> : AdoptedTable<T, O["tenant"] | O["actor"]> : OwnedTable<T>;
+/**
+ * Declares an actor-owned Drizzle table. The table gains `routing_key`,
+ * `tenant_id`, and `actor_id` columns; its primary key, unique constraints, and
+ * indexes are prefixed with them, so drizzle-kit generates keys that are
+ * unique per actor and scans that stay on one shard. Each table also carries
+ * the `durable_tenant` row-level-security policy: the table owner is exempt,
+ * and a runtime with row-level security sees only each transaction's tenant.
+ *
+ * Throws for anything but a `pgTable`, an alias, an already owned table, a
+ * table with a reserved ownership column, a table without a primary key, or a
+ * foreign key, which would cross actors and need ownership columns on both
+ * sides. Column-level `primaryKey` and `unique` would be global, so they move
+ * into the prefixed extra config. Only btree indexes are accepted: other
+ * methods cannot lead with the bigint and text ownership prefix.
+ *
+ * With `owner`, adopts a table that already exists and other code writes: its
+ * `tenant` and `actor` columns, which must be text, varchar, or uuid, hold the
+ * tenant and the actor's key, and nothing else about the table changes, so
+ * foreign keys stay. A writable adopted table gains a nullable `routing_key`
+ * and starts only after `durable adopt observe`; its primary key stays global,
+ * so a key another actor already holds fails the turn. `access: "read"` maps
+ * the two columns for reading and adds nothing.
+ *
+ * @example
+ * const Notes = Actor.table(pgTable("notes", { id: text("id").primaryKey(), body: text("body") }))
+ * const Invoices = Actor.table(invoices, { owner: { tenant: invoices.orgId, actor: invoices.accountId } })
+ */
+export declare const table: <T extends AnyPgTable, const O extends OwnerColumns<T> | undefined = undefined, const A extends AdoptionAccess | undefined = undefined>(source: T, ...adoption: readonly [] | readonly [{
+    readonly owner: O;
+    readonly access?: A;
+}]) => Declared<T, O, A>;
+export {};