@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/runtime/metric-query.js

@@ -0,0 +1,411 @@
+import { Effect } from "effect";
+import { entityStorage, quoteIdentifier } from "../migrate/storage.js";
+import { isCalendarDate } from "../query.js";
+import { InvalidQuery } from "./errors.js";
+import { decodeRecord, selectList } from "./records.js";
+import { validateQuery } from "./reads.js";
+import { Aliases, columnOf, Params } from "./statement.js";
+import { compileWhere, fieldFilter } from "./where.js";
+/**
+ * Fresh metric queries: an entity's declared metrics computed in PostgreSQL over the records a
+ * `where` matches, inside the caller's transaction (docs/ontology.md, "Fresh metric queries inside an
+ * action").
+ * Each metric is computed as SegmentStream computes it in the warehouse
+ * (backend-next's `semantics/adapters/bigquery-expressions.ts` and `bigquery-predicates.ts`):
+ * columns as decimals with nine places, aggregates ignoring nulls, a filtered aggregate over the
+ * rows its conditions hold for, division by zero as null, and values as decimal strings.
+ *
+ * One statement computes every metric over every matching record. The `where` must match the
+ * leading column of an index with `eq` or `in`, so that finding the records never scans the table:
+ * the cost follows the records the indexed condition selects.
+ */
+const OPTIONS = new Set(["metrics", "groupBy", "where"]);
+/** Properties a metric's sum, avg, min and max read. */
+const NUMERIC = new Set(["integer", "number"]);
+/** Fields a fresh metric query cannot group by: their values are documents or sets, not groups. */
+const UNGROUPABLE = new Set(["json", "blob", "list"]);
+/** How deep metric references and arithmetic may nest, as `check` bounds them. */
+const MAX_DEPTH = 30;
+function invalid(entity, path, message) {
+    return new InvalidQuery({
+        entity: entity.name,
+        message: `The metric query does not fit ${entity.name}: ${message}`,
+        issues: [{ path, message }],
+    });
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The fields whose column leads an index of the entity's table, the primary key included. */
+const indexedFields = new WeakMap();
+export function indexedFieldsOf(entity) {
+    const cached = indexedFields.get(entity);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const { table } = entityStorage(entity.manifest);
+    const leading = new Set([table.primaryKey.columns[0], ...table.indexes.map((index) => index.columns[0])].filter((column) => column !== undefined));
+    const fields = new Set(entity.fields
+        .filter((field) => field.source !== "projection" && leading.has(field.column))
+        .map((field) => field.name));
+    indexedFields.set(entity, fields);
+    return fields;
+}
+/** Whether a field condition is `eq` on a value or `in`, which an index can look up. */
+function looksUp(field, condition) {
+    if (condition === null) {
+        return false;
+    }
+    const filter = fieldFilter(field, condition);
+    return (filter.eq !== undefined && filter.eq !== null) || filter.in !== undefined;
+}
+/**
+ * Whether a validated `where` confines the records to an index lookup: a condition of its own, or
+ * of an `and` entry, that looks up an indexed field, or an `or` every branch of which does. `not`
+ * never confines.
+ */
+export function anchored(entity, where) {
+    if (where === undefined) {
+        return false;
+    }
+    const indexed = indexedFieldsOf(entity);
+    return Object.entries(where).some(([key, condition]) => {
+        if (condition === undefined || key === "not") {
+            return false;
+        }
+        if (key === "and") {
+            return condition.some((sub) => anchored(entity, sub));
+        }
+        if (key === "or") {
+            const branches = condition;
+            return branches.length > 0 && branches.every((sub) => anchored(entity, sub));
+        }
+        const field = entity.fieldsByName.get(key);
+        return field !== undefined && indexed.has(key) && looksUp(field, condition);
+    });
+}
+/**
+ * Inlines a metric's references to other metrics of the entity, refusing what a fresh metric query
+ * does not compute: a balance, which only the warehouse's balance rule makes meaningful, and an
+ * operator this SDK does not know.
+ */
+function expand(entity, name, path) {
+    const metrics = new Map((entity.manifest.metrics ?? []).map((metric) => [metric.name, metric]));
+    const visit = (current, stack) => {
+        const metric = metrics.get(current);
+        if (metric === undefined) {
+            throw invalid(entity, path, `${entity.name} has no metric ${current}.`);
+        }
+        if (stack.includes(current) || stack.length > MAX_DEPTH) {
+            throw invalid(entity, path, `${entity.name}.${name} references itself.`);
+        }
+        if (metric.balanceOver !== undefined) {
+            throw invalid(entity, path, `${entity.name}.${current} is a balance over ${metric.balanceOver}, which only the ` +
+                "warehouse computes.");
+        }
+        const inline = (expression, depth) => {
+            if (depth > MAX_DEPTH) {
+                throw invalid(entity, path, `${entity.name}.${name} nests too deeply.`);
+            }
+            switch (expression.op) {
+                case "metric":
+                    return visit(expression.name, [...stack, current]);
+                case "count":
+                case "column":
+                case "literal":
+                    return expression;
+                case "filtered":
+                    return { ...expression, args: expression.args.map((arg) => inline(arg, depth + 1)) };
+                case "sum":
+                case "countDistinct":
+                case "avg":
+                case "min":
+                case "max":
+                case "add":
+                case "subtract":
+                case "multiply":
+                case "divide":
+                    return { ...expression, args: expression.args.map((arg) => inline(arg, depth + 1)) };
+                default:
+                    throw invalid(entity, path, `${entity.name}.${current} uses an operator this SDK does not compute.`);
+            }
+        };
+        return inline(metric.expression, 0);
+    };
+    return visit(name, []);
+}
+/** Compiles metric expressions over the table aliased `alias`, binding values into `params`. */
+class MetricCompiler {
+    entity;
+    alias;
+    params;
+    path;
+    constructor(entity, alias, params, path) {
+        this.entity = entity;
+        this.alias = alias;
+        this.params = params;
+        this.path = path;
+    }
+    /** The field a metric names: a property or system field, by its wire name. */
+    field(name) {
+        const field = this.entity.fieldsByName.get(name);
+        if (field === undefined || (field.source !== "property" && field.source !== "system")) {
+            throw invalid(this.entity, this.path, `a metric reads ${name}, which is not a property.`);
+        }
+        return field;
+    }
+    column(field) {
+        return columnOf(this.alias, field.column);
+    }
+    /** A numeric column as the warehouse casts it: a decimal with nine places. */
+    decimal(name) {
+        const field = this.field(name);
+        if (!NUMERIC.has(field.storage)) {
+            throw invalid(this.entity, this.path, `a metric's aggregate reads ${name}, a non-numeric property.`);
+        }
+        return field.storage === "integer"
+            ? `${this.column(field)}::numeric`
+            : `round(${this.column(field)}::numeric, 9)`;
+    }
+    /** The value an aggregate reads: one numeric column. */
+    argument(expression) {
+        if (expression?.op !== "column") {
+            throw invalid(this.entity, this.path, "an aggregate reads one property.");
+        }
+        return this.decimal(expression.name);
+    }
+    /** One aggregate, restricted to the rows `filter` holds for when there is one. */
+    aggregate(expression, filter) {
+        const only = filter === undefined ? "" : ` FILTER (WHERE ${filter})`;
+        switch (expression.op) {
+            case "count":
+                return `(count(*)${only})::numeric`;
+            case "countDistinct": {
+                const [argument] = expression.args;
+                if (argument?.op !== "column") {
+                    throw invalid(this.entity, this.path, "countDistinct reads one property.");
+                }
+                return `(count(DISTINCT ${this.column(this.field(argument.name))})${only})::numeric`;
+            }
+            case "sum":
+            case "min":
+            case "max":
+                return `${expression.op}(${this.argument(expression.args[0])})${only}`;
+            case "avg":
+                return `round(avg(${this.argument(expression.args[0])})${only}, 9)`;
+            default:
+                throw invalid(this.entity, this.path, "a filtered metric wraps one aggregate.");
+        }
+    }
+    compile(expression) {
+        switch (expression.op) {
+            case "count":
+            case "countDistinct":
+            case "sum":
+            case "avg":
+            case "min":
+            case "max":
+                return this.aggregate(expression);
+            case "filtered": {
+                const [aggregate] = expression.args;
+                if (aggregate === undefined || expression.where.length === 0) {
+                    throw invalid(this.entity, this.path, "a filtered metric wraps one aggregate.");
+                }
+                return this.aggregate(aggregate, expression.where.map((condition) => `(${this.condition(condition)})`).join(" AND "));
+            }
+            case "literal":
+                return this.params.add(expression.value, "numeric");
+            case "add":
+            case "subtract":
+            case "multiply":
+            case "divide": {
+                const [left, right] = expression.args.map((arg) => this.compile(arg));
+                if (left === undefined || right === undefined) {
+                    throw invalid(this.entity, this.path, "arithmetic combines two expressions.");
+                }
+                // The warehouse's decimals keep nine places, and a zero denominator divides to null.
+                return expression.op === "add"
+                    ? `(${left} + ${right})`
+                    : expression.op === "subtract"
+                        ? `(${left} - ${right})`
+                        : expression.op === "multiply"
+                            ? `round(${left} * ${right}, 9)`
+                            : `round(${left} / NULLIF(${right}, 0), 9)`;
+            }
+            default:
+                throw invalid(this.entity, this.path, "a metric uses an operator this SDK does not compute.");
+        }
+    }
+    /**
+     * A metric condition, exactly as the warehouse reads it: negative operators match nulls, text
+     * operators compare case-sensitively, and date bounds on a timestamp cover whole days in UTC, a
+     * stored entity's timezone.
+     */
+    condition(condition) {
+        const field = this.field(condition.column);
+        const storage = field.storage;
+        const text = storage === "select" ? `${this.column(field)}::text` : this.column(field);
+        const type = storage === "integer" || storage === "number"
+            ? "numeric"
+            : storage === "date" || storage === "boolean"
+                ? storage
+                : storage === "timestamp"
+                    ? "timestamptz"
+                    : "text";
+        const bind = (value) => this.params.add(type === "numeric" ? String(value) : value, type);
+        const one = () => bind(condition.value);
+        const several = () => (condition.values ?? []).map(bind).join(", ");
+        const day = (value) => `(${this.params.add(value, "date")}::timestamp AT TIME ZONE 'UTC')`;
+        const nextDay = (value) => `((${this.params.add(value, "date")} + 1)::timestamp AT TIME ZONE 'UTC')`;
+        const isDay = (value) => storage === "timestamp" && typeof value === "string" && isCalendarDate(value);
+        switch (condition.operator) {
+            case "isNull":
+                return `${text} IS NULL`;
+            case "isNotNull":
+                return `${text} IS NOT NULL`;
+            case "equals":
+                return `${text} = ${one()}`;
+            case "notEquals":
+                return `(${text} IS NULL OR ${text} <> ${one()})`;
+            case "in":
+                return `${text} IN (${several()})`;
+            case "notIn":
+                return `(${text} IS NULL OR ${text} NOT IN (${several()}))`;
+            case "between": {
+                const [from, to] = condition.values ?? [];
+                return isDay(from) && isDay(to)
+                    ? `${text} >= ${day(from)} AND ${text} < ${nextDay(to)}`
+                    : `${text} >= ${bind(from)} AND ${text} <= ${bind(to)}`;
+            }
+            case "gt":
+                return isDay(condition.value)
+                    ? `${text} >= ${nextDay(condition.value)}`
+                    : `${text} > ${one()}`;
+            case "gte":
+                return isDay(condition.value)
+                    ? `${text} >= ${day(condition.value)}`
+                    : `${text} >= ${one()}`;
+            case "lt":
+                return isDay(condition.value) ? `${text} < ${day(condition.value)}` : `${text} < ${one()}`;
+            case "lte":
+                return isDay(condition.value)
+                    ? `${text} < ${nextDay(condition.value)}`
+                    : `${text} <= ${one()}`;
+            case "contains":
+                return `strpos(${text}, ${one()}) > 0`;
+            case "startsWith": {
+                const value = one();
+                return `left(${text}, char_length(${value})) = ${value}`;
+            }
+            case "endsWith": {
+                const value = one();
+                return `right(${text}, char_length(${value})) = ${value}`;
+            }
+            default:
+                throw invalid(this.entity, this.path, "a metric condition uses an unknown operator.");
+        }
+    }
+}
+/** The order of a grouped field: nulls first and text by its bytes, as the warehouse orders it. */
+function orderOf(alias, field) {
+    const column = columnOf(alias, field.column);
+    const text = ["text", "email", "url", "select"].includes(field.storage);
+    return `${text ? `${column}::text COLLATE "C"` : column} ASC NULLS FIRST`;
+}
+function plan(entity, input) {
+    return Effect.gen(function* () {
+        if (entity.manifest.builtIn || (entity.manifest.metrics ?? []).length === 0) {
+            return yield* invalid(entity, [], `${entity.name} declares no metrics.`);
+        }
+        if (!isPlainObject(input)) {
+            return yield* invalid(entity, [], "the options are not an object.");
+        }
+        const unknown = Object.keys(input).find((key) => !OPTIONS.has(key));
+        if (unknown === "forUpdate") {
+            return yield* invalid(entity, ["forUpdate"], "metric queries lock no records; lock the record the decision depends on with forUpdate.");
+        }
+        if (unknown !== undefined) {
+            return yield* invalid(entity, [unknown], `${unknown} is not a metric query option.`);
+        }
+        const names = input.metrics;
+        if (!Array.isArray(names) ||
+            names.length === 0 ||
+            names.some((name) => typeof name !== "string") ||
+            new Set(names).size !== names.length) {
+            return yield* invalid(entity, ["metrics"], "metrics names one or more distinct metrics.");
+        }
+        const metrics = yield* Effect.try({
+            try: () => names.map((name, index) => ({
+                name,
+                expression: expand(entity, name, ["metrics", index]),
+            })),
+            catch: (error) => error instanceof InvalidQuery ? error : invalid(entity, ["metrics"], String(error)),
+        });
+        const groupNames = input.groupBy ?? [];
+        if (!Array.isArray(groupNames) ||
+            groupNames.some((name) => typeof name !== "string") ||
+            new Set(groupNames).size !== groupNames.length) {
+            return yield* invalid(entity, ["groupBy"], "groupBy names distinct fields.");
+        }
+        const groups = [];
+        for (const [index, name] of groupNames.entries()) {
+            const field = entity.fieldsByName.get(name);
+            if (field === undefined ||
+                (field.source !== "property" && field.source !== "relationship") ||
+                UNGROUPABLE.has(field.storage)) {
+                return yield* invalid(entity, ["groupBy", index], `${name} is not a property or relationship key ${entity.name} can group by.`);
+            }
+            if (names.includes(name)) {
+                return yield* invalid(entity, ["groupBy", index], `${name} names both a metric and a grouped field.`);
+            }
+            groups.push(field);
+        }
+        if (!isPlainObject(input.where)) {
+            return yield* invalid(entity, ["where"], "where is required.");
+        }
+        const { where } = yield* validateQuery(entity, { where: input.where });
+        if (where === undefined || !anchored(entity, where)) {
+            const indexed = [...indexedFieldsOf(entity)].sort().join(", ");
+            return yield* invalid(entity, ["where"], `where must match an indexed field (${indexed}) with eq or in, so that the records are ` +
+                "found through an index.");
+        }
+        return { metrics, groups, where };
+    });
+}
+/**
+ * Computes the metrics over the records the `where` matches, grouped by the fields of `groupBy`:
+ * one row per group, ordered by the groups, or one row without them. One statement.
+ */
+export function runMetricQuery(context, entity, options) {
+    return Effect.gen(function* () {
+        const planned = yield* plan(entity, options);
+        const params = new Params();
+        const aliases = new Aliases();
+        const alias = aliases.take();
+        const condition = compileWhere({ model: context.model, params, aliases }, entity, alias, planned.where);
+        const compiler = new MetricCompiler(entity, alias, params, ["metrics"]);
+        const metrics = yield* Effect.try({
+            try: () => planned.metrics.map(({ expression }, index) => `trim_scale(${compiler.compile(expression)})::text AS ${quoteIdentifier(`__m${index}`)}`),
+            catch: (error) => error instanceof InvalidQuery ? error : invalid(entity, ["metrics"], String(error)),
+        });
+        const select = [
+            ...(planned.groups.length === 0 ? [] : [selectList(entity, alias, planned.groups)]),
+            ...metrics,
+        ].join(", ");
+        const rows = yield* context.run(`SELECT ${select} FROM ${quoteIdentifier(entity.table)} AS ${quoteIdentifier(alias)} ` +
+            `WHERE ${condition}` +
+            (planned.groups.length === 0
+                ? ""
+                : ` GROUP BY ${planned.groups.map((field) => columnOf(alias, field.column)).join(", ")}` +
+                    ` ORDER BY ${planned.groups.map((field) => orderOf(alias, field)).join(", ")}`), params);
+        return yield* Effect.forEach(rows, (row) => Effect.map(planned.groups.length === 0
+            ? Effect.succeed({})
+            : decodeRecord(entity, row, planned.groups), (groups) => ({
+            ...groups,
+            ...Object.fromEntries(planned.metrics.map(({ name }, index) => {
+                const value = row[`__m${index}`];
+                return [name, value === null || value === undefined ? null : String(value)];
+            })),
+        })));
+    });
+}

package/dist/runtime/model.d.ts

@@ -0,0 +1,67 @@
+import { Schema } from "effect";
+import type { ResolvedEntity, ResolvedProperty } from "../analyze.js";
+import type { EntityManifest } from "../manifest.js";
+import type { Ontology } from "../ontology.js";
+import { type Query, type QueryField, type QueryLink } from "../query.js";
+import type { OnDelete } from "../relationship.js";
+/**
+ * A record field with its column. A projection, the built-in user's `roles`, has none of its own:
+ * it is read from the platform's tables by the row's id, which is its `column`, and never written.
+ */
+export interface FieldModel extends QueryField {
+    readonly column: string;
+    /** The type its parameters are cast to. */
+    readonly sqlType: string;
+    readonly source: "system" | "property" | "relationship" | "projection";
+    /** The declared property, for properties. */
+    readonly property?: ResolvedProperty;
+    /** The relationship whose key the field holds, for `<relationship>_id`. */
+    readonly relationship?: string;
+}
+/** A declared `rel.one`: this entity's key column points at the target's id. */
+export interface KeyLink extends QueryLink {
+    readonly via: "key";
+    readonly column: string;
+    readonly optional: boolean;
+}
+/** A `rel.many`, from either side: rows of a join table. */
+export interface JoinLink extends QueryLink {
+    readonly via: "join";
+    readonly table: string;
+    /** The join column holding this entity's id, and the one holding the target's. */
+    readonly selfColumn: string;
+    readonly otherColumn: string;
+    /** The relationship's name on the target's side. */
+    readonly inverseName: string;
+}
+/** The inverse of a `rel.one`: the target's key column points at this entity's id. */
+export interface InverseKeyLink extends QueryLink {
+    readonly via: "inverse-key";
+    readonly column: string;
+    readonly onDelete: OnDelete;
+}
+export type LinkModel = KeyLink | JoinLink | InverseKeyLink;
+export interface EntityModel {
+    readonly name: string;
+    readonly label: string;
+    readonly table: string;
+    readonly historyTable: string;
+    readonly resolved: ResolvedEntity;
+    readonly manifest: EntityManifest;
+    /** System fields, properties and `<relationship>_id` keys, in record order. */
+    readonly fields: ReadonlyArray<FieldModel>;
+    readonly fieldsByName: ReadonlyMap<string, FieldModel>;
+    readonly links: ReadonlyMap<string, LinkModel>;
+    readonly recordSchema: Schema.Top;
+    readonly querySchema: Schema.Codec<Query>;
+}
+export interface OntologyModel {
+    readonly ontology: Ontology;
+    readonly entities: ReadonlyMap<string, EntityModel>;
+}
+/** The physical model of an ontology: tables, columns and relationship paths per entity. */
+export declare function ontologyModel(ontology: Ontology): OntologyModel;
+/** The model of an entity. An unknown name is a programming error in the caller. */
+export declare function entityModel(model: OntologyModel, name: string): EntityModel;
+/** The schema of a property's value, without the optional-key wrapper. */
+export declare function propertyValueSchema(property: ResolvedProperty): Schema.Top;

package/dist/runtime/model.js

@@ -0,0 +1,150 @@
+import { Schema } from "effect";
+import { entityQuerySchema, entityRecordSchema, findEntityManifest, queryFields, queryLinks, } from "../query.js";
+import { COLUMN_TYPES, columnName, enumTypeName, historyTableName, joinColumnNames, joinTableName, quoteIdentifier, relationshipColumnName, SYSTEM_COLUMNS, tableName, } from "../migrate/storage.js";
+import { User } from "../user.js";
+import { USER_ROLES_PROPERTY } from "./user-roles.js";
+/**
+ * The type a field's parameters are cast to: the planner's column type, the enum type of a
+ * `select`, `uuid` for ids and keys, and the item type of a `list`, whose filters bind items.
+ */
+function sqlType(storage, entity, field) {
+    if (storage === "uuid") {
+        return "uuid";
+    }
+    if (storage === "list") {
+        return "text";
+    }
+    return storage === "select"
+        ? quoteIdentifier(enumTypeName(entity, field))
+        : COLUMN_TYPES[storage];
+}
+const models = new WeakMap();
+/** The physical model of an ontology: tables, columns and relationship paths per entity. */
+export function ontologyModel(ontology) {
+    const cached = models.get(ontology);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const entities = new Map();
+    for (const resolved of ontology.entities) {
+        if (resolved.entity.definition.source !== undefined) {
+            continue;
+        }
+        entities.set(resolved.name, buildEntity(ontology, resolved));
+    }
+    const model = { ontology, entities };
+    models.set(ontology, model);
+    return model;
+}
+/** The model of an entity. An unknown name is a programming error in the caller. */
+export function entityModel(model, name) {
+    const entity = model.entities.get(name);
+    if (entity === undefined) {
+        throw new Error(`"${name}" is not an entity of this ontology.`);
+    }
+    return entity;
+}
+function buildEntity(ontology, resolved) {
+    const manifest = findEntityManifest(ontology.manifest, resolved.name);
+    const properties = new Map(resolved.properties.map((property) => [property.name, property]));
+    const fields = queryFields(manifest).map((field) => buildField(resolved.name, field, properties));
+    return {
+        name: resolved.name,
+        label: manifest.label,
+        table: tableName(resolved.name),
+        historyTable: historyTableName(resolved.name),
+        resolved,
+        manifest,
+        fields,
+        fieldsByName: new Map(fields.map((field) => [field.name, field])),
+        links: new Map(queryLinks(ontology.manifest, resolved.name).map((link) => [
+            link.name,
+            buildLink(ontology, link),
+        ])),
+        recordSchema: entityRecordSchema(manifest),
+        querySchema: entityQuerySchema(ontology.manifest, resolved.name),
+    };
+}
+function buildField(entity, field, properties) {
+    const property = properties.get(field.name);
+    const system = SYSTEM_COLUMNS[field.name];
+    if (system !== undefined) {
+        return {
+            ...field,
+            column: system,
+            sqlType: sqlType(field.storage, entity, field.name),
+            source: "system",
+        };
+    }
+    if (property !== undefined && field.storage === "list") {
+        // `check` refuses a list anywhere else, so another one is a defect in the ontology.
+        if (entity !== User.name || field.name !== USER_ROLES_PROPERTY) {
+            throw new Error(`${entity}.${field.name} is a list, which only the built-in user has.`);
+        }
+        return {
+            ...field,
+            column: SYSTEM_COLUMNS.id,
+            sqlType: sqlType(field.storage, entity, field.name),
+            source: "projection",
+            property,
+        };
+    }
+    if (property !== undefined) {
+        return {
+            ...field,
+            column: columnName(field.name),
+            sqlType: sqlType(field.storage, entity, field.name),
+            source: "property",
+            property,
+        };
+    }
+    const relationship = field.name.slice(0, -"_id".length);
+    return {
+        ...field,
+        column: relationshipColumnName(relationship),
+        sqlType: sqlType(field.storage, entity, field.name),
+        source: "relationship",
+        relationship,
+    };
+}
+function buildLink(ontology, link) {
+    const declaringEntity = findEntityManifest(ontology.manifest, link.declaredBy);
+    const declaration = declaringEntity.relationships.find((candidate) => candidate.name === link.relationship);
+    if (declaration === undefined) {
+        throw new Error(`${link.declaredBy}.${link.relationship} is not declared.`);
+    }
+    if (link.declared === "many") {
+        const columns = joinColumnNames({
+            entity: declaringEntity.name,
+            relationship: declaration.name,
+            target: declaration.to,
+        });
+        return {
+            ...link,
+            via: "join",
+            table: joinTableName(declaringEntity.name, declaration.name),
+            selfColumn: link.inverse ? columns.target : columns.source,
+            otherColumn: link.inverse ? columns.source : columns.target,
+            inverseName: link.inverse ? declaration.name : declaration.inverse,
+        };
+    }
+    if (link.inverse) {
+        return {
+            ...link,
+            via: "inverse-key",
+            column: relationshipColumnName(declaration.name),
+            onDelete: declaration.onDelete ?? "restrict",
+        };
+    }
+    return {
+        ...link,
+        via: "key",
+        column: relationshipColumnName(declaration.name),
+        optional: declaration.optional === true,
+    };
+}
+/** The schema of a property's value, without the optional-key wrapper. */
+export function propertyValueSchema(property) {
+    const { schema } = property;
+    return "schema" in schema && Schema.isSchema(schema.schema) ? schema.schema : schema;
+}

package/dist/runtime/new-user-hook.d.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+/** Runs after admission commits, before a model turn or channel-app session. True means retry pending. */
+export declare function runNewUserHook(ontology: Ontology, sql: SqlClient.SqlClient, principal: Principal): Effect.Effect<boolean>;

package/dist/runtime/new-user-hook.js

@@ -0,0 +1,37 @@
+import { Cause, Effect } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { CHANNEL_USERS_TABLE } from "../migrate/storage.js";
+import { permissionsOf, principalScopes } from "../permissions.js";
+import { runAction } from "./pipeline.js";
+/** Runs after admission commits, before a model turn or channel-app session. True means retry pending. */
+export function runNewUserHook(ontology, sql, principal) {
+    const hook = ontology.signIn.onNewUser;
+    if (hook === undefined) {
+        return Effect.succeed(false);
+    }
+    const [entity, action] = hook.split(":");
+    return runAction(ontology, {
+        entity: entity,
+        action: action,
+        input: {},
+        principal: {
+            id: principal.id,
+            kind: "member",
+            ...(principal.authenticatedVia === undefined
+                ? {}
+                : { authenticatedVia: principal.authenticatedVia }),
+            roles: ["member"],
+            permissions: permissionsOf(ontology.roles, ["member"]),
+            ...principalScopes(ontology.roles, ["member"]),
+        },
+        options: { newUserHook: true },
+    }).pipe(Effect.provideService(SqlClient.SqlClient, sql), Effect.flatMap((outcome) => outcome.validation.ok ? Effect.void : Effect.die(new Error("Invalid onNewUser input."))), Effect.catchCause((cause) => Effect.logWarning("ontology.channel.on_new_user_pending", Cause.pretty(cause)
+        .replace(/(postgres(?:ql)?:\/\/[^:\s]+:)[^@\s]+@/gi, "$1[redacted]@")
+        .replace(/Bearer\s+[^\s"']+/gi, "Bearer [redacted]")
+        .replace(/\b(?:sso|ssr|ssc|sss|ssk|ssw)_[A-Za-z0-9_-]+/g, "[redacted]")).pipe(Effect.annotateLogs({
+        operation: "ontology.channel.on_new_user",
+        userId: principal.id,
+        action: hook,
+    }))), Effect.andThen(sql.unsafe(`SELECT "on_new_user_completed_at" IS NULL AS "pending" FROM "${CHANNEL_USERS_TABLE}"
+       WHERE "user_id" = $1::uuid AND "created_via" NOT IN ('invite', 'email')`, [principal.id])), Effect.map(([stored]) => stored?.pending ?? false), Effect.orDie);
+}