@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/entity.d.ts

@@ -0,0 +1,331 @@
+import type { BlobUpload, BlobValue } from "./blob.js";
+import { Effect, type Schema } from "effect";
+import { type EarlierQueryMetricsName, type EarlierFreshMetricQueryOptions, type EarlierMetricsField, type EarlierMetricsName } from "./legacy.js";
+import type { Metrics } from "./metric.js";
+import type { WarehouseSource } from "./source.js";
+import type { UserHandle } from "./user.js";
+import { type Action, type Actions } from "./action.js";
+import type { ConnectionError } from "./connection.js";
+import type { ActionError, ActionRejected, Conflict, NotFound, ScopeViolated } from "./errors.js";
+import { type AnyProperty } from "./property.js";
+import type { AnyRelationship, ManyRelationship, OneRelationship } from "./relationship.js";
+import { OntologyActions, OntologyReads, OntologyWrites, type BatchOptions, type BatchRecordResult, type BatchResult, type BatchSummaryResult, type FindOptions, type FreshMetricQueryOptions, type GetOptions, type ActionRunOptions, type UpsertResult } from "./runtime.js";
+export declare const EntityTypeId: unique symbol;
+export type Properties = {
+    readonly [name: string]: AnyProperty;
+};
+export type Relationships = {
+    readonly [name: string]: AnyRelationship;
+};
+export type NoRelationships = Readonly<Record<never, never>>;
+/** Fields every record has. They are never declared. */
+export interface SystemFields {
+    /** A UUID. */
+    readonly id: string;
+    /** ISO 8601 timestamps. */
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** The `user` who created or last updated the record; `null` when the platform wrote it. */
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+}
+/** A record id, or a record. */
+export type RecordRef = string | {
+    readonly id: string;
+};
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Unwrapped<S> = S extends Schema.optionalKey<infer Inner> ? Inner : S;
+type IsOptional<S> = S extends {
+    readonly "~type.optionality": "optional";
+} ? true : false;
+type ValueOf<S> = S extends {
+    readonly Type: infer T;
+} ? IsOptional<S> extends true ? T | null : T : never;
+type WriteValueOf<S> = NonNullable<ValueOf<S>> extends BlobValue ? BlobUpload | (null extends ValueOf<S> ? null : never) : ValueOf<S>;
+type RequiredOnCreate<S> = IsOptional<S> extends true ? false : S extends {
+    readonly "~ontology.defaulted": true;
+} ? false : true;
+type KeysWhere<T, Condition> = {
+    [K in keyof T]-?: T[K] extends Condition ? K : never;
+}[keyof T] & string;
+type RequiredPropertyKeys<P> = {
+    [K in keyof P]-?: RequiredOnCreate<P[K]> extends true ? K : never;
+}[keyof P] & string;
+/** 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;
+    } ? K : never;
+}[keyof P] & string;
+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`
+ * between stored entities.
+ */
+export type EntityRecord<P, R> = Simplify<SystemFields & {
+    readonly [K in keyof P]: ValueOf<P[K]>;
+} & RelationshipIds<R>>;
+/**
+ * Values for `create` and `upsertBy`. Properties without a default are required unless optional;
+ * relationships take ids by relationship name (`{ lead: lead.id }`), `rel.many` a list of ids.
+ */
+export type CreateValues<P, R> = Simplify<{
+    readonly [K in RequiredPropertyKeys<P>]: WriteValueOf<P[K]>;
+} & {
+    readonly [K in Exclude<keyof P, RequiredPropertyKeys<P>>]?: WriteValueOf<P[K]>;
+} & {
+    readonly [K in RequiredOneKeys<R>]: string;
+} & {
+    readonly [K in Exclude<OneKeys<R>, RequiredOneKeys<R>>]?: string | null;
+} & {
+    readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
+}>;
+/** Values for `update`. Handlers may write `managed` properties; the generated `update` may not. */
+export type UpdateValues<P, R> = Simplify<{
+    readonly [K in keyof P]?: WriteValueOf<P[K]>;
+} & {
+    readonly [K in OneKeys<R>]?: R[K] extends OneRelationship<true> ? string | null : string;
+} & {
+    readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
+}>;
+type BlobKeys<P> = {
+    [K in keyof P]-?: NonNullable<ValueOf<P[K]>> extends BlobValue ? K : never;
+}[keyof P] & string;
+type UnsupportedBatchKeys<P, R> = BlobKeys<P> | ManyKeys<R>;
+/** Create values for a batch: ordinary properties and stored `rel.one` assignments only. */
+export type BatchCreateValues<P, R> = Simplify<Omit<CreateValues<P, R>, UnsupportedBatchKeys<P, R>> & {
+    readonly [K in UnsupportedBatchKeys<P, R>]?: never;
+}>;
+/** Patch values for a batch. Blob and collection assignments use single-record methods. */
+export type BatchUpdateValues<P, R> = Simplify<Omit<UpdateValues<P, R>, UnsupportedBatchKeys<P, R>> & {
+    readonly [K in UnsupportedBatchKeys<P, R>]?: never;
+}>;
+/** Ordinary declared properties accepted as upsert keys; unique declarations are checked at runtime. */
+export type BatchKey<P> = Exclude<keyof P & string, BlobKeys<P>>;
+/** Upsert inputs must explicitly supply non-null values for every selected conflict key. */
+export type BatchUpsertValues<P, R, K extends BatchKey<P>> = Simplify<Omit<BatchCreateValues<P, R>, K> & {
+    readonly [Key in K]: NonNullable<WriteValueOf<P[Key]>>;
+}>;
+export interface BatchUpdateRecord<P, R> {
+    readonly id: string;
+    readonly values: BatchUpdateValues<P, R>;
+}
+interface EntityUpsertManyInput<P, R, K extends BatchKey<P>> extends BatchOptions {
+    readonly on: readonly [K, ...K[]];
+    readonly records: ReadonlyArray<BatchUpsertValues<P, R, NoInfer<K>>>;
+}
+type BatchWriteError = ActionRejected | Conflict | NotFound | ScopeViolated;
+/** Fields a fresh metric query groups by: declared properties and `<relationship>Id` keys. */
+export type MetricQueryGroupKey<P, R> = Exclude<keyof P & string, BlobKeys<P>> | (keyof RelationshipIds<R> & string);
+/** The options of an entity's fresh metric query, its metrics under either of their names. */
+export type FreshMetricQueryInput<P, R, Metric extends string, Group extends string> = FreshMetricQueryOptions<EntityRecord<P, R>, LinkKeys<R>, Metric, Group> | EarlierFreshMetricQueryOptions<EntityRecord<P, R>, LinkKeys<R>, Metric, Group>;
+/**
+ * One row of a fresh metric query: the grouped fields, typed as the record's, and each metric as a
+ * decimal string, or `null` where the warehouse's value is null too.
+ */
+export type FreshMetricQueryRow<Record, Group extends keyof Record, Metric extends string> = Simplify<{
+    readonly [K in Group]: Record[K];
+} & {
+    readonly [K in Metric]: string | null;
+}>;
+/**
+ * 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;
+};
+/** The metrics of an entity that declares none. */
+type NoMetrics = Readonly<Record<never, never>>;
+export interface EntityDefinition<P extends Properties, R extends Relationships, M extends Metrics = Metrics> extends EarlierMetricsField<M> {
+    /** The stable identity. It never changes; a changed id is a new entity. */
+    readonly id: string;
+    readonly label: string;
+    readonly plural: string;
+    /** The property that names a record in lists, pickers and prose. */
+    readonly title: keyof P & string;
+    readonly description: string;
+    readonly properties: P;
+    readonly source?: WarehouseSource;
+    readonly metrics?: M;
+    readonly relationships?: R;
+    readonly indexes?: ReadonlyArray<IndexDefinition<IndexField<P, R>>>;
+    /** A Markdown file with process knowledge, relative to the ontology folder. */
+    readonly guide?: string;
+    /** The entity's previous name, for one deploy, so that the table is renamed instead of replaced. */
+    readonly renamedFrom?: string;
+    /**
+     * Who writes the entity's records. `"generated"`, the default, adds the generated `create`,
+     * `update`, `delete`, `upsert_by_<property>` and, with a `rel.many`, `link` and `unlink`.
+     * `"actions"` adds none of them: only the entity's authored actions write its records, and no
+     * generated `link` or `unlink` reaches its `rel.many` links from either side. Deleting a record
+     * on the other side still removes that record's own links, as it removes every reference to it.
+     * Reads stay the same. Stored entities only.
+     */
+    readonly writes?: EntityWrites;
+}
+/** Who writes an entity's records; see {@link EntityDefinition.writes}. */
+export type EntityWrites = "generated" | "actions";
+/** The actions of an entity before `.actions(…)` adds any. */
+export type NoActions = Readonly<Record<never, never>>;
+/**
+ * What an authored action handle names besides its definition: the entity it belongs to and its key
+ * in `.actions(…)`, as declared, so `after(name, Lead.actions.changeStatus, …)` can name the action
+ * in the manifest, and type-level only, the entity's record type for the trigger's record.
+ */
+export interface ActionHandle<EntityName extends string = string, Key extends string = string, EntityType = unknown> {
+    /** The entity's name as declared: `lead`. */
+    readonly entity: EntityName;
+    /** The action's key in `.actions(…)`: `changeStatus`. */
+    readonly name: Key;
+    /** Type-level only: the record type of the action's entity, as `typeof Lead.Type`. */
+    readonly "~ontology.record": EntityType;
+}
+/**
+ * An authored action as an entity handle exposes it: its definition, its {@link ActionHandle}
+ * names, and callable as an Effect that runs it as the current caller, through the same path as its
+ * HTTP route, with its permission check and history. Calling it requires {@link OntologyActions},
+ * which a workflow step's `run` provides; inside an action handler the call does not type-check.
+ */
+export type ActionInvoker<A, EntityName extends string = string, Key extends string = string, EntityType = unknown> = A extends Action<infer Input, infer Result> ? A & ActionHandle<EntityName, Key, EntityType> & ((input: Input["Type"], options?: ActionRunOptions) => Effect.Effect<Result, ActionError | ConnectionError, OntologyActions>) : A;
+/** The authored actions of an entity handle, each an {@link ActionInvoker}. */
+export type InvocableActions<A, EntityName extends string = string, EntityType = unknown> = {
+    readonly [K in keyof A]: ActionInvoker<A[K], EntityName, K & string, EntityType>;
+};
+/**
+ * `entity(…).actions((self) => ({ … }))`: declares the entity's actions next to its definition and
+ * returns the entity with `actions` typed as the returned object, so `typeof Lead.actions` carries
+ * every action's input and result types.
+ *
+ * Inside the callback, refer to the entity being defined as `self`, never as the constant it is
+ * being assigned to: `self` is the entity without actions, with the same `ref`, `properties` and
+ * data access. Naming the constant (`Lead.ref` inside `Lead`'s own actions) is a TypeScript
+ * 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, M extends Metrics = Metrics, W extends EntityWrites = EntityWrites> {
+    <const A extends Actions>(define: (self: Entity<Name, P, R, NoActions, M, W>) => A): Entity<Name, P, R, InvocableActions<A, Name, EntityRecord<P, R>>, M, W>;
+}
+/**
+ * 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, M extends Metrics = Metrics, W extends EntityWrites = EntityWrites> = Entity<Name, P, R, ActionsBuilder<Name, P, R, M, W>, M, W>;
+/**
+ * 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. `M` is the type of its
+ * declared metrics, which typed metric query clients read from `definition.metrics`.
+ */
+export interface Entity<Name extends string = string, P extends Properties = Properties, R extends Relationships = Relationships, A extends object = NoActions, M extends Metrics = Metrics, W extends EntityWrites = EntityWrites> extends EarlierQueryMetricsName<P, R, M> {
+    readonly [EntityTypeId]: typeof EntityTypeId;
+    /** The API name and the table name. */
+    readonly name: Name;
+    readonly definition: EntityDefinition<P, R, M>;
+    /**
+     * Type-level only: who writes the records, as `definition.writes` declares it, so typed clients
+     * leave out the generated writes of an entity that declares `writes: "actions"`.
+     */
+    readonly "~ontology.writes": W;
+    readonly properties: P;
+    readonly relationships: R;
+    /** The authored actions by name, as declared with `.actions(…)`. */
+    readonly actions: A;
+    /** Type-level only: the record type, as `typeof Lead.Type`. */
+    readonly Type: EntityRecord<P, R>;
+    /** 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>, LinkKeys<R>>): Effect.Effect<ReadonlyArray<EntityRecord<P, R>>, never, OntologyReads>;
+    /**
+     * A fresh metric query: computes metrics the entity declares over the records `where` matches,
+     * in the action's transaction, so it counts the action's own writes: one row per `groupBy`
+     * group, or one row without it. Metrics mean what the warehouse computes, over every record
+     * `where` matches. `where` must match an indexed field with `eq` or `in`. It locks nothing: lock
+     * the record the decision depends on with `forUpdate`.
+     */
+    queryMetrics<const Metric extends keyof M & string, const Group extends MetricQueryGroupKey<P, R> = never>(options: FreshMetricQueryInput<P, R, Metric, Group>): Effect.Effect<ReadonlyArray<FreshMetricQueryRow<EntityRecord<P, R>, Group, Metric>>, never, OntologyReads>;
+    create(values: CreateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound | ScopeViolated, OntologyWrites>;
+    update(record: RecordRef, values: UpdateValues<P, R>): Effect.Effect<EntityRecord<P, R>, Conflict | NotFound | ScopeViolated, OntologyWrites>;
+    upsertBy(property: UniqueKeys<P>, values: CreateValues<P, R>): Effect.Effect<UpsertResult<EntityRecord<P, R>>, Conflict | NotFound | ScopeViolated, OntologyWrites>;
+    /** Atomically create records. Defaults to returning one record result per input, in order. */
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options: {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options?: {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    createMany(records: ReadonlyArray<BatchCreateValues<P, R>>, options?: BatchOptions): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    /** Atomically patch distinct record IDs; values equal to the locked record remain unchanged. */
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options: {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options?: {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    updateMany(records: ReadonlyArray<BatchUpdateRecord<P, R>>, options?: BatchOptions): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    /** Atomically insert or patch by a declared unique property or compound unique index. */
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K> & {
+        readonly returning: "summary";
+    }): Effect.Effect<BatchSummaryResult, BatchWriteError, OntologyWrites>;
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K> & {
+        readonly returning?: "records";
+    }): Effect.Effect<BatchRecordResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    upsertMany<const K extends BatchKey<P>>(input: EntityUpsertManyInput<P, R, K>): Effect.Effect<BatchResult<EntityRecord<P, R>>, BatchWriteError, OntologyWrites>;
+    delete(record: RecordRef): Effect.Effect<void, Conflict | NotFound | ScopeViolated, OntologyWrites>;
+    link(relationship: ManyKeys<R>, record: RecordRef, target: RecordRef): Effect.Effect<void, NotFound | ScopeViolated, OntologyWrites>;
+    unlink(relationship: ManyKeys<R>, record: RecordRef, target: RecordRef): Effect.Effect<void, NotFound | ScopeViolated, OntologyWrites>;
+}
+/**
+ * Any entity, whatever its properties, relationships and actions. The built-in `User` is listed on
+ * its own: its member writes make it more than an {@link Entity}, which TypeScript then compares
+ * member by member.
+ */
+export type AnyStoredEntity = Entity<string, any, any, any> | UserHandle<any>;
+export type AnyEntity = AnyStoredEntity | WarehouseBackedEntity<string, any, any, Metrics>;
+interface WarehouseBackedEntity<Name extends string, P extends Properties, R extends Relationships, M extends Metrics> extends EarlierMetricsName<M> {
+    readonly [EntityTypeId]: typeof EntityTypeId;
+    readonly name: Name;
+    readonly definition: EntityDefinition<P, R> & {
+        readonly source: WarehouseSource;
+        readonly metrics?: M;
+    };
+    readonly properties: P;
+    readonly relationships: R;
+    readonly actions: NoActions;
+    readonly metrics: M;
+    readonly Type: {
+        readonly id: string;
+    } & {
+        readonly [K in keyof P]: ValueOf<P[K]> | null;
+    };
+}
+/**
+ * Declares an entity. Add its actions with `.actions((self) => ({ … }))`; see {@link ActionsBuilder}.
+ * 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 Metrics = NoMetrics>(name: Name, definition: EntityDefinition<P, R> & {
+    readonly source: WarehouseSource;
+    readonly metrics?: M;
+} & EarlierMetricsField<M>): WarehouseBackedEntity<Name, P, R, M>;
+export declare function entity<const Name extends string, const P extends Properties, const R extends Relationships = NoRelationships, const M extends Metrics = NoMetrics, const W extends EntityWrites = "generated">(name: Name, definition: EntityDefinition<P, R, M> & {
+    readonly writes?: W;
+}): DraftEntity<Name, P, R, M, W>;
+export declare function isEntity(value: unknown): value is AnyEntity;
+export {};

package/dist/entity.js

@@ -0,0 +1,153 @@
+import { Effect } from "effect";
+import { withCurrentFreshMetricQueryNames, withEarlierQueryMetricsName, withCurrentDefinitionNames, withEarlierMetricsName, } from "./legacy.js";
+import { isAction } from "./action.js";
+import { p } from "./property.js";
+import { metricQueryRowFromWire, metricQueryToWire, recordFromWire, valuesToWire, findToWire, } from "./authoring-records.js";
+import { toSnakeCase } from "./names.js";
+import { OntologyActions, OntologyReads, OntologyWrites, } from "./runtime.js";
+export const EntityTypeId = Symbol.for("@segmentstream/ontology/Entity");
+/**
+ * The action, callable: `Lead.actions.addNote(input)` runs it through {@link OntologyActions}. It
+ * carries `entity` and `name` as declared; a function's own `name` is read-only, so it is redefined.
+ */
+function invocable(entity, name, definition) {
+    const invoke = (input, options) => Effect.flatMap(OntologyActions, (actions) => actions.run({
+        entity: toSnakeCase(entity),
+        action: toSnakeCase(name),
+        input,
+        ...(options === undefined ? {} : { options }),
+    }));
+    return Object.defineProperties(Object.assign(invoke, definition), {
+        entity: { value: entity },
+        name: { value: name },
+    });
+}
+function idOf(record) {
+    return typeof record === "string" ? record : record.id;
+}
+export function entity(name, definition) {
+    // Workspace code written for an earlier SDK may name fields, such as the metrics, by earlier names.
+    definition = withCurrentDefinitionNames(definition);
+    if (definition.source !== undefined) {
+        const metrics = definition.metrics ?? {};
+        return {
+            [EntityTypeId]: EntityTypeId,
+            name,
+            definition,
+            properties: definition.properties,
+            relationships: definition.relationships ?? {},
+            actions: {},
+            metrics,
+            ...withEarlierMetricsName(metrics),
+        };
+    }
+    const batchFromWire = (result) => "items" in result
+        ? {
+            ...result,
+            items: result.items.map((item) => ({
+                ...item,
+                record: recordFromWire(item.record, definition),
+            })),
+        }
+        : result;
+    const createMany = ((records, options) => withWrites((runtime) => runtime.createMany({
+        entity: toSnakeCase(name),
+        records: records.map((values) => valuesToWire(values, definition)),
+        ...(options?.returning === undefined ? {} : { returning: options.returning }),
+    })).pipe(Effect.map(batchFromWire)));
+    const updateMany = ((records, options) => withWrites((runtime) => runtime.updateMany({
+        entity: toSnakeCase(name),
+        records: records.map(({ id, values }) => ({
+            id,
+            values: valuesToWire(values, definition),
+        })),
+        ...(options?.returning === undefined ? {} : { returning: options.returning }),
+    })).pipe(Effect.map(batchFromWire)));
+    const upsertMany = ((input) => withWrites((runtime) => runtime.upsertMany({
+        entity: toSnakeCase(name),
+        on: input.on.map(toSnakeCase),
+        records: input.records.map((values) => valuesToWire(values, definition)),
+        ...(input.returning === undefined ? {} : { returning: input.returning }),
+    })).pipe(Effect.map(batchFromWire)));
+    const queryMetrics = ((authored) => Effect.suspend(() => {
+        const options = withCurrentFreshMetricQueryNames(authored);
+        return withReads((runtime) => runtime.queryMetrics({
+            entity: toSnakeCase(name),
+            options: metricQueryToWire(options, definition),
+        })).pipe(Effect.map((rows) => rows.map((row) => metricQueryRowFromWire(row, options.metrics, definition))));
+    }));
+    const handle = {
+        [EntityTypeId]: EntityTypeId,
+        name,
+        definition,
+        properties: definition.properties,
+        relationships: definition.relationships ?? {},
+        ref: p.ref(name),
+        createMany,
+        updateMany,
+        upsertMany,
+        get: (record, options) => withReads((runtime) => runtime.get({
+            entity: toSnakeCase(name),
+            id: idOf(record),
+            ...(options?.forUpdate === true ? { forUpdate: true } : {}),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        find: (options) => withReads((runtime) => runtime.find({ entity: toSnakeCase(name), options: findToWire(options ?? {}, definition) })).pipe(Effect.map((records) => records.map((record) => recordFromWire(record, definition)))),
+        queryMetrics,
+        ...withEarlierQueryMetricsName(queryMetrics),
+        create: (values) => withWrites((runtime) => runtime.create({ entity: toSnakeCase(name), values: valuesToWire(values, definition) })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        update: (record, values) => withWrites((runtime) => runtime.update({
+            entity: toSnakeCase(name),
+            id: idOf(record),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        upsertBy: (property, values) => withWrites((runtime) => runtime.upsertBy({
+            entity: toSnakeCase(name),
+            property: toSnakeCase(property),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((result) => ({
+            ...result,
+            record: recordFromWire(result.record, definition),
+        }))),
+        delete: (record) => withWrites((runtime) => runtime.delete({ entity: toSnakeCase(name), id: idOf(record) })),
+        link: (relationship, record, target) => withWrites((runtime) => runtime.link({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
+        })),
+        unlink: (relationship, record, target) => withWrites((runtime) => runtime.unlink({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
+        })),
+    };
+    // Every form of the entity shares `definition`, which is how defineOntology recognises them.
+    const self = { ...handle, actions: {} };
+    const defineActions = (define) => {
+        const defined = define(self);
+        // A value that is not an object of actions stays as it is, for `check` to report.
+        const actions = typeof defined === "object" && defined !== null && !Array.isArray(defined)
+            ? Object.fromEntries(Object.entries(defined).map(([key, value]) => [
+                key,
+                isAction(value) ? invocable(name, key, value) : value,
+            ]))
+            : defined;
+        return { ...handle, actions };
+    };
+    return { ...handle, actions: defineActions };
+}
+/**
+ * Runs one read. The runtime decodes records against the entity's definition, so the result is typed
+ * as the entity's records here.
+ */
+function withReads(operation) {
+    return Effect.flatMap(OntologyReads, operation);
+}
+/** Runs one write, typed as {@link withReads} types a read. */
+function withWrites(operation) {
+    return Effect.flatMap(OntologyWrites, operation);
+}
+export function isEntity(value) {
+    return typeof value === "object" && value !== null && EntityTypeId in value;
+}

package/dist/errors.d.ts

@@ -0,0 +1,154 @@
+import { Schema } from "effect";
+/** Safe batch failure locations: zero-based input indices and wire field names. */
+export declare const BatchErrorDetails: Schema.Struct<{
+    readonly indices: Schema.$Array<Schema.Int>;
+    readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+export type BatchErrorDetails = typeof BatchErrorDetails.Type;
+/**
+ * The platform limit that refused a file upload or attachment, with the numbers a caller needs to
+ * explain it in its own words. `usedBytes` counts current and retained historical file revisions,
+ * reserved uploads and live agent attachments.
+ */
+export declare const LimitErrorDetails: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"storage_quota">;
+    readonly usedBytes: Schema.Int;
+    readonly requestedBytes: Schema.Int;
+    readonly quotaBytes: Schema.Int;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"pending_uploads">;
+    readonly pending: Schema.Int;
+    readonly max: Schema.Int;
+    /** The caller's open uploads, oldest first, which it can store with their actions or cancel. */
+    readonly uploads: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly filename: Schema.String;
+        readonly expiresAt: Schema.String;
+    }>>>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"member_attachments">;
+    readonly live: Schema.Int;
+    readonly max: Schema.Int;
+}>]>;
+export type LimitErrorDetails = typeof LimitErrorDetails.Type;
+declare const ActionRejected_base: Schema.Class<ActionRejected, Schema.TaggedStruct<"ActionRejected", {
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+    readonly limit: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"storage_quota">;
+        readonly usedBytes: Schema.Int;
+        readonly requestedBytes: Schema.Int;
+        readonly quotaBytes: Schema.Int;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"pending_uploads">;
+        readonly pending: Schema.Int;
+        readonly max: Schema.Int;
+        /** The caller's open uploads, oldest first, which it can store with their actions or cancel. */
+        readonly uploads: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly filename: Schema.String;
+            readonly expiresAt: Schema.String;
+        }>>>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"member_attachments">;
+        readonly live: Schema.Int;
+        readonly max: Schema.Int;
+    }>]>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An action refused the request for a business reason. The message is written for the caller and is
+ * returned to them.
+ */
+export declare class ActionRejected extends ActionRejected_base {
+}
+declare const PermissionDenied_base: Schema.Class<PermissionDenied, Schema.TaggedStruct<"PermissionDenied", {
+    readonly message: Schema.String;
+    /** The permission that is missing, for example `lead:changeStatus`. */
+    readonly permission: Schema.optionalKey<Schema.String>;
+    /**
+     * Refused only because the running ontology and the database catalog differ, as while a
+     * deployment migrates. The caller retries the same request.
+     */
+    readonly updating: Schema.optionalKey<Schema.Literal<true>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The principal's roles do not grant a permission the request requires. The service answers 403
+ * with `<permission> is required.`; the message stays in the logs.
+ */
+export declare class PermissionDenied extends PermissionDenied_base {
+}
+declare const DeploymentSwitching_base: Schema.Class<DeploymentSwitching, Schema.TaggedStruct<"DeploymentSwitching", {
+    readonly message: Schema.String;
+    readonly retryAfter: Schema.Number;
+    readonly generation: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A bounded deployment transition, which ontology SDKs 0.86.0 to 0.88.0 raised while their deploy
+ * guard paused workflow starts. Nothing raises it now; it is kept to read their recorded failures.
+ */
+export declare class DeploymentSwitching extends DeploymentSwitching_base {
+}
+declare const DeploymentInterrupted_base: Schema.Class<DeploymentInterrupted, Schema.TaggedStruct<"DeploymentInterrupted", {
+    readonly message: Schema.String;
+    readonly servedHash: Schema.String;
+    readonly appliedHash: Schema.optionalKey<Schema.String>;
+    readonly servedDeploymentId: Schema.optionalKey<Schema.String>;
+    readonly appliedDeploymentId: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/** This deployment cannot safely execute against the applied catalog. Retrying cannot repair it. */
+export declare class DeploymentInterrupted extends DeploymentInterrupted_base {
+}
+declare const Conflict_base: Schema.Class<Conflict, Schema.TaggedStruct<"Conflict", {
+    readonly entity: Schema.String;
+    readonly message: Schema.String;
+    readonly property: Schema.optionalKey<Schema.String>;
+    /**
+     * Seconds until the same request may succeed, set while another attempt holds the record, such
+     * as an upload whose storage call failed mid-flight.
+     */
+    readonly retryAfter: Schema.optionalKey<Schema.Int>;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** The write conflicts with existing data, for example a duplicate value of a unique property. */
+export declare class Conflict extends Conflict_base {
+}
+declare const NotFound_base: Schema.Class<NotFound, Schema.TaggedStruct<"NotFound", {
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly message: Schema.String;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/** The record does not exist. */
+export declare class NotFound extends NotFound_base {
+}
+declare const ScopeViolated_base: Schema.Class<ScopeViolated, Schema.TaggedStruct<"ScopeViolated", {
+    readonly entity: Schema.String;
+    readonly id: Schema.optionalKey<Schema.String>;
+    /** The scoped permission, for example `staff_member:update`. */
+    readonly permission: Schema.String;
+    readonly message: Schema.String;
+    readonly batch: Schema.optionalKey<Schema.Struct<{
+        readonly indices: Schema.$Array<Schema.Int>;
+        readonly fields: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A write would leave a record outside the scope of the permission that allowed it: the record
+ * matched the role's `where` before the change and does not after it. The service answers 403 with
+ * the entity and the permission; the scope's `where` and the values stay out of the response.
+ */
+export declare class ScopeViolated extends ScopeViolated_base {
+}
+/** The failures an action handler may produce. */
+export type ActionError = ActionRejected | PermissionDenied | DeploymentSwitching | DeploymentInterrupted | Conflict | NotFound | ScopeViolated;
+export {};