ankka 0.11.0 → 0.12.0

package/dist/server/eventSourced.js

@@ -9,12 +9,20 @@
 import { create } from "@bufbuild/protobuf";
 import { EventSourced, EventSourcedOutSchema, } from "../_proto/ankka/protocol/v1/event_sourced_pb.js";
 import { codecFor } from "../codec.js";
-import { commandContext, metadataFromProto } from "../context.js";
+import { commandContext, eventContext, metadataFromProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
 import { binaryCodecs } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { materialiseEventSourced } from "../materialise.js";
 import { decodePayload, encodePayload } from "./payloads.js";
+/** A replicated entity's handover or change to its replication set, as the reply carries it (1.19). */
+export function replicationToProto(change) {
+    if (!change)
+        return undefined;
+    return change.kind === "hand-over"
+        ? { change: { case: "handOverTo", value: change.to } }
+        : { change: { case: "set", value: { add: [...change.add], remove: [...change.remove] } } };
+}
 /** Retention as the protocol carries it; `undefined` when the effect asked for none. */
 export function retentionToProto(retention) {
     if (!retention)
@@ -43,10 +51,13 @@ export async function* handleEventSourced(requests, ctx) {
     let entityId = "";
     let state;
     let sequence = 0n;
+    // This installation, for a replicated entity (1.19): null on a service that names none.
+    let here = null;
     for await (const m of requests) {
         switch (m.message.case) {
             case "init": {
                 const init = m.message.value;
+                here = init.installation || null;
                 const found = ctx.registry.component(init.componentId);
                 if (!found || found.kind !== "event-sourced") {
                     yield failure(0n, { message: `no event sourced entity ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound });
@@ -80,7 +91,8 @@ export async function* handleEventSourced(requests, ctx) {
                 }
                 const ev = m.message.value;
                 try {
-                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload));
+                    const written = ev.installation || here;
+                    state = entity.applyEvent(state, decodePayload(registered.eventCodec, ev.payload), eventContext(written, written === here, ev.sequence));
                     sequence = ev.sequence;
                 }
                 catch (e) {
@@ -95,7 +107,7 @@ export async function* handleEventSourced(requests, ctx) {
                     yield failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal });
                     return;
                 }
-                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx);
+                const result = await runCommand(registered, entity, entityId, state, sequence, m.message.value, ctx, here);
                 yield result.out;
                 if (result.newState !== undefined) {
                     state = result.newState.state;
@@ -108,7 +120,7 @@ export async function* handleEventSourced(requests, ctx) {
         }
     }
 }
-async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx) {
+async function runCommand(registered, entity, entityId, state, sequence, cmd, ctx, here = null) {
     const handler = registered.handlers.get(cmd.name);
     if (!handler)
         return { out: failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound }) };
@@ -120,7 +132,7 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
         return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest }) };
     }
     const metadata = metadataFromProto(cmd.metadata);
-    const context = commandContext(registered.id, entityId, sequence, metadata);
+    const context = commandContext(registered.id, entityId, sequence, metadata, undefined, cmd.installation || null, cmd.atHome);
     let effect;
     entity._bindCommand(state, context, ctx.client.withMetadata(metadata));
     try {
@@ -137,7 +149,12 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
         return { out: failure(cmd.id, { message: `${registered.id}/${cmd.name} is a query and returned a persisting effect`, code: ErrorCode.Internal }) };
     }
     try {
-        const m = materialiseEventSourced(effect, state, (s, e) => entity.applyEvent(s, e));
+        let applied = sequence;
+        const m = materialiseEventSourced(effect, state, (s, e) => {
+            applied += 1n;
+            return entity.applyEvent(s, e, eventContext(here, true, applied));
+        });
+        const replication = !m.error && effect.kind === "persist" ? replicationToProto(effect.replication) : undefined;
         const events = m.events.map((e) => encodePayload(registered.eventCodec, e));
         const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
         const outcome = m.error
@@ -154,6 +171,7 @@ async function runCommand(registered, entity, entityId, state, sequence, cmd, ct
                     retention: retentionToProto(m.retention),
                     outcome,
                     snapshot: cmd.snapshotRequested ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                    replication,
                 },
             },
         });

package/dist/server/http.js

@@ -47,6 +47,8 @@ function callerOf(req) {
             return Object.freeze({ kind: "gateway" });
         case "service":
             return Object.freeze({ kind: "service", project: kind.value.project, name: kind.value.name });
+        case "machine":
+            return Object.freeze({ kind: "machine", organization: kind.value.organization, name: kind.value.name });
         default:
             return Object.freeze({ kind: "local" });
     }

package/dist/server/stateless.js

@@ -15,6 +15,7 @@ import { JSON_CONTENT } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { decodePayload, encodePayload } from "./payloads.js";
 import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+import { standingFromProto } from "../standing.js";
 function messageOf(e) {
     return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
 }
@@ -33,7 +34,7 @@ async function handleKeyedView(req, sourceId, ctx) {
     const view = new registered.cls();
     try {
         const client = ctx.client.withMetadata(metadata);
-        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec));
+        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec), standingFromProto(req.standing));
         const effect = (req.deleted
             ? source.deleted
                 ? await source.deleted(view)
@@ -63,7 +64,7 @@ export async function handleView(req, ctx) {
     const view = new registered.cls();
     try {
         const row = req.row ? decodePayload(registered.rowCodec, req.row) : null;
-        view._bind(row, metadata, ctx.client.withMetadata(metadata));
+        view._bind(row, metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
         const effect = req.deleted ? await view.onDelete() : await view.onChange(decodePayload(registered.eventCodec, req.event));
         switch (effect.kind) {
             case "update-row":
@@ -102,7 +103,7 @@ function produceAll(request, messages) {
 }
 async function graphEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     switch (effect.kind) {
         case "publish":
@@ -121,7 +122,7 @@ async function graphEffect(registered, req, metadata, ctx) {
 }
 async function consumerEffect(registered, req, metadata, ctx) {
     const consumer = new registered.cls();
-    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    consumer._bind(metadata, ctx.client.withMetadata(metadata), standingFromProto(req.standing));
     const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
     const outCodec = () => {
         if (!registered.outCodec)

package/dist/service.d.ts

@@ -28,6 +28,8 @@ export interface RegisteredEventSourced {
     readonly eventCodec: Codec<any>;
     readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
     readonly snapshotEvery: number;
+    /** Declared replicated (1.19). */
+    readonly replicated: boolean;
 }
 export interface RegisteredKeyValue {
     readonly kind: "key-value";
@@ -58,6 +60,8 @@ export type Source = {
     readonly contract?: Contract;
     /** The declared broker the topic is on; absent is the installation's. */
     readonly broker?: string;
+    /** Another project's topic: the project whose topic it is (1.15). */
+    readonly project?: string;
     /** Partitions handled at once, each in order. */
     readonly parallel?: boolean;
 };
@@ -102,6 +106,8 @@ export interface RegisteredConsumer {
     /** A graph consumer: its handlers return elements, each published as a delta under its element key. */
     readonly graph: boolean;
     readonly version: number | undefined;
+    /** Given a replicated entity's mirrored changes too (1.19). */
+    readonly mirroredChanges: boolean;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";

package/dist/service.js

@@ -191,7 +191,18 @@ function registerEventSourced(cls, problems) {
     const handlers = collectHandlers(cls.handlers, "handlers", ["command", "query"], fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "event-sourced", id: cls.componentId, cls, stateCodec: codecFor(cls.state), eventCodec: codecFor(cls.events), handlers, snapshotEvery });
+    if (cls.replicated !== undefined && typeof cls.replicated !== "boolean")
+        fail(`replicated must be true or false, not ${String(cls.replicated)}`);
+    return Object.freeze({
+        kind: "event-sourced",
+        id: cls.componentId,
+        cls,
+        stateCodec: codecFor(cls.state),
+        eventCodec: codecFor(cls.events),
+        handlers,
+        snapshotEvery,
+        replicated: cls.replicated === true,
+    });
 }
 function registerKeyValue(cls, problems) {
     const { fail, ok } = checker(cls, problems);
@@ -261,6 +272,12 @@ function topicProblems(cls, consumer, fail) {
     if ((cls.contract !== undefined || cls.broker !== undefined || cls.parallel !== undefined) && !readsTopic) {
         fail("declares a contract, a broker or parallel, which apply to a topic; it reads a component");
     }
+    if (cls.project !== undefined && (typeof cls.project !== "string" || cls.project.trim() === ""))
+        fail("project must be the id of the project whose topic this is");
+    if (cls.project !== undefined && !readsTopic)
+        fail("names a project, which applies to a topic; it reads a component");
+    if (cls.project !== undefined && cls.broker !== undefined)
+        fail("names a project and a broker; another project's topic is on the installation's broker");
 }
 function sourceOf(cls, fail, consumer) {
     const hasSource = cls.source !== undefined;
@@ -281,6 +298,7 @@ function sourceOf(cls, fail, consumer) {
             ...(cls.contract instanceof Contract ? { contract: cls.contract } : {}),
             ...(typeof cls.broker === "string" ? { broker: cls.broker } : {}),
             ...(cls.parallel === true ? { parallel: true } : {}),
+            ...(typeof cls.project === "string" ? { project: cls.project } : {}),
         };
     }
     const src = cls.source;
@@ -413,6 +431,7 @@ function registerConsumer(cls, problems) {
         produces,
         graph: false,
         version: cls.version,
+        mirroredChanges: cls.mirroredChanges === true,
     });
 }
 /**
@@ -436,10 +455,15 @@ function publicationOf(declared, fail) {
         fail("producesTo.contract must be a Contract: Contract.fromFile(path, name)");
     if (p.broker !== undefined && (typeof p.broker !== "string" || p.broker.trim() === ""))
         fail("producesTo.broker must be the name of a broker the project declares");
+    if (p.project !== undefined && (typeof p.project !== "string" || p.project.trim() === ""))
+        fail("producesTo.project must be the id of the project whose topic this is");
+    if (p.project !== undefined && p.broker !== undefined)
+        fail("producesTo names a project and a broker; another project's topic is on the installation's broker");
     return {
         topic: p.topic,
         ...(p.contract instanceof Contract ? { contract: p.contract } : {}),
         ...(typeof p.broker === "string" ? { broker: p.broker } : {}),
+        ...(typeof p.project === "string" ? { project: p.project } : {}),
     };
 }
 /** A graph consumer is a consumer to discovery and to the runtime: one that produces deltas to its topic. */
@@ -465,6 +489,7 @@ function registerGraphConsumer(cls, problems) {
         produces: undefined,
         graph: true,
         version: cls.version,
+        mirroredChanges: cls.mirroredChanges === true,
     });
 }
 function registerTimedAction(cls, problems) {

package/dist/spec.d.ts

@@ -2,7 +2,7 @@ import { type MessageInitShape } from "@bufbuild/protobuf";
 import { Endpoint_Acl, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import type { Registry } from "./service.ts";
 import type { Acl } from "./routes.ts";
-export declare const PROTOCOL_VERSION = "1.14";
+export declare const PROTOCOL_VERSION = "1.19";
 export declare const SDK_NAME = "ankka-typescript";
 export declare function aclToProto(acl: Acl): Endpoint_Acl;
 /** The callers a CALLERS acl names, as discovery carries them; empty for every other rule. */

package/dist/spec.js

@@ -17,7 +17,7 @@ function toolInit(t) {
         ...(approval !== undefined ? { approval } : {}),
     };
 }
-export const PROTOCOL_VERSION = "1.14";
+export const PROTOCOL_VERSION = "1.19";
 export const SDK_NAME = "ankka-typescript";
 export function aclToProto(acl) {
     if (typeof acl === "object")
@@ -43,6 +43,8 @@ export function callersToProto(acl) {
                 return { kind: { case: "anyInProject", value: {} } };
             case "self":
                 return { kind: { case: "self", value: {} } };
+            case "granted":
+                return { kind: { case: "granted", value: {} } };
             case "service":
                 return { kind: { case: "service", value: m.project !== undefined ? { name: m.name, project: m.project } : { name: m.name } } };
         }
@@ -62,6 +64,8 @@ function sourceInit(source) {
         ...(source.contract !== undefined ? { contract: { name: source.contract.name, fingerprint: source.contract.fingerprint } } : {}),
         ...(source.broker !== undefined ? { broker: source.broker } : {}),
         ...(source.parallel === true ? { parallel: true } : {}),
+        // 1.15: another project's topic.
+        ...(source.project !== undefined ? { project: source.project } : {}),
     };
     if (start === undefined)
         return { source: { case: "topic", value: source.topic }, ...options };
@@ -93,7 +97,7 @@ function componentInit(c) {
         case "autonomous-agent":
             return autonomousInit(c);
         case "event-sourced":
-            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery } } };
+            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery, replicated: c.replicated } } };
         case "key-value":
             return { ...base, handlers: handlerInits(c.handlers), detail: { case: "keyValue", value: {} } };
         case "workflow":
@@ -113,7 +117,7 @@ function componentInit(c) {
                         rowManifest: c.rowCodec.manifest,
                         queries: [...c.queries],
                         ...(c.version !== undefined ? { version: c.version } : {}),
-                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement })),
+                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement, watched: q.watched ?? false })),
                     },
                 },
             };
@@ -128,7 +132,7 @@ function componentInit(c) {
                         queries: [],
                         ...(c.version !== undefined ? { version: c.version } : {}),
                         sources: [...c.sources.values()].map((s) => sourceInit({ component: { kind: s.kind, id: s.id } })),
-                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement })),
+                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement, watched: q.watched ?? false })),
                     },
                 },
             };
@@ -142,6 +146,7 @@ function componentInit(c) {
                         source: sourceInit(c.source),
                         ...(c.producesTo !== undefined ? { producesTo: c.producesTo } : {}),
                         ...(c.version !== undefined ? { version: c.version } : {}),
+                        mirroredChanges: c.mirroredChanges,
                         // 1.14: the publication with its contract and broker; `producesTo` stays for an older sidecar.
                         ...(c.produces !== undefined
                             ? {
@@ -149,6 +154,7 @@ function componentInit(c) {
                                     topic: c.produces.topic,
                                     ...(c.produces.contract !== undefined ? { contract: { name: c.produces.contract.name, fingerprint: c.produces.contract.fingerprint } } : {}),
                                     ...(c.produces.broker !== undefined ? { broker: c.produces.broker } : {}),
+                                    ...(c.produces.project !== undefined ? { project: c.produces.project } : {}),
                                 },
                             }
                             : {}),

package/dist/standing.d.ts

@@ -0,0 +1,18 @@
+import type { WorkflowStanding } from "./_proto/ankka/protocol/v1/payload_pb.ts";
+export type StandingStatus = "NotStarted" | "Running" | "Paused" | "Completed" | "Failed" | "Unknown";
+export interface Standing {
+    readonly status: StandingStatus;
+    /** The step the workflow is on, or the step a pause names or follows. */
+    readonly step?: string;
+    /** Retries so far, per step. */
+    readonly retries: Readonly<Record<string, number>>;
+    /** Why it failed, when it did. */
+    readonly failure?: string;
+}
+export declare function isTerminal(standing: Standing): boolean;
+/** The state was recorded before the platform stamped standings. */
+export declare function isUnknown(standing: Standing): boolean;
+/** @internal The standing a request carries, or `undefined` for a change from an entity or a topic. */
+export declare function standingFromProto(standing: WorkflowStanding | undefined): Standing | undefined;
+/** @internal The version whose runtimes read a workflow as a source. */
+export declare const WORKFLOW_SOURCE_PROTOCOL: readonly [number, number];

package/dist/standing.js

@@ -0,0 +1,26 @@
+// Where a workflow stood once the effect that recorded a state was applied (protocol 1.16).
+//
+// A view or a consumer whose source is a workflow is handed, with each state the workflow records,
+// its standing: running, paused, completed or failed, the step it is on or waits after, the retries
+// of each step and, when it failed, why. `Unknown` is the standing of a state recorded before the
+// platform stamped standings. A change from an entity or a topic has none.
+export function isTerminal(standing) {
+    return standing.status === "Completed" || standing.status === "Failed";
+}
+/** The state was recorded before the platform stamped standings. */
+export function isUnknown(standing) {
+    return standing.status === "Unknown";
+}
+/** @internal The standing a request carries, or `undefined` for a change from an entity or a topic. */
+export function standingFromProto(standing) {
+    if (standing === undefined)
+        return undefined;
+    return Object.freeze({
+        status: standing.status,
+        ...(standing.step ? { step: standing.step } : {}),
+        retries: Object.freeze({ ...standing.retries }),
+        ...(standing.failure ? { failure: standing.failure } : {}),
+    });
+}
+/** @internal The version whose runtimes read a workflow as a source. */
+export const WORKFLOW_SOURCE_PROTOCOL = [1, 16];

package/dist/startFrom.d.ts

@@ -24,9 +24,13 @@ export declare const START_POSITION_PROTOCOL: readonly [number, number];
 export declare function isStartFrom(value: unknown): value is StartFrom;
 /** The first protocol in which a process can declare a view's queries. */
 export declare const DECLARED_QUERY_PROTOCOL: readonly [number, number];
+export declare function olderThan(protocolVersion: string, [wantMajor, wantMinor]: readonly [number, number]): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a start position and a version. */
 export declare function olderThanStartPositions(protocolVersion: string): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a view's declared queries. */
 export declare function olderThanDeclaredQueries(protocolVersion: string): boolean;
+/** Whether a sidecar speaking `protocolVersion` would not know a watched query. */
+export declare function olderThanViewStreams(protocolVersion: string): boolean;
 /** Whether a sidecar speaking `protocolVersion` would ignore a topic's contract, broker and parallel reading. */
+export declare function olderThanWorkflowSources(protocolVersion: string): boolean;
 export declare function olderThanContracts(protocolVersion: string): boolean;

package/dist/startFrom.js

@@ -24,7 +24,7 @@ export function isStartFrom(value) {
 }
 /** The first protocol in which a process can declare a view's queries. */
 export const DECLARED_QUERY_PROTOCOL = [1, 13];
-function olderThan(protocolVersion, [wantMajor, wantMinor]) {
+export function olderThan(protocolVersion, [wantMajor, wantMinor]) {
     const [major, minor] = protocolVersion.split(".").map((part) => Number.parseInt(part, 10));
     if (!Number.isFinite(major) || !Number.isFinite(minor))
         return false;
@@ -38,7 +38,14 @@ export function olderThanStartPositions(protocolVersion) {
 export function olderThanDeclaredQueries(protocolVersion) {
     return olderThan(protocolVersion, DECLARED_QUERY_PROTOCOL);
 }
+/** Whether a sidecar speaking `protocolVersion` would not know a watched query. */
+export function olderThanViewStreams(protocolVersion) {
+    return olderThan(protocolVersion, [1, 17]);
+}
 /** Whether a sidecar speaking `protocolVersion` would ignore a topic's contract, broker and parallel reading. */
+export function olderThanWorkflowSources(protocolVersion) {
+    return olderThan(protocolVersion, [1, 16]);
+}
 export function olderThanContracts(protocolVersion) {
     return olderThan(protocolVersion, [1, 14]);
 }

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/kinds.d.ts

@@ -15,6 +15,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;
@@ -58,8 +59,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 +84,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;
@@ -104,7 +108,7 @@ export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
      * 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>>;
 }
 /**

package/dist/testkit/kinds.js

@@ -199,11 +199,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 +217,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 +268,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 +286,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 +298,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) {
@@ -328,9 +331,9 @@ export class ConsumerTestKit {
     static of(cls, client = noClient()) {
         return new ConsumerTestKit(cls, client);
     }
-    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);
         const effect = await fn(consumer);
         const outCodec = () => {
             const codec = this.#registered.outCodec;
@@ -354,9 +357,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 });

package/dist/testkit/unit.d.ts

@@ -1,15 +1,29 @@
 import { ComponentClient } from "../client.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 +32,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>>;
 }