@segmentstream-cloud/ontology 0.12.0 → 0.14.0

package/dist/analyze.js

@@ -5,7 +5,7 @@ import { BLOB_CONTENT_TYPES, MAX_BLOB_BYTES } from "./blob.js";
 import { isAction } from "./action.js";
 import { CONNECTION_KEY, isConnection } from "./connection.js";
 import { isEntity } from "./entity.js";
-import { LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MCP_READ_TOOLS, MCP_TOOL_NAME_MAX_LENGTH, MEMBER_ROLE, mcpToolName, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
+import { AGGREGATE_ROUTE, LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MCP_READ_TOOLS, MCP_TOOL_NAME_MAX_LENGTH, MEMBER_ROLE, mcpToolName, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
 import { REFERENCE_ANNOTATION, propertyDefinition, referenceTarget, } from "./property.js";
 import { generatedActionPermissions, parsePermission, permissionOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
 import { ON_DELETE, isRelationship } from "./relationship.js";
@@ -63,6 +63,7 @@ export function analyze(config, options = {}) {
     checkConnectionsUsed(resolved, connections, config.connections ?? [], report);
     if (options.checkPermissions !== false) {
         checkPermissions(resolved, roles, report);
+        checkOpenWarehouseReads({ entities: resolved, roles, signIn, report });
     }
     return { entities: resolved, roles, signIn, connections, diagnostics };
 }
@@ -305,6 +306,10 @@ function resolveEntity(candidate, scope) {
     else if (name.endsWith(HISTORY_SUFFIX)) {
         report("reserved-name", name, `names ending in ${HISTORY_SUFFIX} are reserved for history tables.`);
     }
+    else if (name === AGGREGATE_ROUTE) {
+        report("reserved-name", name, `/api/ontology/${name} answers aggregates across the ontology's entities; ` +
+            "choose another entity name.");
+    }
     else if (RESERVED_ENTITY_NAMES.includes(name)) {
         report("reserved-name", name, `/api/ontology/${name} is a route of the ontology service.`);
     }
@@ -514,22 +519,44 @@ function checkRelationship(path, relationship, report) {
         (relationship.phrase.length !== 2 || relationship.phrase.some((part) => isBlank(part)))) {
         report("invalid-phrase", path, "phrase names both directions: [forward, inverse].");
     }
-    if (relationship.cardinality === "many") {
+    // checkWarehouseSource refuses a delete rule or optionality on a relationship matched by value.
+    if (relationship.cardinality === "many" || relationship.on !== undefined) {
         return;
     }
-    if (!ON_DELETE.includes(relationship.onDelete)) {
+    // Undeclared means restrict.
+    const onDelete = relationship.onDelete ?? "restrict";
+    if (!ON_DELETE.includes(onDelete)) {
         report("invalid-on-delete", path, `onDelete is one of ${ON_DELETE.join(", ")}.`);
     }
-    else if (relationship.onDelete === "setNull" && !relationship.optional) {
+    else if (onDelete === "setNull" && !relationship.optional) {
         report("invalid-on-delete", path, 'onDelete "setNull" needs an optional relationship; use "cascade" or "restrict".');
     }
 }
+/**
+ * A relationship with a warehouse-backed end is matched by value, through `on`, and has no
+ * `<name>_id` key. Its declaration may still lack `on`, which checkWarehouseSource reports.
+ */
+function isValueMatchedDeclaration(input) {
+    const { owner, relationship, target } = input;
+    return (relationship.cardinality === "one" &&
+        (relationship.on !== undefined ||
+            owner.definition.source !== undefined ||
+            target?.definition.source !== undefined));
+}
 function resolveIndexes(candidate, properties, relationships, scope) {
+    const valueMatched = new Set(relationships
+        .filter(({ relationship, target }) => isValueMatchedDeclaration({
+        owner: candidate,
+        relationship,
+        target: target === undefined ? undefined : scope.entitiesByName.get(target),
+    }))
+        .map((relationship) => relationship.name));
     const fields = new Set([
         ...SYSTEM_PROPERTIES,
         ...properties.map((property) => property.name),
         ...relationships
             .filter((relationship) => relationship.relationship.cardinality === "one")
+            .filter((relationship) => !valueMatched.has(relationship.name))
             .map((relationship) => relationship.name),
     ]);
     const indexes = candidate.definition.indexes ?? [];
@@ -545,7 +572,10 @@ function resolveIndexes(candidate, properties, relationships, scope) {
             scope.report("invalid-index", path, "an index covers at least one field.");
         }
         for (const field of resolved.properties) {
-            if (!fields.has(field)) {
+            if (valueMatched.has(field)) {
+                scope.report("invalid-index", path, `"${field}" is matched by value and has no key column. Index the property named in on instead.`);
+            }
+            else if (!fields.has(field)) {
                 scope.report("invalid-index", path, `"${field}" is not a property, system property or rel.one relationship of ${candidate.name}.`);
             }
         }
@@ -761,22 +791,22 @@ function checkEntityIdentities(entities, report) {
  * one namespace: they are the record's fields and the API's traversal paths.
  */
 function checkMemberNames(entities, report) {
-    const members = new Map(entities.map((candidate) => [candidate, ownMembers(candidate)]));
     const entitiesByName = new Map();
     for (const candidate of [...entities].reverse()) {
         entitiesByName.set(candidate.name, candidate);
     }
+    const members = new Map(entities.map((candidate) => [candidate, ownMembers(candidate, entitiesByName)]));
     for (const candidate of entities) {
         for (const { name, relationship, target } of candidate.relationships) {
             const landing = target === undefined ? undefined : entitiesByName.get(target);
             if (landing === undefined) {
                 continue;
             }
-            members.get(landing)?.push({
-                name: relationship.inverse,
-                path: `${candidate.name}.relationships.${name}.inverse`,
-                inverse: true,
-            });
+            const path = `${candidate.name}.relationships.${name}.inverse`;
+            members.get(landing)?.push({ name: relationship.inverse, path, inverse: true });
+            if (Object.hasOwn(landing.entity.definition.measures ?? {}, relationship.inverse)) {
+                report("inverse-collision", path, `${relationship.inverse} is already a measure of ${landing.name}.`);
+            }
         }
     }
     for (const [candidate, list] of members) {
@@ -792,18 +822,24 @@ function checkMemberNames(entities, report) {
         }
     }
 }
-function ownMembers(candidate) {
+function ownMembers(candidate, entitiesByName) {
     const properties = candidate.properties.map((property) => ({
         name: property.name,
         path: `${candidate.name}.properties.${property.name}`,
         inverse: false,
     }));
-    const relationships = candidate.relationships.flatMap(({ name, relationship }) => {
+    const relationships = candidate.relationships.flatMap(({ name, relationship, target }) => {
         const path = `${candidate.name}.relationships.${name}`;
         const own = { name, path, inverse: false };
-        return relationship.cardinality === "one" && candidate.entity.definition.source === undefined
-            ? [own, { ...own, name: `${name}_id` }]
-            : [own];
+        const landing = target === undefined ? undefined : entitiesByName.get(target);
+        // Only a stored → stored rel.one has a `<name>_id` key.
+        const keyed = relationship.cardinality === "one" &&
+            !isValueMatchedDeclaration({
+                owner: candidate.entity,
+                relationship,
+                target: landing?.entity,
+            });
+        return keyed ? [own, { ...own, name: `${name}_id` }] : [own];
     });
     return [...properties, ...relationships];
 }
@@ -880,6 +916,37 @@ function checkRolePermissions(candidate, verbs, report) {
         }
     });
 }
+/**
+ * Under the open policy anyone who signs in holds `member`. Warehouse-backed entities hold company
+ * figures, such as revenue or stock, that aggregates read with `<entity>:read`; a wildcard of
+ * member's (`*:read`, the default, or `*:*`) must not hand them to strangers. Granting a
+ * warehouse-backed entity by name, `<entity>:read` or `<entity>:*`, is a deliberate choice.
+ */
+function checkOpenWarehouseReads(input) {
+    const { entities, roles, signIn, report } = input;
+    const warehouseBacked = entities
+        .filter((candidate) => candidate.entity.definition.source !== undefined)
+        .map((candidate) => candidate.name);
+    const memberPermissions = roles.find((candidate) => candidate.name === MEMBER_ROLE)?.permissions;
+    if (signIn.policy !== "open" ||
+        warehouseBacked.length === 0 ||
+        !Array.isArray(memberPermissions)) {
+        return;
+    }
+    const wildcards = memberPermissions.filter((permission) => {
+        const parsed = parsePermission(permission);
+        return (parsed !== undefined &&
+            parsed.entity === WILDCARD &&
+            (parsed.verb === WILDCARD || parsed.verb === READ_VERB));
+    });
+    if (wildcards.length === 0) {
+        return;
+    }
+    report("invalid-sign-in", "signIn.policy", `signIn policy open lets anyone who signs in hold member; member's ${wildcards.join(", ")} ` +
+        `${wildcards.length === 1 ? "reaches" : "reach"} warehouse-backed entities ` +
+        `(${warehouseBacked.join(", ")}). Grant them to member by name, such as ` +
+        `${warehouseBacked[0]}:read, or use the invited policy.`);
+}
 /**
  * Every permission a role lists must match an entity and a verb of the ontology, and an authored
  * action that no role grants is a warning. Generated actions are not warned about: they stay closed

package/dist/entity.d.ts

@@ -50,9 +50,16 @@ type KeysWhere<T, Condition> = {
 type RequiredPropertyKeys<P> = {
     [K in keyof P]-?: RequiredOnCreate<P[K]> extends true ? K : never;
 }[keyof P] & string;
-type OneKeys<R> = KeysWhere<R, OneRelationship>;
-type RequiredOneKeys<R> = KeysWhere<R, OneRelationship<false>>;
+/** Relationships declared with `on`: matched by value, so with no `<relationship>Id`. */
+type MatchedKeys<R> = KeysWhere<R, {
+    readonly "~ontology.matched": true;
+}>;
+/** `rel.one` relationships that hold a `<relationship>Id` key. */
+type OneKeys<R> = Exclude<KeysWhere<R, OneRelationship>, MatchedKeys<R>>;
+type RequiredOneKeys<R> = Exclude<KeysWhere<R, OneRelationship<false>>, MatchedKeys<R>>;
 type ManyKeys<R> = KeysWhere<R, ManyRelationship>;
+/** Relationships `find` can include and filter through. */
+type LinkKeys<R> = Exclude<keyof R & string, MatchedKeys<R>>;
 type UniqueKeys<P> = {
     [K in keyof P]-?: Unwrapped<P[K]> extends {
         readonly "~ontology.unique": true;
@@ -61,7 +68,10 @@ type UniqueKeys<P> = {
 type RelationshipIds<R> = {
     readonly [K in OneKeys<R> as `${K}Id`]: R[K] extends OneRelationship<true> ? string | null : string;
 };
-/** A record of the entity: system fields, declared properties, and `<relationship>Id` per `rel.one`. */
+/**
+ * A record of the entity: system fields, declared properties, and `<relationship>Id` per `rel.one`
+ * between stored entities.
+ */
 export type EntityRecord<P, R> = Simplify<SystemFields & {
     readonly [K in keyof P]: ValueOf<P[K]>;
 } & RelationshipIds<R>>;
@@ -88,14 +98,19 @@ export type UpdateValues<P, R> = Simplify<{
 } & {
     readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
 }>;
-/** Fields an index may cover: declared properties, system properties and `rel.one` relationships. */
+/**
+ * Fields an index may cover: declared properties, system properties and `rel.one` relationships
+ * between stored entities.
+ */
 export type IndexField<P, R> = (keyof P & string) | keyof SystemFields | OneKeys<R>;
 /** An index: the covered fields in order, or the fields with options. */
 export type IndexDefinition<Field extends string = string> = ReadonlyArray<Field> | {
     readonly properties: ReadonlyArray<Field>;
     readonly unique?: boolean;
 };
-export interface EntityDefinition<P extends Properties, R extends Relationships> {
+/** The measures of an entity that declares none. */
+type NoMeasures = Readonly<Record<never, never>>;
+export interface EntityDefinition<P extends Properties, R extends Relationships, M extends Measures = Measures> {
     /** The stable identity. It never changes; a changed id is a new entity. */
     readonly id: string;
     readonly label: string;
@@ -105,7 +120,7 @@ export interface EntityDefinition<P extends Properties, R extends Relationships>
     readonly description: string;
     readonly properties: P;
     readonly source?: WarehouseSource;
-    readonly measures?: Measures;
+    readonly measures?: M;
     readonly relationships?: R;
     readonly indexes?: ReadonlyArray<IndexDefinition<IndexField<P, R>>>;
     /** A Markdown file with process knowledge, relative to the ontology folder. */
@@ -126,23 +141,24 @@ export type NoActions = Readonly<Record<never, never>>;
  * self-reference error, because the constant's type depends on the callback's result. Other
  * entities may be named as usual inside handlers. The callback runs once, when `.actions` is called.
  */
-export interface ActionsBuilder<Name extends string, P extends Properties, R extends Relationships> {
-    <const A extends Actions>(define: (self: Entity<Name, P, R>) => A): Entity<Name, P, R, A>;
+export interface ActionsBuilder<Name extends string, P extends Properties, R extends Relationships, M extends Measures = Measures> {
+    <const A extends Actions>(define: (self: Entity<Name, P, R, NoActions, M>) => A): Entity<Name, P, R, A, M>;
 }
 /**
  * An entity as `entity()` returns it: no actions yet, and `actions` is the builder that adds them.
  * It has no keys, so it reads as an empty set of actions.
  */
-export type DraftEntity<Name extends string, P extends Properties, R extends Relationships> = Entity<Name, P, R, ActionsBuilder<Name, P, R>>;
+export type DraftEntity<Name extends string, P extends Properties, R extends Relationships, M extends Measures = Measures> = Entity<Name, P, R, ActionsBuilder<Name, P, R, M>, M>;
 /**
  * An entity: its definition, the record type (`typeof Lead.Type`), a reference schema for action
- * inputs (`Lead.ref`), its actions, and data access for action handlers.
+ * inputs (`Lead.ref`), its actions, and data access for action handlers. `M` is the type of its
+ * declared measures, which typed aggregate clients read from `definition.measures`.
  */
-export interface Entity<Name extends string = string, P extends Properties = Properties, R extends Relationships = Relationships, A extends object = NoActions> {
+export interface Entity<Name extends string = string, P extends Properties = Properties, R extends Relationships = Relationships, A extends object = NoActions, M extends Measures = Measures> {
     readonly [EntityTypeId]: typeof EntityTypeId;
     /** The API name and the table name. */
     readonly name: Name;
-    readonly definition: EntityDefinition<P, R>;
+    readonly definition: EntityDefinition<P, R, M>;
     readonly properties: P;
     readonly relationships: R;
     /** The authored actions by name, as declared with `.actions(…)`. */
@@ -152,7 +168,7 @@ export interface Entity<Name extends string = string, P extends Properties = Pro
     /** A reference to one of this entity's records, by id, for action inputs. */
     readonly ref: Schema.Codec<string>;
     get(record: RecordRef, options?: GetOptions): Effect.Effect<EntityRecord<P, R>, NotFound, OntologyReads>;
-    find(options?: FindOptions<EntityRecord<P, R>, keyof R & string>): Effect.Effect<ReadonlyArray<EntityRecord<P, R>>, never, OntologyReads>;
+    find(options?: FindOptions<EntityRecord<P, R>, LinkKeys<R>>): Effect.Effect<ReadonlyArray<EntityRecord<P, R>>, never, OntologyReads>;
     create(values: CreateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound, OntologyWrites>;
     update(record: RecordRef, values: UpdateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound, OntologyWrites>;
     upsertBy(property: UniqueKeys<P>, values: CreateValues<P, R>): Effect.Effect<UpsertResult<EntityRecord<P, R>>, Conflict | NotFound, OntologyWrites>;
@@ -183,10 +199,10 @@ interface WarehouseBackedEntity<Name extends string, P extends Properties, R ext
  * The data access methods delegate to {@link OntologyReads} and {@link OntologyWrites}, which the
  * ontology service provides to actions.
  */
-export declare function entity<const Name extends string, const P extends Properties, const R extends Relationships = NoRelationships, const M extends Measures = Readonly<Record<never, never>>>(name: Name, definition: EntityDefinition<P, R> & {
+export declare function entity<const Name extends string, const P extends Properties, const R extends Relationships = NoRelationships, const M extends Measures = NoMeasures>(name: Name, definition: EntityDefinition<P, R> & {
     readonly source: WarehouseSource;
     readonly measures?: M;
 }): WarehouseBackedEntity<Name, P, R, M>;
-export declare function entity<const Name extends string, const P extends Properties, const R extends Relationships = NoRelationships>(name: Name, definition: EntityDefinition<P, R>): DraftEntity<Name, P, R>;
+export declare function entity<const Name extends string, const P extends Properties, const R extends Relationships = NoRelationships, const M extends Measures = NoMeasures>(name: Name, definition: EntityDefinition<P, R, M>): DraftEntity<Name, P, R, M>;
 export declare function isEntity(value: unknown): value is AnyEntity;
 export {};

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { entity, isEntity } from "./entity.js";
 export type { ActionsBuilder, AnyEntity, AnyStoredEntity, CreateValues, DraftEntity, Entity, EntityDefinition, EntityRecord, IndexDefinition, IndexField, NoActions, Properties, RecordRef, Relationships, SystemFields, UpdateValues, } from "./entity.js";
 export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
 export type { ActionError } from "./errors.js";
-export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
+export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, isValueMatched, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
 export type { SystemProperty } from "./names.js";
 export { check, defineOntology } from "./ontology.js";
@@ -52,11 +52,14 @@ export type { DeriveApiOptions, OntologyApi } from "./service/api.js";
 export { CurrentPrincipal } from "./service/authentication.js";
 export { deployedConnections, LocalConnectionContextError, localConnections, OIDC_TOKEN_HEADER, parseLocalConnectionContext, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./service/connections.js";
 export type { ConnectionAudit, ConnectionTransportFactory, LocalConnection, LocalConnectionContext, } from "./service/connections.js";
-export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
+export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } from "./service/config.js";
 export type { ActionCommitted, AfterCommitHook, NeonAuthEnvironment, OntologyEnvironment, OntologyServiceConfig, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
-export type { GeneratedActionsProvider, IdentityProvider, OAuthClient, OAuthClientAuthMethod, OAuthGrant, OAuthRequest, OAuthStore, OAuthToken, OAuthTokenKind, OntologyServiceRuntime, RunActionInput, SignInIdentity, UsedOAuthToken, } from "./service/runtime-contract.js";
+export type { AgentIdentity, AgentMember, AgentPairing, AgentStore, GeneratedActionsProvider, IdentityProvider, OAuthClient, OAuthClientAuthMethod, OAuthGrant, OAuthRequest, OAuthStore, OAuthToken, OAuthTokenKind, OntologyServiceRuntime, RunActionInput, SignInIdentity, UsedOAuthToken, } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+export { AGENT_PATH } from "./service/agent/server.js";
+export { ACT_AS_HEADER } from "./service/runtime-identity.js";
+export type { RuntimeIdentityConfig } from "./service/runtime-identity.js";
 export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
 export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";
 export type { OntologyService } from "./service/service.js";

package/dist/index.js

@@ -6,7 +6,7 @@ export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connectio
 export { Diagnostic, DIAGNOSTIC_CODES, formatDiagnostics, InvalidOntology } from "./diagnostics.js";
 export { entity, isEntity } from "./entity.js";
 export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
-export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
+export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, isValueMatched, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
 export { check, defineOntology } from "./ontology.js";
 export { DEFAULT_MEMBER_PERMISSIONS, generatedActionPermissions, grants, isAllowed, parsePermission, permissionsOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
@@ -31,9 +31,12 @@ export { makeOntologyRuntime } from "./runtime/sql-runtime.js";
 export { BASE_PATH, deriveApi } from "./service/api.js";
 export { CurrentPrincipal } from "./service/authentication.js";
 export { deployedConnections, LocalConnectionContextError, localConnections, OIDC_TOKEN_HEADER, parseLocalConnectionContext, readLocalConnectionContext, RUNTIME_CONTEXT_FD, } from "./service/connections.js";
-export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
+export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, RUNTIME_IDENTITY_ENVIRONMENT_VARIABLES, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+// The app's own agent: pairing channel accounts with members, and acting as them.
+export { AGENT_PATH } from "./service/agent/server.js";
+export { ACT_AS_HEADER } from "./service/runtime-identity.js";
 // The MCP server the service serves beside the HTTP API.
 export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
 export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";

package/dist/manifest.d.ts

@@ -7,9 +7,14 @@ import { type SignInOptions, type SignInPolicy } 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 declare const MANIFEST_VERSION = 4;
+export declare const MANIFEST_VERSION = 6;
 /** The phrase used for a direction the author did not phrase. */
 export declare const DEFAULT_PHRASE = "has";
 export declare const SelectOptionManifest: Schema.Struct<{
@@ -47,6 +52,10 @@ export type PropertyManifest = typeof PropertyManifest.Type;
  * from `to`, `inverse` and the second `phrase`.
  */
 export declare 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.
+     */
     readonly on: Schema.optionalKey<Schema.Struct<{
         readonly property: Schema.String;
         readonly targetProperty: Schema.String;
@@ -55,9 +64,12 @@ export declare const RelationshipManifest: Schema.Struct<{
     readonly to: Schema.String;
     readonly inverse: Schema.String;
     readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
-    /** `rel.one` only. */
+    /** `rel.one` between stored entities only. */
     readonly 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.
+     */
     readonly onDelete: Schema.optionalKey<Schema.Literals<readonly ["setNull", "cascade", "restrict"]>>;
     /** `rel.many` only. */
     readonly ordered: Schema.optionalKey<Schema.Boolean>;
@@ -66,6 +78,14 @@ export declare const RelationshipManifest: Schema.Struct<{
     readonly description: Schema.String;
 }>;
 export type RelationshipManifest = typeof RelationshipManifest.Type;
+/**
+ * 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 declare function isValueMatched(relationship: {
+    readonly on?: unknown;
+}): boolean;
 export declare const IndexManifest: Schema.Struct<{
     readonly properties: Schema.$Array<Schema.String>;
     readonly unique: Schema.Boolean;
@@ -157,6 +177,10 @@ export declare const EntityManifest: Schema.Struct<{
         }>>>;
     }>>;
     readonly relationships: Schema.$Array<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.
+         */
         readonly on: Schema.optionalKey<Schema.Struct<{
             readonly property: Schema.String;
             readonly targetProperty: Schema.String;
@@ -165,9 +189,12 @@ export declare const EntityManifest: Schema.Struct<{
         readonly to: Schema.String;
         readonly inverse: Schema.String;
         readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
-        /** `rel.one` only. */
+        /** `rel.one` between stored entities only. */
         readonly 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.
+         */
         readonly onDelete: Schema.optionalKey<Schema.Literals<readonly ["setNull", "cascade", "restrict"]>>;
         /** `rel.many` only. */
         readonly ordered: Schema.optionalKey<Schema.Boolean>;
@@ -240,7 +267,7 @@ export declare const SignInManifest: Schema.Struct<{
     readonly policy: Schema.String;
 }>;
 export type SignInManifest = typeof SignInManifest.Type;
-/** 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 declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
     readonly entities: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
         readonly properties: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
@@ -283,7 +310,7 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
             readonly to: Schema.String;
             readonly inverse: Schema.String;
             readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
-            /** `rel.one` only. */
+            /** `rel.one` between stored entities only. */
             readonly optional: Schema.optionalKey<Schema.Boolean>;
             /** `rel.many` only. */
             readonly ordered: Schema.optionalKey<Schema.Boolean>;
@@ -426,7 +453,7 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly to: Schema.String;
             readonly inverse: Schema.String;
             readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
-            /** `rel.one` only. */
+            /** `rel.one` between stored entities only. */
             readonly optional: Schema.optionalKey<Schema.Boolean>;
             /** `rel.many` only. */
             readonly ordered: Schema.optionalKey<Schema.Boolean>;
@@ -577,6 +604,10 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             }>>>;
         }>>;
         readonly relationships: Schema.$Array<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.
+             */
             readonly on: Schema.optionalKey<Schema.Struct<{
                 readonly property: Schema.String;
                 readonly targetProperty: Schema.String;
@@ -585,9 +616,12 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly to: Schema.String;
             readonly inverse: Schema.String;
             readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
-            /** `rel.one` only. */
+            /** `rel.one` between stored entities only. */
             readonly 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.
+             */
             readonly onDelete: Schema.optionalKey<Schema.Literals<readonly ["setNull", "cascade", "restrict"]>>;
             /** `rel.many` only. */
             readonly ordered: Schema.optionalKey<Schema.Boolean>;
@@ -661,6 +695,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
         readonly id: string;
         readonly description: string;
         readonly label: string;
+        readonly title: string;
         readonly actions: readonly {
             readonly name: string;
             readonly description: string;
@@ -674,18 +709,15 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];
-        readonly title: string;
         readonly properties: readonly {
             readonly optional: boolean;
             readonly name: string;
             readonly label: string;
-            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json" | "blob";
+            readonly type: "number" | "boolean" | "text" | "email" | "url" | "integer" | "date" | "timestamp" | "select" | "json" | "blob";
             readonly unique: boolean;
             readonly managed: boolean;
             readonly column?: string | undefined;
             readonly description?: string | undefined;
-            readonly default?: Schema.Json | undefined;
-            readonly scope?: readonly string[] | undefined;
             readonly maxLength?: number | undefined;
             readonly min?: number | undefined;
             readonly max?: number | undefined;
@@ -694,6 +726,8 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
                 readonly label: string;
                 readonly description: string;
             }[] | undefined;
+            readonly scope?: readonly string[] | undefined;
+            readonly default?: Schema.Json | undefined;
             readonly renamedFrom?: string | undefined;
             readonly display?: string | undefined;
             readonly accept?: readonly string[] | undefined;
@@ -707,11 +741,11 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly to: string;
             readonly inverse: string;
             readonly optional?: boolean | undefined;
+            readonly onDelete?: "setNull" | "cascade" | "restrict" | undefined;
             readonly on?: {
                 readonly property: string;
                 readonly targetProperty: string;
             } | undefined;
-            readonly onDelete?: "setNull" | "cascade" | "restrict" | undefined;
             readonly ordered?: boolean | undefined;
         }[];
         readonly indexes: readonly {
@@ -720,6 +754,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
         }[];
         readonly plural: string;
         readonly builtIn: boolean;
+        readonly renamedFrom?: string | undefined;
         readonly source?: {
             readonly key: readonly string[];
             readonly asset: string;
@@ -733,7 +768,6 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly format: "currency" | "percent" | "decimal";
             readonly expression: Schema.Json;
         }[] | undefined;
-        readonly renamedFrom?: string | undefined;
         readonly guide?: string | undefined;
         readonly permissions?: {
             readonly read: string;
@@ -765,6 +799,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
         readonly id: string;
         readonly description: string;
         readonly label: string;
+        readonly title: string;
         readonly actions: readonly {
             readonly name: string;
             readonly description: string;
@@ -778,18 +813,15 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];
-        readonly title: string;
         readonly properties: readonly {
             readonly optional: boolean;
             readonly name: string;
             readonly label: string;
-            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json" | "blob";
+            readonly type: "number" | "boolean" | "text" | "email" | "url" | "integer" | "date" | "timestamp" | "select" | "json" | "blob";
             readonly unique: boolean;
             readonly managed: boolean;
             readonly column?: string | undefined;
             readonly description?: string | undefined;
-            readonly default?: Schema.Json | undefined;
-            readonly scope?: readonly string[] | undefined;
             readonly maxLength?: number | undefined;
             readonly min?: number | undefined;
             readonly max?: number | undefined;
@@ -798,6 +830,8 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
                 readonly label: string;
                 readonly description: string;
             }[] | undefined;
+            readonly scope?: readonly string[] | undefined;
+            readonly default?: Schema.Json | undefined;
             readonly renamedFrom?: string | undefined;
             readonly display?: string | undefined;
             readonly accept?: readonly string[] | undefined;
@@ -811,11 +845,11 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly to: string;
             readonly inverse: string;
             readonly optional?: boolean | undefined;
+            readonly onDelete?: "setNull" | "cascade" | "restrict" | undefined;
             readonly on?: {
                 readonly property: string;
                 readonly targetProperty: string;
             } | undefined;
-            readonly onDelete?: "setNull" | "cascade" | "restrict" | undefined;
             readonly ordered?: boolean | undefined;
         }[];
         readonly indexes: readonly {
@@ -824,6 +858,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
         }[];
         readonly plural: string;
         readonly builtIn: boolean;
+        readonly renamedFrom?: string | undefined;
         readonly source?: {
             readonly key: readonly string[];
             readonly asset: string;
@@ -837,7 +872,6 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly format: "currency" | "percent" | "decimal";
             readonly expression: Schema.Json;
         }[] | undefined;
-        readonly renamedFrom?: string | undefined;
         readonly guide?: string | undefined;
         readonly permissions?: {
             readonly read: string;