@segmentstream-cloud/ontology 0.10.0 → 0.12.0

package/dist/migrate/storage.d.ts

@@ -151,6 +151,18 @@ export declare const USER_ROLES_TABLE = "_user_roles";
  * secret only as a salted PBKDF2 hash.
  */
 export declare const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export declare const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export declare const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export declare const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export declare const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export declare const OAUTH_TABLES: ReadonlyArray<string>;
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export declare const OAUTH_TABLES_DDL: ReadonlyArray<string>;
 /**
  * The runtime's own tables beside the catalog. They are created with it, after the entity tables
  * because they refer to the built-in user table, and every statement is idempotent.

package/dist/migrate/storage.js

@@ -433,6 +433,87 @@ export const USER_ROLES_TABLE = "_user_roles";
  * secret only as a salted PBKDF2 hash.
  */
 export const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export const OAUTH_TABLES = [
+    OAUTH_CLIENTS_TABLE,
+    OAUTH_REQUESTS_TABLE,
+    OAUTH_GRANTS_TABLE,
+    OAUTH_TOKENS_TABLE,
+];
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export const OAUTH_TABLES_DDL = [
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "name" text NOT NULL,`,
+        `  "redirect_uris" jsonb NOT NULL,`,
+        `  "auth_method" text NOT NULL,`,
+        `  "secret_hash" text,`,
+        `  "client_uri" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_CLIENTS_TABLE}_pkey" PRIMARY KEY ("id")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_REQUESTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "redirect_uri" text NOT NULL,`,
+        `  "state" text,`,
+        `  "code_challenge" text NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_GRANTS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_GRANTS_TABLE}_user_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("user_id")`,
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_TOKENS_TABLE)} (`,
+        `  "hash" text NOT NULL,`,
+        `  "grant_id" uuid NOT NULL,`,
+        `  "kind" text NOT NULL,`,
+        `  "redirect_uri" text,`,
+        `  "code_challenge" text,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "used_at" timestamptz,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_pkey" PRIMARY KEY ("hash"),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_kind_check" CHECK ("kind" IN ('code', 'access', 'refresh')),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_grant_id_fkey" FOREIGN KEY ("grant_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_TOKENS_TABLE}_grant_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_TOKENS_TABLE)} ("grant_id")`,
+];
 /**
  * The runtime's own tables beside the catalog. They are created with it, after the entity tables
  * because they refer to the built-in user table, and every statement is idempotent.
@@ -464,6 +545,7 @@ export const RUNTIME_TABLES_DDL = [
         `)`,
     ].join("\n"),
     `CREATE INDEX IF NOT EXISTS "${API_KEYS_TABLE}_user_id_idx" ON ${quoteIdentifier(API_KEYS_TABLE)} ("user_id")`,
+    ...OAUTH_TABLES_DDL,
 ];
 export function columnDefinition(column) {
     const parts = [quoteIdentifier(column.name), column.type];

package/dist/names.d.ts

@@ -21,7 +21,15 @@ export declare const HISTORY_SUFFIX = "_history";
 /** The combinators of the query language, which take the place of field names in a `where`. */
 export declare const RESERVED_MEMBER_NAMES: readonly ["and", "or", "not"];
 /** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
-export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "docs", "mcp", "me"];
+export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "docs", "mcp", "me", "oauth"];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export declare const MCP_READ_TOOLS: readonly ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export declare const MCP_GLOBAL_TOOLS: readonly ["describe", "me"];
+/** The longest tool name that Claude and OpenAI accept. */
+export declare const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export declare function mcpToolName(entity: string, operation: string): string;
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export declare const RESERVED_RELATIONSHIP_NAMES: readonly ["history"];
 export declare function isSystemProperty(name: string): boolean;

package/dist/names.js

@@ -57,7 +57,18 @@ export const RESERVED_ENTITY_NAMES = [
     "docs",
     "mcp",
     "me",
+    "oauth",
 ];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export const MCP_READ_TOOLS = ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export const MCP_GLOBAL_TOOLS = ["describe", "me"];
+/** The longest tool name that Claude and OpenAI accept. */
+export const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export function mcpToolName(entity, operation) {
+    return `${entity}_${operation}`;
+}
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export const RESERVED_RELATIONSHIP_NAMES = ["history"];
 export function isSystemProperty(name) {

package/dist/nitro.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The paths the ontology service answers, for the workspace's `ontology/nitro.config.ts`. They come
+ * from the SDK, so a path the service adds arrives with an upgrade and the config stays as it is.
+ * This entry imports nothing: Nitro loads it while it builds.
+ */
+export declare const ONTOLOGY_SERVICE_PATHS: readonly ["/api/ontology", "/api/ontology/**", "/mcp", "/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-authorization-server"];
+/** A Nitro route to the service's handler, loaded on its first request. */
+export interface OntologyRoute {
+    readonly handler: string;
+    readonly lazy: true;
+}
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export declare function ontologyRoutes(handler: string): Record<string, OntologyRoute>;

package/dist/nitro.js

@@ -0,0 +1,18 @@
+/**
+ * The paths the ontology service answers, for the workspace's `ontology/nitro.config.ts`. They come
+ * from the SDK, so a path the service adds arrives with an upgrade and the config stays as it is.
+ * This entry imports nothing: Nitro loads it while it builds.
+ */
+export const ONTOLOGY_SERVICE_PATHS = [
+    "/api/ontology",
+    "/api/ontology/**",
+    "/mcp",
+    // The MCP server's OAuth metadata, on the app's origin.
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-protected-resource/mcp",
+    "/.well-known/oauth-authorization-server",
+];
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export function ontologyRoutes(handler) {
+    return Object.fromEntries(ONTOLOGY_SERVICE_PATHS.map((path) => [path, { handler, lazy: true }]));
+}

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()`,
+                ];
+            }),
+        ];
+    });
+}