ankka 0.10.0 → 0.12.0

package/dist/routes.d.ts

@@ -1,3 +1,4 @@
+import type { Socket } from "./socket.ts";
 import type { Shape } from "./codec.ts";
 import type { RequestContext } from "./context.ts";
 import type { Infer, Schema } from "./schema.ts";
@@ -12,15 +13,20 @@ export type CallerMatcher = {
     readonly kind: "anyInProject";
 } | {
     readonly kind: "self";
+} | {
+    readonly kind: "granted";
 };
 /**
  * The callers an endpoint can name: `Acl.allowCallers(Callers.internet, Callers.service("orders"))`. A named
- * service is in this service's own project unless `project` names another.
+ * service is in this service's own project unless `project` names another. `Callers.granted` is whoever this
+ * service's project has granted the route to — a service of another project, or a registered machine
+ * (protocol 1.15); a route that does not name it can never be granted.
  */
 export declare const Callers: Readonly<{
     internet: CallerMatcher;
     anyInProject: CallerMatcher;
     self: CallerMatcher;
+    granted: CallerMatcher;
     service(name: string, options?: {
         readonly project?: string;
     }): CallerMatcher;
@@ -74,8 +80,10 @@ export interface RouteRef<Ep = unknown, P = unknown, B = unknown, R = unknown> {
     readonly body: Shape<B> | undefined;
     readonly reply: Shape<R> | undefined;
     readonly streaming: boolean;
+    /** Answered by opening a socket (protocol 1.9); `run`'s third argument is then the `Socket`. */
+    readonly socket: boolean;
     readonly acl: Acl | undefined;
-    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string>;
+    readonly run: (self: Ep, request: RequestContext<P>, body: B) => MaybePromise<R> | AsyncIterable<string | SseEvent>;
 }
 export declare function parseTemplate(template: string): string[];
 type NoBodyRun<Ep, T extends string, PS, R> = (self: Ep, request: RequestContext<Params<T, PS>>) => MaybePromise<R>;
@@ -100,8 +108,40 @@ export declare const del: {
     <Ep, T extends string, B, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, body: Shape<B>, reply: Shape<R>, run: BodyRun<Ep, T, PS, B, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, B, R>;
     <Ep, T extends string, R, PS extends Readonly<Record<string, Schema>> = {}>(template: T, reply: Shape<R>, run: NoBodyRun<Ep, T, PS, R>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, R>;
 };
-/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
-export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string> | Promise<AsyncIterable<string>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A server-sent event under a name of its own, which an `sse` handler may yield beside text: an agent
+ * turn that stops for approval ends its stream with `sseEvent("approval", requests)`. `value` is sent as
+ * JSON. Needs protocol 1.11 of the runtime.
+ */
+export interface SseEvent {
+    readonly kind: "sse-event";
+    readonly name: string;
+    readonly value: unknown;
+}
+/**
+ * A watch as server-sent events, for an `sse` route: each row as `row` carrying the key and the row,
+ * each removal as `removed`, the marker as `caught-up`, and a watch that ended with a reason as a last
+ * event `ended` carrying it, so a page is told why.
+ */
+export declare function sseEvents<Row>(watch: AsyncIterable<{
+    readonly kind: "row";
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly kind: "removed";
+    readonly key: string;
+} | {
+    readonly kind: "caughtUp";
+}>): AsyncIterable<SseEvent>;
+export declare function sseEvent(name: string, value: unknown): SseEvent;
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
+export declare function sse<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>) => AsyncIterable<string | SseEvent> | Promise<AsyncIterable<string | SseEvent>>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, undefined, never>;
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export declare function socket<Ep, T extends string, PS extends Readonly<Record<string, Schema>> = {}>(template: T, run: (self: Ep, request: RequestContext<Params<T, PS>>, socket: Socket) => Promise<void>, options?: RouteOptions<PS>): RouteRef<Ep, Params<T, PS>, Socket, void>;
 /** The routes table type an endpoint declares. */
 export type RouteTable<Ep> = Readonly<Record<string, RouteRef<Ep, any, any, any>>>;
 export {};

package/dist/routes.js

@@ -11,12 +11,15 @@
 import { isCodec } from "./codec.js";
 /**
  * The callers an endpoint can name: `Acl.allowCallers(Callers.internet, Callers.service("orders"))`. A named
- * service is in this service's own project unless `project` names another.
+ * service is in this service's own project unless `project` names another. `Callers.granted` is whoever this
+ * service's project has granted the route to — a service of another project, or a registered machine
+ * (protocol 1.15); a route that does not name it can never be granted.
  */
 export const Callers = Object.freeze({
     internet: Object.freeze({ kind: "internet" }),
     anyInProject: Object.freeze({ kind: "anyInProject" }),
     self: Object.freeze({ kind: "self" }),
+    granted: Object.freeze({ kind: "granted" }),
     service(name, options) {
         return Object.freeze(options?.project !== undefined ? { kind: "service", name, project: options.project } : { kind: "service", name });
     },
@@ -57,7 +60,7 @@ export function parseTemplate(template) {
         throw new TypeError(`route template ${template} repeats a parameter`);
     return names;
 }
-function route(method, template, body, reply, run, options, streaming) {
+function route(method, template, body, reply, run, options, streaming, socket = false) {
     const paramNames = parseTemplate(template);
     if (typeof run !== "function")
         throw new TypeError(`route ${method} ${template}: the handler is not a function`);
@@ -68,7 +71,7 @@ function route(method, template, body, reply, run, options, streaming) {
         if (!paramNames.includes(name))
             throw new TypeError(`route ${method} ${template}: params names ${name}, which is not in the template`);
     }
-    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, acl: options?.acl, run });
+    return Object.freeze({ method, template, paramNames, paramShapes, body, reply, streaming, socket, acl: options?.acl, run });
 }
 function isShape(x) {
     return typeof x === "object" && x !== null && (typeof x.kind === "string" || isCodec(x));
@@ -96,7 +99,43 @@ export const put = withBody("PUT");
 export const patch = withBody("PATCH");
 /** A DELETE route; `delete` is a reserved word, so `del`. */
 export const del = withBody("DELETE");
-/** A server-sent-events route: the handler returns an `AsyncIterable<string>`, one frame per string. */
+/**
+ * A watch as server-sent events, for an `sse` route: each row as `row` carrying the key and the row,
+ * each removal as `removed`, the marker as `caught-up`, and a watch that ended with a reason as a last
+ * event `ended` carrying it, so a page is told why.
+ */
+export async function* sseEvents(watch) {
+    try {
+        for await (const event of watch) {
+            if (event.kind === "row")
+                yield sseEvent("row", { key: event.key, row: event.row });
+            else if (event.kind === "removed")
+                yield sseEvent("removed", { key: event.key });
+            else
+                yield sseEvent("caught-up", {});
+        }
+    }
+    catch (failure) {
+        if (failure instanceof Error && failure.name === "WatchEnded")
+            yield sseEvent("ended", { reason: failure.reason });
+        else
+            throw failure;
+    }
+}
+export function sseEvent(name, value) {
+    if (typeof name !== "string" || name === "" || /[\r\n]/.test(name))
+        throw new TypeError(`an event name must be one non-empty line, not ${JSON.stringify(name)}`);
+    return Object.freeze({ kind: "sse-event", name, value });
+}
+/** A server-sent-events route: the handler returns an `AsyncIterable<string | SseEvent>`, one frame per string, and may yield an `SseEvent` among them. */
 export function sse(template, run, options) {
     return route("GET", template, undefined, undefined, run, options, true);
 }
+/**
+ * A socket route: `socket("/{room}", async (ep: Rooms, req, socket) => { for await (const t of socket) await socket.send(t) })`.
+ * The handler runs for as long as the socket is open, with the opening request as `req` throughout.
+ * Needs protocol 1.9 of the runtime.
+ */
+export function socket(template, run, options) {
+    return route("GET", template, undefined, undefined, run, options, false, true);
+}

package/dist/server/agent.js

@@ -84,7 +84,10 @@ export async function handleTool(req, ctx) {
     if (!registered)
         return create(ToolResultSchema, { result: { case: "error", value: `no agent ${JSON.stringify(req.componentId)} is registered` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, {}, ctx.client);
+    // What the sidecar says about the tool's run: its trace, and the agent's handler as the caller of
+    // whatever the tool calls. A sidecar before 1.3 sends none.
+    const metadata = metadataFromProto(req.metadata);
+    agent._bind(req.sessionId, metadata, ctx.client.withMetadata(metadata));
     try {
         return create(ToolResultSchema, { result: { case: "ok", value: await runTool(registered, agent, req.tool, req.argumentsJson) } });
     }
@@ -95,11 +98,16 @@ export async function handleTool(req, ctx) {
 }
 export async function handleGuardrail(req, ctx) {
     const registered = ctx.registry.of("agent", req.componentId) ?? ctx.registry.of("autonomous-agent", req.componentId);
-    const guardrail = registered?.guardrails.get(req.guardrail);
+    // RESULT (1.11): what an MCP server's tool answered, checked by one of the agent's result guardrails,
+    // which are declared apart from its other guardrails.
+    const result = req.stage === GuardrailRequest_Stage.RESULT;
+    const guardrail = result ? registered?.resultGuardrails.get(req.guardrail) : registered?.guardrails.get(req.guardrail);
     if (!registered || !guardrail)
         return create(GuardrailResultSchema, { result: { case: "block", value: `no guardrail ${JSON.stringify(req.guardrail)} on ${req.componentId}` } });
     try {
-        const reason = await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
+        const reason = result
+            ? await guardrail.check(req.tool ?? "", req.text)
+            : await guardrail.check(req.stage === GuardrailRequest_Stage.OUTPUT ? "output" : "input", req.text);
         return reason === null || reason === undefined
             ? create(GuardrailResultSchema, { result: { case: "pass", value: {} } })
             : create(GuardrailResultSchema, { result: { case: "block", value: reason } });
@@ -114,7 +122,7 @@ async function handleAutonomousTool(registered, req, ctx) {
     if (!tool)
         return create(ToolResultSchema, { result: { case: "error", value: `no tool ${JSON.stringify(req.tool)} on ${registered.id}` } });
     const agent = new registered.cls();
-    agent._bind(req.sessionId, ctx.client);
+    agent._bind(req.sessionId, ctx.client.withMetadata(metadataFromProto(req.metadata)));
     try {
         let input;
         if (isCodec(tool.input))

package/dist/server/discovery.d.ts

@@ -1,5 +1,21 @@
-import type { ConnectRouter } from "@connectrpc/connect";
+import { type ConnectRouter } from "@connectrpc/connect";
 import { type Spec } from "../_proto/ankka/protocol/v1/discovery_pb.ts";
+/**
+ * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
+ * declared `latest` would read everything, and a raised version would rebuild nothing. Refused,
+ * naming what declares them, rather than served wrong.
+ */
+export declare function refusal(spec: Spec, sidecarProtocol: string): string | undefined;
 /** Every problem the sidecar has reported to this process, in order. */
 export declare const problems: string[];
 export declare function discoveryRoutes(router: ConnectRouter, spec: () => Spec, log?: (message: string) => void): void;
+/** The protocol version whose runtimes serve socket routes. */
+export declare const SOCKETS_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
+ * does not know a socket route, and would serve it as a plain GET. */
+export declare function socketRefusal(spec: Spec, runtime: string): string | undefined;
+/** The protocol version whose runtimes admit granted callers. */
+export declare const GRANTS_SINCE: readonly [number, number];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
+ * does not know `Callers.granted`, and would admit nobody by it. */
+export declare function grantsRefusal(spec: Spec, runtime: string): string | undefined;

package/dist/server/discovery.js

@@ -1,16 +1,158 @@
 // Discovery: the first conversation. The sidecar asks what we host; we answer with the Spec the
 // registry renders. `ReportError` is how the sidecar tells us why it refused to start — logged, and kept
 // so a service can expose it (the conformance reference does, at GET /conformance/problems).
+import { Code, ConnectError } from "@connectrpc/connect";
 import { create } from "@bufbuild/protobuf";
 import { Discovery } from "../_proto/ankka/protocol/v1/discovery_pb.js";
 import { EmptySchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
+import { PROTOCOL_VERSION } from "../spec.js";
+import { Kind } from "../_proto/ankka/protocol/v1/discovery_pb.js";
+import { olderThan, olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions, olderThanViewStreams, olderThanWorkflowSources } from "../startFrom.js";
+/**
+ * A sidecar older than 1.7 would ignore where a topic source starts and its version: a consumer
+ * declared `latest` would read everything, and a raised version would rebuild nothing. Refused,
+ * naming what declares them, rather than served wrong.
+ */
+export function refusal(spec, sidecarProtocol) {
+    return (workflowSourceRefusal(spec, sidecarProtocol) ??
+        startPositionRefusal(spec, sidecarProtocol) ??
+        declaredQueryRefusal(spec, sidecarProtocol) ??
+        contractRefusal(spec, sidecarProtocol) ??
+        watchedQueryRefusal(spec, sidecarProtocol) ??
+        // Last: a reason an older sidecar has too is named first, by the version it needs.
+        replicationRefusal(spec, sidecarProtocol));
+}
+/**
+ * A sidecar older than 1.19 would host a replicated entity at one installation and say nothing, and
+ * would hand a consumer given mirrored changes only the changes written here. Refused at discovery,
+ * naming the components and the version.
+ */
+function replicationRefusal(spec, sidecarProtocol) {
+    if (!olderThan(sidecarProtocol, [1, 19]))
+        return undefined;
+    const replicated = spec.components
+        .filter((c) => (c.detail.case === "eventSourced" && c.detail.value.replicated) ||
+        (c.detail.case === "consumer" && c.detail.value.mirroredChanges))
+        .map((c) => c.id);
+    if (replicated.length === 0)
+        return undefined;
+    return (`${replicated.join(", ")} declare replication, which needs protocol 1.19: ` +
+        `the sidecar speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.19 or later.`);
+}
+/**
+ * A sidecar older than 1.16 would not read a workflow as a source: a view or consumer that does would
+ * be handed nothing. Refused at discovery, naming them.
+ */
+function workflowSourceRefusal(spec, sidecarProtocol) {
+    if (!olderThanWorkflowSources(sidecarProtocol))
+        return undefined;
+    const reading = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        const sources = d.case === "view" ? [d.value.source, ...d.value.sources] : [d.value.source];
+        return sources.some((s) => s?.source.case === "component" && s.source.value.kind === Kind.WORKFLOW);
+    })
+        .map((c) => c.id);
+    if (reading.length === 0)
+        return undefined;
+    return (`${reading.join(", ")} read a workflow, which the sidecar does not know: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.16 or later.`);
+}
+/**
+ * A sidecar older than 1.14 would ignore a topic's contract, broker and parallel reading and a
+ * publication's contract and broker: a contract would go unchecked, a topic on another broker would be
+ * read from the installation's. Refused at discovery, naming the components, rather than served wrong.
+ */
+function contractRefusal(spec, sidecarProtocol) {
+    if (!olderThanContracts(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        const src = d.value.source;
+        const onSource = src !== undefined && (src.contract !== undefined || src.broker !== undefined || src.parallel === true);
+        const onPublication = d.case === "consumer" && d.value.produces !== undefined && (d.value.produces.contract !== undefined || d.value.produces.broker !== undefined);
+        return onSource || onPublication;
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare a topic's contract, broker or parallel reading, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.14 or later.`);
+}
+/**
+ * A sidecar older than 1.17 would not know that a view's query may be watched, and a watch of it would
+ * be refused at its first asking. Refused at discovery, naming the views.
+ */
+function watchedQueryRefusal(spec, sidecarProtocol) {
+    if (!olderThanViewStreams(sidecarProtocol))
+        return undefined;
+    const watching = spec.components
+        .filter((c) => c.detail.case === "view" && c.detail.value.declaredQueries.some((q) => q.watched))
+        .map((c) => c.id);
+    if (watching.length === 0)
+        return undefined;
+    return (`${watching.join(", ")} declare a watched query, which the sidecar does not know: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.17 or later.`);
+}
+/**
+ * A sidecar older than 1.13 would ignore a view's declared queries, would read a keyed view as having
+ * no source, and would refuse a version on a view that reads an entity as applying only to a topic.
+ * Refused at discovery, naming the views, rather than found later or misreported.
+ */
+function declaredQueryRefusal(spec, sidecarProtocol) {
+    if (!olderThanDeclaredQueries(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        if (c.detail.case !== "view")
+            return false;
+        const v = c.detail.value;
+        // A declared query, a keyed view, or a version on a view that reads an entity.
+        return v.declaredQueries.length > 0 || v.sources.length > 0 || (v.version !== undefined && v.source?.source.case === "component");
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare queries, several sources, or a version on a view that reads an entity, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.13 or later.`);
+}
+function startPositionRefusal(spec, sidecarProtocol) {
+    if (!olderThanStartPositions(sidecarProtocol))
+        return undefined;
+    const declaring = spec.components
+        .filter((c) => {
+        const d = c.detail;
+        if (d.case !== "view" && d.case !== "consumer")
+            return false;
+        return d.value.source?.startFrom !== undefined || d.value.version !== undefined;
+    })
+        .map((c) => c.id);
+    if (declaring.length === 0)
+        return undefined;
+    return (`${declaring.join(", ")} declare where a topic source starts or its version, which the sidecar ignores: ` +
+        `it speaks protocol ${sidecarProtocol}, and this SDK ${PROTOCOL_VERSION}. Run a sidecar speaking 1.7 or later.`);
+}
 /** Every problem the sidecar has reported to this process, in order. */
 export const problems = [];
 export function discoveryRoutes(router, spec, log = console.error) {
     router.service(Discovery, {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
-            return spec();
+            const answer = spec();
+            const why = refusal(answer, info.protocolVersion) ??
+                socketRefusal(answer, info.protocolVersion) ??
+                grantsRefusal(answer, info.protocolVersion);
+            if (why !== undefined) {
+                log(`ankka: ${why}`);
+                problems.push(why);
+                throw new ConnectError(why, Code.FailedPrecondition);
+            }
+            return answer;
         },
         async reportError(problem) {
             log(`ankka: the sidecar refused to start: ${problem.message}`);
@@ -19,3 +161,42 @@ export function discoveryRoutes(router, spec, log = console.error) {
         },
     });
 }
+/** The protocol version whose runtimes serve socket routes. */
+export const SOCKETS_SINCE = [1, 9];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.9
+ * does not know a socket route, and would serve it as a plain GET. */
+export function socketRefusal(spec, runtime) {
+    const routes = spec.endpoints.flatMap((e) => e.routes.filter((r) => r.socket).map((r) => `${e.id}.${r.id}`));
+    if (routes.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > SOCKETS_SINCE[0] || (speaks[0] === SOCKETS_SINCE[0] && speaks[1] >= SOCKETS_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; a socket route needs 1.9 (${routes.join(", ")})`;
+}
+/** The protocol version whose runtimes admit granted callers. */
+export const GRANTS_SINCE = [1, 15];
+/** Why `spec` cannot be declared to a runtime speaking `runtime`, or undefined. A runtime before 1.15
+ * does not know `Callers.granted`, and would admit nobody by it. */
+export function grantsRefusal(spec, runtime) {
+    const grants = (callers) => callers.some((m) => m.kind.case === "granted");
+    const endpoints = spec.endpoints
+        .filter((e) => grants(e.allowCallers) || e.routes.some((r) => grants(r.allowCallers)))
+        .map((e) => e.id);
+    // Another project's topic is 1.15's too: an older runtime would read it as this project's.
+    for (const c of spec.components) {
+        const d = c.detail;
+        const sources = d.case === "view" ? [d.value.source, ...d.value.sources] : d.case === "consumer" ? [d.value.source] : [];
+        const publishes = d.case === "consumer" && d.value.produces?.project !== undefined;
+        if (sources.some((s) => s?.project !== undefined) || publishes)
+            endpoints.push(c.id);
+    }
+    if (endpoints.length === 0)
+        return undefined;
+    const [major, minor] = runtime.split(".").map((part) => Number.parseInt(part, 10));
+    const speaks = Number.isFinite(major) && Number.isFinite(minor) ? [major, minor] : [0, 0];
+    if (speaks[0] > GRANTS_SINCE[0] || (speaks[0] === GRANTS_SINCE[0] && speaks[1] >= GRANTS_SINCE[1]))
+        return undefined;
+    return `this runtime speaks protocol ${runtime || "unknown"}; granted callers and another project's topics need 1.15 (${endpoints.join(", ")})`;
+}

package/dist/server/eventSourced.d.ts

@@ -1,10 +1,13 @@
 import type { ConnectRouter } from "@connectrpc/connect";
 import { type MessageInitShape } from "@bufbuild/protobuf";
-import { type EventSourcedIn, type EventSourcedOut } from "../_proto/ankka/protocol/v1/event_sourced_pb.ts";
+import { type ReplicationChangeSchema, type EventSourcedIn, type EventSourcedOut } from "../_proto/ankka/protocol/v1/event_sourced_pb.ts";
 import type { RetentionSchema } from "../_proto/ankka/protocol/v1/payload_pb.ts";
 import { type Retention } from "../effects/common.ts";
+import type { ReplicationChange } from "../effects/eventSourced.ts";
 import type { ServerContext } from "./server.ts";
 type RetentionInit = MessageInitShape<typeof RetentionSchema>;
+/** A replicated entity's handover or change to its replication set, as the reply carries it (1.19). */
+export declare function replicationToProto(change: ReplicationChange | undefined): MessageInitShape<typeof ReplicationChangeSchema> | undefined;
 /** Retention as the protocol carries it; `undefined` when the effect asked for none. */
 export declare function retentionToProto(retention: Retention | null): RetentionInit | undefined;
 export declare function eventSourcedRoutes(router: ConnectRouter, ctx: ServerContext): void;

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

@@ -1,9 +1,10 @@
 import type { ConnectRouter } from "@connectrpc/connect";
-import { type HttpRequest, type HttpReply, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
+import { type HttpRequest, type HttpReply, type SocketIn, type SocketOut, type StreamFrame } from "../_proto/ankka/protocol/v1/endpoint_pb.ts";
 import type { ServerContext } from "./server.ts";
 export interface HttpDispatcher {
     handle(req: HttpRequest): Promise<HttpReply>;
     handleStream(req: HttpRequest): AsyncIterable<StreamFrame>;
+    handleSocket(requests: AsyncIterable<SocketIn>): AsyncIterable<SocketOut>;
 }
 /** The behaviour behind `Http.Handle` and `Http.HandleStream`, over the registry's endpoints. */
 export declare function createHttpDispatcher(ctx: ServerContext): HttpDispatcher;