ankka 0.11.0 → 0.13.0

package/dist/testkit/index.d.ts

@@ -1,3 +1,3 @@
-export { EventSourcedTestKit, EndpointTestKit, Response, type RequestOptions, type Materialised, type SocketRun } from "./unit.ts";
+export { EventSourcedTestKit, EndpointTestKit, Response, type RequestOptions, type Materialised, type SocketRun, type ReplicationMode } from "./unit.ts";
 export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, KeyedViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, type GraphChange, } from "./kinds.ts";
 export { AnkkaTestKit, PUBLISHED_SIDECAR, sidecarImage, type AnkkaTestKitOptions, type HttpResponse, type Http, type Beside } from "./integration.ts";

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";
@@ -15,6 +16,7 @@ import type { Agent, AgentClass } from "../agent.ts";
 import type { HandlerRef } from "../handlers.ts";
 import { type MaterialisedKeyValue, type MaterialisedStep, type MaterialisedWorkflowCommand } from "../materialise.ts";
 import { type AgentOutcome, type DecisionInput } from "../approvals.ts";
+import type { Standing } from "../standing.ts";
 /** Drives one key value entity instance through its handlers. */
 export declare class KeyValueTestKit<S, C extends KeyValueEntity<S>> {
     #private;
@@ -41,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). */
@@ -58,8 +62,11 @@ export declare class ViewTestKit<E, Row, C extends View<E, Row>> {
     readonly rows: Map<string, Row>;
     private constructor();
     static of<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>, client?: ComponentClient): ViewTestKit<E, Row, C>;
-    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
-    onChange(key: string, event: E, metadata?: Metadata): Promise<ViewEffect<Row>>;
+    /**
+     * A change from source instance `key`: the event, round-tripped through the source's event codec.
+     * `standing` is a workflow's, for a view whose source is one.
+     */
+    onChange(key: string, event: E, metadata?: Metadata, standing?: Standing): Promise<ViewEffect<Row>>;
     /** The source instance `key` was deleted. */
     onDelete(key: string, metadata?: Metadata): Promise<ViewEffect<Row>>;
     get(key: string): Row | null;
@@ -80,8 +87,8 @@ export declare class KeyedViewTestKit<Row, C extends KeyedView<Row>> {
     static of<Row, C extends KeyedView<Row>>(cls: KeyedViewClass<Row, C>, client?: ComponentClient): KeyedViewTestKit<Row, C>;
     /** What the declared query `name` answers, given the values it is asked with. */
     answering(name: string, answer: (values: Readonly<Record<string, string>>) => Row[]): this;
-    /** A change of the entity `key` of `entity`, round-tripped through that source's codec. */
-    change<E>(entity: ComponentRef, key: string, event: E): Promise<KeyedViewEffect<Row>>;
+    /** A change of `key` of `entity`, round-tripped through that source's codec; `standing` a workflow's. */
+    change<E>(entity: ComponentRef, key: string, event: E, standing?: Standing): Promise<KeyedViewEffect<Row>>;
     /** The entity `key` of `entity` was deleted. */
     deleted(entity: ComponentRef, key: string): Promise<KeyedViewEffect<Row>>;
     get(key: string): Row | null;
@@ -98,13 +105,15 @@ 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.
      */
-    onMessage(message: M, subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
+    onMessage(message: M, subject?: string, metadata?: Metadata, standing?: Standing): Promise<ConsumerEffect<Out>>;
     onDelete(subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
 }
 /**
@@ -114,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`. */
@@ -131,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. */
@@ -185,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));
@@ -199,11 +205,11 @@ export class ViewTestKit {
     static of(cls, client = noClient()) {
         return new ViewTestKit(cls, client);
     }
-    async #apply(key, fn, metadata) {
+    async #apply(key, fn, metadata, standing) {
         const view = new this.#cls();
         const rowCodec = this.#registered.rowCodec;
         const current = this.rows.get(key);
-        view._bind(current === undefined ? null : roundTrip(rowCodec, current), { "ce-subject": key, ...metadata }, this.#client.withMetadata(metadata));
+        view._bind(current === undefined ? null : roundTrip(rowCodec, current), { "ce-subject": key, ...metadata }, this.#client.withMetadata(metadata), standing);
         const effect = await fn(view);
         switch (effect.kind) {
             case "update-row":
@@ -217,10 +223,13 @@ export class ViewTestKit {
         }
         return effect;
     }
-    /** A change from source instance `key`: the event, round-tripped through the source's event codec. */
-    onChange(key, event, metadata = {}) {
+    /**
+     * A change from source instance `key`: the event, round-tripped through the source's event codec.
+     * `standing` is a workflow's, for a view whose source is one.
+     */
+    onChange(key, event, metadata = {}, standing) {
         const wire = roundTrip(this.#registered.eventCodec, event);
-        return this.#apply(key, (v) => v.onChange(wire), metadata);
+        return this.#apply(key, (v) => v.onChange(wire), metadata, standing);
     }
     /** The source instance `key` was deleted. */
     onDelete(key, metadata = {}) {
@@ -265,7 +274,7 @@ export class KeyedViewTestKit {
             throw new Error(`${this.#registered.id} reads no ${JSON.stringify(entity.componentId)}`);
         return source;
     }
-    async #apply(key, run) {
+    async #apply(key, run, standing) {
         const view = new this.#cls();
         const rowCodec = this.#registered.rowCodec;
         const id = this.#registered.id;
@@ -283,7 +292,7 @@ export class KeyedViewTestKit {
         };
         this.#sequence += 1;
         const metadata = { "ce-subject": key, "ankka.sequence": String(this.#sequence) };
-        view._bind(metadata, this.#client.withMetadata(metadata), rows);
+        view._bind(metadata, this.#client.withMetadata(metadata), rows, standing);
         const effect = ((await run(view)) ?? { kind: "rows", changes: [] });
         if (effect.kind !== "rows")
             throw new TypeError(`${id}'s handler returned something that is not a keyed view effect`);
@@ -295,11 +304,11 @@ export class KeyedViewTestKit {
         }
         return effect;
     }
-    /** A change of the entity `key` of `entity`, round-tripped through that source's codec. */
-    change(entity, key, event) {
+    /** A change of `key` of `entity`, round-tripped through that source's codec; `standing` a workflow's. */
+    change(entity, key, event, standing) {
         const source = this.#source(entity);
         const wire = roundTrip(source.eventCodec, event);
-        return this.#apply(key, (v) => source.onChange(v, wire));
+        return this.#apply(key, (v) => source.onChange(v, wire), standing);
     }
     /** The entity `key` of `entity` was deleted. */
     deleted(entity, key) {
@@ -320,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) {
+    async #apply(fn, metadata, standing) {
         const consumer = new this.#cls();
-        consumer._bind(metadata, this.#client.withMetadata(metadata));
+        consumer._bind(metadata, this.#client.withMetadata(metadata), standing);
+        consumer.storage = this.storage;
         const effect = await fn(consumer);
         const outCodec = () => {
             const codec = this.#registered.outCodec;
@@ -354,9 +367,9 @@ export class ConsumerTestKit {
      * 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.
      */
-    onMessage(message, subject = "test", metadata = {}) {
+    onMessage(message, subject = "test", metadata = {}, standing) {
         const wire = roundTrip(this.#registered.messageCodec, message);
-        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
+        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata }, standing);
     }
     onDelete(subject = "test", metadata = {}) {
         return this.#apply((c) => c.onDelete(), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
@@ -371,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 = {
@@ -388,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);
@@ -408,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));
     }
 }
@@ -472,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,15 +1,30 @@
 import { ComponentClient } from "../client.ts";
+import { type Buckets } from "../storage.ts";
 import { type Principal } from "../context.ts";
-import type { ErrorDetail, Metadata, Retention } from "../effects/common.ts";
+import { type ErrorDetail, type Metadata, type Retention } from "../effects/common.ts";
+import type { ReplicationChange } from "../effects/eventSourced.ts";
 import type { Endpoint, EndpointClass } from "../endpoint.ts";
 import { EventSourcedEntity, type EventSourcedEntityClass } from "../eventSourcedEntity.ts";
 import type { HandlerRef } from "../handlers.ts";
 import { type Materialised } from "../materialise.ts";
 export type { Materialised };
 /** Drives one event sourced entity instance through its handlers, folding events as it goes. */
+/** How a replicated entity's copy stands in the test kit (1.19); `installation` is the copy's own. */
+export type ReplicationMode = {
+    readonly kind: "unreplicated";
+} | {
+    readonly kind: "home";
+    readonly installation?: string;
+} | {
+    readonly kind: "follower";
+    readonly home: string;
+    readonly installation?: string;
+};
 export declare class EventSourcedTestKit<S, E, C extends EventSourcedEntity<S, E>> {
     #private;
     readonly entityId: string;
+    /** The handover or change to the replication set the last call asked for, if any. */
+    lastReplication: ReplicationChange | undefined;
     /** The state now, after every call so far. */
     state: S;
     /** The sequence number of the last event, `0n` before any. */
@@ -18,7 +33,18 @@ export declare class EventSourcedTestKit<S, E, C extends EventSourcedEntity<S, E
     readonly allEvents: E[];
     private constructor();
     /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
-    static of<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>, entityId?: string, client?: ComponentClient): EventSourcedTestKit<S, E, C>;
+    static of<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>, entityId?: string, client?: ComponentClient, 
+    /**
+     * How a replicated entity's copy stands (1.19): `{ kind: "home" }`, where every command runs, or
+     * `{ kind: "follower", home }`, where a command that may persist is refused `NOT_HOME` and a query is
+     * answered from what `replay` gave it. Not replicated by default.
+     */
+    mode?: ReplicationMode): EventSourcedTestKit<S, E, C>;
+    /**
+     * Applies `events` as history the copy already holds, written at `writtenAt` (this installation by
+     * default): for a follower, what it has mirrored from its home.
+     */
+    replay(events: readonly E[], writtenAt?: string | null): void;
     /** Sends a command or query and returns what its effect amounts to. */
     call<I, R>(handler: HandlerRef<C, I, R, any> | string, input?: I, metadata?: Metadata): Promise<Materialised<S, E, R>>;
 }
@@ -47,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,8 +6,10 @@
 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 } from "../context.js";
+import { commandContext, eventContext } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
 import { EventSourcedEntity } from "../eventSourcedEntity.js";
 import { materialiseEventSourced } from "../materialise.js";
 import { Ankka } from "../service.js";
@@ -22,19 +24,24 @@ function findHandler(handlers, handler, who) {
         throw new Error(`${who} has no handler ${JSON.stringify(name)}; declared: ${[...handlers.keys()].sort().join(", ")}`);
     return found;
 }
-/** Drives one event sourced entity instance through its handlers, folding events as it goes. */
 export class EventSourcedTestKit {
     #registered;
     #entity;
     #client;
+    #mode;
+    #here;
     entityId;
+    /** The handover or change to the replication set the last call asked for, if any. */
+    lastReplication = undefined;
     /** The state now, after every call so far. */
     state;
     /** The sequence number of the last event, `0n` before any. */
     sequence = 0n;
     /** Every event persisted so far, in order. */
     allEvents = [];
-    constructor(cls, entityId, client) {
+    constructor(cls, entityId, client, mode = { kind: "unreplicated" }) {
+        this.#mode = mode;
+        this.#here = mode.kind === "unreplicated" ? null : (mode.installation ?? "test");
         const registry = Ankka.service({ client, log: () => { } })
             .register(cls)
             .validate();
@@ -46,15 +53,36 @@ export class EventSourcedTestKit {
         this.state = this.#entity.emptyState();
     }
     /** A kit for `cls` as instance `entityId`. Calls to other components reach `client`, which by default refuses them. */
-    static of(cls, entityId = "test", client = noClient()) {
-        return new EventSourcedTestKit(cls, entityId, client);
+    static of(cls, entityId = "test", client = noClient(), 
+    /**
+     * How a replicated entity's copy stands (1.19): `{ kind: "home" }`, where every command runs, or
+     * `{ kind: "follower", home }`, where a command that may persist is refused `NOT_HOME` and a query is
+     * answered from what `replay` gave it. Not replicated by default.
+     */
+    mode = { kind: "unreplicated" }) {
+        return new EventSourcedTestKit(cls, entityId, client, mode);
+    }
+    /**
+     * Applies `events` as history the copy already holds, written at `writtenAt` (this installation by
+     * default): for a follower, what it has mirrored from its home.
+     */
+    replay(events, writtenAt = this.#here) {
+        for (const event of events) {
+            this.sequence += 1n;
+            this.state = this.#entity.applyEvent(this.state, event, eventContext(writtenAt, writtenAt === this.#here, this.sequence));
+        }
     }
     /** Sends a command or query and returns what its effect amounts to. */
     async call(handler, input, metadata = {}) {
         const ref = findHandler(this.#registered.handlers, handler, this.#registered.cls.name);
+        if (this.#mode.kind === "follower" && !ref.readOnly) {
+            // The runtime forwards such a command to the home; here there is no home to forward to.
+            const error = { message: `the home of '${this.entityId}' is '${this.#mode.home}'; a follower handles no command that may persist`, code: ErrorCode.NotHome };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
         const inputCodec = ref.input ? codecFor(ref.input) : undefined;
         const wireInput = inputCodec ? roundTrip(inputCodec, input) : undefined;
-        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata);
+        const context = commandContext(this.#registered.id, this.entityId, this.sequence, metadata, undefined, this.#here, this.#mode.kind !== "follower");
         this.#entity._bindCommand(this.state, context, this.#client.withMetadata(metadata));
         let effect;
         try {
@@ -65,7 +93,20 @@ export class EventSourcedTestKit {
         }
         if (ref.readOnly && effect.kind !== "read-only")
             throw new Error(`${this.#registered.id}/${ref.name} is a query and returned a persisting effect`);
-        const m = materialiseEventSourced(effect, this.state, (s, e) => this.#entity.applyEvent(s, e));
+        let applied = this.sequence;
+        const m = materialiseEventSourced(effect, this.state, (s, e) => {
+            applied += 1n;
+            return this.#entity.applyEvent(s, e, eventContext(this.#here, true, applied));
+        });
+        const replication = effect.kind === "persist" ? effect.replication : undefined;
+        if (!m.error && replication && this.#mode.kind === "unreplicated") {
+            const error = {
+                message: `${this.#registered.id} is not replicated in this test kit; drive it with { kind: "home" } to see the handover or the change to the replication set it asks for`,
+                code: ErrorCode.BadRequest,
+            };
+            return Object.freeze({ events: [], newState: this.state, retention: null, reply: undefined, error, noReply: false });
+        }
+        this.lastReplication = m.error ? undefined : replication;
         const eventCodec = this.#registered.eventCodec;
         const stateCodec = this.#registered.stateCodec;
         const events = m.events.map((e) => roundTrip(eventCodec, e));
@@ -103,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.11.0";
+export declare const VERSION = "0.13.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.11.0";
+export const VERSION = "0.13.0";