@acid-cat/core-ts 0.4.0 → 0.5.0

package/README.md

@@ -27,18 +27,20 @@ export const aircon = defineApp<{ unit: Unit }>({
       audience: ["cli", "mcp"],
       input: z.object({ on: z.boolean() }),
       failures: { Offline },
-      run: async ({ on }, { context, signal }) => ((await context.unit.setPower(on, signal)) ? ok(null) : fail("Offline")),
+      run: async ({ on }, { context, signal }) => ((await context.unit.setPower(on, signal)) ? ok(null) : fail({ _tag: "Offline" })),
     }),
   ],
 });
 ```
 
-- `run` gets the input, an `AbortSignal` and the context. It returns `ok(value)` or `fail(tag, data)`. If it throws, the call fails as `internal`.
+- `run` gets the input, an `AbortSignal` and the context. It returns `ok(value)` or `fail(failure)`, for example `fail({ _tag: "Offline", since })`. The types check that the value agrees with the output schema, that the failure has a tag of `failures`, and that it has the members of the schema of that tag. If `run` throws, the call fails as `internal`.
+- With an input schema, `run` gets the output of the schema. With none, it gets an empty object.
 - A failure schema describes the whole failure object, with its `_tag`.
 - `availability` is an optional function that returns an observable availability. A session reads it with `getSnapshot` when a call comes in. It subscribes to it only while `onChange` or the handle has listeners.
 - `state` is an optional `{ schema, source }`: the schema of the [state](../../spec/invocation.md#state), and a function that returns an observable. The handle gives it as `snapshot`.
 - `capabilitiesFor<Context>()` sets the context type one time. The other types come from the schemas.
 - `defineCapability` and `capabilitiesFor` keep the literal type of `id`, so that an application can type its ids. `run`, `availability` and `state` all get the same `Context`.
+- An application lists only capabilities that `defineCapability` or `capabilitiesFor` made. Each one has `decode`, which validates an input that is not trusted with the input schema and then gives the call of `run`. A session calls it, because there the type of the input is not known.
 
 ## Write the catalog
 
@@ -63,28 +65,29 @@ Standard Schema does not convert to JSON Schema. Give the converter of your sche
 
 When the signal of a request aborts, `mcpHandler` and `httpHandler` cancel the call of the request.
 
-### Typed handles
+### Typed calls and handles
 
-`getHandle(session.handles, capability)` gives the handle of a capability with the types of its schemas. For a capability outside the view, the handle is always unavailable, and each call rejects as `unknown-capability`.
+`createSession` gives a `Session<Context>`. It calls a capability with the types of the capability in two ways. Both take the capability object, so the types come from its schemas:
 
-```ts
-import { createSession, getHandle } from "@acid-cat/core-ts";
+- `session.call(capability, input)` takes an input that is not trusted, for example the arguments of a request. The input schema of the capability checks it. The result has the types of the capability. An input that does not agree rejects as `invalid-input`.
+- `session.handle(capability)` gives the handle of the capability (spec/bindings/typescript.md#handles): its availability, its `snapshot` of the state, and `execute` for an input that the types already check.
 
-const session = createSession(aircon, { target: "app", context: { unit }, toJsonSchema });
-const power = getHandle(session.handles, powerSet); // HandleOf<typeof powerSet>
-const result = await power.execute({ on: true }); // Result<null, { _tag: "Offline"; since?: string }>
-```
+Both call the capability through the session: availability, cancellation, and the checks of the output and of the failures. The session must serve that capability object. For any other capability, also one with the same id, a call rejects as `unknown-capability`, and the handle is always unavailable.
 
-### Context for each request
+`session.handles` is the map of the handles by id, for bindings. A handle of the map has the input type `never`: call it with `invokeExternal`, which validates the input. A function that gets a session declares its context: `(session: Session<{ unit: Unit }>) => …`.
 
-`mcpHandler` and `httpHandler` take `context` or `createContext`. With `context`, all requests share one context. With `createContext(request)`, the handler makes a new context for each request that passes the screening. Use it when a request must not use objects that an earlier request made, for example on Cloudflare Workers, or when a stateful service must not be shared between callers. When the context has `Symbol.asyncDispose` or `Symbol.dispose`, the handler calls it after the response:
+A session is async-disposable. `await using` closes it at the end of the block, as `dispose()` does:
 
 ```ts
-const handler = httpHandler(aircon, {
-  allowedOrigins: [],
-  toJsonSchema,
-  createContext: () => ({ unit: connectUnit(env), [Symbol.asyncDispose]: () => disconnectUnit() }),
-});
+import { createSession } from "@acid-cat/core-ts";
+
+await using session = createSession(aircon, { target: "app", context: { unit }, toJsonSchema });
+const result = await session.call(powerSet, request.body); // Result<null, { readonly _tag: "Offline"; since?: string }>
+if (!result.ok) console.log(result.error._tag); // "Offline"
+
+const power = session.handle(powerSet);
+power.availability.subscribe(render);
+await power.execute({ on: true });
 ```
 
 ### Context for each request
@@ -121,7 +124,7 @@ cliMain(aircon, { name: "aircon", version: "0.1.0", context: { unit }, toJsonSch
 
 ## Examples and tests
 
-- [`examples/aircon.ts`](examples/aircon.ts) is the air conditioner of [`examples/aircon.pkl`](../../examples/aircon.pkl), with a simulated unit. Its catalog agrees with the Pkl catalog.
-- [`examples/aircon-cli.ts`](examples/aircon-cli.ts) is its command line: `node examples/aircon-cli.ts aircon power set --on`.
-- [`examples/apis`](../../examples/apis/README.md) builds GraphQL, Cap'n Web and Elysia APIs on it, each beside the HTTP binding.
-- `moon run core-ts:test` tests sessions, handles and all bindings with a test application, and runs `acid-cat conform` against all bindings.
+- [`examples/aircon/core-ts`](../../examples/aircon/README.md) is an air conditioner written with this package, with its command line. [`examples/aircon/apis`](../../examples/aircon/README.md#apis) builds GraphQL, Cap'n Web and Elysia APIs on it, each beside the HTTP binding.
+- `moon run core-ts:test` tests sessions, handles and all bindings with a test application, and runs `acid-cat conform` against all bindings. Each test application is in `test/`:
+  - [`test/fixture.ts`](test/fixture.ts) has one capability for each behavior that `acid-cat conform` tests.
+  - [`test/kettle.ts`](test/kettle.ts) is an electric kettle, simulated in memory. Its tests examine the catalog that the core writes, named types, state, availability, typed handles and the command line.

package/dist/app.d.ts

@@ -7,52 +7,111 @@ export interface Observable<T> {
         unsubscribe(): void;
     };
 }
-/** The input that `run` receives: the output of the input schema, or an empty object. */
-export type InputOf<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : Record<string, never>;
-/** The value of a successful call: the output of the output schema, or `null`. */
-export type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : null;
-/** The failures, each with its `_tag`. */
-export type FailureOf<F> = {
-    [Tag in keyof F]: {
+/** The input of a capability that has no input schema: an empty object. */
+export type EmptyInput = Record<string, never>;
+/** The data of each failure, by tag: the output of its schema. */
+export type FailureData = {
+    readonly [tag: string]: object;
+};
+/** The failures of a capability, each with its `_tag`. */
+export type FailureOf<Failures> = {
+    [Tag in keyof Failures]: {
         readonly _tag: Tag;
-    } & (F[Tag] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<F[Tag]> : object);
-}[keyof F];
-export interface Capability<Context = unknown, Input extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, OutputSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, Failures extends {
-    readonly [tag: string]: StandardSchemaV1;
-} = {
-    readonly [tag: string]: StandardSchemaV1;
-}, StateSchema extends StandardSchemaV1 = StandardSchemaV1, Id extends string = string> {
+    } & Failures[Tag];
+}[keyof Failures];
+/** The failure schemas of a capability, by tag. The schema of a failure describes the object, without or with its `_tag`. */
+export type FailureSchemas<Failures> = {
+    readonly [Tag in keyof Failures]: StandardSchemaV1<unknown, Failures[Tag]>;
+};
+/** What `run` receives beside the input: the signal of the call, and the context. */
+export interface Call<Context> {
+    readonly signal: AbortSignal;
+    readonly context: Context;
+}
+/** The function of a capability. Its result has the types of the output schema and of the failure schemas. */
+export type Run<Context, Input, Value, Failures> = (input: Input, call: Call<Context>) => Promise<Result<NoInfer<Value>, NoInfer<FailureOf<Failures>>>> | Result<NoInfer<Value>, NoInfer<FailureOf<Failures>>>;
+/** The members of a capability that do not depend on its input. */
+export interface CapabilityParts<Context, Value, Failures, State, Id extends string> {
     readonly id: Id;
     readonly description: string;
     /** The targets that can use the capability. With no audience, no target can use it. */
     readonly audience: readonly string[];
     readonly readOnly?: boolean | undefined;
-    /**
-     * The input: an object schema, or a union of object schemas. The catalog writes a union with `"type": "object"`. With
-     * no input schema, the input is an empty object.
-     */
-    readonly input?: Input;
     /** The value of a successful call. With no output schema, the value is `null`. */
-    readonly output?: OutputSchema;
-    /** The failures, by tag. The schema of a failure describes the object, without or with its `_tag`. */
-    readonly failures?: Failures;
+    readonly output?: StandardSchemaV1<unknown, Value> | undefined;
+    /** The failures, by tag. */
+    readonly failures?: FailureSchemas<Failures> | undefined;
     /** A value that clients can observe (spec/invocation.md#state): its schema, and its source. */
     readonly state?: {
-        readonly schema: StateSchema;
-        readonly source: (context: Context) => Observable<StandardSchemaV1.InferOutput<StateSchema>>;
+        readonly schema: StandardSchemaV1<unknown, State>;
+        readonly source: (context: Context) => Observable<NoInfer<State>>;
     } | undefined;
     /** The availability of the capability. With none, the capability is always available. */
     readonly availability?: ((context: Context) => Observable<Availability>) | undefined;
-    readonly run: (input: InputOf<Input>, call: {
-        readonly signal: AbortSignal;
-        readonly context: Context;
-    }) => Promise<Result<Output<OutputSchema>, FailureOf<Failures>>> | Result<Output<OutputSchema>, FailureOf<Failures>>;
 }
-export type AnyCapability<Context = any> = Capability<Context, any, any, any, any>;
-/** Declare a capability. `Context` is the type of the services that `run` receives. The id keeps its literal type. */
-export declare const defineCapability: <Context = unknown, Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
-    readonly [tag: string]: StandardSchemaV1;
-} = {}, StateSchema extends StandardSchemaV1 = never, const Id extends string = string>(capability: Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>) => Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>;
+/**
+ * A capability with an input schema: an object schema, or a union of object schemas. The catalog writes a union with
+ * `"type": "object"`. `run` receives the output of the schema.
+ */
+export interface WithInput<Context, Input, Value, Failures> {
+    readonly input: StandardSchemaV1<unknown, Input>;
+    readonly run: Run<Context, Input, Value, Failures>;
+}
+/** A capability with no input schema. `run` receives an empty object. */
+export interface WithoutInput<Context, Value, Failures> {
+    readonly input?: undefined;
+    readonly run: Run<Context, EmptyInput, Value, Failures>;
+}
+/**
+ * A capability as an application declares it. `Context` is the type of the services that `run` receives. `Input`,
+ * `Value`, `Failures` and `State` are the outputs of its schemas.
+ */
+export type CapabilityDeclaration<Context, Input, Value, Failures, State, Id extends string> = CapabilityParts<Context, Value, Failures, State, Id> & (WithInput<Context, Input, Value, Failures> | WithoutInput<Context, Value, Failures>);
+/** The result of `decode`: the issues of an input that is not valid, or the call of `run` with the decoded input. */
+export type Decoded<Context> = {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+} | {
+    readonly start: (call: Call<Context>) => Promise<Result<unknown, unknown>> | Result<unknown, unknown>;
+};
+/** Decode an input that is not trusted with the input schema of a capability. */
+export type Decode<Context> = (input: unknown) => Promise<Decoded<Context>>;
+/**
+ * A capability that `defineCapability` or `capabilitiesFor` made: its declaration, and `decode`. A session calls
+ * `decode` for an input that is not trusted, because the type of the input is not known there.
+ */
+export type Capability<Context = unknown, Input = EmptyInput, Value = null, Failures = {}, State = never, Id extends string = string> = CapabilityDeclaration<Context, Input, Value, Failures, State, Id> & {
+    readonly decode: Decode<Context>;
+};
+/** Any capability whose services the context `Context` gives, whatever its schemas are. */
+export interface AnyCapability<Context = never> {
+    readonly id: string;
+    readonly description: string;
+    readonly audience: readonly string[];
+    readonly readOnly?: boolean | undefined;
+    readonly input?: StandardSchemaV1 | undefined;
+    readonly output?: StandardSchemaV1 | undefined;
+    readonly failures?: {
+        readonly [tag: string]: StandardSchemaV1;
+    } | undefined;
+    readonly state?: {
+        readonly schema: StandardSchemaV1;
+        readonly source: (context: Context) => Observable<unknown>;
+    } | undefined;
+    readonly availability?: ((context: Context) => Observable<Availability>) | undefined;
+    readonly decode: Decode<Context>;
+}
+/**
+ * Declare a capability. `Context` is the type of the services that `run` receives. The other types come from the
+ * schemas, and the id keeps its literal type. With an input schema, `run` receives the output of the schema. With
+ * none, it receives an empty object.
+ */
+export declare function defineCapability<Context = unknown, Input = EmptyInput, Value = null, Failures extends FailureData = {}, State = never, const Id extends string = string>(declaration: CapabilityParts<Context, Value, Failures, State, Id> & WithInput<Context, Input, Value, Failures>): Capability<Context, Input, Value, Failures, State, Id>;
+export declare function defineCapability<Context = unknown, Value = null, Failures extends FailureData = {}, State = never, const Id extends string = string>(declaration: CapabilityParts<Context, Value, Failures, State, Id> & WithoutInput<Context, Value, Failures>): Capability<Context, EmptyInput, Value, Failures, State, Id>;
+/** The function that `capabilitiesFor` gives: `defineCapability`, with one context type. */
+export interface CapabilityFactory<Context> {
+    <Input, Value = null, Failures extends FailureData = {}, State = never, const Id extends string = string>(declaration: CapabilityParts<Context, Value, Failures, State, Id> & WithInput<Context, Input, Value, Failures>): Capability<Context, Input, Value, Failures, State, Id>;
+    <Value = null, Failures extends FailureData = {}, State = never, const Id extends string = string>(declaration: CapabilityParts<Context, Value, Failures, State, Id> & WithoutInput<Context, Value, Failures>): Capability<Context, EmptyInput, Value, Failures, State, Id>;
+}
 /**
  * Declare capabilities for one context type. The other types come from the schemas:
  *
@@ -61,9 +120,7 @@ export declare const defineCapability: <Context = unknown, Input extends Standar
  * capability({ id: "aircon.power.set", input: z.object({ on: z.boolean() }), run: ({ on }, { context }) => … });
  * ```
  */
-export declare const capabilitiesFor: <Context>() => <Input extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Failures extends {
-    readonly [tag: string]: StandardSchemaV1;
-} = {}, StateSchema extends StandardSchemaV1 = never, const Id extends string = string>(capability: Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>) => Capability<Context, Input, OutputSchema, Failures, StateSchema, Id>;
+export declare const capabilitiesFor: <Context>() => CapabilityFactory<Context>;
 export interface Target {
     readonly bindings: readonly string[];
     readonly description?: string | undefined;
@@ -85,10 +142,10 @@ export type ToJsonSchema = (schema: StandardSchemaV1) => JsonObject;
  * The catalog of an application, as a JSON document. The catalog is written one time for each application and
  * `toJsonSchema`. Later calls with the same two give the same document.
  */
-export declare function catalogOf(app: App<any>, options: {
+export declare function catalogOf(app: App<never>, options: {
     readonly toJsonSchema: ToJsonSchema;
 }): CatalogDocument;
 /** The catalog of an application, as text in canonical form. */
-export declare const renderCatalog: (app: App<any>, options: {
+export declare const renderCatalog: (app: App<never>, options: {
     readonly toJsonSchema: ToJsonSchema;
 }) => string;

package/dist/app.js

@@ -1,12 +1,30 @@
 import { canonicalText } from "@acid-cat/catalog";
-import { objectInput } from "@acid-cat/spec-ts";
+import { isJsonObject, objectInput } from "@acid-cat/spec-ts";
 //#region src/app.ts
 /**
 * Capabilities and applications in plain TypeScript. An application writes its own catalog.
 * See spec/catalog.md.
 */
-/** Declare a capability. `Context` is the type of the services that `run` receives. The id keeps its literal type. */
-const defineCapability = (capability) => capability;
+function defineCapability(declaration) {
+	return {
+		...declaration,
+		decode: decoderOf(declaration)
+	};
+}
+/** The `decode` of a capability: validate the input with the input schema, then give the call of `run`. */
+function decoderOf(declaration) {
+	if (declaration.input === void 0) {
+		const { run } = declaration;
+		return () => Promise.resolve({ start: (call) => run({}, call) });
+	}
+	const { input: schema, run } = declaration;
+	return async (input) => {
+		const validated = await schema["~standard"].validate(input);
+		if (validated.issues !== void 0) return { issues: validated.issues };
+		const { value } = validated;
+		return { start: (call) => run(value, call) };
+	};
+}
 /**
 * Declare capabilities for one context type. The other types come from the schemas:
 *
@@ -15,7 +33,7 @@ const defineCapability = (capability) => capability;
 * capability({ id: "aircon.power.set", input: z.object({ on: z.boolean() }), run: ({ on }, { context }) => … });
 * ```
 */
-const capabilitiesFor = () => (capability) => capability;
+const capabilitiesFor = () => defineCapability;
 /** Declare an application. */
 const defineApp = (app) => app;
 const catalogs = /* @__PURE__ */ new WeakMap();
@@ -40,7 +58,8 @@ function write(app, toJsonSchema) {
 	const types = {};
 	const toJson = (schema, where) => {
 		const { $schema: _, $defs, ...json } = toJsonSchema(schema);
-		for (const [name, definition] of Object.entries($defs ?? {})) {
+		for (const [name, definition] of Object.entries(isJsonObject($defs) ? $defs : {})) {
+			if (!isJsonObject(definition)) throw new Error(`${where}: the schema ${name} is not an object. Give each named schema as an object.`);
 			const existing = types[name];
 			if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(definition)) throw new Error(`${where}: two different schemas have the name ${name}. Give each one its own name.`);
 			types[name] = definition;

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { createSession } from "./session.js";
-import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, cliFlags, cliUsage, commandPath, isCallFailure } from "@acid-cat/spec-ts";
+import { CLI_EXIT_CODES, REFERENCE, bundle, cliExitCode, cliFlags, cliUsage, commandPath, isCallFailure, isJsonObject } from "@acid-cat/spec-ts";
 //#region src/cli.ts
 /**
 * The CLI binding (spec/bindings/cli.md): a command line made from the catalog.
@@ -40,7 +40,7 @@ async function runCli(app, options, args, io) {
 	const taken = /* @__PURE__ */ new Set([
 		"call",
 		"list",
-		...commands.map(({ path }) => path[0])
+		...commands.flatMap(({ path }) => path.slice(0, 1))
 	]);
 	for (const command of added) {
 		if (taken.has(command.name)) throw new Error(`The command ${command.name} of the application has the same name as another command.`);
@@ -67,7 +67,7 @@ async function runCli(app, options, args, io) {
 		}
 		if (first === "list") {
 			io.stdout(JSON.stringify([...session.handles.values()].map((handle) => {
-				const input = session.view.capabilities[handle.id].input;
+				const input = viewCapability(session.view, handle.id).input;
 				return {
 					id: handle.id,
 					description: handle.description,
@@ -98,7 +98,7 @@ async function runCli(app, options, args, io) {
 		});
 		const match = commands.filter(({ path }) => path.every((word, index) => args[index] === word)).sort((a, b) => b.path.length - a.path.length)[0];
 		if (match === void 0) throw new UsageError(`There is no command ${args.filter((arg) => !arg.startsWith("-")).join(" ")}.`, CLI_EXIT_CODES["unknown-capability"]);
-		const capability = session.view.capabilities[match.id];
+		const capability = viewCapability(session.view, match.id);
 		const schema = bundle(capability.input ?? { type: "object" }, types);
 		const flagArgs = args.slice(match.path.length);
 		if (flagArgs.includes("--help") || flagArgs.includes("-h")) {
@@ -116,25 +116,26 @@ async function runCli(app, options, args, io) {
 }
 /** Make the input from the flags (spec/bindings/cli.md#commands). */
 function parseFlags(args, schema) {
-	const properties = schema.properties ?? {};
-	const definitions = schema.$defs ?? {};
+	const properties = objectOrEmpty(schema.properties);
+	const definitions = objectOrEmpty(schema.$defs);
 	const input = {};
-	for (let index = 0; index < args.length; index += 1) {
-		const arg = args[index];
+	const remaining = args.values();
+	for (const arg of remaining) {
 		if (!arg.startsWith("--")) throw new UsageError(`Unexpected argument ${arg}.`, CLI_EXIT_CODES["invalid-input"]);
-		const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
+		const [name = "", inline] = arg.slice(2).split(/=(.*)/s, 2);
 		const property = properties[name];
 		if (property === void 0) throw new UsageError(`Unknown flag --${name}.`, CLI_EXIT_CODES["invalid-input"]);
-		const type = resolve(property, definitions);
+		const type = resolve(objectOrEmpty(property), definitions);
 		if (type.type === "boolean") {
 			input[name] = inline === void 0 ? true : inline === "true";
 			continue;
 		}
-		const text = inline ?? args[index += 1];
+		const text = inline ?? remaining.next().value;
 		if (text === void 0) throw new UsageError(`The flag --${name} needs a value.`, CLI_EXIT_CODES["invalid-input"]);
 		input[name] = valueOf(name, text, type);
 	}
-	for (const name of schema.required ?? []) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
+	const required = Array.isArray(schema.required) ? schema.required.filter((name) => typeof name === "string") : [];
+	for (const name of required) if (!(name in input)) throw new UsageError(`The flag --${name} is required.`, CLI_EXIT_CODES["invalid-input"]);
 	return input;
 }
 function valueOf(name, text, type) {
@@ -156,7 +157,15 @@ function valueOf(name, text, type) {
 }
 function resolve(property, definitions) {
 	const name = typeof property.$ref === "string" ? REFERENCE.exec(property.$ref)?.[1] : void 0;
-	return name === void 0 ? property : definitions[name] ?? property;
+	return name === void 0 ? property : objectOrEmpty(definitions[name] ?? property);
+}
+/** A value as a JSON object, or an empty object when it is not one. */
+const objectOrEmpty = (value) => isJsonObject(value) ? value : {};
+/** The capability `id` of a view. The view has it, because the session serves it. */
+function viewCapability(view, id) {
+	const capability = view.capabilities[id];
+	if (capability === void 0) throw new Error(`The view of the session has no capability ${id}.`);
+	return capability;
 }
 function help(name, description, paths, added) {
 	return [

package/dist/context.js

@@ -12,9 +12,12 @@ async function withContext(option, request, use) {
 /** Call `Symbol.asyncDispose` or `Symbol.dispose` of a value, if it has one. */
 async function release(value) {
 	if (typeof value !== "object" || value === null) return;
-	const disposable = value;
-	if (typeof disposable[Symbol.asyncDispose] === "function") await disposable[Symbol.asyncDispose]();
-	else if (typeof disposable[Symbol.dispose] === "function") disposable[Symbol.dispose]();
+	const asyncDispose = Symbol.asyncDispose in value ? value[Symbol.asyncDispose] : void 0;
+	const dispose = Symbol.dispose in value ? value[Symbol.dispose] : void 0;
+	if (isFunction(asyncDispose)) await asyncDispose.call(value);
+	else if (isFunction(dispose)) dispose.call(value);
 }
+/** Tell if a value is a function. A function can take any arguments, and its result is not known. */
+const isFunction = (value) => typeof value === "function";
 //#endregion
 export { withContext };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
-export type { AnyCapability, App, Capability, Observable, Target, ToJsonSchema } from "./app.js";
-export { createSession, getHandle } from "./session.js";
+export type { AnyCapability, App, Call, Capability, CapabilityDeclaration, CapabilityFactory, EmptyInput, FailureOf, Observable, Target, ToJsonSchema } from "./app.js";
+export { createSession } from "./session.js";
 export type { Handle, HandleOf, Session, SessionOptions } from "./session.js";
 export { mcpHandler } from "./mcp.js";
 export type { McpOptions, McpSettings } from "./mcp.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 import { capabilitiesFor, catalogOf, defineApp, defineCapability, renderCatalog } from "./app.js";
-import { createSession, getHandle } from "./session.js";
+import { createSession } from "./session.js";
 import { mcpHandler } from "./mcp.js";
 import { httpHandler } from "./http.js";
 import { main, runCli } from "./cli.js";
 import { findHost, installWebMcp } from "./webmcp.js";
 import { AVAILABLE, CallFailureError, fail, ok, unavailable } from "@acid-cat/spec-ts";
-export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, getHandle, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };
+export { AVAILABLE, CallFailureError, capabilitiesFor, catalogOf, main as cliMain, createSession, defineApp, defineCapability, fail, findHost, httpHandler, installWebMcp, mcpHandler, ok, renderCatalog, runCli, unavailable };

package/dist/mcp.js

@@ -1,11 +1,27 @@
 import { createSession } from "./session.js";
 import { withContext } from "./context.js";
-import { MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, bundle, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
+import { MCP_PROTOCOL_VERSION, MCP_REJECTIONS, MCP_UNKNOWN_TOOL, bundle, isJsonObject, mcpToolResult, readBounded, screenRequest } from "@acid-cat/spec-ts";
 //#region src/mcp.ts
 /**
 * The MCP binding (spec/bindings/mcp.md): an MCP server through HTTP, revision 2026-07-28, with no state on the
 * server between requests.
 */
+/**
+* Read the members of a JSON-RPC request from a parsed body. A member that does not have its type is left out. An
+* `id` that is not a string or a number is `null`.
+*/
+function readRequest(body) {
+	if (!isJsonObject(body)) return {};
+	const { id, method, params } = body;
+	const meta = isJsonObject(params) ? params["_meta"] : void 0;
+	return {
+		..."id" in body ? { id: typeof id === "string" || typeof id === "number" ? id : null } : {},
+		method: typeof method === "string" ? method : void 0,
+		name: isJsonObject(params) && typeof params["name"] === "string" ? params["name"] : void 0,
+		arguments: isJsonObject(params) ? params["arguments"] : void 0,
+		protocolVersion: isJsonObject(meta) ? meta["io.modelcontextprotocol/protocolVersion"] : void 0
+	};
+}
 /** A web request handler for the MCP server. Each request has its own session, and with `createContext` its own context. */
 function mcpHandler(app, options) {
 	const maximumBytes = options.maximumBytes ?? 1048576;
@@ -21,7 +37,7 @@ function mcpHandler(app, options) {
 		if ("rejection" in body) return rejection(body.rejection);
 		let message;
 		try {
-			message = JSON.parse(body.text);
+			message = readRequest(JSON.parse(body.text));
 		} catch {
 			return rejection("not-utf8");
 		}
@@ -33,7 +49,7 @@ function mcpHandler(app, options) {
 			status: 200,
 			headers: { "Content-Type": "application/json" }
 		});
-		const metaVersion = message.params?._meta?.["io.modelcontextprotocol/protocolVersion"];
+		const metaVersion = message.protocolVersion;
 		if (metaVersion === void 0) return error(400, id, -32602, "Required request metadata is missing");
 		if (metaVersion !== version) return error(400, id, -32020, "MCP-Protocol-Version header does not match request metadata");
 		return withContext(options, request, async (context) => {
@@ -75,10 +91,10 @@ async function answer(session, message, options, signal) {
 		}, true);
 		case "tools/list": return complete({ tools: listTools(session) }, true);
 		case "tools/call": {
-			const name = message.params?.name ?? "";
+			const name = message.name ?? "";
 			const handle = session.handles.get(name);
 			if (handle === void 0 || !handle.availability.getSnapshot().available) return error(200, id, MCP_UNKNOWN_TOOL, `Tool '${name}' not found`);
-			const outcome = await session.invoke(name, message.params?.arguments ?? {}, { signal });
+			const outcome = await session.invoke(name, message.arguments ?? {}, { signal });
 			return complete(mcpToolResult(outcome, hasObjectOutput(session, name)));
 		}
 		default: return error(404, id, -32601, `Method not found: ${message.method}`);
@@ -88,6 +104,7 @@ function listTools(session) {
 	const types = session.view.$defs ?? {};
 	return [...session.handles.values()].filter((handle) => handle.availability.getSnapshot().available).map((handle) => {
 		const capability = session.view.capabilities[handle.id];
+		if (capability === void 0) throw new Error(`The view of the session has no capability ${handle.id}.`);
 		const output = capability.output === void 0 ? void 0 : bundle(capability.output, types);
 		return {
 			name: handle.id,

package/dist/session.d.ts

@@ -1,11 +1,11 @@
 import type { Availability, CatalogDocument, Outcome, Result } from "@acid-cat/spec-ts";
-import type { AnyCapability, App, Capability, FailureOf, InputOf, Observable, Output, ToJsonSchema } from "./app.js";
-import type { StandardSchemaV1 } from "./standard-schema.js";
+import type { App, Capability, FailureOf, Observable, ToJsonSchema } from "./app.js";
 /**
  * The handle of a capability (spec/bindings/typescript.md#handles). `Input`, `Value`, `Failure` and `State` are the
- * types of the schemas of the capability. `getHandle` gives a handle with these types.
+ * types of the schemas of the capability. `session.handle` gives a handle with these types. A handle of
+ * `session.handles` has the input type `never`: only `invokeExternal` can call it, because it decodes the input.
  */
-export interface Handle<Input = unknown, Value = unknown, Failure = unknown, State = unknown> {
+export interface Handle<Input = never, Value = unknown, Failure = unknown, State = unknown> {
     readonly id: string;
     readonly description: string;
     readonly audience: readonly string[];
@@ -21,22 +21,31 @@ export interface Handle<Input = unknown, Value = unknown, Failure = unknown, Sta
         readonly signal?: AbortSignal | undefined;
     }): Promise<Result<unknown, unknown>>;
 }
-/** The handle of a capability, with the types of its schemas. */
-export type HandleOf<C> = C extends Capability<any, infer Input, infer OutputSchema, infer Failures, infer StateSchema> ? Handle<InputOf<Input>, Output<OutputSchema>, FailureOf<Failures>, StandardSchemaV1.InferOutput<StateSchema>> : never;
-/**
- * The handle of a capability in `handles`, with the types of the capability. For a capability outside the view, the
- * handle is always unavailable, and each call rejects as `unknown-capability`.
- */
-export declare function getHandle<C extends AnyCapability>(handles: ReadonlyMap<string, Handle>, capability: C): HandleOf<C>;
-export interface Session {
+/** The handle of a capability, with the types of its schemas. `session.handle` gives it. */
+export type HandleOf<C> = C extends Capability<never, infer Input, infer Value, infer Failures, infer State, string> ? Handle<Input, Value, FailureOf<Failures>, State> : never;
+export interface Session<Context = unknown> {
     readonly target: string;
     /**
      * The view of the target. Bindings take names, descriptions and schemas from it. The session writes the view when it
      * is first read.
      */
     readonly view: CatalogDocument;
-    /** The handles of the capabilities in the view, by id. */
+    /** The handles of the capabilities in the view, by id. Bindings use them. */
     readonly handles: ReadonlyMap<string, Handle>;
+    /**
+     * The handle of a capability, with the types of the capability. Only the capability object that the session serves
+     * gets a handle that calls it. Any other capability, also one with the same id, gets a handle that is always
+     * unavailable, and each call rejects as `unknown-capability`. Each call of `handle` gives a new handle.
+     */
+    handle<Input, Value, Failures, State, Id extends string>(capability: Capability<Context, Input, Value, Failures, State, Id>): Handle<Input, Value, FailureOf<Failures>, State>;
+    /**
+     * A call of a capability with an input that is not trusted. The input schema of the capability checks the input, so
+     * the result has the types of the capability. A call failure rejects with a `CallFailureError`. An input that does not
+     * agree with the schema rejects as `invalid-input`.
+     */
+    call<Input, Value, Failures, State, Id extends string>(capability: Capability<Context, Input, Value, Failures, State, Id>, input: unknown, options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<Result<Value, FailureOf<Failures>>>;
     /** A call with an input that is not trusted. The outcome is in its JSON form. The promise never rejects. */
     invoke(id: string, input: unknown, options?: {
         readonly signal?: AbortSignal | undefined;
@@ -52,6 +61,8 @@ export interface Session {
     readonly signal: AbortSignal;
     /** Close the session: accept no new calls, cancel the calls in progress, and wait for them. */
     dispose(): Promise<void>;
+    /** Close the session, as `dispose` does, at the end of the block of `await using session = createSession(…)`. */
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export interface SessionOptions<Context> {
     readonly target: string;
@@ -62,4 +73,4 @@ export interface SessionOptions<Context> {
     readonly onDefect?: ((id: string, cause: unknown) => void) | undefined;
 }
 /** Open a session for a target. */
-export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session;
+export declare function createSession<Context>(app: App<Context>, options: SessionOptions<Context>): Session<Context>;

package/dist/session.js

@@ -4,13 +4,7 @@ import { AVAILABLE, CallFailureError, callFailure, isCallFailure, viewOf } from
 /**
 * Sessions and handles (spec/invocation.md, spec/bindings/typescript.md).
 */
-/**
-* The handle of a capability in `handles`, with the types of the capability. For a capability outside the view, the
-* handle is always unavailable, and each call rejects as `unknown-capability`.
-*/
-function getHandle(handles, capability) {
-	return handles.get(capability.id) ?? outsideView(capability);
-}
+/** The handle of a capability that the session does not serve. */
 function outsideView(capability) {
 	const failure = callFailure("unknown-capability", `There is no capability ${capability.id}.`);
 	const unavailable = {
@@ -51,33 +45,26 @@ function createSession(app, options) {
 			availability
 		});
 	}
-	/** Run a call. The result is a result or a call failure. */
-	async function call(id, input, trusted, signal) {
+	/**
+	* Run a call of a capability that the session serves: availability, then the decoded input, then the work, with
+	* cancellation. A defect is the call failure `internal`.
+	*/
+	async function perform(id, entry, prepare, signal) {
 		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
-		const entry = served.get(id);
-		if (entry === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
 		const availability = entry.availability.getSnapshot();
 		if (!availability.available) return callFailure("unavailable", availability.reason);
-		const { capability } = entry;
-		let decoded = input ?? {};
-		if (!trusted && capability.input !== void 0) {
-			const validated = await capability.input["~standard"].validate(input);
-			if (validated.issues !== void 0) {
-				const message = validated.issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
-				return callFailure("invalid-input", message);
-			}
-			decoded = validated.value;
-		}
+		const prepared = await prepare();
+		if ("issues" in prepared) return callFailure("invalid-input", issueMessage(prepared.issues));
 		const controller = new AbortController();
 		const abort = () => controller.abort();
 		lifetime.signal.addEventListener("abort", abort);
 		signal?.addEventListener("abort", abort);
 		const cancelled = new Promise((resolve) => controller.signal.addEventListener("abort", () => resolve(callFailure("cancelled", "The call was cancelled."))));
 		if (lifetime.signal.aborted || signal?.aborted) controller.abort();
-		const work = Promise.resolve().then(() => capability.run(decoded, {
+		const work = Promise.resolve().then(() => prepared.start({
 			signal: controller.signal,
 			context: options.context
-		})).then((result) => checkResult(capability, result)).catch((cause) => {
+		})).catch((cause) => {
 			onDefect(id, cause);
 			return callFailure("internal", "The capability failed.");
 		});
@@ -91,13 +78,62 @@ function createSession(app, options) {
 			signal?.removeEventListener("abort", abort);
 		}
 	}
+	/** A call with an input that is not trusted. The outcome is a result or a call failure. */
+	async function invoke(id, input, signal) {
+		if (lifetime.signal.aborted || signal?.aborted) return callFailure("cancelled", "The call was cancelled.");
+		const entry = served.get(id);
+		if (entry === void 0) return callFailure("unknown-capability", `There is no capability ${id}.`);
+		const { capability } = entry;
+		return perform(id, entry, async () => {
+			const decoded = await capability.decode(input);
+			if ("issues" in decoded) return decoded;
+			return { start: async (call) => checkResult(capability, await decoded.start(call)) };
+		}, signal);
+	}
+	/** Reject a call failure, as a handle does. */
+	const settle = async (outcome) => {
+		const settled = await outcome;
+		if (isCallFailure(settled)) throw new CallFailureError(settled);
+		return settled;
+	};
+	/** The typed handle of a capability that the session serves, or the handle outside the view. */
+	function handle(capability) {
+		const entry = served.get(capability.id);
+		if (entry === void 0 || entry.capability !== capability) return outsideView(capability);
+		const state = capability.state?.source(options.context);
+		const run = (input, call) => capability.input === void 0 ? capability.run({}, call) : capability.run(input, call);
+		return {
+			id: capability.id,
+			description: capability.description,
+			audience: [options.target],
+			availability: entry.availability,
+			...state === void 0 ? {} : { snapshot: detached(state) },
+			execute: async (input, callOptions) => {
+				const outcome = await perform(capability.id, entry, () => Promise.resolve({ start: async (call) => checkTyped(capability, await run(input, call)) }), callOptions?.signal);
+				if (isCallFailure(outcome)) throw new CallFailureError(outcome);
+				return outcome;
+			},
+			invokeExternal: (input, callOptions) => settle(invoke(capability.id, input, callOptions?.signal))
+		};
+	}
+	/** A typed call with an input that is not trusted: the input schema of the capability decodes it. */
+	async function call(capability, input, signal) {
+		const entry = served.get(capability.id);
+		if (entry === void 0 || entry.capability !== capability) throw new CallFailureError(callFailure("unknown-capability", `There is no capability ${capability.id}.`));
+		const prepare = async () => {
+			if (capability.input === void 0) return { start: async (each) => checkTyped(capability, await capability.run({}, each)) };
+			const validated = await capability.input["~standard"].validate(input);
+			if (validated.issues !== void 0) return { issues: validated.issues };
+			const { value } = validated;
+			return { start: async (each) => checkTyped(capability, await capability.run(value, each)) };
+		};
+		const outcome = await perform(capability.id, entry, prepare, signal);
+		if (isCallFailure(outcome)) throw new CallFailureError(outcome);
+		return outcome;
+	}
 	const handles = /* @__PURE__ */ new Map();
 	for (const [id, { capability, availability }] of served) {
-		const reject = async (outcome) => {
-			const settled = await outcome;
-			if (isCallFailure(settled)) throw new CallFailureError(settled);
-			return settled;
-		};
+		const invokeExternal = (input, callOptions) => settle(invoke(id, input, callOptions?.signal));
 		const state = capability.state?.source(options.context);
 		handles.set(id, {
 			id,
@@ -105,8 +141,8 @@ function createSession(app, options) {
 			audience: [options.target],
 			availability,
 			...state === void 0 ? {} : { snapshot: detached(state) },
-			execute: (input, callOptions) => reject(call(id, input, true, callOptions?.signal)),
-			invokeExternal: (input, callOptions) => reject(call(id, input, false, callOptions?.signal))
+			execute: invokeExternal,
+			invokeExternal
 		});
 	}
 	const unsubscribeAll = () => {
@@ -114,14 +150,22 @@ function createSession(app, options) {
 		subscriptions = [];
 	};
 	let view;
+	async function dispose() {
+		lifetime.abort();
+		listeners.clear();
+		unsubscribeAll();
+		await Promise.allSettled(running);
+	}
 	return {
 		target: options.target,
 		get view() {
 			return view ??= viewOf(catalogOf(app, { toJsonSchema: options.toJsonSchema }), options.target);
 		},
 		handles,
+		handle,
+		call: (capability, input, callOptions) => call(capability, input, callOptions?.signal),
 		signal: lifetime.signal,
-		invoke: (id, input, callOptions) => call(id, input, false, callOptions?.signal),
+		invoke: (id, input, callOptions) => invoke(id, input, callOptions?.signal),
 		onChange(listener) {
 			if (lifetime.signal.aborted) return { unsubscribe() {} };
 			if (listeners.size === 0) {
@@ -133,14 +177,14 @@ function createSession(app, options) {
 				if (listeners.delete(listener) && listeners.size === 0) unsubscribeAll();
 			} };
 		},
-		async dispose() {
-			lifetime.abort();
-			listeners.clear();
-			unsubscribeAll();
-			await Promise.allSettled([...running]);
-		}
+		dispose,
+		[Symbol.asyncDispose]: dispose
 	};
 }
+/** The message of the call failure `invalid-input`: each issue with its path. */
+function issueMessage(issues) {
+	return issues.map((issue) => `${(issue.path ?? []).map((key) => typeof key === "object" ? String(key.key) : String(key)).join(".") || "input"}: ${issue.message}`).join("; ");
+}
 /** An observable whose values are copies, so that a client cannot change the data of the provider. */
 function detached(source) {
 	return {
@@ -162,18 +206,50 @@ async function checkResult(capability, result) {
 			value: checked.value
 		};
 	}
-	const tag = result.error._tag;
-	const schema = tag === void 0 ? void 0 : capability.failures?.[tag];
-	if (schema === void 0) throw new Error(`The failure ${String(tag)} is not in failures.`);
-	const checked = await schema["~standard"].validate(result.error);
+	const { error } = result;
+	const tag = typeof error === "object" && error !== null && "_tag" in error ? error._tag : void 0;
+	const schema = typeof tag === "string" ? capability.failures?.[tag] : void 0;
+	if (typeof tag !== "string" || schema === void 0) throw new Error(`The failure ${String(tag)} is not in failures.`);
+	const checked = await schema["~standard"].validate(error);
 	if (checked.issues !== void 0) throw new Error(`The failure ${tag} does not agree with its schema: ${checked.issues[0]?.message}`);
 	return {
 		ok: false,
 		error: {
 			_tag: tag,
-			...checked.value
+			...typeof checked.value === "object" && checked.value !== null ? checked.value : {}
 		}
 	};
 }
+/**
+* Check a result of a typed handle, as `checkResult` does. The values come from the output schema and from the failure
+* schema, so they have the types of the capability.
+*/
+async function checkTyped(capability, result) {
+	if (result.ok) {
+		if (capability.output === void 0) return result;
+		const checked = await capability.output["~standard"].validate(result.value);
+		if (checked.issues !== void 0) throw new Error(`The output does not agree with its schema: ${checked.issues[0]?.message}`);
+		return {
+			ok: true,
+			value: checked.value
+		};
+	}
+	if (capability.failures === void 0) throw new Error(`The failure ${String(result.error._tag)} is not in failures.`);
+	return {
+		ok: false,
+		error: await checkFailure(result.error, result.error._tag, capability.failures)
+	};
+}
+/** Check one failure against the schema of its tag. The result has the type of the failure with that tag. */
+async function checkFailure(failure, tag, schemas) {
+	const schema = schemas[tag];
+	if (schema === void 0) throw new Error(`The failure ${String(tag)} is not in failures.`);
+	const checked = await schema["~standard"].validate(failure);
+	if (checked.issues !== void 0) throw new Error(`The failure ${String(tag)} does not agree with its schema: ${checked.issues[0]?.message}`);
+	return {
+		_tag: tag,
+		...checked.value
+	};
+}
 //#endregion
-export { createSession, getHandle };
+export { createSession };

package/dist/webmcp.js

@@ -6,12 +6,21 @@ import { CallFailureError, bundle, isCallFailure } from "@acid-cat/spec-ts";
 /** The WebMCP host of the page, if there is one (spec/bindings/webmcp.md#host). */
 function findHost() {
 	const scope = globalThis;
-	for (const candidate of [scope.document?.modelContext, scope.navigator?.modelContext]) if (typeof candidate?.registerTool === "function") return candidate;
+	const holders = ["document" in scope ? scope.document : void 0, "navigator" in scope ? scope.navigator : void 0];
+	for (const holder of holders) {
+		const candidate = typeof holder === "object" && holder !== null && "modelContext" in holder ? holder.modelContext : void 0;
+		if (isModelContext(candidate)) return candidate;
+	}
+}
+/** Tell if a value has a `registerTool` function. The result of `registerTool` is not known, as `ModelContext` says. */
+function isModelContext(value) {
+	return typeof value === "object" && value !== null && "registerTool" in value && typeof value.registerTool === "function";
 }
 /** Register the capabilities of a session as tools. If there is no host, do nothing and return `undefined`. */
 function installWebMcp(session, options = {}) {
-	const host = options.host ?? findHost();
-	if (host === void 0) return void 0;
+	const found = options.host ?? findHost();
+	if (found === void 0) return void 0;
+	const host = found;
 	let status = {
 		phase: "loading",
 		message: null
@@ -29,6 +38,7 @@ function installWebMcp(session, options = {}) {
 	let dirty = false;
 	const toolFor = (id) => {
 		const capability = session.view.capabilities[id];
+		if (capability === void 0) throw new Error(`The view of the session has no capability ${id}.`);
 		return {
 			name: id,
 			description: capability.description,
@@ -118,7 +128,7 @@ function installWebMcp(session, options = {}) {
 			subscription.unsubscribe();
 			lifetime.abort();
 			registered.clear();
-			await Promise.allSettled([...calls]);
+			await Promise.allSettled(calls);
 			setStatus({
 				phase: "disposed",
 				message: null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acid-cat/core-ts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Serve AcidCat capabilities in plain TypeScript, with no Effect dependency.",
   "keywords": [
     "acidcat",
@@ -32,11 +32,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@acid-cat/catalog": "0.4.0",
-    "@acid-cat/spec-ts": "0.4.0"
+    "@acid-cat/catalog": "0.5.0",
+    "@acid-cat/spec-ts": "0.5.0"
   },
   "devDependencies": {
-    "@acid-cat/cli": "0.4.0",
+    "@acid-cat/cli": "0.5.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
     "playwright": "1.64.0",