@ultimat3/entity 0.0.1 → 1.0.0

package/src/repo.js

@@ -0,0 +1,203 @@
+// The repository seam. Two rules are structural rather than advisory:
+//
+//  1. `tx` is an explicit parameter on every write, so the transactional outbox can join the
+//     request's transaction instead of opening its own and losing atomicity.
+//  2. Pagination is cursor-only. OFFSET is wrong under concurrent writes: a row inserted or
+//     deleted before the offset shifts every later page, so a client paging through a live
+//     table silently skips and repeats rows. A keyset cursor is stable because it names a
+//     position in the sort order, not a row count.
+import { invariantViolated, notFound } from './errors';
+import { assertScoped } from './tenancy';
+export const encodeCursor = (key, id) => btoa(JSON.stringify({ k: key, id }));
+export const decodeCursor = (cursor) => {
+    try {
+        const parsed = JSON.parse(atob(cursor));
+        return typeof parsed.k === 'string' && typeof parsed.id === 'string'
+            ? { key: parsed.k, id: parsed.id }
+            : null;
+    }
+    catch {
+        return null;
+    }
+};
+const field = (row, property) => typeof row === 'object' && row !== null ? row[property] : undefined;
+const matches = (row, predicate) => {
+    const actual = field(row, predicate.column);
+    switch (predicate.op) {
+        case 'eq':
+            return actual === predicate.value;
+        case 'neq':
+            return actual !== predicate.value;
+        case 'in':
+            return Array.isArray(predicate.value) && predicate.value.includes(actual);
+        case 'gt':
+            return compare(actual, predicate.value) > 0;
+        case 'gte':
+            return compare(actual, predicate.value) >= 0;
+        case 'lt':
+            return compare(actual, predicate.value) < 0;
+        case 'lte':
+            return compare(actual, predicate.value) <= 0;
+        case 'like':
+            return String(actual).includes(String(predicate.value).replaceAll('%', ''));
+        case 'is-null':
+            return actual === null || actual === undefined;
+        case 'is-not-null':
+            return actual !== null && actual !== undefined;
+    }
+};
+const compare = (left, right) => {
+    if (left instanceof Date && right instanceof Date)
+        return left.getTime() - right.getTime();
+    if (typeof left === 'number' && typeof right === 'number')
+        return left - right;
+    if (typeof left === 'bigint' && typeof right === 'bigint') {
+        return left < right ? -1 : left > right ? 1 : 0;
+    }
+    const [a, b] = [String(left), String(right)];
+    return a < b ? -1 : a > b ? 1 : 0;
+};
+const sortKey = (row, plan) => plan.orderBy
+    .map((entry) => {
+    const value = field(row, entry.column);
+    return value instanceof Date ? value.toISOString() : String(value);
+})
+    .join(' ');
+/**
+ * The default driver: correct semantics, no database. `x dev` uses it before the first
+ * migration and tests use it everywhere. Postgres is the production driver and implements
+ * this same interface.
+ */
+export const memoryRepo = (entity, seed = []) => {
+    const keyOf = (row) => entity.$primaryKey.map((property) => String(field(row, property))).join('
');
+    const rows = new Map(seed.map((row) => [keyOf(row), row]));
+    const singleKey = (operation) => {
+        const [only] = entity.$primaryKey;
+        if (entity.$primaryKey.length !== 1 || only === undefined) {
+            throw invariantViolated(entity.$name, operation, `${entity.$name} has a composite primary key (${entity.$primaryKey.join(', ')}) — ` +
+                'use findMany({ where }) instead of an id');
+        }
+        return only;
+    };
+    const planFor = (args) => {
+        const scoped = args.orgId === undefined || entity.$tenantColumn === null
+            ? []
+            : [{ column: entity.$tenantColumn, op: 'eq', value: args.orgId }];
+        const ordered = args.orderBy ?? [];
+        return {
+            entity: entity.$name,
+            where: [...(args.where ?? []), ...scoped],
+            // The primary key is always the final sort key: a cursor needs a total order, or two
+            // rows with the same sort value straddle a page boundary.
+            orderBy: [
+                ...ordered,
+                ...entity.$primaryKey
+                    .filter((property) => !ordered.some((entry) => entry.column === property))
+                    .map((property) => ({ column: property, direction: 'asc' })),
+            ],
+            limit: args.limit ?? 50,
+            ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
+            ...(args.select === undefined ? {} : { select: args.select }),
+        };
+    };
+    const select = (args, operation) => {
+        const plan = planFor(args);
+        assertScoped(entity.$name, entity.$tenantColumn, operation, plan);
+        const visible = (row) => !entity.$softDelete ||
+            args.includeDeleted === true ||
+            field(row, 'deletedAt') === null ||
+            field(row, 'deletedAt') === undefined;
+        const found = [...rows.values()]
+            .filter((row) => plan.where.every((predicate) => matches(row, predicate)))
+            .filter(visible)
+            .sort((left, right) => {
+            for (const entry of plan.orderBy) {
+                const order = compare(field(left, entry.column), field(right, entry.column));
+                if (order !== 0)
+                    return entry.direction === 'desc' ? -order : order;
+            }
+            return 0;
+        });
+        return { plan, found };
+    };
+    const write = (row, options) => {
+        entity.$assert(row);
+        const key = keyOf(row);
+        const previous = rows.get(key);
+        options?.tx?.onRollback(() => {
+            if (previous === undefined)
+                rows.delete(key);
+            else
+                rows.set(key, previous);
+        });
+        rows.set(key, row);
+        return row;
+    };
+    const byId = (id) => {
+        const current = rows.get(id);
+        if (current === undefined)
+            throw notFound(entity.$name, id);
+        return current;
+    };
+    // Every method is async: a repository call that fails must reject, never throw
+    // synchronously, or half the call sites would need two error paths.
+    return {
+        async findById(id, options) {
+            const property = singleKey('findById');
+            const { found } = select({ ...options, where: [{ column: property, op: 'eq', value: id }] }, 'findById');
+            return found[0] ?? null;
+        },
+        async findMany(args = {}) {
+            const { plan, found } = select(args, 'findMany');
+            const decoded = plan.cursor === undefined ? null : decodeCursor(plan.cursor);
+            const start = decoded === null ? 0 : found.findIndex((row) => keyOf(row) === decoded.id) + 1;
+            const page = found.slice(start, start + plan.limit);
+            const last = page.at(-1);
+            const more = start + page.length < found.length;
+            return {
+                rows: page,
+                nextCursor: more && last !== undefined ? encodeCursor(sortKey(last, plan), keyOf(last)) : null,
+            };
+        },
+        async insert(values, options) {
+            return write(values, options);
+        },
+        async update(id, patch, options) {
+            singleKey('update');
+            return write(Object.assign({}, byId(id), patch), options);
+        },
+        async delete(id, options) {
+            singleKey('delete');
+            const current = byId(id);
+            // Soft delete hides the row without losing it; the column's presence is the switch.
+            if (entity.$softDelete) {
+                write(Object.assign({}, current, { deletedAt: new Date() }), options);
+                return;
+            }
+            const key = keyOf(current);
+            options?.tx?.onRollback(() => rows.set(key, current));
+            rows.delete(key);
+        },
+        async count(args = {}) {
+            return select(args, 'count').found.length;
+        },
+    };
+};
+let txCounter = 0;
+/** In-memory transactor: undo closures registered by drivers run on failure. */
+export const memoryTransactor = () => ({
+    async run(work) {
+        const undos = [];
+        txCounter += 1;
+        const tx = { id: `tx-${txCounter}`, onRollback: (undo) => undos.push(undo) };
+        try {
+            return await work(tx);
+        }
+        catch (error) {
+            for (const undo of undos.reverse())
+                undo();
+            throw error;
+        }
+    },
+});
+//# sourceMappingURL=repo.js.map

package/src/repo.js.map

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

package/src/seed.d.ts

@@ -0,0 +1,20 @@
+import type { Driver } from './database';
+import type { EntityCore } from './entity';
+import type { ColumnMap, Insertable } from './types';
+/** RFC 4122 v5: SHA-1 of namespace + name, with the version and variant bits pinned. */
+export declare const seedId: (label: string) => string;
+export interface SeedContext {
+    insert<Row, C extends ColumnMap>(entity: EntityCore<Row, C>, rows: readonly Insertable<C>[]): Promise<void>;
+    /** Deterministic id for a label. Same label, same uuid, every run. */
+    id(label: string): string;
+}
+export interface SeedOptions {
+    /** Defaults to a fresh in-memory driver, so a seed runs with no database at all. */
+    readonly driver?: Driver;
+}
+export interface Seed {
+    readonly name: string;
+    run(options?: SeedOptions): Promise<void>;
+}
+export declare const defineSeed: (name: string, build: (context: SeedContext) => Promise<void>) => Seed;
+//# sourceMappingURL=seed.d.ts.map

package/src/seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["seed.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAQrD,wFAAwF;AACxF,eAAO,MAAM,MAAM,UAAW,MAAM,KAAG,MAiBtC,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,SAAS,EAC7B,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,EAC1B,IAAI,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAC7B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,sEAAsE;IACtE,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,eAAO,MAAM,UAAU,SAAU,MAAM,SAAS,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,KAAG,IAYxF,CAAC"}

package/src/seed.js

@@ -0,0 +1,43 @@
+// A seed is the fixture graph, written once and replayed anywhere. `id('post:tenancy')` is a
+// UUID v5 of the label, so the same row gets the same id on every machine and a bug reproduced
+// locally reproduces in CI. Rows go through `entity.$parse` and the invariants, which makes a
+// seed a test of the schema as well as data for one.
+import { createHash } from 'node:crypto';
+import { memoryDriver } from './database';
+/** Framework namespace for seed labels. Fixed forever: changing it moves every seeded id. */
+const NAMESPACE = 'a3c1f0d6-5c2b-4a3e-9f1b-6d4e7c8a9b02';
+const bytesOf = (uuid) => Uint8Array.from((uuid.replaceAll('-', '').match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
+/** RFC 4122 v5: SHA-1 of namespace + name, with the version and variant bits pinned. */
+export const seedId = (label) => {
+    const name = new TextEncoder().encode(label);
+    const input = new Uint8Array(16 + name.length);
+    input.set(bytesOf(NAMESPACE));
+    input.set(name, 16);
+    const digest = new Uint8Array(createHash('sha1').update(input).digest());
+    const bytes = digest.slice(0, 16);
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join('-');
+};
+export const defineSeed = (name, build) => ({
+    name,
+    run: async (options = {}) => {
+        const driver = options.driver ?? memoryDriver();
+        await build({
+            insert: async (entity, rows) => {
+                const repo = driver.repo(entity);
+                for (const row of rows)
+                    await repo.insert(entity.$parse(row));
+            },
+            id: seedId,
+        });
+    },
+});
+//# sourceMappingURL=seed.js.map

package/src/seed.js.map

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

package/src/seed.ts

@@ -0,0 +1,69 @@
+// A seed is the fixture graph, written once and replayed anywhere. `id('post:tenancy')` is a
+// UUID v5 of the label, so the same row gets the same id on every machine and a bug reproduced
+// locally reproduces in CI. Rows go through `entity.$parse` and the invariants, which makes a
+// seed a test of the schema as well as data for one.
+
+import { createHash } from 'node:crypto';
+import type { Driver } from './database';
+import { memoryDriver } from './database';
+import type { EntityCore } from './entity';
+import type { ColumnMap, Insertable } from './types';
+
+/** Framework namespace for seed labels. Fixed forever: changing it moves every seeded id. */
+const NAMESPACE = 'a3c1f0d6-5c2b-4a3e-9f1b-6d4e7c8a9b02';
+
+const bytesOf = (uuid: string): Uint8Array =>
+  Uint8Array.from((uuid.replaceAll('-', '').match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
+
+/** RFC 4122 v5: SHA-1 of namespace + name, with the version and variant bits pinned. */
+export const seedId = (label: string): string => {
+  const name = new TextEncoder().encode(label);
+  const input = new Uint8Array(16 + name.length);
+  input.set(bytesOf(NAMESPACE));
+  input.set(name, 16);
+  const digest = new Uint8Array(createHash('sha1').update(input).digest());
+  const bytes = digest.slice(0, 16);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+};
+
+export interface SeedContext {
+  insert<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    rows: readonly Insertable<C>[],
+  ): Promise<void>;
+  /** Deterministic id for a label. Same label, same uuid, every run. */
+  id(label: string): string;
+}
+
+export interface SeedOptions {
+  /** Defaults to a fresh in-memory driver, so a seed runs with no database at all. */
+  readonly driver?: Driver;
+}
+
+export interface Seed {
+  readonly name: string;
+  run(options?: SeedOptions): Promise<void>;
+}
+
+export const defineSeed = (name: string, build: (context: SeedContext) => Promise<void>): Seed => ({
+  name,
+  run: async (options = {}) => {
+    const driver = options.driver ?? memoryDriver();
+    await build({
+      insert: async (entity, rows) => {
+        const repo = driver.repo(entity);
+        for (const row of rows) await repo.insert(entity.$parse(row));
+      },
+      id: seedId,
+    });
+  },
+});

package/src/tenancy.d.ts

@@ -0,0 +1,41 @@
+import type { ColumnMap } from './types';
+export type Operator = 'eq' | 'neq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'is-null' | 'is-not-null';
+export interface Predicate {
+    readonly column: string;
+    readonly op: Operator;
+    readonly value?: unknown;
+}
+export type SortDirection = 'asc' | 'desc';
+export interface SortKey {
+    readonly column: string;
+    readonly direction: SortDirection;
+}
+export interface QueryPlan {
+    readonly entity: string;
+    readonly where: readonly Predicate[];
+    readonly orderBy: readonly SortKey[];
+    readonly limit: number;
+    /** Keyset position. There is no `offset` and there will not be one — see `repo.ts`. */
+    readonly cursor?: string;
+    readonly select?: readonly string[];
+}
+/** The property key a tenant column takes when it is not marked explicitly. */
+export declare const ORG_COLUMN = "orgId";
+/**
+ * `.tenant()` is the switch; a column literally named `orgId` counts too, so an entity cannot
+ * become unscoped by forgetting one call.
+ */
+export declare const tenantColumnOf: (columns: ColumnMap) => string | null;
+export declare const isOrgScoped: (columns: ColumnMap) => boolean;
+export declare const emptyPlan: (entity: string, limit?: number) => QueryPlan;
+export declare const hasOrgPredicate: (plan: QueryPlan, column?: string) => boolean;
+/** Adds the org predicate exactly once; calling it twice is not an error. */
+export declare const orgScoped: (plan: QueryPlan, orgId: string, column?: string) => QueryPlan;
+/**
+ * Called by every repository operation. Runtime here, and a build-time check in `x verify`
+ * that no query for a tenant-scoped entity is constructed without it.
+ */
+export declare const assertScoped: (entityName: string, tenantColumn: string | null, operation: string, plan: QueryPlan) => void;
+/** Debug and `x db explain` rendering. Values stay out: a plan is safe to log. */
+export declare const describePlan: (plan: QueryPlan) => string;
+//# sourceMappingURL=tenancy.d.ts.map

package/src/tenancy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy.d.ts","sourceRoot":"","sources":["tenancy.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAChB,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,MAAM,GACN,SAAS,GACT,aAAa,CAAC;AAElB,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,+EAA+E;AAC/E,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC;;;GAGG;AACH,eAAO,MAAM,cAAc,YAAa,SAAS,KAAG,MAAM,GAAG,IAK5D,CAAC;AAEF,eAAO,MAAM,WAAW,YAAa,SAAS,KAAG,OAA2C,CAAC;AAE7F,eAAO,MAAM,SAAS,WAAY,MAAM,qBAAe,SAKrD,CAAC;AAEH,eAAO,MAAM,eAAe,SAAU,SAAS,WAAU,MAAM,KAAgB,OAClB,CAAC;AAE9D,6EAA6E;AAC7E,eAAO,MAAM,SAAS,SACd,SAAS,SACR,MAAM,WACL,MAAM,KACb,SAG0E,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,YAAY,eACX,MAAM,gBACJ,MAAM,GAAG,IAAI,aAChB,MAAM,QACX,SAAS,KACd,IAIF,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,YAAY,SAAU,SAAS,KAAG,MAc9C,CAAC"}

package/src/tenancy.js

@@ -0,0 +1,57 @@
+// Multi-tenancy is a guard, not a convention. An entity with a tenant column can only be read
+// through a plan that carries an org predicate; building one without it throws
+// `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
+import { tenancyUnscoped } from './errors';
+/** The property key a tenant column takes when it is not marked explicitly. */
+export const ORG_COLUMN = 'orgId';
+/**
+ * `.tenant()` is the switch; a column literally named `orgId` counts too, so an entity cannot
+ * become unscoped by forgetting one call.
+ */
+export const tenantColumnOf = (columns) => {
+    for (const [property, column] of Object.entries(columns)) {
+        if (column.$meta.tenant)
+            return property;
+    }
+    return Object.hasOwn(columns, ORG_COLUMN) ? ORG_COLUMN : null;
+};
+export const isOrgScoped = (columns) => tenantColumnOf(columns) !== null;
+export const emptyPlan = (entity, limit = 50) => ({
+    entity,
+    where: [],
+    orderBy: [],
+    limit,
+});
+export const hasOrgPredicate = (plan, column = ORG_COLUMN) => plan.where.some((predicate) => predicate.column === column);
+/** Adds the org predicate exactly once; calling it twice is not an error. */
+export const orgScoped = (plan, orgId, column = ORG_COLUMN) => hasOrgPredicate(plan, column)
+    ? plan
+    : { ...plan, where: [...plan.where, { column, op: 'eq', value: orgId }] };
+/**
+ * Called by every repository operation. Runtime here, and a build-time check in `x verify`
+ * that no query for a tenant-scoped entity is constructed without it.
+ */
+export const assertScoped = (entityName, tenantColumn, operation, plan) => {
+    if (tenantColumn === null)
+        return;
+    if (hasOrgPredicate(plan, tenantColumn))
+        return;
+    throw tenancyUnscoped(entityName, operation);
+};
+/** Debug and `x db explain` rendering. Values stay out: a plan is safe to log. */
+export const describePlan = (plan) => {
+    const where = plan.where
+        .map((predicate) => `${predicate.column} ${predicate.op} ?`)
+        .join(' and ');
+    const order = plan.orderBy.map((entry) => `${entry.column} ${entry.direction}`).join(', ');
+    return [
+        `from ${plan.entity}`,
+        where === '' ? null : `where ${where}`,
+        order === '' ? null : `order by ${order}`,
+        `limit ${plan.limit}`,
+        plan.cursor === undefined ? null : 'after cursor',
+    ]
+        .filter((part) => part !== null)
+        .join(' ');
+};
+//# sourceMappingURL=tenancy.js.map

package/src/tenancy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenancy.js","sourceRoot":"","sources":["tenancy.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,+EAA+E;AAC/E,6EAA6E;AAE7E,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAsC3C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAkB,EAAiB,EAAE;IAClE,KAAK,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM;YAAE,OAAO,QAAQ,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAkB,EAAW,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;AAE7F,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,KAAK,GAAG,EAAE,EAAa,EAAE,CAAC,CAAC;IACnE,MAAM;IACN,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,EAAE;IACX,KAAK;CACN,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAe,EAAE,MAAM,GAAW,UAAU,EAAW,EAAE,CACvF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,IAAe,EACf,KAAa,EACb,MAAM,GAAW,UAAU,EAChB,EAAE,CACb,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC;IAC3B,CAAC,CAAC,IAAI;IACN,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,UAAkB,EAClB,YAA2B,EAC3B,SAAiB,EACjB,IAAe,EACT,EAAE;IACR,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO;IAClC,IAAI,eAAe,CAAC,IAAI,EAAE,YAAY,CAAC;QAAE,OAAO;IAChD,MAAM,eAAe,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAC/C,CAAC,CAAC;AAEF,kFAAkF;AAClF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAe,EAAU,EAAE;IACtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;SACrB,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,EAAE,IAAI,CAAC;SAC3D,IAAI,CAAC,OAAO,CAAC,CAAC;IACjB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3F,OAAO;QACL,QAAQ,IAAI,CAAC,MAAM,EAAE;QACrB,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE;QACtC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,KAAK,EAAE;QACzC,SAAS,IAAI,CAAC,KAAK,EAAE;QACrB,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;KAClD;SACE,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC;SAC/C,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC,CAAC"}

package/src/tenancy.ts

@@ -1,8 +1,9 @@
-// Multi-tenancy is a guard, not a convention. An entity with an `orgId` column can
-// only be queried through a plan that carries an org predicate; building one without
-// it throws `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
-import { tenancyUnscoped } from './errors';
-import type { TableDef } from './types';
+// Multi-tenancy is a guard, not a convention. An entity with a tenant column can only be read
+// through a plan that carries an org predicate; building one without it throws
+// `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
+
+import { EntityError, tenancyUnscoped } from './errors';
+import type { ColumnMap } from './types';
 
 export type Operator =
   | 'eq'
@@ -24,18 +25,62 @@ export interface Predicate {
 
 export type SortDirection = 'asc' | 'desc';
 
+export interface SortKey {
+  readonly column: string;
+  readonly direction: SortDirection;
+}
+
 export interface QueryPlan {
   readonly entity: string;
   readonly where: readonly Predicate[];
-  readonly orderBy: readonly { readonly column: string; readonly direction: SortDirection }[];
+  readonly orderBy: readonly SortKey[];
   readonly limit: number;
+  /** Keyset position. There is no `offset` and there will not be one — see `repo.ts`. */
   readonly cursor?: string;
+  readonly select?: readonly string[];
 }
 
+/** The property key a tenant column takes when it is not marked explicitly. */
 export const ORG_COLUMN = 'orgId';
 
-/** True when the table declares an `orgId` column — presence is the switch. */
-export const isOrgScoped = (table: TableDef): boolean => Object.hasOwn(table.columns, ORG_COLUMN);
+/**
+ * `.tenant()` is the switch; a column literally named `orgId` counts too, so an entity cannot
+ * become unscoped by forgetting one call.
+ */
+export const tenantColumnOf = (columns: ColumnMap): string | null => {
+  for (const [property, column] of Object.entries(columns)) {
+    if (column.$meta.tenant) return property;
+  }
+  return Object.hasOwn(columns, ORG_COLUMN) ? ORG_COLUMN : null;
+};
+
+export const isOrgScoped = (columns: ColumnMap): boolean => tenantColumnOf(columns) !== null;
+
+/**
+ * `entity(name, { tenant: 'workspaceId' })` wins over inference — a tenant column need not be
+ * called `orgId` and need not carry `.tenant()`. Omitting it keeps the inference, so an entity
+ * cannot become unscoped by forgetting the key; naming a column that does not exist is a
+ * declaration error, because the alternative is a silently unscoped table.
+ */
+export const resolveTenantColumn = (
+  entityName: string,
+  columns: ColumnMap,
+  declared: string | undefined,
+): string | null => {
+  if (declared === undefined) return tenantColumnOf(columns);
+  if (!Object.hasOwn(columns, declared)) {
+    const available = Object.keys(columns).join(', ');
+    // Not `invariantViolated`: its fix points at `x entity explain`, which describes invariants
+    // the author never wrote. What repairs this is one edit to the declaration, so the error
+    // carries that edit and both ways out of it.
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName}.tenant: tenant: '${declared}' names no column — pick from: ${available}`,
+      fix: `set tenant to one of ${available} in entity('${entityName}'), or remove the tenant key — inference then takes the .tenant() column, else one named ${ORG_COLUMN}`,
+    });
+  }
+  return declared;
+};
 
 export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
   entity,
@@ -44,31 +89,35 @@ export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
   limit,
 });
 
-export const hasOrgPredicate = (plan: QueryPlan): boolean =>
-  plan.where.some((predicate) => predicate.column === ORG_COLUMN);
+export const hasOrgPredicate = (plan: QueryPlan, column: string = ORG_COLUMN): boolean =>
+  plan.where.some((predicate) => predicate.column === column);
 
 /** Adds the org predicate exactly once; calling it twice is not an error. */
-export const orgScoped = (plan: QueryPlan, orgId: string): QueryPlan =>
-  hasOrgPredicate(plan)
+export const orgScoped = (
+  plan: QueryPlan,
+  orgId: string,
+  column: string = ORG_COLUMN,
+): QueryPlan =>
+  hasOrgPredicate(plan, column)
     ? plan
-    : { ...plan, where: [...plan.where, { column: ORG_COLUMN, op: 'eq', value: orgId }] };
+    : { ...plan, where: [...plan.where, { column, op: 'eq', value: orgId }] };
 
 /**
- * Called by every repository operation. Runtime here, and a build-time check in
- * `x verify` that no query for a tenant-scoped entity is constructed without it.
+ * Called by every repository operation. Runtime here, and a build-time check in `x verify`
+ * that no query for a tenant-scoped entity is constructed without it.
  */
 export const assertScoped = (
   entityName: string,
-  table: TableDef,
+  tenantColumn: string | null,
   operation: string,
   plan: QueryPlan,
 ): void => {
-  if (!isOrgScoped(table)) return;
-  if (hasOrgPredicate(plan)) return;
+  if (tenantColumn === null) return;
+  if (hasOrgPredicate(plan, tenantColumn)) return;
   throw tenancyUnscoped(entityName, operation);
 };
 
-/** Debug/`x db explain` rendering. Values stay out: a plan is safe to log. */
+/** Debug and `x db explain` rendering. Values stay out: a plan is safe to log. */
 export const describePlan = (plan: QueryPlan): string => {
   const where = plan.where
     .map((predicate) => `${predicate.column} ${predicate.op} ?`)