ankka 0.10.0 → 0.12.0

package/dist/endpoint.js

@@ -8,7 +8,9 @@
 //     static readonly routes = { getCart: get("/{cartId}", ShoppingCart, (ep: ShoppingCartEndpoint, req) => ep.getCart(req.params.cartId)) }
 //     getCart(cartId: string) { return this.client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.getCart).invoke() }
 //   }
+import { secretsFor } from "./client.js";
 import { currentRequest, requestIfAny } from "./context.js";
+import { servicesFor } from "./services.js";
 export class Endpoint {
     #client;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
@@ -22,6 +24,24 @@ export class Endpoint {
         const request = requestIfAny();
         return request ? this.#client.withMetadata(request.metadata) : 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 */
     _bindClient(client) {
         this.#client = client;

package/dist/eventSourcedEntity.d.ts

@@ -1,5 +1,5 @@
 import type { Shape } from "./codec.ts";
-import type { CommandContext } from "./context.ts";
+import type { CommandContext, EventContext } from "./context.ts";
 import type { HandlerTable } from "./handlers.ts";
 import type { ComponentClient } from "./client.ts";
 import { EventSourcedEffects } from "./effects/eventSourced.ts";
@@ -19,8 +19,11 @@ export declare abstract class EventSourcedEntity<S, E> {
     get _kind(): "event-sourced";
     /** The state of an instance with no events yet. `this.entityId` is available here. */
     abstract emptyState(): S;
-    /** The fold: the state after `event`, given the state before it. Must not read `this.state`. */
-    abstract applyEvent(state: S, event: E): S;
+    /**
+     * The fold: the state after `event`, given the state before it. Must not read `this.state`. The third
+     * argument, which a two-argument fold may leave out, says where the event was written (1.19).
+     */
+    abstract applyEvent(state: S, event: E, context?: EventContext): S;
     /** @internal Bound by the runtime and the testkit before `emptyState`. */
     _bindInstance(entityId: string): void;
     /** @internal Bound by the runtime and the testkit for the duration of one handler call. */
@@ -37,4 +40,6 @@ export interface EventSourcedEntityClass<S = unknown, E = unknown, C extends Eve
     readonly handlers: HandlerTable<C>;
     /** Ask for a snapshot every N events; absent or 0: never. */
     readonly snapshotEvery?: number;
+    /** Held at every installation in its replication set and written only at its home (1.19). */
+    readonly replicated?: boolean;
 }

package/dist/graph.d.ts

@@ -1,6 +1,9 @@
+import type { StartFrom } from "./startFrom.ts";
 import { type Codec, type Shape } from "./codec.ts";
 import type { EffectLike, Metadata } from "./effects/common.ts";
-import type { ComponentClient, ComponentRef } from "./client.ts";
+import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
+import { type Services } from "./services.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** The contract's name: the manifest and the `ce-type` of every delta. */
 export declare const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
@@ -134,24 +137,43 @@ export declare abstract class GraphConsumer<M> {
     /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata(): Metadata;
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     /** The change's sequence number, which is the version of every element that states none. */
     get sequenceNumber(): bigint | undefined;
     get client(): ComponentClient;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     get _kind(): "consumer";
     abstract onMessage(message: M): MaybePromise<GraphEffect>;
     /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
     onDelete(): MaybePromise<GraphEffect>;
     /** @internal */
-    _bind(metadata: Metadata, client: ComponentClient): void;
+    _bind(metadata: Metadata, client: ComponentClient, standing?: Standing): void;
 }
 export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = GraphConsumer<M>> {
     new (): C;
     readonly componentId: string;
     readonly source?: ComponentRef;
     readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /** Raised to read the topic again from the start position, under a group of its own. Absent is 1. */
+    readonly version?: number;
     readonly message: Shape<M>;
     /** The delta topic. It must be compacted to hold the graph; the pipeline that reads it creates it so. */
     readonly producesTo: string;
+    /**
+     * Given a replicated entity's changes written at other installations too (1.19); otherwise each delta
+     * is published once, from the installation that wrote the change.
+     */
+    readonly mirroredChanges?: boolean;
 }
 export {};

package/dist/graph.js

@@ -15,8 +15,10 @@
 //     }
 //   }
 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`. */
@@ -393,6 +395,7 @@ export class GraphConsumer {
     graph = new Graph();
     effects = new GraphEffects();
     #metadata = {};
+    #standing = undefined;
     #client;
     /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata() {
@@ -401,6 +404,10 @@ export class GraphConsumer {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     /** The change's sequence number, which is the version of every element that states none. */
     get sequenceNumber() {
         return sequenceNumberOf(this.#metadata);
@@ -410,6 +417,24 @@ export class GraphConsumer {
             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";
@@ -419,8 +444,9 @@ export class GraphConsumer {
         return this.effects.ignore();
     }
     /** @internal */
-    _bind(metadata, client) {
+    _bind(metadata, client, standing) {
         this.#metadata = metadata;
+        this.#standing = standing;
         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

@@ -5,27 +5,36 @@ export { EncodingError, DecodingError, renderDouble } from "./json.ts";
 export { Instant, Duration, LocalDate, LocalDateTime } from "./time.ts";
 export { ErrorCode, CommandError, Outcome, Retention, httpStatusOf, type ErrorDetail, type Metadata, type EffectLike, type ReadOnlyLike } from "./effects/common.ts";
 export { command, query, stream, step, action, tool, guardrail, type HandlerRef, type ToolRef, type GuardrailRef, type GuardrailStage, type HandlerTable } from "./handlers.ts";
-export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect } from "./effects/eventSourced.ts";
+export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect, type ReplicationChange } from "./effects/eventSourced.ts";
 export { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
 export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnlyEffect, type KeyValueEffect } from "./effects/keyValue.ts";
 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 OutgoingMessage, type TimedActionEffect } from "./effects/stateless.ts";
-export { View, type ViewClass } from "./view.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 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 { type Socket, SocketClosed } from "./socket.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type CommandContext, type EventContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE, type AwaitPart, type WatchEvent, type WatchOptions, type Overflow, 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 { isTerminal, isUnknown, type Standing, type StandingStatus } from "./standing.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,19 +23,28 @@ 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 { 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, sseEvents, 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, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE } 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 { isTerminal, isUnknown } from "./standing.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/keyedView.d.ts

@@ -0,0 +1,59 @@
+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";
+import type { Standing } from "./standing.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;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
+    /** 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>, standing?: Standing): 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 {};

package/dist/keyedView.js

@@ -0,0 +1,73 @@
+// A keyed view: several entities' changes, each through a handler of its own, written to whichever rows
+// a change is about, by key. The sidecar runs one projection per source and handles one change at a
+// time across all of them; this process only says which rows each change writes.
+//
+//   export class Shipments extends KeyedView<ShipmentRow> {
+//     static readonly componentId = "shipments"
+//     static readonly row = ShipmentRowShape
+//     static readonly sources = [
+//       on(ShipmentEntity, ShipmentEvents, (v: Shipments, e) => v.onShipment(e)),
+//       on(CustomerEntity, CustomerEvents, (v: Shipments, e) => v.onCustomer(e)),
+//     ]
+//     static readonly declared = [declaredQuery("of-customer", `SELECT payload FROM ${tableOf("shipments")} WHERE ...`)]
+//     async onCustomer(event: CustomerEvent) {
+//       const theirs = await this.rows.ask("of-customer", { customer: this.subject })
+//       return this.effects.updateRows(theirs.map((r) => [r.shipmentId, { ...r, name: event.name }]))
+//     }
+//   }
+import { KeyedViewEffects } from "./effects/keyed.js";
+/**
+ * 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 function on(source, events, onChange, options = {}) {
+    return Object.freeze({ source, events, onChange, ...(options.deleted ? { deleted: options.deleted } : {}) });
+}
+export class KeyedView {
+    effects = new KeyedViewEffects();
+    #metadata = {};
+    #standing = undefined;
+    #client;
+    #rows;
+    /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    /** The id of the entity the change came from. */
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
+    /** This view's own rows, by key or by one of its declared queries. */
+    get rows() {
+        if (!this.#rows)
+            throw new Error("rows are only available inside a keyed view's handler");
+        return this.#rows;
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside a keyed view's handler");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "view";
+    }
+    /** @internal */
+    _bind(metadata, client, rows, standing) {
+        this.#metadata = metadata;
+        this.#standing = standing;
+        this.#client = client;
+        this.#rows = rows;
+    }
+}
+/** The rows a keyed view reads through the component client, on its own id. */
+export function clientRows(client, viewId, row) {
+    return {
+        get: (key) => client.views.get(viewId, key, row),
+        ask: (name, values = {}) => client.views.ask(viewId, name, values, row),
+    };
+}

package/dist/kinds.js

@@ -30,6 +30,8 @@ const CODE_TO_PROTO = Object.freeze({
     CONFLICT: ProtoErrorCode.CONFLICT,
     TIMEOUT: ProtoErrorCode.TIMEOUT,
     UNAVAILABLE: ProtoErrorCode.UNAVAILABLE,
+    WORKFLOW_FAILED: ProtoErrorCode.WORKFLOW_FAILED,
+    NOT_HOME: ProtoErrorCode.NOT_HOME,
 });
 export function errorCodeToProto(code) {
     return CODE_TO_PROTO[code];

package/dist/mcp.d.ts

@@ -0,0 +1,57 @@
+import { type Approval } from "./approvals.ts";
+export declare const VARIABLE_PREFIX = "ANKKA_MCP_";
+export declare const TOOL_PREFIX = "mcp__";
+type MaybePromise<T> = T | Promise<T>;
+export interface McpServerOptions {
+    /** Where the server is; `ANKKA_MCP_<NAME>_URL` replaces it, and is required when neither this nor `service` is given. */
+    readonly url?: string;
+    /** An ankka service, called as one, at `path` (by default `/mcp`), in `project` (by default this one). */
+    readonly service?: string;
+    readonly project?: string;
+    readonly path?: string;
+    /** A header's name and the `ANKKA_MCP_` variable its value is read from. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Every tool of the server waits for a person. */
+    readonly approval?: Approval;
+}
+export interface McpServerRef extends McpServerOptions {
+    readonly name: string;
+}
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export declare function mcpServer(name: string, options?: McpServerOptions): McpServerRef;
+/** Checks what an MCP server's tool answered before the model is told it: a reason to withhold it, or `null`. */
+export interface ResultGuardrailRef {
+    readonly name: string;
+    readonly check: (tool: string, text: string) => MaybePromise<string | null>;
+}
+export declare function resultGuardrail(name: string, check: (tool: string, text: string) => MaybePromise<string | null>): ResultGuardrailRef;
+/** The name a server's tool is offered to the model under. */
+export declare function toolName(server: string, tool: string): string;
+/** What is wrong with one server, in the sidecar's words. */
+export declare function serverProblems(server: McpServerRef): string[];
+/** The discovery form of a server. */
+export declare function serverToProto(server: McpServerRef): {
+    name: string;
+    address: {
+        case: "url";
+        value: string;
+    } | {
+        case: "service";
+        value: {
+            name: string;
+            path: string;
+            project?: string | undefined;
+        };
+    } | {
+        value?: undefined;
+        case: undefined;
+    };
+    headers: {
+        name: string;
+        variable: string;
+    }[];
+    approval?: {
+        withinMillis?: bigint;
+    } | undefined;
+};
+export {};

package/dist/mcp.js

@@ -0,0 +1,64 @@
+// MCP servers an agent offers the model, and the guardrails that check what they answer.
+//
+// The sidecar connects to each server when it starts, reads its tools and offers them to the model as
+// `mcp__<server>__<tool>`. This process is never asked to run one, and never sees a credential: a
+// header's value is read from a variable on the sidecar, and only `ANKKA_MCP_` variables reach it. What a
+// server's tool answers is put through the agent's result guardrails, which this process answers,
+// before the model is told it.
+//
+//   static readonly mcpServers = { tickets: mcpServer("tickets", { headers: { Authorization: "ANKKA_MCP_TICKETS_TOKEN" } }) }
+//   static readonly resultGuardrails = { noInstructions: resultGuardrail("no-instructions", (tool, text) => null) }
+import { approvalProblem, approvalToProto } from "./approvals.js";
+export const VARIABLE_PREFIX = "ANKKA_MCP_";
+export const TOOL_PREFIX = "mcp__";
+const NAME = /^[a-z0-9-]+$/;
+/** An MCP server the agent lists under `name`, lower-case letters, digits and hyphens. */
+export function mcpServer(name, options = {}) {
+    return Object.freeze({ ...options, name });
+}
+export function resultGuardrail(name, check) {
+    if (typeof name !== "string" || name.trim() === "")
+        throw new TypeError("a result guardrail needs a name");
+    return Object.freeze({ name, check });
+}
+/** The name a server's tool is offered to the model under. */
+export function toolName(server, tool) {
+    return `${TOOL_PREFIX}${server}__${tool}`;
+}
+/** What is wrong with one server, in the sidecar's words. */
+export function serverProblems(server) {
+    const found = [];
+    const name = server.name;
+    if (!NAME.test(name))
+        found.push(`an MCP server's name is lower-case letters, digits and hyphens ([a-z0-9-]), not '${name}'`);
+    if (server.url !== undefined && server.service !== undefined)
+        found.push(`MCP server '${name}' has both a URL and a service; give one`);
+    if (server.url !== undefined && server.url.trim() === "")
+        found.push(`MCP server '${name}' needs a URL`);
+    for (const [header, variable] of Object.entries(server.headers ?? {})) {
+        if (header.trim() === "")
+            found.push(`MCP server '${name}' has a header with no name`);
+        else if (!variable.startsWith(VARIABLE_PREFIX)) {
+            found.push(`MCP server '${name}': the header '${header}' takes its value from '${variable}', which must start ${VARIABLE_PREFIX} — only those variables reach the platform's program, which is what connects to the server`);
+        }
+    }
+    const approval = approvalProblem(server.approval);
+    if (approval)
+        found.push(`MCP server '${name}': ${approval}`);
+    return found;
+}
+/** The discovery form of a server. */
+export function serverToProto(server) {
+    const approval = approvalToProto(server.approval);
+    const address = server.url !== undefined
+        ? { case: "url", value: server.url }
+        : server.service !== undefined
+            ? { case: "service", value: { name: server.service, path: server.path ?? "/mcp", ...(server.project !== undefined ? { project: server.project } : {}) } }
+            : { case: undefined };
+    return {
+        name: server.name,
+        address,
+        headers: Object.entries(server.headers ?? {}).map(([name, variable]) => ({ name, variable })),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}