@segmentstream-cloud/ontology 0.24.1 → 0.25.0

package/dist/replication/schema.js

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { queryFields } from "../query.js";
 import { columnName, historyTableName, quoteIdentifier as qi, quoteLiteral as ql, relationshipColumnName, SYSTEM_COLUMNS, tableName, joinTableName, } from "../migrate/storage.js";
 import { REPLICATION_RECORD_BYTES } from "./model.js";
-export const REPLICATION_SCHEMA_VERSION = 3;
+export const REPLICATION_SCHEMA_VERSION = 4;
 /** Installed only by the SDK migration runner, never at service startup. */
 export const REPLICATION_DDL = [
     `CREATE TABLE IF NOT EXISTS _ontology_replication (
@@ -17,6 +17,49 @@ export const REPLICATION_DDL = [
     generation uuid PRIMARY KEY, source_id uuid NOT NULL, from_revision bigint NOT NULL,
     manifest jsonb NOT NULL, selection jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now()
   )`,
+    `DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint
+      WHERE conrelid = '_ontology_replication'::regclass AND conname = '_ontology_replication_protocol_floor') THEN
+      ALTER TABLE _ontology_replication ADD CONSTRAINT _ontology_replication_protocol_floor
+        CHECK (version >= 4) NOT VALID;
+    END IF;
+  END $$`,
+    `CREATE SEQUENCE IF NOT EXISTS _ontology_replication_revision AS bigint CACHE 1`,
+    `SELECT setval('_ontology_replication_revision', GREATEST(
+    (SELECT revision FROM _ontology_replication WHERE id),
+    (SELECT last_value FROM _ontology_replication_revision), 1), true)
+    WHERE (SELECT version FROM _ontology_replication WHERE id) < 4`,
+    `ALTER TABLE _ontology_replication_targets
+    ADD COLUMN IF NOT EXISTS protocol integer NOT NULL DEFAULT 3,
+    ADD COLUMN IF NOT EXISTS baseline_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS baseline_cursor jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN IF NOT EXISTS initial_revision bigint,
+    ADD COLUMN IF NOT EXISTS backfill_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS backfill_cursor jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN IF NOT EXISTS backfill_revision bigint,
+    ADD COLUMN IF NOT EXISTS verified_count bigint NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS replay_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS replay_cursor uuid`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_delivery (
+    generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
+    event_id uuid NOT NULL, history_table text, revision bigint NOT NULL,
+    is_baseline boolean NOT NULL DEFAULT false,
+    accepted_at timestamptz, verified_at timestamptz,
+    next_verify_at timestamptz NOT NULL DEFAULT now(), last_checked_at timestamptz,
+    PRIMARY KEY (generation, event_id)
+  )`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_pending ON _ontology_replication_delivery
+    (generation, revision, event_id) WHERE accepted_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_verify ON _ontology_replication_delivery
+    (generation, next_verify_at, event_id) WHERE accepted_at IS NOT NULL AND verified_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_unverified ON _ontology_replication_delivery
+    (generation, event_id) WHERE verified_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_initial ON _ontology_replication_delivery
+    (generation, revision, event_id) WHERE verified_at IS NULL`,
+    `UPDATE _ontology_replication_targets SET backfill_complete = false,
+     backfill_revision = (SELECT revision FROM _ontology_replication WHERE id),
+     initial_revision = (SELECT revision FROM _ontology_replication WHERE id)
+     WHERE protocol = 3 AND backfill_revision IS NULL`,
     `CREATE TABLE IF NOT EXISTS _ontology_replication_baselines (
     generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
     id uuid PRIMARY KEY DEFAULT gen_random_uuid(), event jsonb NOT NULL
@@ -29,7 +72,7 @@ export const REPLICATION_DDL = [
     `CREATE OR REPLACE FUNCTION _ontology_replication_guard() RETURNS trigger LANGUAGE plpgsql AS $$
   BEGIN
     IF (SELECT enabled FROM _ontology_replication WHERE id) AND
-       current_setting('segmentstream.writer', true) IS DISTINCT FROM '1' THEN
+       COALESCE(current_setting('segmentstream.writer', true), '') NOT IN ('1', '2') THEN
       RAISE EXCEPTION 'Replication requires a compatible ontology writer; pause replication before a data migration';
     END IF;
     RETURN NULL;
@@ -71,7 +114,8 @@ export function replicationEntityDdl(manifest) {
         (((replication->>'revision')::bigint)) WHERE replication IS NOT NULL`,
             `CREATE OR REPLACE FUNCTION ${fn}() RETURNS trigger LANGUAGE plpgsql AS $$
       DECLARE state _ontology_replication; policy jsonb; snapshot jsonb; relation text; other_id text;
-              record_key text; record_kind text := 'entity'; is_deleted boolean := NEW.kind = 'delete';
+              event_revision bigint; record_key text; record_kind text := 'entity';
+              is_deleted boolean := NEW.kind = 'delete';
       BEGIN
         SELECT * INTO state FROM _ontology_replication WHERE id;
         policy := state.selection->${ql(entity.id)};
@@ -96,11 +140,13 @@ export function replicationEntityDdl(manifest) {
         IF octet_length(snapshot::text) > ${REPLICATION_RECORD_BYTES} THEN
           RAISE EXCEPTION 'Projected ontology record exceeds the replication size limit';
         END IF;
-        UPDATE _ontology_replication SET revision = revision + 1 WHERE id RETURNING * INTO state;
+        event_revision := nextval('_ontology_replication_revision');
         NEW.replication := jsonb_build_object('source_id', state.source_id::text,
           'entity_id', ${ql(entity.id)}, 'record_key', record_key, 'record_kind', record_kind,
-          'revision', state.revision::text, 'deleted', is_deleted,
+          'revision', event_revision::text, 'generation', state.active_generation::text, 'deleted', is_deleted,
           'schema_hash', ${ql(manifest.hash)}, 'payload', snapshot::text);
+        INSERT INTO _ontology_replication_delivery (generation, event_id, history_table, revision)
+          VALUES (state.active_generation, NEW.id, TG_TABLE_NAME, event_revision);
         RETURN NEW;
       END $$`,
             `DROP TRIGGER IF EXISTS _ontology_capture ON ${history}`,

package/dist/replication/store.d.ts

@@ -1,35 +1,38 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
 import { type ReplicationEvent, type ReplicationSelection, type ReplicationExclusion } from "./model.js";
-import { ReplicationBaselineFailed, type ReplicationTarget } from "./baseline.js";
+import { advanceReplicationBaseline, ReplicationBaselineFailed, 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 | ReplicationBaselineFailed | import("effect/unstable/sql/SqlError").SqlError, never>;
+}) => Effect.Effect<ReplicationTarget, import("../index.js").CatalogInvalid | import("effect/unstable/sql/SqlError").SqlError | ReplicationBaselineFailed, 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 pauseReplication: (sql: SqlClient.SqlClient) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
 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 { advanceReplicationBaseline };
+/** Retained history is recovery storage; frequent delivery reads only indexed outstanding references. */
 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>;
+/** Initialization is a fixed fence, so continuing writes cannot move the readiness goal. */
+export declare const replicationInitiallyReady: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<boolean, 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>;
+export declare const advanceReplicationReplay: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Static pre-upgrade histories have no new inserts: v4 writers atomically enqueue new history. */
+export declare const advanceReplicationBackfill: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<boolean, import("../index.js").CatalogInvalid | import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const acknowledgeReplication: (sql: SqlClient.SqlClient, generation: string, ids: ReadonlyArray<string>, version?: number) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const verifyReplicationEvents: (sql: SqlClient.SqlClient, generation: string, ids: ReadonlyArray<string>, version?: number) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const retryUnverifiedReplication: (sql: SqlClient.SqlClient, generation: string, ids?: ReadonlyArray<string>, version?: number) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const replayReplication: (sql: SqlClient.SqlClient, generation: string) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/replication/store.js

@@ -1,12 +1,12 @@
 import { Effect } from "effect";
+import * as legacy from "./legacy-store.js";
+import { createReplicationBaseline as createLegacyBaseline } from "./legacy-baseline.js";
+import { lockReplicationLifecycle, shareReplicationLifecycle } from "./transaction.js";
 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, ReplicationBaselineFailed, } 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");
+import { createReplicationBaseline, advanceReplicationBaseline, ReplicationBaselineFailed, } from "./baseline.js";
+export const startReplication = (sql, input) => Effect.gen(function* () {
     const manifest = yield* readCatalog({ sql });
     if (!manifest) {
         return yield* new ReplicationBaselineFailed({
@@ -18,76 +18,265 @@ export const startReplication = (sql, input) => sql.withTransaction(Effect.gen(f
             try: () => resolveReplicationSelection(manifest, input.exclusions),
             catch: (cause) => new ReplicationBaselineFailed({ message: "Invalid replication exclusions.", cause }),
         }));
-    return yield* createReplicationBaseline(sql, { ...input, manifest, selection });
+    const version = yield* protocol(sql);
+    return yield* version >= 4
+        ? createReplicationBaseline(sql, { ...input, manifest, selection })
+        : createLegacyBaseline(sql, { ...input, manifest, selection }).pipe(Effect.map((target) => target));
+});
+const targetFields = `generation::text, source_id::text, from_revision::text, manifest, selection,
+  protocol, baseline_complete, backfill_complete, initial_revision::text, replay_complete, 4 AS delivery_version`;
+const protocol = (sql) => sql
+    .unsafe("SELECT version FROM _ontology_replication WHERE id")
+    .pipe(Effect.map((rows) => rows[0]?.version ?? 3));
+export const activeReplicationTarget = (sql) => Effect.gen(function* () {
+    const version = yield* protocol(sql);
+    const fields = version >= 4
+        ? targetFields
+        : "generation::text, source_id::text, from_revision::text, manifest, selection";
+    const rows = yield* sql.unsafe(`SELECT ${fields} FROM _ontology_replication_targets
+     WHERE generation = (SELECT active_generation FROM _ontology_replication WHERE id)`);
+    return rows[0];
+});
+export const pauseReplication = (sql) => sql.withTransaction(Effect.gen(function* () {
+    yield* lockReplicationLifecycle(sql);
+    yield* sql.unsafe("UPDATE _ontology_replication SET enabled = false WHERE id");
 }));
-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) => {
+export const replicationTarget = (sql, generation) => Effect.gen(function* () {
+    const version = yield* protocol(sql);
+    const fields = version >= 4
+        ? targetFields
+        : "generation::text, source_id::text, from_revision::text, manifest, selection";
+    const rows = yield* sql.unsafe(`SELECT ${fields} FROM _ontology_replication_targets WHERE generation = $1::uuid`, [generation]);
+    return rows[0];
+});
+export { advanceReplicationBaseline };
+/** Retained history is recovery storage; frequent delivery reads only indexed outstanding references. */
+export const pendingReplicationEvents = (sql, target) => Effect.gen(function* () {
+    if (target.delivery_version !== 4 &&
+        target.protocol !== 4) {
+        return yield* legacy.pendingReplicationEvents(sql, target);
+    }
+    const references = yield* sql.unsafe(`SELECT event_id::text AS id, history_table FROM _ontology_replication_delivery
+       WHERE generation = $1::uuid AND accepted_at IS NULL
+       ORDER BY revision, event_id LIMIT ${REPLICATION_BATCH_SIZE}`, [target.generation]);
+    const groups = new Map();
+    for (const reference of references) {
+        const ids = groups.get(reference.history_table) ?? [];
+        ids.push(reference.id);
+        groups.set(reference.history_table, ids);
+    }
+    const events = new Map();
+    for (const [table, ids] of groups) {
+        const rows = yield* sql.unsafe(table === null
+            ? `SELECT id::text, event FROM _ontology_replication_baselines
+             WHERE generation = $1::uuid AND id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`
+            : `SELECT id::text, replication AS event FROM ${qi(table)}
+             WHERE $1::uuid IS NOT NULL AND id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`, [target.generation, JSON.stringify(ids)]);
+        for (const row of rows) {
+            events.set(row.id, row.event);
+        }
+    }
     let size = 32;
     const result = [];
-    for (const row of rows) {
+    for (const reference of references) {
+        const payload = events.get(reference.id);
+        if (!payload) {
+            return yield* Effect.die(new Error("A queued replication event is missing from retained history."));
+        }
         const event = {
-            ...row.event,
+            ...payload,
             generation: target.generation,
-            event_id: replicationEventId(target.source_id, row.id, target.generation),
+            event_id: replicationEventId(target.source_id, reference.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.");
+            return yield* Effect.die(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 });
+        result.push({ historyId: reference.id, event });
     }
     return result;
+});
+/** Lost publish responses deliberately leave the same immutable IDs pending. */
+const acknowledgeReplicationV4 = (sql, generation, ids) => sql.withTransaction(Effect.gen(function* () {
+    // Receipt foreign keys touch targets after delivery rows; drain before migration table locks.
+    yield* shareReplicationLifecycle(sql);
+    yield* sql.unsafe(`WITH accepted AS (
+          UPDATE _ontology_replication_delivery SET accepted_at = now(), next_verify_at = now()
+          WHERE generation = $1::uuid AND accepted_at IS NULL
+            AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))
+          RETURNING event_id, accepted_at
+        ) INSERT INTO _ontology_replication_receipts (generation, event_id, accepted_at)
+          SELECT $1::uuid, event_id, accepted_at FROM accepted ON CONFLICT DO NOTHING`, [generation, JSON.stringify(ids)]);
+}));
+export const replicationStatus = (sql, target) => target.delivery_version !== 4 &&
+    target.protocol !== 4
+    ? legacy.replicationStatus(sql, target)
+    : sql
+        .unsafe(`SELECT (t.verified_count + outstanding.total)::text AS total,
+      (t.verified_count + outstanding.accepted)::text AS accepted, t.verified_count::text AS verified
+     FROM _ontology_replication_targets t CROSS JOIN LATERAL (
+       SELECT count(*) AS total, count(accepted_at) AS accepted FROM _ontology_replication_delivery
+       WHERE generation = t.generation AND verified_at IS NULL
+     ) outstanding WHERE t.generation = $1::uuid`, [target.generation])
+        .pipe(Effect.map((rows) => rows[0]));
+/** Initialization is a fixed fence, so continuing writes cannot move the readiness goal. */
+export const replicationInitiallyReady = (sql, generation) => sql
+    .unsafe(`SELECT baseline_complete AND backfill_complete AND replay_complete AND NOT EXISTS (
+      SELECT 1 FROM _ontology_replication_delivery d WHERE d.generation = t.generation
+        AND d.verified_at IS NULL AND (d.is_baseline OR d.revision <= t.initial_revision)
+    ) AS ready FROM _ontology_replication_targets t WHERE generation = $1::uuid`, [generation])
+    .pipe(Effect.map((rows) => rows[0]?.ready ?? false));
+export const unverifiedReplicationEvents = (sql, target) => target.delivery_version !== 4 &&
+    target.protocol !== 4
+    ? legacy.unverifiedReplicationEvents(sql, target)
+    : sql
+        .unsafe(`SELECT event_id::text AS id FROM _ontology_replication_delivery
+     WHERE generation = $1::uuid AND accepted_at IS NOT NULL AND verified_at IS NULL
+       AND next_verify_at <= now() ORDER BY next_verify_at, event_id LIMIT 1000`, [target.generation])
+        .pipe(Effect.map((rows) => rows.map(({ id }) => ({
+        historyId: id,
+        eventId: replicationEventId(target.source_id, id, target.generation),
+    }))));
+const verifyReplicationEventsV4 = (sql, generation, ids) => sql.unsafe(`WITH locked AS MATERIALIZED (
+      SELECT generation FROM _ontology_replication_targets WHERE generation = $1::uuid FOR NO KEY UPDATE
+    ), verified AS (
+      UPDATE _ontology_replication_delivery SET verified_at = now(), last_checked_at = now()
+      WHERE generation = (SELECT generation FROM locked) AND accepted_at IS NOT NULL AND verified_at IS NULL
+        AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))
+      RETURNING event_id, verified_at
+    ), receipts AS (
+      UPDATE _ontology_replication_receipts r SET verified_at = v.verified_at FROM verified v
+      WHERE r.generation = $1::uuid AND r.event_id = v.event_id
+    ) UPDATE _ontology_replication_targets SET verified_count = verified_count + (SELECT count(*) FROM verified)
+      WHERE generation = $1::uuid`, [generation, JSON.stringify(ids)]);
+/** Retry only IDs actually checked and absent; a verification backlog is never a delivery failure. */
+const retryUnverifiedReplicationV4 = (sql, generation, missingIds = []) => sql.unsafe(`WITH checked AS (
+      UPDATE _ontology_replication_delivery SET last_checked_at = now(), next_verify_at = now() + interval '30 seconds',
+        accepted_at = CASE WHEN accepted_at < now() - interval '15 minutes' THEN NULL ELSE accepted_at END
+      WHERE generation = $1::uuid AND accepted_at IS NOT NULL AND verified_at IS NULL
+        AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))
+      RETURNING event_id, accepted_at
+    ) DELETE FROM _ontology_replication_receipts r USING checked c
+      WHERE r.generation = $1::uuid AND r.event_id = c.event_id AND c.accepted_at IS NULL`, [generation, JSON.stringify(missingIds)]);
+/** Replay initialization is constant time; reset work is resumed in bounded pages. */
+const replayReplicationV4 = (sql, generation) => sql.withTransaction(Effect.gen(function* () {
+    yield* lockReplicationLifecycle(sql);
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets SET replay_complete = false, replay_cursor = NULL,
+        initial_revision = (SELECT CASE WHEN is_called THEN last_value ELSE 0 END FROM _ontology_replication_revision)
+       WHERE generation = $1::uuid`, [generation]);
+}));
+export const advanceReplicationReplay = (sql, generation) => sql.withTransaction(Effect.gen(function* () {
+    const [target] = yield* sql.unsafe(`SELECT replay_complete, replay_cursor::text, initial_revision::text FROM _ontology_replication_targets
+       WHERE generation = $1::uuid FOR NO KEY UPDATE`, [generation]);
+    if (!target || target.replay_complete) {
+        return true;
+    }
+    const rows = yield* sql.unsafe(`SELECT event_id::text AS id, verified_at IS NOT NULL AS verified FROM _ontology_replication_delivery
+       WHERE generation = $1::uuid AND ($2::uuid IS NULL OR event_id > $2::uuid)
+         AND (is_baseline OR revision <= $3::bigint)
+       ORDER BY event_id LIMIT 1000`, [generation, target.replay_cursor, target.initial_revision]);
+    const ids = JSON.stringify(rows.map((row) => row.id));
+    yield* sql.unsafe(`UPDATE _ontology_replication_delivery SET accepted_at = NULL, verified_at = NULL, next_verify_at = now()
+       WHERE generation = $1::uuid AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`, [generation, ids]);
+    yield* sql.unsafe(`DELETE FROM _ontology_replication_receipts WHERE generation = $1::uuid
+       AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`, [generation, ids]);
+    const complete = rows.length < 1000;
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets SET replay_cursor = $2::uuid, replay_complete = $3,
+        verified_count = verified_count - $4::bigint WHERE generation = $1::uuid`, [
+        generation,
+        rows.at(-1)?.id ?? target.replay_cursor,
+        complete,
+        rows.filter((row) => row.verified).length,
+    ]);
+    return complete;
+}));
+/** Static pre-upgrade histories have no new inserts: v4 writers atomically enqueue new history. */
+export const advanceReplicationBackfill = (sql, generation) => sql.withTransaction(Effect.gen(function* () {
+    yield* shareReplicationLifecycle(sql);
+    const [target] = yield* sql.unsafe(`SELECT ${targetFields}, backfill_cursor, backfill_revision::text
+       FROM _ontology_replication_targets WHERE generation = $1::uuid FOR NO KEY UPDATE`, [generation]);
+    if (!target || target.backfill_complete) {
+        return true;
+    }
+    const catalog = yield* readCatalog({ sql });
+    const tables = [
+        null,
+        ...target.selection.map((item) => {
+            const entity = (catalog ?? target.manifest).entities.find((entity) => entity.id === item.entityId) ??
+                target.manifest.entities.find((entity) => entity.id === item.entityId);
+            return historyTableName(entity.name);
+        }),
+    ];
+    const position = target.backfill_cursor.table ?? 0;
+    const table = tables[position];
+    const cursor = target.backfill_cursor.id ?? null;
+    const rows = yield* sql.unsafe(table === null
+        ? `SELECT id::text FROM _ontology_replication_baselines WHERE generation = $1::uuid
+           AND ($2::uuid IS NULL OR id > $2::uuid) ORDER BY id LIMIT 1000`
+        : `SELECT id::text FROM ${qi(table)} WHERE replication IS NOT NULL
+           AND replication->>'source_id' = $3 AND (replication->>'revision')::bigint > $4::bigint
+           AND (replication->>'revision')::bigint <= $5::bigint
+           AND ($2::uuid IS NULL OR id > $2::uuid) AND $1::uuid IS NOT NULL ORDER BY id LIMIT 1000`, table === null
+        ? [generation, cursor]
+        : [generation, cursor, target.source_id, target.from_revision, target.backfill_revision]);
+    const ids = JSON.stringify(rows.map((row) => row.id));
+    const eventSelect = table === null
+        ? `SELECT id, event FROM _ontology_replication_baselines WHERE generation = $1::uuid`
+        : `SELECT id, replication AS event FROM ${qi(table)}`;
+    yield* sql.unsafe(`WITH inserted AS (
+        INSERT INTO _ontology_replication_delivery
+          (generation, event_id, history_table, revision, is_baseline, accepted_at, verified_at, next_verify_at)
+        SELECT $1::uuid, e.id, $3::text, (e.event->>'revision')::bigint, $4::boolean,
+          r.accepted_at, r.verified_at, now() FROM (${eventSelect}) e
+        LEFT JOIN _ontology_replication_receipts r ON r.generation = $1::uuid AND r.event_id = e.id
+        WHERE e.id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))
+        ON CONFLICT DO NOTHING RETURNING verified_at
+      ) UPDATE _ontology_replication_targets SET verified_count = verified_count +
+        (SELECT count(verified_at) FROM inserted) WHERE generation = $1::uuid`, [generation, ids, table, table === null]);
+    const finishedTable = rows.length < 1000;
+    const complete = finishedTable && position + 1 >= tables.length;
+    const next = finishedTable
+        ? { table: position + 1 }
+        : { table: position, id: rows.at(-1).id };
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets SET backfill_cursor = $2::jsonb, backfill_complete = $3
+       WHERE generation = $1::uuid`, [generation, JSON.stringify(next), complete]);
+    return complete;
 }));
-/** 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]);
+export const acknowledgeReplication = (sql, generation, ids, version) => Effect.gen(function* () {
+    const current = version ?? (yield* protocol(sql));
+    yield* current >= 4
+        ? acknowledgeReplicationV4(sql, generation, ids)
+        : legacy.acknowledgeReplication(sql, generation, ids);
+});
+export const verifyReplicationEvents = (sql, generation, ids, version) => Effect.gen(function* () {
+    const current = version ?? (yield* protocol(sql));
+    yield* current >= 4
+        ? verifyReplicationEventsV4(sql, generation, ids)
+        : legacy.verifyReplicationEvents(sql, generation, ids);
+});
+export const retryUnverifiedReplication = (sql, generation, ids = [], version) => Effect.gen(function* () {
+    const current = version ?? (yield* protocol(sql));
+    if (current >= 4) {
+        yield* retryUnverifiedReplicationV4(sql, generation, ids);
+    }
+    else {
+        // Even legacy recovery retries only checked missing IDs, never the unchecked backlog.
+        yield* sql.unsafe(`DELETE FROM _ontology_replication_receipts WHERE generation = $1::uuid
+         AND verified_at IS NULL AND accepted_at < now() - interval '15 minutes'
+         AND event_id IN (SELECT value::uuid FROM jsonb_array_elements_text($2::jsonb))`, [generation, JSON.stringify(ids)]);
+    }
+});
+export const replayReplication = (sql, generation) => Effect.gen(function* () {
+    const current = yield* protocol(sql);
+    if (current >= 4) {
+        yield* replayReplicationV4(sql, generation);
+        yield* advanceReplicationReplay(sql, generation);
+    }
+    else {
+        yield* legacy.replayReplication(sql, generation);
+    }
+});

package/dist/replication/transaction.d.ts

@@ -1,4 +1,8 @@
 import { Effect } from "effect";
 import type { SqlClient } from "effect/unstable/sql";
+export declare const REPLICATION_LIFECYCLE_LOCK = "segmentstream.ontology.replication.lifecycle";
+/** Legacy writers take the singleton first; every lifecycle operation keeps that order. */
+export declare const lockReplicationLifecycle: (sql: SqlClient.SqlClient) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const shareReplicationLifecycle: (sql: SqlClient.SqlClient) => import("effect/unstable/sql/Statement").Statement<object>;
 /** 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

@@ -1,11 +1,30 @@
 import { Effect } from "effect";
+export const REPLICATION_LIFECYCLE_LOCK = "segmentstream.ontology.replication.lifecycle";
+/** Legacy writers take the singleton first; every lifecycle operation keeps that order. */
+export const lockReplicationLifecycle = (sql) => Effect.gen(function* () {
+    yield* sql.unsafe("SELECT id FROM _ontology_replication WHERE id FOR UPDATE");
+    yield* sql.unsafe("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [
+        REPLICATION_LIFECYCLE_LOCK,
+    ]);
+});
+export const shareReplicationLifecycle = (sql) => sql.unsafe("SELECT pg_advisory_xact_lock_shared(hashtextextended($1, 0))", [
+    REPLICATION_LIFECYCLE_LOCK,
+]);
 /** 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");
+    }
+    // Shared admission permits independent writes while lifecycle changes drain admitted writers.
+    const [state] = yield* sql.unsafe("SELECT version FROM _ontology_replication WHERE id");
+    if ((state?.version ?? 0) < 4) {
+        // A new service may be deployed before its owner applies the protocol upgrade.
+        yield* sql.unsafe("SELECT id FROM _ontology_replication WHERE id FOR UPDATE");
+        yield* sql.unsafe("SELECT set_config('segmentstream.writer', '1', true)");
+    }
+    else {
+        yield* shareReplicationLifecycle(sql);
+        yield* sql.unsafe("SELECT set_config('segmentstream.writer', '2', true)");
+    }
 });

package/dist/runtime/action-transactions.d.ts

@@ -0,0 +1,35 @@
+import { Context, Effect } from "effect";
+/** Admission happens before reserving SQL connections; two pool slots remain for other work. */
+export declare const ACTION_TRANSACTION_LIMITS: {
+    readonly concurrency: 3;
+    readonly maxWaiting: 32;
+    readonly queueTimeoutMs: 5000;
+    readonly handlerTimeoutMs: 60000;
+    readonly statementTimeoutMs: 30000;
+    readonly lockTimeoutMs: 5000;
+};
+export interface ActionTransactionLimits {
+    readonly handlerTimeoutMs: number;
+    readonly statementTimeoutMs: number;
+    readonly lockTimeoutMs: number;
+}
+export declare class ActionTransactionDeadline extends Error {
+    readonly name = "ActionTransactionDeadline";
+}
+export declare class ActionAdmissionRejected extends Error {
+    readonly name = "ActionAdmissionRejected";
+}
+export interface ActionTransactionsService {
+    readonly limits: ActionTransactionLimits;
+    readonly admit: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+}
+declare const ActionTransactions_base: Context.ServiceClass<ActionTransactions, "segmentstream/ontology/ActionTransactions", ActionTransactionsService>;
+/** Internal configuration and one admission gate per service instance, never per request. */
+export declare class ActionTransactions extends ActionTransactions_base {
+}
+export declare function makeActionTransactions(options?: ActionTransactionLimits & {
+    readonly concurrency: number;
+    readonly maxWaiting: number;
+    readonly queueTimeoutMs: number;
+}): ActionTransactionsService;
+export {};

package/dist/runtime/action-transactions.js

@@ -0,0 +1,54 @@
+import { Context, Duration, Effect, Exit, Semaphore } from "effect";
+/** Admission happens before reserving SQL connections; two pool slots remain for other work. */
+export const ACTION_TRANSACTION_LIMITS = {
+    concurrency: 3,
+    maxWaiting: 32,
+    queueTimeoutMs: 5_000,
+    handlerTimeoutMs: 60_000,
+    statementTimeoutMs: 30_000,
+    lockTimeoutMs: 5_000,
+};
+export class ActionTransactionDeadline extends Error {
+    name = "ActionTransactionDeadline";
+}
+export class ActionAdmissionRejected extends Error {
+    name = "ActionAdmissionRejected";
+}
+/** Internal configuration and one admission gate per service instance, never per request. */
+export class ActionTransactions extends Context.Service()("segmentstream/ontology/ActionTransactions") {
+}
+export function makeActionTransactions(options = ACTION_TRANSACTION_LIMITS) {
+    const permits = Semaphore.makeUnsafe(options.concurrency);
+    let waiting = 0;
+    let active = 0;
+    return {
+        limits: options,
+        admit: (effect) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+            const queuedAt = Date.now();
+            if (!(yield* permits.takeIfAvailable(1))) {
+                if (waiting >= options.maxWaiting) {
+                    yield* Effect.logWarning("ontology.action.admission_rejected").pipe(Effect.annotateLogs({ active, waiting, reason: "queue_full" }));
+                    return yield* Effect.die(new ActionAdmissionRejected("Action write queue is full."));
+                }
+                waiting += 1;
+                yield* restore(permits.take(1).pipe(Effect.timeoutOrElse({
+                    duration: Duration.millis(options.queueTimeoutMs),
+                    orElse: () => Effect.logWarning("ontology.action.admission_rejected").pipe(Effect.annotateLogs({ active, waiting, reason: "queue_timeout" }), Effect.andThen(Effect.die(new ActionAdmissionRejected("Action write admission timed out.")))),
+                }))).pipe(Effect.ensuring(Effect.sync(() => {
+                    waiting -= 1;
+                })));
+            }
+            active += 1;
+            const startedAt = Date.now();
+            return yield* restore(effect).pipe(Effect.onExit((exit) => Effect.logDebug("ontology.action.transaction_completed").pipe(Effect.annotateLogs({
+                active,
+                waiting,
+                queueMs: startedAt - queuedAt,
+                transactionMs: Date.now() - startedAt,
+                outcome: Exit.isSuccess(exit) ? "success" : "failure",
+            }))), Effect.ensuring(Effect.sync(() => {
+                active -= 1;
+            }).pipe(Effect.andThen(permits.release(1)))));
+        })),
+    };
+}