@graphrefly/ts 0.0.0

package/dist/adapters/observe-storage.cjs

@@ -0,0 +1,260 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/adapters/observe-storage.ts
+var observe_storage_exports = {};
+__export(observe_storage_exports, {
+  attachObserveEventLog: () => attachObserveEventLog,
+  attachObserveSink: () => attachObserveSink
+});
+module.exports = __toCommonJS(observe_storage_exports);
+
+// src/storage/scalar.ts
+var NON_NEGATIVE_DECIMAL_INTEGER_RE = /^(0|[1-9]\d*)$/;
+function isNonNegativeDecimalIntegerString(value) {
+  return typeof value === "string" && NON_NEGATIVE_DECIMAL_INTEGER_RE.test(value);
+}
+function assertNonNegativeDecimalIntegerString(value, label = "decimal integer") {
+  if (!isNonNegativeDecimalIntegerString(value)) {
+    throw new TypeError(`${label} must be a canonical non-negative decimal integer string`);
+  }
+  return value;
+}
+function bigIntToNonNegativeDecimalString(value) {
+  if (value < 0n) {
+    throw new TypeError("decimal integer must be non-negative");
+  }
+  return value.toString();
+}
+
+// src/storage/change.ts
+function nowNs() {
+  return bigIntToNonNegativeDecimalString(BigInt(Date.now()) * 1000000n);
+}
+function envelopeChange(change, opts) {
+  const envelope = {
+    lifecycle: opts.lifecycle ?? "data",
+    structure: opts.structure,
+    version: opts.version ?? 1,
+    t_ns: opts.t_ns ?? nowNs(),
+    ...opts.seq === void 0 ? {} : { seq: opts.seq },
+    change
+  };
+  return assertChangeEnvelope(envelope);
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isLifecycle(value) {
+  return value === "spec" || value === "data" || value === "ownership";
+}
+function assertChangeEnvelope(value) {
+  if (!isRecord(value)) throw new TypeError("changeEnvelopeCodec: frame must be an object");
+  if (!isLifecycle(value.lifecycle)) {
+    throw new TypeError("changeEnvelopeCodec: lifecycle must be spec, data, or ownership");
+  }
+  if (typeof value.structure !== "string" || value.structure.length === 0) {
+    throw new TypeError("changeEnvelopeCodec: structure must be a non-empty string");
+  }
+  if ((typeof value.version !== "number" || !Number.isFinite(value.version)) && typeof value.version !== "string") {
+    throw new TypeError("changeEnvelopeCodec: version must be a finite number or string");
+  }
+  assertNonNegativeDecimalIntegerString(value.t_ns, "changeEnvelopeCodec: t_ns");
+  if (value.seq !== void 0 && (!Number.isSafeInteger(value.seq) || value.seq < 0)) {
+    throw new TypeError(
+      "changeEnvelopeCodec: seq must be a non-negative safe integer when present"
+    );
+  }
+  if (!Object.hasOwn(value, "change")) {
+    throw new TypeError("changeEnvelopeCodec: change payload is required");
+  }
+  return value;
+}
+
+// src/storage/observe-event-log.ts
+function observeEventFrame(event, value, opts = {}) {
+  return {
+    ...envelopeChange(value, {
+      lifecycle: "data",
+      structure: "observe-event",
+      version: 1,
+      seq: event.seq
+    }),
+    structure: "observe-event",
+    observeSeq: event.seq,
+    path: event.path,
+    ...opts.stream === void 0 ? {} : { stream: opts.stream }
+  };
+}
+
+// src/adapters/observe-storage.ts
+function attachObserveSink(graph, sink, opts = {}) {
+  const { map, onError, path } = opts;
+  const queue = [];
+  const disposeDone = [];
+  let draining = false;
+  let disposeRequested = false;
+  let disposed = false;
+  function report(error, ctx) {
+    if (!onError) return;
+    try {
+      onError(error, ctx);
+    } catch {
+    }
+  }
+  function callDone(done) {
+    try {
+      done?.();
+    } catch {
+    }
+  }
+  function run(item) {
+    switch (item.kind) {
+      case "write":
+        return sink.write(item.value);
+      case "flush":
+        return sink.flush?.();
+      case "rollback":
+        return sink.rollback?.();
+      case "dispose":
+        return sink.dispose?.();
+    }
+  }
+  function finish(item) {
+    if (item.kind === "dispose") {
+      disposed = true;
+      for (const done of disposeDone.splice(0)) callDone(done);
+    } else if (item.kind !== "write") {
+      callDone(item.done);
+    }
+    draining = false;
+    drain();
+  }
+  function fail(item, error) {
+    if (item.kind === "write")
+      report(error, { phase: "write", event: item.event, value: item.value });
+    else report(error, { phase: item.kind });
+    finish(item);
+  }
+  function chainThenable(item, value) {
+    if (typeof value !== "object" && typeof value !== "function" || value === null) return false;
+    let then;
+    try {
+      then = value.then;
+    } catch (error) {
+      fail(item, error);
+      return true;
+    }
+    if (typeof then !== "function") return false;
+    let settled = false;
+    const settle = (next) => {
+      if (settled) return;
+      settled = true;
+      next();
+    };
+    try {
+      then.call(
+        value,
+        () => settle(() => finish(item)),
+        (error) => settle(() => fail(item, error))
+      );
+    } catch (error) {
+      settle(() => fail(item, error));
+    }
+    return true;
+  }
+  function drain() {
+    if (draining) return;
+    const item = queue.shift();
+    if (!item) return;
+    draining = true;
+    let result;
+    try {
+      result = run(item);
+    } catch (error) {
+      fail(item, error);
+      return;
+    }
+    if (chainThenable(item, result)) return;
+    finish(item);
+  }
+  function enqueueBarrier(kind, done) {
+    if (disposeRequested) {
+      callDone(done);
+      return;
+    }
+    queue.push({ kind, done });
+    drain();
+  }
+  const stop = graph.observe(path).subscribe((event) => {
+    if (disposeRequested) return;
+    let value;
+    try {
+      value = map ? map(event) : event;
+    } catch (error) {
+      report(error, { phase: "map", event });
+      return;
+    }
+    if (value === void 0) return;
+    queue.push({ kind: "write", event, value });
+    drain();
+  });
+  return {
+    flush(done) {
+      enqueueBarrier("flush", done);
+    },
+    rollback(done) {
+      enqueueBarrier("rollback", done);
+    },
+    dispose(done) {
+      if (disposed) {
+        callDone(done);
+        return;
+      }
+      if (done) disposeDone.push(done);
+      if (disposeRequested) {
+        return;
+      }
+      disposeRequested = true;
+      stop();
+      queue.push({ kind: "dispose" });
+      drain();
+    }
+  };
+}
+function attachObserveEventLog(graph, log, opts = {}) {
+  return attachObserveSink(
+    graph,
+    { write: (frame) => log.append(frame).then(() => void 0) },
+    {
+      path: opts.path,
+      map: (event) => {
+        const value = opts.map ? opts.map(event) : event;
+        return value === void 0 ? void 0 : observeEventFrame(event, value, opts);
+      },
+      onError: opts.onError
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  attachObserveEventLog,
+  attachObserveSink
+});
+//# sourceMappingURL=observe-storage.cjs.map

package/dist/adapters/observe-storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/observe-storage.ts","../../src/storage/scalar.ts","../../src/storage/change.ts","../../src/storage/observe-event-log.ts"],"sourcesContent":["/**\n * Graph-bound observe storage adapters.\n *\n * Passive storage lives under ../storage. This subpath owns bridges that need\n * Graph.observe() and therefore sit above both graph and passive storage (D125).\n */\n\nimport type { Graph } from \"../graph/graph.js\";\nimport type { ObserveEvent } from \"../graph/inspect.js\";\nimport type { AppendLogStorageTier } from \"../storage/append-log.js\";\nimport {\n\ttype ObserveEventFrame,\n\ttype ObserveEventLogPage,\n\tobserveEventFrame,\n} from \"../storage/observe-event-log.js\";\n\n/** Adapter-owned sink for observed graph events (D57/D74/D125). */\nexport interface ObserveSink<T = ObserveEvent> {\n\t/** Persist or forward one mapped observe event. Thenables are serialized in observe order. */\n\twrite(event: T): void | PromiseLike<void>;\n\t/** Optional adapter flush barrier. Runs after all earlier writes. */\n\tflush?(): void | PromiseLike<void>;\n\t/** Optional adapter rollback hook. Runs after all earlier writes. */\n\trollback?(): void | PromiseLike<void>;\n\t/** Optional adapter cleanup hook. Runs once after queued work drains. */\n\tdispose?(): void | PromiseLike<void>;\n}\n\n/** Error routing context for attachObserveSink lifecycle hooks. */\nexport interface ObserveSinkErrorContext<T = ObserveEvent> {\n\tphase: \"map\" | \"write\" | \"flush\" | \"rollback\" | \"dispose\";\n\tevent?: ObserveEvent;\n\tvalue?: T;\n}\n\n/** Queue-drain completion callback for observe-sink control calls (D75). */\nexport type ObserveSinkDone = () => void;\n\n/** Options for attaching a sink to the read-only observe egress (D74/D125). */\nexport interface AttachObserveSinkOptions<T = ObserveEvent> {\n\t/** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */\n\tpath?: string;\n\t/** Optional projection/filter. Return `undefined` to drop an observed event. */\n\tmap?: (event: ObserveEvent) => T | undefined;\n\t/** Optional error hook for mapper, write, and lifecycle failures. */\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;\n}\n\n/** Done-only callback control handle for an attached observe sink (D75). */\nexport interface ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\ntype QueueItem<T> =\n\t| { kind: \"write\"; event: ObserveEvent; value: T }\n\t| { kind: \"flush\"; done?: ObserveSinkDone }\n\t| { kind: \"rollback\"; done?: ObserveSinkDone }\n\t| { kind: \"dispose\" };\n\n/** Options for persisting Graph.observe() events into an append log. */\nexport interface AttachObserveEventLogOptions<T = ObserveEvent> {\n\tpath?: string;\n\tstream?: string;\n\tmap?: (event: ObserveEvent) => T | undefined;\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;\n}\n\n/** Done-callback lifecycle handle for an attached observe-event log. */\nexport interface ObserveEventLogHandle extends ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\nexport type { ObserveEventFrame, ObserveEventLogPage };\n\n/**\n * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are\n * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.\n */\nexport function attachObserveSink<T = ObserveEvent>(\n\tgraph: Graph,\n\tsink: ObserveSink<T>,\n\topts: AttachObserveSinkOptions<T> = {},\n): ObserveSinkHandle {\n\tconst { map, onError, path } = opts;\n\tconst queue: QueueItem<T>[] = [];\n\tconst disposeDone: ObserveSinkDone[] = [];\n\tlet draining = false;\n\tlet disposeRequested = false;\n\tlet disposed = false;\n\n\tfunction report(error: unknown, ctx: ObserveSinkErrorContext<T>): void {\n\t\tif (!onError) return;\n\t\ttry {\n\t\t\tonError(error, ctx);\n\t\t} catch {\n\t\t\t// Error routing is best-effort; never let adapter logging wedge the queue.\n\t\t}\n\t}\n\n\tfunction callDone(done?: ObserveSinkDone): void {\n\t\ttry {\n\t\t\tdone?.();\n\t\t} catch {\n\t\t\t// Completion callbacks are advisory only; never wedge the queue on observer code.\n\t\t}\n\t}\n\n\tfunction run(item: QueueItem<T>): void | PromiseLike<void> {\n\t\tswitch (item.kind) {\n\t\t\tcase \"write\":\n\t\t\t\treturn sink.write(item.value);\n\t\t\tcase \"flush\":\n\t\t\t\treturn sink.flush?.();\n\t\t\tcase \"rollback\":\n\t\t\t\treturn sink.rollback?.();\n\t\t\tcase \"dispose\":\n\t\t\t\treturn sink.dispose?.();\n\t\t}\n\t}\n\n\tfunction finish(item: QueueItem<T>): void {\n\t\tif (item.kind === \"dispose\") {\n\t\t\tdisposed = true;\n\t\t\tfor (const done of disposeDone.splice(0)) callDone(done);\n\t\t} else if (item.kind !== \"write\") {\n\t\t\tcallDone(item.done);\n\t\t}\n\t\tdraining = false;\n\t\tdrain();\n\t}\n\n\tfunction fail(item: QueueItem<T>, error: unknown): void {\n\t\tif (item.kind === \"write\")\n\t\t\treport(error, { phase: \"write\", event: item.event, value: item.value });\n\t\telse report(error, { phase: item.kind });\n\t\tfinish(item);\n\t}\n\n\tfunction chainThenable(item: QueueItem<T>, value: unknown): boolean {\n\t\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) return false;\n\n\t\tlet then: unknown;\n\t\ttry {\n\t\t\tthen = (value as { then?: unknown }).then;\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn true;\n\t\t}\n\t\tif (typeof then !== \"function\") return false;\n\n\t\tlet settled = false;\n\t\tconst settle = (next: () => void) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tnext();\n\t\t};\n\t\ttry {\n\t\t\t(then as (onFulfilled: () => void, onRejected: (error: unknown) => void) => unknown).call(\n\t\t\t\tvalue,\n\t\t\t\t() => settle(() => finish(item)),\n\t\t\t\t(error) => settle(() => fail(item, error)),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tsettle(() => fail(item, error));\n\t\t}\n\t\treturn true;\n\t}\n\n\tfunction drain(): void {\n\t\tif (draining) return;\n\t\tconst item = queue.shift();\n\t\tif (!item) return;\n\t\tdraining = true;\n\t\tlet result: void | PromiseLike<void>;\n\t\ttry {\n\t\t\tresult = run(item);\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn;\n\t\t}\n\t\tif (chainThenable(item, result)) return;\n\t\tfinish(item);\n\t}\n\n\tfunction enqueueBarrier(kind: \"flush\" | \"rollback\", done?: ObserveSinkDone): void {\n\t\tif (disposeRequested) {\n\t\t\tcallDone(done);\n\t\t\treturn;\n\t\t}\n\t\tqueue.push({ kind, done });\n\t\tdrain();\n\t}\n\n\tconst stop = graph.observe(path).subscribe((event) => {\n\t\tif (disposeRequested) return;\n\t\tlet value: T | undefined;\n\t\ttry {\n\t\t\tvalue = map ? map(event) : (event as unknown as T);\n\t\t} catch (error) {\n\t\t\treport(error, { phase: \"map\", event });\n\t\t\treturn;\n\t\t}\n\t\tif (value === undefined) return;\n\t\tqueue.push({ kind: \"write\", event, value });\n\t\tdrain();\n\t});\n\n\treturn {\n\t\tflush(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"flush\", done);\n\t\t},\n\t\trollback(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"rollback\", done);\n\t\t},\n\t\tdispose(done?: ObserveSinkDone): void {\n\t\t\tif (disposed) {\n\t\t\t\tcallDone(done);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (done) disposeDone.push(done);\n\t\t\tif (disposeRequested) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tdisposeRequested = true;\n\t\t\tstop();\n\t\t\tqueue.push({ kind: \"dispose\" });\n\t\t\tdrain();\n\t\t},\n\t};\n}\n\n/**\n * Persist Graph.observe() events to an append log. This is a graph-bound\n * adapter over passive storage frames, not graph restore or projection.\n */\nexport function attachObserveEventLog<T = ObserveEvent>(\n\tgraph: Graph,\n\tlog: AppendLogStorageTier<ObserveEventFrame<T>>,\n\topts: AttachObserveEventLogOptions<T> = {},\n): ObserveEventLogHandle {\n\treturn attachObserveSink<ObserveEventFrame<T>>(\n\t\tgraph,\n\t\t{ write: (frame) => log.append(frame).then(() => undefined) },\n\t\t{\n\t\t\tpath: opts.path,\n\t\t\tmap: (event) => {\n\t\t\t\tconst value = opts.map ? opts.map(event) : (event as unknown as T);\n\t\t\t\treturn value === undefined ? undefined : observeEventFrame(event, value, opts);\n\t\t\t},\n\t\t\tonError: opts.onError,\n\t\t},\n\t);\n}\n","/**\n * Storage scalar helpers (D88): host BigInt in memory, canonical decimal strings on JSON/storage.\n */\n\n/** Canonical decimal integer string; no leading zeroes, and no negative zero. */\nexport type DecimalIntegerString = string;\n\n/** Canonical non-negative decimal integer string. */\nexport type NonNegativeDecimalIntegerString = DecimalIntegerString;\n\nconst DECIMAL_INTEGER_RE = /^(0|-?[1-9]\\d*)$/;\nconst NON_NEGATIVE_DECIMAL_INTEGER_RE = /^(0|[1-9]\\d*)$/;\n\n/** Test whether a value is a canonical decimal integer string. */\nexport function isDecimalIntegerString(value: unknown): value is DecimalIntegerString {\n\treturn typeof value === \"string\" && DECIMAL_INTEGER_RE.test(value);\n}\n\n/** Test whether a value is a canonical non-negative decimal integer string. */\nexport function isNonNegativeDecimalIntegerString(\n\tvalue: unknown,\n): value is NonNegativeDecimalIntegerString {\n\treturn typeof value === \"string\" && NON_NEGATIVE_DECIMAL_INTEGER_RE.test(value);\n}\n\n/** Assert a canonical decimal integer string and return it typed. */\nexport function assertDecimalIntegerString(\n\tvalue: unknown,\n\tlabel = \"decimal integer\",\n): DecimalIntegerString {\n\tif (!isDecimalIntegerString(value)) {\n\t\tthrow new TypeError(`${label} must be a canonical decimal integer string`);\n\t}\n\treturn value;\n}\n\n/** Assert a canonical non-negative decimal integer string and return it typed. */\nexport function assertNonNegativeDecimalIntegerString(\n\tvalue: unknown,\n\tlabel = \"decimal integer\",\n): NonNegativeDecimalIntegerString {\n\tif (!isNonNegativeDecimalIntegerString(value)) {\n\t\tthrow new TypeError(`${label} must be a canonical non-negative decimal integer string`);\n\t}\n\treturn value;\n}\n\n/** Convert a host BigInt to the canonical decimal storage scalar. */\nexport function bigIntToDecimalString(value: bigint): DecimalIntegerString {\n\treturn value.toString();\n}\n\n/** Convert a non-negative host BigInt to the canonical non-negative decimal storage scalar. */\nexport function bigIntToNonNegativeDecimalString(value: bigint): NonNegativeDecimalIntegerString {\n\tif (value < 0n) {\n\t\tthrow new TypeError(\"decimal integer must be non-negative\");\n\t}\n\treturn value.toString();\n}\n\n/** Parse a canonical decimal storage scalar into host BigInt. */\nexport function decimalStringToBigInt(value: DecimalIntegerString): bigint {\n\treturn BigInt(assertDecimalIntegerString(value));\n}\n\n/** Parse a canonical non-negative decimal storage scalar into host BigInt. */\nexport function nonNegativeDecimalStringToBigInt(value: NonNegativeDecimalIntegerString): bigint {\n\treturn BigInt(assertNonNegativeDecimalIntegerString(value));\n}\n","/**\n * Storage change envelopes (D82): persistence framing for raw graph/data-structure deltas.\n */\n\nimport type { Codec } from \"./codec.js\";\nimport { strictJsonCodecFor } from \"./codec.js\";\nimport {\n\tassertNonNegativeDecimalIntegerString,\n\tbigIntToNonNegativeDecimalString,\n\ttype NonNegativeDecimalIntegerString,\n} from \"./scalar.js\";\n\n/** Storage-side lifecycle namespace for change envelopes; presentation framing only. */\nexport type ChangeLifecycle = \"spec\" | \"data\" | \"ownership\";\n\n/** D84 cross-runtime wall-clock nanosecond metadata: canonical non-negative decimal string. */\nexport type StorageTimestampNs = NonNegativeDecimalIntegerString;\n\n/** Persistence envelope for raw graph/data-structure deltas (D82), not restore semantics. */\nexport interface ChangeEnvelope<T = unknown> {\n\treadonly lifecycle: ChangeLifecycle;\n\treadonly structure: string;\n\treadonly version: number | string;\n\treadonly t_ns: StorageTimestampNs;\n\treadonly seq?: number;\n\treadonly change: T;\n}\n\n/** Options for wrapping a raw change in a storage envelope. */\nexport interface ChangeEnvelopeOptions {\n\tlifecycle?: ChangeLifecycle;\n\tstructure: string;\n\tversion?: number | string;\n\tt_ns?: StorageTimestampNs;\n\tseq?: number;\n}\n\n/** Wall-clock nanoseconds for storage metadata. */\nexport function nowNs(): StorageTimestampNs {\n\treturn bigIntToNonNegativeDecimalString(BigInt(Date.now()) * 1_000_000n);\n}\n\n/** Wrap a raw change payload in a D82 storage envelope. */\nexport function envelopeChange<T>(change: T, opts: ChangeEnvelopeOptions): ChangeEnvelope<T> {\n\tconst envelope = {\n\t\tlifecycle: opts.lifecycle ?? \"data\",\n\t\tstructure: opts.structure,\n\t\tversion: opts.version ?? 1,\n\t\tt_ns: opts.t_ns ?? nowNs(),\n\t\t...(opts.seq === undefined ? {} : { seq: opts.seq }),\n\t\tchange,\n\t};\n\treturn assertChangeEnvelope<T>(envelope);\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction isLifecycle(value: unknown): value is ChangeLifecycle {\n\treturn value === \"spec\" || value === \"data\" || value === \"ownership\";\n}\n\n/** Validate a decoded D82 change envelope and return it with typed payload. */\nexport function assertChangeEnvelope<T = unknown>(value: unknown): ChangeEnvelope<T> {\n\tif (!isRecord(value)) throw new TypeError(\"changeEnvelopeCodec: frame must be an object\");\n\tif (!isLifecycle(value.lifecycle)) {\n\t\tthrow new TypeError(\"changeEnvelopeCodec: lifecycle must be spec, data, or ownership\");\n\t}\n\tif (typeof value.structure !== \"string\" || value.structure.length === 0) {\n\t\tthrow new TypeError(\"changeEnvelopeCodec: structure must be a non-empty string\");\n\t}\n\tif (\n\t\t(typeof value.version !== \"number\" || !Number.isFinite(value.version)) &&\n\t\ttypeof value.version !== \"string\"\n\t) {\n\t\tthrow new TypeError(\"changeEnvelopeCodec: version must be a finite number or string\");\n\t}\n\tassertNonNegativeDecimalIntegerString(value.t_ns, \"changeEnvelopeCodec: t_ns\");\n\tif (value.seq !== undefined && (!Number.isSafeInteger(value.seq) || (value.seq as number) < 0)) {\n\t\tthrow new TypeError(\n\t\t\t\"changeEnvelopeCodec: seq must be a non-negative safe integer when present\",\n\t\t);\n\t}\n\tif (!Object.hasOwn(value, \"change\")) {\n\t\tthrow new TypeError(\"changeEnvelopeCodec: change payload is required\");\n\t}\n\treturn value as unknown as ChangeEnvelope<T>;\n}\n\n/** Stable JSON codec for D82 change envelopes, with strict framing checks. */\nexport function changeEnvelopeCodec<T = unknown>(): Codec<ChangeEnvelope<T>> {\n\tconst codec = strictJsonCodecFor<unknown>();\n\treturn {\n\t\tencode(value) {\n\t\t\treturn codec.encode(assertChangeEnvelope(value));\n\t\t},\n\t\tdecode(bytes) {\n\t\t\treturn assertChangeEnvelope<T>(codec.decode(bytes));\n\t\t},\n\t};\n}\n","import type { AppendLogPage, AppendLogReadOptions, AppendLogStorageTier } from \"./append-log.js\";\nimport { readAppendLogPage } from \"./append-log.js\";\nimport { assertChangeEnvelope, type ChangeEnvelope, envelopeChange } from \"./change.js\";\nimport type { Codec } from \"./codec.js\";\nimport { strictJsonCodecFor } from \"./codec.js\";\n\nexport interface ObserveEventLike {\n\treadonly seq: number;\n\treadonly path: string;\n}\n\n/** Storage frame for one Graph.observe() event, preserving graph observe sequence. */\nexport interface ObserveEventFrame<T = unknown> extends ChangeEnvelope<T> {\n\treadonly structure: \"observe-event\";\n\treadonly observeSeq: number;\n\treadonly path: string;\n\treadonly stream?: string;\n}\n\n/** One ordered observe-event log page. It is not graph projection or restore replay. */\nexport type ObserveEventLogPage<T = unknown> = AppendLogPage<ObserveEventFrame<T>>;\n\n/** Create a storage frame from one observe event and mapped payload. */\nexport function observeEventFrame<T>(\n\tevent: ObserveEventLike,\n\tvalue: T,\n\topts: { stream?: string } = {},\n): ObserveEventFrame<T> {\n\treturn {\n\t\t...envelopeChange(value, {\n\t\t\tlifecycle: \"data\",\n\t\t\tstructure: \"observe-event\",\n\t\t\tversion: 1,\n\t\t\tseq: event.seq,\n\t\t}),\n\t\tstructure: \"observe-event\",\n\t\tobserveSeq: event.seq,\n\t\tpath: event.path,\n\t\t...(opts.stream === undefined ? {} : { stream: opts.stream }),\n\t};\n}\n\n/** Validate a decoded D82 observe-event storage frame. */\nexport function assertObserveEventFrame<T = unknown>(value: unknown): ObserveEventFrame<T> {\n\tconst frame = assertChangeEnvelope<T>(value);\n\tconst record = frame as unknown as Record<string, unknown>;\n\tif (frame.structure !== \"observe-event\") {\n\t\tthrow new TypeError(\"observeEventFrameCodec: structure must be observe-event\");\n\t}\n\tif (!Number.isSafeInteger(record.observeSeq) || (record.observeSeq as number) < 0) {\n\t\tthrow new TypeError(\"observeEventFrameCodec: observeSeq must be a non-negative safe integer\");\n\t}\n\tif (typeof record.path !== \"string\") {\n\t\tthrow new TypeError(\"observeEventFrameCodec: path must be a string\");\n\t}\n\tif (record.stream !== undefined && typeof record.stream !== \"string\") {\n\t\tthrow new TypeError(\"observeEventFrameCodec: stream must be a string when present\");\n\t}\n\treturn frame as ObserveEventFrame<T>;\n}\n\n/** Stable JSON codec for D82 observe-event frames, not restore records. */\nexport function observeEventFrameCodec<T = unknown>(): Codec<ObserveEventFrame<T>> {\n\tconst codec = strictJsonCodecFor<unknown>();\n\treturn {\n\t\tencode(value) {\n\t\t\treturn codec.encode(assertObserveEventFrame(value));\n\t\t},\n\t\tdecode(bytes) {\n\t\t\treturn assertObserveEventFrame<T>(codec.decode(bytes));\n\t\t},\n\t};\n}\n\n/**\n * Read one ordered observe-event log page without projecting it into graph state.\n */\nexport function readObserveEventLogPage<T = unknown>(\n\tlog: AppendLogStorageTier<ObserveEventFrame<T>>,\n\topts: AppendLogReadOptions = {},\n): Promise<ObserveEventLogPage<T>> {\n\treturn readAppendLogPage(log, opts);\n}\n"],"mappings":"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","names":[]}

package/dist/adapters/observe-storage.d.cts

@@ -0,0 +1,77 @@
+import { O as ObserveEvent, d as Graph } from '../graph-s23RbbFO.cjs';
+import { d as AppendLogStorageTier } from '../append-log-DisvEReb.cjs';
+import { O as ObserveEventFrame } from '../observe-event-log-0SVsx7JG.cjs';
+export { c as ObserveEventLogPage } from '../observe-event-log-0SVsx7JG.cjs';
+import '../core/index.cjs';
+import '../types-bNMSWKqF.cjs';
+import '../messages-BZqrGGm1.cjs';
+import '../codec-BB7p8fJc.cjs';
+import '../describe-Ciu8SUnN.cjs';
+
+/**
+ * Graph-bound observe storage adapters.
+ *
+ * Passive storage lives under ../storage. This subpath owns bridges that need
+ * Graph.observe() and therefore sit above both graph and passive storage (D125).
+ */
+
+/** Adapter-owned sink for observed graph events (D57/D74/D125). */
+interface ObserveSink<T = ObserveEvent> {
+    /** Persist or forward one mapped observe event. Thenables are serialized in observe order. */
+    write(event: T): void | PromiseLike<void>;
+    /** Optional adapter flush barrier. Runs after all earlier writes. */
+    flush?(): void | PromiseLike<void>;
+    /** Optional adapter rollback hook. Runs after all earlier writes. */
+    rollback?(): void | PromiseLike<void>;
+    /** Optional adapter cleanup hook. Runs once after queued work drains. */
+    dispose?(): void | PromiseLike<void>;
+}
+/** Error routing context for attachObserveSink lifecycle hooks. */
+interface ObserveSinkErrorContext<T = ObserveEvent> {
+    phase: "map" | "write" | "flush" | "rollback" | "dispose";
+    event?: ObserveEvent;
+    value?: T;
+}
+/** Queue-drain completion callback for observe-sink control calls (D75). */
+type ObserveSinkDone = () => void;
+/** Options for attaching a sink to the read-only observe egress (D74/D125). */
+interface AttachObserveSinkOptions<T = ObserveEvent> {
+    /** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */
+    path?: string;
+    /** Optional projection/filter. Return `undefined` to drop an observed event. */
+    map?: (event: ObserveEvent) => T | undefined;
+    /** Optional error hook for mapper, write, and lifecycle failures. */
+    onError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;
+}
+/** Done-only callback control handle for an attached observe sink (D75). */
+interface ObserveSinkHandle {
+    flush(done?: ObserveSinkDone): void;
+    rollback(done?: ObserveSinkDone): void;
+    dispose(done?: ObserveSinkDone): void;
+}
+/** Options for persisting Graph.observe() events into an append log. */
+interface AttachObserveEventLogOptions<T = ObserveEvent> {
+    path?: string;
+    stream?: string;
+    map?: (event: ObserveEvent) => T | undefined;
+    onError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;
+}
+/** Done-callback lifecycle handle for an attached observe-event log. */
+interface ObserveEventLogHandle extends ObserveSinkHandle {
+    flush(done?: ObserveSinkDone): void;
+    rollback(done?: ObserveSinkDone): void;
+    dispose(done?: ObserveSinkDone): void;
+}
+
+/**
+ * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are
+ * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.
+ */
+declare function attachObserveSink<T = ObserveEvent>(graph: Graph, sink: ObserveSink<T>, opts?: AttachObserveSinkOptions<T>): ObserveSinkHandle;
+/**
+ * Persist Graph.observe() events to an append log. This is a graph-bound
+ * adapter over passive storage frames, not graph restore or projection.
+ */
+declare function attachObserveEventLog<T = ObserveEvent>(graph: Graph, log: AppendLogStorageTier<ObserveEventFrame<T>>, opts?: AttachObserveEventLogOptions<T>): ObserveEventLogHandle;
+
+export { type AttachObserveEventLogOptions, type AttachObserveSinkOptions, ObserveEventFrame, type ObserveEventLogHandle, type ObserveSink, type ObserveSinkDone, type ObserveSinkErrorContext, type ObserveSinkHandle, attachObserveEventLog, attachObserveSink };

package/dist/adapters/observe-storage.d.ts

@@ -0,0 +1,77 @@
+import { O as ObserveEvent, d as Graph } from '../graph-DfdF9zy4.js';
+import { d as AppendLogStorageTier } from '../append-log-DzKMmjxx.js';
+import { O as ObserveEventFrame } from '../observe-event-log-Dnm76owp.js';
+export { c as ObserveEventLogPage } from '../observe-event-log-Dnm76owp.js';
+import '../core/index.js';
+import '../types-h12mNYbq.js';
+import '../messages-BZqrGGm1.js';
+import '../codec-BB7p8fJc.js';
+import '../describe-BZb7AS2y.js';
+
+/**
+ * Graph-bound observe storage adapters.
+ *
+ * Passive storage lives under ../storage. This subpath owns bridges that need
+ * Graph.observe() and therefore sit above both graph and passive storage (D125).
+ */
+
+/** Adapter-owned sink for observed graph events (D57/D74/D125). */
+interface ObserveSink<T = ObserveEvent> {
+    /** Persist or forward one mapped observe event. Thenables are serialized in observe order. */
+    write(event: T): void | PromiseLike<void>;
+    /** Optional adapter flush barrier. Runs after all earlier writes. */
+    flush?(): void | PromiseLike<void>;
+    /** Optional adapter rollback hook. Runs after all earlier writes. */
+    rollback?(): void | PromiseLike<void>;
+    /** Optional adapter cleanup hook. Runs once after queued work drains. */
+    dispose?(): void | PromiseLike<void>;
+}
+/** Error routing context for attachObserveSink lifecycle hooks. */
+interface ObserveSinkErrorContext<T = ObserveEvent> {
+    phase: "map" | "write" | "flush" | "rollback" | "dispose";
+    event?: ObserveEvent;
+    value?: T;
+}
+/** Queue-drain completion callback for observe-sink control calls (D75). */
+type ObserveSinkDone = () => void;
+/** Options for attaching a sink to the read-only observe egress (D74/D125). */
+interface AttachObserveSinkOptions<T = ObserveEvent> {
+    /** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */
+    path?: string;
+    /** Optional projection/filter. Return `undefined` to drop an observed event. */
+    map?: (event: ObserveEvent) => T | undefined;
+    /** Optional error hook for mapper, write, and lifecycle failures. */
+    onError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;
+}
+/** Done-only callback control handle for an attached observe sink (D75). */
+interface ObserveSinkHandle {
+    flush(done?: ObserveSinkDone): void;
+    rollback(done?: ObserveSinkDone): void;
+    dispose(done?: ObserveSinkDone): void;
+}
+/** Options for persisting Graph.observe() events into an append log. */
+interface AttachObserveEventLogOptions<T = ObserveEvent> {
+    path?: string;
+    stream?: string;
+    map?: (event: ObserveEvent) => T | undefined;
+    onError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;
+}
+/** Done-callback lifecycle handle for an attached observe-event log. */
+interface ObserveEventLogHandle extends ObserveSinkHandle {
+    flush(done?: ObserveSinkDone): void;
+    rollback(done?: ObserveSinkDone): void;
+    dispose(done?: ObserveSinkDone): void;
+}
+
+/**
+ * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are
+ * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.
+ */
+declare function attachObserveSink<T = ObserveEvent>(graph: Graph, sink: ObserveSink<T>, opts?: AttachObserveSinkOptions<T>): ObserveSinkHandle;
+/**
+ * Persist Graph.observe() events to an append log. This is a graph-bound
+ * adapter over passive storage frames, not graph restore or projection.
+ */
+declare function attachObserveEventLog<T = ObserveEvent>(graph: Graph, log: AppendLogStorageTier<ObserveEventFrame<T>>, opts?: AttachObserveEventLogOptions<T>): ObserveEventLogHandle;
+
+export { type AttachObserveEventLogOptions, type AttachObserveSinkOptions, ObserveEventFrame, type ObserveEventLogHandle, type ObserveSink, type ObserveSinkDone, type ObserveSinkErrorContext, type ObserveSinkHandle, attachObserveEventLog, attachObserveSink };

package/dist/adapters/observe-storage.js

@@ -0,0 +1,161 @@
+import {
+  observeEventFrame
+} from "../chunk-K3FXTC3I.js";
+import "../chunk-6PHB5CJS.js";
+import "../chunk-DKP56CSW.js";
+import "../chunk-4VLAQHZI.js";
+
+// src/adapters/observe-storage.ts
+function attachObserveSink(graph, sink, opts = {}) {
+  const { map, onError, path } = opts;
+  const queue = [];
+  const disposeDone = [];
+  let draining = false;
+  let disposeRequested = false;
+  let disposed = false;
+  function report(error, ctx) {
+    if (!onError) return;
+    try {
+      onError(error, ctx);
+    } catch {
+    }
+  }
+  function callDone(done) {
+    try {
+      done?.();
+    } catch {
+    }
+  }
+  function run(item) {
+    switch (item.kind) {
+      case "write":
+        return sink.write(item.value);
+      case "flush":
+        return sink.flush?.();
+      case "rollback":
+        return sink.rollback?.();
+      case "dispose":
+        return sink.dispose?.();
+    }
+  }
+  function finish(item) {
+    if (item.kind === "dispose") {
+      disposed = true;
+      for (const done of disposeDone.splice(0)) callDone(done);
+    } else if (item.kind !== "write") {
+      callDone(item.done);
+    }
+    draining = false;
+    drain();
+  }
+  function fail(item, error) {
+    if (item.kind === "write")
+      report(error, { phase: "write", event: item.event, value: item.value });
+    else report(error, { phase: item.kind });
+    finish(item);
+  }
+  function chainThenable(item, value) {
+    if (typeof value !== "object" && typeof value !== "function" || value === null) return false;
+    let then;
+    try {
+      then = value.then;
+    } catch (error) {
+      fail(item, error);
+      return true;
+    }
+    if (typeof then !== "function") return false;
+    let settled = false;
+    const settle = (next) => {
+      if (settled) return;
+      settled = true;
+      next();
+    };
+    try {
+      then.call(
+        value,
+        () => settle(() => finish(item)),
+        (error) => settle(() => fail(item, error))
+      );
+    } catch (error) {
+      settle(() => fail(item, error));
+    }
+    return true;
+  }
+  function drain() {
+    if (draining) return;
+    const item = queue.shift();
+    if (!item) return;
+    draining = true;
+    let result;
+    try {
+      result = run(item);
+    } catch (error) {
+      fail(item, error);
+      return;
+    }
+    if (chainThenable(item, result)) return;
+    finish(item);
+  }
+  function enqueueBarrier(kind, done) {
+    if (disposeRequested) {
+      callDone(done);
+      return;
+    }
+    queue.push({ kind, done });
+    drain();
+  }
+  const stop = graph.observe(path).subscribe((event) => {
+    if (disposeRequested) return;
+    let value;
+    try {
+      value = map ? map(event) : event;
+    } catch (error) {
+      report(error, { phase: "map", event });
+      return;
+    }
+    if (value === void 0) return;
+    queue.push({ kind: "write", event, value });
+    drain();
+  });
+  return {
+    flush(done) {
+      enqueueBarrier("flush", done);
+    },
+    rollback(done) {
+      enqueueBarrier("rollback", done);
+    },
+    dispose(done) {
+      if (disposed) {
+        callDone(done);
+        return;
+      }
+      if (done) disposeDone.push(done);
+      if (disposeRequested) {
+        return;
+      }
+      disposeRequested = true;
+      stop();
+      queue.push({ kind: "dispose" });
+      drain();
+    }
+  };
+}
+function attachObserveEventLog(graph, log, opts = {}) {
+  return attachObserveSink(
+    graph,
+    { write: (frame) => log.append(frame).then(() => void 0) },
+    {
+      path: opts.path,
+      map: (event) => {
+        const value = opts.map ? opts.map(event) : event;
+        return value === void 0 ? void 0 : observeEventFrame(event, value, opts);
+      },
+      onError: opts.onError
+    }
+  );
+}
+export {
+  attachObserveEventLog,
+  attachObserveSink
+};
+//# sourceMappingURL=observe-storage.js.map

package/dist/adapters/observe-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/adapters/observe-storage.ts"],"sourcesContent":["/**\n * Graph-bound observe storage adapters.\n *\n * Passive storage lives under ../storage. This subpath owns bridges that need\n * Graph.observe() and therefore sit above both graph and passive storage (D125).\n */\n\nimport type { Graph } from \"../graph/graph.js\";\nimport type { ObserveEvent } from \"../graph/inspect.js\";\nimport type { AppendLogStorageTier } from \"../storage/append-log.js\";\nimport {\n\ttype ObserveEventFrame,\n\ttype ObserveEventLogPage,\n\tobserveEventFrame,\n} from \"../storage/observe-event-log.js\";\n\n/** Adapter-owned sink for observed graph events (D57/D74/D125). */\nexport interface ObserveSink<T = ObserveEvent> {\n\t/** Persist or forward one mapped observe event. Thenables are serialized in observe order. */\n\twrite(event: T): void | PromiseLike<void>;\n\t/** Optional adapter flush barrier. Runs after all earlier writes. */\n\tflush?(): void | PromiseLike<void>;\n\t/** Optional adapter rollback hook. Runs after all earlier writes. */\n\trollback?(): void | PromiseLike<void>;\n\t/** Optional adapter cleanup hook. Runs once after queued work drains. */\n\tdispose?(): void | PromiseLike<void>;\n}\n\n/** Error routing context for attachObserveSink lifecycle hooks. */\nexport interface ObserveSinkErrorContext<T = ObserveEvent> {\n\tphase: \"map\" | \"write\" | \"flush\" | \"rollback\" | \"dispose\";\n\tevent?: ObserveEvent;\n\tvalue?: T;\n}\n\n/** Queue-drain completion callback for observe-sink control calls (D75). */\nexport type ObserveSinkDone = () => void;\n\n/** Options for attaching a sink to the read-only observe egress (D74/D125). */\nexport interface AttachObserveSinkOptions<T = ObserveEvent> {\n\t/** Optional exact-id or subtree path filter; forwarded to `graph.observe(path?)`. */\n\tpath?: string;\n\t/** Optional projection/filter. Return `undefined` to drop an observed event. */\n\tmap?: (event: ObserveEvent) => T | undefined;\n\t/** Optional error hook for mapper, write, and lifecycle failures. */\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<T>) => void;\n}\n\n/** Done-only callback control handle for an attached observe sink (D75). */\nexport interface ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\ntype QueueItem<T> =\n\t| { kind: \"write\"; event: ObserveEvent; value: T }\n\t| { kind: \"flush\"; done?: ObserveSinkDone }\n\t| { kind: \"rollback\"; done?: ObserveSinkDone }\n\t| { kind: \"dispose\" };\n\n/** Options for persisting Graph.observe() events into an append log. */\nexport interface AttachObserveEventLogOptions<T = ObserveEvent> {\n\tpath?: string;\n\tstream?: string;\n\tmap?: (event: ObserveEvent) => T | undefined;\n\tonError?: (error: unknown, ctx: ObserveSinkErrorContext<ObserveEventFrame<T>>) => void;\n}\n\n/** Done-callback lifecycle handle for an attached observe-event log. */\nexport interface ObserveEventLogHandle extends ObserveSinkHandle {\n\tflush(done?: ObserveSinkDone): void;\n\trollback(done?: ObserveSinkDone): void;\n\tdispose(done?: ObserveSinkDone): void;\n}\n\nexport type { ObserveEventFrame, ObserveEventLogPage };\n\n/**\n * Attach adapter-owned storage to `Graph.observe()` read-only egress (D57/D74/D125). Writes are\n * serialized in observe order; lifecycle barriers drain the queue without mutating graph topology.\n */\nexport function attachObserveSink<T = ObserveEvent>(\n\tgraph: Graph,\n\tsink: ObserveSink<T>,\n\topts: AttachObserveSinkOptions<T> = {},\n): ObserveSinkHandle {\n\tconst { map, onError, path } = opts;\n\tconst queue: QueueItem<T>[] = [];\n\tconst disposeDone: ObserveSinkDone[] = [];\n\tlet draining = false;\n\tlet disposeRequested = false;\n\tlet disposed = false;\n\n\tfunction report(error: unknown, ctx: ObserveSinkErrorContext<T>): void {\n\t\tif (!onError) return;\n\t\ttry {\n\t\t\tonError(error, ctx);\n\t\t} catch {\n\t\t\t// Error routing is best-effort; never let adapter logging wedge the queue.\n\t\t}\n\t}\n\n\tfunction callDone(done?: ObserveSinkDone): void {\n\t\ttry {\n\t\t\tdone?.();\n\t\t} catch {\n\t\t\t// Completion callbacks are advisory only; never wedge the queue on observer code.\n\t\t}\n\t}\n\n\tfunction run(item: QueueItem<T>): void | PromiseLike<void> {\n\t\tswitch (item.kind) {\n\t\t\tcase \"write\":\n\t\t\t\treturn sink.write(item.value);\n\t\t\tcase \"flush\":\n\t\t\t\treturn sink.flush?.();\n\t\t\tcase \"rollback\":\n\t\t\t\treturn sink.rollback?.();\n\t\t\tcase \"dispose\":\n\t\t\t\treturn sink.dispose?.();\n\t\t}\n\t}\n\n\tfunction finish(item: QueueItem<T>): void {\n\t\tif (item.kind === \"dispose\") {\n\t\t\tdisposed = true;\n\t\t\tfor (const done of disposeDone.splice(0)) callDone(done);\n\t\t} else if (item.kind !== \"write\") {\n\t\t\tcallDone(item.done);\n\t\t}\n\t\tdraining = false;\n\t\tdrain();\n\t}\n\n\tfunction fail(item: QueueItem<T>, error: unknown): void {\n\t\tif (item.kind === \"write\")\n\t\t\treport(error, { phase: \"write\", event: item.event, value: item.value });\n\t\telse report(error, { phase: item.kind });\n\t\tfinish(item);\n\t}\n\n\tfunction chainThenable(item: QueueItem<T>, value: unknown): boolean {\n\t\tif ((typeof value !== \"object\" && typeof value !== \"function\") || value === null) return false;\n\n\t\tlet then: unknown;\n\t\ttry {\n\t\t\tthen = (value as { then?: unknown }).then;\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn true;\n\t\t}\n\t\tif (typeof then !== \"function\") return false;\n\n\t\tlet settled = false;\n\t\tconst settle = (next: () => void) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tnext();\n\t\t};\n\t\ttry {\n\t\t\t(then as (onFulfilled: () => void, onRejected: (error: unknown) => void) => unknown).call(\n\t\t\t\tvalue,\n\t\t\t\t() => settle(() => finish(item)),\n\t\t\t\t(error) => settle(() => fail(item, error)),\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tsettle(() => fail(item, error));\n\t\t}\n\t\treturn true;\n\t}\n\n\tfunction drain(): void {\n\t\tif (draining) return;\n\t\tconst item = queue.shift();\n\t\tif (!item) return;\n\t\tdraining = true;\n\t\tlet result: void | PromiseLike<void>;\n\t\ttry {\n\t\t\tresult = run(item);\n\t\t} catch (error) {\n\t\t\tfail(item, error);\n\t\t\treturn;\n\t\t}\n\t\tif (chainThenable(item, result)) return;\n\t\tfinish(item);\n\t}\n\n\tfunction enqueueBarrier(kind: \"flush\" | \"rollback\", done?: ObserveSinkDone): void {\n\t\tif (disposeRequested) {\n\t\t\tcallDone(done);\n\t\t\treturn;\n\t\t}\n\t\tqueue.push({ kind, done });\n\t\tdrain();\n\t}\n\n\tconst stop = graph.observe(path).subscribe((event) => {\n\t\tif (disposeRequested) return;\n\t\tlet value: T | undefined;\n\t\ttry {\n\t\t\tvalue = map ? map(event) : (event as unknown as T);\n\t\t} catch (error) {\n\t\t\treport(error, { phase: \"map\", event });\n\t\t\treturn;\n\t\t}\n\t\tif (value === undefined) return;\n\t\tqueue.push({ kind: \"write\", event, value });\n\t\tdrain();\n\t});\n\n\treturn {\n\t\tflush(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"flush\", done);\n\t\t},\n\t\trollback(done?: ObserveSinkDone): void {\n\t\t\tenqueueBarrier(\"rollback\", done);\n\t\t},\n\t\tdispose(done?: ObserveSinkDone): void {\n\t\t\tif (disposed) {\n\t\t\t\tcallDone(done);\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (done) disposeDone.push(done);\n\t\t\tif (disposeRequested) {\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tdisposeRequested = true;\n\t\t\tstop();\n\t\t\tqueue.push({ kind: \"dispose\" });\n\t\t\tdrain();\n\t\t},\n\t};\n}\n\n/**\n * Persist Graph.observe() events to an append log. This is a graph-bound\n * adapter over passive storage frames, not graph restore or projection.\n */\nexport function attachObserveEventLog<T = ObserveEvent>(\n\tgraph: Graph,\n\tlog: AppendLogStorageTier<ObserveEventFrame<T>>,\n\topts: AttachObserveEventLogOptions<T> = {},\n): ObserveEventLogHandle {\n\treturn attachObserveSink<ObserveEventFrame<T>>(\n\t\tgraph,\n\t\t{ write: (frame) => log.append(frame).then(() => undefined) },\n\t\t{\n\t\t\tpath: opts.path,\n\t\t\tmap: (event) => {\n\t\t\t\tconst value = opts.map ? opts.map(event) : (event as unknown as T);\n\t\t\t\treturn value === undefined ? undefined : observeEventFrame(event, value, opts);\n\t\t\t},\n\t\t\tonError: opts.onError,\n\t\t},\n\t);\n}\n"],"mappings":"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","names":[]}