ankka 0.9.1 → 0.11.0

package/dist/graph.js

@@ -0,0 +1,446 @@
+// Publishing a graph: a consumer that says which elements a change leaves in which state, and has each
+// published as a graph delta — one element's whole state at a version, or a tombstone marking it
+// deleted — under the contract `ankka.graph-delta.v1`. The record's key is the element's
+// (`node:<id>` or `edge:<id>`), never the author's to set, and its version is the change's sequence
+// number unless one is stated. A graph database kept in step with the topic applies a delta when its
+// version is newer than what it holds, so a change handled twice does no harm.
+//
+//   export class CartGraph extends GraphConsumer<ShoppingCartEvent> {
+//     static readonly componentId = "cart-graph"
+//     static readonly source = ShoppingCartEntity
+//     static readonly message = ShoppingCartEntity.events
+//     static readonly producesTo = "cart-graph"
+//     onMessage(event) {
+//       return this.effects.publish([this.graph.node(`cart:${this.subject}`, { labels: ["Cart"] })])
+//     }
+//   }
+import { JSON_CONTENT } from "./codec.js";
+import { secretsFor } from "./client.js";
+import { sequenceNumberOf } from "./consumer.js";
+import { renderDouble, reviver } from "./json.js";
+import { servicesFor } from "./services.js";
+/** The contract's name: the manifest and the `ce-type` of every delta. */
+export const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
+/** The record key of every delta for the node `id`. */
+export function nodeKey(id) {
+    return `node:${id}`;
+}
+/** The record key of every delta for the edge `id`. Nodes and edges are separate id spaces. */
+export function edgeKey(id) {
+    return `edge:${id}`;
+}
+/** Thrown where an element is built, or when a result is returned, for something the merge sink would refuse. */
+export class GraphError extends Error {
+    why;
+    constructor(why, message) {
+        super(message);
+        this.name = "GraphError";
+        this.why = why;
+    }
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED = new Set(["id", "_version", "_deleted"]);
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+function show(value) {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (typeof value === "number")
+        return String(value);
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function spaceOf(element) {
+    return element.kind === "edge" || (element.kind === "tombstone" && element.element === "edge") ? "edge" : "node";
+}
+function describe(element) {
+    const what = element.kind === "tombstone" ? `tombstone of ${spaceOf(element)}` : element.kind;
+    return `${what} ${show(element.id)}`;
+}
+/** The element key: `node:<id>` or `edge:<id>`; a tombstone has the key of the element it marks. */
+export function elementKey(element) {
+    return spaceOf(element) === "edge" ? edgeKey(element.id) : nodeKey(element.id);
+}
+/** The kind of one scalar. A float with a whole value is an integer, as the sink reads it. */
+function scalarKind(who, name, value) {
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "boolean":
+            return "boolean";
+        case "bigint":
+            if (value < INT64_MIN || value > INT64_MAX)
+                throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, which does not fit 64 bits`);
+            return "integer";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new GraphError("property-value", `${who}: property ${show(name)} is ${value}, which is not a finite number`);
+            if (!Number.isInteger(value))
+                return "float";
+            if (Number.isSafeInteger(value))
+                return "integer";
+            if (value < Number(INT64_MIN) || value >= 2 ** 63)
+                throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, a whole number that does not fit 64 bits`);
+            throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, a whole number past 2^53 that a number cannot hold exactly; pass it as a bigint`);
+        default:
+            throw new GraphError("property-value", `${who}: property ${show(name)} is ${show(value)}; a property is a string, a number, a boolean, or a non-empty list of one of those`);
+    }
+}
+function checkProperties(who, properties) {
+    if (properties === undefined)
+        return Object.freeze({});
+    if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
+        throw new GraphError("property-value", `${who}: properties must be an object of property values, not ${show(properties)}`);
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(properties)) {
+        if (RESERVED.has(name))
+            throw new GraphError("reserved", `${who}: property ${show(name)} is reserved`);
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                throw new GraphError("property-value", `${who}: property ${show(name)} is an empty list; leave the property out instead`);
+            const kinds = new Set(value.map((v) => scalarKind(who, name, v)));
+            if (kinds.size > 1)
+                throw new GraphError("property-value", `${who}: property ${show(name)} is a list of more than one kind (${[...kinds].join(", ")}); a whole-number float counts as an integer`);
+            out[name] = Object.freeze([...value]);
+        }
+        else {
+            scalarKind(who, name, value);
+            out[name] = value;
+        }
+    }
+    return Object.freeze(out);
+}
+function checkVersion(who, version) {
+    if (typeof version === "bigint") {
+        if (version < 1n || version > INT64_MAX)
+            throw new GraphError("version", `${who}: version must be a whole number of at least 1 within 64 bits, not ${version}`);
+        return version <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(version) : version;
+    }
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
+        throw new GraphError("version", `${who}: version must be a whole number of at least 1 (a safe integer, or a bigint within 64 bits), not ${show(version)}`);
+    }
+    return version;
+}
+function checkId(who, id) {
+    if (typeof id !== "string" || id === "")
+        throw new GraphError("id", `${who}: id must be a non-empty string`);
+    return id;
+}
+function checkEndpoints(who, e) {
+    for (const field of ["type", "from", "to"]) {
+        if (typeof e[field] !== "string" || e[field] === "")
+            throw new GraphError("endpoints", `${who}: an edge needs a type, a from and a to; ${field} is missing or empty`);
+    }
+    if (!IDENTIFIER.test(e.type))
+        throw new GraphError("identifier", `${who}: type ${show(e.type)} is not an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+    return { type: e.type, from: e.from, to: e.to };
+}
+function checkLabels(who, labels) {
+    if (labels === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(labels))
+        throw new GraphError("identifier", `${who}: labels must be a list of identifiers, not ${show(labels)}`);
+    for (const label of labels) {
+        if (typeof label !== "string" || !IDENTIFIER.test(label))
+            throw new GraphError("identifier", `${who}: label ${show(label)} is not an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+    }
+    return Object.freeze([...labels]);
+}
+/** The element, checked against everything the merge sink would refuse of it, as a frozen value. */
+function checked(element) {
+    const raw = element;
+    if (typeof raw !== "object" || raw === null)
+        throw new TypeError(`not a graph element: ${show(raw)}`);
+    if (raw.kind !== "node" && raw.kind !== "edge" && raw.kind !== "tombstone")
+        throw new TypeError(`not a graph element: kind is ${show(raw.kind)}`);
+    if (raw.kind === "tombstone" && raw.element !== "node" && raw.element !== "edge")
+        throw new TypeError(`not a graph element: a tombstone marks a node or an edge, not ${show(raw.element)}`);
+    const who = describe(raw);
+    const id = checkId(who, raw.id);
+    const version = raw.version === undefined ? {} : { version: checkVersion(who, raw.version) };
+    if (raw.kind === "node") {
+        return Object.freeze({ kind: "node", id, ...version, labels: checkLabels(who, raw.labels), properties: checkProperties(who, raw.properties) });
+    }
+    if (raw.kind === "edge") {
+        return Object.freeze({ kind: "edge", id, ...version, ...checkEndpoints(who, raw), properties: checkProperties(who, raw.properties) });
+    }
+    if (raw.element === "edge")
+        return Object.freeze({ kind: "tombstone", element: "edge", id, ...version, ...checkEndpoints(who, raw) });
+    return Object.freeze({ kind: "tombstone", element: "node", id, ...version });
+}
+/** `this.graph` in a graph consumer: builds elements, refusing where they are built what the sink would refuse. */
+export class Graph {
+    node(id, options = {}) {
+        return checked({ kind: "node", id, labels: options.labels, properties: options.properties, ...(options.version !== undefined ? { version: options.version } : {}) });
+    }
+    edge(id, options) {
+        return checked({ kind: "edge", id, type: options?.type, from: options?.from, to: options?.to, properties: options?.properties, ...(options?.version !== undefined ? { version: options.version } : {}) });
+    }
+    /** Marks a node deleted. The node stays in the graph, marked, so a straggling older delta cannot bring it back. */
+    tombstoneNode(id, options = {}) {
+        return checked({ kind: "tombstone", element: "node", id, ...(options.version !== undefined ? { version: options.version } : {}) });
+    }
+    /** Marks an edge deleted; it names the edge's type and endpoints so the edge is found without a scan. */
+    tombstoneEdge(id, options) {
+        return checked({ kind: "tombstone", element: "edge", id, type: options?.type, from: options?.from, to: options?.to, ...(options?.version !== undefined ? { version: options.version } : {}) });
+    }
+}
+/** `this.effects` in a graph consumer: there is nothing here that publishes anything but elements. */
+export class GraphEffects {
+    /** Publish these elements, each as a delta under its own key. An empty list publishes nothing. */
+    publish(elements) {
+        if (!Array.isArray(elements))
+            throw new TypeError("publish takes a list of elements");
+        return Object.freeze({ kind: "publish", elements: Object.freeze(elements.map(checked)) });
+    }
+    done() {
+        return Object.freeze({ kind: "done" });
+    }
+    ignore() {
+        return Object.freeze({ kind: "ignore" });
+    }
+}
+// ── writing ──
+function writeScalar(value) {
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "bigint":
+            return value.toString();
+        default:
+            return Number.isInteger(value) ? String(value) : renderDouble(value);
+    }
+}
+function writeProperties(properties) {
+    const fields = Object.entries(properties).map(([name, value]) => `${JSON.stringify(name)}:${Array.isArray(value) ? `[${value.map(writeScalar).join(",")}]` : writeScalar(value)}`);
+    return `{${fields.join(",")}}`;
+}
+/** The delta as the contract writes it. `labels` and `properties` are always written. */
+function writeDelta(delta) {
+    const id = JSON.stringify(delta.id);
+    const version = delta.version.toString();
+    switch (delta.kind) {
+        case "node":
+            return `{"kind":"node","id":${id},"version":${version},"labels":[${delta.labels.map((l) => JSON.stringify(l)).join(",")}],"properties":${writeProperties(delta.properties)}}`;
+        case "edge":
+            return `{"kind":"edge","id":${id},"version":${version},"type":${JSON.stringify(delta.type)},"from":${JSON.stringify(delta.from)},"to":${JSON.stringify(delta.to)},"properties":${writeProperties(delta.properties)}}`;
+        default:
+            return delta.element === "edge"
+                ? `{"kind":"tombstone","element":"edge","id":${id},"version":${version},"type":${JSON.stringify(delta.type)},"from":${JSON.stringify(delta.from)},"to":${JSON.stringify(delta.to)}}`
+                : `{"kind":"tombstone","element":"node","id":${id},"version":${version}}`;
+    }
+}
+// ── reading ──
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function readScalar(name, raw) {
+    const refuse = () => {
+        throw new Error(`property '${name}' is not a scalar or array of scalars`);
+    };
+    switch (typeof raw) {
+        case "string":
+            return { kind: "string", value: raw };
+        case "boolean":
+            return { kind: "boolean", value: raw };
+        case "bigint":
+            return raw < INT64_MIN || raw > INT64_MAX ? refuse() : { kind: "integer", value: raw };
+        case "number":
+            if (!Number.isInteger(raw))
+                return { kind: "float", value: raw };
+            if (Number.isSafeInteger(raw))
+                return { kind: "integer", value: raw };
+            // A whole number written with a fraction or an exponent: an integer if it fits 64 bits.
+            return raw < Number(INT64_MIN) || raw >= 2 ** 63 ? refuse() : { kind: "integer", value: BigInt(raw) };
+        default:
+            return refuse();
+    }
+}
+function readProperties(raw) {
+    if (raw === undefined)
+        return Object.freeze({});
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("properties must be an object");
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (RESERVED.has(name))
+            throw new Error(`property '${name}' is reserved`);
+        if (Array.isArray(value)) {
+            const read = value.map((v) => readScalar(name, v));
+            if (read.length === 0 || new Set(read.map((r) => r.kind)).size > 1)
+                throw new Error(`property '${name}' is not a scalar or array of scalars`);
+            out[name] = Object.freeze(read.map((r) => r.value));
+        }
+        else {
+            out[name] = readScalar(name, value).value;
+        }
+    }
+    return Object.freeze(out);
+}
+function readVersion(raw) {
+    if (typeof raw === "bigint" && raw >= 0n && raw <= INT64_MAX)
+        return raw;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 0) {
+        if (Number.isSafeInteger(raw))
+            return raw;
+        if (raw < 2 ** 63)
+            return BigInt(raw);
+    }
+    throw new Error("version is not a non-negative integer");
+}
+function readEndpoints(o, problem) {
+    const text = (v) => typeof v === "string" && v !== "";
+    if (!text(o.type) || !IDENTIFIER.test(o.type) || !text(o.from) || !text(o.to))
+        throw new Error(problem);
+    return { type: o.type, from: o.from, to: o.to };
+}
+/**
+ * Reads a delta's value back into an element, for tests and for a consumer of a delta topic. Given a
+ * `key` it also holds the contract's rule that the key is the delta's element key. It accepts a
+ * version of 0, which the contract allows and the builder does not write. An integer past 2⁵³ comes
+ * back as a `bigint`.
+ */
+export function readDelta(value, key) {
+    let raw;
+    try {
+        raw = JSON.parse(utf8Decoder.decode(value), reviver);
+    }
+    catch {
+        throw new Error("not a JSON object");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("not a JSON object");
+    const o = raw;
+    if (o.kind === undefined)
+        throw new Error("kind missing");
+    if (o.kind !== "node" && o.kind !== "edge" && o.kind !== "tombstone")
+        throw new Error(`unknown kind '${String(o.kind)}'`);
+    if (typeof o.id !== "string" || o.id === "")
+        throw new Error("id missing or empty");
+    const id = o.id;
+    const version = readVersion(o.version);
+    let delta;
+    if (o.kind === "node") {
+        const labels = o.labels ?? [];
+        if (!Array.isArray(labels) || labels.some((l) => typeof l !== "string" || !IDENTIFIER.test(l)))
+            throw new Error("labels must be an array of identifiers");
+        delta = Object.freeze({ kind: "node", id, version, labels: Object.freeze([...labels]), properties: readProperties(o.properties) });
+    }
+    else if (o.kind === "edge") {
+        delta = Object.freeze({ kind: "edge", id, version, ...readEndpoints(o, "edge needs type, from and to"), properties: readProperties(o.properties) });
+    }
+    else if (o.element === "node") {
+        delta = Object.freeze({ kind: "tombstone", element: "node", id, version });
+    }
+    else if (o.element === "edge") {
+        delta = Object.freeze({ kind: "tombstone", element: "edge", id, version, ...readEndpoints(o, "tombstone of an edge needs type, from and to") });
+    }
+    else {
+        throw new Error("tombstone needs element 'node' or 'edge'");
+    }
+    if (key !== undefined && key !== elementKey(delta))
+        throw new Error(`key '${key}' is not this delta's element key '${elementKey(delta)}'`);
+    return delta;
+}
+/** The codec of a delta: JSON under the manifest `ankka.graph-delta.v1`. Hand-written, since a delta's properties have no fixed shape. */
+export const graphDeltaCodec = Object.freeze({
+    manifest: GRAPH_DELTA_SCHEMA,
+    contentType: JSON_CONTENT,
+    encode: (delta) => utf8.encode(writeDelta(checked(delta))),
+    decode: (bytes) => readDelta(bytes),
+});
+/**
+ * What a graph consumer's effect publishes for the change `metadata` describes: every element at its
+ * stated version, else the change's sequence number, refusing a result that names an element twice or
+ * leaves a version to a change that has no sequence number. The server and the test kit both read an
+ * effect through this, so they cannot disagree about what a handler published.
+ *
+ * @internal
+ */
+export function deltaRecords(effect, metadata) {
+    if (effect.kind !== "publish")
+        return [];
+    const sequence = sequenceNumberOf(metadata);
+    const seen = new Set();
+    return effect.elements.map((given) => {
+        const element = checked(given);
+        const key = elementKey(element);
+        if (seen.has(key))
+            throw new GraphError("duplicate", `${describe(element)} is in this result twice (${key}); an element is published once for a change`);
+        seen.add(key);
+        let version = element.version;
+        if (version === undefined) {
+            if (sequence === undefined || sequence < 1n) {
+                throw new GraphError("no-sequence", `${describe(element)}: this source has no sequence number; state a version`);
+            }
+            version = checkVersion(describe(element), sequence);
+        }
+        const delta = Object.freeze({ ...element, version });
+        return Object.freeze({ key, value: utf8.encode(writeDelta(delta)), delta });
+    });
+}
+// ── the consumer ──
+/**
+ * A consumer that publishes a graph. Its handlers return elements; each is published to `producesTo`
+ * as a delta under its element key. It has no `produce` and no way to set a key, and it is discovered
+ * and hosted as an ordinary consumer.
+ */
+export class GraphConsumer {
+    graph = new Graph();
+    effects = new GraphEffects();
+    #metadata = {};
+    #client;
+    /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    /** The change's sequence number, which is the version of every element that states none. */
+    get sequenceNumber() {
+        return sequenceNumberOf(this.#metadata);
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside onMessage or onDelete");
+        return this.#client;
+    }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
+    /** @internal */
+    get _kind() {
+        return "consumer";
+    }
+    /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
+    onDelete() {
+        return this.effects.ignore();
+    }
+    /** @internal */
+    _bind(metadata, client) {
+        this.#metadata = metadata;
+        this.#client = client;
+    }
+}

package/dist/handlers.d.ts

@@ -1,3 +1,4 @@
+import { type Approval } from "./approvals.ts";
 import type { Shape } from "./codec.ts";
 import type { EffectLike, ReadOnlyLike } from "./effects/common.ts";
 export type HandlerKind = "command" | "query" | "stream" | "step" | "action";
@@ -35,14 +36,21 @@ export declare function step<C, E extends EffectLike>(name: string, run: (self:
 /** A timed action: `action("remind", s.string, (t, id) => t.remind(id))`. */
 export declare function action<C, I, E extends EffectLike>(name: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<E>): HandlerRef<C, I, undefined, E>;
 export declare function action<C, E extends EffectLike>(name: string, run: (self: C) => MaybePromise<E>): HandlerRef<C, undefined, undefined, E>;
-/** An agent tool: the model sees `description` and the JSON Schema of `input`; the process runs `run`. */
+/**
+ * An agent tool: the model sees `description` and the JSON Schema of `input`; the process runs `run`.
+ * With `approval`, the tool waits for a person's decision before it runs: the caller is answered with an
+ * approval request, and the turn goes on when someone decides it.
+ */
 export interface ToolRef<C = unknown, I = unknown> {
     readonly name: string;
     readonly description: string;
     readonly input: Shape<I>;
     readonly run: (self: C, input: I) => MaybePromise<unknown>;
+    readonly approval?: Approval;
 }
-export declare function tool<C, I>(name: string, description: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<unknown>): ToolRef<C, I>;
+export declare function tool<C, I>(name: string, description: string, input: Shape<I>, run: (self: C, input: I) => MaybePromise<unknown>, options?: {
+    readonly approval?: Approval;
+}): ToolRef<C, I>;
 export type GuardrailStage = "input" | "output";
 /** An agent guardrail: returns a reason to block, or `null` to let the text through. */
 export interface GuardrailRef {

package/dist/handlers.js

@@ -2,6 +2,7 @@
 // and `guardrails` tables. Each carries the wire name, the input and reply schemas, and the function
 // that runs it. The wire name is declared here and nowhere else; renaming the method it calls changes
 // nothing on the wire. These are plain values, so the registry can read them without reflection.
+import { approvalProblem } from "./approvals.js";
 function ref(kind, name, input, reply, run, flags) {
     if (typeof name !== "string" || name.trim() === "")
         throw new TypeError(`a ${kind} needs a wire name`);
@@ -49,13 +50,16 @@ export function action(name, ...rest) {
     const [run] = rest;
     return ref("action", name, undefined, undefined, run, { readOnly: false, streaming: false });
 }
-export function tool(name, description, input, run) {
+export function tool(name, description, input, run, options = {}) {
     if (typeof name !== "string" || name.trim() === "")
         throw new TypeError("a tool needs a name");
     if (typeof description !== "string" || description.trim() === "") {
         throw new TypeError(`tool ${name}: a tool needs a description, or the model cannot choose it`);
     }
-    return Object.freeze({ name, description, input, run });
+    const problem = approvalProblem(options.approval);
+    if (problem)
+        throw new TypeError(`tool ${name}: ${problem}`);
+    return Object.freeze({ name, description, input, run, ...(options.approval !== undefined ? { approval: options.approval } : {}) });
 }
 export function guardrail(name, check) {
     if (typeof name !== "string" || name.trim() === "")

package/dist/index.d.ts

@@ -11,20 +11,29 @@ export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnl
 export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, type WorkflowEffect, type WorkflowReadOnlyEffect, type WorkflowCommandEffect, type StepEffect, type StepOutcome, type StepRef, type PauseOptions, type WorkflowSettings, type StepSettings, type Recovery, } from "./effects/workflow.ts";
 export { Workflow, type WorkflowClass } from "./workflow.ts";
-export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type TimedActionEffect } from "./effects/stateless.ts";
-export { View, type ViewClass } from "./view.ts";
-export { Consumer, type ConsumerClass } from "./consumer.ts";
+export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type OutgoingMessage, type TimedActionEffect } from "./effects/stateless.ts";
+export { View, declaredQuery, tableOf, type DeclaredQuery, type ViewClass } from "./view.ts";
+export { KeyedView, on, type KeyedSource, type KeyedViewClass, type ViewRows } from "./keyedView.ts";
+export { KeyedViewEffects, type KeyedViewEffect, type RowChange } from "./effects/keyed.ts";
+export { Consumer, ProtocolVersionError, type ConsumerClass } from "./consumer.ts";
+export { Contract, CONTRACT_NAME_RULE, fingerprintOf, type Publication } from "./contract.ts";
+export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, type Delta, type Element, type GraphConsumerClass, type GraphEffect, type GraphFault, type Properties, type PropertyValue, type Scalar, type Version, } from "./graph.ts";
 export { TimedAction, type TimedActionClass } from "./timedAction.ts";
 export { AgentEffects, type AgentEffect } from "./effects/agent.ts";
 export { Agent, type AgentClass } from "./agent.ts";
+export { ApprovalAwaited, APPROVALS_SINCE, type AgentOutcome, type Approval, type ApprovalRequest, type DecisionInput } from "./approvals.ts";
+export { mcpServer, resultGuardrail, toolName, type McpServerOptions, type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, type Accepted, type AgentState, type Attachment, type AutonomousAgentClass, type AutonomousSettings, type Notification, type Rejected, type TaskAcceptance, type TaskRule, type TaskSnapshot, type TaskType, } from "./autonomous.ts";
 export { Endpoint, type EndpointClass } from "./endpoint.ts";
-export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type Socket, SocketClosed } from "./socket.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
 export { type CommandContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, type TimerTarget, type ComponentRef } from "./client.ts";
-export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
+export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, type ServiceResponse, type ServiceRequest, type ServiceHeaders, } from "./services.ts";
+export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredKeyedView, type RegisteredKeyedSource, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
 export { Server, type ServerOptions } from "./server/server.ts";
 export { problems as sidecarProblems } from "./server/discovery.ts";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.ts";
+export { StartFrom } from "./startFrom.ts";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
 export type { ComponentKind } from "./kinds.ts";

package/dist/index.js

@@ -23,18 +23,27 @@ export { KeyValueEntity } from "./keyValueEntity.js";
 export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, } from "./effects/workflow.js";
 export { Workflow } from "./workflow.js";
 export { ViewEffects, ConsumerEffects, TimedActionEffects } from "./effects/stateless.js";
-export { View } from "./view.js";
-export { Consumer } from "./consumer.js";
+export { View, declaredQuery, tableOf } from "./view.js";
+export { KeyedView, on } from "./keyedView.js";
+export { KeyedViewEffects } from "./effects/keyed.js";
+export { Consumer, ProtocolVersionError } from "./consumer.js";
+export { Contract, CONTRACT_NAME_RULE, fingerprintOf } from "./contract.js";
+export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, } from "./graph.js";
 export { TimedAction } from "./timedAction.js";
 export { AgentEffects } from "./effects/agent.js";
 export { Agent } from "./agent.js";
+export { ApprovalAwaited, APPROVALS_SINCE } from "./approvals.js";
+export { mcpServer, resultGuardrail, toolName } from "./mcp.js";
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, } from "./autonomous.js";
 export { Endpoint } from "./endpoint.js";
-export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse } from "./routes.js";
+export { SocketClosed } from "./socket.js";
+export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, socket } from "./routes.js";
 export { Query, Headers } from "./context.js";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers } from "./client.js";
+export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets } from "./client.js";
+export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, } from "./services.js";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";
 export { Server } from "./server/server.js";
 export { problems as sidecarProblems } from "./server/discovery.js";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
+export { StartFrom } from "./startFrom.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/keyedView.d.ts

@@ -0,0 +1,56 @@
+import type { Shape } from "./codec.ts";
+import type { Metadata } from "./effects/common.ts";
+import type { ComponentClient, ComponentRef } from "./client.ts";
+import { KeyedViewEffects, type KeyedViewEffect } from "./effects/keyed.ts";
+import type { DeclaredQuery } from "./view.ts";
+type MaybePromise<T> = T | Promise<T>;
+/** A keyed view's own rows, for the length of one change. It reaches no other view. */
+export interface ViewRows<Row> {
+    /** The row under `key`, or `null`. */
+    get(key: string): Promise<Row | null>;
+    /** The rows of one of this view's declared queries, asked with its values. */
+    ask(name: string, values?: Readonly<Record<string, string>>): Promise<Row[]>;
+}
+/** One source of a keyed view, and what the view does with each of its changes and with its entity's deletion. */
+export interface KeyedSource<V = any, E = any> {
+    readonly source: ComponentRef;
+    readonly events: Shape<E>;
+    readonly onChange: (view: V, event: E) => MaybePromise<KeyedViewEffect<any>>;
+    readonly deleted?: (view: V) => MaybePromise<KeyedViewEffect<any>>;
+}
+/**
+ * Declares a source of a keyed view: the entity whose changes it reads, the shape of those changes, and
+ * the handler for each. When the entity is deleted the view does nothing unless `deleted` names rows.
+ */
+export declare function on<V, E>(source: ComponentRef, events: Shape<E>, onChange: (view: V, event: E) => MaybePromise<KeyedViewEffect<any>>, options?: {
+    readonly deleted?: (view: V) => MaybePromise<KeyedViewEffect<any>>;
+}): KeyedSource<V, E>;
+export declare abstract class KeyedView<Row> {
+    #private;
+    readonly effects: KeyedViewEffects<Row>;
+    /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
+    get metadata(): Metadata;
+    /** The id of the entity the change came from. */
+    get subject(): string;
+    /** This view's own rows, by key or by one of its declared queries. */
+    get rows(): ViewRows<Row>;
+    get client(): ComponentClient;
+    /** @internal */
+    get _kind(): "view";
+    /** @internal */
+    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>): void;
+}
+export interface KeyedViewClass<Row = unknown, C extends KeyedView<Row> = KeyedView<Row>> {
+    new (): C;
+    readonly componentId: string;
+    readonly row: Shape<Row>;
+    /** One per entity the view reads, declared with `on(...)`. */
+    readonly sources: readonly KeyedSource<C, any>[];
+    /** Raised to have the view emptied and every source read again from its beginning. Absent is 1. */
+    readonly version?: number;
+    /** The queries the view can be asked by name, by its own handlers among others. */
+    readonly declared?: readonly DeclaredQuery[];
+}
+/** The rows a keyed view reads through the component client, on its own id. */
+export declare function clientRows<Row>(client: ComponentClient, viewId: string, row: Shape<Row>): ViewRows<Row>;
+export {};