@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/replication/schema.js

@@ -0,0 +1,226 @@
+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";
+import { SHADOW_REPLICATION_DDL, SHADOW_CONTROL_JOBS_DDL, SHADOW_SOURCE_REPLACEMENTS_DDL, } from "./shadow-schema.js";
+export const REPLICATION_SCHEMA_VERSION = 6;
+/** Targets of sources not migrated since fills were introduced have no `fills` column. */
+export const REPLICATION_TARGET_FILLS = `COALESCE(to_jsonb(_ontology_replication_targets) -> 'fills',
+  '{}'::jsonb) AS fills`;
+/** Optional metadata keeps the platform reader compatible with sources not upgraded yet. */
+export const REPLICATION_TARGET_METADATA = `
+  to_jsonb(_ontology_replication_targets)->'identities' AS identities,
+  COALESCE(to_jsonb(_ontology_replication_targets)->'lineage', 'null'::jsonb) AS lineage,
+  COALESCE((to_jsonb(_ontology_replication_targets)->>'scans_complete')::boolean, true) AS scans_complete,
+  to_jsonb(_ontology_replication_targets)->'backfill_sources' AS backfill_sources,
+  (SELECT version FROM _ontology_replication WHERE id) AS schema_version`;
+/** 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()
+  )`,
+    `DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint
+      WHERE conrelid = '_ontology_replication'::regclass AND conname = '_ontology_replication_protocol_floor') THEN
+      ALTER TABLE _ontology_replication ADD CONSTRAINT _ontology_replication_protocol_floor
+        CHECK (version >= 4) NOT VALID;
+    END IF;
+  END $$`,
+    `DO $$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_constraint
+      WHERE conrelid = '_ontology_replication'::regclass AND conname = '_ontology_replication_schema_floor_v5') THEN
+      ALTER TABLE _ontology_replication ADD CONSTRAINT _ontology_replication_schema_floor_v5
+        CHECK (version >= 5) NOT VALID;
+    END IF;
+  END $$`,
+    `CREATE SEQUENCE IF NOT EXISTS _ontology_replication_revision AS bigint CACHE 1`,
+    `SELECT setval('_ontology_replication_revision', GREATEST(
+    (SELECT revision FROM _ontology_replication WHERE id),
+    (SELECT last_value FROM _ontology_replication_revision), 1), true)
+    WHERE (SELECT version FROM _ontology_replication WHERE id) < 4`,
+    `ALTER TABLE _ontology_replication_targets
+    ADD COLUMN IF NOT EXISTS protocol integer NOT NULL DEFAULT 3,
+    ADD COLUMN IF NOT EXISTS baseline_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS baseline_cursor jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN IF NOT EXISTS initial_revision bigint,
+    ADD COLUMN IF NOT EXISTS backfill_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS backfill_cursor jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN IF NOT EXISTS backfill_revision bigint,
+    ADD COLUMN IF NOT EXISTS verified_count bigint NOT NULL DEFAULT 0,
+    ADD COLUMN IF NOT EXISTS replay_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS replay_cursor uuid,
+    ADD COLUMN IF NOT EXISTS fills jsonb NOT NULL DEFAULT '{}'::jsonb,
+    ADD COLUMN IF NOT EXISTS lineage jsonb,
+    ADD COLUMN IF NOT EXISTS scans_complete boolean NOT NULL DEFAULT true,
+    ADD COLUMN IF NOT EXISTS backfill_sources jsonb`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_scans (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
+    entity_id text NOT NULL, record_kind text NOT NULL,
+    initial boolean NOT NULL DEFAULT false, required boolean NOT NULL DEFAULT true,
+    complete boolean NOT NULL DEFAULT false, cursor text NOT NULL DEFAULT ''
+  )`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS _ontology_replication_scan_pending
+    ON _ontology_replication_scans (generation, entity_id, record_kind) WHERE NOT complete`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_delivery (
+    generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
+    event_id uuid NOT NULL, history_table text, revision bigint NOT NULL,
+    is_baseline boolean NOT NULL DEFAULT false,
+    accepted_at timestamptz, verified_at timestamptz,
+    next_verify_at timestamptz NOT NULL DEFAULT now(), last_checked_at timestamptz,
+    PRIMARY KEY (generation, event_id)
+  )`,
+    `ALTER TABLE _ontology_replication_delivery
+    ADD COLUMN IF NOT EXISTS payload jsonb,
+    ADD COLUMN IF NOT EXISTS scan_id uuid REFERENCES _ontology_replication_scans(id)`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_scan_pending
+    ON _ontology_replication_delivery (generation, scan_id) WHERE accepted_at IS NULL AND scan_id IS NOT NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_pending ON _ontology_replication_delivery
+    (generation, revision, event_id) WHERE accepted_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_verify ON _ontology_replication_delivery
+    (generation, next_verify_at, event_id) WHERE accepted_at IS NOT NULL AND verified_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_unverified ON _ontology_replication_delivery
+    (generation, event_id) WHERE verified_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS _ontology_delivery_initial ON _ontology_replication_delivery
+    (generation, revision, event_id) WHERE verified_at IS NULL`,
+    `UPDATE _ontology_replication_targets SET backfill_complete = false,
+     backfill_revision = (SELECT revision FROM _ontology_replication WHERE id),
+     initial_revision = (SELECT revision FROM _ontology_replication WHERE id)
+     WHERE protocol = 3 AND backfill_revision IS NULL`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_baselines (
+    generation uuid NOT NULL REFERENCES _ontology_replication_targets(generation),
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(), event jsonb NOT NULL
+  )`,
+    `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)
+  )`,
+    ...SHADOW_REPLICATION_DDL,
+    SHADOW_CONTROL_JOBS_DDL,
+    SHADOW_SOURCE_REPLACEMENTS_DDL,
+    `CREATE OR REPLACE FUNCTION _ontology_replication_guard() RETURNS trigger LANGUAGE plpgsql AS $$
+  BEGIN
+    IF (SELECT enabled FROM _ontology_replication WHERE id) AND
+       COALESCE(current_setting('segmentstream.writer', true), '') NOT IN ('1', '2') THEN
+      RAISE EXCEPTION 'replication_writer_incompatible' USING ERRCODE='55000';
+    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, previous) {
+    return manifest.entities
+        .filter((e) => e.source === undefined && !e.builtIn)
+        .flatMap((entity) => {
+        const old = previous?.entities.find((item) => item.id === entity.id);
+        const compatible = {
+            ...entity,
+            properties: [
+                ...entity.properties,
+                ...(old?.properties ?? []).filter((property) => !entity.properties.some((item) => item.name === property.name || item.renamedFrom === property.name)),
+            ],
+        };
+        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;
+              event_revision bigint; record_key text; record_kind text := 'entity';
+              is_deleted boolean := NEW.kind = 'delete';
+      BEGIN
+        SELECT * INTO state FROM _ontology_replication WHERE id;
+        policy := state.selection->${ql(entity.id)};
+        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(compatible, "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;
+        event_revision := nextval('_ontology_replication_revision');
+        NEW.replication := jsonb_build_object('source_id', state.source_id::text,
+          'entity_id', ${ql(entity.id)}, 'record_key', record_key, 'record_kind', record_kind,
+          'revision', event_revision::text, 'generation', state.active_generation::text, 'deleted', is_deleted,
+          'schema_hash', ${ql(manifest.hash)}, 'payload', snapshot::text);
+        IF state.version >= 6 THEN
+          INSERT INTO _ontology_replication_delivery (generation, event_id, history_table, revision, payload_bytes)
+          SELECT t.generation, NEW.id, TG_TABLE_NAME, event_revision, octet_length(NEW.replication::text)
+          FROM _ontology_replication_targets t
+          WHERE t.capturing AND t.source_id = state.source_id
+            AND (t.capture_scopes IS NULL OR t.capture_scopes @>
+              jsonb_build_array(jsonb_build_object('entityId',${ql(entity.id)},'kind',record_kind)));
+        ELSE
+          INSERT INTO _ontology_replication_delivery (generation, event_id, history_table, revision)
+            VALUES (state.active_generation, NEW.id, TG_TABLE_NAME, event_revision);
+        END IF;
+        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/shadow-schema.d.ts

@@ -0,0 +1,4 @@
+/** Source-side checkpoints commit with capture. Provider operations are always outside transactions. */
+export declare const SHADOW_REPLICATION_DDL: string[];
+export declare const SHADOW_CONTROL_JOBS_DDL = "CREATE TABLE IF NOT EXISTS _ontology_replication_control_jobs (\n  logical_id text PRIMARY KEY, configuration_hash text NOT NULL, attempt integer NOT NULL DEFAULT 0,\n  failure text, updated_at timestamptz NOT NULL DEFAULT now()\n)";
+export declare const SHADOW_SOURCE_REPLACEMENTS_DDL = "CREATE TABLE IF NOT EXISTS _ontology_replication_source_replacements (\n  source_id uuid PRIMARY KEY, operation_id uuid NOT NULL UNIQUE, expected jsonb NOT NULL, proof jsonb,\n  attempts jsonb NOT NULL DEFAULT '[]'::jsonb,\n  state text NOT NULL CHECK(state IN ('pending','completed')), created_at timestamptz NOT NULL DEFAULT now()\n)";

package/dist/replication/shadow-schema.js

@@ -0,0 +1,61 @@
+/** Source-side checkpoints commit with capture. Provider operations are always outside transactions. */
+export const SHADOW_REPLICATION_DDL = [
+    `DO $$ BEGIN
+    IF NOT EXISTS(SELECT 1 FROM pg_constraint WHERE conrelid='_ontology_replication'::regclass
+      AND conname='_ontology_replication_schema_floor_v6') THEN
+      ALTER TABLE _ontology_replication ADD CONSTRAINT _ontology_replication_schema_floor_v6
+        CHECK(version>=6) NOT VALID;
+    END IF;
+  END $$`,
+    `ALTER TABLE _ontology_replication ADD COLUMN IF NOT EXISTS serving_epoch uuid`,
+    `ALTER TABLE _ontology_replication
+    ADD COLUMN IF NOT EXISTS requested_manifest_hash text,
+    ADD COLUMN IF NOT EXISTS destination_repair_pending boolean NOT NULL DEFAULT false,
+    ADD COLUMN IF NOT EXISTS destination_rebuilding boolean NOT NULL DEFAULT false,
+    ADD COLUMN IF NOT EXISTS requested_manifest_until timestamptz`,
+    `ALTER TABLE _ontology_replication_targets
+    ADD COLUMN IF NOT EXISTS identities jsonb,
+    ADD COLUMN IF NOT EXISTS capturing boolean NOT NULL DEFAULT false,
+    ADD COLUMN IF NOT EXISTS capture_bindings jsonb,
+    ADD COLUMN IF NOT EXISTS capture_versions jsonb,
+    ADD COLUMN IF NOT EXISTS capture_scopes jsonb`,
+    `CREATE SEQUENCE IF NOT EXISTS _ontology_replication_cutover_fence AS bigint CACHE 1`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_epochs (
+    id uuid PRIMARY KEY REFERENCES _ontology_replication_targets(generation),
+    source_id uuid NOT NULL, desired_hash text NOT NULL,
+    target jsonb NOT NULL, routes jsonb NOT NULL,
+    state text NOT NULL CHECK (state IN ('candidate','serving','retired','cancelled')),
+    predecessor uuid, created_at timestamptz NOT NULL DEFAULT now(), retired_at timestamptz,
+    owner uuid, owner_until timestamptz,
+    boundary bigint, catchup_boundary bigint, token uuid, fence bigint, handoff_until timestamptz, operation_id uuid,
+    installed boolean NOT NULL DEFAULT false, cancel_requested boolean NOT NULL DEFAULT false,
+    policy_installed boolean NOT NULL DEFAULT false
+  )`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS _ontology_replication_one_candidate
+    ON _ontology_replication_epochs ((true)) WHERE state = 'candidate'`,
+    `CREATE TABLE IF NOT EXISTS _ontology_replication_segments (
+    id uuid PRIMARY KEY, epoch uuid NOT NULL REFERENCES _ontology_replication_epochs(id),
+    generation uuid NOT NULL, source_id uuid NOT NULL, through_revision bigint NOT NULL,
+    events jsonb NOT NULL, event_ids jsonb NOT NULL, digest text NOT NULL,
+    object_uri text NOT NULL, job_id text NOT NULL, attempt integer NOT NULL DEFAULT 0,
+    state text NOT NULL DEFAULT 'pending' CHECK (state IN ('pending','committed','failed')),
+    failure jsonb, retry_after timestamptz NOT NULL DEFAULT now(),
+    created_at timestamptz NOT NULL DEFAULT now(), committed_at timestamptz
+  )`,
+    `ALTER TABLE _ontology_replication_delivery
+    ADD COLUMN IF NOT EXISTS committed_at timestamptz,
+    ADD COLUMN IF NOT EXISTS suppressed_at timestamptz,
+    ADD COLUMN IF NOT EXISTS payload_bytes integer NOT NULL DEFAULT 401000,
+    ADD COLUMN IF NOT EXISTS segment_id uuid REFERENCES _ontology_replication_segments(id)`,
+    `CREATE INDEX IF NOT EXISTS _ontology_replication_uncommitted
+    ON _ontology_replication_delivery (generation,revision,event_id) WHERE committed_at IS NULL`,
+];
+export const SHADOW_CONTROL_JOBS_DDL = `CREATE TABLE IF NOT EXISTS _ontology_replication_control_jobs (
+  logical_id text PRIMARY KEY, configuration_hash text NOT NULL, attempt integer NOT NULL DEFAULT 0,
+  failure text, updated_at timestamptz NOT NULL DEFAULT now()
+)`;
+export const SHADOW_SOURCE_REPLACEMENTS_DDL = `CREATE TABLE IF NOT EXISTS _ontology_replication_source_replacements (
+  source_id uuid PRIMARY KEY, operation_id uuid NOT NULL UNIQUE, expected jsonb NOT NULL, proof jsonb,
+  attempts jsonb NOT NULL DEFAULT '[]'::jsonb,
+  state text NOT NULL CHECK(state IN ('pending','completed')), created_at timestamptz NOT NULL DEFAULT now()
+)`;

package/dist/replication/shadow.d.ts

@@ -0,0 +1,127 @@
+import { type ReplicationIdentities } from "./identities.js";
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { type OntologyManifest } from "../manifest.js";
+import type { ReplicationTarget } from "./baseline.js";
+import { ReplicationBaselineFailed } from "./baseline.js";
+import { type ReplicationScanScope } from "./scans.js";
+import type { ReplicationEvent, ReplicationSelection } from "./model.js";
+export declare const SHADOW_HANDOFF_MS = 30000;
+export declare const SHADOW_RETENTION_MS: number;
+export declare const SHADOW_QUERY_LIFETIME_MS: number;
+export interface ShadowRoute extends ReplicationScanScope {
+    readonly target: ReplicationTarget;
+}
+export interface ShadowEpoch {
+    readonly id: string;
+    readonly source_id: string;
+    readonly desired_hash: string;
+    readonly target: ReplicationTarget;
+    readonly routes: readonly ShadowRoute[];
+    readonly state: "candidate" | "serving" | "retired" | "cancelled";
+    readonly predecessor: string | null;
+    readonly boundary: string | null;
+    readonly catchup_boundary?: string | null;
+    readonly token: string | null;
+    readonly fence: string | null;
+    readonly handoff_until: string | null;
+    readonly operation_id: string | null;
+    readonly installed: boolean;
+    readonly cancel_requested?: boolean;
+}
+export interface ShadowSegment {
+    readonly id: string;
+    readonly epoch: string;
+    readonly generation: string;
+    readonly source_id: string;
+    readonly through_revision: string;
+    readonly events: readonly ReplicationEvent[];
+    readonly event_ids: readonly string[];
+    readonly digest: string;
+    readonly object_uri: string;
+    readonly job_id: string;
+    readonly attempt: number;
+    readonly retry_after: string;
+    readonly state: "pending" | "committed" | "failed";
+}
+/**
+ * Every route carries a full target, and most routes repeat the epoch target's manifest and
+ * projection. One copy per scope grows with entities times manifest size, past what a single
+ * PostgreSQL message may carry, so a stored route names the keys it takes from its epoch target.
+ */
+export declare function compactShadowRoutes(routes: readonly ShadowRoute[], target: ReplicationTarget): readonly unknown[];
+/** Restores the keys a stored route took from its epoch target. Full stored routes pass through. */
+export declare function expandShadowRoutes(routes: readonly unknown[], target: ReplicationTarget): readonly ShadowRoute[];
+export declare const shadowEpoch: (sql: SqlClient.SqlClient, id: string) => Effect.Effect<ShadowEpoch | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const servingShadowEpoch: (sql: SqlClient.SqlClient) => Effect.Effect<ShadowEpoch | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const candidateShadowEpoch: (sql: SqlClient.SqlClient) => Effect.Effect<ShadowEpoch | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const shadowProjectionHash: (target: ReplicationTarget) => string;
+/** Called under exclusive lifecycle admission; no provider I/O is permitted here. */
+export declare const adoptShadowServing: (sql: SqlClient.SqlClient, target: ReplicationTarget) => Effect.Effect<ShadowEpoch, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Capture bindings name wire fields, not public columns. Renames never rewrite historical JSON. */
+export declare const enableShadowCapture: (sql: SqlClient.SqlClient, target: ReplicationTarget, scopes: readonly ReplicationScanScope[]) => Effect.Effect<readonly object[], import("effect/unstable/sql/SqlError").SqlError, never>;
+/**
+ * Immutable epochs may share unaffected generations. Only complete affected entity scopes get a
+ * fresh incarnation. Generation-zero snapshots cannot overwrite mutations in another incarnation.
+ */
+export declare const prepareShadowEpoch: (sql: SqlClient.SqlClient, input: {
+    readonly target: ReplicationTarget;
+    readonly affected: readonly ReplicationScanScope[];
+    readonly predecessor?: ShadowEpoch;
+    readonly force?: boolean;
+}) => Effect.Effect<ShadowEpoch, import("effect/unstable/sql/SqlError").SqlError | ReplicationBaselineFailed, never>;
+/** Remap destination wire bindings before installing the next source snapshot trigger. */
+export declare const migrateShadowCapture: (sql: SqlClient.SqlClient, current: OntologyManifest, next: OntologyManifest, selection: readonly ReplicationSelection[], identities: ReplicationIdentities) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Every pass has a source-side lease as well as the product lease; stale completions are rejected. */
+export declare const claimShadowEpoch: (sql: SqlClient.SqlClient, id: string, owner: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const releaseShadowEpoch: (sql: SqlClient.SqlClient, id: string, owner: string) => import("effect/unstable/sql/Statement").Statement<object>;
+/** A closed source boundary is selected only after all admitted writers and scans have drained. */
+export declare const beginShadowHandoff: (sql: SqlClient.SqlClient, id: string, owner: string, minimumFence?: string) => Effect.Effect<ShadowEpoch | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Destination invalidation must have succeeded (or switched) before this transaction runs. */
+export declare const abandonShadowHandoff: (sql: SqlClient.SqlClient, epoch: ShadowEpoch) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const completeShadowEpoch: (sql: SqlClient.SqlClient, epoch: ShadowEpoch) => Effect.Effect<undefined, import("effect/unstable/sql/SqlError").SqlError | ReplicationBaselineFailed, never>;
+export declare const pendingShadowSegment: (sql: SqlClient.SqlClient, epoch: string) => Effect.Effect<ShadowSegment | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Source events, immutable object names and job identities commit before the first upload. */
+export declare const journalShadowSegment: (sql: SqlClient.SqlClient, input: {
+    readonly epoch: ShadowEpoch;
+    readonly owner: string;
+    readonly projectId: string;
+    readonly events: readonly {
+        readonly historyId: string;
+        readonly event: ReplicationEvent;
+    }[];
+}) => Effect.Effect<ShadowSegment | undefined, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const finishShadowSegment: (sql: SqlClient.SqlClient, segment: ShadowSegment, owner: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const retryShadowSegment: (sql: SqlClient.SqlClient, segment: ShadowSegment, owner: string, failure: unknown) => import("effect/unstable/sql/Statement").Statement<object>;
+/** Recheck references under the lifecycle fence. Audit journals and immutable epoch routes survive. */
+export declare const retireShadowCapture: (sql: SqlClient.SqlClient) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Filter by the destination's immutable wire schema, including missing keys and explicit nulls. */
+export declare function shadowWireEvent(event: ReplicationEvent, bindings: Record<string, Record<string, string>>, selection: readonly ReplicationSelection[]): ReplicationEvent;
+/** Capture is the union needed by live destinations; export shaping remains destination-specific. */
+export declare const refreshShadowCapturePolicy: (sql: SqlClient.SqlClient) => import("effect/unstable/sql/Statement").Statement<object>;
+/** Only generations retired for seven days qualify; creation time is never a query-safety fence. */
+export declare const retiredShadowGenerations: (sql: SqlClient.SqlClient) => Effect.Effect<readonly {
+    generation: string;
+    source_id: string;
+}[], import("effect/unstable/sql/SqlError").SqlError, never>;
+/** The destination has already fenced and deselected an observably destroyed event table. */
+export declare const replaceDestroyedShadowDestination: (sql: SqlClient.SqlClient, input: {
+    readonly target: ReplicationTarget;
+    readonly fence: string;
+}) => Effect.Effect<ShadowEpoch, import("effect/unstable/sql/SqlError").SqlError | ReplicationBaselineFailed, never>;
+export declare const installShadowEpoch: (sql: SqlClient.SqlClient, id: string, owner: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Strict warehouse job completion, not Pub/Sub acceptance, is the publication prerequisite. */
+export declare const shadowPublicationReady: (sql: SqlClient.SqlClient, epoch: ShadowEpoch, owner: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const unfinishedRetiredSegments: (sql: SqlClient.SqlClient) => import("effect/unstable/sql/Statement").Statement<ShadowSegment>;
+export declare const settleRetiredSegment: (sql: SqlClient.SqlClient, segment: ShadowSegment, committed: boolean) => import("effect/unstable/sql/Statement").Statement<object>;
+/** Restriction-only refresh is independent of build leases and cannot confer publication eligibility. */
+export declare const shadowPolicyViewOwnership: (sql: SqlClient.SqlClient, generation: string, source: string, exclusions: unknown) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+export declare const recordShadowPolicyViews: (sql: SqlClient.SqlClient, generation: string, source: string, exclusions: unknown) => import("effect/unstable/sql/Statement").Statement<object>;
+/** Used after reading a destination view's etag, before its conditional DDL update. */
+export declare const shadowViewOwnership: (sql: SqlClient.SqlClient, id: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** A finite background goal prevents continuous writes from moving initialization's finish line. */
+export declare const closeShadowCatchup: (sql: SqlClient.SqlClient, id: string, owner: string) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Persist cancellation before returning a retryable migration decision; provider fencing follows. */
+export declare const requestShadowSupersession: (sql: SqlClient.SqlClient, manifestHash: string) => Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** The destination token has been invalidated, or no token ever existed. */
+export declare const cancelShadowEpoch: (sql: SqlClient.SqlClient, epoch: ShadowEpoch) => Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;