@segmentstream-cloud/ontology 0.11.0 → 0.13.0

package/dist/manifest.js

@@ -10,9 +10,16 @@ import { DEFAULT_SIGN_IN_POLICY, isSignInPolicy, } from "./sign-in.js";
  * 2 replaced the actions' `allow` with `permission`, and added the roles' `permissions` and the
  * entities' `permissions`; those fields are optional when decoding, so version 1 manifests still read.
  * `signIn` came later within version 2 and is optional too, as are the actions' `connections` and the
- * top-level `connections`, which are written only when an action calls a connection.
+ * top-level `connections`, which are written only when an action calls a connection. Version 3 added
+ * warehouse sources and measures. Version 4 writes snake_case names on the wire. Version 5 lets
+ * relationships target warehouse-backed entities and warehouse-backed properties declare `unique`:
+ * a relationship with a warehouse-backed end carries `on` and omits `optional` and `onDelete`.
+ * Version 6 adds the `countDistinct` measure operator and lets stored entities declare `measures`,
+ * whose columns name the stored properties' replication view columns.
  */
-export const MANIFEST_VERSION = 4;
+export const MANIFEST_VERSION = 6;
+/** The first version whose documents use snake_case names on the wire. */
+const WIRE_MANIFEST_VERSION = 4;
 /** The phrase used for a direction the author did not phrase. */
 export const DEFAULT_PHRASE = "has";
 export const SelectOptionManifest = Schema.Struct({
@@ -45,14 +52,21 @@ export const PropertyManifest = Schema.Struct({
  * from `to`, `inverse` and the second `phrase`.
  */
 export const RelationshipManifest = Schema.Struct({
+    /**
+     * The property pair of a value-matched relationship, one with a warehouse-backed end. Absent
+     * between stored entities, which use a `<name>_id` key instead.
+     */
     on: Schema.optionalKey(Schema.Struct({ property: Schema.String, targetProperty: Schema.String })),
     name: Schema.String,
     to: Schema.String,
     inverse: Schema.String,
     cardinality: Schema.Literals(["one", "many"]),
-    /** `rel.one` only. */
+    /** `rel.one` between stored entities only. */
     optional: Schema.optionalKey(Schema.Boolean),
-    /** `rel.one` only. */
+    /**
+     * `rel.one` between stored entities only. Before version 5, warehouse → stored relationships
+     * carried it too, as `restrict`, though nothing enforced it.
+     */
     onDelete: Schema.optionalKey(Schema.Literals(ON_DELETE)),
     /** `rel.many` only. */
     ordered: Schema.optionalKey(Schema.Boolean),
@@ -60,6 +74,14 @@ export const RelationshipManifest = Schema.Struct({
     phrase: Schema.Tuple([Schema.String, Schema.String]),
     description: Schema.String,
 });
+/**
+ * Whether a relationship is matched by value: either end is warehouse-backed. A value-matched
+ * relationship always declares `on`; a stored → stored relationship never does. It has no
+ * `<name>_id` column, foreign key, index or traversal route.
+ */
+export function isValueMatched(relationship) {
+    return relationship.on !== undefined;
+}
 export const IndexManifest = Schema.Struct({
     properties: Schema.Array(Schema.String),
     unique: Schema.Boolean,
@@ -190,7 +212,7 @@ const EntityManifestWire = Schema.Struct({
     relationships: Schema.Array(RelationshipManifestWire),
 }).pipe(Schema.encodeKeys({ builtIn: "built_in", renamedFrom: "renamed_from" }));
 const RoleManifestWire = RoleManifest.pipe(Schema.encodeKeys({ builtIn: "built_in" }));
-/** The JSON contract written by version 4; decoded SDK models remain camelCase. */
+/** The JSON contract written since version 4; decoded SDK models remain camelCase. */
 export const OntologyManifestWire = Schema.Struct({
     ...OntologyManifestModel.fields,
     entities: Schema.Array(EntityManifestWire),
@@ -210,7 +232,7 @@ export function encodeManifest(manifest) {
     if (original !== undefined) {
         return original;
     }
-    return manifest.version < MANIFEST_VERSION
+    return manifest.version < WIRE_MANIFEST_VERSION
         ? manifest
         : Schema.encodeSync(OntologyManifestWire)(manifest);
 }
@@ -292,7 +314,13 @@ function propertyManifest({ name, definition }) {
             : {}),
     };
 }
-function relationshipManifest({ name, relationship, target, }) {
+/**
+ * `stored` says whether both ends are stored: only then does a `rel.one` have a key column, and so
+ * an optionality and a delete rule.
+ */
+function relationshipManifest(input) {
+    const { resolved, stored } = input;
+    const { name, relationship, target } = resolved;
     const common = {
         name,
         to: target ?? "",
@@ -306,8 +334,9 @@ function relationshipManifest({ name, relationship, target, }) {
     return {
         ...common,
         cardinality: "one",
-        optional: relationship.optional,
-        onDelete: relationship.onDelete,
+        ...(stored
+            ? { optional: relationship.optional, onDelete: relationship.onDelete ?? "restrict" }
+            : {}),
         ...(relationship.on === undefined
             ? {}
             : {
@@ -318,27 +347,39 @@ function relationshipManifest({ name, relationship, target, }) {
             }),
     };
 }
-function entityManifest(resolved) {
+/**
+ * The measures of an entity. A warehouse-backed property's column is its `column`; a stored property
+ * has none, and its column in the replication view is its wire name.
+ */
+function measuresManifest(resolved) {
+    const columns = new Map(resolved.properties.map((property) => [
+        property.name,
+        property.definition.column ?? property.name,
+    ]));
+    return Object.entries(resolved.entity.definition.measures ?? {}).map(([name, measure]) => ({
+        name,
+        label: measure.label ?? humanize(name),
+        description: measure.description ?? "",
+        unit: measure.unit ?? "number",
+        format: measure.format ??
+            (measure.unit === "currency"
+                ? "currency"
+                : measure.unit === "percent"
+                    ? "percent"
+                    : "decimal"),
+        expression: measureExpression(measure, columns),
+    }));
+}
+/** `warehouseBacked` names the ontology's warehouse-backed entities, which relationships may target. */
+function entityManifest(input) {
+    const { resolved, warehouseBacked } = input;
     const { definition } = resolved.entity;
+    const storedOwner = definition.source === undefined;
+    const measures = measuresManifest(resolved);
     return {
-        ...(definition.source === undefined
-            ? {}
-            : {
-                source: definition.source,
-                measures: Object.entries(definition.measures ?? {}).map(([name, measure]) => ({
-                    name,
-                    label: measure.label ?? humanize(name),
-                    description: measure.description ?? "",
-                    unit: measure.unit ?? "number",
-                    format: measure.format ??
-                        (measure.unit === "currency"
-                            ? "currency"
-                            : measure.unit === "percent"
-                                ? "percent"
-                                : "decimal"),
-                    expression: measureExpression(measure, new Map(resolved.properties.map((p) => [p.name, p.definition.column]))),
-                })),
-            }),
+        // A warehouse-backed entity always lists its measures; a stored entity only when it has some.
+        ...(definition.source === undefined ? {} : { source: definition.source, measures }),
+        ...(definition.source === undefined && measures.length > 0 ? { measures } : {}),
         id: definition.id,
         name: resolved.name,
         label: definition.label,
@@ -349,7 +390,10 @@ function entityManifest(resolved) {
         ...(definition.renamedFrom !== undefined ? { renamedFrom: definition.renamedFrom } : {}),
         ...(definition.guide !== undefined ? { guide: definition.guide } : {}),
         properties: resolved.properties.map(propertyManifest),
-        relationships: resolved.relationships.map(relationshipManifest),
+        relationships: resolved.relationships.map((relationship) => relationshipManifest({
+            resolved: relationship,
+            stored: storedOwner && !warehouseBacked.has(relationship.target ?? ""),
+        })),
         indexes: resolved.indexes.map((index) => ({
             properties: [...index.properties],
             unique: index.unique,
@@ -368,9 +412,12 @@ function entityManifest(resolved) {
 /** Builds the manifest of a resolved ontology that passed `check`. */
 export function buildManifest(input) {
     const connections = input.connections ?? [];
+    const warehouseBacked = new Set(input.entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name));
     const body = {
         version: MANIFEST_VERSION,
-        entities: input.entities.map(entityManifest),
+        entities: input.entities.map((candidate) => entityManifest({ resolved: candidate, warehouseBacked })),
         roles: input.roles.map((candidate) => ({
             name: candidate.name,
             description: candidate.description,

package/dist/measure.d.ts

@@ -7,7 +7,7 @@ export type MeasureExpression = {
     readonly op: "literal";
     readonly value: string;
 } | {
-    readonly op: "sum" | "add" | "subtract" | "multiply" | "divide";
+    readonly op: "sum" | "countDistinct" | "add" | "subtract" | "multiply" | "divide";
     readonly args: ReadonlyArray<MeasureExpression>;
 };
 export interface MeasureOptions {
@@ -22,6 +22,11 @@ export type Measures = Readonly<Record<string, Measure>>;
 export declare const m: {
     readonly count: (options?: MeasureOptions) => Measure;
     readonly sum: (property: string, options?: MeasureOptions) => Measure;
+    /**
+     * The number of distinct non-null values of a text, email, url, select, integer, date or timestamp
+     * property. Distinct counts do not add up across groups.
+     */
+    readonly countDistinct: (property: string, options?: MeasureOptions) => Measure;
     readonly ref: (name: string, options?: MeasureOptions) => Measure;
     readonly literal: (value: number | string, options?: MeasureOptions) => Measure;
     readonly add: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
@@ -29,5 +34,9 @@ export declare const m: {
     readonly multiply: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
     readonly divide: (left: MeasureExpression, right: MeasureExpression, options?: MeasureOptions) => Measure;
 };
-/** Strip authoring options and resolve logical properties to physical columns for the manifest. */
+/**
+ * Strip authoring options and resolve logical properties to physical columns for the manifest: a
+ * warehouse-backed property's `column`, or a stored property's replication view column, which is its
+ * wire name.
+ */
 export declare function measureExpression(value: MeasureExpression, columns: ReadonlyMap<string, string>): MeasureExpression;

package/dist/measure.js

@@ -9,6 +9,15 @@ export const m = {
         args: [{ op: "column", name: property }],
         ...options,
     }),
+    /**
+     * The number of distinct non-null values of a text, email, url, select, integer, date or timestamp
+     * property. Distinct counts do not add up across groups.
+     */
+    countDistinct: (property, options) => ({
+        op: "countDistinct",
+        args: [{ op: "column", name: property }],
+        ...options,
+    }),
     ref: (name, options) => ({ op: "measure", name, ...options }),
     literal: (value, options) => ({
         op: "literal",
@@ -20,7 +29,11 @@ export const m = {
     multiply: binary("multiply"),
     divide: binary("divide"),
 };
-/** Strip authoring options and resolve logical properties to physical columns for the manifest. */
+/**
+ * Strip authoring options and resolve logical properties to physical columns for the manifest: a
+ * warehouse-backed property's `column`, or a stored property's replication view column, which is its
+ * wire name.
+ */
 export function measureExpression(value, columns) {
     switch (value.op) {
         case "count":

package/dist/migrate/apply.d.ts

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

package/dist/migrate/apply.js

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

package/dist/migrate/plan.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyManifest } from "../manifest.js";
+import { type OntologyManifest } from "../manifest.js";
 import type { MigrationPlan } from "./model.js";
 export interface MigrationOptions {
     /**

package/dist/migrate/plan.js

@@ -1,3 +1,4 @@
+import { isValueMatched, } from "../manifest.js";
 import { BLOB_TABLES_DDL } from "../storage/tables.js";
 import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
 import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
@@ -150,29 +151,32 @@ function validateManifest(manifest, refusals) {
     const invalid = (path, message) => {
         refusals.push(refusal("invalid-manifest", path, message));
     };
-    const names = new Set();
+    const entitiesByName = new Map();
     const ids = new Set();
     for (const entity of manifest.entities) {
         if (!SNAKE_CASE_NAME.test(entity.name)) {
             invalid(entity.name, "entity names are lowercase snake_case.");
         }
-        if (names.has(entity.name)) {
+        if (entitiesByName.has(entity.name)) {
             invalid(entity.name, `two entities are named ${entity.name}.`);
         }
+        else {
+            entitiesByName.set(entity.name, entity);
+        }
         if (ids.has(entity.id)) {
             invalid(entity.name, `two entities have the id ${entity.id}.`);
         }
-        names.add(entity.name);
         ids.add(entity.id);
     }
-    if (!names.has(USER_TABLE)) {
+    if (!entitiesByName.has(USER_TABLE)) {
         invalid(USER_TABLE, "the built-in user entity is missing; every ontology includes it.");
     }
     for (const entity of manifest.entities) {
-        validateEntity(entity, names, invalid);
+        validateEntity({ entity, entitiesByName, invalid });
     }
 }
-function validateEntity(entity, entityNames, invalid) {
+function validateEntity(input) {
+    const { entity, entitiesByName, invalid } = input;
     for (const property of entity.properties) {
         const path = `${entity.name}.properties.${property.name}`;
         const values = (property.options ?? []).map((option) => option.value);
@@ -195,11 +199,21 @@ function validateEntity(entity, entityNames, invalid) {
         if (!SNAKE_CASE_NAME.test(relationship.name) || isSystemProperty(relationship.name)) {
             invalid(path, "relationship names are lowercase snake_case and cannot be system properties.");
         }
-        if (!entityNames.has(relationship.to)) {
+        const target = entitiesByName.get(relationship.to);
+        if (target === undefined) {
             invalid(path, `it points at ${relationship.to}, which is not an entity.`);
         }
-        if (relationship.cardinality === "one" && relationship.onDelete === undefined) {
-            invalid(path, "a rel.one relationship needs onDelete.");
+        else if (isValueMatched(relationship) !== (entity.source !== undefined || target.source !== undefined)) {
+            // `on` is what keeps a relationship with a warehouse-backed end out of storage.
+            invalid(path, isValueMatched(relationship)
+                ? "a relationship between stored entities uses a key column and cannot declare on."
+                : "a relationship with a warehouse-backed end is matched by value and needs on.");
+        }
+        // A value-matched relationship has no foreign key, so no delete rule.
+        if (relationship.cardinality === "one" &&
+            !isValueMatched(relationship) &&
+            relationship.onDelete === undefined) {
+            invalid(path, "a rel.one relationship between stored entities needs onDelete.");
         }
         if (relationship.onDelete === "setNull" && relationship.optional !== true) {
             invalid(path, 'onDelete "setNull" needs an optional relationship.');
@@ -344,12 +358,17 @@ function matchEntities(currentEntities, targetEntities, refusals) {
         for (const relationship of target.relationships) {
             const previous = current.relationships.find(({ name }) => name === relationship.name);
             if (previous === undefined) {
-                addedRelationships.push(relationship);
+                if (!isValueMatched(relationship)) {
+                    addedRelationships.push(relationship);
+                }
                 continue;
             }
+            // Both lists hold stored entities only, so a warehouse-backed target has no id here.
             const previousTarget = entityIdByName(currentEntities, previous.to);
             const nextTarget = entityIdByName(targetEntities, relationship.to);
-            if (previous.cardinality !== relationship.cardinality || previousTarget !== nextTarget) {
+            if (previous.cardinality !== relationship.cardinality ||
+                previousTarget !== nextTarget ||
+                isValueMatched(previous) !== isValueMatched(relationship)) {
                 changed.add(relationship.name);
                 refusals.push(refusal("relationship-change", `${target.name}.relationships.${relationship.name}`, `was rel.${previous.cardinality} to ${previous.to} and is now ` +
                     `rel.${relationship.cardinality} to ${relationship.to}; a relationship keeps its ` +
@@ -357,9 +376,15 @@ function matchEntities(currentEntities, targetEntities, refusals) {
                 continue;
             }
             kept.add(relationship.name);
-            relationships.push({ current: previous, target: relationship });
+            if (!isValueMatched(relationship)) {
+                relationships.push({ current: previous, target: relationship });
+            }
         }
-        const removedRelationships = current.relationships.filter(({ name }) => !kept.has(name) && !changed.has(name));
+        // A value-matched relationship is stored as the property its `on` names: adding, keeping or
+        // removing one plans no statement and drops nothing.
+        const removedRelationships = current.relationships.filter((relationship) => !kept.has(relationship.name) &&
+            !changed.has(relationship.name) &&
+            !isValueMatched(relationship));
         pairs.push({
             current,
             target,

package/dist/migrate/storage.d.ts

@@ -1,4 +1,4 @@
-import type { EntityManifest, PropertyManifest, RelationshipManifest } from "../manifest.js";
+import { type EntityManifest, type PropertyManifest, type RelationshipManifest } from "../manifest.js";
 /**
  * The physical mapping of an ontology onto Postgres. The planner creates exactly these objects and the
  * runtime reads and writes them, so every name here is part of the storage contract.
@@ -121,7 +121,8 @@ export declare function primaryKeyName(table: string): string;
 export declare function indexName(table: string, columns: ReadonlyArray<string>): string;
 /**
  * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
- * `rel.one` (`owner` → `owner_id`). Returns undefined for anything else.
+ * stored `rel.one` (`owner` → `owner_id`). Returns undefined for anything else, value-matched
+ * relationships included: they have no column.
  */
 export declare function fieldColumnName(entity: EntityManifest, field: string): string | undefined;
 /** The SQL default of a property, or undefined when it declares none. */

package/dist/migrate/storage.js

@@ -1,3 +1,4 @@
+import { isValueMatched, } from "../manifest.js";
 /**
  * The physical mapping of an ontology onto Postgres. The planner creates exactly these objects and the
  * runtime reads and writes them, so every name here is part of the storage contract.
@@ -102,7 +103,8 @@ export function indexName(table, columns) {
 }
 /**
  * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
- * `rel.one` (`owner` → `owner_id`). Returns undefined for anything else.
+ * stored `rel.one` (`owner` → `owner_id`). Returns undefined for anything else, value-matched
+ * relationships included: they have no column.
  */
 export function fieldColumnName(entity, field) {
     // Applied manifests may still name system fields in camelCase.
@@ -121,7 +123,9 @@ export function fieldColumnName(entity, field) {
     if (entity.properties.some((property) => property.name === field)) {
         return columnName(field);
     }
-    if (entity.relationships.some((relationship) => relationship.name === field && relationship.cardinality === "one")) {
+    if (entity.relationships.some((relationship) => relationship.name === field &&
+        relationship.cardinality === "one" &&
+        !isValueMatched(relationship))) {
         return relationshipColumnName(field);
     }
     return undefined;
@@ -364,8 +368,7 @@ function entityIndexes(entity) {
         unique: true,
         origin: `${entity.name}.${property.name} is unique`,
     }));
-    const keys = entity.relationships
-        .filter((relationship) => relationship.cardinality === "one")
+    const keys = keyedRelationships(entity)
         .map((relationship) => ({
         name: indexName(table, [relationshipColumnName(relationship.name)]),
         table,
@@ -376,10 +379,17 @@ function entityIndexes(entity) {
         .filter((index) => !declaredNames.has(index.name));
     return [...unique, ...keys, ...declared];
 }
+/**
+ * The `rel.one` relationships that have a key column and a foreign key: those between stored
+ * entities. A value-matched relationship is stored as the ordinary property its `on` names.
+ */
+function keyedRelationships(entity) {
+    return entity.relationships.filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship));
+}
 /** The table, history table, enum types and join tables of an entity. */
 export function entityStorage(entity) {
     const table = tableName(entity.name);
-    const ones = entity.relationships.filter((relationship) => relationship.cardinality === "one");
+    const ones = keyedRelationships(entity);
     const manys = entity.relationships.filter((relationship) => relationship.cardinality === "many");
     const checks = entity.properties.flatMap((property) => {
         const check = propertyCheck(entity.name, property);

package/dist/names.d.ts

@@ -20,12 +20,14 @@ export declare const MEMBER_ROLE = "member";
 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"];
+/** The ontology service's route for aggregates across entities: `/api/ontology/aggregate`. */
+export declare const AGGREGATE_ROUTE = "aggregate";
 /** 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", "oauth"];
+export declare const RESERVED_ENTITY_NAMES: readonly ["aggregate", "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"];
+export declare const MCP_GLOBAL_TOOLS: readonly ["describe", "me", "aggregate"];
 /** 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`. */

package/dist/names.js

@@ -48,8 +48,11 @@ export const MEMBER_ROLE = "member";
 export const HISTORY_SUFFIX = "_history";
 /** The combinators of the query language, which take the place of field names in a `where`. */
 export const RESERVED_MEMBER_NAMES = ["and", "or", "not"];
+/** The ontology service's route for aggregates across entities: `/api/ontology/aggregate`. */
+export const AGGREGATE_ROUTE = "aggregate";
 /** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
 export const RESERVED_ENTITY_NAMES = [
+    AGGREGATE_ROUTE,
     "graph",
     "status",
     "describe",
@@ -62,7 +65,7 @@ export const RESERVED_ENTITY_NAMES = [
 /** 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"];
+export const MCP_GLOBAL_TOOLS = ["describe", "me", "aggregate"];
 /** 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`. */

package/dist/query.d.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 import type { JsonSchemaObject } from "./analyze.js";
-import type { EntityManifest, OntologyManifest } from "./manifest.js";
+import { type EntityManifest, type OntologyManifest } from "./manifest.js";
 import type { PropertyType } from "./property.js";
 /** How a record field is stored: a property type, or a UUID for ids and `<relationship>_id` keys. */
 export type StorageType = PropertyType | "uuid";
@@ -139,7 +139,10 @@ export interface QueryLink {
     readonly declared: "one" | "many";
     readonly inverse: boolean;
 }
-/** The fields of an entity's records, in record order. */
+/**
+ * The fields of an entity's records, in record order. A value-matched relationship has no
+ * `<relationship>_id`: its reference is the property named in `on`.
+ */
 export declare function queryFields(entity: EntityManifest): ReadonlyArray<QueryField>;
 /** The relationships of an entity, declared ones first, then the inverses landing on it. */
 export declare function queryLinks(manifest: OntologyManifest, entityName: string): ReadonlyArray<QueryLink>;

package/dist/query.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { wireStruct } from "./wire.js";
+import { isValueMatched } from "./manifest.js";
 import { BlobValue } from "./blob.js";
 /**
  * The query language of `find` and of the HTTP API's list and query endpoints.
@@ -79,7 +80,10 @@ const SYSTEM_FIELDS = [
     { name: "created_by", storage: "uuid", nullable: true },
     { name: "updated_by", storage: "uuid", nullable: true },
 ];
-/** The fields of an entity's records, in record order. */
+/**
+ * The fields of an entity's records, in record order. A value-matched relationship has no
+ * `<relationship>_id`: its reference is the property named in `on`.
+ */
 export function queryFields(entity) {
     const properties = entity.properties.map((property) => ({
         name: property.name,
@@ -90,7 +94,7 @@ export function queryFields(entity) {
             : {}),
     }));
     const keys = entity.relationships
-        .filter((relationship) => relationship.cardinality === "one")
+        .filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship))
         .map((relationship) => ({
         name: `${relationship.name}_id`,
         storage: "uuid",