@segmentstream-cloud/ontology 0.10.0 → 0.12.0

package/dist/replication/store.d.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type ReplicationEvent, type ReplicationSelection, type ReplicationExclusion } from "./model.js";
+import { type ReplicationTarget } from "./baseline.js";
+export type { ReplicationTarget } from "./baseline.js";
+export declare const startReplication: (sql: SqlClient.SqlClient, input: {
+    readonly generation: string;
+    readonly exclusions?: ReadonlyArray<ReplicationExclusion>;
+    readonly selection?: ReadonlyArray<ReplicationSelection>;
+    readonly newSource?: boolean;
+}) => Effect.Effect<ReplicationTarget, import("../index.js").CatalogInvalid | import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const activeReplicationTarget: (sql: SqlClient.SqlClient) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const pauseReplication: (sql: SqlClient.SqlClient) => import("effect/unstable/sql/Statement").Statement<object>;
+export declare const replicationTarget: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** No timestamp/high-water cursor: every unacknowledged immutable event remains discoverable. */
+export declare function replicationEventsSql(target: ReplicationTarget): string;
+export declare const pendingReplicationEvents: (sql: SqlClient.SqlClient, target: ReplicationTarget) => Effect.Effect<{
+    readonly historyId: string;
+    readonly event: ReplicationEvent;
+}[], import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Call only after Pub/Sub accepts the complete batch. Lost responses deliberately produce duplicates. */
+export declare const acknowledgeReplication: (sql: SqlClient.SqlClient, generation: string, ids: ReadonlyArray<string>) => import("effect/unstable/sql/Statement").Statement<object>;
+export declare const replayReplication: (sql: SqlClient.SqlClient, generation: string) => import("effect/unstable/sql/Statement").Statement<object>;
+export declare const replicationStatus: (sql: SqlClient.SqlClient, target: ReplicationTarget) => Effect.Effect<{
+    total: string;
+    accepted: string;
+    verified: string;
+}, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const unverifiedReplicationEvents: (sql: SqlClient.SqlClient, target: ReplicationTarget) => Effect.Effect<{
+    historyId: string;
+    eventId: string;
+}[], import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const verifyReplicationEvents: (sql: SqlClient.SqlClient, generation: string, ids: ReadonlyArray<string>) => import("effect/unstable/sql/Statement").Statement<object>;
+/** Retry accepted events that never appeared, including dead letters and transport expiry. */
+export declare const retryUnverifiedReplication: (sql: SqlClient.SqlClient, generation: string) => import("effect/unstable/sql/Statement").Statement<object>;

package/dist/replication/store.js

@@ -0,0 +1,88 @@
+import { Effect } from "effect";
+import { readCatalog } from "../migrate/apply.js";
+import { historyTableName, quoteIdentifier as qi } from "../migrate/storage.js";
+import { REPLICATION_BATCH_BYTES, REPLICATION_BATCH_SIZE, publishMessage, replicationEventId, resolveReplicationSelection, } from "./model.js";
+import { createReplicationBaseline } from "./baseline.js";
+export const startReplication = (sql, input) => sql.withTransaction(Effect.gen(function* () {
+    yield* sql.unsafe("SET LOCAL statement_timeout = '30s'");
+    yield* sql.unsafe("SET LOCAL lock_timeout = '5s'");
+    yield* sql.unsafe("SELECT id FROM _ontology_replication WHERE id FOR UPDATE");
+    const manifest = yield* readCatalog({ sql });
+    if (!manifest) {
+        return yield* Effect.die(new Error("The ontology has not been migrated."));
+    }
+    const selection = input.selection ??
+        (yield* Effect.sync(() => resolveReplicationSelection(manifest, input.exclusions)));
+    return yield* createReplicationBaseline(sql, { ...input, manifest, selection });
+}));
+export const activeReplicationTarget = (sql) => sql
+    .unsafe(`SELECT t.generation::text, t.source_id::text, t.from_revision::text, t.manifest, t.selection
+     FROM _ontology_replication_targets t JOIN _ontology_replication r ON r.active_generation = t.generation
+     WHERE r.id`)
+    .pipe(Effect.map((rows) => rows[0]));
+export const pauseReplication = (sql) => sql.unsafe("UPDATE _ontology_replication SET enabled = false WHERE id");
+export const replicationTarget = (sql, generation) => sql
+    .unsafe(`SELECT generation::text, source_id::text, from_revision::text, manifest, selection
+     FROM _ontology_replication_targets WHERE generation = $1::uuid`, [generation])
+    .pipe(Effect.map((rows) => rows[0]));
+/** No timestamp/high-water cursor: every unacknowledged immutable event remains discoverable. */
+export function replicationEventsSql(target) {
+    const histories = target.selection.map((item) => {
+        const entity = target.manifest.entities.find((e) => e.id === item.entityId);
+        return `SELECT id, replication AS event FROM ${qi(historyTableName(entity.name))}
+      WHERE replication IS NOT NULL AND replication->>'source_id' = $2
+      AND (replication->>'revision')::bigint > $3::bigint`;
+    });
+    const baseline = `SELECT id, event FROM _ontology_replication_baselines WHERE generation = $1::uuid
+    AND $2::text IS NOT NULL AND $3::bigint IS NOT NULL`;
+    return [baseline, ...histories].join(" UNION ALL ");
+}
+export const pendingReplicationEvents = (sql, target) => sql
+    .unsafe(`SELECT e.id::text, e.event FROM (${replicationEventsSql(target)}) e
+     WHERE NOT EXISTS (SELECT 1 FROM _ontology_replication_receipts r
+       WHERE r.generation = $1::uuid AND r.event_id = e.id)
+     ORDER BY (event->>'revision')::bigint, id LIMIT ${REPLICATION_BATCH_SIZE}`, [target.generation, target.source_id, target.from_revision])
+    .pipe(Effect.map((rows) => {
+    let size = 32;
+    const result = [];
+    for (const row of rows) {
+        const event = {
+            ...row.event,
+            generation: target.generation,
+            event_id: replicationEventId(target.source_id, row.id, target.generation),
+        };
+        const bytes = Buffer.byteLength(JSON.stringify(publishMessage(event))) + 1;
+        if (bytes + 32 > REPLICATION_BATCH_BYTES) {
+            throw new Error("A replication event exceeds the publish request limit.");
+        }
+        if (size + bytes > REPLICATION_BATCH_BYTES) {
+            break;
+        }
+        size += bytes;
+        result.push({ historyId: row.id, event });
+    }
+    return result;
+}));
+/** Call only after Pub/Sub accepts the complete batch. Lost responses deliberately produce duplicates. */
+export const acknowledgeReplication = (sql, generation, ids) => sql.unsafe(`INSERT INTO _ontology_replication_receipts (generation, event_id)
+     SELECT $1::uuid, value::uuid FROM jsonb_array_elements_text($2::jsonb) ON CONFLICT DO NOTHING`, [generation, JSON.stringify(ids)]);
+export const replayReplication = (sql, generation) => sql.unsafe("DELETE FROM _ontology_replication_receipts WHERE generation = $1::uuid", [
+    generation,
+]);
+export const replicationStatus = (sql, target) => sql
+    .unsafe(`SELECT count(*)::text AS total, count(r.event_id)::text AS accepted, count(r.verified_at)::text AS verified
+     FROM (${replicationEventsSql(target)}) e
+     LEFT JOIN _ontology_replication_receipts r ON r.generation = $1::uuid AND r.event_id = e.id`, [target.generation, target.source_id, target.from_revision])
+    .pipe(Effect.map((rows) => rows[0]));
+export const unverifiedReplicationEvents = (sql, target) => sql
+    .unsafe(`SELECT event_id::text AS id FROM _ontology_replication_receipts
+     WHERE generation = $1::uuid AND verified_at IS NULL ORDER BY accepted_at, event_id LIMIT 1000`, [target.generation])
+    .pipe(Effect.map((rows) => rows.map(({ id }) => ({
+    historyId: id,
+    eventId: replicationEventId(target.source_id, id, target.generation),
+}))));
+export const verifyReplicationEvents = (sql, generation, ids) => sql.unsafe(`UPDATE _ontology_replication_receipts SET verified_at = now()
+    WHERE generation = $1::uuid AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`, [generation, JSON.stringify(ids)]);
+/** Retry accepted events that never appeared, including dead letters and transport expiry. */
+export const retryUnverifiedReplication = (sql, generation) => sql.unsafe(`DELETE FROM _ontology_replication_receipts WHERE generation = $1::uuid
+    AND verified_at IS NULL AND accepted_at < now() - interval '15 minutes'`, [generation]);

package/dist/replication/transaction.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+/** Must run inside the write transaction, before any business row locks. */
+export declare const beginReplicationWrite: (sql: SqlClient.SqlClient) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/replication/transaction.js

@@ -0,0 +1,11 @@
+import { Effect } from "effect";
+/** Must run inside the write transaction, before any business row locks. */
+export const beginReplicationWrite = (sql) => Effect.gen(function* () {
+    const [schema] = yield* sql.unsafe("SELECT to_regclass('_ontology_replication') IS NOT NULL AS present");
+    if (!schema?.present) {
+        return;
+    } // Platform principal operations also serve pre-upgrade databases.
+    yield* sql.unsafe("SELECT set_config('segmentstream.writer', '1', true)");
+    // Lock even while disabled: enabling and the baseline must exclude concurrent writes.
+    yield* sql.unsafe("SELECT id FROM _ontology_replication WHERE id FOR UPDATE");
+});

package/dist/runtime/generated-actions.d.ts

@@ -1,3 +1,4 @@
+import { Schema } from "effect";
 import { type AnyAction } from "../action.js";
 import type { JsonSchemaObject } from "../analyze.js";
 import type { Ontology } from "../ontology.js";
@@ -14,6 +15,8 @@ export declare function upsertActionName(property: string): string;
  * and services by the app or the CLI.
  */
 export declare function generatedActions(ontology: Ontology, entityName: string): GeneratedActions;
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export declare function actionInputJsonSchema(input: Schema.Top): JsonSchemaObject;
 /** A generated action, described as the manifest describes authored ones. */
 export interface GeneratedActionManifest {
     readonly name: string;

package/dist/runtime/generated-actions.js

@@ -166,7 +166,8 @@ function buildGeneratedActions(ontology, entityName) {
     }
     return actions;
 }
-function inputJsonSchema(input) {
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export function actionInputJsonSchema(input) {
     const document = Schema.toJsonSchemaDocument(input, {
         includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
         onExcessProperty: "error",
@@ -182,6 +183,6 @@ export function generatedActionManifests(ontology, entityName) {
         name,
         description: generated.description,
         permissions: generatedActionPermissions(entityName, name),
-        input: inputJsonSchema(generated.input),
+        input: actionInputJsonSchema(generated.input),
     }));
 }

package/dist/runtime/oauth.d.ts

@@ -0,0 +1,9 @@
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { OAuthStore } from "../service/runtime-contract.js";
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * `now()`; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export declare function sqlOAuthStore(ontology: Ontology, sql: SqlClient.SqlClient): OAuthStore;

package/dist/runtime/oauth.js

@@ -0,0 +1,165 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { OAUTH_CLIENTS_TABLE, OAUTH_GRANTS_TABLE, OAUTH_REQUESTS_TABLE, OAUTH_TOKENS_TABLE, } from "../migrate/storage.js";
+import { resolveMemberById } from "./principals.js";
+const CLIENTS = `"${OAUTH_CLIENTS_TABLE}"`;
+const REQUESTS = `"${OAUTH_REQUESTS_TABLE}"`;
+const GRANTS = `"${OAUTH_GRANTS_TABLE}"`;
+const TOKENS = `"${OAUTH_TOKENS_TABLE}"`;
+const CLIENT_COLUMNS = `"id", "name", "redirect_uris"::text AS "redirect_uris", "auth_method", "secret_hash", ` +
+    `"client_uri"`;
+/** 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 REQUEST_COLUMNS = `"id", "client_id", "redirect_uri", "state", "code_challenge", "scope", "resource", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+/** The grant's columns, read through the alias `g`. */
+const GRANT_COLUMNS = `"g"."id"::text AS "grant_id", "g"."client_id" AS "client_id", ` +
+    `"g"."user_id"::text AS "user_id", "g"."scope" AS "scope", "g"."resource" AS "resource"`;
+function text(value) {
+    return String(value);
+}
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function date(value) {
+    return new Date(Number(value));
+}
+function clientOf(row) {
+    return {
+        id: text(row.id),
+        name: text(row.name),
+        redirectUris: JSON.parse(text(row.redirect_uris)),
+        authMethod: text(row.auth_method),
+        secretHash: nullableText(row.secret_hash),
+        clientUri: nullableText(row.client_uri),
+    };
+}
+function requestOf(row) {
+    return {
+        id: text(row.id),
+        clientId: text(row.client_id),
+        redirectUri: text(row.redirect_uri),
+        state: nullableText(row.state),
+        codeChallenge: text(row.code_challenge),
+        scope: text(row.scope),
+        resource: text(row.resource),
+        expiresAt: date(row.expires_at),
+    };
+}
+function grantOf(row) {
+    return {
+        id: text(row.grant_id),
+        clientId: text(row.client_id),
+        userId: text(row.user_id),
+        scope: text(row.scope),
+        resource: text(row.resource),
+    };
+}
+function tokenOf(row) {
+    return {
+        hash: text(row.hash),
+        grantId: text(row.grant_id),
+        kind: text(row.kind),
+        expiresAt: date(row.expires_at),
+        ...(row.redirect_uri === null ? {} : { redirectUri: text(row.redirect_uri) }),
+        ...(row.code_challenge === null ? {} : { codeChallenge: text(row.code_challenge) }),
+    };
+}
+const INSERT_TOKEN = `INSERT INTO ${TOKENS} ("hash", "grant_id", "kind", "redirect_uri", "code_challenge", ` +
+    `"expires_at") VALUES ($1, $2::uuid, $3, $4, $5, $6::timestamptz)`;
+function tokenValues(token) {
+    return [
+        token.hash,
+        token.grantId,
+        token.kind,
+        token.redirectUri ?? null,
+        token.codeChallenge ?? null,
+        token.expiresAt.toISOString(),
+    ];
+}
+/**
+ * The OAuth store on the runtime's OAuth tables, as `ontology_app`. Expiry is the database's
+ * `now()`; codes and refresh tokens are used with one `UPDATE … WHERE "used_at" IS NULL`, so two
+ * concurrent uses cannot both succeed.
+ */
+export function sqlOAuthStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    return {
+        saveClient: (client) => rows(`INSERT INTO ${CLIENTS} ("id", "name", "redirect_uris", "auth_method", "secret_hash", ` +
+            `"client_uri") VALUES ($1, $2, $3::jsonb, $4, $5, $6)`, [
+            client.id,
+            client.name,
+            JSON.stringify(client.redirectUris),
+            client.authMethod,
+            client.secretHash,
+            client.clientUri,
+        ]).pipe(Effect.asVoid),
+        findClient: (id) => rows(`SELECT ${CLIENT_COLUMNS} FROM ${CLIENTS} WHERE "id" = $1`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : clientOf(row)))),
+        saveRequest: (request) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${REQUESTS} WHERE "expires_at" <= now()`);
+            yield* rows(`INSERT INTO ${REQUESTS} ("id", "client_id", "redirect_uri", "state", ` +
+                `"code_challenge", "scope", "resource", "expires_at") ` +
+                `VALUES ($1, $2, $3, $4, $5, $6, $7, $8::timestamptz)`, [
+                request.id,
+                request.clientId,
+                request.redirectUri,
+                request.state,
+                request.codeChallenge,
+                request.scope,
+                request.resource,
+                request.expiresAt.toISOString(),
+            ]);
+        }))
+            .pipe(Effect.orDie),
+        findRequest: (id) => rows(`SELECT ${REQUEST_COLUMNS} FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now()`, [
+            id,
+        ]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        takeRequest: (id) => rows(`DELETE FROM ${REQUESTS} WHERE "id" = $1 AND "expires_at" > now() ` +
+            `RETURNING ${REQUEST_COLUMNS}`, [id]).pipe(Effect.map(([row]) => (row === undefined ? undefined : requestOf(row)))),
+        saveGrant: (grant, code) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`INSERT INTO ${GRANTS} ("id", "client_id", "user_id", "scope", "resource") ` +
+                `VALUES ($1::uuid, $2, $3::uuid, $4, $5)`, [grant.id, grant.clientId, grant.userId, grant.scope, grant.resource]);
+            yield* rows(INSERT_TOKEN, tokenValues(code));
+        }))
+            .pipe(Effect.orDie),
+        useToken: (hash, kind) => Effect.gen(function* () {
+            const [used] = yield* rows(`UPDATE ${TOKENS} AS "t" SET "used_at" = now() FROM ${GRANTS} AS "g" ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NULL ` +
+                `AND "t"."expires_at" > now() AND "g"."id" = "t"."grant_id" ` +
+                `AND "g"."revoked_at" IS NULL ` +
+                `RETURNING "t"."hash" AS "hash", "t"."kind" AS "kind", ` +
+                `"t"."redirect_uri" AS "redirect_uri", "t"."code_challenge" AS "code_challenge", ` +
+                `${epochMs(`"t"."expires_at"`)} AS "expires_at", ${GRANT_COLUMNS}`, [hash, kind]);
+            if (used !== undefined) {
+                return { status: "valid", token: tokenOf(used), grant: grantOf(used) };
+            }
+            const [reused] = yield* rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+                `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+                `WHERE "t"."hash" = $1 AND "t"."kind" = $2 AND "t"."used_at" IS NOT NULL ` +
+                `AND "t"."expires_at" > now() AND "g"."revoked_at" IS NULL`, [hash, kind]);
+            return reused === undefined
+                ? { status: "invalid" }
+                : { status: "reused", grant: grantOf(reused) };
+        }),
+        saveTokens: (tokens) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${TOKENS} WHERE "expires_at" <= now()`);
+            for (const token of tokens) {
+                yield* rows(INSERT_TOKEN, tokenValues(token));
+            }
+        }))
+            .pipe(Effect.orDie),
+        findAccess: (hash) => rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" ` +
+            `WHERE "t"."hash" = $1 AND "t"."kind" = 'access' AND "t"."expires_at" > now() ` +
+            `AND "g"."revoked_at" IS NULL`, [hash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : grantOf(row)))),
+        findGrantOfToken: (hash) => rows(`SELECT ${GRANT_COLUMNS} FROM ${TOKENS} AS "t" ` +
+            `JOIN ${GRANTS} AS "g" ON "g"."id" = "t"."grant_id" WHERE "t"."hash" = $1`, [hash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : grantOf(row)))),
+        revokeGrant: (id) => rows(`UPDATE ${GRANTS} SET "revoked_at" = now() WHERE "id" = $1::uuid AND "revoked_at" IS NULL`, [id]).pipe(Effect.asVoid),
+        memberPrincipal: (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql)),
+    };
+}

package/dist/runtime/pipeline.js

@@ -1,4 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
+import { beginReplicationWrite } from "../replication/transaction.js";
 import { Cause, Duration, Effect, Option, Schema } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
@@ -204,7 +205,7 @@ export function runAction(ontology, request) {
             return result;
         });
         const result = yield* sql
-            .withTransaction(transactionalHandler)
+            .withTransaction(beginReplicationWrite(sql).pipe(Effect.andThen(transactionalHandler)))
             .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
         if (replay) {
             return replay;

package/dist/runtime/principals.d.ts

@@ -54,6 +54,11 @@ export declare function resolvePrincipalByIdentity(ontology: Ontology, claims: I
  * revoked keys and inactive users are rejected.
  */
 export declare function resolvePrincipalByApiKey(ontology: Ontology, key: string): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export declare function resolveMemberById(ontology: Ontology, userId: string): Effect.Effect<Principal | undefined, never, SqlClient.SqlClient>;
 export interface CreatedApiKey {
     readonly id: string;
     /** The key itself. It is not stored and cannot be shown again. */

package/dist/runtime/principals.js

@@ -11,6 +11,7 @@ import { buildOntology } from "../ontology.js";
 import { permissionsOf } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
 import { role } from "../role.js";
+import { beginReplicationWrite } from "../replication/transaction.js";
 import { User } from "../user.js";
 import { MemberNotFound, PrincipalRejected, UnknownRole } from "./errors.js";
 import { isRecordId } from "./records.js";
@@ -116,6 +117,7 @@ function signIn(ontology, sql, claims) {
     const email = claimedEmail !== undefined && EMAIL_PATTERN.test(claimedEmail) ? claimedEmail : undefined;
     return sql
         .withTransaction(Effect.gen(function* () {
+        yield* beginReplicationWrite(sql);
         const now = new Date();
         const signedIn = { last_sign_in_at: now.toISOString() };
         const [linked] = yield* runtime.find({
@@ -241,6 +243,21 @@ export function resolvePrincipalByApiKey(ontology, key) {
         return yield* activePrincipal(ontology, sql, decodeUser({ id: row.id, kind: row.kind, active: row.active }));
     }).pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
 }
+/**
+ * A member by user id, with the roles they hold now: whom an OAuth grant acts for. `undefined` for
+ * an unknown user, a service and an inactive member.
+ */
+export function resolveMemberById(ontology, userId) {
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql.unsafe(`SELECT "id"::text AS "id", "kind"::text AS "kind", "active" AS "active" ` +
+            `FROM "${USER_TABLE}" WHERE "id" = $1::uuid`, [userId]);
+        if (row === undefined || row.kind !== "member" || row.active !== true) {
+            return undefined;
+        }
+        return yield* rolesOf(ontology, sql, decodeUser(row));
+    }).pipe(Effect.orDie);
+}
 /** Issues an API key for a user. */
 export function createApiKey(input) {
     return Effect.gen(function* () {
@@ -280,6 +297,7 @@ export function setUserRoles(ontology, input) {
         }
         const roles = [...new Set(input.roles)];
         yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
             yield* sql.unsafe(`DELETE FROM "${USER_ROLES_TABLE}" WHERE "user_id" = $1::uuid`, [
                 input.userId,
             ]);
@@ -298,6 +316,7 @@ export function createServiceUser(ontology, input) {
         const sql = yield* SqlClient.SqlClient;
         const runtime = platformRuntime(ontology, sql, "user.create_service");
         return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
             const user = yield* runtime
                 .create({ entity: "user", values: { name: input.name, kind: "service" } })
                 .pipe(Effect.orDie);
@@ -561,6 +580,7 @@ export function updateMemberRoles(ontology, change) {
         yield* refuseMember(revoke === "all" ? [] : revoke);
         const runtime = platformRuntime(ontology, sql, "user.invite");
         const attempt = sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
             const found = yield* lockUser(runtime, { email });
             if (found !== undefined && found.kind !== "member") {
                 return yield* new MemberNotFound({
@@ -621,6 +641,7 @@ export function setMemberActive(ontology, input) {
         const action = input.active ? "user.reactivate" : "user.deactivate";
         const runtime = platformRuntime(ontology, sql, action);
         return yield* sql.withTransaction(Effect.gen(function* () {
+            yield* beginReplicationWrite(sql);
             const user = yield* lockUser(runtime, input);
             if (user === undefined || user.kind !== "member") {
                 return yield* memberNotFound(input);

package/dist/runtime/service-binding.js

@@ -7,6 +7,7 @@ import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
 import { generatedActions } from "./generated-actions.js";
+import { sqlOAuthStore } from "./oauth.js";
 import { runAction } from "./pipeline.js";
 import { checkSignIn, resolvePrincipalByApiKey, resolvePrincipalByIdentity } from "./principals.js";
 import { postgresTls } from "./postgres-tls.js";
@@ -59,6 +60,15 @@ export function backendLayer(ontology, blobStorage) {
             checkSignIn: (email) => withSql(checkSignIn(ontology, email)),
             resolveApiKey: (key) => withSql(resolvePrincipalByApiKey(ontology, Redacted.value(key))).pipe(Effect.catchTag("PrincipalRejected", rejectedAs("api_key"))),
             appliedHash: readCatalog({ sql }).pipe(Effect.map((manifest) => manifest?.hash), Effect.orDie),
+            replicationEnabled: Effect.gen(function* () {
+                const [presence] = yield* sql.unsafe("SELECT to_regclass('_ontology_replication') IS NOT NULL AS present");
+                if (!presence?.present) {
+                    return false;
+                }
+                const [state] = yield* sql.unsafe("SELECT enabled FROM _ontology_replication WHERE id");
+                return state?.enabled === true;
+            }).pipe(Effect.orDie),
+            oauth: sqlOAuthStore(ontology, sql),
         });
     }));
 }

package/dist/runtime/sql-runtime.js

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { beginReplicationWrite } from "../replication/transaction.js";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { Conflict } from "../errors.js";
 import { InvalidQuery, WriteOutsideAction } from "./errors.js";
@@ -67,7 +68,7 @@ export function makeOntologyRuntime(ontology, sql, scope) {
         }
         const edits = [];
         const result = yield* sql
-            .withTransaction(operation({ ...context, scope, edits }, entity))
+            .withTransaction(beginReplicationWrite(sql).pipe(Effect.andThen(operation({ ...context, scope, edits }, entity))))
             .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(entity, error)));
         for (const edit of edits) {
             scope.onEdit?.(edit);

package/dist/service/api.js

@@ -5,6 +5,7 @@ import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
 import { generatedActions } from "../runtime/generated-actions.js";
 import { Authentication } from "./authentication.js";
+import { actionDescription, requires } from "./descriptions.js";
 import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
 import { planApi, } from "./plan.js";
 import { ActionResponse, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
@@ -58,10 +59,6 @@ const connectionActionErrors = [
     ErrorSchemas.connectionResponseInvalid,
     ErrorSchemas.connectionUnavailable,
 ];
-/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
-function requires(permissions) {
-    return `Requires ${permissions.join(" and ")}.`;
-}
 function readPermission(entity) {
     return permissionOf(entity, READ_VERB);
 }
@@ -75,17 +72,14 @@ function traversalEndpoint(planned, traversal, target, targetNames) {
     return documented(endpoint, `${label} ${traversal.phrase} ${reach} (${traversal.name})`, `${traversal.description}\n\n${requires(permissions)} Including a relationship requires ` +
         "reading its entity too.");
 }
-function actionEndpoint(planned, { name, action, generated, permissions }) {
+function actionEndpoint(planned, plannedAction) {
+    const { name, action } = plannedAction;
     const endpoint = HttpApiEndpoint.post(`actions.${name}`, `${BASE_PATH}/${planned.name}/actions/${name}`, {
         payload: actionRequest(action.input),
         success: ActionResponse,
         error: action.connections.length > 0 ? connectionActionErrors : actionErrors,
     });
-    const origin = generated ? "Generated action." : "Action.";
-    const calls = action.connections.length > 0
-        ? ` Calls ${action.connections.map((handle) => handle.key).join(", ")} before its transaction.`
-        : "";
-    return documented(endpoint, `${planned.name}.${name}`, `${action.description}\n\n${origin} ${requires(permissions)}${calls}`);
+    return documented(endpoint, `${planned.name}.${name}`, actionDescription(plannedAction));
 }
 function entityGroup(planned, schemas, names) {
     const own = schemas.get(planned.name);

package/dist/service/authentication.d.ts

@@ -1,4 +1,5 @@
 import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpServerRequest, type HttpServerResponse } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
 import { type JWTVerifyGetKey } from "jose";
 import type { Principal } from "../runtime.js";
@@ -117,8 +118,33 @@ type Authenticated = {
 } | {
     readonly status: "unavailable";
 };
+/** Where a credential is presented. */
+export interface CredentialOptions {
+    /**
+     * The resource OAuth access tokens must have been issued for: the MCP server's URL. Elsewhere,
+     * an access token is rejected, as it was issued for the MCP server only.
+     */
+    readonly oauthResource?: string;
+}
 /** Resolves a bearer credential to a principal. */
-export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier): Effect.Effect<Authenticated, never, OntologyBackend>;
+export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
+/** A browser's request, which may authenticate with the app's Neon Auth session cookie. */
+export interface BrowserSession {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly exchange: SessionExchange | undefined;
+}
+/**
+ * Runs `effect` as the principal a bearer credential names, or answers the request as every route
+ * does: 401 without a valid credential, 403 for a person nobody invited or a session cookie sent
+ * from another origin, 503 while sign-in cannot be verified, and a sanitized 500 when
+ * authentication itself fails.
+ */
+export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, backend: OntologyBackend["Service"], effect: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, options?: CredentialOptions & {
+    /** The `WWW-Authenticate` challenge of a 401, by whether the credential was missing. */
+    readonly challenge?: (missing: boolean) => string;
+    /** Without a bearer token, the app's session cookie may authenticate this browser request. */
+    readonly session?: BrowserSession;
+}): Effect.Effect<HttpServerResponse.HttpServerResponse, E, Exclude<R, CurrentPrincipal> | RequestId>;
 /**
  * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
  * a request without a bearer token may authenticate with the app's Neon Auth session cookie.