ankka 0.6.0

package/dist/server/server.js

@@ -0,0 +1,101 @@
+// The process side of the protocol: an HTTP/2 server on loopback carrying Connect's adapter, speaking
+// gRPC to the sidecar. HTTP/2 because the gRPC protocol and the per-instance bidirectional streams
+// need it; loopback because the protocol is never reachable from outside the pod, and `0.0.0.0` only for
+// the integration testkit, whose sidecar reaches this process from a container.
+import { createServer } from "node:http2";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import { renderSpec } from "../spec.js";
+import { discoveryRoutes } from "./discovery.js";
+import { eventSourcedRoutes } from "./eventSourced.js";
+import { keyValueRoutes } from "./keyValue.js";
+import { workflowRoutes } from "./workflow.js";
+import { statelessRoutes } from "./stateless.js";
+import { agentRoutes } from "./agent.js";
+import { httpRoutes } from "./http.js";
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0", "::"]);
+export class Server {
+    #context;
+    #options;
+    #shutdown = new AbortController();
+    #sessions = new Set();
+    #http2;
+    #address;
+    #resolveClosed;
+    closed = new Promise((resolve) => {
+        this.#resolveClosed = resolve;
+    });
+    constructor(registry, client, options = {}) {
+        this.#context = { registry, client, log: options.log ?? ((m) => console.error(m)) };
+        this.#options = options;
+    }
+    /** Binds and starts serving. Resolves with the bound address, which matters when `port` was 0. */
+    async start() {
+        if (this.#http2)
+            throw new Error("the server is already started");
+        const host = this.#options.host ?? "127.0.0.1";
+        if (!LOOPBACK.has(host)) {
+            throw new Error(`ankka serves the protocol on loopback only (or 0.0.0.0 for the testkit); refusing to bind ${host}`);
+        }
+        const port = this.#options.port ?? Number(process.env.ANKKA_PROCESS_PORT ?? 9010);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error(`not a port: ${String(port)}`);
+        const handler = connectNodeAdapter({
+            routes: (router) => {
+                discoveryRoutes(router, () => renderSpec(this.#context.registry), this.#context.log);
+                eventSourcedRoutes(router, this.#context);
+                keyValueRoutes(router, this.#context);
+                workflowRoutes(router, this.#context);
+                statelessRoutes(router, this.#context);
+                agentRoutes(router, this.#context);
+                httpRoutes(router, this.#context);
+            },
+            shutdownSignal: this.#shutdown.signal,
+            readMaxBytes: this.#options.readMaxBytes ?? 64 * 1024 * 1024,
+            grpcWeb: false,
+            connect: false,
+        });
+        const server = createServer({ maxSessionMemory: 64 }, handler);
+        this.#http2 = server;
+        // `server.close()` waits for every session to end, and a client keeps an idle session open for
+        // minutes; `stop` closes the sessions it knows about so a stop is a stop.
+        server.on("session", (session) => {
+            this.#sessions.add(session);
+            session.once("close", () => this.#sessions.delete(session));
+        });
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(port, host, () => {
+                server.off("error", reject);
+                resolve();
+            });
+        });
+        const info = server.address();
+        this.#address = { host, port: info.port };
+        server.on("close", () => this.#resolveClosed());
+        return this.#address;
+    }
+    /** The bound address; throws before `start`. */
+    get address() {
+        if (!this.#address)
+            throw new Error("the server is not started");
+        return this.#address;
+    }
+    /** Aborts every stream, closes every session and the listener, and resolves `closed`. */
+    async stop() {
+        const server = this.#http2;
+        if (!server)
+            return;
+        this.#shutdown.abort();
+        const closing = new Promise((resolve) => server.close(() => resolve()));
+        for (const session of this.#sessions)
+            session.close();
+        const grace = setTimeout(() => {
+            for (const session of this.#sessions)
+                session.destroy();
+        }, 250);
+        await closing;
+        clearTimeout(grace);
+        this.#http2 = undefined;
+        this.#resolveClosed();
+    }
+}

package/dist/server/stateless.d.ts

@@ -0,0 +1,9 @@
+import { type ConnectRouter } from "@connectrpc/connect";
+import { type ViewEffect as ProtoViewEffect, type ViewRequest } from "../_proto/ankka/protocol/v1/view_pb.ts";
+import { type ConsumerEffect as ProtoConsumerEffect, type ConsumerRequest } from "../_proto/ankka/protocol/v1/consumer_pb.ts";
+import { type TimedActionEffect as ProtoTimedActionEffect, type TimedActionRequest } from "../_proto/ankka/protocol/v1/timed_action_pb.ts";
+import type { ServerContext } from "./server.ts";
+export declare function handleView(req: ViewRequest, ctx: ServerContext): Promise<ProtoViewEffect>;
+export declare function handleConsumer(req: ConsumerRequest, ctx: ServerContext): Promise<ProtoConsumerEffect>;
+export declare function handleTimedAction(req: TimedActionRequest, ctx: ServerContext): Promise<ProtoTimedActionEffect>;
+export declare function statelessRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/stateless.js

@@ -0,0 +1,108 @@
+// The stateless conversations: a view's change, a consumer's message, a timed action's call. A new
+// instance per request; nothing is held between requests.
+import { Code, ConnectError } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { View as ViewService, ViewEffectSchema } from "../_proto/ankka/protocol/v1/view_pb.js";
+import { Consumer as ConsumerService, ConsumerEffectSchema } from "../_proto/ankka/protocol/v1/consumer_pb.js";
+import { TimedAction as TimedActionService, TimedActionEffectSchema } from "../_proto/ankka/protocol/v1/timed_action_pb.js";
+import { codecFor } from "../codec.js";
+import { metadataFromProto, metadataToProto } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
+import { errorCodeToProto } from "../kinds.js";
+import { decodePayload, encodePayload } from "./payloads.js";
+function messageOf(e) {
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+export async function handleView(req, ctx) {
+    const registered = ctx.registry.of("view", req.componentId);
+    if (!registered)
+        throw new ConnectError(`no view ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
+    const metadata = metadataFromProto(req.metadata);
+    const view = new registered.cls();
+    try {
+        const row = req.row ? decodePayload(registered.rowCodec, req.row) : null;
+        view._bind(row, metadata, ctx.client.withMetadata(metadata));
+        const effect = req.deleted ? await view.onDelete() : await view.onChange(decodePayload(registered.eventCodec, req.event));
+        switch (effect.kind) {
+            case "update-row":
+                return create(ViewEffectSchema, { effect: { case: "updateRow", value: encodePayload(registered.rowCodec, effect.row) } });
+            case "delete-row":
+                return create(ViewEffectSchema, { effect: { case: "deleteRow", value: {} } });
+            case "ignore":
+                return create(ViewEffectSchema, { effect: { case: "ignore", value: {} } });
+            default:
+                throw new TypeError(`${registered.id}.onChange returned something that is not a view effect`);
+        }
+    }
+    catch (e) {
+        if (e instanceof ConnectError)
+            throw e;
+        ctx.log(`ankka: view ${registered.id} on ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        throw new ConnectError(messageOf(e), Code.Internal);
+    }
+}
+export async function handleConsumer(req, ctx) {
+    const registered = ctx.registry.of("consumer", req.componentId);
+    if (!registered)
+        throw new ConnectError(`no consumer ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
+    const metadata = metadataFromProto(req.metadata);
+    const consumer = new registered.cls();
+    try {
+        consumer._bind(metadata, ctx.client.withMetadata(metadata));
+        const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+        switch (effect.kind) {
+            case "produce": {
+                if (!registered.outCodec)
+                    throw new Error(`${registered.id} produced a message but declares no out shape`);
+                return create(ConsumerEffectSchema, { effect: { case: "produce", value: { payload: encodePayload(registered.outCodec, effect.payload), metadata: metadataToProto(effect.metadata) } } });
+            }
+            case "done":
+                return create(ConsumerEffectSchema, { effect: { case: "done", value: {} } });
+            case "ignore":
+                return create(ConsumerEffectSchema, { effect: { case: "ignore", value: {} } });
+            default:
+                throw new TypeError(`${registered.id}.onMessage returned something that is not a consumer effect`);
+        }
+    }
+    catch (e) {
+        if (e instanceof ConnectError)
+            throw e;
+        ctx.log(`ankka: consumer ${registered.id} on ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        throw new ConnectError(messageOf(e), Code.Internal);
+    }
+}
+export async function handleTimedAction(req, ctx) {
+    const fail = (message, code = ErrorCode.Internal) => create(TimedActionEffectSchema, { effect: { case: "fail", value: { message, code: errorCodeToProto(code) } } });
+    const registered = ctx.registry.of("timed-action", req.componentId);
+    if (!registered)
+        return fail(`no timed action ${JSON.stringify(req.componentId)} is registered`, ErrorCode.NotFound);
+    const action = registered.actions.get(req.name);
+    if (!action)
+        return fail(`no action ${JSON.stringify(req.name)} on ${registered.id}`, ErrorCode.NotFound);
+    const metadata = metadataFromProto(req.metadata);
+    const instance = new registered.cls();
+    try {
+        const input = action.input ? decodePayload(codecFor(action.input), req.payload) : undefined;
+        instance._bind(metadata, ctx.client.withMetadata(metadata));
+        const effect = await action.run(instance, input);
+        switch (effect.kind) {
+            case "done":
+                return create(TimedActionEffectSchema, { effect: { case: "done", value: {} } });
+            case "fail": {
+                const f = effect;
+                return fail(f.error.message, f.error.code);
+            }
+            default:
+                return fail(`${registered.id}/${req.name} returned something that is not a timed action effect`);
+        }
+    }
+    catch (e) {
+        ctx.log(`ankka: timed action ${registered.id}/${req.name} threw: ${messageOf(e)}`);
+        return fail(messageOf(e));
+    }
+}
+export function statelessRoutes(router, ctx) {
+    router.service(ViewService, { handle: (req) => handleView(req, ctx) });
+    router.service(ConsumerService, { handle: (req) => handleConsumer(req, ctx) });
+    router.service(TimedActionService, { invoke: (req) => handleTimedAction(req, ctx) });
+}

package/dist/server/workflow.d.ts

@@ -0,0 +1,5 @@
+import type { ConnectRouter } from "@connectrpc/connect";
+import { type WorkflowIn, type WorkflowOut } from "../_proto/ankka/protocol/v1/workflow_pb.ts";
+import type { ServerContext } from "./server.ts";
+export declare function handleWorkflow(requests: AsyncIterable<WorkflowIn>, ctx: ServerContext): AsyncIterable<WorkflowOut>;
+export declare function workflowRoutes(router: ConnectRouter, ctx: ServerContext): void;

package/dist/server/workflow.js

@@ -0,0 +1,244 @@
+// The workflow conversation: one bidirectional stream per loaded instance, carrying commands *and*
+// steps. The engine keeps answering commands while a step runs, so this side holds two slots: the
+// stream's own instance answers commands from the state before the step, and each step runs on a fresh
+// instance so the two never share a context. Replies leave through one queue, so a command is never
+// stuck behind a step.
+import { create } from "@bufbuild/protobuf";
+import { Workflow as WorkflowService, WorkflowOutSchema, } from "../_proto/ankka/protocol/v1/workflow_pb.js";
+import { binaryCodecs, codecFor } from "../codec.js";
+import { commandContext, metadataFromProto } from "../context.js";
+import { ErrorCode } from "../effects/common.js";
+import { errorCodeToProto } from "../kinds.js";
+import { materialiseStep, materialiseWorkflowCommand } from "../materialise.js";
+import { decodePayload, encodePayload } from "./payloads.js";
+import { AsyncQueue } from "./queue.js";
+function failure(commandId, error) {
+    return create(WorkflowOutSchema, { message: { case: "failure", value: { commandId, error: { message: error.message, code: errorCodeToProto(error.code) } } } });
+}
+function messageOf(e) {
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+/** A step reference as the protocol carries it; the input is encoded with the *target* step's declared shape. */
+function stepRefInit(registered, ref) {
+    const target = registered.steps.get(ref.step);
+    if (!target)
+        throw new Error(`transition to ${JSON.stringify(ref.step)}, which is not a declared step`);
+    if (ref.input === undefined || ref.input === null)
+        return { step: ref.step };
+    if (!target.input)
+        throw new Error(`step ${JSON.stringify(ref.step)} takes no input, but one was given`);
+    return { step: ref.step, input: encodePayload(codecFor(target.input), ref.input) };
+}
+class WorkflowStream {
+    registered;
+    instance;
+    entityId;
+    state;
+    running;
+    out = new AsyncQueue();
+    constructor(registered, instance, entityId, state) {
+        this.registered = registered;
+        this.instance = instance;
+        this.entityId = entityId;
+        this.state = state;
+    }
+    async command(cmd, ctx) {
+        const { registered, instance } = this;
+        const handler = registered.handlers.get(cmd.name);
+        if (!handler)
+            return failure(cmd.id, { message: `no handler ${JSON.stringify(cmd.name)} on ${registered.id}`, code: ErrorCode.NotFound });
+        let input;
+        try {
+            input = handler.input ? decodePayload(codecFor(handler.input), cmd.payload) : undefined;
+        }
+        catch (e) {
+            return failure(cmd.id, { message: `${registered.id}/${cmd.name}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest });
+        }
+        const metadata = metadataFromProto(cmd.metadata);
+        let effect;
+        instance._bindCommand(this.state, commandContext(registered.id, this.entityId, 0n, metadata), ctx.client.withMetadata(metadata));
+        try {
+            effect = (await handler.run(instance, input));
+        }
+        catch (e) {
+            ctx.log(`ankka: ${registered.id}/${this.entityId}/${cmd.name} threw: ${messageOf(e)}`);
+            return failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal });
+        }
+        finally {
+            instance._unbindCommand();
+        }
+        if (handler.readOnly && effect?.kind !== "read-only") {
+            return failure(cmd.id, { message: `${registered.id}/${cmd.name} is a query and returned a changing effect`, code: ErrorCode.Internal });
+        }
+        try {
+            const m = materialiseWorkflowCommand(effect, this.state);
+            const replyCodec = handler.reply ? codecFor(handler.reply) : binaryCodecs.done;
+            const outcome = m.error
+                ? { outcome: { case: "error", value: { message: m.error.message, code: errorCodeToProto(m.error.code) } } }
+                : m.noReply
+                    ? { outcome: { case: "noReply", value: {} } }
+                    : { outcome: { case: "reply", value: { payload: encodePayload(replyCodec, m.reply), metadata: { entries: [] } } } };
+            const out = create(WorkflowOutSchema, {
+                message: {
+                    case: "reply",
+                    value: {
+                        commandId: cmd.id,
+                        newState: m.changed && !m.error ? encodePayload(registered.stateCodec, m.newState) : undefined,
+                        transition: m.transition && !m.error ? stepRefInit(registered, m.transition) : undefined,
+                        outcome,
+                    },
+                },
+            });
+            if (!m.error)
+                this.state = m.newState;
+            return out;
+        }
+        catch (e) {
+            ctx.log(`ankka: ${registered.id}/${this.entityId}/${cmd.name}: the effect could not be applied: ${messageOf(e)}`);
+            return failure(cmd.id, { message: messageOf(e), code: ErrorCode.Internal });
+        }
+    }
+    /** Runs a step on a fresh instance, as the sidecar's engine does: commands keep arriving on the stream's instance meanwhile. */
+    async step(run, ctx) {
+        const { registered } = this;
+        const step = registered.steps.get(run.step);
+        if (!step)
+            return failure(run.id, { message: `no step ${JSON.stringify(run.step)} on ${registered.id}`, code: ErrorCode.NotFound });
+        const fresh = new registered.cls();
+        fresh._bindInstance(this.entityId);
+        let input;
+        try {
+            input = step.input ? decodePayload(codecFor(step.input), run.input) : undefined;
+        }
+        catch (e) {
+            return failure(run.id, { message: `${registered.id}/${run.step}: the input could not be decoded: ${messageOf(e)}`, code: ErrorCode.BadRequest });
+        }
+        let effect;
+        fresh._bindCommand(this.state, commandContext(registered.id, this.entityId, 0n, {}), ctx.client);
+        try {
+            effect = (await step.run(fresh, input));
+        }
+        catch (e) {
+            // A thrown step is a *fault*: the engine applies the declared recovery. A `thenFail` is a decision.
+            ctx.log(`ankka: ${registered.id}/${this.entityId} step ${run.step} threw: ${messageOf(e)}`);
+            return failure(run.id, { message: messageOf(e), code: ErrorCode.Internal });
+        }
+        finally {
+            fresh._unbindCommand();
+        }
+        try {
+            const m = materialiseStep(effect, this.state);
+            let next;
+            switch (m.next.kind) {
+                case "transition":
+                    next = { outcome: { case: "transitionTo", value: stepRefInit(registered, m.next.ref) } };
+                    break;
+                case "pause":
+                    next = {
+                        outcome: {
+                            case: "pause",
+                            value: {
+                                ...(m.next.after ? { afterMillis: BigInt(m.next.after.toMillis()) } : {}),
+                                ...(m.next.onTimeout ? { onTimeout: stepRefInit(registered, m.next.onTimeout) } : {}),
+                            },
+                        },
+                    };
+                    break;
+                case "end":
+                    next = { outcome: { case: "end", value: {} } };
+                    break;
+                case "fail":
+                    next = { outcome: { case: "fail", value: { message: m.next.error.message, code: errorCodeToProto(m.next.error.code) } } };
+                    break;
+            }
+            const out = create(WorkflowOutSchema, {
+                message: { case: "stepReply", value: { commandId: run.id, newState: m.changed ? encodePayload(registered.stateCodec, m.newState) : undefined, next } },
+            });
+            this.state = m.newState;
+            return out;
+        }
+        catch (e) {
+            ctx.log(`ankka: ${registered.id}/${this.entityId} step ${run.step}: the effect could not be applied: ${messageOf(e)}`);
+            return failure(run.id, { message: messageOf(e), code: ErrorCode.Internal });
+        }
+    }
+}
+export async function* handleWorkflow(requests, ctx) {
+    const out = new AsyncQueue();
+    let stream;
+    const read = async () => {
+        try {
+            for await (const m of requests) {
+                switch (m.message.case) {
+                    case "init": {
+                        const init = m.message.value;
+                        const found = ctx.registry.of("workflow", init.componentId);
+                        if (!found) {
+                            out.push(failure(0n, { message: `no workflow ${JSON.stringify(init.componentId)} is registered`, code: ErrorCode.NotFound }));
+                            return;
+                        }
+                        try {
+                            const instance = new found.cls();
+                            instance._bindInstance(init.entityId);
+                            const state = init.state ? decodePayload(found.stateCodec, init.state) : instance.emptyState();
+                            stream = new WorkflowStream(found, instance, init.entityId, state);
+                        }
+                        catch (e) {
+                            ctx.log(`ankka: ${init.componentId}/${init.entityId}: recovery failed: ${messageOf(e)}`);
+                            out.push(failure(0n, { message: `recovery failed: ${messageOf(e)}`, code: ErrorCode.Internal }));
+                            return;
+                        }
+                        break;
+                    }
+                    case "command": {
+                        if (!stream) {
+                            out.push(failure(m.message.value.id, { message: "a command arrived before Init", code: ErrorCode.Internal }));
+                            return;
+                        }
+                        out.push(await stream.command(m.message.value, ctx));
+                        break;
+                    }
+                    case "runStep": {
+                        if (!stream) {
+                            out.push(failure(m.message.value.id, { message: "a step arrived before Init", code: ErrorCode.Internal }));
+                            return;
+                        }
+                        if (stream.running) {
+                            out.push(failure(m.message.value.id, { message: "a step is already running", code: ErrorCode.Internal }));
+                            break;
+                        }
+                        const s = stream;
+                        const run = m.message.value;
+                        s.running = s
+                            .step(run, ctx)
+                            .then((reply) => out.push(reply))
+                            .finally(() => {
+                            s.running = undefined;
+                        });
+                        break;
+                    }
+                    default:
+                        break;
+                }
+            }
+        }
+        catch (e) {
+            out.fail(e);
+            return;
+        }
+        // The sidecar closed its side: a step still running has nowhere to answer; its result is dropped with the state.
+        out.close();
+    };
+    void read();
+    try {
+        yield* out;
+    }
+    finally {
+        out.close();
+    }
+}
+export function workflowRoutes(router, ctx) {
+    router.service(WorkflowService, {
+        handle: (requests) => handleWorkflow(requests, ctx),
+    });
+}

package/dist/service.d.ts

@@ -0,0 +1,147 @@
+import { type Codec } from "./codec.ts";
+import { EventSourcedEntity, type EventSourcedEntityClass } from "./eventSourcedEntity.ts";
+import { KeyValueEntity, type KeyValueEntityClass } from "./keyValueEntity.ts";
+import { Workflow, type WorkflowClass } from "./workflow.ts";
+import { View, type ViewClass } from "./view.ts";
+import { Consumer, type ConsumerClass } from "./consumer.ts";
+import { TimedAction, type TimedActionClass } from "./timedAction.ts";
+import { Agent, type AgentClass } from "./agent.ts";
+import { Endpoint, type EndpointClass } from "./endpoint.ts";
+import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
+import type { RouteRef, Acl } from "./routes.ts";
+import { ComponentClient } from "./client.ts";
+import type { ComponentKind } from "./kinds.ts";
+import type { WorkflowSettings } from "./effects/workflow.ts";
+import { Server, type ServerOptions } from "./server/server.ts";
+import type { Spec } from "./_proto/ankka/protocol/v1/discovery_pb.ts";
+export interface RegisteredEventSourced {
+    readonly kind: "event-sourced";
+    readonly id: string;
+    readonly cls: EventSourcedEntityClass<any, any, any>;
+    readonly stateCodec: Codec<any>;
+    readonly eventCodec: Codec<any>;
+    readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+    readonly snapshotEvery: number;
+}
+export interface RegisteredKeyValue {
+    readonly kind: "key-value";
+    readonly id: string;
+    readonly cls: KeyValueEntityClass<any, any>;
+    readonly stateCodec: Codec<any>;
+    readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+}
+export interface RegisteredWorkflow {
+    readonly kind: "workflow";
+    readonly id: string;
+    readonly cls: WorkflowClass<any, any>;
+    readonly stateCodec: Codec<any>;
+    readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+    readonly steps: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+    readonly settings: WorkflowSettings | undefined;
+}
+/** Where a view or consumer reads from: a component, by kind and id, or a topic. */
+export type Source = {
+    readonly component: {
+        readonly kind: ComponentKind;
+        readonly id: string;
+    };
+} | {
+    readonly topic: string;
+};
+export interface RegisteredView {
+    readonly kind: "view";
+    readonly id: string;
+    readonly cls: ViewClass<any, any, any>;
+    readonly source: Source;
+    readonly eventCodec: Codec<any>;
+    readonly rowCodec: Codec<any>;
+    readonly queries: readonly string[];
+}
+export interface RegisteredConsumer {
+    readonly kind: "consumer";
+    readonly id: string;
+    readonly cls: ConsumerClass<any, any, any>;
+    readonly source: Source;
+    readonly messageCodec: Codec<any>;
+    readonly outCodec: Codec<any> | undefined;
+    readonly producesTo: string | undefined;
+}
+export interface RegisteredTimedAction {
+    readonly kind: "timed-action";
+    readonly id: string;
+    readonly cls: TimedActionClass<any>;
+    readonly actions: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+}
+export interface RegisteredAgent {
+    readonly kind: "agent";
+    readonly id: string;
+    readonly cls: AgentClass<any>;
+    readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+    readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
+    readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly role: string;
+    readonly maxToolCallSteps: number;
+}
+export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent;
+export interface RegisteredEndpoint {
+    readonly id: string;
+    readonly cls: EndpointClass<any>;
+    readonly prefix: string;
+    readonly acl: Acl;
+    /** Route id (the property name) → route. */
+    readonly routes: ReadonlyMap<string, RouteRef<any, any, any, any>>;
+}
+/** Everything the service hosts, validated. */
+export declare class Registry {
+    readonly components: ReadonlyMap<string, RegisteredComponent>;
+    readonly endpoints: ReadonlyMap<string, RegisteredEndpoint>;
+    constructor(components: ReadonlyMap<string, RegisteredComponent>, endpoints: ReadonlyMap<string, RegisteredEndpoint>);
+    component(id: string): RegisteredComponent | undefined;
+    /** The component `id` when it is of `kind`. */
+    of<K extends RegisteredComponent["kind"]>(kind: K, id: string): Extract<RegisteredComponent, {
+        kind: K;
+    }> | undefined;
+    endpoint(id: string): RegisteredEndpoint | undefined;
+}
+/** Thrown by `validate`, `spec`, `server` and `listen` with every problem the registration has. */
+export declare class RegistrationError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+export interface ServiceOptions {
+    /** The client handlers receive; the default dials `ANKKA_SIDECAR_ADDRESS`. */
+    readonly client?: ComponentClient;
+    /** Where log lines go; the default is `console.error`. */
+    readonly log?: (message: string) => void;
+}
+export declare class ServiceBuilder {
+    #private;
+    constructor(options?: ServiceOptions);
+    /** The component client every handler receives; the integration testkit repoints it at the sidecar it started. */
+    get client(): ComponentClient;
+    /** Register a component or endpoint class. A class missing a static the kind requires is refused here, by the type checker. */
+    register<S, E, C extends EventSourcedEntity<S, E>>(cls: EventSourcedEntityClass<S, E, C>): this;
+    register<S, C extends KeyValueEntity<S>>(cls: KeyValueEntityClass<S, C>): this;
+    register<S, C extends Workflow<S>>(cls: WorkflowClass<S, C>): this;
+    register<E, Row, C extends View<E, Row>>(cls: ViewClass<E, Row, C>): this;
+    register<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>): this;
+    register<C extends TimedAction>(cls: TimedActionClass<C>): this;
+    register<C extends Agent>(cls: AgentClass<C>): this;
+    register<C extends Endpoint>(cls: EndpointClass<C>): this;
+    /** Validates every registration and returns the registry, or throws a `RegistrationError` naming every problem. */
+    validate(): Registry;
+    /** The discovery `Spec` for what is registered, without listening. */
+    spec(): Spec;
+    /** An unstarted server over the validated registry, for the integration testkit. */
+    server(options?: ServerOptions): Server;
+    /** Validates, binds `ANKKA_PROCESS_PORT` (default 9010) on loopback, answers discovery, and runs until stopped. */
+    listen(options?: ServerOptions): Promise<void>;
+}
+type Fail = (message: string) => void;
+/** Collects a handler table by wire name, reporting a duplicate wire name or a kind the component cannot host. */
+export declare function collectHandlers(table: unknown, what: string, allowed: readonly HandlerRef["kind"][], fail: Fail): ReadonlyMap<string, HandlerRef<any, any, any, any>>;
+/** The entry point: `Ankka.service().register(...).listen()`. */
+export declare const Ankka: Readonly<{
+    service(options?: ServiceOptions): ServiceBuilder;
+}>;
+export {};