@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/writes.d.ts

@@ -0,0 +1,108 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { Conflict, ScopeViolated, type NotFound } from "../errors.js";
+import type { StoredRecord, StoredValues, UpsertResult } from "../runtime.js";
+import { type Edit, type HistoryScope } from "./history.js";
+import { type EntityModel } from "./model.js";
+import { type SqlContext } from "./reads.js";
+import { Aliases, Params } from "./statement.js";
+import { type RowScope } from "./where.js";
+/**
+ * Writes inside one action. Each write records its history rows in the same transaction and
+ * collects its edits; the runtime hands them to the action once the write has succeeded.
+ */
+export interface WriteContext extends SqlContext {
+    readonly scope: HistoryScope;
+    readonly edits: Array<Edit>;
+    /** When set, the stored record before and after each create, update and delete. */
+    readonly snapshots?: Array<RecordSnapshot>;
+}
+/**
+ * A record a write changed, as stored before and after it: `before` is undefined on a create,
+ * `after` on a delete. Action triggers read them; links and unlinks change neither.
+ */
+export interface RecordSnapshot {
+    readonly entity: string;
+    readonly id: string;
+    readonly before: StoredRecord | undefined;
+    readonly after: StoredRecord | undefined;
+}
+type WriteError = Conflict | NotFound | ScopeViolated | SqlError;
+/** A scoped permission a write of one record must stay inside. */
+export interface ScopeCheck {
+    /** The permission whose scope it is, for example `staff_member:update`. */
+    readonly permission: string;
+    readonly scope: RowScope;
+}
+/**
+ * The scopes an action's writes of its own entity are checked against: `create` for records it
+ * creates (after the insert), `change` for records it updates, deletes, links or unlinks (before the
+ * change and, except for a delete, after it). Absent when the acting principal holds the action's
+ * permissions unscoped.
+ */
+export interface WriteGuard {
+    /** The action's entity; writes of other entities run with the action's authority. */
+    readonly entity: string;
+    readonly create?: ScopeCheck;
+    readonly change?: ScopeCheck;
+}
+/** The scope condition on the table aliased `alias`, with its own aliases from `aliases`. */
+export declare function scopeCondition(context: SqlContext, entity: EntityModel, params: Params, aliases: Aliases, alias: string, check: ScopeCheck): string;
+export declare function scopeViolated(entity: EntityModel, check: ScopeCheck, id?: string, batch?: {
+    readonly indices: ReadonlyArray<number>;
+}): ScopeViolated;
+/**
+ * Creates a record; with a guard, the record must be inside its `create` scope. `id` is for the
+ * platform's own records that keep an id issued before them; every other record gets a new one.
+ */
+export declare function createRecord(context: WriteContext, entity: EntityModel, values: StoredValues, guard?: WriteGuard, id?: string): Effect.Effect<StoredRecord, WriteError>;
+/**
+ * Updates a record. With a check, the record must be inside its scope before the change (else
+ * NotFound) and after it (else ScopeViolated).
+ */
+export declare function updateRecord(context: WriteContext, entity: EntityModel, id: string, values: StoredValues, check?: ScopeCheck): Effect.Effect<StoredRecord, WriteError>;
+/**
+ * Creates the record, or updates the one with the same value of a unique property. The insert
+ * yields to an existing record with `ON CONFLICT DO NOTHING`, which also waits for a concurrent
+ * insert of the same value; the existing record is then locked and updated with the given values
+ * only, so defaults never overwrite it.
+ */
+export declare function upsertRecord(context: WriteContext, entity: EntityModel, property: string, values: StoredValues, guard?: WriteGuard): Effect.Effect<UpsertResult, WriteError>;
+/**
+ * Deletes a record after applying what each relationship pointing at it asks for: `restrict`
+ * refuses, `cascade` deletes the dependent records and `setNull` clears their key, each with its
+ * own history. Join rows go too, with an unlink in the history of both records. Doing this here
+ * rather than through the foreign keys keeps every change in history.
+ *
+ * With a check, the record must be inside its scope before the delete (else NotFound), and so must
+ * every record of the same entity the delete cascades to or clears, however many relationships
+ * away (else ScopeViolated): a cascade writes the action's entity with the caller's scope too.
+ */
+export declare function deleteRecord(context: WriteContext, entity: EntityModel, id: string, deleting?: Set<string>, check?: ScopeCheck): Effect.Effect<void, WriteError>;
+/** Links two records through a `rel.many` the entity declares. Linking twice changes nothing. */
+export declare function linkRecords(context: WriteContext, entity: EntityModel, input: {
+    readonly relationship: string;
+    readonly id: string;
+    readonly targetId: string;
+}, check?: ScopeCheck): Effect.Effect<void, NotFound | ScopeViolated | SqlError>;
+/** Removes a link between two existing records. Unlinking records that are not linked changes nothing. */
+export declare function unlinkRecords(context: WriteContext, entity: EntityModel, input: {
+    readonly relationship: string;
+    readonly id: string;
+    readonly targetId: string;
+}, check?: ScopeCheck): Effect.Effect<void, NotFound | ScopeViolated | SqlError>;
+/** A change to a user's role assignments. A role in both `grant` and `revoke` stays assigned. */
+export interface UserRolesChange {
+    readonly grant?: ReadonlyArray<string>;
+    /** Roles to remove, or every assigned role. */
+    readonly revoke?: ReadonlyArray<string> | "all";
+}
+/**
+ * Grants and revokes a user's roles, which the caller checked against the ontology, and records the
+ * change as an update of the user: one history row with `roles` before and after, and a new
+ * `updated_at`. A change that leaves the roles as they were writes nothing. Granting a role the
+ * user holds, or revoking one they do not, changes nothing. The record returned carries the new
+ * roles.
+ */
+export declare function changeUserRoles(context: WriteContext, entity: EntityModel, id: string, change: UserRolesChange): Effect.Effect<StoredRecord, NotFound | SqlError>;
+export {};

package/dist/runtime/writes.js

@@ -0,0 +1,491 @@
+import { Effect } from "effect";
+import { resolveBlobWrites } from "../storage/writes.js";
+import { Conflict, ScopeViolated } from "../errors.js";
+import { ACTION_ATTRIBUTION_TABLE, USER_ROLES_TABLE, quoteIdentifier } from "../migrate/storage.js";
+import { canonicalJson } from "../manifest.js";
+import { User } from "../user.js";
+import { InvalidValues } from "./errors.js";
+import { uuidv7 } from "./ids.js";
+import { diffRecords, insertHistory, } from "./history.js";
+import { entityModel } from "./model.js";
+import { loadRecord, normalizeId, notFound, requireRecords } from "./reads.js";
+import { bindValue, decodeRecord, prepareWrite, selectList, } from "./records.js";
+import { Aliases, columnOf, Params } from "./statement.js";
+import { USER_ROLES_PROPERTY } from "./user-roles.js";
+import { compileScope } from "./where.js";
+/** The scope condition on the table aliased `alias`, with its own aliases from `aliases`. */
+export function scopeCondition(context, entity, params, aliases, alias, check) {
+    return compileScope({ model: context.model, params, aliases }, entity, alias, check.scope);
+}
+/**
+ * The after-check: fails with ScopeViolated unless the record, as the write left it, is inside the
+ * scope. It runs in the write's own savepoint, so the failure rolls the write and its history back.
+ */
+function requireInScope(context, entity, id, check) {
+    return Effect.gen(function* () {
+        if (check === undefined) {
+            return;
+        }
+        const params = new Params();
+        const aliases = new Aliases();
+        const alias = aliases.take();
+        const scope = scopeCondition(context, entity, params, aliases, alias, check);
+        const rows = yield* context.run(`SELECT 1 AS "inside" FROM ${quoteIdentifier(entity.table)} AS ${quoteIdentifier(alias)} ` +
+            `WHERE ${columnOf(alias, "id")} = ${params.add(id, "uuid")} AND (${scope})`, params);
+        if (rows.length === 0) {
+            return yield* scopeViolated(entity, check, id);
+        }
+    });
+}
+export function scopeViolated(entity, check, id, batch) {
+    return new ScopeViolated({
+        entity: entity.name,
+        ...(id === undefined ? {} : { id }),
+        permission: check.permission,
+        message: `${check.permission} does not cover the ${entity.label.toLowerCase()} as the change ` +
+            "would leave it.",
+        ...(batch === undefined ? {} : { batch: { indices: [...batch.indices] } }),
+    });
+}
+/** Records an edit: one history row, and the edit for the action's response. */
+function recordEdit(context, entity, edit, snapshot) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        if (context.scope.execution !== undefined) {
+            const attribution = new Params();
+            yield* context.run(`INSERT INTO "${ACTION_ATTRIBUTION_TABLE}" (action_id, execution) VALUES (` +
+                `${attribution.add(context.scope.actionId, "uuid")}, ` +
+                `${attribution.add(JSON.stringify(context.scope.execution), "jsonb")}) ON CONFLICT DO NOTHING`, attribution);
+        }
+        yield* context.run(insertHistory(context.scope, { entity, edit }, params), params);
+        context.edits.push(edit);
+        if (snapshot !== undefined) {
+            context.snapshots?.push({ entity: entity.name, id: edit.id, ...snapshot });
+        }
+    });
+}
+function requireReferences(context, references) {
+    return Effect.forEach(references, (reference) => requireRecords(context, entityModel(context.model, reference.link.target), [reference.id]), { discard: true });
+}
+function insertRecord(context, entity, values, onConflict, check, id) {
+    return Effect.gen(function* () {
+        const recordId = id ?? uuidv7();
+        const resolved = yield* resolveBlobWrites(context, entity, recordId, values, true);
+        const write = yield* prepareWrite(entity, resolved, "create");
+        yield* requireReferences(context, write.references);
+        const params = new Params();
+        const principal = params.add(context.scope.principalId, "uuid");
+        const columns = [
+            '"id"',
+            '"created_at"',
+            '"updated_at"',
+            '"created_by"',
+            '"updated_by"',
+            ...write.columns.map(({ field }) => quoteIdentifier(field.column)),
+        ];
+        const placeholders = [
+            params.add(recordId, "uuid"),
+            "now()",
+            "now()",
+            principal,
+            principal,
+            ...write.columns.map(({ field, value }) => params.add(bindValue(field, value), field.sqlType)),
+        ];
+        const rows = yield* context.run(`INSERT INTO ${quoteIdentifier(entity.table)} AS "t0" (${columns.join(", ")}) ` +
+            `VALUES (${placeholders.join(", ")})${onConflict} ` +
+            `RETURNING ${selectList(entity, "t0")}`, params);
+        const [row] = rows;
+        if (row === undefined) {
+            return undefined;
+        }
+        const record = yield* decodeRecord(entity, row);
+        yield* recordEdit(context, entity, {
+            entity: entity.name,
+            id: record.id,
+            kind: "create",
+            changes: diffRecords(entity, undefined, record),
+        }, { before: undefined, after: record });
+        yield* setCollections(context, entity, record.id, write.collections);
+        yield* requireInScope(context, entity, record.id, check);
+        return record;
+    });
+}
+/**
+ * Creates a record; with a guard, the record must be inside its `create` scope. `id` is for the
+ * platform's own records that keep an id issued before them; every other record gets a new one.
+ */
+export function createRecord(context, entity, values, guard, id) {
+    return insertRecord(context, entity, values, "", guard?.create, id).pipe(Effect.map((record) => record));
+}
+/**
+ * Updates a record. With a check, the record must be inside its scope before the change (else
+ * NotFound) and after it (else ScopeViolated).
+ */
+export function updateRecord(context, entity, id, values, check) {
+    return Effect.gen(function* () {
+        const before = yield* loadRecord(context, entity, id, "update", check?.scope);
+        if (before === undefined) {
+            return yield* notFound(entity, id);
+        }
+        const resolved = yield* resolveBlobWrites(context, entity, id, values, false);
+        const write = yield* prepareWrite(entity, resolved, "update");
+        yield* requireReferences(context, write.references);
+        let after = before;
+        if (write.columns.length > 0) {
+            const params = new Params();
+            const assignments = write.columns.map(({ field, value }) => `${quoteIdentifier(field.column)} = ${params.add(bindValue(field, value), field.sqlType)}`);
+            // Only a real change touches the row, its updated_at and its history.
+            const changed = write.columns.map(({ field, value }) => `${columnOf("t0", field.column)} IS DISTINCT FROM ` +
+                params.add(bindValue(field, value), field.sqlType));
+            const rows = yield* context.run(`UPDATE ${quoteIdentifier(entity.table)} AS "t0" ` +
+                `SET ${assignments.join(", ")}, "updated_at" = now(), ` +
+                `"updated_by" = ${params.add(context.scope.principalId, "uuid")} ` +
+                `WHERE "t0"."id" = ${params.add(before.id, "uuid")} AND (${changed.join(" OR ")}) ` +
+                `RETURNING ${selectList(entity, "t0")}`, params);
+            const [row] = rows;
+            if (row !== undefined) {
+                after = yield* decodeRecord(entity, row);
+                yield* recordEdit(context, entity, {
+                    entity: entity.name,
+                    id: before.id,
+                    kind: "update",
+                    changes: diffRecords(entity, before, after),
+                }, { before, after });
+            }
+        }
+        yield* setCollections(context, entity, before.id, write.collections);
+        yield* requireInScope(context, entity, before.id, check);
+        return after;
+    });
+}
+/**
+ * Creates the record, or updates the one with the same value of a unique property. The insert
+ * yields to an existing record with `ON CONFLICT DO NOTHING`, which also waits for a concurrent
+ * insert of the same value; the existing record is then locked and updated with the given values
+ * only, so defaults never overwrite it.
+ */
+export function upsertRecord(context, entity, property, values, guard) {
+    return Effect.gen(function* () {
+        const field = entity.fieldsByName.get(property);
+        const key = values[property];
+        if (field?.source !== "property" || field.property?.definition.unique !== true) {
+            return yield* Effect.die(new InvalidValues({
+                entity: entity.name,
+                message: `upsertBy needs a unique property of ${entity.name}; ${property} is not one.`,
+                issues: [{ path: [property], message: "Expected a unique property" }],
+            }));
+        }
+        if (key === undefined || key === null) {
+            return yield* Effect.die(new InvalidValues({
+                entity: entity.name,
+                message: `upsertBy("${property}") needs a value of ${property}.`,
+                issues: [{ path: [property], message: `${property} is required` }],
+            }));
+        }
+        // A file ticket for an existing record must not be consumed by a speculative INSERT.
+        if (entity.fields.some((candidate) => candidate.storage === "blob" && values[candidate.name] != null)) {
+            const lookup = new Params();
+            const [existing] = yield* context.run(`SELECT id::text AS id FROM ${quoteIdentifier(entity.table)}
+        WHERE ${quoteIdentifier(field.column)} = ${lookup.add(bindValue(field, key), field.sqlType)} FOR UPDATE`, lookup);
+            if (existing) {
+                const record = yield* updateRecord(context, entity, existing.id, values, guard?.change);
+                return { record, created: false };
+            }
+        }
+        const created = yield* insertRecord(context, entity, values, ` ON CONFLICT (${quoteIdentifier(field.column)}) DO NOTHING`, guard?.create);
+        if (created !== undefined) {
+            return { record: created, created: true };
+        }
+        const params = new Params();
+        const rows = yield* context.run(`SELECT "t0"."id"::text AS "id" FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+            `WHERE ${columnOf("t0", field.column)} = ${params.add(bindValue(field, key), field.sqlType)} ` +
+            `FOR UPDATE OF "t0"`, params);
+        const [existing] = rows;
+        if (existing === undefined) {
+            return yield* new Conflict({
+                entity: entity.name,
+                property,
+                message: `The ${entity.label.toLowerCase()} with this ${property} changed concurrently.`,
+            });
+        }
+        const record = yield* updateRecord(context, entity, existing.id, values, guard?.change);
+        return { record, created: false };
+    });
+}
+/**
+ * Deletes a record after applying what each relationship pointing at it asks for: `restrict`
+ * refuses, `cascade` deletes the dependent records and `setNull` clears their key, each with its
+ * own history. Join rows go too, with an unlink in the history of both records. Doing this here
+ * rather than through the foreign keys keeps every change in history.
+ *
+ * With a check, the record must be inside its scope before the delete (else NotFound), and so must
+ * every record of the same entity the delete cascades to or clears, however many relationships
+ * away (else ScopeViolated): a cascade writes the action's entity with the caller's scope too.
+ */
+export function deleteRecord(context, entity, id, deleting = new Set(), check) {
+    return deleteChecked(context, entity, id, deleting, check === undefined ? undefined : { entity: entity.name, check });
+}
+function deleteChecked(context, entity, id, deleting, cascade) {
+    return Effect.gen(function* () {
+        // A delete is checked before only: the record is gone after it.
+        const check = cascade?.entity === entity.name ? cascade.check : undefined;
+        const before = yield* loadRecord(context, entity, id, "update", check?.scope);
+        if (before === undefined) {
+            return yield* notFound(entity, id);
+        }
+        const recordId = before.id;
+        deleting.add(`${entity.name}:${recordId}`);
+        for (const link of entity.links.values()) {
+            if (link.via === "inverse-key") {
+                yield* releaseDependents(context, entity, recordId, link, deleting, cascade);
+            }
+            else if (link.via === "join") {
+                yield* removeLinks(context, entity, recordId, link);
+            }
+        }
+        const params = new Params();
+        yield* context.run(`DELETE FROM ${quoteIdentifier(entity.table)} WHERE "id" = ${params.add(recordId, "uuid")}`, params);
+        yield* recordEdit(context, entity, {
+            entity: entity.name,
+            id: recordId,
+            kind: "delete",
+            changes: diffRecords(entity, before, undefined),
+        }, { before, after: undefined });
+    });
+}
+function releaseDependents(context, entity, id, link, deleting, cascade) {
+    return Effect.gen(function* () {
+        const dependent = entityModel(context.model, link.target);
+        const params = new Params();
+        const rows = yield* context.run(`SELECT "t0"."id"::text AS "id" FROM ${quoteIdentifier(dependent.table)} AS "t0" ` +
+            `WHERE ${columnOf("t0", link.column)} = ${params.add(id, "uuid")} ` +
+            `ORDER BY "t0"."id" FOR UPDATE OF "t0"`, params);
+        const ids = rows
+            .map((row) => row.id)
+            .filter((candidate) => !deleting.has(`${dependent.name}:${candidate}`));
+        if (ids.length === 0) {
+            return;
+        }
+        if (link.onDelete === "restrict") {
+            return yield* new Conflict({
+                entity: entity.name,
+                message: `The ${entity.label.toLowerCase()} cannot be deleted while ` +
+                    `${dependent.manifest.plural.toLowerCase()} refer to it through ${link.relationship}.`,
+            });
+        }
+        if (cascade?.entity === dependent.name) {
+            yield* requireDependentsInScope(context, dependent, ids, link, cascade.check);
+        }
+        for (const dependentId of ids) {
+            if (link.onDelete === "cascade") {
+                yield* deleteChecked(context, dependent, dependentId, deleting, cascade);
+            }
+            else {
+                yield* updateRecord(context, dependent, dependentId, { [link.relationship]: null });
+            }
+        }
+    });
+}
+/**
+ * The before-check of the records of the action's entity a guarded delete cascades to or clears:
+ * fails with ScopeViolated, without naming a record the caller may not see, unless all are inside
+ * the scope. The cascade's dependents of other entities are written with the action's authority.
+ */
+function requireDependentsInScope(context, dependent, ids, link, check) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const aliases = new Aliases();
+        const alias = aliases.take();
+        const scope = scopeCondition(context, dependent, params, aliases, alias, check);
+        const bound = ids.map((candidate) => params.add(candidate, "uuid"));
+        const rows = yield* context.run(`SELECT count(*)::int AS "inside" FROM ${quoteIdentifier(dependent.table)} AS ` +
+            `${quoteIdentifier(alias)} WHERE ${columnOf(alias, "id")} IN (${bound.join(", ")}) ` +
+            `AND (${scope})`, params);
+        if (Number(rows[0]?.inside ?? 0) < ids.length) {
+            return yield* new ScopeViolated({
+                entity: dependent.name,
+                permission: check.permission,
+                message: `${check.permission} does not cover every ${dependent.label.toLowerCase()} the delete ` +
+                    `would ${link.onDelete === "cascade" ? "delete" : "change"} through ${link.relationship}.`,
+            });
+        }
+    });
+}
+function removeLinks(context, entity, id, link) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const rows = yield* context.run(`DELETE FROM ${quoteIdentifier(link.table)} ` +
+            `WHERE ${quoteIdentifier(link.selfColumn)} = ${params.add(id, "uuid")} ` +
+            `RETURNING ${quoteIdentifier(link.otherColumn)}::text AS "other"`, params);
+        for (const row of rows) {
+            yield* recordLinkEdits(context, entity, link, id, row.other, "unlink");
+        }
+    });
+}
+/** History of a link or an unlink on both records, each keyed by the relationship's name on its side. */
+function recordLinkEdits(context, entity, link, id, targetId, kind) {
+    return Effect.gen(function* () {
+        const target = entityModel(context.model, link.target);
+        const change = (other) => kind === "link" ? { before: null, after: other } : { before: other, after: null };
+        yield* recordEdit(context, entity, {
+            entity: entity.name,
+            id,
+            kind,
+            changes: { [link.name]: change(targetId) },
+        });
+        yield* recordEdit(context, target, {
+            entity: target.name,
+            id: targetId,
+            kind,
+            changes: { [link.inverseName]: change(id) },
+        });
+    });
+}
+function addLink(context, entity, link, id, targetId) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const rows = yield* context.run(`INSERT INTO ${quoteIdentifier(link.table)} ` +
+            `(${quoteIdentifier(link.selfColumn)}, ${quoteIdentifier(link.otherColumn)}, "created_at", "created_by") ` +
+            `VALUES (${params.add(id, "uuid")}, ${params.add(targetId, "uuid")}, now(), ` +
+            `${params.add(context.scope.principalId, "uuid")}) ` +
+            `ON CONFLICT DO NOTHING RETURNING 1 AS "linked"`, params);
+        if (rows.length > 0) {
+            yield* recordLinkEdits(context, entity, link, id, targetId, "link");
+        }
+    });
+}
+function removeLink(context, entity, link, id, targetId) {
+    return Effect.gen(function* () {
+        const params = new Params();
+        const rows = yield* context.run(`DELETE FROM ${quoteIdentifier(link.table)} ` +
+            `WHERE ${quoteIdentifier(link.selfColumn)} = ${params.add(id, "uuid")} ` +
+            `AND ${quoteIdentifier(link.otherColumn)} = ${params.add(targetId, "uuid")} ` +
+            `RETURNING 1 AS "unlinked"`, params);
+        if (rows.length > 0) {
+            yield* recordLinkEdits(context, entity, link, id, targetId, "unlink");
+        }
+    });
+}
+/** Replaces `rel.many` collections: links what is new and unlinks what is gone. */
+function setCollections(context, entity, id, collections) {
+    return Effect.forEach(collections, ({ link, ids }) => Effect.gen(function* () {
+        const params = new Params();
+        const rows = yield* context.run(`SELECT ${quoteIdentifier(link.otherColumn)}::text AS "other" FROM ${quoteIdentifier(link.table)} ` +
+            `WHERE ${quoteIdentifier(link.selfColumn)} = ${params.add(id, "uuid")}`, params);
+        const current = new Set(rows.map((row) => row.other));
+        const wanted = ids.map(normalizeId);
+        const added = wanted.filter((targetId) => !current.has(targetId));
+        const removed = [...current].filter((targetId) => !wanted.includes(targetId));
+        yield* requireRecords(context, entityModel(context.model, link.target), added);
+        for (const targetId of added) {
+            yield* addLink(context, entity, link, id, targetId);
+        }
+        for (const targetId of removed) {
+            yield* removeLink(context, entity, link, id, targetId);
+        }
+    }), { discard: true });
+}
+function joinLink(entity, relationship) {
+    const link = entity.links.get(relationship);
+    if (link?.via !== "join" || link.inverse) {
+        throw new Error(`${entity.name}.${relationship} is not a rel.many of ${entity.name}.`);
+    }
+    return link;
+}
+/** Links two records through a `rel.many` the entity declares. Linking twice changes nothing. */
+export function linkRecords(context, entity, input, check) {
+    return Effect.gen(function* () {
+        const link = joinLink(entity, input.relationship);
+        const id = normalizeId(input.id);
+        const targetId = normalizeId(input.targetId);
+        if (check === undefined) {
+            yield* requireRecords(context, entity, [id]);
+        }
+        else if ((yield* loadRecord(context, entity, id, "update", check.scope)) === undefined) {
+            return yield* notFound(entity, id);
+        }
+        yield* requireRecords(context, entityModel(context.model, link.target), [targetId]);
+        yield* addLink(context, entity, link, id, targetId);
+        yield* requireInScope(context, entity, id, check);
+    });
+}
+/** Removes a link between two existing records. Unlinking records that are not linked changes nothing. */
+export function unlinkRecords(context, entity, input, check) {
+    return Effect.gen(function* () {
+        const link = joinLink(entity, input.relationship);
+        const id = normalizeId(input.id);
+        const targetId = normalizeId(input.targetId);
+        if (check === undefined) {
+            yield* requireRecords(context, entity, [id]);
+        }
+        else if ((yield* loadRecord(context, entity, id, "update", check.scope)) === undefined) {
+            return yield* notFound(entity, id);
+        }
+        yield* requireRecords(context, entityModel(context.model, link.target), [targetId]);
+        yield* removeLink(context, entity, link, id, targetId);
+        yield* requireInScope(context, entity, id, check);
+    });
+}
+/**
+ * Grants and revokes a user's roles, which the caller checked against the ontology, and records the
+ * change as an update of the user: one history row with `roles` before and after, and a new
+ * `updated_at`. A change that leaves the roles as they were writes nothing. Granting a role the
+ * user holds, or revoking one they do not, changes nothing. The record returned carries the new
+ * roles.
+ */
+export function changeUserRoles(context, entity, id, change) {
+    return Effect.gen(function* () {
+        if (entity.name !== User.name || !entity.fieldsByName.has(USER_ROLES_PROPERTY)) {
+            return yield* Effect.die(new Error("Only the built-in user has role assignments."));
+        }
+        const before = yield* loadRecord(context, entity, id, "update");
+        if (before === undefined) {
+            return yield* notFound(entity, id);
+        }
+        const userId = before.id;
+        const grant = [...new Set(change.grant ?? [])];
+        const revoke = change.revoke === "all"
+            ? "all"
+            : [...new Set(change.revoke ?? [])].filter((role) => !grant.includes(role));
+        const table = quoteIdentifier(USER_ROLES_TABLE);
+        if (revoke === "all" || revoke.length > 0) {
+            const params = new Params();
+            const user = params.add(userId, "uuid");
+            const roles = (revoke === "all" ? grant : revoke).map((role) => params.add(role, "text"));
+            const condition = revoke === "all"
+                ? roles.length === 0
+                    ? ""
+                    : ` AND "role" NOT IN (${roles.join(", ")})`
+                : ` AND "role" IN (${roles.join(", ")})`;
+            yield* context.run(`DELETE FROM ${table} WHERE "user_id" = ${user}${condition}`, params);
+        }
+        if (grant.length > 0) {
+            const params = new Params();
+            const user = params.add(userId, "uuid");
+            const rows = grant.map((role) => `(${user}, ${params.add(role, "text")})`);
+            yield* context.run(`INSERT INTO ${table} ("user_id", "role") VALUES ${rows.join(", ")} ` +
+                `ON CONFLICT ("user_id", "role") DO NOTHING`, params);
+        }
+        const params = new Params();
+        const [row] = yield* context.run(`SELECT ${selectList(entity, "t0")} FROM ${quoteIdentifier(entity.table)} AS "t0" ` +
+            `WHERE "t0"."id" = ${params.add(userId, "uuid")}`, params);
+        const current = yield* decodeRecord(entity, row);
+        const previous = (before[USER_ROLES_PROPERTY] ?? []);
+        const next = (current[USER_ROLES_PROPERTY] ?? []);
+        if (canonicalJson(previous) === canonicalJson(next)) {
+            return current;
+        }
+        const touch = new Params();
+        const [touched] = yield* context.run(`UPDATE ${quoteIdentifier(entity.table)} AS "t0" SET "updated_at" = now(), ` +
+            `"updated_by" = ${touch.add(context.scope.principalId, "uuid")} ` +
+            `WHERE "t0"."id" = ${touch.add(userId, "uuid")} RETURNING ${selectList(entity, "t0")}`, touch);
+        const after = yield* decodeRecord(entity, touched);
+        yield* recordEdit(context, entity, {
+            entity: entity.name,
+            id: userId,
+            kind: "update",
+            changes: { [USER_ROLES_PROPERTY]: { before: previous, after: next } },
+        });
+        return after;
+    });
+}

package/dist/runtime-source.d.ts

@@ -0,0 +1,22 @@
+import { Schema } from "effect";
+/** Decoded only at a verified runtime boundary; ordinary action arguments never establish provenance. */
+export declare const RuntimeSource: Schema.Struct<{
+    readonly provider: Schema.Literal<"telegram">;
+    readonly chat_id: Schema.String;
+    readonly thread_id: Schema.String;
+    readonly message_id: Schema.optionalKey<Schema.String>;
+    readonly reply_to_message_id: Schema.optionalKey<Schema.String>;
+    readonly callback_query_id: Schema.optionalKey<Schema.String>;
+    readonly sender: Schema.optionalKey<Schema.String>;
+    readonly attachments: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly file_id: Schema.String;
+        readonly file_unique_id: Schema.optionalKey<Schema.String>;
+        readonly kind: Schema.Literals<readonly ["photo", "document", "voice", "audio", "video", "video_note", "sticker", "animation"]>;
+        readonly media_type: Schema.optionalKey<Schema.String>;
+        readonly staged_id: Schema.String;
+    }>>>;
+}>;
+export type RuntimeSource = typeof RuntimeSource.Type;
+export interface ActionRuntime {
+    readonly source: RuntimeSource;
+}

package/dist/runtime-source.js

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+const Id = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(512));
+/** Decoded only at a verified runtime boundary; ordinary action arguments never establish provenance. */
+export const RuntimeSource = Schema.Struct({
+    provider: Schema.Literal("telegram"),
+    chat_id: Id,
+    thread_id: Schema.String.check(Schema.isMaxLength(512)),
+    message_id: Schema.optionalKey(Id),
+    reply_to_message_id: Schema.optionalKey(Id),
+    callback_query_id: Schema.optionalKey(Id),
+    sender: Schema.optionalKey(Id),
+    attachments: Schema.optionalKey(Schema.Array(Schema.Struct({
+        file_id: Id,
+        file_unique_id: Schema.optionalKey(Id),
+        kind: Schema.Literals([
+            "photo",
+            "document",
+            "voice",
+            "audio",
+            "video",
+            "video_note",
+            "sticker",
+            "animation",
+        ]),
+        media_type: Schema.optionalKey(Schema.String.check(Schema.isMaxLength(128))),
+        staged_id: Id,
+    })).check(Schema.isMaxLength(10))),
+});