ankka 0.12.0 → 0.14.0

package/dist/testkit/integration.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentClient } from "../client.ts";
 import type { ServiceBuilder } from "../service.ts";
+import { type Buckets } from "../storage.ts";
 export interface AnkkaTestKitOptions {
     /** The sidecar image; `sidecarImage()` by default. */
     readonly image?: string;
@@ -9,6 +10,12 @@ export interface AnkkaTestKitOptions {
     /** How long to wait for the sidecar to report healthy; 120s by default. */
     readonly readyTimeoutMs?: number;
     readonly log?: (message: string) => void;
+    /**
+     * The service's buckets. By default the store `ANKKA_STORAGE_BACKEND=memory` gives this process: in
+     * memory, with the buckets `service.json` in the working directory declares (the unnamed one, and no
+     * named one, when there is no such file). `kit.storage` is the same store.
+     */
+    readonly storage?: Buckets;
 }
 /** What `http` answers with. */
 export declare class HttpResponse {
@@ -47,6 +54,8 @@ export declare class AnkkaTestKit {
     #private;
     /** The component client every handler in `service` uses, pointed at the sidecar's mapped callback port. */
     readonly client: ComponentClient;
+    /** The buckets the service holds: what a handler kept, a test reads here, and what a test puts here a handler reads. */
+    readonly storage: Buckets;
     private constructor();
     /** Starts Postgres, this process's server and the sidecar; a start that fails half-way stops what it started. */
     static start(service: ServiceBuilder, options?: AnkkaTestKitOptions): Promise<AnkkaTestKit>;

package/dist/testkit/integration.js

@@ -16,6 +16,7 @@ import { randomBytes } from "node:crypto";
 import { chmodSync, mkdtempSync, readdirSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { chooseStorage } from "../storage.js";
 import { VERSION } from "../version.js";
 const POSTGRES_IMAGE = "postgres:17-alpine";
 const HTTP_PORT = 9000;
@@ -149,7 +150,10 @@ export class AnkkaTestKit {
     #http;
     /** The component client every handler in `service` uses, pointed at the sidecar's mapped callback port. */
     client;
+    /** The buckets the service holds: what a handler kept, a test reads here, and what a test puts here a handler reads. */
+    storage;
     constructor(service, options) {
+        this.storage = options.storage ?? chooseStorage({ ...process.env, ANKKA_STORAGE_BACKEND: "memory" }).buckets;
         this.#service = service;
         this.#image = options.image ?? sidecarImage();
         this.#env = options.env ?? {};
@@ -203,7 +207,7 @@ export class AnkkaTestKit {
             .withCopyDirectoriesToContainer([{ source: this.#ddlDir, target: "/docker-entrypoint-initdb.d", mode: 0o755 }])
             .start();
         // This process's server, on all interfaces: the sidecar is in a container and dials in.
-        this.#server = this.#service.server({ host: "0.0.0.0", port: 0, log: this.#log });
+        this.#server = this.#service.server({ host: "0.0.0.0", port: 0, log: this.#log, storage: this.storage });
         this.#processPort = (await this.#server.start()).port;
         await this.#startSidecar();
     }

package/dist/testkit/kinds.d.ts

@@ -1,4 +1,5 @@
 import { ComponentClient } from "../client.ts";
+import { type Buckets } from "../storage.ts";
 import { type ErrorDetail, type Metadata } from "../effects/common.ts";
 import type { StepRef } from "../effects/workflow.ts";
 import type { ConsumerEffect, TimedActionEffect, ViewEffect } from "../effects/stateless.ts";
@@ -42,8 +43,10 @@ export declare class WorkflowTestKit<S, C extends Workflow<S>> {
     #private;
     readonly entityId: string;
     state: S;
+    /** The buckets the workflow's steps are given; the test reads what they kept here. */
+    readonly storage: Buckets;
     private constructor();
-    static of<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>, entityId?: string, client?: ComponentClient): WorkflowTestKit<S, C>;
+    static of<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>, entityId?: string, client?: ComponentClient, storage?: Buckets): WorkflowTestKit<S, C>;
     get progress(): WorkflowProgress;
     call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<MaterialisedWorkflowCommand<S, R>>;
     /** Runs one step, by name or declaration, with an input (or the pending transition's). */
@@ -102,8 +105,10 @@ export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
         readonly metadata: Metadata;
         readonly key?: string;
     }[];
+    /** The buckets the consumer is given; the test reads what it kept here. */
+    readonly storage: Buckets;
     private constructor();
-    static of<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>, client?: ComponentClient): ConsumerTestKit<M, Out, C>;
+    static of<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>, client?: ComponentClient, storage?: Buckets): ConsumerTestKit<M, Out, C>;
     /**
      * A message from source instance `subject`. The metadata says the runtime speaks this SDK's protocol
      * version; pass `"ankka.protocol"` or `"ankka.sequence"` to say otherwise.
@@ -118,8 +123,10 @@ export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
  */
 export declare class GraphConsumerTestKit<M> {
     #private;
+    /** The buckets the graph consumer is given; the test reads what it kept here. */
+    readonly storage: Buckets;
     private constructor();
-    static of<M>(cls: GraphConsumerClass<M>, client?: ComponentClient): GraphConsumerTestKit<M>;
+    static of<M>(cls: GraphConsumerClass<M>, client?: ComponentClient, storage?: Buckets): GraphConsumerTestKit<M>;
     /** A change from source instance `subject` (default `"test"`) at `sequence` (default 1). */
     onMessage(message: M, options?: GraphChange): Promise<Delta[]>;
     /** The source instance was deleted, at `sequence`. */
@@ -135,8 +142,10 @@ export interface GraphChange {
 /** Invokes a timed action's handlers as the sweeper would. */
 export declare class TimedActionTestKit<C extends TimedAction> {
     #private;
+    /** The buckets the timed action is given; the test reads what it kept here. */
+    readonly storage: Buckets;
     private constructor();
-    static of<C extends TimedAction>(cls: TimedActionClass<C>, client?: ComponentClient): TimedActionTestKit<C>;
+    static of<C extends TimedAction>(cls: TimedActionClass<C>, client?: ComponentClient, storage?: Buckets): TimedActionTestKit<C>;
     invoke<I>(action: HandlerRef<C, I, any, any> | string, input?: I, metadata?: Metadata): Promise<TimedActionEffect>;
 }
 /** What a scripted model answers next. */
@@ -189,9 +198,12 @@ export declare class AgentTestKit<C extends Agent> {
         role: "user" | "assistant";
         text: string;
     }[];
+    /** The buckets the agent's tools are given; the test reads what they kept here. */
+    readonly storage: Buckets;
     private constructor();
     static of<C extends Agent>(cls: AgentClass<C>, sessionId: string, model: ScriptedModel, client?: ComponentClient, options?: {
         readonly mcp?: ScriptedMcp;
+        readonly storage?: Buckets;
     }): AgentTestKit<C>;
     /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`; a turn that waits, with `ApprovalAwaited`. */
     ask<I>(handler: HandlerRef<C, I, any, any> | string, input?: I): Promise<string>;

package/dist/testkit/kinds.js

@@ -2,6 +2,7 @@
 // agents. Same rules as the event sourced kit: no sidecar, effects as values, every value round-tripped
 // through the component's codecs, the server's reduction.
 import { ComponentClient, noClient } from "../client.js";
+import { InMemoryBuckets } from "../storage.js";
 import { binaryCodecs, codecFor } from "../codec.js";
 import { commandContext } from "../context.js";
 import { CommandError, ErrorCode } from "../effects/common.js";
@@ -78,17 +79,20 @@ export class WorkflowTestKit {
     entityId;
     state;
     #progress = { pending: null, paused: null, ended: false, failed: null };
-    constructor(cls, entityId, client) {
+    /** The buckets the workflow's steps are given; the test reads what they kept here. */
+    storage;
+    constructor(cls, entityId, client, storage) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
+        this.storage = storage;
         this.entityId = entityId;
         const instance = new cls();
         instance._bindInstance(entityId);
         this.state = instance.emptyState();
     }
-    static of(cls, entityId = "test", client = noClient()) {
-        return new WorkflowTestKit(cls, entityId, client);
+    static of(cls, entityId = "test", client = noClient(), storage = new InMemoryBuckets()) {
+        return new WorkflowTestKit(cls, entityId, client, storage);
     }
     get progress() {
         return this.#progress;
@@ -96,6 +100,7 @@ export class WorkflowTestKit {
     #instance() {
         const w = new this.#cls();
         w._bindInstance(this.entityId);
+        w.storage = this.storage;
         return w;
     }
     async call(handler, input, metadata = {}) {
@@ -135,6 +140,7 @@ export class WorkflowTestKit {
         const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
         const w = this.#instance();
         w._bindCommand(this.state, commandContext(this.#registered.id, this.entityId, 0n, {}), this.#client);
+        w._enterStep();
         let effect;
         try {
             effect = (await ref.run(w, wireInput));
@@ -323,17 +329,21 @@ export class ConsumerTestKit {
      * `key` is the record key a message of `produceAll` named; absent, the message is keyed by its subject.
      */
     produced = [];
-    constructor(cls, client) {
+    /** The buckets the consumer is given; the test reads what it kept here. */
+    storage;
+    constructor(cls, client, storage) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
+        this.storage = storage;
     }
-    static of(cls, client = noClient()) {
-        return new ConsumerTestKit(cls, client);
+    static of(cls, client = noClient(), storage = new InMemoryBuckets()) {
+        return new ConsumerTestKit(cls, client, storage);
     }
     async #apply(fn, metadata, standing) {
         const consumer = new this.#cls();
         consumer._bind(metadata, this.#client.withMetadata(metadata), standing);
+        consumer.storage = this.storage;
         const effect = await fn(consumer);
         const outCodec = () => {
             const codec = this.#registered.outCodec;
@@ -374,13 +384,16 @@ export class GraphConsumerTestKit {
     #registered;
     #cls;
     #client;
-    constructor(cls, client) {
+    /** The buckets the graph consumer is given; the test reads what it kept here. */
+    storage;
+    constructor(cls, client, storage) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
+        this.storage = storage;
     }
-    static of(cls, client = noClient()) {
-        return new GraphConsumerTestKit(cls, client);
+    static of(cls, client = noClient(), storage = new InMemoryBuckets()) {
+        return new GraphConsumerTestKit(cls, client, storage);
     }
     async #apply(fn, options) {
         const metadata = {
@@ -391,6 +404,7 @@ export class GraphConsumerTestKit {
         };
         const consumer = new this.#cls();
         consumer._bind(metadata, this.#client.withMetadata(metadata));
+        consumer.storage = this.storage;
         const records = deltaRecords(await fn(consumer), metadata);
         if (records.length > 0)
             requireSeveralMessages(metadata);
@@ -411,19 +425,23 @@ export class TimedActionTestKit {
     #registered;
     #cls;
     #client;
-    constructor(cls, client) {
+    /** The buckets the timed action is given; the test reads what it kept here. */
+    storage;
+    constructor(cls, client, storage) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
+        this.storage = storage;
     }
-    static of(cls, client = noClient()) {
-        return new TimedActionTestKit(cls, client);
+    static of(cls, client = noClient(), storage = new InMemoryBuckets()) {
+        return new TimedActionTestKit(cls, client, storage);
     }
     async invoke(action, input, metadata = {}) {
         const ref = findHandler(this.#registered.actions, action, this.#registered.cls.name);
         const wireInput = ref.input ? roundTrip(codecFor(ref.input), input) : undefined;
         const instance = new this.#cls();
         instance._bind({ "ankka.timer": "test", "ankka.attempts": "1", ...metadata }, this.#client.withMetadata(metadata));
+        instance.storage = this.storage;
         return (await ref.run(instance, wireInput));
     }
 }
@@ -475,20 +493,24 @@ export class AgentTestKit {
     #turn;
     #decided = new Set();
     #nextId = 0;
-    constructor(cls, sessionId, model, client, mcp) {
+    /** The buckets the agent's tools are given; the test reads what they kept here. */
+    storage;
+    constructor(cls, sessionId, model, client, mcp, storage) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
         this.#cls = cls;
         this.#client = client;
+        this.storage = storage;
         this.#model = model;
         this.#mcp = mcp;
         this.sessionId = sessionId;
     }
     static of(cls, sessionId, model, client = noClient(), options = {}) {
-        return new AgentTestKit(cls, sessionId, model, client, options.mcp ?? {});
+        return new AgentTestKit(cls, sessionId, model, client, options.mcp ?? {}, options.storage ?? new InMemoryBuckets());
     }
     #agent() {
         const a = new this.#cls();
         a._bind(this.sessionId, {}, this.#client);
+        a.storage = this.storage;
         return a;
     }
     /** One turn: returns the reply text (JSON text for a `thenReplyJson` plan). A refusal or a blocked guardrail rejects with `CommandError`; a turn that waits, with `ApprovalAwaited`. */

package/dist/testkit/unit.d.ts

@@ -1,4 +1,5 @@
 import { ComponentClient } from "../client.ts";
+import { type Buckets } from "../storage.ts";
 import { type Principal } from "../context.ts";
 import { type ErrorDetail, type Metadata, type Retention } from "../effects/common.ts";
 import type { ReplicationChange } from "../effects/eventSourced.ts";
@@ -72,8 +73,10 @@ export interface SocketRun {
 /** Calls an endpoint's routes by path, matching them as the sidecar's router does: literal segments outrank parameters. */
 export declare class EndpointTestKit<C extends Endpoint> {
     #private;
+    /** The buckets the endpoint is given; the test reads what its routes kept here. */
+    readonly storage: Buckets;
     private constructor();
-    static of<C extends Endpoint>(cls: EndpointClass<C>, client?: ComponentClient): EndpointTestKit<C>;
+    static of<C extends Endpoint>(cls: EndpointClass<C>, client?: ComponentClient, storage?: Buckets): EndpointTestKit<C>;
     request(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<Response>;
     /**
      * Opens a socket route with no runtime: the handler is given `frames` one at a time and then told the

package/dist/testkit/unit.js

@@ -6,6 +6,7 @@
 import { create } from "@bufbuild/protobuf";
 import { HttpRequestSchema, SocketInSchema } from "../_proto/ankka/protocol/v1/endpoint_pb.js";
 import { ComponentClient, noClient } from "../client.js";
+import { InMemoryBuckets } from "../storage.js";
 import { binaryCodecs, codecFor } from "../codec.js";
 import { commandContext, eventContext } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
@@ -143,15 +144,18 @@ const PLACEHOLDER = /\{[A-Za-z_][A-Za-z0-9_]*\}/g;
 export class EndpointTestKit {
     #cls;
     #dispatcher;
-    constructor(cls, client) {
+    /** The buckets the endpoint is given; the test reads what its routes kept here. */
+    storage;
+    constructor(cls, client, storage) {
         this.#cls = cls;
+        this.storage = storage;
         const registry = Ankka.service({ client, log: () => { } })
             .register(cls)
             .validate();
-        this.#dispatcher = createHttpDispatcher({ registry, client, log: () => { } });
+        this.#dispatcher = createHttpDispatcher({ registry, client, log: () => { }, storage });
     }
-    static of(cls, client = noClient()) {
-        return new EndpointTestKit(cls, client);
+    static of(cls, client = noClient(), storage = new InMemoryBuckets()) {
+        return new EndpointTestKit(cls, client, storage);
     }
     #match(method, path) {
         const prefix = this.#cls.prefix;

package/dist/timedAction.d.ts

@@ -1,5 +1,7 @@
 import type { Metadata } from "./effects/common.ts";
+import { type ClientKeys } from "./client-keys.ts";
 import { type ComponentClient, type Secrets } from "./client.ts";
+import { type Buckets } from "./storage.ts";
 import type { HandlerTable } from "./handlers.ts";
 import { TimedActionEffects } from "./effects/stateless.ts";
 import { type Services } from "./services.ts";
@@ -19,6 +21,14 @@ export declare abstract class TimedAction {
     get secrets(): Secrets;
     /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
     set secrets(store: Secrets);
+    /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
+    get clientKeys(): ClientKeys;
+    /** A unit test's in place of the runtime's: `component.clientKeys = new InMemoryClientKeys()`. */
+    set clientKeys(keys: ClientKeys);
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage(): Buckets;
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets: Buckets);
     /** 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()`. */

package/dist/timedAction.js

@@ -2,7 +2,9 @@
 // sweeper delivers it here, retrying a failure with backoff.
 //
 //   static readonly actions = { remind: action("remind", s.string, (t: Reminder, id) => t.remind(id)) }
+import { clientKeysFor } from "./client-keys.js";
 import { secretsFor } from "./client.js";
+import { processStorage } from "./storage.js";
 import { TimedActionEffects } from "./effects/stateless.js";
 import { servicesFor } from "./services.js";
 export class TimedAction {
@@ -39,6 +41,24 @@ export class TimedAction {
     set secrets(store) {
         this.#secrets = store;
     }
+    #clientKeys;
+    /** The service's client keys (1.20): issued for its MCP endpoint, kept by the runtime, each shown once. */
+    get clientKeys() {
+        return this.#clientKeys ?? clientKeysFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.clientKeys = new InMemoryClientKeys()`. */
+    set clientKeys(keys) {
+        this.#clientKeys = keys;
+    }
+    #storage;
+    /** The service's buckets: `this.storage.default`, or `this.storage.bucket("photos")`. */
+    get storage() {
+        return this.#storage ?? processStorage();
+    }
+    /** A unit test's store in place of the runtime's: `component.storage = new InMemoryBuckets()`. */
+    set storage(buckets) {
+        this.#storage = buckets;
+    }
     #services;
     /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
     get services() {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.12.0";
+export declare const VERSION = "0.14.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.12.0";
+export const VERSION = "0.14.0";

package/dist/workflow.d.ts

@@ -4,6 +4,7 @@ import type { HandlerTable } from "./handlers.ts";
 import { type ComponentClient, type Secrets } from "./client.ts";
 import { StepEffects, WorkflowEffects, type WorkflowSettings } from "./effects/workflow.ts";
 import { type Services } from "./services.ts";
+import { type Buckets } from "./storage.ts";
 export declare abstract class Workflow<S> {
     #private;
     /** Inside a command handler. */
@@ -21,6 +22,13 @@ export declare abstract class Workflow<S> {
     get secrets(): Secrets;
     /** A unit test's store in place of the runtime's. */
     set secrets(store: Secrets);
+    /**
+     * The service's buckets, in a step. A command handler is refused: a wait on a store would hold the
+     * workflow's other commands behind it.
+     */
+    get storage(): Buckets;
+    /** A unit test's store in place of the runtime's. */
+    set storage(buckets: Buckets);
     /**
      * Other services, called as this one, in a step. A command handler is refused, as for the secret
      * store: it would block the workflow's other commands behind another service.

package/dist/workflow.js

@@ -9,6 +9,7 @@ import { secretsFor } from "./client.js";
 import { CommandError } from "./effects/common.js";
 import { StepEffects, WorkflowEffects } from "./effects/workflow.js";
 import { servicesFor } from "./services.js";
+import { processStorage, StorageRefusals } from "./storage.js";
 export class Workflow {
     /** Inside a command handler. */
     effects = new WorkflowEffects();
@@ -55,6 +56,20 @@ export class Workflow {
     set secrets(store) {
         this.#secrets = store;
     }
+    #storage;
+    /**
+     * The service's buckets, in a step. A command handler is refused: a wait on a store would hold the
+     * workflow's other commands behind it.
+     */
+    get storage() {
+        if (!this.#inStep)
+            throw StorageRefusals.stepsOnly();
+        return this.#storage ?? processStorage();
+    }
+    /** A unit test's store in place of the runtime's. */
+    set storage(buckets) {
+        this.#storage = buckets;
+    }
     #services;
     /**
      * Other services, called as this one, in a step. A command handler is refused, as for the secret

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ankka",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Build services on ankka in TypeScript: entities, views, workflows, agents and endpoints hosted by the ankka sidecar.",
   "license": "Apache-2.0",
   "type": "module",
@@ -51,7 +51,7 @@
     "@bufbuild/protobuf": "^2.15.0",
     "@connectrpc/connect": "^2.2.0",
     "@connectrpc/connect-node": "^2.2.0",
-    "canonicalize": "^2.1.0"
+    "canonicalize": "^5.1.0"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",