ankka 0.10.0 → 0.12.0

package/dist/consumer.d.ts

@@ -1,7 +1,11 @@
+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";
+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";
@@ -23,25 +27,60 @@ 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;
+    /** 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>>;
     /** 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;
     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;
+    /**
+     * 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>;
     /** 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;
+    /**
+     * 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

@@ -1,5 +1,7 @@
 // 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. */
@@ -29,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() {
@@ -37,15 +40,45 @@ 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");
         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";
@@ -55,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: {
@@ -26,6 +44,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
@@ -37,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

@@ -0,0 +1,40 @@
+/** 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;
+    /** 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

@@ -0,0 +1,60 @@
+// 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 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;
 }

package/dist/effects/common.js

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

package/dist/effects/eventSourced.d.ts

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

package/dist/effects/eventSourced.js

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

package/dist/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][];

package/dist/effects/keyed.js

@@ -0,0 +1,41 @@
+// Effects for a keyed view: the rows one change writes and deletes, each named by its key.
+function rows(changes) {
+    return Object.freeze({ kind: "rows", changes: Object.freeze([...changes]) });
+}
+function checkedKey(key) {
+    if (typeof key !== "string" || key === "")
+        throw new TypeError("a row key is a string of one character or more");
+    return key;
+}
+export class KeyedViewEffects {
+    updateRow(key, row) {
+        return rows([{ key: checkedKey(key), row }]);
+    }
+    deleteRow(key) {
+        return rows([{ key: checkedKey(key), deleted: true }]);
+    }
+    /** Several rows written, each under its key. */
+    updateRows(entries) {
+        return rows([...entries].map(([key, row]) => ({ key: checkedKey(key), row })));
+    }
+    deleteRows(keys) {
+        return rows([...keys].map((key) => ({ key: checkedKey(key), deleted: true })));
+    }
+    ignore() {
+        return rows([]);
+    }
+    /** Several effects as one, in the order given. */
+    all(...effects) {
+        return rows(effects.flatMap((e) => e.changes));
+    }
+}
+/**
+ * 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 function reduceRowChanges(changes) {
+    const last = new Map();
+    for (const change of changes)
+        last.set(change.key, "deleted" in change ? undefined : change.row);
+    return [...last.entries()];
+}

package/dist/endpoint.d.ts

@@ -1,12 +1,21 @@
-import type { ComponentClient } from "./client.ts";
+import { type ComponentClient, type Secrets } from "./client.ts";
 import { type RequestContext } from "./context.ts";
 import type { Acl, RouteTable } from "./routes.ts";
+import { type Services } from "./services.ts";
 export declare abstract class Endpoint {
     #private;
     /** The request being handled: path parameters, query, headers, principal. Request-scoped. */
     get request(): RequestContext;
     /** The component client, scoped to the current request's trace so the sidecar records child spans. */
     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 */
     _bindClient(client: ComponentClient | undefined): void;
 }