@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/federation.js

@@ -0,0 +1,222 @@
+import { randomUUID, createHash } from "node:crypto";
+import { Effect, Schema } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { makePrincipalUserWriter } from "./sql-runtime.js";
+import { lockSessionMember, resolvePrincipalById, resolvePrincipalByIdentity, } from "./principals.js";
+import { ensureSignInIdentity, liveSignInIdentities, makeIdentityWriter, NEON_AUTH_PROVIDER, OIDC_PROVIDER, USER_IDENTITY_TABLE, userOfAccount, } from "./user-identities.js";
+export const FEDERATION_TOKEN_PREFIX = "ssfs_";
+export const federationDigest = (value) => createHash("sha256").update(value).digest("hex");
+export const FederationSession = Schema.Struct({
+    hash: Schema.String,
+    userId: Schema.NullOr(Schema.String),
+    linkUserId: Schema.optionalKey(Schema.String),
+    issuer: Schema.String,
+    subject: Schema.String,
+    clientId: Schema.String,
+    generation: Schema.Int,
+    consentId: Schema.String,
+    sessionId: Schema.optionalKey(Schema.String),
+    environment: Schema.optionalKey(Schema.String),
+    deploymentId: Schema.optionalKey(Schema.String),
+    manifestDigest: Schema.optionalKey(Schema.String),
+    expiresAt: Schema.Number,
+});
+function decodeSession(value) {
+    const row = { ...value };
+    for (const key of ["sessionId", "environment", "deploymentId", "manifestDigest", "linkUserId"]) {
+        if (row[key] === null) {
+            delete row[key];
+        }
+    }
+    return Schema.decodeUnknownSync(FederationSession)(row);
+}
+export function sqlFederationStore(ontology, sql) {
+    const principal = (id) => resolvePrincipalById(ontology, sql, id).pipe(Effect.catchTag("PrincipalRejected", () => Effect.succeed(undefined)), Effect.orDie);
+    // Every binding is a `user_identity` record; `_user_identities` and the user's columns are still
+    // written beside it for earlier SDKs. See docs/workspace-user-identities.md.
+    const identityWriter = (action) => makeIdentityWriter(ontology, sql, {
+        action: `${USER_IDENTITY_TABLE}.${action}`,
+        actionId: randomUUID(),
+    });
+    const identity = (issuer, subject) => Effect.gen(function* () {
+        const userId = yield* userOfAccount(sql, { provider: OIDC_PROVIDER, issuer, subject });
+        return userId ? yield* principal(userId) : undefined;
+    }).pipe(Effect.orDie);
+    return {
+        identity,
+        principal,
+        emailIdentity: (subject) => userOfAccount(sql, { provider: NEON_AUTH_PROVIDER, issuer: null, subject }).pipe(Effect.flatMap((userId) => (userId ? principal(userId) : Effect.succeed(undefined))), Effect.orDie),
+        // A revoked binding is known too: it never falls back to the email of the account. So is a link
+        // an earlier SDK made only in `_user_identities` since the last copy: sign-in fails closed until
+        // the next migration copies it, instead of matching another member by email.
+        bindingExists: (issuer, subject) => sql
+            .unsafe(`SELECT 1 FROM "${USER_IDENTITY_TABLE}" WHERE "provider" = $1 AND "issuer" = $2 ` +
+            `AND "subject" = $3 UNION ALL ` +
+            `SELECT 1 FROM "_user_identities" WHERE "issuer" = $2 AND "subject" = $3 LIMIT 1`, [OIDC_PROVIDER, issuer, subject])
+            .pipe(Effect.map((rows) => rows.length > 0), Effect.orDie),
+        enroll: (claims) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock_shared(hashtextextended('segmentstream.ontology.migration', 0))`);
+            const [catalog] = yield* sql.unsafe(`SELECT manifest->'sign_in'->'browser'->'methods' AS methods FROM "_ontology" WHERE id`);
+            if (Array.isArray(catalog?.methods) && !catalog.methods.includes("segmentstream")) {
+                return undefined;
+            }
+            // Serialize enrollment for a pairwise identity; the primary identity resolver locks invitations.
+            yield* sql.unsafe(`SELECT pg_advisory_xact_lock(hashtextextended($1, 0))`, [
+                JSON.stringify([claims.issuer, claims.subject]),
+            ]);
+            const existing = yield* identity(claims.issuer, claims.subject);
+            if (existing) {
+                return existing;
+            }
+            // An earlier SDK linked the account since the last copy: never enroll it as someone else.
+            const [legacy] = yield* sql.unsafe(`SELECT 1 FROM "_user_identities" WHERE "issuer" = $1 AND "subject" = $2`, [claims.issuer, claims.subject]);
+            if (legacy) {
+                return undefined;
+            }
+            if (claims.email) {
+                const [invited] = yield* sql.unsafe(`SELECT id::text FROM "user" WHERE lower(email) = lower($1) FOR UPDATE`, [claims.email]);
+                if (invited) {
+                    const [binding] = yield* sql.unsafe(`SELECT 1 FROM "${USER_IDENTITY_TABLE}" WHERE "user_id" = $1::uuid ` +
+                        `AND "provider" = $2 AND "revoked_at" IS NULL`, [invited.id, OIDC_PROVIDER]);
+                    if (binding) {
+                        return undefined;
+                    }
+                }
+            }
+            const member = yield* resolvePrincipalByIdentity(ontology, {
+                identityProvider: `oidc:${claims.issuer}`,
+                identitySubject: claims.subject,
+                ...(claims.email === undefined ? {} : { email: claims.email }),
+                ...(claims.name === undefined ? {} : { name: claims.name }),
+            }).pipe(Effect.provideService(SqlClient.SqlClient, sql), Effect.catchTag("PrincipalRejected", () => Effect.succeed(undefined)));
+            if (!member) {
+                return undefined;
+            }
+            // @legacy identities.legacy-stores-dual-write
+            yield* sql.unsafe(`INSERT INTO "_user_identities" (issuer, subject, user_id)
+               VALUES ($1, $2, $3::uuid) ON CONFLICT (issuer, subject) DO NOTHING`, [claims.issuer, claims.subject, member.id]);
+            // Sign-in recorded the identity with the member; this keeps it if the member was found.
+            yield* ensureSignInIdentity(identityWriter("enroll"), sql, {
+                provider: OIDC_PROVIDER,
+                issuer: claims.issuer,
+                subject: claims.subject,
+                userId: member.id,
+                origin: "sign_in",
+            });
+            return yield* identity(claims.issuer, claims.subject);
+        }))
+            .pipe(Effect.orDie),
+        linkEmail: (userId, subject, email) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* sql.unsafe(`SELECT id FROM "user" WHERE id = $1::uuid FOR UPDATE`, [userId]);
+            yield* lockSessionMember(sql, userId);
+            const proof = yield* principal(userId);
+            if (!proof) {
+                return undefined;
+            }
+            const [row] = yield* sql.unsafe(`SELECT email FROM "user" WHERE id = $1::uuid FOR UPDATE`, [userId]);
+            if (!email?.trim() ||
+                !row?.email?.trim() ||
+                email.trim().toLowerCase() !== row.email.trim().toLowerCase()) {
+                return "email_identity_mismatch";
+            }
+            // Email links to a member who signs in with SegmentStream only, or with this account.
+            const held = yield* liveSignInIdentities(sql, userId);
+            if (held.some((identity) => identity.provider !== OIDC_PROVIDER &&
+                !(identity.provider === NEON_AUTH_PROVIDER && identity.subject === subject))) {
+                return undefined;
+            }
+            const owner = yield* userOfAccount(sql, {
+                provider: NEON_AUTH_PROVIDER,
+                issuer: null,
+                subject,
+            });
+            if (owner !== undefined && owner !== userId) {
+                return undefined;
+            }
+            const actionId = randomUUID();
+            yield* makePrincipalUserWriter(ontology, sql, {
+                action: "user.link_email",
+                actionId,
+            }).update(userId, { identity_provider: NEON_AUTH_PROVIDER, identity_subject: subject });
+            yield* ensureSignInIdentity(makeIdentityWriter(ontology, sql, {
+                action: `${USER_IDENTITY_TABLE}.link_email`,
+                actionId,
+            }), sql, { provider: NEON_AUTH_PROVIDER, issuer: null, subject, userId, origin: "link" });
+            return yield* principal(userId);
+        }))
+            .pipe(Effect.orDie),
+        link: (issuer, subject, proofUserId) => sql
+            .withTransaction(Effect.gen(function* () {
+            yield* lockSessionMember(sql, proofUserId);
+            yield* sql.unsafe(`SELECT id FROM "user" WHERE id = $1::uuid FOR UPDATE`, [
+                proofUserId,
+            ]);
+            const proof = yield* principal(proofUserId);
+            if (!proof || proof.kind !== "member") {
+                return undefined;
+            }
+            // The legacy insert waits for a concurrent link of the account, which then holds it.
+            // @legacy identities.legacy-stores-dual-write
+            yield* sql.unsafe(`INSERT INTO "_user_identities" (issuer, subject, user_id)
+        VALUES ($1, $2, $3::uuid) ON CONFLICT (issuer, subject) DO NOTHING`, [issuer, subject, proofUserId]);
+            const [bound] = yield* sql.unsafe(`SELECT user_id::text FROM "_user_identities" WHERE issuer = $1 AND subject = $2`, [issuer, subject]);
+            if (bound?.user_id === proofUserId) {
+                yield* ensureSignInIdentity(identityWriter("link"), sql, {
+                    provider: OIDC_PROVIDER,
+                    issuer,
+                    subject,
+                    userId: proofUserId,
+                    origin: "link",
+                });
+            }
+            const linked = yield* identity(issuer, subject);
+            return linked?.id === proofUserId ? linked : undefined;
+        }))
+            .pipe(Effect.orDie),
+        save: (session) => sql
+            .withTransaction(Effect.gen(function* () {
+            if (session.userId !== null) {
+                yield* lockSessionMember(sql, session.userId);
+            }
+            yield* sql.unsafe(`INSERT INTO "_federation_sessions"
+      (hash, user_id, issuer, subject, client_id, generation, consent_id, expires_at,
+       session_id, environment, deployment_id, manifest_digest, link_user_id)
+      VALUES ($1, $2::uuid, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::uuid)`, [
+                session.hash,
+                session.userId,
+                session.issuer,
+                session.subject,
+                session.clientId,
+                session.generation,
+                session.consentId,
+                session.expiresAt,
+                session.sessionId ?? null,
+                session.environment ?? null,
+                session.deploymentId ?? null,
+                session.manifestDigest ?? null,
+                session.linkUserId ?? null,
+            ]);
+        }))
+            .pipe(Effect.asVoid, Effect.orDie),
+        read: (hash) => sql
+            .unsafe(`SELECT hash, user_id::text AS "userId", issuer, subject, client_id AS "clientId",
+      generation, consent_id AS "consentId", expires_at::double precision AS "expiresAt",
+      session_id AS "sessionId", environment, deployment_id AS "deploymentId",
+      manifest_digest AS "manifestDigest", link_user_id::text AS "linkUserId"
+      FROM "_federation_sessions" WHERE hash = $1 AND expires_at > extract(epoch FROM now()) * 1000`, [hash])
+            .pipe(Effect.map((rows) => (rows[0] ? decodeSession(rows[0]) : undefined)), Effect.orDie),
+        consumePending: (hash) => sql
+            .unsafe(`DELETE FROM "_federation_sessions"
+      WHERE hash = $1 AND user_id IS NULL AND expires_at > extract(epoch FROM now()) * 1000
+      RETURNING hash, user_id::text AS "userId", issuer, subject, client_id AS "clientId",
+        generation, consent_id AS "consentId", expires_at::double precision AS "expiresAt",
+      session_id AS "sessionId", environment, deployment_id AS "deploymentId",
+      manifest_digest AS "manifestDigest", link_user_id::text AS "linkUserId"`, [hash])
+            .pipe(Effect.map((rows) => (rows[0] ? decodeSession(rows[0]) : undefined)), Effect.orDie),
+        remove: (hash) => sql
+            .unsafe(`DELETE FROM "_federation_sessions" WHERE hash = $1`, [hash])
+            .pipe(Effect.asVoid, Effect.orDie),
+    };
+}

package/dist/runtime/files.d.ts

@@ -0,0 +1,39 @@
+import { Context, Effect, Schema } from "effect";
+import { NotFound, PermissionDenied } from "../errors.js";
+import type { OntologyManifest } from "../manifest.js";
+import type { OntologyReads, Principal } from "../runtime.js";
+export interface FileReference {
+    readonly entity: string;
+    readonly id: string;
+    readonly property?: string;
+}
+declare const UnsupportedFile_base: Schema.Class<UnsupportedFile, Schema.TaggedStruct<"UnsupportedFile", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class UnsupportedFile extends UnsupportedFile_base {
+}
+/** Resolve only declared file properties, checking permission before reading any record. */
+export declare function resolveFileRecord(input: {
+    readonly manifest: OntologyManifest;
+    readonly reads: Pick<OntologyReads["Service"], "get">;
+    readonly principal: Principal;
+    readonly reference: FileReference;
+}): Effect.Effect<{
+    entity: string;
+    id: string;
+    property: string;
+    file: {
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    };
+}, PermissionDenied | NotFound | UnsupportedFile, never>;
+declare const AgentFileRecords_base: Context.ServiceClass<AgentFileRecords, "@segmentstream/ontology/AgentFileRecords", {
+    readonly resolve: (reference: FileReference, principal: Principal) => ReturnType<typeof resolveFileRecord>;
+}>;
+/** File validation in an action's prepare, bound to its ontology and read runtime. */
+export declare class AgentFileRecords extends AgentFileRecords_base {
+}
+export {};

package/dist/runtime/files.js

@@ -0,0 +1,44 @@
+import { Context, Effect, Schema } from "effect";
+import { BlobValue } from "../blob.js";
+import { NotFound, PermissionDenied } from "../errors.js";
+import { isAllowed, permissionOf, READ_VERB } from "../permissions.js";
+export class UnsupportedFile extends Schema.TaggedError()("UnsupportedFile", {
+    message: Schema.String,
+}) {
+}
+/** Resolve only declared file properties, checking permission before reading any record. */
+export function resolveFileRecord(input) {
+    return Effect.gen(function* () {
+        const { entity: entityName, id, property: propertyName } = input.reference;
+        const permission = permissionOf(entityName, READ_VERB);
+        if (!isAllowed(permission, input.principal)) {
+            return yield* new PermissionDenied({ permission, message: "The file requires read access." });
+        }
+        const entity = input.manifest.entities.find((candidate) => candidate.name === entityName);
+        if (entity === undefined) {
+            return yield* new NotFound({ entity: entityName, id, message: "File record not found." });
+        }
+        const properties = entity.properties.filter((candidate) => candidate.type === "blob");
+        const property = propertyName === undefined
+            ? properties.length === 1
+                ? properties[0]
+                : undefined
+            : properties.find((candidate) => candidate.name === propertyName);
+        if (property === undefined) {
+            return yield* new UnsupportedFile({
+                message: "Name a file property; the entity must have exactly one when property is omitted.",
+            });
+        }
+        const record = yield* input.reads.get({ entity: entityName, id });
+        const file = record[property.name];
+        if (file === null || file === undefined) {
+            return yield* new NotFound({ entity: entityName, id, message: "File not found." });
+        }
+        // Runtime records are decoded already; malformed stored metadata is an operator failure.
+        const decoded = yield* Schema.decodeUnknownEffect(BlobValue)(file).pipe(Effect.orDie);
+        return { entity: entityName, id, property: property.name, file: decoded };
+    });
+}
+/** File validation in an action's prepare, bound to its ontology and read runtime. */
+export class AgentFileRecords extends Context.Service()("@segmentstream/ontology/AgentFileRecords") {
+}

package/dist/runtime/generated-actions.d.ts

@@ -0,0 +1,37 @@
+import { Schema } from "effect";
+import { type AnyAction } from "../action.js";
+import type { JsonSchemaObject } from "../analyze.js";
+import type { Ontology } from "../ontology.js";
+/** An entity's generated actions by name. */
+export type GeneratedActions = Readonly<Record<string, AnyAction>>;
+/** `upsert_by_email`. */
+export declare function upsertActionName(property: string): string;
+/**
+ * The actions generated for an entity: `create`, `update` (without `managed` properties), `delete`,
+ * `upsert_by_<property>` per unique property, and `link`/`unlink` when it declares a `rel.many`
+ * whose target keeps its generated writes. An entity that declares `writes: "actions"` has none. They
+ * are ordinary actions and run through the same pipeline. Their `permission` is unset: each requires
+ * the permission named after it (`lead:create`), and `upsert_by_<property>` both `create` and `update`,
+ * as `generatedActionPermissions` says. The built-in User has only its member management: `invite`,
+ * `grant_roles`, `revoke_roles`, `deactivate` and `reactivate`; members are otherwise created by
+ * sign-in and services by the app or the CLI. The built-in agent chat has only `update`, for its
+ * unmanaged properties: the agent records chats and their members.
+ */
+export declare function generatedActions(ontology: Ontology, entityName: string): GeneratedActions;
+/**
+ * Why a generated write is missing when its entity declares `writes: "actions"`, naming the
+ * authored actions that write it instead; `undefined` for any other unknown action.
+ */
+export declare function writesOnlyThroughActions(ontology: Ontology, entityName: string, actionName: string): string | undefined;
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export declare function actionInputJsonSchema(input: Schema.Top): JsonSchemaObject;
+/** A generated action, described as the manifest describes authored ones. */
+export interface GeneratedActionManifest {
+    readonly name: string;
+    readonly description: string;
+    /** Every permission the action requires: one, or `create` and `update` for `upsert_by_<property>`. */
+    readonly permissions: ReadonlyArray<string>;
+    readonly input: JsonSchemaObject;
+}
+/** The generated actions described as the manifest describes authored ones, for catalogs and MCP. */
+export declare function generatedActionManifests(ontology: Ontology, entityName: string): ReadonlyArray<GeneratedActionManifest>;

package/dist/runtime/generated-actions.js

@@ -0,0 +1,307 @@
+import { Effect, Schema } from "effect";
+import { uploadInput, BLOB_UPLOAD_ANNOTATION } from "../blob.js";
+import { action } from "../action.js";
+import { GENERATED_UPSERT_PREFIX, MEMBER_ROLE } from "../names.js";
+import { generatedActionPermissions } from "../permissions.js";
+import { p, REFERENCE_ANNOTATION } from "../property.js";
+import { isCalendarDate, isInstant } from "../query.js";
+import { OntologyWrites } from "../runtime.js";
+import { User } from "../user.js";
+import { entityModel, ontologyModel, propertyValueSchema, } from "./model.js";
+/** Generated actions, built once per ontology and entity. */
+const builtActions = new WeakMap();
+function article(word) {
+    return /^[aeiou]/i.test(word) ? `an ${word}` : `a ${word}`;
+}
+/** `upsert_by_email`. */
+export function upsertActionName(property) {
+    return `${GENERATED_UPSERT_PREFIX}${property}`;
+}
+/** A property's value schema, refusing days that do not exist, which PostgreSQL would reject. */
+function propertyInput(field, entity) {
+    if (field.storage === "blob") {
+        return uploadInput(entity.name, field.name);
+    }
+    const schema = propertyValueSchema(field.property);
+    if (field.storage === "date") {
+        return schema.check(Schema.makeFilter((value) => isCalendarDate(value) || "Expected a date that exists"));
+    }
+    if (field.storage === "timestamp") {
+        return schema.check(Schema.makeFilter((value) => isInstant(value) || "Expected an instant that exists"));
+    }
+    return schema;
+}
+function reference(link, description) {
+    return p.ref(link.target, { description });
+}
+function relationshipDescription(entity, link) {
+    const declaration = entity.manifest.relationships.find((candidate) => candidate.name === link.name);
+    return declaration?.description ?? `The id of a ${link.target} record.`;
+}
+/**
+ * Whether a `rel.many` keeps its generated writes: not when its target declares `writes: "actions"`,
+ * whose links change only through authored actions on either side.
+ */
+function generatedJoin(ontology, link) {
+    return ontology.manifest.entities.find((e) => e.name === link.target)?.writes !== "actions";
+}
+/** Input fields for the values of a record: properties, `rel.one` ids and `rel.many` id lists. */
+function valueFields(ontology, entity, { mode }) {
+    const fields = {};
+    for (const field of entity.fields) {
+        if (field.source !== "property") {
+            continue;
+        }
+        const definition = field.property?.definition;
+        if (mode === "update" && definition?.managed === true) {
+            continue;
+        }
+        const value = propertyInput(field, entity);
+        const required = mode === "create" &&
+            !field.nullable &&
+            !(definition !== undefined && "default" in definition);
+        fields[field.name] = required
+            ? value
+            : Schema.optionalKey(field.nullable ? Schema.NullOr(value) : value);
+    }
+    for (const link of entity.links.values()) {
+        if (link.via === "key") {
+            const target = reference(link, relationshipDescription(entity, link));
+            const required = mode === "create" && !link.optional;
+            fields[link.name] = required
+                ? target
+                : Schema.optionalKey(link.optional ? Schema.NullOr(target) : target);
+        }
+        else if (link.via === "join" &&
+            !link.inverse &&
+            !entity.resolved.builtIn &&
+            generatedJoin(ontology, link)) {
+            fields[link.name] = Schema.optionalKey(Schema.Array(reference(link, `The id of a ${link.target} record.`)).annotate({
+                description: `${relationshipDescription(entity, link)} The list replaces the current links.`,
+            }));
+        }
+    }
+    return fields;
+}
+function joinLinks(ontology, entity) {
+    return [...entity.links.values()]
+        .filter((link) => link.via === "join" && !link.inverse && generatedJoin(ontology, link))
+        .map((link) => link.name);
+}
+/** Values to write, without the keys a generated input adds around them. */
+function valuesOf(input, omit) {
+    return Object.fromEntries(Object.entries(input).filter(([key]) => !omit.includes(key)));
+}
+/**
+ * The actions generated for an entity: `create`, `update` (without `managed` properties), `delete`,
+ * `upsert_by_<property>` per unique property, and `link`/`unlink` when it declares a `rel.many`
+ * whose target keeps its generated writes. An entity that declares `writes: "actions"` has none. They
+ * are ordinary actions and run through the same pipeline. Their `permission` is unset: each requires
+ * the permission named after it (`lead:create`), and `upsert_by_<property>` both `create` and `update`,
+ * as `generatedActionPermissions` says. The built-in User has only its member management: `invite`,
+ * `grant_roles`, `revoke_roles`, `deactivate` and `reactivate`; members are otherwise created by
+ * sign-in and services by the app or the CLI. The built-in agent chat has only `update`, for its
+ * unmanaged properties: the agent records chats and their members.
+ */
+export function generatedActions(ontology, entityName) {
+    const declared = ontology.manifest.entities.find((e) => e.name === entityName);
+    // A warehouse-backed entity has no writes; one with `writes: "actions"` only authored ones.
+    if (declared?.source !== undefined || declared?.writes === "actions") {
+        return {};
+    }
+    const byEntity = builtActions.get(ontology) ?? new Map();
+    const actions = byEntity.get(entityName) ?? buildGeneratedActions(ontology, entityName);
+    byEntity.set(entityName, actions);
+    builtActions.set(ontology, byEntity);
+    return actions;
+}
+const GENERATED_WRITES = new Set(["create", "update", "delete", "link", "unlink"]);
+/**
+ * Why a generated write is missing when its entity declares `writes: "actions"`, naming the
+ * authored actions that write it instead; `undefined` for any other unknown action.
+ */
+export function writesOnlyThroughActions(ontology, entityName, actionName) {
+    const declared = ontology.manifest.entities.find((candidate) => candidate.name === entityName);
+    const generatedName = GENERATED_WRITES.has(actionName) || actionName.startsWith(GENERATED_UPSERT_PREFIX);
+    if (declared?.writes !== "actions" || !generatedName) {
+        return undefined;
+    }
+    const authored = declared.actions.map((action) => action.name);
+    return (`${entityName} declares writes: "actions", so it has no generated ${actionName}; only its ` +
+        `own actions write its records` +
+        (authored.length > 0 ? `: ${authored.join(", ")}.` : ", and it declares none."));
+}
+/** A role a member may be granted: one the ontology declares, never the implicit `member`. */
+function grantableRole(ontology) {
+    const declared = ontology.roles
+        .map((candidate) => candidate.name)
+        .filter((name) => name !== MEMBER_ROLE);
+    return declared.length > 0
+        ? Schema.Literals(declared)
+        : Schema.String.check(Schema.makeFilter(() => "Expected a role of the ontology, which declares none"));
+}
+/** A role to revoke: any assigned role, including one the ontology no longer declares. */
+const revocableRole = Schema.String.check(Schema.makeFilter((role) => role !== MEMBER_ROLE || `${MEMBER_ROLE} is held by every active member and is never revoked`));
+/**
+ * The built-in user's actions: inviting a member and changing a member's roles and activation, each
+ * through the runtime's member writes, which the `User` handle and the console share. Each returns
+ * the user, with its roles. A service is no member: its roles come with its API key.
+ */
+function memberActions(ontology, entity) {
+    const label = entity.label.toLowerCase();
+    const member = (verb) => p.ref(entity.name, { description: `The member to ${verb}.` });
+    const roles = Schema.Array(grantableRole(ontology)).annotate({
+        description: "Roles the ontology declares. Every member holds member, which is never listed.",
+    });
+    return {
+        invite: action({
+            description: `Invite a member: create a ${label} for an email no ${label} has, with roles. ` +
+                "The member is linked to it at their first sign-in.",
+            input: Schema.Struct({
+                email: p.email({ description: "The address the member signs in with." }),
+                name: Schema.optionalKey(p.text({ description: "The name shown in the app; the email when omitted." })),
+                roles: Schema.optionalKey(roles),
+            }),
+            hints: { destructive: false, idempotent: false },
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.inviteUser({
+                email: input.email,
+                name: input.name,
+                roles: input.roles,
+            })),
+        }),
+        grant_roles: action({
+            description: "Grant roles to a member; roles the member holds stay as they are.",
+            input: Schema.Struct({ id: member("grant the roles to"), roles }),
+            hints: { destructive: false, idempotent: true },
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.grantUserRoles({
+                id: input.id,
+                roles: input.roles,
+            })),
+        }),
+        revoke_roles: action({
+            description: "Revoke roles from a member, or every role with all; roles the member does not hold are " +
+                "ignored. Give roles or all, not both.",
+            input: Schema.Struct({
+                id: member("revoke the roles from"),
+                roles: Schema.optionalKey(Schema.Array(revocableRole).annotate({ description: "The roles to revoke." })),
+                all: Schema.optionalKey(Schema.Literal(true).annotate({ description: "Revoke every role the member holds." })),
+            }).check(Schema.makeFilter((input) => (input.roles === undefined) !== (input.all === undefined) ||
+                "Expected roles or all: true, not both")),
+            hints: { destructive: true, idempotent: true },
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.revokeUserRoles({
+                id: input.id,
+                roles: input.all === true ? "all" : input.roles,
+            })),
+        }),
+        deactivate: action({
+            description: "Deactivate a member: they can no longer sign in or run actions, and their sessions end. " +
+                "Their roles and history stay.",
+            input: Schema.Struct({ id: member("deactivate") }),
+            hints: { destructive: true, idempotent: true },
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.setUserActive({ id: input.id, active: false })),
+        }),
+        reactivate: action({
+            description: "Reactivate a deactivated member, with the roles they held.",
+            input: Schema.Struct({ id: member("reactivate") }),
+            hints: { destructive: false, idempotent: true },
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.setUserActive({ id: input.id, active: true })),
+        }),
+    };
+}
+function buildGeneratedActions(ontology, entityName) {
+    const entity = entityModel(ontologyModel(ontology), entityName);
+    if (entity.resolved.builtIn && entity.name === User.name) {
+        return memberActions(ontology, entity);
+    }
+    if (entity.resolved.builtIn && entity.resolved.permissions.update === undefined) {
+        return {};
+    }
+    const label = entity.label.toLowerCase();
+    const id = (verb) => p.ref(entityName, { description: `The ${label} to ${verb}.` });
+    const managed = entity.fields
+        .filter((field) => field.property?.definition.managed === true)
+        .map((field) => field.name);
+    const update = action({
+        description: `Change ${article(label)}'s properties and relationships; omitted values stay as they are.` +
+            (managed.length > 0 ? ` ${managed.join(", ")} change only through other actions.` : ""),
+        input: Schema.Struct({
+            id: id("change"),
+            ...valueFields(ontology, entity, { mode: "update" }),
+        }),
+        handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.update({
+            entity: entityName,
+            id: input.id,
+            values: valuesOf(input, ["id"]),
+        })),
+    });
+    if (entity.resolved.builtIn) {
+        return { update };
+    }
+    const actions = {
+        create: action({
+            description: `Create ${article(label)}.`,
+            input: Schema.Struct(valueFields(ontology, entity, { mode: "create" })),
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.create({ entity: entityName, values: input })),
+        }),
+        update,
+        delete: action({
+            description: `Delete ${article(label)}. Records that refer to it are deleted, cleared or protect it, ` +
+                "as each relationship's onDelete says.",
+            input: Schema.Struct({ id: id("delete") }),
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.delete({ entity: entityName, id: input.id })),
+        }),
+    };
+    for (const field of entity.fields) {
+        if (field.property?.definition.unique !== true) {
+            continue;
+        }
+        const name = upsertActionName(field.name);
+        actions[name] = action({
+            description: `Create ${article(label)}, or update the ${label} with the same ${field.name}.`,
+            input: Schema.Struct(valueFields(ontology, entity, { mode: "create" })),
+            handler: ({ input }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.upsertBy({ entity: entityName, property: field.name, values: input })),
+        });
+    }
+    const many = joinLinks(ontology, entity);
+    if (many.length > 0) {
+        const input = Schema.Struct({
+            relationship: Schema.Literals(many),
+            id: p.ref(entityName, { description: `The ${label}.` }),
+            target: Schema.String.annotate({
+                format: "uuid",
+                description: "The id of the related record.",
+            }),
+        });
+        actions.link = action({
+            description: `Link ${article(label)} to a record through ${many.join(" or ")}.`,
+            input,
+            handler: ({ input: { relationship, id: recordId, target } }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.link({ entity: entityName, relationship, id: recordId, targetId: target })),
+        });
+        actions.unlink = action({
+            description: `Remove a link of ${article(label)} through ${many.join(" or ")}.`,
+            input,
+            handler: ({ input: { relationship, id: recordId, target } }) => Effect.flatMap(OntologyWrites, (runtime) => runtime.unlink({ entity: entityName, relationship, id: recordId, targetId: target })),
+        });
+    }
+    return actions;
+}
+/** An action's input as JSON Schema (draft 2020-12), as the manifest describes authored actions. */
+export function actionInputJsonSchema(input) {
+    const document = Schema.toJsonSchemaDocument(input, {
+        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
+        onExcessProperty: "error",
+    });
+    const schema = document.schema;
+    return Object.keys(document.definitions).length === 0
+        ? schema
+        : { ...schema, $defs: document.definitions };
+}
+/** The generated actions described as the manifest describes authored ones, for catalogs and MCP. */
+export function generatedActionManifests(ontology, entityName) {
+    return Object.entries(generatedActions(ontology, entityName)).map(([name, generated]) => ({
+        name,
+        description: generated.description,
+        permissions: generatedActionPermissions(entityName, name),
+        input: actionInputJsonSchema(generated.input),
+    }));
+}