@segmentstream-cloud/ontology 0.12.0 → 0.14.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.js

@@ -7,7 +7,7 @@ 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";
+import { AGENT_TABLES, 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. */
 const MIGRATION_LOCK = "segmentstream.ontology.migration";
@@ -171,6 +171,7 @@ export const RUNTIME_TABLES = [
     USER_ROLES_TABLE,
     API_KEYS_TABLE,
     ...OAUTH_TABLES,
+    ...AGENT_TABLES,
 ];
 /**
  * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an

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,6 +1,7 @@
+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";
+import { AGENT_TABLES, AGENT_TABLES_DDL, 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";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
 function step(input) {
     return {
@@ -69,17 +70,29 @@ export function planMigration(input) {
         draft.runtimeTables.push(step({
             kind: "createCatalog",
             classification: "additive",
-            description: "Create the runtime's role assignment, API key and OAuth tables.",
+            description: "Create the runtime's role assignment, API key, OAuth and agent tables.",
             sql: RUNTIME_TABLES_DDL,
         }));
     }
-    else if (OAUTH_TABLES.some((table) => input.existingTables?.has(table) === false)) {
-        draft.runtimeTables.push(step({
-            kind: "createCatalog",
-            classification: "additive",
-            description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
-            sql: OAUTH_TABLES_DDL,
-        }));
+    else {
+        // A database an earlier SDK migrated lacks the tables added since; each set arrives on its own.
+        const lacks = (tables) => tables.some((table) => input.existingTables?.has(table) === false);
+        if (lacks(OAUTH_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
+                sql: OAUTH_TABLES_DDL,
+            }));
+        }
+        if (lacks(AGENT_TABLES)) {
+            draft.runtimeTables.push(step({
+                kind: "createCatalog",
+                classification: "additive",
+                description: "Create the runtime's agent tables, which pair channel accounts with members.",
+                sql: AGENT_TABLES_DDL,
+            }));
+        }
     }
     if (storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob")) &&
         !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {
@@ -150,29 +163,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 +211,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 +370,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 +388,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. */
@@ -163,6 +164,18 @@ export declare const OAUTH_TOKENS_TABLE = "_oauth_tokens";
 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>;
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export declare const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/** Channel accounts paired with members: the app's agent acts as the member for their messages. */
+export declare const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/** The agent's tables, in the order they are created. */
+export declare const AGENT_TABLES: ReadonlyArray<string>;
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, and the identities
+ * they create. An account and a member each have at most one live identity per provider. Every
+ * statement is idempotent.
+ */
+export declare const AGENT_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

@@ -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);
@@ -514,6 +524,53 @@ export const OAUTH_TABLES_DDL = [
     `CREATE INDEX IF NOT EXISTS "${OAUTH_TOKENS_TABLE}_grant_id_idx" ` +
         `ON ${quoteIdentifier(OAUTH_TOKENS_TABLE)} ("grant_id")`,
 ];
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/** Channel accounts paired with members: the app's agent acts as the member for their messages. */
+export const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/** The agent's tables, in the order they are created. */
+export const AGENT_TABLES = [AGENT_PAIRINGS_TABLE, AGENT_IDENTITIES_TABLE];
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, and the identities
+ * they create. An account and a member each have at most one live identity per provider. Every
+ * statement is idempotent.
+ */
+export const AGENT_TABLES_DDL = [
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_PAIRINGS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "code_hash" text NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "consumed_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_code_hash_key" UNIQUE ("code_hash")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_account_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("provider", "external_id") ` +
+        `WHERE "revoked_at" IS NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_member_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("user_id", "provider") ` +
+        `WHERE "revoked_at" IS NULL`,
+];
 /**
  * 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.
@@ -546,6 +603,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,
+    ...AGENT_TABLES_DDL,
 ];
 export function columnDefinition(column) {
     const parts = [quoteIdentifier(column.name), column.type];

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", "agent"];
 /** 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",
@@ -58,11 +61,12 @@ export const RESERVED_ENTITY_NAMES = [
     "mcp",
     "me",
     "oauth",
+    "agent",
 ];
 /** 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>;