@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/bin/output.d.ts

@@ -0,0 +1,31 @@
+/** Where a command writes. The binary binds these to stdout and stderr; tests collect them. */
+export interface Output {
+    /** The command's result: a summary, the manifest, the catalog or the plan. */
+    readonly stdout: (text: string) => void;
+    /** Diagnostics, refusals and failures. */
+    readonly stderr: (text: string) => void;
+}
+export declare const EXIT_CODES: {
+    readonly ok: 0;
+    /** The ontology has errors or does not load, or the migration failed. */
+    readonly failed: 1;
+    /** The migration plan has refusals; nothing was applied. */
+    readonly refused: 2;
+    /** The command line is wrong (`EX_USAGE`). */
+    readonly usage: 64;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/**
+ * The error's message, or its stack, then each `cause` in turn, so that a wrapper never hides the
+ * original explanation of a failure.
+ */
+export declare function describeError(error: unknown, options?: {
+    readonly stack?: boolean;
+}): string;
+/**
+ * Replaces the connection string, and its password on its own, wherever they appear in a text. A
+ * driver may echo either in an error message.
+ */
+export declare function credentialRedactor(connectionString: string): (text: string) => string;
+/** The same output, with the connection string and its password redacted from everything written. */
+export declare function redactedOutput(output: Output, connectionString: string): Output;

package/dist/bin/output.js

@@ -0,0 +1,84 @@
+export const EXIT_CODES = {
+    ok: 0,
+    /** The ontology has errors or does not load, or the migration failed. */
+    failed: 1,
+    /** The migration plan has refusals; nothing was applied. */
+    refused: 2,
+    /** The command line is wrong (`EX_USAGE`). */
+    usage: 64,
+};
+/** How far `describeError` follows `cause`; real chains are three or four errors deep. */
+const MAXIMUM_CAUSES = 8;
+/** Shorter passwords would redact ordinary words; the whole connection string is always redacted. */
+const MINIMUM_REDACTED_PASSWORD = 4;
+const REDACTED = "[redacted]";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** A value that is not an error, such as the hashes `CatalogInvalid` keeps as its cause. */
+function plainText(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function headline(error, withStack) {
+    if (!isRecord(error)) {
+        return String(error);
+    }
+    const stack = withStack && typeof error.stack === "string" ? error.stack : undefined;
+    const message = typeof error.message === "string" ? error.message : plainText(error);
+    // PostgreSQL errors explain a failed statement in `detail` and `hint`.
+    const explanations = [error.detail, error.hint].filter((value) => typeof value === "string" && value.length > 0);
+    return [stack ?? message, ...explanations].join("\n");
+}
+/**
+ * The error's message, or its stack, then each `cause` in turn, so that a wrapper never hides the
+ * original explanation of a failure.
+ */
+export function describeError(error, options = {}) {
+    const lines = [];
+    const seen = new Set();
+    let current = error;
+    let previous;
+    while (current !== undefined && !seen.has(current) && seen.size < MAXIMUM_CAUSES) {
+        seen.add(current);
+        const line = headline(current, lines.length === 0 && options.stack === true);
+        // A wrapper often repeats its cause's message, as SqlError does its reason's.
+        if (line !== previous) {
+            lines.push(lines.length === 0 ? line : `Caused by: ${line}`);
+        }
+        previous = line;
+        current = isRecord(current) ? current.cause : undefined;
+    }
+    return lines.join("\n");
+}
+function decodeComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Replaces the connection string, and its password on its own, wherever they appear in a text. A
+ * driver may echo either in an error message.
+ */
+export function credentialRedactor(connectionString) {
+    const password = URL.canParse(connectionString) ? new URL(connectionString).password : "";
+    const passwords = [password, decodeComponent(password)].filter((candidate) => candidate.length >= MINIMUM_REDACTED_PASSWORD);
+    // The longest first, so that a password inside the connection string never splits it.
+    const secrets = [...new Set([connectionString, ...passwords])].sort((left, right) => right.length - left.length);
+    return (text) => secrets.reduce((redacted, secret) => redacted.split(secret).join(REDACTED), text);
+}
+/** The same output, with the connection string and its password redacted from everything written. */
+export function redactedOutput(output, connectionString) {
+    const redact = credentialRedactor(connectionString);
+    return {
+        stdout: (text) => output.stdout(redact(text)),
+        stderr: (text) => output.stderr(redact(text)),
+    };
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// The `segmentstream-ontology` binary: wires the process to the commands in ./bin/.
+import { importWithTsx, loadOntology } from "./bin/load.js";
+import { runMain } from "./bin/main.js";
+import { connectOwnerDatabase } from "./bin/migrate.js";
+// As in the deploy pipeline's evaluator, the ontology's own console output goes to stderr, so that
+// stdout carries only the command's result (`check --manifest` prints JSON).
+for (const method of ["log", "info", "debug", "warn"]) {
+    console[method] = console.error.bind(console);
+}
+function writer(stream) {
+    return (text) => {
+        stream.write(text);
+    };
+}
+/** Resolves once everything written so far has been handed to the operating system. */
+function flushed(stream) {
+    return new Promise((resolve) => {
+        stream.write("", () => resolve());
+    });
+}
+const cwd = process.cwd();
+const exitCode = await runMain(process.argv.slice(2), {
+    environment: process.env,
+    output: { stdout: writer(process.stdout), stderr: writer(process.stderr) },
+    load: (entry) => loadOntology({ entry, cwd }, importWithTsx),
+    connect: connectOwnerDatabase,
+});
+await Promise.all([flushed(process.stdout), flushed(process.stderr)]);
+// The ontology's modules may hold timers or sockets open; the command is done.
+process.exit(exitCode);

package/dist/blob.d.ts

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+import type { FileTarget } from "./files.js";
+/** Metadata of an immutable file revision. Provider keys and grants never appear in records. */
+export declare const BlobValue: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly filename: Schema.String;
+    readonly contentType: Schema.String;
+    readonly size: Schema.Int;
+    readonly createdAt: Schema.String;
+}>;
+export type BlobValue = typeof BlobValue.Type;
+/** An opaque completed-upload ticket. Only the action runtime may resolve and consume it. */
+declare function uploadCodec(entity?: string, property?: string): Schema.decodeTo<Schema.Struct<{
+    readonly uploadId: Schema.String;
+}>, Schema.Struct<{
+    readonly upload_id: Schema.String;
+}>, never, never>;
+export declare const BlobUpload: Schema.Struct<{
+    readonly uploadId: Schema.String;
+}>;
+export type BlobUpload = typeof BlobUpload.Type;
+export declare const BLOB_UPLOAD_ANNOTATION = "x-ontology-upload";
+export declare const MAX_BLOB_BYTES: number;
+/** Common content types for file properties; any valid MIME type may be declared. */
+export declare const BLOB_CONTENT_TYPES: readonly ["application/pdf", "image/jpeg", "image/png", "text/plain", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "text/csv", "text/tab-separated-values", "application/json", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/zip", "application/octet-stream"];
+/** A concrete MIME type, without wildcards, parameters or header control characters. */
+export declare function isBlobContentType(contentType: string): boolean;
+/** A property's MIME restriction: a concrete type, a type range, or all files. */
+export declare function isBlobAccept(accept: string): boolean;
+/** Omitted restrictions accept every concrete MIME type; an empty list accepts nothing. */
+export declare function acceptsBlobContentType(accept: ReadonlyArray<string> | undefined, contentType: string): boolean;
+type SchemaValue<S> = S extends {
+    readonly Type: infer T;
+} ? T : S extends Schema.optionalKey<infer Inner> ? Inner["Type"] : never;
+type BlobPropertyKey<P> = {
+    [K in keyof P]: NonNullable<SchemaValue<P[K]>> extends BlobValue ? K : never;
+}[keyof P] & string;
+/** Internal wire codec for session tickets and generated action inputs. */
+export declare function uploadInput(entity?: string, property?: string): ReturnType<typeof uploadCodec>;
+/** Declares which blob field an authored action's upload input may write. */
+export declare const uploads: {
+    /** Declares a preparation's file write; the runtime supplies its principal and upload binding. */
+    target<const P extends Readonly<Record<string, unknown>>>(entity: {
+        readonly name: string;
+        readonly properties: P;
+    }, property: BlobPropertyKey<P>): FileTarget;
+    for<const P extends Readonly<Record<string, unknown>>>(entity: {
+        readonly name: string;
+        readonly properties: P;
+    }, property: BlobPropertyKey<P>): typeof BlobUpload;
+};
+export {};

package/dist/blob.js

@@ -0,0 +1,87 @@
+import { Schema, SchemaTransformation } from "effect";
+import { nameToWire } from "./authoring-names.js";
+/** Metadata of an immutable file revision. Provider keys and grants never appear in records. */
+export const BlobValue = Schema.Struct({
+    id: Schema.String.check(Schema.isUUID()),
+    filename: Schema.String,
+    contentType: Schema.String,
+    size: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    createdAt: Schema.String,
+});
+/** An opaque completed-upload ticket. Only the action runtime may resolve and consume it. */
+function uploadCodec(entity, property) {
+    const id = Schema.String.check(Schema.isUUID());
+    return Schema.Struct({ upload_id: id })
+        .annotate({
+        ...(entity && property
+            ? {
+                description: `A completed upload for ${entity}.${property}.`,
+                "x-ontology-upload": { entity, property },
+            }
+            : {}),
+    })
+        .pipe(Schema.decodeTo(Schema.Struct({ uploadId: id }), SchemaTransformation.transform({
+        decode: (value) => ({ uploadId: value.upload_id }),
+        encode: (value) => ({ upload_id: value.uploadId }),
+    })));
+}
+export const BlobUpload = Schema.Struct({ uploadId: Schema.String.check(Schema.isUUID()) });
+export const BLOB_UPLOAD_ANNOTATION = "x-ontology-upload";
+export const MAX_BLOB_BYTES = 250 * 1024 * 1024;
+/** Common content types for file properties; any valid MIME type may be declared. */
+export const BLOB_CONTENT_TYPES = [
+    "application/pdf",
+    "image/jpeg",
+    "image/png",
+    "text/plain",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "text/csv",
+    "text/tab-separated-values",
+    "application/json",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/zip",
+    "application/octet-stream",
+];
+const CONTENT_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+const CONTENT_TYPE_RANGE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/\*$/i;
+/** A concrete MIME type, without wildcards, parameters or header control characters. */
+export function isBlobContentType(contentType) {
+    return contentType === contentType.trim() && CONTENT_TYPE.test(contentType);
+}
+/** A property's MIME restriction: a concrete type, a type range, or all files. */
+export function isBlobAccept(accept) {
+    return (accept === accept.trim() &&
+        (accept === "*/*" || CONTENT_TYPE_RANGE.test(accept) || isBlobContentType(accept)));
+}
+/** Omitted restrictions accept every concrete MIME type; an empty list accepts nothing. */
+export function acceptsBlobContentType(accept, contentType) {
+    if (!isBlobContentType(contentType)) {
+        return false;
+    }
+    const normalized = contentType.toLowerCase();
+    return (accept === undefined ||
+        accept.some((candidate) => {
+            const pattern = candidate.toLowerCase();
+            return (pattern === "*/*" ||
+                pattern === normalized ||
+                (CONTENT_TYPE_RANGE.test(pattern) && normalized.startsWith(pattern.slice(0, -1))));
+        }));
+}
+/** Internal wire codec for session tickets and generated action inputs. */
+export function uploadInput(entity, property) {
+    return uploadCodec(entity, property);
+}
+/** Declares which blob field an authored action's upload input may write. */
+export const uploads = {
+    /** Declares a preparation's file write; the runtime supplies its principal and upload binding. */
+    target(entity, property) {
+        return { entity: nameToWire(entity.name), property: nameToWire(property) };
+    },
+    for(entity, property) {
+        return BlobUpload.annotate({
+            description: `A completed upload for ${entity.name}.${property}.`,
+            "x-ontology-upload": { entity: nameToWire(entity.name), property: nameToWire(property) },
+        });
+    },
+};

package/dist/channel-session.d.ts

@@ -0,0 +1,16 @@
+/** Browser-safe wire protocol shared by the ontology service and app SDK. */
+export declare const CHANNEL_SESSION_PATH = "/api/ontology/session";
+export declare const CHANNEL_LOGOUT_PATH = "/api/ontology/sign-in/logout";
+export declare const CHANNEL_SESSION_TTL_SECONDS = 3600;
+export declare const channelSignInPath: (provider: string) => string;
+export declare const channelClientId: (provider: string) => string;
+export declare const channelCookieName: (workspaceId: string) => string;
+export declare const CHANNEL_COOKIE_PATTERN: RegExp;
+export declare const channelCookieAttributes: {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "none";
+    partitioned: boolean;
+    path: string;
+};
+export declare const channelCookie: (name: string, token: string, maxAge: number) => string;

package/dist/channel-session.js

@@ -0,0 +1,16 @@
+/** Browser-safe wire protocol shared by the ontology service and app SDK. */
+export const CHANNEL_SESSION_PATH = "/api/ontology/session";
+export const CHANNEL_LOGOUT_PATH = "/api/ontology/sign-in/logout";
+export const CHANNEL_SESSION_TTL_SECONDS = 3600;
+export const channelSignInPath = (provider) => `/api/ontology/sign-in/${encodeURIComponent(provider)}`;
+export const channelClientId = (provider) => `${provider}-mini-app`;
+export const channelCookieName = (workspaceId) => `__Host-ss_channel_session.${workspaceId.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+export const CHANNEL_COOKIE_PATTERN = /^__Host-ss_channel_session\.[A-Za-z0-9_-]+$/;
+export const channelCookieAttributes = {
+    httpOnly: true,
+    secure: true,
+    sameSite: "none",
+    partitioned: true,
+    path: "/",
+};
+export const channelCookie = (name, token, maxAge) => `${name}=${token}; HttpOnly; Secure; SameSite=None; Partitioned; Path=/; Max-Age=${maxAge}`;

package/dist/chat.d.ts

@@ -0,0 +1,43 @@
+/** Workspace-authored exact-post attribution; neutral defaults are name and a blank line. */
+export interface ChatAttributionSettings {
+    readonly template?: string;
+    readonly separator?: string;
+}
+import { Context, Effect, Schema } from "effect";
+import type { ActionError } from "./errors.js";
+export declare const ChatPostInput: Schema.Struct<{
+    readonly chat: Schema.String;
+    readonly text: Schema.String;
+    readonly replyTo: Schema.optionalKey<Schema.String>;
+    readonly idempotencyKey: Schema.String;
+}>;
+export type ChatPostInput = typeof ChatPostInput.Type;
+export declare const ChatPostResult: Schema.Struct<{
+    readonly status: Schema.Literals<readonly ["sent", "uncertain"]>;
+    readonly message_id: Schema.NullOr<Schema.String>;
+    readonly url: Schema.NullOr<Schema.String>;
+    readonly duplicate: Schema.Boolean;
+    readonly history_recorded: Schema.Boolean;
+}>;
+export type ChatPostResult = typeof ChatPostResult.Type;
+export interface ChatPreview {
+    readonly chatId: string;
+    readonly provider: string;
+    readonly externalId: string;
+    readonly title: string;
+    readonly attribution: string;
+    readonly text: string;
+    readonly finalText: string;
+    readonly replyTo: string | null;
+}
+export declare const chatOperationId: (sessionId: string, callId: string) => string;
+export declare const chatPreviewDigest: (preview: ChatPreview) => string;
+declare const ChatDelivery_base: Context.ServiceClass<ChatDelivery, "@segmentstream/ontology/ChatDelivery", {
+    readonly preview: (input: ChatPostInput) => Effect.Effect<ChatPreview, ActionError>;
+    readonly validate: (input: ChatPostInput) => Effect.Effect<void, ActionError>;
+    readonly post: (input: ChatPostInput) => Effect.Effect<ChatPostResult, ActionError>;
+}>;
+/** Deliver the exact Markdown source through the channel renderer, without invoking an agent. */
+export declare class ChatDelivery extends ChatDelivery_base {
+}
+export {};

package/dist/chat.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { Context, Schema } from "effect";
+const Identifier = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(512));
+export const ChatPostInput = Schema.Struct({
+    chat: Identifier,
+    text: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(4096)).annotate({
+        description: "Markdown source; the platform adds sender attribution after channel rendering.",
+    }),
+    replyTo: Schema.optionalKey(Identifier),
+    idempotencyKey: Identifier,
+});
+export const ChatPostResult = Schema.Struct({
+    status: Schema.Literals(["sent", "uncertain"]),
+    message_id: Schema.NullOr(Schema.String),
+    url: Schema.NullOr(Schema.String),
+    duplicate: Schema.Boolean,
+    history_recorded: Schema.Boolean,
+});
+const chatProtocolDigest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const chatOperationId = (sessionId, callId) => `hq:${chatProtocolDigest([sessionId, callId])}`;
+export const chatPreviewDigest = (preview) => chatProtocolDigest([
+    "v2",
+    preview.chatId,
+    preview.provider,
+    preview.externalId,
+    preview.title,
+    preview.attribution,
+    preview.text,
+    preview.finalText,
+    preview.replyTo,
+]);
+/** Deliver the exact Markdown source through the channel renderer, without invoking an agent. */
+export class ChatDelivery extends Context.Service()("@segmentstream/ontology/ChatDelivery") {
+}

package/dist/confirmation.d.ts

@@ -0,0 +1,46 @@
+import { Schema } from "effect";
+import type { Principal } from "./runtime.js";
+/** One thing a person checks before they confirm, such as the document, a signer or an amount. */
+export declare const ConfirmationFact: Schema.Struct<{
+    readonly icon: Schema.optionalKey<Schema.String>;
+    readonly text: Schema.String;
+    /** A page that shows what the line names; the line links to it. */
+    readonly url: Schema.optionalKey<Schema.String>;
+}>;
+export type ConfirmationFact = typeof ConfirmationFact.Type;
+/**
+ * What a person confirms before an agent runs an action, in the language of the chat the agent asks
+ * in. The agent shows it as its confirmation card, with the confirm and cancel buttons and the
+ * outcome below it. Every text is plain: no markup, ids, codes or links in the text itself.
+ */
+export declare const ActionConfirmation: Schema.Struct<{
+    /** The action as a short verb phrase, such as "Send for signature". */
+    readonly title: Schema.String;
+    /** One emoji that marks the action. */
+    readonly icon: Schema.optionalKey<Schema.String>;
+    /** What the person checks, most important first: the record, who it reaches, the amount. */
+    readonly facts: Schema.$Array<Schema.Struct<{
+        readonly icon: Schema.optionalKey<Schema.String>;
+        readonly text: Schema.String;
+        /** A page that shows what the line names; the line links to it. */
+        readonly url: Schema.optionalKey<Schema.String>;
+    }>>;
+    /** Secondary detail and consequences, shown collapsed. */
+    readonly details: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    /** A page where the person can look at what the action concerns, shown as a button. */
+    readonly link: Schema.optionalKey<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly url: Schema.String;
+    }>>;
+}>;
+export type ActionConfirmation = typeof ActionConfirmation.Type;
+/** What an action's `confirm` runs with. */
+export interface ConfirmContext<Input> {
+    /** The input, already decoded with the action's input schema. */
+    readonly input: Input;
+    readonly principal: Principal;
+    /** The language of the chat the person confirms in, as a BCP 47 tag such as `ru` or `en-gb`. */
+    readonly locale: string;
+    /** The id of the request, for logs. */
+    readonly requestId: string;
+}

package/dist/confirmation.js

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+/** One emoji, or a short emoji sequence such as a flag or a person with a skin tone. */
+const Icon = Schema.String.check(Schema.makeFilter((value) => /^[\p{Extended_Pictographic}\p{Regional_Indicator}\u{1F3FB}-\u{1F3FF}\u200D\uFE0F\u20E3#*0-9]{1,16}$/u.test(value) && /\p{Extended_Pictographic}|\p{Regional_Indicator}/u.test(value)
+    ? undefined
+    : "Expected one emoji"));
+/** Plain text a person reads: one line, no markup. Agents refuse ids, codes and links in it. */
+const Line = (maximum) => Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(maximum), Schema.makeFilter((value) => value === value.trim() && !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(value)
+    ? undefined
+    : "Expected one line of text, without spaces around it"));
+const Url = Schema.String.check(Schema.isMaxLength(2048), Schema.makeFilter((value) => {
+    try {
+        return new URL(value).protocol === "https:" ? undefined : "Expected an https URL";
+    }
+    catch {
+        return "Expected an https URL";
+    }
+}));
+/** One thing a person checks before they confirm, such as the document, a signer or an amount. */
+export const ConfirmationFact = Schema.Struct({
+    icon: Schema.optionalKey(Icon),
+    text: Line(300),
+    /** A page that shows what the line names; the line links to it. */
+    url: Schema.optionalKey(Url),
+});
+/**
+ * What a person confirms before an agent runs an action, in the language of the chat the agent asks
+ * in. The agent shows it as its confirmation card, with the confirm and cancel buttons and the
+ * outcome below it. Every text is plain: no markup, ids, codes or links in the text itself.
+ */
+export const ActionConfirmation = Schema.Struct({
+    /** The action as a short verb phrase, such as "Send for signature". */
+    title: Line(80),
+    /** One emoji that marks the action. */
+    icon: Schema.optionalKey(Icon),
+    /** What the person checks, most important first: the record, who it reaches, the amount. */
+    facts: Schema.Array(ConfirmationFact).check(Schema.isMaxLength(20)),
+    /** Secondary detail and consequences, shown collapsed. */
+    details: Schema.optionalKey(Schema.Array(Line(300)).check(Schema.isMaxLength(10))),
+    /** A page where the person can look at what the action concerns, shown as a button. */
+    link: Schema.optionalKey(Schema.Struct({ text: Line(40), url: Url })),
+});