ankka 0.11.0 → 0.12.0

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type Client as ConnectClient, type Transport } from "@connectrpc/connect";
 import { Client } from "./_proto/ankka/protocol/v1/client_pb.ts";
 import { jsonCodec, type Shape } from "./codec.ts";
-import { type Metadata } from "./effects/common.ts";
+import { CommandError, type Metadata } from "./effects/common.ts";
 import type { HandlerRef } from "./handlers.ts";
 import { type ComponentKind } from "./kinds.ts";
 import { Duration } from "./time.ts";
@@ -19,15 +19,38 @@ interface Connection {
     transport: Transport | undefined;
     stub: ConnectClient<typeof Client> | undefined;
 }
+/** The first protocol whose runtime can wait for a workflow's end; an older one answers `UNIMPLEMENTED`. */
+export declare const AWAIT_SINCE = "1.18";
+/** One part of a wait served as a stream: the wait goes on, or how it ended. */
+export type AwaitPart<S> = {
+    readonly kind: "heartbeat";
+} | {
+    readonly kind: "ended";
+    readonly state: S;
+} | {
+    readonly kind: "failed";
+    readonly error: CommandError;
+} | {
+    readonly kind: "timed-out";
+    readonly message: string;
+};
+/** A part as one line of JSON, which is what an `sse` route yields for it. */
+export declare function awaitPartJson<S>(part: AwaitPart<S>): string;
 /** One call, ready to invoke or stream. */
 export declare class Invocation<I, R> {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined);
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, name: string, input: Shape<I> | undefined, reply: Shape<R> | undefined, state?: Shape<unknown>);
     /**
      * Invokes and decodes the reply; a refusal rejects with `CommandError`. An agent's turn that waits for a
      * person rejects with `ApprovalAwaited`; `ask` answers it instead.
      */
     invoke(input?: I): Promise<R>;
+    /**
+     * Sends this command to the workflow and then waits for its end, as one call: answered with the state it
+     * ended with, within `timeoutMillis` of the command being sent. A refusal of the command rejects at once and
+     * no wait begins; the command's own reply is not kept. `state` decodes it, unless the workflow class did.
+     */
+    thenAwaitEnd<S>(timeoutMillis: number, state?: Shape<S>): AwaitingInvocation<I, S>;
     /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
     ask(input?: I): Promise<AgentOutcome<R>>;
     /**
@@ -43,12 +66,31 @@ export declare class Invocation<I, R> {
         kind: "awaiting-approval";
     }>>;
 }
+/** A command to a workflow followed by a wait for its end, with one deadline from the send. */
+export declare class AwaitingInvocation<I, S> {
+    #private;
+    constructor(timeoutMillis: number, send: (input: I | undefined) => Promise<unknown>, wait: (leftMillis: number) => Promise<S>);
+    /** Sends the command and waits for the end; rejects as `Calls.awaitEnd` does. */
+    invoke(input?: I): Promise<S>;
+}
 /** Calls on one component instance, by wire name. */
 export declare class Calls {
     #private;
-    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string);
+    constructor(connection: Connection, metadata: Metadata, kind: ComponentKind, componentId: string, entityId: string, state?: Shape<unknown>);
     /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
     call<I = undefined, R = unknown>(name: string, input?: Shape<I>, reply?: Shape<R>): Invocation<I, R>;
+    /**
+     * Waits for this workflow's end, for at most `timeoutMillis`, and resolves with the state it ended with — at
+     * once when it already has. A workflow that failed or was deleted rejects with `CommandError` whose code is
+     * `WORKFLOW_FAILED` and whose `details` hold `step`, `reason` and `deleted`; a wait not answered in time
+     * rejects with `TIMEOUT` and the workflow runs on. A paused workflow has not ended. There is no default.
+     */
+    awaitEnd<S>(timeoutMillis: number, state?: Shape<S>): Promise<S>;
+    /**
+     * The same wait as a stream, for an `sse` route that must outlast the idle timeout: a heartbeat while it goes
+     * on, then exactly one `ended`, `failed` or `timed-out` part. `awaitPartJson` renders a part as a line.
+     */
+    awaitEndParts<S>(timeoutMillis: number, state?: Shape<S>): AsyncIterable<AwaitPart<S>>;
 }
 /** Calls on one component instance through its class's handler table, fully typed. */
 export declare class TypedCalls<C> {
@@ -56,7 +98,41 @@ export declare class TypedCalls<C> {
     constructor(calls: Calls);
     /** `call(ShoppingCartEntity.handlers.addItem)`: the handler's wire name and shapes come from the declaration. */
     call<I, R>(handler: HandlerRef<C, I, R, any>): Invocation<I, R>;
+    /** For a workflow: waits for its end and resolves with its state, decoded as the class declares it. */
+    awaitEnd<S = StateOf<C>>(timeoutMillis: number): Promise<S>;
+    /** For a workflow: the same wait as a stream of parts. */
+    awaitEndParts<S = StateOf<C>>(timeoutMillis: number): AsyncIterable<AwaitPart<S>>;
+}
+/** The first protocol in which a view's query can be streamed and watched. */
+export declare const VIEW_STREAMS_SINCE = "1.17";
+/** What a watch of a view gives: a row as the query sees it now, a removal of one it gave, or the caught-up marker. */
+export type WatchEvent<Row> = {
+    readonly kind: "row";
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly kind: "removed";
+    readonly key: string;
+} | {
+    readonly kind: "caughtUp";
+};
+/** What a watch does past its unread bound: none slows the view. */
+export type Overflow = "dropHead" | "dropTail" | "dropNew" | "dropAll" | "fail";
+export interface WatchOptions {
+    /** How many unread rows the watch holds, one per key; the instance's own bound when absent. */
+    readonly unread?: number;
+    /** What it does past that bound; `dropHead`, the row changed longest ago, when absent. */
+    readonly overflow?: Overflow;
 }
+/** A watch ended for `reason`: `rebuilt`, `instance-stopping`, `listener-lost` or `unread`. Watch again for the rows now. */
+export declare class WatchEnded extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/** A workflow instance's state type, read from its `state` getter. */
+type StateOf<C> = C extends {
+    readonly state: infer S;
+} ? S : unknown;
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export declare class Views {
     #private;
@@ -69,6 +145,23 @@ export declare class Views {
      * `limit` rows, 1000 when it is not given, in the statement's own order.
      */
     ask<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, limit?: number): Promise<Row[]>;
+    /**
+     * The rows of `all` or one of a view's declared queries as the database yields them: nothing
+     * collected, and no limit unless one is given. A statement the database ends, or a reader that
+     * takes nothing for its timeout, throws.
+     */
+    stream<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: {
+        readonly limit?: number;
+    }): AsyncIterable<Row>;
+    /**
+     * A watch of one of a view's declared queries, declared `{ watched: true }`: every row it matches
+     * now, then `caughtUp`, then each row as it is written and matches and a `removed` for each given row
+     * that stops matching. Throws `WatchEnded` when it ends with a reason. `unread` bounds the rows held
+     * for a reader that has not read them, and `overflow` says what happens past that bound.
+     */
+    watch<Row>(viewId: string, name: string, values: Readonly<Record<string, string>>, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
+    /** A watch of one row by its key: the row now, then `caughtUp`, then each version and a `removed` when it is deleted. */
+    watchRow<Row>(viewId: string, key: string, row: Shape<Row>, options?: WatchOptions): AsyncIterable<WatchEvent<Row>>;
 }
 /** What a timer fires: a component class and one of its handlers, or the same by name. */
 export type TimerTarget = {

package/dist/client.js

@@ -5,7 +5,7 @@
 // so the sidecar records the call as a child span.
 import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
-import { Client } from "./_proto/ankka/protocol/v1/client_pb.js";
+import { Client, Overflow as ProtoOverflow } from "./_proto/ankka/protocol/v1/client_pb.js";
 import { codecFor, jsonCodec, isCodec, textCodecs, binaryCodecs, codecForManifest } from "./codec.js";
 import { CommandError } from "./effects/common.js";
 import { decodeJsonValue, reviver } from "./json.js";
@@ -24,7 +24,28 @@ function stubOf(connection) {
     return connection.stub;
 }
 function errorOf(error) {
-    return { message: error.message, code: errorCodeFromProto(error.code) };
+    return { message: error.message, code: errorCodeFromProto(error.code), details: { ...(error.details ?? {}) } };
+}
+/** The first protocol whose runtime can wait for a workflow's end; an older one answers `UNIMPLEMENTED`. */
+export const AWAIT_SINCE = "1.18";
+/** A part as one line of JSON, which is what an `sse` route yields for it. */
+export function awaitPartJson(part) {
+    switch (part.kind) {
+        case "heartbeat":
+            return JSON.stringify({ heartbeat: true });
+        case "ended":
+            return JSON.stringify({ ended: part.state });
+        case "failed":
+            return JSON.stringify({ failed: { code: part.error.code, message: part.error.message, ...part.error.details } });
+        case "timed-out":
+            return JSON.stringify({ timedOut: true });
+    }
+}
+function timeoutOf(timeoutMillis) {
+    if (!(timeoutMillis > 0)) {
+        throw new CommandError({ message: `a wait for a workflow's end needs a timeout of more than zero, not ${timeoutMillis}`, code: "BAD_REQUEST" });
+    }
+    return Math.max(1, Math.floor(timeoutMillis));
 }
 function inputPayload(shape, input) {
     if (shape === undefined) {
@@ -88,7 +109,9 @@ export class Invocation {
     #name;
     #input;
     #reply;
-    constructor(connection, metadata, kind, componentId, entityId, name, input, reply) {
+    #state;
+    constructor(connection, metadata, kind, componentId, entityId, name, input, reply, state) {
+        this.#state = state;
         this.#connection = connection;
         this.#metadata = metadata;
         this.#kind = kind;
@@ -118,6 +141,16 @@ export class Invocation {
             throw new ApprovalAwaited(outcome.requests);
         return outcome.value;
     }
+    /**
+     * Sends this command to the workflow and then waits for its end, as one call: answered with the state it
+     * ended with, within `timeoutMillis` of the command being sent. A refusal of the command rejects at once and
+     * no wait begins; the command's own reply is not kept. `state` decodes it, unless the workflow class did.
+     */
+    thenAwaitEnd(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        const calls = new Calls(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, shape);
+        return new AwaitingInvocation(timeoutMillis, (input) => this.invoke(input), (left) => calls.awaitEnd(left));
+    }
     /** Calls an agent's handler for its outcome: the model's answer, or the approval requests the turn waits on. */
     async ask(input) {
         return outcomeOf(this.#reply, await stubOf(this.#connection).invoke(this.#request(input)));
@@ -156,6 +189,32 @@ export class Invocation {
         }
     }
 }
+/** A command to a workflow followed by a wait for its end, with one deadline from the send. */
+export class AwaitingInvocation {
+    #timeoutMillis;
+    #send;
+    #await;
+    constructor(timeoutMillis, send, wait) {
+        this.#timeoutMillis = timeoutMillis;
+        this.#send = send;
+        this.#await = wait;
+    }
+    /** Sends the command and waits for the end; rejects as `Calls.awaitEnd` does. */
+    async invoke(input) {
+        const deadline = Date.now() + timeoutOf(this.#timeoutMillis);
+        await this.#send(input);
+        return await this.#await(Math.max(1, deadline - Date.now()));
+    }
+}
+const awaitTooOld = (failure) => {
+    if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+        throw new CommandError({
+            message: `the runtime beside this process is too old for waiting for a workflow's end, which needs protocol ${AWAIT_SINCE}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+            code: "UNAVAILABLE",
+        });
+    }
+    throw failure;
+};
 /** Calls on one component instance, by wire name. */
 export class Calls {
     #connection;
@@ -163,16 +222,67 @@ export class Calls {
     #kind;
     #componentId;
     #entityId;
-    constructor(connection, metadata, kind, componentId, entityId) {
+    #state;
+    constructor(connection, metadata, kind, componentId, entityId, state) {
         this.#connection = connection;
         this.#metadata = metadata;
         this.#kind = kind;
         this.#componentId = componentId;
         this.#entityId = entityId;
+        this.#state = state;
     }
     /** `call("add-item", LineItem, Done)`: the wire name, the input shape (omit for none) and the reply shape (omit for `done`). */
     call(name, input, reply) {
-        return new Invocation(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, name, input, reply);
+        return new Invocation(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, name, input, reply, this.#state);
+    }
+    #awaitRequest(timeoutMillis) {
+        return {
+            componentId: this.#componentId,
+            entityId: this.#entityId,
+            timeoutMillis: BigInt(timeoutOf(timeoutMillis)),
+            metadata: metadataToProto(this.#metadata),
+        };
+    }
+    /**
+     * Waits for this workflow's end, for at most `timeoutMillis`, and resolves with the state it ended with — at
+     * once when it already has. A workflow that failed or was deleted rejects with `CommandError` whose code is
+     * `WORKFLOW_FAILED` and whose `details` hold `step`, `reason` and `deleted`; a wait not answered in time
+     * rejects with `TIMEOUT` and the workflow runs on. A paused workflow has not ended. There is no default.
+     */
+    async awaitEnd(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        const answer = await stubOf(this.#connection).awaitEnd(this.#awaitRequest(timeoutMillis)).catch(awaitTooOld);
+        const outcome = outcomeOf(shape, answer);
+        if (outcome.kind !== "answered")
+            throw new CommandError({ message: "a workflow answered a wait as an agent", code: "INTERNAL" });
+        return outcome.value;
+    }
+    /**
+     * The same wait as a stream, for an `sse` route that must outlast the idle timeout: a heartbeat while it goes
+     * on, then exactly one `ended`, `failed` or `timed-out` part. `awaitPartJson` renders a part as a line.
+     */
+    async *awaitEndParts(timeoutMillis, state) {
+        const shape = (state ?? this.#state);
+        try {
+            for await (const token of stubOf(this.#connection).awaitEndStream(this.#awaitRequest(timeoutMillis))) {
+                switch (token.token.case) {
+                    case "heartbeat":
+                        yield { kind: "heartbeat" };
+                        break;
+                    case "ended":
+                        yield { kind: "ended", state: decodeReply(shape, token.token.value) };
+                        return;
+                    case "failed": {
+                        const error = new CommandError(errorOf(token.token.value));
+                        yield error.code === "TIMEOUT" ? { kind: "timed-out", message: error.message } : { kind: "failed", error };
+                        return;
+                    }
+                }
+            }
+        }
+        catch (failure) {
+            awaitTooOld(failure);
+        }
     }
 }
 /** Calls on one component instance through its class's handler table, fully typed. */
@@ -185,6 +295,39 @@ export class TypedCalls {
     call(handler) {
         return this.#calls.call(handler.name, handler.input, handler.reply);
     }
+    /** For a workflow: waits for its end and resolves with its state, decoded as the class declares it. */
+    awaitEnd(timeoutMillis) {
+        return this.#calls.awaitEnd(timeoutMillis);
+    }
+    /** For a workflow: the same wait as a stream of parts. */
+    awaitEndParts(timeoutMillis) {
+        return this.#calls.awaitEndParts(timeoutMillis);
+    }
+}
+/** The first protocol in which a view's query can be streamed and watched. */
+export const VIEW_STREAMS_SINCE = "1.17";
+/** A watch ended for `reason`: `rebuilt`, `instance-stopping`, `listener-lost` or `unread`. Watch again for the rows now. */
+export class WatchEnded extends Error {
+    reason;
+    constructor(reason) {
+        super(`the watch ended: ${reason}`);
+        this.name = "WatchEnded";
+        this.reason = reason;
+    }
+}
+function overflowToProto(overflow) {
+    switch (overflow) {
+        case "dropHead":
+            return ProtoOverflow.DROP_HEAD;
+        case "dropTail":
+            return ProtoOverflow.DROP_TAIL;
+        case "dropNew":
+            return ProtoOverflow.DROP_NEW;
+        case "dropAll":
+            return ProtoOverflow.DROP_ALL;
+        case "fail":
+            return ProtoOverflow.FAIL;
+    }
 }
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export class Views {
@@ -219,6 +362,83 @@ export class Views {
         });
         return Views.#rows(answer, row);
     }
+    /**
+     * The rows of `all` or one of a view's declared queries as the database yields them: nothing
+     * collected, and no limit unless one is given. A statement the database ends, or a reader that
+     * takes nothing for its timeout, throws.
+     */
+    async *stream(viewId, name, values, row, options = {}) {
+        const frames = stubOf(this.#connection).queryStream({
+            viewId,
+            name,
+            metadata: metadataToProto(this.#metadata),
+            values: { ...values },
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        });
+        for await (const event of Views.#frames(frames, row))
+            if (event.kind === "row")
+                yield event.row;
+    }
+    /**
+     * A watch of one of a view's declared queries, declared `{ watched: true }`: every row it matches
+     * now, then `caughtUp`, then each row as it is written and matches and a `removed` for each given row
+     * that stops matching. Throws `WatchEnded` when it ends with a reason. `unread` bounds the rows held
+     * for a reader that has not read them, and `overflow` says what happens past that bound.
+     */
+    async *watch(viewId, name, values, row, options = {}) {
+        const frames = stubOf(this.#connection).watch({
+            viewId,
+            metadata: metadataToProto(this.#metadata),
+            target: { case: "named", value: { name, values: { ...values } } },
+            ...(options.unread !== undefined ? { unreadBound: options.unread } : {}),
+            overflow: overflowToProto(options.overflow ?? "dropHead"),
+        });
+        yield* Views.#frames(frames, row);
+    }
+    /** A watch of one row by its key: the row now, then `caughtUp`, then each version and a `removed` when it is deleted. */
+    async *watchRow(viewId, key, row, options = {}) {
+        const frames = stubOf(this.#connection).watch({
+            viewId,
+            metadata: metadataToProto(this.#metadata),
+            target: { case: "key", value: key },
+            ...(options.unread !== undefined ? { unreadBound: options.unread } : {}),
+            overflow: overflowToProto(options.overflow ?? "dropHead"),
+        });
+        yield* Views.#frames(frames, row);
+    }
+    static async *#frames(frames, row) {
+        const codec = isCodec(row) ? row : codecFor(row);
+        try {
+            for await (const frame of frames) {
+                switch (frame.frame.case) {
+                    case "row":
+                        yield { kind: "row", key: frame.frame.value.key, row: codec.decode(frame.frame.value.payload?.data ?? new Uint8Array()) };
+                        break;
+                    case "removed":
+                        yield { kind: "removed", key: frame.frame.value.key };
+                        break;
+                    case "caughtUp":
+                        yield { kind: "caughtUp" };
+                        break;
+                    case "ended":
+                        throw new WatchEnded(frame.frame.value.reason);
+                    case "failed":
+                        throw new CommandError(errorOf(frame.frame.value));
+                    default:
+                        return;
+                }
+            }
+        }
+        catch (failure) {
+            if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+                throw new CommandError({
+                    message: `the runtime beside this process does not offer view streams, which need protocol ${VIEW_STREAMS_SINCE} (this SDK speaks ${PROTOCOL_VERSION}): ${failure.rawMessage}`,
+                    code: "INTERNAL",
+                });
+            }
+            throw failure;
+        }
+    }
     static #rows(answer, row) {
         switch (answer.result.case) {
             case "rows": {
@@ -517,7 +737,9 @@ export class ComponentClient {
     }
     /** Typed calls through a component class's handler table: `client.of(ShoppingCartEntity, cartId).call(ShoppingCartEntity.handlers.addItem).invoke(item)`. */
     of(component, entityId) {
-        return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId));
+        // A workflow class declares its state's shape: what a wait for its end decodes the state with.
+        const state = component.state;
+        return new TypedCalls(new Calls(this.#connection, this.#metadata, component.prototype._kind, component.componentId, entityId, state));
     }
 }
 /** A client for unit tests: every call throws, naming what was attempted. */

package/dist/consumer.d.ts

@@ -5,6 +5,7 @@ import type { Metadata } from "./effects/common.ts";
 import { type ComponentClient, type ComponentRef, type Secrets } from "./client.ts";
 import { ConsumerEffects, type ConsumerEffect } from "./effects/stateless.ts";
 import { type Services } from "./services.ts";
+import type { Standing } from "./standing.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";
@@ -26,8 +27,14 @@ export declare abstract class Consumer<M, Out = never> {
     /** The message's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata(): Metadata;
     get subject(): string;
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing(): Standing | undefined;
     /** The change's sequence number: an event's, or a key value state's revision. `0n` for a topic's message. */
     get sequenceNumber(): bigint | undefined;
+    /** Of a replicated entity's change (1.19): the installation that wrote it. `undefined` otherwise. */
+    get installation(): string | undefined;
+    /** Whether the change was written at this installation: `false` only for a replicated entity's mirrored change. */
+    get localOrigin(): boolean;
     get client(): ComponentClient;
     /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
     get secrets(): Secrets;
@@ -43,7 +50,7 @@ export declare abstract class Consumer<M, Out = never> {
     /** The source was deleted. Ignored unless this says otherwise. */
     onDelete(): MaybePromise<ConsumerEffect<Out>>;
     /** @internal */
-    _bind(metadata: Metadata, client: ComponentClient): void;
+    _bind(metadata: Metadata, client: ComponentClient, standing?: Standing): void;
 }
 export interface ConsumerClass<M = unknown, Out = unknown, C extends Consumer<M, Out> = Consumer<M, Out>> {
     new (): C;
@@ -58,6 +65,11 @@ export interface ConsumerClass<M = unknown, Out = unknown, C extends Consumer<M,
     readonly contract?: Contract;
     /** The declared broker the topic read is on; absent is the installation's. */
     readonly broker?: string;
+    /**
+     * Another project's topic (1.15): the id of the project whose topic `topic` is. The broker serves it
+     * while that project grants this service consume on it.
+     */
+    readonly project?: string;
     /** Whether the partitions an instance holds are handled at once, each in order. */
     readonly parallel?: boolean;
     readonly message: Shape<M>;
@@ -65,5 +77,10 @@ export interface ConsumerClass<M = unknown, Out = unknown, C extends Consumer<M,
     readonly out?: Shape<Out>;
     /** The topic produced to: its name, or a `Publication` with the contract stated for it and its broker. */
     readonly producesTo?: string | Publication;
+    /**
+     * A consumer that publishes is given a replicated entity's changes written at other installations
+     * too only when this says so (1.19); otherwise each is published once, where it was written.
+     */
+    readonly mirroredChanges?: boolean;
 }
 export {};

package/dist/consumer.js

@@ -31,6 +31,7 @@ export function sequenceNumberOf(metadata) {
 export class Consumer {
     effects = new ConsumerEffects();
     #metadata = {};
+    #standing = undefined;
     #client;
     /** The message's metadata: `ce-subject` is the source instance's id, `ankka.sequence` its sequence number. */
     get metadata() {
@@ -39,10 +40,22 @@ export class Consumer {
     get subject() {
         return this.#metadata["ce-subject"] ?? "";
     }
+    /** Of a change from a workflow: where it stood once the effect that recorded the state was applied. `undefined` for a change from an entity or a topic. */
+    get standing() {
+        return this.#standing;
+    }
     /** The change's sequence number: an event's, or a key value state's revision. `0n` for a topic's message. */
     get sequenceNumber() {
         return sequenceNumberOf(this.#metadata);
     }
+    /** Of a replicated entity's change (1.19): the installation that wrote it. `undefined` otherwise. */
+    get installation() {
+        return this.#metadata["ankka.installation"];
+    }
+    /** Whether the change was written at this installation: `false` only for a replicated entity's mirrored change. */
+    get localOrigin() {
+        return this.#metadata["ankka.local"] !== "false";
+    }
     get client() {
         if (!this.#client)
             throw new Error("client is only available inside onMessage or onDelete");
@@ -75,8 +88,9 @@ export class Consumer {
         return this.effects.ignore();
     }
     /** @internal */
-    _bind(metadata, client) {
+    _bind(metadata, client, standing) {
         this.#metadata = metadata;
+        this.#standing = standing;
         this.#client = client;
     }
 }

package/dist/context.d.ts

@@ -10,8 +10,26 @@ export interface CommandContext {
     readonly metadata: Metadata;
     /** The current instant; a seam a test can replace. */
     now(): Instant;
+    /** The installation handling the command, for a replicated entity (1.19); `null` when none is named. */
+    readonly installation: string | null;
+    /**
+     * Whether this installation is the replicated entity's home. A command that may persist runs only at
+     * the home, so this is `false` only for a query a follower answers; `true` for an entity not replicated.
+     */
+    readonly isHome: boolean;
 }
-export declare function commandContext(componentId: string, entityId: string, sequenceNumber: bigint, metadata: Metadata, now?: () => Instant): CommandContext;
+export declare function commandContext(componentId: string, entityId: string, sequenceNumber: bigint, metadata: Metadata, now?: () => Instant, installation?: string | null, isHome?: boolean): CommandContext;
+/**
+ * Where the event `applyEvent` is applying was written (1.19): the installation (`null` when none is
+ * named; an event from before replication reads as written at the home), whether that was this
+ * installation, and its sequence number. The third argument of `applyEvent`.
+ */
+export interface EventContext {
+    readonly installation: string | null;
+    readonly isLocal: boolean;
+    readonly sequence: bigint;
+}
+export declare function eventContext(installation: string | null, isLocal: boolean, sequence: bigint): EventContext;
 export declare function metadataFromProto(proto: ProtoMetadata | undefined): Metadata;
 export declare function metadataToProto(metadata: Metadata | undefined): {
     entries: {
@@ -41,6 +59,12 @@ export type Caller = {
     readonly kind: "service";
     readonly project: string;
     readonly name: string;
+}
+/** A machine registered on an organization, proven by a token the control plane issued (protocol 1.15). */
+ | {
+    readonly kind: "machine";
+    readonly organization: string;
+    readonly name: string;
 } | {
     readonly kind: "local";
 };

package/dist/context.js

@@ -4,8 +4,11 @@
 // request per asynchronous context, and work handed to another context cannot see it.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Instant } from "./time.js";
-export function commandContext(componentId, entityId, sequenceNumber, metadata, now = Instant.now) {
-    return Object.freeze({ componentId, entityId, sequenceNumber, metadata, now });
+export function commandContext(componentId, entityId, sequenceNumber, metadata, now = Instant.now, installation = null, isHome = true) {
+    return Object.freeze({ componentId, entityId, sequenceNumber, metadata, now, installation, isHome });
+}
+export function eventContext(installation, isLocal, sequence) {
+    return Object.freeze({ installation, isLocal, sequence });
 }
 export function metadataFromProto(proto) {
     const out = {};

package/dist/contract.d.ts

@@ -31,6 +31,10 @@ export interface Publication {
     readonly topic: string;
     readonly contract?: Contract;
     readonly broker?: string;
+    /** Another project's topic (1.15), which that project must grant this service produce on. */
+    readonly project?: string;
 }
+/** The first protocol in which a process can read or publish to another project's topic. */
+export declare const GRANTS_PROTOCOL: readonly [number, number];
 /** The first protocol in which a process can declare a contract, a broker or parallel reading. */
 export declare const CONTRACT_PROTOCOL: readonly [number, number];

package/dist/contract.js

@@ -54,5 +54,7 @@ export function fingerprintOf(document) {
         throw new TypeError("a schema document must be JSON");
     return "sha256:" + createHash("sha256").update(canonical, "utf8").digest("hex");
 }
+/** The first protocol in which a process can read or publish to another project's topic. */
+export const GRANTS_PROTOCOL = [1, 15];
 /** The first protocol in which a process can declare a contract, a broker or parallel reading. */
 export const CONTRACT_PROTOCOL = [1, 14];

package/dist/effects/common.d.ts

@@ -9,6 +9,10 @@ export declare const ErrorCode: Readonly<{
     readonly Conflict: "CONFLICT";
     readonly Timeout: "TIMEOUT";
     readonly Unavailable: "UNAVAILABLE";
+    /** A workflow a caller waited for failed or was deleted (protocol 1.18); the step and the reason are in `details`. */
+    readonly WorkflowFailed: "WORKFLOW_FAILED";
+    /** A replicated entity's copy here cannot answer (1.19): its home is unreachable, or the read is outside the replication set. */
+    readonly NotHome: "NOT_HOME";
 }>;
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export declare function httpStatusOf(code: ErrorCode): number;
@@ -16,10 +20,13 @@ export declare function httpStatusOf(code: ErrorCode): number;
 export interface ErrorDetail {
     readonly message: string;
     readonly code: ErrorCode;
+    /** What a caller reads without parsing the message: a failed workflow's `step`, `reason` and `deleted`. */
+    readonly details?: Readonly<Record<string, string>>;
 }
 /** Thrown by the component client when the callee refused. */
 export declare class CommandError extends Error {
     readonly code: ErrorCode;
+    readonly details: Readonly<Record<string, string>>;
     constructor(detail: ErrorDetail);
     get detail(): ErrorDetail;
 }