@segmentstream-cloud/ontology 0.25.1 → 0.26.0

package/dist/runtime/batch.js

@@ -0,0 +1,473 @@
+import { Effect, Schema } from "effect";
+import { ActionRejected, Conflict, NotFound } from "../errors.js";
+import { ACTION_ATTRIBUTION_TABLE, quoteIdentifier } from "../migrate/storage.js";
+import { InvalidValues, StoredRecordMismatch } from "./errors.js";
+import { diffRecords } from "./history.js";
+import { uuidv7 } from "./ids.js";
+import { entityModel } from "./model.js";
+import { normalizeId } from "./reads.js";
+import { bindValue, decodeRecord, isRecordId, prepareWrite, selectList, } from "./records.js";
+import { columnOf, Params } from "./statement.js";
+import { validate } from "./validation.js";
+export const BATCH_MAX_ROWS = 200;
+export const BATCH_MAX_BYTES = 2 * 1024 * 1024;
+export const ACTION_MAX_BATCH_ROWS = 500;
+/** The pinned PostgreSQL driver's signed Int16 count caps bindings at 32,767. */
+export const BATCH_MAX_PARAMETERS = 30_000;
+/** Includes bound values and an allowance for their SQL placeholders. */
+export const BATCH_MAX_STATEMENT_BYTES = 4 * 1024 * 1024;
+const summaryFields = new WeakMap();
+const KeyOrderRow = Schema.Struct({ index: Schema.Int, duplicates: Schema.Int });
+function rejected(message, indices, fields) {
+    return new ActionRejected({
+        message,
+        batch: { indices: [...indices], ...(fields === undefined ? {} : { fields: [...fields] }) },
+    });
+}
+/** One UTF-8 JSON encoding defines the public byte bound, including IDs and conflict fields. */
+export function batchInputBytes(input) {
+    return Buffer.byteLength(JSON.stringify({ records: input.records, ...(input.on ? { on: input.on } : {}) }));
+}
+function unsupportedFields(entity, values) {
+    return Object.keys(values).filter((name) => {
+        const field = entity.fieldsByName.get(name);
+        const link = entity.links.get(name);
+        return (values[name] !== undefined &&
+            (field?.storage === "blob" || link?.via === "join" || link?.via === "inverse-key"));
+    });
+}
+function conflictFields(entity, on) {
+    return Effect.suspend(() => {
+        const fields = on.map((name) => entity.fieldsByName.get(name));
+        const uniqueProperty = on.length === 1 && fields[0]?.property?.definition.unique === true;
+        const declaredIndex = entity.manifest.indexes.find((index) => index.unique &&
+            index.properties.length === on.length &&
+            index.properties.every((name) => on.includes(name)));
+        if (on.length === 0 ||
+            new Set(on).size !== on.length ||
+            fields.some((field) => field?.source !== "property") ||
+            (!uniqueProperty && declaredIndex === undefined)) {
+            return Effect.die(new InvalidValues({
+                entity: entity.name,
+                message: `upsertMany needs declared ordinary properties forming a unique key of ${entity.name}.`,
+                issues: [
+                    {
+                        path: ["on"],
+                        message: "Expected a declared unique property or compound unique index",
+                    },
+                ],
+            }));
+        }
+        // Equivalent conflict-key permutations must acquire unique-index locks in the same order.
+        const canonical = declaredIndex?.properties ?? on;
+        return Effect.succeed(canonical.map((name) => entity.fieldsByName.get(name)));
+    });
+}
+function prepareBatchWrite(entity, values, mode, index) {
+    return prepareWrite(entity, values, mode).pipe(Effect.catchDefect((defect) => {
+        if (!(defect instanceof InvalidValues)) {
+            return Effect.die(defect);
+        }
+        const indexed = new InvalidValues({
+            entity: defect.entity,
+            message: `Invalid ${entity.name} values at batch index ${index}.`,
+            issues: defect.issues.map((issue) => ({
+                ...issue,
+                path: ["records", index, ...issue.path],
+            })),
+        });
+        Object.defineProperty(indexed, "cause", { value: defect, enumerable: false });
+        return Effect.die(indexed);
+    }));
+}
+/** All authored-value validation finishes before a record mutation can execute. */
+export function planBatch(entity, operation, input) {
+    return Effect.gen(function* () {
+        const returning = input.returning ?? "records";
+        if (returning !== "records" && returning !== "summary") {
+            return yield* rejected("Unknown batch returning mode.", []);
+        }
+        const keys = operation === "upsert" ? yield* conflictFields(entity, input.on ?? []) : [];
+        const rows = [];
+        const updateIds = new Map();
+        const references = new Set();
+        for (const [index, entry] of input.records.entries()) {
+            const update = entry;
+            const values = operation === "update" ? update.values : entry;
+            const unsupported = unsupportedFields(entity, values);
+            if (unsupported.length > 0) {
+                return yield* rejected("Batch writes do not support blob or collection assignments.", [index], unsupported);
+            }
+            if (operation === "upsert") {
+                const missing = keys.filter((field) => values[field.name] === undefined || values[field.name] === null);
+                if (missing.length > 0) {
+                    return yield* Effect.die(new InvalidValues({
+                        entity: entity.name,
+                        message: "Every upsertMany record needs non-null conflict key values.",
+                        issues: missing.map((field) => ({
+                            path: [index, field.name],
+                            message: `${field.name} is required`,
+                        })),
+                    }));
+                }
+            }
+            const id = operation === "update" ? normalizeId(update.id) : uuidv7();
+            if (operation === "update") {
+                if (!isRecordId(id)) {
+                    return yield* missingRecord(entity, id, [index], ["id"]);
+                }
+                const indices = updateIds.get(id) ?? [];
+                indices.push(index);
+                updateIds.set(id, indices);
+            }
+            const create = yield* prepareBatchWrite(entity, values, operation === "update" ? "update" : "create", index);
+            const patch = operation === "upsert"
+                ? yield* prepareBatchWrite(entity, Object.fromEntries(Object.entries(values).filter(([name]) => !keys.some((key) => key.name === name))), "update", index)
+                : create;
+            for (const reference of create.references) {
+                references.add(`${reference.link.target}:${normalizeId(reference.id)}`);
+            }
+            rows.push({ index, id, create, patch });
+        }
+        const duplicates = [...updateIds.values()].filter((indices) => indices.length > 1).flat();
+        if (duplicates.length > 0) {
+            return yield* rejected("A batch cannot update a record more than once.", duplicates.sort((a, b) => a - b), ["id"]);
+        }
+        return { operation, returning, rows, keys, distinctReferences: references.size };
+    });
+}
+function missingRecord(entity, id, indices, fields) {
+    return new NotFound({
+        entity: entity.name,
+        id,
+        message: `A required ${entity.label.toLowerCase()} record does not exist.`,
+        batch: { indices: [...indices], ...(fields ? { fields: [...fields] } : {}) },
+    });
+}
+/** Chunk by protocol parameters and encoded statement weight; chunks share one savepoint. */
+function chunks(rows, width, valueBytes) {
+    return Effect.gen(function* () {
+        const result = [];
+        let current = [];
+        let bytes = 0;
+        for (const row of rows) {
+            const rowBytes = valueBytes(row) + width * 48;
+            if (width > BATCH_MAX_PARAMETERS || rowBytes > BATCH_MAX_STATEMENT_BYTES) {
+                return yield* rejected("A batch row exceeds the SQL statement resource limit.", []);
+            }
+            if (current.length > 0 &&
+                ((current.length + 1) * width > BATCH_MAX_PARAMETERS ||
+                    bytes + rowBytes > BATCH_MAX_STATEMENT_BYTES)) {
+                result.push(current);
+                current = [];
+                bytes = 0;
+            }
+            current.push(row);
+            bytes += rowBytes;
+        }
+        if (current.length > 0) {
+            result.push(current);
+        }
+        return result;
+    });
+}
+function writeBytes(write) {
+    return Buffer.byteLength(JSON.stringify(write.columns.map(({ field, value }) => bindValue(field, value))));
+}
+function selectedFields(entity, returning) {
+    if (returning === "records") {
+        return entity.fields;
+    }
+    const fields = summaryFields.get(entity) ??
+        entity.fields.filter((field) => field.source !== "system" || field.name === "id");
+    summaryFields.set(entity, fields);
+    return fields;
+}
+/** Summary mode needs history values, but never decodes a projected row as a complete record. */
+function decodeBatchRow(entity, row, returning) {
+    return decodeRecord(entity, row, selectedFields(entity, returning));
+}
+function requireBatchReferences(context, plan) {
+    return Effect.gen(function* () {
+        const targets = new Map();
+        for (const row of plan.rows) {
+            for (const reference of row.create.references) {
+                const ids = targets.get(reference.link.target) ?? new Map();
+                const id = normalizeId(reference.id);
+                const positions = ids.get(id) ?? { indices: new Set(), fields: new Set() };
+                positions.indices.add(row.index);
+                positions.fields.add(reference.link.name);
+                ids.set(id, positions);
+                targets.set(reference.link.target, ids);
+            }
+        }
+        for (const name of [...targets.keys()].sort()) {
+            const entity = entityModel(context.model, name);
+            const ids = targets.get(name);
+            const wanted = [...ids.keys()].sort();
+            const malformed = wanted.find((id) => !isRecordId(id));
+            if (malformed !== undefined) {
+                const positions = ids.get(malformed);
+                return yield* missingRecord(entity, malformed, [...positions.indices], [...positions.fields]);
+            }
+            for (const part of yield* chunks(wanted, 1, (id) => id.length)) {
+                const params = new Params();
+                const placeholders = part.map((id) => params.add(id, "uuid"));
+                const rows = yield* context.run(`SELECT "t0"."id"::text AS "id" FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+                    `WHERE "t0"."id" IN (${placeholders.join(", ")}) ORDER BY "t0"."id" FOR KEY SHARE OF "t0"`, params);
+                const found = new Set(rows.map((row) => row.id));
+                const missing = part.filter((id) => !found.has(id));
+                if (missing.length > 0) {
+                    const positions = missing.map((id) => ids.get(id));
+                    return yield* missingRecord(entity, missing[0], [...new Set(positions.flatMap((position) => [...position.indices]))].sort((a, b) => a - b), [...new Set(positions.flatMap((position) => [...position.fields]))].sort());
+                }
+            }
+        }
+    });
+}
+function keyValue(row, field) {
+    return row.create.columns.find((column) => column.field.name === field.name).value;
+}
+/** PostgreSQL casts, equality and collation define duplicate keys; JS string encodings do not. */
+function requireDistinctKeys(context, entity, plan) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const input = plan.rows.map((row) => Object.fromEntries([
+            ["index", row.index],
+            ...plan.keys.map((field, index) => [`k${index}`, keyValue(row, field)]),
+        ]));
+        const keyNames = plan.keys.map((_, index) => quoteIdentifier(`k${index}`));
+        const definitions = plan.keys.map((field, index) => `${keyNames[index]} ${field.sqlType}`);
+        const rows = yield* context.run(`SELECT "index", count(*) OVER (PARTITION BY ${keyNames.join(", ")})::integer AS "duplicates" ` +
+            `FROM jsonb_to_recordset(${params.add(JSON.stringify(input), "jsonb")}) AS "input" ` +
+            `("index" integer, ${definitions.join(", ")}) ORDER BY ${keyNames.join(", ")}`, params);
+        const decoded = validate(Schema.Array(KeyOrderRow), rows);
+        if (!decoded.ok) {
+            return yield* Effect.die(new StoredRecordMismatch({
+                entity: entity.name,
+                message: "The database returned an invalid batch key ordering projection.",
+            }));
+        }
+        const indices = decoded.value
+            .filter((row) => Number(row.duplicates) > 1)
+            .map((row) => Number(row.index))
+            .sort((a, b) => a - b);
+        if (indices.length > 0) {
+            return yield* rejected("The batch contains duplicate conflict keys.", indices, plan.keys.map((field) => field.name));
+        }
+        const byIndex = new Map(plan.rows.map((row) => [row.index, row]));
+        return decoded.value.map((row) => byIndex.get(row.index));
+    });
+}
+function createRows(context, entity, plan) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const fields = entity.fields.filter((field) => field.source !== "system");
+        const sorted = plan.operation === "upsert"
+            ? plan.rows
+            : [...plan.rows].sort((left, right) => left.id.localeCompare(right.id));
+        for (const part of yield* chunks(sorted, fields.length + 2, (row) => writeBytes(row.create))) {
+            const params = new Params();
+            const principal = params.add(context.scope.principalId, "uuid");
+            const values = part.map((row) => {
+                const columns = new Map(row.create.columns.map((column) => [column.field.name, column.value]));
+                const placeholders = [
+                    params.add(row.id, "uuid"),
+                    ...fields.map((field) => params.add(bindValue(field, columns.get(field.name)), field.sqlType)),
+                ];
+                return `(${placeholders.join(", ")})`;
+            });
+            const columns = fields.map((field) => quoteIdentifier(field.column));
+            const inputColumns = ['"id"', ...columns];
+            const targetColumns = [
+                '"id"',
+                '"created_at"',
+                '"updated_at"',
+                '"created_by"',
+                '"updated_by"',
+                ...columns,
+            ];
+            const selected = [
+                '"input"."id"',
+                "now()",
+                "now()",
+                principal,
+                principal,
+                ...columns.map((column) => `"input".${column}`),
+            ];
+            const conflict = plan.operation === "upsert"
+                ? ` ON CONFLICT (${plan.keys.map((field) => quoteIdentifier(field.column)).join(", ")}) DO NOTHING`
+                : "";
+            const order = plan.operation === "upsert"
+                ? plan.keys.map((field) => columnOf("input", field.column)).join(", ")
+                : '"input"."id"';
+            const rows = yield* context.run(`INSERT INTO ${quoteIdentifier(entity.table)} AS "t0" ` +
+                `(${targetColumns.join(", ")}) SELECT ${selected.join(", ")} ` +
+                `FROM (VALUES ${values.join(", ")}) AS "input" (${inputColumns.join(", ")}) ` +
+                `ORDER BY ${order}${conflict} RETURNING ${selectList(entity, "t0", selectedFields(entity, plan.returning))}`, params);
+            const byId = new Map(part.map((row) => [row.id, row.index]));
+            for (const row of rows) {
+                const record = yield* decodeBatchRow(entity, row, plan.returning);
+                records.set(byId.get(record.id), record);
+            }
+        }
+        return records;
+    });
+}
+function lockRows(context, entity, plan, pending) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const sorted = plan.operation === "upsert"
+            ? pending
+            : [...pending].sort((left, right) => left.id.localeCompare(right.id));
+        const width = plan.operation === "upsert" ? plan.keys.length + 1 : 2;
+        for (const part of yield* chunks(sorted, width, (row) => writeBytes(row.create))) {
+            const params = new Params();
+            const keys = plan.operation === "upsert" ? plan.keys : [entity.fieldsByName.get("id")];
+            const values = part.map((row) => `(${params.add(row.index, "integer")}, ${keys
+                .map((field) => params.add(field.name === "id" ? row.id : bindValue(field, keyValue(row, field)), field.sqlType))
+                .join(", ")})`);
+            const keyNames = keys.map((_, index) => quoteIdentifier(`k${index}`));
+            const condition = keys
+                .map((field, index) => `${columnOf("t0", field.column)} = "input".${keyNames[index]}`)
+                .join(" AND ");
+            const order = keys.map((field) => columnOf("t0", field.column)).join(", ");
+            const rows = yield* context.run(`SELECT "input"."index" AS "__batch_index", ` +
+                `${selectList(entity, "t0", selectedFields(entity, plan.returning))} ` +
+                `FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+                `JOIN (VALUES ${values.join(", ")}) AS "input" ("index", ${keyNames.join(", ")}) ON ${condition} ` +
+                `ORDER BY ${order} FOR UPDATE OF "t0"`, params);
+            for (const row of rows) {
+                records.set(Number(row.__batch_index), yield* decodeBatchRow(entity, row, plan.returning));
+            }
+        }
+        const missing = pending.filter((row) => !records.has(row.index));
+        if (missing.length > 0) {
+            if (plan.operation === "upsert") {
+                return yield* new Conflict({
+                    entity: entity.name,
+                    message: "A conflicting upsert record disappeared before it could be locked.",
+                    batch: {
+                        indices: missing.map((row) => row.index),
+                        fields: plan.keys.map((field) => field.name),
+                    },
+                });
+            }
+            return yield* missingRecord(entity, missing[0].id, missing.map((row) => row.index), ["id"]);
+        }
+        return records;
+    });
+}
+/** Presence flags support heterogeneous patches in one set mutation without filling omissions. */
+function updateRows(context, entity, plan, pending, before) {
+    return Effect.gen(function* () {
+        const records = new Map();
+        const names = new Set(pending.flatMap((row) => row.patch.columns.map(({ field }) => field.name)));
+        const fields = entity.fields.filter((field) => names.has(field.name));
+        if (fields.length === 0) {
+            return records;
+        }
+        const sorted = [...pending].sort((left, right) => String(before.get(left.index).id).localeCompare(String(before.get(right.index).id)));
+        for (const part of yield* chunks(sorted, fields.length * 2 + 2, (row) => writeBytes(row.patch))) {
+            const params = new Params();
+            const principal = params.add(context.scope.principalId, "uuid");
+            const values = part.map((row) => {
+                const columns = new Map(row.patch.columns.map((column) => [column.field.name, column.value]));
+                const fieldsSql = fields.flatMap((field) => [
+                    params.add(columns.has(field.name), "boolean"),
+                    params.add(columns.has(field.name) ? bindValue(field, columns.get(field.name)) : null, field.sqlType),
+                ]);
+                return `(${params.add(before.get(row.index).id, "uuid")}, ${fieldsSql.join(", ")})`;
+            });
+            const inputColumns = fields.flatMap((_, index) => [`"has${index}"`, `"v${index}"`]);
+            const assignments = fields.map((field, index) => `${quoteIdentifier(field.column)} = CASE WHEN "input"."has${index}" ` +
+                `THEN "input"."v${index}" ELSE ${columnOf("t0", field.column)} END`);
+            const changed = fields.map((field, index) => `("input"."has${index}" AND ${columnOf("t0", field.column)} IS DISTINCT FROM "input"."v${index}")`);
+            const rows = yield* context.run(`UPDATE ${quoteIdentifier(entity.table)} AS "t0" SET ${assignments.join(", ")}, ` +
+                `"updated_at" = now(), "updated_by" = ${principal} ` +
+                `FROM (VALUES ${values.join(", ")}) AS "input" ("id", ${inputColumns.join(", ")}) ` +
+                `WHERE "t0"."id" = "input"."id" AND (${changed.join(" OR ")}) ` +
+                `RETURNING ${selectList(entity, "t0", selectedFields(entity, plan.returning))}`, params);
+            const byId = new Map(part.map((row) => [before.get(row.index).id, row.index]));
+            for (const row of rows) {
+                const record = yield* decodeBatchRow(entity, row, plan.returning);
+                records.set(byId.get(record.id), record);
+            }
+        }
+        return records;
+    });
+}
+function recordBatchEdits(context, entity, edits) {
+    return Effect.gen(function* () {
+        if (edits.length === 0) {
+            return;
+        }
+        if (context.scope.execution !== undefined && !context.attributionInitialized) {
+            const params = new Params();
+            yield* context.run(`INSERT INTO "${ACTION_ATTRIBUTION_TABLE}" (action_id, execution) VALUES (` +
+                `${params.add(context.scope.actionId, "uuid")}, ` +
+                `${params.add(JSON.stringify(context.scope.execution), "jsonb")}) ON CONFLICT DO NOTHING`, params);
+        }
+        for (const part of yield* chunks(edits, 7, (edit) => Buffer.byteLength(JSON.stringify(edit.changes)))) {
+            const params = new Params();
+            const values = part.map((edit) => `(${[
+                params.add(uuidv7(), "uuid"),
+                params.add(edit.id, "uuid"),
+                params.add(context.scope.action, "text"),
+                params.add(context.scope.actionId, "uuid"),
+                params.add(edit.kind, "text"),
+                params.add(context.scope.principalId, "uuid"),
+                "now()",
+                params.add(JSON.stringify(edit.changes), "jsonb"),
+            ].join(", ")})`);
+            yield* context.run(`INSERT INTO ${quoteIdentifier(entity.historyTable)} ` +
+                '("id", "record_id", "action", "action_id", "kind", "principal_id", "at", "changes") ' +
+                `VALUES ${values.join(", ")}`, params);
+        }
+        context.edits.push(...edits);
+    });
+}
+/** Executes one set of mutations; the caller owns its single savepoint and edit publication. */
+export function executeBatch(context, entity, plan) {
+    return Effect.gen(function* () {
+        const sortedRows = plan.operation === "upsert" ? yield* requireDistinctKeys(context, entity, plan) : plan.rows;
+        const orderedPlan = { ...plan, rows: sortedRows };
+        yield* requireBatchReferences(context, plan);
+        const created = plan.operation === "update"
+            ? new Map()
+            : yield* createRows(context, entity, orderedPlan);
+        const pending = sortedRows.filter((row) => !created.has(row.index));
+        // A new READ COMMITTED statement observes insertions that DO NOTHING waited for.
+        const before = pending.length === 0
+            ? new Map()
+            : yield* lockRows(context, entity, plan, pending);
+        const updated = pending.length === 0
+            ? new Map()
+            : yield* updateRows(context, entity, plan, pending, before);
+        const edits = [];
+        const items = plan.rows.map((row) => {
+            const record = created.get(row.index) ?? updated.get(row.index) ?? before.get(row.index);
+            const status = created.has(row.index)
+                ? "created"
+                : updated.has(row.index)
+                    ? "updated"
+                    : "unchanged";
+            if (status !== "unchanged") {
+                edits.push({
+                    entity: entity.name,
+                    id: record.id,
+                    kind: status === "created" ? "create" : "update",
+                    changes: diffRecords(entity, status === "created" ? undefined : before.get(row.index), record),
+                });
+            }
+            return { index: row.index, status, record };
+        });
+        yield* recordBatchEdits(context, entity, edits);
+        const counts = {
+            created: created.size,
+            updated: updated.size,
+            unchanged: before.size - updated.size,
+        };
+        return plan.returning === "summary" ? counts : { ...counts, items };
+    });
+}

package/dist/runtime/records.d.ts

@@ -3,11 +3,11 @@ import type { StoredRecord, StoredValues } from "../runtime.js";
 import { type EntityModel, type FieldModel, type JoinLink, type KeyLink } from "./model.js";
 export type Row = Readonly<Record<string, unknown>>;
 /** The select list of an entity's records from the table aliased `alias`. */
-export declare function selectList(entity: EntityModel, alias: string): string;
+export declare function selectList(entity: EntityModel, alias: string, fields?: ReadonlyArray<FieldModel>): string;
 /** `2026-10-04T09:30:00.120000Z` → `2026-10-04T09:30:00.120Z`: milliseconds, then any further digits. */
 export declare function canonicalInstant(value: string): string;
 /** Decodes a row read with {@link selectList} against the entity's record schema. */
-export declare function decodeRecord(entity: EntityModel, row: Row): Effect.Effect<StoredRecord>;
+export declare function decodeRecord(entity: EntityModel, row: Row, fields?: ReadonlyArray<FieldModel>): Effect.Effect<StoredRecord>;
 export declare function decodeRecords(entity: EntityModel, rows: ReadonlyArray<Row>): Effect.Effect<Array<StoredRecord>>;
 /** The parameter a value of a field is bound as. JSON is bound as text and cast to `jsonb`. */
 export declare function bindValue(field: FieldModel, value: unknown): unknown;

package/dist/runtime/records.js

@@ -1,10 +1,28 @@
-import { Effect } from "effect";
+import { Effect, Schema } from "effect";
 import { isCalendarDate, isInstant, isUuid } from "../query.js";
 import { quoteIdentifier } from "../migrate/storage.js";
 import { InvalidValues, StoredRecordMismatch } from "./errors.js";
 import { propertyValueSchema, } from "./model.js";
 import { columnOf } from "./statement.js";
 import { validate } from "./validation.js";
+const projectionSchemas = new WeakMap();
+function projectionSchema(entity, fields) {
+    if (fields === entity.fields) {
+        return entity.recordSchema;
+    }
+    const key = fields.map((field) => field.name).join(",");
+    const cached = projectionSchemas.get(entity) ?? new Map();
+    const existing = cached.get(key);
+    if (existing !== undefined) {
+        return existing;
+    }
+    // entityRecordSchema builds a Struct; derive each SQL projection from those field schemas.
+    const complete = entity.recordSchema;
+    const schema = Schema.Struct(Object.fromEntries(fields.map((field) => [field.name, complete.fields[field.name]])));
+    cached.set(key, schema);
+    projectionSchemas.set(entity, cached);
+    return schema;
+}
 /**
  * How a column is read. Values come back as text where the driver's own decoding would lose
  * information or depend on the driver: timestamps keep their microseconds in UTC, dates stay
@@ -31,8 +49,8 @@ function readExpression(field, column) {
     }
 }
 /** The select list of an entity's records from the table aliased `alias`. */
-export function selectList(entity, alias) {
-    return entity.fields
+export function selectList(entity, alias, fields = entity.fields) {
+    return fields
         .map((field) => `${readExpression(field, columnOf(alias, field.column))} AS ${quoteIdentifier(field.name)}`)
         .join(", ");
 }
@@ -57,13 +75,14 @@ function readValue(field, value) {
     }
 }
 /** Decodes a row read with {@link selectList} against the entity's record schema. */
-export function decodeRecord(entity, row) {
+export function decodeRecord(entity, row, fields = entity.fields) {
     return Effect.suspend(() => {
         const values = {};
-        for (const field of entity.fields) {
+        for (const field of fields) {
             values[field.name] = readValue(field, row[field.name]);
         }
-        const decoded = validate(entity.recordSchema, values);
+        const schema = projectionSchema(entity, fields);
+        const decoded = validate(schema, values);
         if (!decoded.ok) {
             const fields = decoded.issues.map((issue) => issue.path.join(".")).join(", ");
             return Effect.die(new StoredRecordMismatch({