@segmentstream-cloud/ontology 0.24.0 → 0.25.0

package/dist/runtime/pipeline.js

@@ -16,6 +16,7 @@ import { Edit } from "./history.js";
 import { makeOntologyRuntime } from "./sql-runtime.js";
 import { AgentFileRecords, resolveFileRecord } from "./files.js";
 import { validate } from "./validation.js";
+import { ACTION_TRANSACTION_LIMITS, ActionTransactionDeadline, ActionTransactions, } from "./action-transactions.js";
 /** How long `prepare` may take, connection calls included; each call has its own 30 s deadline. */
 export const PREPARE_TIMEOUT = Duration.seconds(60);
 export const ActionValidation = Schema.Struct({
@@ -173,6 +174,7 @@ export function runAction(ontology, request) {
             ...(request.branchId ? { branchId: request.branchId } : {}),
             ...(request.options?.createIntent ? { createIntent: request.options.createIntent } : {}),
             onEdit: (edit) => edits.push(edit),
+            replicationInitialized: true,
         });
         const handle = action.handler;
         const handler = Effect.suspend(() => handle({ ...context, prepared }));
@@ -209,9 +211,21 @@ export function runAction(ontology, request) {
             }
             return result;
         });
-        const result = yield* sql
-            .withTransaction(beginReplicationWrite(sql).pipe(Effect.andThen(transactionalHandler)))
-            .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+        const admission = Option.getOrUndefined(yield* Effect.serviceOption(ActionTransactions));
+        const limits = admission?.limits ?? ACTION_TRANSACTION_LIMITS;
+        const transactionBody = Effect.gen(function* () {
+            // Server deadlines also protect the reserved connection if client cancellation cannot arrive.
+            yield* sql.unsafe(`SELECT set_config('statement_timeout', $1, true), set_config('lock_timeout', $2, true)`, [`${limits.statementTimeoutMs}ms`, `${limits.lockTimeoutMs}ms`]);
+            yield* beginReplicationWrite(sql);
+            return yield* transactionalHandler;
+        }).pipe(Effect.timeoutOrElse({
+            duration: Duration.millis(limits.handlerTimeoutMs),
+            orElse: () => Effect.logWarning("ontology.action.transaction_deadline").pipe(Effect.annotateLogs({ deadlineMs: limits.handlerTimeoutMs }), Effect.andThen(Effect.die(new ActionTransactionDeadline(`${qualified} exceeded its transaction deadline.`)))),
+        }));
+        // Time out the interruptible body only. The SQL manager must finish rollback/commit and
+        // release its connection; a lost COMMIT response must never cause an automatic replay.
+        const transaction = sql.withTransaction(transactionBody);
+        const result = yield* (admission ? admission.admit(transaction) : transaction).pipe(Effect.annotateLogs({ action: qualified, actionId, requestId }), Effect.catchIf(isSqlError, (error) => Effect.die(error)));
         if (replay) {
             return replay;
         }

package/dist/runtime/principals.d.ts

@@ -46,7 +46,8 @@ export declare const SIGN_IN_RECORD_INTERVAL_MS: number;
  * is linked by email when someone invited them; a person nobody invited is rejected as
  * `not_invited` under the `invited` policy and becomes a member holding only `member` under
  * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
- * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. Inactive users are rejected.
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
  */
 export declare function resolvePrincipalByIdentity(ontology: Ontology, claims: IdentityClaims): Effect.Effect<Principal, PrincipalRejected, SqlClient.SqlClient>;
 /** Resolve the workspace's stable keyless pipeline service, without customer roles or sign-in. */

package/dist/runtime/principals.js

@@ -15,7 +15,7 @@ import { beginReplicationWrite } from "../replication/transaction.js";
 import { User } from "../user.js";
 import { MemberNotFound, PrincipalRejected, UnknownRole } from "./errors.js";
 import { isRecordId } from "./records.js";
-import { makeOntologyRuntime } from "./sql-runtime.js";
+import { makeOntologyRuntime, makePrincipalUserWriter, } from "./sql-runtime.js";
 /** API keys are `ssk_<key id>.<secret>`. */
 export const API_KEY_PREFIX = "ssk_";
 /**
@@ -107,93 +107,116 @@ function userRow(record) {
     return decodeUser({ id: record.id, kind: record.kind, active: record.active });
 }
 /**
- * Finds, links or creates the member's user, in one transaction, and records the sign-in on it. A
+ * Finds the member's user without locking. Links or creates it transactionally when needed. A
  * user linked to this identity is found; else a member invited with the same email is linked; else
  * the ontology's sign-in policy decides: `invited` turns the person away, `open` creates a member.
  */
 function signIn(ontology, sql, claims) {
-    const runtime = platformRuntime(ontology, sql, "user.sign_in");
+    const runtime = makeOntologyRuntime(ontology, sql);
+    const writer = makePrincipalUserWriter(ontology, sql, {
+        action: "user.sign_in",
+        actionId: randomUUID(),
+    });
     const claimedEmail = claims.email?.trim().toLowerCase();
     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({
-            entity: "user",
-            options: {
-                where: {
-                    identity_provider: claims.identityProvider,
-                    identity_subject: claims.identitySubject,
-                },
-                limit: 1,
-                forUpdate: true,
+    const findLinked = (forUpdate = false) => runtime.find({
+        entity: "user",
+        options: {
+            where: {
+                identity_provider: claims.identityProvider,
+                identity_subject: claims.identitySubject,
             },
-        });
-        if (linked !== undefined) {
-            // An inactive user is turned away, which is not a sign-in to record.
-            if (linked.active !== true || !signInDue(linked.last_sign_in_at, now)) {
-                return userRow(linked);
+            limit: 1,
+            forUpdate,
+        },
+    });
+    const member = (record) => record.kind === "member"
+        ? Effect.succeed(userRow(record))
+        : Effect.fail(new PrincipalRejected({
+            reason: "identity_conflict",
+            message: "This identity belongs to a service, not a member.",
+        }));
+    return Effect.gen(function* () {
+        const [known] = yield* findLinked();
+        if (known !== undefined) {
+            const user = yield* member(known);
+            // Ordinary authentication is read-only. Optional bookkeeping must never queue behind a
+            // business transaction holding a User key or row lock; a later request can record it.
+            if (!user.active || !writer.recordsSignIn || !signInDue(known.last_sign_in_at, new Date())) {
+                return user;
             }
-            const returning = yield* runtime.update({
-                entity: "user",
-                id: linked.id,
-                values: signedIn,
-            });
-            return userRow(returning);
+            return yield* sql.withTransaction(Effect.gen(function* () {
+                const [locked] = yield* sql.unsafe(`SELECT "id" FROM "${USER_TABLE}" WHERE "id" = $1::uuid FOR UPDATE SKIP LOCKED`, [user.id]);
+                if (locked === undefined) {
+                    return user;
+                }
+                const current = yield* runtime.get({ entity: "user", id: user.id });
+                const principal = yield* member(current);
+                const now = new Date();
+                if (principal.active && signInDue(current.last_sign_in_at, now)) {
+                    yield* writer.update(user.id, { last_sign_in_at: now.toISOString() });
+                }
+                return principal;
+            }));
         }
-        const [invited] = email === undefined
-            ? []
-            : yield* runtime.find({
-                entity: "user",
-                options: { where: { email }, limit: 1, forUpdate: true },
-            });
-        if (invited !== undefined) {
-            if (invited.kind !== "member" || invited.identity_subject !== null) {
-                return yield* new PrincipalRejected({
-                    reason: "identity_conflict",
-                    message: "Another user already has this email.",
-                });
+        return yield* sql.withTransaction(Effect.gen(function* () {
+            const now = new Date();
+            const signedIn = writer.recordsSignIn ? { last_sign_in_at: now.toISOString() } : {};
+            const [linked] = yield* findLinked(true);
+            if (linked !== undefined) {
+                return yield* member(linked);
             }
-            const linkedUser = yield* runtime.update({
-                entity: "user",
-                id: invited.id,
-                values: {
+            const [invited] = email === undefined
+                ? []
+                : yield* runtime.find({
+                    entity: "user",
+                    options: { where: { email }, limit: 1, forUpdate: true },
+                });
+            if (invited !== undefined) {
+                // A concurrent first sign-in may have linked this invitation while this transaction
+                // waited for its row. Accept the exact identity; another identity still conflicts.
+                if (invited.identity_provider === claims.identityProvider &&
+                    invited.identity_subject === claims.identitySubject) {
+                    return yield* member(invited);
+                }
+                if (invited.kind !== "member" || invited.identity_subject !== null) {
+                    return yield* new PrincipalRejected({
+                        reason: "identity_conflict",
+                        message: "Another user already has this email.",
+                    });
+                }
+                const linkedUser = yield* writer.update(invited.id, {
                     identity_provider: claims.identityProvider,
                     identity_subject: claims.identitySubject,
                     ...(invited.active === true ? signedIn : {}),
-                },
-            });
-            return userRow(linkedUser);
-        }
-        if (ontology.signIn.policy !== "open") {
-            return yield* new PrincipalRejected({
-                reason: "not_invited",
-                message: "No member was invited with this identity or email.",
-            });
-        }
-        const created = yield* runtime.create({
-            entity: "user",
-            values: {
+                });
+                return userRow(linkedUser);
+            }
+            if (ontology.signIn.policy !== "open") {
+                return yield* new PrincipalRejected({
+                    reason: "not_invited",
+                    message: "No member was invited with this identity or email.",
+                });
+            }
+            const created = yield* writer.create({
                 name: claims.name?.trim() || email || claims.identitySubject,
                 email: email ?? null,
                 kind: "member",
                 identity_provider: claims.identityProvider,
                 identity_subject: claims.identitySubject,
                 ...signedIn,
-            },
-        });
-        return userRow(created);
-    }))
-        .pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
+            });
+            return userRow(created);
+        }));
+    }).pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
 }
 /**
  * The principal of a member signed in with a verified token. On first sign-in the member's `user`
  * is linked by email when someone invited them; a person nobody invited is rejected as
  * `not_invited` under the `invited` policy and becomes a member holding only `member` under
  * `open`. Every sign-in that lets the member in sets `lastSignInAt`, at most once per
- * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. Inactive users are rejected.
+ * {@link SIGN_IN_RECORD_INTERVAL_MS}, so history keeps it. If the User row is busy, recording is
+ * deferred to a later request instead of delaying authentication. Inactive users are rejected.
  */
 export function resolvePrincipalByIdentity(ontology, claims) {
     return Effect.gen(function* () {

package/dist/runtime/service-binding.js

@@ -14,6 +14,7 @@ import { runAction } from "./pipeline.js";
 import { checkSignIn, resolvePrincipalByApiKey, resolvePrincipalByIdentity, resolvePipelineWorker, } from "./principals.js";
 import { postgresTls } from "./postgres-tls.js";
 import { makeOntologyRuntime } from "./sql-runtime.js";
+import { ActionTransactions, makeActionTransactions } from "./action-transactions.js";
 /** Connections one service instance holds to the database's pooler. */
 const MAX_CONNECTIONS = 5;
 /**
@@ -28,6 +29,7 @@ export function backendLayer(ontology, blobStorage) {
     return Layer.effect(OntologyBackend, Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const runtime = makeOntologyRuntime(ontology, sql);
+        const actionTransactions = makeActionTransactions();
         const withSql = (effect) => Effect.provideService(effect, SqlClient.SqlClient, sql);
         const binding = blobStorage ? Redacted.value(blobStorage) : undefined;
         const provider = binding
@@ -49,7 +51,7 @@ export function backendLayer(ontology, blobStorage) {
                 afterCommit: input.afterCommit === undefined ? [] : [input.afterCommit],
                 ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
                 ...(input.connections === undefined ? {} : { connections: input.connections }),
-            })).pipe(Effect.catchTag("UnknownAction", (error) => Effect.die(error))),
+            })).pipe(Effect.provideService(ActionTransactions, actionTransactions), Effect.catchTag("UnknownAction", (error) => Effect.die(error))),
             get: (input) => runtime.get(input),
             find: (input) => runtime.query(input),
             history: (input) => runtime.history(input),
@@ -87,6 +89,7 @@ export function postgresLayer(databaseUrl) {
         url: databaseUrl,
         ssl: postgresTls(databaseUrl),
         maxConnections: MAX_CONNECTIONS,
+        connectTimeout: "5 seconds",
         applicationName: "segmentstream-ontology",
     });
 }

package/dist/runtime/sql-runtime.d.ts

@@ -1,9 +1,9 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
-import { type NotFound } from "../errors.js";
+import { Conflict, type NotFound } from "../errors.js";
 import type { Ontology } from "../ontology.js";
 import type { Query, QueryResult } from "../query.js";
-import type { OntologyRuntimeService, StoredRecord } from "../runtime.js";
+import type { OntologyRuntimeService, StoredRecord, StoredValues } from "../runtime.js";
 import { InvalidQuery } from "./errors.js";
 import type { Edit, HistoryEntry, HistoryScope } from "./history.js";
 /**
@@ -11,6 +11,8 @@ import type { Edit, HistoryEntry, HistoryScope } from "./history.js";
  * `created_by`/`updated_by` to its principal.
  */
 export interface WriteScope extends HistoryScope {
+    /** Set only when the enclosing action initialized replication in its outer transaction. */
+    readonly replicationInitialized?: boolean;
     /** Receives the edits of each write that succeeded, in order. */
     readonly onEdit?: (edit: Edit) => void;
 }
@@ -39,6 +41,16 @@ export interface SqlOntologyRuntime extends OntologyRuntimeService {
         readonly limit?: number;
     }) => Effect.Effect<QueryResult<HistoryEntry>, InvalidQuery>;
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export declare function makePrincipalUserWriter(ontology: Ontology, sql: SqlClient.SqlClient, scope: Pick<HistoryScope, "action" | "actionId">): {
+    recordsSignIn: boolean;
+    create: (values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+    update: (id: string, values: StoredValues) => Effect.Effect<Readonly<Record<string, unknown>>, Conflict | NotFound, never>;
+};
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares

package/dist/runtime/sql-runtime.js

@@ -1,7 +1,9 @@
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
 import { beginReplicationWrite } from "../replication/transaction.js";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { Conflict } from "../errors.js";
+import { toSnakeCase } from "../names.js";
+import { User } from "../user.js";
 import { InvalidQuery, WriteOutsideAction } from "./errors.js";
 import { entityModel, ontologyModel } from "./model.js";
 import { loadRecord, notFound, readHistory, relatedCondition, runQuery, validateQuery, } from "./reads.js";
@@ -41,6 +43,37 @@ function uniqueConflict(entity, error) {
             message: `A ${label} with this ${field.name} already exists.`,
         }));
 }
+/**
+ * Platform identity bookkeeping touches only User properties and their history. User is excluded
+ * from business replication; keep this internal capability separate from the general runtime so
+ * deleting users, cascading relationships or editing business records still takes its fence.
+ */
+export function makePrincipalUserWriter(ontology, sql, scope) {
+    const model = ontologyModel(ontology);
+    const user = entityModel(model, User.name);
+    const allowed = new Set(Object.keys(User.definition.properties).map(toSnakeCase));
+    const client = sql.withoutTransforms();
+    const context = () => ({
+        model,
+        scope: { action: scope.action, actionId: scope.actionId, principalId: null },
+        edits: [],
+        run: (text, params) => client.unsafe(text, params.values),
+    });
+    const write = (values, operation) => Effect.suspend(() => {
+        if (!user.manifest.builtIn ||
+            Object.keys(values).some((name) => !allowed.has(name) || user.fieldsByName.get(name)?.source !== "property")) {
+            return Effect.die(new Error("Principal writes accept only built-in User properties."));
+        }
+        return sql
+            .withTransaction(operation())
+            .pipe(Effect.catchIf(isSqlError, (error) => uniqueConflict(user, error)));
+    });
+    return {
+        recordsSignIn: user.fieldsByName.has("last_sign_in_at"),
+        create: (values) => write(values, () => createRecord(context(), user, values)),
+        update: (id, values) => write(values, () => updateRecord(context(), user, id, values)),
+    };
+}
 /**
  * The runtime over one SQL client, normally `@effect/sql-pg`'s. Statements are parameterised; the
  * client runs them on the transaction of the calling fiber, so a runtime made for an action shares
@@ -67,8 +100,10 @@ export function makeOntologyRuntime(ontology, sql, scope) {
             }));
         }
         const edits = [];
+        const enclosingTransaction = yield* Effect.serviceOption(sql.transactionService);
+        const initialized = scope.replicationInitialized && Option.isSome(enclosingTransaction);
         const result = yield* sql
-            .withTransaction(beginReplicationWrite(sql).pipe(Effect.andThen(operation({ ...context, scope, edits }, entity))))
+            .withTransaction((initialized ? Effect.void : 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/replication.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
 import type { OntologyEnvironment } from "./config.js";
 export type ReplicationKick = (identity: string | undefined) => Effect.Effect<void>;
-/** A fast path only. The committed history, not this request, makes delivery durable. */
+/** Coalesce best-effort wakes without adding network latency to committed actions. Durable recovery owns retries. */
 export declare function deployedReplication(environment: OntologyEnvironment, fetchImpl?: typeof fetch): ReplicationKick;

package/dist/service/replication.js

@@ -1,25 +1,36 @@
 import { Effect } from "effect";
-/** A fast path only. The committed history, not this request, makes delivery durable. */
+/** Coalesce best-effort wakes without adding network latency to committed actions. Durable recovery owns retries. */
 export function deployedReplication(environment, fetchImpl = fetch) {
+    let inFlight = false;
+    let nextWakeAt = 0;
     return (identity) => {
         if (!identity) {
             return Effect.void;
         }
-        return Effect.tryPromise(async () => {
-            const response = await fetchImpl(`${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
-                `${encodeURIComponent(environment.workspaceId)}/ontology/replication/drain`, {
-                method: "POST",
-                redirect: "error",
-                signal: AbortSignal.timeout(5000),
-                headers: {
-                    "x-segmentstream-runtime-identity": identity,
-                    "x-segmentstream-organization-id": environment.organizationId,
-                },
-            });
-            await response.body?.cancel();
-            if (!response.ok) {
-                throw new Error(`Replication wake-up returned HTTP ${response.status}.`);
+        return Effect.suspend(() => {
+            if (inFlight || Date.now() < nextWakeAt) {
+                return Effect.void;
             }
-        }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause)));
+            inFlight = true;
+            nextWakeAt = Date.now() + 1000;
+            return Effect.tryPromise(async () => {
+                const response = await fetchImpl(`${environment.segmentstreamUrl}/api/internal/v1/workspaces/` +
+                    `${encodeURIComponent(environment.workspaceId)}/ontology/replication/drain`, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: AbortSignal.timeout(5000),
+                    headers: {
+                        "x-segmentstream-runtime-identity": identity,
+                        "x-segmentstream-organization-id": environment.organizationId,
+                    },
+                });
+                await response.body?.cancel();
+                if (!response.ok) {
+                    throw new Error(`Replication wake-up returned HTTP ${response.status}.`);
+                }
+            }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause)), Effect.ensuring(Effect.sync(() => {
+                inFlight = false;
+            })), Effect.forkDetach, Effect.asVoid);
+        });
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -44,6 +44,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint src tests --config ../../eslint.config.mjs",
     "test": "vitest run",
+    "test:postgres": "vitest run --config vitest.postgres.config.ts",
     "prepack": "npm run build"
   },
   "dependencies": {