@segmentstream-cloud/ontology 0.11.0 → 0.12.0

package/README.md

@@ -28,6 +28,12 @@ one Effect version.
 `ontology/` is a package of its own. The SDK is an ES module, so `ontology/package.json`
 must set `"type": "module"`.
 
+SDK 0.12.0 adds warehouse replication enabled by default for all stored business entities,
+fields and business relationships. Existing history captures immutable snapshots and the
+service wakes the publisher after commits. Upgrade and redeploy to activate it; workspace
+configuration can disable replication or exclude individual entities, fields and relationships. See
+[setup and recovery](../../docs/ontology-replication.md).
+
 ## Define the ontology
 
 ```ts

package/dist/migrate/apply.d.ts

@@ -46,7 +46,7 @@ export declare const readCatalog: (input: CatalogInput) => Effect.Effect<Ontolog
  * then runs in one transaction with `statement_timeout` and `lock_timeout` set, which also verifies
  * that the catalog still records the manifest the plan starts from and finally records the target. A
  * failure rolls the transaction back and leaves the applied version in place. A no-op plan writes
- * nothing.
+ * nothing when the runtime schema is also current.
  */
 export declare const applyMigration: (plan: MigrationPlan, options: ApplyMigrationOptions) => Effect.Effect<MigrationResult, ApplyMigrationError>;
 /**

package/dist/migrate/apply.js

@@ -1,8 +1,12 @@
+import { randomUUID } from "node:crypto";
 import { Duration, Effect, Schema } from "effect";
 import { canonicalJson, decodeManifestDocument, encodeManifest, manifestHash, } from "../manifest.js";
 import { CatalogInvalid, CatalogMismatch, MigrationFailed, MigrationRefused } from "./errors.js";
 import { isNoopMigration } from "./model.js";
 import { planMigration } from "./plan.js";
+import { REPLICATION_DDL, REPLICATION_SCHEMA_VERSION, replicationEntityDdl, } from "../replication/schema.js";
+import { createReplicationBaseline } from "../replication/baseline.js";
+import { resolveReplicationSelection } from "../replication/model.js";
 import { API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
 const CATALOG = quoteIdentifier(CATALOG_TABLE);
 /** Serializes migrations of one database; transaction-scoped, so it ends with the transaction. */
@@ -79,7 +83,7 @@ const runStep = (sql, step, stepIndex) => Effect.forEach(step.sql, (statement) =
  * then runs in one transaction with `statement_timeout` and `lock_timeout` set, which also verifies
  * that the catalog still records the manifest the plan starts from and finally records the target. A
  * failure rolls the transaction back and leaves the applied version in place. A no-op plan writes
- * nothing.
+ * nothing when the runtime schema is also current.
  */
 export const applyMigration = (plan, options) => Effect.gen(function* () {
     const { sql } = options;
@@ -89,8 +93,12 @@ export const applyMigration = (plan, options) => Effect.gen(function* () {
             refusals: plan.refusals,
         });
     }
-    if (isNoopMigration(plan)) {
-        return { hash: plan.target.hash, appliedSteps: 0, changed: false };
+    const [presence] = yield* sql.unsafe("SELECT to_regclass('_ontology_replication') IS NOT NULL AS present");
+    if (presence?.present) {
+        const [state] = yield* sql.unsafe("SELECT version, enabled FROM _ontology_replication WHERE id");
+        if (isNoopMigration(plan) && state?.version === REPLICATION_SCHEMA_VERSION) {
+            return { hash: plan.target.hash, appliedSteps: 0, changed: false };
+        }
     }
     const statementTimeout = Duration.toMillis(options.statementTimeout ?? DEFAULT_STATEMENT_TIMEOUT);
     const lockTimeout = Duration.toMillis(options.lockTimeout ?? DEFAULT_LOCK_TIMEOUT);
@@ -109,11 +117,26 @@ export const applyMigration = (plan, options) => Effect.gen(function* () {
             MIGRATION_LOCK,
         ]);
         yield* verifyCatalog(sql, plan, { forUpdate: true });
+        let refresh;
+        if (presence?.present) {
+            const [state] = yield* sql.unsafe("SELECT * FROM _ontology_replication WHERE id FOR UPDATE");
+            if (state?.enabled) {
+                refresh = state.exclusions ?? [];
+                // Writers wait on this row. Capture, schema changes and the new baseline commit together.
+                yield* sql.unsafe("UPDATE _ontology_replication SET enabled = false WHERE id");
+            }
+        }
         for (const [stepIndex, step] of plan.steps.entries()) {
             if (step.transactional) {
                 yield* runStep(sql, step, stepIndex);
             }
         }
+        for (const statement of [...REPLICATION_DDL, ...replicationEntityDdl(plan.target)]) {
+            yield* sql.unsafe(statement).unprepared;
+        }
+        yield* sql.unsafe("UPDATE _ontology_replication SET version = $1 WHERE id", [
+            REPLICATION_SCHEMA_VERSION,
+        ]);
         yield* sql.unsafe(`
             INSERT INTO ${CATALOG} ("id", "version", "hash", "manifest")
             VALUES (true, $1, $2, $3::jsonb)
@@ -123,6 +146,16 @@ export const applyMigration = (plan, options) => Effect.gen(function* () {
               "manifest" = excluded."manifest",
               "applied_at" = now()
           `, [plan.target.version, plan.target.hash, canonicalJson(encodeManifest(plan.target))]);
+        if (refresh !== undefined) {
+            const selection = yield* Effect.sync(() => resolveReplicationSelection(plan.target, refresh));
+            yield* createReplicationBaseline(sql, {
+                generation: randomUUID(),
+                manifest: plan.target,
+                exclusions: refresh,
+                selection,
+                newSource: true,
+            });
+        }
     }));
     return { hash: plan.target.hash, appliedSteps: plan.steps.length, changed: true };
 }).pipe(Effect.withSpan("ontology.migrate.apply", {

package/dist/replication/baseline.d.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { OntologyManifest } from "../manifest.js";
+import { type ReplicationSelection, type ReplicationExclusion } from "./model.js";
+export interface ReplicationTarget {
+    readonly generation: string;
+    readonly source_id: string;
+    readonly from_revision: string;
+    readonly manifest: OntologyManifest;
+    readonly selection: ReadonlyArray<ReplicationSelection>;
+}
+/** All baseline rows are committed with capture enablement; interrupted setup can safely resume. */
+export declare const createReplicationBaseline: (sql: SqlClient.SqlClient, input: {
+    readonly generation: string;
+    readonly manifest: OntologyManifest;
+    readonly exclusions?: ReadonlyArray<ReplicationExclusion>;
+    readonly selection: ReadonlyArray<ReplicationSelection>;
+    readonly newSource?: boolean;
+}) => Effect.Effect<ReplicationTarget, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/replication/baseline.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { Effect } from "effect";
+import { joinColumnNames, joinTableName, quoteIdentifier as qi, quoteLiteral as ql, tableName, } from "../migrate/storage.js";
+import { REPLICATION_RECORD_BYTES, validateReplicationSelection, } from "./model.js";
+import { snapshotExpression } from "./schema.js";
+const MAX_BASELINE_RECORDS = 50_000;
+/** All baseline rows are committed with capture enablement; interrupted setup can safely resume. */
+export const createReplicationBaseline = (sql, input) => sql.withTransaction(Effect.gen(function* () {
+    yield* sql.unsafe("SET LOCAL statement_timeout = '30s'");
+    yield* sql.unsafe("SET LOCAL lock_timeout = '5s'");
+    const [state] = yield* sql.unsafe("SELECT source_id::text, revision::text, enabled FROM _ontology_replication WHERE id FOR UPDATE");
+    if (!state) {
+        return yield* Effect.die(new Error("Run the ontology SDK migration before enabling replication."));
+    }
+    const existing = yield* sql.unsafe("SELECT * FROM _ontology_replication_targets WHERE generation = $1::uuid", [input.generation]);
+    if (existing[0]) {
+        return existing[0];
+    }
+    if (state.enabled) {
+        return yield* Effect.die(new Error("Pause replication before starting a new generation."));
+    }
+    const manifest = input.manifest;
+    yield* Effect.sync(() => validateReplicationSelection(manifest, input.selection));
+    // Drain older SDK transactions that started before the compatibility fence was enabled.
+    const tables = manifest.entities
+        .filter((e) => e.source === undefined && e.name !== "user")
+        .flatMap((e) => [
+        tableName(e.name),
+        ...e.relationships
+            .filter((r) => r.cardinality === "many")
+            .map((r) => joinTableName(e.name, r.name)),
+    ]);
+    if (tables.length > 0) {
+        yield* sql.unsafe(`LOCK TABLE ${tables.map(qi).join(", ")} IN SHARE MODE`);
+    }
+    const source = input.newSource ? randomUUID() : state.source_id;
+    const selection = Object.fromEntries(input.selection.map((s) => [s.entityId, s]));
+    yield* sql.unsafe(`UPDATE _ontology_replication SET source_id = $1::uuid, selection = $2::jsonb, enabled = true,
+          exclusions = $3::jsonb, active_generation = $4::uuid WHERE id`, [
+        source,
+        JSON.stringify(selection),
+        JSON.stringify(input.exclusions ?? []),
+        input.generation,
+    ]);
+    const target = {
+        generation: input.generation,
+        source_id: source,
+        from_revision: state.revision,
+        manifest,
+        selection: input.selection,
+    };
+    yield* sql.unsafe(`INSERT INTO _ontology_replication_targets (generation, source_id, from_revision, manifest, selection)
+     VALUES ($1::uuid, $2::uuid, $3::bigint, $4::jsonb, $5::jsonb)`, [
+        target.generation,
+        source,
+        state.revision,
+        JSON.stringify(manifest),
+        JSON.stringify(input.selection),
+    ]);
+    let total = 0;
+    const baseline = (entityId, kind, records) => Effect.gen(function* () {
+        // Keep the snapshot in PostgreSQL; large baselines must not fill a serverless process's heap.
+        const [size] = yield* sql.unsafe(`SELECT count(*)::int AS count, max(octet_length(payload::text)) AS largest
+          FROM (${records} LIMIT ${MAX_BASELINE_RECORDS + 1}) snapshot`);
+        total += size.count;
+        if (total > MAX_BASELINE_RECORDS) {
+            return yield* Effect.die(new Error("The replication baseline exceeds 50,000 records; use a bulk bootstrap."));
+        }
+        if ((size.largest ?? 0) > REPLICATION_RECORD_BYTES) {
+            return yield* Effect.die(new Error("A projected baseline record exceeds the replication size limit."));
+        }
+        yield* sql.unsafe(`INSERT INTO _ontology_replication_baselines (generation, event)
+      SELECT $1::uuid, jsonb_build_object('source_id', $2::text, 'entity_id', $3::text,
+        'record_key', record_key, 'record_kind', $4::text, 'revision', $5::text,
+        'deleted', false, 'schema_hash', $6::text, 'payload', payload::text)
+      FROM (${records}) snapshot`, [target.generation, source, entityId, kind, state.revision, manifest.hash]);
+    });
+    for (const item of input.selection) {
+        const entity = manifest.entities.find((e) => e.id === item.entityId);
+        yield* baseline(entity.id, "entity", `SELECT r.id::text AS record_key,
+        (SELECT jsonb_object_agg(key, value) FROM jsonb_each(${snapshotExpression(entity, "r")})
+         WHERE key = 'id' OR ${ql(JSON.stringify(item.fields))}::jsonb ? key) AS payload
+       FROM ${qi(tableName(entity.name))} r`);
+        for (const relationship of entity.relationships.filter((r) => item.relationships?.includes(r.name))) {
+            const columns = joinColumnNames({
+                entity: entity.name,
+                relationship: relationship.name,
+                target: relationship.to,
+            });
+            yield* baseline(entity.id, `edge:${relationship.name}`, `SELECT ${qi(columns.source)}::text || ':' || ${qi(columns.target)}::text AS record_key,
+          jsonb_build_object('source_id', ${qi(columns.source)}::text,
+            'target_id', ${qi(columns.target)}::text) AS payload
+         FROM ${qi(joinTableName(entity.name, relationship.name))}`);
+        }
+    }
+    return target;
+}));

package/dist/replication/bigquery.d.ts

@@ -0,0 +1,23 @@
+import type { ReplicationTarget } from "./store.js";
+export declare const REPLICATION_TABLE_SCHEMA: readonly [...{
+    name: string;
+    type: string;
+    mode: string;
+}[], {
+    readonly name: "revision";
+    readonly type: "NUMERIC";
+    readonly mode: "REQUIRED";
+}, {
+    readonly name: "deleted";
+    readonly type: "BOOLEAN";
+    readonly mode: "REQUIRED";
+}, {
+    readonly name: "payload";
+    readonly type: "JSON";
+    readonly mode: "REQUIRED";
+}];
+/** Rank first, then apply tombstones. Every view reads the whole retained event history. */
+export declare function replicationViews(project: string, target: ReplicationTarget): {
+    readonly name: string;
+    readonly query: string;
+}[];

package/dist/replication/bigquery.js

@@ -0,0 +1,63 @@
+import { queryFields } from "../query.js";
+export const REPLICATION_TABLE_SCHEMA = [
+    ...[
+        "event_id",
+        "source_id",
+        "generation",
+        "entity_id",
+        "record_key",
+        "record_kind",
+        "schema_hash",
+    ].map((name) => ({ name, type: "STRING", mode: "REQUIRED" })),
+    { name: "revision", type: "NUMERIC", mode: "REQUIRED" },
+    { name: "deleted", type: "BOOLEAN", mode: "REQUIRED" },
+    { name: "payload", type: "JSON", mode: "REQUIRED" },
+];
+const literal = (value) => `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+const identifier = (value) => {
+    if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw new Error("Invalid BigQuery replication identifier.");
+    }
+    return `\`${value}\``;
+};
+/** Rank first, then apply tombstones. Every view reads the whole retained event history. */
+export function replicationViews(project, target) {
+    identifier(project);
+    const result = [];
+    const latest = (entity, kind, columns) => `SELECT ${columns} FROM (
+      SELECT *, ROW_NUMBER() OVER (PARTITION BY record_key ORDER BY revision DESC, event_id DESC) AS position
+      FROM \`${project}.ontology_internal.events\`
+      WHERE generation = ${literal(target.generation)} AND source_id = ${literal(target.source_id)}
+        AND entity_id = ${literal(entity)} AND record_kind = ${literal(kind)}
+    ) WHERE position = 1 AND NOT deleted`;
+    for (const selection of target.selection) {
+        const entity = target.manifest.entities.find((e) => e.id === selection.entityId);
+        const columns = queryFields(entity)
+            .filter((field) => field.name === "id" || selection.fields.includes(field.name))
+            .map((field) => {
+            const path = literal(`$.${field.name}`);
+            const type = {
+                integer: "INT64",
+                number: "FLOAT64",
+                boolean: "BOOL",
+                date: "DATE",
+                timestamp: "TIMESTAMP",
+            }[field.storage];
+            const value = field.storage === "json"
+                ? `JSON_QUERY(payload, ${path})`
+                : `JSON_VALUE(payload, ${path})`;
+            return `${type ? `SAFE_CAST(${value} AS ${type})` : value} AS ${identifier(field.name)}`;
+        });
+        result.push({ name: entity.name, query: latest(entity.id, "entity", columns.join(", ")) });
+        for (const relationship of selection.relationships ?? []) {
+            result.push({
+                name: `${entity.name}_${relationship}`,
+                query: latest(entity.id, `edge:${relationship}`, "JSON_VALUE(payload, '$.source_id') AS source_id, JSON_VALUE(payload, '$.target_id') AS target_id"),
+            });
+        }
+    }
+    if (new Set(result.map((v) => v.name.toLowerCase())).size !== result.length) {
+        throw new Error("Replicated entity and relationship view names collide.");
+    }
+    return result;
+}

package/dist/replication/model.d.ts

@@ -0,0 +1,38 @@
+import type { OntologyManifest } from "../manifest.js";
+/** The resolved projection for one immutable generation. `id` is always included. */
+export interface ReplicationSelection {
+    readonly entityId: string;
+    readonly fields: ReadonlyArray<string>;
+    readonly relationships?: ReadonlyArray<string>;
+}
+/** Everything is replicated unless explicitly excluded. Internal identity data is never exported. */
+export interface ReplicationExclusion {
+    readonly entityId: string;
+    readonly disabled?: boolean;
+    readonly fields?: ReadonlyArray<string>;
+    readonly relationships?: ReadonlyArray<string>;
+}
+export declare function resolveReplicationSelection(manifest: OntologyManifest, exclusions?: ReadonlyArray<ReplicationExclusion>): ReadonlyArray<ReplicationSelection>;
+export interface ReplicationEvent {
+    readonly event_id: string;
+    readonly source_id: string;
+    readonly generation: string;
+    readonly entity_id: string;
+    readonly record_key: string;
+    readonly record_kind: string;
+    /** Decimal strings preserve PostgreSQL bigint precision in JavaScript. */
+    readonly revision: string;
+    readonly deleted: boolean;
+    readonly schema_hash: string;
+    /** Pub/Sub's BigQuery table-schema mode expects a string for a JSON column. */
+    readonly payload: string;
+}
+export declare const REPLICATION_BATCH_SIZE = 100;
+export declare const REPLICATION_BATCH_BYTES = 1000000;
+export declare const REPLICATION_RECORD_BYTES = 200000;
+export declare function validateReplicationSelection(manifest: OntologyManifest, selection: ReadonlyArray<ReplicationSelection>): void;
+export declare function replicationEventId(source: string, history: string, generation: string): string;
+/** Includes base64 and JSON overhead, not just the original payload bytes. */
+export declare function publishMessage(event: ReplicationEvent): {
+    data: string;
+};

package/dist/replication/model.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { queryFields } from "../query.js";
+export function resolveReplicationSelection(manifest, exclusions = []) {
+    const entities = manifest.entities.filter((entity) => !entity.builtIn && !entity.source);
+    if (new Set(exclusions.map((item) => item.entityId)).size !== exclusions.length) {
+        throw new Error("Replication exclusions must name distinct entities.");
+    }
+    for (const item of exclusions) {
+        const entity = entities.find((candidate) => candidate.id === item.entityId);
+        if (!entity) {
+            throw new Error(`Unknown stored business entity in replication exclusions: ${item.entityId}.`);
+        }
+        const fields = new Set(queryFields(entity).map((field) => field.name));
+        const relationships = new Set(entity.relationships.map((relationship) => relationship.name));
+        if (item.fields?.some((field) => field === "id" || !fields.has(field))) {
+            throw new Error(`Unknown or required replication field on ${entity.name}.`);
+        }
+        if (item.relationships?.some((relationship) => !relationships.has(relationship))) {
+            throw new Error(`Unknown replication relationship on ${entity.name}.`);
+        }
+    }
+    const included = entities.filter((entity) => !exclusions.some((item) => item.entityId === entity.id && item.disabled));
+    const selection = included.map((entity) => {
+        const excluded = exclusions.find((item) => item.entityId === entity.id);
+        const excludedFields = new Set([
+            ...(excluded?.fields ?? []),
+            ...(excluded?.relationships ?? []).map((relationship) => `${relationship}_id`),
+        ]);
+        return {
+            entityId: entity.id,
+            fields: queryFields(entity)
+                .filter((field) => !excludedFields.has(field.name))
+                .map((field) => field.name),
+            relationships: entity.relationships
+                .filter((relationship) => relationship.cardinality === "many" &&
+                !excluded?.relationships?.includes(relationship.name) &&
+                included.some((target) => target.name === relationship.to))
+                .map((relationship) => relationship.name),
+        };
+    });
+    validateReplicationSelection(manifest, selection);
+    return selection;
+}
+export const REPLICATION_BATCH_SIZE = 100;
+export const REPLICATION_BATCH_BYTES = 1_000_000;
+// Leaves room for JSON escaping, the envelope and base64 inside a 1 MB publish request.
+export const REPLICATION_RECORD_BYTES = 200_000;
+export function validateReplicationSelection(manifest, selection) {
+    if (new Set(selection.map((s) => s.entityId)).size !== selection.length) {
+        throw new Error("Replicated entities must be distinct.");
+    }
+    const viewNames = new Set();
+    const addView = (name) => {
+        const key = name.toLowerCase();
+        if (viewNames.has(key)) {
+            throw new Error("Replicated entity and relationship view names collide.");
+        }
+        viewNames.add(key);
+    };
+    for (const item of selection) {
+        const entity = manifest.entities.find((e) => e.id === item.entityId);
+        if (!entity || entity.name === "user" || entity.source !== undefined) {
+            throw new Error(`Only stored business entities can be replicated: ${item.entityId}.`);
+        }
+        addView(entity.name);
+        const fields = new Set(queryFields(entity).map((f) => f.name));
+        if (item.fields.some((field) => !fields.has(field))) {
+            throw new Error(`Unknown replication field on ${entity.name}.`);
+        }
+        for (const name of item.relationships ?? []) {
+            const relationship = entity.relationships.find((r) => r.name === name);
+            const target = manifest.entities.find((e) => e.name === relationship?.to);
+            if (relationship?.cardinality !== "many" ||
+                !target ||
+                target.name === "user" ||
+                !selection.some((s) => s.entityId === target.id)) {
+                throw new Error(`Replication of ${entity.name}.${name} requires both business entities.`);
+            }
+            addView(`${entity.name}_${name}`);
+        }
+    }
+}
+export function replicationEventId(source, history, generation) {
+    return createHash("sha256").update(`${source}:${history}:${generation}`).digest("hex");
+}
+/** Includes base64 and JSON overhead, not just the original payload bytes. */
+export function publishMessage(event) {
+    return { data: Buffer.from(JSON.stringify(event)).toString("base64") };
+}

package/dist/replication/schema.d.ts

@@ -0,0 +1,7 @@
+import type { EntityManifest, OntologyManifest } from "../manifest.js";
+export declare const REPLICATION_SCHEMA_VERSION = 3;
+/** Installed only by the SDK migration runner, never at service startup. */
+export declare const REPLICATION_DDL: string[];
+export declare function snapshotExpression(entity: EntityManifest, alias: string): string;
+/** History is the durable source. Triggers also reject old writers while capture is enabled. */
+export declare function replicationEntityDdl(manifest: OntologyManifest): ReadonlyArray<string>;

package/dist/replication/schema.js

@@ -0,0 +1,123 @@
+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;
+/** Installed only by the SDK migration runner, never at service startup. */
+export const REPLICATION_DDL = [
+    `CREATE TABLE IF NOT EXISTS _ontology_replication (
+    id boolean PRIMARY KEY DEFAULT true CHECK (id), version integer NOT NULL,
+    source_id uuid NOT NULL DEFAULT gen_random_uuid(), revision bigint NOT NULL DEFAULT 0,
+    selection jsonb NOT NULL DEFAULT '{}'::jsonb, enabled boolean NOT NULL DEFAULT false
+  )`,
+    `INSERT INTO _ontology_replication (id, version) VALUES (true, ${REPLICATION_SCHEMA_VERSION}) ON CONFLICT DO NOTHING`,
+    `ALTER TABLE _ontology_replication ADD COLUMN IF NOT EXISTS exclusions jsonb NOT NULL DEFAULT '[]'::jsonb`,
+    `ALTER TABLE _ontology_replication ADD COLUMN IF NOT EXISTS active_generation uuid`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_targets (
+    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()
+  )`,
+    `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
+  )`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_receipts (
+    generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
+    event_id uuid NOT NULL, accepted_at timestamptz NOT NULL DEFAULT now(), verified_at timestamptz,
+    PRIMARY KEY (generation, event_id)
+  )`,
+    `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
+      RAISE EXCEPTION 'Replication requires a compatible ontology writer; pause replication before a data migration';
+    END IF;
+    RETURN NULL;
+  END $$`,
+];
+export function snapshotExpression(entity, alias) {
+    const values = queryFields(entity).flatMap((field) => {
+        const system = SYSTEM_COLUMNS[field.name];
+        const column = system ??
+            (entity.properties.some((p) => p.name === field.name)
+                ? columnName(field.name)
+                : relationshipColumnName(field.name.slice(0, -3)));
+        // JSON numbers cannot safely carry a PostgreSQL bigint across all transports.
+        const cast = field.storage === "integer" ? "::text" : "";
+        return [ql(field.name), `${alias}.${qi(column)}${cast}`];
+    });
+    const chunks = [];
+    for (let offset = 0; offset < values.length; offset += 80) {
+        chunks.push(`jsonb_build_object(${values.slice(offset, offset + 80).join(", ")})`);
+    }
+    return `(${chunks.join(" || ")})`;
+}
+/** History is the durable source. Triggers also reject old writers while capture is enabled. */
+export function replicationEntityDdl(manifest) {
+    return manifest.entities
+        .filter((e) => e.source === undefined && e.name !== "user")
+        .flatMap((entity) => {
+        const history = qi(historyTableName(entity.name));
+        const table = qi(tableName(entity.name));
+        // Keep names stable across renames and below PostgreSQL's 63-byte identifier limit.
+        const key = createHash("sha256").update(entity.id).digest("hex").slice(0, 40);
+        const fn = qi(`_replicate_${key}`);
+        const declared = entity.relationships
+            .filter((r) => r.cardinality === "many")
+            .map((r) => r.name);
+        return [
+            `ALTER TABLE ${history} ADD COLUMN IF NOT EXISTS replication jsonb`,
+            `CREATE INDEX IF NOT EXISTS ${qi(`_replication_${key}_idx`)} ON ${history}
+        (((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';
+      BEGIN
+        SELECT * INTO state FROM _ontology_replication WHERE id;
+        policy := state.selection->${ql(entity.id)};
+        IF NOT state.enabled OR policy IS NULL THEN RETURN NEW; END IF;
+        record_key := NEW.record_id::text;
+        IF NEW.kind IN ('link', 'unlink') THEN
+          SELECT key INTO relation FROM jsonb_object_keys(NEW.changes) AS key LIMIT 1;
+          IF NOT (${ql(JSON.stringify(declared))}::jsonb ? relation) OR
+             NOT (COALESCE(policy->'relationships', '[]'::jsonb) ? relation) THEN RETURN NEW; END IF;
+          other_id := COALESCE(NEW.changes->relation->>'after', NEW.changes->relation->>'before');
+          record_key := NEW.record_id::text || ':' || other_id;
+          record_kind := 'edge:' || relation;
+          is_deleted := NEW.kind = 'unlink';
+          snapshot := jsonb_build_object('source_id', NEW.record_id::text, 'target_id', other_id);
+        ELSIF is_deleted THEN snapshot := '{}'::jsonb;
+        ELSE
+          SELECT ${snapshotExpression(entity, "record")} INTO snapshot FROM ${table} AS record WHERE id = NEW.record_id;
+          SELECT COALESCE(jsonb_object_agg(key, value), '{}'::jsonb) INTO snapshot
+            FROM jsonb_each(snapshot) WHERE key = 'id' OR (policy->'fields' ? key);
+          IF snapshot IS NULL OR snapshot = '{}'::jsonb THEN RAISE EXCEPTION 'Replication snapshot is missing'; END IF;
+        END IF;
+        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;
+        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,
+          'schema_hash', ${ql(manifest.hash)}, 'payload', snapshot::text);
+        RETURN NEW;
+      END $$`,
+            `DROP TRIGGER IF EXISTS _ontology_capture ON ${history}`,
+            `CREATE TRIGGER _ontology_capture BEFORE INSERT ON ${history} FOR EACH ROW EXECUTE FUNCTION ${fn}()`,
+            `DROP TRIGGER IF EXISTS _ontology_writer_guard ON ${table}`,
+            `CREATE TRIGGER _ontology_writer_guard BEFORE INSERT OR UPDATE OR DELETE OR TRUNCATE ON ${table}
+        FOR EACH STATEMENT EXECUTE FUNCTION _ontology_replication_guard()`,
+            ...entity.relationships
+                .filter((r) => r.cardinality === "many")
+                .flatMap((r) => {
+                const join = qi(joinTableName(entity.name, r.name));
+                return [
+                    `DROP TRIGGER IF EXISTS _ontology_writer_guard ON ${join}`,
+                    `CREATE TRIGGER _ontology_writer_guard BEFORE INSERT OR UPDATE OR DELETE OR TRUNCATE ON ${join}
+              FOR EACH STATEMENT EXECUTE FUNCTION _ontology_replication_guard()`,
+                ];
+            }),
+        ];
+    });
+}

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/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.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({
@@ -295,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,
             ]);
@@ -313,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);
@@ -576,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({
@@ -636,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

@@ -60,6 +60,14 @@ 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/handlers.d.ts

@@ -2,6 +2,7 @@ import { Layer } from "effect";
 import { type HttpApiGroup } from "effect/unstable/httpapi";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
+import type { ReplicationKick } from "./replication.js";
 import type { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
@@ -11,4 +12,4 @@ import { OntologyBackend } from "./runtime-contract.js";
  */
 export declare const SIGN_IN_CHECK_LIMIT: RateLimit;
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;
+export declare function handlersLayer(built: BuiltApi, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): Layer.Layer<HttpApiGroup.Service<"ontology", string>, never, OntologyBackend>;

package/dist/service/handlers.js

@@ -178,8 +178,8 @@ function storageHandlers(built) {
     }));
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
-export function handlersLayer(built, hooks, connections) {
-    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections);
+export function handlersLayer(built, hooks, connections, replicate) {
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections, replicate);
     const layers = [
         serviceHandlers(built, operationsOf),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))

package/dist/service/mcp/server.d.ts

@@ -5,6 +5,7 @@ import { type TokenVerifier } from "../authentication.js";
 import type { AfterCommitHook } from "../config.js";
 import type { ConnectionTransportFactory } from "../connections.js";
 import { RequestId } from "../errors.js";
+import type { ReplicationKick } from "../replication.js";
 import { OntologyBackend } from "../runtime-contract.js";
 /** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
 export declare const MCP_PATH = "/mcp";
@@ -14,6 +15,7 @@ export interface McpServerOptions {
     readonly built: BuiltApi;
     readonly hooks: ReadonlyMap<string, AfterCommitHook>;
     readonly connections: ConnectionTransportFactory;
+    readonly replicate: ReplicationKick;
     readonly verifyToken: TokenVerifier;
 }
 /**

package/dist/service/mcp/server.js

@@ -361,7 +361,7 @@ export function mcpLayer(options) {
         const server = {
             built: options.built,
             tools,
-            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections),
+            operations: makeOperations(backend, options.built.plan, options.hooks, options.connections, options.replicate),
         };
         yield* router.add("POST", MCP_PATH, handlePost(server, options.verifyToken, backend));
         yield* router.add("GET", MCP_PATH, METHOD_NOT_ALLOWED);

package/dist/service/operations.d.ts

@@ -4,6 +4,7 @@ import { PermissionDenied } from "../errors.js";
 import type { Query, QueryResult } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import type { AfterCommitHook } from "./config.js";
+import type { ReplicationKick } from "./replication.js";
 import { type ConnectionTransportFactory } from "./connections.js";
 import { InvalidActionInput, RequestId } from "./errors.js";
 import type { ApiPlan, PlannedAction, PlannedEntity, Traversal } from "./plan.js";
@@ -59,7 +60,7 @@ export interface Caller {
 }
 type Backend = OntologyBackend["Service"];
 /** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory): {
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick): {
     /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
     find: (planned: PlannedEntity, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../index.js").InvalidQuery, CurrentPrincipal>;
     /** One record. Requires `read` on the entity. */

package/dist/service/operations.js

@@ -145,7 +145,7 @@ function traverseOf(backend, targets, planned, traversal, id, query) {
         return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
     });
 }
-function runActionOf(backend, ontology, hooks, connections) {
+function runActionOf(backend, ontology, hooks, connections, replicate) {
     return (planned, { name, generated }, call) => Effect.gen(function* () {
         const principal = yield* CurrentPrincipal;
         const requestId = yield* RequestId;
@@ -161,9 +161,19 @@ function runActionOf(backend, ontology, hooks, connections) {
                 identityToken: call.identityToken,
                 audit: { action: `${planned.name}.${name}`, principalId: principal.id, requestId },
             }),
-            ...(hook === undefined
-                ? {}
-                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
+            ...(hook || backend.replicationEnabled
+                ? {
+                    afterCommit: (committed) => Effect.gen(function* () {
+                        if (hook) {
+                            yield* afterCommitOf(hook, { requestId, generated }, ontology)(committed);
+                        }
+                        if (committed.edits.length > 0 &&
+                            (yield* backend.replicationEnabled ?? Effect.succeed(false))) {
+                            yield* replicate(call.identityToken);
+                        }
+                    }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause))),
+                }
+                : {}),
         });
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !call.validateOnly) {
@@ -199,7 +209,7 @@ function callerOf(backend) {
     });
 }
 /** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
-export function makeOperations(backend, plan, hooks, connections) {
+export function makeOperations(backend, plan, hooks, connections, replicate) {
     const targets = relationshipTargets(plan);
     return {
         /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
@@ -211,7 +221,7 @@ export function makeOperations(backend, plan, hooks, connections) {
         /** The records a relationship reaches from one record, as a page of the target entity. */
         traverse: (planned, traversal, id, query) => traverseOf(backend, targets, planned, traversal, id, query),
         /** Runs an action as the caller, with the action's after-commit hook and connections. */
-        runAction: runActionOf(backend, plan.ontology, hooks, connections),
+        runAction: runActionOf(backend, plan.ontology, hooks, connections, replicate),
         /** The caller's user, roles and permissions. It needs no permission. */
         caller: callerOf(backend),
     };

package/dist/service/replication.d.ts

@@ -0,0 +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. */
+export declare function deployedReplication(environment: OntologyEnvironment, fetchImpl?: typeof fetch): ReplicationKick;

package/dist/service/replication.js

@@ -0,0 +1,25 @@
+import { Effect } from "effect";
+/** A fast path only. The committed history, not this request, makes delivery durable. */
+export function deployedReplication(environment, fetchImpl = fetch) {
+    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}.`);
+            }
+        }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause)));
+    };
+}

package/dist/service/runtime-contract.d.ts

@@ -189,6 +189,7 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
     readonly resolveApiKey: (key: Redacted.Redacted<string>) => Effect.Effect<Principal | undefined>;
     /** The manifest hash recorded in the `_ontology` catalog table, or `undefined` before the first. */
     readonly appliedHash: Effect.Effect<string | undefined>;
+    readonly replicationEnabled?: Effect.Effect<boolean>;
     /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
     readonly oauth?: OAuthStore;
 }>;

package/dist/service/service.js

@@ -11,6 +11,7 @@ import { RequestId, failureResponse, internalError, errorBodyForWire, routeNotFo
 import { deployedConnections, localConnections } from "./connections.js";
 import { DocsRoute } from "./docs.js";
 import { handlersLayer } from "./handlers.js";
+import { deployedReplication } from "./replication.js";
 import { mcpLayer } from "./mcp/server.js";
 import { oauthLayer } from "./oauth/server.js";
 import { planApi } from "./plan.js";
@@ -82,14 +83,15 @@ export function createOntologyService(ontology, config) {
         (config.localConnections === undefined
             ? deployedConnections(config)
             : localConnections(config.localConnections));
-    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections)), Layer.provide([
+    const replicate = deployedReplication(config);
+    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections, replicate)), Layer.provide([
         authenticationLayer(verifyToken, exchangeSession),
         ErrorResponsesLive,
         storageMaintenanceAuthenticationLayer(config.storageMaintenanceKey),
     ]));
     const mcp = config.mcp === false
         ? Layer.empty
-        : Layer.mergeAll(mcpLayer({ built, hooks, connections, verifyToken }), oauthLayer({ verifyToken }));
+        : Layer.mergeAll(mcpLayer({ built, hooks, connections, verifyToken, replicate }), oauthLayer({ verifyToken }));
     const application = Layer.mergeAll(routes, mcp, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(backend), Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",