@graphrefly/graphrefly 0.21.0 → 0.22.0

package/dist/index-DsGxLfwL.d.ts

@@ -0,0 +1,315 @@
+import { k as GraphReFlyConfig } from './node-C5UD5MGq.js';
+import { r as GraphPersistSnapshot, g as GraphCheckpointRecord, D as DescribeFilter, e as GRAPH_META_SEGMENT, G as Graph, f as GraphActorOptions, b as GraphAttachStorageOptions, h as GraphDescribeOptions, i as GraphDescribeOutput, j as GraphDiagramDirection, k as GraphDiagramOptions, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, d as GraphProfileOptions, c as GraphProfileResult, s as GraphVersionChange, t as GraphWALDiff, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, A as diffForWAL, B as graphProfile, C as reachable } from './graph-DFr0diXB.js';
+
+/**
+ * Approximate in-memory size estimation for arbitrary JS values.
+ *
+ * Iterative walk with cycle detection via `WeakSet`. V8-tuned overhead
+ * heuristics. Not exact — approximate enough for profiling and hotspot
+ * detection.
+ *
+ * Use cases: `graphProfile` (per-node value size), reactive data structure
+ * memory audits, heuristic cache admission.
+ *
+ * @module
+ */
+/** Approximate per-type overhead in bytes (V8 heuristics). */
+declare const OVERHEAD: {
+    readonly object: 56;
+    readonly array: 64;
+    readonly string: 40;
+    readonly number: 8;
+    readonly boolean: 4;
+    readonly null: 0;
+    readonly undefined: 0;
+    readonly symbol: 40;
+    readonly bigint: 16;
+    readonly function: 120;
+    readonly map: 72;
+    readonly set: 72;
+    readonly mapEntry: 40;
+    readonly setEntry: 24;
+    readonly date: 24;
+    readonly regexp: 48;
+    readonly error: 64;
+    readonly url: 80;
+    readonly promise: 48;
+    readonly weakmap: 40;
+    readonly weakset: 40;
+};
+/**
+ * Optional user hook. Declare a `sizeof` symbol key on any object to return
+ * a precomputed size (in bytes); the walker will honor it and skip recursion.
+ *
+ * @example
+ * ```ts
+ * const SIZEOF = Symbol.for("sizeof");
+ * class MyCache { [SIZEOF]() { return this.bytes; } }
+ * ```
+ */
+declare const SIZEOF_SYMBOL: unique symbol;
+/**
+ * Estimate the approximate retained memory (in bytes) of a JS value.
+ *
+ * Handles primitives, plain objects, arrays, Maps, Sets, ArrayBuffers +
+ * TypedArrays (shared-buffer dedup), Date, RegExp, Error, URL, Promise,
+ * WeakMap, WeakSet, nested combinations. Cyclic refs are counted once.
+ *
+ * @param value - The value to measure.
+ * @returns Approximate size in bytes.
+ */
+declare function sizeof(value: unknown): number;
+
+/**
+ * GraphCodec — pluggable serialization for graph snapshots (Phase 8.6).
+ *
+ * Design reference: `archive/docs/SESSION-serialization-memory-footprint.md`
+ *
+ * The codec interface decouples snapshot format from graph internals.
+ * Default is JSON (current behavior). DAG-CBOR and compressed variants
+ * ship as optional codecs. FlatBuffers/Arrow for advanced tiers.
+ *
+ * Tiered representation:
+ *   HOT  — JS objects (live propagation, no codec involved)
+ *   WARM — DAG-CBOR in-memory buffer (lazy hydration, delta checkpoints)
+ *   COLD — Arrow/Parquet (bulk storage, ML pipelines, archival)
+ *   PEEK — FlatBuffers (zero-copy read from dormant graph)
+ *
+ * Wire-protocol envelope (v1):
+ *
+ *   [envelope_v=1: u8][name_len: u8][name: utf8][codec_v: u16 BE][payload: rest]
+ *
+ * `graph.snapshot({format: "bytes", codec: name})` wraps the codec's
+ * `encode` output in this envelope; `Graph.decode(bytes)` auto-dispatches
+ * via the config's codec registry — no out-of-band content-type needed.
+ */
+
+/**
+ * Encode/decode graph snapshots to/from binary.
+ *
+ * Implementations must be deterministic: `encode(x)` always produces the
+ * same bytes for the same input. This is critical for CID computation (V1)
+ * and snapshot hash-comparison.
+ */
+interface GraphCodec {
+    /** Human-readable name; used as the lookup key in the envelope and config registry. */
+    readonly name: string;
+    /**
+     * Codec version. Bumps on breaking wire format changes; `decode` receives
+     * this via the envelope so codecs can dispatch on historical layouts.
+     * Must fit in a `u16` (0–65535).
+     */
+    readonly version: number;
+    /** MIME-like content type identifier (e.g. `"application/dag-cbor+zstd"`). */
+    readonly contentType: string;
+    /** Encode a snapshot to binary. */
+    encode(snapshot: GraphPersistSnapshot): Uint8Array;
+    /**
+     * Decode binary back to a snapshot.
+     *
+     * `codecVersion` is the version that produced `buffer` (read from the
+     * envelope). Omit when the caller is sure of the version (tests, one-shot
+     * round-trips). Codecs that support multiple historical layouts dispatch
+     * on this value.
+     *
+     * For lazy codecs, this may return a proxy that decodes nodes on access
+     * (see {@link LazyGraphCodec}).
+     */
+    decode(buffer: Uint8Array, codecVersion?: number): GraphPersistSnapshot;
+}
+/**
+ * Extended codec that supports lazy (on-demand) node decoding.
+ *
+ * `decodeLazy` returns a snapshot where `nodes` is a Proxy — individual
+ * nodes are decoded only when accessed. This enables near-zero cold-start
+ * for large graphs (decode envelope + topology, skip node values until read).
+ */
+interface LazyGraphCodec extends GraphCodec {
+    /** Decode envelope and topology; defer node value decoding to access time. */
+    decodeLazy(buffer: Uint8Array, codecVersion?: number): GraphPersistSnapshot;
+}
+/**
+ * WAL entry. Unified with {@link GraphCheckpointRecord} — every record
+ * already carries `mode` / `seq` / `timestamp_ns` / `format_version`, so the
+ * WAL is just an ordered list of records. `replayWAL` walks this list.
+ */
+type WALEntry = GraphCheckpointRecord;
+/**
+ * Policy for evicting dormant subgraphs to reduce memory.
+ *
+ * When a subgraph hasn't propagated for `idleTimeoutMs`, it is serialized
+ * using the graph's codec and JS objects are released. Re-hydrated on next
+ * access (read, propagation, describe).
+ */
+interface EvictionPolicy {
+    /** Milliseconds of inactivity before eviction. */
+    idleTimeoutMs: number;
+    /** Codec to use for serializing evicted subgraphs (default: graph's codec). */
+    codec?: GraphCodec;
+}
+/** Metadata about an evicted subgraph, exposed via describe(). */
+interface EvictedSubgraphInfo {
+    /** True if currently evicted (serialized, JS objects released). */
+    evicted: true;
+    /** Wall-clock ns of last propagation before eviction. */
+    lastActiveNs: bigint;
+    /** Size of serialized buffer in bytes. */
+    serializedBytes: number;
+    /** Codec used for serialization. */
+    codecName: string;
+}
+/**
+ * Default JSON codec. Wraps `JSON.stringify`/`JSON.parse` with deterministic
+ * key ordering (matching current `snapshot()` behavior).
+ */
+declare const JsonCodec: GraphCodec;
+/**
+ * Create a DAG-CBOR codec.
+ *
+ * Requires `@ipld/dag-cbor` as a peer dependency. ~40-50% smaller than JSON,
+ * deterministic encoding (required for V1 CID), CID links as native type.
+ *
+ * @example
+ * ```ts
+ * import * as dagCbor from "@ipld/dag-cbor";
+ * const codec = createDagCborCodec(dagCbor);
+ * config.registerCodec(codec);
+ * const bytes = graph.snapshot({ format: "bytes", codec: "dag-cbor" });
+ * ```
+ */
+declare function createDagCborCodec(dagCbor: {
+    encode: (value: unknown) => Uint8Array;
+    decode: (bytes: Uint8Array) => unknown;
+}): GraphCodec;
+/**
+ * Create a DAG-CBOR + zstd codec. ~80-90% smaller than JSON.
+ *
+ * Requires `@ipld/dag-cbor` and a zstd implementation (e.g. `fzstd` for
+ * browser, `node:zlib` for Node.js).
+ *
+ * @example
+ * ```ts
+ * import * as dagCbor from "@ipld/dag-cbor";
+ * import { compressSync, decompressSync } from "fzstd";
+ * const codec = createDagCborZstdCodec(dagCbor, { compressSync, decompressSync });
+ * config.registerCodec(codec);
+ * ```
+ */
+declare function createDagCborZstdCodec(dagCbor: {
+    encode: (value: unknown) => Uint8Array;
+    decode: (bytes: Uint8Array) => unknown;
+}, zstd: {
+    compressSync: (data: Uint8Array) => Uint8Array;
+    decompressSync: (data: Uint8Array) => Uint8Array;
+}): GraphCodec;
+/** Current envelope format version. Bump on breaking layout changes. */
+declare const ENVELOPE_VERSION = 1;
+/**
+ * Prepend the v1 envelope to `payload` identifying `codec`. The resulting
+ * bytes are self-describing — any caller with access to the registering
+ * {@link GraphReFlyConfig} can {@link decodeEnvelope} without knowing the
+ * codec up front.
+ *
+ * Layout:
+ * `[envelope_v=1: u8][name_len: u8][name: utf8][codec_v: u16 BE][payload: rest]`
+ *
+ * @throws If `codec.name` encodes to more than 255 UTF-8 bytes or
+ *   `codec.version` doesn't fit in a u16.
+ */
+declare function encodeEnvelope(codec: Pick<GraphCodec, "name" | "version">, payload: Uint8Array): Uint8Array;
+/**
+ * Inverse of {@link encodeEnvelope}. Reads the header, resolves the codec
+ * via `config.lookupCodec(name)`, and returns the codec + its version + the
+ * inner payload slice. The caller feeds `payload` to `codec.decode(payload,
+ * codecVersion)` — or uses {@link Graph.decode} which does both steps.
+ *
+ * @throws If the envelope is truncated, the version is unsupported, or the
+ *   named codec isn't registered on `config`.
+ */
+declare function decodeEnvelope(bytes: Uint8Array, config: GraphReFlyConfig): {
+    codec: GraphCodec;
+    codecVersion: number;
+    payload: Uint8Array;
+};
+/**
+ * Register the built-in {@link JsonCodec} on a config. Called once on
+ * `defaultConfig` at module load so `graph.snapshot({format: "bytes", codec:
+ * "json"})` works out of the box. Test / isolated configs should call this
+ * manually before the first node is created.
+ */
+declare function registerBuiltinCodecs(config: GraphReFlyConfig): void;
+/**
+ * Reconstruct a snapshot from a WAL (sequence of {@link GraphCheckpointRecord}s).
+ *
+ * - Must start with a `"full"` record carrying a baseline snapshot — that's
+ *   the anchor {@link Graph.attachStorage} always emits on the first flush
+ *   of any tier (and every `compactEvery`-th flush thereafter).
+ * - Subsequent `"full"` entries (compaction points) **replace** the result
+ *   wholesale.
+ * - `"diff"` entries roll forward by applying the structural diff —
+ *   added nodes (via `nodesAddedFull`), removed nodes, and changed fields
+ *   are reflected into the accumulated snapshot.
+ *
+ * Validates monotonic `seq` progression across entries.
+ */
+declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
+
+/**
+ * Graph container: registry, wiring, introspection (Phase 1).
+ */
+
+declare const index_DescribeFilter: typeof DescribeFilter;
+declare const index_ENVELOPE_VERSION: typeof ENVELOPE_VERSION;
+type index_EvictedSubgraphInfo = EvictedSubgraphInfo;
+type index_EvictionPolicy = EvictionPolicy;
+declare const index_GRAPH_META_SEGMENT: typeof GRAPH_META_SEGMENT;
+declare const index_Graph: typeof Graph;
+declare const index_GraphActorOptions: typeof GraphActorOptions;
+declare const index_GraphAttachStorageOptions: typeof GraphAttachStorageOptions;
+declare const index_GraphCheckpointRecord: typeof GraphCheckpointRecord;
+type index_GraphCodec = GraphCodec;
+declare const index_GraphDescribeOptions: typeof GraphDescribeOptions;
+declare const index_GraphDescribeOutput: typeof GraphDescribeOutput;
+declare const index_GraphDiagramDirection: typeof GraphDiagramDirection;
+declare const index_GraphDiagramOptions: typeof GraphDiagramOptions;
+declare const index_GraphDiffChange: typeof GraphDiffChange;
+declare const index_GraphDiffResult: typeof GraphDiffResult;
+declare const index_GraphFactoryContext: typeof GraphFactoryContext;
+declare const index_GraphNodeFactory: typeof GraphNodeFactory;
+declare const index_GraphObserveAll: typeof GraphObserveAll;
+declare const index_GraphObserveOne: typeof GraphObserveOne;
+declare const index_GraphOptions: typeof GraphOptions;
+declare const index_GraphPersistSnapshot: typeof GraphPersistSnapshot;
+declare const index_GraphProfileOptions: typeof GraphProfileOptions;
+declare const index_GraphProfileResult: typeof GraphProfileResult;
+declare const index_GraphVersionChange: typeof GraphVersionChange;
+declare const index_GraphWALDiff: typeof GraphWALDiff;
+declare const index_JsonCodec: typeof JsonCodec;
+type index_LazyGraphCodec = LazyGraphCodec;
+declare const index_NodeProfile: typeof NodeProfile;
+declare const index_ObserveDetail: typeof ObserveDetail;
+declare const index_ObserveEvent: typeof ObserveEvent;
+declare const index_ObserveOptions: typeof ObserveOptions;
+declare const index_ObserveResult: typeof ObserveResult;
+declare const index_ObserveTheme: typeof ObserveTheme;
+declare const index_ObserveThemeName: typeof ObserveThemeName;
+declare const index_ReachableDirection: typeof ReachableDirection;
+declare const index_ReachableOptions: typeof ReachableOptions;
+declare const index_SIZEOF_SYMBOL: typeof SIZEOF_SYMBOL;
+declare const index_TraceEntry: typeof TraceEntry;
+type index_WALEntry = WALEntry;
+declare const index_createDagCborCodec: typeof createDagCborCodec;
+declare const index_createDagCborZstdCodec: typeof createDagCborZstdCodec;
+declare const index_decodeEnvelope: typeof decodeEnvelope;
+declare const index_diffForWAL: typeof diffForWAL;
+declare const index_encodeEnvelope: typeof encodeEnvelope;
+declare const index_graphProfile: typeof graphProfile;
+declare const index_reachable: typeof reachable;
+declare const index_registerBuiltinCodecs: typeof registerBuiltinCodecs;
+declare const index_replayWAL: typeof replayWAL;
+declare const index_sizeof: typeof sizeof;
+declare namespace index {
+  export { index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_TraceEntry as TraceEntry, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_graphProfile as graphProfile, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof };
+}
+
+export { ENVELOPE_VERSION as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, OVERHEAD as O, SIZEOF_SYMBOL as S, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, createDagCborCodec as c, createDagCborZstdCodec as d, decodeEnvelope as e, encodeEnvelope as f, replayWAL as g, index as i, registerBuiltinCodecs as r, sizeof as s };

package/dist/index-Dy04P4W3.d.cts

@@ -0,0 +1,315 @@
+import { k as GraphReFlyConfig } from './node-C5UD5MGq.cjs';
+import { r as GraphPersistSnapshot, g as GraphCheckpointRecord, D as DescribeFilter, e as GRAPH_META_SEGMENT, G as Graph, f as GraphActorOptions, b as GraphAttachStorageOptions, h as GraphDescribeOptions, i as GraphDescribeOutput, j as GraphDiagramDirection, k as GraphDiagramOptions, l as GraphDiffChange, m as GraphDiffResult, n as GraphFactoryContext, o as GraphNodeFactory, p as GraphObserveAll, q as GraphObserveOne, a as GraphOptions, d as GraphProfileOptions, c as GraphProfileResult, s as GraphVersionChange, t as GraphWALDiff, N as NodeProfile, O as ObserveDetail, u as ObserveEvent, v as ObserveOptions, w as ObserveResult, x as ObserveTheme, y as ObserveThemeName, R as ReachableDirection, z as ReachableOptions, T as TraceEntry, A as diffForWAL, B as graphProfile, C as reachable } from './graph-ab1yPwIB.cjs';
+
+/**
+ * Approximate in-memory size estimation for arbitrary JS values.
+ *
+ * Iterative walk with cycle detection via `WeakSet`. V8-tuned overhead
+ * heuristics. Not exact — approximate enough for profiling and hotspot
+ * detection.
+ *
+ * Use cases: `graphProfile` (per-node value size), reactive data structure
+ * memory audits, heuristic cache admission.
+ *
+ * @module
+ */
+/** Approximate per-type overhead in bytes (V8 heuristics). */
+declare const OVERHEAD: {
+    readonly object: 56;
+    readonly array: 64;
+    readonly string: 40;
+    readonly number: 8;
+    readonly boolean: 4;
+    readonly null: 0;
+    readonly undefined: 0;
+    readonly symbol: 40;
+    readonly bigint: 16;
+    readonly function: 120;
+    readonly map: 72;
+    readonly set: 72;
+    readonly mapEntry: 40;
+    readonly setEntry: 24;
+    readonly date: 24;
+    readonly regexp: 48;
+    readonly error: 64;
+    readonly url: 80;
+    readonly promise: 48;
+    readonly weakmap: 40;
+    readonly weakset: 40;
+};
+/**
+ * Optional user hook. Declare a `sizeof` symbol key on any object to return
+ * a precomputed size (in bytes); the walker will honor it and skip recursion.
+ *
+ * @example
+ * ```ts
+ * const SIZEOF = Symbol.for("sizeof");
+ * class MyCache { [SIZEOF]() { return this.bytes; } }
+ * ```
+ */
+declare const SIZEOF_SYMBOL: unique symbol;
+/**
+ * Estimate the approximate retained memory (in bytes) of a JS value.
+ *
+ * Handles primitives, plain objects, arrays, Maps, Sets, ArrayBuffers +
+ * TypedArrays (shared-buffer dedup), Date, RegExp, Error, URL, Promise,
+ * WeakMap, WeakSet, nested combinations. Cyclic refs are counted once.
+ *
+ * @param value - The value to measure.
+ * @returns Approximate size in bytes.
+ */
+declare function sizeof(value: unknown): number;
+
+/**
+ * GraphCodec — pluggable serialization for graph snapshots (Phase 8.6).
+ *
+ * Design reference: `archive/docs/SESSION-serialization-memory-footprint.md`
+ *
+ * The codec interface decouples snapshot format from graph internals.
+ * Default is JSON (current behavior). DAG-CBOR and compressed variants
+ * ship as optional codecs. FlatBuffers/Arrow for advanced tiers.
+ *
+ * Tiered representation:
+ *   HOT  — JS objects (live propagation, no codec involved)
+ *   WARM — DAG-CBOR in-memory buffer (lazy hydration, delta checkpoints)
+ *   COLD — Arrow/Parquet (bulk storage, ML pipelines, archival)
+ *   PEEK — FlatBuffers (zero-copy read from dormant graph)
+ *
+ * Wire-protocol envelope (v1):
+ *
+ *   [envelope_v=1: u8][name_len: u8][name: utf8][codec_v: u16 BE][payload: rest]
+ *
+ * `graph.snapshot({format: "bytes", codec: name})` wraps the codec's
+ * `encode` output in this envelope; `Graph.decode(bytes)` auto-dispatches
+ * via the config's codec registry — no out-of-band content-type needed.
+ */
+
+/**
+ * Encode/decode graph snapshots to/from binary.
+ *
+ * Implementations must be deterministic: `encode(x)` always produces the
+ * same bytes for the same input. This is critical for CID computation (V1)
+ * and snapshot hash-comparison.
+ */
+interface GraphCodec {
+    /** Human-readable name; used as the lookup key in the envelope and config registry. */
+    readonly name: string;
+    /**
+     * Codec version. Bumps on breaking wire format changes; `decode` receives
+     * this via the envelope so codecs can dispatch on historical layouts.
+     * Must fit in a `u16` (0–65535).
+     */
+    readonly version: number;
+    /** MIME-like content type identifier (e.g. `"application/dag-cbor+zstd"`). */
+    readonly contentType: string;
+    /** Encode a snapshot to binary. */
+    encode(snapshot: GraphPersistSnapshot): Uint8Array;
+    /**
+     * Decode binary back to a snapshot.
+     *
+     * `codecVersion` is the version that produced `buffer` (read from the
+     * envelope). Omit when the caller is sure of the version (tests, one-shot
+     * round-trips). Codecs that support multiple historical layouts dispatch
+     * on this value.
+     *
+     * For lazy codecs, this may return a proxy that decodes nodes on access
+     * (see {@link LazyGraphCodec}).
+     */
+    decode(buffer: Uint8Array, codecVersion?: number): GraphPersistSnapshot;
+}
+/**
+ * Extended codec that supports lazy (on-demand) node decoding.
+ *
+ * `decodeLazy` returns a snapshot where `nodes` is a Proxy — individual
+ * nodes are decoded only when accessed. This enables near-zero cold-start
+ * for large graphs (decode envelope + topology, skip node values until read).
+ */
+interface LazyGraphCodec extends GraphCodec {
+    /** Decode envelope and topology; defer node value decoding to access time. */
+    decodeLazy(buffer: Uint8Array, codecVersion?: number): GraphPersistSnapshot;
+}
+/**
+ * WAL entry. Unified with {@link GraphCheckpointRecord} — every record
+ * already carries `mode` / `seq` / `timestamp_ns` / `format_version`, so the
+ * WAL is just an ordered list of records. `replayWAL` walks this list.
+ */
+type WALEntry = GraphCheckpointRecord;
+/**
+ * Policy for evicting dormant subgraphs to reduce memory.
+ *
+ * When a subgraph hasn't propagated for `idleTimeoutMs`, it is serialized
+ * using the graph's codec and JS objects are released. Re-hydrated on next
+ * access (read, propagation, describe).
+ */
+interface EvictionPolicy {
+    /** Milliseconds of inactivity before eviction. */
+    idleTimeoutMs: number;
+    /** Codec to use for serializing evicted subgraphs (default: graph's codec). */
+    codec?: GraphCodec;
+}
+/** Metadata about an evicted subgraph, exposed via describe(). */
+interface EvictedSubgraphInfo {
+    /** True if currently evicted (serialized, JS objects released). */
+    evicted: true;
+    /** Wall-clock ns of last propagation before eviction. */
+    lastActiveNs: bigint;
+    /** Size of serialized buffer in bytes. */
+    serializedBytes: number;
+    /** Codec used for serialization. */
+    codecName: string;
+}
+/**
+ * Default JSON codec. Wraps `JSON.stringify`/`JSON.parse` with deterministic
+ * key ordering (matching current `snapshot()` behavior).
+ */
+declare const JsonCodec: GraphCodec;
+/**
+ * Create a DAG-CBOR codec.
+ *
+ * Requires `@ipld/dag-cbor` as a peer dependency. ~40-50% smaller than JSON,
+ * deterministic encoding (required for V1 CID), CID links as native type.
+ *
+ * @example
+ * ```ts
+ * import * as dagCbor from "@ipld/dag-cbor";
+ * const codec = createDagCborCodec(dagCbor);
+ * config.registerCodec(codec);
+ * const bytes = graph.snapshot({ format: "bytes", codec: "dag-cbor" });
+ * ```
+ */
+declare function createDagCborCodec(dagCbor: {
+    encode: (value: unknown) => Uint8Array;
+    decode: (bytes: Uint8Array) => unknown;
+}): GraphCodec;
+/**
+ * Create a DAG-CBOR + zstd codec. ~80-90% smaller than JSON.
+ *
+ * Requires `@ipld/dag-cbor` and a zstd implementation (e.g. `fzstd` for
+ * browser, `node:zlib` for Node.js).
+ *
+ * @example
+ * ```ts
+ * import * as dagCbor from "@ipld/dag-cbor";
+ * import { compressSync, decompressSync } from "fzstd";
+ * const codec = createDagCborZstdCodec(dagCbor, { compressSync, decompressSync });
+ * config.registerCodec(codec);
+ * ```
+ */
+declare function createDagCborZstdCodec(dagCbor: {
+    encode: (value: unknown) => Uint8Array;
+    decode: (bytes: Uint8Array) => unknown;
+}, zstd: {
+    compressSync: (data: Uint8Array) => Uint8Array;
+    decompressSync: (data: Uint8Array) => Uint8Array;
+}): GraphCodec;
+/** Current envelope format version. Bump on breaking layout changes. */
+declare const ENVELOPE_VERSION = 1;
+/**
+ * Prepend the v1 envelope to `payload` identifying `codec`. The resulting
+ * bytes are self-describing — any caller with access to the registering
+ * {@link GraphReFlyConfig} can {@link decodeEnvelope} without knowing the
+ * codec up front.
+ *
+ * Layout:
+ * `[envelope_v=1: u8][name_len: u8][name: utf8][codec_v: u16 BE][payload: rest]`
+ *
+ * @throws If `codec.name` encodes to more than 255 UTF-8 bytes or
+ *   `codec.version` doesn't fit in a u16.
+ */
+declare function encodeEnvelope(codec: Pick<GraphCodec, "name" | "version">, payload: Uint8Array): Uint8Array;
+/**
+ * Inverse of {@link encodeEnvelope}. Reads the header, resolves the codec
+ * via `config.lookupCodec(name)`, and returns the codec + its version + the
+ * inner payload slice. The caller feeds `payload` to `codec.decode(payload,
+ * codecVersion)` — or uses {@link Graph.decode} which does both steps.
+ *
+ * @throws If the envelope is truncated, the version is unsupported, or the
+ *   named codec isn't registered on `config`.
+ */
+declare function decodeEnvelope(bytes: Uint8Array, config: GraphReFlyConfig): {
+    codec: GraphCodec;
+    codecVersion: number;
+    payload: Uint8Array;
+};
+/**
+ * Register the built-in {@link JsonCodec} on a config. Called once on
+ * `defaultConfig` at module load so `graph.snapshot({format: "bytes", codec:
+ * "json"})` works out of the box. Test / isolated configs should call this
+ * manually before the first node is created.
+ */
+declare function registerBuiltinCodecs(config: GraphReFlyConfig): void;
+/**
+ * Reconstruct a snapshot from a WAL (sequence of {@link GraphCheckpointRecord}s).
+ *
+ * - Must start with a `"full"` record carrying a baseline snapshot — that's
+ *   the anchor {@link Graph.attachStorage} always emits on the first flush
+ *   of any tier (and every `compactEvery`-th flush thereafter).
+ * - Subsequent `"full"` entries (compaction points) **replace** the result
+ *   wholesale.
+ * - `"diff"` entries roll forward by applying the structural diff —
+ *   added nodes (via `nodesAddedFull`), removed nodes, and changed fields
+ *   are reflected into the accumulated snapshot.
+ *
+ * Validates monotonic `seq` progression across entries.
+ */
+declare function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot;
+
+/**
+ * Graph container: registry, wiring, introspection (Phase 1).
+ */
+
+declare const index_DescribeFilter: typeof DescribeFilter;
+declare const index_ENVELOPE_VERSION: typeof ENVELOPE_VERSION;
+type index_EvictedSubgraphInfo = EvictedSubgraphInfo;
+type index_EvictionPolicy = EvictionPolicy;
+declare const index_GRAPH_META_SEGMENT: typeof GRAPH_META_SEGMENT;
+declare const index_Graph: typeof Graph;
+declare const index_GraphActorOptions: typeof GraphActorOptions;
+declare const index_GraphAttachStorageOptions: typeof GraphAttachStorageOptions;
+declare const index_GraphCheckpointRecord: typeof GraphCheckpointRecord;
+type index_GraphCodec = GraphCodec;
+declare const index_GraphDescribeOptions: typeof GraphDescribeOptions;
+declare const index_GraphDescribeOutput: typeof GraphDescribeOutput;
+declare const index_GraphDiagramDirection: typeof GraphDiagramDirection;
+declare const index_GraphDiagramOptions: typeof GraphDiagramOptions;
+declare const index_GraphDiffChange: typeof GraphDiffChange;
+declare const index_GraphDiffResult: typeof GraphDiffResult;
+declare const index_GraphFactoryContext: typeof GraphFactoryContext;
+declare const index_GraphNodeFactory: typeof GraphNodeFactory;
+declare const index_GraphObserveAll: typeof GraphObserveAll;
+declare const index_GraphObserveOne: typeof GraphObserveOne;
+declare const index_GraphOptions: typeof GraphOptions;
+declare const index_GraphPersistSnapshot: typeof GraphPersistSnapshot;
+declare const index_GraphProfileOptions: typeof GraphProfileOptions;
+declare const index_GraphProfileResult: typeof GraphProfileResult;
+declare const index_GraphVersionChange: typeof GraphVersionChange;
+declare const index_GraphWALDiff: typeof GraphWALDiff;
+declare const index_JsonCodec: typeof JsonCodec;
+type index_LazyGraphCodec = LazyGraphCodec;
+declare const index_NodeProfile: typeof NodeProfile;
+declare const index_ObserveDetail: typeof ObserveDetail;
+declare const index_ObserveEvent: typeof ObserveEvent;
+declare const index_ObserveOptions: typeof ObserveOptions;
+declare const index_ObserveResult: typeof ObserveResult;
+declare const index_ObserveTheme: typeof ObserveTheme;
+declare const index_ObserveThemeName: typeof ObserveThemeName;
+declare const index_ReachableDirection: typeof ReachableDirection;
+declare const index_ReachableOptions: typeof ReachableOptions;
+declare const index_SIZEOF_SYMBOL: typeof SIZEOF_SYMBOL;
+declare const index_TraceEntry: typeof TraceEntry;
+type index_WALEntry = WALEntry;
+declare const index_createDagCborCodec: typeof createDagCborCodec;
+declare const index_createDagCborZstdCodec: typeof createDagCborZstdCodec;
+declare const index_decodeEnvelope: typeof decodeEnvelope;
+declare const index_diffForWAL: typeof diffForWAL;
+declare const index_encodeEnvelope: typeof encodeEnvelope;
+declare const index_graphProfile: typeof graphProfile;
+declare const index_reachable: typeof reachable;
+declare const index_registerBuiltinCodecs: typeof registerBuiltinCodecs;
+declare const index_replayWAL: typeof replayWAL;
+declare const index_sizeof: typeof sizeof;
+declare namespace index {
+  export { index_DescribeFilter as DescribeFilter, index_ENVELOPE_VERSION as ENVELOPE_VERSION, type index_EvictedSubgraphInfo as EvictedSubgraphInfo, type index_EvictionPolicy as EvictionPolicy, index_GRAPH_META_SEGMENT as GRAPH_META_SEGMENT, index_Graph as Graph, index_GraphActorOptions as GraphActorOptions, index_GraphAttachStorageOptions as GraphAttachStorageOptions, index_GraphCheckpointRecord as GraphCheckpointRecord, type index_GraphCodec as GraphCodec, index_GraphDescribeOptions as GraphDescribeOptions, index_GraphDescribeOutput as GraphDescribeOutput, index_GraphDiagramDirection as GraphDiagramDirection, index_GraphDiagramOptions as GraphDiagramOptions, index_GraphDiffChange as GraphDiffChange, index_GraphDiffResult as GraphDiffResult, index_GraphFactoryContext as GraphFactoryContext, index_GraphNodeFactory as GraphNodeFactory, index_GraphObserveAll as GraphObserveAll, index_GraphObserveOne as GraphObserveOne, index_GraphOptions as GraphOptions, index_GraphPersistSnapshot as GraphPersistSnapshot, index_GraphProfileOptions as GraphProfileOptions, index_GraphProfileResult as GraphProfileResult, index_GraphVersionChange as GraphVersionChange, index_GraphWALDiff as GraphWALDiff, index_JsonCodec as JsonCodec, type index_LazyGraphCodec as LazyGraphCodec, index_NodeProfile as NodeProfile, index_ObserveDetail as ObserveDetail, index_ObserveEvent as ObserveEvent, index_ObserveOptions as ObserveOptions, index_ObserveResult as ObserveResult, index_ObserveTheme as ObserveTheme, index_ObserveThemeName as ObserveThemeName, index_ReachableDirection as ReachableDirection, index_ReachableOptions as ReachableOptions, OVERHEAD as SIZEOF_OVERHEAD, index_SIZEOF_SYMBOL as SIZEOF_SYMBOL, index_TraceEntry as TraceEntry, type index_WALEntry as WALEntry, index_createDagCborCodec as createDagCborCodec, index_createDagCborZstdCodec as createDagCborZstdCodec, index_decodeEnvelope as decodeEnvelope, index_diffForWAL as diffForWAL, index_encodeEnvelope as encodeEnvelope, index_graphProfile as graphProfile, index_reachable as reachable, index_registerBuiltinCodecs as registerBuiltinCodecs, index_replayWAL as replayWAL, index_sizeof as sizeof };
+}
+
+export { ENVELOPE_VERSION as E, type GraphCodec as G, JsonCodec as J, type LazyGraphCodec as L, OVERHEAD as O, SIZEOF_SYMBOL as S, type WALEntry as W, type EvictedSubgraphInfo as a, type EvictionPolicy as b, createDagCborCodec as c, createDagCborZstdCodec as d, decodeEnvelope as e, encodeEnvelope as f, replayWAL as g, index as i, registerBuiltinCodecs as r, sizeof as s };