iterate 0.2.7 → 0.4.0

package/dist/client/react.d.ts

@@ -0,0 +1,77 @@
+import type { SubscriptionListEntry } from "../api.ts";
+import type { StreamEvent } from "../stream/processor.ts";
+import { type LiveStateItx, type LiveStateSeed } from "./live-state.ts";
+export type LiveStateStatus = "connecting" | "live" | "error";
+/** One live state as a component reads it: the latest value (undefined until the first seed lands),
+ *  the revision it is at, whether its subscription is connecting, live or failed, and the failure. */
+export type LiveStateResult<S = unknown> = {
+    value: S | undefined;
+    rev: number | null;
+    status: LiveStateStatus;
+    error?: string;
+};
+/** Subscribe to a producer's live state and render its latest value. Pass a ready `itx` (a capnweb
+ *  `api.authenticate(credentials).user` or `.projects.get(id)`), the producer's `key`, and a `readSeed`
+ *  thunk that reads `{rev, state}` (`() => itx.invoke("itx.facets.get('slug').liveSnapshot()")`).
+ *  Re-subscribes when the session, `key`, or `name` changes; unmount (and every re-subscribe)
+ *  disposes the previous server-side subscription. */
+export declare function useLiveState<S>(itx: LiveStateItx | undefined, opts: {
+    key: string;
+    name?: string;
+    readSeed: () => Promise<LiveStateSeed<S>>;
+}): LiveStateResult<S>;
+/** One presence: who acted on the context and when last, from the log's stamps. */
+export type IterateContextPresence = {
+    actor: string;
+    email?: string;
+    grant?: string;
+    lastSeenAt: string;
+};
+/** The slice of a context handle `useIterateContext` reads — a capnweb `IterateContextApi` stub
+ *  satisfies it structurally. `invoke` seeds a named facet's live state
+ *  (`itx.facets.get('<name>').liveSnapshot()`, as an expression). */
+export type IterateContextHandle = LiveStateItx & {
+    readEvents(afterOffset?: number, limit?: number): Promise<{
+        events: unknown[];
+        atHead: boolean;
+        scannedThroughOffset: number;
+    }>;
+    processors: {
+        list(): Promise<SubscriptionListEntry[]> | SubscriptionListEntry[];
+    };
+    rpcStubs: {
+        list(): Promise<string[]> | string[];
+    };
+    invoke(call: string): Promise<unknown>;
+};
+/** THE ITERATE CONTEXT, live — one hook, one stream subscription. THE LOG: subscribe to every
+ *  committed event (or `consumes`) BEFORE the catch-up read, so nothing lands between the two;
+ *  pushes and pages both dedupe into one map by offset; `caughtUp` once the read reached the head;
+ *  `error` when the connect failed. Off that same log, THE PROCESSORS TABLE, re-read whenever the
+ *  log grows a row-changing event (a subscription configured, halted or resumed — the table is core
+ *  state, one call away, no push of its own), and WHO IS HERE: the rpc stubs lent right now
+ *  (`itx.rpcStubs.list()` — physical, re-read at every new head, since presence changes are
+ *  ephemeral facts) and, from the log, every principal that acted, newest first. And named facets'
+ *  LIVE STATE, each seeded through `itx.facets.get('<name>').liveSnapshot()` — one entry per name,
+ *  always. `liveState` OMITTED opens `core` (the core reduce answers under that name) plus every
+ *  hosted facet in the processors table the hook holds, following the table as it loads and changes;
+ *  `liveState` GIVEN is exactly the names to open, no implicit `core`. Re-connects when `itx`
+ *  changes; unmount disposes every server-side subscription. */
+export declare function useIterateContext(itx: IterateContextHandle | undefined, opts?: {
+    consumes?: string[];
+    liveState?: string[];
+}): {
+    events: StreamEvent[];
+    caughtUp: boolean;
+    error?: string;
+    processors: {
+        rows: SubscriptionListEntry[];
+        loaded: boolean;
+        error?: string;
+    };
+    presence: {
+        actors: IterateContextPresence[];
+        rpcStubs: string[];
+    };
+    liveState: Record<string, LiveStateResult>;
+};

package/dist/client/socket.d.ts

@@ -0,0 +1,7 @@
+export declare function openSocketWithRetry(url: string | URL, options?: {
+    delaysMs?: readonly number[];
+    handshakeTimeoutMs?: number;
+    /** the constructor to use — a test's fake, `WebSocket` otherwise */
+    WebSocket?: typeof WebSocket;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<WebSocket>;

package/dist/client.mjs

@@ -0,0 +1,156 @@
+import { applyPatch } from "./lib.mjs";
+import { z } from "zod";
+//#region src/client/live-state.ts
+/** The delta as it arrives over the wire — PARSED, never cast: `from`/`to` MUST be real numbers (a
+*  non-numeric rev would poison the held revision and silently wedge every later frame), and each
+*  patch op is a known RFC-6902-subset shape. A frame that fails this heals by re-reading the seed
+*  rather than being applied — the same recovery the store already runs on a revision gap. */
+const LiveStateDeltaMessage = z.object({
+	key: z.string(),
+	from: z.number(),
+	to: z.number(),
+	patch: z.array(z.union([
+		z.object({
+			op: z.literal("add"),
+			path: z.string(),
+			value: z.unknown()
+		}),
+		z.object({
+			op: z.literal("replace"),
+			path: z.string(),
+			value: z.unknown()
+		}),
+		z.object({
+			op: z.literal("remove"),
+			path: z.string()
+		})
+	])).nullable()
+});
+function createLiveStateStore() {
+	let held = {
+		rev: null,
+		state: void 0
+	};
+	const listeners = /* @__PURE__ */ new Set();
+	const notify = () => listeners.forEach((l) => l());
+	return {
+		get: () => held.state,
+		rev: () => held.rev,
+		subscribe: (listener) => {
+			listeners.add(listener);
+			return () => void listeners.delete(listener);
+		},
+		seed: (seed) => {
+			if (held.rev !== null && seed.rev < held.rev) return;
+			held = {
+				rev: seed.rev,
+				state: seed.state
+			};
+			notify();
+		},
+		apply: (delta, resync) => {
+			if (held.rev !== null && delta.to <= held.rev) return;
+			if (delta.from !== held.rev || !delta.patch) {
+				resync();
+				return;
+			}
+			held = {
+				rev: delta.to,
+				state: applyPatch(held.state, delta.patch)
+			};
+			notify();
+		}
+	};
+}
+/** Subscribe to a producer's live state and reduce it into a store. `readSeed` reads the seed
+*  (`itx.invoke("itx.facets.get('slug').liveSnapshot()")` for a processor, or a mini-app's
+*  own `state()` method). Subscribe happens BEFORE the first seed, so a delta racing the seed just
+*  triggers one seed re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped
+*  frames triggers one seed read, not one per frame); a failed heal is reported through `onResync`
+*  and retried by the next delivered delta (its `from` still mismatches, so it re-triggers). */
+async function connectLiveState(itx, opts) {
+	const store = createLiveStateStore();
+	let healing = false;
+	let healWantedAgain = false;
+	let disposed = false;
+	const reseed = () => {
+		if (disposed) return;
+		if (healing) {
+			healWantedAgain = true;
+			return;
+		}
+		healing = true;
+		const settled = () => {
+			healing = false;
+			if (disposed || !healWantedAgain) return;
+			healWantedAgain = false;
+			reseed();
+		};
+		opts.readSeed().then((s) => {
+			if (!disposed) {
+				store.seed(s);
+				opts.onResync?.("healed");
+			}
+			settled();
+		}, (e) => {
+			if (!disposed) opts.onResync?.(e instanceof Error ? e : new Error(String(e)));
+			settled();
+		});
+	};
+	const subscription = await itx.subscribe({
+		name: opts.name,
+		consumes: ["events.iterate.com/itx/live-state-changed"],
+		target: (events) => {
+			if (disposed) return;
+			for (const e of events) {
+				let parsed;
+				try {
+					parsed = LiveStateDeltaMessage.safeParse(JSON.parse(JSON.stringify(e.payload)));
+				} catch {
+					parsed = void 0;
+				}
+				if (!parsed?.success) {
+					reseed();
+					continue;
+				}
+				if (parsed.data.key !== opts.key) continue;
+				try {
+					store.apply(parsed.data, reseed);
+				} catch {
+					reseed();
+				}
+			}
+		}
+	});
+	try {
+		const seed = opts.readSeed();
+		const { signal } = opts;
+		const aborted = signal && new Promise((_, reject) => {
+			const abort = () => reject(signal.reason ?? /* @__PURE__ */ new Error("connectLiveState: aborted while the first seed was pending"));
+			if (signal.aborted) abort();
+			else signal.addEventListener("abort", abort, { once: true });
+		});
+		if (aborted) seed.catch(() => void 0);
+		store.seed(await (aborted ? Promise.race([seed, aborted]) : seed));
+	} catch (error) {
+		disposed = true;
+		try {
+			subscription[Symbol.dispose]();
+		} catch {}
+		throw error;
+	}
+	return {
+		store,
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			try {
+				subscription[Symbol.dispose]();
+			} catch {}
+		}
+	};
+}
+//#endregion
+export { connectLiveState, createLiveStateStore };
+
+//# sourceMappingURL=client.mjs.map

package/dist/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../src/client/live-state.ts"],"sourcesContent":["// client/live-state.ts — THE CLIENT HALF of live state (`iterate/client`), framework-free, for\n// browsers and node test clients. Two concepts:\n//   live state store  — `createLiveStateStore`: the pure reduce — seed from the producer, apply each delta, heal on a gap\n//   live state client — `connectLiveState`: wire an itx session's `subscribe` + a seed read to the store\n\nimport { z } from \"zod\";\nimport { applyPatch, type PatchOp } from \"../lib.ts\";\n\n// ── live state store ── THE CLIENT HALF of live state, for browsers and node test clients.\n// A deliberately small store for the platform's live-state wire:\n//\n//   • SEED from the producer — `{rev, state}` read via an RPC method (a processor's\n//     `liveSnapshot()`, a mini-app's `state()`).\n//   • APPLY each `{key, from, to, patch}` delta the subscription delivers: a patch lands only when\n//     its `from` matches the held rev; a mismatch means a missed delta (or a reborn producer's fresh\n//     epoch) — resync by re-reading the seed.\n//\n// The patch format is lib.ts (an RFC-6902 subset), so this store shares ONE applyPatch with\n// the producer — no second diff implementation. No capnweb import: a caller wires the transport and\n// hands deltas in, so the same store backs a node test client and the React hook (client/react.tsx).\n\n/** One live-state delta off the wire — the payload of an `events.iterate.com/itx/live-state-changed`\n *  ephemeral event, delivered raw to the subscriber. `patch: null` = the change was too large to\n *  send — the rev moved, re-read the seed. */\nexport type LiveStateDelta = { key: string; from: number; to: number; patch: PatchOp[] | null };\n\n/** The delta as it arrives over the wire — PARSED, never cast: `from`/`to` MUST be real numbers (a\n *  non-numeric rev would poison the held revision and silently wedge every later frame), and each\n *  patch op is a known RFC-6902-subset shape. A frame that fails this heals by re-reading the seed\n *  rather than being applied — the same recovery the store already runs on a revision gap. */\nconst LiveStateDeltaMessage: z.ZodType<LiveStateDelta> = z.object({\n  key: z.string(),\n  from: z.number(),\n  to: z.number(),\n  patch: z\n    .array(\n      z.union([\n        z.object({ op: z.literal(\"add\"), path: z.string(), value: z.unknown() }),\n        z.object({ op: z.literal(\"replace\"), path: z.string(), value: z.unknown() }),\n        z.object({ op: z.literal(\"remove\"), path: z.string() }),\n      ]),\n    )\n    .nullable(),\n});\n\n/** What the producer's seed read returns: the current revision paired with the current value. */\nexport type LiveStateSeed<S> = { rev: number; state: S };\n\nexport type LiveStateStore<S> = {\n  /** The current value, or undefined until the first seed lands. */\n  get(): S | undefined;\n  /** The held revision, or null before the first seed. */\n  rev(): number | null;\n  /** Subscribe to changes (for React's useSyncExternalStore, or a test's await-loop). */\n  subscribe(listener: () => void): () => void;\n  /** Seed (or re-seed) from a seed read — the first paint, and the heal after a gap. */\n  seed(seed: LiveStateSeed<S>): void;\n  /** Reduce one delta in; on a revision gap call `resync` and hold the value until a fresh seed. */\n  apply(delta: LiveStateDelta, resync: () => void): void;\n};\n\nexport function createLiveStateStore<S>(): LiveStateStore<S> {\n  // `rev: null` until the first seed lands.\n  let held: { rev: number | null; state: S | undefined } = { rev: null, state: undefined };\n  const listeners = new Set<() => void>();\n  const notify = () => listeners.forEach((l) => l());\n  return {\n    get: () => held.state,\n    rev: () => held.rev,\n    subscribe: (listener) => {\n      listeners.add(listener);\n      return () => void listeners.delete(listener);\n    },\n    seed: (seed) => {\n      // MONOTONIC: a late-resolving OLDER seed read must never move the store backwards past state\n      // deltas have already advanced (a delta-triggered resync can race the initial seed). Revisions\n      // are time-seeded epochs plus increments, so \"newer\" is numeric.\n      if (held.rev !== null && seed.rev < held.rev) return;\n      held = { rev: seed.rev, state: seed.state };\n      notify();\n    },\n    apply: (delta, resync) => {\n      // A delta at-or-behind the held rev is a duplicate/out-of-order frame — drop it silently.\n      // (Epochs are minted from the clock, so a reborn producer's fresh chain sits numerically above\n      // every rev an old chain handed out; a frame wholly behind us is genuinely old. The one\n      // exception is a clock that regressed across a producer rebirth — accepted: the next applied\n      // or gapped frame resyncs from a fresh seed anyway.)\n      if (held.rev !== null && delta.to <= held.rev) return;\n      // A gap (its `from` is not the held rev — including \"no seed yet\") means a missed delta or a\n      // reborn epoch, and a `null` patch means the change was too large to send — either way re-read\n      // the seed instead of applying onto a diverged base.\n      if (delta.from !== held.rev || !delta.patch) {\n        resync();\n        return;\n      }\n      held = { rev: delta.to, state: applyPatch(held.state as S, delta.patch) };\n      notify();\n    },\n  };\n}\n\n// ── live state client ── wire an itx session's `subscribe` + a seed read to a LiveStateStore.\n// This is the whole cleanroom client: a subscription that consumes the one live-state event type\n// (`itx.subscribe({ target, consumes: [\"events.iterate.com/itx/live-state-changed\"] })`) delivers every\n// key's deltas in batches; this filters the watched `key` and reduces each delta into the store; a\n// `readSeed` thunk reads `{rev, state}` for the first paint and every gap heal. Transport lives here so\n// the store above and the React hook stay pure.\n\n/** The slice of an itx session this needs — a capnweb `IterateContextRpcTarget` proxy satisfies it structurally:\n *  `subscribe` hands back a DISPOSABLE handle (disposing it removes the subscription server-side). */\nexport type LiveStateItx = {\n  subscribe(input: {\n    name?: string;\n    consumes?: string[];\n    target: (events: unknown[], range: unknown) => void;\n  }): Promise<{ [Symbol.dispose](): void }>;\n};\n\n/** A connected live-state subscription: the store rendering it, and the dispose that removes the\n *  server-side subscription (the handle's disposer; the session's end does the same). */\nexport type LiveStateConnection<S> = {\n  store: LiveStateStore<S>;\n  /** Unsubscribe on the server and stop reducing deltas. Safe to call more than once. */\n  dispose(): Promise<void>;\n};\n\n/** Subscribe to a producer's live state and reduce it into a store. `readSeed` reads the seed\n *  (`itx.invoke(\"itx.facets.get('slug').liveSnapshot()\")` for a processor, or a mini-app's\n *  own `state()` method). Subscribe happens BEFORE the first seed, so a delta racing the seed just\n *  triggers one seed re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped\n *  frames triggers one seed read, not one per frame); a failed heal is reported through `onResync`\n *  and retried by the next delivered delta (its `from` still mismatches, so it re-triggers). */\nexport async function connectLiveState<S>(\n  itx: LiveStateItx,\n  opts: {\n    key: string;\n    name?: string;\n    readSeed: () => Promise<LiveStateSeed<S>>;\n    /** Called after each gap heal attempt: \"healed\" on a fresh seed, the error when the seed read\n     *  failed (the store keeps its last value; the next delta retries). */\n    onResync?: (result: \"healed\" | Error) => void;\n    /** Abort while the FIRST seed is still pending (a component unmounting): the row just configured\n     *  is recalled and the connect rejects — a seed read that never answers leaves nothing lent. */\n    signal?: AbortSignal;\n  },\n): Promise<LiveStateConnection<S>> {\n  const store = createLiveStateStore<S>();\n  let healing = false;\n  let healWantedAgain = false; // a gap seen WHILE a heal was in flight: the seed may predate it\n  let disposed = false;\n  const reseed = () => {\n    if (disposed) return;\n    if (healing) {\n      healWantedAgain = true;\n      return;\n    }\n    healing = true;\n    const settled = () => {\n      healing = false;\n      if (disposed || !healWantedAgain) return;\n      healWantedAgain = false;\n      reseed();\n    };\n    void opts.readSeed().then(\n      (s) => {\n        if (!disposed) {\n          store.seed(s);\n          opts.onResync?.(\"healed\");\n        }\n        settled();\n      },\n      (e: unknown) => {\n        if (!disposed) opts.onResync?.(e instanceof Error ? e : new Error(String(e)));\n        settled();\n      },\n    );\n  };\n  const subscription = await itx.subscribe({\n    name: opts.name,\n    consumes: [\"events.iterate.com/itx/live-state-changed\"],\n    // A batch of live-state deltas (every key's); keep the watched key's.\n    target: (events: unknown[]) => {\n      if (disposed) return;\n      for (const e of events) {\n        // capnweb hands each event as a live proxy value — deep-copy to a plain object, then PARSE\n        // the frame (never cast network data). The whole decode is guarded: an ABSENT payload makes\n        // `JSON.parse(JSON.stringify(undefined))` throw before validation, and any throw here would\n        // skip every later delta in the batch. A malformed OR undecodable frame heals from a fresh seed\n        // instead of poisoning the held rev or escaping this callback.\n        let parsed: ReturnType<(typeof LiveStateDeltaMessage)[\"safeParse\"]> | undefined;\n        try {\n          parsed = LiveStateDeltaMessage.safeParse(\n            JSON.parse(JSON.stringify((e as { payload: unknown }).payload)),\n          );\n        } catch {\n          parsed = undefined;\n        }\n        if (!parsed?.success) {\n          reseed();\n          continue;\n        }\n        if (parsed.data.key !== opts.key) continue;\n        // `store.apply` runs `applyPatch`, which THROWS on a patch it refuses (a `/__proto__` path a\n        // legitimate state with an own `__proto__` key produces, say). Contain it per frame: heal from\n        // a fresh seed — which re-seeds the state DIRECTLY, no patch to reject — instead of escaping this\n        // callback and skipping every later frame.\n        try {\n          store.apply(parsed.data, reseed);\n        } catch {\n          reseed();\n        }\n      }\n    },\n  });\n  try {\n    const seed = opts.readSeed();\n    const { signal } = opts;\n    const aborted =\n      signal &&\n      new Promise<never>((_, reject) => {\n        const abort = () =>\n          reject(\n            signal.reason ??\n              new Error(\"connectLiveState: aborted while the first seed was pending\"),\n          );\n        if (signal.aborted) abort();\n        else signal.addEventListener(\"abort\", abort, { once: true });\n      });\n    if (aborted) seed.catch(() => undefined); // the seed read may still settle after the abort — quietly\n    store.seed(await (aborted ? Promise.race([seed, aborted]) : seed));\n  } catch (error) {\n    // The seed failed after the row was configured: recall it, or the server keeps delivering to a\n    // callback no one holds (and the session's other rows wait behind it).\n    disposed = true;\n    try {\n      subscription[Symbol.dispose]();\n    } catch {\n      // a dead session has already removed it\n    }\n    throw error;\n  }\n  return {\n    store,\n    async dispose() {\n      if (disposed) return;\n      disposed = true;\n      try {\n        subscription[Symbol.dispose](); // the server removes the row and recalls the lent callback\n      } catch {\n        // a dead session has already removed it — the socket close disposed every handle\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/expression.d.ts

@@ -0,0 +1,88 @@
+import { RpcTarget } from "capnweb";
+/** One step: a property read (string) or a call (`[method, ...args]`). Args are plain JSON. The
+ *  method `""` is the ANONYMOUS call — call the value itself: `itx.builtins.rpcStubs.get('cam')(1, 2)`
+ *  is `["itx","builtins","rpcStubs",["get","cam"],["",1,2]]` — what a `provide(stub)` rule spells when
+ *  the lent stub is called with args. */
+export type ItxExpressionStep = string | [method: string, ...args: unknown[]];
+/** An itx expression as data: the scope root (`itx`) then get/call steps. THE parsed form every
+ *  dispatching method works on. */
+export type ItxExpression = ItxExpressionStep[];
+/** THE dispatch target, in EITHER codec half — a dotted string that starts with the scope root
+ *  (`"itx.facets.get('core')"`) OR the parsed structured form (`["itx","facets",["get","core"]]`).
+ *  Both carry call args (the string via `.method(args)`), and `normalizedItxExpression` normalizes
+ *  either to the structured form — so either works wherever one works, in every method that dispatches. */
+export type ItxExpressionInput = string | ItxExpression;
+/** An itx-expression PREFIX — a rewrite rule's `match`: dotted names, any of which may be a call step
+ *  PINNING literal args — `itx.ai.run` or `itx.ai.run('gpt-5')` or `itx.repo.get('main').files`. A
+ *  pinned arg must equal the call's arg at that position for the rule to match, and is CONSUMED by
+ *  the match (partial application): `itx.ai.run('gpt-5') ⇒ itx.openai.chat` makes
+ *  `itx.ai.run('gpt-5', inputs)` into `itx.openai.chat(inputs)`. */
+export type ItxExpressionPrefix = ItxExpression;
+/** The name a step carries: the property itself, or a call step's method. */
+export declare const itxExpressionStepName: (step: ItxExpressionStep | undefined) => string | undefined;
+/** The merge entry's key — `...@` — read by apps/os `fillItxExpressionHoles`. */
+export declare const ITX_EXPRESSION_MERGE_KEY = "...@";
+/** Is `value` the marker literal `{ "@": true }`? */
+export declare const isItxExpressionHole: (value: unknown) => boolean;
+/** Does `value` (a step, an arg tree, a whole expression) hold the marker or a merge entry anywhere? */
+export declare function containsItxExpressionHole(value: unknown): boolean;
+/** Parse the STRING half: dotted names + `.method(args)` calls (args JSON5-parsed); rejects reserved
+ *  names + bare scope calls. `holes: true` — a rewrite rule's TARGET only — lexes `@` / `...@` into
+ *  the marker literals; anywhere else a bare `@` is refused. */
+export declare function parse(source: string, options?: {
+    holes?: boolean;
+}): ItxExpression;
+/** THE ONE NORMALIZER: either half, normalized to the array half and checked — a string is
+ *  parsed (short by rule), an array is shape-checked in place. Every function that takes an
+ *  `ItxExpressionInput` (the edge `invoke`, the resolver, the event builders, the prefix parser
+ *  below) enters through it. */
+export declare function normalizedItxExpression(input: ItxExpressionInput, options?: {
+    holes?: boolean;
+}): ItxExpression;
+/** Object args print with their keys SORTED, so two spellings of one object are one canonical string
+ *  — one rewrite-rule row, one facet memo, one library connection memo (library.ts) — the way
+ *  `jsonEqual` already matches them. A `JSON.stringify` / `JSON5.stringify` replacer. */
+export declare const keySortedForPrint: (_key: string, value: unknown) => unknown;
+/** Canonical stored form: dotted path + `.method(args)` calls (args `JSON5.stringify`d, object keys
+ *  sorted). `holes: true` — a rewrite rule's TARGET only — spells the marker literals back as `@` /
+ *  `...@`, and `parse(print(e, { holes: true }), { holes: true })` round-trips; without it the
+ *  reserved literals print as the plain JSON5 they are, so a CALL that happens to carry `{ "@": true }`
+ *  as data round-trips through `parse` (no holes) unchanged — the resolve/invoke law holds for it. */
+export declare function print(expr: ItxExpression, options?: {
+    holes?: boolean;
+}): string;
+/** Parse an itx-expression prefix (either codec half) — `normalizedItxExpression` (so every step is
+ *  an identifier that is not reserved, in either half) plus the two refusals only a PREFIX has: the
+ *  anonymous call step (`f(x)(y)` — a prefix cannot call a result), and a call step with NO args,
+ *  which pins nothing and is the same prefix as the plain name: spell `itx.ai.run`. */
+export declare function parseItxExpressionPrefix(source: ItxExpressionInput): ItxExpressionPrefix;
+/** THE ONE canonical spelling of an itx-expression prefix — the rewrite-rule table's key, what a lent
+ *  stub is keyed by through `provide`'s sugar: parsed, then printed (dotted names; pinned args as JSON5
+ *  literals). */
+export declare function canonicalItxExpressionPrefix(source: ItxExpressionInput): string;
+/** Install the hop drawn in the header on a class's PROTOTYPE CHAIN, with the scope `root` (`["itx"]`
+ *  for the edge context, `[]` for a handle). Call ONCE per class. Constructor inheritance is
+ *  untouched — only `Class.prototype`'s parent link changes, and the hop forwards everything it does
+ *  not intercept. */
+export declare function installPrototypeInvokeFallback<T extends abstract new (...args: never[]) => object>(cls: T, root: readonly string[]): void;
+/** A branded, pipelinable handle for a MID-CHAIN capability (`facets.get(name)`, `cd(path)`,
+ *  `workers.get(spec)`, a lent stub) whose unknown dotted members reduce into ONE dispatch of the
+ *  itx-expression STEPS relative to it; the constructor's `dispatch` routes those steps into the
+ *  underlying object. Declared members (`invoke` / `applyRoot`) win over the fallback, so a
+ *  capability cannot be named either — the two reserved words this wrapper adds. */
+export declare class InvokeHandle extends RpcTarget {
+    #private;
+    constructor(dispatchItxExpressionSteps: (itxExpressionSteps: ItxExpression) => unknown);
+    /** THE dispatch method the prototype hop reduces onto; the expression is RELATIVE to this handle. */
+    invoke(itxExpressionSteps: ItxExpression): unknown;
+    /** Call the bare capability this handle fronts — the ANONYMOUS call step (how a rewritten call
+     *  whose target IS a handle calls it: `handle(events, range)`). */
+    applyRoot(args: unknown[]): unknown;
+}
+/** Walk itx-expression steps off a capnweb stub; the ANONYMOUS call step (`""`) calls the value
+ *  itself (a bare function lent as a capability). NO await inside the loop: on a capnweb stub every
+ *  step is a PIPELINED path, so an n-step chain costs ONE round trip, flushed by the caller's single
+ *  await. A DIRECT call on the stub, never `.apply`: reading `.apply` off a capnweb stub's method is
+ *  itself a pipelined remote path, and calling it sends the stub as an argument, which a facet stub
+ *  refuses with a DataCloneError. What a connector over a lent stub or a remote capnweb API walks. */
+export declare function walkStepsOnRpcStub(stub: unknown, steps: ItxExpression): unknown;

package/dist/expression.mjs

@@ -0,0 +1,301 @@
+import { codedError, jsonEqual } from "./lib.mjs";
+import { RpcTarget } from "capnweb";
+import JSON5 from "json5";
+//#region src/expression.ts
+/** A STRING expression is for what a person types: short. Anything bigger — a worker's source, a large
+*  literal — rides the PARSED form (`["itx","workers",["get",{ source }]]`), which is plain data and never
+*  meets json5. The cap is O(1), before any parsing (stock json5 allocates per character and a
+*  multi-megabyte literal kills a 128 MiB isolate). */
+const ITX_EXPRESSION_STRING_MAX_CHARS = 2048;
+/** The name a step carries: the property itself, or a call step's method. */
+const itxExpressionStepName = (step) => Array.isArray(step) ? step[0] : step;
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$-]*/;
+const RESERVED = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/** The marker's array-half spelling, the one reserved literal. */
+const ITX_EXPRESSION_HOLE = { "@": true };
+/** The merge entry's key — `...@` — read by apps/os `fillItxExpressionHoles`. */
+const ITX_EXPRESSION_MERGE_KEY = "...@";
+/** A single- or double-quoted string literal (escapes honored) or a JSON5 comment (block or line):
+*  THE one pattern every walk that must skip what is inside them is built from — the marker lex, the
+*  marker print, the paren matcher. In an alternation a span is consumed whole, so nothing inside one
+*  (a quote in a comment, an `@` in a string) is ever seen by the other alternatives. */
+const STRING_OR_COMMENT = String.raw`"(?:[^"\\]|\\[\s\S])*"|'(?:[^'\\]|\\[\s\S])*'|/\*[\s\S]*?\*/|//[^\n]*`;
+const isStringOrComment = (match) => match[0] === "\"" || match[0] === "'" || match[0] === "/";
+/** In call args: a literal (kept verbatim) or a marker — `...@` before `@`, so the merge form wins. */
+const MARKERS_IN_ARGS = new RegExp(`${STRING_OR_COMMENT}|\\.\\.\\.@|@`, "g");
+/** In JSON5's printed output: the marker literal `{'@':true}` and the merge entry `'...@':true` are
+*  spelled with a single-quoted key and matched on those exact boundaries — listed BEFORE the literal
+*  alternative so the entry's `'...@'` is read as the entry, not as a string. A user's string that
+*  merely contains those characters is emitted by JSON5 as a longer (double-quoted) literal and is
+*  consumed whole. */
+const MARKERS_IN_PRINT = new RegExp(`\\{'@':true\\}|'\\.\\.\\.@':true|${STRING_OR_COMMENT}`, "g");
+/** A bracket outside a literal. */
+const BRACKETS = new RegExp(`${STRING_OR_COMMENT}|[()[\\]{}]`, "g");
+/** Is `value` the marker literal `{ "@": true }`? */
+const isItxExpressionHole = (value) => jsonEqual(value, ITX_EXPRESSION_HOLE);
+/** Does `value` (a step, an arg tree, a whole expression) hold the marker or a merge entry anywhere? */
+function containsItxExpressionHole(value) {
+	if (isItxExpressionHole(value)) return true;
+	if (Array.isArray(value)) return value.some(containsItxExpressionHole);
+	if (value !== null && typeof value === "object") return value["...@"] === true || Object.values(value).some(containsItxExpressionHole);
+	return false;
+}
+/** Index of the `)` closing the `(` at `open`; tracks bracket depth, skipping quoted string args. */
+function matchingParen(source, open) {
+	let depth = 0;
+	BRACKETS.lastIndex = open;
+	for (let bracket = BRACKETS.exec(source); bracket; bracket = BRACKETS.exec(source)) {
+		if (isStringOrComment(bracket[0])) continue;
+		if ("([{".includes(bracket[0])) depth++;
+		else if (--depth === 0) return bracket.index;
+	}
+	throw new Error(`expression: unbalanced "(" in ${JSON.stringify(source)}`);
+}
+/** Parse the STRING half: dotted names + `.method(args)` calls (args JSON5-parsed); rejects reserved
+*  names + bare scope calls. `holes: true` — a rewrite rule's TARGET only — lexes `@` / `...@` into
+*  the marker literals; anywhere else a bare `@` is refused. */
+function parse(source, options) {
+	if (source.length > ITX_EXPRESSION_STRING_MAX_CHARS) throw codedError("EXPRESSION_TOO_LONG", `itx expression: ${source.length} chars is over the ${ITX_EXPRESSION_STRING_MAX_CHARS}-char limit for the string form — a string expression is for what a person types; pass the parsed form instead: ["itx","workers",["get",{ source: … }]]`);
+	const s = source.trim();
+	const steps = [];
+	let i = 0;
+	function fail(m) {
+		throw new Error(`expression: ${m} in ${JSON.stringify(source)}`);
+	}
+	const readName = () => {
+		const m = IDENT.exec(s.slice(i));
+		if (!m) fail(`name expected at ${i}`);
+		if (RESERVED.has(m[0])) fail(`reserved name "${m[0]}"`);
+		i += m[0].length;
+		return m[0];
+	};
+	steps.push(readName());
+	while (i < s.length) {
+		const c = s[i];
+		if (/\s/.test(c)) i++;
+		else if (c === ".") steps.push((i++, readName()));
+		else if (c === "(") {
+			const end = matchingParen(s, i);
+			const inner = s.slice(i + 1, end).trim().replace(MARKERS_IN_ARGS, (match) => {
+				if (isStringOrComment(match)) return match;
+				if (!options?.holes) fail("`@` (the caller's input) is legal only in a rewrite rule's target");
+				return match === "@" ? JSON.stringify(ITX_EXPRESSION_HOLE) : `${JSON.stringify(ITX_EXPRESSION_MERGE_KEY)}:true`;
+			});
+			let args = [];
+			try {
+				if (inner !== "") args = JSON5.parse(`[${inner}]`);
+			} catch (e) {
+				fail(`call args are not JSON5 (${e.message})`);
+			}
+			const previous = steps.at(-1);
+			if (Array.isArray(previous)) steps.push(["", ...args]);
+			else {
+				const name = steps.pop();
+				if (typeof name !== "string") fail("a call must follow a name");
+				if (steps.length === 0) fail("cannot call the scope symbol itself");
+				steps.push([name, ...args]);
+			}
+			i = end + 1;
+		} else fail(`unexpected ${JSON.stringify(c)} at ${i}`);
+	}
+	return steps;
+}
+/** The array half, checked the way the parser checks the string half — every name step an identifier
+*  that is not reserved, every call step `[method, ...args]` with an identifier method (or `""`, the
+*  anonymous call, only right after a call) — WITHOUT printing and re-parsing: a stored target carries a worker's whole source as
+*  data, and that data must never meet the string codec (the 2 KiB cap, json5). Throws in the
+*  parser's words. */
+function assertItxExpressionShape(expression) {
+	const fail = (m) => {
+		throw new Error(`expression: ${m} in ${JSON.stringify(expression).slice(0, 200)}`);
+	};
+	if (!Array.isArray(expression) || expression.length === 0) fail("an expression is a non-empty array");
+	const name = (step, what) => {
+		if (!IDENT.test(step) || IDENT.exec(step)[0] !== step) fail(`${what} ${JSON.stringify(step)} is not an identifier`);
+		if (RESERVED.has(step)) fail(`reserved name "${step}"`);
+	};
+	expression.forEach((step, i) => {
+		if (typeof step === "string") {
+			name(step, i === 0 ? "the root" : "a name step");
+			return;
+		}
+		if (!Array.isArray(step) || typeof step[0] !== "string") fail(`step ${i} is neither a name nor [method, ...args]`);
+		const [method] = step;
+		if (method === "") {
+			if (i === 0 || !Array.isArray(expression[i - 1])) fail("the anonymous call `f(x)(y)` follows a call");
+		} else name(method, "a method");
+		if (i === 0) fail("a call on the root itself");
+	});
+}
+/** THE ONE NORMALIZER: either half, normalized to the array half and checked — a string is
+*  parsed (short by rule), an array is shape-checked in place. Every function that takes an
+*  `ItxExpressionInput` (the edge `invoke`, the resolver, the event builders, the prefix parser
+*  below) enters through it. */
+function normalizedItxExpression(input, options) {
+	if (typeof input === "string") return parse(input, options);
+	assertItxExpressionShape(input);
+	return input;
+}
+/** Object args print with their keys SORTED, so two spellings of one object are one canonical string
+*  — one rewrite-rule row, one facet memo, one library connection memo (library.ts) — the way
+*  `jsonEqual` already matches them. A `JSON.stringify` / `JSON5.stringify` replacer. */
+const keySortedForPrint = (_key, value) => value !== null && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort().map((k) => [k, value[k]])) : value;
+/** Canonical stored form: dotted path + `.method(args)` calls (args `JSON5.stringify`d, object keys
+*  sorted). `holes: true` — a rewrite rule's TARGET only — spells the marker literals back as `@` /
+*  `...@`, and `parse(print(e, { holes: true }), { holes: true })` round-trips; without it the
+*  reserved literals print as the plain JSON5 they are, so a CALL that happens to carry `{ "@": true }`
+*  as data round-trips through `parse` (no holes) unchanged — the resolve/invoke law holds for it. */
+function print(expr, options) {
+	return expr.map((step, i) => {
+		const dot = i ? "." : "";
+		if (typeof step === "string") return dot + step;
+		const json = JSON5.stringify(step.slice(1), keySortedForPrint).slice(1, -1);
+		const args = options?.holes ? json.replace(MARKERS_IN_PRINT, (match) => match === "{'@':true}" ? "@" : match === "'...@':true" ? "...@" : match) : json;
+		return step[0] === "" ? `(${args})` : `${dot}${step[0]}(${args})`;
+	}).join("");
+}
+/** Parse an itx-expression prefix (either codec half) — `normalizedItxExpression` (so every step is
+*  an identifier that is not reserved, in either half) plus the two refusals only a PREFIX has: the
+*  anonymous call step (`f(x)(y)` — a prefix cannot call a result), and a call step with NO args,
+*  which pins nothing and is the same prefix as the plain name: spell `itx.ai.run`. */
+function parseItxExpressionPrefix(source) {
+	const expr = normalizedItxExpression(source);
+	const spelled = typeof source === "string" ? source : print(expr);
+	for (const step of expr) {
+		if (!Array.isArray(step)) continue;
+		if (step[0] === "") throw new Error(`an itx-expression prefix cannot call a result — ${JSON.stringify(spelled)}`);
+		if (step.length === 1) throw new Error(`an itx-expression prefix pins literal args with a call step — ${JSON.stringify(spelled)} has "${step[0]}()" with none; spell "${step[0]}"`);
+	}
+	return expr;
+}
+/** THE ONE canonical spelling of an itx-expression prefix — the rewrite-rule table's key, what a lent
+*  stub is keyed by through `provide`'s sugar: parsed, then printed (dotted names; pinned args as JSON5
+*  literals). */
+function canonicalItxExpressionPrefix(source) {
+	return print(parseItxExpressionPrefix(source));
+}
+/** Names that must NEVER become dynamic capability segments — a dispatcher answering them would turn
+*  a plain property probe into a live capability call. Enforced at the prototype-chain hop and at
+*  every depth of the path proxies it hands out. Two kinds, one set: */
+const RESERVED_SEGMENT_NAMES = new Set([
+	"__defineGetter__",
+	"__defineSetter__",
+	"__lookupGetter__",
+	"__lookupSetter__",
+	"__proto__",
+	"apply",
+	"bind",
+	"call",
+	"catch",
+	"constructor",
+	"dup",
+	"finally",
+	"hasOwnProperty",
+	"isPrototypeOf",
+	"map",
+	"onRpcBroken",
+	"propertyIsEnumerable",
+	"prototype",
+	"then",
+	"toLocaleString",
+	"toString",
+	"valueOf",
+	"toJSON",
+	"asymmetricMatch"
+]);
+/** The path proxy: a function-backed Proxy (not an RpcTarget instance) — each missing property
+*  extends `path`, and applying the function reduces the whole accumulated access into ONE
+*  `invoke(expression)` call, `[...root, ...path.slice(0, -1), [path.at(-1), ...args]]`. */
+function createItxExpressionPathProxy(invoker, root, path) {
+	const valueFor = (key) => createItxExpressionPathProxy(invoker, root, [...path, key]);
+	return new Proxy(function() {}, {
+		apply(_target, _thisArg, args) {
+			const method = path[path.length - 1];
+			const expr = [
+				...root,
+				...path.slice(0, -1),
+				[method, ...args]
+			];
+			return invoker.invoke(expr);
+		},
+		get(target, key, receiver) {
+			if (typeof key === "symbol") return Reflect.get(target, key, receiver);
+			if (RESERVED_SEGMENT_NAMES.has(key)) return void 0;
+			return valueFor(key);
+		},
+		getOwnPropertyDescriptor(target, key) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(target, key);
+			if (descriptor) return descriptor;
+			if (typeof key === "symbol" || RESERVED_SEGMENT_NAMES.has(key)) return void 0;
+			return {
+				configurable: true,
+				enumerable: true,
+				value: valueFor(key),
+				writable: false
+			};
+		},
+		has(target, key) {
+			if (typeof key === "symbol") return key in target;
+			return !RESERVED_SEGMENT_NAMES.has(key);
+		}
+	});
+}
+/** Install the hop drawn in the header on a class's PROTOTYPE CHAIN, with the scope `root` (`["itx"]`
+*  for the edge context, `[]` for a handle). Call ONCE per class. Constructor inheritance is
+*  untouched — only `Class.prototype`'s parent link changes, and the hop forwards everything it does
+*  not intercept. */
+function installPrototypeInvokeFallback(cls, root) {
+	const parentPrototype = Object.getPrototypeOf(cls.prototype);
+	const hop = new Proxy(Object.create(parentPrototype), { get(hopTarget, key, receiver) {
+		if (typeof key === "symbol" || key in hopTarget) return Reflect.get(hopTarget, key, receiver);
+		if (RESERVED_SEGMENT_NAMES.has(key)) return void 0;
+		if (!(receiver instanceof cls)) return;
+		return createItxExpressionPathProxy(receiver, root, [key]);
+	} });
+	Object.setPrototypeOf(cls.prototype, hop);
+}
+/** A branded, pipelinable handle for a MID-CHAIN capability (`facets.get(name)`, `cd(path)`,
+*  `workers.get(spec)`, a lent stub) whose unknown dotted members reduce into ONE dispatch of the
+*  itx-expression STEPS relative to it; the constructor's `dispatch` routes those steps into the
+*  underlying object. Declared members (`invoke` / `applyRoot`) win over the fallback, so a
+*  capability cannot be named either — the two reserved words this wrapper adds. */
+var InvokeHandle = class extends RpcTarget {
+	#dispatchItxExpressionSteps;
+	constructor(dispatchItxExpressionSteps) {
+		super();
+		this.#dispatchItxExpressionSteps = dispatchItxExpressionSteps;
+	}
+	/** THE dispatch method the prototype hop reduces onto; the expression is RELATIVE to this handle. */
+	invoke(itxExpressionSteps) {
+		return this.#dispatchItxExpressionSteps(itxExpressionSteps);
+	}
+	/** Call the bare capability this handle fronts — the ANONYMOUS call step (how a rewritten call
+	*  whose target IS a handle calls it: `handle(events, range)`). */
+	applyRoot(args) {
+		return this.#dispatchItxExpressionSteps([["", ...args]]);
+	}
+};
+installPrototypeInvokeFallback(InvokeHandle, []);
+/** Walk itx-expression steps off a capnweb stub; the ANONYMOUS call step (`""`) calls the value
+*  itself (a bare function lent as a capability). NO await inside the loop: on a capnweb stub every
+*  step is a PIPELINED path, so an n-step chain costs ONE round trip, flushed by the caller's single
+*  await. A DIRECT call on the stub, never `.apply`: reading `.apply` off a capnweb stub's method is
+*  itself a pipelined remote path, and calling it sends the stub as an argument, which a facet stub
+*  refuses with a DataCloneError. What a connector over a lent stub or a remote capnweb API walks. */
+function walkStepsOnRpcStub(stub, steps) {
+	let value = stub;
+	for (const step of steps) if (typeof step === "string") value = value[step];
+	else {
+		const [method, ...args] = step;
+		value = method === "" ? value(...args) : value[method](...args);
+	}
+	return value;
+}
+//#endregion
+export { ITX_EXPRESSION_MERGE_KEY, InvokeHandle, canonicalItxExpressionPrefix, containsItxExpressionHole, installPrototypeInvokeFallback, isItxExpressionHole, itxExpressionStepName, keySortedForPrint, normalizedItxExpression, parse, parseItxExpressionPrefix, print, walkStepsOnRpcStub };
+
+//# sourceMappingURL=expression.mjs.map