ankka 0.9.1 → 0.11.0

package/dist/server/stateless.js

@@ -8,12 +8,54 @@ import { TimedAction as TimedActionService, TimedActionEffectSchema } from "../_
 import { codecFor } from "../codec.js";
 import { metadataFromProto, metadataToProto } from "../context.js";
 import { ErrorCode } from "../effects/common.js";
+import { clientRows } from "../keyedView.js";
+import { ProtocolVersionError, requireSeveralMessages } from "../consumer.js";
+import { GRAPH_DELTA_SCHEMA, deltaRecords } from "../graph.js";
+import { JSON_CONTENT } from "../codec.js";
 import { errorCodeToProto } from "../kinds.js";
 import { decodePayload, encodePayload } from "./payloads.js";
+import { PayloadSchema } from "../_proto/ankka/protocol/v1/payload_pb.js";
 function messageOf(e) {
     return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
 }
+/**
+ * A keyed view's change: sent with the component it came from and no row, answered with the rows the
+ * source's handler names. The view reads its own rows through the client, on its own id.
+ */
+async function handleKeyedView(req, sourceId, ctx) {
+    const registered = ctx.registry.of("keyed-view", req.componentId);
+    if (!registered)
+        throw new ConnectError(`no keyed view ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
+    const source = registered.sources.get(sourceId);
+    if (!source)
+        throw new ConnectError(`keyed view ${registered.id} reads no ${JSON.stringify(sourceId)}`, Code.NotFound);
+    const metadata = metadataFromProto(req.metadata);
+    const view = new registered.cls();
+    try {
+        const client = ctx.client.withMetadata(metadata);
+        view._bind(metadata, client, clientRows(client, registered.id, registered.rowCodec));
+        const effect = (req.deleted
+            ? source.deleted
+                ? await source.deleted(view)
+                : undefined
+            : await source.onChange(view, decodePayload(source.eventCodec, req.event)));
+        if (effect !== undefined && effect?.kind !== "rows")
+            throw new TypeError(`${registered.id}'s handler for ${sourceId} returned something that is not a keyed view effect`);
+        const changes = (effect?.changes ?? []).map((c) => "deleted" in c
+            ? { key: c.key, change: { case: "delete", value: {} } }
+            : { key: c.key, change: { case: "upsert", value: encodePayload(registered.rowCodec, c.row) } });
+        return create(ViewEffectSchema, { effect: { case: "rows", value: { changes } } });
+    }
+    catch (e) {
+        if (e instanceof ConnectError)
+            throw e;
+        ctx.log(`ankka: keyed view ${registered.id} on ${sourceId} ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        throw new ConnectError(messageOf(e), Code.Internal);
+    }
+}
 export async function handleView(req, ctx) {
+    if (req.sourceId !== undefined)
+        return handleKeyedView(req, req.sourceId, ctx);
     const registered = ctx.registry.of("view", req.componentId);
     if (!registered)
         throw new ConnectError(`no view ${JSON.stringify(req.componentId)} is registered`, Code.NotFound);
@@ -41,33 +83,79 @@ export async function handleView(req, ctx) {
         throw new ConnectError(messageOf(e), Code.Internal);
     }
 }
+const DONE = () => create(ConsumerEffectSchema, { effect: { case: "done", value: {} } });
+const IGNORE = () => create(ConsumerEffectSchema, { effect: { case: "ignore", value: {} } });
+/**
+ * Several messages as the reply `produce_all`, which only a runtime at protocol 1.3 understands: the
+ * request must have said so. None at all is `done`, which every runtime understands and means the same.
+ */
+function produceAll(request, messages) {
+    if (messages.length === 0)
+        return DONE();
+    requireSeveralMessages(request);
+    return create(ConsumerEffectSchema, {
+        effect: {
+            case: "produceAll",
+            value: { messages: messages.map((m) => ({ payload: m.payload, metadata: metadataToProto(m.metadata), ...(m.key !== undefined ? { key: m.key } : {}) })) },
+        },
+    });
+}
+async function graphEffect(registered, req, metadata, ctx) {
+    const consumer = new registered.cls();
+    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 "publish":
+            return produceAll(metadata, deltaRecords(effect, metadata).map((r) => ({
+                payload: create(PayloadSchema, { contentType: JSON_CONTENT, manifest: GRAPH_DELTA_SCHEMA, data: r.value }),
+                metadata: { "ce-type": GRAPH_DELTA_SCHEMA },
+                key: r.key,
+            })));
+        case "done":
+            return DONE();
+        case "ignore":
+            return IGNORE();
+        default:
+            throw new TypeError(`${registered.id}.onMessage returned something that is not a graph effect`);
+    }
+}
+async function consumerEffect(registered, req, metadata, ctx) {
+    const consumer = new registered.cls();
+    consumer._bind(metadata, ctx.client.withMetadata(metadata));
+    const effect = req.deleted ? await consumer.onDelete() : await consumer.onMessage(decodePayload(registered.messageCodec, req.message));
+    const outCodec = () => {
+        if (!registered.outCodec)
+            throw new Error(`${registered.id} produced a message but declares no out shape`);
+        return registered.outCodec;
+    };
+    switch (effect.kind) {
+        case "produce":
+            return create(ConsumerEffectSchema, { effect: { case: "produce", value: { payload: encodePayload(outCodec(), effect.payload), metadata: metadataToProto(effect.metadata) } } });
+        case "produceAll":
+            return produceAll(metadata, effect.messages.map((m) => ({ payload: encodePayload(outCodec(), m.payload), metadata: m.metadata ?? {}, ...(m.key !== undefined ? { key: m.key } : {}) })));
+        case "done":
+            return DONE();
+        case "ignore":
+            return IGNORE();
+        default:
+            throw new TypeError(`${registered.id}.onMessage returned something that is not a consumer effect`);
+    }
+}
 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`);
-        }
+        return registered.graph ? await graphEffect(registered, req, metadata, ctx) : await consumerEffect(registered, req, metadata, ctx);
     }
     catch (e) {
         if (e instanceof ConnectError)
             throw e;
         ctx.log(`ankka: consumer ${registered.id} on ${metadata["ce-subject"] ?? "?"} threw: ${messageOf(e)}`);
+        // The message alone, so the runtime's log says what the SDK needs and of which runtime.
+        if (e instanceof ProtocolVersionError)
+            throw new ConnectError(e.message, Code.Internal);
         throw new ConnectError(messageOf(e), Code.Internal);
     }
 }

package/dist/server/workflow.js

@@ -114,7 +114,11 @@ class WorkflowStream {
             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);
+        // What the sidecar says about this step: its trace, and the step as the caller of whatever it calls.
+        // Carried on the step's calls as a command's is; a sidecar before 1.3 sends none.
+        const metadata = metadataFromProto(run.metadata);
+        fresh._bindCommand(this.state, commandContext(registered.id, this.entityId, 0n, metadata), ctx.client.withMetadata(metadata));
+        fresh._enterStep();
         try {
             effect = (await step.run(fresh, input));
         }

package/dist/service.d.ts

@@ -1,11 +1,16 @@
+import { type StartFrom } from "./startFrom.ts";
+import { Contract, type Publication } from "./contract.ts";
 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 { View, type DeclaredQuery, type ViewClass } from "./view.ts";
+import { KeyedView, type KeyedViewClass } from "./keyedView.ts";
 import { Consumer, type ConsumerClass } from "./consumer.ts";
+import { GraphConsumer, type GraphConsumerClass } from "./graph.ts";
 import { TimedAction, type TimedActionClass } from "./timedAction.ts";
 import { Agent, type AgentClass } from "./agent.ts";
+import { type McpServerRef, type ResultGuardrailRef } from "./mcp.ts";
 import { AutonomousAgent, type AutonomousAgentClass, type TaskType } from "./autonomous.ts";
 import { Endpoint, type EndpointClass } from "./endpoint.ts";
 import type { GuardrailRef, HandlerRef, ToolRef } from "./handlers.ts";
@@ -48,6 +53,13 @@ export type Source = {
     };
 } | {
     readonly topic: string;
+    readonly startFrom?: StartFrom;
+    /** The contract the topic is expected to carry. */
+    readonly contract?: Contract;
+    /** The declared broker the topic is on; absent is the installation's. */
+    readonly broker?: string;
+    /** Partitions handled at once, each in order. */
+    readonly parallel?: boolean;
 };
 export interface RegisteredView {
     readonly kind: "view";
@@ -57,15 +69,39 @@ export interface RegisteredView {
     readonly eventCodec: Codec<any>;
     readonly rowCodec: Codec<any>;
     readonly queries: readonly string[];
+    readonly version: number | undefined;
+    readonly declared: readonly DeclaredQuery[];
+}
+/** One source of a keyed view: the entity it reads, how its changes decode, and its handlers. */
+export interface RegisteredKeyedSource {
+    readonly id: string;
+    readonly kind: ComponentKind;
+    readonly eventCodec: Codec<any>;
+    readonly onChange: (view: any, event: any) => unknown;
+    readonly deleted: ((view: any) => unknown) | undefined;
+}
+export interface RegisteredKeyedView {
+    readonly kind: "keyed-view";
+    readonly id: string;
+    readonly cls: KeyedViewClass<any, any>;
+    readonly sources: ReadonlyMap<string, RegisteredKeyedSource>;
+    readonly rowCodec: Codec<any>;
+    readonly version: number | undefined;
+    readonly declared: readonly DeclaredQuery[];
 }
 export interface RegisteredConsumer {
     readonly kind: "consumer";
     readonly id: string;
-    readonly cls: ConsumerClass<any, any, any>;
+    readonly cls: ConsumerClass<any, any, any> | GraphConsumerClass<any, any>;
     readonly source: Source;
     readonly messageCodec: Codec<any>;
     readonly outCodec: Codec<any> | undefined;
     readonly producesTo: string | undefined;
+    /** The publication as declared: the topic with the contract stated for it and its broker. */
+    readonly produces: Publication | undefined;
+    /** A graph consumer: its handlers return elements, each published as a delta under its element key. */
+    readonly graph: boolean;
+    readonly version: number | undefined;
 }
 export interface RegisteredTimedAction {
     readonly kind: "timed-action";
@@ -80,6 +116,8 @@ export interface RegisteredAgent {
     readonly handlers: ReadonlyMap<string, HandlerRef<any, any, any, any>>;
     readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
     readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly mcpServers: ReadonlyMap<string, McpServerRef>;
+    readonly resultGuardrails: ReadonlyMap<string, ResultGuardrailRef>;
     readonly role: string;
     readonly maxToolCallSteps: number;
 }
@@ -89,9 +127,11 @@ export interface RegisteredAutonomousAgent {
     readonly cls: AutonomousAgentClass<any>;
     readonly tools: ReadonlyMap<string, ToolRef<any, any>>;
     readonly guardrails: ReadonlyMap<string, GuardrailRef>;
+    readonly mcpServers: ReadonlyMap<string, McpServerRef>;
+    readonly resultGuardrails: ReadonlyMap<string, ResultGuardrailRef>;
     readonly taskTypes: ReadonlyMap<string, TaskType<any>>;
 }
-export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent | RegisteredAutonomousAgent;
+export type RegisteredComponent = RegisteredEventSourced | RegisteredKeyValue | RegisteredWorkflow | RegisteredView | RegisteredKeyedView | RegisteredConsumer | RegisteredTimedAction | RegisteredAgent | RegisteredAutonomousAgent;
 export interface RegisteredEndpoint {
     readonly id: string;
     readonly cls: EndpointClass<any>;
@@ -133,7 +173,9 @@ export declare class ServiceBuilder {
     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<Row, C extends KeyedView<Row>>(cls: KeyedViewClass<Row, C>): this;
     register<M, Out, C extends Consumer<M, Out>>(cls: ConsumerClass<M, Out, C>): this;
+    register<M, C extends GraphConsumer<M>>(cls: GraphConsumerClass<M, C>): this;
     register<C extends TimedAction>(cls: TimedActionClass<C>): this;
     register<C extends Agent>(cls: AgentClass<C>): this;
     register<C extends AutonomousAgent>(cls: AutonomousAgentClass<C>): this;

package/dist/service.js

@@ -3,14 +3,19 @@
 // time, and reported together before anything listens — the same rule as the Scala builder.
 //
 //   await Ankka.service().register(ShoppingCartEntity).register(ShoppingCartEndpoint).listen()
+import { isStartFrom } from "./startFrom.js";
+import { Contract } from "./contract.js";
 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 { KeyedView } from "./keyedView.js";
 import { Consumer } from "./consumer.js";
+import { GraphConsumer, graphDeltaCodec } from "./graph.js";
 import { TimedAction } from "./timedAction.js";
 import { Agent } from "./agent.js";
+import { serverProblems, TOOL_PREFIX } from "./mcp.js";
 import { AutonomousAgent, COMPLETE_TASK, FAIL_TASK } from "./autonomous.js";
 import { Endpoint } from "./endpoint.js";
 import { isAcl } from "./routes.js";
@@ -95,8 +100,12 @@ export class ServiceBuilder {
                 add(registerWorkflow(cls, problems), cls);
             else if (extendsBase(cls, View))
                 add(registerView(cls, problems), cls);
+            else if (extendsBase(cls, KeyedView))
+                add(registerKeyedView(cls, problems), cls);
             else if (extendsBase(cls, Consumer))
                 add(registerConsumer(cls, problems), cls);
+            else if (extendsBase(cls, GraphConsumer))
+                add(registerGraphConsumer(cls, problems), cls);
             else if (extendsBase(cls, TimedAction))
                 add(registerTimedAction(cls, problems), cls);
             else if (extendsBase(cls, Agent))
@@ -120,7 +129,7 @@ export class ServiceBuilder {
                 }
             }
             else {
-                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, Consumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
+                problems.push(`${nameOf(cls)} is not a component class: it must extend EventSourcedEntity, KeyValueEntity, Workflow, View, KeyedView, Consumer, GraphConsumer, TimedAction, Agent, AutonomousAgent or Endpoint`);
             }
         }
         if (problems.length > 0)
@@ -220,19 +229,59 @@ function registerWorkflow(cls, problems) {
         return undefined;
     return Object.freeze({ kind: "workflow", id: cls.componentId, cls, stateCodec: codecFor(cls.state), handlers, steps, settings });
 }
-function sourceOf(cls, fail) {
+/**
+ * What a view or consumer says about the topic it reads, checked where its other declarations are:
+ * a consumer must say where it starts, and a start position means something only for a topic. A
+ * version means something for a view whatever it reads — raising it rebuilds the view, from a topic
+ * as far back as the broker retains and from an entity from its first event — and for a consumer only
+ * over a topic, whose group it renames.
+ */
+function topicProblems(cls, consumer, fail) {
+    const readsTopic = cls.source === undefined && cls.topic !== undefined;
+    if (cls.startFrom !== undefined && !isStartFrom(cls.startFrom))
+        fail("startFrom must be StartFrom.earliest, StartFrom.latest or StartFrom.at(...)");
+    if (cls.startFrom !== undefined && !readsTopic)
+        fail("declares a start position, which applies to a topic; it reads a component");
+    if (consumer && readsTopic && cls.startFrom === undefined) {
+        fail(`reads topic ${JSON.stringify(cls.topic)} and declares no start position; declare static startFrom = StartFrom.earliest, StartFrom.latest or StartFrom.at(...)`);
+    }
+    if (cls.version !== undefined) {
+        if (typeof cls.version !== "number" || !Number.isSafeInteger(cls.version) || cls.version < 1) {
+            fail(`declares version ${String(cls.version)}; a version is a whole number of 1 or more`);
+        }
+        else if (consumer && !readsTopic)
+            fail("declares a version, which applies to a topic; it reads a component");
+    }
+    if (cls.contract !== undefined && !(cls.contract instanceof Contract))
+        fail("contract must be a Contract: Contract.fromFile(path, name)");
+    if (cls.broker !== undefined && (typeof cls.broker !== "string" || cls.broker.trim() === ""))
+        fail("broker must be the name of a broker the project declares");
+    if (cls.parallel !== undefined && typeof cls.parallel !== "boolean")
+        fail("parallel must be true or false");
+    if ((cls.contract !== undefined || cls.broker !== undefined || cls.parallel !== undefined) && !readsTopic) {
+        fail("declares a contract, a broker or parallel, which apply to a topic; it reads a component");
+    }
+}
+function sourceOf(cls, fail, consumer) {
     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;
     }
+    topicProblems(cls, consumer, fail);
     if (hasTopic) {
         if (typeof cls.topic !== "string" || cls.topic.trim() === "") {
             fail("topic must be a non-empty string");
             return undefined;
         }
-        return { topic: cls.topic };
+        return {
+            topic: cls.topic,
+            ...(isStartFrom(cls.startFrom) ? { startFrom: cls.startFrom } : {}),
+            ...(cls.contract instanceof Contract ? { contract: cls.contract } : {}),
+            ...(typeof cls.broker === "string" ? { broker: cls.broker } : {}),
+            ...(cls.parallel === true ? { parallel: true } : {}),
+        };
     }
     const src = cls.source;
     const kind = src?.prototype?._kind;
@@ -245,25 +294,112 @@ function sourceOf(cls, fail) {
 function registerView(cls, problems) {
     const { fail, ok } = checker(cls, problems);
     requireId(cls, fail);
-    const source = sourceOf(cls, fail);
+    const source = sourceOf(cls, fail, false);
     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");
+    const declared = cls.declared ?? [];
+    if (!Array.isArray(declared) || declared.some((q) => typeof q?.name !== "string" || q.name.trim() === "" || typeof q?.statement !== "string" || q.statement.trim() === "")) {
+        fail("declared must be a list of declaredQuery(name, statement)");
+    }
+    else {
+        const names = declared.map((q) => q.name);
+        const twice = names.filter((n, i) => names.indexOf(n) !== i);
+        if (twice.length > 0)
+            fail(`declares the query '${twice[0]}' twice; each query has a name of its own`);
+    }
     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]) });
+    return Object.freeze({
+        kind: "view",
+        id: cls.componentId,
+        cls,
+        source,
+        eventCodec: codecFor(cls.events),
+        rowCodec: codecFor(cls.row),
+        queries: Object.freeze([...queries]),
+        version: cls.version,
+        declared: Object.freeze([...declared]),
+    });
+}
+function checkVersion(version, fail) {
+    if (version !== undefined && (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1)) {
+        fail(`declares version ${String(version)}; a version is a whole number of 1 or more`);
+    }
+}
+function checkDeclared(declared, fail) {
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared) || declared.some((q) => typeof q?.name !== "string" || q.name.trim() === "" || typeof q?.statement !== "string" || q.statement.trim() === "")) {
+        fail("declared must be a list of declaredQuery(name, statement)");
+        return [];
+    }
+    const names = declared.map((q) => q.name);
+    const twice = names.filter((n, i) => names.indexOf(n) !== i);
+    if (twice.length > 0)
+        fail(`declares the query '${twice[0]}' twice; each query has a name of its own`);
+    return declared;
+}
+/**
+ * A keyed view: one or more entities, each through a handler of its own. A topic is not a keyed view's
+ * source, and one entity is read once.
+ */
+function registerKeyedView(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    requireShape(cls.row, "row: a schema or codec for its rows", fail);
+    checkVersion(cls.version, fail);
+    const declared = checkDeclared(cls.declared, fail);
+    const sources = new Map();
+    const declaredSources = cls.sources;
+    if (!Array.isArray(declaredSources) || declaredSources.length === 0) {
+        fail("declares no source; a keyed view reads one or more entities, each declared with on(...)");
+    }
+    else {
+        for (const [i, s] of declaredSources.entries()) {
+            const ref = s?.source;
+            const kind = ref?.prototype?._kind;
+            if (typeof s?.onChange !== "function" || typeof ref?.componentId !== "string" || typeof kind !== "string") {
+                fail(`sources[${i}] is not a source: declare it with on(EntityClass, events, handler)`);
+                continue;
+            }
+            if (kind !== "event-sourced" && kind !== "key-value") {
+                fail(`reads ${kind} ${JSON.stringify(ref.componentId)}; a keyed view reads event sourced and key value entities`);
+                continue;
+            }
+            if (!isShape(s.events)) {
+                fail(`sources[${i}] needs a schema or codec for ${ref.componentId}'s changes`);
+                continue;
+            }
+            if (sources.has(ref.componentId)) {
+                fail(`reads ${JSON.stringify(ref.componentId)} twice; each source is read once`);
+                continue;
+            }
+            sources.set(ref.componentId, Object.freeze({ id: ref.componentId, kind, eventCodec: codecFor(s.events), onChange: s.onChange, deleted: s.deleted }));
+        }
+    }
+    if (!ok())
+        return undefined;
+    return Object.freeze({
+        kind: "keyed-view",
+        id: cls.componentId,
+        cls,
+        sources,
+        rowCodec: codecFor(cls.row),
+        version: cls.version,
+        declared: Object.freeze([...declared]),
+    });
 }
 function registerConsumer(cls, problems) {
     const { fail, ok } = checker(cls, problems);
     requireId(cls, fail);
-    const source = sourceOf(cls, fail);
+    const source = sourceOf(cls, fail, true);
     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`);
+    const produces = publicationOf(cls.producesTo, fail);
+    if (produces !== undefined && !isShape(cls.out))
+        fail(`produces to ${JSON.stringify(produces.topic)} and needs a static out: the shape of what it produces`);
     if (!ok() || !source)
         return undefined;
     return Object.freeze({
@@ -273,7 +409,62 @@ function registerConsumer(cls, problems) {
         source,
         messageCodec: codecFor(cls.message),
         outCodec: cls.out ? codecFor(cls.out) : undefined,
+        producesTo: produces?.topic,
+        produces,
+        graph: false,
+        version: cls.version,
+    });
+}
+/**
+ * `producesTo` as declared: a topic name, or a Publication naming the topic with the contract stated
+ * for it and its broker. Undefined when the consumer produces nothing.
+ */
+function publicationOf(declared, fail) {
+    if (declared === undefined)
+        return undefined;
+    if (typeof declared === "string") {
+        if (declared.trim() === "")
+            fail("producesTo must be a topic name");
+        return declared.trim() === "" ? undefined : { topic: declared };
+    }
+    const p = declared;
+    if (typeof p !== "object" || p === null || typeof p.topic !== "string" || p.topic.trim() === "") {
+        fail("producesTo must be a topic name, or { topic, contract?, broker? }");
+        return undefined;
+    }
+    if (p.contract !== undefined && !(p.contract instanceof Contract))
+        fail("producesTo.contract must be a Contract: Contract.fromFile(path, name)");
+    if (p.broker !== undefined && (typeof p.broker !== "string" || p.broker.trim() === ""))
+        fail("producesTo.broker must be the name of a broker the project declares");
+    return {
+        topic: p.topic,
+        ...(p.contract instanceof Contract ? { contract: p.contract } : {}),
+        ...(typeof p.broker === "string" ? { broker: p.broker } : {}),
+    };
+}
+/** A graph consumer is a consumer to discovery and to the runtime: one that produces deltas to its topic. */
+function registerGraphConsumer(cls, problems) {
+    const { fail, ok } = checker(cls, problems);
+    requireId(cls, fail);
+    const source = sourceOf(cls, fail, true);
+    requireShape(cls.message, "message: a schema or codec for the source's messages", fail);
+    if (typeof cls.producesTo !== "string" || cls.producesTo.trim() === "")
+        fail("needs a static producesTo: the topic its deltas are published to");
+    if (cls.out !== undefined)
+        fail("declares a static out, which a graph consumer does not have: what it produces is graph deltas");
+    if (!ok() || !source)
+        return undefined;
+    return Object.freeze({
+        kind: "consumer",
+        id: cls.componentId,
+        cls,
+        source,
+        messageCodec: codecFor(cls.message),
+        outCodec: graphDeltaCodec,
         producesTo: cls.producesTo,
+        produces: undefined,
+        graph: true,
+        version: cls.version,
     });
 }
 function registerTimedAction(cls, problems) {
@@ -313,9 +504,10 @@ function registerAgent(cls, problems) {
     const maxToolCallSteps = cls.maxToolCallSteps ?? 100;
     if (!Number.isInteger(maxToolCallSteps) || maxToolCallSteps <= 0)
         fail("maxToolCallSteps must be a positive integer");
+    const { mcpServers, resultGuardrails } = collectMcp(cls, tools, fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, role: cls.role ?? "", maxToolCallSteps });
+    return Object.freeze({ kind: "agent", id: cls.componentId, cls, handlers, tools, guardrails, mcpServers, resultGuardrails, role: cls.role ?? "", maxToolCallSteps });
 }
 function registerAutonomousAgent(cls, problems) {
     const { fail, ok } = checker(cls, problems);
@@ -351,9 +543,39 @@ function registerAutonomousAgent(cls, problems) {
             fail(`task type ${JSON.stringify(a.taskType.name)} needs a budget of at least one iteration`);
         taskTypes.set(a.taskType.name, a.taskType);
     }
+    const { mcpServers, resultGuardrails } = collectMcp(cls, tools, fail);
     if (!ok())
         return undefined;
-    return Object.freeze({ kind: "autonomous-agent", id: cls.componentId, cls, tools, guardrails, taskTypes });
+    return Object.freeze({ kind: "autonomous-agent", id: cls.componentId, cls, tools, guardrails, mcpServers, resultGuardrails, taskTypes });
+}
+/** An agent's MCP servers and result guardrails by name, with what is wrong with them in the sidecar's words. */
+function collectMcp(cls, tools, fail) {
+    const mcpServers = new Map();
+    for (const [property, server] of Object.entries(cls.mcpServers ?? {})) {
+        if (typeof server !== "object" || server === null || typeof server.name !== "string") {
+            fail(`mcpServers.${property} is not an MCP server: declare it with mcpServer(name, options)`);
+            continue;
+        }
+        serverProblems(server).forEach(fail);
+        if (mcpServers.has(server.name))
+            fail(`MCP server '${server.name}' is listed twice`);
+        mcpServers.set(server.name, server);
+    }
+    for (const t of tools.values()) {
+        if (t.name.startsWith(TOOL_PREFIX))
+            fail(`tool '${t.name}' takes the prefix '${TOOL_PREFIX}', which names an MCP server's tools`);
+    }
+    const resultGuardrails = new Map();
+    for (const [property, g] of Object.entries(cls.resultGuardrails ?? {})) {
+        if (typeof g !== "object" || g === null || typeof g.name !== "string" || typeof g.check !== "function") {
+            fail(`resultGuardrails.${property} is not a result guardrail: declare it with resultGuardrail(name, check)`);
+            continue;
+        }
+        if (resultGuardrails.has(g.name))
+            fail(`result guardrail '${g.name}' is declared twice`);
+        resultGuardrails.set(g.name, g);
+    }
+    return { mcpServers, resultGuardrails };
 }
 /** 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) {