@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/sign-in.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Who may become a member by signing in. `invited`: only a person whose email a member row already
+ * holds, created by an invitation or a role grant; anyone else is refused. `open`: anyone who signs
+ * in becomes a member holding only `member`, as a customer-facing app wants.
+ */
+export declare const SIGN_IN_POLICIES: readonly ["invited", "open"];
+export type SignInPolicy = (typeof SIGN_IN_POLICIES)[number];
+/** An internal app is closed by default: a person enters by invitation. */
+export declare const DEFAULT_SIGN_IN_POLICY: SignInPolicy;
+/** Channels this SDK can enforce at admission. */
+export declare const CHANNEL_PROVIDERS: readonly ["telegram"];
+export type ChannelProvider = (typeof CHANNEL_PROVIDERS)[number];
+/** How people become members of the app. Email and channel admission are independent. */
+export interface SignInOptions {
+    readonly policy: SignInPolicy;
+    readonly browser?: BrowserSignInOptions;
+    readonly channels?: Readonly<Partial<Record<ChannelProvider, SignInPolicy>>>;
+    /** Idempotent, input-free app action, run as member after channel self-registration. */
+    readonly onNewUser?: string;
+    /**
+     * Whether the platform's sign-in code emails also carry a link to the app's `/sign-in` page with
+     * the address and code in its fragment, so the person signs in without typing the code. Off when
+     * omitted. The page's `useSignIn()` reads the link; the app submits the code at once or asks the
+     * person to confirm. The link signs in whichever browser opens it.
+     */
+    readonly codeLink?: boolean;
+}
+/**
+ * How a person signs in with an address. `code`: a six-digit code, for a member who has signed in
+ * with Neon Auth before, so their Neon Auth account exists. `link`: an emailed sign-in link, for
+ * everyone else; Neon Auth sends codes only to existing accounts, and a link creates the account.
+ */
+export declare const SIGN_IN_METHODS: readonly ["code", "link"];
+export type SignInMethod = (typeof SIGN_IN_METHODS)[number];
+/**
+ * Whether an address may sign in, and how, as `POST /api/ontology/sign-in/check` answers before the
+ * app sends an email. Under `invited`, only an active member's address is allowed. Under `open`,
+ * every address is allowed with `link`, so the answer reveals nothing about who has signed in.
+ */
+export type SignInCheck = {
+    readonly allowed: false;
+} | {
+    readonly allowed: true;
+    readonly method: SignInMethod;
+};
+export declare function isSignInPolicy(value: unknown): value is SignInPolicy;
+/** Workspace-owned browser authentication policy; omission keeps legacy behavior. */
+export interface BrowserSignInOptions {
+    readonly methods: ReadonlyArray<BrowserSignInMethod>;
+    readonly primary: BrowserSignInMethod;
+    readonly autoRedirect: boolean;
+    readonly local?: {
+        readonly port: number;
+    };
+}
+export type BrowserSignInMethod = "email" | "segmentstream";
+/** Returns a stable machine code for invalid declarations. */
+export declare function validateBrowserSignIn(value: unknown): string | undefined;

package/dist/sign-in.js

@@ -0,0 +1,57 @@
+/**
+ * Who may become a member by signing in. `invited`: only a person whose email a member row already
+ * holds, created by an invitation or a role grant; anyone else is refused. `open`: anyone who signs
+ * in becomes a member holding only `member`, as a customer-facing app wants.
+ */
+export const SIGN_IN_POLICIES = ["invited", "open"];
+/** An internal app is closed by default: a person enters by invitation. */
+export const DEFAULT_SIGN_IN_POLICY = "invited";
+/** Channels this SDK can enforce at admission. */
+export const CHANNEL_PROVIDERS = ["telegram"];
+/**
+ * How a person signs in with an address. `code`: a six-digit code, for a member who has signed in
+ * with Neon Auth before, so their Neon Auth account exists. `link`: an emailed sign-in link, for
+ * everyone else; Neon Auth sends codes only to existing accounts, and a link creates the account.
+ */
+export const SIGN_IN_METHODS = ["code", "link"];
+export function isSignInPolicy(value) {
+    return SIGN_IN_POLICIES.includes(value);
+}
+/** Returns a stable machine code for invalid declarations. */
+export function validateBrowserSignIn(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return "invalid_browser";
+    }
+    const browser = value;
+    if (Object.keys(browser).some((key) => !["methods", "primary", "autoRedirect", "local"].includes(key))) {
+        return "unknown_browser_field";
+    }
+    const methods = browser.methods;
+    if (!Array.isArray(methods) ||
+        methods.length === 0 ||
+        new Set(methods).size !== methods.length ||
+        methods.some((method) => method !== "email" && method !== "segmentstream")) {
+        return "invalid_browser_methods";
+    }
+    if (!methods.includes(browser.primary)) {
+        return "invalid_browser_primary";
+    }
+    if (typeof browser.autoRedirect !== "boolean" ||
+        (browser.autoRedirect && (methods.length !== 1 || methods[0] !== "segmentstream"))) {
+        return "invalid_browser_auto_redirect";
+    }
+    if (browser.local !== undefined) {
+        const local = browser.local;
+        if (!methods.includes("segmentstream") ||
+            !local ||
+            typeof local !== "object" ||
+            Array.isArray(local) ||
+            Object.keys(local).some((key) => key !== "port") ||
+            !Number.isInteger(local.port) ||
+            Number(local.port) < 1 ||
+            Number(local.port) > 65535) {
+            return "invalid_browser_local";
+        }
+    }
+    return undefined;
+}

package/dist/source.d.ts

@@ -0,0 +1,30 @@
+import type { EntityManifest } from "./manifest.js";
+/** A warehouse asset supplies a warehouse-backed entity's records. Keys name physical columns. */
+export interface WarehouseSource {
+    readonly asset: string;
+    readonly key: ReadonlyArray<string>;
+    readonly currency?: string;
+}
+export declare function warehouse(asset: string, options: Omit<WarehouseSource, "asset">): WarehouseSource;
+/** Normalize scalar pipeline and warehouse schema spellings without accepting nested values. */
+export declare function warehouseColumnType(value: unknown): string | undefined;
+export declare function compatibleWarehouseColumn(propertyType: string, field: {
+    readonly type?: unknown;
+    readonly mode?: unknown;
+    readonly fields?: unknown;
+}): boolean;
+export declare class SourceMappingError extends Error {
+    readonly entity: string;
+    readonly asset: string;
+    readonly column?: string | undefined;
+    constructor(entity: string, asset: string, column?: string | undefined);
+}
+/** Validate mappings against a deployment's pipeline schema, never against live warehouse values. */
+export declare function validateWarehouseSource(entity: EntityManifest, assets: readonly unknown[]): {
+    readonly schema: readonly unknown[];
+    readonly partitioning: {
+        readonly type: string;
+        readonly column?: string;
+        readonly timezone?: string;
+    };
+};

package/dist/source.js

@@ -0,0 +1,107 @@
+export function warehouse(asset, options) {
+    return { asset, ...options };
+}
+/** Normalize scalar pipeline and warehouse schema spellings without accepting nested values. */
+export function warehouseColumnType(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const type = value.replace(/^!/, "").toUpperCase();
+    if (/^(?:STRING|TEXT)$/.test(type)) {
+        return "text";
+    }
+    if (/^(?:INTEGER|INT8|INT16|INT32|INT64)$/.test(type)) {
+        return "integer";
+    }
+    if (/^(?:FLOAT|FLOAT32|FLOAT64|DOUBLE|NUMERIC|BIGNUMERIC|DECIMAL(?:\(\d+,\s*\d+\))?)$/.test(type)) {
+        return "number";
+    }
+    if (type === "BOOL" || type === "BOOLEAN") {
+        return "boolean";
+    }
+    if (type === "DATE") {
+        return "date";
+    }
+    if (type === "TIMESTAMP") {
+        return "timestamp";
+    }
+    return undefined;
+}
+export function compatibleWarehouseColumn(propertyType, field) {
+    if ((typeof field.mode === "string" && field.mode.toUpperCase() === "REPEATED") ||
+        (Array.isArray(field.fields) && field.fields.length > 0)) {
+        return false;
+    }
+    const type = warehouseColumnType(field.type);
+    return (type !== undefined &&
+        (type === propertyType ||
+            (propertyType === "select" && type === "text") ||
+            (propertyType === "number" && type === "integer")));
+}
+export class SourceMappingError extends Error {
+    entity;
+    asset;
+    column;
+    constructor(entity, asset, column) {
+        super(`Invalid warehouse source ${entity}: ${asset}${column ? ` (${column})` : ""}.`);
+        this.entity = entity;
+        this.asset = asset;
+        this.column = column;
+        this.name = "SourceMappingError";
+    }
+}
+/** Validate mappings against a deployment's pipeline schema, never against live warehouse values. */
+export function validateWarehouseSource(entity, assets) {
+    const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+    const source = entity.source;
+    const fail = (column) => {
+        throw new SourceMappingError(entity.name, source?.asset ?? "missing", column);
+    };
+    if (!source || !source.key.length || new Set(source.key).size !== source.key.length) {
+        fail();
+    }
+    const asset = assets.map(record).find((asset) => asset?.key === source.asset);
+    if (!asset || !Array.isArray(asset.modelSchema)) {
+        fail();
+    }
+    const schema = asset.modelSchema;
+    const columns = new Map(schema.flatMap((value) => {
+        const field = record(value);
+        return field && typeof field.name === "string" ? [[field.name, field]] : [];
+    }));
+    for (const key of source.key) {
+        const field = columns.get(key);
+        const type = warehouseColumnType(field?.type);
+        if (!field || !type || !compatibleWarehouseColumn(type, field)) {
+            fail(key);
+        }
+    }
+    for (const property of entity.properties) {
+        const field = columns.get(property.column ?? "");
+        if (!field || !compatibleWarehouseColumn(property.type, field)) {
+            fail(property.column ?? property.name);
+        }
+    }
+    const rawPartition = asset.partitioning;
+    const partition = rawPartition === undefined ? { type: "unpartitioned" } : record(rawPartition);
+    if (!partition || typeof partition.type !== "string") {
+        fail();
+    }
+    const type = partition.type;
+    const column = typeof partition.column === "string" ? partition.column : undefined;
+    if (type !== "unpartitioned" &&
+        (!column ||
+            !entity.properties.some((p) => p.column === column && ["date", "timestamp"].includes(p.type)))) {
+        fail(column);
+    }
+    const timezone = typeof partition.timezone === "string" ? partition.timezone : "UTC";
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: timezone }).format(0);
+    }
+    catch {
+        fail(column);
+    }
+    return { schema, partitioning: { type, ...(column ? { column } : {}), timezone } };
+}

package/dist/start-recovery-contract.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What the start recovery run and the ontology service agree on. The `workflows` entry imports this
+ * module for the run's body and step; the service imports it for the step's implementation. It
+ * imports nothing and holds no I/O.
+ *
+ * An action whose triggers may fire arms a recovery run before its transaction opens. The run
+ * sleeps, then sweeps the pending starts of `_workflow_starts`: the rows an earlier request's
+ * commit left without a run id because the process died or the Workflow SDK refused the start.
+ * Sleeping costs nothing and touches no database, so an idle workspace is never visited.
+ */
+/** A recovery run's first sweep, after the request that armed it has committed or failed. */
+export declare const RECOVERY_FIRST_SWEEP_MS = 60000;
+/**
+ * After an empty sweep, one more a minute later, so that every request the run covers has
+ * committed before the run's last look. A request is covered when its transaction deadline falls
+ * before the run's horizon: its first sweep plus this delay.
+ */
+export declare const RECOVERY_CONFIRM_MS = 60000;
+/** Sleeps between sweeps while starts keep failing; the last one repeats. */
+export declare const RECOVERY_RETRY_MS: ReadonlyArray<number>;
+/** Coverage the arming request keeps back from the run's horizon, for the start's own latency. */
+export declare const RECOVERY_COVERAGE_MARGIN_MS = 5000;
+/** The sweeps one run makes at most; rows still pending then are left for an operator's sweep. */
+export declare const RECOVERY_MAX_SWEEPS = 32;
+/** The step's input: the horizon the run answers for, from its second sweep on. */
+export interface StartRecoveryInput {
+    /** Count as waiting only the pending rows created before this instant, ISO 8601. */
+    readonly before?: string;
+}
+/** What one sweep did and what is left. */
+export interface StartRecoveryOutcome {
+    readonly started: number;
+    readonly failed: number;
+    /** Pending rows that failed too often; the automatic sweep skips them. */
+    readonly abandoned: number;
+    /** Pending rows an automatic sweep still takes, created before `before` when it was given. */
+    readonly waiting: number;
+    /** The database's clock at the sweep, ISO 8601 with milliseconds. */
+    readonly at: string;
+}
+/** A recovery run's result: its sweeps added up. */
+export interface StartRecoveryReport {
+    readonly sweeps: number;
+    readonly started: number;
+    readonly failed: number;
+    /** Rows created before the run's horizon that were still pending when the run ended. */
+    readonly waiting: number;
+    readonly abandoned: number;
+}

package/dist/start-recovery-contract.js

@@ -0,0 +1,26 @@
+/**
+ * What the start recovery run and the ontology service agree on. The `workflows` entry imports this
+ * module for the run's body and step; the service imports it for the step's implementation. It
+ * imports nothing and holds no I/O.
+ *
+ * An action whose triggers may fire arms a recovery run before its transaction opens. The run
+ * sleeps, then sweeps the pending starts of `_workflow_starts`: the rows an earlier request's
+ * commit left without a run id because the process died or the Workflow SDK refused the start.
+ * Sleeping costs nothing and touches no database, so an idle workspace is never visited.
+ */
+/** A recovery run's first sweep, after the request that armed it has committed or failed. */
+export const RECOVERY_FIRST_SWEEP_MS = 60_000;
+/**
+ * After an empty sweep, one more a minute later, so that every request the run covers has
+ * committed before the run's last look. A request is covered when its transaction deadline falls
+ * before the run's horizon: its first sweep plus this delay.
+ */
+export const RECOVERY_CONFIRM_MS = 60_000;
+/** Sleeps between sweeps while starts keep failing; the last one repeats. */
+export const RECOVERY_RETRY_MS = [
+    60_000, 120_000, 300_000, 600_000, 1_800_000, 3_600_000,
+];
+/** Coverage the arming request keeps back from the run's horizon, for the start's own latency. */
+export const RECOVERY_COVERAGE_MARGIN_MS = 5_000;
+/** The sweeps one run makes at most; rows still pending then are left for an operator's sweep. */
+export const RECOVERY_MAX_SWEEPS = 32;

package/dist/start-recovery.d.ts

@@ -0,0 +1,27 @@
+import { type StartRecoveryReport } from "./start-recovery-contract.js";
+export type { StartRecoveryInput, StartRecoveryOutcome, StartRecoveryReport, } from "./start-recovery-contract.js";
+/**
+ * The start recovery run's body, for the platform workflow `ontologyWorkflows()` compiles into the
+ * workspace's bundle. This module is part of the `workflows` entry, which the Workflow SDK bundles
+ * for a runtime without Node built-ins: it imports none, and none of the SDK. Its step only calls
+ * the ontology service through the process's workflow binding, as `agentTask`'s steps do.
+ */
+/** `recoverWorkflowStarts` was called outside a `"use workflow"` body. Marked fatal. */
+export declare class StartRecoveryWorkflowRequired extends Error {
+    readonly fatal = true;
+    constructor();
+}
+/**
+ * Sleeps, then sweeps the pending starts until none created before the run's horizon is left, and
+ * answers with what it did. The horizon is the first sweep's instant plus {@link RECOVERY_CONFIRM_MS},
+ * read from the database's clock in the step's result so that a replay computes the same value.
+ * An empty sweep is confirmed by one more at the horizon; a sweep that failed starts is followed by
+ * another after a growing delay, until every such row is started or abandoned. Rows created after
+ * the horizon belong to the runs their own requests armed.
+ */
+export declare function recoverWorkflowStarts(
+/** Shorter sleeps, for tests; the generated platform workflow passes none. */
+delays?: {
+    readonly firstSweepMs?: number;
+    readonly confirmMs?: number;
+}): Promise<StartRecoveryReport>;

package/dist/start-recovery.js

@@ -0,0 +1,81 @@
+import { RECOVERY_CONFIRM_MS, RECOVERY_FIRST_SWEEP_MS, RECOVERY_MAX_SWEEPS, RECOVERY_RETRY_MS, } from "./start-recovery-contract.js";
+import { boundStep } from "./workflow-runtime.js";
+/**
+ * The start recovery run's body, for the platform workflow `ontologyWorkflows()` compiles into the
+ * workspace's bundle. This module is part of the `workflows` entry, which the Workflow SDK bundles
+ * for a runtime without Node built-ins: it imports none, and none of the SDK. Its step only calls
+ * the ontology service through the process's workflow binding, as `agentTask`'s steps do.
+ */
+/** `recoverWorkflowStarts` was called outside a `"use workflow"` body. Marked fatal. */
+export class StartRecoveryWorkflowRequired extends Error {
+    fatal = true;
+    constructor() {
+        super('recoverWorkflowStarts runs only in the "use workflow" body of the platform\'s recovery ' +
+            "workflow, which ontologyWorkflows() compiles.");
+        this.name = "StartRecoveryWorkflowRequired";
+    }
+}
+/**
+ * The Workflow SDK's `sleep` inside a `"use workflow"` body, read from the `globalThis` symbol its
+ * workflow sandbox sets; `undefined` in a step and outside a workflow.
+ */
+function workflowSleep() {
+    const sleep = globalThis[Symbol.for("WORKFLOW_SLEEP")];
+    return typeof sleep === "function"
+        ? sleep
+        : undefined;
+}
+/** One sweep of the pending starts, through the service that serves this process's runs. */
+async function recoverStartsStep(input) {
+    "use step";
+    const { binding, step } = boundStep();
+    return binding.recoverStarts(step, input);
+}
+function add(report, outcome) {
+    return {
+        sweeps: report.sweeps + 1,
+        started: report.started + outcome.started,
+        failed: report.failed + outcome.failed,
+        waiting: outcome.waiting,
+        abandoned: outcome.abandoned,
+    };
+}
+/**
+ * Sleeps, then sweeps the pending starts until none created before the run's horizon is left, and
+ * answers with what it did. The horizon is the first sweep's instant plus {@link RECOVERY_CONFIRM_MS},
+ * read from the database's clock in the step's result so that a replay computes the same value.
+ * An empty sweep is confirmed by one more at the horizon; a sweep that failed starts is followed by
+ * another after a growing delay, until every such row is started or abandoned. Rows created after
+ * the horizon belong to the runs their own requests armed.
+ */
+export async function recoverWorkflowStarts(
+/** Shorter sleeps, for tests; the generated platform workflow passes none. */
+delays = {}) {
+    const sleep = workflowSleep();
+    if (sleep === undefined) {
+        throw new StartRecoveryWorkflowRequired();
+    }
+    const firstSweepMs = delays.firstSweepMs ?? RECOVERY_FIRST_SWEEP_MS;
+    const confirmMs = delays.confirmMs ?? RECOVERY_CONFIRM_MS;
+    await sleep(firstSweepMs);
+    const first = await recoverStartsStep({});
+    const before = new Date(Date.parse(first.at) + confirmMs).toISOString();
+    let report = add({ sweeps: 0, started: 0, failed: 0, waiting: 0, abandoned: 0 }, first);
+    let outcome = first;
+    let retries = 0;
+    while (report.sweeps < RECOVERY_MAX_SWEEPS) {
+        if (outcome.failed > 0) {
+            await sleep(RECOVERY_RETRY_MS[Math.min(retries, RECOVERY_RETRY_MS.length - 1)]);
+            retries += 1;
+        }
+        else {
+            await sleep(confirmMs);
+        }
+        outcome = await recoverStartsStep({ before });
+        report = add(report, outcome);
+        if (outcome.waiting === 0) {
+            break;
+        }
+    }
+    return report;
+}

package/dist/storage/api.d.ts

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const STORAGE_GROUP = "BlobStorage";
+export declare function storageGroup(authenticate: (endpoint: HttpApiEndpoint.Top) => HttpApiEndpoint.Top, errors: ReadonlyArray<Schema.Top>, maintenanceErrors: (endpoint: HttpApiEndpoint.Top) => HttpApiEndpoint.Top): HttpApiGroup.HttpApiGroup<"BlobStorage", HttpApiEndpoint.Top | HttpApiEndpoint.HttpApiEndpoint<string, import("effect/unstable/http/HttpMethod").HttpMethod, string, Schema.Top, Schema.Top, Schema.Top, Schema.Top, Schema.Top, Schema.Top, any, unknown>, false>;

package/dist/storage/api.js

@@ -0,0 +1,40 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { StorageMaintenanceAuthentication } from "./maintenance-auth.js";
+import { BeginUpload, OpenUploads, UploadView, TransferGrant } from "./sessions.js";
+export const STORAGE_GROUP = "BlobStorage";
+export function storageGroup(authenticate, errors, maintenanceErrors) {
+    const base = "/api/ontology/uploads";
+    const params = { id: Schema.String.check(Schema.isUUID()) };
+    const endpoints = [
+        HttpApiEndpoint.get("list", base, { success: OpenUploads, error: errors }),
+        HttpApiEndpoint.post("begin", base, {
+            payload: BeginUpload,
+            success: UploadView,
+            error: errors,
+        }),
+        HttpApiEndpoint.get("status", `${base}/:id`, { params, success: UploadView, error: errors }),
+        HttpApiEndpoint.post("part", `${base}/:id/parts`, {
+            params,
+            success: TransferGrant,
+            error: errors,
+        }),
+        HttpApiEndpoint.post("complete", `${base}/:id/complete`, {
+            params,
+            success: UploadView,
+            error: errors,
+        }),
+        HttpApiEndpoint.post("cancel", `${base}/:id/cancel`, {
+            params,
+            success: UploadView,
+            error: errors,
+        }),
+    ];
+    const [first, ...rest] = endpoints.map(authenticate);
+    return HttpApiGroup.make(STORAGE_GROUP)
+        .add(first, ...rest)
+        .add(maintenanceErrors(HttpApiEndpoint.post("maintain", "/api/ontology/internal/storage/maintenance", {
+        success: Schema.Struct({ removed: Schema.Int }),
+        error: errors,
+    })).middleware(StorageMaintenanceAuthentication));
+}

package/dist/storage/attachments.d.ts

@@ -0,0 +1,146 @@
+import { Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { ActionRejected, Conflict, NotFound, type PermissionDenied } from "../errors.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal } from "../runtime.js";
+import type { BlobProvider, TransferGrant } from "./provider.js";
+import { ATTACHMENT_SOURCES } from "./tables.js";
+/**
+ * The agent's temporary attachments: a file a member sends the app's agent is stored once, as a
+ * `_blobs` revision in the ontology's private file storage. Group files belong to the chat's current
+ * members; private files belong to their sender and the agent session that first reads them.
+ * Nothing about it is an ontology record. It expires 24 hours after receipt; the agent may read it,
+ * discard it, or promote it into a record through an action, which adopts the same stored object
+ * without copying it. Every operation derives chat access from the caller and registry, never from
+ * tool input.
+ */
+/** The largest file the agent takes: what Telegram's Bot API lets a bot download. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** How long an attachment stays readable after it arrives; reads never extend it. */
+export declare const ATTACHMENT_TTL_HOURS = 24;
+/** Live attachments one member may hold at once, so a busy chat cannot fill the storage. */
+export declare const MAX_LIVE_ATTACHMENTS = 50;
+export { ATTACHMENT_SOURCES };
+/** Who asks, as the agent's runtime knows it: the member, their chat and the agent session. */
+export interface AttachmentCaller {
+    readonly principal: Principal;
+    /** The chat the attachment arrived in, such as `telegram:12345`. */
+    readonly conversation: string;
+    /**
+     * The agent session the request comes from. Private attachments stay bound to the first session
+     * that reads them. Group attachments are shared across authorized sessions in the same chat.
+     */
+    readonly sessionId?: string;
+    /** Trusted user boundary; never accepted from agent tool arguments. */
+    readonly access?: "member";
+}
+export interface ReceiveAttachment {
+    readonly source: (typeof ATTACHMENT_SOURCES)[number];
+    /** Identifies the file at its source, such as the message and attachment index; retries reuse it. */
+    readonly sourceRef: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface AttachmentView {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly state: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly promotion: unknown;
+    readonly conversation?: string;
+    readonly senderId?: string;
+}
+export interface AttachmentSearch {
+    readonly conversation?: string;
+    readonly senderId?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly before?: string;
+    readonly limit?: number;
+}
+export interface PromotionTarget {
+    /** The entity whose action adopts the file, such as `document`. */
+    readonly entity: string;
+    /** The action, such as `upload` or `create`. */
+    readonly action: string;
+    /** The action's input without the file; the field that takes the upload is filled in. */
+    readonly input: Readonly<Record<string, unknown>>;
+    /** The input field that takes the upload, when the action has more than one. */
+    readonly field?: string;
+    /** The record the action updates, for an action that sets the file on an existing record. */
+    readonly recordId?: string;
+}
+/** Runs the promotion's action as the caller, with the upload's options. */
+export type PromotionRunner = (input: {
+    readonly entity: string;
+    readonly action: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly options: {
+        readonly idempotencyKey: string;
+        readonly createIntent?: string;
+    };
+}) => Effect.Effect<{
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<unknown>;
+}, unknown>;
+/** The fields of an action's input that take an upload, with the property each one writes. */
+export declare function uploadFields(input: Schema.Top): ReadonlyArray<{
+    readonly field: string;
+    readonly entity: string;
+    readonly property: string;
+}>;
+/** Persisted phases surround every provider call; no external I/O holds a database transaction. */
+export declare function attachmentRuntime(ontology: Ontology, sql: SqlClient.SqlClient, provider: BlobProvider["Service"]): {
+    receive: (input: ReceiveAttachment, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        upload?: undefined;
+    } | {
+        attachment: AttachmentView;
+        upload: TransferGrant;
+    }, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    complete: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, ActionRejected | PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    list: (caller: AttachmentCaller) => Effect.Effect<AttachmentView[], PermissionDenied | import("effect/unstable/sql/SqlError").SqlError, never>;
+    read: (id: string, caller: AttachmentCaller) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    discard: (id: string, caller: AttachmentCaller) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    promote: (id: string, target: PromotionTarget, caller: AttachmentCaller, run: PromotionRunner) => Effect.Effect<{
+        attachment: AttachmentView;
+        deduplicated: boolean;
+        result: {} | null;
+    }, unknown, never>;
+    listForMember: (filters: AttachmentSearch, principal: Principal) => Effect.Effect<{
+        attachments: AttachmentView[];
+        nextCursor: string | null;
+    }, PermissionDenied | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    getForMember: (id: string, principal: Principal) => Effect.Effect<AttachmentView, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError, never>;
+    readForMember: (id: string, principal: Principal) => Effect.Effect<{
+        attachment: AttachmentView;
+        download: TransferGrant;
+    }, PermissionDenied | Conflict | NotFound | import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;
+    promoteForMember: (id: string, target: PromotionTarget, principal: Principal, run: PromotionRunner) => Effect.Effect<{
+        attachment: AttachmentView;
+        deduplicated: boolean;
+        result: {} | null;
+    }, unknown, never>;
+};
+export type AttachmentRuntime = ReturnType<typeof attachmentRuntime>;
+export type AttachmentFailure = ActionRejected | Conflict | NotFound | PermissionDenied;
+/**
+ * Expires attachments past their deadline and removes the bytes of every expired or discarded one
+ * that no record adopted. A revision a promotion ticket still points at is left to the upload
+ * maintenance, once the ticket is canceled. Runs from the storage maintenance schedule, so files
+ * expire while the agent is idle.
+ */
+export declare function maintainAttachments(sql: SqlClient.SqlClient, provider: BlobProvider["Service"], limit?: number): Effect.Effect<{
+    expired: number;
+    removed: number;
+    hasMore: boolean;
+}, import("effect/unstable/sql/SqlError").SqlError | import("./provider.js").BlobStorageError, never>;