@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/reads.d.ts

@@ -0,0 +1,55 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { NotFound } from "../errors.js";
+import { type Query, type QueryResult } from "../query.js";
+import type { StoredRecord } from "../runtime.js";
+import { InvalidQuery } from "./errors.js";
+import { HistoryEntry } from "./history.js";
+import { type EntityModel, type LinkModel, type OntologyModel } from "./model.js";
+import { type Row } from "./records.js";
+import { Params } from "./statement.js";
+import { type RowScope, type ScopeReader } from "./where.js";
+/** What reads and writes run against: the ontology's model and one SQL client. */
+export interface SqlContext {
+    readonly model: OntologyModel;
+    readonly run: (text: string, params: Params) => Effect.Effect<ReadonlyArray<Row>, SqlError>;
+    /**
+     * The caller whose read scopes the reads honour: only the rows inside them exist for it. Absent
+     * for reads with the action's authority and for callers without scoped permissions.
+     */
+    readonly reader?: ScopeReader;
+}
+export type RowLock = "update" | "key share";
+export declare function notFound(entity: EntityModel, id: string): NotFound;
+/** Record ids as PostgreSQL prints them, so that ids compare as strings. */
+export declare function normalizeId(id: string): string;
+/**
+ * One record by id, optionally locked until the transaction ends. With a scope, a record outside it
+ * is not found.
+ */
+export declare function loadRecord(context: SqlContext, entity: EntityModel, id: string, lock?: RowLock, scope?: RowScope): Effect.Effect<StoredRecord | undefined, SqlError>;
+/**
+ * Fails with NotFound unless every record exists, and keeps them from being deleted until the
+ * transaction ends (`FOR KEY SHARE`), so that a key written to them stays valid.
+ */
+export declare function requireRecords(context: SqlContext, entity: EntityModel, ids: ReadonlyArray<string>): Effect.Effect<void, NotFound | SqlError>;
+/** Checks a query against the entity's query schema. */
+export declare function validateQuery(entity: EntityModel, input: unknown): Effect.Effect<Query, InvalidQuery>;
+export interface QueryOptions {
+    /** Lock the matching records until the transaction ends. */
+    readonly forUpdate?: boolean;
+    /** A further condition on the table aliased `t0`, such as a relationship to one record. */
+    readonly condition?: (params: Params) => string;
+}
+/** A page of the entity's records matching a validated query. */
+export declare function runQuery(context: SqlContext, entity: EntityModel, query: Query, options?: QueryOptions): Effect.Effect<QueryResult<StoredRecord>, InvalidQuery | SqlError>;
+/** Included to-many relationships return at most this many records per record. */
+export declare const MAX_INCLUDED = 200;
+/** The condition that a target record is related to `id` through `link`, for traversal. */
+export declare function relatedCondition(link: LinkModel, id: string, keyValue: string | null): (params: Params) => string;
+/** A page of a record's history, newest first. A deleted record keeps its history. */
+export declare function readHistory(context: SqlContext, entity: EntityModel, input: {
+    readonly id: string;
+    readonly after?: string;
+    readonly limit?: number;
+}): Effect.Effect<QueryResult<HistoryEntry>, InvalidQuery | SqlError>;

package/dist/runtime/reads.js

@@ -0,0 +1,313 @@
+import { Effect, Schema } from "effect";
+import { NotFound } from "../errors.js";
+import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, includedRelationships, isInstant, } from "../query.js";
+import { quoteIdentifier } from "../migrate/storage.js";
+import { afterCondition, decodeCursor, encodeCursor, orderByClause, sortKeys } from "./cursor.js";
+import { InvalidQuery } from "./errors.js";
+import { HistoryEntry } from "./history.js";
+import { entityModel } from "./model.js";
+import { canonicalInstant, decodeRecord, decodeRecords, isRecordId, selectList, } from "./records.js";
+import { Aliases, columnOf, Params } from "./statement.js";
+import { validate } from "./validation.js";
+import { compileScope, compileWhere, readScopeOf, } from "./where.js";
+/** The condition `scope` puts on the table aliased `t0`, compiled into `params`. */
+function scopeOnT0(context, entity, params, scope) {
+    const aliases = new Aliases();
+    aliases.take(); // t0
+    return compileScope({ model: context.model, params, aliases }, entity, "t0", scope);
+}
+function lockClause(lock, alias) {
+    if (lock === undefined) {
+        return "";
+    }
+    return ` FOR ${lock === "update" ? "UPDATE" : "KEY SHARE"} OF ${quoteIdentifier(alias)}`;
+}
+export function notFound(entity, id) {
+    return new NotFound({
+        entity: entity.name,
+        id,
+        message: `There is no ${entity.label.toLowerCase()} with the id ${id}.`,
+    });
+}
+/** Record ids as PostgreSQL prints them, so that ids compare as strings. */
+export function normalizeId(id) {
+    return id.toLowerCase();
+}
+/**
+ * One record by id, optionally locked until the transaction ends. With a scope, a record outside it
+ * is not found.
+ */
+export function loadRecord(context, entity, id, lock, scope) {
+    return Effect.gen(function* () {
+        if (!isRecordId(id)) {
+            return undefined;
+        }
+        const params = new Params();
+        const key = `"t0"."id" = ${params.add(normalizeId(id), "uuid")}`;
+        const condition = scope === undefined ? key : `${key} AND (${scopeOnT0(context, entity, params, scope)})`;
+        const rows = yield* context.run(`SELECT ${selectList(entity, "t0")} ` +
+            `FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+            `WHERE ${condition}${lockClause(lock, "t0")}`, params);
+        const [row] = rows;
+        return row === undefined ? undefined : yield* decodeRecord(entity, row);
+    });
+}
+/**
+ * Fails with NotFound unless every record exists, and keeps them from being deleted until the
+ * transaction ends (`FOR KEY SHARE`), so that a key written to them stays valid.
+ */
+export function requireRecords(context, entity, ids) {
+    return Effect.gen(function* () {
+        const wanted = [...new Set(ids.map(normalizeId))];
+        const malformed = wanted.find((id) => !isRecordId(id));
+        if (malformed !== undefined) {
+            return yield* notFound(entity, malformed);
+        }
+        if (wanted.length === 0) {
+            return;
+        }
+        const params = new Params();
+        const placeholders = wanted.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(", ")})${lockClause("key share", "t0")}`, params);
+        const found = new Set(rows.map((row) => row.id));
+        const missing = wanted.find((id) => !found.has(id));
+        if (missing !== undefined) {
+            return yield* notFound(entity, missing);
+        }
+    });
+}
+/** Checks a query against the entity's query schema. */
+export function validateQuery(entity, input) {
+    const validated = validate(entity.querySchema, input);
+    if (validated.ok) {
+        return Effect.succeed(validated.value);
+    }
+    return Effect.fail(new InvalidQuery({
+        entity: entity.name,
+        message: `The query does not fit ${entity.name}.`,
+        issues: validated.issues,
+    }));
+}
+/** A page of the entity's records matching a validated query. */
+export function runQuery(context, entity, query, options = {}) {
+    return Effect.gen(function* () {
+        const keys = sortKeys(entity, query.orderBy);
+        const requested = query.select === undefined ? undefined : new Set(["id", ...query.select]);
+        const needed = new Set([...(requested ?? []), ...keys.map(({ field }) => field.name)]);
+        for (const name of includedRelationships(query.include)) {
+            if (entity.links.get(name)?.via === "key") {
+                needed.add(`${name}_id`);
+            }
+        }
+        const fields = requested === undefined
+            ? entity.fields
+            : entity.fields.filter((field) => needed.has(field.name));
+        const limit = Math.min(query.limit ?? DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT);
+        const params = new Params();
+        const aliases = new Aliases();
+        const alias = aliases.take();
+        const where = {
+            model: context.model,
+            params,
+            aliases,
+            ...(context.reader === undefined ? {} : { reader: context.reader }),
+        };
+        const conditions = [compileWhere(where, entity, alias, query.where)];
+        const scope = readScopeOf(context.reader, entity);
+        if (scope !== undefined) {
+            conditions.push(compileScope(where, entity, alias, scope));
+        }
+        if (options.condition !== undefined) {
+            conditions.push(options.condition(params));
+        }
+        if (query.after !== undefined) {
+            const values = decodeCursor(keys, query.after);
+            if (values === undefined) {
+                return yield* new InvalidQuery({
+                    entity: entity.name,
+                    message: "The cursor was not issued for this query.",
+                    issues: [{ path: ["after"], message: "Expected the nextCursor of the same query" }],
+                });
+            }
+            conditions.push(afterCondition(keys, values, alias, params));
+        }
+        const rows = yield* context.run(`SELECT ${selectList(entity, alias, fields)} ` +
+            `FROM ${quoteIdentifier(entity.table)} AS ${quoteIdentifier(alias)} ` +
+            `WHERE ${conditions.map((condition) => `(${condition})`).join(" AND ")} ` +
+            `ORDER BY ${orderByClause(keys, alias)} ` +
+            `LIMIT ${params.add(limit + 1, "bigint")}` +
+            lockClause(options.forUpdate === true ? "update" : undefined, alias), params);
+        const records = yield* requested === undefined
+            ? decodeRecords(entity, rows.slice(0, limit))
+            : Effect.forEach(rows.slice(0, limit), (row) => decodeRecord(entity, row, fields));
+        const last = records[records.length - 1];
+        const nextCursor = rows.length > limit && last !== undefined ? encodeCursor(keys, last) : null;
+        const items = yield* includeRelated(context, entity, records, query.include);
+        if (requested === undefined) {
+            return { items, nextCursor };
+        }
+        for (const name of includedRelationships(query.include)) {
+            requested.add(name);
+        }
+        return {
+            items: items.map((record) => Object.fromEntries(Object.entries(record).filter(([name]) => requested.has(name)))),
+            nextCursor,
+            projected: true,
+        };
+    });
+}
+/** Included to-many relationships return at most this many records per record. */
+export const MAX_INCLUDED = MAX_QUERY_LIMIT;
+function includeRelated(context, entity, records, include) {
+    return Effect.gen(function* () {
+        const names = includedRelationships(include);
+        let items = [...records];
+        if (records.length === 0) {
+            return items;
+        }
+        for (const name of names) {
+            const link = entity.links.get(name);
+            const related = yield* loadRelated(context, link, records);
+            items = items.map((record) => ({ ...record, [name]: related(record) }));
+        }
+        return items;
+    });
+}
+/** Loads the records related through one link to all of `records` in one query. */
+function loadRelated(context, link, records) {
+    return Effect.gen(function* () {
+        const target = entityModel(context.model, link.target);
+        const params = new Params();
+        const scope = readScopeOf(context.reader, target);
+        // A related record outside the reader's scope is left out: a to-one include is null.
+        const visible = scope === undefined ? "" : ` AND (${scopeOnT0(context, target, params, scope)})`;
+        if (link.via === "key") {
+            const keyField = `${link.name}_id`;
+            const ids = [...new Set(records.map((record) => record[keyField]).filter(isString))];
+            const byId = new Map();
+            if (ids.length > 0) {
+                const rows = yield* context.run(`SELECT ${selectList(target, "t0")} FROM ${quoteIdentifier(target.table)} AS "t0" ` +
+                    `WHERE "t0"."id" IN (${ids.map((id) => params.add(id, "uuid")).join(", ")})${visible}`, params);
+                for (const related of yield* decodeRecords(target, rows)) {
+                    byId.set(related.id, related);
+                }
+            }
+            return (record) => byId.get(record[keyField]) ?? null;
+        }
+        const ids = records.map((record) => params.add(record.id, "uuid")).join(", ");
+        const ranked = link.via === "join"
+            ? `SELECT ${columnOf("j", link.selfColumn)}::text AS "__source", ${selectList(target, "t0")}, ` +
+                `row_number() OVER (PARTITION BY ${columnOf("j", link.selfColumn)} ` +
+                `ORDER BY ${columnOf("j", "created_at")}, "t0"."id") AS "__rank" ` +
+                `FROM ${quoteIdentifier(link.table)} AS "j" ` +
+                `JOIN ${quoteIdentifier(target.table)} AS "t0" ON "t0"."id" = ${columnOf("j", link.otherColumn)} ` +
+                `WHERE ${columnOf("j", link.selfColumn)} IN (${ids})${visible}`
+            : `SELECT ${columnOf("t0", link.column)}::text AS "__source", ${selectList(target, "t0")}, ` +
+                `row_number() OVER (PARTITION BY ${columnOf("t0", link.column)} ` +
+                `ORDER BY "t0"."created_at", "t0"."id") AS "__rank" ` +
+                `FROM ${quoteIdentifier(target.table)} AS "t0" ` +
+                `WHERE ${columnOf("t0", link.column)} IN (${ids})${visible}`;
+        const rows = yield* context.run(`SELECT * FROM (${ranked}) AS "ranked" ` +
+            `WHERE "ranked"."__rank" <= ${params.add(MAX_INCLUDED, "bigint")} ` +
+            `ORDER BY "ranked"."__source", "ranked"."__rank"`, params);
+        const bySource = new Map();
+        for (const row of rows) {
+            const related = yield* decodeRecord(target, row);
+            const source = row.__source;
+            const list = bySource.get(source) ?? [];
+            list.push(related);
+            bySource.set(source, list);
+        }
+        return (record) => bySource.get(record.id) ?? [];
+    });
+}
+function isString(value) {
+    return typeof value === "string";
+}
+/** The condition that a target record is related to `id` through `link`, for traversal. */
+export function relatedCondition(link, id, keyValue) {
+    return (params) => {
+        if (link.via === "key") {
+            return keyValue === null ? "FALSE" : `"t0"."id" = ${params.add(keyValue, "uuid")}`;
+        }
+        if (link.via === "inverse-key") {
+            return `${columnOf("t0", link.column)} = ${params.add(id, "uuid")}`;
+        }
+        return (`EXISTS (SELECT 1 FROM ${quoteIdentifier(link.table)} AS "j" ` +
+            `WHERE ${columnOf("j", link.otherColumn)} = "t0"."id" ` +
+            `AND ${columnOf("j", link.selfColumn)} = ${params.add(id, "uuid")})`);
+    };
+}
+const HistoryCursor = Schema.Tuple([Schema.String, Schema.String]);
+function encodeHistoryCursor(entry) {
+    return Buffer.from(JSON.stringify([entry.at, entry.id]), "utf8").toString("base64url");
+}
+function decodeHistoryCursor(cursor) {
+    try {
+        const value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        return Schema.is(HistoryCursor)(value) && isInstant(value[0]) && isRecordId(value[1])
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A page of a record's history, newest first. A deleted record keeps its history. */
+export function readHistory(context, entity, input) {
+    return Effect.gen(function* () {
+        const limit = input.limit ?? DEFAULT_QUERY_LIMIT;
+        if (!Number.isInteger(limit) || limit < 1 || limit > MAX_QUERY_LIMIT) {
+            return yield* new InvalidQuery({
+                entity: entity.name,
+                message: "The limit is out of range.",
+                issues: [{ path: ["limit"], message: `Expected a value between 1 and ${MAX_QUERY_LIMIT}` }],
+            });
+        }
+        if (!isRecordId(input.id)) {
+            return { items: [], nextCursor: null };
+        }
+        const params = new Params();
+        const conditions = [`"h"."record_id" = ${params.add(normalizeId(input.id), "uuid")}`];
+        if (input.after !== undefined) {
+            const cursor = decodeHistoryCursor(input.after);
+            if (cursor === undefined) {
+                return yield* new InvalidQuery({
+                    entity: entity.name,
+                    message: "The cursor was not issued for this history.",
+                    issues: [{ path: ["after"], message: "Expected the nextCursor of the previous page" }],
+                });
+            }
+            const at = params.add(cursor[0], "timestamptz");
+            conditions.push(`("h"."at" < ${at} OR ("h"."at" = ${at} AND "h"."id" < ${params.add(cursor[1], "uuid")}))`);
+        }
+        const presenceParams = new Params();
+        const [presence] = yield* context.run("SELECT to_regclass('_ontology_action_attribution') IS NOT NULL AS present", presenceParams);
+        const attribution = presence?.present === true;
+        const rows = yield* context.run(`SELECT "h"."id"::text AS "id", "h"."record_id"::text AS "recordId", "h"."action" AS "action", ` +
+            `"h"."action_id"::text AS "actionId", "h"."kind" AS "kind", ` +
+            `"h"."principal_id"::text AS "principalId", ` +
+            `to_char("h"."at" AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"') AS "at", ` +
+            `"h"."changes"::text AS "changes" ` +
+            (attribution ? `, "a"."execution" AS "execution" ` : "") +
+            `FROM ${quoteIdentifier(entity.historyTable)} AS "h" ` +
+            (attribution
+                ? `LEFT JOIN "_ontology_action_attribution" AS "a" ON "a"."action_id" = "h"."action_id" `
+                : "") +
+            `WHERE ${conditions.join(" AND ")} ` +
+            `ORDER BY "h"."at" DESC, "h"."id" DESC ` +
+            `LIMIT ${params.add(limit + 1, "bigint")}`, params);
+        const items = rows.slice(0, limit).map((row) => Schema.decodeUnknownSync(HistoryEntry)({
+            ...Object.fromEntries(Object.entries(row).filter(([key, value]) => key !== "execution" || value != null)),
+            ...(row.execution == null ? {} : { execution: row.execution }),
+            at: canonicalInstant(String(row.at)),
+            changes: JSON.parse(String(row.changes)),
+        }));
+        const last = items[items.length - 1];
+        return {
+            items,
+            nextCursor: rows.length > limit && last !== undefined ? encodeHistoryCursor(last) : null,
+        };
+    });
+}

package/dist/runtime/records.d.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+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, 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, 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;
+export interface ColumnWrite {
+    readonly field: FieldModel;
+    readonly value: unknown;
+}
+export interface CollectionWrite {
+    readonly link: JoinLink;
+    readonly ids: ReadonlyArray<string>;
+}
+export interface ReferenceWrite {
+    readonly link: KeyLink;
+    readonly id: string;
+}
+/** Values of a write, checked against the entity and split by where they are stored. */
+export interface PreparedWrite {
+    readonly columns: ReadonlyArray<ColumnWrite>;
+    /** `rel.many` collections to set. */
+    readonly collections: ReadonlyArray<CollectionWrite>;
+    /** `rel.one` targets that must exist. */
+    readonly references: ReadonlyArray<ReferenceWrite>;
+}
+/**
+ * Checks the values a handler writes. Properties take their property's values, `rel.one`
+ * relationships a record id (or `null` when optional), `rel.many` relationships a list of ids,
+ * which replaces the collection. `undefined` leaves a value as it is; on create, a property without
+ * a value takes its default, or `null` when optional. Anything else is a defect in the handler.
+ */
+export declare function prepareWrite(entity: EntityModel, values: StoredValues, mode: "create" | "update"): Effect.Effect<PreparedWrite>;
+/** Whether a string can be a record id. Anything else names no record. */
+export declare function isRecordId(value: string): boolean;

package/dist/runtime/records.js

@@ -0,0 +1,245 @@
+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 { userRolesExpression } from "./user-roles.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
+ * calendar dates, `bigint` and `jsonb` are parsed here, and enums are read as their labels. The
+ * user's `roles` is read from the role assignments by the row's id, its column.
+ */
+function readExpression(field, column) {
+    switch (field.storage) {
+        case "list":
+            return `${userRolesExpression(column)}::text`;
+        case "blob":
+            return (`(SELECT json_build_object('id', b.id::text, 'filename', b.filename, ` +
+                `'contentType', b.content_type, 'size', b.size, 'createdAt', ` +
+                `to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))::text ` +
+                `FROM "_blobs" b WHERE b.id = ${column})`);
+        case "timestamp":
+            return `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`;
+        case "date":
+            return `to_char(${column}, 'YYYY-MM-DD')`;
+        case "integer":
+        case "json":
+        case "select":
+        case "uuid":
+            return `${column}::text`;
+        default:
+            return column;
+    }
+}
+/** The select list of an entity's records from the table aliased `alias`. */
+export function selectList(entity, alias, fields = entity.fields) {
+    return fields
+        .map((field) => `${readExpression(field, columnOf(alias, field.column))} AS ${quoteIdentifier(field.name)}`)
+        .join(", ");
+}
+/** `2026-10-04T09:30:00.120000Z` → `2026-10-04T09:30:00.120Z`: milliseconds, then any further digits. */
+export function canonicalInstant(value) {
+    return value.replace(/\.(\d{3})(\d*?)0*Z$/, ".$1$2Z");
+}
+function readValue(field, value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    switch (field.storage) {
+        case "integer":
+            return Number(value);
+        case "blob":
+        case "json":
+        case "list":
+            return typeof value === "string" ? JSON.parse(value) : value;
+        case "timestamp":
+            return canonicalInstant(String(value));
+        default:
+            return value;
+    }
+}
+/** Decodes a row read with {@link selectList} against the entity's record schema. */
+export function decodeRecord(entity, row, fields = entity.fields) {
+    return Effect.suspend(() => {
+        const values = {};
+        for (const field of fields) {
+            values[field.name] = readValue(field, row[field.name]);
+        }
+        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({
+                entity: entity.name,
+                message: `A stored ${entity.name} record does not match the definition (${fields}).`,
+            }));
+        }
+        return Effect.succeed(decoded.value);
+    });
+}
+export function decodeRecords(entity, rows) {
+    return Effect.forEach(rows, (row) => decodeRecord(entity, row));
+}
+/** The parameter a value of a field is bound as. JSON is bound as text and cast to `jsonb`. */
+export function bindValue(field, value) {
+    if (value === null) {
+        return null;
+    }
+    if (field.storage === "blob") {
+        return typeof value === "string" ? value : value.id;
+    }
+    return field.storage === "json" ? JSON.stringify(value) : value;
+}
+function propertyIssue(field, value) {
+    const property = field.property;
+    if (property === undefined) {
+        return undefined;
+    }
+    const decoded = validate(propertyValueSchema(property), value);
+    if (!decoded.ok) {
+        return { path: [field.name], message: decoded.issues[0]?.message ?? "Invalid value" };
+    }
+    // A pattern accepts days that do not exist; PostgreSQL would reject them mid-transaction.
+    if (field.storage === "date" && !isCalendarDate(value)) {
+        return { path: [field.name], message: "Expected a date that exists" };
+    }
+    if (field.storage === "timestamp" && !isInstant(value)) {
+        return { path: [field.name], message: "Expected an instant that exists" };
+    }
+    return undefined;
+}
+function isIdList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+/**
+ * Checks the values a handler writes. Properties take their property's values, `rel.one`
+ * relationships a record id (or `null` when optional), `rel.many` relationships a list of ids,
+ * which replaces the collection. `undefined` leaves a value as it is; on create, a property without
+ * a value takes its default, or `null` when optional. Anything else is a defect in the handler.
+ */
+export function prepareWrite(entity, values, mode) {
+    return Effect.suspend(() => {
+        const issues = [];
+        const columns = [];
+        const collections = [];
+        const references = [];
+        for (const [name, value] of Object.entries(values)) {
+            const field = entity.fieldsByName.get(name);
+            const link = entity.links.get(name);
+            if (value === undefined) {
+                continue;
+            }
+            if (field?.source === "property") {
+                if (value === null && !field.nullable) {
+                    issues.push({ path: [name], message: `${name} is required` });
+                    continue;
+                }
+                const issue = value === null ? undefined : propertyIssue(field, value);
+                if (issue !== undefined) {
+                    issues.push(issue);
+                    continue;
+                }
+                columns.push({ field, value });
+            }
+            else if (field?.source === "projection") {
+                issues.push({ path: [name], message: `${name} is read-only; the platform keeps it` });
+            }
+            else if (link?.via === "key") {
+                const key = entity.fieldsByName.get(`${name}_id`);
+                if (value === null && !link.optional) {
+                    issues.push({ path: [name], message: `${name} is required` });
+                }
+                else if (value !== null && typeof value !== "string") {
+                    issues.push({ path: [name], message: "Expected a record id" });
+                }
+                else {
+                    columns.push({ field: key, value });
+                    if (value !== null) {
+                        references.push({ link, id: value });
+                    }
+                }
+            }
+            else if (link?.via === "join" && !link.inverse) {
+                if (isIdList(value)) {
+                    collections.push({ link, ids: [...new Set(value)] });
+                }
+                else {
+                    issues.push({ path: [name], message: "Expected a list of record ids" });
+                }
+            }
+            else {
+                issues.push({ path: [name], message: `${name} is not a property or relationship` });
+            }
+        }
+        if (mode === "create") {
+            completeCreate(entity, values, columns, issues);
+        }
+        if (issues.length > 0) {
+            const summary = issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+            return Effect.die(new InvalidValues({
+                entity: entity.name,
+                message: `Invalid ${entity.name} values: ${summary.join("; ")}.`,
+                issues,
+            }));
+        }
+        return Effect.succeed({ columns, collections, references });
+    });
+}
+/** Defaults, `null` for optional values and missing required values, on create. */
+function completeCreate(entity, values, columns, issues) {
+    for (const field of entity.fields) {
+        if (field.source === "system" ||
+            field.source === "projection" ||
+            values[field.name] !== undefined) {
+            continue;
+        }
+        if (field.source === "relationship") {
+            const relationship = field.relationship;
+            if (values[relationship] !== undefined) {
+                continue;
+            }
+            if (field.nullable) {
+                columns.push({ field, value: null });
+            }
+            else {
+                issues.push({ path: [relationship], message: `${relationship} is required` });
+            }
+            continue;
+        }
+        const definition = field.property?.definition;
+        if (definition !== undefined && "default" in definition) {
+            columns.push({ field, value: definition.default });
+        }
+        else if (field.nullable) {
+            columns.push({ field, value: null });
+        }
+        else {
+            issues.push({ path: [field.name], message: `${field.name} is required` });
+        }
+    }
+}
+/** Whether a string can be a record id. Anything else names no record. */
+export function isRecordId(value) {
+    return isUuid(value);
+}

package/dist/runtime/resolve-agent-identity.d.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { AgentResolution, AgentStore, ResolveIdentityInput } from "../service/runtime-contract.js";
+/** Account admission shares pairing's lock and creates User plus identity in one transaction. */
+export declare function resolveAgentIdentity(ontology: Ontology, sql: SqlClient.SqlClient, store: AgentStore, input: ResolveIdentityInput, context?: "agent" | "channel_app"): Effect.Effect<AgentResolution>;