@segmentstream-cloud/ontology 0.12.0 → 0.14.0

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",

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/model.d.ts

@@ -1,4 +1,4 @@
-import type { OntologyManifest } from "../manifest.js";
+import { type OntologyManifest } from "../manifest.js";
 /** The resolved projection for one immutable generation. `id` is always included. */
 export interface ReplicationSelection {
     readonly entityId: string;

package/dist/replication/model.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isValueMatched } from "../manifest.js";
 import { queryFields } from "../query.js";
 export function resolveReplicationSelection(manifest, exclusions = []) {
     const entities = manifest.entities.filter((entity) => !entity.builtIn && !entity.source);
@@ -18,13 +19,22 @@ export function resolveReplicationSelection(manifest, exclusions = []) {
         if (item.relationships?.some((relationship) => !relationships.has(relationship))) {
             throw new Error(`Unknown replication relationship on ${entity.name}.`);
         }
+        // A value-matched relationship has no `<name>_id`: its reference is the property `on` names.
+        const matched = entity.relationships.find((relationship) => item.relationships?.includes(relationship.name) && isValueMatched(relationship));
+        if (matched !== undefined) {
+            throw new Error(`${entity.name}.${matched.name} is matched by value; exclude its property ` +
+                `${matched.on?.property ?? ""} instead.`);
+        }
     }
     const included = entities.filter((entity) => !exclusions.some((item) => item.entityId === entity.id && item.disabled));
     const selection = included.map((entity) => {
         const excluded = exclusions.find((item) => item.entityId === entity.id);
+        const keyed = entity.relationships.filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship));
         const excludedFields = new Set([
             ...(excluded?.fields ?? []),
-            ...(excluded?.relationships ?? []).map((relationship) => `${relationship}_id`),
+            ...keyed
+                .filter((relationship) => excluded?.relationships?.includes(relationship.name))
+                .map((relationship) => `${relationship.name}_id`),
         ]);
         return {
             entityId: entity.id,

package/dist/runtime/agents.d.ts

@@ -0,0 +1,9 @@
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { AgentStore } from "../service/runtime-contract.js";
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ */
+export declare function sqlAgentStore(ontology: Ontology, sql: SqlClient.SqlClient): AgentStore;

package/dist/runtime/agents.js

@@ -0,0 +1,145 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { AGENT_IDENTITIES_TABLE, AGENT_PAIRINGS_TABLE, USER_TABLE } from "../migrate/storage.js";
+import { resolveMemberById } from "./principals.js";
+import { isRecordId } from "./records.js";
+const PAIRINGS = `"${AGENT_PAIRINGS_TABLE}"`;
+const IDENTITIES = `"${AGENT_IDENTITIES_TABLE}"`;
+const USERS = `"${USER_TABLE}"`;
+/** A timestamp as epoch milliseconds, which every driver returns as a plain number. */
+function epochMs(column) {
+    return `(extract(epoch from ${column}) * 1000)::double precision`;
+}
+const PAIRING_COLUMNS = `"id"::text AS "id", "provider", "external_id", "display", ` +
+    `${epochMs(`"expires_at"`)} AS "expires_at"`;
+const IDENTITY_COLUMNS = `"id"::text AS "id", "provider", "external_id", "user_id"::text AS "user_id", "display", ` +
+    `${epochMs(`"created_at"`)} AS "created_at", ${epochMs(`"revoked_at"`)} AS "revoked_at"`;
+function nullableText(value) {
+    return value === null || value === undefined ? null : String(value);
+}
+function pairingOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        display: nullableText(row.display),
+        expiresAt: new Date(Number(row.expires_at)),
+    };
+}
+function identityOf(row) {
+    return {
+        id: String(row.id),
+        provider: String(row.provider),
+        externalId: String(row.external_id),
+        userId: String(row.user_id),
+        display: nullableText(row.display),
+        createdAt: new Date(Number(row.created_at)),
+        revokedAt: row.revoked_at === null ? null : new Date(Number(row.revoked_at)),
+    };
+}
+/**
+ * The agent store on the runtime's agent tables, as `ontology_app`. Expiry is the database's
+ * `now()`; a pairing is consumed with one `UPDATE … WHERE "consumed_at" IS NULL`, so two concurrent
+ * approvals cannot both succeed. Ids that are not UUIDs find nothing rather than fail the cast.
+ */
+export function sqlAgentStore(ontology, sql) {
+    const rows = (statement, values = []) => sql.unsafe(statement, values).pipe(Effect.orDie);
+    const memberPrincipal = (userId) => resolveMemberById(ontology, userId).pipe(Effect.provideService(SqlClient.SqlClient, sql));
+    return {
+        savePairing: (pairing) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* rows(`DELETE FROM ${PAIRINGS} WHERE "expires_at" <= now()`);
+            const inserted = yield* rows([
+                `INSERT INTO ${PAIRINGS}`,
+                `  ("id", "code_hash", "provider", "external_id", "display", "expires_at")`,
+                `VALUES ($1::uuid, $2, $3, $4, $5, $6::timestamptz)`,
+                `ON CONFLICT ("code_hash") DO NOTHING`,
+                `RETURNING "id"`,
+            ].join("\n"), [
+                pairing.id,
+                pairing.codeHash,
+                pairing.provider,
+                pairing.externalId,
+                pairing.display,
+                pairing.expiresAt.toISOString(),
+            ]);
+            return inserted.length > 0;
+        }))
+            .pipe(Effect.orDie),
+        findPairing: (codeHash) => rows([
+            `SELECT ${PAIRING_COLUMNS}`,
+            `FROM ${PAIRINGS}`,
+            `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+        ].join("\n"), [codeHash]).pipe(Effect.map(([row]) => (row === undefined ? undefined : pairingOf(row)))),
+        approvePairing: ({ codeHash, userId, identityId }) => sql
+            .withTransaction(Effect.gen(function* () {
+            const [consumed] = yield* rows([
+                `UPDATE ${PAIRINGS} SET "consumed_at" = now()`,
+                `WHERE "code_hash" = $1 AND "consumed_at" IS NULL AND "expires_at" > now()`,
+                `RETURNING ${PAIRING_COLUMNS}`,
+            ].join("\n"), [codeHash]);
+            if (consumed === undefined) {
+                return undefined;
+            }
+            const pairing = pairingOf(consumed);
+            // Two approvals that replace the same account's or the same member's identity run one
+            // after the other, so the partial unique indexes never refuse a valid one.
+            yield* rows(`SELECT pg_advisory_xact_lock(hashtext($1)), pg_advisory_xact_lock(hashtext($2))`, [
+                `account:${pairing.provider}:${pairing.externalId}`,
+                `member:${userId}:${pairing.provider}`,
+            ]);
+            yield* rows([
+                `UPDATE ${IDENTITIES} SET "revoked_at" = now()`,
+                `WHERE "revoked_at" IS NULL AND "provider" = $1`,
+                `  AND ("external_id" = $2 OR "user_id" = $3::uuid)`,
+            ].join("\n"), [pairing.provider, pairing.externalId, userId]);
+            const [created] = yield* rows([
+                `INSERT INTO ${IDENTITIES} ("id", "provider", "external_id", "user_id", "display")`,
+                `VALUES ($1::uuid, $2, $3, $4::uuid, $5)`,
+                `RETURNING ${IDENTITY_COLUMNS}`,
+            ].join("\n"), [identityId, pairing.provider, pairing.externalId, userId, pairing.display]);
+            return created === undefined ? undefined : identityOf(created);
+        }))
+            .pipe(Effect.orDie),
+        findIdentity: ({ provider, externalId }) => rows([
+            `SELECT ${IDENTITY_COLUMNS}`,
+            `FROM ${IDENTITIES}`,
+            `WHERE "provider" = $1 AND "external_id" = $2`,
+            `ORDER BY "revoked_at" IS NOT NULL, "revoked_at" DESC`,
+            `LIMIT 1`,
+        ].join("\n"), [provider, externalId]).pipe(Effect.map(([row]) => (row === undefined ? undefined : identityOf(row)))),
+        listIdentities: (userId) => isRecordId(userId)
+            ? rows([
+                `SELECT ${IDENTITY_COLUMNS}`,
+                `FROM ${IDENTITIES}`,
+                `WHERE "user_id" = $1::uuid AND "revoked_at" IS NULL`,
+                `ORDER BY "created_at", "id"`,
+            ].join("\n"), [userId]).pipe(Effect.map((found) => found.map(identityOf)))
+            : Effect.succeed([]),
+        revokeIdentity: ({ id, userId }) => isRecordId(id) && isRecordId(userId)
+            ? rows([
+                `UPDATE ${IDENTITIES} SET "revoked_at" = now()`,
+                `WHERE "id" = $1::uuid AND "user_id" = $2::uuid AND "revoked_at" IS NULL`,
+                `RETURNING "id"`,
+            ].join("\n"), [id, userId]).pipe(Effect.map((revoked) => revoked.length > 0))
+            : Effect.succeed(false),
+        member: (userId) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const principal = yield* memberPrincipal(userId);
+            if (principal === undefined) {
+                return undefined;
+            }
+            const [user] = yield* rows(`SELECT "name" FROM ${USERS} WHERE "id" = $1::uuid`, [userId]);
+            return { name: String(user?.name ?? ""), principal };
+        }),
+        actingMember: (userId) => Effect.gen(function* () {
+            if (!isRecordId(userId)) {
+                return undefined;
+            }
+            const [paired] = yield* rows(`SELECT 1 FROM ${IDENTITIES} WHERE "user_id" = $1::uuid AND "revoked_at" IS NULL LIMIT 1`, [userId]);
+            return paired === undefined ? undefined : yield* memberPrincipal(userId);
+        }),
+    };
+}

package/dist/runtime/service-binding.js

@@ -6,6 +6,7 @@ import { maintainBlobStorage } from "../storage/maintenance.js";
 import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
+import { sqlAgentStore } from "./agents.js";
 import { generatedActions } from "./generated-actions.js";
 import { sqlOAuthStore } from "./oauth.js";
 import { runAction } from "./pipeline.js";
@@ -69,6 +70,7 @@ export function backendLayer(ontology, blobStorage) {
                 return state?.enabled === true;
             }).pipe(Effect.orDie),
             oauth: sqlOAuthStore(ontology, sql),
+            agents: sqlAgentStore(ontology, sql),
         });
     }));
 }

package/dist/service/agent/protocol.d.ts

@@ -0,0 +1,47 @@
+import { Schema } from "effect";
+import type { Principal } from "../../runtime.js";
+import type { AgentIdentity } from "../runtime-contract.js";
+/** How long a member has to open the connect link, sign in and approve the pairing. */
+export declare const PAIRING_TTL_MS: number;
+/**
+ * The letters and digits a pairing code uses: no 0/O, 1/I/L, so that a code read aloud or typed from
+ * a phone comes out right. 31 symbols, 8 of them: about 40 bits, against ten minutes of guessing by
+ * signed-in members only.
+ */
+export declare const PAIRING_CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+export declare const PAIRING_CODE_LENGTH = 8;
+/** A new pairing code, from the operating system's random source without modulo bias. */
+export declare function newPairingCode(): string;
+/**
+ * A code as the member's browser sends it, in the canonical form it was hashed in: upper case,
+ * without the spaces or dashes someone may type between groups. `undefined` when it cannot be one.
+ */
+export declare function canonicalPairingCode(value: string): string | undefined;
+/** A channel's name: `telegram`, `slack`. It is part of a URL path and of every identity. */
+export declare const Provider: Schema.String;
+/** `POST /api/ontology/agent/pairings`: the account an unknown sender writes from. */
+export declare const PairingRequest: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly external_id: Schema.String;
+    readonly display: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+}>;
+export type PairingRequest = typeof PairingRequest.Type;
+/** An identity on the wire, as the member's connect page and settings show it. */
+export declare function identityForWire(identity: AgentIdentity): {
+    id: string;
+    provider: string;
+    external_id: string;
+    display: string | null;
+    created_at: string;
+};
+/** The member the agent acts for, as `GET …/identities/{provider}/{external_id}` answers. */
+export declare function memberForWire(input: {
+    readonly name: string;
+    readonly principal: Principal;
+}): {
+    user: {
+        id: string;
+        name: string;
+    };
+    roles: readonly string[];
+};