ankka 0.11.0 → 0.12.0

package/dist/effects/common.js

@@ -10,6 +10,10 @@ export const ErrorCode = Object.freeze({
     Conflict: "CONFLICT",
     Timeout: "TIMEOUT",
     Unavailable: "UNAVAILABLE",
+    /** A workflow a caller waited for failed or was deleted (protocol 1.18); the step and the reason are in `details`. */
+    WorkflowFailed: "WORKFLOW_FAILED",
+    /** A replicated entity's copy here cannot answer (1.19): its home is unreachable, or the read is outside the replication set. */
+    NotHome: "NOT_HOME",
 });
 const HTTP_STATUS = Object.freeze({
     INTERNAL: 500,
@@ -20,6 +24,8 @@ const HTTP_STATUS = Object.freeze({
     CONFLICT: 409,
     TIMEOUT: 504,
     UNAVAILABLE: 503,
+    WORKFLOW_FAILED: 424,
+    NOT_HOME: 421,
 });
 export function httpStatusOf(code) {
     return HTTP_STATUS[code];
@@ -27,13 +33,15 @@ export function httpStatusOf(code) {
 /** Thrown by the component client when the callee refused. */
 export class CommandError extends Error {
     code;
+    details;
     constructor(detail) {
         super(detail.message);
         this.name = "CommandError";
         this.code = detail.code;
+        this.details = detail.details ?? {};
     }
     get detail() {
-        return { message: this.message, code: this.code };
+        return { message: this.message, code: this.code, details: this.details };
     }
 }
 export const Outcome = Object.freeze({

package/dist/effects/eventSourced.d.ts

@@ -1,11 +1,21 @@
 import type { Duration } from "../time.ts";
 import { done, type Done } from "../schema.ts";
 import { ErrorCode, Outcome, Retention, type EffectLike, type Metadata, type ReadOnlyLike } from "./common.ts";
+/** What a replicated entity's handler asks of its home beside the events it persists (1.19). */
+export type ReplicationChange = {
+    readonly kind: "hand-over";
+    readonly to: string;
+} | {
+    readonly kind: "set";
+    readonly add: readonly string[];
+    readonly remove: readonly string[];
+};
 export interface PersistEffect<S, E, R> extends EffectLike<R> {
     readonly kind: "persist";
     readonly events: readonly E[];
     readonly retention: Retention | null;
     readonly outcome: Outcome<S, R>;
+    readonly replication?: ReplicationChange;
 }
 export interface ReadOnlyEffect<S, E, R> extends ReadOnlyLike<R> {
     readonly kind: "read-only";
@@ -18,11 +28,20 @@ export type EventSourcedEffect<S, E, R> = PersistEffect<S, E, R> | ReadOnlyEffec
 /** `effects.persist(e)` returns one of these; finish it with `thenReply`, `thenReplyState` or `thenNoReply`. */
 export declare class PersistBuilder<S, E> {
     #private;
-    constructor(events: readonly E[], retention?: Retention | null);
+    constructor(events: readonly E[], retention?: Retention | null, replication?: ReplicationChange);
     /** Delete the entity once these events are persisted. */
     deleteEntity(): PersistBuilder<S, E>;
     /** Expire the entity a while after these events are persisted. */
     expireAfter(after: Duration): PersistBuilder<S, E>;
+    /**
+     * Persist these events, then hand a replicated entity's home to `installation`, which must be in its
+     * replication set. Recorded once the new home holds everything before it.
+     */
+    handOverTo(installation: string): PersistBuilder<S, E>;
+    /** Persist these events, then add `installation` to a replicated entity's replication set. */
+    replicateTo(installation: string): PersistBuilder<S, E>;
+    /** Persist these events, then take `installation` out of a replicated entity's replication set; it keeps its copy. */
+    stopReplicatingTo(installation: string): PersistBuilder<S, E>;
     /** Reply with a value computed from the state *after* the events. */
     thenReply<R>(compute: (state: S) => R, metadata?: Metadata): PersistEffect<S, E, R>;
     /** Reply with the state after the events. */
@@ -46,5 +65,11 @@ export declare class EventSourcedEffects<S, E> {
     deleteEntity(): PersistBuilder<S, E>;
     /** Expire the entity after a while, persisting nothing more. */
     expireAfter(after: Duration): PersistBuilder<S, E>;
+    /** Hand a replicated entity's home to `installation`, with no event of its own. */
+    handOverTo(installation: string): PersistBuilder<S, E>;
+    /** Add `installation` to a replicated entity's replication set, with no event of its own. */
+    replicateTo(installation: string): PersistBuilder<S, E>;
+    /** Take `installation` out of a replicated entity's replication set; it keeps its copy. */
+    stopReplicatingTo(installation: string): PersistBuilder<S, E>;
 }
 export { done, type Done };

package/dist/effects/eventSourced.js

@@ -1,27 +1,67 @@
 // The effects an event sourced entity's handlers return: persist these events and then reply from the
 // state after them, or answer without persisting. Inert values. `ReadOnlyEffect` is a distinct type
 // with `kind: "read-only"`, which is what lets `query` refuse a persisting handler at compile time.
+var _a;
 import { done } from "../schema.js";
 import { ErrorCode, Outcome, Retention } from "./common.js";
 /** `effects.persist(e)` returns one of these; finish it with `thenReply`, `thenReplyState` or `thenNoReply`. */
 export class PersistBuilder {
     #events;
     #retention;
-    constructor(events, retention = null) {
+    #replication;
+    constructor(events, retention = null, replication) {
         this.#events = events;
         this.#retention = retention;
+        this.#replication = replication;
     }
     /** Delete the entity once these events are persisted. */
     deleteEntity() {
-        return new PersistBuilder(this.#events, Retention.deleteNow);
+        return new _a(this.#events, Retention.deleteNow, this.#replication);
     }
     /** Expire the entity a while after these events are persisted. */
     expireAfter(after) {
-        return new PersistBuilder(this.#events, Retention.expireAfter(after));
+        return new _a(this.#events, Retention.expireAfter(after), this.#replication);
+    }
+    /**
+     * Persist these events, then hand a replicated entity's home to `installation`, which must be in its
+     * replication set. Recorded once the new home holds everything before it.
+     */
+    handOverTo(installation) {
+        if (this.#replication)
+            throw new Error(`a command asks for one handover or one change to the replication set; it asked for ${JSON.stringify(this.#replication)}`);
+        return new _a(this.#events, this.#retention, Object.freeze({ kind: "hand-over", to: installation }));
+    }
+    /** Persist these events, then add `installation` to a replicated entity's replication set. */
+    replicateTo(installation) {
+        return this.#setChange([installation], []);
+    }
+    /** Persist these events, then take `installation` out of a replicated entity's replication set; it keeps its copy. */
+    stopReplicatingTo(installation) {
+        return this.#setChange([], [installation]);
+    }
+    #setChange(add, remove) {
+        const current = this.#replication;
+        if (current?.kind === "hand-over")
+            throw new Error(`a command asks for one handover or one change to the replication set; it asked for ${JSON.stringify(current)}`);
+        const adding = [...new Set([...(current?.add ?? []), ...add])].sort();
+        const removing = [...new Set([...(current?.remove ?? []), ...remove])].sort();
+        const both = adding.filter((name) => removing.includes(name));
+        if (both.length > 0)
+            throw new Error(`a command both adds and removes ${both.join(", ")} in the replication set`);
+        return new _a(this.#events, this.#retention, Object.freeze({ kind: "set", add: Object.freeze(adding), remove: Object.freeze(removing) }));
+    }
+    #effect(outcome) {
+        return Object.freeze({
+            kind: "persist",
+            events: this.#events,
+            retention: this.#retention,
+            outcome,
+            ...(this.#replication ? { replication: this.#replication } : {}),
+        });
     }
     /** Reply with a value computed from the state *after* the events. */
     thenReply(compute, metadata) {
-        return Object.freeze({ kind: "persist", events: this.#events, retention: this.#retention, outcome: Outcome.reply(compute, metadata) });
+        return this.#effect(Outcome.reply(compute, metadata));
     }
     /** Reply with the state after the events. */
     thenReplyState() {
@@ -29,9 +69,10 @@ export class PersistBuilder {
     }
     /** Persist and answer nothing. */
     thenNoReply() {
-        return Object.freeze({ kind: "persist", events: this.#events, retention: this.#retention, outcome: Outcome.noReply() });
+        return this.#effect(Outcome.noReply());
     }
 }
+_a = PersistBuilder;
 /** The factory a handler reaches as `this.effects`. */
 export class EventSourcedEffects {
     /** Persist one or more events. */
@@ -62,5 +103,17 @@ export class EventSourcedEffects {
     expireAfter(after) {
         return new PersistBuilder(Object.freeze([]), Retention.expireAfter(after));
     }
+    /** Hand a replicated entity's home to `installation`, with no event of its own. */
+    handOverTo(installation) {
+        return new PersistBuilder(Object.freeze([])).handOverTo(installation);
+    }
+    /** Add `installation` to a replicated entity's replication set, with no event of its own. */
+    replicateTo(installation) {
+        return new PersistBuilder(Object.freeze([])).replicateTo(installation);
+    }
+    /** Take `installation` out of a replicated entity's replication set; it keeps its copy. */
+    stopReplicatingTo(installation) {
+        return new PersistBuilder(Object.freeze([])).stopReplicatingTo(installation);
+    }
 }
 export { done };

package/dist/eventSourcedEntity.d.ts

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

package/dist/graph.d.ts

@@ -3,6 +3,7 @@ import { type Codec, type Shape } from "./codec.ts";
 import type { EffectLike, Metadata } from "./effects/common.ts";
 import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
 import { type Services } from "./services.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** The contract's name: the manifest and the `ce-type` of every delta. */
 export declare const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
@@ -136,6 +137,8 @@ export declare abstract class GraphConsumer<M> {
     /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata(): Metadata;
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     /** The change's sequence number, which is the version of every element that states none. */
     get sequenceNumber(): bigint | undefined;
     get client(): ComponentClient;
@@ -153,7 +156,7 @@ export declare abstract class GraphConsumer<M> {
     /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
     onDelete(): MaybePromise<GraphEffect>;
     /** @internal */
-    _bind(metadata: Metadata, client: ComponentClient): void;
+    _bind(metadata: Metadata, client: ComponentClient, standing?: Standing): void;
 }
 export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = GraphConsumer<M>> {
     new (): C;
@@ -167,5 +170,10 @@ export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = Gr
     readonly message: Shape<M>;
     /** The delta topic. It must be compacted to hold the graph; the pipeline that reads it creates it so. */
     readonly producesTo: string;
+    /**
+     * Given a replicated entity's changes written at other installations too (1.19); otherwise each delta
+     * is published once, from the installation that wrote the change.
+     */
+    readonly mirroredChanges?: boolean;
 }
 export {};

package/dist/graph.js

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

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { EncodingError, DecodingError, renderDouble } from "./json.ts";
 export { Instant, Duration, LocalDate, LocalDateTime } from "./time.ts";
 export { ErrorCode, CommandError, Outcome, Retention, httpStatusOf, type ErrorDetail, type Metadata, type EffectLike, type ReadOnlyLike } from "./effects/common.ts";
 export { command, query, stream, step, action, tool, guardrail, type HandlerRef, type ToolRef, type GuardrailRef, type GuardrailStage, type HandlerTable } from "./handlers.ts";
-export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect } from "./effects/eventSourced.ts";
+export { PersistBuilder, EventSourcedEffects, type PersistEffect, type ReadOnlyEffect, type EventSourcedEffect, type ReplicationChange } from "./effects/eventSourced.ts";
 export { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
 export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnlyEffect, type KeyValueEffect } from "./effects/keyValue.ts";
 export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
@@ -26,14 +26,15 @@ export { mcpServer, resultGuardrail, toolName, type McpServerOptions, type McpSe
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, type Accepted, type AgentState, type Attachment, type AutonomousAgentClass, type AutonomousSettings, type Notification, type Rejected, type TaskAcceptance, type TaskRule, type TaskSnapshot, type TaskType, } from "./autonomous.ts";
 export { Endpoint, type EndpointClass } from "./endpoint.ts";
 export { type Socket, SocketClosed } from "./socket.ts";
-export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
-export { type CommandContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
+export { Acl, Callers, type CallerMatcher, type CallersAcl, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, type SseEvent, socket, type RouteRef, type RouteOptions, type RouteTable, type Params, type ParamNames, type HttpMethod } from "./routes.ts";
+export { type CommandContext, type EventContext, type RequestContext, type Principal, type Caller, Query, Headers } from "./context.ts";
+export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE, type AwaitPart, type WatchEvent, type WatchOptions, type Overflow, type TimerTarget, type TimedActionTarget, type ComponentRef } from "./client.ts";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, type ServiceResponse, type ServiceRequest, type ServiceHeaders, } from "./services.ts";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, type ServiceOptions, type RegisteredComponent, type RegisteredEndpoint, type Source, type RegisteredEventSourced, type RegisteredKeyValue, type RegisteredWorkflow, type RegisteredView, type RegisteredKeyedView, type RegisteredKeyedSource, type RegisteredConsumer, type RegisteredTimedAction, type RegisteredAgent, } from "./service.ts";
 export { Server, type ServerOptions } from "./server/server.ts";
 export { problems as sidecarProblems } from "./server/discovery.ts";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.ts";
 export { StartFrom } from "./startFrom.ts";
+export { isTerminal, isUnknown, type Standing, type StandingStatus } from "./standing.ts";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, type Materialised, type MaterialisedKeyValue, type MaterialisedWorkflowCommand, type MaterialisedStep, } from "./materialise.ts";
 export type { ComponentKind } from "./kinds.ts";

package/dist/index.js

@@ -37,13 +37,14 @@ export { mcpServer, resultGuardrail, toolName } from "./mcp.js";
 export { AutonomousAgent, AutonomousAgentCalls, TaskCalls, Tasks, accepted, rejected, taskAcceptance, taskRule, taskType, } from "./autonomous.js";
 export { Endpoint } from "./endpoint.js";
 export { SocketClosed } from "./socket.js";
-export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, socket } from "./routes.js";
+export { Acl, Callers, HttpProblem, get, post, put, patch, del, sse, sseEvent, sseEvents, socket } from "./routes.js";
 export { Query, Headers } from "./context.js";
-export { ComponentClient, Calls, TypedCalls, Invocation, Views, Timers, Secrets, InMemorySecrets, noSecrets } from "./client.js";
+export { ComponentClient, Calls, TypedCalls, Invocation, AwaitingInvocation, AWAIT_SINCE, awaitPartJson, Views, Timers, Secrets, InMemorySecrets, noSecrets, WatchEnded, VIEW_STREAMS_SINCE } from "./client.js";
 export { Services, ServiceClient, ScriptedServices, noServices, ServiceError, ServiceUnresolvable, ServiceIdentityMismatch, ServiceUnanswered, ServiceCallFailed, } from "./services.js";
 export { Ankka, ServiceBuilder, Registry, RegistrationError, } from "./service.js";
 export { Server } from "./server/server.js";
 export { problems as sidecarProblems } from "./server/discovery.js";
 export { PROTOCOL_VERSION, SDK_NAME } from "./spec.js";
 export { StartFrom } from "./startFrom.js";
+export { isTerminal, isUnknown } from "./standing.js";
 export { materialiseEventSourced, materialiseKeyValue, materialiseWorkflowCommand, materialiseStep, } from "./materialise.js";

package/dist/keyedView.d.ts

@@ -3,6 +3,7 @@ import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient, ComponentRef } from "./client.ts";
 import { KeyedViewEffects, type KeyedViewEffect } from "./effects/keyed.ts";
 import type { DeclaredQuery } from "./view.ts";
+import type { Standing } from "./standing.ts";
 type MaybePromise<T> = T | Promise<T>;
 /** A keyed view's own rows, for the length of one change. It reaches no other view. */
 export interface ViewRows<Row> {
@@ -32,13 +33,15 @@ export declare abstract class KeyedView<Row> {
     get metadata(): Metadata;
     /** The id of the entity the change came from. */
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     /** This view's own rows, by key or by one of its declared queries. */
     get rows(): ViewRows<Row>;
     get client(): ComponentClient;
     /** @internal */
     get _kind(): "view";
     /** @internal */
-    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>): void;
+    _bind(metadata: Metadata, client: ComponentClient | undefined, rows: ViewRows<Row>, standing?: Standing): void;
 }
 export interface KeyedViewClass<Row = unknown, C extends KeyedView<Row> = KeyedView<Row>> {
     new (): C;

package/dist/keyedView.js

@@ -26,6 +26,7 @@ export function on(source, events, onChange, options = {}) {
 export class KeyedView {
     effects = new KeyedViewEffects();
     #metadata = {};
+    #standing = undefined;
     #client;
     #rows;
     /** The change's metadata: `ce-subject` is the source entity's id, `ankka.sequence` its sequence number. */
@@ -36,6 +37,10 @@ export class KeyedView {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     /** This view's own rows, by key or by one of its declared queries. */
     get rows() {
         if (!this.#rows)
@@ -52,8 +57,9 @@ export class KeyedView {
         return "view";
     }
     /** @internal */
-    _bind(metadata, client, rows) {
+    _bind(metadata, client, rows, standing) {
         this.#metadata = metadata;
+        this.#standing = standing;
         this.#client = client;
         this.#rows = rows;
     }

package/dist/kinds.js

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

package/dist/routes.d.ts

@@ -13,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;
@@ -113,6 +118,21 @@ export interface SseEvent {
     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>;

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 });
     },
@@ -96,6 +99,29 @@ 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 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)}`);

package/dist/server/discovery.d.ts

@@ -14,3 +14,8 @@ 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

@@ -6,14 +6,59 @@ 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 { olderThanContracts, olderThanDeclaredQueries, olderThanStartPositions } from "../startFrom.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 startPositionRefusal(spec, sidecarProtocol) ?? declaredQueryRefusal(spec, sidecarProtocol) ?? contractRefusal(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
@@ -39,6 +84,21 @@ function contractRefusal(spec, sidecarProtocol) {
     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.
@@ -84,7 +144,9 @@ export function discoveryRoutes(router, spec, log = console.error) {
         async discover(info) {
             log(`ankka: discovery from sidecar (protocol ${info.protocolVersion}, runtime ${info.runtimeVersion})`);
             const answer = spec();
-            const why = refusal(answer, info.protocolVersion) ?? socketRefusal(answer, info.protocolVersion);
+            const why = refusal(answer, info.protocolVersion) ??
+                socketRefusal(answer, info.protocolVersion) ??
+                grantsRefusal(answer, info.protocolVersion);
             if (why !== undefined) {
                 log(`ankka: ${why}`);
                 problems.push(why);
@@ -113,3 +175,28 @@ export function socketRefusal(spec, runtime) {
         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;