@graphrefly/graphrefly 0.44.0 → 0.46.0

package/README.md

@@ -1,8 +1,8 @@
 # GraphReFly
 
-**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
+**The reactive graph your code, your agents, and your humans share as a blueprint.** Compose in code, review the projected spec, co-edit across agents without colliding, trace every decision.
 
-GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
+GraphReFly is a reactive graph protocol for human + LLM co-operation. Code is the source of truth — `factoryTag`-stamped factories project automatically into a `GraphSpec` blueprint that humans and agents read, diff, and review together. Multi-agent worktrees claim subgraph ownership through a structural protocol (TTL → heartbeat → supervisor) so concurrent edits don't corrupt shared topology. Every decision has a causal chain — `graph.explain()` walks back through dependencies and tells you exactly why a value is what it is.
 
 [![npm](https://img.shields.io/npm/v/@graphrefly/graphrefly?color=blue)](https://www.npmjs.com/package/@graphrefly/graphrefly)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-ts)](./LICENSE)
@@ -14,8 +14,7 @@ GraphReFly makes long-running human + LLM co-operation reactive, resumable, and
 | Package | What it is |
 |---|---|
 | [`@graphrefly/graphrefly`](https://www.npmjs.com/package/@graphrefly/graphrefly) | The library — reactive graph primitives, operators, `Graph` container, framework adapters. |
-| [`@graphrefly/mcp-server`](./packages/mcp-server) | Model Context Protocol server — expose GraphReFly to Claude Desktop, Claude Code, Cline, Cursor, and any MCP client as `graphrefly_*` tools. |
-| [`@graphrefly/cli`](./packages/cli) | Stateless command-line shell — `describe`, `explain`, `observe`, `reduce`, `snapshot`, and `mcp` (boot the server) from your terminal or CI. |
+| [`@graphrefly/cli`](./packages/cli) | Stateless command-line shell — `describe`, `explain`, `observe`, `reduce`, `snapshot` from your terminal or CI. |
 
 ---
 
@@ -52,11 +51,13 @@ count.set(3);
 
 ## How it works
 
-You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
+Code is the source of truth. You compose a reactive graph using primitives (`state`, `derived`, `effect`, `producer`) and factories (`agentLoop`, `harnessLoop`, `agentMemory`, …). `factoryTag`-stamped factories carry self-description into the live graph. `graph.describe({ detail: "spec" })` projects the topology into a JSON `GraphSpec` blueprint — the same shape the original spec was written from, but always in sync with what's actually running. Spec is what your agents read to understand the topology. Code is what they (and you) actually edit.
 
-## Harness engineering coverage
+The graph runs persistently, checkpoints state on `messageTier ≥ 3` and topology on `_topologyVersion` bump, and traces every decision through a causal chain. Ask "why?" at any point — `graph.explain(from, to)` walks backward through dependencies and returns a structured chain that's both human-readable and LLM-parseable.
 
-The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+## Substrate coverage
+
+The eight requirements of a production agent system cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
 
 | Need | GraphReFly |
 |---|---|
@@ -68,23 +69,25 @@ The eight requirements of a production agent harness cluster into a handful of c
 | Human governance | `gate` — reactive `pending` / `isOpen` with `approve` / `reject` / `modify(fn, n)` |
 | Verification | Multi-model eval harness with regression gates |
 | Continuous improvement | Strategy model: `rootCause × intervention → successRate` |
+| Multi-agent coordination | `ownershipController()` — L0 static / L1 TTL / L2 heartbeat / L3 supervisor staircase; `Actor / Guard ABAC` enforces claims at write time; `validateOwnership` lints PR diffs |
 
 The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
 
 ## Why GraphReFly?
 
-|  | Zustand / Jotai | RxJS | XState | LangGraph | TC39 Signals | **GraphReFly** |
-|--|-----------------|------|--------|-----------|-------------|---------------|
-| Simple store API | yes | no | no | no | yes | **yes** |
-| Streaming operators | no | yes | no | no | no | **yes** |
-| Diamond resolution | no | n/a | n/a | n/a | partial | **glitch-free** |
-| Graph introspection | no | no | visual | checkpoints | no | **describe / observe / diagram** |
-| Causal tracing | no | no | no | no | no | **explain every decision** |
-| Durable checkpoints | no | no | persistence | yes | no | **file / SQLite / IndexedDB** |
-| LLM orchestration | no | no | no | yes | no | **agentLoop / chatStream / toolRegistry** |
-| NL → graph composition | no | no | no | no | no | **graphFromSpec / llmCompose** |
-| Framework adapters | React | Angular | React / Vue | n/a | varies | **React / Vue / Svelte / Solid / NestJS** |
-| Dependencies | 0 | 0 | 0 | many | n/a | **0** |
+|  | Zustand / Jotai | RxJS | XState | LangGraph | Archon | Hermes | **GraphReFly** |
+|--|-----------------|------|--------|-----------|--------|--------|---------------|
+| Simple store API | yes | no | no | no | n/a | n/a | **yes** |
+| Streaming operators | no | yes | no | no | no | no | **yes** |
+| Diamond resolution | no | n/a | n/a | n/a | n/a | n/a | **glitch-free** |
+| Graph introspection | no | no | visual | checkpoints | YAML view | no | **describe / observe / diagram** |
+| Causal tracing | no | no | no | no | no | no (black-box) | **explain every decision** |
+| Durable checkpoints | no | no | persistence | yes | sqlite | yes | **file / SQLite / IndexedDB** |
+| LLM orchestration | no | no | no | yes | yes (workflow) | yes (skills) | **agentLoop / chatStream / toolRegistry** |
+| Auto-projection: code → spec | no | no | no | no | no (manual YAML) | partial (skill emit) | **factoryTag round-trip** |
+| Multi-agent on shared topology | no | no | no | no | no (worktree-isolated) | no (skill-isolated) | **L0–L3 ownership protocol** |
+| Framework adapters | React | Angular | React / Vue | n/a | n/a | n/a | **React / Vue / Svelte / Solid / NestJS** |
+| Dependencies | 0 | 0 | 0 | many | many | many | **0** |
 
 ## One primitive
 

package/dist/_internal-B23BagFd.d.cts

@@ -0,0 +1,33 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * Internal helpers shared by resilience sub-files.
+ *
+ * Not part of the public surface. The base-layer resilience operators
+ * co-located here (`retry.ts`, `status.ts`, `timeout.ts`) import what they
+ * need from this file directly; the utils-layer resilience primitives that
+ * stayed in `utils/resilience/` (`breaker.ts`, `rate-limiter.ts`,
+ * `fallback.ts`) import it top-down via `../../base/resilience/_internal.js`.
+ *
+ * `NodeOrValue<T>` is the only export re-surfaced publicly — there is no
+ * `base/resilience/index.ts`; it ships through `utils/resilience/index.ts`
+ * (and `utils/memory/index.ts`). Every resilience primitive that accepts
+ * reactive options uses it as the option-arg shape.
+ */
+
+/**
+ * Either a literal value or a reactive Node carrying it. Mirrors
+ * {@link FallbackInput}'s precedent for "options that may be reactive."
+ *
+ * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
+ * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
+ * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
+ * to the option Node via {@link resolveReactiveOption} and rebinds
+ * internal state per its locked swap-semantic rule (see each primitive's
+ * JSDoc for the rule).
+ *
+ * @category extra
+ */
+type NodeOrValue<T> = T | Node<T>;
+
+export type { NodeOrValue as N };

package/dist/_internal-B23BagFd.d.ts

@@ -0,0 +1,33 @@
+import { Node } from '@graphrefly/pure-ts/core';
+
+/**
+ * Internal helpers shared by resilience sub-files.
+ *
+ * Not part of the public surface. The base-layer resilience operators
+ * co-located here (`retry.ts`, `status.ts`, `timeout.ts`) import what they
+ * need from this file directly; the utils-layer resilience primitives that
+ * stayed in `utils/resilience/` (`breaker.ts`, `rate-limiter.ts`,
+ * `fallback.ts`) import it top-down via `../../base/resilience/_internal.js`.
+ *
+ * `NodeOrValue<T>` is the only export re-surfaced publicly — there is no
+ * `base/resilience/index.ts`; it ships through `utils/resilience/index.ts`
+ * (and `utils/memory/index.ts`). Every resilience primitive that accepts
+ * reactive options uses it as the option-arg shape.
+ */
+
+/**
+ * Either a literal value or a reactive Node carrying it. Mirrors
+ * {@link FallbackInput}'s precedent for "options that may be reactive."
+ *
+ * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
+ * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
+ * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
+ * to the option Node via {@link resolveReactiveOption} and rebinds
+ * internal state per its locked swap-semantic rule (see each primitive's
+ * JSDoc for the rule).
+ *
+ * @category extra
+ */
+type NodeOrValue<T> = T | Node<T>;
+
+export type { NodeOrValue as N };

package/dist/adaptive-rate-limiter-Dch_xYIi.d.cts

@@ -0,0 +1,111 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+
+/**
+ * Adaptive rate limiter — reactive, live-tunable, 429-aware.
+ *
+ * Wraps two `tokenBucket` instances (requests, tokens) with:
+ *   - Reactive `rpm` / `tpm` knobs that can be re-tuned at runtime via `NodeInput<number>`.
+ *   - An adaptation signal input (`Node<RateLimitSignal>`) that feeds back
+ *     provider 429 / retry-after / x-ratelimit-* headers to tighten limits.
+ *   - A `clampCooldownMs` TTL on signal-induced caps so a transient 429 doesn't
+ *     permanently throttle — caps decay back to user-configured values after
+ *     the cooldown elapses.
+ *   - TPM-miss recovery: consumed RPM tokens are returned to the request
+ *     bucket when the TPM admit fails, via `TokenBucket.putBack`.
+ *   - Imperative `acquire()` for bridging to Promise-based call paths
+ *     (used by the `withRateLimiter` adapter middleware).
+ *
+ * **Timer policy:** sleeps use `ResettableTimer` (documented spec §5.10
+ * escape hatch in `src/extra/timer.ts`) rather than `fromTimer` to avoid
+ * allocating a new Node per acquire cycle.
+ *
+ * Design lives in `docs/optimizations.md` § "Reactive adaptive rate limiter".
+ */
+
+/**
+ * Rate-limit signal emitted by an adaptation source (e.g., an HTTP 429 parser).
+ *
+ * Any subset of fields may be present. The adaptive rate limiter uses:
+ * - `retryAfterMs` — blocks acquire() for this duration.
+ * - `rpmCap` / `tpmCap` — tightens effective rpm/tpm to this value (decays
+ *   back to the user-configured cap after `clampCooldownMs`).
+ * - `usageHint` — updates the last-known rpm/tpm usage ratio for logging.
+ */
+interface RateLimitSignal {
+    /** Throttle duration — pause acquire() for this long. */
+    retryAfterMs?: number;
+    /** Hard cap for requests-per-minute; effective rpm = min(current, rpmCap) while clamp is active. */
+    rpmCap?: number;
+    /** Hard cap for tokens-per-minute; effective tpm = min(current, tpmCap) while clamp is active. */
+    tpmCap?: number;
+    /** Observed usage-percentage hint (0..1) — for observability, not gating. */
+    usageHint?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    /** Free-form provider-specific payload. */
+    metadata?: Record<string, unknown>;
+}
+interface AdaptiveRateLimiterOptions {
+    name?: string;
+    /** Effective requests-per-minute cap. Reactive — reads push-on-subscribe. */
+    rpm?: NodeInput<number>;
+    /** Effective tokens-per-minute cap. Reactive. */
+    tpm?: NodeInput<number>;
+    /** Source of adaptation signals (429 parser output, etc.). */
+    adaptation?: NodeInput<RateLimitSignal>;
+    /**
+     * How long (ms) a signal-induced `rpmCap` / `tpmCap` stays in effect before
+     * relaxing back to the user-configured value. Default 60_000 (one minute).
+     * Set to `Infinity` to make signal caps sticky until manually cleared.
+     * A fresh signal with the same cap resets the cooldown.
+     */
+    clampCooldownMs?: number;
+    /** Burst capacity overshoot above the steady-state rpm/tpm. Default 1 (no burst). */
+    burstMultiplier?: number;
+}
+interface AdaptiveRateLimiterBundle {
+    /** Effective requests-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveRpm: Node<number>;
+    /** Effective tokens-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveTpm: Node<number>;
+    /** Last adaptation signal observed. */
+    readonly lastSignal: Node<RateLimitSignal>;
+    /** Pending `acquire()` callers waiting for capacity. */
+    readonly pending: Node<number>;
+    /** Current request-token-bucket fill (approximate). */
+    readonly rpmAvailable: Node<number>;
+    /** Current token-bucket fill (approximate). */
+    readonly tpmAvailable: Node<number>;
+    /**
+     * Imperative bridge: wait until `requestCost` request-tokens and
+     * `tokenCost` tokens are available, then consume them. Honors the
+     * most recent `retryAfterMs` from adaptation signals. Rejects with
+     * an `AbortError`-named error if `signal` aborts while waiting.
+     * `requestCost` defaults to 1; `tokenCost` defaults to 0 (rpm-only gating).
+     */
+    acquire(opts?: {
+        requestCost?: number;
+        tokenCost?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Feed back observed token usage (post-call) so the TPM bucket reflects
+     * real consumption rather than the pre-call estimate. A positive `delta`
+     * debits additional TPM (undershot estimate); a negative `delta` credits
+     * back overshoot (`putBack`).
+     */
+    recordUsage(delta: number): void;
+    /** Manually feed an adaptation signal — useful for tests. */
+    recordSignal(sig: RateLimitSignal): void;
+    /** Dispose internal subscriptions and pending timers. */
+    dispose(): void;
+}
+/**
+ * Create an adaptive rate limiter. Compose with any call source via
+ * `await limiter.acquire({ requestCost, tokenCost, signal })`.
+ */
+declare function adaptiveRateLimiter(opts?: AdaptiveRateLimiterOptions): AdaptiveRateLimiterBundle;
+
+export { type AdaptiveRateLimiterBundle as A, type RateLimitSignal as R, type AdaptiveRateLimiterOptions as a, adaptiveRateLimiter as b };

package/dist/adaptive-rate-limiter-Dch_xYIi.d.ts

@@ -0,0 +1,111 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput } from '@graphrefly/pure-ts/extra';
+
+/**
+ * Adaptive rate limiter — reactive, live-tunable, 429-aware.
+ *
+ * Wraps two `tokenBucket` instances (requests, tokens) with:
+ *   - Reactive `rpm` / `tpm` knobs that can be re-tuned at runtime via `NodeInput<number>`.
+ *   - An adaptation signal input (`Node<RateLimitSignal>`) that feeds back
+ *     provider 429 / retry-after / x-ratelimit-* headers to tighten limits.
+ *   - A `clampCooldownMs` TTL on signal-induced caps so a transient 429 doesn't
+ *     permanently throttle — caps decay back to user-configured values after
+ *     the cooldown elapses.
+ *   - TPM-miss recovery: consumed RPM tokens are returned to the request
+ *     bucket when the TPM admit fails, via `TokenBucket.putBack`.
+ *   - Imperative `acquire()` for bridging to Promise-based call paths
+ *     (used by the `withRateLimiter` adapter middleware).
+ *
+ * **Timer policy:** sleeps use `ResettableTimer` (documented spec §5.10
+ * escape hatch in `src/extra/timer.ts`) rather than `fromTimer` to avoid
+ * allocating a new Node per acquire cycle.
+ *
+ * Design lives in `docs/optimizations.md` § "Reactive adaptive rate limiter".
+ */
+
+/**
+ * Rate-limit signal emitted by an adaptation source (e.g., an HTTP 429 parser).
+ *
+ * Any subset of fields may be present. The adaptive rate limiter uses:
+ * - `retryAfterMs` — blocks acquire() for this duration.
+ * - `rpmCap` / `tpmCap` — tightens effective rpm/tpm to this value (decays
+ *   back to the user-configured cap after `clampCooldownMs`).
+ * - `usageHint` — updates the last-known rpm/tpm usage ratio for logging.
+ */
+interface RateLimitSignal {
+    /** Throttle duration — pause acquire() for this long. */
+    retryAfterMs?: number;
+    /** Hard cap for requests-per-minute; effective rpm = min(current, rpmCap) while clamp is active. */
+    rpmCap?: number;
+    /** Hard cap for tokens-per-minute; effective tpm = min(current, tpmCap) while clamp is active. */
+    tpmCap?: number;
+    /** Observed usage-percentage hint (0..1) — for observability, not gating. */
+    usageHint?: {
+        rpm?: number;
+        tpm?: number;
+    };
+    /** Free-form provider-specific payload. */
+    metadata?: Record<string, unknown>;
+}
+interface AdaptiveRateLimiterOptions {
+    name?: string;
+    /** Effective requests-per-minute cap. Reactive — reads push-on-subscribe. */
+    rpm?: NodeInput<number>;
+    /** Effective tokens-per-minute cap. Reactive. */
+    tpm?: NodeInput<number>;
+    /** Source of adaptation signals (429 parser output, etc.). */
+    adaptation?: NodeInput<RateLimitSignal>;
+    /**
+     * How long (ms) a signal-induced `rpmCap` / `tpmCap` stays in effect before
+     * relaxing back to the user-configured value. Default 60_000 (one minute).
+     * Set to `Infinity` to make signal caps sticky until manually cleared.
+     * A fresh signal with the same cap resets the cooldown.
+     */
+    clampCooldownMs?: number;
+    /** Burst capacity overshoot above the steady-state rpm/tpm. Default 1 (no burst). */
+    burstMultiplier?: number;
+}
+interface AdaptiveRateLimiterBundle {
+    /** Effective requests-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveRpm: Node<number>;
+    /** Effective tokens-per-minute (post-signal-clamp). Reactive. */
+    readonly effectiveTpm: Node<number>;
+    /** Last adaptation signal observed. */
+    readonly lastSignal: Node<RateLimitSignal>;
+    /** Pending `acquire()` callers waiting for capacity. */
+    readonly pending: Node<number>;
+    /** Current request-token-bucket fill (approximate). */
+    readonly rpmAvailable: Node<number>;
+    /** Current token-bucket fill (approximate). */
+    readonly tpmAvailable: Node<number>;
+    /**
+     * Imperative bridge: wait until `requestCost` request-tokens and
+     * `tokenCost` tokens are available, then consume them. Honors the
+     * most recent `retryAfterMs` from adaptation signals. Rejects with
+     * an `AbortError`-named error if `signal` aborts while waiting.
+     * `requestCost` defaults to 1; `tokenCost` defaults to 0 (rpm-only gating).
+     */
+    acquire(opts?: {
+        requestCost?: number;
+        tokenCost?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Feed back observed token usage (post-call) so the TPM bucket reflects
+     * real consumption rather than the pre-call estimate. A positive `delta`
+     * debits additional TPM (undershot estimate); a negative `delta` credits
+     * back overshoot (`putBack`).
+     */
+    recordUsage(delta: number): void;
+    /** Manually feed an adaptation signal — useful for tests. */
+    recordSignal(sig: RateLimitSignal): void;
+    /** Dispose internal subscriptions and pending timers. */
+    dispose(): void;
+}
+/**
+ * Create an adaptive rate limiter. Compose with any call source via
+ * `await limiter.acquire({ requestCost, tokenCost, signal })`.
+ */
+declare function adaptiveRateLimiter(opts?: AdaptiveRateLimiterOptions): AdaptiveRateLimiterBundle;
+
+export { type AdaptiveRateLimiterBundle as A, type RateLimitSignal as R, type AdaptiveRateLimiterOptions as a, adaptiveRateLimiter as b };