@jarenjs/linq 0.49.2 → 0.56.0

package/src/capture-root.js

@@ -0,0 +1,82 @@
+//@ts-check
+/**
+ * @file One capture over a value rooted at `$` with named externals —
+ * the shared piece under every pen's query-valued member: a schema
+ * `check()` rule (`root`, `path`), a model `compute()` default (no
+ * externals), a JSLT rule body (`root`, `path` and the parameters the
+ * body declares). The value proxy is rooted at `$`, the instance the
+ * query is evaluated at; the externals proxy answers exactly the named
+ * expressions and refuses any other name at build time (`JL0104`),
+ * earlier than the engine's own error and with the same meaning. One
+ * implementation: a pen adds an externals list, never a capture entry
+ * point.
+ */
+
+import { captureExpression } from './expression.js';
+import { LinqBuildError } from './errors.js';
+
+/** No parameters are declared for a rule: `p.x` cannot appear. */
+const NO_PARAMS = new Set();
+
+/** The indefinite article for a method name (`edge() select` → `an`). */
+const article = (/** @type {string} */ what) =>
+  ('aeiou'.includes(what.charAt(0).toLowerCase()) ? 'an' : 'a');
+
+/**
+ * The externals proxy: exactly the named expressions the capture handed
+ * us; anything else has nothing to bind to.
+ *
+ * The message states only what this file KNOWS — how many externals the
+ * evaluator binds and which — because that is all it can know: WHERE the
+ * query is evaluated differs per pen (a schema rule over the instance, a
+ * model default over the document being written, a flow guard over the
+ * step scope at step time), and naming one pen's answer here made the
+ * message contradict its own advice for every other pen. A caller that
+ * has a scope to name passes it as `advice`.
+ * @param {string} what - the method, for the message
+ * @param {readonly string[]} names - the externals bound
+ * @param {readonly any[]} proxies - one expression proxy per name
+ * @param {((name: string) => string) | undefined} advice - the fix, when one exists
+ * @param {string} noun - what this pen calls the callback
+ */
+function externalsProxy(what, names, proxies, advice, noun) {
+  return new Proxy(Object.freeze({}), {
+    get(_target, prop) {
+      if (typeof prop === 'symbol') return undefined;
+      const index = names.indexOf(/** @type {string} */ (prop));
+      if (index !== -1) return proxies[index];
+      const bound = names.length === 0
+        ? 'no externals at all'
+        : `exactly ${names.length === 1 ? 'one external' : `${names.length} externals`}, `
+          + `${names.map((n) => `'${n}'`).join(' and ')}`;
+      throw new LinqBuildError('JL0104',
+        `${article(what)} ${what} ${noun} cannot bind '${prop}' — its query evaluates with `
+        + `${bound}; anything else has nothing to bind to`
+        + (advice === undefined ? '' : advice(prop)));
+    },
+  });
+}
+
+/**
+ * Capture one rule into a query document over a value rooted at `$`,
+ * with the named externals as the second argument.
+ * @param {string} what - the method, for the message
+ * @param {readonly string[]} externals - the externals the evaluator binds
+ * @param {(value: any, externals: any) => any} rule
+ * @param {{ advice?: (name: string) => string, fold?: boolean, noun?: string }} [options] -
+ *   `advice`: appended to the `JL0104` message — how an unbound name could
+ *   be declared where it can, or what the callback's own argument already
+ *   is; `fold`: whether a pure data tree folds into one `$const` (the
+ *   default) or is spelled as a constructor tree; `noun`: what this pen
+ *   calls the callback (`'rule'` by default; a pen with no rules passes
+ *   its own word)
+ * @returns {any} the captured query expression (plain JSON)
+ */
+export function captureQuery(what, externals, rule, options = {}) {
+  const noun = options.noun ?? 'rule';
+  return captureExpression(
+    (value, ...bound) => rule(value, externalsProxy(what, externals, bound, options.advice, noun)),
+    [{ doc: '$', pathable: true }, ...externals],
+    NO_PARAMS,
+    options.fold !== false);
+}

package/src/concurrency.js

@@ -1,7 +1,7 @@
 //@ts-check
 /**
  * @file `mapAsync` — the ONE explicit bounded-concurrency boundary
- * (LINQ-FORMAT.md §11). Element-wise asynchronous work (an HTTP call, a
+ * (QUERY-PEN.md §11). Element-wise asynchronous work (an HTTP call, a
  * model call, a file read per row) happens here and nowhere else: there
  * is no parallel universe of `selectAwait`-shaped operators, and a
  * per-element async *predicate* is `mapAsync` then `where`, by design.
@@ -118,25 +118,30 @@ export async function* applyMapAsync(items, fn, opts) {
     // parallel: a sliding window of `concurrency` in-flight tasks
     const window = [];
     let sourceDone = false;
+    // the first rejection anywhere in the window aborts every sibling
+    // and stops the pull, at once — not when it reaches the head of the
+    // ordered window: the rejection itself still surfaces in order
+    let rejected = false;
     const pull = async () => {
       const step = await items.next();
       if (step.done) { sourceDone = true; return null; }
+      if (rejected) return null; // a sibling failed while this pull awaited
       const promise = Promise.resolve(fn(step.value, signal));
       // a rejection must wait its turn in the ordered window without
       // firing unhandledRejection while an earlier task is in flight
-      promise.catch(() => {});
+      promise.catch(() => { rejected = true; controller.abort(); });
       return { promise };
     };
     if (opts.ordered) {
       // completion order = source order; the window buffers at most
       // `concurrency` results (the documented buffering cost)
-      while (!sourceDone && window.length < opts.concurrency) {
+      while (!sourceDone && !rejected && window.length < opts.concurrency) {
         const task = await pull();
         if (task !== null) window.push(task.promise);
       }
       while (window.length > 0) {
         const value = await window.shift();
-        if (!sourceDone) {
+        if (!sourceDone && !rejected) {
           const task = await pull();
           if (task !== null) window.push(task.promise);
         }

package/src/contract/define.js

@@ -0,0 +1,269 @@
+//@ts-check
+/**
+ * @file `defineContract({ id?, version?, compat? }, operations)` — one
+ * `$contract` 0.1 document, deep-frozen, that `compileContract` takes
+ * unchanged.
+ *
+ * Two rules make the pen's document and its own public projection
+ * comparable member for member. First, the member ORDER is §12.1's, the
+ * normative one the revision hashes: root `$contract, id, version,
+ * compat, $defs, operations`; operation `kind, input, output, errors,
+ * policy, http, doc`; error `status, schema`; http `method, path, in,
+ * body, status, media`; `$defs` in first-reference order. Second, no
+ * DEFAULT is written: `describe()` marks a default inferred, and a pen
+ * that wrote them would turn every default into a declaration and move
+ * the revision for nothing.
+ *
+ * Every `named()` builder any operation reaches becomes one entry of the
+ * contract's own `$defs`, referenced `#/$defs/<name>` — the schema pen's
+ * hoisting walk over several roots instead of one. Nothing here imports
+ * `@jarenjs/contract`: the compiler stays the only judge of what the
+ * document means.
+ */
+
+import { cloneJson, deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
+import { isSchemaBuilder } from '../schema/brand.js';
+import { createHoist, emitInto, hoistedDefs } from '../schema/emit.js';
+import { http as httpBinding, isHttpBinding } from './http.js';
+import { checkOperation, emitPolicy, isOperation, KINDS, readErrors } from './operation.js';
+
+const CONTRACT_VERSION = '0.1';
+const HEAD_MEMBERS = ['id', 'version', 'compat'];
+
+/** `[A-Za-z_][A-Za-z0-9_-]*` — a contract id (§2.1). */
+const ID = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/** @param {any} value */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * One schema position — `input`, `output`, an error's `schema` — as the
+ * document carries it: a builder emitted into the shared `$defs`
+ * context, or a JSON Schema written by hand, copied.
+ * @param {any} value
+ * @param {any} ctx - the hoisting context
+ * @param {string} at
+ * @returns {any}
+ */
+function schemaAt(value, ctx, at) {
+  if (isSchemaBuilder(value)) return emitInto(value, ctx, at);
+  const json = requireJson(value, `the schema at ${at}`);
+  if (typeof json !== 'boolean' && !isPlainObject(json)) {
+    throw new LinqBuildError('JL0101',
+      `a schema is an object, true or false — got ${describeValue(value)}`, at);
+  }
+  return cloneJson(json);
+}
+
+/**
+ * The kind and spec of one declared operation: a `read()`/`command()`/
+ * `subscribe()` declaration, or the same members written by hand with a
+ * `kind`.
+ *
+ * The hand-written form is checked HERE by the same predicate the three
+ * declaration functions run, against its own position in the document.
+ * It is a second door into one emitter, and a door with no check behind
+ * it is worse than no door: an unknown member would be dropped in
+ * silence (the pen never sees it again, and the compiler never sees it
+ * at all), and a non-string `doc` would be written into a document
+ * `jaren-contract` refuses.
+ * @param {any} declared
+ * @param {string} at
+ * @returns {{ kind: string, spec: any }}
+ */
+function declarationOf(declared, at) {
+  if (isOperation(declared)) return declared;
+  if (!isPlainObject(declared)) {
+    throw new LinqBuildError('JL0101',
+      `an operation is read(), command() or subscribe() — got ${describeValue(declared)}`, at);
+  }
+  if (!KINDS.includes(declared.kind)) {
+    throw new LinqBuildError('JL0102',
+      `an operation kind is one of ${KINDS.join(', ')} — got ${describeValue(declared.kind)}`,
+      `${at}/kind`);
+  }
+  const { kind, ...spec } = declared;
+  checkOperation(kind, spec, at);
+  return { kind, spec };
+}
+
+/**
+ * Emit one operation, in §12.1's member order, declared members only.
+ * @param {string} id
+ * @param {any} declared
+ * @param {any} ctx - the hoisting context
+ * @returns {any}
+ */
+function emitOperation(id, declared, ctx) {
+  const at = `/operations/${id}`;
+  const { kind, spec } = declarationOf(declared, at);
+  const out = { kind };
+  if (spec.input !== undefined) out.input = schemaAt(spec.input, ctx, `${at}/input`);
+  out.output = schemaAt(spec.output, ctx, `${at}/output`);
+  if (spec.errors !== undefined) {
+    const declaredErrors = readErrors(spec.errors, `${at}/errors`);
+    const errors = {};
+    for (const [code, entry] of declaredErrors) {
+      const e = {};
+      if (entry.status !== undefined) e.status = entry.status;
+      if (entry.schema !== undefined) {
+        e.schema = schemaAt(entry.schema, ctx, `${at}/errors/${code}/schema`);
+      }
+      setObjectMember(errors, code, e);
+    }
+    out.errors = errors;
+  }
+  if (spec.policy !== undefined) out.policy = emitPolicy(spec.policy, `${at}/policy`);
+  if (spec.http !== undefined) {
+    out.http = isHttpBinding(spec.http) ? { ...spec.http } : { ...httpBinding(spec.http) };
+  }
+  if (spec.doc !== undefined) out.doc = spec.doc;
+  return out;
+}
+
+/**
+ * The contract under construction: frozen on creation, its document
+ * assembled once. `document` and `toJSON()` are the same deep-frozen
+ * `$contract` 0.1 JSON; the phantom the declarations carry is what
+ * `ContractOf<>` reads.
+ */
+export class Contract {
+  #document;
+
+  /**
+   * @param {any} document - the assembled document
+   */
+  constructor(document) {
+    this.#document = document;
+    Object.freeze(this);
+  }
+
+  /** The deep-frozen `$contract` 0.1 document. */
+  get document() { return this.#document; }
+
+  /** The document — what `JSON.stringify` writes. @returns {any} */
+  toJSON() { return this.#document; }
+}
+
+/**
+ * Write a `$contract` 0.1 document.
+ *
+ * @param {any} meta - `{ id?, version?, compat? }` (§2.1)
+ * @param {any} operations - operation id → `read()` / `command()` / `subscribe()`
+ * @returns {Contract} the contract, its `document` deep-frozen JSON
+ * @throws {LinqBuildError} `JL0101` a value the pen cannot spell;
+ *   `JL0102` a kind or path template the format reserves; `JL0103` two
+ *   distinct builders under one `$defs` name, or a `ref()` nothing defines
+ * @example
+ * const shop = defineContract({ id: 'shop', version: '5' }, {
+ *   'catalog.load': read({ output: Catalog, http: http({ method: 'GET', path: '/api/catalog' }) }),
+ * });
+ * compileContract(shop.document).ids;   // ['catalog.load']
+ */
+export function defineContract(meta, operations) {
+  if (!isPlainObject(meta)) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() takes ({ id?, version?, compat? }, operations), got `
+      + `${describeValue(meta)} as its first argument`);
+  }
+  for (const key of Object.keys(meta)) {
+    if (!HEAD_MEMBERS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `defineContract() does not take '${key}' — the head is ${HEAD_MEMBERS.join(', ')}; `
+        + 'everything else is an operation', `/${key}`);
+    }
+  }
+  if (meta.id !== undefined && (typeof meta.id !== 'string' || !ID.test(meta.id))) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() id matches [A-Za-z_][A-Za-z0-9_-]*, got ${describeValue(meta.id)}`, '/id');
+  }
+  if (meta.version !== undefined && typeof meta.version !== 'string') {
+    throw new LinqBuildError('JL0101',
+      `defineContract() version is a string, got ${describeValue(meta.version)}`, '/version');
+  }
+  if (meta.compat !== undefined
+    && (!Array.isArray(meta.compat) || meta.compat.some((v) => typeof v !== 'string'))) {
+    throw new LinqBuildError('JL0101',
+      'defineContract() compat is an array of peer version strings', '/compat');
+  }
+  if (!isPlainObject(operations)) {
+    throw new LinqBuildError('JL0101',
+      `defineContract() operations is a plain object of id → operation, got `
+      + `${describeValue(operations)}`, '/operations');
+  }
+  requireNameMap(operations, 'defineContract() operations', '/operations');
+  const ids = Object.keys(operations);
+  if (ids.length === 0) {
+    throw new LinqBuildError('JL0101',
+      'defineContract() needs at least one operation', '/operations');
+  }
+
+  const ctx = createHoist();
+  const emitted = ids.map((id) => [id, emitOperation(id, operations[id], ctx)]);
+  const defs = hoistedDefs(ctx);
+
+  const out = { $contract: CONTRACT_VERSION };
+  if (meta.id !== undefined) out.id = meta.id;
+  if (meta.version !== undefined) out.version = meta.version;
+  if (meta.compat !== undefined) out.compat = meta.compat.slice();
+  if (defs !== null) out.$defs = defs;
+  const ops = {};
+  for (const [id, op] of emitted) setObjectMember(ops, id, op);
+  out.operations = ops;
+  return new Contract(deepFreeze(out));
+}
+
+/**
+ * Bind a contract client to the contract that types it. Identity at
+ * runtime: `invoke`, `url` and `subscribe` are narrowed by the pen's
+ * phantoms, and nothing is added to the binding.
+ * @template C
+ * @param {any} client - any contract client (local, http, port)
+ * @param {C} contract - the pen's contract; the type argument only
+ * @returns {any}
+ * @example
+ * const api = typedClient(openLocalClient(compileContract(shop.document), handlers), shop);
+ * const outcome = await api.invoke('product.save', { id: 1, revision: 4, product });
+ */
+export function typedClient(client, contract) {
+  void contract;
+  return client;
+}
+
+/**
+ * Bind a handler table to the contract it serves. Identity at runtime:
+ * the table is checked against the operation ids and each handler's
+ * input and output typed by the pen's phantoms.
+ * @template C
+ * @template H
+ * @param {C} contract - the pen's contract; the type argument only
+ * @param {H} handlers - operation id → handler
+ * @returns {H}
+ * @example
+ * serveHttp(compiled, typedHandlers(shop, { 'catalog.load': () => catalog }));
+ */
+export function typedHandlers(contract, handlers) {
+  void contract;
+  return handlers;
+}
+
+/**
+ * Bind `contractTools`' output to the contract that types it. Identity
+ * at runtime: each tool's `name` and `execute` argument are narrowed by
+ * the pen's phantoms.
+ * @template C
+ * @param {any} tools - what `contractTools(compiled, client)` answered
+ * @param {C} contract - the pen's contract; the type argument only
+ * @returns {any}
+ * @example
+ * for (const tool of typedTools(contractTools(compiled, client), shop)) toolbox.add(tool);
+ */
+export function typedTools(tools, contract) {
+  void contract;
+  return tools;
+}

package/src/contract/http.js

@@ -0,0 +1,247 @@
+//@ts-check
+/**
+ * @file `http()` — the REST binding of one operation (CONTRACT-FORMAT
+ * §4), written as the format spells it and checked as far as the pen can
+ * see. The path template scan mirrors the compiler's own parser: every
+ * form §4.2 reserves is refused by name with `JL0102`, at build time,
+ * before `compileContract` would answer `JC0008` with the same meaning.
+ * Nothing is canonicalized here — a `:name` template is written as the
+ * author declared it, and the projections are what show the `{name}`
+ * form.
+ */
+
+import { LinqBuildError } from '../errors.js';
+import { describeValue, requireJson } from '../json-boundary.js';
+
+/** The binding brand: how `defineContract` tells a checked binding apart. */
+export const HTTP_BINDING = Symbol.for('@jarenjs/linq/contract-http');
+
+/** The members `http` accepts, in the order §12.1 fixes. */
+export const HTTP_MEMBERS = Object.freeze(['method', 'path', 'in', 'body', 'status', 'media']);
+
+/** The uppercase tokens §4's table lists. */
+export const HTTP_METHODS = Object.freeze(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
+
+/** The four places an input member can travel. */
+export const LOCATIONS = Object.freeze(['path', 'query', 'header', 'body']);
+
+/** `[A-Za-z_][A-Za-z0-9_]*` — a path variable's name. */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The RFC 6570 operators a `{…}` expression may open with; all reserved. */
+const OPERATORS = '+#./;?&=';
+
+/**
+ * One static segment: any character but the structural ones (`/ { } : *
+ * ? #`), whitespace and controls; a `%` must open a well-formed escape.
+ * @param {string} segment
+ * @param {string} at
+ */
+function checkStatic(segment, at) {
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment[i];
+    if (ch === '{' || ch === '}') {
+      throw new LinqBuildError('JL0102',
+        `a variable must be a whole segment ("{name}"), found "${segment}" — the format `
+        + 'reserves a variable that is only part of a segment', at);
+    }
+    if (ch === ':') {
+      throw new LinqBuildError('JL0102',
+        `":" is reserved for a variable segment (":name"), found "${segment}"`, at);
+    }
+    if (ch === '*') {
+      throw new LinqBuildError('JL0102',
+        `"*" is a reserved wildcard form; $contract 0.1 has no wildcards, found "${segment}"`, at);
+    }
+    if (ch === '?' || ch === '#') {
+      throw new LinqBuildError('JL0102',
+        `"${ch}" cannot appear in a path template (the query and fragment are not part of `
+        + 'the path)', at);
+    }
+    const code = segment.charCodeAt(i);
+    if (code <= 0x20 || code === 0x7f) {
+      throw new LinqBuildError('JL0102',
+        `whitespace or a control character in segment "${segment}"`, at);
+    }
+    if (ch === '%') {
+      if (!/^[0-9A-Fa-f]{2}$/.test(segment.slice(i + 1, i + 3))) {
+        throw new LinqBuildError('JL0102',
+          `a malformed percent-escape in segment "${segment}"`, at);
+      }
+      i += 2;
+    }
+  }
+}
+
+/**
+ * The variables a template declares, refusing every reserved form by
+ * name (§4.2). Mirrors the compiler's parser; nothing is rewritten.
+ * @param {any} source
+ * @param {string} at
+ * @returns {string[]} the variable names, in order
+ */
+export function pathVariables(source, at) {
+  if (typeof source !== 'string') {
+    throw new LinqBuildError('JL0102',
+      `http() path is a path template string, got ${describeValue(source)}`, at);
+  }
+  if (source.length === 0 || source[0] !== '/') {
+    throw new LinqBuildError('JL0102', 'a path template must start with "/"', at);
+  }
+  /** @type {string[]} */
+  const variables = [];
+  if (source === '/') return variables;
+  const segments = source.slice(1).split('/');
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment.length === 0) {
+      throw new LinqBuildError('JL0102', i === segments.length - 1
+        ? 'a trailing "/" declares an empty segment; the root template "/" is the only empty path'
+        : 'an empty segment ("//")', at);
+    }
+    /** @type {string | null} */
+    let name = null;
+    if (segment[0] === '{') {
+      if (segment[segment.length - 1] !== '}') {
+        throw new LinqBuildError('JL0102',
+          `a variable must be a whole segment ("{name}"), found "${segment}" — the format `
+          + 'reserves a variable that is only part of a segment', at);
+      }
+      name = segment.slice(1, -1);
+      if (name.length > 0 && OPERATORS.includes(name[0])) {
+        throw new LinqBuildError('JL0102',
+          `"{${name}}" uses the reserved RFC 6570 operator "${name[0]}"; $contract 0.1 `
+          + 'supports only "{name}"', at);
+      }
+      const last = name[name.length - 1];
+      if (last === '+' || last === '*') {
+        throw new LinqBuildError('JL0102',
+          `"{${name}}" uses the reserved "${last}" expansion modifier; $contract 0.1 has no `
+          + 'wildcards', at);
+      }
+      if (name.includes(',') || name.includes(':')) {
+        throw new LinqBuildError('JL0102',
+          `"{${name}}" uses a reserved RFC 6570 list or prefix form; $contract 0.1 supports `
+          + 'only "{name}"', at);
+      }
+    }
+    else if (segment[0] === ':') {
+      name = segment.slice(1);
+      if (name.length === 0 || name.includes('{') || name.includes('}')) {
+        throw new LinqBuildError('JL0102',
+          `":name" must be a whole segment with an identifier name, found "${segment}"`, at);
+      }
+      const last = name[name.length - 1];
+      if (last === '*' || last === '+' || last === '?') {
+        throw new LinqBuildError('JL0102',
+          `":${name}" uses a reserved "${last}" modifier; $contract 0.1 has no wildcards or `
+          + 'optional segments', at);
+      }
+    }
+    if (name === null) {
+      checkStatic(segment, at);
+      continue;
+    }
+    if (!IDENT.test(name)) {
+      throw new LinqBuildError('JL0102',
+        `a variable name must match [A-Za-z_][A-Za-z0-9_]*, found "${name}"`, at);
+    }
+    if (variables.includes(name)) {
+      throw new LinqBuildError('JL0102', `the variable "${name}" is declared twice`, at);
+    }
+    variables.push(name);
+  }
+  return variables;
+}
+
+/**
+ * One operation's HTTP binding, checked and branded. The members are
+ * written in §12.1's order — `method`, `path`, `in`, `body`, `status`,
+ * `media` — and only the ones declared: a default is the compiler's to
+ * materialize, never the pen's to write.
+ *
+ * @param {any} spec - `{ method, path, in?, body?, status?, media? }`
+ * @returns {any} the binding, frozen and branded
+ * @throws {LinqBuildError} `JL0101` a member that is not what it takes;
+ *   `JL0102` a path template form the format reserves
+ * @example
+ * http({ method: 'PUT', path: '/api/products/{id}', in: { revision: 'body' } });
+ */
+export function http(spec) {
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    throw new LinqBuildError('JL0101',
+      `http() takes { method, path, in?, body?, status?, media? }, got ${describeValue(spec)}`);
+  }
+  for (const key of Object.keys(spec)) {
+    if (!HTTP_MEMBERS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `http() does not take '${key}' — the binding is ${HTTP_MEMBERS.join(', ')} `
+        + '(CONTRACT-FORMAT §4)', `/${key}`);
+    }
+  }
+  if (!HTTP_METHODS.includes(spec.method)) {
+    throw new LinqBuildError('JL0101',
+      `http() method is one uppercase token of ${HTTP_METHODS.join(' ')}, got `
+      + `${describeValue(spec.method)}`, '/method');
+  }
+  const variables = pathVariables(spec.path, '/path');
+
+  const out = { method: spec.method, path: spec.path };
+  if (spec.in !== undefined) {
+    const locations = requireJson(spec.in, 'http() in');
+    if (locations === null || typeof locations !== 'object' || Array.isArray(locations)) {
+      throw new LinqBuildError('JL0101',
+        'http() in is a plain object of input member → path | query | header | body', '/in');
+    }
+    const placed = {};
+    for (const member of Object.keys(locations)) {
+      const where = locations[member];
+      if (!LOCATIONS.includes(where)) {
+        throw new LinqBuildError('JL0101',
+          `http() in.${member} is one of ${LOCATIONS.join(', ')}, got ${describeValue(where)}`,
+          `/in/${member}`);
+      }
+      if (where === 'path' && !variables.includes(member)) {
+        throw new LinqBuildError('JL0102',
+          `http() maps '${member}' to path, but the template declares no {${member}} — a `
+          + 'path member is named by the template itself', `/in/${member}`);
+      }
+      placed[member] = where;
+    }
+    out.in = placed;
+  }
+  if (spec.body !== undefined) {
+    if (typeof spec.body !== 'string' || spec.body.length === 0) {
+      throw new LinqBuildError('JL0101',
+        `http() body names the input member whose value IS the request body, got `
+        + `${describeValue(spec.body)}`, '/body');
+    }
+    out.body = spec.body;
+  }
+  if (spec.status !== undefined) {
+    if (!Number.isInteger(spec.status) || spec.status < 200 || spec.status > 299) {
+      throw new LinqBuildError('JL0101',
+        `http() status is an integer in 200–299, got ${describeValue(spec.status)}`, '/status');
+    }
+    out.status = spec.status;
+  }
+  if (spec.media !== undefined) {
+    if (typeof spec.media !== 'string' || spec.media.length === 0) {
+      throw new LinqBuildError('JL0101',
+        `http() media is a media type, got ${describeValue(spec.media)}`, '/media');
+    }
+    out.media = spec.media;
+  }
+  Object.defineProperty(out, HTTP_BINDING, { value: true, enumerable: false });
+  return Object.freeze(out);
+}
+
+/**
+ * Whether a value is an `http()` binding (as opposed to the same members
+ * written by hand, which `defineContract` accepts and checks the same way).
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isHttpBinding(value) {
+  return value !== null && typeof value === 'object' && value[HTTP_BINDING] === true;
+}

package/src/contract/index.js

@@ -0,0 +1,23 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/contract` — `$contract` 0.1 documents by code.
+ * `defineContract({ id?, version?, compat? }, operations)` writes the
+ * document `compileContract` takes, with every `named()` schema builder
+ * an operation reaches hoisted into the contract's own `$defs` and every
+ * member in the order CONTRACT-FORMAT §12.1 fixes, so a pen document and
+ * its own public projection differ by nothing but the defaults the
+ * compiler materializes. `read`/`command`/`subscribe` declare the three
+ * kinds, `http()` the REST binding (its path template checked here,
+ * earlier than the compiler's `JC0008`), `error()` one entry of an
+ * operation's `errors`.
+ *
+ * The three identity wrappers — `typedClient`, `typedHandlers`,
+ * `typedTools` — carry the inferred `Operations` type onto a client, a
+ * handler table and an AI toolbox without running the TypeScript
+ * projection. The document is the deliverable; nothing here imports
+ * `@jarenjs/contract` or an engine.
+ */
+
+export { defineContract, typedClient, typedHandlers, typedTools, Contract } from './define.js';
+export { read, command, subscribe, error } from './operation.js';
+export { http } from './http.js';