@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/workflow.js

@@ -0,0 +1,259 @@
+import { nameToWire } from "./authoring-names.js";
+/** Marks the values `workflow(…)` returns, so that `check` can tell them from look-alikes. */
+export const WorkflowTypeId = Symbol.for("@segmentstream/ontology/Workflow");
+/** Marks the values trigger constructors such as `cron(…)` and `after(…)` return. */
+export const WorkflowTriggerTypeId = Symbol.for("@segmentstream/ontology/WorkflowTrigger");
+/** The most workflows one ontology may declare. */
+export const MAX_WORKFLOWS = 50;
+/** The most action triggers, `after(…)`, one ontology may declare across its workflows. */
+export const MAX_ACTION_TRIGGERS = 20;
+/** Declares a cron trigger; list it in `workflow(name, { triggers })`. UTC, five fields. */
+export function cron(name, expression, options) {
+    return {
+        [WorkflowTriggerTypeId]: WorkflowTriggerTypeId,
+        kind: "cron",
+        name,
+        description: options.description,
+        cron: expression,
+        input: options.input,
+    };
+}
+/**
+ * Declares a webhook trigger; list it in `workflow(name, { input: webhookDelivery, triggers })`.
+ * A workflow with a webhook trigger has only webhook triggers.
+ */
+export function webhook(name, options) {
+    return {
+        [WorkflowTriggerTypeId]: WorkflowTriggerTypeId,
+        kind: "webhook",
+        name,
+        description: options.description,
+        signature: options.signature,
+        ...(options.verification === undefined ? {} : { verification: options.verification }),
+        headers: options.headers ?? [],
+    };
+}
+export function after(name, target, options) {
+    const names = triggerTarget(target);
+    return {
+        [WorkflowTriggerTypeId]: WorkflowTriggerTypeId,
+        kind: "action",
+        name,
+        description: options?.description,
+        entity: names?.entity ?? "",
+        action: names?.action,
+        target,
+        when: options?.when,
+        input: options?.input,
+    };
+}
+/**
+ * The wire names an action or entity handle carries, `undefined` for anything else. Recognized by
+ * shape: this entry does not load the entity module, and `check` verifies the handle.
+ */
+function triggerTarget(target) {
+    if (typeof target === "function") {
+        const handle = target;
+        return typeof handle.entity === "string" && typeof handle.name === "string"
+            ? { entity: nameToWire(handle.entity), action: nameToWire(handle.name) }
+            : undefined;
+    }
+    if (typeof target === "object" && target !== null) {
+        const handle = target;
+        return typeof handle.name === "string" && typeof handle.definition === "object"
+            ? { entity: nameToWire(handle.name), action: undefined }
+            : undefined;
+    }
+    return undefined;
+}
+/**
+ * A `when` predicate: true when the record's `field` differs before and after the action and
+ * matches the bounds given. A missing record or value counts as no value, so a create that sets
+ * `status` changed it, and `{ to: "qualified" }` does not fire when it was already qualified.
+ */
+export function changed(field, bounds = {}) {
+    return (_event, { before, after }) => {
+        const from = valueOf(before, field);
+        const to = valueOf(after, field);
+        return (!sameValue(from, to) &&
+            (bounds.from === undefined || sameValue(from, bounds.from)) &&
+            (bounds.to === undefined || sameValue(to, bounds.to)));
+    };
+}
+function valueOf(record, field) {
+    const value = record === undefined || record === null
+        ? undefined
+        : record[field];
+    return value === undefined ? null : value;
+}
+/** Equality of stored values: primitives, lists and objects of them, and dates. */
+function sameValue(left, right) {
+    if (Object.is(left, right)) {
+        return true;
+    }
+    if (left instanceof Date && right instanceof Date) {
+        return left.getTime() === right.getTime();
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((item, index) => sameValue(item, right[index])));
+    }
+    if (typeof left === "object" && left !== null && typeof right === "object" && right !== null) {
+        const leftKeys = Object.keys(left);
+        const rightRecord = right;
+        return (leftKeys.length === Object.keys(right).length &&
+            leftKeys.every((key) => key in rightRecord &&
+                sameValue(left[key], rightRecord[key])));
+    }
+    return false;
+}
+/** Whether a function is declared `async`; action trigger functions must be synchronous. */
+export function isAsyncFunction(value) {
+    return (typeof value === "function" &&
+        (value.constructor?.name === "AsyncFunction" ||
+            Object.prototype.toString.call(value) === "[object AsyncFunction]"));
+}
+/** Whether a value was declared with a trigger constructor such as `cron(…)` or `after(…)`. */
+export function isWorkflowTrigger(value) {
+    return typeof value === "object" && value !== null && WorkflowTriggerTypeId in value;
+}
+/** Declares a workflow; list it in `defineOntology({ workflows })`. */
+export function workflow(name, options) {
+    return {
+        [WorkflowTypeId]: WorkflowTypeId,
+        name,
+        description: options.description,
+        role: options.role,
+        input: options.input,
+        run: options.run,
+        triggers: options.triggers ?? [],
+        connections: options.connections ?? [],
+    };
+}
+/** Whether a value was declared with `workflow(…)`. */
+export function isWorkflow(value) {
+    return typeof value === "object" && value !== null && WorkflowTypeId in value;
+}
+/** The values a valid field matches. */
+function fieldValues(text, spec) {
+    const values = new Set();
+    for (const item of text.split(",")) {
+        const [base = "*", stepText] = item.split("/");
+        const step = stepText === undefined ? 1 : Number(stepText);
+        const [low, high] = base === "*"
+            ? [spec.min, spec.max]
+            : (() => {
+                const [from = NaN, to] = base.split("-").map(Number);
+                return [from, to ?? (stepText === undefined ? from : spec.max)];
+            })();
+        for (let value = low; value <= high; value += step) {
+            values.add(value);
+        }
+    }
+    return values;
+}
+/**
+ * The first minute after `after` at which the expression fires, in UTC, within the next 366 days;
+ * `undefined` for an invalid expression or one that does not fire in that time.
+ */
+export function nextCronTime(expression, after) {
+    if (cronProblem(expression) !== undefined) {
+        return undefined;
+    }
+    const [minute = "", hour = "", day = "", month = "", weekday = ""] = expression
+        .trim()
+        .split(/\s+/);
+    const minutes = [...fieldValues(minute, { min: 0, max: 59 })].sort((a, b) => a - b);
+    const hours = [...fieldValues(hour, { min: 0, max: 23 })].sort((a, b) => a - b);
+    const days = fieldValues(day, { min: 1, max: 31 });
+    const months = fieldValues(month, { min: 1, max: 12 });
+    const weekdays = fieldValues(weekday, { min: 0, max: 6 });
+    const start = new Date(after.getTime());
+    start.setUTCSeconds(0, 0);
+    start.setUTCMinutes(start.getUTCMinutes() + 1);
+    for (let offset = 0; offset <= 366; offset += 1) {
+        const date = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate() + offset));
+        if (!months.has(date.getUTCMonth() + 1) ||
+            !days.has(date.getUTCDate()) ||
+            !weekdays.has(date.getUTCDay())) {
+            continue;
+        }
+        for (const h of hours) {
+            for (const m of minutes) {
+                const candidate = new Date(date.getTime() + (h * 60 + m) * 60_000);
+                if (candidate.getTime() >= start.getTime()) {
+                    return candidate;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+/** The longest each month can be, February in a leap year included. */
+const MONTH_DAYS = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+/**
+ * Whether a valid expression names no day that exists: a day of the month no listed month has,
+ * such as `0 0 31 4 *` or `0 0 30 2 *`. The 29th of February counts: it exists in leap years.
+ */
+export function cronNeverFires(expression) {
+    if (cronProblem(expression) !== undefined) {
+        return false;
+    }
+    const [, , day = "", month = ""] = expression.trim().split(/\s+/);
+    const days = fieldValues(day, { min: 1, max: 31 });
+    const months = fieldValues(month, { min: 1, max: 12 });
+    return ![...months].some((m) => [...days].some((d) => d <= MONTH_DAYS[m - 1]));
+}
+/** `*`, a number, a range, `*` or a range with a step, or a comma list of them; numbers only. */
+function validField(text, spec) {
+    return text.split(",").every((item) => {
+        const match = /^(\*|\d{1,2}(?:-\d{1,2})?)(?:\/(\d{1,2}))?$/.exec(item);
+        if (match === null) {
+            return false;
+        }
+        const [, base = "", stepText] = match;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        // A step follows `*` or a range: `*/15`, `0-30/5`, never a bare number such as `5/15`.
+        if (step < 1 || step > spec.max || (stepText !== undefined && !/^\*$|-/.test(base))) {
+            return false;
+        }
+        if (base === "*") {
+            return true;
+        }
+        const [low = NaN, high = low] = base.split("-").map(Number);
+        return low >= spec.min && high <= spec.max && low <= high;
+    });
+}
+/**
+ * Checks a cron expression by the syntax Vercel crons accept: five fields, read in UTC, each `*`,
+ * numbers, ranges, steps and lists, without month or day names, and with at most one of the day
+ * fields restricted. It validates syntax only. `undefined` when it parses.
+ */
+export function cronProblem(expression) {
+    const fields = expression.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        return "fields";
+    }
+    const [minute = "", hour = "", day = "", month = "", weekday = ""] = fields;
+    if (!validField(minute, { min: 0, max: 59 })) {
+        return "minute";
+    }
+    if (!validField(hour, { min: 0, max: 23 })) {
+        return "hour";
+    }
+    if (!validField(day, { min: 1, max: 31 })) {
+        return "day_of_month";
+    }
+    if (!validField(month, { min: 1, max: 12 })) {
+        return "month";
+    }
+    if (!validField(weekday, { min: 0, max: 6 })) {
+        return "day_of_week";
+    }
+    if (day !== "*" && weekday !== "*") {
+        return "both_days";
+    }
+    return undefined;
+}

package/dist/workflows.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@segmentstream/ontology/workflows`: declaring workflows and running the ontology inside
+ * their steps. Evaluating this entry reads no environment and loads no part of the Workflow SDK's
+ * runtime, so `check` and the sandbox evaluation of `index.ts` stay credential-free.
+ *
+ * Everything a workflow file uses at its top level comes from here, and this entry's module graph
+ * imports no Node built-in: the Workflow SDK bundles a workflow file's top-level imports for a
+ * runtime without them. `p` is re-exported for the workflow's `input`; import `Schema` from
+ * `effect`. Steps may use the whole package, since the SDK strips step bodies from that bundle.
+ * `agentTask` ships two steps of its own, which the SDK finds through this entry and compiles
+ * with the workflow's.
+ */
+export { p } from "./property.js";
+export type { AnyProperty, NumberOptions, Property, PropertyOptions, TextOptions, } from "./property.js";
+export { after, changed, cron, cronNeverFires, cronProblem, isWorkflow, isWorkflowTrigger, MAX_ACTION_TRIGGERS, MAX_WORKFLOWS, nextCronTime, webhook, workflow, } from "./workflow.js";
+export { MAX_WEBHOOK_BODY_BYTES, MAX_META_WEBHOOK_BODY_BYTES, MAX_WEBHOOK_HEADERS, MAX_WEBHOOKS, WEBHOOK_BASE_PATH, WEBHOOK_SIGNATURE_SCHEMES, webhookDelivery, webhookHeaderProblem, webhookPath, } from "./webhooks.js";
+export type { WebhookDelivery, WebhookSignatureScheme } from "./webhooks.js";
+export type { ActionEvent, ActionTrigger, AfterOptions, AnyActionHandle, AnyWorkflow, ChangedBounds, CronOptions, CronProblem, CronTrigger, TriggerFunction, TriggerRecord, WebhookOptions, WebhookSignature, WebhookVerification, WebhookTrigger, Workflow, WorkflowFunction, WorkflowOptions, WorkflowRunContext, WorkflowTrigger, } from "./workflow.js";
+export { run, WORKFLOW_BASE_PATH, WorkflowStepRequired } from "./workflow-runtime.js";
+export { recoverWorkflowStarts, StartRecoveryWorkflowRequired } from "./start-recovery.js";
+export type { StartRecoveryInput, StartRecoveryOutcome, StartRecoveryReport, } from "./start-recovery.js";
+export { agentTask, AgentTaskOptionsInvalid, AgentTaskWorkflowRequired, DEFAULT_AGENT_TASK_TIMEOUT_MS, MAX_AGENT_TASK_PROMPT_LENGTH, MAX_AGENT_TASK_TEXT_LENGTH, MAX_AGENT_TASK_TIMEOUT_MS, MAX_LIVE_AGENT_TASKS, MIN_AGENT_TASK_TIMEOUT_MS, } from "./agent-task.js";
+export type { AgentTaskFailure, AgentTaskOptions, AgentTaskResult } from "./agent-task.js";
+export type { WorkflowStepContext, WorkflowStepServices } from "./workflow-runtime.js";

package/dist/workflows.js

@@ -0,0 +1,18 @@
+/**
+ * `@segmentstream/ontology/workflows`: declaring workflows and running the ontology inside
+ * their steps. Evaluating this entry reads no environment and loads no part of the Workflow SDK's
+ * runtime, so `check` and the sandbox evaluation of `index.ts` stay credential-free.
+ *
+ * Everything a workflow file uses at its top level comes from here, and this entry's module graph
+ * imports no Node built-in: the Workflow SDK bundles a workflow file's top-level imports for a
+ * runtime without them. `p` is re-exported for the workflow's `input`; import `Schema` from
+ * `effect`. Steps may use the whole package, since the SDK strips step bodies from that bundle.
+ * `agentTask` ships two steps of its own, which the SDK finds through this entry and compiles
+ * with the workflow's.
+ */
+export { p } from "./property.js";
+export { after, changed, cron, cronNeverFires, cronProblem, isWorkflow, isWorkflowTrigger, MAX_ACTION_TRIGGERS, MAX_WORKFLOWS, nextCronTime, webhook, workflow, } from "./workflow.js";
+export { MAX_WEBHOOK_BODY_BYTES, MAX_META_WEBHOOK_BODY_BYTES, MAX_WEBHOOK_HEADERS, MAX_WEBHOOKS, WEBHOOK_BASE_PATH, WEBHOOK_SIGNATURE_SCHEMES, webhookDelivery, webhookHeaderProblem, webhookPath, } from "./webhooks.js";
+export { run, WORKFLOW_BASE_PATH, WorkflowStepRequired } from "./workflow-runtime.js";
+export { recoverWorkflowStarts, StartRecoveryWorkflowRequired } from "./start-recovery.js";
+export { agentTask, AgentTaskOptionsInvalid, AgentTaskWorkflowRequired, DEFAULT_AGENT_TASK_TIMEOUT_MS, MAX_AGENT_TASK_PROMPT_LENGTH, MAX_AGENT_TASK_TEXT_LENGTH, MAX_AGENT_TASK_TIMEOUT_MS, MAX_LIVE_AGENT_TASKS, MIN_AGENT_TASK_TIMEOUT_MS, } from "./agent-task.js";

package/package.json

@@ -1,6 +1,129 @@
 {
   "name": "@segmentstream/ontology",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.92.0",
+  "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
+  "license": "Apache-2.0",
+  "author": "SegmentStream",
+  "homepage": "https://segmentstream.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/segmentstream/segmentstream.git",
+    "directory": "packages/ontology-sdk"
+  },
+  "keywords": [
+    "segmentstream",
+    "ontology",
+    "effect"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./nitro": {
+      "types": "./dist/nitro.d.ts",
+      "import": "./dist/nitro.js"
+    },
+    "./telegram": {
+      "types": "./dist/telegram.d.ts",
+      "import": "./dist/telegram.js"
+    },
+    "./channel-session": {
+      "types": "./dist/channel-session.d.ts",
+      "import": "./dist/channel-session.js"
+    },
+    "./workflows": {
+      "types": "./dist/workflows.d.ts",
+      "import": "./dist/workflows.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./groups": {
+      "types": "./dist/groups.d.ts",
+      "import": "./dist/groups.js"
+    },
+    "./navigation-catalog": {
+      "types": "./dist/navigation-catalog.d.ts",
+      "import": "./dist/navigation-catalog.js"
+    },
+    "./navigation-artifact": {
+      "types": "./dist/navigation-artifact.d.ts",
+      "import": "./dist/navigation-artifact.js",
+      "default": "./dist/navigation-artifact.js"
+    }
+  },
+  "bin": {
+    "segmentstream-ontology": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/build-diagnostics.mjs && chmod +x dist/bin.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src tests --config ../../eslint.config.mjs",
+    "test": "vitest run",
+    "test:postgres": "vitest run --config vitest.postgres.config.ts",
+    "prepack": "pnpm run build",
+    "benchmark:batch": "tsx tests/batch/benchmark.ts",
+    "benchmark:batch:profile": "tsx tests/batch/profile.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.1148.0",
+    "@aws-sdk/s3-request-presigner": "^3.1148.0",
+    "@chat-adapter/telegram": "4.41.0",
+    "@effect/sql-pg": "4.0.0-rc.113",
+    "@vercel/functions": "^3.8.0",
+    "@workflow/builders": "5.0.5",
+    "@workflow/core": "5.2.2",
+    "@workflow/errors": "5.0.4",
+    "@workflow/rollup": "5.0.5",
+    "@workflow/serde": "5.0.0",
+    "@workflow/utils": "5.0.2",
+    "@workflow/world": "5.0.4",
+    "acorn": "8.15.0",
+    "devalue": "6.0.3",
+    "jose": "^6.2.12",
+    "marked": "15.0.12",
+    "semver": "7.7.4",
+    "tsx": "4.21.0",
+    "ulid": "~3.0.1",
+    "zod": "~4.5.4"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.113",
+    "nitro": "3.0.260903-beta",
+    "workflow": "5.2.2"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "0.4.6",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@segmentstream/diagnostics": "0.0.0",
+    "@types/node": "^24",
+    "@workflow/world-local": "5.1.1",
+    "effect": "4.0.0-rc.113",
+    "esbuild": "^0.27.0",
+    "nitro": "3.0.260903-beta",
+    "typescript": "^5.9",
+    "vitest": "^4.1.11",
+    "workflow": "5.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependenciesMeta": {
+    "nitro": {
+      "optional": true
+    }
+  }
+}