@alpacakit/channels 0.1.0-beta.37 → 0.2.0-beta.2

package/dist/schema.d.ts

@@ -1,14 +1,17 @@
 import type { EntryChannelBinding, EntryTreeDefinition, EntryTreeEndpoint, EntryTreeNode } from "./model.js";
-export declare class EntryTreeDefinitionError extends Error {
-    readonly issues: readonly string[];
-    constructor(issues: readonly string[]);
-}
+import type { EntryTreeSource } from "./registration.js";
+export { EntryTreeDefinitionError } from "./definition-error.js";
 export interface EntryTreeVisitor {
-    visitNode(node: EntryTreeNode, path: readonly string[]): void;
-    visitEndpoint(endpoint: EntryTreeEndpoint, node: EntryTreeNode, path: readonly string[]): void;
+    readonly visitNode: (node: EntryTreeNode, path: readonly string[], root: boolean) => void;
+    readonly visitEndpoint: (endpoint: EntryTreeEndpoint, node: EntryTreeNode, path: readonly string[], root: boolean) => void;
 }
-export declare function visitEntryTree(tree: EntryTreeDefinition, visitor: EntryTreeVisitor): void;
-export declare function validateEntryTreeStructure(tree: EntryTreeDefinition): readonly string[];
+export declare function isEntryTreeDefinition(source: EntryTreeSource): source is EntryTreeDefinition;
+export declare function visitEntryTreeSource(source: EntryTreeSource, visitor: EntryTreeVisitor): void;
+export declare function visitEntryTree(tree: EntryTreeDefinition, visitor: Omit<EntryTreeVisitor, "visitNode" | "visitEndpoint"> & {
+    readonly visitNode: (node: EntryTreeNode, path: readonly string[]) => void;
+    readonly visitEndpoint: (endpoint: EntryTreeEndpoint, node: EntryTreeNode, path: readonly string[]) => void;
+}): void;
+export declare function validateEntryTreeStructure(source: EntryTreeSource): readonly string[];
 export declare function findChannelBinding(endpoint: EntryTreeEndpoint, channel: EntryChannelBinding["channel"]): EntryChannelBinding | null;
 export declare function formatTreePath(path: readonly string[]): string;
 //# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,qBAAa,wBAAyB,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;gBAAzB,MAAM,EAAE,SAAS,MAAM,EAAE;CAI/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC9D,aAAa,CACX,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,IAAI,CAAC;CACT;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,gBAAgB,GACxB,IAAI,CAsBN;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,mBAAmB,GACxB,SAAS,MAAM,EAAE,CAyCnB;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GACtC,mBAAmB,GAAG,IAAI,CAI5B;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE9D"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,CAClB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,OAAO,KACV,IAAI,CAAC;IACV,QAAQ,CAAC,aAAa,EAAE,CACtB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,OAAO,KACV,IAAI,CAAC;CACX;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,GACtB,MAAM,IAAI,mBAAmB,CAE/B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,GACxB,IAAI,CA8BN;AAED,wBAAgB,cAAc,CAC5B,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,eAAe,CAAC,GAAG;IAC/D,QAAQ,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IAC3E,QAAQ,CAAC,aAAa,EAAE,CACtB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,SAAS,MAAM,EAAE,KACpB,IAAI,CAAC;CACX,GACA,IAAI,CAON;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,eAAe,GACtB,SAAS,MAAM,EAAE,CA4CnB;AAsED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,mBAAmB,CAAC,SAAS,CAAC,GACtC,mBAAmB,GAAG,IAAI,CAI5B;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAE9D"}

package/dist/schema.js

@@ -1,67 +1,130 @@
-export class EntryTreeDefinitionError extends Error {
-    issues;
-    constructor(issues) {
-        super(`Invalid entry tree definition:\n${issues.join("\n")}`);
-        this.issues = issues;
-        this.name = EntryTreeDefinitionError.name;
-    }
+export { EntryTreeDefinitionError } from "./definition-error.js";
+export function isEntryTreeDefinition(source) {
+    return Object.hasOwn(source, "root");
 }
-export function visitEntryTree(tree, visitor) {
-    const stack = [{ node: tree.root, path: [] }];
+export function visitEntryTreeSource(source, visitor) {
+    const tree = isEntryTreeDefinition(source);
+    const root = tree ? source.root : source;
+    const stack = [
+        {
+            node: root,
+            path: tree ? [] : [root.name],
+            root: true,
+        },
+    ];
     while (stack.length > 0) {
         const current = stack.pop();
-        if (!current) {
+        if (current === undefined) {
             continue;
         }
-        const path = [...current.path, current.node.name];
-        visitor.visitNode(current.node, path);
+        visitor.visitNode(current.node, current.path, current.root);
         for (const endpoint of current.node.endpoints) {
-            visitor.visitEndpoint(endpoint, current.node, path);
+            visitor.visitEndpoint(endpoint, current.node, current.path, current.root);
         }
         for (let index = current.node.children.length - 1; index >= 0; index -= 1) {
             const child = current.node.children[index];
-            if (child) {
-                stack.push({ node: child, path });
+            if (child !== undefined) {
+                stack.push({
+                    node: child,
+                    path: [...current.path, child.name],
+                    root: false,
+                });
             }
         }
     }
 }
-export function validateEntryTreeStructure(tree) {
+export function visitEntryTree(tree, visitor) {
+    visitEntryTreeSource(tree, {
+        visitNode: (node, path) => visitor.visitNode(node, [tree.root.name, ...path]),
+        visitEndpoint: (endpoint, node, path) => visitor.visitEndpoint(endpoint, node, [tree.root.name, ...path]),
+    });
+}
+export function validateEntryTreeStructure(source) {
+    const root = isEntryTreeDefinition(source) ? source.root : source;
     const issues = [];
-    visitEntryTree(tree, {
-        visitNode(node, path) {
-            const location = formatTreePath(path);
-            if (node.name.length === 0) {
-                issues.push(`${location}: node name must not be empty`);
-            }
-            const childNames = new Set();
-            for (const child of node.children) {
-                if (childNames.has(child.name)) {
-                    issues.push(`${location}: duplicate child name ${JSON.stringify(child.name)}`);
-                }
-                childNames.add(child.name);
-            }
-            const overrideChannels = new Set();
-            for (const override of node.segments) {
-                if (overrideChannels.has(override.channel)) {
-                    issues.push(`${location}: duplicate ${override.channel} segment override`);
-                }
-                overrideChannels.add(override.channel);
-            }
-        },
-        visitEndpoint(endpoint, _node, path) {
-            const location = `${formatTreePath(path)}#${endpoint.entry.name}`;
-            const channels = new Set();
-            for (const channelBinding of endpoint.channels) {
-                if (channels.has(channelBinding.channel)) {
-                    issues.push(`${location}: duplicate ${channelBinding.channel} channel binding`);
-                }
-                channels.add(channelBinding.channel);
+    const placements = new Map();
+    const active = new Set();
+    const stack = [
+        { kind: STRUCTURE_FRAME_KIND.enter, node: root, parent: null },
+    ];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame === undefined) {
+            continue;
+        }
+        if (frame.kind === STRUCTURE_FRAME_KIND.exit) {
+            active.delete(frame.node);
+            continue;
+        }
+        const placement = { node: frame.node, parent: frame.parent };
+        const firstPlacement = placements.get(frame.node);
+        if (firstPlacement !== undefined) {
+            const issue = active.has(frame.node)
+                ? "TreeNode cycle"
+                : "TreeNode is placed more than once";
+            issues.push(`${formatPlacement(placement)}: ${issue}; first placement is ${formatPlacement(firstPlacement)}`);
+            continue;
+        }
+        placements.set(frame.node, placement);
+        active.add(frame.node);
+        validateNode(placement, issues);
+        stack.push({ kind: STRUCTURE_FRAME_KIND.exit, node: frame.node });
+        for (let index = frame.node.children.length - 1; index >= 0; index -= 1) {
+            const child = frame.node.children[index];
+            if (child !== undefined) {
+                stack.push({
+                    kind: STRUCTURE_FRAME_KIND.enter,
+                    node: child,
+                    parent: placement,
+                });
             }
-        },
-    });
+        }
+    }
     return issues;
 }
+const STRUCTURE_FRAME_KIND = {
+    enter: "enter",
+    exit: "exit",
+};
+function validateNode(placement, issues) {
+    const { node } = placement;
+    const location = formatPlacement(placement);
+    if (node.name.length === 0) {
+        issues.push(`${location}: node name must not be empty`);
+    }
+    const childNames = new Set();
+    for (const child of node.children) {
+        if (childNames.has(child.name)) {
+            issues.push(`${location}: duplicate child name ${JSON.stringify(child.name)}; merge same-name nodes explicitly`);
+        }
+        childNames.add(child.name);
+    }
+    const overrideChannels = new Set();
+    for (const override of node.segments) {
+        if (overrideChannels.has(override.channel)) {
+            issues.push(`${location}: duplicate ${override.channel} segment override`);
+        }
+        overrideChannels.add(override.channel);
+    }
+    for (const endpoint of node.endpoints) {
+        const channels = new Set();
+        for (const channelBinding of endpoint.channels) {
+            if (channels.has(channelBinding.channel)) {
+                issues.push(`${location}#${endpoint.entry.name}: duplicate ${channelBinding.channel} channel binding`);
+            }
+            channels.add(channelBinding.channel);
+        }
+    }
+}
+function formatPlacement(placement) {
+    const path = [];
+    let current = placement;
+    while (current !== null) {
+        path.push(current.node.name);
+        current = current.parent;
+    }
+    return formatTreePath(path.reverse());
+}
 export function findChannelBinding(endpoint, channel) {
     return (endpoint.channels.find((candidate) => candidate.channel === channel) ?? null);
 }

package/dist/string-coercion.d.ts

@@ -0,0 +1,4 @@
+import type { JsonValue } from "@alpacakit/core";
+import type { ValueShape } from "./model.js";
+export declare function coerceStringValue(shape: ValueShape, rawValue: unknown): JsonValue;
+//# sourceMappingURL=string-coercion.d.ts.map

package/dist/string-coercion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-coercion.d.ts","sourceRoot":"","sources":["../src/string-coercion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,OAAO,GAChB,SAAS,CAMX"}

package/dist/string-coercion.js

@@ -0,0 +1,24 @@
+import { VALUE_SHAPE_KIND } from "./values.js";
+export function coerceStringValue(shape, rawValue) {
+    if (shape.kind === VALUE_SHAPE_KIND.array) {
+        const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+        return values.map((value) => coerceStringScalarValue(shape.element, value));
+    }
+    return coerceStringScalarValue(shape, rawValue);
+}
+function coerceStringScalarValue(shape, value) {
+    if (shape.kind === VALUE_SHAPE_KIND.boolean) {
+        if (value === "true") {
+            return true;
+        }
+        if (value === "false") {
+            return false;
+        }
+    }
+    if (shape.kind === VALUE_SHAPE_KIND.positiveInteger &&
+        typeof value === "string" &&
+        /^[+-]?\d+$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}

package/dist/tree-internal.d.ts

@@ -3,12 +3,14 @@ import type { Channel } from "./values.js";
 export declare const PAYLOAD_KIND: {
     readonly cliBinding: "cli_binding";
     readonly cliSegment: "cli_segment";
+    readonly httpBinding: "http_binding";
+    readonly httpSegment: "http_segment";
     readonly mcpBinding: "mcp_binding";
 };
 type PayloadKind = (typeof PAYLOAD_KIND)[keyof typeof PAYLOAD_KIND];
 export declare function registerChannelPayload(kind: PayloadKind, payload: object): void;
 export declare function isChannelPayload(kind: PayloadKind, value: unknown): boolean;
-export declare function createChannelSegmentOverride(channel: Channel, segment: unknown): ChannelSegmentOverride;
-export declare function createEntryChannelBinding<const ChannelName extends Channel, const ParameterName extends string>(channel: ChannelName, binding: unknown): EntryChannelBinding<ChannelName, ParameterName>;
+export declare function createChannelSegmentOverride<const ChannelName extends Channel, Segment>(channel: ChannelName, segment: Segment): ChannelSegmentOverride<ChannelName, Segment>;
+export declare function createEntryChannelBinding<const ChannelName extends Channel, Binding>(channel: ChannelName, binding: Binding): EntryChannelBinding<ChannelName, Binding>;
 export {};
 //# sourceMappingURL=tree-internal.d.ts.map

package/dist/tree-internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree-internal.d.ts","sourceRoot":"","sources":["../src/tree-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,KAAK,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAIpE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAM3E;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GACf,sBAAsB,CAExB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,CAAC,WAAW,SAAS,OAAO,EACjC,KAAK,CAAC,aAAa,SAAS,MAAM,EAElC,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,OAAO,GACf,mBAAmB,CAAC,WAAW,EAAE,aAAa,CAAC,CAKjD"}
+{"version":3,"file":"tree-internal.d.ts","sourceRoot":"","sources":["../src/tree-internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,KAAK,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAIpE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAM3E;AAED,wBAAgB,4BAA4B,CAC1C,KAAK,CAAC,WAAW,SAAS,OAAO,EACjC,OAAO,EAEP,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,OAAO,GACf,sBAAsB,CAAC,WAAW,EAAE,OAAO,CAAC,CAK9C;AAED,wBAAgB,yBAAyB,CACvC,KAAK,CAAC,WAAW,SAAS,OAAO,EACjC,OAAO,EAEP,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,OAAO,GACf,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,CAK3C"}

package/dist/tree-internal.js

@@ -1,6 +1,9 @@
+import { ownedRecord } from "./owned.js";
 export const PAYLOAD_KIND = {
     cliBinding: "cli_binding",
     cliSegment: "cli_segment",
+    httpBinding: "http_binding",
+    httpSegment: "http_segment",
     mcpBinding: "mcp_binding",
 };
 const REGISTERED_PAYLOADS = new WeakMap();
@@ -13,8 +16,8 @@ export function isChannelPayload(kind, value) {
         REGISTERED_PAYLOADS.get(value) === kind);
 }
 export function createChannelSegmentOverride(channel, segment) {
-    return { channel, segment };
+    return ownedRecord({ channel, segment });
 }
 export function createEntryChannelBinding(channel, binding) {
-    return { channel, binding };
+    return ownedRecord({ channel, binding });
 }

package/dist/values.d.ts

@@ -1,5 +1,6 @@
 export declare const CHANNEL: {
     readonly cli: "cli";
+    readonly http: "http";
     readonly mcp: "mcp";
 };
 export type Channel = (typeof CHANNEL)[keyof typeof CHANNEL];
@@ -15,12 +16,6 @@ export declare const VALUE_SHAPE_KIND: {
     readonly stringEnum: "string_enum";
     readonly array: "array";
 };
-export declare const ENTRY_DECODE_RESULT_KIND: {
-    readonly resolved: "resolved";
-    readonly invalidInput: "invalid_input";
-    readonly invalidParameter: "invalid_parameter";
-    readonly internalError: "internal_error";
-};
 export declare const ENTRY_INPUT_TARGET_KIND: {
     readonly entry: "entry";
     readonly parameter: "parameter";

package/dist/values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;;CAK3B,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX,eAAO,MAAM,6BAA6B;;;CAGhC,CAAC"}
+{"version":3,"file":"values.d.ts","sourceRoot":"","sources":["../src/values.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO;;;;CAIV,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,0BAA0B;;;;CAI7B,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC;AAEX,eAAO,MAAM,6BAA6B;;;CAGhC,CAAC"}

package/dist/values.js

@@ -1,5 +1,6 @@
 export const CHANNEL = {
     cli: "cli",
+    http: "http",
     mcp: "mcp",
 };
 export const PARAMETER_REQUIREMENT_KIND = {
@@ -14,12 +15,6 @@ export const VALUE_SHAPE_KIND = {
     stringEnum: "string_enum",
     array: "array",
 };
-export const ENTRY_DECODE_RESULT_KIND = {
-    resolved: "resolved",
-    invalidInput: "invalid_input",
-    invalidParameter: "invalid_parameter",
-    internalError: "internal_error",
-};
 export const ENTRY_INPUT_TARGET_KIND = {
     entry: "entry",
     parameter: "parameter",

package/examples/README.md

@@ -0,0 +1,28 @@
+# External-adapter examples
+
+[`greeting.ts`](./greeting.ts) is the canonical copy-ready Hono, MCP SDK, and
+Commander example. The packed-distribution verifier copies this exact shipped
+file, type-checks it, and invokes all three host paths so the documentation and
+executable fixture cannot drift apart.
+
+## Book search
+
+[`book-search.ts`](./book-search.ts) defines one Entry, one shared handler, one
+Endpoint, and one Tree. `collectCliCommands`, `collectHttpRoutes`, and
+`collectMcpTools` expose registration views for an application-owned parser,
+router, or SDK.
+
+The example deliberately does not parse argv, start a server, open an MCP
+transport, choose response envelopes, or manage process exit. Those jobs belong
+to the host. It does show the two valid input paths:
+
+- CLI and HTTP convert their external string forms with `parseOptions` and
+  `parseQuery`.
+- An MCP SDK can apply `input.schema` and then call `input.project` exactly
+  once. A host without SDK validation can call `input.parse` instead.
+
+All three views retain the exact `searchBooks` function reference and require
+the host-created `BookSearchContext` at invocation time.
+
+Host adapters deliberately live in the consumer: channels never starts a
+server, connects a transport, parses `argv`, or chooses a response envelope.

package/examples/book-search.ts

@@ -0,0 +1,151 @@
+import {
+  codecs,
+  createOutputContract,
+  defineEntry,
+  defineEntryEndpoint,
+  defineEntryNode,
+  defineEntryTree,
+  defineParameter,
+  optional,
+  required,
+  verifyEntryOutput,
+} from "@alpacakit/channels";
+import {
+  bindCliEntry,
+  CLI_ARG_KIND,
+  collectCliCommands,
+} from "@alpacakit/channels/cli";
+import { bindHttpEntry, collectHttpRoutes } from "@alpacakit/channels/http";
+import { bindMcpEntry, collectMcpTools } from "@alpacakit/channels/mcp";
+import { z } from "zod";
+
+const BookSearchDataSchema = z
+  .object({
+    books: z.array(
+      z.object({ id: z.string(), title: z.string(), author: z.string() }),
+    ),
+  })
+  .readonly();
+
+export type BookSearchData = z.output<typeof BookSearchDataSchema>;
+export type Book = BookSearchData["books"][number];
+
+export const BookSearchEntry = defineEntry({
+  name: "book-search",
+  parameters: [
+    defineParameter({
+      name: "query",
+      codec: codecs.string(),
+      requirement: required(),
+      description: "Text to find in a title or author",
+    }),
+    defineParameter({
+      name: "limit",
+      codec: codecs.positiveInteger({ max: 50 }),
+      requirement: optional({ default: 10 }),
+      description: "Maximum number of books to return",
+    }),
+  ],
+  project: ({ values }) => ({ query: values.query, limit: values.limit }),
+  output: createOutputContract(BookSearchDataSchema),
+});
+
+export type BookSearchInput = ReturnType<typeof BookSearchEntry.project>;
+export type BookSearchContext = {
+  readonly canSearch: boolean;
+  readonly findBooks: (query: string) => Promise<readonly Book[]>;
+};
+
+export type BookSearchOutcome =
+  | { readonly kind: "found"; readonly data: BookSearchData }
+  | { readonly kind: "forbidden" };
+
+/** The shared business handler; channel collectors retain this exact reference. */
+export async function searchBooks(
+  input: BookSearchInput,
+  context: BookSearchContext,
+): Promise<BookSearchOutcome> {
+  if (!context.canSearch) {
+    return { kind: "forbidden" };
+  }
+  const books = await context.findBooks(input.query);
+  return {
+    kind: "found",
+    data: verifyEntryOutput(BookSearchEntry, {
+      books: books.slice(0, input.limit),
+    }),
+  };
+}
+
+export const BookSearchEndpoint = defineEntryEndpoint(BookSearchEntry, {
+  handler: searchBooks,
+  channels: [
+    bindCliEntry({
+      parameters: [
+        { kind: CLI_ARG_KIND.positional, parameterName: "query" },
+        { kind: CLI_ARG_KIND.option, parameterName: "limit" },
+      ],
+    }),
+    bindMcpEntry({ name: "books_search" }),
+    bindHttpEntry({ method: "GET" }),
+  ],
+});
+
+export const BookSearchTree = defineEntryTree(
+  defineEntryNode({
+    name: "books",
+    description: "Book catalog",
+    children: [
+      defineEntryNode({
+        name: "search",
+        description: "Search books",
+        endpoints: [BookSearchEndpoint],
+      }),
+    ],
+  }),
+);
+
+export const bookSearchCliCommands = collectCliCommands(BookSearchTree);
+export const bookSearchHttpRoutes = collectHttpRoutes(BookSearchTree);
+export const bookSearchMcpTools = collectMcpTools(BookSearchTree);
+
+/**
+ * A small host-owned invocation demonstration. Real applications register the
+ * same views with their CLI parser, HTTP router, and MCP SDK.
+ */
+export async function runBookSearchDemo(): Promise<{
+  readonly cli: BookSearchOutcome;
+  readonly http: BookSearchOutcome;
+  readonly mcp: BookSearchOutcome;
+}> {
+  const context: BookSearchContext = {
+    canSearch: true,
+    findBooks: async () => [
+      {
+        id: "1",
+        title: "The Left Hand of Darkness",
+        author: "Ursula K. Le Guin",
+      },
+      { id: "2", title: "Kindred", author: "Octavia E. Butler" },
+    ],
+  };
+  const tasks: Promise<BookSearchOutcome>[] = [];
+  bookSearchCliCommands.root.children[0]?.commands.forEach((command) => {
+    const input = command.input.parseOptions({ query: "kind", limit: "1" });
+    tasks.push(Promise.resolve(command.handler(input, context)));
+  });
+  bookSearchHttpRoutes.forEach((route) => {
+    const input = route.input.parseQuery({ query: "kind", limit: "1" });
+    tasks.push(Promise.resolve(route.handler(input, context)));
+  });
+  bookSearchMcpTools.forEach((tool) => {
+    const values = tool.input.schema.parse({ query: "kind", limit: 1 });
+    const input = tool.input.project(values);
+    tasks.push(Promise.resolve(tool.handler(input, context)));
+  });
+  const [cli, http, mcp] = await Promise.all(tasks);
+  if (cli === undefined || http === undefined || mcp === undefined) {
+    throw new Error("Book search adapters were not collected");
+  }
+  return { cli, http, mcp };
+}