@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/analyze.d.ts

@@ -0,0 +1,215 @@
+import type { ChatAttributionSettings } from "./chat.js";
+import { Schema } from "effect";
+import { type Action, type ActionHints } from "./action.js";
+import { type AnyConnectionHandle } from "./connection.js";
+import type { Diagnostic } from "./diagnostics.js";
+import { type AnyEntity, type EntityWrites } from "./entity.js";
+import { type PropertyDefinition } from "./property.js";
+import { type AnyRelationship } from "./relationship.js";
+import { type Role, type RolePermission } from "./role.js";
+import { type SignInOptions } from "./sign-in.js";
+import { type EmailTemplate } from "./emails.js";
+import { type FeedbackOptions, type ResolvedFeedback } from "./feedback-config.js";
+import { type ModelMetricManifest, type WorkflowManifest } from "./manifest.js";
+import type { ModelMetrics } from "./metric.js";
+import { type EarlierMetricsField } from "./legacy.js";
+import { type AnyWorkflow } from "./workflow.js";
+/** The input of `defineOntology` and `check`. */
+export interface OntologyConfig<Entities extends ReadonlyArray<AnyEntity> = ReadonlyArray<AnyEntity>, Metrics extends ModelMetrics = ModelMetrics> extends EarlierMetricsField<Metrics> {
+    /**
+     * The app's entities. The built-in `User`, `AgentChat` and `UserIdentity` are always included;
+     * listing them is optional.
+     */
+    readonly entities: Entities;
+    /**
+     * Text feedback is enabled by default for authenticated human members. Files default on only
+     * when another entity has a blob. `true` explicitly enables files; `false` disables feedback.
+     * Builders default to declared roles explicitly granting user:grantRoles or user:*.
+     */
+    readonly feedback?: boolean | FeedbackOptions;
+    /** Opt-in after-commit service execution; only this declared role supplies permissions. */
+    readonly hooks?: {
+        readonly role: string;
+    };
+    /** Business roles. The built-in `member` role is always included. */
+    readonly roles?: ReadonlyArray<Role>;
+    /**
+     * Durable processes written with the Vercel Workflow SDK, each declared with
+     * `workflow(name, { … })` and run by the ontology service as its own keyless service user holding
+     * one declared role. At most 50.
+     */
+    readonly workflows?: ReadonlyArray<AnyWorkflow>;
+    /**
+     * The built-in role every active app user holds. Its permissions default to `["*:read"]`: members
+     * read everything and run only what other roles grant them.
+     */
+    readonly member?: MemberOptions;
+    /** Who may become a member by signing in. Only invited people by default. */
+    readonly signIn?: SignInOptions;
+    /**
+     * How the MCP `discover` tool finds a request's entities. By default it matches words in their
+     * names and descriptions. `{ model }` asks that decision model on AI Gateway, such as
+     * `"typesafe-ai/jev-1.14.0"`, which of the caller's entities the request concerns, and falls back
+     * to word matching when the model fails. Each such search is one model request billed to the
+     * deployment's AI Gateway, so it pays off once the catalog has many entities, or agents miss the
+     * right one by searching words.
+     */
+    readonly discovery?: DiscoveryOptions;
+    /**
+     * The workspace's own emails by camelCase name, each sent with a sign-in link by
+     * `User.sendSignInLink`: plain-text fields the platform lays out, with `{{value}}` placeholders.
+     */
+    readonly emails?: Readonly<Record<string, EmailTemplate>>;
+    /**
+     * The workspace connections the actions call, each declared with `connection(key, …)`. Every
+     * handle an action lists must be here, and every handle here must be used by an action.
+     */
+    readonly connections?: ReadonlyArray<AnyConnectionHandle>;
+    /** Provider connections used by the built-in exact chat delivery action. */
+    readonly chat?: {
+        readonly telegram?: {
+            readonly connection: AnyConnectionHandle;
+        };
+        readonly attribution?: ChatAttributionSettings;
+    };
+    /**
+     * Metrics of the model, by camelCase name: each combines metrics of entities, read with
+     * `m.ref("entity.metric")`, or other model metrics, read with `m.ref("name")`, through
+     * `m.add`, `m.subtract`, `m.multiply`, `m.divide` and `m.literal`. `align` names the properties
+     * that stand for one another across the entities it reads.
+     */
+    readonly metrics?: Metrics;
+}
+/** How `discover` ranks entities: see {@link OntologyConfig.discovery}. */
+export interface DiscoveryOptions {
+    /** A decision model on AI Gateway, as `<provider>/<model>`. */
+    readonly model: string;
+}
+/** What every active app user may do, beyond the roles they are given. */
+export interface MemberOptions {
+    /**
+     * `<entity>:<verb>` permissions, scoped or not, as a role's. An empty list gives members nothing
+     * of their own.
+     */
+    readonly permissions: ReadonlyArray<RolePermission>;
+}
+export interface AnalyzeOptions {
+    /**
+     * Check the roles' permissions against the entities and actions, and warn about actions no role
+     * may run. Off only for an ontology rebuilt from a deployed manifest's roles without its entities,
+     * whose permissions were checked when that manifest was built.
+     */
+    readonly checkPermissions?: boolean;
+    /** Optional trusted agent config; absent means notice/limit checks are skipped. */
+    readonly agentConfig?: {
+        readonly firstContact?: unknown;
+        readonly limits?: unknown;
+    };
+    /**
+     * The built-in user entity: the SDK's `User`, unless an ontology is rebuilt from a deployed
+     * manifest that an earlier SDK built, whose `user` table lacks the properties added since.
+     */
+    readonly user?: AnyEntity;
+}
+export type JsonSchemaObject = {
+    readonly [key: string]: Schema.Json;
+};
+export interface ResolvedProperty {
+    readonly name: string;
+    readonly schema: Schema.Top;
+    readonly definition: PropertyDefinition;
+}
+export interface ResolvedRelationship {
+    readonly name: string;
+    readonly relationship: AnyRelationship;
+    /** The target entity's name, or `undefined` when the target could not be resolved. */
+    readonly target: string | undefined;
+}
+export interface ResolvedAction {
+    readonly name: string;
+    readonly action: Action;
+    /** The permission the action requires: its `permission`, or `<entity>:<action name>`. */
+    readonly permission: string;
+    /** The input as JSON Schema, or `undefined` when it could not be generated. */
+    readonly input: JsonSchemaObject | undefined;
+    /** The keys of the connections the action's `prepare` calls, in declaration order. */
+    readonly connections: ReadonlyArray<string>;
+    /** The hints the action declares, or `undefined` when it declares none. */
+    readonly hints: ActionHints | undefined;
+    /** The entities the handler may write, by wire name, or `undefined` when it declares none. */
+    readonly writes: ReadonlyArray<string> | undefined;
+}
+/** A connection the ontology declares. */
+export interface ResolvedConnection {
+    readonly key: string;
+    readonly description: string;
+    /** Whether the ontology sends data out through the connection. */
+    readonly delivers: boolean;
+    readonly handle: AnyConnectionHandle;
+}
+export interface ResolvedIndex {
+    readonly properties: ReadonlyArray<string>;
+    readonly unique: boolean;
+}
+/**
+ * The permissions of an entity's reads and generated actions. The built-in agent chat has only
+ * `update`; `link` and `unlink` exist when the entity declares a `rel.many`. The built-in User has
+ * only `read` here: its generated member actions require `user:<verb>` for each of
+ * `USER_MEMBER_VERBS`.
+ */
+export interface EntityPermissions {
+    readonly read: string;
+    readonly create?: string;
+    readonly update?: string;
+    readonly delete?: string;
+    readonly link?: string;
+    readonly unlink?: string;
+}
+/** An entity with its relationship targets resolved and its actions evaluated. */
+export interface ResolvedEntity {
+    readonly entity: AnyEntity;
+    readonly name: string;
+    readonly builtIn: boolean;
+    readonly properties: ReadonlyArray<ResolvedProperty>;
+    readonly relationships: ReadonlyArray<ResolvedRelationship>;
+    readonly indexes: ReadonlyArray<ResolvedIndex>;
+    readonly actions: ReadonlyArray<ResolvedAction>;
+    readonly permissions: EntityPermissions;
+    /** Who writes the records: `"actions"` when the entity declares it, otherwise `"generated"`. */
+    readonly writes: EntityWrites;
+}
+export interface Analysis {
+    readonly feedback: ResolvedFeedback;
+    readonly chat?: {
+        readonly telegram?: {
+            readonly connection: string;
+        };
+        readonly attribution?: ChatAttributionSettings;
+    };
+    readonly entities: ReadonlyArray<ResolvedEntity>;
+    /** The workspace-owned `member` role and declared roles, then the implicit reporter when enabled. */
+    readonly roles: ReadonlyArray<Role>;
+    /** The sign-in options, with the default policy when the definition sets none. */
+    readonly signIn: SignInOptions;
+    /** The declared emails that passed `check`, by wire name. */
+    readonly emails: Readonly<Record<string, EmailTemplate>>;
+    /** The declared connections, in order. */
+    readonly connections: ReadonlyArray<ResolvedConnection>;
+    /** The metrics of the model that passed `check`, in their manifest form. */
+    readonly metrics: ReadonlyArray<ModelMetricManifest>;
+    /** The workflows that passed `check`, in their manifest form: wire names and wire input. */
+    readonly workflows: ReadonlyArray<WorkflowManifest>;
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+}
+/**
+ * Resolves an ontology definition and checks it. It never throws: every problem, including a thunk
+ * that throws, becomes a diagnostic.
+ */
+export declare function analyze(config: OntologyConfig, options?: AnalyzeOptions): Analysis;
+/** The input of a workflow that declares none: exactly `{}`. */
+export declare const NO_INPUT: Schema.Top;
+/**
+ * The JSON Schema of `webhookDelivery`, the input every webhook-started workflow declares, as the
+ * manifest writes it. Publication compares a workflow's input with it.
+ */
+export declare function webhookDeliveryJsonSchema(): JsonSchemaObject;