nexus-ai-pro 1.19.0 → 1.21.0

package/API_STABILITY.md

@@ -439,8 +439,9 @@ from the root.
   that reconnects with an id never receives it again.
 - The server is not a security boundary on its own: authentication, authorization beyond tenancy and
   scopes, and rate limiting are the application's, through the hooks.
-- Recovery re-runs a whole run rather than the step it died on, so an assistant with side effects
-  should be idempotent or be left at a single attempt.
+- Recovery repeats the step a run died in for graphs and workflows served by `graphAssistant()`, and
+  the whole run for any other assistant, so the repeated part should be idempotent or the run left at a
+  single attempt.
 
 ## Studio stage (1.19.0)
 
@@ -455,6 +456,29 @@ with nexus-ai-pro and declares the core versions it works with as a peer depende
 - The access rules are a guarantee: loopback binding by default, a token on every request, the token
   in a header for every change, and loopback hosts only unless others are allowed.
 
+## Durable execution stage (1.21.0)
+
+Functional workflows (`nexus-ai-pro/graph/functional`) and the SQLite adapters (`nexus-ai-pro/sqlite`)
+are experimental in production readiness. Their contracts follow the 1.x rules.
+
+- A workflow checkpoint is a graph checkpoint whose state holds the input, the recorded step results
+  keyed by step name and call order, and the output. That layout is stable across 1.x, so a thread
+  started by one release resumes on the next.
+- The SQLite table layouts may gain columns in a minor release; `migrate()` adds what is missing.
+- `ServerAssistant.recover()` and `AssistantRunContext.attempt` are optional additions: an assistant
+  without `recover()` behaves as before.
+
+## Retrieval stores stage (1.20.0)
+
+`PostgresVectorStore` (`nexus-ai-pro/postgres/vectors`) and `QdrantVectorStore` (`nexus-ai-pro/rag/qdrant`)
+are experimental in production readiness. The `VectorStore` contract they share with
+`MemoryVectorStore` follows the 1.x rules: a minor release may add optional methods and options, not
+remove or reshape these.
+
+- The pgvector table layout may gain columns in a minor release; `migrate()` adds what is missing.
+- A Qdrant point id is derived from the chunk id and is stable across releases, so a collection
+  written by one version is read by the next.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,83 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.21.0] - 2026-09-29
+
+Durable execution everywhere. Durability no longer requires drawing a graph, and a crash costs a
+step rather than a run.
+
+### Added
+
+- **Functional workflows**, experimental, on `nexus-ai-pro/graph/functional`. `workflow()` makes an
+  ordinary async function durable: each `step()` records its result, so a workflow that is resumed,
+  continued, or recovered on another worker returns finished steps from its checkpoint and carries on
+  from the first that did not finish. Steps run in parallel through `Promise.all`, bounded by
+  `maxConcurrency`, with per-step retries and timeouts; `interrupt()` pauses for a person exactly as in
+  a graph node; and the checkpoints are ordinary graph checkpoints, so every checkpointer stores
+  them, `traceGraph()` records them, and `graphAssistant()` serves a workflow on the agent server.
+- **Step-level recovery in the agent server.** A run recovered after its worker died continues from
+  the last checkpoint that run wrote — for graphs and workflows served by `graphAssistant()` — so
+  only the step in flight runs again. `AssistantRunContext.attempt` reports the attempt, and the new
+  optional `ServerAssistant.recover()` hook is how an assistant continues.
+- **SQLite persistence** on `nexus-ai-pro/sqlite`: `SqliteOperationStore` for durable operations and,
+  through `OperationStoreCheckpointer`, graph and workflow checkpoints; and `SqliteStore` for
+  long-term memory. Both take the database you open — `node:sqlite` and `better-sqlite3` directly,
+  libSQL through `fromLibsql()` — so no driver is a dependency, and both pass the same contract tests as
+  the memory, Redis, and Postgres stores.
+- **Diagrams as images.** `toSvg()` on `nexus-ai-pro/graph/visualize` draws a graph as a standalone,
+  escaped SVG document with no dependency. `layoutGraph()`, the layered layout underneath, moved from
+  the studio into the core visualizer, so both draw the same diagram.
+
+### Changed
+
+- The server reads a streamed event's `output` before its `state` when it records a run's output, so a
+  workflow's return value is the run's output.
+- `nexus-ai-pro-studio` requires nexus-ai-pro 1.21 or newer, and re-exports `layoutGraph()` from the
+  core visualizer.
+
+### Fixed
+
+- `guardrailPolicy()`, `GUARDRAIL_POLICIES`, `calibrateSemanticInjectionClassifier()`, and
+  `SEMANTIC_INJECTION_CALIBRATION_SET` are exported from `nexus-ai-pro/security`, and the four domain
+  workflows such as `supportTriageWorkflow()` from `nexus-ai-pro/workflows`, as their guides already
+  showed. They were reachable only from the package root. A new docs check fails when a guide's
+  example imports a name from an entry point that does not export it.
+
+## [1.20.0] - 2026-09-28
+
+Retrieval that scales past one process. Deprecated options now say so at run time, and every guide
+explains every export it lists.
+
+### Added
+
+- **Vector stores for retrieval.** `VectorStore` is a shared contract — `add()`, which replaces a chunk
+  whose id already exists, `search()`, `searchVector()` for a vector computed elsewhere, `delete()`,
+  and an exact-match metadata `filter` — with three implementations checked by one contract test:
+  - `PostgresVectorStore` on `nexus-ai-pro/postgres/vectors`, ranking with pgvector in the database,
+    with an HNSW index by default or an exact scan. `vectorStoreMigration()` gives its schema, and
+    `postgresMigration()` and `nexus db sql` include it when `vectors` is named.
+  - `QdrantVectorStore` on `nexus-ai-pro/rag/qdrant`, through Qdrant's REST API with `fetch` and Web
+    Crypto, so no Qdrant client is a dependency and it runs on edge runtimes. `migrate()` creates the
+    collection and indexes filter fields; failures raise `QdrantError`.
+  - `MemoryVectorStore`, which gains `searchVector()`, `delete()`, and the filter.
+- Retrieval is reachable from `nexus-ai-pro/rag` — `MemoryVectorStore`, `createHashEmbeddings()`,
+  `cosineSimilarity()`, `normalizeVector()`, `matchesMetadata()`, and the types — so an application
+  that ingests and searches no longer loads the root import.
+- **Deprecated options warn once per process** through Node's `DeprecationWarning` channel, with a
+  `NEXUS_DEP_*` code each, so `--no-deprecation` silences them and `--throw-deprecation` fails a CI
+  job on them: `GoogleProviderConfig.projectId`, `OllamaProviderConfig.timeout`,
+  `MetricsConfig.prometheus`, `HealthConfig.latencyHalfLife`, `DensificationConfig.preserveMarkdown`,
+  `InjectionDetectionConfig.sensitivity`, and `ToolPolicyConfig.requiresApproval`.
+
+### Changed
+
+- `MemoryVectorStore.add()` replaces a chunk whose id already exists instead of storing a second
+  copy, so re-ingesting a document no longer duplicates its passages in search results.
+- The guide check enforces that every export is explained in a guide's own text, not only named in
+  its generated reference; the five remaining guides — operations, embeddings, evaluation, images,
+  and realtime — now are. The README's limitations and production notes moved into the guides they
+  belong to.
+
 ## [1.19.0] - 2026-09-28
 
 A studio to look at it all. `nexus-ai-pro-studio` is a separate package — so the core install never
@@ -1008,7 +1085,9 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.21.0...HEAD
+[1.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.20.0...v1.21.0
+[1.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.19.0...v1.20.0
 [1.19.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.18.0...v1.19.0
 [1.18.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.16.0...v1.17.0

package/README.md

@@ -114,6 +114,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
 | [Postgres](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/postgres.md) | One adapter family for operations, memory, traces, evaluation, circuits, and prompts |
+| [SQLite](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/sqlite.md) | Durable operations, checkpoints, and memory on one machine, over any SQLite driver |
 | [Durable operations and jobs](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/operations.md) | Operations that survive a restart, webhooks, and in-process job helpers |
 | [Resilience and observability](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/resilience.md) | Circuit breaking, distributed rate limits, metrics, logs, and audit |
 | [Batch tiers](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/batch.md) | The providers' discounted batch APIs, resumable from any process |
@@ -197,37 +198,22 @@ Shipped so far:
 - queryable traces, an evaluation platform, and a CI gate on top of it;
 - record and replay of provider traffic;
 - prompt versioning: typed templates, content versions, gated promotion, and serving through outages;
+- a self-hosted agent server, and a local studio as a separate package;
 - per-entry-point size budgets.
 
-Next is a self-hosted agent server. The image family leaves experimental once recorded live
-conformance passes on all three backends.
-
-## Known Limitations
-
-- Voice, telephony, images, local models, and custom providers are optional layers; enable only what
-  you use.
-- Audio and video preprocessing is limited, and provider modality support differs.
-- Bundled model metadata is a routing and estimation convenience, not a pricing contract.
-- Process-memory cache, queues, and asset storage are not enough for a distributed deployment; use
-  the Redis, BullMQ, filesystem, or S3 adapters instead.
-- Default hash embeddings suit tests and demos, not strong semantic search. Register a real
-  embedding provider for production retrieval.
-- NLI verification is an interface; bring a specialized verifier for high-confidence entailment.
-- Guardrails reduce risk but do not replace application authorization, provider-side moderation, or
-  human review of high-impact actions.
-- Realtime sessions are not yet routed through the metrics, audit, and rate-limit path that every
-  other family uses.
-- The image adapters are verified against documented wire shapes; recorded live conformance for all
-  three backends is still to come, which is why the family is experimental.
-
-## Production Notes
-
-- Use direct or rules-based routing when model choice is already known.
-- Keep semantic cache, semantic security, and custom hooks off latency-sensitive routes unless needed.
-- Disable response traces with `pipeline.includeTraceInResponse = false`.
-- Use shared adapters for distributed apps instead of process memory.
-- Treat bundled model pricing and context metadata as defaults, not financial truth.
-- Keep server-side authorization and provider moderation around high-risk workflows.
+Next: durable functional workflows and step-level recovery, then retrieval and integration breadth,
+a shared team studio, and self-managed deployment at scale, before 2.0.0 consolidates. The image
+family leaves experimental once recorded live conformance passes on all three backends.
+
+## Before Production
+
+Each guide ends with its limitations. The ones worth reading first: the
+[client guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/core.md#in-production) on latency, traces,
+and shared adapters; the [security guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md#limitations)
+on what guardrails do not replace; and the
+[grounding guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/grounding.md#limitations) on embeddings
+and verification. Voice, telephony, images, realtime, local models, and custom providers are optional
+layers; enable only what you use.
 
 ## Donations
 

package/dist/cli/db.js

@@ -1,6 +1,14 @@
 import { postgresMigration } from '../postgres/index.js';
 import { CliUsageError, listFlag, numberFlag } from './args.js';
-const ADAPTERS = ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts'];
+const ADAPTERS = [
+    'operations',
+    'store',
+    'traces',
+    'evaluation',
+    'circuits',
+    'prompts',
+    'vectors',
+];
 export async function runDbCommand(subcommand, { flags }) {
     if (subcommand !== 'sql')
         throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
@@ -10,6 +18,9 @@ export async function runDbCommand(subcommand, { flags }) {
         throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
     }
     const vectorDimensions = numberFlag(flags, 'vector-dimensions');
+    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
+        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
     process.stdout.write(postgresMigration({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),

package/dist/graph/functional.d.ts

@@ -0,0 +1,217 @@
+import { GraphError } from './errors.js';
+import type { GraphCheckpoint, GraphCheckpointer, GraphDescription, GraphEvent, GraphStatus, InterruptRequest, PendingInterrupt, RetryPolicy } from '../types/graph.js';
+import type { Store } from '../types/store.js';
+/** What a workflow checkpoint holds: the input, every completed step's result, and the output. */
+export interface WorkflowState<I = unknown, O = unknown> {
+    /** The input the workflow was started with. */
+    input: I;
+    /** Each completed step's result, keyed by step name — `name#2` for the second call with a name. */
+    steps: Record<string, {
+        value?: unknown;
+    }>;
+    /** The workflow's return value, once it has completed. */
+    output?: O;
+}
+/** What a step's function receives. */
+export interface StepContext {
+    /** The step's name. */
+    readonly name: string;
+    /** The key its result is recorded under: the name, or `name#n` for a repeated name. */
+    readonly key: string;
+    /** Attempt number, starting at 1. Above 1 only under a retry policy. */
+    readonly attempt: number;
+    /** Aborted when the run is cancelled or the step exceeds its timeout. */
+    readonly signal: AbortSignal;
+}
+/** How one step runs. */
+export interface StepOptions {
+    /** Retries a failing attempt, overriding the workflow's default policy. */
+    retry?: RetryPolicy;
+    /** Aborts the step's signal and fails the attempt when it runs longer than this, in milliseconds. */
+    timeoutMs?: number;
+}
+/** What a workflow function receives besides its input. */
+export interface WorkflowContext {
+    /** The thread this run belongs to. */
+    readonly threadId: string;
+    /** Aborted when the run is cancelled. */
+    readonly signal: AbortSignal;
+    /** Long-term memory, when the workflow was created with a store. */
+    readonly store?: Store;
+    /**
+     * Runs a piece of work once per thread and records its result.
+     *
+     * When the workflow runs again, a step that already finished returns its recorded result without
+     * running. Name steps so the same call has the same name every time; a name used more than once
+     * is numbered in call order. The result must survive JSON serialization.
+     */
+    step<T>(name: string, run: (context: StepContext) => Promise<T> | T, options?: StepOptions): Promise<T>;
+    /**
+     * Suspends the workflow until a person answers.
+     *
+     * The first time, the run stops with status `awaiting_input` and this question pending. After
+     * `resume()` supplies a value, the workflow runs again from the top — completed steps return their
+     * recorded results — and this call returns the value instead of stopping.
+     */
+    interrupt<T = unknown>(request: InterruptRequest): T;
+    /** Sends anything to the run's `onEvent` listener as a `custom` event. Nothing is recorded. */
+    emit(data: unknown): void;
+}
+/** A workflow function: its input and context in, its output out. */
+export type WorkflowFn<I, O> = (input: I, context: WorkflowContext) => Promise<O> | O;
+/** Options for `workflow()`. */
+export interface WorkflowOptions {
+    /** Names the workflow in checkpoints, events, and diagrams. Defaults to `workflow`. */
+    name?: string;
+    /**
+     * Where checkpoints go. Defaults to an in-process `MemoryGraphCheckpointer`; pass a persistent one
+     * to survive restarts, or `false` to record nothing, which also disables interrupts and resume.
+     */
+    checkpointer?: GraphCheckpointer | false;
+    /** Long-term memory handed to the function as `context.store`. */
+    store?: Store;
+    /** Default retry policy for every step. A step's own policy wins. Defaults to one attempt. */
+    retry?: RetryPolicy;
+    /** Steps that may run at once, for a workflow that starts many with `Promise.all`. Defaults to 16. */
+    maxConcurrency?: number;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
+}
+/** Options for one run of a workflow. */
+export interface WorkflowRunOptions {
+    /** Identifies the run. Reusing one continues that thread. Defaults to a generated id. */
+    threadId?: string;
+    /** Stops the run. Steps in flight see the signal. */
+    signal?: AbortSignal;
+    /** Application data recorded on every checkpoint of the run. */
+    metadata?: Record<string, unknown>;
+    /** Receives each step starting, retrying, and finishing, each checkpoint, and custom events. */
+    onEvent?: (event: GraphEvent) => void;
+}
+/** One event of a streamed workflow run. */
+export type WorkflowEvent<O = unknown> = {
+    /** A step finished, or returned its recorded result. */
+    type: 'step';
+    /** Checkpoints written so far in the thread. */
+    step: number;
+    /** The step's name. */
+    name: string;
+    /** The key its result is recorded under. */
+    key: string;
+    /** True when the result came from a checkpoint and the step did not run. */
+    cached: boolean;
+    /** The workflow state after the step. */
+    state: WorkflowState<unknown, O>;
+    /** Always `running`. */
+    status: 'running';
+} | {
+    /** The workflow returned. */
+    type: 'done';
+    /** Checkpoints written in the thread. */
+    step: number;
+    /** The final state. */
+    state: WorkflowState<unknown, O>;
+    /** Always `completed`. */
+    status: 'completed';
+    /** What the workflow returned. */
+    output: O;
+} | {
+    /** The workflow is waiting for a person, or was stopped by its signal. */
+    type: 'interrupt';
+    /** Checkpoints written in the thread. */
+    step: number;
+    /** The state when it stopped. */
+    state: WorkflowState<unknown, O>;
+    /** `awaiting_input` for a question, `interrupted` for a cancelled run. */
+    status: 'awaiting_input' | 'interrupted';
+    /** The first pending question. */
+    interrupt?: PendingInterrupt;
+    /** Every pending question. */
+    interrupts?: PendingInterrupt[];
+};
+/** The outcome of a workflow run. */
+export interface WorkflowResult<O = unknown> {
+    /** The thread the run belongs to. */
+    threadId: string;
+    /** `completed`, `awaiting_input`, or `interrupted`. A failed run throws instead. */
+    status: GraphStatus;
+    /** What the workflow returned, when it completed. */
+    output?: O;
+    /** The workflow state: input, step results, and output. */
+    state: WorkflowState<unknown, O>;
+    /** Steps whose results are recorded. */
+    steps: number;
+    /** The first pending question, when it is waiting. */
+    interrupt?: PendingInterrupt;
+    /** Every pending question. */
+    interrupts?: PendingInterrupt[];
+}
+/** Raised when a step outlives its `timeoutMs`. */
+export declare class WorkflowStepTimeoutError extends GraphError {
+    /** The step. */
+    readonly stepName: string;
+    /** The limit it exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(
+    /** The step. */
+    stepName: string, 
+    /** The limit it exceeded, in milliseconds. */
+    timeoutMs: number);
+}
+/**
+ * A durable workflow: a function whose steps are checkpointed, so it survives interrupts, restarts,
+ * and a move to another worker. Create one with `workflow()`.
+ */
+export declare class Workflow<I = unknown, O = unknown> {
+    private readonly fn;
+    private readonly options;
+    /** The workflow's name. */
+    readonly name: string;
+    private readonly defaultCheckpointer;
+    private readonly now;
+    constructor(fn: WorkflowFn<I, O>, options?: WorkflowOptions);
+    /** Runs to the end, or to the first question, and returns the result. */
+    invoke(input: I, runOptions?: WorkflowRunOptions): Promise<WorkflowResult<O>>;
+    /** Runs, yielding an event as each step finishes. */
+    stream(input: I, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** Answers the first pending question and runs on. */
+    resume(threadId: string, value: unknown, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** Answers the first pending question, runs on, and returns the result. */
+    resumeWith(threadId: string, value: unknown, runOptions?: WorkflowRunOptions): Promise<WorkflowResult<O>>;
+    /** Answers pending questions by id and runs on. */
+    resumeInterrupts(threadId: string, answers: Record<string, unknown>, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /**
+     * Runs a thread on from its latest checkpoint: after a crash, a failure, or a cancelled run.
+     * Completed steps return their recorded results, so only unfinished work runs again.
+     */
+    continue(threadId: string, runOptions?: WorkflowRunOptions): AsyncIterable<WorkflowEvent<O>>;
+    /** The latest checkpoint, or the one at `step`. */
+    state(threadId: string, step?: number): Promise<GraphCheckpoint | undefined>;
+    /** Every checkpoint of a thread, newest first. */
+    history(threadId: string, limit?: number): Promise<GraphCheckpoint[]>;
+    /** The workflow as a one-node graph, so diagrams and the studio can show it. */
+    describe(): GraphDescription;
+    private checkpointer;
+    private latest;
+    private fresh;
+    private waiting;
+    private answered;
+    private collect;
+    /** Runs the function against a starting checkpoint, streaming events through a queue. */
+    private execute;
+    private run;
+    private runStep;
+}
+/**
+ * Creates a durable workflow from a function.
+ *
+ * ```ts
+ * const refund = workflow(async (input: { orderId: string }, { step, interrupt }) => {
+ *   const order = await step('load', () => orders.get(input.orderId));
+ *   if (!interrupt<boolean>({ reason: `Refund ${order.total}?` })) return { refunded: false };
+ *   await step('refund', () => payments.refund(order.id));
+ *   return { refunded: true };
+ * }, { checkpointer });
+ * ```
+ */
+export declare function workflow<I, O>(fn: WorkflowFn<I, O>, options?: WorkflowOptions): Workflow<I, O>;