ankka 0.9.1 → 0.11.0

package/dist/client.js

@@ -3,7 +3,7 @@
 // One channel per process, opened on first use so the integration testkit can learn the sidecar's
 // mapped port after construction. A client handed to a handler is scoped to that request's metadata,
 // so the sidecar records the call as a child span.
-import { createClient } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
 import { Client } from "./_proto/ankka/protocol/v1/client_pb.js";
 import { codecFor, jsonCodec, isCodec, textCodecs, binaryCodecs, codecForManifest } from "./codec.js";
@@ -12,7 +12,10 @@ import { decodeJsonValue, reviver } from "./json.js";
 import { errorCodeFromProto, kindToProto } from "./kinds.js";
 import { metadataToProto } from "./context.js";
 import { encodePayload, decodePayload, EMPTY_PAYLOAD } from "./server/payloads.js";
+import { Duration } from "./time.js";
+import { PROTOCOL_VERSION } from "./spec.js";
 import { AutonomousAgentCalls, TaskCalls, Tasks } from "./autonomous.js";
+import { APPROVALS_SINCE, ApprovalAwaited, awaitingOf } from "./approvals.js";
 function stubOf(connection) {
     if (!connection.stub) {
         connection.transport = createGrpcTransport({ baseUrl: `http://${connection.address}` });
@@ -38,6 +41,43 @@ function decodeReply(shape, payload) {
     const codec = payload ? codecForManifest(payload.manifest) : undefined;
     return (codec ?? binaryCodecs.done).decode(payload?.data ?? new Uint8Array());
 }
+function outcomeOf(reply, answer) {
+    switch (answer.result.case) {
+        case "reply":
+            return { kind: "answered", value: decodeReply(reply, answer.result.value.payload) };
+        case "approval":
+            return awaitingOf(answer.result.value);
+        case "error":
+            throw new CommandError(errorOf(answer.result.value));
+        default:
+            throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
+    }
+}
+/** Sends a decision; a runtime before approvals is reported as too old. */
+async function decideOn(connection, metadata, kind, componentId, entityId, name, approvalId, decision) {
+    try {
+        return await stubOf(connection).decide({
+            kind: kindToProto(kind),
+            componentId,
+            entityId,
+            name,
+            approvalId,
+            approved: decision.approved,
+            by: decision.by,
+            ...(decision.note ? { note: decision.note } : {}),
+            metadata: metadataToProto(metadata),
+        });
+    }
+    catch (failure) {
+        if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+            throw new CommandError({
+                message: `the runtime beside this process cannot record a decision on an approval request, which needs protocol ${APPROVALS_SINCE}: ${failure.rawMessage}`,
+                code: "INTERNAL",
+            });
+        }
+        throw failure;
+    }
+}
 /** One call, ready to invoke or stream. */
 export class Invocation {
     #connection;
@@ -68,20 +108,38 @@ export class Invocation {
             metadata: metadataToProto(this.#metadata),
         };
     }
-    /** Invokes and decodes the reply; a refusal rejects with `CommandError`. */
+    /**
+     * 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.
+     */
     async invoke(input) {
-        const answer = await stubOf(this.#connection).invoke(this.#request(input));
-        switch (answer.result.case) {
-            case "reply":
-                return decodeReply(this.#reply, answer.result.value.payload);
-            case "error":
-                throw new CommandError(errorOf(answer.result.value));
-            default:
-                throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
-        }
+        const outcome = await this.ask(input);
+        if (outcome.kind === "awaiting-approval")
+            throw new ApprovalAwaited(outcome.requests);
+        return outcome.value;
+    }
+    /** 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)));
+    }
+    /**
+     * Decides one of the session's approval requests; this invocation names the handler whose turn waits.
+     * `by` names who decided and is required. When it was the turn's last awaited decision the turn goes on,
+     * and this answers as `ask` would have. A request already decided is a conflict.
+     */
+    async decide(approvalId, decision) {
+        return outcomeOf(this.#reply, await decideOn(this.#connection, this.#metadata, this.#kind, this.#componentId, this.#entityId, this.#name, approvalId, decision));
     }
-    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`. */
+    /** Invokes a streaming handler; yields tokens in order; a failure rejects with `CommandError`, a turn that waits with `ApprovalAwaited`. */
     async *stream(input) {
+        for await (const part of this.streamParts(input)) {
+            if (typeof part !== "string")
+                throw new ApprovalAwaited(part.requests);
+            yield part;
+        }
+    }
+    /** As `stream`, ending with one awaiting part when the turn waits for a person. */
+    async *streamParts(input) {
         for await (const token of stubOf(this.#connection).invokeStream(this.#request(input))) {
             switch (token.token.case) {
                 case "text":
@@ -91,6 +149,9 @@ export class Invocation {
                     return;
                 case "failed":
                     throw new CommandError(errorOf(token.token.value));
+                case "approval":
+                    yield awaitingOf(token.token.value);
+                    return;
             }
         }
     }
@@ -128,8 +189,10 @@ export class TypedCalls {
 /** View queries: rows come back as a JSON array decoded with the row shape. */
 export class Views {
     #connection;
-    constructor(connection) {
+    #metadata;
+    constructor(connection, metadata = {}) {
         this.#connection = connection;
+        this.#metadata = metadata;
     }
     async get(viewId, key, row) {
         const rows = await this.query(viewId, "get", key, row);
@@ -139,7 +202,24 @@ export class Views {
         return this.query(viewId, "all", null, row);
     }
     async query(viewId, name, key, row) {
-        const answer = await stubOf(this.#connection).query({ viewId, name, payload: encodePayload(textCodecs.string, key ?? "") });
+        const answer = await stubOf(this.#connection).query({ viewId, name, payload: encodePayload(textCodecs.string, key ?? ""), metadata: metadataToProto(this.#metadata) });
+        return Views.#rows(answer, row);
+    }
+    /**
+     * The rows of one of a view's declared queries, asked by name with the values it takes. At most
+     * `limit` rows, 1000 when it is not given, in the statement's own order.
+     */
+    async ask(viewId, name, values, row, limit) {
+        const answer = await stubOf(this.#connection).query({
+            viewId,
+            name,
+            metadata: metadataToProto(this.#metadata),
+            values: { ...values },
+            ...(limit !== undefined ? { limit } : {}),
+        });
+        return Views.#rows(answer, row);
+    }
+    static #rows(answer, row) {
         switch (answer.result.case) {
             case "rows": {
                 const text = new TextDecoder().decode(answer.result.value.data);
@@ -159,6 +239,16 @@ export class Views {
         }
     }
 }
+const RECURRING_SINCE = "1.12";
+const MAX_PERIOD_DAYS = 36500;
+const MIN_PERIOD = Duration.ofMillis(1);
+const MAX_PERIOD = Duration.ofSeconds(MAX_PERIOD_DAYS * 86400);
+/** What is wrong with a recurring timer's period, if anything: the runtime's own rule. */
+function periodProblem(timerId, period) {
+    if (Duration.compare(period, MIN_PERIOD) >= 0 && Duration.compare(period, MAX_PERIOD) <= 0)
+        return undefined;
+    return `timer '${timerId}' has a period of ${period.toString()}; a period is from 1 millisecond to ${MAX_PERIOD_DAYS} days`;
+}
 export class Timers {
     #connection;
     constructor(connection) {
@@ -179,10 +269,161 @@ export class Timers {
             payload: inputPayload(t.input, input),
         });
     }
+    /**
+     * Schedules `target`, a timed action's handler, first after `delay` (zero or less is due at once) and
+     * then every `period` until it is cancelled or replaced. Setting it again with the same handler and
+     * period keeps its next due time, so a service may set its recurring timers every time it starts.
+     * A period outside 1 millisecond to 36,500 days is refused with `BAD_REQUEST` before anything is sent.
+     */
+    async scheduleRecurring(timerId, delay, period, target, input) {
+        const problem = periodProblem(timerId, period);
+        if (problem !== undefined)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        const t = "component" in target ? { componentId: target.component.componentId, name: target.handler.name, input: target.handler.input } : target;
+        const reply = await stubOf(this.#connection)
+            .scheduleRecurring({
+            timerId,
+            delayMillis: BigInt(delay.toMillis()),
+            periodMillis: BigInt(period.toMillis()),
+            componentId: t.componentId,
+            name: t.name,
+            payload: inputPayload(t.input, input),
+        })
+            .catch(tooOld("recurring timers", RECURRING_SINCE));
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+    /** Cancels the timer under `timerId`, whether it fires once or recurs. */
     async cancel(timerId) {
         await stubOf(this.#connection).cancel({ timerId });
     }
 }
+// ── The secret store (protocol 1.6) ───────────────────────────────────────────
+const SECRETS_SINCE = "1.6";
+export const MAX_SECRET_NAME_LENGTH = 253;
+export const MAX_SECRET_VALUE_BYTES = 65536;
+const SECRET_NAME_RULE = `a secret's name is 1 to ${MAX_SECRET_NAME_LENGTH} characters, each a letter, a digit, '.', '_', '-' or '/'`;
+const VALID_SECRET_NAME = new RegExp(`^[A-Za-z0-9._/-]{1,${MAX_SECRET_NAME_LENGTH}}$`);
+/** What is wrong with a secret's name, if anything: the runtime's own rule. */
+export function secretNameProblem(name) {
+    if (VALID_SECRET_NAME.test(name))
+        return undefined;
+    const shown = name.length > 40 ? `${name.slice(0, 40)}…` : name;
+    return `${SECRET_NAME_RULE}; "${shown}" is not`;
+}
+/** What is wrong with a secret's value, if anything. Never quotes the value. */
+export function secretValueProblem(value) {
+    if (value === "")
+        return "a secret's value must not be empty";
+    const size = new TextEncoder().encode(value).length;
+    return size > MAX_SECRET_VALUE_BYTES ? `a secret's value is at most ${MAX_SECRET_VALUE_BYTES} bytes as UTF-8; this one is ${size}` : undefined;
+}
+/** Turns `UNIMPLEMENTED` from a runtime older than protocol `since` into an error naming both versions. */
+function tooOld(what, since) {
+    return (failure) => {
+        if (failure instanceof ConnectError && failure.code === Code.Unimplemented) {
+            throw new CommandError({
+                message: `the runtime beside this process is too old for ${what}, which needs protocol ${since}; this process speaks ${PROTOCOL_VERSION}: ${failure.rawMessage}`,
+                code: "INTERNAL",
+            });
+        }
+        throw failure;
+    };
+}
+const secretsTooOld = tooOld("the secret store", SECRETS_SINCE);
+/**
+ * The service's secret store: named text values the runtime keeps in the service's own database,
+ * encrypted with a key this process never sees. Offered to endpoints, workflow steps, consumers,
+ * timed actions and agents; an entity and a view have no `secrets` at all.
+ *
+ * Every refusal is a `CommandError` with the runtime's code: `BAD_REQUEST` for a name or a value that
+ * breaks its rule, `INTERNAL` when the service has no secret key or a value was kept with another
+ * one, `UNAVAILABLE` when the database cannot be reached.
+ */
+export class Secrets {
+    #client;
+    /** The store reached through `client`'s sidecar; with none, every call throws. */
+    constructor(client) {
+        this.#client = client;
+    }
+    #stub() {
+        const connection = this.#client ? connectionOf.get(this.#client) : undefined;
+        if (!connection)
+            throw new Error("this secret store is not connected to a runtime; a unit test passes an InMemorySecrets");
+        return stubOf(connection);
+    }
+    /** Keeps `value` under `name`, replacing what was there. */
+    async put(name, value) {
+        const reply = await this.#stub().putSecret({ name, value }).catch(secretsTooOld);
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+    /** The value kept under `name`, or `undefined` when there is none. Never an empty string. */
+    async get(name) {
+        const reply = await this.#stub().getSecret({ name }).catch(secretsTooOld);
+        switch (reply.result.case) {
+            case "value":
+                return reply.result.value;
+            case "absent":
+                return undefined;
+            case "error":
+                throw new CommandError(errorOf(reply.result.value));
+            default:
+                throw new CommandError({ message: "the runtime answered a secret's read with nothing", code: "INTERNAL" });
+        }
+    }
+    /** Removes what is kept under `name`. Removing nothing is not an error. */
+    async delete(name) {
+        const reply = await this.#stub().deleteSecret({ name }).catch(secretsTooOld);
+        if (reply.error)
+            throw new CommandError(errorOf(reply.error));
+    }
+}
+/** A secret store for unit tests: a map, applying the runtime's rules with its words. */
+export class InMemorySecrets extends Secrets {
+    values = new Map();
+    async put(name, value) {
+        const problem = secretNameProblem(name) ?? secretValueProblem(value);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        this.values.set(name, value);
+    }
+    async get(name) {
+        const problem = secretNameProblem(name);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        return this.values.get(name);
+    }
+    async delete(name) {
+        const problem = secretNameProblem(name);
+        if (problem)
+            throw new CommandError({ message: problem, code: "BAD_REQUEST" });
+        this.values.delete(name);
+    }
+}
+/** A store for unit tests whose every call throws: the unit kit's default, beside `noClient()`. */
+export function noSecrets() {
+    return new Secrets(undefined);
+}
+const connectionOf = new WeakMap();
+const metadataOf = new WeakMap();
+/**
+ * @internal What a call to another service is sent through: `client`'s sidecar, and the metadata of
+ * the handler `client` was scoped to. Not a member of the client, which an entity holds too.
+ */
+export function channelOf(client) {
+    const connection = connectionOf.get(client);
+    if (!connection)
+        return undefined;
+    return { stub: () => stubOf(connection), metadata: metadataOf.get(client) ?? {} };
+}
+/**
+ * @internal The secret store reached through `client`'s sidecar. Not a member of the client, which
+ * an entity holds too: only the component kinds that may have a store call this.
+ */
+export function secretsFor(client) {
+    return new Secrets(client);
+}
 export class ComponentClient {
     #connection;
     #metadata;
@@ -191,8 +432,10 @@ export class ComponentClient {
     constructor(address = process.env.ANKKA_SIDECAR_ADDRESS ?? "127.0.0.1:9011", connection, metadata = {}) {
         this.#connection = connection ?? { address, transport: undefined, stub: undefined };
         this.#metadata = metadata;
-        this.views = new Views(this.#connection);
+        this.views = new Views(this.#connection, metadata);
         this.timers = new Timers(this.#connection);
+        connectionOf.set(this, this.#connection);
+        metadataOf.set(this, metadata);
     }
     /** Points every client sharing this connection at a new sidecar address (the integration testkit's mapped port). */
     reconnect(address) {
@@ -253,6 +496,10 @@ export class ComponentClient {
                 throw new CommandError({ message: "the sidecar answered nothing", code: "INTERNAL" });
         }
     }
+    /** @internal A decision on an approval request; a refusal rejects with `CommandError`. */
+    async _decide(kind, componentId, entityId, name, approvalId, decision) {
+        outcomeOf(undefined, await decideOn(this.#connection, this.#metadata, kind, componentId, entityId, name, approvalId, decision));
+    }
     /** @internal A streaming call whose tokens are text. */
     async *_rawStream(kind, componentId, entityId, name) {
         const request = { kind: kindToProto(kind), componentId, entityId, name, payload: EMPTY_PAYLOAD, metadata: metadataToProto(this.#metadata) };

package/dist/consumer.d.ts

@@ -1,15 +1,42 @@
+import type { StartFrom } from "./startFrom.ts";
+import type { Contract, Publication } from "./contract.ts";
 import type { Shape } from "./codec.ts";
 import type { Metadata } from "./effects/common.ts";
-import type { ComponentClient, ComponentRef } from "./client.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";
 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;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets(): Secrets;
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store: Secrets);
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services(): Services;
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services: Services);
     /** @internal */
     get _kind(): "consumer";
     abstract onMessage(message: M): MaybePromise<ConsumerEffect<Out>>;
@@ -23,9 +50,20 @@ export interface ConsumerClass<M = unknown, Out = unknown, C extends Consumer<M,
     readonly componentId: string;
     readonly source?: ComponentRef;
     readonly topic?: string;
+    /** Where a topic source starts the first time its group reads the topic. */
+    readonly startFrom?: StartFrom;
+    /** Raised to read the topic again from the start position, under a group of its own. Absent is 1. */
+    readonly version?: number;
+    /** The contract the topic read is expected to carry, checked at start against the project's declaration. */
+    readonly contract?: Contract;
+    /** The declared broker the topic read is on; absent is the installation's. */
+    readonly broker?: string;
+    /** Whether the partitions an instance holds are handled at once, each in order. */
+    readonly parallel?: boolean;
     readonly message: Shape<M>;
     /** The shape of what `produce` sends onward; required with `producesTo`. */
     readonly out?: Shape<Out>;
-    readonly producesTo?: string;
+    /** The topic produced to: its name, or a `Publication` with the contract stated for it and its broker. */
+    readonly producesTo?: string | Publication;
 }
 export {};

package/dist/consumer.js

@@ -1,5 +1,33 @@
 // A consumer: reacts to a source's changes, optionally producing onward to a topic.
+import { secretsFor } from "./client.js";
 import { ConsumerEffects } from "./effects/stateless.js";
+import { servicesFor } from "./services.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,11 +39,33 @@ 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");
         return this.#client;
     }
+    #secrets;
+    /** The service's secret store: values kept encrypted in the service's own database, never in a journal or a view. */
+    get secrets() {
+        return this.#secrets ?? secretsFor(this.client);
+    }
+    /** A unit test's store in place of the runtime's: `component.secrets = new InMemorySecrets()`. */
+    set secrets(store) {
+        this.#secrets = store;
+    }
+    #services;
+    /** Other services, called as this one, through the runtime: `this.services.service("orders")`. */
+    get services() {
+        return this.#services ?? servicesFor(this.client);
+    }
+    /** A unit test's in place of the runtime's: `component.services = new ScriptedServices()`. */
+    set services(services) {
+        this.#services = services;
+    }
     /** @internal */
     get _kind() {
         return "consumer";

package/dist/context.d.ts

@@ -26,6 +26,10 @@ export interface Principal {
     readonly email: string | null;
     readonly emailVerified: boolean;
     readonly roles: readonly string[];
+    /** Every other claim of the verified token, as text. */
+    readonly claims: Readonly<Record<string, string>>;
+    /** The service's own name for the issuer that verified the token, from `ANKKA_AUTH_ISSUERS`. */
+    readonly issuer: string | null;
 }
 /**
  * Which workload sent a request, as the platform established it from the client certificate: the gateway

package/dist/contract.d.ts

@@ -0,0 +1,36 @@
+/** A contract's name: a topic's letters and `_`, 2 to 100 characters. */
+export declare const CONTRACT_NAME_RULE: RegExp;
+/**
+ * What a topic carries, as a project declares it and a component states it: a name and the
+ * fingerprint of the schema document. The platform refuses, at a service's start, a side whose name
+ * or fingerprint is not the declared one; the name travels as every message's `ce-type`. Nothing
+ * checks a message against the schema.
+ *
+ * The fingerprint is `sha256:` and the hex SHA-256 of the document under RFC 8785 (the JSON
+ * Canonicalization Scheme), so whitespace and key order in a saved file do not change it and a
+ * changed field does. Every SDK fingerprints the same way, held to `protocol/fixtures/contracts/`.
+ */
+export declare class Contract {
+    readonly name: string;
+    readonly fingerprint: string;
+    constructor(name: string, fingerprint: string);
+    /** The contract `name` of the schema document at `path`, fetched from the project's declaration. */
+    static fromFile(path: string, name: string): Contract;
+    /** The contract `name` of a schema document held in memory. */
+    static fromBytes(document: Uint8Array | string, name: string): Contract;
+    /** @internal */
+    equals(other: Contract): boolean;
+}
+/** `sha256:` and the hex SHA-256 of `document` canonicalised under RFC 8785. Throws when it is not JSON. */
+export declare function fingerprintOf(document: Uint8Array | string): string;
+/**
+ * A topic a consumer publishes to, with the contract it states for it and the declared broker it is
+ * on. `producesTo` takes a plain topic name as the short form.
+ */
+export interface Publication {
+    readonly topic: string;
+    readonly contract?: Contract;
+    readonly broker?: string;
+}
+/** 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

@@ -0,0 +1,58 @@
+// A contract: a name and the fingerprint of the schema document a component was built against.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import * as canonicalizeModule from "canonicalize";
+// `canonicalize` is CommonJS whose declaration says `export default`: under Node's ESM loader the
+// namespace's `default` is `module.exports`, the function, which is also what the types say.
+const canonicalize = canonicalizeModule.default;
+/** A contract's name: a topic's letters and `_`, 2 to 100 characters. */
+export const CONTRACT_NAME_RULE = /^[a-z0-9][a-z0-9._-]{0,98}[a-z0-9]$/;
+/**
+ * What a topic carries, as a project declares it and a component states it: a name and the
+ * fingerprint of the schema document. The platform refuses, at a service's start, a side whose name
+ * or fingerprint is not the declared one; the name travels as every message's `ce-type`. Nothing
+ * checks a message against the schema.
+ *
+ * The fingerprint is `sha256:` and the hex SHA-256 of the document under RFC 8785 (the JSON
+ * Canonicalization Scheme), so whitespace and key order in a saved file do not change it and a
+ * changed field does. Every SDK fingerprints the same way, held to `protocol/fixtures/contracts/`.
+ */
+export class Contract {
+    name;
+    fingerprint;
+    constructor(name, fingerprint) {
+        if (!CONTRACT_NAME_RULE.test(name))
+            throw new TypeError(`contract name ${JSON.stringify(name)} is not ${CONTRACT_NAME_RULE.source}`);
+        this.name = name;
+        this.fingerprint = fingerprint;
+    }
+    /** The contract `name` of the schema document at `path`, fetched from the project's declaration. */
+    static fromFile(path, name) {
+        return Contract.fromBytes(readFileSync(path), name);
+    }
+    /** The contract `name` of a schema document held in memory. */
+    static fromBytes(document, name) {
+        return new Contract(name, fingerprintOf(document));
+    }
+    /** @internal */
+    equals(other) {
+        return this.name === other.name && this.fingerprint === other.fingerprint;
+    }
+}
+/** `sha256:` and the hex SHA-256 of `document` canonicalised under RFC 8785. Throws when it is not JSON. */
+export function fingerprintOf(document) {
+    const text = typeof document === "string" ? document : new TextDecoder("utf-8", { fatal: true }).decode(document);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new TypeError(`a schema document must be JSON: ${e.message}`);
+    }
+    const canonical = canonicalize(parsed);
+    if (canonical === undefined)
+        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 declare a contract, a broker or parallel reading. */
+export const CONTRACT_PROTOCOL = [1, 14];

package/dist/effects/keyed.d.ts

@@ -0,0 +1,33 @@
+import type { EffectLike } from "./common.ts";
+/** One row written under its key, or the key's row deleted. */
+export type RowChange<Row> = {
+    readonly key: string;
+    readonly row: Row;
+} | {
+    readonly key: string;
+    readonly deleted: true;
+};
+/**
+ * What a keyed view's handler says to do with one change: rows to write and rows to delete, in order.
+ * Empty is "nothing". The platform deletes no row the handler did not name; a row is moved by deleting
+ * its old key and writing its new one in the same effect.
+ */
+export type KeyedViewEffect<Row> = {
+    readonly kind: "rows";
+    readonly changes: readonly RowChange<Row>[];
+} & EffectLike<never>;
+export declare class KeyedViewEffects<Row> {
+    updateRow(key: string, row: Row): KeyedViewEffect<Row>;
+    deleteRow(key: string): KeyedViewEffect<Row>;
+    /** Several rows written, each under its key. */
+    updateRows(entries: Iterable<readonly [string, Row]>): KeyedViewEffect<Row>;
+    deleteRows(keys: Iterable<string>): KeyedViewEffect<Row>;
+    ignore(): KeyedViewEffect<Row>;
+    /** Several effects as one, in the order given. */
+    all(...effects: readonly KeyedViewEffect<Row>[]): KeyedViewEffect<Row>;
+}
+/**
+ * The final change for each key, a later change to a key winning, keys in the order they first
+ * appear; `undefined` is a deletion. How the test kit applies an effect, as the runtime does.
+ */
+export declare function reduceRowChanges<Row>(changes: readonly RowChange<Row>[]): [string, Row | undefined][];