@graphrefly/ts 0.0.0 → 0.0.2

package/dist/types-BhveCMg5.d.cts

@@ -0,0 +1,274 @@
+import { DataIssue } from './data/index.cjs';
+import { N as Node } from './types-BS6CyR-x.cjs';
+import { L as LockId } from './messages-CAzUPPJM.cjs';
+
+interface MessageEnvelope<T = unknown> {
+    readonly topic: string;
+    readonly seq: number;
+    readonly payload: T;
+    readonly key?: string;
+    readonly idempotencyKey?: string;
+    readonly timestampMs: number;
+    readonly commandId?: string;
+}
+/** Minimal JSON Schema vocabulary for passive topic payload descriptions (D125/D132). */
+interface JsonSchema {
+    readonly type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | readonly ("string" | "number" | "integer" | "boolean" | "object" | "array" | "null")[];
+    readonly properties?: Readonly<Record<string, JsonSchema>>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean | JsonSchema;
+    readonly items?: JsonSchema | readonly JsonSchema[];
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly $ref?: string;
+    readonly definitions?: Readonly<Record<string, JsonSchema>>;
+    readonly description?: string;
+    readonly title?: string;
+}
+/** Passive envelope for payloads that cross topic, agent, or graph boundaries. */
+interface TopicMessage<T = unknown> {
+    readonly id: string;
+    readonly schema?: JsonSchema;
+    readonly expiresAt?: string;
+    readonly correlationId?: string;
+    readonly payload: T;
+}
+/** Passive domain event vocabulary for messageBus/eventFlow composition (D329). */
+interface EventMessage<T = unknown> {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: T;
+    readonly key?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly occurredAtMs?: number;
+    readonly actor?: string;
+    readonly evidenceRefs?: readonly string[];
+    readonly schema?: JsonSchema;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface EventMessageOptions {
+    readonly id: string;
+    readonly key?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly occurredAtMs?: number;
+    readonly actor?: string;
+    readonly evidenceRefs?: readonly string[];
+    readonly schema?: JsonSchema;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+declare const PROMPTS_TOPIC = "prompts";
+declare const RESPONSES_TOPIC = "responses";
+declare const INJECTIONS_TOPIC = "injections";
+declare const DEFERRED_TOPIC = "deferred";
+declare const SPAWNS_TOPIC = "spawns";
+declare const CONTEXT_TOPIC = "context";
+declare const TODOS_TOPIC = "todos";
+declare const STANDARD_TOPICS: readonly ["prompts", "responses", "injections", "deferred", "spawns", "context", "todos"];
+type StandardTopic = (typeof STANDARD_TOPICS)[number];
+type MessageBusTopicPolicy = "strict" | "create-as-fact";
+interface MessageBusRetentionPolicy {
+    /** Count retention. Trimming advances headSeq and never rewrites seq (D284). */
+    readonly maxMessages?: number;
+}
+interface MessageBusDedupePolicy {
+    /** Duplicate commandId emits status and never publishes a second retained message (D284). */
+    readonly commandId?: "status" | "issue";
+}
+interface MessageBusOptions<TTopic extends string = string> {
+    readonly topics?: readonly TTopic[];
+    readonly name?: string;
+    readonly now?: () => number;
+    readonly topicPolicy?: MessageBusTopicPolicy;
+    readonly retention?: MessageBusRetentionPolicy;
+    readonly dedupe?: MessageBusDedupePolicy;
+}
+type MessageBusCommand<T = unknown> = {
+    readonly kind: "ensure-topic";
+    readonly topic: string;
+    readonly commandId?: string;
+} | {
+    readonly kind: "close-topic";
+    readonly topic: string;
+    readonly commandId?: string;
+} | {
+    readonly kind: "publish";
+    readonly topic: string;
+    readonly payload: T;
+    readonly key?: string;
+    readonly commandId?: string;
+    readonly idempotencyKey?: string;
+} | {
+    readonly kind: "topic-policy";
+    readonly topicPolicy: MessageBusTopicPolicy;
+    readonly commandId?: string;
+} | {
+    readonly kind: "ack";
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly seq: number;
+    readonly commandId?: string;
+} | {
+    readonly kind: "seek";
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly nextSeq: number;
+    readonly commandId?: string;
+} | {
+    readonly kind: "close-subscription";
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly commandId?: string;
+};
+type MessageBusMessage<T = unknown> = MessageEnvelope<T>;
+interface MessageBusStatus {
+    readonly kind: "topic-created" | "topic-closed" | "message-published" | "retention-trimmed" | "duplicate-command" | "subscription-acked" | "subscription-sought" | "subscription-closed" | "command-rejected" | "projection-ready" | "projection-partial";
+    readonly topic?: string;
+    readonly seq?: number;
+    readonly headSeq?: number;
+    readonly subscriptionId?: string;
+    readonly nextSeq?: number;
+    readonly commandId?: string;
+    readonly issueCode?: string;
+    readonly timestampMs: number;
+    readonly details?: unknown;
+}
+interface MessageBusCatalogEntry {
+    readonly topic: string;
+    readonly closed: boolean;
+    readonly headSeq: number;
+    readonly nextSeq: number;
+    readonly messageCount: number;
+}
+interface MessageBusCatalogPage {
+    readonly topics: readonly MessageBusCatalogEntry[];
+    readonly nextAfterTopic?: string;
+    readonly hasMore: boolean;
+}
+interface MessageBusDeadLetterEntry<T = unknown> {
+    readonly entrySeq: number;
+    readonly topic?: string;
+    readonly command?: MessageBusCommand<T>;
+    readonly message?: MessageBusMessage<T>;
+    readonly issue: DataIssue;
+    readonly timestampMs: number;
+}
+interface MessageBusDeadLetterPage<T = unknown> {
+    readonly entries: readonly MessageBusDeadLetterEntry<T>[];
+    readonly nextAfterEntrySeq?: number;
+    readonly hasMore: boolean;
+}
+interface MessageBusTopicPage<T = unknown> {
+    readonly topic: string;
+    readonly messages: readonly MessageBusMessage<T>[];
+    readonly fromSeq: number;
+    readonly throughSeq?: number;
+    readonly nextAfterSeq?: number;
+    readonly hasMore: boolean;
+}
+interface MessageBusCursor {
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly nextSeq: number;
+    readonly closed: boolean;
+    readonly retentionGap: boolean;
+    readonly headSeq: number;
+}
+interface MessageBusAvailablePage<T = unknown> {
+    readonly topic: string;
+    readonly subscriptionId: string;
+    readonly cursor: MessageBusCursor;
+    readonly messages: readonly MessageBusMessage<T>[];
+    readonly fromSeq: number;
+    readonly throughSeq?: number;
+    readonly nextAfterSeq?: number;
+    readonly hasMore: boolean;
+}
+interface MessageBusPageParams {
+    readonly limit?: number;
+}
+interface MessageBusCatalogParams extends MessageBusPageParams {
+    readonly afterTopic?: string;
+    readonly includeClosed?: boolean;
+}
+interface MessageBusDeadLetterParams extends MessageBusPageParams {
+    readonly afterEntrySeq?: number;
+    readonly topic?: string;
+    readonly code?: string;
+}
+interface MessageBusTopicParams extends MessageBusPageParams {
+    readonly afterSeq?: number;
+}
+interface MessageBusAvailableParams extends MessageBusPageParams {
+    readonly afterSeq?: number;
+}
+interface MessageBusPullProjection<TPage> {
+    readonly snapshot: Node<TPage>;
+    readonly snapshotPullId: LockId;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+}
+interface MessageBusTopicProjection<T = unknown> extends MessageBusPullProjection<MessageBusTopicPage<T>> {
+}
+interface MessageBusSubscription<T = unknown> {
+    readonly available: Node<MessageBusAvailablePage<T>>;
+    readonly availablePullId: LockId;
+    readonly cursor: Node<MessageBusCursor>;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+    ack(seq: number, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    seek(nextSeq: number, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    close(opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+}
+interface MessageBus<TTopic extends string = string> {
+    readonly commands: Node<MessageBusCommand>;
+    readonly messages: Node<MessageBusMessage>;
+    readonly status: Node<MessageBusStatus>;
+    readonly issues: Node<DataIssue>;
+    ensureTopic(topic: TTopic | string, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    closeTopic(topic: TTopic | string, opts?: {
+        commandId?: string;
+    }): MessageBusCommand;
+    publish<T = unknown>(topic: TTopic | string, payload: T, opts?: {
+        key?: string;
+        commandId?: string;
+        idempotencyKey?: string;
+    }): MessageBusCommand<T>;
+    topic<T = unknown>(topic: TTopic | string, opts?: {
+        name?: string;
+    }): MessageBusTopicProjection<T>;
+    catalog(opts?: {
+        name?: string;
+    }): MessageBusPullProjection<MessageBusCatalogPage>;
+    deadLetter<T = unknown>(opts?: {
+        name?: string;
+    }): MessageBusPullProjection<MessageBusDeadLetterPage<T>>;
+    subscription<T = unknown>(opts: {
+        topic: TTopic | string;
+        subscriptionId: string;
+        from?: "earliest" | "latest" | number;
+        name?: string;
+    }): MessageBusSubscription<T>;
+}
+interface ToTopicOptions {
+    readonly name?: string;
+    readonly keyOf?: (value: unknown) => string | undefined;
+    readonly commandIdOf?: (value: unknown) => string | undefined;
+}
+interface ToTopicBundle<T> {
+    readonly commands: Node<MessageBusCommand<T>>;
+    release(): void;
+}
+
+export { type StandardTopic as A, TODOS_TOPIC as B, CONTEXT_TOPIC as C, DEFERRED_TOPIC as D, type EventMessage as E, type TopicMessage as F, INJECTIONS_TOPIC as I, type JsonSchema as J, type MessageBusMessage as M, PROMPTS_TOPIC as P, RESPONSES_TOPIC as R, SPAWNS_TOPIC as S, type ToTopicOptions as T, type MessageBusCommand as a, type MessageBusAvailablePage as b, type MessageEnvelope as c, type MessageBus as d, type EventMessageOptions as e, type MessageBusTopicPage as f, type MessageBusOptions as g, type ToTopicBundle as h, type MessageBusAvailableParams as i, type MessageBusCatalogEntry as j, type MessageBusCatalogPage as k, type MessageBusCatalogParams as l, type MessageBusCursor as m, type MessageBusDeadLetterEntry as n, type MessageBusDeadLetterPage as o, type MessageBusDeadLetterParams as p, type MessageBusDedupePolicy as q, type MessageBusPageParams as r, type MessageBusPullProjection as s, type MessageBusRetentionPolicy as t, type MessageBusStatus as u, type MessageBusSubscription as v, type MessageBusTopicParams as w, type MessageBusTopicPolicy as x, type MessageBusTopicProjection as y, STANDARD_TOPICS as z };

package/dist/{types-bNMSWKqF.d.cts → types-C9NOgNJw.d.ts}

@@ -1,4 +1,4 @@
-import { L as LockId, W as Wave, M as Message } from './messages-BZqrGGm1.cjs';
+import { L as LockId, W as Wave, P as PullDemand, M as Message } from './messages-CAzUPPJM.js';
 
 /**
  * Dispatcher, pools, and the pure-data Handle.
@@ -6,7 +6,7 @@ import { L as LockId, W as Wave, M as Message } from './messages-BZqrGGm1.cjs';
  * Canonical authority: ~/src/graphrefly/spec/rules.jsonl
  *   R-handle (D7), R-dispatch-all (D21), R-sync-core (D20/D21).
  *
- * Lifted from the validated handle-dispatch PoC (packages/pure-ts r8-poc, R8/R9):
+ * Lifted from the validated retired handle-dispatch PoC (R8/R9):
  * fn lives in an external pool, indexed by handle; `dispatcher.invoke` is uniformly
  * SYNC void — async/remote behavior lives in the fn body (it kicks off async work
  * and emits later via `ctx.down`), not in a different call mechanism.
@@ -290,21 +290,6 @@ type NodeVersionJson = NodeVersion;
  */
 declare function defaultNodeVersionHash(bytes: Uint8Array): string;
 
-/**
- * The node primitive — the thinnest substrate object (R-node-thin / D5).
- *
- * Holds a fn handle + deps + the wave state machine; ZERO inspection cruft
- * (naming/find/describe are the graph layer, CSP-2). Canonical authority:
- * ~/src/graphrefly/spec/rules.jsonl (R-node-*, R-two-phase, R-diamond, R-resolved-undirty,
- * R-first-run-gate, R-push-subscribe, R-rom-ram, R-fn-contract, R-initial, R-ctx-up).
- *
- * Slice 1 = core wave: state node, compute node, two-phase DIRTY->DATA, diamond
- * pending-counter join, first-run gate, substrate-synthesized undirty RESOLVED
- * (R-resolved-undirty / D49 — no equals-substitution; every occurrence is DATA),
- * push-on-subscribe, lazy activation, ROM/RAM. Lifecycle (terminal/INVALIDATE/cleanup),
- * control (PAUSE/async), batch, and dynamicNode land in later slices.
- */
-
 type Status = "sentinel" | "pending" | "dirty" | "settled" | "resolved" | "completed" | "errored";
 interface NodeOptions<T = unknown> {
     /** Pre-populate cache; source pushes [DATA, initial] on subscribe (R-initial). `null` is valid. */
@@ -324,19 +309,21 @@ interface NodeOptions<T = unknown> {
     /** PAUSE/RESUME behavior (R-pause-modes). Default true. */
     pausable?: boolean | "resumeAll";
     /**
-     * Pull-mode node (R-pull / D55,D59): a quiet-until-demanded source, identified by this
+     * Pull-mode node (R-pull / D269): a quiet-until-demanded source, identified by this
      * author-supplied `pullId` (a unique LockId — a `Symbol` recommended; NOT the node name, NOT a
-     * bare string which collides with a same-string pause lock). The node self-holds the pullId as
-     * its demand lock. QUIET by default: it ABSORBS an upstream DIRTY WITHOUT relaying it downstream
-     * (the wedge fix) and does NOT push-on-subscribe its cached value (START only). A DEMAND = a
-     * cone-routed `RESUME` of this pullId (R-up-routing — NO new message type): a downstream consumer
-     * issues `ctx.up([[RESUME, pullId]])` (broadcast up the declared cone) or `ctx.up(msgs, towardDep)`
-     * (directed) WITHOUT holding this node's reference; the RESUME travels up to the pullId-holder,
-     * which fires EXACTLY ONE delivery (DIRTY-before-DATA) then RE-QUIETS (1:1). Delivery content =
+     * bare string if callers may also use strings as pause locks). QUIET by default: it ABSORBS
+     * an upstream DIRTY WITHOUT relaying it downstream
+     * (the wedge fix) and does NOT push-on-subscribe its cached value (START only). A DEMAND =
+     * cone-routed `PULL({pullId, params?})`: a downstream consumer issues
+     * `ctx.up([["PULL", { pullId, params }]])` (broadcast up the declared cone) or
+     * `ctx.up(msgs, towardDep)` (directed) WITHOUT holding this node's reference; the PULL travels
+     * up to the pullId-holder, which fires EXACTLY ONE delivery (DIRTY-before-DATA when it emits)
+     * then RE-QUIETS (1:1). Delivery content =
      * the orthogonal `pausable` mode: `true` → coalesced LATEST (one DATA); `'resumeAll'` → buffered
      * BACKLOG. `pullId` + `pausable:false` is REJECTED at construction. A SELF-triggered demand (a
-     * consumer demanding a dep it ALSO reads) must defer via {@link Ctx.upNext} (R-rewire-deferred /
-     * D37). Author the pullId as a shared module const used at both this node and the demander's fn.
+     * consumer demanding a dep it ALSO reads) must defer via {@link import("../ctx/types.js").Ctx.upNext}
+     * (R-rewire-deferred / D37). Author the pullId as a shared module const used at both this node and
+     * the demander's fn.
      */
     pullId?: LockId;
     /** Buffer the last N outgoing DATA for late subscribers (R-replay-buffer). */
@@ -363,6 +350,22 @@ interface NodeOptions<T = unknown> {
      */
     factory?: string;
 }
+
+/**
+ * The node primitive — the thinnest substrate object (R-node-thin / D5).
+ *
+ * Holds a fn handle + deps + the wave state machine; ZERO inspection cruft
+ * (naming/find/describe are the graph layer, CSP-2). Canonical authority:
+ * ~/src/graphrefly/spec/rules.jsonl (R-node-*, R-two-phase, R-diamond, R-resolved-undirty,
+ * R-first-run-gate, R-push-subscribe, R-rom-ram, R-fn-contract, R-initial, R-ctx-up).
+ *
+ * Slice 1 = core wave: state node, compute node, two-phase DIRTY->DATA, diamond
+ * pending-counter join, first-run gate, substrate-synthesized undirty RESOLVED
+ * (R-resolved-undirty / D49 — no equals-substitution; every occurrence is DATA),
+ * push-on-subscribe, lazy activation, ROM/RAM. Lifecycle (terminal/INVALIDATE/cleanup),
+ * control (PAUSE/async), batch, and dynamicNode land in later slices.
+ */
+
 declare class Node<T = unknown> {
     private readonly _core;
     private readonly _id;
@@ -380,16 +383,16 @@ declare class Node<T = unknown> {
     private _released;
     private get _syncCtx();
     private set _syncCtx(value);
+    private static _retainIndirectRuntimeMethods;
     constructor(deps: Node<unknown>[], handleOrFn: Handle | NodeFn | null, opts?: NodeOptions<T>);
-    /** R-pull (D55): true while a pull node is quiet (holds its own pullId/demand lock). */
+    /** R-pull (D55/D272): true while a pull node is not serving a PULL demand pulse. */
     private _isPullQuiet;
     /**
-     * R-pull (D55/D59): this pull node's pullId (pure data, like {@link cache}/{@link handle} — never
-     * triggers computation). A consumer demands one delivery by cone-routing a RESUME of it (no node
-     * reference): `ctx.up([["RESUME", pullId]])` (immediate; loops back → D37 for a self-read dep) or
-     * `ctx.upNext([["RESUME", pullId]])` (boundary-deferred self-demand, R-up-routing/R-rewire-deferred).
-     * Undefined for a non-pull node. The author writes the pullId verbatim, so this getter is mainly
-     * for inspection/describe; routing matches by the pullId value carried in the RESUME, by identity.
+     * R-pull (D269/D272): this pull node's pullId (pure data, like {@link cache}/{@link handle} —
+     * never triggers computation). A consumer demands one delivery by cone-routing PULL of it (no
+     * node reference): `ctx.up([["PULL", { pullId }]])` (immediate; loops back → D37 for a self-read
+     * dep) or `ctx.upNext([["PULL", { pullId }]])` (boundary-deferred self-demand). Undefined for a
+     * non-pull node. The author writes the pullId verbatim; routing matches by identity.
      */
     get pullId(): LockId | undefined;
     get cache(): T | undefined;
@@ -421,23 +424,6 @@ declare class Node<T = unknown> {
      * ONE declared edge (R-up-routing directed-up); omitted = broadcast up all deps.
      */
     up(msgs: Wave, towardDep?: number): void;
-    /**
-     * Enqueue a deferred self-rewire op (issued from this node's fn via `ctx.rewireNext`).
-     * Applied at the committed wave boundary (boundary.ts drain), never in place — the in-fn
-     * immediate path (`subscribeDep`/`replaceDeps`/`unsubscribeDep`) still throws mid-run (D37/R-reentrancy).
-     */
-    private _requestRewireNext;
-    /**
-     * Enqueue a deferred up-going control wave (R-up-routing / R-pull / D59): at the committed wave
-     * boundary, route `msgs` up from THIS node (broadcast, or up the single `towardDep` edge). The
-     * deferred form of `ctx.up` — the SELF-demand path: a consumer issues `ctx.upNext([[RESUME,
-     * pullId]])` to demand a dep it ALSO reads; the demand applies at the boundary (not mid-fn), so
-     * the pull node's delivery loops back as a FRESH wave rather than re-entering the consumer (D37 /
-     * R-reentrancy). Rides the same R-rewire-deferred (D47) drain as ctx.rewireNext.
-     */
-    private _requestUpNext;
-    /** Apply one queued self-rewire at the boundary (drain thunk). */
-    private _applyRewireNext;
     /**
      * Replace this node's deps atomically (surgical, Option-C). Requires an explicit
      * `fn` (SD-1 fn-deps pairing — user fns read dep input positionally). Kept deps
@@ -450,57 +436,29 @@ declare class Node<T = unknown> {
     subscribeDep(depNode: Node<unknown>, fn: NodeFn): number;
     /** Unsubscribe from one dep (special case of replaceDeps); idempotent if absent (fn swap still applies). */
     unsubscribeDep(depNode: Node<unknown>, fn: NodeFn): void;
+    private _requestRewireNext;
+    private _requestUpNext;
+    private _applyRewireNext;
     private _dedupDeps;
-    /** Is `target` reachable upstream from `from` (following deps)? Cycle-prevention DFS. */
     private _reachableUpstream;
     private _assertRewireDepOwner;
     private _rewire;
     private _activate;
-    /**
-     * Subscribe to a dep. The dispatch callback reads the dep's CURRENT index from a
-     * mutable box (O(1)); a surgical rewire that reorders kept deps just updates the box
-     * (R-rewire Option-C / D42) — no re-subscribe, no per-message indexOf scan. A removed
-     * dep's box is set to -1 so any stale in-flight callback drops (drain).
-     */
-    private _subscribeDepAt;
-    private _seedRestoredDepAt;
     private _deactivate;
     private _assertNotReleased;
     private _subscriberCount;
     private _isRuntimeQuiescentForRelease;
     private _releaseRuntime;
     private _resetDepState;
+    private _subscribeDepAt;
+    private _seedRestoredDepAt;
     private _recordDepProjection;
     private _depProjectionHasData;
     private _receiveFromDep;
-    /**
-     * R-terminal-settles-dirty (B35): release a dep's outstanding in-wave DIRTY contribution.
-     * A settle-class event for that dep (DATA/RESOLVED inline above, INVALIDATE, and now
-     * COMPLETE/ERROR) clears its dirty flag + decrements _pending. No-op if the dep already
-     * settled this wave (DATA/RESOLVED ran first) — so the normal DATA-then-COMPLETE flow is
-     * unaffected. This makes the exactly-one-settle invariant a single, shared step.
-     */
     private _releaseDepDirty;
-    /**
-     * R-terminal-settles-dirty (B35): settle a node whose dirtied dep was released by an ABSORBED
-     * terminal that is NOT a real input (a plain derived/effect — the common default-node case when
-     * one of several deps completes while others stay live). Runs only when the release drained
-     * _pending while the node still owes a downstream settle (it broadcast DIRTY this wave):
-     *   - if some OTHER dep delivered real DATA this wave (a value occurred) → recompute (→ DATA);
-     *   - else the terminal's signalled change did not materialise (no value) → one undirty RESOLVED
-     *     (R-resolved-undirty), keeping the cache (a terminal, unlike INVALIDATE, leaves the value).
-     * A terminalAsRealInput node instead recomputes unconditionally (its fn reads the terminal).
-     */
     private _settleAfterAbsorbedTerminal;
     private _markDirty;
     private _maybeRun;
-    /**
-     * R-rewire atomic settle (after a rewire that warrants a recompute): emit a proper
-     * two-phase DIRTY→DATA wave (R-dirty-before-data — a rewire-triggered settle is a wave),
-     * once, with every added dep already wired. Mirrors _maybeRun/_tryRun's pause + gate +
-     * pending guards, then injects the phase-1 DIRTY the added dep's [START,DATA] handshake
-     * did not carry.
-     */
     private _settleRewire;
     private _tryRun;
     private _allDepsSettled;
@@ -513,14 +471,6 @@ declare class Node<T = unknown> {
     private _down;
     private _up;
     private _markDemandRouted;
-    /**
-     * Forward one up-going control message toward deps (R-up-routing): up the single declared edge
-     * `towardDep` (directed — prunes other branches; only meaningful on the issuer's FIRST hop) or
-     * broadcast up ALL deps. A depless source has no deps → the message DROPS here (the terminus —
-     * e.g. a cone-routed RESUME whose pullId no node up this cone holds, R-up-at-source). Recursive
-     * forwarding carries the same per-wave route state and no `towardDep` → broadcast beyond the
-     * first hop.
-     */
     private _forwardUp;
     private _isPaused;
     private _hasBoundaryPauseLock;
@@ -528,50 +478,17 @@ declare class Node<T = unknown> {
     private _pauseAcquire;
     private _pauseRelease;
     private _onResume;
-    /**
-     * R-pull (D59): can this pull node fire a demand NOW? — not terminal, settle-ready (_pending===0),
-     * and no OTHER (non-pullId) lock holds it paused. The gate that decides fire-now vs OWE.
-     */
     private _canFireDemand;
-    /**
-     * R-pull (D59): deliver ONE demand pulse — release the pullId so the demand wave RELAYS (not
-     * absorbed), fire it, then RE-QUIET (1:1). The pullId re-add + the re-entrancy flag are in a
-     * `finally` so a throwing pull fn (graph-less node, no D30 catch) cannot leave the node
-     * permanently non-quiet (the wedge-fix silently disabled) — QA-found robustness fix.
-     */
     private _deliverPullDemand;
-    /**
-     * R-pull (D59): a cone-routed RESUME of THIS node's pullId arrived (R-up-routing) = a DEMAND.
-     * Fire immediately if able; else OWE it — pin-5 (a dep DIRTY in flight, _pending>0) or F4/F5 (an
-     * external PAUSE lock co-holds the node) — and fire when the node next becomes able. A demand
-     * arriving WHILE a delivery is in flight (synchronous re-entry) is DROPPED (1:1, QA guard).
-     */
     private _onDemand;
-    /**
-     * R-pull (D55): service ONE demand. Delivery content = the orthogonal pausable mode:
-     *   - 'resumeAll' → drain the buffered BACKLOG (each `_down` re-synthesizes a leading DIRTY, so
-     *     the per-entry replay is DIRTY-before-DATA — R-pause-modes per-entry arrival order);
-     *   - true → deliver the coalesced LATEST as ONE DIRTY-before-DATA wave (pin 2: the quiet absorb
-     *     suppressed the dep's original DIRTY, so the demand wave restores it before the value).
-     * Neither branch fires when nothing changed since the last demand → the demand is SILENT.
-     * Called by `_deliverPullDemand` only when settle-ready; the caller has released the pullId, so
-     * `_markDirty` relays the leading DIRTY (not absorbed).
-     */
     private _firePullDemand;
-    /**
-     * R-pull (D55/D59): fire a demand that was OWED (deferred at demand time) once the node becomes
-     * able — called from the dep-settle arms (DATA/RESOLVED/INVALIDATE/terminal drain _pending, pin-5
-     * + B1/F6) and from `_pauseRelease` (an external PAUSE lock releases, F4/F5).
-     */
     private _fireOwedDemandIfReady;
-    /** Should an outgoing settle slice be deferred into the pause buffer? */
     private _shouldBufferOnPause;
-    /** R-invalidate-idempotent: clear cache + flush + cascade; no-op if nothing cached. */
     private _invalidate;
     private _allDepsTerminal;
+    private _emitToSubs;
     /** R-terminal: resubscribable reset clears terminal + dep state + re-arms the gate. */
     private _resetLifecycle;
-    private _emitToSubs;
     /** Batch commit (R-batch-coalesce): deliver the deferred tier-3 wave now. */
     __commitBatchedWave(wave: Wave): void;
     /** Batch rollback: balance the immediate DIRTY with a RESOLVED so downstream un-dirties. */
@@ -667,8 +584,8 @@ interface Ctx {
     /**
      * Emit upstream toward deps — control tiers only (R-ctx-up). IMMEDIATE. `towardDep` (a dep index)
      * routes the wave up ONE declared edge (R-up-routing directed-up); omitted = broadcast up all deps.
-     * A pull DEMAND is `up([[RESUME, pullId]])` — but for a SELF-demand (demanding a dep this fn also
-     * reads) use {@link Ctx.upNext} instead, since an immediate demand whose delivery loops back
+     * A pull DEMAND is `up([[PULL, { pullId, params }]])` — but for a SELF-demand (demanding a dep
+     * this fn also reads) use {@link Ctx.upNext} instead, since an immediate demand whose delivery loops back
      * re-enters this fn mid-wave (D37 / R-reentrancy).
      */
     up(msgs: Wave, towardDep?: number): void;
@@ -689,6 +606,8 @@ interface Ctx {
     onInvalidate(fn: () => void): void;
     /** Graph-owned environment drivers for source/adapter boundaries (D130/D131). */
     environment(): EnvironmentDrivers;
+    /** Holder-visible context for a PULL-caused invocation (D272); absent for ordinary waves. */
+    readonly pull?: PullDemand;
     /**
      * Deferred SELF-rewire (R-rewire-deferred / D47) — the substrate affordance higher-order
      * operators (switchMap/mergeMap/concatMap/exhaustMap/flatMap) use to grow/shrink their own
@@ -699,8 +618,8 @@ interface Ctx {
      * Deferred up — the boundary-deferred form of {@link Ctx.up} (R-up-routing / R-pull / D59). Routes
      * `msgs` up from this node at the COMMITTED wave boundary (broadcast, or up the single `towardDep`
      * edge), riding the same R-rewire-deferred (D47) drain as {@link RewireNext}. This is the
-     * SELF-DEMAND path: a consumer issues `ctx.upNext([[RESUME, pullId]])` to demand a pull dep it
-     * ALSO reads — the cone-routed RESUME reaches the pullId-holder, whose delivery loops back as a
+     * SELF-DEMAND path: a consumer issues `ctx.upNext([[PULL, { pullId, params }]])` to demand a pull
+     * dep it ALSO reads — the cone-routed PULL reaches the pullId-holder, whose delivery loops back as a
      * FRESH wave (not a mid-fn re-entry → no D37). The consumer accepts one-wave latency (the
      * HTTP-request model). No node reference needed: the author writes the pullId verbatim.
      */