@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/runtime/agent-tasks.js

@@ -0,0 +1,120 @@
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { AGENT_TASKS_TABLE } from "../storage/tables.js";
+/** How long tasks are kept after their deadline, for diagnosis, before the next start deletes them. */
+export const AGENT_TASK_RETENTION_DAYS = 30;
+const COLUMNS = `"id"::text AS "id", "workflow", "run_id", "hook_token", "prompt", "status", "result", ` +
+    `"deadline_at"`;
+const LIVE = `"status" IN ('pending', 'started')`;
+/** The terminal outcome a row's status and `result` fields describe. */
+function resultOf(status, stored) {
+    const fields = (typeof stored === "string" ? JSON.parse(stored) : (stored ?? {}));
+    switch (status) {
+        case "pending":
+        case "started":
+            return undefined;
+        case "completed":
+        case "needs_input":
+            return { status, text: String(fields.text ?? ""), truncated: fields.truncated === true };
+        case "failed":
+            return {
+                status,
+                reason: fields.reason,
+            };
+        case "timed_out":
+            return { status };
+    }
+}
+/** The fields of a terminal outcome that `result` stores; the status has its own column. */
+function storedFields(result) {
+    switch (result.status) {
+        case "completed":
+        case "needs_input":
+            return { text: result.text, truncated: result.truncated };
+        case "failed":
+            return { reason: result.reason };
+        case "timed_out":
+            return null;
+    }
+}
+function recordOf(row) {
+    return {
+        id: row.id,
+        workflow: row.workflow,
+        runId: row.run_id,
+        hookToken: row.hook_token,
+        prompt: row.prompt,
+        status: row.status,
+        result: resultOf(row.status, row.result),
+        deadlineAt: row.deadline_at instanceof Date ? row.deadline_at : new Date(row.deadline_at),
+    };
+}
+/** The task store over `_agent_tasks`. Database failures are defects. */
+export function sqlAgentTaskStore(sql) {
+    const one = (text, params) => sql
+        .unsafe(text, params)
+        .pipe(Effect.map(([row]) => (row === undefined ? undefined : recordOf(row))));
+    const byHook = (hookToken) => one(`SELECT ${COLUMNS} FROM "${AGENT_TASKS_TABLE}" WHERE "hook_token" = $1`, [hookToken]);
+    const byId = (id) => one(`SELECT ${COLUMNS} FROM "${AGENT_TASKS_TABLE}" WHERE "id" = $1::uuid`, [id]);
+    return {
+        byHook: (hookToken) => byHook(hookToken).pipe(Effect.orDie),
+        live: (secretSha256) => one(`SELECT ${COLUMNS} FROM "${AGENT_TASKS_TABLE}" ` +
+            `WHERE "secret_sha256" = $1 AND ${LIVE} AND "deadline_at" > now()`, [secretSha256]).pipe(Effect.orDie),
+        create: (input) => sql
+            .withTransaction(Effect.gen(function* () {
+            const existing = yield* byHook(input.hookToken);
+            if (existing !== undefined) {
+                return { status: "existing", task: existing };
+            }
+            // Concurrent starts count the live tasks one at a time, so that at most `limit` are.
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock(hashtextextended($1, 0))`, [
+                AGENT_TASKS_TABLE,
+            ]);
+            yield* sql.unsafe(`DELETE FROM "${AGENT_TASKS_TABLE}" ` +
+                `WHERE "deadline_at" < now() - make_interval(days => $1)`, [AGENT_TASK_RETENTION_DAYS]);
+            const [counted] = yield* sql.unsafe(`SELECT count(*)::text AS "live" FROM "${AGENT_TASKS_TABLE}" ` +
+                `WHERE ${LIVE} AND "deadline_at" > now()`);
+            if (Number(counted?.live ?? 0) >= input.limit) {
+                return { status: "busy" };
+            }
+            const created = yield* one(`INSERT INTO "${AGENT_TASKS_TABLE}" ` +
+                `("id", "workflow", "run_id", "hook_token", "secret_sha256", "prompt", "status", ` +
+                `"deadline_at") VALUES ($1::uuid, $2, $3, $4, $5, $6, 'pending', ` +
+                `now() + make_interval(secs => $7::double precision / 1000)) ` +
+                `ON CONFLICT ("hook_token") DO NOTHING RETURNING ${COLUMNS}`, [
+                randomUUID(),
+                input.workflow,
+                input.runId,
+                input.hookToken,
+                input.secretSha256,
+                input.prompt,
+                input.timeoutMs,
+            ]);
+            if (created !== undefined) {
+                return { status: "created", task: created };
+            }
+            // Another attempt of the same step inserted it first.
+            const raced = yield* byHook(input.hookToken);
+            return raced === undefined
+                ? yield* Effect.die(new Error("The agent task's row disappeared after a conflict."))
+                : { status: "existing", task: raced };
+        }))
+            .pipe(Effect.orDie),
+        rekey: (id, secretSha256) => sql
+            .unsafe(`UPDATE "${AGENT_TASKS_TABLE}" SET "secret_sha256" = $2 ` +
+            `WHERE "id" = $1::uuid AND "status" = 'pending' RETURNING "id"::text AS "id"`, [id, secretSha256])
+            .pipe(Effect.map((rows) => rows.length > 0), Effect.orDie),
+        markStarted: (id) => sql
+            .unsafe(`UPDATE "${AGENT_TASKS_TABLE}" SET "status" = 'started', "started_at" = now() ` +
+            `WHERE "id" = $1::uuid AND "status" = 'pending' RETURNING "id"::text AS "id"`, [id])
+            .pipe(Effect.map((rows) => rows.length > 0), Effect.orDie),
+        finish: (id, result) => Effect.gen(function* () {
+            const fields = storedFields(result);
+            const finished = yield* one(`UPDATE "${AGENT_TASKS_TABLE}" SET "status" = $2, "result" = $3::jsonb, ` +
+                `"finished_at" = now() WHERE "id" = $1::uuid AND ${LIVE} RETURNING ${COLUMNS}`, [id, result.status, fields === null ? null : JSON.stringify(fields)]);
+            return finished !== undefined
+                ? { finished: true, task: finished }
+                : { finished: false, task: yield* byId(id) };
+        }).pipe(Effect.orDie),
+    };
+}

package/dist/runtime/agents.d.ts

@@ -0,0 +1,15 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import { type AgentStore, type ResolveIdentityInput, type ChannelSignInInput } from "../service/runtime-contract.js";
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ * Chats the agent sees are `agent_chat` records, written as the platform with history.
+ */
+export declare function sqlAgentStore(ontology: Ontology, sql: SqlClient.SqlClient): AgentStore;
+/** Shared verified admission for agents and channel-app adapters; never expose trusted inputs to browsers. */
+export declare function resolveChannelIdentity(ontology: Ontology, sql: SqlClient.SqlClient, input: ResolveIdentityInput): Effect.Effect<import("../index.js").AgentResolution, never, never>;
+/** Call only after verifying a channel-app assertion. Shares admission, limits and onboarding with agents. */
+export declare function resolveChannelSignIn(ontology: Ontology, sql: SqlClient.SqlClient, input: ChannelSignInInput): Effect.Effect<import("../index.js").AgentResolution, never, never>;

package/dist/runtime/agents.js

@@ -0,0 +1,457 @@
+import { sqlConfirmationStore } from "./confirmations.js";
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { AgentChat } from "../agent-chat.js";
+import { AGENT_IDENTITIES_TABLE, AGENT_PAIRINGS_TABLE, CHANNEL_USERS_TABLE, IDENTITY_NOTICES_TABLE, USER_TABLE, } from "../migrate/storage.js";
+import { MAX_QUERY_LIMIT } from "../query.js";
+import { beginReplicationWrite } from "../replication/transaction.js";
+import { IdentityInUse, } from "../service/runtime-contract.js";
+import { revokeChannelSessions } from "./channel-session-revocation.js";
+import { resolveAgentIdentity } from "./resolve-agent-identity.js";
+import { completeAgentLimitNotice } from "./agent-counters.js";
+import { isMemberBlocked, setMemberBlocked, resolveMemberById } from "./principals.js";
+import { isRecordId } from "./records.js";
+import { makeOntologyRuntime } from "./sql-runtime.js";
+import { CHANNEL_IDENTITIES_FROM, CHANNEL_ORIGIN_SQL, CHANNEL_REVOKED_AT, LIVE_CHANNEL_IDENTITY, makeIdentityWriter, USER_IDENTITY_TABLE, } from "./user-identities.js";
+const PAIRINGS = `"${AGENT_PAIRINGS_TABLE}"`;
+/** The legacy channel accounts, written beside `user_identity` for earlier SDKs. */
+const LEGACY_IDENTITIES = `"${AGENT_IDENTITIES_TABLE}"`;
+const USERS = `"${USER_TABLE}"`;
+/** A timestamp as epoch milliseconds, which every driver returns as a plain number. */
+function epochMs(column) {
+    return `(extract(epoch from ${column}) * 1000)::double precision`;
+}
+const PAIRING_COLUMNS = `"id"::text AS "id", "provider", "external_id", "display", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+/** Channel accounts are `user_identity` records `i`, with their first-contact notice `n`. */
+const IDENTITIES_FROM = `${CHANNEL_IDENTITIES_FROM} LEFT JOIN "${IDENTITY_NOTICES_TABLE}" AS "n" ` +
+    `ON "n"."identity_id" = "i"."id"`;
+const CHANNEL_ACCOUNT = `"i"."origin"::text IN ${CHANNEL_ORIGIN_SQL}`;
+/** Revoked in either store: see {@link CHANNEL_IDENTITIES_FROM}. */
+const REVOKED_AT = CHANNEL_REVOKED_AT;
+const IDENTITY_COLUMNS = `"i"."id"::text AS "id", "i"."provider", "i"."subject" AS "external_id", ` +
+    `"i"."user_id"::text AS "user_id", "i"."display", ` +
+    `${epochMs(`"i"."created_at"`)} AS "created_at", ${epochMs(REVOKED_AT)} AS "revoked_at", ` +
+    `"i"."username", "i"."origin"::text AS "origin", ${epochMs(`"n"."noticed_at"`)} AS "noticed_at", ` +
+    `"n"."notice_sha256", "n"."notice_version"`;
+/**
+ * How often a chat's `last_message_at` is recorded: each record is a history row, and a busy chat
+ * would otherwise add one per message.
+ */
+const CHAT_MESSAGE_RECORD_INTERVAL_MS = 15 * 60 * 1000;
+/** Whether a chat's latest message is recorded: it has none yet, or none this interval. */
+function messageDue(lastMessageAt, now) {
+    const last = typeof lastMessageAt === "string" ? Date.parse(lastMessageAt) : Number.NaN;
+    return Number.isNaN(last) || now.getTime() - last >= CHAT_MESSAGE_RECORD_INTERVAL_MS;
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function pairingOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        display: nullableText(row.display),
+        expiresAt: new Date(Number(row.expires_at)),
+    };
+}
+function identityOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        userId: String(row.user_id),
+        display: nullableText(row.display),
+        ...(typeof row.username === "string" ? { username: row.username } : {}),
+        createdAt: new Date(Number(row.created_at)),
+        revokedAt: row.revoked_at === null ? null : new Date(Number(row.revoked_at)),
+        // The wire keeps the names `_agent_identities` gave the origins.
+        origin: row.origin === "channel" ? "provisioned" : "paired",
+        noticedAt: row.noticed_at === null ? null : new Date(Number(row.noticed_at)),
+        noticeSha256: nullableText(row.notice_sha256),
+        noticeVersion: nullableText(row.notice_version),
+    };
+}
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ * Chats the agent sees are `agent_chat` records, written as the platform with history.
+ */
+export function sqlAgentStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    const memberPrincipal = (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql));
+    const store = {
+        confirmations: sqlConfirmationStore(sql),
+        savePairing: (pairing) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${PAIRINGS} WHERE "expires_at" <= now()`);
+            const inserted = yield* rows([
+                `INSERT INTO ${PAIRINGS}`,
+                `  ("id", "code_hash", "provider", "external_id", "display", "expires_at")`,
+                `VALUES ($1::uuid, $2, $3, $4, $5, $6::timestamptz)`,
+                `ON CONFLICT ("code_hash") DO NOTHING`,
+                `RETURNING "id"`,
+            ].join("\n"), [
+                pairing.id,
+                pairing.codeHash,
+                pairing.provider,
+                pairing.externalId,
+                pairing.display,
+                pairing.expiresAt.toISOString(),
+            ]);
+            return inserted.length > 0;
+        }))
+            .pipe(Effect.orDie),
+        findPairing: (codeHash) => rows([
+            `SELECT ${PAIRING_COLUMNS}`,
+            `FROM ${PAIRINGS}`,
+            `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+        ].join("\n"), [codeHash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : pairingOf(row)))),
+        approvePairing: ({ codeHash, userId, identityId }) => sql
+            .withTransaction(Effect.gen(function* () {
+            // Consume once before locking; IdentityInUse must roll this transaction back to keep the code usable.
+            const [consumed] = yield* rows([
+                `UPDATE ${PAIRINGS} SET "consumed_at" = now()`,
+                `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+                `RETURNING ${PAIRING_COLUMNS}`,
+            ].join("\n"), [codeHash]);
+            if (consumed === undefined) {
+                return undefined;
+            }
+            const pairing = pairingOf(consumed);
+            // Two approvals that replace the same account's or the same member's identity run one
+            // after the other, so the partial unique indexes never refuse a valid one.
+            yield* rows(`SELECT pg_advisory_xact_lock(hashtext($1)), pg_advisory_xact_lock(hashtext($2))`, [
+                `account:${pairing.provider}:${pairing.externalId}`,
+                `member:${userId}:${pairing.provider}`,
+            ]);
+            // Blocking locks User FOR UPDATE. Keep both the new member and previous account
+            // owners stable until approval commits, then recheck their block state. An owner only
+            // the legacy store knows, as an earlier SDK may have paired, counts too.
+            const owners = yield* rows(`SELECT "id"::text AS "id", "kind"::text AS "kind", "active" FROM ${USERS}
+               WHERE "id" = $3::uuid OR "id" IN (
+                 SELECT "user_id" FROM "${USER_IDENTITY_TABLE}" AS "i"
+                 WHERE "i"."provider" = $1 AND "i"."subject" = $2 AND ${CHANNEL_ACCOUNT}
+               ) OR "id" IN (
+                 SELECT "user_id" FROM ${LEGACY_IDENTITIES} WHERE "provider" = $1 AND "external_id" = $2
+               ) ORDER BY "id" FOR SHARE`, [pairing.provider, pairing.externalId, userId]);
+            const target = owners.find((owner) => owner.id === userId);
+            if (target?.kind !== "member" ||
+                !target.active ||
+                (yield* isMemberBlocked(sql, userId))) {
+                return yield* new IdentityInUse({});
+            }
+            // Any member who ever held the account and is blocked keeps it from being paired.
+            const [blocked] = yield* rows(`SELECT 1 FROM "${CHANNEL_USERS_TABLE}" c WHERE c."user_id" IN (` +
+                owners.map((_, index) => `$${index + 1}::uuid`).join(", ") +
+                `) AND c."blocked_at" IS NOT NULL LIMIT 1`, owners.map((owner) => String(owner.id)));
+            if (blocked !== undefined) {
+                return yield* new IdentityInUse({});
+            }
+            const [bound] = yield* rows(`SELECT ${IDENTITY_COLUMNS} FROM ${IDENTITIES_FROM} ` +
+                `WHERE "i"."provider" = $1 AND "i"."subject" = $2 AND ${LIVE_CHANNEL_IDENTITY}`, [pairing.provider, pairing.externalId]);
+            if (bound !== undefined) {
+                if (String(bound.user_id) !== userId) {
+                    return yield* new IdentityInUse({});
+                }
+                return identityOf(bound);
+            }
+            const [legacyBound] = yield* rows(`SELECT "user_id"::text AS "user_id" FROM ${LEGACY_IDENTITIES}
+               WHERE "provider" = $1 AND "external_id" = $2 AND "revoked_at" IS NULL`, [pairing.provider, pairing.externalId]);
+            // Paired only in the legacy store, by an earlier SDK: the next migration copies it.
+            if (legacyBound !== undefined && String(legacyBound.user_id) !== userId) {
+                return yield* new IdentityInUse({});
+            }
+            const at = new Date().toISOString();
+            const writer = makeIdentityWriter(ontology, sql, {
+                action: `${USER_IDENTITY_TABLE}.pair`,
+                actionId: randomUUID(),
+            });
+            // The member's live account of the provider is displaced, and the account's own record
+            // that the legacy store revoked or no longer holds is revoked too, freeing its key.
+            const replaced = yield* rows(`SELECT "i"."id"::text AS "id" FROM ${CHANNEL_IDENTITIES_FROM}
+               WHERE "i"."revoked_at" IS NULL AND ${CHANNEL_ACCOUNT} AND "i"."provider" = $1
+                 AND ("i"."user_id" = $2::uuid OR ("i"."subject" = $3
+                   AND ("a"."id" IS NULL OR "a"."revoked_at" IS NOT NULL)))
+               ORDER BY "i"."id" FOR UPDATE OF "i"`, [pairing.provider, userId, pairing.externalId]);
+            for (const identity of replaced) {
+                yield* writer.revoke(String(identity.id), at);
+            }
+            const displaced = yield* rows([
+                `UPDATE ${LEGACY_IDENTITIES} SET "revoked_at" = $3::timestamptz`,
+                `WHERE "revoked_at" IS NULL AND "provider" = $1`,
+                `  AND "user_id" = $2::uuid RETURNING "id"::text AS "id"`,
+            ].join("\n"), [pairing.provider, userId, at]);
+            for (const id of new Set([...replaced, ...displaced].map((row) => String(row.id)))) {
+                yield* revokeChannelSessions(sql, id);
+            }
+            yield* writer.create({
+                id: identityId,
+                provider: pairing.provider,
+                issuer: null,
+                subject: pairing.externalId,
+                userId,
+                origin: "pairing",
+                display: pairing.display,
+            });
+            yield* rows([
+                `INSERT INTO ${LEGACY_IDENTITIES} ("id", "provider", "external_id", "user_id", "display")`,
+                `VALUES ($1::uuid, $2, $3, $4::uuid, $5)`,
+            ].join("\n"), [identityId, pairing.provider, pairing.externalId, userId, pairing.display]);
+            const [created] = yield* rows(`SELECT ${IDENTITY_COLUMNS} FROM ${IDENTITIES_FROM} WHERE "i"."id" = $1::uuid`, [identityId]);
+            return created === undefined ? undefined : identityOf(created);
+        }))
+            .pipe(Effect.catchIf((error) => error._tag !== "IdentityInUse", (error) => Effect.die(error))),
+        resolveIdentity: (input) => resolveAgentIdentity(ontology, sql, store, input),
+        completeLimitNotice: (input) => completeAgentLimitNotice(sql, input),
+        setMemberBlocked: (input) => setMemberBlocked(ontology, input).pipe(Effect.provideService(SqlClient.SqlClient, sql), Effect.as(true), Effect.catchTag("MemberNotFound", () => Effect.succeed(false))),
+        // The notice is operational state beside the identity; the legacy columns are kept in step.
+        recordNotice: ({ provider, externalId, sha256, version }) => sql
+            .withTransaction(Effect.gen(function* () {
+            const noticed = yield* rows(`INSERT INTO "${IDENTITY_NOTICES_TABLE}" ` +
+                `("identity_id", "noticed_at", "notice_sha256", "notice_version") ` +
+                `SELECT "i"."id", now(), $3, $4 FROM ${CHANNEL_IDENTITIES_FROM} ` +
+                `WHERE "i"."provider" = $1 AND "i"."subject" = $2 AND ${LIVE_CHANNEL_IDENTITY} ` +
+                `AND EXISTS (SELECT 1 FROM "${CHANNEL_USERS_TABLE}" c WHERE c."user_id" = "i"."user_id"
+                 AND c."created_via" NOT IN ('invite', 'email')) ` +
+                `ON CONFLICT ("identity_id") DO UPDATE SET "noticed_at" = now(), ` +
+                `"notice_sha256" = EXCLUDED."notice_sha256", ` +
+                `"notice_version" = EXCLUDED."notice_version" ` +
+                `WHERE "${IDENTITY_NOTICES_TABLE}"."notice_version" IS DISTINCT FROM EXCLUDED."notice_version" ` +
+                `OR "${IDENTITY_NOTICES_TABLE}"."notice_sha256" IS DISTINCT FROM EXCLUDED."notice_sha256" ` +
+                `RETURNING "identity_id"`, [provider, externalId, sha256, version ?? null]);
+            yield* rows(`UPDATE ${LEGACY_IDENTITIES} SET "noticed_at" = now(), "notice_sha256" = $3, "notice_version" = $4 ` +
+                `WHERE "provider" = $1 AND "external_id" = $2 AND "revoked_at" IS NULL ` +
+                `AND EXISTS (SELECT 1 FROM "${CHANNEL_USERS_TABLE}" c WHERE c."user_id" = ${LEGACY_IDENTITIES}."user_id"
+                 AND c."created_via" NOT IN ('invite', 'email')) AND ("noticed_at" IS NULL
+                 OR "notice_version" IS DISTINCT FROM $4 OR "notice_sha256" IS DISTINCT FROM $3)`, [provider, externalId, sha256, version ?? null]);
+            return noticed.length > 0;
+        }))
+            .pipe(Effect.orDie),
+        findIdentity: ({ provider, externalId }) => rows([
+            `SELECT ${IDENTITY_COLUMNS}`,
+            `FROM ${IDENTITIES_FROM}`,
+            `WHERE "i"."provider" = $1 AND "i"."subject" = $2 AND ${CHANNEL_ACCOUNT}`,
+            `ORDER BY ${REVOKED_AT} IS NOT NULL, ${REVOKED_AT} DESC`,
+            `LIMIT 1`,
+        ].join("\n"), [provider, externalId]).pipe(Effect.map(([row]) => (row === undefined ? undefined : identityOf(row)))),
+        listIdentities: (userId) => isRecordId(userId)
+            ? rows([
+                `SELECT ${IDENTITY_COLUMNS}`,
+                `FROM ${IDENTITIES_FROM}`,
+                `WHERE "i"."user_id" = $1::uuid AND ${LIVE_CHANNEL_IDENTITY}`,
+                `ORDER BY "i"."created_at", "i"."id"`,
+            ].join("\n"), [userId]).pipe(Effect.map((found) => found.map(identityOf)))
+            : Effect.succeed([]),
+        revokeIdentity: ({ id, userId }) => isRecordId(id) && isRecordId(userId)
+            ? sql
+                .withTransaction(Effect.gen(function* () {
+                const [live] = yield* rows(`SELECT "i"."id"::text AS "id" FROM ${CHANNEL_IDENTITIES_FROM}
+                   WHERE "i"."id" = $1::uuid AND "i"."user_id" = $2::uuid AND ${LIVE_CHANNEL_IDENTITY}
+                   FOR UPDATE OF "i"`, [id, userId]);
+                if (live === undefined) {
+                    return false;
+                }
+                const at = new Date().toISOString();
+                yield* makeIdentityWriter(ontology, sql, {
+                    action: `${USER_IDENTITY_TABLE}.revoke`,
+                    actionId: randomUUID(),
+                }).revoke(id, at);
+                // @legacy identities.legacy-stores-dual-write
+                yield* rows(`UPDATE ${LEGACY_IDENTITIES} SET "revoked_at" = $3::timestamptz
+                   WHERE "id" = $1::uuid AND "user_id" = $2::uuid AND "revoked_at" IS NULL`, [id, userId, at]);
+                yield* revokeChannelSessions(sql, id);
+                return true;
+            }))
+                .pipe(Effect.orDie)
+            : Effect.succeed(false),
+        member: (userId) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const principal = yield* memberPrincipal(userId);
+            if (principal === undefined) {
+                return undefined;
+            }
+            const [user] = yield* rows(`SELECT "name" FROM ${USERS} WHERE "id" = $1::uuid`, [userId]);
+            return { name: String(user?.name ?? ""), principal };
+        }),
+        actingMember: (userId, provider) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const [paired] = yield* rows(`SELECT "i"."provider" FROM ${CHANNEL_IDENTITIES_FROM}
+           WHERE "i"."user_id" = $1::uuid AND ${LIVE_CHANNEL_IDENTITY}
+           AND ($2::text IS NULL OR "i"."provider" = $2) ORDER BY "i"."created_at" LIMIT 1`, [userId, provider ?? null]);
+            const principal = paired === undefined ? undefined : yield* memberPrincipal(userId);
+            return principal === undefined || provider === undefined
+                ? principal
+                : { ...principal, authenticatedVia: provider };
+        }),
+        seeChat: ({ provider, externalId, title, memberId, leftMemberId, agentLeft, migratedFrom }) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
+            const previous = migratedFrom === undefined || migratedFrom === externalId ? undefined : migratedFrom;
+            // Calls for one chat run one after the other: the first creates it, the rest find it. A
+            // migration locks both chats, in one order, so that two calls never wait on each other.
+            for (const id of [externalId, ...(previous === undefined ? [] : [previous])].sort()) {
+                yield* rows(`SELECT pg_advisory_xact_lock(hashtext($1))`, [`chat:${provider}:${id}`]);
+            }
+            const runtime = makeOntologyRuntime(ontology, sql, {
+                action: `${AgentChat.name}.seen`,
+                actionId: randomUUID(),
+                principalId: null,
+            });
+            const now = new Date();
+            const chatOf = (id) => runtime
+                .find({
+                entity: AgentChat.name,
+                options: { where: { provider, external_id: id }, limit: 1, forUpdate: true },
+            })
+                .pipe(Effect.map(([chat]) => chat));
+            const membersOf = (id) => runtime
+                .related({
+                entity: AgentChat.name,
+                id,
+                relationship: "members",
+                query: { limit: MAX_QUERY_LIMIT },
+            })
+                .pipe(Effect.map((page) => page.items.map((member) => String(member.id))));
+            // Unlinks every member of the chat, linking each to `to` first when given. Each page
+            // unlinked is gone, so the first page is read until it is empty.
+            const releaseMembers = (id, to) => Effect.gen(function* () {
+                for (;;) {
+                    const members = yield* membersOf(id);
+                    if (members.length === 0) {
+                        return;
+                    }
+                    for (const targetId of members) {
+                        if (to !== undefined) {
+                            yield* runtime.link({
+                                entity: AgentChat.name,
+                                relationship: "members",
+                                id: to,
+                                targetId,
+                            });
+                        }
+                        yield* runtime.unlink({
+                            entity: AgentChat.name,
+                            relationship: "members",
+                            id,
+                            targetId,
+                        });
+                    }
+                }
+            });
+            let found = yield* chatOf(externalId);
+            if (previous !== undefined) {
+                const old = yield* chatOf(previous);
+                if (old !== undefined && found === undefined) {
+                    // The group became a supergroup: the chat keeps its record under its new id.
+                    found = yield* runtime.update({
+                        entity: AgentChat.name,
+                        id: String(old.id),
+                        values: { external_id: externalId },
+                    });
+                }
+                else if (old !== undefined && found !== undefined) {
+                    // Both were recorded: the new one keeps what members said and gains the members,
+                    // and the old one is deleted.
+                    const kept = {};
+                    for (const key of ["purpose", "when_to_use"]) {
+                        if (nullableText(found[key]) === null && nullableText(old[key]) !== null) {
+                            kept[key] = old[key];
+                        }
+                    }
+                    if (Object.keys(kept).length > 0) {
+                        found = yield* runtime.update({
+                            entity: AgentChat.name,
+                            id: String(found.id),
+                            values: kept,
+                        });
+                    }
+                    yield* releaseMembers(String(old.id), String(found.id));
+                    yield* runtime.delete({ entity: AgentChat.name, id: String(old.id) });
+                }
+            }
+            const changes = {
+                ...(found?.title === title ? {} : { title }),
+                ...(messageDue(found?.last_message_at, now)
+                    ? { last_message_at: now.toISOString() }
+                    : {}),
+            };
+            const chat = found === undefined
+                ? yield* runtime.create({
+                    entity: AgentChat.name,
+                    values: { provider, external_id: externalId, ...changes },
+                })
+                : Object.keys(changes).length === 0
+                    ? found
+                    : yield* runtime.update({
+                        entity: AgentChat.name,
+                        id: String(found.id),
+                        values: changes,
+                    });
+            if (memberId !== undefined && isRecordId(memberId)) {
+                const [member] = yield* rows(`SELECT 1 FROM ${USERS} WHERE "id" = $1::uuid AND "kind"::text = 'member' AND "active"`, [memberId]);
+                // A link already there changes nothing and records no history.
+                if (member !== undefined) {
+                    yield* runtime.link({
+                        entity: AgentChat.name,
+                        relationship: "members",
+                        id: String(chat.id),
+                        targetId: memberId,
+                    });
+                }
+            }
+            if (leftMemberId !== undefined && isRecordId(leftMemberId)) {
+                const [user] = yield* rows(`SELECT 1 FROM ${USERS} WHERE "id" = $1::uuid`, [
+                    leftMemberId,
+                ]);
+                // Whatever their state now; a member who is not linked changes nothing and records no
+                // history.
+                if (user !== undefined) {
+                    yield* runtime.unlink({
+                        entity: AgentChat.name,
+                        relationship: "members",
+                        id: String(chat.id),
+                        targetId: leftMemberId,
+                    });
+                }
+            }
+            if (agentLeft === true) {
+                // The agent left: no member is in the chat with it any more. The chat stays; members
+                // link again when they write after the agent is back.
+                yield* releaseMembers(String(chat.id));
+            }
+            return {
+                id: String(chat.id),
+                title: String(chat.title),
+                purpose: nullableText(chat.purpose),
+                whenToUse: nullableText(chat.when_to_use),
+            };
+        }))
+            .pipe(Effect.orDie),
+    };
+    return store;
+}
+/** Shared verified admission for agents and channel-app adapters; never expose trusted inputs to browsers. */
+export function resolveChannelIdentity(ontology, sql, input) {
+    return sqlAgentStore(ontology, sql).resolveIdentity(input);
+}
+/** Call only after verifying a channel-app assertion. Shares admission, limits and onboarding with agents. */
+export function resolveChannelSignIn(ontology, sql, input) {
+    const { provider, externalId, display, username } = input;
+    const identity = {
+        provider,
+        externalId,
+        chat: "private",
+        turn: false,
+        ...(display === undefined ? {} : { display }),
+        ...(username === undefined ? {} : { username }),
+    };
+    return resolveAgentIdentity(ontology, sql, sqlAgentStore(ontology, sql), identity, "channel_app");
+}

package/dist/runtime/batch-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import { Effect } from "effect";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import type { EntityModel } from "./model.js";
+interface CauseDiagnostic {
+    readonly tag: string;
+    readonly message: string;
+    readonly messageRedacted: boolean;
+    readonly stack?: string;
+}
+/** A safe projection of every wrapper; the original driver cause stays on the Conflict itself. */
+export declare function batchConflictDiagnostic(entity: EntityModel, error: SqlError): {
+    causeChain: CauseDiagnostic[];
+    constraint?: string | undefined;
+    sqlState: string;
+};
+/** Emit before mapping the error, so even a handler-caught conflict has a correlated diagnostic. */
+export declare function logBatchConflict(entity: EntityModel, error: SqlError, scope: {
+    readonly operation: string;
+    readonly action: string;
+    readonly actionId: string;
+}): Effect.Effect<void>;
+export {};