@jarenjs/linq 0.56.0 → 0.67.0

package/src/flow/fsm.js

@@ -22,7 +22,7 @@
  * and everything else §5.1 lists.
  */
 
-import { deepFreeze } from '@jarenjs/core/object';
+import { deepFreeze, isJsonObject } from '@jarenjs/core/object';
 
 import { LinqBuildError } from '../errors.js';
 import { effectDescriptor, readEffects } from '../effect.js';
@@ -47,11 +47,6 @@ const ON_MEMBERS = Object.freeze(['payload']);
 /** The members `defineFsm()` takes. */
 const FSM_MEMBERS = Object.freeze(['initial', 'states', 'transitions', 'context']);
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * A member set the pen knows, or `JL0101` naming the one it does not.
  * @param {any} spec
@@ -111,7 +106,7 @@ export function effect(run, props = undefined) {
 export function state(id, options = undefined) {
   const out = { id: readId(id, 'state()') };
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         `state() options are { entry?, exit?, final? }, got ${describeValue(options)}`);
     }
@@ -203,7 +198,7 @@ export function on(from, event = null, options = undefined) {
     entry.event = event;
   }
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         `on() options are { payload? }, got ${describeValue(options)}`);
     }
@@ -239,7 +234,7 @@ export function on(from, event = null, options = undefined) {
  * compileFsm(machine).step('draft', 'submit').state;   // 'review'
  */
 export function defineFsm(spec) {
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101',
       `defineFsm() takes { initial, states, transitions, context? }, got ${describeValue(spec)}`);
   }
@@ -266,7 +261,7 @@ export function defineFsm(spec) {
       states.push(entry);
       return;
     }
-    if (!isPlainObject(entry) || entry[STATE] !== true) {
+    if (!isJsonObject(entry) || entry[STATE] !== true) {
       throw new LinqBuildError('JL0101',
         `defineFsm() states[${i}] is an id or state(id, options?), got ${describeValue(entry)}`,
         `/states/${i}`);
@@ -305,7 +300,7 @@ export function defineFsm(spec) {
   }
   const transitions = spec.transitions.map((declaration, i) => {
     const at = `/transitions/${i}`;
-    const entry = isPlainObject(declaration) ? declaration[TRANSITION] : undefined;
+    const entry = isJsonObject(declaration) ? declaration[TRANSITION] : undefined;
     if (entry === undefined) {
       throw new LinqBuildError('JL0101',
         `defineFsm() transitions[${i}] is on(from, event?).to(state), got `

package/src/index.js

@@ -13,4 +13,5 @@
 export { from, fromDocument, Sequence } from './sequence.js';
 export { fromAsync, AsyncSequence } from './async.js';
 export { createPushQueue } from './sources.js';
+export { federate } from './federate.js';
 export { LinqBuildError, LinqRuntimeError, LINQ_CODES } from './errors.js';

package/src/jslt/rules.js

@@ -13,7 +13,7 @@
  * body's operators, the schema — is the compiler's.
  */
 
-import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+import { deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
 import { LinqBuildError } from '../errors.js';
 import { isSchemaBuilder, schemaOf } from '../schema/brand.js';
 import { describeValue, requireJson, requireNameMap } from '../json-boundary.js';
@@ -24,11 +24,6 @@ const DISPOSITIONS = ['share', 'fresh', 'error'];
 /** A JSON value, copied: the document is a value of its own. @param {any} v */
 const copy = (v) => JSON.parse(JSON.stringify(v));
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * The `match` member (§3.1), or `undefined` for the unconditional rule.
  * @param {any} match
@@ -37,7 +32,7 @@ function isPlainObject(value) {
 function readMatch(match) {
   if (match === undefined || match === null) return undefined;
   if (typeof match === 'string') return match;
-  if (!isPlainObject(match)) {
+  if (!isJsonObject(match)) {
     throw new LinqBuildError('JL0101',
       `rule() match is a JSONPath string or { path?, schema? }, got ${describeValue(match)}`,
       '/match');
@@ -97,7 +92,7 @@ function readBody(value) {
 export function rule(match, bodyOrFn, options = undefined) {
   const out = {};
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         `rule() options are { mode?, priority? }, got ${describeValue(options)}`);
     }
@@ -156,7 +151,7 @@ export function stylesheet(rules, options = undefined) {
   }
   const out = { $jslt: '0.1' };
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101',
         `stylesheet() options are { unmatched?, modes? }, got ${describeValue(options)}`);
     }
@@ -170,7 +165,7 @@ export function stylesheet(rules, options = undefined) {
       out.unmatched = readDisposition(options.unmatched, 'unmatched');
     }
     if (options.modes !== undefined) {
-      if (!isPlainObject(options.modes)) {
+      if (!isJsonObject(options.modes)) {
         throw new LinqBuildError('JL0101',
           `stylesheet() modes is { name: { unmatched } }, got ${describeValue(options.modes)}`,
           '/modes');
@@ -179,7 +174,7 @@ export function stylesheet(rules, options = undefined) {
       const modes = {};
       for (const name of Object.keys(options.modes)) {
         const mode = options.modes[name];
-        if (!isPlainObject(mode) || Object.keys(mode).length !== 1 || mode.unmatched === undefined) {
+        if (!isJsonObject(mode) || Object.keys(mode).length !== 1 || mode.unmatched === undefined) {
           throw new LinqBuildError('JL0101',
             `stylesheet() mode '${name}' is { unmatched } and nothing else (JSLT-FORMAT §2.1)`,
             `/modes/${name}`);
@@ -191,7 +186,7 @@ export function stylesheet(rules, options = undefined) {
     }
   }
   out.rules = rules.map((r, i) => {
-    if (!isPlainObject(r)) {
+    if (!isJsonObject(r)) {
       throw new LinqBuildError('JL0101',
         `stylesheet() rule ${i} is an object — rule(match, body) — got ${describeValue(r)}`,
         `/rules/${i}`);

package/src/migration/define.js

@@ -16,7 +16,7 @@
 
 import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { hashContent } from '@jarenjs/core/string';
-import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+import { deepFreeze, setObjectMember, isJsonObject } from '@jarenjs/core/object';
 
 import { LinqBuildError } from '../errors.js';
 import { describeValue, requireJson } from '../json-boundary.js';
@@ -30,11 +30,6 @@ const HEAD_MEMBERS = ['$migration', 'id', 'from', 'to', 'note', 'steps'];
 /** A JSON value, copied: the document is a value of its own. @param {any} v */
 const copy = (v) => JSON.parse(JSON.stringify(v));
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * The model without its `x-rename` hints. A hint is a PLANNING
  * instruction, not shape (MIGRATION-FORMAT §3): two models that differ
@@ -47,11 +42,11 @@ function withoutRenameHints(model) {
   for (const key of Object.keys(model)) setObjectMember(out, key, model[key]);
   for (const member of ['collections', 'entities']) {
     const declared = model[member];
-    if (!isPlainObject(declared)) continue;
+    if (!isJsonObject(declared)) continue;
     const stripped = {};
     for (const name of Object.keys(declared)) {
       const spec = declared[name];
-      if (isPlainObject(spec) && Object.hasOwn(spec, 'x-rename')) {
+      if (isJsonObject(spec) && Object.hasOwn(spec, 'x-rename')) {
         const { 'x-rename': _hint, ...rest } = spec;
         setObjectMember(stripped, name, rest);
       }
@@ -82,10 +77,10 @@ function shapeHashOf(model) {
  */
 function requireModel(model, what) {
   const doc = requireJson(model, what);
-  if (!isPlainObject(doc) || doc.$model !== '0.1') {
+  if (!isJsonObject(doc) || doc.$model !== '0.1') {
     throw new LinqBuildError('JL0101',
       `${what} is a $model 0.1 document (defineModel(…), or its JSON), got `
-      + `${isPlainObject(doc) ? 'an object without $model: \'0.1\'' : describeValue(model)}`);
+      + `${isJsonObject(doc) ? 'an object without $model: \'0.1\'' : describeValue(model)}`);
   }
   return doc;
 }
@@ -98,7 +93,7 @@ function requireModel(model, what) {
 function declaredNames(model) {
   const names = [];
   for (const member of ['entities', 'collections']) {
-    if (isPlainObject(model[member])) names.push(...Object.keys(model[member]));
+    if (isJsonObject(model[member])) names.push(...Object.keys(model[member]));
   }
   return names;
 }
@@ -241,7 +236,7 @@ export class Migration {
  * @returns {Migration}
  */
 export function defineMigration(spec) {
-  if (!isPlainObject(spec)) {
+  if (!isJsonObject(spec)) {
     throw new LinqBuildError('JL0101', 'defineMigration() takes { id, from, to, note? }');
   }
   for (const key of Object.keys(spec)) {
@@ -277,7 +272,7 @@ export function defineMigration(spec) {
  */
 export function fromPlanned(document, options = undefined) {
   const doc = copy(requireJson(document, 'fromPlanned() document'));
-  if (!isPlainObject(doc) || doc.$migration !== MIGRATION_VERSION
+  if (!isJsonObject(doc) || doc.$migration !== MIGRATION_VERSION
     || typeof doc.id !== 'string' || doc.id === ''
     || typeof doc.from !== 'string' || typeof doc.to !== 'string' || !Array.isArray(doc.steps)) {
     throw new LinqBuildError('JL0101',
@@ -293,7 +288,7 @@ export function fromPlanned(document, options = undefined) {
   }
   let names = null;
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101', `fromPlanned() options are { from?, to? }, got ${describeValue(options)}`);
     }
     for (const key of Object.keys(options)) {

package/src/migration/steps.js

@@ -13,6 +13,7 @@
  * `$it` inside the `$for` the format's own example writes.
  */
 
+import { isJsonObject } from '@jarenjs/core/object';
 import { captureExpression } from '../expression.js';
 import { body } from '../jslt/body.js';
 import { describeValue, requireJson } from '../json-boundary.js';
@@ -28,11 +29,6 @@ const NO_PARAMS = new Set();
 /** A JSON value, copied: the document is a value of its own. @param {any} v */
 const copy = (v) => JSON.parse(JSON.stringify(v));
 
-/** @param {any} value */
-function isPlainObject(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
 /**
  * A table name: an identifier, as the artifact's pattern admits.
  * @param {any} name
@@ -117,7 +113,7 @@ export function transformStep(name, spelling) {
   else if (Array.isArray(spelling)) {
     stylesheet = copy(requireJson(spelling, 'transform() rules'));
   }
-  else if (isPlainObject(spelling) && spelling.$jslt === '0.1') {
+  else if (isJsonObject(spelling) && spelling.$jslt === '0.1') {
     for (const key of Object.keys(spelling)) {
       if (key !== '$jslt' && key !== 'rules') {
         throw new LinqBuildError('JL0102',
@@ -155,7 +151,7 @@ export function assertStep(name, spelling, options = undefined) {
   requireName(name, 'assert()');
   let expect;
   if (options !== undefined) {
-    if (!isPlainObject(options)) {
+    if (!isJsonObject(options)) {
       throw new LinqBuildError('JL0101', `assert() options are { expect? }, got ${describeValue(options)}`);
     }
     for (const key of Object.keys(options)) {
@@ -211,10 +207,10 @@ export function deriveStep(name, columns) {
  */
 export function rawStep(step) {
   const raw = copy(requireJson(step, 'step()'));
-  if (!isPlainObject(raw) || !STEP_KINDS.includes(raw.kind)) {
+  if (!isJsonObject(raw) || !STEP_KINDS.includes(raw.kind)) {
     throw new LinqBuildError('JL0101',
       `step() takes a migration step with a recognised kind (${STEP_KINDS.join(', ')}), got `
-      + `${isPlainObject(raw) ? `kind ${describeValue(raw.kind)}` : describeValue(step)}`);
+      + `${isJsonObject(raw) ? `kind ${describeValue(raw.kind)}` : describeValue(step)}`);
   }
   const need = (member, ok) => {
     if (!ok) {

package/src/model/collection.js

@@ -18,6 +18,10 @@ import { DOCUMENT_SCOPE, refuseStrandedRename } from './entity.js';
 /** The index options the grammar names beside `name` and `path`. */
 const INDEX_OPTIONS = new Set(['name', 'unique', 'derive', 'precision', 'dims', 'physical']);
 
+/** The options an EXPRESSION index takes: it names the members it reads
+ * itself, so nothing that describes a member's storage belongs here. */
+const EXPRESSION_OPTIONS = new Set(['name', 'unique']);
+
 /** The marker a collection spec carries so `defineModel` can tell it apart. */
 export const COLLECTION = Symbol.for('@jarenjs/linq/model-collection');
 
@@ -108,6 +112,104 @@ export function index(path, options = {}) {
   return Object.freeze(out);
 }
 
+/**
+ * One node of an index expression, checked here so a pen mistake is a
+ * build error rather than a store refusal at open. The vocabulary is the
+ * model's, closed: a member path (a lambda or a JSONPath string), a JSON
+ * scalar, or a call to a function the HOST declares — this pen resolves
+ * no name, because arity and determinism are the store's to check
+ * against the declarations it was given.
+ * @param {any} node
+ * @param {string} what
+ * @param {number} depth
+ * @returns {any}
+ */
+function expressionNode(node, what, depth) {
+  if (depth > 8)
+    throw new LinqBuildError('JL0101', `${what} nests deeper than 8`);
+  if (typeof node === 'function') return { member: capturePath(node, what) };
+  if (typeof node === 'string' && node.charCodeAt(0) === 0x24) return { member: node };
+  if (typeof node === 'number' || typeof node === 'boolean') return { value: node };
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) {
+    throw new LinqBuildError('JL0101',
+      `${what} takes a path lambda, a JSONPath string, a JSON scalar, or `
+      + '{ call, args } — an index expression is never SQL text');
+  }
+  if (node.member !== undefined) {
+    if (typeof node.member === 'function')
+      return { member: capturePath(node.member, `${what}.member`) };
+    if (typeof node.member !== 'string' || node.member.length === 0)
+      throw new LinqBuildError('JL0101', `${what}.member takes a path lambda or a JSONPath string`);
+    return { member: node.member };
+  }
+  if (node.value !== undefined) {
+    if (typeof node.value !== 'string' && typeof node.value !== 'number'
+      && typeof node.value !== 'boolean') {
+      throw new LinqBuildError('JL0101',
+        `${what}.value takes a JSON string, number or boolean`);
+    }
+    return { value: node.value };
+  }
+  if (typeof node.call !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(node.call))
+    throw new LinqBuildError('JL0101', `${what}.call names a function by identifier`);
+  const args = node.args ?? [];
+  if (!Array.isArray(args))
+    throw new LinqBuildError('JL0101', `${what}.args is an array`);
+  return {
+    call: node.call,
+    args: args.map((argument, i) => expressionNode(argument, `${what}.args[${i}]`, depth + 1)),
+  };
+}
+
+/**
+ * An index over a computed value: a closed expression over declared
+ * members, JSON scalars and functions the HOST declares deterministic.
+ *
+ * The function is resolved where the declarations are — at
+ * `openStore({ expressions })` — so a name this pen has never heard of
+ * is not an error here; a wrong ARITY and a missing declaration are
+ * `JD0004` at open, before any DDL. What this pen decides is the shape.
+ * @param {any} expression - a `{ call, args }` node, a path lambda, a
+ *   JSONPath string, or a JSON scalar
+ * @param {{ name?: string, unique?: boolean }} [options]
+ * @returns {any} the frozen index document
+ */
+export function expressionIndex(expression, options = {}) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options))
+    throw new LinqBuildError('JL0101', 'expressionIndex() takes an options object');
+  for (const key of Object.keys(options)) {
+    if (!EXPRESSION_OPTIONS.has(key)) {
+      throw new LinqBuildError('JL0101',
+        `expressionIndex() does not take '${key}' — the options are name, unique`);
+    }
+  }
+  const resolved = expressionNode(expression, 'expressionIndex()', 0);
+  const out = {
+    name: options.name === undefined
+      ? expressionName(resolved)
+      : requireName(options.name, 'expressionIndex() name'),
+    expression: resolved,
+  };
+  if (options.unique !== undefined)
+    out.unique = requireJson(options.unique, 'expressionIndex() unique');
+  return Object.freeze(out);
+}
+
+/** The default name: `by_` + the outermost call and the members it
+ * reads, identifier-safe — the same stem the store's column takes.
+ * @param {any} node */
+function expressionName(node) {
+  const members = [];
+  const walk = (current) => {
+    if (current.member !== undefined) members.push(current.member);
+    else if (current.call !== undefined) current.args.forEach(walk);
+  };
+  walk(node);
+  const parts = [node.call ?? 'x', ...members.map((path) =>
+    path.replace(/^\$\.?/, '').replace(/[^A-Za-z0-9]+/g, '_'))];
+  return `by_${parts.join('_').replace(/^_+|_+$/g, '')}`;
+}
+
 /**
  * The key declaration: a pointer string, a captured member path, or
  * `null` (the store allocates; `identity` says how).

package/src/model/index.js

@@ -41,7 +41,7 @@ export const {
 /** The relation members: `rel.hasMany`, `rel.hasOne`, `rel.belongsToMany`. */
 export const rel = createRelations(EntityBuilder);
 
-export { collection, index } from './collection.js';
+export { collection, index, expressionIndex } from './collection.js';
 export { defineModel } from './define.js';
 export { withEntity } from './entity.js';
 export { isSchemaBuilder, schemaOf, SCHEMA_BUILDER } from '../schema/brand.js';

package/types/contract.d.ts

@@ -7,8 +7,9 @@
  * 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.
+ * 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
@@ -215,6 +216,13 @@ export type SubscribableOf<C> = Simplify<{
   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
@@ -249,36 +257,104 @@ export type Failure = {
   retryable: boolean | null;
 };
 
-/** The per-request context a server binding hands a handler. */
-export interface HandlerContext {
+/** 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;
-  method: string;
-  path: string;
-  params: Readonly<Record<string, string>>;
+  host: Host;
   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;
+}
+
+/** 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;
 }
 
-/** What `client.subscribe` takes (§19); every callback is optional. */
+/** 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: { seq: number; resumed: boolean }): void;
+  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 (§19). */
+/** 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 ———
@@ -303,11 +379,25 @@ export interface TypedClient<C> {
   close(): void;
 }
 
-/** The handler table of a server binding, one handler per invokable operation. */
-export type TypedHandlerTable<C> = {
+/** 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,
+    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>;
@@ -360,10 +450,17 @@ export function defineContract<O extends Record<string, AnyOperation | ({
 /** 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. */
-export function typedHandlers<C extends Contract<any>>(
-  contract: C, handlers: TypedHandlerTable<C>): TypedHandlerTable<C>;
+ * 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. */