@lazily-hub/lazily-js 0.4.0

package/src/stable-id.js

@@ -0,0 +1,214 @@
+// Manufactured identity for text (cell-model.md § Manufactured identity for
+// text, #lzstableid). Markdown has no inherent node ids, so reconciliation keys
+// are *manufactured* from text in three layers:
+//
+// 1. in-band **anchors** (exact, survive a body rewrite),
+// 2. **content-derived hashes** of whitespace-normalized text (survive
+//    reflow/reorder, change on edit),
+// 3. **alignment** by word-LCS similarity (>= 0.5 => Edited/key-inherited;
+//    below => Inserted).
+//
+// This is the bridge to LIS keyed reconciliation (#lzkeyrecon): a new block
+// that is `Same`/`Edited` inherits the matched predecessor's key, so the
+// reconciler emits an `update` rather than remove+insert.
+
+export const EDIT_THRESHOLD = 0.5;
+export const ANCHOR_PREFIX = "a:";
+export const CONTENT_PREFIX = "c:";
+
+export class Block {
+  constructor(text, anchor = null) {
+    this.text = String(text);
+    this.anchor = anchor;
+    Object.freeze(this);
+  }
+  static text(text) {
+    return new Block(text, null);
+  }
+  static anchored(anchor, text) {
+    return new Block(text, String(anchor));
+  }
+}
+
+export class BlockKey {
+  constructor(kind, value) {
+    this.kind = kind; // "anchored" | "content"
+    this.value = value; // string (anchor) | bigint (content hash)
+    Object.freeze(this);
+  }
+  get isAnchored() {
+    return this.kind === "anchored";
+  }
+  get isContent() {
+    return this.kind === "content";
+  }
+  equals(other) {
+    if (this.kind !== other.kind) {
+      return false;
+    }
+    return this.value === other.value;
+  }
+  asString() {
+    if (this.kind === "anchored") {
+      return `${ANCHOR_PREFIX}${this.value}`;
+    }
+    return `${CONTENT_PREFIX}${this.value.toString(16).padStart(16, "0")}`;
+  }
+}
+
+// Whitespace normalization: split on any Unicode whitespace run, drop empties,
+// rejoin with a single ASCII space. Matches Rust `split_whitespace().join(" ")`.
+export function normalize(text) {
+  return String(text)
+    .split(/\s+/u)
+    .filter((token) => token.length > 0)
+    .join(" ");
+}
+
+// FNV-1a 64-bit content hash of the normalized text. Deterministic and
+// cross-language stable (unlike Rust's per-process DefaultHasher); the
+// ecosystem already uses FNV-1a-64 for ShmBlobArena checksums. The spec pins
+// only "content-derived hashes of normalized text", not the algorithm.
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK64 = 0xffffffffffffffffn;
+
+export function contentHash(text) {
+  let hash = FNV_OFFSET;
+  for (const byte of new TextEncoder().encode(normalize(text))) {
+    hash ^= BigInt(byte);
+    hash = (hash * FNV_PRIME) & MASK64;
+  }
+  return hash;
+}
+
+// Layer dispatch: anchor wins over content (the controlled skeleton's in-band
+// marker is the highest-certainty identity and is never overridden by text).
+export function blockKey(block) {
+  if (block.anchor !== null && block.anchor !== undefined) {
+    return new BlockKey("anchored", String(block.anchor));
+  }
+  return new BlockKey("content", contentHash(block.text));
+}
+
+// Longest-common-subsequence length over two token arrays (rolling two-row DP).
+function lcsLen(a, b) {
+  const dp = new Array(b.length + 1).fill(0);
+  for (const x of a) {
+    let prev = 0;
+    for (let j = 0; j < b.length; j++) {
+      const cur = dp[j + 1];
+      dp[j + 1] = x === b[j] ? prev + 1 : Math.max(dp[j + 1], dp[j]);
+      prev = cur;
+    }
+  }
+  return dp[b.length];
+}
+
+// Word-LCS similarity ratio in [0,1]: 2·|LCS| / (|a|+|b|). 1.0 = identical token
+// sequence; both-empty => 1.0.
+export function similarity(a, b) {
+  const aw = String(a).split(/\s+/u).filter((t) => t.length > 0);
+  const bw = String(b).split(/\s+/u).filter((t) => t.length > 0);
+  if (aw.length === 0 && bw.length === 0) {
+    return 1.0;
+  }
+  const lcs = lcsLen(aw, bw);
+  return (2 * lcs) / (aw.length + bw.length);
+}
+
+export class Match {
+  constructor(kind, oldIndex = -1, similarity = 0) {
+    this.kind = kind; // "same" | "edited" | "inserted"
+    this.oldIndex = oldIndex;
+    this.similarity = similarity;
+    Object.freeze(this);
+  }
+  static same(oldIndex) {
+    return new Match("same", oldIndex);
+  }
+  static edited(oldIndex, similarity) {
+    return new Match("edited", oldIndex, similarity);
+  }
+  static inserted() {
+    return new Match("inserted");
+  }
+}
+
+export class Alignment {
+  constructor(newMatches, removed) {
+    this.newMatches = newMatches;
+    this.removed = removed;
+    Object.freeze(this);
+  }
+}
+
+// Diff two block sequences by manufactured key, then by similarity.
+// Pass 1: exact key match, lowest-unused-old-index first (left-to-right so
+// duplicate identical blocks pair deterministically).
+// Pass 2: word-LCS similarity for the remaining; >= EDIT_THRESHOLD => Edited
+// (tiebreak: nearest index), else Inserted.
+export function align(oldBlocks, newBlocks) {
+  const oldKeys = oldBlocks.map(blockKey);
+  const newKeys = newBlocks.map(blockKey);
+  const oldUsed = new Array(oldBlocks.length).fill(false);
+  const newMatches = new Array(newBlocks.length).fill(null);
+
+  for (let ni = 0; ni < newBlocks.length; ni++) {
+    for (let oi = 0; oi < oldBlocks.length; oi++) {
+      if (!oldUsed[oi] && newKeys[ni].equals(oldKeys[oi])) {
+        oldUsed[oi] = true;
+        newMatches[ni] = Match.same(oi);
+        break;
+      }
+    }
+  }
+
+  for (let ni = 0; ni < newBlocks.length; ni++) {
+    if (newMatches[ni] !== null) {
+      continue;
+    }
+    let bestOi = -1;
+    let bestSim = -1;
+    for (let oi = 0; oi < oldBlocks.length; oi++) {
+      if (oldUsed[oi]) {
+        continue;
+      }
+      const sim = similarity(newBlocks[ni].text, oldBlocks[oi].text);
+      const better =
+        sim > bestSim ||
+        (sim === bestSim && Math.abs(oi - ni) < Math.abs(bestOi - ni));
+      if (better) {
+        bestSim = sim;
+        bestOi = oi;
+      }
+    }
+    if (bestOi !== -1 && bestSim >= EDIT_THRESHOLD) {
+      oldUsed[bestOi] = true;
+      newMatches[ni] = Match.edited(bestOi, bestSim);
+    } else {
+      newMatches[ni] = Match.inserted();
+    }
+  }
+
+  const removed = [];
+  for (let oi = 0; oi < oldBlocks.length; oi++) {
+    if (!oldUsed[oi]) {
+      removed.push(oi);
+    }
+  }
+  return new Alignment(newMatches, removed);
+}
+
+// One stable string key per NEW block: Same/Edited inherit the matched old
+// block's key; Inserted mints its own. This is what feeds keyed reconciliation.
+export function assignStableKeys(oldBlocks, newBlocks) {
+  const oldKeyStrings = oldBlocks.map((b) => blockKey(b).asString());
+  const alignment = align(oldBlocks, newBlocks);
+  return alignment.newMatches.map((m, ni) => {
+    if (m.kind === "same" || m.kind === "edited") {
+      return oldKeyStrings[m.oldIndex];
+    }
+    return blockKey(newBlocks[ni]).asString();
+  });
+}

package/src/state-machine.d.ts

@@ -0,0 +1,14 @@
+import type { Context, CellHandle, EffectHandle, SignalHandle } from "./reactive.js";
+
+export type TransitionFn<S, E> = (state: S, event: E) => S | null;
+
+export type TransitionListener<S> = (old: S, next: S) => void;
+
+export class StateMachine<S, E> {
+  constructor(ctx: Context, initial: S, transition: TransitionFn<S, E>);
+  get state(): S;
+  send(event: E): boolean;
+  stateHandle(): CellHandle<S>;
+  onTransition(handler: TransitionListener<S>): EffectHandle;
+  stateIs(target: S): SignalHandle<boolean>;
+}

package/src/state-machine.js

@@ -0,0 +1,78 @@
+// Flat finite-state-machine kernel (lazily-spec/docs/state-machine.md) — the
+// native JavaScript counterpart of lazily-kt's `StateMachine` and the Lean
+// `LazilyFormal.StateMachine`. It is the kernel a single-region state chart
+// compiles down to (state-machine.md: "a flat StateMachine is the degenerate
+// chart with no nesting").
+//
+// A state machine is **compute, not protocol**: it is never serialized as a
+// distinct wire kind — only its current state crosses IPC/FFI as an ordinary
+// cell `Payload`. The state lives in a reactive `Cell` so any slot, signal, or
+// effect that reads `state` is automatically invalidated when the machine
+// transitions. The transition function is pure `(state, event) -> next | null`:
+// a non-null result accepts the event; `null` rejects it (guard). A
+// self-transition that returns an equal state is accepted but suppressed by the
+// cell's `==` guard, so no downstream cascade fires.
+
+import { SignalHandle } from "./reactive.js";
+
+export class StateMachine {
+  #ctx;
+  #cell;
+  #transition;
+
+  constructor(ctx, initial, transition) {
+    if (typeof transition !== "function") {
+      throw new TypeError("StateMachine transition must be a function");
+    }
+    this.#ctx = ctx;
+    this.#transition = transition;
+    this.#cell = ctx.cell(initial);
+  }
+
+  // Send an event. Returns `true` if accepted (non-null), `false` if rejected
+  // (`null`/guard). An accepted transition to an equal state returns `true`
+  // but the `==` guard suppresses invalidation (no downstream cascade).
+  send(event) {
+    const current = this.#ctx.getCell(this.#cell);
+    const next = this.#transition(current, event);
+    if (next === null || next === undefined) {
+      return false;
+    }
+    this.#ctx.setCell(this.#cell, next);
+    return true;
+  }
+
+  get state() {
+    return this.#ctx.getCell(this.#cell);
+  }
+
+  // The underlying active-state cell handle, for reactive composition.
+  stateHandle() {
+    return this.#cell;
+  }
+
+  // Register an effect firing with `(old, new)` on each *real* state change.
+  // Not called on registration; only on subsequent changes. Returns a handle
+  // whose disposal stops further callbacks.
+  onTransition(handler) {
+    let prev = this.state;
+    return this.#ctx.effect(() => {
+      const current = this.state;
+      if (prev !== current) {
+        handler(prev, current);
+      }
+      prev = current;
+      return null;
+    });
+  }
+
+  // An eager signal that is `true` while in `target`, else `false`.
+  stateIs(target) {
+    const slot = this.#ctx.memo(() => this.state === target);
+    const effect = this.#ctx.effect(() => {
+      this.#ctx.get(slot);
+      return null;
+    });
+    return new SignalHandle(slot, effect);
+  }
+}

package/src/state-projection.d.ts

@@ -0,0 +1,114 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * JS-friendly interface to the lazily / agent-doc state-projection FFI channel.
+ *
+ * `loadAgentDocFFI` returns an implementation; tests inject a mock.
+ */
+export interface LazilyFFI {
+  /**
+   * Read the binary's `DocumentStateProjection` JSON for a document, or `null`
+   * when no events have been recorded.
+   */
+  stateProjection(documentHash: string): string | null;
+  /**
+   * Feed a `StateEvent` JSON object into the binary's state backbone.
+   * @returns `true` if accepted, `false` on parse/ledger failure.
+   */
+  recordStateEvent(documentHash: string, factJson: string): boolean;
+}
+
+export interface ProjectionSummary {
+  routeReadiness?: string;
+  routePaneId?: string;
+  latestTransportPatchId?: string;
+  latestTransportPhase?: string;
+  proofMarkers: number;
+}
+
+export interface StateBackboneEvent {
+  event_id: string;
+  fact: Record<string, unknown> & {
+    type: string;
+    document_hash: string;
+  };
+}
+
+/** Compute the canonical-path SHA-256 document key used by agent-doc. */
+export function documentHash(filePath: string): string;
+
+/** Build the Rust `StateEvent` JSON object for a typed fact. */
+export function buildStateEvent(
+  documentHashValue: string,
+  type: string,
+  fields: Record<string, unknown>,
+  eventSuffix: string,
+): StateBackboneEvent;
+
+/** Reduce a `DocumentStateProjection` JSON object into editor status fields. */
+export function projectionSummary(projection: unknown): ProjectionSummary | null;
+
+/** Render the compact editor-visible state projection summary. */
+export function compactProjectionSummary(summary: ProjectionSummary): string;
+
+/** Decode and free one `agent_doc_state_projection` pointer. */
+export function decodeStateProjectionPointer(
+  koffi: unknown,
+  ptr: unknown,
+  freeString: (ptr: unknown) => void,
+): string | null;
+
+/** Wrap an already-loaded native library with the lazily state-projection FFI. */
+export function wrapAgentDocStateProjectionFFI(koffi: unknown, lib: unknown): LazilyFFI;
+
+/**
+ * Lazily load the `agent_doc` native library and wrap its state-projection C
+ * ABI into the {@link LazilyFFI} interface. `koffi` is resolved only when
+ * called, not at module import.
+ */
+export function loadAgentDocFFI(libPath?: string): LazilyFFI;
+
+/** `"projection"` event payload: the new projection JSON, or `null`. */
+export type ProjectionEvent = [projection: string | null];
+
+/**
+ * EventEmitter-based holder for the binary's state projection, plus an event
+ * reporter. The JS analogue of lazily-kt's `StateProjectionClient`.
+ */
+export class StateProjectionClient extends EventEmitter {
+  constructor(documentHash: string, ffi?: LazilyFFI);
+
+  readonly documentHash: string;
+
+  /** Current projection JSON, or `null` when no events have been recorded. */
+  get projection(): string | null;
+
+  /** `true` once a non-null projection has been observed. */
+  get isAvailable(): boolean;
+
+  /**
+   * Pull the latest state projection from the binary. Emits a `"projection"`
+   * event with the new JSON (or `null`).
+   * @returns The freshly-read projection JSON, or `null`.
+   */
+  refresh(): string | null;
+
+  /**
+   * Record a state event in the binary's backbone.
+   * @returns `true` if accepted, `false` on parse/ledger failure.
+   */
+  recordStateEvent(factJson: string): boolean;
+
+  on(event: "projection", listener: (projection: string | null) => void): this;
+  once(event: "projection", listener: (projection: string | null) => void): this;
+  off(event: "projection", listener: (projection: string | null) => void): this;
+  emit(event: "projection", projection: string | null): boolean;
+  addListener(
+    event: "projection",
+    listener: (projection: string | null) => void,
+  ): this;
+  removeListener(
+    event: "projection",
+    listener: (projection: string | null) => void,
+  ): this;
+}

package/src/state-projection.js

@@ -0,0 +1,256 @@
+import { EventEmitter } from "node:events";
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHash } from "node:crypto";
+
+/**
+ * JS-friendly interface to the lazily / agent-doc state-projection FFI channel.
+ *
+ * The native loader (`loadAgentDocFFI`) returns an object implementing this
+ * interface; tests inject a plain-object mock instead (no native dependency).
+ *
+ * Mirrors the Kotlin `LazilyFFI` + `StateProjectionClient` pair from lazily-kt
+ * (#mes4), but adapts the pointer/free lifecycle into the loader boundary so
+ * the consumer never handles raw C pointers.
+ *
+ * @typedef {object} LazilyFFI
+ * @property {(documentHash: string) => (string | null)} stateProjection
+ *   Read the binary's `DocumentStateProjection` JSON for a document, or `null`
+ *   when no events have been recorded. The loader reads the NUL-terminated C
+ *   string and frees the backing pointer before returning.
+ * @property {(documentHash: string, factJson: string) => boolean} recordStateEvent
+ *   Feed a `StateEvent` JSON object into the binary's state backbone. Returns
+ *   `true` if accepted, `false` on parse/ledger failure.
+ */
+
+const nativeRequire = createRequire(import.meta.url);
+
+/**
+ * Compute the canonical document key used by agent-doc snapshots and editor
+ * state-projection events.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function documentHash(filePath) {
+  let canonical;
+  try {
+    canonical = realpathSync(filePath);
+  } catch {
+    canonical = resolve(filePath);
+  }
+  return createHash("sha256").update(canonical, "utf-8").digest("hex");
+}
+
+/**
+ * Build the Rust `StateEvent` JSON shape for a typed fact.
+ *
+ * @param {string} documentHashValue
+ * @param {string} type
+ * @param {Record<string, unknown>} fields
+ * @param {string} eventSuffix
+ * @returns {{ event_id: string, fact: Record<string, unknown> & { type: string, document_hash: string } }}
+ */
+export function buildStateEvent(documentHashValue, type, fields, eventSuffix) {
+  return {
+    event_id: `${documentHashValue}:${eventSuffix}`,
+    fact: {
+      type,
+      document_hash: documentHashValue,
+      ...fields,
+    },
+  };
+}
+
+/**
+ * Reduce a `DocumentStateProjection` JSON object into the compact editor status
+ * shape used by JetBrains and VS Code.
+ *
+ * @param {any} projection
+ * @returns {{ routeReadiness?: string, routePaneId?: string, latestTransportPatchId?: string, latestTransportPhase?: string, proofMarkers: number } | null}
+ */
+export function projectionSummary(projection) {
+  if (!projection || typeof projection !== "object") return null;
+  const route = projection.route ?? {};
+  const transport = projection.transport ?? {};
+  const proof = projection.proof ?? {};
+  const patches = transport.patches && typeof transport.patches === "object"
+    ? Object.entries(transport.patches)
+    : [];
+  const sortedPatches = patches.sort(([a], [b]) => a.localeCompare(b));
+  const latest = sortedPatches.length > 0 ? sortedPatches[sortedPatches.length - 1] : undefined;
+  return {
+    routeReadiness: typeof route.readiness === "string" ? route.readiness : undefined,
+    routePaneId: typeof route.pane_id === "string" ? route.pane_id : undefined,
+    latestTransportPatchId: latest?.[0],
+    latestTransportPhase: typeof latest?.[1]?.phase === "string" ? latest[1].phase : undefined,
+    proofMarkers: proof.markers && typeof proof.markers === "object"
+      ? Object.keys(proof.markers).length
+      : 0,
+  };
+}
+
+/**
+ * Render a compact editor-visible status string for a projection summary.
+ *
+ * @param {{ routeReadiness?: string, routePaneId?: string, latestTransportPatchId?: string, latestTransportPhase?: string, proofMarkers: number }} summary
+ * @returns {string}
+ */
+export function compactProjectionSummary(summary) {
+  return `route=${summary.routeReadiness ?? "unknown"} pane=${summary.routePaneId ?? "-"} `
+    + `transport=${summary.latestTransportPatchId ?? "-"}:${summary.latestTransportPhase ?? "-"} `
+    + `proof_markers=${summary.proofMarkers}`;
+}
+
+/**
+ * Decode and free one `agent_doc_state_projection` pointer.
+ *
+ * @param {any} koffi
+ * @param {any} ptr
+ * @param {(ptr: any) => void} freeString
+ * @returns {string | null}
+ */
+export function decodeStateProjectionPointer(koffi, ptr, freeString) {
+  if (ptr === null || ptr === undefined) return null;
+  const address = typeof koffi.address === "function" ? koffi.address(ptr) : 1n;
+  if (address === 0n || address === 0) return null;
+  try {
+    const json = koffi.decode.string(ptr);
+    return json === "null" || json == null ? null : json;
+  } finally {
+    freeString(ptr);
+  }
+}
+
+/**
+ * Wrap an already-loaded native library with the lazily state-projection FFI
+ * interface. Exported so package and editor parity tests can cover pointer/free
+ * lifecycle without loading a real native library.
+ *
+ * @param {any} koffi
+ * @param {any} lib
+ * @returns {LazilyFFI}
+ */
+export function wrapAgentDocStateProjectionFFI(koffi, lib) {
+  const state_projection = lib.func(
+    "void *agent_doc_state_projection(const char *document_hash)",
+  );
+  const record_state_event = lib.func(
+    "int agent_doc_record_state_event(const char *document_hash, const char *fact_json)",
+  );
+  const free_string = lib.func("void agent_doc_free_string(void *ptr)");
+  return {
+    stateProjection(documentHashValue) {
+      return decodeStateProjectionPointer(
+        koffi,
+        state_projection(documentHashValue),
+        free_string,
+      );
+    },
+    recordStateEvent(documentHashValue, factJson) {
+      return record_state_event(documentHashValue, factJson) === 1;
+    },
+  };
+}
+
+/**
+ * Lazily load the `agent_doc` native library and wrap its state-projection C
+ * ABI into the {@link LazilyFFI} interface.
+ *
+ * Uses `createRequire` so `koffi` is resolved **only when this function is
+ * called**, not when the module is imported — keeping `make check` (pure-JS
+ * tests with injected mocks) free of any native build dependency. koffi ships
+ * prebuilt binaries (no native compile step), so — unlike the previous
+ * ffi-napi/ref-napi loader — it installs cleanly on Node >= 23 (ffi-napi's
+ * `napi_add_finalizer` ABI break made it uninstallable there).
+ *
+ * @param {string} [libPath] Library name or path (defaults to `agent_doc`,
+ *   resolved from the process load path / `LD_LIBRARY_PATH`).
+ * @returns {LazilyFFI}
+ */
+export function loadAgentDocFFI(libPath) {
+  const koffi = nativeRequire("koffi");
+  const lib = koffi.load(libPath ?? "agent_doc");
+  return wrapAgentDocStateProjectionFFI(koffi, lib);
+}
+
+/**
+ * Holds the raw JSON projection returned by the binary's
+ * `agent_doc_state_projection` FFI, exposed as an `EventEmitter` for reactive
+ * UI binding (VSCode status items, webviews), plus {@link recordStateEvent}
+ * for feeding facts into the binary's state backbone.
+ *
+ * `null` means no state events have been recorded for the document. The JSON
+ * contains document/queue/closeout/transport/supervisor/route/proof slices —
+ * consumers parse it with their preferred JSON library.
+ *
+ * This is the JS analogue of lazily-kt's `StateProjectionClient` (Kotlin
+ * `StateFlow` → JS `EventEmitter`): plugins become thin projection-renderer +
+ * event-reporter, NOT a reactive-core port (FFI-first rule).
+ *
+ * @example
+ * import { StateProjectionClient, loadAgentDocFFI } from "@lazily-hub/js/state-projection";
+ * const ffi = loadAgentDocFFI();
+ * const client = new StateProjectionClient(documentHash, ffi);
+ * client.on("projection", (json) => renderStatus(json));
+ * client.refresh();                 // pull latest projection, emits "projection"
+ * client.recordStateEvent(JSON.stringify({ type: "BaselineSaved" }));
+ */
+export class StateProjectionClient extends EventEmitter {
+  #documentHash;
+  #ffi;
+  #projection = null;
+
+  /**
+   * @param {string} documentHash
+   * @param {LazilyFFI} [ffi] Native FFI handle. When omitted the `agent_doc`
+   *   library is loaded eagerly via {@link loadAgentDocFFI}. Tests pass a
+   *   plain-object mock implementing {@link LazilyFFI}.
+   */
+  constructor(documentHash, ffi = loadAgentDocFFI()) {
+    super();
+    this.#documentHash = documentHash;
+    this.#ffi = ffi;
+  }
+
+  /** The document hash this client is bound to. */
+  get documentHash() {
+    return this.#documentHash;
+  }
+
+  /** Current projection JSON, or `null` when no events have been recorded. */
+  get projection() {
+    return this.#projection;
+  }
+
+  /** `true` once a non-null projection has been observed. */
+  get isAvailable() {
+    return this.#projection !== null;
+  }
+
+  /**
+   * Pull the latest state projection from the binary. Updates {@link projection}
+   * and emits a `"projection"` event with the new JSON (or `null`). Safe to call
+   * on any thread — the FFI is thread-safe.
+   *
+   * @returns {string | null} The freshly-read projection JSON, or `null`.
+   */
+  refresh() {
+    const json = this.#ffi.stateProjection(this.#documentHash);
+    this.#projection = json;
+    this.emit("projection", json);
+    return json;
+  }
+
+  /**
+   * Record a state event in the binary's backbone.
+   *
+   * @param {string} factJson JSON object deserializable as a `StateEvent`
+   *   (internally tagged `{ "event_id": "...", "fact": { "type": "..." } }`).
+   * @returns {boolean} `true` if accepted, `false` on parse/ledger failure.
+   */
+  recordStateEvent(factJson) {
+    return this.#ffi.recordStateEvent(this.#documentHash, factJson);
+  }
+}