@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/replication/evolution.js

@@ -0,0 +1,184 @@
+import { migratedReplicationIdentities, replicationIdentities } from "./identities.js";
+import { prepareShadowEpoch, servingShadowEpoch, migrateShadowCapture, candidateShadowEpoch, shadowEpoch, shadowProjectionHash, enableShadowCapture, expandShadowRoutes, } from "./shadow.js";
+import { Effect } from "effect";
+import { historyTableName, quoteIdentifier as qi, tableName, joinTableName, columnName, } from "../migrate/storage.js";
+import { queryFields } from "../query.js";
+import { migratedReplicationLineage, renamedReplicationField } from "./lineage.js";
+import { replicationScanScopes, scheduleReplicationScans, upgradeReplicationScans, reconcileReplicationScans, } from "./scans.js";
+/** Freeze an import's source order before migrations change declaration order or storage names. */
+export const prepareReplicationEvolution = (sql) => Effect.gen(function* () {
+    const targets = yield* sql.unsafe("SELECT * FROM _ontology_replication_targets");
+    for (const target of targets) {
+        if (target.backfill_complete === false && !target.backfill_sources) {
+            const sources = [
+                { table: null },
+                ...target.selection.map((item) => ({
+                    table: historyTableName(target.manifest.entities.find((entity) => entity.id === item.entityId).name),
+                })),
+            ];
+            yield* sql.unsafe("UPDATE _ontology_replication_targets SET backfill_sources = $2::jsonb WHERE generation = $1::uuid", [target.generation, JSON.stringify(sources)]);
+        }
+        yield* upgradeReplicationScans(sql, target);
+    }
+});
+export function replicationRecoveryScopes(current, target, retained) {
+    const scopes = [];
+    const resets = [];
+    for (const next of target.selection) {
+        const previous = current.selection.find((item) => item.entityId === next.entityId);
+        const before = current.manifest.entities.find((entity) => entity.id === next.entityId);
+        const entity = target.manifest.entities.find((entity) => entity.id === next.entityId);
+        const kept = retained?.entities.find((entity) => entity.id === next.entityId);
+        if (!previous || !before) {
+            const all = replicationScanScopes({ selection: [next] });
+            scopes.push(...all);
+            resets.push(...all);
+            continue;
+        }
+        const previousFields = new Set(queryFields(before).map((field) => field.name));
+        const needsRecords = next.fields.some((field) => {
+            const old = renamedReplicationField(current.manifest, target.manifest, entity.id, field) ?? field;
+            return ((!previous.fields.includes(old) && previousFields.has(old)) ||
+                kept?.fields.properties.some((property) => property.name === field) ||
+                kept?.fields.relationships.some((relationship) => `${relationship.name}_id` === field));
+        });
+        if (needsRecords) {
+            scopes.push({ entityId: entity.id, kind: "entity" });
+        }
+        for (const name of next.relationships ?? []) {
+            if (!previous.relationships?.includes(name) ||
+                kept?.fields.relationships.some((relationship) => relationship.name === name)) {
+                const scope = { entityId: entity.id, kind: `edge:${name}` };
+                scopes.push(scope);
+                resets.push(scope);
+            }
+        }
+    }
+    return { scopes, resets };
+}
+export const refreshReplicationProjection = (sql, current, target, retained, options = {}) => Effect.gen(function* () {
+    const [version] = yield* sql.unsafe("SELECT version FROM _ontology_replication WHERE id");
+    if ((version?.version ?? 0) >= 6) {
+        target = { ...target, identities: migratedReplicationIdentities(current, target) };
+        if (!options.resuming && shadowProjectionHash(current) === shadowProjectionHash(target)) {
+            const [capture] = yield* sql.unsafe("SELECT capturing FROM _ontology_replication_targets WHERE generation=$1::uuid", [current.generation]);
+            if (!capture?.capturing) {
+                yield* enableShadowCapture(sql, current, replicationScanScopes(current));
+            }
+            return;
+        }
+        yield* migrateShadowCapture(sql, current.manifest, target.manifest, target.selection, replicationIdentities(target));
+        const serving = yield* servingShadowEpoch(sql);
+        const pending = yield* candidateShadowEpoch(sql);
+        const previous = pending?.predecessor
+            ? yield* shadowEpoch(sql, pending.predecessor)
+            : undefined;
+        // Only a recorded serving epoch (or its recorded predecessor) is publication evidence.
+        // An unfinished first scan is never coverage that another epoch may reuse.
+        const predecessor = serving ?? previous;
+        // Explicit resume must recover writes missed while capture was paused. Migration callers
+        // omit that intent: their transaction-local capture fence still permits scoped recovery.
+        const scopes = predecessor && !options.resuming
+            ? replicationRecoveryScopes(predecessor.target, target, retained).scopes
+            : replicationScanScopes(target);
+        yield* prepareShadowEpoch(sql, {
+            target: { ...target, generation: crypto.randomUUID() },
+            affected: scopes,
+            predecessor,
+        });
+        return;
+    }
+    const [revision] = yield* sql.unsafe("SELECT (CASE WHEN is_called THEN last_value ELSE 0 END)::text AS revision FROM _ontology_replication_revision");
+    const { scopes, resets } = replicationRecoveryScopes(current, target, retained);
+    const lineage = migratedReplicationLineage(current, target, revision.revision, resets);
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets SET manifest = $2::jsonb, selection = $3::jsonb,
+    fills = $4::jsonb, lineage = $5::jsonb WHERE generation = $1::uuid`, [
+        target.generation,
+        JSON.stringify(target.manifest),
+        JSON.stringify(target.selection),
+        JSON.stringify(target.fills ?? {}),
+        JSON.stringify(lineage),
+    ]);
+    yield* reconcileReplicationScans(sql, target);
+    yield* scheduleReplicationScans(sql, target.generation, scopes, { reset: true });
+});
+/** Pending and replayable envelopes outlive storage explicitly dropped by a supported migration. */
+export const retainReplicationHistory = (sql, table) => Effect.gen(function* () {
+    const [exists] = yield* sql.unsafe("SELECT to_regclass($1) IS NOT NULL AS present", [qi(table)]);
+    if (!exists?.present) {
+        return;
+    }
+    // Imports may not yet have reached this history. Materialize only this affected history before
+    // its DROP, in the same transaction, retaining original IDs, revisions and acceptance receipts.
+    yield* sql.unsafe(`INSERT INTO _ontology_replication_delivery
+    (generation,event_id,history_table,revision,payload,accepted_at,verified_at)
+    SELECT t.generation,h.id,NULL,(h.replication->>'revision')::bigint,h.replication,r.accepted_at,r.verified_at
+    FROM _ontology_replication_targets t CROSS JOIN ${qi(table)} h
+    LEFT JOIN _ontology_replication_receipts r ON r.generation=t.generation AND r.event_id=h.id
+    WHERE NOT t.backfill_complete AND h.replication IS NOT NULL
+      AND h.replication->>'source_id'=t.source_id::text
+      AND (h.replication->>'revision')::bigint > t.from_revision
+      AND (h.replication->>'revision')::bigint <= t.backfill_revision
+      AND EXISTS (SELECT 1 FROM jsonb_array_elements(t.backfill_sources) s WHERE s->>'table'=$1)
+    ON CONFLICT DO NOTHING`, [table]);
+    yield* sql.unsafe(`UPDATE _ontology_replication_delivery d SET payload=h.replication, history_table=NULL
+    FROM ${qi(table)} h WHERE d.history_table=$1 AND d.event_id=h.id`, [table]);
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets t SET backfill_sources=(
+    SELECT jsonb_agg(CASE WHEN s->>'table'=$1 THEN s || '{"skip":true}'::jsonb ELSE s END ORDER BY n)
+    FROM jsonb_array_elements(t.backfill_sources) WITH ORDINALITY AS item(s,n))
+    WHERE t.backfill_sources IS NOT NULL`, [table]);
+});
+export const renameReplicationHistory = (sql, previous, next) => Effect.gen(function* () {
+    yield* sql.unsafe("UPDATE _ontology_replication_delivery SET history_table=$2 WHERE history_table=$1", [previous, next]);
+    yield* sql.unsafe(`UPDATE _ontology_replication_targets t SET backfill_sources=(
+      SELECT jsonb_agg(CASE WHEN s->>'table'=$1 THEN jsonb_set(s,'{table}',to_jsonb($2::text)) ELSE s END ORDER BY n)
+      FROM jsonb_array_elements(t.backfill_sources) WITH ORDINALITY AS item(s,n))
+      WHERE t.backfill_sources IS NOT NULL`, [previous, next]);
+});
+/** Physical cleanup may proceed after cutover; only storage still needed by serving is protected. */
+export const dropsServingReplicationStorage = (sql, input) => Effect.gen(function* () {
+    const destructive = input.steps.filter((step) => step.classification === "destructive");
+    if (!destructive.length) {
+        return false;
+    }
+    const epochs = input.version >= 6
+        ? yield* sql.unsafe(`SELECT target, routes FROM _ontology_replication_epochs WHERE state='serving'
+      OR (state='retired' AND retired_at IS NULL)`)
+        : [];
+    const routes = epochs.length
+        ? epochs.flatMap((epoch) => expandShadowRoutes(epoch.routes, epoch.target))
+        : replicationScanScopes(input.target).map((scope) => ({ ...scope, target: input.target }));
+    const captures = input.version >= 6
+        ? yield* sql.unsafe("SELECT generation::text,capture_bindings FROM _ontology_replication_targets WHERE capturing")
+        : [];
+    const statements = destructive
+        .flatMap((step) => step.sql)
+        .map((statement) => statement.replace(/\s+/g, " "));
+    for (const route of routes) {
+        const entity = route.target.manifest.entities.find((entity) => entity.id === route.entityId);
+        const name = input.current.entities.find((item) => item.id === entity.id)?.name ??
+            input.retained?.entities.find((item) => item.id === entity.id)?.name ??
+            entity.name;
+        const table = route.kind === "entity" ? tableName(name) : joinTableName(name, route.kind.slice(5));
+        if (statements.some((statement) => statement.includes(`DROP TABLE ${qi(table)}`))) {
+            return true;
+        }
+        if (route.kind !== "entity") {
+            continue;
+        }
+        const selection = route.target.selection.find((item) => item.entityId === entity.id);
+        const bindings = captures.find((capture) => capture.generation === route.target.generation)
+            ?.capture_bindings?.[entity.id];
+        const fields = route.target.lineage?.epochs.at(-1)?.fields[entity.id];
+        for (const field of selection.fields) {
+            const slot = fields?.[field]?.key ?? field;
+            const current = bindings?.[slot] ?? field;
+            const column = columnName(current);
+            if (statements.some((statement) => statement.includes(`ALTER TABLE ${qi(table)} `) &&
+                statement.includes(`DROP COLUMN ${qi(column)}`))) {
+                return true;
+            }
+        }
+    }
+    return false;
+});

package/dist/replication/identities.d.ts

@@ -0,0 +1,6 @@
+import type { ReplicationTarget } from "./baseline.js";
+/** Logical field identities survive renames and copies, but never transfer to a reused name. */
+export type ReplicationIdentities = Readonly<Record<string, Readonly<Record<string, string>>>>;
+export declare function replicationIdentities(target: ReplicationTarget): ReplicationIdentities;
+export declare function migratedReplicationIdentities(current: ReplicationTarget, target: ReplicationTarget): ReplicationIdentities;
+export declare function permittedReplicationField(actual: ReplicationTarget, policy: ReplicationTarget, entity: string, field: string): boolean;

package/dist/replication/identities.js

@@ -0,0 +1,47 @@
+import { createHash } from "node:crypto";
+import { queryFields } from "../query.js";
+import { renamedReplicationField } from "./lineage.js";
+export function replicationIdentities(target) {
+    return (target.identities ??
+        Object.fromEntries(target.manifest.entities.map((entity) => [
+            entity.id,
+            Object.fromEntries([
+                ...queryFields(entity).map((field) => field.name),
+                ...entity.relationships
+                    .filter((relationship) => relationship.cardinality === "many")
+                    .map((relationship) => `edge:${relationship.name}`),
+            ].map((field) => [
+                field,
+                createHash("sha256")
+                    .update(`${target.source_id}:${target.generation}:${target.manifest.hash}:${entity.id}:${field}`)
+                    .digest("hex"),
+            ])),
+        ])));
+}
+export function migratedReplicationIdentities(current, target) {
+    const previous = replicationIdentities(current);
+    const initial = replicationIdentities({ ...target, identities: undefined });
+    return Object.fromEntries(Object.entries(initial).map(([entityId, fields]) => [
+        entityId,
+        Object.fromEntries(Object.entries(fields).map(([field, identity]) => {
+            const old = renamedReplicationField(current.manifest, target.manifest, entityId, field) ?? field;
+            return [field, previous[entityId]?.[old] ?? identity];
+        })),
+    ]));
+}
+export function permittedReplicationField(actual, policy, entity, field) {
+    const selected = policy.selection.find((item) => item.entityId === entity);
+    const actualIdentity = replicationIdentities(actual)[entity]?.[field];
+    if (!selected || !actualIdentity) {
+        return false;
+    }
+    const identities = replicationIdentities(policy)[entity] ?? {};
+    const permitted = field.startsWith("edge:")
+        ? (selected.relationships ?? []).map((name) => `edge:${name}`)
+        : ["id", ...selected.fields];
+    // When the public name still exists, it must denote this exact identity. Only an absent old name
+    // may remain a compatibility alias for a permitted renamed property.
+    return identities[field] !== undefined
+        ? permitted.includes(field) && identities[field] === actualIdentity
+        : permitted.some((name) => identities[name] === actualIdentity);
+}

package/dist/replication/legacy-baseline.d.ts

@@ -0,0 +1,27 @@
+import { Effect, Schema } 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>;
+}
+declare const ReplicationBaselineFailed_base: Schema.Class<ReplicationBaselineFailed, Schema.TaggedStruct<"ReplicationBaselineFailed", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/** An initial snapshot cannot be created with the requested state or record projection. */
+export declare class ReplicationBaselineFailed extends ReplicationBaselineFailed_base {
+}
+/** Legacy snapshots commit with enablement; an upgraded protocol uses resumable online pages. */
+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 | import("./baseline.js").ReplicationBaselineFailed | ReplicationBaselineFailed, never>;
+export {};

package/dist/replication/legacy-baseline.js

@@ -0,0 +1,109 @@
+import { randomUUID } from "node:crypto";
+import { Effect, Schema } 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";
+import { createReplicationBaseline as createCurrentBaseline } from "./baseline.js";
+import { lockReplicationLifecycle } from "./transaction.js";
+/** An initial snapshot cannot be created with the requested state or record projection. */
+export class ReplicationBaselineFailed extends Schema.TaggedError()("ReplicationBaselineFailed", { message: Schema.String, cause: Schema.optionalKey(Schema.Unknown) }) {
+}
+// @legacy ontology.replication-older-source-protocols
+/** Legacy snapshots commit with enablement; an upgraded protocol uses resumable online pages. */
+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'");
+    yield* lockReplicationLifecycle(sql);
+    const [state] = yield* sql.unsafe("SELECT source_id::text, revision::text, enabled, version FROM _ontology_replication WHERE id");
+    if (!state) {
+        return yield* new ReplicationBaselineFailed({
+            message: "Run the ontology SDK migration before enabling replication.",
+        });
+    }
+    // Protocol dispatch happened outside this transaction; a migration may have upgraded it.
+    if (state.version >= 4) {
+        return yield* createCurrentBaseline(sql, input);
+    }
+    const existing = yield* sql.unsafe("SELECT * FROM _ontology_replication_targets WHERE generation = $1::uuid", [input.generation]);
+    if (existing[0]) {
+        return existing[0];
+    }
+    const manifest = input.manifest;
+    yield* Effect.try({
+        try: () => validateReplicationSelection(manifest, input.selection),
+        catch: (cause) => new ReplicationBaselineFailed({ message: "Invalid replication projection.", cause }),
+    });
+    // Drain older SDK transactions that started before the compatibility fence was enabled.
+    const tables = manifest.entities
+        .filter((e) => e.source === undefined && !e.builtIn)
+        .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),
+    ]);
+    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 EXISTS (
+              SELECT 1 FROM (${records}) snapshot
+              WHERE octet_length(payload::text) > ${REPLICATION_RECORD_BYTES}
+            ) AS oversized`);
+        if (size.oversized) {
+            return yield* new ReplicationBaselineFailed({
+                message: `A projected baseline record exceeds ${REPLICATION_RECORD_BYTES} bytes; ` +
+                    "exclude large fields before enabling replication.",
+            });
+        }
+        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/legacy-store.d.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type ReplicationEvent } from "./model.js";
+import type { ReplicationTarget } from "./baseline.js";
+/** 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;
+}, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Legacy writers serialize their revisions; the platform persists this fixed upper boundary. */
+export declare const replicationInitiallyReady: (sql: SqlClient.SqlClient, target: ReplicationTarget, initialRevision: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/replication/legacy-store.js

@@ -0,0 +1,63 @@
+import { Effect } from "effect";
+import { historyTableName, quoteIdentifier as qi } from "../migrate/storage.js";
+import { REPLICATION_BATCH_BYTES, REPLICATION_BATCH_SIZE, publishMessage, replicationEventId, } from "./model.js";
+/** 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
+     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]));
+// @legacy ontology.replication-older-source-protocols
+/** Legacy writers serialize their revisions; the platform persists this fixed upper boundary. */
+export const replicationInitiallyReady = (sql, target, initialRevision) => sql
+    .unsafe(`SELECT NOT EXISTS (
+     SELECT 1 FROM (${replicationEventsSql(target)}) e
+     WHERE (e.event->>'revision')::bigint <= $4::bigint AND NOT EXISTS (
+       SELECT 1 FROM _ontology_replication_receipts r
+       WHERE r.generation = $1::uuid AND r.event_id = e.id
+     )
+   ) AS ready`, [target.generation, target.source_id, target.from_revision, initialRevision])
+    .pipe(Effect.map((rows) => rows[0].ready));

package/dist/replication/lineage.d.ts

@@ -0,0 +1,36 @@
+import type { OntologyManifest } from "../manifest.js";
+import type { ReplicationFills, ReplicationSelection } from "./model.js";
+/** One logical property's representation in a captured schema. A missing key is not JSON null. */
+export interface ReplicationFieldBinding {
+    readonly key: string | null;
+    readonly fill?: unknown;
+}
+export interface ReplicationProjectionEpoch {
+    readonly schemaHash: string;
+    /** Inclusive, fixed while lifecycle admission drains all earlier writers. */
+    readonly throughRevision?: string;
+    readonly fields: Readonly<Record<string, Readonly<Record<string, ReplicationFieldBinding>>>>;
+}
+export interface ReplicationLineage {
+    readonly epochs: ReadonlyArray<ReplicationProjectionEpoch>;
+    /** Earlier incarnations of re-included records/edges must not resurrect after a scoped scan. */
+    readonly minimumRevisions: Readonly<Record<string, Readonly<Record<string, string>>>>;
+}
+interface Projection {
+    readonly manifest: OntologyManifest;
+    readonly selection: ReadonlyArray<ReplicationSelection>;
+    readonly fills?: ReplicationFills;
+    readonly lineage?: ReplicationLineage | null;
+}
+export declare function renamedReplicationField(current: OntologyManifest, target: OntologyManifest, entityId: string, field: string): string | undefined;
+export declare function initialReplicationLineage(projection: Projection): ReplicationLineage;
+/**
+ * Rewrite historical bindings, never historical events. Revision intervals disambiguate a schema
+ * hash used again after a rollback or a name reused for a different property. Hashes record the
+ * schema at each boundary; migrations with identical wire fields need no different expression.
+ */
+export declare function migratedReplicationLineage(current: Projection, target: Projection, throughRevision: string, resetScopes?: ReadonlyArray<{
+    readonly entityId: string;
+    readonly kind: string;
+}>): ReplicationLineage;
+export {};

package/dist/replication/lineage.js

@@ -0,0 +1,72 @@
+import { toSnakeCase } from "../names.js";
+const fieldsWithId = (fields) => fields.includes("id") ? fields : ["id", ...fields];
+export function renamedReplicationField(current, target, entityId, field) {
+    const previous = current.entities.find((entity) => entity.id === entityId);
+    const property = target.entities
+        .find((entity) => entity.id === entityId)
+        ?.properties.find((property) => property.name === field);
+    const old = property?.renamedFrom;
+    // `renamedFrom` can remain in a manifest after the migration already renamed its storage.
+    if (!old || previous?.properties.some((property) => property.name === field)) {
+        return undefined;
+    }
+    return previous?.properties.find((property) => property.name === old || property.name === toSnakeCase(old))?.name;
+}
+export function initialReplicationLineage(projection) {
+    return {
+        epochs: [
+            {
+                schemaHash: projection.manifest.hash,
+                fields: Object.fromEntries(projection.selection.map((entity) => [
+                    entity.entityId,
+                    Object.fromEntries(fieldsWithId(entity.fields).map((field) => [
+                        field,
+                        {
+                            key: field,
+                            ...(Object.hasOwn(projection.fills?.[entity.entityId] ?? {}, field)
+                                ? { fill: projection.fills[entity.entityId][field] }
+                                : {}),
+                        },
+                    ])),
+                ])),
+            },
+        ],
+        minimumRevisions: {},
+    };
+}
+/**
+ * Rewrite historical bindings, never historical events. Revision intervals disambiguate a schema
+ * hash used again after a rollback or a name reused for a different property. Hashes record the
+ * schema at each boundary; migrations with identical wire fields need no different expression.
+ */
+export function migratedReplicationLineage(current, target, throughRevision, resetScopes = []) {
+    const lineage = current.lineage ?? initialReplicationLineage(current);
+    const epochs = lineage.epochs.map((epoch) => ({
+        schemaHash: epoch.schemaHash,
+        throughRevision: epoch.throughRevision ?? throughRevision,
+        fields: Object.fromEntries(target.selection.map((next) => {
+            const previous = current.selection.find((entity) => entity.entityId === next.entityId);
+            const bindings = Object.fromEntries(fieldsWithId(next.fields).map((field) => {
+                const old = renamedReplicationField(current.manifest, target.manifest, next.entityId, field) ??
+                    field;
+                const captured = previous !== undefined && (old === "id" || previous.fields.includes(old));
+                const binding = captured ? epoch.fields[next.entityId]?.[old] : undefined;
+                const fill = target.fills?.[next.entityId];
+                return [
+                    field,
+                    binding ?? {
+                        key: null,
+                        ...(Object.hasOwn(fill ?? {}, field) ? { fill: fill[field] } : {}),
+                    },
+                ];
+            }));
+            return [next.entityId, bindings];
+        })),
+    }));
+    const next = initialReplicationLineage(target).epochs[0];
+    const minimumRevisions = Object.fromEntries(Object.entries(lineage.minimumRevisions).map(([entity, kinds]) => [entity, { ...kinds }]));
+    for (const scope of resetScopes) {
+        (minimumRevisions[scope.entityId] ??= {})[scope.kind] = throughRevision;
+    }
+    return { epochs: [...epochs, next], minimumRevisions };
+}

package/dist/replication/migrate.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { OntologyManifest } from "../manifest.js";
+import type { RetainedStorage } from "../migrate/model.js";
+import type { ReplicationTarget } from "./baseline.js";
+import { type ReplicationExclusion, type ReplicationSelection } from "./model.js";
+/** Persist exclusions across temporary removals, and follow a property's logical rename. */
+export declare function migrationReplicationExclusions(current: OntologyManifest, target: OntologyManifest, exclusions: ReadonlyArray<ReplicationExclusion>): ReadonlyArray<ReplicationExclusion>;
+/** Only current declarations participate; retained exclusions still protect a later restoration. */
+export declare function effectiveReplicationExclusions(manifest: OntologyManifest, exclusions: readonly ReplicationExclusion[]): {
+    relationships?: ReadonlyArray<string>;
+    fields?: ReadonlyArray<string>;
+    entityId: string;
+    disabled?: boolean;
+}[];
+/**
+ * Fills of the migrated target, read inside the migration transaction after its steps. PostgreSQL gives
+ * a field added to an existing entity one value on every row, so any row shows it as capture would
+ * serialize it. A null value needs no fill: a missing key already reads as null.
+ */
+export declare const migratedReplicationFills: (sql: SqlClient.SqlClient, current: ReplicationTarget, manifest: OntologyManifest, selection: ReadonlyArray<ReplicationSelection>, retained?: RetainedStorage) => Effect.Effect<Readonly<Record<string, Readonly<Record<string, unknown>>>>, import("effect/unstable/sql/SqlError").SqlError, never>;