@jarenjs/linq 0.49.2 → 0.56.0

package/types/app.d.ts

@@ -0,0 +1,293 @@
+/**
+ * Hand-authored declarations for `@jarenjs/linq/app` — the app pen's
+ * type contract, kept to the same line as `index.d.ts`: the common path
+ * is precisely typed, the exotic path is honestly `unknown`, nothing is
+ * ever a WRONG type.
+ *
+ * `AppDocument<State, Actions>` carries the state shape and the ACTION
+ * NAMES as phantoms, both read off the declarations themselves — the
+ * keys of `actions` are literal, so `ActionsOf<typeof app>` is the union
+ * a `bind<Names>()` is checked against and `bind<Names>('nope')` does
+ * not compile, before it is `JL0102` and long before the loop's
+ * `JA2001`.
+ *
+ * The honest limits, both of them TypeScript's own (a function's type
+ * arguments are all-or-none, and a sibling member's inferred type cannot
+ * contextually type a callback beside it):
+ *
+ * - an action's `s` is typed by ANNOTATION — `action((s: Expr<State>, x)
+ *   => …)` — because `action()` is evaluated before `defineApp()` sees
+ *   the `state` builder. What `defineApp({ state })` types is the
+ *   DOCUMENT (`StateOf<typeof app>`), which is what a host reading
+ *   `app.getState()` needs. `x.payload` needs no annotation:
+ *   `action(fn, { payload })` declares it on the same call.
+ * - `bind()`'s action name is checked by annotating the call —
+ *   `bind<Action>('todo/add')` — where `Action` is the union the author
+ *   declared or `ActionsOf<>` read back. `defineApp()` checks the other
+ *   direction at run time over the whole view, which is the half a type
+ *   cannot reach: a view is a compiled stylesheet by then.
+ *
+ * Every claim here has a runtime twin in `test/linq/app-pen.test.js` and
+ * a compile-level pin in `test/consumer/linq-app.ts`; APP-PEN.md is the
+ * normative mapping table.
+ */
+
+import type { Expr, MemberExpr, UnknownExpr } from './index.js';
+import type { BuilderLike, Infer, Json, JsonSchema } from './schema.js';
+
+type AnyBuilder = BuilderLike<any, any, any>;
+
+/** `Expr<any>`/`Expr<unknown>` would pick a wrong arm; the honest top instead. */
+type ValueExpr<T> = MemberExpr<T>;
+
+// ————— the action scope —————
+
+/**
+ * APP-FORMAT §3.1's default `$event` slice, plus one member per field
+ * the binding requested. Every value is a JSON primitive by
+ * construction: `$event` MUST survive `JSON.stringify`, the same
+ * invariant as state.
+ */
+export type EventSlice<Fields extends string = never> =
+  & { readonly type: unknown; readonly value: unknown; readonly checked: unknown; readonly key: unknown }
+  & { readonly [K in Fields]: unknown };
+
+/**
+ * The two externals §3.1 binds beside the state — and the whole ambient
+ * vocabulary an action has.
+ */
+export interface ActionScope<Payload = unknown, Fields extends string = never> {
+  /** The dispatch payload (a binding's `with`), `null` when absent. */
+  readonly payload: ValueExpr<Payload>;
+  /** The serializable event slice, `null` for a programmatic dispatch. */
+  readonly event: Expr<EventSlice<Fields>>;
+}
+
+/** A patch path: a lambda over the state, or an RFC 6901 pointer. The
+ * lambda sees the SAME scope the action does, so a computed index may
+ * read `$payload` — annotate it (`(c: Expr<State>, y: ActionScope<P>)`)
+ * exactly as an action's own callback is annotated. */
+export type PatchPath<State = unknown, Payload = unknown> =
+  | ((state: ValueExpr<State>, externals: ActionScope<Payload>) => unknown)
+  | string;
+
+/** One RFC 6902 operation of a transition's `patch` (§3.2). */
+export interface PatchOp {
+  readonly op: 'add' | 'replace' | 'remove' | 'move' | 'copy' | 'test';
+  readonly from?: unknown;
+  readonly path: unknown;
+  readonly value?: unknown;
+}
+
+/** One effect invocation (§5.1). */
+export interface EffectDeclaration<Run extends string = string> {
+  readonly run: Run;
+  readonly with?: unknown;
+}
+
+/** A transition object (§3.2), as the action's capture spells it. */
+export interface Transition {
+  readonly state?: unknown;
+  readonly patch?: readonly PatchOp[];
+  readonly effects?: readonly EffectDeclaration[];
+}
+
+/** One captured action document, carrying its payload type as a phantom. */
+export interface ActionDeclaration<Payload = unknown> {
+  readonly __payload: Payload;
+  readonly document: Json;
+}
+
+// ————— bindings and subscriptions —————
+
+/** §4's object binding form. */
+export interface Binding<Names extends string = string> {
+  readonly action: Names;
+  readonly with?: unknown;
+  readonly event?: readonly string[];
+  readonly preventDefault?: boolean;
+  readonly stopPropagation?: boolean;
+}
+
+/** One subscription entry (§5.3). */
+export interface SubDeclaration<Run extends string = string> {
+  readonly run: Run;
+  readonly with?: Json;
+  readonly when?: Json;
+  readonly withQuery?: Json;
+  readonly key?: Json;
+  readonly for?: Json;
+}
+
+/** What a subscription's `withQuery`/`key` binds under a `for` fan-out. */
+export interface FanScope<Item = unknown> {
+  /** The item this instance was fanned out over (`$item`). */
+  readonly item: ValueExpr<Item>;
+}
+
+/** A subscription member: a callback over the state, or a query document. */
+export type SubRule<State, Externals> =
+  | ((state: ValueExpr<State>, externals: Externals) => unknown)
+  | { readonly [keyword: string]: unknown }
+  | string;
+
+// ————— the document —————
+
+/**
+ * A `jaren-app` 0.1 document as the pen writes it, carrying the state
+ * shape and the declared action names as phantoms.
+ */
+export interface AppDocument<State = unknown, Actions extends string = string> {
+  readonly __state: State;
+  readonly __actions: Actions;
+  readonly $app: '0.1';
+  readonly state?: Json;
+  readonly view: unknown;
+  readonly actions?: { readonly [name: string]: Json };
+  readonly subs?: readonly SubDeclaration[];
+}
+
+/**
+ * What `defineApp()` answers: the document, and the state's schema
+ * beside it — never merged, because the format has no slot for one.
+ *
+ * `Schema` is the third phantom because the SLOT is not always filled:
+ * `defineApp()` answers `null` for a plain-JSON state with no `schema`
+ * beside it, and a `JsonSchema | boolean` for the two overloads that
+ * were given a builder. Carrying that per overload is what lets the one
+ * line every consumer writes —
+ * `new JarenValidator().compile(stateSchema)` — compile without a narrow
+ * on the overloads that can never answer `null`. It defaults to the
+ * whole union, so `AppResult<State, Actions>` still names any result.
+ */
+export interface AppResult<
+  State = unknown,
+  Actions extends string = string,
+  Schema extends JsonSchema | boolean | null = JsonSchema | boolean | null,
+> {
+  readonly document: AppDocument<State, Actions>;
+  readonly stateSchema: Schema;
+}
+
+/** The state an app document describes — what `app.getState()` answers. */
+export type StateOf<A> = A extends AppResult<infer S, any, any> ? S
+  : A extends AppDocument<infer S, any> ? S : never;
+/** The action names an app declares — what a `bind<>()` is checked against. */
+export type ActionsOf<A> = A extends AppResult<any, infer N, any> ? N
+  : A extends AppDocument<any, infer N> ? N : never;
+
+// ————— the surface —————
+
+/**
+ * One action document (§3): a callback captured over the state, `$event`
+ * and `$payload`, whose result is a transition. Annotate `s` to type it
+ * (`(s: Expr<State>, x) => …`); `payload` and `event` are TYPES only —
+ * the format carries no schema for either.
+ */
+export function action<State = unknown>(
+  fn: (state: ValueExpr<State>, externals: ActionScope<unknown, never>) => unknown,
+): ActionDeclaration<unknown>;
+export function action<
+  B extends AnyBuilder, const Fields extends readonly string[] = [], State = unknown,
+>(
+  fn: (state: ValueExpr<State>, externals: ActionScope<Infer<B>, Fields[number]>) => unknown,
+  options: { readonly payload: B; readonly event?: Fields },
+): ActionDeclaration<Infer<B>>;
+export function action<const Fields extends readonly string[], State = unknown>(
+  fn: (state: ValueExpr<State>, externals: ActionScope<unknown, Fields[number]>) => unknown,
+  options: { readonly event: Fields },
+): ActionDeclaration<unknown>;
+
+/** A transition object (§3.2), in the order the runtime applies it. */
+export function transition(spec: {
+  readonly state?: unknown;
+  readonly patch?: readonly PatchOp[];
+  readonly effects?: readonly EffectDeclaration[];
+}): Transition;
+
+/** One effect invocation (§5.1). Its props are a value in the ACTION's
+ * own scope: one document, one capture. */
+export function effect<const Run extends string>(
+  run: Run, props?: unknown): EffectDeclaration<Run>;
+
+/** `{ "op": "add", "path", "value" }` — sets a member, or REPLACES an
+ * array when the path names one; `append()` is the array insert. */
+export function add<State = unknown, Payload = unknown>(
+  path: PatchPath<State, Payload>, value: unknown): PatchOp;
+/** `{ "op": "add", "path": "<path>/-", "value" }` — RFC 6902's array append. */
+export function append<State = unknown, Payload = unknown>(
+  path: PatchPath<State, Payload>, value: unknown): PatchOp;
+/** `{ "op": "replace", "path", "value" }` — and the op an array ELEMENT needs. */
+export function replace<State = unknown, Payload = unknown>(
+  path: PatchPath<State, Payload>, value: unknown): PatchOp;
+/** `{ "op": "remove", "path" }`. */
+export function remove<State = unknown, Payload = unknown>(
+  path: PatchPath<State, Payload>): PatchOp;
+/** `{ "op": "move", "from", "path" }`. */
+export function move<State = unknown, Payload = unknown>(
+  from: PatchPath<State, Payload>, path: PatchPath<State, Payload>): PatchOp;
+/** `{ "op": "copy", "from", "path" }`. */
+export function copy<State = unknown, Payload = unknown>(
+  from: PatchPath<State, Payload>, path: PatchPath<State, Payload>): PatchOp;
+/** `{ "op": "test", "path", "value" }` — a failing test aborts the transition. */
+export function test<State = unknown, Payload = unknown>(
+  path: PatchPath<State, Payload>, value: unknown): PatchOp;
+
+/**
+ * One event binding (§4). Annotate the call with the declared action
+ * names — `bind<Action>('todo/add')` — and a name the app does not
+ * declare stops compiling.
+ */
+export function bind<Names extends string = string>(
+  name: Names,
+  options?: {
+    readonly payload?: unknown;
+    readonly event?: readonly string[];
+    readonly preventDefault?: boolean;
+    readonly stopPropagation?: boolean;
+  },
+): Binding<Names>;
+
+/** One subscription entry (§5.3). `with` is verbatim data and never
+ * restarts; `withQuery`/`key`/`for` are queries and make it dynamic. */
+export function sub<const Run extends string, State = unknown, Item = unknown>(
+  run: Run,
+  options?: {
+    readonly with?: Json;
+    readonly when?: SubRule<State, Record<string, never>>;
+    readonly withQuery?: SubRule<State, FanScope<Item>>;
+    readonly key?: SubRule<State, FanScope<Item>>;
+    readonly for?: SubRule<State, Record<string, never>>;
+  },
+): SubDeclaration<Run>;
+
+/**
+ * Write a `jaren-app` 0.1 document (§2) and the JSON Schema of its
+ * state. The initial state comes from the state builder's `default()`s
+ * unless `initial` names one; a required member that declares neither is
+ * `JL0102`.
+ */
+export function defineApp<
+  B extends AnyBuilder, const A extends Record<string, ActionDeclaration<any>> = {},
+>(spec: {
+  readonly state: B;
+  readonly initial?: Infer<B>;
+  readonly view: unknown;
+  readonly actions?: A;
+  readonly subs?: readonly SubDeclaration[];
+}): AppResult<Infer<B>, keyof A & string, JsonSchema | boolean>;
+export function defineApp<
+  B extends AnyBuilder, const A extends Record<string, ActionDeclaration<any>> = {},
+>(spec: {
+  readonly state?: Json;
+  readonly schema: B;
+  readonly view: unknown;
+  readonly actions?: A;
+  readonly subs?: readonly SubDeclaration[];
+}): AppResult<Infer<B>, keyof A & string, JsonSchema | boolean>;
+export function defineApp<const A extends Record<string, ActionDeclaration<any>> = {}>(spec: {
+  readonly state?: Json;
+  readonly view: unknown;
+  readonly actions?: A;
+  readonly subs?: readonly SubDeclaration[];
+}): AppResult<unknown, keyof A & string, null>;

package/types/contract.d.ts

@@ -0,0 +1,371 @@
+/**
+ * `@jarenjs/linq/contract` — the contract pen's declarations.
+ *
+ * `defineContract()` returns a `Contract<Ops>` whose phantom `Ops` is
+ * read by `ContractOf<>`: one entry per declared operation carrying its
+ * `kind`, the `Infer<>` of its input (or `null` when it declares none),
+ * the `Infer<>` of its output, the union of its declared error codes,
+ * and whether its media makes it opaque. Every one of those is a
+ * compile-time reading of the SAME builders the emitted document was
+ * written from (D2), so the three wrappers below can type a client, a
+ * handler table and an AI toolbox with no `generate` step.
+ *
+ * The agreement is a gate: `test/consumer/linq-contract.ts` proves
+ * `ContractOf<>`'s members EQUAL to what
+ * `@jarenjs/contract/project`'s `toTypeScript` declares for the document
+ * the pen emitted (`test/consumer/linq-contract-generated.ts`,
+ * regenerated byte-identically by `test/linq/contract-pen.test.js`),
+ * for every worked example. Where the projection widens — an opaque or
+ * boolean `output` is `unknown`, an error's `details` is `unknown` — the
+ * pen widens identically. The shapes `Meta`, `WireError`, `Outcome<T>`,
+ * `InvokeContext`, `Failure`, `HandlerContext` restate
+ * CONTRACT-FORMAT §10.1's fixed D6 members and §12.3's rendering of
+ * them, and the same file pins them equal.
+ *
+ * The runtime is in src/contract/*; CONTRACT-PEN.md is the normative
+ * mapping table.
+ */
+
+import type { BuilderLike, Infer, Input, Json, JsonSchema, Simplify } from './schema.js';
+
+/** A `$contract` 0.1 document as the pen writes it: members, verbatim. */
+export interface ContractDocument {
+  readonly [member: string]: unknown;
+}
+
+// ——— the declaration surface ———
+
+/** The head members §2.1 declares beside `operations`. */
+export interface ContractMeta {
+  /** An identifier for the contract (`[A-Za-z_][A-Za-z0-9_-]*`). */
+  readonly id?: string;
+  /** The consumer's version string — a compatibility claim. */
+  readonly version?: string;
+  /** Peer `version` strings this contract accepts. */
+  readonly compat?: readonly string[];
+}
+
+/** An uppercase method token §4's table lists. */
+export type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+
+/** Where one input member travels (§4.1). */
+export type Location = 'path' | 'query' | 'header' | 'body';
+
+/** The REST binding of one operation (§4). */
+export interface HttpSpec {
+  readonly method: HttpMethod;
+  /** A path template (§4.2): `/api/products/{id}` or `/docs/:id`. */
+  readonly path: string;
+  /** Input member → location; the ones the default does not place. */
+  readonly in?: { readonly [member: string]: Location };
+  /** The input member whose value IS the request body. */
+  readonly body?: string;
+  /** The success status, 200–299. Default `200`, never written. */
+  readonly status?: number;
+  /** The response media type. Default `application/json`, never written. */
+  readonly media?: string;
+}
+
+/** A checked binding: the spec it was written from, carried as a phantom. */
+export interface HttpBinding<H extends HttpSpec = HttpSpec> {
+  readonly __http: H;
+}
+
+/** The stream knobs of a subscribe operation (§3.1). */
+export interface StreamPolicy {
+  readonly resume?: 'snapshot' | 'replay';
+  readonly heartbeatMs?: number;
+  readonly maxPatchBytes?: number;
+}
+
+/** The declared behavior of one operation (§3.1). Every member has a
+ * default the COMPILER materializes; the pen writes only what is here. */
+export interface Policy {
+  readonly task?: 'switch' | 'exhaust' | 'concat' | 'parallel';
+  readonly idempotency?: 'none' | 'optional' | 'required';
+  /** `"input:<json-pointer>"` — where the revision a command asserts lives. */
+  readonly revision?: string;
+  readonly cache?: 'none' | 'revision';
+  readonly limits?: { readonly maxBodyBytes: number };
+  readonly errors?: { readonly details: 'none' | 'paths' | 'full' };
+  readonly retry?: { readonly max: number; readonly on: readonly string[] };
+  readonly stream?: StreamPolicy;
+  readonly audience?: 'public' | 'server';
+}
+
+/** A schema position: a schema-pen builder, or a JSON Schema by hand. */
+export type SchemaSpec = BuilderLike<any, any, any> | JsonSchema | boolean;
+
+/** One entry of an operation's `errors` map (§3). */
+export interface ErrorSpec {
+  /** 100–599. Default `400`, never written. */
+  readonly status?: number;
+  /** A JSON Schema for the error's details. */
+  readonly schema?: SchemaSpec;
+}
+
+/** A checked error declaration: the spec it was written from. */
+export interface ErrorDeclaration<E extends ErrorSpec = ErrorSpec> {
+  readonly __error: E;
+}
+
+/** What `read()`/`command()`/`subscribe()` take (§3). */
+export interface OperationSpec {
+  /** A schema whose effective type is `object`; absent takes no input. */
+  readonly input?: SchemaSpec;
+  readonly output: SchemaSpec;
+  readonly errors?: { readonly [code: string]: ErrorDeclaration<any> | ErrorSpec };
+  readonly policy?: Policy;
+  readonly http?: HttpBinding<any> | HttpSpec;
+  readonly doc?: string;
+}
+
+/** A declared operation: its kind and the spec it was written from. */
+export interface OperationDeclaration<K extends OperationKind, S extends OperationSpec> {
+  readonly __kind: K;
+  readonly __spec: S;
+}
+
+/** The three kinds §3 declares. */
+export type OperationKind = 'read' | 'command' | 'subscribe';
+
+/** An operation of any kind. */
+export type AnyOperation = OperationDeclaration<OperationKind, any>;
+
+// ——— the phantom reading ———
+
+/** The output shape of a schema position; `unknown` for JSON by hand. */
+type SchemaOut<S> = S extends BuilderLike<any, any, any> ? Infer<S> : unknown;
+/** The accepted shape of a schema position; `unknown` for JSON by hand. */
+type SchemaIn<S> = S extends BuilderLike<any, any, any> ? Input<S> : unknown;
+
+/** The media a binding declares; the default when it declares none. A
+ * spec is matched by PATTERN, never indexed: an absent optional member
+ * of the constraint is not the same as one the author declared. */
+type MediaOf<S> =
+  S extends { http: HttpBinding<infer H> }
+    ? (H extends { media: infer M extends string } ? M : 'application/json')
+    : S extends { http: { media: infer M extends string } } ? M : 'application/json';
+
+/** A non-JSON media marks the operation opaque (§4.5); a subscribe never is. */
+type IsOpaque<K extends OperationKind, S> =
+  K extends 'subscribe' ? false
+    : MediaOf<S> extends 'application/json' ? false
+      : MediaOf<S> extends `${string}+json` ? false : true;
+
+/** The codes an operation declares, as a literal union. */
+type CodesOf<S> = S extends { errors: infer E } ? Extract<keyof E, string> : never;
+
+/** One operation, as the type system reads it. */
+export interface OperationType<
+  K extends OperationKind, I, In, O, E extends string, Opaque extends boolean,
+> {
+  readonly kind: K;
+  /** The output shape of the input schema; `null` when none is declared. */
+  readonly input: I;
+  /** The accepted (pre-normalization) shape of the input schema. */
+  readonly accepts: In;
+  readonly output: O;
+  /** The declared error codes; `never` when none is declared. */
+  readonly errors: E;
+  readonly opaque: Opaque;
+}
+
+/** The reading of one declared operation. */
+type Read<D> = D extends OperationDeclaration<infer K, infer S>
+  ? OperationType<
+    K,
+    S extends { input: infer I } ? SchemaOut<I> : null,
+    S extends { input: infer I } ? SchemaIn<I> : null,
+    S extends { output: infer O } ? SchemaOut<O> : unknown,
+    CodesOf<S>,
+    IsOpaque<K, S>>
+  : never;
+
+/** The reading of a whole operation map. */
+export type OperationsOf<O> = Simplify<{ readonly [K in keyof O]: Read<O[K]> }>;
+
+/**
+ * The contract a pen wrote: `document` and `toJSON()` are the same
+ * deep-frozen `$contract` 0.1 JSON, and `Ops` is the phantom
+ * `ContractOf<>` reads.
+ */
+export class Contract<Ops = Record<string, never>> {
+  private constructor();
+  /** Declared, never present at runtime. */
+  readonly __ops: Ops;
+  /** The deep-frozen `$contract` 0.1 document. */
+  readonly document: ContractDocument;
+  toJSON(): ContractDocument;
+}
+
+/** Every operation a contract declares, opaque ones included. */
+export type ContractOf<C> = C extends Contract<infer Ops> ? Ops : never;
+
+/** The invokable operations: everything the AI tools and `invoke` reach —
+ * the opaque ones are excluded, exactly as §12.3's `Operations` is. */
+export type InvokableOf<C> = Simplify<{
+  [K in keyof ContractOf<C> as ContractOf<C>[K] extends { opaque: true } ? never : K]:
+  ContractOf<C>[K]
+}>;
+
+/** The subscribe operations of a contract. */
+export type SubscribableOf<C> = Simplify<{
+  [K in keyof ContractOf<C> as ContractOf<C>[K] extends { kind: 'subscribe' } ? K : never]:
+  ContractOf<C>[K]
+}>;
+
+// ——— the fixed outcome shapes (§10.1, rendered by §12.3) ———
+
+/** The correlation members of every outcome. A member a binding cannot
+ * carry is null (or false for `notModified`), never omitted. */
+export type Meta = {
+  op: string; attempt: unknown; trace: string | null; revision: string | null;
+  etag: string | null; notModified: boolean;
+};
+
+/** The error member of a failed outcome. */
+export type WireError = {
+  code: string; message: string; status: number | null; details: unknown; retryable: boolean;
+};
+
+/** What every invoke resolves to — JSON, never a thrown error. */
+export type Outcome<T> =
+  | { ok: true; value: T; meta: Meta }
+  | {
+    ok: false; kind: 'failure' | 'network' | 'contract' | 'cancelled';
+    error: WireError; meta: Meta;
+  };
+
+/** Per-call options of `invoke`. */
+export interface InvokeContext {
+  signal?: AbortSignal; attempt?: unknown; idempotencyKey?: string;
+  headers?: Record<string, string>; ifNoneMatch?: string; ifMatch?: string;
+}
+
+/** A declared failure a handler returns (`ctx.fail`). */
+export type Failure = {
+  code: string; params: Readonly<Record<string, unknown>>; details: unknown;
+  retryable: boolean | null;
+};
+
+/** The per-request context a server binding hands a handler. */
+export interface HandlerContext {
+  op: unknown;
+  trace: string;
+  method: string;
+  path: string;
+  params: Readonly<Record<string, string>>;
+  headers: Readonly<Record<string, string>>;
+  body: string | Uint8Array | null;
+  signal: AbortSignal | null;
+  idempotency: Readonly<{ key: string; scope: string }> | null;
+  fail(code: string, params?: Record<string, unknown>, details?: unknown,
+    options?: { retryable?: boolean }): Failure;
+  etag(tag: string, options?: { strong?: boolean }): void;
+  status(status: number): void;
+}
+
+/** What `client.subscribe` takes (§19); every callback is optional. */
+export interface SubscribeHandlers<T> {
+  onSnapshot?(value: T, info: { seq: number; resumed: boolean }): void;
+  onPatch?(emission: { patch: readonly Json[]; seq: number }): void;
+  onError?(outcome: Outcome<never>): void;
+  onEnd?(info: { reason: string }): void;
+  signal?: AbortSignal;
+  lastSeq?: number;
+}
+
+/** A live subscription: `stop()` releases it (§19). */
+export interface Subscription {
+  stop(): void;
+}
+
+// ——— the three identity wrappers ———
+
+/** A contract client typed by one contract's operations. */
+export interface TypedClient<C> {
+  invoke<K extends keyof InvokableOf<C>>(
+    op: K,
+    input: InvokableOf<C>[K] extends { input: infer I } ? I : never,
+    ctx?: InvokeContext,
+  ): Promise<Outcome<InvokableOf<C>[K] extends { output: infer O } ? O : never>>;
+  subscribe<K extends keyof SubscribableOf<C>>(
+    op: K,
+    input: SubscribableOf<C>[K] extends { input: infer I } ? I : never,
+    handlers: SubscribeHandlers<
+      SubscribableOf<C>[K] extends { output: infer O } ? O : never>,
+  ): Subscription;
+  url<K extends keyof ContractOf<C>>(
+    op: K,
+    input: ContractOf<C>[K] extends { input: infer I } ? I : never,
+  ): string;
+  close(): void;
+}
+
+/** The handler table of a server binding, one handler per invokable operation. */
+export type TypedHandlerTable<C> = {
+  [K in keyof InvokableOf<C>]: (
+    input: InvokableOf<C>[K] extends { input: infer I } ? I : never,
+    ctx: HandlerContext,
+  ) => (InvokableOf<C>[K] extends { output: infer O } ? O : never)
+  | Failure
+  | Promise<(InvokableOf<C>[K] extends { output: infer O } ? O : never) | Failure>;
+};
+
+/** An operation id as `contractTools` names it: `.` → `_`. */
+export type ToolName<S extends string> =
+  S extends `${infer A}.${infer B}` ? `${A}_${ToolName<B>}` : S;
+
+/** One tool definition, typed by the operation it invokes — the
+ * `ToolDef` shape `@jarenjs/ai`'s `createToolbox().add` takes. */
+export type TypedTool<C> = {
+  [K in keyof InvokableOf<C>]: {
+    name: ToolName<Extract<K, string>>;
+    description: string;
+    inputSchema: JsonSchema;
+    execute: InvokableOf<C>[K] extends { accepts: infer In; output: infer O }
+      ? (In extends null ? null : (args: In) => Promise<Outcome<O>>)
+      : never;
+  };
+}[keyof InvokableOf<C>];
+
+// ——— the functions ———
+
+/** A `read` operation: a query whose input members default to the query
+ * string and whose result may be cached by revision. */
+export function read<const S extends OperationSpec>(spec: S): OperationDeclaration<'read', S>;
+
+/** A `command` operation: a state change whose input members default to
+ * the request body. */
+export function command<const S extends OperationSpec>(spec: S): OperationDeclaration<'command', S>;
+
+/** A `subscribe` operation (§17): `output` is the snapshot schema and
+ * the emissions travel the stream binding. */
+export function subscribe<const S extends OperationSpec>(spec: S):
+OperationDeclaration<'subscribe', S>;
+
+/** One entry of an operation's `errors` map. */
+export function error<const E extends ErrorSpec>(spec?: E): ErrorDeclaration<E>;
+
+/** The REST binding of one operation; the path template is checked here
+ * (`JL0102` naming the reserved form), earlier than `JC0008`. */
+export function http<const H extends HttpSpec>(spec: H): HttpBinding<H>;
+
+/** Write a `$contract` 0.1 document. */
+export function defineContract<O extends Record<string, AnyOperation | ({
+  kind: OperationKind } & OperationSpec)>>(
+  meta: ContractMeta, operations: O): Contract<OperationsOf<O>>;
+
+/** Bind a contract client to the contract that types it. Identity at runtime. */
+export function typedClient<C extends Contract<any>>(client: unknown, contract: C): TypedClient<C>;
+
+/** Bind a handler table to the contract it serves. Identity at runtime;
+ * a missing or misspelled operation is a type error. */
+export function typedHandlers<C extends Contract<any>>(
+  contract: C, handlers: TypedHandlerTable<C>): TypedHandlerTable<C>;
+
+/** Bind `contractTools`' output to the contract that types it. Identity
+ * at runtime. */
+export function typedTools<C extends Contract<any>>(
+  tools: readonly unknown[], contract: C): TypedTool<C>[];