ankka 0.9.1 → 0.10.0

package/dist/_proto/ankka/protocol/v1/consumer_pb.d.ts

@@ -20,12 +20,14 @@ export type ConsumerRequest = Message<"ankka.protocol.v1.ConsumerRequest"> & {
      */
     message?: Payload | undefined;
     /**
-     * ce-subject: the source's id; ankka.sequence
+     * ce-subject: the source's id; ankka.sequence;
      *
      * @generated from field: ankka.protocol.v1.Metadata metadata = 3;
      */
     metadata?: Metadata | undefined;
     /**
+     * ankka.protocol: what the runtime speaks (1.3)
+     *
      * the source was deleted
      *
      * @generated from field: bool deleted = 4;
@@ -62,6 +64,14 @@ export type ConsumerEffect = Message<"ankka.protocol.v1.ConsumerEffect"> & {
          */
         value: Empty;
         case: "ignore";
+    } | {
+        /**
+         * 1.3: several messages for one change
+         *
+         * @generated from field: ankka.protocol.v1.ConsumerEffect.ProduceAll produce_all = 4;
+         */
+        value: ConsumerEffect_ProduceAll;
+        case: "produceAll";
     } | {
         case: undefined;
         value?: undefined;
@@ -90,6 +100,47 @@ export type ConsumerEffect_Produce = Message<"ankka.protocol.v1.ConsumerEffect.P
  * Use `create(ConsumerEffect_ProduceSchema)` to create a new message.
  */
 export declare const ConsumerEffect_ProduceSchema: GenMessage<ConsumerEffect_Produce>;
+/**
+ * Published in order; the change is handled when the broker has accepted all of them. None at
+ * all is `done`. Send it only to a runtime whose request carried `ankka.protocol` >= 1.3.
+ *
+ * @generated from message ankka.protocol.v1.ConsumerEffect.ProduceAll
+ */
+export type ConsumerEffect_ProduceAll = Message<"ankka.protocol.v1.ConsumerEffect.ProduceAll"> & {
+    /**
+     * @generated from field: repeated ankka.protocol.v1.ConsumerEffect.Message messages = 1;
+     */
+    messages: ConsumerEffect_Message[];
+};
+/**
+ * Describes the message ankka.protocol.v1.ConsumerEffect.ProduceAll.
+ * Use `create(ConsumerEffect_ProduceAllSchema)` to create a new message.
+ */
+export declare const ConsumerEffect_ProduceAllSchema: GenMessage<ConsumerEffect_ProduceAll>;
+/**
+ * @generated from message ankka.protocol.v1.ConsumerEffect.Message
+ */
+export type ConsumerEffect_Message = Message<"ankka.protocol.v1.ConsumerEffect.Message"> & {
+    /**
+     * @generated from field: ankka.protocol.v1.Payload payload = 1;
+     */
+    payload?: Payload | undefined;
+    /**
+     * @generated from field: ankka.protocol.v1.Metadata metadata = 2;
+     */
+    metadata?: Metadata | undefined;
+    /**
+     * the record key; absent: the message's subject
+     *
+     * @generated from field: optional string key = 3;
+     */
+    key?: string | undefined;
+};
+/**
+ * Describes the message ankka.protocol.v1.ConsumerEffect.Message.
+ * Use `create(ConsumerEffect_MessageSchema)` to create a new message.
+ */
+export declare const ConsumerEffect_MessageSchema: GenMessage<ConsumerEffect_Message>;
 /**
  * @generated from service ankka.protocol.v1.Consumer
  */

package/dist/_proto/ankka/protocol/v1/consumer_pb.js

@@ -6,7 +6,7 @@ import { file_ankka_protocol_v1_payload } from "./payload_pb.js";
 /**
  * Describes the file ankka/protocol/v1/consumer.proto.
  */
-export const file_ankka_protocol_v1_consumer = /*@__PURE__*/ fileDesc("CiBhbmtrYS9wcm90b2NvbC92MS9jb25zdW1lci5wcm90bxIRYW5ra2EucHJvdG9jb2wudjEilAEKD0NvbnN1bWVyUmVxdWVzdBIUCgxjb21wb25lbnRfaWQYASABKAkSKwoHbWVzc2FnZRgCIAEoCzIaLmFua2thLnByb3RvY29sLnYxLlBheWxvYWQSLQoIbWV0YWRhdGEYAyABKAsyGy5hbmtrYS5wcm90b2NvbC52MS5NZXRhZGF0YRIPCgdkZWxldGVkGAQgASgIIpUCCg5Db25zdW1lckVmZmVjdBI8Cgdwcm9kdWNlGAEgASgLMikuYW5ra2EucHJvdG9jb2wudjEuQ29uc3VtZXJFZmZlY3QuUHJvZHVjZUgAEigKBGRvbmUYAiABKAsyGC5hbmtrYS5wcm90b2NvbC52MS5FbXB0eUgAEioKBmlnbm9yZRgDIAEoCzIYLmFua2thLnByb3RvY29sLnYxLkVtcHR5SAAaZQoHUHJvZHVjZRIrCgdwYXlsb2FkGAEgASgLMhouYW5ra2EucHJvdG9jb2wudjEuUGF5bG9hZBItCghtZXRhZGF0YRgCIAEoCzIbLmFua2thLnByb3RvY29sLnYxLk1ldGFkYXRhQggKBmVmZmVjdDJbCghDb25zdW1lchJPCgZIYW5kbGUSIi5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lclJlcXVlc3QaIS5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lckVmZmVjdGIGcHJvdG8z", [file_ankka_protocol_v1_payload]);
+export const file_ankka_protocol_v1_consumer = /*@__PURE__*/ fileDesc("CiBhbmtrYS9wcm90b2NvbC92MS9jb25zdW1lci5wcm90bxIRYW5ra2EucHJvdG9jb2wudjEilAEKD0NvbnN1bWVyUmVxdWVzdBIUCgxjb21wb25lbnRfaWQYASABKAkSKwoHbWVzc2FnZRgCIAEoCzIaLmFua2thLnByb3RvY29sLnYxLlBheWxvYWQSLQoIbWV0YWRhdGEYAyABKAsyGy5hbmtrYS5wcm90b2NvbC52MS5NZXRhZGF0YRIPCgdkZWxldGVkGAQgASgIIqYECg5Db25zdW1lckVmZmVjdBI8Cgdwcm9kdWNlGAEgASgLMikuYW5ra2EucHJvdG9jb2wudjEuQ29uc3VtZXJFZmZlY3QuUHJvZHVjZUgAEigKBGRvbmUYAiABKAsyGC5hbmtrYS5wcm90b2NvbC52MS5FbXB0eUgAEioKBmlnbm9yZRgDIAEoCzIYLmFua2thLnByb3RvY29sLnYxLkVtcHR5SAASQwoLcHJvZHVjZV9hbGwYBCABKAsyLC5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lckVmZmVjdC5Qcm9kdWNlQWxsSAAaZQoHUHJvZHVjZRIrCgdwYXlsb2FkGAEgASgLMhouYW5ra2EucHJvdG9jb2wudjEuUGF5bG9hZBItCghtZXRhZGF0YRgCIAEoCzIbLmFua2thLnByb3RvY29sLnYxLk1ldGFkYXRhGkkKClByb2R1Y2VBbGwSOwoIbWVzc2FnZXMYASADKAsyKS5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lckVmZmVjdC5NZXNzYWdlGn8KB01lc3NhZ2USKwoHcGF5bG9hZBgBIAEoCzIaLmFua2thLnByb3RvY29sLnYxLlBheWxvYWQSLQoIbWV0YWRhdGEYAiABKAsyGy5hbmtrYS5wcm90b2NvbC52MS5NZXRhZGF0YRIQCgNrZXkYAyABKAlIAIgBAUIGCgRfa2V5QggKBmVmZmVjdDJbCghDb25zdW1lchJPCgZIYW5kbGUSIi5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lclJlcXVlc3QaIS5hbmtrYS5wcm90b2NvbC52MS5Db25zdW1lckVmZmVjdGIGcHJvdG8z", [file_ankka_protocol_v1_payload]);
 /**
  * Describes the message ankka.protocol.v1.ConsumerRequest.
  * Use `create(ConsumerRequestSchema)` to create a new message.
@@ -22,6 +22,16 @@ export const ConsumerEffectSchema = /*@__PURE__*/ messageDesc(file_ankka_protoco
  * Use `create(ConsumerEffect_ProduceSchema)` to create a new message.
  */
 export const ConsumerEffect_ProduceSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_consumer, 1, 0);
+/**
+ * Describes the message ankka.protocol.v1.ConsumerEffect.ProduceAll.
+ * Use `create(ConsumerEffect_ProduceAllSchema)` to create a new message.
+ */
+export const ConsumerEffect_ProduceAllSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_consumer, 1, 1);
+/**
+ * Describes the message ankka.protocol.v1.ConsumerEffect.Message.
+ * Use `create(ConsumerEffect_MessageSchema)` to create a new message.
+ */
+export const ConsumerEffect_MessageSchema = /*@__PURE__*/ messageDesc(file_ankka_protocol_v1_consumer, 1, 2);
 /**
  * @generated from service ankka.protocol.v1.Consumer
  */

package/dist/consumer.d.ts

@@ -3,12 +3,28 @@ import type { Metadata } from "./effects/common.ts";
 import type { ComponentClient, ComponentRef } from "./client.ts";
 import { ConsumerEffects, type ConsumerEffect } from "./effects/stateless.ts";
 type MaybePromise<T> = T | Promise<T>;
+/** The metadata entry a runtime sets on a consumer's request to say what it speaks: its protocol version. */
+export declare const PROTOCOL_KEY = "ankka.protocol";
+/** Thrown when a consumer answers with several messages, or a record key, to a runtime that would drop them. */
+export declare class ProtocolVersionError extends Error {
+    constructor(declared: string | undefined);
+}
+/**
+ * Refuses to answer with several messages unless the request says the runtime accepts them. A runtime
+ * before protocol 1.3 reads the reply as no effect at all and records the change as handled with
+ * nothing published, so the request is failed instead: the change is delivered again, visibly.
+ */
+export declare function requireSeveralMessages(metadata: Metadata): void;
+/** The change's sequence number from its metadata: an event's, a key value state's revision; absent when there is none. */
+export declare function sequenceNumberOf(metadata: Metadata): bigint | undefined;
 export declare abstract class Consumer<M, Out = never> {
     #private;
     readonly effects: ConsumerEffects<Out>;
     /** The message's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata(): Metadata;
     get subject(): string;
+    /** The change's sequence number: an event's, or a key value state's revision. `0n` for a topic's message. */
+    get sequenceNumber(): bigint | undefined;
     get client(): ComponentClient;
     /** @internal */
     get _kind(): "consumer";

package/dist/consumer.js

@@ -1,5 +1,31 @@
 // A consumer: reacts to a source's changes, optionally producing onward to a topic.
 import { ConsumerEffects } from "./effects/stateless.js";
+/** The metadata entry a runtime sets on a consumer's request to say what it speaks: its protocol version. */
+export const PROTOCOL_KEY = "ankka.protocol";
+/** Thrown when a consumer answers with several messages, or a record key, to a runtime that would drop them. */
+export class ProtocolVersionError extends Error {
+    constructor(declared) {
+        super(`this runtime speaks protocol ${declared ?? "1.2 or earlier"}; several messages or a record key need 1.3`);
+        this.name = "ProtocolVersionError";
+    }
+}
+/**
+ * Refuses to answer with several messages unless the request says the runtime accepts them. A runtime
+ * before protocol 1.3 reads the reply as no effect at all and records the change as handled with
+ * nothing published, so the request is failed instead: the change is delivered again, visibly.
+ */
+export function requireSeveralMessages(metadata) {
+    const declared = metadata[PROTOCOL_KEY];
+    const match = declared === undefined ? null : /^(\d+)\.(\d+)$/.exec(declared.trim());
+    const accepted = match !== null && (Number(match[1]) > 1 || (Number(match[1]) === 1 && Number(match[2]) >= 3));
+    if (!accepted)
+        throw new ProtocolVersionError(declared);
+}
+/** The change's sequence number from its metadata: an event's, a key value state's revision; absent when there is none. */
+export function sequenceNumberOf(metadata) {
+    const raw = metadata["ankka.sequence"];
+    return raw !== undefined && /^-?\d+$/.test(raw) ? BigInt(raw) : undefined;
+}
 export class Consumer {
     effects = new ConsumerEffects();
     #metadata = {};
@@ -11,6 +37,10 @@ export class Consumer {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** The change's sequence number: an event's, or a key value state's revision. `0n` for a topic's message. */
+    get sequenceNumber() {
+        return sequenceNumberOf(this.#metadata);
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside onMessage or onDelete");

package/dist/effects/stateless.d.ts

@@ -12,10 +12,25 @@ export declare class ViewEffects<Row> {
     deleteRow(): ViewEffect<Row>;
     ignore(): ViewEffect<Row>;
 }
+/**
+ * One message of several: what to publish, optionally the record key it is published under, and its
+ * headers. A message with no key is keyed by its subject — the source instance's id unless the
+ * metadata sets `ce-subject` — which keeps everything about one instance on one partition, in order.
+ * A key is for a message about something else: a line item, an element of a graph. Naming one does
+ * not change the subject.
+ */
+export interface OutgoingMessage<Out> {
+    readonly payload: Out;
+    readonly key?: string;
+    readonly metadata?: Metadata;
+}
 export type ConsumerEffect<Out> = ({
     readonly kind: "produce";
     readonly payload: Out;
     readonly metadata: Metadata;
+} & EffectLike<never>) | ({
+    readonly kind: "produceAll";
+    readonly messages: readonly OutgoingMessage<Out>[];
 } & EffectLike<never>) | ({
     readonly kind: "done";
 } & EffectLike<never>) | ({
@@ -24,6 +39,12 @@ export type ConsumerEffect<Out> = ({
 export declare class ConsumerEffects<Out> {
     /** Produce onward to the topic the consumer declares in `producesTo`. */
     produce(payload: Out, metadata?: Metadata): ConsumerEffect<Out>;
+    /**
+     * Produce several messages for this change, in the order given. The change is handled when the
+     * broker has accepted every one; if one is refused the change comes again and all are published
+     * again. An empty list publishes nothing and is handled at once.
+     */
+    produceAll(messages: readonly OutgoingMessage<Out>[]): ConsumerEffect<Out>;
     done(): ConsumerEffect<Out>;
     ignore(): ConsumerEffect<Out>;
 }

package/dist/effects/stateless.js

@@ -17,6 +17,25 @@ export class ConsumerEffects {
     produce(payload, metadata = {}) {
         return Object.freeze({ kind: "produce", payload, metadata });
     }
+    /**
+     * Produce several messages for this change, in the order given. The change is handled when the
+     * broker has accepted every one; if one is refused the change comes again and all are published
+     * again. An empty list publishes nothing and is handled at once.
+     */
+    produceAll(messages) {
+        if (!Array.isArray(messages))
+            throw new TypeError("produceAll takes a list of messages");
+        const checked = messages.map((m, i) => {
+            if (typeof m !== "object" || m === null || !("payload" in m))
+                throw new TypeError(`produceAll: message ${i} is not a message: { payload, key?, metadata? }`);
+            if (m.key !== undefined && typeof m.key !== "string")
+                throw new TypeError(`produceAll: message ${i} has a record key that is not a string`);
+            if (m.key === "")
+                throw new TypeError(`produceAll: message ${i} has an empty record key; leave the key out to key the message by its subject`);
+            return Object.freeze({ ...m });
+        });
+        return Object.freeze({ kind: "produceAll", messages: Object.freeze(checked) });
+    }
     done() {
         return Object.freeze({ kind: "done" });
     }

package/dist/graph.d.ts

@@ -0,0 +1,157 @@
+import { type Codec, type Shape } from "./codec.ts";
+import type { EffectLike, Metadata } from "./effects/common.ts";
+import type { ComponentClient, ComponentRef } from "./client.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";
+/** The record key of every delta for the node `id`. */
+export declare function nodeKey(id: string): string;
+/** The record key of every delta for the edge `id`. Nodes and edges are separate id spaces. */
+export declare function edgeKey(id: string): string;
+/** A property's scalar: an integral `number` must be a safe integer; a larger integer is a `bigint`. */
+export type Scalar = string | boolean | number | bigint;
+/** A scalar, or a non-empty list of scalars of one kind. */
+export type PropertyValue = Scalar | readonly Scalar[];
+export type Properties = Readonly<Record<string, PropertyValue>>;
+/** A version: a whole number of at least 1, as a safe-integer `number` or a `bigint` within 64 bits. */
+export type Version = number | bigint;
+/** An element as the author describes it. Without a `version` it takes its change's sequence number. */
+export type Element = {
+    readonly kind: "node";
+    readonly id: string;
+    readonly version?: Version;
+    readonly labels: readonly string[];
+    readonly properties: Properties;
+} | {
+    readonly kind: "edge";
+    readonly id: string;
+    readonly version?: Version;
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+    readonly properties: Properties;
+} | {
+    readonly kind: "tombstone";
+    readonly element: "node";
+    readonly id: string;
+    readonly version?: Version;
+} | {
+    readonly kind: "tombstone";
+    readonly element: "edge";
+    readonly id: string;
+    readonly version?: Version;
+    readonly type: string;
+    readonly from: string;
+    readonly to: string;
+};
+/** An element at a version: what is written and read. */
+export type Delta = Element & {
+    readonly version: Version;
+};
+/** Why an element or a result was refused; the names the shared fixture `refused.json` uses. */
+export type GraphFault = "id" | "endpoints" | "identifier" | "reserved" | "property-value" | "integer-range" | "version" | "duplicate" | "no-sequence";
+/** Thrown where an element is built, or when a result is returned, for something the merge sink would refuse. */
+export declare class GraphError extends Error {
+    readonly why: GraphFault;
+    constructor(why: GraphFault, message: string);
+}
+/** The element key: `node:<id>` or `edge:<id>`; a tombstone has the key of the element it marks. */
+export declare function elementKey(element: Element): string;
+/** `this.graph` in a graph consumer: builds elements, refusing where they are built what the sink would refuse. */
+export declare class Graph {
+    node(id: string, options?: {
+        readonly labels?: readonly string[];
+        readonly properties?: Properties;
+        readonly version?: Version;
+    }): Element;
+    edge(id: string, options: {
+        readonly type: string;
+        readonly from: string;
+        readonly to: string;
+        readonly properties?: Properties;
+        readonly version?: Version;
+    }): Element;
+    /** Marks a node deleted. The node stays in the graph, marked, so a straggling older delta cannot bring it back. */
+    tombstoneNode(id: string, options?: {
+        readonly version?: Version;
+    }): Element;
+    /** Marks an edge deleted; it names the edge's type and endpoints so the edge is found without a scan. */
+    tombstoneEdge(id: string, options: {
+        readonly type: string;
+        readonly from: string;
+        readonly to: string;
+        readonly version?: Version;
+    }): Element;
+}
+export type GraphEffect = ({
+    readonly kind: "publish";
+    readonly elements: readonly Element[];
+} & EffectLike<never>) | ({
+    readonly kind: "done";
+} & EffectLike<never>) | ({
+    readonly kind: "ignore";
+} & EffectLike<never>);
+/** `this.effects` in a graph consumer: there is nothing here that publishes anything but elements. */
+export declare class GraphEffects {
+    /** Publish these elements, each as a delta under its own key. An empty list publishes nothing. */
+    publish(elements: readonly Element[]): GraphEffect;
+    done(): GraphEffect;
+    ignore(): GraphEffect;
+}
+/**
+ * Reads a delta's value back into an element, for tests and for a consumer of a delta topic. Given a
+ * `key` it also holds the contract's rule that the key is the delta's element key. It accepts a
+ * version of 0, which the contract allows and the builder does not write. An integer past 2⁵³ comes
+ * back as a `bigint`.
+ */
+export declare function readDelta(value: Uint8Array, key?: string): Delta;
+/** The codec of a delta: JSON under the manifest `ankka.graph-delta.v1`. Hand-written, since a delta's properties have no fixed shape. */
+export declare const graphDeltaCodec: Codec<Delta>;
+/** One record a graph consumer's result comes to: the element key, the delta's bytes, and the delta. */
+export interface DeltaRecord {
+    readonly key: string;
+    readonly value: Uint8Array;
+    readonly delta: Delta;
+}
+/**
+ * What a graph consumer's effect publishes for the change `metadata` describes: every element at its
+ * stated version, else the change's sequence number, refusing a result that names an element twice or
+ * leaves a version to a change that has no sequence number. The server and the test kit both read an
+ * effect through this, so they cannot disagree about what a handler published.
+ *
+ * @internal
+ */
+export declare function deltaRecords(effect: GraphEffect, metadata: Metadata): readonly DeltaRecord[];
+/**
+ * A consumer that publishes a graph. Its handlers return elements; each is published to `producesTo`
+ * as a delta under its element key. It has no `produce` and no way to set a key, and it is discovered
+ * and hosted as an ordinary consumer.
+ */
+export declare abstract class GraphConsumer<M> {
+    #private;
+    readonly graph: Graph;
+    readonly effects: GraphEffects;
+    /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata(): Metadata;
+    get subject(): string;
+    /** The change's sequence number, which is the version of every element that states none. */
+    get sequenceNumber(): bigint | undefined;
+    get client(): ComponentClient;
+    /** @internal */
+    get _kind(): "consumer";
+    abstract onMessage(message: M): MaybePromise<GraphEffect>;
+    /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
+    onDelete(): MaybePromise<GraphEffect>;
+    /** @internal */
+    _bind(metadata: Metadata, client: ComponentClient): void;
+}
+export interface GraphConsumerClass<M = unknown, C extends GraphConsumer<M> = GraphConsumer<M>> {
+    new (): C;
+    readonly componentId: string;
+    readonly source?: ComponentRef;
+    readonly topic?: string;
+    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;
+}
+export {};

package/dist/graph.js

@@ -0,0 +1,426 @@
+// Publishing a graph: a consumer that says which elements a change leaves in which state, and has each
+// published as a graph delta — one element's whole state at a version, or a tombstone marking it
+// deleted — under the contract `ankka.graph-delta.v1`. The record's key is the element's
+// (`node:<id>` or `edge:<id>`), never the author's to set, and its version is the change's sequence
+// number unless one is stated. A graph database kept in step with the topic applies a delta when its
+// version is newer than what it holds, so a change handled twice does no harm.
+//
+//   export class CartGraph extends GraphConsumer<ShoppingCartEvent> {
+//     static readonly componentId = "cart-graph"
+//     static readonly source = ShoppingCartEntity
+//     static readonly message = ShoppingCartEntity.events
+//     static readonly producesTo = "cart-graph"
+//     onMessage(event) {
+//       return this.effects.publish([this.graph.node(`cart:${this.subject}`, { labels: ["Cart"] })])
+//     }
+//   }
+import { JSON_CONTENT } from "./codec.js";
+import { sequenceNumberOf } from "./consumer.js";
+import { renderDouble, reviver } from "./json.js";
+/** The contract's name: the manifest and the `ce-type` of every delta. */
+export const GRAPH_DELTA_SCHEMA = "ankka.graph-delta.v1";
+/** The record key of every delta for the node `id`. */
+export function nodeKey(id) {
+    return `node:${id}`;
+}
+/** The record key of every delta for the edge `id`. Nodes and edges are separate id spaces. */
+export function edgeKey(id) {
+    return `edge:${id}`;
+}
+/** Thrown where an element is built, or when a result is returned, for something the merge sink would refuse. */
+export class GraphError extends Error {
+    why;
+    constructor(why, message) {
+        super(message);
+        this.name = "GraphError";
+        this.why = why;
+    }
+}
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const RESERVED = new Set(["id", "_version", "_deleted"]);
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+function show(value) {
+    if (typeof value === "bigint")
+        return `${value}n`;
+    if (typeof value === "number")
+        return String(value);
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function spaceOf(element) {
+    return element.kind === "edge" || (element.kind === "tombstone" && element.element === "edge") ? "edge" : "node";
+}
+function describe(element) {
+    const what = element.kind === "tombstone" ? `tombstone of ${spaceOf(element)}` : element.kind;
+    return `${what} ${show(element.id)}`;
+}
+/** The element key: `node:<id>` or `edge:<id>`; a tombstone has the key of the element it marks. */
+export function elementKey(element) {
+    return spaceOf(element) === "edge" ? edgeKey(element.id) : nodeKey(element.id);
+}
+/** The kind of one scalar. A float with a whole value is an integer, as the sink reads it. */
+function scalarKind(who, name, value) {
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "boolean":
+            return "boolean";
+        case "bigint":
+            if (value < INT64_MIN || value > INT64_MAX)
+                throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, which does not fit 64 bits`);
+            return "integer";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new GraphError("property-value", `${who}: property ${show(name)} is ${value}, which is not a finite number`);
+            if (!Number.isInteger(value))
+                return "float";
+            if (Number.isSafeInteger(value))
+                return "integer";
+            if (value < Number(INT64_MIN) || value >= 2 ** 63)
+                throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, a whole number that does not fit 64 bits`);
+            throw new GraphError("integer-range", `${who}: property ${show(name)} is ${value}, a whole number past 2^53 that a number cannot hold exactly; pass it as a bigint`);
+        default:
+            throw new GraphError("property-value", `${who}: property ${show(name)} is ${show(value)}; a property is a string, a number, a boolean, or a non-empty list of one of those`);
+    }
+}
+function checkProperties(who, properties) {
+    if (properties === undefined)
+        return Object.freeze({});
+    if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
+        throw new GraphError("property-value", `${who}: properties must be an object of property values, not ${show(properties)}`);
+    }
+    const out = {};
+    for (const [name, value] of Object.entries(properties)) {
+        if (RESERVED.has(name))
+            throw new GraphError("reserved", `${who}: property ${show(name)} is reserved`);
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                throw new GraphError("property-value", `${who}: property ${show(name)} is an empty list; leave the property out instead`);
+            const kinds = new Set(value.map((v) => scalarKind(who, name, v)));
+            if (kinds.size > 1)
+                throw new GraphError("property-value", `${who}: property ${show(name)} is a list of more than one kind (${[...kinds].join(", ")}); a whole-number float counts as an integer`);
+            out[name] = Object.freeze([...value]);
+        }
+        else {
+            scalarKind(who, name, value);
+            out[name] = value;
+        }
+    }
+    return Object.freeze(out);
+}
+function checkVersion(who, version) {
+    if (typeof version === "bigint") {
+        if (version < 1n || version > INT64_MAX)
+            throw new GraphError("version", `${who}: version must be a whole number of at least 1 within 64 bits, not ${version}`);
+        return version <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(version) : version;
+    }
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) {
+        throw new GraphError("version", `${who}: version must be a whole number of at least 1 (a safe integer, or a bigint within 64 bits), not ${show(version)}`);
+    }
+    return version;
+}
+function checkId(who, id) {
+    if (typeof id !== "string" || id === "")
+        throw new GraphError("id", `${who}: id must be a non-empty string`);
+    return id;
+}
+function checkEndpoints(who, e) {
+    for (const field of ["type", "from", "to"]) {
+        if (typeof e[field] !== "string" || e[field] === "")
+            throw new GraphError("endpoints", `${who}: an edge needs a type, a from and a to; ${field} is missing or empty`);
+    }
+    if (!IDENTIFIER.test(e.type))
+        throw new GraphError("identifier", `${who}: type ${show(e.type)} is not an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+    return { type: e.type, from: e.from, to: e.to };
+}
+function checkLabels(who, labels) {
+    if (labels === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(labels))
+        throw new GraphError("identifier", `${who}: labels must be a list of identifiers, not ${show(labels)}`);
+    for (const label of labels) {
+        if (typeof label !== "string" || !IDENTIFIER.test(label))
+            throw new GraphError("identifier", `${who}: label ${show(label)} is not an identifier ([A-Za-z_][A-Za-z0-9_]*)`);
+    }
+    return Object.freeze([...labels]);
+}
+/** The element, checked against everything the merge sink would refuse of it, as a frozen value. */
+function checked(element) {
+    const raw = element;
+    if (typeof raw !== "object" || raw === null)
+        throw new TypeError(`not a graph element: ${show(raw)}`);
+    if (raw.kind !== "node" && raw.kind !== "edge" && raw.kind !== "tombstone")
+        throw new TypeError(`not a graph element: kind is ${show(raw.kind)}`);
+    if (raw.kind === "tombstone" && raw.element !== "node" && raw.element !== "edge")
+        throw new TypeError(`not a graph element: a tombstone marks a node or an edge, not ${show(raw.element)}`);
+    const who = describe(raw);
+    const id = checkId(who, raw.id);
+    const version = raw.version === undefined ? {} : { version: checkVersion(who, raw.version) };
+    if (raw.kind === "node") {
+        return Object.freeze({ kind: "node", id, ...version, labels: checkLabels(who, raw.labels), properties: checkProperties(who, raw.properties) });
+    }
+    if (raw.kind === "edge") {
+        return Object.freeze({ kind: "edge", id, ...version, ...checkEndpoints(who, raw), properties: checkProperties(who, raw.properties) });
+    }
+    if (raw.element === "edge")
+        return Object.freeze({ kind: "tombstone", element: "edge", id, ...version, ...checkEndpoints(who, raw) });
+    return Object.freeze({ kind: "tombstone", element: "node", id, ...version });
+}
+/** `this.graph` in a graph consumer: builds elements, refusing where they are built what the sink would refuse. */
+export class Graph {
+    node(id, options = {}) {
+        return checked({ kind: "node", id, labels: options.labels, properties: options.properties, ...(options.version !== undefined ? { version: options.version } : {}) });
+    }
+    edge(id, options) {
+        return checked({ kind: "edge", id, type: options?.type, from: options?.from, to: options?.to, properties: options?.properties, ...(options?.version !== undefined ? { version: options.version } : {}) });
+    }
+    /** Marks a node deleted. The node stays in the graph, marked, so a straggling older delta cannot bring it back. */
+    tombstoneNode(id, options = {}) {
+        return checked({ kind: "tombstone", element: "node", id, ...(options.version !== undefined ? { version: options.version } : {}) });
+    }
+    /** Marks an edge deleted; it names the edge's type and endpoints so the edge is found without a scan. */
+    tombstoneEdge(id, options) {
+        return checked({ kind: "tombstone", element: "edge", id, type: options?.type, from: options?.from, to: options?.to, ...(options?.version !== undefined ? { version: options.version } : {}) });
+    }
+}
+/** `this.effects` in a graph consumer: there is nothing here that publishes anything but elements. */
+export class GraphEffects {
+    /** Publish these elements, each as a delta under its own key. An empty list publishes nothing. */
+    publish(elements) {
+        if (!Array.isArray(elements))
+            throw new TypeError("publish takes a list of elements");
+        return Object.freeze({ kind: "publish", elements: Object.freeze(elements.map(checked)) });
+    }
+    done() {
+        return Object.freeze({ kind: "done" });
+    }
+    ignore() {
+        return Object.freeze({ kind: "ignore" });
+    }
+}
+// ── writing ──
+function writeScalar(value) {
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "bigint":
+            return value.toString();
+        default:
+            return Number.isInteger(value) ? String(value) : renderDouble(value);
+    }
+}
+function writeProperties(properties) {
+    const fields = Object.entries(properties).map(([name, value]) => `${JSON.stringify(name)}:${Array.isArray(value) ? `[${value.map(writeScalar).join(",")}]` : writeScalar(value)}`);
+    return `{${fields.join(",")}}`;
+}
+/** The delta as the contract writes it. `labels` and `properties` are always written. */
+function writeDelta(delta) {
+    const id = JSON.stringify(delta.id);
+    const version = delta.version.toString();
+    switch (delta.kind) {
+        case "node":
+            return `{"kind":"node","id":${id},"version":${version},"labels":[${delta.labels.map((l) => JSON.stringify(l)).join(",")}],"properties":${writeProperties(delta.properties)}}`;
+        case "edge":
+            return `{"kind":"edge","id":${id},"version":${version},"type":${JSON.stringify(delta.type)},"from":${JSON.stringify(delta.from)},"to":${JSON.stringify(delta.to)},"properties":${writeProperties(delta.properties)}}`;
+        default:
+            return delta.element === "edge"
+                ? `{"kind":"tombstone","element":"edge","id":${id},"version":${version},"type":${JSON.stringify(delta.type)},"from":${JSON.stringify(delta.from)},"to":${JSON.stringify(delta.to)}}`
+                : `{"kind":"tombstone","element":"node","id":${id},"version":${version}}`;
+    }
+}
+// ── reading ──
+const utf8 = new TextEncoder();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function readScalar(name, raw) {
+    const refuse = () => {
+        throw new Error(`property '${name}' is not a scalar or array of scalars`);
+    };
+    switch (typeof raw) {
+        case "string":
+            return { kind: "string", value: raw };
+        case "boolean":
+            return { kind: "boolean", value: raw };
+        case "bigint":
+            return raw < INT64_MIN || raw > INT64_MAX ? refuse() : { kind: "integer", value: raw };
+        case "number":
+            if (!Number.isInteger(raw))
+                return { kind: "float", value: raw };
+            if (Number.isSafeInteger(raw))
+                return { kind: "integer", value: raw };
+            // A whole number written with a fraction or an exponent: an integer if it fits 64 bits.
+            return raw < Number(INT64_MIN) || raw >= 2 ** 63 ? refuse() : { kind: "integer", value: BigInt(raw) };
+        default:
+            return refuse();
+    }
+}
+function readProperties(raw) {
+    if (raw === undefined)
+        return Object.freeze({});
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("properties must be an object");
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (RESERVED.has(name))
+            throw new Error(`property '${name}' is reserved`);
+        if (Array.isArray(value)) {
+            const read = value.map((v) => readScalar(name, v));
+            if (read.length === 0 || new Set(read.map((r) => r.kind)).size > 1)
+                throw new Error(`property '${name}' is not a scalar or array of scalars`);
+            out[name] = Object.freeze(read.map((r) => r.value));
+        }
+        else {
+            out[name] = readScalar(name, value).value;
+        }
+    }
+    return Object.freeze(out);
+}
+function readVersion(raw) {
+    if (typeof raw === "bigint" && raw >= 0n && raw <= INT64_MAX)
+        return raw;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= 0) {
+        if (Number.isSafeInteger(raw))
+            return raw;
+        if (raw < 2 ** 63)
+            return BigInt(raw);
+    }
+    throw new Error("version is not a non-negative integer");
+}
+function readEndpoints(o, problem) {
+    const text = (v) => typeof v === "string" && v !== "";
+    if (!text(o.type) || !IDENTIFIER.test(o.type) || !text(o.from) || !text(o.to))
+        throw new Error(problem);
+    return { type: o.type, from: o.from, to: o.to };
+}
+/**
+ * Reads a delta's value back into an element, for tests and for a consumer of a delta topic. Given a
+ * `key` it also holds the contract's rule that the key is the delta's element key. It accepts a
+ * version of 0, which the contract allows and the builder does not write. An integer past 2⁵³ comes
+ * back as a `bigint`.
+ */
+export function readDelta(value, key) {
+    let raw;
+    try {
+        raw = JSON.parse(utf8Decoder.decode(value), reviver);
+    }
+    catch {
+        throw new Error("not a JSON object");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        throw new Error("not a JSON object");
+    const o = raw;
+    if (o.kind === undefined)
+        throw new Error("kind missing");
+    if (o.kind !== "node" && o.kind !== "edge" && o.kind !== "tombstone")
+        throw new Error(`unknown kind '${String(o.kind)}'`);
+    if (typeof o.id !== "string" || o.id === "")
+        throw new Error("id missing or empty");
+    const id = o.id;
+    const version = readVersion(o.version);
+    let delta;
+    if (o.kind === "node") {
+        const labels = o.labels ?? [];
+        if (!Array.isArray(labels) || labels.some((l) => typeof l !== "string" || !IDENTIFIER.test(l)))
+            throw new Error("labels must be an array of identifiers");
+        delta = Object.freeze({ kind: "node", id, version, labels: Object.freeze([...labels]), properties: readProperties(o.properties) });
+    }
+    else if (o.kind === "edge") {
+        delta = Object.freeze({ kind: "edge", id, version, ...readEndpoints(o, "edge needs type, from and to"), properties: readProperties(o.properties) });
+    }
+    else if (o.element === "node") {
+        delta = Object.freeze({ kind: "tombstone", element: "node", id, version });
+    }
+    else if (o.element === "edge") {
+        delta = Object.freeze({ kind: "tombstone", element: "edge", id, version, ...readEndpoints(o, "tombstone of an edge needs type, from and to") });
+    }
+    else {
+        throw new Error("tombstone needs element 'node' or 'edge'");
+    }
+    if (key !== undefined && key !== elementKey(delta))
+        throw new Error(`key '${key}' is not this delta's element key '${elementKey(delta)}'`);
+    return delta;
+}
+/** The codec of a delta: JSON under the manifest `ankka.graph-delta.v1`. Hand-written, since a delta's properties have no fixed shape. */
+export const graphDeltaCodec = Object.freeze({
+    manifest: GRAPH_DELTA_SCHEMA,
+    contentType: JSON_CONTENT,
+    encode: (delta) => utf8.encode(writeDelta(checked(delta))),
+    decode: (bytes) => readDelta(bytes),
+});
+/**
+ * What a graph consumer's effect publishes for the change `metadata` describes: every element at its
+ * stated version, else the change's sequence number, refusing a result that names an element twice or
+ * leaves a version to a change that has no sequence number. The server and the test kit both read an
+ * effect through this, so they cannot disagree about what a handler published.
+ *
+ * @internal
+ */
+export function deltaRecords(effect, metadata) {
+    if (effect.kind !== "publish")
+        return [];
+    const sequence = sequenceNumberOf(metadata);
+    const seen = new Set();
+    return effect.elements.map((given) => {
+        const element = checked(given);
+        const key = elementKey(element);
+        if (seen.has(key))
+            throw new GraphError("duplicate", `${describe(element)} is in this result twice (${key}); an element is published once for a change`);
+        seen.add(key);
+        let version = element.version;
+        if (version === undefined) {
+            if (sequence === undefined || sequence < 1n) {
+                throw new GraphError("no-sequence", `${describe(element)}: this source has no sequence number; state a version`);
+            }
+            version = checkVersion(describe(element), sequence);
+        }
+        const delta = Object.freeze({ ...element, version });
+        return Object.freeze({ key, value: utf8.encode(writeDelta(delta)), delta });
+    });
+}
+// ── the consumer ──
+/**
+ * A consumer that publishes a graph. Its handlers return elements; each is published to `producesTo`
+ * as a delta under its element key. It has no `produce` and no way to set a key, and it is discovered
+ * and hosted as an ordinary consumer.
+ */
+export class GraphConsumer {
+    graph = new Graph();
+    effects = new GraphEffects();
+    #metadata = {};
+    #client;
+    /** The change's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
+    get metadata() {
+        return this.#metadata;
+    }
+    get subject() {
+        return this.#metadata["ce-subject"] ?? "";
+    }
+    /** The change's sequence number, which is the version of every element that states none. */
+    get sequenceNumber() {
+        return sequenceNumberOf(this.#metadata);
+    }
+    get client() {
+        if (!this.#client)
+            throw new Error("client is only available inside onMessage or onDelete");
+        return this.#client;
+    }
+    /** @internal */
+    get _kind() {
+        return "consumer";
+    }
+    /** The source was deleted. Ignored unless this says otherwise; publish tombstones here. */
+    onDelete() {
+        return this.effects.ignore();
+    }
+    /** @internal */
+    _bind(metadata, client) {
+        this.#metadata = metadata;
+        this.#client = client;
+    }
+}

package/dist/index.d.ts

@@ -11,9 +11,10 @@ export { UpdateBuilder, KeyValueEffects, type UpdateEffect, type KeyValueReadOnl
 export { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder, workflowSettings, type WorkflowEffect, type WorkflowReadOnlyEffect, type WorkflowCommandEffect, type StepEffect, type StepOutcome, type StepRef, type PauseOptions, type WorkflowSettings, type StepSettings, type Recovery, } from "./effects/workflow.ts";
 export { Workflow, type WorkflowClass } from "./workflow.ts";
-export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type TimedActionEffect } from "./effects/stateless.ts";
+export { ViewEffects, ConsumerEffects, TimedActionEffects, type ViewEffect, type ConsumerEffect, type OutgoingMessage, type TimedActionEffect } from "./effects/stateless.ts";
 export { View, type ViewClass } from "./view.ts";
-export { Consumer, type ConsumerClass } from "./consumer.ts";
+export { Consumer, ProtocolVersionError, type ConsumerClass } from "./consumer.ts";
+export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, type Delta, type Element, type GraphConsumerClass, type GraphEffect, type GraphFault, type Properties, type PropertyValue, type Scalar, type Version, } from "./graph.ts";
 export { TimedAction, type TimedActionClass } from "./timedAction.ts";
 export { AgentEffects, type AgentEffect } from "./effects/agent.ts";
 export { Agent, type AgentClass } from "./agent.ts";

package/dist/index.js

@@ -24,7 +24,8 @@ export { WorkflowEffects, StepEffects, WorkflowUpdateBuilder, StepUpdateBuilder,
 export { Workflow } from "./workflow.js";
 export { ViewEffects, ConsumerEffects, TimedActionEffects } from "./effects/stateless.js";
 export { View } from "./view.js";
-export { Consumer } from "./consumer.js";
+export { Consumer, ProtocolVersionError } from "./consumer.js";
+export { GRAPH_DELTA_SCHEMA, Graph, GraphConsumer, GraphEffects, GraphError, edgeKey, elementKey, graphDeltaCodec, nodeKey, readDelta, } from "./graph.js";
 export { TimedAction } from "./timedAction.js";
 export { AgentEffects } from "./effects/agent.js";
 export { Agent } from "./agent.js";

package/dist/server/stateless.js

@@ -8,8 +8,12 @@ import { TimedAction as TimedActionService, TimedActionEffectSchema } from "../_
 import { codecFor } from "../codec.js";
 import { metadataFromProto, metadataToProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
+import { ProtocolVersionError, requireSeveralMessages } from "../consumer.js";
+import { GRAPH_DELTA_SCHEMA, deltaRecords } from "../graph.js";
+import { JSON_CONTENT } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { decodePayload, encodePayload } from "./payloads.js";
+import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 function messageOf(e) {
     return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
 }
@@ -41,33 +45,79 @@ export async function handleView(req, ctx) {
         throw new ConnectError(messageOf(e), Code.Internal);
     }
 }
+const DONE = () => create(ConsumerEffectSchema, { effect: { case: "done", value: {} } });
+const IGNORE = () => create(ConsumerEffectSchema, { effect: { case: "ignore", value: {} } });
+/**
+ * Several messages as the reply `produce_all`, which only a runtime at protocol 1.3 understands: the
+ * request must have said so. None at all is `done`, which every runtime understands and means the same.
+ */
+function produceAll(request, messages) {
+    if (messages.length === 0)
+        return DONE();
+    requireSeveralMessages(request);
+    return create(ConsumerEffectSchema, {
+        effect: {
+            case: "produceAll",
+            value: { messages: messages.map((m) => ({ payload: m.payload, metadata: metadataToProto(m.metadata), ...(m.key !== undefined ? { key: m.key } : {}) })) },
+        },
+    });
+}
+async function graphEffect(registered, req, metadata, ctx) {
+    const consumer = new registered.cls();
+    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+    switch (effect.kind) {
+        case "publish":
+            return produceAll(metadata, deltaRecords(effect, metadata).map((r) => ({
+                payload: create(PayloadSchema, { contentType: JSON_CONTENT, manifest: GRAPH_DELTA_SCHEMA, data: r.value }),
+                metadata: { "ce-type": GRAPH_DELTA_SCHEMA },
+                key: r.key,
+            })));
+        case "done":
+            return DONE();
+        case "ignore":
+            return IGNORE();
+        default:
+            throw new TypeError(`${registered.id}.onMessage returned something that is not a graph effect`);
+    }
+}
+async function consumerEffect(registered, req, metadata, ctx) {
+    const consumer = new registered.cls();
+    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+    const outCodec = () => {
+        if (!registered.outCodec)
+            throw new Error(`${registered.id} produced a message but declares no out shape`);
+        return registered.outCodec;
+    };
+    switch (effect.kind) {
+        case "produce":
+            return create(ConsumerEffectSchema, { effect: { case: "produce", value: { payload: encodePayload(outCodec(), effect.payload), metadata: metadataToProto(effect.metadata) } } });
+        case "produceAll":
+            return produceAll(metadata, effect.messages.map((m) => ({ payload: encodePayload(outCodec(), m.payload), metadata: m.metadata ?? {}, ...(m.key !== undefined ? { key: m.key } : {}) })));
+        case "done":
+            return DONE();
+        case "ignore":
+            return IGNORE();
+        default:
+            throw new TypeError(`${registered.id}.onMessage returned something that is not a consumer effect`);
+    }
+}
 export async function handleConsumer(req, ctx) {
     const registered = ctx.registry.of("consumer", req.componentId);
     if (!registered)
         throw new ConnectError(`no consumer ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
     const metadata = metadataFromProto(req.metadata);
-    const consumer = new registered.cls();
     try {
-        consumer._bind(metadata, ctx.client.withMetadata(metadata));
-        const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
-        switch (effect.kind) {
-            case "produce": {
-                if (!registered.outCodec)
-                    throw new Error(`${registered.id} produced a message but declares no out shape`);
-                return create(ConsumerEffectSchema, { effect: { case: "produce", value: { payload: encodePayload(registered.outCodec, effect.payload), metadata: metadataToProto(effect.metadata) } } });
-            }
-            case "done":
-                return create(ConsumerEffectSchema, { effect: { case: "done", value: {} } });
-            case "ignore":
-                return create(ConsumerEffectSchema, { effect: { case: "ignore", value: {} } });
-            default:
-                throw new TypeError(`${registered.id}.onMessage returned something that is not a consumer effect`);
-        }
+        return registered.graph ? await graphEffect(registered, req, metadata, ctx) : await consumerEffect(registered, req, metadata, ctx);
     }
     catch (e) {
         if (e instanceof ConnectError)
             throw e;
         ctx.log(`ankka: consumer ${registered.id} on ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        // The message alone, so the runtime's log says what the SDK needs and of which runtime.
+        if (e instanceof ProtocolVersionError)
+            throw new ConnectError(e.message, Code.Internal);
         throw new ConnectError(messageOf(e), Code.Internal);
     }
 }

package/dist/service.d.ts

@@ -4,6 +4,7 @@ import { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
 import { Workflow, type WorkflowClass } from "./workflow.ts";
 import { View, type ViewClass } from "./view.ts";
 import { Consumer, type ConsumerClass } from "./consumer.ts";
+import { GraphConsumer, type GraphConsumerClass } from "./graph.ts";
 import { TimedAction, type TimedActionClass } from "./timedAction.ts";
 import { Agent, type AgentClass } from "./agent.ts";
 import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
@@ -61,11 +62,13 @@ export interface RegisteredView {
 export interface RegisteredConsumer {
     readonly kind: "consumer";
     readonly id: string;
-    readonly cls: ConsumerClass<any, any, any>;
+    readonly cls: ConsumerClass<any, any, any> | GraphConsumerClass<any, any>;
     readonly source: Source;
     readonly messageCodec: Codec<any>;
     readonly outCodec: Codec<any> | undefined;
     readonly producesTo: string | undefined;
+    /** A graph consumer: its handlers return elements, each published as a delta under its element key. */
+    readonly graph: boolean;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";
@@ -134,6 +137,7 @@ export declare class ServiceBuilder {
     register<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>): this;
     register<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>): this;
     register<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>): this;
+    register<M, C extends GraphConsumer<M>>(cls: GraphConsumerClass<M, C>): this;
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;
     register<C extends Agent>(cls: AgentClass<C>): this;
     register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;

package/dist/service.js

@@ -9,6 +9,7 @@ import { KeyValueEntity } from "./keyValueEntity.js";
 import { Workflow } from "./workflow.js";
 import { View } from "./view.js";
 import { Consumer } from "./consumer.js";
+import { GraphConsumer, graphDeltaCodec } from "./graph.js";
 import { TimedAction } from "./timedAction.js";
 import { Agent } from "./agent.js";
 import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
@@ -97,6 +98,8 @@ export class ServiceBuilder {
                 add(registerView(cls, problems), cls);
             else if (extendsBase(cls, Consumer))
                 add(registerConsumer(cls, problems), cls);
+            else if (extendsBase(cls, GraphConsumer))
+                add(registerGraphConsumer(cls, problems), cls);
             else if (extendsBase(cls, TimedAction))
                 add(registerTimedAction(cls, problems), cls);
             else if (extendsBase(cls, Agent))
@@ -120,7 +123,7 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
             }
         }
         if (problems.length > 0)
@@ -274,6 +277,30 @@ function registerConsumer(cls, problems) {
         messageCodec: codecFor(cls.message),
         outCodec: cls.out ? codecFor(cls.out) : undefined,
         producesTo: cls.producesTo,
+        graph: false,
+    });
+}
+/** A graph consumer is a consumer to discovery and to the runtime: one that produces deltas to its topic. */
+function registerGraphConsumer(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const source = sourceOf(cls, fail);
+    requireShape(cls.message, "message: a schema or codec for the source's messages", fail);
+    if (typeof cls.producesTo !== "string" || cls.producesTo.trim() === "")
+        fail("needs a static producesTo: the topic its deltas are published to");
+    if (cls.out !== undefined)
+        fail("declares a static out, which a graph consumer does not have: what it produces is graph deltas");
+    if (!ok() || !source)
+        return undefined;
+    return Object.freeze({
+        kind: "consumer",
+        id: cls.componentId,
+        cls,
+        source,
+        messageCodec: codecFor(cls.message),
+        outCodec: graphDeltaCodec,
+        producesTo: cls.producesTo,
+        graph: true,
     });
 }
 function registerTimedAction(cls, problems) {

package/dist/spec.d.ts

@@ -2,7 +2,7 @@ import { type MessageInitShape } from "@bufbuild/protobuf";
 import { Endpoint_Acl, type CallerMatcherSchema, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
 import type { Registry } from "./service.ts";
 import type { Acl } from "./routes.ts";
-export declare const PROTOCOL_VERSION = "1.2";
+export declare const PROTOCOL_VERSION = "1.3";
 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

@@ -6,7 +6,7 @@ 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.2";
+export const PROTOCOL_VERSION = "1.3";
 export const SDK_NAME = "ankka-typescript";
 export function aclToProto(acl) {
     if (typeof acl === "object")

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, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, } from "./kinds.ts";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, 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, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, GraphConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
 export { AnkkaTestKit, PUBLISHED_SIDECAR, sidecarImage } from "./integration.js";

package/dist/testkit/kinds.d.ts

@@ -5,7 +5,8 @@ import type { ConsumerEffect, TimedActionEffect, ViewEffect } from "../effects/s
 import type { KeyValueEntity, KeyValueEntityClass } from "../keyValueEntity.ts";
 import type { Workflow, WorkflowClass } from "../workflow.ts";
 import type { View, ViewClass } from "../view.ts";
-import type { Consumer, ConsumerClass } from "../consumer.ts";
+import { type Consumer, type ConsumerClass } from "../consumer.ts";
+import { type Delta, type GraphConsumerClass } from "../graph.ts";
 import type { TimedAction, TimedActionClass } from "../timedAction.ts";
 import type { Agent, AgentClass } from "../agent.ts";
 import type { HandlerRef } from "../handlers.ts";
@@ -62,17 +63,45 @@ export declare class ViewTestKit<E, Row, C extends View<E, Row>> {
 /** Feeds a consumer messages and collects what it produced. */
 export declare class ConsumerTestKit<M, Out, C extends Consumer<M, Out>> {
     #private;
-    /** Everything `produce` sent, round-tripped through the out codec. */
+    /**
+     * Everything the consumer produced, one entry per message, round-tripped through the out codec.
+     * `key` is the record key a message of `produceAll` named; absent, the message is keyed by its subject.
+     */
     readonly produced: {
         readonly payload: Out;
         readonly metadata: Metadata;
+        readonly key?: string;
     }[];
     private constructor();
     static of<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>, client?: ComponentClient): ConsumerTestKit<M, Out, C>;
-    /** A message from source instance `subject`. */
+    /**
+     * A message from source instance `subject`. The metadata says the runtime speaks this SDK's protocol
+     * version; pass `"ankka.protocol"` or `"ankka.sequence"` to say otherwise.
+     */
     onMessage(message: M, subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
     onDelete(subject?: string, metadata?: Metadata): Promise<ConsumerEffect<Out>>;
 }
+/**
+ * Feeds a graph consumer changes and answers with the elements it published: each read back from the
+ * bytes that would be published, under the key it would be published under, so a test asserts on what
+ * a reader of the topic sees.
+ */
+export declare class GraphConsumerTestKit<M> {
+    #private;
+    private constructor();
+    static of<M>(cls: GraphConsumerClass<M>, client?: ComponentClient): GraphConsumerTestKit<M>;
+    /** A change from source instance `subject` (default `"test"`) at `sequence` (default 1). */
+    onMessage(message: M, options?: GraphChange): Promise<Delta[]>;
+    /** The source instance was deleted, at `sequence`. */
+    onDelete(options?: GraphChange): Promise<Delta[]>;
+}
+/** The change a graph consumer is handed: whose it is and where in that instance's history. */
+export interface GraphChange {
+    readonly subject?: string;
+    /** The change's sequence number; `0` is a source with none, as a topic is. */
+    readonly sequence?: number | bigint;
+    readonly metadata?: Metadata;
+}
 /** Invokes a timed action's handlers as the sweeper would. */
 export declare class TimedActionTestKit<C extends TimedAction> {
     #private;

package/dist/testkit/kinds.js

@@ -5,6 +5,9 @@ import { ComponentClient, noClient } from "../client.js";
 import { binaryCodecs, codecFor } from "../codec.js";
 import { commandContext } from "../context.js";
 import { CommandError, ErrorCode } from "../effects/common.js";
+import { PROTOCOL_KEY, requireSeveralMessages } from "../consumer.js";
+import { deltaRecords, readDelta } from "../graph.js";
+import { PROTOCOL_VERSION } from "../spec.js";
 import { materialiseKeyValue, materialiseStep, materialiseWorkflowCommand } from "../materialise.js";
 import { Ankka } from "../service.js";
 import { checkPlan, runTool } from "../server/agent.js";
@@ -229,7 +232,10 @@ export class ConsumerTestKit {
     #registered;
     #cls;
     #client;
-    /** Everything `produce` sent, round-tripped through the out codec. */
+    /**
+     * Everything the consumer produced, one entry per message, round-tripped through the out codec.
+     * `key` is the record key a message of `produceAll` named; absent, the message is keyed by its subject.
+     */
     produced = [];
     constructor(cls, client) {
         this.#registered = registryFor(cls, client).component(cls.componentId);
@@ -243,21 +249,75 @@ export class ConsumerTestKit {
         const consumer = new this.#cls();
         consumer._bind(metadata, this.#client.withMetadata(metadata));
         const effect = await fn(consumer);
-        if (effect.kind === "produce") {
-            const outCodec = this.#registered.outCodec;
-            if (!outCodec)
+        const outCodec = () => {
+            const codec = this.#registered.outCodec;
+            if (!codec)
                 throw new Error(`${this.#registered.id} produced a message but declares no out shape`);
-            this.produced.push({ payload: roundTrip(outCodec, effect.payload), metadata: effect.metadata });
+            return codec;
+        };
+        if (effect.kind === "produce") {
+            this.produced.push({ payload: roundTrip(outCodec(), effect.payload), metadata: effect.metadata });
+        }
+        else if (effect.kind === "produceAll" && effect.messages.length > 0) {
+            // The server's rule: several messages go only to a runtime that said it accepts them.
+            requireSeveralMessages(metadata);
+            for (const m of effect.messages) {
+                this.produced.push({ payload: roundTrip(outCodec(), m.payload), metadata: m.metadata ?? {}, ...(m.key !== undefined ? { key: m.key } : {}) });
+            }
         }
         return effect;
     }
-    /** A message from source instance `subject`. */
+    /**
+     * A message from source instance `subject`. The metadata says the runtime speaks this SDK's protocol
+     * version; pass `"ankka.protocol"` or `"ankka.sequence"` to say otherwise.
+     */
     onMessage(message, subject = "test", metadata = {}) {
         const wire = roundTrip(this.#registered.messageCodec, message);
-        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, ...metadata });
+        return this.#apply((c) => c.onMessage(wire), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
     }
     onDelete(subject = "test", metadata = {}) {
-        return this.#apply((c) => c.onDelete(), { "ce-subject": subject, ...metadata });
+        return this.#apply((c) => c.onDelete(), { "ce-subject": subject, [PROTOCOL_KEY]: PROTOCOL_VERSION, ...metadata });
+    }
+}
+/**
+ * Feeds a graph consumer changes and answers with the elements it published: each read back from the
+ * bytes that would be published, under the key it would be published under, so a test asserts on what
+ * a reader of the topic sees.
+ */
+export class GraphConsumerTestKit {
+    #registered;
+    #cls;
+    #client;
+    constructor(cls, client) {
+        this.#registered = registryFor(cls, client).component(cls.componentId);
+        this.#cls = cls;
+        this.#client = client;
+    }
+    static of(cls, client = noClient()) {
+        return new GraphConsumerTestKit(cls, client);
+    }
+    async #apply(fn, options) {
+        const metadata = {
+            "ce-subject": options.subject ?? "test",
+            "ankka.sequence": String(options.sequence ?? 1),
+            [PROTOCOL_KEY]: PROTOCOL_VERSION,
+            ...options.metadata,
+        };
+        const consumer = new this.#cls();
+        consumer._bind(metadata, this.#client.withMetadata(metadata));
+        const records = deltaRecords(await fn(consumer), metadata);
+        if (records.length > 0)
+            requireSeveralMessages(metadata);
+        return records.map((r) => readDelta(r.value, r.key));
+    }
+    /** A change from source instance `subject` (default `"test"`) at `sequence` (default 1). */
+    onMessage(message, options = {}) {
+        const wire = roundTrip(this.#registered.messageCodec, message);
+        return this.#apply((c) => c.onMessage(wire), options);
+    }
+    /** The source instance was deleted, at `sequence`. */
+    onDelete(options = {}) {
+        return this.#apply((c) => c.onDelete(), options);
     }
 }
 /** Invokes a timed action's handlers as the sweeper would. */

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.9.1";
+export declare const VERSION = "0.10.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Written by scripts/proto.ts from package.json; do not edit. 0.0.0 in the tree, the tag's version in a release.
-export const VERSION = "0.9.1";
+export const VERSION = "0.10.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ankka",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Build services on ankka in TypeScript: entities, views, workflows, agents and endpoints hosted by the ankka sidecar.",
   "license": "Apache-2.0",
   "type": "module",