iterate 0.2.6 → 0.3.0

package/dist/next/client/socket.d.ts

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

package/dist/next/client.mjs

@@ -0,0 +1,156 @@
+import { applyPatch } from "./lib.mjs";
+import { z } from "zod";
+//#region src/next/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 through the seed door
+*  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. `door` 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 door re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped
+*  frames triggers one door 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.door().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/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.door();
+		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/next/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../../src/next/client/live-state.ts"],"sourcesContent":["// client/live-state.ts — THE CLIENT HALF of live state (`iterate/next/client`), framework-free, for\n// browsers and node test clients. Two concepts:\n//   live state store  — `createLiveStateStore`: the pure reduce — seed through the door, apply each delta, heal on a gap\n//   live state client — `connectLiveState`: wire an itx session's `subscribe` + a seed door 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// Adapted from apps/os's `createLiveStateStore` (packages/iterate/src/sdk/capnweb/live-state), kept\n// deliberately tiny, and pointed at the CLEAN-ROOM wire instead of apps/os's in-band snapshot:\n//\n//   • SEED through the producer's door — `{rev, state}` read via an RPC method (a processor's\n//     `liveSnapshot()`, a mini-app's `state()`). apps/os reduces the first snapshot in-band on the\n//     subscription; here the stream keeps no per-subscriber state, so the seed is a separate read.\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 door, exactly like apps/os's revision-gap resync.\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/demo.tsx).\n\n/** One live-state delta off the wire — the payload of an `events.iterate.com/live-state/changed`\n *  ephemeral event, delivered raw to the subscriber. */\n/** `patch: null` = the change was too large to send — the rev moved, re-seed through the door. */\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 through the seed door\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 door 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 the door — 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 door 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 through the door 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 door 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 door 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/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// `door` thunk reads `{rev, state}` for the first paint and every gap heal. Transport lives here so\n// the store (client/live-state.ts) 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. `door` 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 door re-read — never a lost update. Gap heals are SINGLE-FLIGHT (a burst of gapped\n *  frames triggers one door 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    door: () => Promise<LiveStateSeed<S>>;\n    /** Called after each gap heal attempt: \"healed\" on a fresh seed, the error when the door 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 door 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.door().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/live-state/changed\"],\n    // A batch of live-state deltas (every key's); keep the watched key's. capnweb hands each event\n    // as a live proxy value — deep-copy to a plain object before reducing.\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 via the door\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 via\n        // the door — 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.door();\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 door 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/next/expression.d.ts

@@ -0,0 +1,146 @@
+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 door
+ *  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, at every door 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 rule 7. */
+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 NORMALIZING DOOR: either half, normalized to the array half and checked — a string is
+ *  parsed (short by rule), an array is shape-checked in place. Every door 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;
+/** Register a pipelinable promise brand (the workerd entrypoint's two calls at boot). */
+export declare function registerPipelinedRpcBrand(brand: abstract new (...args: never[]) => unknown): void;
+/**
+ * THE step walk: property steps `Reflect.get` with the receiver carried; call steps `Reflect.apply`
+ * ON that receiver (detaching a method from a Workers-RPC receiver breaks it); an ordinary promise
+ * is awaited between steps, a branded one (PIPELINED_RPC_BRANDS, above) is not.
+ *
+ * ⚠️  DataCloneError LEARNING:
+ * invoke facet/RPC-stub methods with `Reflect.apply(fn, receiver, args)`, NEVER `stub[m].apply(stub,
+ * args)`. Reading `.apply` off an RPC stub's method proxy is a capnweb PIPELINED REMOTE PATH;
+ * calling it passes the stub as an argument, so workerd serializes it — and a Worker-Loader facet
+ * stub may never be serialized (`requireAllowsTransfer()` throws unconditionally) → `DataCloneError:
+ * Durable Object Facet stubs cannot be transferred between Workers`. Do not "simplify" this away.
+ */
+export declare function walkSteps(start: {
+    value: unknown;
+    receiver: unknown;
+}, steps: ItxExpression): Promise<{
+    value: unknown;
+    receiver: unknown;
+}>;
+/** Apply `args` to a resolved value on its carried receiver, or a LOUD error if it is not callable
+ *  (never the silent arg-drop apps/os shipped). An `InvokeHandle` is NOT a JS function (a real
+ *  RpcTarget so dotted access pipelines — the invoke handle section), so ROOT-calling it dispatches
+ *  those args at its EMPTY path: `handle(events,range)` ⇒ the bare callback the handle fronts. The one
+ *  bridge between "callable capability" and "pipelinable RpcTarget". */
+export declare function callOn(value: unknown, receiver: unknown, args: unknown[]): Promise<unknown>;
+/** 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 reduce door the prototype hop dispatches onto; the expression is RELATIVE to this handle. */
+    invoke(itxExpressionSteps: ItxExpression): unknown;
+    /** Call the bare capability this handle fronts — the ANONYMOUS call step (`callOn` in the dispatch section
+     *  uses it when a rewritten call's target IS a handle: `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 (`walkSteps`'s DataCloneError learning). Exported for the library
+ *  tier, which may import this module only. */
+export declare function walkStepsOnRpcStub(stub: unknown, steps: ItxExpression): unknown;
+/** `itx.facets.get(name)` / `itx.facets.get(name, { source, className })` — a facet of this context. */
+export declare class FacetHandle extends InvokeHandle {
+}
+/** A HANDLE ON THE WIRE IS THE EXPRESSION THAT NAMES IT. An `InvokeHandle` a context mints (`repos.get(path)`,
+ *  `workspaces.get(path)`, `facets.get(name)`, `cd(path)`, `workers.get(spec)`) holds no state — it is a
+ *  dispatch closure over a path — yet as a Workers-RPC result it would cross a hop as a LIVE stub whose
+ *  session keeps the context's actor resident for as long as the holder keeps it (prd 2026-09-22: ~125
+ *  such sessions parked around the clock). So the context's RPC door answers with THIS instead: the
+ *  caller's own expression, which from the caller's root denotes the same handle; the caller mints its
+ *  own handle over it (`materializeItxHandleReference`), and every later verb is one whole call the
+ *  context resolves from scratch. Nothing outlives a call. A lent client stub (`RpcStubHandle`) is the
+ *  one handle that IS live and crosses as itself. */
+export declare const ITX_HANDLE_REFERENCE_KEY = "$itxHandleExpression";
+export type ItxHandleReference = {
+    [ITX_HANDLE_REFERENCE_KEY]: ItxExpression;
+};
+export declare const isItxHandleReference: (value: unknown) => value is ItxHandleReference;
+/** What a context's RPC door hands back for `expression`'s result: a reference when the result is a
+ *  path-shaped handle (an `InvokeHandle` that is not a lent stub) or a reference from a hop below —
+ *  re-rooted, since `expression` is how THIS caller reached it — else nothing (the result crosses as it
+ *  is). Runtime args that fold into a terminal NAME fold here exactly as the resolver folds them, so the
+ *  reference is the call the resolver ran; args left over apply to the value and never name a handle. */
+export declare function itxHandleReferenceOf(result: unknown, expression: ItxExpression, args?: unknown[]): ItxHandleReference | undefined;
+/** The holder's side: a reference becomes a handle of the HOLDER's own whose every dotted call is one
+ *  whole expression through `invoke` — the reference's expression plus the steps. Anything else passes
+ *  through untouched. The proxy hands relative steps; a caller's own `.invoke("itx.whoami()")` is a
+ *  whole call, spelled from the root. */
+export declare function materializeItxHandleReference(result: unknown, invoke: (expression: ItxExpression) => unknown): unknown;
+/** `itx.rpcStubs.get(key)` — a live stub lent to the registry. */
+export declare class RpcStubHandle extends InvokeHandle {
+}