@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/history.d.ts

@@ -0,0 +1,91 @@
+import { Schema } from "effect";
+import { WorkloadExecution } from "./workload.js";
+import type { StoredRecord } from "../runtime.js";
+import type { EntityModel } from "./model.js";
+import type { Params } from "./statement.js";
+export declare const EditKind: Schema.Literals<readonly ["create", "update", "delete", "link", "unlink"]>;
+export type EditKind = typeof EditKind.Type;
+/** One property's change. A relationship's change carries record ids. */
+export declare const Change: Schema.Struct<{
+    readonly before: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly after: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+export type Change = typeof Change.Type;
+export declare const Changes: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly before: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly after: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>>;
+export type Changes = typeof Changes.Type;
+/**
+ * A change an action made to one record, as the action response lists it. A link between two
+ * records is an edit of each, keyed by the relationship's name on that side.
+ */
+export declare const Edit: Schema.Struct<{
+    readonly entity: Schema.String;
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["create", "update", "delete", "link", "unlink"]>;
+    readonly changes: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly before: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly after: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
+}>;
+export type Edit = typeof Edit.Type;
+/** A row of `<entity>_history`. */
+export declare const HistoryEntry: Schema.Struct<{
+    readonly execution: Schema.optionalKey<Schema.Struct<{
+        readonly issuer: Schema.String;
+        readonly audience: Schema.String;
+        readonly organizationId: Schema.String;
+        readonly workspaceId: Schema.String;
+        readonly subject: Schema.String;
+        readonly deploymentId: Schema.String;
+        readonly ontologyDeploymentId: Schema.String;
+        readonly servingOntologyDeploymentId: Schema.String;
+        readonly ontologyOrigin: Schema.String;
+        readonly environment: Schema.Literals<readonly ["production", "preview"]>;
+        readonly jobName: Schema.NullOr<Schema.String>;
+        readonly runId: Schema.String;
+        readonly executionId: Schema.NullOr<Schema.String>;
+        readonly attemptId: Schema.String;
+        readonly generation: Schema.Number;
+        readonly tokenId: Schema.String;
+        readonly issuedAt: Schema.Number;
+        readonly expiresAt: Schema.Number;
+    }>>;
+    readonly id: Schema.String;
+    readonly recordId: Schema.String;
+    /** The qualified action, for example `lead.changeStatus`. */
+    readonly action: Schema.String;
+    /** Shared by every row one run of an action wrote. */
+    readonly actionId: Schema.String;
+    readonly kind: Schema.Literals<readonly ["create", "update", "delete", "link", "unlink"]>;
+    /** The user who ran the action; `null` when the platform wrote. */
+    readonly principalId: Schema.NullOr<Schema.String>;
+    readonly at: Schema.String;
+    readonly changes: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly before: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly after: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
+}>;
+export type HistoryEntry = typeof HistoryEntry.Type;
+/** The fields whose values differ. A created record diffs from nothing, a deleted one to nothing. */
+export declare function diffRecords(entity: EntityModel, before: StoredRecord | undefined, after: StoredRecord | undefined): Changes;
+export interface HistoryWrite {
+    readonly entity: EntityModel;
+    readonly edit: Edit;
+}
+export interface HistoryScope {
+    readonly execution?: WorkloadExecution;
+    readonly workflow?: {
+        readonly name: string;
+        readonly subject: string;
+    };
+    readonly action: string;
+    readonly actionId: string;
+    readonly principalId: string | null;
+    readonly branchId?: string;
+    readonly blobActionKey?: string;
+    readonly createIntent?: string;
+}
+/** `INSERT` of one history row; `at` is the transaction's time, shared by the whole action. */
+export declare function insertHistory(scope: HistoryScope, write: HistoryWrite, params: Params): string;

package/dist/runtime/history.js

@@ -0,0 +1,77 @@
+import { Schema } from "effect";
+import { canonicalJson } from "../manifest.js";
+import { WorkloadExecution } from "./workload.js";
+import { quoteIdentifier } from "../migrate/storage.js";
+import { uuidv7 } from "./ids.js";
+export const EditKind = Schema.Literals(["create", "update", "delete", "link", "unlink"]);
+/** One property's change. A relationship's change carries record ids. */
+export const Change = Schema.Struct({
+    before: Schema.Json,
+    after: Schema.Json,
+});
+export const Changes = Schema.Record(Schema.String, Change);
+/**
+ * A change an action made to one record, as the action response lists it. A link between two
+ * records is an edit of each, keyed by the relationship's name on that side.
+ */
+export const Edit = Schema.Struct({
+    entity: Schema.String,
+    id: Schema.String,
+    kind: EditKind,
+    changes: Changes,
+});
+/** A row of `<entity>_history`. */
+export const HistoryEntry = Schema.Struct({
+    execution: Schema.optionalKey(WorkloadExecution),
+    id: Schema.String,
+    recordId: Schema.String,
+    /** The qualified action, for example `lead.changeStatus`. */
+    action: Schema.String,
+    /** Shared by every row one run of an action wrote. */
+    actionId: Schema.String,
+    kind: EditKind,
+    /** The user who ran the action; `null` when the platform wrote. */
+    principalId: Schema.NullOr(Schema.String),
+    at: Schema.String,
+    changes: Changes,
+});
+/**
+ * The fields a write's history diffs: declared properties and `<relationship>_id` keys. A projection
+ * such as the user's `roles` changes through no column write; the writes that change it record
+ * their own rows.
+ */
+function changedFields(entity) {
+    return entity.fields.filter((field) => field.source !== "system" && field.source !== "projection");
+}
+function same(left, right) {
+    return canonicalJson(left ?? null) === canonicalJson(right ?? null);
+}
+/** The fields whose values differ. A created record diffs from nothing, a deleted one to nothing. */
+export function diffRecords(entity, before, after) {
+    const changes = {};
+    for (const field of changedFields(entity)) {
+        const previous = (before?.[field.name] ?? null);
+        const next = (after?.[field.name] ?? null);
+        if (!same(previous, next)) {
+            changes[field.name] = { before: previous, after: next };
+        }
+    }
+    return changes;
+}
+/** `INSERT` of one history row; `at` is the transaction's time, shared by the whole action. */
+export function insertHistory(scope, write, params) {
+    const table = quoteIdentifier(write.entity.historyTable);
+    const values = [
+        params.add(uuidv7(), "uuid"),
+        params.add(write.edit.id, "uuid"),
+        params.add(scope.action, "text"),
+        params.add(scope.actionId, "uuid"),
+        params.add(write.edit.kind, "text"),
+        params.add(scope.principalId, "uuid"),
+        "now()",
+        params.add(JSON.stringify(write.edit.changes), "jsonb"),
+    ];
+    return (`INSERT INTO ${table} ` +
+        '("id", "record_id", "action", "action_id", "kind", "principal_id", "at", "changes") ' +
+        `VALUES (${values.join(", ")})`);
+}

package/dist/runtime/ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A UUIDv7 (RFC 9562): a millisecond timestamp, a 12-bit sequence and random bits. Ids from one
+ * process sort in the order they were made, also within a millisecond, so record ids keep index
+ * locality and the history rows of one action, which share their `at`, read back in order.
+ */
+export declare function uuidv7(): string;

package/dist/runtime/ids.js

@@ -0,0 +1,39 @@
+import { randomBytes } from "node:crypto";
+let lastMillis = 0;
+let sequence = 0;
+/**
+ * A UUIDv7 (RFC 9562): a millisecond timestamp, a 12-bit sequence and random bits. Ids from one
+ * process sort in the order they were made, also within a millisecond, so record ids keep index
+ * locality and the history rows of one action, which share their `at`, read back in order.
+ */
+export function uuidv7() {
+    const now = Date.now();
+    if (now > lastMillis) {
+        lastMillis = now;
+        sequence = 0;
+    }
+    else {
+        sequence += 1;
+        if (sequence > 0xfff) {
+            lastMillis += 1;
+            sequence = 0;
+        }
+    }
+    const bytes = randomBytes(16);
+    let millis = lastMillis;
+    for (let index = 5; index >= 0; index -= 1) {
+        bytes[index] = millis % 256;
+        millis = Math.floor(millis / 256);
+    }
+    bytes[6] = 0x70 | (sequence >> 8);
+    bytes[7] = sequence & 0xff;
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const hex = bytes.toString("hex");
+    return [
+        hex.slice(0, 8),
+        hex.slice(8, 12),
+        hex.slice(12, 16),
+        hex.slice(16, 20),
+        hex.slice(20, 32),
+    ].join("-");
+}

package/dist/runtime/member-tables.d.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+/** Legacy workspace databases remain readable before their next additive migration. */
+export declare function channelUsersAvailable(sql: SqlClient.SqlClient): Effect.Effect<boolean, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Records how a user came to be: `invite`, `email` or a channel's sign-up. The first record stays. */
+export declare function recordUserCreation(sql: SqlClient.SqlClient, userId: string, via: string): Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;
+/** Session revocation integration point for every channel-app issuer (including Mini Apps). */
+export declare function revokeMemberSessions(sql: SqlClient.SqlClient, userId: string): Effect.Effect<void, import("effect/unstable/sql/SqlError").SqlError, never>;

package/dist/runtime/member-tables.js

@@ -0,0 +1,33 @@
+import { Effect } from "effect";
+import { CHANNEL_USERS_TABLE } from "../migrate/storage.js";
+// @legacy ontology.pre-upgrade-database-tolerance
+/** Legacy workspace databases remain readable before their next additive migration. */
+export function channelUsersAvailable(sql) {
+    return sql
+        .unsafe(`SELECT to_regclass($1) IS NOT NULL AS "present"`, [
+        CHANNEL_USERS_TABLE,
+    ])
+        .pipe(Effect.map(([table]) => table?.present === true));
+}
+/** Records how a user came to be: `invite`, `email` or a channel's sign-up. The first record stays. */
+export function recordUserCreation(sql, userId, via) {
+    return Effect.gen(function* () {
+        if (yield* channelUsersAvailable(sql)) {
+            yield* sql.unsafe(`INSERT INTO "${CHANNEL_USERS_TABLE}" ("user_id", "created_via") VALUES ($1::uuid, $2)
+         ON CONFLICT ("user_id") DO NOTHING`, [userId, via]);
+        }
+    });
+}
+/** Session revocation integration point for every channel-app issuer (including Mini Apps). */
+export function revokeMemberSessions(sql, userId) {
+    return Effect.gen(function* () {
+        const [tables] = yield* sql.unsafe(`SELECT to_regclass('_oauth_grants') IS NOT NULL AS "oauth",
+       to_regclass('_federation_sessions') IS NOT NULL AS "federation"`);
+        if (tables?.oauth) {
+            yield* sql.unsafe(`UPDATE "_oauth_grants" SET "revoked_at" = now() WHERE "user_id" = $1::uuid AND "revoked_at" IS NULL`, [userId]);
+        }
+        if (tables?.federation) {
+            yield* sql.unsafe(`DELETE FROM "_federation_sessions" WHERE "user_id" = $1::uuid`, [userId]);
+        }
+    });
+}

package/dist/runtime/member-writes.d.ts

@@ -0,0 +1,78 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { ActionRejected, type Conflict, type NotFound } from "../errors.js";
+import type { EmailTemplateManifest } from "../manifest.js";
+import type { StoredRecord } from "../runtime.js";
+import { UnknownRole } from "./errors.js";
+import type { EntityModel } from "./model.js";
+import { type WriteContext } from "./writes.js";
+/**
+ * Member management: inviting a member, granting and revoking roles, and deactivating and
+ * reactivating a member. The generated `user` actions, the `User` handle's writes in a handler and
+ * the console's and CLI's principal functions all run these, under the scope of the write: history
+ * names its action and principal. Only members are managed here; a service's roles come with its
+ * API key.
+ */
+export interface MemberWriteContext extends WriteContext {
+    /** The client whose transaction the write runs on, for the tables beside the user. */
+    readonly sql: SqlClient.SqlClient;
+    /** The roles the ontology declares, `member` included. */
+    readonly roles: ReadonlyArray<string>;
+}
+/** Implicit human roles cannot be assigned or revoked; their authority comes from resolution. */
+export declare function refuseMember(roles: ReadonlyArray<string>): Effect.Effect<void, UnknownRole>;
+/** Only declared business roles may be granted; implicit built-in roles are never assignable. */
+export declare function requireGrantable(declared: ReadonlyArray<string>, roles: ReadonlyArray<string>): Effect.Effect<void, UnknownRole>;
+/** Grants declared roles to a member. A role the member holds changes nothing. */
+export declare function grantMemberRoles(context: MemberWriteContext, entity: EntityModel, input: {
+    readonly id: string;
+    readonly roles: ReadonlyArray<string>;
+}): Effect.Effect<StoredRecord, UnknownRole | NotFound | SqlError>;
+/**
+ * Revokes roles from a member, or every role. A role the member does not hold, or one the ontology
+ * no longer declares, is removed without error.
+ */
+export declare function revokeMemberRoles(context: MemberWriteContext, entity: EntityModel, input: {
+    readonly id: string;
+    readonly roles: ReadonlyArray<string> | "all";
+}): Effect.Effect<StoredRecord, UnknownRole | NotFound | SqlError>;
+/**
+ * Creates a member for an email no user has, with declared roles: a `create` row, and an `update`
+ * row for the roles. The member is linked to their identity by email at their first sign-in. An
+ * email a user has fails with Conflict, through the unique index, so concurrent invitations of one
+ * email fail too. The name defaults to the email.
+ */
+export declare function inviteMember(context: MemberWriteContext, entity: EntityModel, input: {
+    readonly email: string;
+    readonly name?: string | undefined;
+    readonly roles?: ReadonlyArray<string> | undefined;
+}): Effect.Effect<StoredRecord, UnknownRole | Conflict | SqlError>;
+/**
+ * Deactivates or reactivates a member. An inactive member keeps their roles and history, and the
+ * service rejects their requests. Deactivation also ends their sessions, even when they were
+ * inactive already. A change that leaves `active` as it was writes no history.
+ */
+export declare function setMemberActive(context: MemberWriteContext, entity: EntityModel, input: {
+    readonly id: string;
+    readonly active: boolean;
+}): Effect.Effect<StoredRecord, NotFound | SqlError>;
+/** A sign-in email an action queued: the row, the address and the path its link opens. */
+export interface QueuedSignInEmail {
+    readonly id: string;
+    readonly email: string;
+    readonly returnTo: string;
+}
+/**
+ * Queues an email with a sign-in link for an active member, in the action's transaction: a row of
+ * {@link SIGN_IN_EMAILS_TABLE}, sent once the action commits. `template` is the wire name of one of
+ * the ontology's `emails`, or none for the platform's own email; `returnTo` is the path of the app
+ * the link opens, `/` by default. What the caller can fix is ActionRejected; a service or an
+ * unknown id is NotFound.
+ */
+export declare function queueSignInEmail(context: MemberWriteContext, entity: EntityModel, emails: Readonly<Record<string, EmailTemplateManifest>>, input: {
+    readonly id: string;
+    readonly template?: string | undefined;
+    readonly returnTo?: string | undefined;
+    readonly values?: Readonly<Record<string, string>> | undefined;
+}): Effect.Effect<QueuedSignInEmail, ActionRejected | NotFound | SqlError>;

package/dist/runtime/member-writes.js

@@ -0,0 +1,202 @@
+import { Effect } from "effect";
+import { appReturnPath, emailValueNames, MAX_EMAIL_TEXT, MAX_EMAIL_VALUES } from "../emails.js";
+import { ActionRejected } from "../errors.js";
+import { MEMBER_ROLE, FEEDBACK_REPORTER_ROLE, toCamelCase, toSnakeCase } from "../names.js";
+import { SIGN_IN_EMAILS_TABLE } from "../storage/tables.js";
+import { UnknownRole } from "./errors.js";
+import { uuidv7 } from "./ids.js";
+import { recordUserCreation, revokeMemberSessions } from "./member-tables.js";
+import { loadRecord, notFound } from "./reads.js";
+import { changeUserRoles, createRecord, updateRecord } from "./writes.js";
+/** Implicit human roles cannot be assigned or revoked; their authority comes from resolution. */
+export function refuseMember(roles) {
+    const reporter = roles.find((name) => toSnakeCase(name) === FEEDBACK_REPORTER_ROLE);
+    if (reporter !== undefined) {
+        return Effect.fail(new UnknownRole({
+            role: reporter,
+            message: "feedback_reporter is implicit human authority; it cannot be granted or revoked.",
+        }));
+    }
+    if (!roles.includes(MEMBER_ROLE)) {
+        return Effect.void;
+    }
+    return Effect.fail(new UnknownRole({
+        role: MEMBER_ROLE,
+        message: `${MEMBER_ROLE} is held by every active member; it cannot be granted or revoked.`,
+    }));
+}
+/** Only declared business roles may be granted; implicit built-in roles are never assignable. */
+export function requireGrantable(declared, roles) {
+    return Effect.gen(function* () {
+        yield* refuseMember(roles);
+        const unknown = roles.find((candidate) => !declared.includes(candidate));
+        if (unknown !== undefined) {
+            return yield* new UnknownRole({
+                role: unknown,
+                message: `${unknown} is not a role of this ontology.`,
+            });
+        }
+    });
+}
+/** The member with this id, locked until the transaction ends. A service is not found. */
+function lockMember(context, entity, id) {
+    return Effect.gen(function* () {
+        const user = yield* loadRecord(context, entity, id, "update");
+        if (user === undefined || user.kind !== "member") {
+            return yield* notFound(entity, id);
+        }
+        return user;
+    });
+}
+/** Grants declared roles to a member. A role the member holds changes nothing. */
+export function grantMemberRoles(context, entity, input) {
+    return Effect.gen(function* () {
+        yield* requireGrantable(context.roles, input.roles);
+        yield* lockMember(context, entity, input.id);
+        return yield* changeUserRoles(context, entity, input.id, { grant: input.roles });
+    });
+}
+/**
+ * Revokes roles from a member, or every role. A role the member does not hold, or one the ontology
+ * no longer declares, is removed without error.
+ */
+export function revokeMemberRoles(context, entity, input) {
+    return Effect.gen(function* () {
+        yield* refuseMember(input.roles === "all" ? [] : input.roles);
+        yield* lockMember(context, entity, input.id);
+        return yield* changeUserRoles(context, entity, input.id, { revoke: input.roles });
+    });
+}
+/**
+ * Creates a member for an email no user has, with declared roles: a `create` row, and an `update`
+ * row for the roles. The member is linked to their identity by email at their first sign-in. An
+ * email a user has fails with Conflict, through the unique index, so concurrent invitations of one
+ * email fail too. The name defaults to the email.
+ */
+export function inviteMember(context, entity, input) {
+    return Effect.gen(function* () {
+        const roles = input.roles ?? [];
+        yield* requireGrantable(context.roles, roles);
+        // Emails are stored lowercased, as sign-in links them.
+        const email = input.email.trim().toLowerCase();
+        const user = yield* createRecord(context, entity, {
+            name: input.name?.trim() || email,
+            email,
+            kind: "member",
+            // An unguarded write: no scope applies, so ScopeViolated cannot occur.
+        }).pipe(Effect.catchTag(["NotFound", "ScopeViolated"], (error) => Effect.die(error)));
+        const id = user.id;
+        yield* recordUserCreation(context.sql, id, "invite");
+        return roles.length === 0
+            ? user
+            : yield* changeUserRoles(context, entity, id, { grant: roles }).pipe(Effect.catchTag("NotFound", (error) => Effect.die(error)));
+    });
+}
+/**
+ * Deactivates or reactivates a member. An inactive member keeps their roles and history, and the
+ * service rejects their requests. Deactivation also ends their sessions, even when they were
+ * inactive already. A change that leaves `active` as it was writes no history.
+ */
+export function setMemberActive(context, entity, input) {
+    return Effect.gen(function* () {
+        const user = yield* lockMember(context, entity, input.id);
+        const id = user.id;
+        const after = user.active === input.active
+            ? user
+            : yield* updateRecord(context, entity, id, { active: input.active }).pipe(Effect.catchTag(["Conflict", "ScopeViolated"], (error) => Effect.die(error)));
+        if (!input.active) {
+            yield* revokeMemberSessions(context.sql, id);
+        }
+        return after;
+    });
+}
+/**
+ * The values a sign-in email is sent with, checked against its template: every value the template
+ * uses, and no other, each a text of at most {@link MAX_EMAIL_TEXT} characters. Without a template
+ * the platform's own email takes none.
+ */
+function signInEmailValues(name, template, values) {
+    const reject = (message) => Effect.fail(new ActionRejected({ message }));
+    if (values === undefined) {
+        values = {};
+    }
+    if (typeof values !== "object" || values === null || Array.isArray(values)) {
+        return reject("values maps each value the email uses to its text.");
+    }
+    const entries = Object.entries(values);
+    if (entries.length > MAX_EMAIL_VALUES) {
+        return reject(`An email takes at most ${MAX_EMAIL_VALUES} values.`);
+    }
+    for (const [key, value] of entries) {
+        if (typeof value !== "string") {
+            return reject(`The value ${key} is a text.`);
+        }
+        if (value.length > MAX_EMAIL_TEXT) {
+            return reject(`The value ${key} has at most ${MAX_EMAIL_TEXT} characters.`);
+        }
+    }
+    if (template === undefined) {
+        return entries.length === 0
+            ? Effect.succeed({})
+            : reject("values fill one of the ontology's emails; name it with template.");
+    }
+    const used = emailValueNames(template);
+    const missing = used.filter((key) => !Object.hasOwn(values, key));
+    const unknown = entries.map(([key]) => key).filter((key) => !used.includes(key));
+    if (missing.length > 0) {
+        return reject(`The email ${name} needs the values ${missing.join(", ")}.`);
+    }
+    if (unknown.length > 0) {
+        return reject(`The email ${name} does not use the values ${unknown.join(", ")}.`);
+    }
+    return Effect.succeed(Object.fromEntries(entries));
+}
+/**
+ * Queues an email with a sign-in link for an active member, in the action's transaction: a row of
+ * {@link SIGN_IN_EMAILS_TABLE}, sent once the action commits. `template` is the wire name of one of
+ * the ontology's `emails`, or none for the platform's own email; `returnTo` is the path of the app
+ * the link opens, `/` by default. What the caller can fix is ActionRejected; a service or an
+ * unknown id is NotFound.
+ */
+export function queueSignInEmail(context, entity, emails, input) {
+    return Effect.gen(function* () {
+        const user = yield* lockMember(context, entity, input.id);
+        const email = typeof user.email === "string" ? user.email.trim().toLowerCase() : "";
+        if (user.active === false) {
+            return yield* new ActionRejected({
+                message: "The member is inactive; reactivate them before sending a sign-in link.",
+            });
+        }
+        if (email === "") {
+            return yield* new ActionRejected({ message: "The member has no email address." });
+        }
+        const template = input.template === undefined ? undefined : emails[input.template];
+        if (input.template !== undefined && template === undefined) {
+            return yield* new ActionRejected({
+                message: `${toCamelCase(input.template)} is not one of the ontology's emails.`,
+            });
+        }
+        const name = input.template === undefined ? undefined : toCamelCase(input.template);
+        const values = yield* signInEmailValues(name, template, input.values);
+        const returnTo = appReturnPath(input.returnTo ?? "/");
+        if (returnTo === undefined) {
+            return yield* new ActionRejected({
+                message: "returnTo is a path of the app, such as /shared/123.",
+            });
+        }
+        const id = uuidv7();
+        yield* context.sql.unsafe(`INSERT INTO "${SIGN_IN_EMAILS_TABLE}"
+         ("id", "user_id", "email", "template", "values", "return_to", "action_id", "sender_id", "status")
+       VALUES ($1::uuid, $2::uuid, $3, $4, $5::jsonb, $6, $7::uuid, $8::uuid, 'pending')`, [
+            id,
+            user.id,
+            email,
+            input.template ?? null,
+            JSON.stringify(values),
+            returnTo,
+            context.scope.actionId,
+            context.scope.principalId,
+        ]);
+        return { id, email, returnTo };
+    });
+}

package/dist/runtime/metric-query.d.ts

@@ -0,0 +1,19 @@
+import { Effect } from "effect";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import { type Where } from "../query.js";
+import type { StoredRecord } from "../runtime.js";
+import { InvalidQuery } from "./errors.js";
+import type { EntityModel } from "./model.js";
+import { type SqlContext } from "./reads.js";
+export declare function indexedFieldsOf(entity: EntityModel): ReadonlySet<string>;
+/**
+ * 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 declare function anchored(entity: EntityModel, where: Where | undefined): boolean;
+/**
+ * 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 declare function runMetricQuery(context: SqlContext, entity: EntityModel, options: unknown): Effect.Effect<ReadonlyArray<StoredRecord>, InvalidQuery | SqlError>;