@jarenjs/linq 0.49.2 → 0.66.1

package/types/contract.d.ts

@@ -0,0 +1,468 @@
+/**
+ * `@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 wrappers below can type a client (an HTTP
+ * one with its byte method), 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 opaque operations of a contract: what an HTTP client's `bytes`
+ * reaches — exactly the set §12.3's `ByteOperations` declares. */
+export type OpaqueOf<C> = Simplify<{
+  [K in keyof ContractOf<C> as ContractOf<C>[K] extends { opaque: true } ? 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 binding a handler context comes from. */
+export type CarrierName = 'http' | 'port' | 'local';
+
+/** The members every carrier's context shares; `host` is the host
+ * lifecycle's acquired value (§7.7), `null` by default. */
+export interface HandlerContextBase<Host = null> {
+  op: unknown;
+  trace: string;
+  host: Host;
+  headers: Readonly<Record<string, string>>;
+  signal: AbortSignal | null;
+  fail(code: string, params?: Record<string, unknown>, details?: unknown,
+    options?: { retryable?: boolean }): Failure;
+}
+
+/** The HTTP binding's context: the request line, the raw body of an
+ * opaque operation, the idempotency key, and the entity-tag and status
+ * arms. */
+export interface HttpHandlerContext<Host = null> extends HandlerContextBase<Host> {
+  carrier: 'http';
+  method: string;
+  path: string;
+  params: Readonly<Record<string, string>>;
+  body: string | Uint8Array | AsyncIterable<Uint8Array> | null;
+  idempotency: Readonly<{ key: string; scope: string }> | null;
+  etag(tag: string, options?: { strong?: boolean }): void;
+  status(status: number): void;
+}
+
+/** The port and local bindings' context: no request line, no body, no
+ * key, and no callable `etag` or `status` — spelled `null`, never
+ * omitted (§15, §16). */
+export interface ChannelHandlerContext<Host = null, Carrier extends 'port' | 'local' = 'port' | 'local'>
+  extends HandlerContextBase<Host> {
+  carrier: Carrier;
+  method: null;
+  path: null;
+  params: null;
+  body: null;
+  idempotency: null;
+  etag: null;
+  status: null;
+}
+
+/** The per-request context a server binding hands a handler, selected
+ * by carrier: the HTTP context by default (`HandlerContext` is the
+ * shape it always was, plus `carrier` and `host`); a carrier union is a
+ * discriminated union — narrow on `carrier` before an HTTP-only
+ * member. */
+export type HandlerContext<Host = null, Carrier extends CarrierName = 'http'> =
+  Extract<HttpHandlerContext<Host> | ChannelHandlerContext<Host, 'port'> | ChannelHandlerContext<Host, 'local'>, { carrier: Carrier }>;
+
+/** Per-call options of `bytes` (§10.6): the members of `InvokeContext`
+ * that apply to an opaque call, plus the request body to send. */
+export interface ByteContext {
+  signal?: AbortSignal; attempt?: unknown; headers?: Record<string, string>;
+  ifNoneMatch?: string; ifMatch?: string;
+  body?: string | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | null;
+}
+
+/** The success value of `bytes`: the status, the lowercase response
+ * headers, the response media and the LIVE body — a stream the caller
+ * reads; `null` when the response carries none. */
+export type ByteResponse = {
+  status: number; headers: Record<string, string>; media: string | null;
+  body: ReadableStream<Uint8Array> | null;
+};
+
+/** The info beside every snapshot (§19): the event's seq, whether the
+ * stream resumed, whether the snapshot re-seeds a consumer whose cursor
+ * fell behind the server's retention (`reset`), and the server log's
+ * watermarks when it reported them. */
+export interface SnapshotInfo {
+  seq: number; resumed: boolean; reset: boolean;
+  earliestAvailable: number | null; highWatermark: number | null;
+}
+
+/** What `client.subscribe` takes (§19); every callback is optional.
+ * `reconnect` opts the HTTP client into re-establishing the stream
+ * after a network loss, up to `max` further attempts from the last
+ * delivered seq; the budget spent, `onError` gets one `JC2097`. The
+ * port client has no network loss to reconnect from and ignores it. */
+export interface SubscribeHandlers<T> {
+  onSnapshot?(value: T, info: SnapshotInfo): void;
+  onPatch?(emission: { patch: readonly Json[]; seq: number }): void;
+  onError?(outcome: Outcome<never>): void;
+  onEnd?(info: { reason: string }): void;
+  signal?: AbortSignal;
+  lastSeq?: number;
+  reconnect?: { max: number };
+}
+
+/** A live subscription: `stop()` releases it; `lastSeq` is the last
+ * delivered seq (`null` before the first, the passed `lastSeq` until an
+ * event moves it) — what a re-entered `subscribe` passes (§19). */
+export interface Subscription {
+  stop(): void;
+  readonly lastSeq: number | null;
+}
+
+// ——— 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;
+}
+
+/** An HTTP client typed by one contract's operations: `TypedClient` plus
+ * `bytes` over the opaque ones, whose success owns a live stream. */
+export interface TypedHttpClient<C> extends TypedClient<C> {
+  bytes<K extends keyof OpaqueOf<C>>(
+    op: K,
+    input: OpaqueOf<C>[K] extends { input: infer I } ? I : never,
+    ctx?: ByteContext,
+  ): Promise<Outcome<ByteResponse>>;
+}
+
+/** The handler table of a server binding, one handler per invokable
+ * operation. `Host` is what the host lifecycle's `acquire` hands the
+ * handler as `ctx.host`; `Carrier` selects the context — `'http'` by
+ * default, a union for a table several bindings share (narrow on
+ * `ctx.carrier` before an HTTP-only member). */
+export type TypedHandlerTable<C, Host = null, Carrier extends CarrierName = 'http'> = {
+  [K in keyof InvokableOf<C>]: (
+    input: InvokableOf<C>[K] extends { input: infer I } ? I : never,
+    ctx: HandlerContext<Host, Carrier>,
+  ) => (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 an HTTP client (`openHttpClient`) to the contract that types it:
+ * `typedClient` plus `bytes` over the opaque operations. Identity at
+ * runtime; a local or port client has no `bytes` and takes `typedClient`. */
+export function typedHttpClient<C extends Contract<any>>(client: unknown, contract: C): TypedHttpClient<C>;
+
+/** Bind a handler table to the contract it serves. Identity at runtime;
+ * a missing or misspelled operation is a type error. Name `Host` and
+ * `Carrier` explicitly for a table whose context is not the HTTP default:
+ * `typedHandlers<typeof Shop, { db: Client }, 'http' | 'port'>(Shop, …)`. */
+export function typedHandlers<C extends Contract<any>, Host = null, Carrier extends CarrierName = 'http'>(
+  contract: C, handlers: TypedHandlerTable<C, Host, Carrier>): TypedHandlerTable<C, Host, Carrier>;
+
+/** 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>[];