ankka 0.6.0

package/dist/service.js

@@ -0,0 +1,384 @@
+// The service: the explicit registry of components and endpoints. Nothing is found by scanning; a class
+// exists to the runtime only once it is `register`ed here. Problems are collected, not thrown one at a
+// time, and reported together before anything listens — the same rule as the Scala builder.
+//
+//   await Ankka.service().register(ShoppingCartEntity).register(ShoppingCartEndpoint).listen()
+import { codecFor, isCodec } from "./codec.js";
+import { EventSourcedEntity } from "./eventSourcedEntity.js";
+import { KeyValueEntity } from "./keyValueEntity.js";
+import { Workflow } from "./workflow.js";
+import { View } from "./view.js";
+import { Consumer } from "./consumer.js";
+import { TimedAction } from "./timedAction.js";
+import { Agent } from "./agent.js";
+import { Endpoint } from "./endpoint.js";
+import { Acl as AclValues } from "./routes.js";
+import { ComponentClient } from "./client.js";
+import { Server } from "./server/server.js";
+import { renderSpec } from "./spec.js";
+/** Everything the service hosts, validated. */
+export class Registry {
+    components;
+    endpoints;
+    constructor(components, endpoints) {
+        this.components = components;
+        this.endpoints = endpoints;
+        Object.freeze(this);
+    }
+    component(id) {
+        return this.components.get(id);
+    }
+    /** The component `id` when it is of `kind`. */
+    of(kind, id) {
+        const c = this.components.get(id);
+        return c && c.kind === kind ? c : undefined;
+    }
+    endpoint(id) {
+        return this.endpoints.get(id);
+    }
+}
+/** Thrown by `validate`, `spec`, `server` and `listen` with every problem the registration has. */
+export class RegistrationError extends Error {
+    problems;
+    constructor(problems) {
+        super(`the service cannot start:\n${problems.map((p) => `  - ${p}`).join("\n")}`);
+        this.name = "RegistrationError";
+        this.problems = problems;
+    }
+}
+function extendsBase(cls, base) {
+    return typeof cls === "function" && cls.prototype instanceof base;
+}
+function isShape(x) {
+    return typeof x === "object" && x !== null && (typeof x.kind === "string" || isCodec(x));
+}
+function nameOf(cls) {
+    return typeof cls === "function" && cls.name ? cls.name : String(cls);
+}
+export class ServiceBuilder {
+    #classes = [];
+    #client;
+    #log;
+    constructor(options = {}) {
+        this.#client = options.client ?? new ComponentClient();
+        this.#log = options.log ?? ((m) => console.error(m));
+    }
+    /** The component client every handler receives; the integration testkit repoints it at the sidecar it started. */
+    get client() {
+        return this.#client;
+    }
+    register(cls) {
+        this.#classes.push(cls);
+        return this;
+    }
+    /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
+    validate() {
+        const problems = [];
+        const components = new Map();
+        const endpoints = new Map();
+        const prefixes = new Map();
+        const add = (r, cls) => {
+            if (!r)
+                return;
+            if (components.has(r.id))
+                problems.push(`two components declare the id ${JSON.stringify(r.id)} (${nameOf(components.get(r.id).cls)} and ${nameOf(cls)})`);
+            else
+                components.set(r.id, r);
+        };
+        for (const cls of this.#classes) {
+            if (extendsBase(cls, EventSourcedEntity))
+                add(registerEventSourced(cls, problems), cls);
+            else if (extendsBase(cls, KeyValueEntity))
+                add(registerKeyValue(cls, problems), cls);
+            else if (extendsBase(cls, Workflow))
+                add(registerWorkflow(cls, problems), cls);
+            else if (extendsBase(cls, View))
+                add(registerView(cls, problems), cls);
+            else if (extendsBase(cls, Consumer))
+                add(registerConsumer(cls, problems), cls);
+            else if (extendsBase(cls, TimedAction))
+                add(registerTimedAction(cls, problems), cls);
+            else if (extendsBase(cls, Agent))
+                add(registerAgent(cls, problems), cls);
+            else if (extendsBase(cls, Endpoint)) {
+                const ep = cls;
+                if (typeof ep.prefix === "string") {
+                    const other = prefixes.get(ep.prefix);
+                    if (other && other !== nameOf(cls))
+                        problems.push(`endpoints ${other} and ${nameOf(cls)} share the prefix ${ep.prefix}`);
+                    prefixes.set(ep.prefix, nameOf(cls));
+                }
+                const r = registerEndpoint(ep, problems);
+                if (r) {
+                    if (endpoints.has(r.id))
+                        problems.push(`two endpoints are named ${r.id}`);
+                    else
+                        endpoints.set(r.id, r);
+                }
+            }
+            else {
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, TimedAction, Agent or Endpoint`);
+            }
+        }
+        if (problems.length > 0)
+            throw new RegistrationError(problems);
+        return new Registry(components, endpoints);
+    }
+    /** The discovery `Spec` for what is registered, without listening. */
+    spec() {
+        return renderSpec(this.validate());
+    }
+    /** An unstarted server over the validated registry, for the integration testkit. */
+    server(options = {}) {
+        return new Server(this.validate(), this.#client, { log: this.#log, ...options });
+    }
+    /** Validates, binds `ANKKA_PROCESS_PORT` (default 9010) on loopback, answers discovery, and runs until stopped. */
+    async listen(options = {}) {
+        const server = this.server(options);
+        const { host, port } = await server.start();
+        this.#log(`ankka: serving ${this.#classes.length} registered class(es) to the sidecar on ${host}:${port}`);
+        const stop = () => void server.stop();
+        process.once("SIGTERM", stop);
+        process.once("SIGINT", stop);
+        try {
+            await server.closed;
+        }
+        finally {
+            process.off("SIGTERM", stop);
+            process.off("SIGINT", stop);
+        }
+    }
+}
+function checker(cls, problems) {
+    let ok = true;
+    const name = nameOf(cls);
+    return {
+        fail: (m) => {
+            problems.push(`${name}: ${m}`);
+            ok = false;
+        },
+        ok: () => ok,
+    };
+}
+function requireId(cls, fail) {
+    if (typeof cls.componentId !== "string" || cls.componentId.trim() === "")
+        fail("needs a static componentId");
+}
+function requireShape(value, what, fail) {
+    if (!isShape(value))
+        fail(`needs a static ${what}`);
+}
+function registerEventSourced(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    requireShape(cls.state, "state: a schema or codec for its state", fail);
+    requireShape(cls.events, "events: a schema or codec for its events", fail);
+    const snapshotEvery = cls.snapshotEvery ?? 0;
+    if (!Number.isInteger(snapshotEvery) || snapshotEvery < 0)
+        fail(`snapshotEvery must be a non-negative integer, not ${String(cls.snapshotEvery)}`);
+    const handlers = collectHandlers(cls.handlers, "handlers", ["command", "query"], fail);
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "event-sourced", id: cls.componentId, cls, stateCodec: codecFor(cls.state), eventCodec: codecFor(cls.events), handlers, snapshotEvery });
+}
+function registerKeyValue(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    requireShape(cls.state, "state: a schema or codec for its state", fail);
+    const handlers = collectHandlers(cls.handlers, "handlers", ["command", "query"], fail);
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "key-value", id: cls.componentId, cls, stateCodec: codecFor(cls.state), handlers });
+}
+function registerWorkflow(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    requireShape(cls.state, "state: a schema or codec for its state", fail);
+    const handlers = collectHandlers(cls.handlers, "handlers", ["command", "query"], fail);
+    const steps = collectHandlers(cls.steps, "steps", ["step"], fail);
+    const settings = cls.settings;
+    if (settings !== undefined) {
+        if (typeof settings !== "object" || settings === null)
+            fail("settings must be a WorkflowSettings object");
+        else {
+            const check = (what, failoverTo) => {
+                if (failoverTo !== undefined && !steps.has(failoverTo))
+                    fail(`${what} fails over to ${JSON.stringify(failoverTo)}, which is not a declared step`);
+            };
+            check("default recovery", settings.defaultRecovery?.failoverTo);
+            for (const [name, st] of Object.entries(settings.steps ?? {})) {
+                if (!steps.has(name))
+                    fail(`settings name step ${JSON.stringify(name)}, which is not declared`);
+                check(`step ${JSON.stringify(name)}'s recovery`, st.recovery?.failoverTo);
+            }
+        }
+    }
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "workflow", id: cls.componentId, cls, stateCodec: codecFor(cls.state), handlers, steps, settings });
+}
+function sourceOf(cls, fail) {
+    const hasSource = cls.source !== undefined;
+    const hasTopic = cls.topic !== undefined;
+    if (hasSource === hasTopic) {
+        fail("needs a static source (a component class) or a static topic, and not both");
+        return undefined;
+    }
+    if (hasTopic) {
+        if (typeof cls.topic !== "string" || cls.topic.trim() === "") {
+            fail("topic must be a non-empty string");
+            return undefined;
+        }
+        return { topic: cls.topic };
+    }
+    const src = cls.source;
+    const kind = src?.prototype?._kind;
+    if (typeof src?.componentId !== "string" || typeof kind !== "string") {
+        fail("source must be a component class (one that extends EventSourcedEntity, KeyValueEntity, ...)");
+        return undefined;
+    }
+    return { component: { kind, id: src.componentId } };
+}
+function registerView(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const source = sourceOf(cls, fail);
+    requireShape(cls.events, "events: a schema or codec for the source's events", fail);
+    requireShape(cls.row, "row: a schema or codec for its rows", fail);
+    const queries = cls.queries ?? ["get", "all"];
+    if (!Array.isArray(queries) || queries.some((q) => typeof q !== "string" || q.trim() === ""))
+        fail("queries must be a list of names");
+    if (!ok() || !source)
+        return undefined;
+    return Object.freeze({ kind: "view", id: cls.componentId, cls, source, eventCodec: codecFor(cls.events), rowCodec: codecFor(cls.row), queries: Object.freeze([...queries]) });
+}
+function registerConsumer(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const source = sourceOf(cls, fail);
+    requireShape(cls.message, "message: a schema or codec for the source's messages", fail);
+    if (cls.producesTo !== undefined && (typeof cls.producesTo !== "string" || cls.producesTo.trim() === ""))
+        fail("producesTo must be a topic name");
+    if (cls.producesTo !== undefined && !isShape(cls.out))
+        fail(`produces to ${JSON.stringify(cls.producesTo)} and needs a static out: the shape of what it produces`);
+    if (!ok() || !source)
+        return undefined;
+    return Object.freeze({
+        kind: "consumer",
+        id: cls.componentId,
+        cls,
+        source,
+        messageCodec: codecFor(cls.message),
+        outCodec: cls.out ? codecFor(cls.out) : undefined,
+        producesTo: cls.producesTo,
+    });
+}
+function registerTimedAction(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const actions = collectHandlers(cls.actions, "actions", ["action"], fail);
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "timed-action", id: cls.componentId, cls, actions });
+}
+function registerAgent(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const handlers = collectHandlers(cls.handlers, "handlers", ["command", "stream"], fail);
+    const tools = new Map();
+    for (const [property, t] of Object.entries(cls.tools ?? {})) {
+        if (typeof t !== "object" || t === null || typeof t.name !== "string" || typeof t.run !== "function") {
+            fail(`tools.${property} is not a tool: declare it with tool(name, description, input, run)`);
+            continue;
+        }
+        if (typeof t.description !== "string" || t.description.trim() === "")
+            fail(`tool ${JSON.stringify(t.name)} needs a description; the model decides by it`);
+        if (tools.has(t.name))
+            fail(`two tools declare the name ${JSON.stringify(t.name)}`);
+        tools.set(t.name, t);
+    }
+    const guardrails = new Map();
+    for (const [property, g] of Object.entries(cls.guardrails ?? {})) {
+        if (typeof g !== "object" || g === null || typeof g.name !== "string" || typeof g.check !== "function") {
+            fail(`guardrails.${property} is not a guardrail: declare it with guardrail(name, check)`);
+            continue;
+        }
+        if (guardrails.has(g.name))
+            fail(`two guardrails declare the name ${JSON.stringify(g.name)}`);
+        guardrails.set(g.name, g);
+    }
+    const maxToolCallSteps = cls.maxToolCallSteps ?? 100;
+    if (!Number.isInteger(maxToolCallSteps) || maxToolCallSteps <= 0)
+        fail("maxToolCallSteps must be a positive integer");
+    if (!ok())
+        return undefined;
+    return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, role: cls.role ?? "", maxToolCallSteps });
+}
+/** Collects a handler table by wire name, reporting a duplicate wire name or a kind the component cannot host. */
+export function collectHandlers(table, what, allowed, fail) {
+    const out = new Map();
+    if (typeof table !== "object" || table === null) {
+        fail(`needs a static ${what} table`);
+        return out;
+    }
+    for (const [property, ref] of Object.entries(table)) {
+        if (!isHandlerRef(ref)) {
+            fail(`${what}.${property} is not a handler: declare it with command(...), query(...), step(...), action(...) or stream(...)`);
+            continue;
+        }
+        if (!allowed.includes(ref.kind)) {
+            fail(`${what}.${property} is a ${ref.kind}, which does not belong in ${what}`);
+            continue;
+        }
+        if (out.has(ref.name)) {
+            fail(`two ${what} declare the wire name ${JSON.stringify(ref.name)}`);
+            continue;
+        }
+        out.set(ref.name, ref);
+    }
+    return out;
+}
+function isHandlerRef(x) {
+    return typeof x === "object" && x !== null && typeof x.name === "string" && typeof x.run === "function" && typeof x.kind === "string";
+}
+function registerEndpoint(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    const name = nameOf(cls);
+    if (typeof cls.prefix !== "string" || !cls.prefix.startsWith("/") || (cls.prefix.length > 1 && cls.prefix.endsWith("/"))) {
+        fail(`needs a static prefix starting with "/" and not ending with one, not ${JSON.stringify(cls.prefix)}`);
+    }
+    if (!Object.values(AclValues).includes(cls.acl)) {
+        fail(`needs a static acl — Acl.allowAll, Acl.denyAll or Acl.authenticated. An unstated access rule is a decision nobody made`);
+    }
+    const routes = new Map();
+    const seen = new Map();
+    if (typeof cls.routes !== "object" || cls.routes === null) {
+        fail("needs a static routes table");
+    }
+    else {
+        for (const [id, route] of Object.entries(cls.routes)) {
+            if (typeof route !== "object" || route === null || typeof route.template !== "string" || typeof route.run !== "function") {
+                fail(`routes.${id} is not a route: declare it with get(...), post(...), put(...), patch(...), del(...) or sse(...)`);
+                continue;
+            }
+            const r = route;
+            const key = `${r.method} ${r.template}`;
+            const other = seen.get(key);
+            if (other)
+                fail(`routes ${other} and ${id} both declare ${key}`);
+            seen.set(key, id);
+            if (r.acl !== undefined && !Object.values(AclValues).includes(r.acl))
+                fail(`routes.${id}: unknown acl ${JSON.stringify(r.acl)}`);
+            routes.set(id, r);
+        }
+    }
+    if (!ok())
+        return undefined;
+    return Object.freeze({ id: name, cls, prefix: cls.prefix, acl: cls.acl, routes });
+}
+/** The entry point: `Ankka.service().register(...).listen()`. */
+export const Ankka = Object.freeze({
+    service(options) {
+        return new ServiceBuilder(options);
+    },
+});

package/dist/spec.d.ts

@@ -0,0 +1,7 @@
+import { Endpoint_Acl, type Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
+import type { Registry } from "./service.ts";
+import { Acl } from "./routes.ts";
+export declare const PROTOCOL_VERSION = "1.0";
+export declare const SDK_NAME = "ankka-typescript";
+export declare function aclToProto(acl: Acl): Endpoint_Acl;
+export declare function renderSpec(registry: Registry): Spec;

package/dist/spec.js

@@ -0,0 +1,106 @@
+// Renders the discovery Spec from the registry: what the sidecar hosts is exactly what is registered.
+import { create } from "@bufbuild/protobuf";
+import { Endpoint_Acl, SpecSchema } from "./_proto/ankka/protocol/v1/discovery_pb.js";
+import { kindToProto } from "./kinds.js";
+import { Acl } from "./routes.js";
+import { toJsonSchema } from "./schema.js";
+import { isCodec } from "./codec.js";
+import { VERSION } from "./version.js";
+export const PROTOCOL_VERSION = "1.0";
+export const SDK_NAME = "ankka-typescript";
+export function aclToProto(acl) {
+    switch (acl) {
+        case Acl.allowAll:
+            return Endpoint_Acl.ALLOW_ALL;
+        case Acl.denyAll:
+            return Endpoint_Acl.DENY_ALL;
+        case Acl.authenticated:
+            return Endpoint_Acl.AUTHENTICATED;
+    }
+}
+function handlerInits(handlers) {
+    return [...handlers.values()]
+        .map((h) => ({ name: h.name, readOnly: h.readOnly, streaming: h.streaming }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function sourceInit(source) {
+    return "topic" in source
+        ? { source: { case: "topic", value: source.topic } }
+        : { source: { case: "component", value: { kind: kindToProto(source.component.kind), id: source.component.id } } };
+}
+function recoveryInit(r) {
+    return { maxRetries: r.maxRetries, ...(r.failoverTo !== undefined ? { failoverTo: r.failoverTo } : {}) };
+}
+function settingsInit(s) {
+    return {
+        ...(s.timeout ? { timeoutMillis: BigInt(s.timeout.toMillis()) } : {}),
+        ...(s.defaultStepTimeout ? { defaultStepTimeoutMillis: BigInt(s.defaultStepTimeout.toMillis()) } : {}),
+        ...(s.defaultRecovery ? { defaultRecovery: recoveryInit(s.defaultRecovery) } : {}),
+        steps: Object.entries(s.steps ?? {})
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([step, st]) => ({
+            step,
+            ...(st.timeout ? { timeoutMillis: BigInt(st.timeout.toMillis()) } : {}),
+            ...(st.recovery ? { recovery: recoveryInit(st.recovery) } : {}),
+        })),
+    };
+}
+function componentInit(c) {
+    const base = { kind: kindToProto(c.kind), id: c.id };
+    switch (c.kind) {
+        case "event-sourced":
+            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "eventSourced", value: { snapshotEvery: c.snapshotEvery } } };
+        case "key-value":
+            return { ...base, handlers: handlerInits(c.handlers), detail: { case: "keyValue", value: {} } };
+        case "workflow":
+            return {
+                ...base,
+                handlers: handlerInits(c.handlers),
+                detail: { case: "workflow", value: { steps: [...c.steps.keys()].sort(), ...(c.settings ? { settings: settingsInit(c.settings) } : {}) } },
+            };
+        case "view":
+            return { ...base, handlers: [], detail: { case: "view", value: { source: sourceInit(c.source), rowManifest: c.rowCodec.manifest, queries: [...c.queries] } } };
+        case "consumer":
+            return { ...base, handlers: [], detail: { case: "consumer", value: { source: sourceInit(c.source), ...(c.producesTo !== undefined ? { producesTo: c.producesTo } : {}) } } };
+        case "timed-action":
+            return { ...base, handlers: handlerInits(c.actions), detail: { case: "timedAction", value: {} } };
+        case "agent":
+            return {
+                ...base,
+                handlers: handlerInits(c.handlers),
+                detail: {
+                    case: "agent",
+                    value: {
+                        role: c.role,
+                        maxToolCallSteps: c.maxToolCallSteps,
+                        tools: [...c.tools.values()]
+                            .sort((a, b) => a.name.localeCompare(b.name))
+                            .map((t) => ({ name: t.name, description: t.description, inputSchemaJson: JSON.stringify(isCodec(t.input) ? { type: "object" } : toJsonSchema(t.input)) })),
+                        guardrails: [...c.guardrails.keys()].sort(),
+                    },
+                },
+            };
+    }
+}
+export function renderSpec(registry) {
+    const components = [...registry.components.values()].sort((a, b) => a.id.localeCompare(b.id)).map(componentInit);
+    const endpoints = [...registry.endpoints.values()].map((e) => ({
+        id: e.id,
+        prefix: e.prefix,
+        acl: aclToProto(e.acl),
+        routes: [...e.routes.entries()].map(([id, r]) => ({
+            id,
+            method: r.method,
+            template: r.template,
+            hasBody: r.body !== undefined,
+            streaming: r.streaming,
+            ...(r.acl !== undefined ? { acl: aclToProto(r.acl) } : {}),
+        })),
+    }));
+    return create(SpecSchema, {
+        protocolVersion: PROTOCOL_VERSION,
+        sdk: { name: SDK_NAME, version: VERSION },
+        components,
+        endpoints,
+    });
+}

package/dist/testkit/index.d.ts

@@ -0,0 +1,3 @@
+export { EventSourcedTestKit, EndpointTestKit, Response, type RequestOptions, type Materialised } from "./unit.ts";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, type WorkflowProgress, type ModelResponse, type ModelCall, } from "./kinds.ts";
+export { AnkkaTestKit, type AnkkaTestKitOptions, type HttpResponse, type Http, type Beside } from "./integration.ts";

package/dist/testkit/index.js

@@ -0,0 +1,6 @@
+// `import { ... } from "ankka/testkit"`: the unit testkits (no sidecar) and the integration testkit
+// (Postgres and the real sidecar image in Docker). The integration testkit's Docker dependencies,
+// `testcontainers` and `@testcontainers/postgresql`, are loaded only when `AnkkaTestKit.start` runs.
+export { EventSourcedTestKit, EndpointTestKit, Response } from "./unit.js";
+export { KeyValueTestKit, WorkflowTestKit, ViewTestKit, ConsumerTestKit, TimedActionTestKit, AgentTestKit, ScriptedModel, } from "./kinds.js";
+export { AnkkaTestKit } from "./integration.js";

package/dist/testkit/integration.d.ts

@@ -0,0 +1,60 @@
+import type { ComponentClient } from "../client.ts";
+import type { ServiceBuilder } from "../service.ts";
+export interface AnkkaTestKitOptions {
+    /** The sidecar image; `$ANKKA_SIDECAR_IMAGE` or `ankka-sidecar:latest` by default. */
+    readonly image?: string;
+    /** Environment for the sidecar container: `ANKKA_MODEL_SCRIPT` scripts its model. */
+    readonly env?: Readonly<Record<string, string>>;
+    readonly postgresImage?: string;
+    /** How long to wait for the sidecar to report healthy; 120s by default. */
+    readonly readyTimeoutMs?: number;
+    readonly log?: (message: string) => void;
+}
+/** What `http` answers with. */
+export declare class HttpResponse {
+    readonly status: number;
+    readonly headers: globalThis.Headers;
+    readonly body: Uint8Array;
+    constructor(status: number, headers: globalThis.Headers, body: Uint8Array);
+    text(): string;
+    json(): unknown;
+}
+/** A small HTTP client over `fetch` for the sidecar's routes. */
+export declare class Http {
+    readonly baseUrl: string;
+    constructor(baseUrl: string);
+    request(method: string, path: string, body?: unknown, headers?: Record<string, string>): Promise<HttpResponse>;
+    get(path: string, headers?: Record<string, string>): Promise<HttpResponse>;
+    post(path: string, body?: unknown, headers?: Record<string, string>): Promise<HttpResponse>;
+    put(path: string, body?: unknown, headers?: Record<string, string>): Promise<HttpResponse>;
+    delete(path: string, headers?: Record<string, string>): Promise<HttpResponse>;
+    /** The frames of an SSE response, each `data:` line decoded from its JSON. */
+    sse(path: string, headers?: Record<string, string>): Promise<string[]>;
+}
+/** Another service started on this kit's database, from `startBeside`. */
+export interface Beside {
+    readonly http: Http;
+    logs(): Promise<string>;
+    stop(): Promise<void>;
+}
+export declare class AnkkaTestKit {
+    #private;
+    /** The component client every handler in `service` uses, pointed at the sidecar's mapped callback port. */
+    readonly client: ComponentClient;
+    private constructor();
+    /** Starts Postgres, this process's server and the sidecar; a start that fails half-way stops what it started. */
+    static start(service: ServiceBuilder, options?: AnkkaTestKitOptions): Promise<AnkkaTestKit>;
+    /** The sidecar's HTTP surface: the routes this service declared. */
+    get http(): Http;
+    get baseUrl(): string;
+    /** The JDBC URL of the throwaway database. */
+    get jdbcUrl(): string;
+    /** Replaces the sidecar against the same database: every instance is gone from memory, so the next read rebuilds from the journal. */
+    restart(): Promise<void>;
+    /** Starts another image against this kit's Postgres — the Scala cart, say, to prove the journal is shared. */
+    startBeside(image: string, env?: Readonly<Record<string, string>>, httpPort?: number): Promise<Beside>;
+    /** The sidecar container's log so far. */
+    sidecarLogs(): Promise<string>;
+    stop(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}