ankka 0.10.0 → 0.12.0

package/dist/services.js

@@ -0,0 +1,259 @@
+// Other services, called as this one. The runtime beside this process makes the call: it finds the
+// service, presents this service's certificate and checks that what answered is the service asked
+// for. This process never holds a key. Offered to endpoints, workflow steps, consumers, timed actions
+// and agents; an entity and a view have no `services` at all.
+import { Code, ConnectError } from "@connectrpc/connect";
+import { ServiceFailure_Reason } from "./_proto/ankka/protocol/v1/client_pb.js";
+import { channelOf } from "./client.js";
+import { codecFor } from "./codec.js";
+import { CommandError } from "./effects/common.js";
+import { errorCodeFromProto } from "./kinds.js";
+import { metadataToProto } from "./context.js";
+import { PROTOCOL_VERSION } from "./spec.js";
+/** The protocol that added calls to other services. */
+export const SERVICES_SINCE = "1.8";
+/** The largest body, either way, a call through the sidecar carries: under gRPC's 4 MiB. */
+export const MAX_BODY_BYTES = 4_000_000;
+/** A call to another service that did not end in an answer a typed helper accepts. */
+export class ServiceError extends Error {
+    service;
+    constructor(service, message) {
+        super(message);
+        this.name = "ServiceError";
+        this.service = service;
+    }
+}
+/** No such service was found; nothing was sent. `reason` says what was tried. */
+export class ServiceUnresolvable extends ServiceError {
+    reason;
+    constructor(service, reason) {
+        super(service, `cannot reach ${service}: ${reason}`);
+        this.name = "ServiceUnresolvable";
+        this.reason = reason;
+    }
+}
+/** What answered for the name is not the service asked for; nothing was sent. */
+export class ServiceIdentityMismatch extends ServiceError {
+    detail;
+    constructor(service, detail) {
+        super(service, `the service reached as ${service} is not it: ${detail}`);
+        this.name = "ServiceIdentityMismatch";
+        this.detail = detail;
+    }
+}
+/**
+ * No answer came: the connection was refused or broke, or the service's timeout passed. The service
+ * may have received the request; one that may change something was sent at most once.
+ */
+export class ServiceUnanswered extends ServiceError {
+    reason;
+    constructor(service, reason) {
+        super(service, `${service} did not answer: ${reason}`);
+        this.name = "ServiceUnanswered";
+        this.reason = reason;
+    }
+}
+/** The service answered with a status outside 2xx, to a typed helper. `request` returns every answer. */
+export class ServiceCallFailed extends ServiceError {
+    status;
+    body;
+    constructor(service, status, body) {
+        super(service, `${service} answered ${status}: ${body}`);
+        this.name = "ServiceCallFailed";
+        this.status = status;
+        this.body = body;
+    }
+}
+const decoder = new TextDecoder();
+function response(status, contentType, body, headers) {
+    return { status, contentType, body, headers, get text() { return decoder.decode(body); } };
+}
+/** Calls one service. `target` is the service as it was named: `name` or `project/name`. */
+export class ServiceClient {
+    target;
+    #send;
+    #service;
+    #project;
+    /** @internal */
+    constructor(send, service, project) {
+        this.#send = send;
+        this.#service = service;
+        this.#project = project;
+        this.target = project ? `${project}/${service}` : service;
+    }
+    /** One request, answered whatever its status. Throws only when no answer came. */
+    async request(method, path, options = {}) {
+        if (options.body && options.body.length > MAX_BODY_BYTES) {
+            throw new CommandError({
+                message: `a call's body is at most ${MAX_BODY_BYTES} bytes through the sidecar; this one is ${options.body.length}`,
+                code: "BAD_REQUEST",
+            });
+        }
+        return this.#send({
+            service: this.#service,
+            project: this.#project,
+            method,
+            path,
+            headers: options.headers ?? [],
+            contentType: options.contentType,
+            body: options.body,
+        }, this.target);
+    }
+    /** A JSON answer, decoded as `returns`; a status outside 2xx is a `ServiceCallFailed`. */
+    async get(path, returns, options = {}) {
+        return codecFor(returns).decode(this.#succeeded(await this.request("GET", path, options)).body);
+    }
+    /** A text answer: what an endpoint returning a string sends. */
+    async getText(path, options = {}) {
+        return this.#succeeded(await this.request("GET", path, options)).text;
+    }
+    async post(path, body, shapes, options = {}) {
+        return this.#withBody("POST", path, body, shapes, options);
+    }
+    async put(path, body, shapes, options = {}) {
+        return this.#withBody("PUT", path, body, shapes, options);
+    }
+    /** For a route answering nothing: succeeds on any 2xx. */
+    async delete(path, options = {}) {
+        this.#succeeded(await this.request("DELETE", path, options));
+    }
+    async #withBody(method, path, body, shapes, options) {
+        const codec = codecFor(shapes.body);
+        const answer = await this.request(method, path, { body: codec.encode(body), contentType: codec.contentType, headers: options.headers });
+        return codecFor(shapes.returns).decode(this.#succeeded(answer).body);
+    }
+    #succeeded(answer) {
+        if (Math.floor(answer.status / 100) !== 2)
+            throw new ServiceCallFailed(this.target, answer.status, answer.text);
+        return answer;
+    }
+}
+/**
+ * How a component obtains clients for other services: `this.services.service("orders")`, or
+ * `this.services.service("billing", "invoices")` for a service in another project — whether it admits
+ * this one is its own ACL's decision. The call carries the metadata of the handler that is running, so
+ * the runtime makes it as that handler: counted from it, and in its trace.
+ */
+export class Services {
+    #client;
+    /** Calls through `client`'s sidecar, as the handler `client` is scoped to; with none, every call throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    service(first, second) {
+        const send = (request, target) => this._send(request, target);
+        return second === undefined ? new ServiceClient(send, first, undefined) : new ServiceClient(send, second, first);
+    }
+    /** @internal */
+    async _send(request, target) {
+        const channel = this.#client ? channelOf(this.#client) : undefined;
+        if (!channel)
+            throw new Error("these services are not connected to a runtime; a unit test passes a ScriptedServices");
+        const reply = await channel
+            .stub()
+            .request({
+            service: request.service,
+            project: request.project,
+            method: request.method,
+            path: request.path,
+            headers: request.headers.map(([name, value]) => ({ name, value })),
+            contentType: request.contentType,
+            body: request.body,
+            metadata: metadataToProto(channel.metadata),
+        })
+            .catch(tooOld);
+        return answerOf(target, reply);
+    }
+}
+function tooOld(failure) {
+    if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+        throw new CommandError({
+            message: `the runtime beside this process cannot call another service, which needs protocol ${SERVICES_SINCE} (this SDK speaks ${PROTOCOL_VERSION}): ${failure.rawMessage}`,
+            code: "INTERNAL",
+        });
+    }
+    throw failure;
+}
+function answerOf(target, reply) {
+    switch (reply.result.case) {
+        case "response": {
+            const r = reply.result.value;
+            return response(r.status, r.contentType, r.body, r.headers.map((h) => [h.name, h.value]));
+        }
+        case "failure": {
+            const { reason, detail } = reply.result.value;
+            if (reason === ServiceFailure_Reason.UNRESOLVABLE)
+                throw new ServiceUnresolvable(target, detail);
+            if (reason === ServiceFailure_Reason.IDENTITY_MISMATCH)
+                throw new ServiceIdentityMismatch(target, detail);
+            throw new ServiceUnanswered(target, detail);
+        }
+        case "error":
+            throw new CommandError({ message: reply.result.value.message, code: errorCodeFromProto(reply.result.value.code) });
+        default:
+            throw new CommandError({ message: `the runtime answered a call to ${target} with nothing`, code: "INTERNAL" });
+    }
+}
+/**
+ * Other services, for a unit test: each answers as the test scripted it, and every request is
+ * recorded. A call to a service nothing is scripted for fails the test, naming the service: a test
+ * whose call quietly got a default answer is no longer testing what it says.
+ */
+export class ScriptedServices extends Services {
+    requests = [];
+    #scripts = new Map();
+    constructor() {
+        super(undefined);
+    }
+    /** `name` answers with what `handler` returns; in this service's own project unless one is given. */
+    answer(name, handler, project) {
+        this.#scripts.set(keyOf(project, name), handler);
+        return this;
+    }
+    unresolvable(name, project) {
+        this.#scripts.set(keyOf(project, name), new ServiceUnresolvable(keyOf(project, name), "scripted as unresolvable"));
+        return this;
+    }
+    unanswered(name, project) {
+        this.#scripts.set(keyOf(project, name), new ServiceUnanswered(keyOf(project, name), "scripted as unanswered"));
+        return this;
+    }
+    mismatch(name, project) {
+        this.#scripts.set(keyOf(project, name), new ServiceIdentityMismatch(keyOf(project, name), "scripted as another service"));
+        return this;
+    }
+    /** An answer of `body` as `text/plain`, for a script. */
+    static text(body, status = 200) {
+        return response(status, "text/plain", new TextEncoder().encode(body), []);
+    }
+    /** An answer of `body` as `application/json`, for a script. */
+    static json(body, status = 200) {
+        return response(status, "application/json", new TextEncoder().encode(body), []);
+    }
+    /** @internal */
+    async _send(request, target) {
+        this.requests.push(request);
+        const script = this.#scripts.get(keyOf(request.project, request.service));
+        if (script === undefined) {
+            const project = request.project ? `, "${request.project}"` : "";
+            throw new Error(`the test called the service '${target}', and nothing is scripted for it: script it with answer("${request.service}", (request) => ScriptedServices.text(...)${project})`);
+        }
+        if (script instanceof ServiceError)
+            throw script;
+        return script(request);
+    }
+}
+function keyOf(project, name) {
+    return project ? `${project}/${name}` : name;
+}
+/** Services for a unit test whose every call throws: the unit kit's default, beside `noClient()`. */
+export function noServices() {
+    return new Services(undefined);
+}
+/**
+ * @internal Other services, reached through `client`'s sidecar as the handler it is scoped to. Not a
+ * member of the client, which an entity holds too: only the kinds that may call one call this.
+ */
+export function servicesFor(client) {
+    return new Services(client);
+}

package/dist/socket.d.ts

@@ -0,0 +1,15 @@
+/** Thrown by `Socket.send` once the socket is closed. A handler that lets it escape has ended as a
+ * handler ends when its client goes: it is not a failure. */
+export declare class SocketClosed extends Error {
+    constructor(message?: string);
+}
+/** A socket route handler's hold on its socket: `for await (const text of socket)` reads frames until
+ * it is closed, and `await socket.send(text)` writes one. */
+export interface Socket extends AsyncIterable<string> {
+    /** The next frame, or `undefined` once the socket is closed. */
+    receive(): Promise<string | undefined>;
+    /** Sends a frame; rejects with `SocketClosed` once the socket is closed. */
+    send(text: string): Promise<void>;
+}
+/** A socket over two functions: what the servicer and the endpoint test kit each give a handler. */
+export declare function socketOf(receive: () => Promise<string | undefined>, send: (text: string) => Promise<void>): Socket;

package/dist/socket.js

@@ -0,0 +1,25 @@
+// A socket route's open socket, as its handler holds it. The sidecar holds the socket itself — its
+// access rule, its limits, its close codes — and relays each frame over `Http.HandleSocket`.
+/** Thrown by `Socket.send` once the socket is closed. A handler that lets it escape has ended as a
+ * handler ends when its client goes: it is not a failure. */
+export class SocketClosed extends Error {
+    constructor(message = "the socket is closed") {
+        super(message);
+        this.name = "SocketClosed";
+    }
+}
+/** A socket over two functions: what the servicer and the endpoint test kit each give a handler. */
+export function socketOf(receive, send) {
+    return Object.freeze({
+        receive,
+        send,
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    const text = await receive();
+                    return text === undefined ? { value: undefined, done: true } : { value: text, done: false };
+                },
+            };
+        },
+    });
+}

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.3";
+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

@@ -1,12 +1,23 @@
 // Renders the discovery Spec from the registry: what the sidecar hosts is exactly what is registered.
 import { create } from "@bufbuild/protobuf";
-import { Endpoint_Acl, SpecSchema } from "./_proto/ankka/protocol/v1/discovery_pb.js";
+import { Endpoint_Acl, Kind, SpecSchema, StartFrom_Named } from "./_proto/ankka/protocol/v1/discovery_pb.js";
 import { resultSchemaJson } from "./autonomous.js";
 import { kindToProto } from "./kinds.js";
 import { toJsonSchema } from "./schema.js";
 import { isCodec } from "./codec.js";
 import { VERSION } from "./version.js";
-export const PROTOCOL_VERSION = "1.3";
+import { approvalToProto } from "./approvals.js";
+import { serverToProto } from "./mcp.js";
+function toolInit(t) {
+    const approval = approvalToProto(t.approval);
+    return {
+        name: t.name,
+        description: t.description,
+        inputSchemaJson: JSON.stringify(isCodec(t.input) ? { type: "object" } : toJsonSchema(t.input)),
+        ...(approval !== undefined ? { approval } : {}),
+    };
+}
+export const PROTOCOL_VERSION = "1.19";
 export const SDK_NAME = "ankka-typescript";
 export function aclToProto(acl) {
     if (typeof acl === "object")
@@ -32,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 } } };
         }
@@ -43,9 +56,23 @@ function handlerInits(handlers) {
         .sort((a, b) => a.name.localeCompare(b.name));
 }
 function sourceInit(source) {
-    return "topic" in source
-        ? { source: { case: "topic", value: source.topic } }
-        : { source: { case: "component", value: { kind: kindToProto(source.component.kind), id: source.component.id } } };
+    if (!("topic" in source))
+        return { source: { case: "component", value: { kind: kindToProto(source.component.kind), id: source.component.id } } };
+    const start = source.startFrom;
+    // 1.14: the contract, the broker and parallel, absent when not declared.
+    const options = {
+        ...(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 };
+    const position = start.kind === "at"
+        ? { case: "atMillis", value: BigInt(start.atMillis) }
+        : { case: "named", value: start.kind === "earliest" ? StartFrom_Named.EARLIEST : StartFrom_Named.LATEST };
+    return { source: { case: "topic", value: source.topic }, startFrom: { position }, ...options };
 }
 function recoveryInit(r) {
     return { maxRetries: r.maxRetries, ...(r.failoverTo !== undefined ? { failoverTo: r.failoverTo } : {}) };
@@ -65,12 +92,12 @@ function settingsInit(s) {
     };
 }
 function componentInit(c) {
-    const base = { kind: kindToProto(c.kind), id: c.id };
+    const base = { kind: c.kind === "keyed-view" ? Kind.VIEW : kindToProto(c.kind), id: c.id };
     switch (c.kind) {
         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":
@@ -80,9 +107,60 @@ function componentInit(c) {
                 detail: { case: "workflow", value: { steps: [...c.steps.keys()].sort(), ...(c.settings ? { settings: settingsInit(c.settings) } : {}) } },
             };
         case "view":
-            return { ...base, handlers: [], detail: { case: "view", value: { source: sourceInit(c.source), rowManifest: c.rowCodec.manifest, queries: [...c.queries] } } };
+            return {
+                ...base,
+                handlers: [],
+                detail: {
+                    case: "view",
+                    value: {
+                        source: sourceInit(c.source),
+                        rowManifest: c.rowCodec.manifest,
+                        queries: [...c.queries],
+                        ...(c.version !== undefined ? { version: c.version } : {}),
+                        declaredQueries: c.declared.map((q) => ({ name: q.name, statement: q.statement, watched: q.watched ?? false })),
+                    },
+                },
+            };
+        case "keyed-view":
+            return {
+                ...base,
+                handlers: [],
+                detail: {
+                    case: "view",
+                    value: {
+                        rowManifest: c.rowCodec.manifest,
+                        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, watched: q.watched ?? false })),
+                    },
+                },
+            };
         case "consumer":
-            return { ...base, handlers: [], detail: { case: "consumer", value: { source: sourceInit(c.source), ...(c.producesTo !== undefined ? { producesTo: c.producesTo } : {}) } } };
+            return {
+                ...base,
+                handlers: [],
+                detail: {
+                    case: "consumer",
+                    value: {
+                        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
+                            ? {
+                                produces: {
+                                    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 } : {}),
+                                },
+                            }
+                            : {}),
+                    },
+                },
+            };
         case "timed-action":
             return { ...base, handlers: handlerInits(c.actions), detail: { case: "timedAction", value: {} } };
         case "agent":
@@ -94,10 +172,10 @@ function componentInit(c) {
                     value: {
                         role: c.role,
                         maxToolCallSteps: c.maxToolCallSteps,
-                        tools: [...c.tools.values()]
-                            .sort((a, b) => a.name.localeCompare(b.name))
-                            .map((t) => ({ name: t.name, description: t.description, inputSchemaJson: JSON.stringify(isCodec(t.input) ? { type: "object" } : toJsonSchema(t.input)) })),
+                        tools: [...c.tools.values()].sort((a, b) => a.name.localeCompare(b.name)).map(toolInit),
                         guardrails: [...c.guardrails.keys()].sort(),
+                        mcpServers: [...c.mcpServers.values()].sort((a, b) => a.name.localeCompare(b.name)).map(serverToProto),
+                        resultGuardrails: [...c.resultGuardrails.keys()].sort(),
                     },
                 },
             };
@@ -123,10 +201,10 @@ function autonomousInit(c) {
                 description: cls.description,
                 ...(cls.instructions !== undefined ? { instructions: cls.instructions } : {}),
                 ...(cls.model !== undefined ? { model: cls.model } : {}),
-                tools: [...c.tools.values()]
-                    .sort((a, b) => a.name.localeCompare(b.name))
-                    .map((t) => ({ name: t.name, description: t.description, inputSchemaJson: JSON.stringify(isCodec(t.input) ? { type: "object" } : toJsonSchema(t.input)) })),
+                tools: [...c.tools.values()].sort((a, b) => a.name.localeCompare(b.name)).map(toolInit),
                 guardrails: [...c.guardrails.keys()].sort(),
+                mcpServers: [...c.mcpServers.values()].sort((a, b) => a.name.localeCompare(b.name)).map(serverToProto),
+                resultGuardrails: [...c.resultGuardrails.keys()].sort(),
                 taskTypes: [...c.taskTypes.values()].map((t) => {
                     const schema = resultSchemaJson(t);
                     return { name: t.name, description: t.description, rules: t.rules.map((r) => r.name), ...(schema !== undefined ? { resultSchemaJson: schema } : {}) };
@@ -150,6 +228,7 @@ export function renderSpec(registry) {
             template: r.template,
             hasBody: r.body !== undefined,
             streaming: r.streaming,
+            socket: r.socket,
             ...(r.acl !== undefined ? { acl: aclToProto(r.acl), allowCallers: callersToProto(r.acl) } : {}),
         })),
     }));

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

@@ -0,0 +1,36 @@
+/**
+ * Where a topic source begins, the first time its consumer group reads a partition. Applied once and
+ * committed at once, so a restart, a rebalance or a new instance resumes where the group got to,
+ * never from here again.
+ */
+export type StartFrom = {
+    readonly kind: "earliest";
+} | {
+    readonly kind: "latest";
+} | {
+    readonly kind: "at";
+    readonly atMillis: number;
+};
+export declare const StartFrom: Readonly<{
+    /** The oldest message the broker still holds. */
+    earliest: StartFrom;
+    /** After the newest: only what is published from then on. */
+    latest: StartFrom;
+    /** The first message published at or after `when`. */
+    at(when: Date): StartFrom;
+}>;
+/** The first protocol in which a process can declare a start position or a version. */
+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

@@ -0,0 +1,51 @@
+// Where a topic source starts, and what a view or consumer that reads a topic may declare about it.
+export const StartFrom = Object.freeze({
+    /** The oldest message the broker still holds. */
+    earliest: Object.freeze({ kind: "earliest" }),
+    /** After the newest: only what is published from then on. */
+    latest: Object.freeze({ kind: "latest" }),
+    /** The first message published at or after `when`. */
+    at(when) {
+        const atMillis = when instanceof Date ? when.getTime() : Number.NaN;
+        if (!Number.isFinite(atMillis))
+            throw new TypeError(`StartFrom.at needs a valid Date, not ${String(when)}`);
+        return Object.freeze({ kind: "at", atMillis });
+    },
+});
+/** The first protocol in which a process can declare a start position or a version. */
+export const START_POSITION_PROTOCOL = [1, 7];
+export function isStartFrom(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const kind = value.kind;
+    if (kind === "earliest" || kind === "latest")
+        return true;
+    return kind === "at" && Number.isFinite(value.atMillis);
+}
+/** The first protocol in which a process can declare a view's queries. */
+export const DECLARED_QUERY_PROTOCOL = [1, 13];
+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;
+    return major < wantMajor || (major === wantMajor && minor < wantMinor);
+}
+/** Whether a sidecar speaking `protocolVersion` would ignore a start position and a version. */
+export function olderThanStartPositions(protocolVersion) {
+    return olderThan(protocolVersion, START_POSITION_PROTOCOL);
+}
+/** Whether a sidecar speaking `protocolVersion` would ignore a view's declared queries. */
+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 } from "./unit.ts";
-export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, type GraphChange, } from "./kinds.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/index.js

@@ -2,5 +2,5 @@
 // (Postgres and the real sidecar image in Docker). The integration testkit's Docker dependencies,
 // `testcontainers` and `@testcontainers/postgresql`, are loaded only when `AnkkaTestKit.start` runs.
 export { EventSourcedTestKit, EndpointTestKit, Response } from "./unit.js";
-export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, KeyedViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
 export { AnkkaTestKit, PUBLISHED_SIDECAR, sidecarImage } from "./integration.js";