@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/dist/relationship.d.ts

@@ -12,19 +12,42 @@ export type OnDelete = (typeof ON_DELETE)[number];
 export type LazyEntity = Function;
 /** Where a relationship points: an entity, a thunk returning one, or an entity name. */
 export type EntityTarget = AnyEntity | LazyEntity | string;
+/**
+ * The name of the entity a target points at, as far as its type shows: the given name, or the
+ * entity's name. A thunk is a `Function`, whose `name` is any string, so its target stays unknown.
+ */
+type TargetName<Target> = Target extends string ? Target : Target extends {
+    readonly name: infer Name extends string;
+} ? Name : string;
 /** Names a relationship in both directions, for example `["is owned by", "owns"]`. */
 export type Phrase = readonly [forward: string, inverse: string];
-/** A many-to-one relationship, declared on the side that holds the key (`owner_id` on `lead`). */
-export interface OneRelationship<Optional extends boolean = boolean> {
+/**
+ * A many-to-one relationship. Between stored entities it is declared on the side that holds the key
+ * (`owner_id` on `lead`). When either end is warehouse-backed it is value-matched: it declares `on`,
+ * one pair of an own property and a target property, and has no key column, delete rule or
+ * optionality of its own.
+ */
+export interface OneRelationship<Optional extends boolean = boolean, Matched extends boolean = boolean, Target extends string = string> {
     readonly [RelationshipTypeId]: typeof RelationshipTypeId;
     readonly cardinality: "one";
     readonly on?: Readonly<Record<string, string>>;
     readonly target: EntityTarget;
     readonly optional: Optional;
     readonly inverse: string;
-    readonly onDelete: OnDelete;
+    /** As declared. A stored → stored relationship without one restricts deletes. */
+    readonly onDelete?: OnDelete;
     readonly phrase?: Phrase;
     readonly description: string;
+    /**
+     * Exists only in the type: whether `on` was given, which makes the relationship value-matched.
+     * Value-matched relationships add no `<relationship>Id` to records and inputs.
+     */
+    readonly "~ontology.matched": Matched;
+    /**
+     * Exists only in the type: the target entity's name when the target was given as an entity or a
+     * name, and `string` for a thunk. Typed aggregate clients resolve relationship paths with it.
+     */
+    readonly "~ontology.target": Target;
 }
 /** A plain many-to-many relationship, stored in a hidden join table. It never carries properties. */
 export interface ManyRelationship {
@@ -38,11 +61,16 @@ export interface ManyRelationship {
 }
 export type AnyRelationship = OneRelationship | ManyRelationship;
 export interface OneOptions {
+    /**
+     * The property pair a relationship with a warehouse-backed end matches on: `{ ownProperty:
+     * targetProperty }`. Required for those relationships and refused between stored entities.
+     */
     readonly on?: Readonly<Record<string, string>>;
-    /** The record may point at nothing: the key column is nullable. */
+    /** The record may point at nothing: the key column is nullable. Stored → stored only. */
     readonly optional?: boolean;
     /** The name of the relationship as seen from the target, for example `ownedLeads` on `user`. */
     readonly inverse: string;
+    /** What deleting the target does to this record, `restrict` by default. Stored → stored only. */
     readonly onDelete?: OnDelete;
     readonly phrase?: Phrase;
     readonly description: string;
@@ -57,7 +85,10 @@ export interface ManyOptions {
 type IsOptional<O> = O extends {
     readonly optional: true;
 } ? true : false;
-declare function one<const O extends OneOptions>(target: EntityTarget, options: O): OneRelationship<IsOptional<O>>;
+type IsMatched<O> = O extends {
+    readonly on: Readonly<Record<string, string>>;
+} ? true : false;
+declare function one<const Target extends EntityTarget, const O extends OneOptions>(target: Target, options: O): OneRelationship<IsOptional<O>, IsMatched<O>, TargetName<Target>>;
 declare function many(target: EntityTarget, options: ManyOptions): ManyRelationship;
 /** Relationship constructors. */
 export declare const rel: {

package/dist/relationship.js

@@ -1,17 +1,19 @@
 export const RelationshipTypeId = Symbol.for("@segmentstream-cloud/ontology/Relationship");
 export const ON_DELETE = ["setNull", "cascade", "restrict"];
 function one(target, options) {
-    return {
+    // `onDelete` stays absent unless declared, so that check can refuse it where it means nothing.
+    const relationship = {
         [RelationshipTypeId]: RelationshipTypeId,
         cardinality: "one",
         target,
-        optional: (options.optional === true),
+        optional: options.optional === true,
         inverse: options.inverse,
-        onDelete: options.onDelete ?? "restrict",
+        ...(options.onDelete !== undefined ? { onDelete: options.onDelete } : {}),
         ...(options.on !== undefined ? { on: options.on } : {}),
         ...(options.phrase !== undefined ? { phrase: options.phrase } : {}),
         description: options.description,
     };
+    return relationship;
 }
 function many(target, options) {
     return {

package/dist/render.d.ts

@@ -1,8 +1,9 @@
-import type { ActionManifest, OntologyManifest } from "./manifest.js";
+import type { ActionManifest, EntityManifest, OntologyManifest } from "./manifest.js";
 export interface RenderOptions {
     /**
-     * The permissions of the reader. Only the actions these permissions may run are listed. Without
-     * it, every action is listed with the permission it requires and the roles that grant it.
+     * The permissions of the reader. Only the actions these permissions may run are listed, and only
+     * the measures and routes of entities they may read. Without it, every action is listed with the
+     * permission it requires and the roles that grant it, and every measure and route.
      */
     readonly as?: ReadonlyArray<string>;
 }
@@ -16,3 +17,46 @@ export declare function actionPermission(entity: string, action: ActionManifest)
  * the console, the CLI and the service describe the same ontology.
  */
 export declare function renderCatalog(manifest: OntologyManifest, options?: RenderOptions): string;
+/**
+ * The catalog as `describe` answers a reader: {@link renderCatalog} with the reader's permissions,
+ * or everything without them.
+ */
+export declare function describeCatalog(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
+type MeasureManifest = NonNullable<EntityManifest["measures"]>[number];
+/** A measure as aggregates name it: `<entity>.<measure>`. */
+export interface NamedMeasure {
+    readonly name: string;
+    readonly entity: EntityManifest;
+    readonly measure: MeasureManifest;
+}
+/**
+ * An entity a measure entity reaches, and the shortest routes there the reader may follow:
+ * `product.region`. `ambiguous` when the resolver finds several shortest routes, readable or not,
+ * so a request must write the route.
+ */
+export interface Reach {
+    readonly target: string;
+    readonly routes: ReadonlyArray<string>;
+    readonly ambiguous: boolean;
+}
+/** The rule every surface repeats (docs/ontology-aggregates-spec.md, "Three ways to ask"). */
+export declare const RECORDS_OR_AGGREGATES = "look at or change records through find and actions; count, sum or compare through aggregate";
+/**
+ * Every measure of the entities the reader may read, warehouse-backed and stored alike, in
+ * declaration order. Without permissions, every measure.
+ */
+export declare function measuresFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<NamedMeasure>;
+/**
+ * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
+ * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
+ * not read is left out, and so is any route through an entity they may not read, which the service
+ * would refuse. A target keeps `ambiguous` from before that filter, so a route is never shown as the
+ * only one when the resolver would ask for it to be written.
+ */
+export declare function reachesOf(manifest: OntologyManifest, from: string, permissions?: ReadonlyArray<string>): ReadonlyArray<Reach>;
+/**
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
+ * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ */
+export declare function renderAggregates(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
+export {};

package/dist/render.js

@@ -1,3 +1,4 @@
+import { shortestRoutesFrom } from "./aggregate-routes.js";
 import { isAllowed, permissionOf, READ_VERB, rolesGranting } from "./permissions.js";
 import { REFERENCE_ANNOTATION } from "./property.js";
 /** What an action of the manifest requires; version 1 manifests leave it implicit. */
@@ -24,11 +25,14 @@ function withDescription(head, description) {
 function formatValue(value) {
     return typeof value === "string" ? value : JSON.stringify(value);
 }
-function propertyLines(property) {
+/** A warehouse-backed property's `unique` is an assertion the platform does not enforce. */
+function propertyLines(input) {
+    const { property, warehouseBacked } = input;
+    const unique = warehouseBacked ? "unique, not enforced" : "unique";
     const traits = [
         property.type,
         ...(property.optional ? ["optional"] : []),
-        ...(property.unique ? ["unique"] : []),
+        ...(property.unique ? [unique] : []),
         ...(property.default !== undefined ? [`default ${formatValue(property.default)}`] : []),
         ...(property.min !== undefined ? [`min ${property.min}`] : []),
         ...(property.max !== undefined ? [`max ${property.max}`] : []),
@@ -43,18 +47,40 @@ function propertyLines(property) {
         ...options.map((option) => `${INDENT}${option}`),
     ];
 }
+/**
+ * The inverse of a relationship as its target reads it. A value-matched inverse, one with `on`, has
+ * no route: a warehouse-backed source is read through aggregates, a stored one by its `on` property.
+ */
+function inverseLine(source, relationship) {
+    const { on, phrase, inverse } = relationship;
+    if (on === undefined) {
+        return `${phrase[1]} many ${source.plural} (${inverse})`;
+    }
+    if (source.source !== undefined) {
+        return `${phrase[1]} ${source.plural} (${inverse}), through aggregates`;
+    }
+    return `${phrase[1]} ${source.plural} (${inverse}), matched on ${on.property}`;
+}
 function relationshipLines(entity, entities, all) {
     const declared = entity.relationships.map((relationship) => {
+        const { on, phrase, name } = relationship;
         const target = entities.get(relationship.to);
+        const label = target?.label ?? relationship.to;
         const optional = relationship.optional === true ? ", optional" : "";
-        const head = relationship.cardinality === "one"
-            ? `${relationship.phrase[0]} one ${target?.label ?? relationship.to} (${relationship.name})${optional}`
-            : `${relationship.phrase[0]} many ${target?.plural ?? relationship.to} (${relationship.name})`;
+        let head = `${phrase[0]} one ${label} (${name})${optional}`;
+        if (relationship.cardinality === "many") {
+            head = `${phrase[0]} many ${target?.plural ?? relationship.to} (${name})`;
+        }
+        else if (on !== undefined) {
+            // Value-matched: nothing promises a match, and the key is the declared property pair.
+            const key = `${on.property} = ${label}.${on.targetProperty}`;
+            head = `${phrase[0]} at most one ${label} (${name}), matched on ${key}`;
+        }
         return withDescription(head, relationship.description);
     });
     const inverses = all.flatMap((source) => source.relationships
         .filter((relationship) => relationship.to === entity.name)
-        .map((relationship) => `${relationship.phrase[1]} many ${source.plural} (${relationship.inverse})`));
+        .map((relationship) => inverseLine(source, relationship)));
     return [...declared, ...inverses];
 }
 function inputType(schema) {
@@ -143,10 +169,8 @@ function renderEntity(entity, manifest, entities, options) {
         ...(entity.source
             ? [`${INDENT}Source: ${entity.source.asset}; key: ${entity.source.key.join(", ")}.`]
             : []),
-        ...section("Properties", entity.properties.flatMap(propertyLines)),
-        ...(entity.source
-            ? section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measure.description} (${measure.unit}).`))
-            : []),
+        ...section("Properties", entity.properties.flatMap((property) => propertyLines({ property, warehouseBacked: entity.source !== undefined }))),
+        ...section("Measures", (entity.measures ?? []).map((measure) => `${measure.name}: ${measure.description} (${measure.unit}).`)),
         ...section("Relationships", relationshipLines(entity, entities, manifest.entities)),
         ...section(reader === undefined ? "Actions" : "Actions you may run", actions.flatMap((action) => actionLines(action, reader === undefined
             ? requirement("Requires", actionPermission(entity.name, action), manifest.roles)
@@ -180,5 +204,87 @@ export function renderCatalog(manifest, options = {}) {
         options.as === undefined ||
         isAllowed(entity.permissions?.read ?? `${entity.name}:read`, { permissions: options.as }))
         .map((entity) => renderEntity(entity, manifest, entities, options));
-    return `${[...sections, renderRoles(manifest.roles)].join("\n\n")}\n`;
+    const aggregates = renderAggregates(manifest, options.as);
+    return `${[...sections, renderRoles(manifest.roles), ...(aggregates === "" ? [] : [aggregates])].join("\n\n")}\n`;
+}
+/**
+ * The catalog as `describe` answers a reader: {@link renderCatalog} with the reader's permissions,
+ * or everything without them.
+ */
+export function describeCatalog(manifest, permissions) {
+    return renderCatalog(manifest, permissions === undefined ? {} : { as: permissions });
+}
+/** The rule every surface repeats (docs/ontology-aggregates-spec.md, "Three ways to ask"). */
+export const RECORDS_OR_AGGREGATES = "look at or change records through find and actions; count, sum or compare through aggregate";
+/** Whether the reader may read the entity; without a reader, everything is described. */
+function readable(entity, permissions) {
+    return permissions === undefined || isAllowed(permissionOf(entity, READ_VERB), { permissions });
+}
+/**
+ * Every measure of the entities the reader may read, warehouse-backed and stored alike, in
+ * declaration order. Without permissions, every measure.
+ */
+export function measuresFor(manifest, permissions) {
+    return manifest.entities
+        .filter((entity) => readable(entity.name, permissions))
+        .flatMap((entity) => (entity.measures ?? []).map((measure) => ({
+        name: `${entity.name}.${measure.name}`,
+        entity,
+        measure,
+    })));
+}
+/**
+ * The entities one entity reaches, with the shortest routes to each: exactly the routes aggregate
+ * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
+ * not read is left out, and so is any route through an entity they may not read, which the service
+ * would refuse. A target keeps `ambiguous` from before that filter, so a route is never shown as the
+ * only one when the resolver would ask for it to be written.
+ */
+export function reachesOf(manifest, from, permissions) {
+    return [...shortestRoutesFrom(manifest, from)].flatMap(([target, routes]) => {
+        const followed = routes.filter((route) => route.entities.every((entity) => readable(entity, permissions)));
+        return followed.length === 0
+            ? []
+            : [
+                {
+                    target,
+                    routes: followed.map((route) => route.relationships.join(".")),
+                    ambiguous: routes.length > 1,
+                },
+            ];
+    });
+}
+/** `sales reaches product (product), region (product.region or listing.region; write the route).` */
+function reachLine(entity, reaches) {
+    const targets = reaches.map(({ target, routes, ambiguous }) => `${target} (${routes.join(" or ")}${ambiguous ? "; write the route" : ""})`);
+    return `${entity} reaches ${targets.join(", ")}.`;
+}
+/**
+ * The aggregate part of the catalog's prose: every measure the reader may read, model-wide, and
+ * per measure entity the entities it reaches. Empty when the reader may read no measure.
+ */
+export function renderAggregates(manifest, permissions) {
+    const measures = measuresFor(manifest, permissions);
+    if (measures.length === 0) {
+        return "";
+    }
+    const owners = [...new Set(measures.map(({ entity }) => entity.name))];
+    const reachLines = owners.flatMap((owner) => {
+        const reaches = reachesOf(manifest, owner, permissions);
+        return reaches.length === 0 ? [] : [reachLine(owner, reaches)];
+    });
+    const measureLines = measures.map(({ name, measure }) => `${name} (${measure.unit}): ${sentence(measure.description)}`);
+    return [
+        `Aggregates: ${RECORDS_OR_AGGREGATES} (POST /api/ontology/aggregate, or the aggregate tool).`,
+        `${INDENT}Measures, as <entity>.<measure>:`,
+        ...measureLines.map((line) => `${INDENT}${INDENT}${line}`),
+        ...(reachLines.length === 0
+            ? []
+            : [
+                `${INDENT}Group and filter by <entity>.<property>. Where a target says write the route, ` +
+                    "name it from the measure's entity: <entity>.<relationship>.<property>. Through " +
+                    "to-one relationships:",
+                ...reachLines.map((line) => `${INDENT}${INDENT}${line}`),
+            ]),
+    ].join("\n");
 }

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;
+};