@graphrefly/ts 0.0.0 → 0.0.1

package/dist/data/index.d.cts

@@ -0,0 +1,36 @@
+/**
+ * Passive DATA-level result vocabulary (D184).
+ *
+ * These shapes are ordinary payload facts. They are not protocol ERROR messages and
+ * carry no wave terminal or lifecycle semantics.
+ */
+interface DataIssue {
+    readonly kind: "issue";
+    readonly code: string;
+    readonly message: string;
+    readonly severity?: "info" | "warning" | "error";
+    readonly source?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly path?: readonly (string | number)[];
+    readonly refs?: readonly string[];
+    readonly retryable?: boolean;
+    readonly details?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+interface DataOk<T> {
+    readonly kind: "ok";
+    readonly value: T;
+    readonly issues?: readonly DataIssue[];
+    readonly metadata?: Record<string, unknown>;
+}
+interface DataError<E extends DataIssue = DataIssue> {
+    readonly kind: "error";
+    readonly error: E;
+    readonly issues?: readonly DataIssue[];
+    readonly metadata?: Record<string, unknown>;
+}
+type DataResult<T, E extends DataIssue = DataIssue> = DataOk<T> | DataError<E>;
+
+export type { DataError, DataIssue, DataOk, DataResult };

package/dist/data/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Passive DATA-level result vocabulary (D184).
+ *
+ * These shapes are ordinary payload facts. They are not protocol ERROR messages and
+ * carry no wave terminal or lifecycle semantics.
+ */
+interface DataIssue {
+    readonly kind: "issue";
+    readonly code: string;
+    readonly message: string;
+    readonly severity?: "info" | "warning" | "error";
+    readonly source?: string;
+    readonly subjectId?: string;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+    readonly path?: readonly (string | number)[];
+    readonly refs?: readonly string[];
+    readonly retryable?: boolean;
+    readonly details?: unknown;
+    readonly metadata?: Record<string, unknown>;
+}
+interface DataOk<T> {
+    readonly kind: "ok";
+    readonly value: T;
+    readonly issues?: readonly DataIssue[];
+    readonly metadata?: Record<string, unknown>;
+}
+interface DataError<E extends DataIssue = DataIssue> {
+    readonly kind: "error";
+    readonly error: E;
+    readonly issues?: readonly DataIssue[];
+    readonly metadata?: Record<string, unknown>;
+}
+type DataResult<T, E extends DataIssue = DataIssue> = DataOk<T> | DataError<E>;
+
+export type { DataError, DataIssue, DataOk, DataResult };

package/dist/data/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/data-structures/index.cjs

@@ -52,6 +52,7 @@ var TIER = {
   START: TIER_START,
   PAUSE: TIER_CONTROL,
   RESUME: TIER_CONTROL,
+  PULL: TIER_CONTROL,
   DIRTY: TIER_NOTIFICATION,
   DATA: TIER_VALUE,
   RESOLVED: TIER_VALUE,
@@ -908,6 +909,17 @@ function releaseRuntimeOfNode(n) {
 function terminalView(t) {
   return t === void 0 ? false : t;
 }
+function normalizePullDemand(demand) {
+  if (typeof demand !== "object" || demand === null || Array.isArray(demand)) {
+    throw new Error("ctx.up: PULL requires { pullId, params? } demand payload (D269)");
+  }
+  const pullId = demand.pullId;
+  if (typeof pullId !== "string" && typeof pullId !== "symbol") {
+    throw new Error("ctx.up: PULL demand requires a string or symbol pullId (D269)");
+  }
+  const params = demand.params;
+  return params === void 0 ? { pullId } : { pullId, params };
+}
 function validateDownPayloads(msgs) {
   for (const m of msgs) {
     if (m[0] === "DATA" && m[1] === void 0) {
@@ -951,7 +963,7 @@ var Node = class {
     const pull = opts.pullId !== void 0;
     if (pull && pausable === false)
       throw new Error(
-        "node: pullId is incompatible with pausable:false \u2014 a pull node is demanded via RESUME, which pausable:false ignores (R-pull / R-pause-modes / D55,D59)"
+        "node: pullId is incompatible with pausable:false \u2014 a pull node uses the pausable delivery-content axis (R-pull / R-pause-modes / D55,D269)"
       );
     let handle;
     if (handleOrFn === null) handle = null;
@@ -974,7 +986,6 @@ var Node = class {
       value.status = "settled";
     }
     const pauseLockset = /* @__PURE__ */ new Set();
-    if (pull) pauseLockset.add(pullLock);
     this._core = core ?? new NodeCore();
     const created = this._core.createSlot(
       {
@@ -1015,7 +1026,9 @@ var Node = class {
           pauseLockset,
           pausedDepWaveOccurred: false,
           pauseBuffer: [],
-          demandOwed: false,
+          demandOwed: void 0,
+          activePull: void 0,
+          pullDirtyOwed: false,
           inDeliverDemand: false
         },
         privateState: { value: SENTINEL, persist: false },
@@ -1072,10 +1085,11 @@ var Node = class {
       this._wave.batchDirtyOwed = false;
       this._control.pauseBuffer = [];
       this._control.pausedDepWaveOccurred = false;
-      this._control.demandOwed = false;
+      this._control.demandOwed = void 0;
+      this._control.activePull = void 0;
+      this._control.pullDirtyOwed = false;
       this._control.inDeliverDemand = false;
       this._control.pauseLockset.clear();
-      if (this._slot.pull) this._control.pauseLockset.add(this._slot.pullLock);
       this._privateState.value = state.ctxState.value;
       this._privateState.persist = state.ctxState.persist;
       if (state.version === false) {
@@ -1114,17 +1128,16 @@ var Node = class {
     subscriberCountReaders.set(this, () => this._subscriberCount());
     activationReaders.set(this, () => this._lifecycle.activated);
   }
-  /** 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. */
   _isPullQuiet() {
-    return this._slot.pull && this._control.pauseLockset.has(this._slot.pullLock);
+    return this._slot.pull && this._control.activePull === void 0;
   }
   /**
-   * 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() {
     return this._slot.pullLock;
@@ -1231,10 +1244,10 @@ var Node = class {
     });
   }
   /**
-   * Enqueue a deferred up-going control wave (R-up-routing / R-pull / D59): at the committed wave
+   * Enqueue a deferred up-going control/demand wave (R-up-routing / R-pull / D269): 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
+   * deferred form of `ctx.up` — the SELF-demand path: a consumer issues `ctx.upNext([[PULL,
+   * { 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.
    */
@@ -1449,7 +1462,6 @@ var Node = class {
     this._lifecycle.activated = true;
     const seedRestoredDeps = this._restoredActivationPending;
     this._restoredActivationPending = false;
-    if (this._slot.pull) this._control.pauseLockset.add(this._slot.pullLock);
     this._dep.unsubs = new Array(this._slot.deps.length);
     this._dep.idxBoxes = new Array(this._slot.deps.length);
     for (const dep of this._slot.deps)
@@ -1521,7 +1533,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._value.replayRing = [];
     if (!this._privateState.persist) this._privateState.value = SENTINEL;
   }
@@ -1533,8 +1547,7 @@ var Node = class {
     return this._lifecycle.subscribers.size;
   }
   _isRuntimeQuiescentForRelease() {
-    const allowedPullQuietLock = this._slot.pull && this._control.pauseLockset.size === 1 && this._control.pauseLockset.has(this._slot.pullLock);
-    return !this._released && this._value.status !== "dirty" && this._value.status !== "pending" && this._wave.pending === 0 && !this._wave.insideRunWave && !this._wave.inDepMutation && !this._wave.rewireRunPending && !this._wave.batchDirtyOwed && this._dep.dirty.every((dirty) => !dirty) && this._control.pauseBuffer.length === 0 && !this._control.pausedDepWaveOccurred && !this._control.demandOwed && !this._control.inDeliverDemand && (this._control.pauseLockset.size === 0 || allowedPullQuietLock);
+    return !this._released && this._value.status !== "dirty" && this._value.status !== "pending" && this._wave.pending === 0 && !this._wave.insideRunWave && !this._wave.inDepMutation && !this._wave.rewireRunPending && !this._wave.batchDirtyOwed && this._dep.dirty.every((dirty) => !dirty) && this._control.pauseBuffer.length === 0 && !this._control.pausedDepWaveOccurred && this._control.demandOwed === void 0 && this._control.activePull === void 0 && !this._control.inDeliverDemand && this._control.pauseLockset.size === 0;
   }
   _releaseRuntime() {
     if (this._released) return;
@@ -1590,7 +1603,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._restoredActivationPending = false;
     checkpointReaders.delete(this);
     restoreWriters.delete(this);
@@ -1772,7 +1787,7 @@ var Node = class {
       this._wave.rewireRunPending = true;
       return;
     }
-    if (this._slot.pausable === true && this._isPaused()) {
+    if (this._slot.pausable === true && (this._isPaused() || this._isPullQuiet())) {
       this._control.pausedDepWaveOccurred = true;
       return;
     }
@@ -1912,10 +1927,11 @@ var Node = class {
         unsubscribeDep: (dep, fn) => this._requestRewireNext({ kind: "remove", dep, fn }),
         replaceDeps: (deps, fn) => this._requestRewireNext({ kind: "set", deps, fn })
       },
-      // R-up-routing / R-pull (D59): deferred up — route a control wave (e.g. a RESUME pull
-      // DEMAND) up the declared cone at the committed boundary. The SELF-demand path: an
+      // R-up-routing / R-pull (D269): deferred up — route a control/demand wave (e.g. PULL)
+      // up the declared cone at the committed boundary. The SELF-demand path: an
       // immediate ctx.up whose delivery loops back re-enters this fn (D37 / R-reentrancy).
       upNext: (msgs, towardDep) => this._requestUpNext(msgs, towardDep),
+      ...this._control.activePull === void 0 ? {} : { pull: this._control.activePull },
       [CTX_DEP_CACHE]: { latest: snapshot?.latest ?? this._dep.prev },
       [CTX_NODE_BINDING]: {
         dispatcher: this._slot.dispatcher,
@@ -1930,6 +1946,11 @@ var Node = class {
   _refreshCtx(ctx) {
     ctx.waveData = this._dep.waveData;
     ctx.terminal = this._dep.terminalInput.map(terminalView);
+    if (this._control.activePull === void 0) {
+      delete ctx.pull;
+    } else {
+      ctx.pull = this._control.activePull;
+    }
     ctx[CTX_DEP_CACHE] = { latest: this._dep.prev };
   }
   _makeState() {
@@ -2022,7 +2043,7 @@ var Node = class {
         plannedVersions[i] = plannedVersion;
       }
     }
-    if (hasTier3 && !this._wave.insideRunWave && !this._wave.emittedDirtyThisWave) {
+    if (hasTier3 && (!this._wave.insideRunWave || this._control.pullDirtyOwed) && !this._wave.emittedDirtyThisWave) {
       this._wave.emittedDirtyThisWave = true;
       this._value.status = "dirty";
       this._emitToSubs(["DIRTY"], { wave: deliveryWave, last: false });
@@ -2102,13 +2123,18 @@ var Node = class {
       if (m[0] === "PAUSE") {
         this._pauseAcquire(m[1]);
       } else if (m[0] === "RESUME") {
-        if (this._slot.pull && m[1] === this._slot.pullLock) {
-          if (!this._markDemandRouted(m[1], routeState)) this._onDemand();
-        } else if (this._control.pauseLockset.has(m[1])) {
+        if (this._control.pauseLockset.has(m[1])) {
           this._pauseRelease(m[1]);
         } else {
           this._forwardUp(m, towardDep, routeState);
         }
+      } else if (m[0] === "PULL") {
+        const demand = normalizePullDemand(m[1]);
+        if (this._slot.pull && demand.pullId === this._slot.pullLock) {
+          if (!this._markDemandRouted(demand.pullId, routeState)) this._onDemand(demand);
+        } else {
+          this._forwardUp(["PULL", demand], towardDep, routeState);
+        }
       } else if (this._slot.deps.length === 0) {
         if (m[0] === "INVALIDATE") this._down([["INVALIDATE"]]);
       } else {
@@ -2130,7 +2156,7 @@ var Node = class {
    * 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
+   * e.g. a cone-routed PULL 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.
    */
@@ -2149,9 +2175,7 @@ var Node = class {
   }
   _hasBoundaryPauseLock() {
     if (this._slot.pausable === false) return false;
-    let locks = this._control.pauseLockset.size;
-    if (this._slot.pull && this._control.pauseLockset.has(this._slot.pullLock)) locks--;
-    return locks > 0;
+    return this._control.pauseLockset.size > 0;
   }
   _isAsyncPool() {
     return this._slot.handle !== null && this._slot.dispatcher.poolKind(this._slot.handle.poolId) === "async";
@@ -2162,17 +2186,19 @@ var Node = class {
   _pauseRelease(lockId) {
     if (!this._control.pauseLockset.has(lockId)) return;
     this._control.pauseLockset.delete(lockId);
-    if (this._slot.pull && this._control.demandOwed) this._fireOwedDemandIfReady();
+    if (this._slot.pull && this._control.demandOwed !== void 0) this._fireOwedDemandIfReady();
     if (this._hasBoundaryPauseLock()) return;
     scheduleBoundaryDrain(this._core);
-    if (this._control.pauseLockset.size > 0) return;
+    if (this._slot.pull) return;
     this._onResume();
   }
   _onResume() {
     if (this._value.terminal !== void 0) {
       this._control.pauseBuffer = [];
       this._control.pausedDepWaveOccurred = false;
-      this._control.demandOwed = false;
+      this._control.demandOwed = void 0;
+      this._control.activePull = void 0;
+      this._control.pullDirtyOwed = false;
       return;
     }
     if (this._control.pauseBuffer.length > 0) {
@@ -2186,41 +2212,38 @@ var Node = class {
     }
   }
   /**
-   * R-pull (D59): can this pull node fire a demand NOW? — not terminal, settle-ready (_pending===0),
+   * R-pull (D269): 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.
    */
   _canFireDemand() {
     if (this._value.terminal !== void 0 || this._wave.pending > 0) return false;
-    const own = this._control.pauseLockset.has(this._slot.pullLock) ? 1 : 0;
-    return this._control.pauseLockset.size <= own;
+    return this._control.pauseLockset.size === 0;
   }
   /**
-   * 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.
+   * R-pull (D269/D272): deliver ONE demand pulse — install activePull so the demand wave may
+   * emit, fire it, then clear activePull so the node is quiet again (1:1).
    */
-  _deliverPullDemand() {
-    this._control.demandOwed = false;
+  _deliverPullDemand(demand) {
+    this._control.demandOwed = void 0;
+    this._control.activePull = demand;
     this._control.inDeliverDemand = true;
-    this._control.pauseLockset.delete(this._slot.pullLock);
     try {
       this._firePullDemand();
     } finally {
-      this._control.pauseLockset.add(this._slot.pullLock);
+      this._control.activePull = void 0;
       this._control.inDeliverDemand = false;
     }
   }
   /**
-   * R-pull (D59): a cone-routed RESUME of THIS node's pullId arrived (R-up-routing) = a DEMAND.
+   * R-pull (D269): a cone-routed PULL 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).
    */
-  _onDemand() {
+  _onDemand(demand) {
     if (this._control.inDeliverDemand) return;
-    if (this._canFireDemand()) this._deliverPullDemand();
-    else this._control.demandOwed = true;
+    if (this._canFireDemand()) this._deliverPullDemand(demand);
+    else this._control.demandOwed = demand;
   }
   /**
    * R-pull (D55): service ONE demand. Delivery content = the orthogonal pausable mode:
@@ -2233,33 +2256,53 @@ var Node = class {
    * `_markDirty` relays the leading DIRTY (not absorbed).
    */
   _firePullDemand() {
+    let drainedBuffer = false;
     if (this._control.pauseBuffer.length > 0) {
       const buf = this._control.pauseBuffer;
       this._control.pauseBuffer = [];
       for (const wave of buf) this._down(wave);
+      drainedBuffer = true;
     }
+    if (drainedBuffer) return;
     if (this._control.pausedDepWaveOccurred) {
       const gated = this._slot.handle !== null && !this._wave.hasCalledFnOnce && !(this._slot.partial || this._allDepsSettled());
       if (this._wave.pending > 0 || gated) return;
       this._control.pausedDepWaveOccurred = false;
-      this._markDirty();
-      this._tryRun();
+      this._wave.emittedDirtyThisWave = false;
+      this._control.pullDirtyOwed = true;
+      try {
+        this._tryRun();
+      } finally {
+        this._control.pullDirtyOwed = false;
+      }
+      return;
+    }
+    if (this._slot.handle !== null) {
+      if (!this._wave.hasCalledFnOnce && !(this._slot.partial || this._allDepsSettled())) return;
+      this._wave.emittedDirtyThisWave = false;
+      this._control.pullDirtyOwed = true;
+      try {
+        this._runWave();
+      } finally {
+        this._control.pullDirtyOwed = false;
+      }
     }
   }
   /**
-   * R-pull (D55/D59): fire a demand that was OWED (deferred at demand time) once the node becomes
+   * R-pull (D269): 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).
    */
   _fireOwedDemandIfReady() {
     if (this._control.inDeliverDemand) return;
-    if (this._slot.pull && this._control.demandOwed && this._canFireDemand())
-      this._deliverPullDemand();
+    if (this._slot.pull && this._control.demandOwed !== void 0 && this._canFireDemand()) {
+      this._deliverPullDemand(this._control.demandOwed);
+    }
   }
   /** Should an outgoing settle slice be deferred into the pause buffer? */
   _shouldBufferOnPause() {
     if (this._slot.pausable === false) return false;
-    if (!this._isPaused()) return false;
+    if (!this._isPaused() && !this._isPullQuiet()) return false;
     if (this._slot.pausable === "resumeAll") return true;
     if (!this._wave.insideRunWave && this._isAsyncPool() && this._slot.deps.length > 0) return true;
     return false;
@@ -2299,7 +2342,9 @@ var Node = class {
     this._control.pauseLockset.clear();
     this._control.pauseBuffer = [];
     this._control.pausedDepWaveOccurred = false;
-    this._control.demandOwed = false;
+    this._control.demandOwed = void 0;
+    this._control.activePull = void 0;
+    this._control.pullDirtyOwed = false;
     this._value.replayRing = [];
     const isCompute = this._slot.handle !== null || this._slot.deps.length > 0;
     if (isCompute) {
@@ -2478,7 +2523,10 @@ function collectionCore(backend, factory, opts = {}, restore) {
     name: name ? `${name}.delta` : void 0
   });
   const pullId = /* @__PURE__ */ Symbol(name ? `${name}.snapshot` : `${factory}.snapshot`);
+  let deliveredVersion = backend.version;
   const snapFn = (ctx) => {
+    if (ctx.pull !== void 0 && backend.version === deliveredVersion) return;
+    deliveredVersion = backend.version;
     ctx.down([["DATA", backend.snapshot()]]);
   };
   const snapshot = graph ? graph.node([delta], snapFn, {