arborkit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 1.0.0 — 2026-07-03
+
+First public release of Arbor as `arborkit`. The milestone arc:
+
+- Artifact tree with size/type-aware decomposition — large JSON splits into addressable nodes automatically (M1–M2).
+- Typed nodes via a Zod adapter and a pluggable type registry (M3).
+- Lazy navigator with glob-based `find` over paths, types, and tags (M4).
+- Per-node semantic index with a stale-node lifecycle and batched `reindex` (M5).
+- Snapshot persistence: `serializeArtifact`/`restoreArtifact` over a `StoragePort` (memory + atomic file impls) (M6).
+- Reversible event log with value-level replay: `getAt`, `diff`, time-travel, and `revert` (M7).
+- Scoped agent toolset — `describe`/`get`/`patch`/`find`/`search`/`history` with structured results and read/write scopes (M8).
+- End-to-end content-site scenario plus a runnable example (M9).
+- Hardening round 1: tx rollback restores index state, deep-cloned tool results, atomic file saves, type-aware revert (M10).
+- Packaging: ESM build via tsup, exports map, pack-and-run capstone in plain Node (M11).
+- Opt-in event-log compaction: `compactTo` + `baseSeq` sliding window, floor-aware replay, StoredArtifact v2 (v1 files still load) (M12).
+- Delta persistence: checkpoint + appendable NDJSON journal with forward-replay restore (`DeltaStoragePort`, memory + file impls) (M13).
+- Hardening round 2: move guards, aliasing hygiene, interleave-safe reindex, tags recorded in events, move-aware revert (M14).
+- API polish: async `VectorIndexPort`, `patch` returns `{id, path, version}`, `find` returns `{hits, truncated}`, single `isWithin` scope helper (M15).
+- `createArbor`/`restoreArbor` facade — one-call wiring, guarded restore, auto-checkpoint on first `saveDelta` — and published as `arborkit` (M15–M16).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 D. A. Pominov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# Arbor (`arborkit`)
+
+A general-purpose TypeScript core for multi-agent systems built around one shared
+**artifact tree**: agents navigate and edit a JSON tree through scoped tools, with a
+per-node exact + semantic index, a reversible event log, snapshots + delta persistence,
+and time-travel. **Zero runtime dependencies.**
+
+```bash
+npm install arborkit
+```
+
+ESM-only, Node ≥ 20.6.
+
+## The stack
+
+- **Tree** — decompose a JSON value into addressable nodes (stable ids + JSON-Pointer paths), reconstruct any subtree.
+- **Mutations** — `set`/`insert`/`remove`/`move` with scope + optimistic-version guards, recorded in a reversible event log; atomic transactions.
+- **Types** — optional per-type validation + decomposition override (`TypeRegistry`); a structural Zod adapter (zod is a dev-only dependency).
+- **Navigate** — `describe`/`get`/`find` (by id, path, tag, or glob) — depth-bounded and paginated; `find` returns `{hits, truncated}` so truncation is never silent.
+- **Semantic index** — per-node embeddings via pluggable `EmbeddingPort`/`VectorIndexPort` (async — DB-backed adapters welcome); `search` by meaning returns `{results, staleCount}`, off the mutation path (mutations only mark stale; an async reindexer embeds).
+- **Storage** — serialize the whole artifact (tree + log + vectors) to memory or a JSON file; or persist incrementally (checkpoint + appendable NDJSON journal); restore intact either way.
+- **Replay** — reconstruct any past version, `diff` two versions, `revert` a node (append-only, path-addressed).
+- **Toolset** — hand an agent a scoped, async, structured-result bundle: `describe`/`get`/`find`/`search`/`patch`/`history`. Writes are confined to `writeScope`, reads to `readScope`; errors are returned, never thrown across the boundary. `patch` returns `{id, path, version}` of the touched node.
+- **Facade** — `createArbor`/`restoreArbor` wire all of the above in one call.
+
+## Quickstart
+
+```ts
+import { createArbor, restoreArbor, MockEmbeddingPort, MemoryDeltaStorage, sizeBasedDecision } from "arborkit";
+
+const delta = new MemoryDeltaStorage();
+const arbor = createArbor({
+  initial: { pages: {}, plan: "" },
+  decompose: sizeBasedDecision(1), // decompose aggressively so this tiny demo gets addressable nodes
+  embedding: new MockEmbeddingPort(), // swap in a real EmbeddingPort (e.g. an API-backed one)
+  delta,
+});
+
+// Hand an agent a scoped toolset — writes confined to /pages:
+const tools = arbor.toolset({ owner: "writer", writeScope: "/pages", readScope: "/pages" });
+const ins = await tools.patch({ path: "/pages" }, { op: "insert", key: "home", value: { title: "Home" } });
+if (!ins.ok) throw new Error(ins.error.message); // ins.value === { id, path: "/pages/home", version }
+const home = await tools.get({ path: "/pages/home" }); // home.value.content === { title: "Home" } (a clone)
+const refused = await tools.patch({ path: "/plan" }, { op: "set", value: "hacked" });
+// refused.ok === false — out of scope; violations are returned, never thrown
+
+// Semantic search — mutations only mark nodes stale; reindex() embeds:
+await arbor.index!.reindex();
+const found = await arbor.index!.search("home page"); // { results, staleCount }
+
+// Incremental persistence — the first saveDelta() auto-checkpoints:
+await arbor.saveDelta();
+
+// Later (e.g. a new process): restore, then time-travel:
+const restored = await restoreArbor({ decompose: sizeBasedDecision(1), embedding: new MockEmbeddingPort(), delta });
+const past = restored!.replay.getAt("/pages/home", 0); // undefined — before the insert
+```
+
+## Lifecycle notes
+
+- The first `saveDelta()` auto-checkpoints — a journal without a checkpoint is
+  unrestorable, so the facade snapshots instead of appending.
+- `checkpoint({ keepLast: N })` first compacts the event log to a sliding window of
+  the last N events, then snapshots — this is the knob that bounds both memory and
+  checkpoint size.
+- Time-travel (`getAt`/`reconstructValueAt`/`revert`) below the compaction floor
+  throws — that history is gone by design.
+- `restoreArbor` MUST be given the same `decompose`/`registry` as the original run:
+  journal-touched nodes are re-decomposed on delta restore, so a different policy
+  would silently reshape the tree.
+
+## Format compatibility
+
+StoredArtifact **v1** files (written before compaction existed) still load; **v2**
+adds `baseSeq` (the persisted compaction floor). Delta storage keeps a checkpoint
+plus an NDJSON journal; a torn journal tail is isolated on restore.
+
+## Scope & limits (read this before adopting)
+
+- **Single process, single writer.** The tree lives in memory; storage is a snapshot
+  target, not a database. There is no locking — two processes sharing one artifact
+  file will clobber each other. One artifact = one run = one process.
+- **Scoping is a guardrail, not a security boundary.** `writeScope`/`readScope`
+  contain an agent's *tool calls* (including prompt-injected ones — a writer scoped
+  to `/pages/home` has no path to `/secret`). They do NOT isolate *code*: every
+  toolset shares the same heap, and anything holding the `Mutator` or tree can
+  bypass scope. Do not run mutually-untrusted agent code in one process.
+- **Log growth is bounded by opt-in compaction.** `EventLog.compactTo(floorSeq)` drops
+  history before a floor — e.g. `log.compactTo(log.length() - N)` keeps a sliding window
+  of the last N events, capping both memory and the serialized event payload (the floor
+  is persisted as `baseSeq` and survives restore). Time-travel below the floor throws —
+  that history is gone. Nothing auto-compacts; choose a policy (per run, sliding window,
+  or never; `checkpoint({keepLast})` is the facade shortcut).
+- **Saves can be incremental (opt-in delta persistence).** `DeltaStoragePort` (memory + file)
+  splits persistence into a periodic full checkpoint and cheap event appends — a
+  routine save costs O(new events) instead of rewriting the whole artifact. Restore loads
+  the checkpoint and forward-replays the journal, preserving node types and the vectors of
+  unchanged nodes (touched nodes are re-decomposed and left stale for reindex). A checkpoint
+  still serializes the whole **tree** — delta-of-tree is future work; restore must use the
+  same decompose decision as the original run.
+- **Vector search is brute-force cosine** in the bundled `MemoryVectorIndex` — comfortable
+  to ~10⁴ vectors; plug a real ANN store into the (async) `VectorIndexPort` beyond that.
+- **Ops are id-anchored** (a useful property for a future CRDT backend), but there is
+  **no CRDT**: no merge, no convergence, no multi-writer conflict resolution.
+- **`ifVersion` on `insert` is parent-scoped:** it is a compare-and-set on the
+  *container's* version, and every sibling insert bumps the container. Use it to
+  guard "the container hasn't changed", not "my item is new".
+
+## Run the example
+
+```bash
+npm run example   # narrated end-to-end content-site scenario (examples/content-site.ts)
+```
+
+## Develop
+
+```bash
+npm test          # vitest
+npm run typecheck # tsc --noEmit
+npm run build     # tsup → dist/ (ESM + type declarations)
+```
+
+Subpath imports work too: `import { Replay } from "arborkit/replay";` — every
+module in `src/` maps onto `arborkit/<module>`.
+
+## Docs
+
+Design spec and milestone plans live in [`docs/superpowers/`](docs/superpowers/).
+
+## Status
+
+**v1 core complete (M1–M9), hardened (M10), packaged (M11), log compaction (M12), delta persistence (M13), hardening-2 (M14), API polish + facade (M15), published as arborkit (M16):** tree, mutations + reversible log, optional types, exact navigation, semantic index, storage, replay/time-travel, scoped agent toolset, end-to-end scenario, index-lifecycle hardening, and an installable ESM build.
+
+Deferred (post-v1): LangChain `tool()` / MCP-server adapters over the toolset; `getAt`/`revert` as toolset methods; DB-backed storage & vector adapters (SQLite/sqlite-vec, Postgres/pgvector); a CRDT backend.

package/dist/addressing.d.ts

@@ -0,0 +1,22 @@
+import { NodeId, ArbNode } from './types.js';
+import { ArtifactTree } from './artifact-tree.js';
+import './ids.js';
+import './clock.js';
+import './decompose.js';
+
+/**
+ * Resolves nodes by stable id and by JSON Pointer path.
+ * `path` is DERIVED from the current structure (not stored), so it stays
+ * consistent automatically — id is identity, path is current location.
+ */
+declare class Addressing {
+    private readonly tree;
+    constructor(tree: ArtifactTree);
+    byId(id: NodeId): ArbNode | undefined;
+    /** Compute the JSON Pointer for a node by walking parent links to the root. */
+    pathOf(id: NodeId): string;
+    /** Resolve a JSON Pointer to a node, or undefined if any segment is missing. */
+    byPath(pointer: string): ArbNode | undefined;
+}
+
+export { Addressing };

package/dist/addressing.js

@@ -0,0 +1,56 @@
+// src/jsonpointer.ts
+function encodeSegment(s) {
+  return s.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function decodeSegment(s) {
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function buildPointer(segments) {
+  if (segments.length === 0) return "";
+  return "/" + segments.map((s) => encodeSegment(String(s))).join("/");
+}
+function parsePointer(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) {
+    throw new Error(`Invalid JSON Pointer (must be "" or start with "/"): ${pointer}`);
+  }
+  return pointer.slice(1).split("/").map(decodeSegment);
+}
+
+// src/addressing.ts
+var Addressing = class {
+  constructor(tree) {
+    this.tree = tree;
+  }
+  tree;
+  byId(id) {
+    return this.tree.get(id);
+  }
+  /** Compute the JSON Pointer for a node by walking parent links to the root. */
+  pathOf(id) {
+    const cur0 = this.tree.get(id);
+    if (!cur0) throw new Error(`Unknown node: ${id}`);
+    const segments = [];
+    let cur = cur0;
+    while (cur && cur.parentId !== null) {
+      segments.unshift(cur.key);
+      cur = this.tree.get(cur.parentId);
+    }
+    return buildPointer(segments);
+  }
+  /** Resolve a JSON Pointer to a node, or undefined if any segment is missing. */
+  byPath(pointer) {
+    const segments = parsePointer(pointer);
+    let cur = this.tree.root();
+    for (const seg of segments) {
+      if (!cur) return void 0;
+      cur = this.tree.childByKey(cur.id, seg);
+      if (!cur) return void 0;
+    }
+    return cur;
+  }
+};
+export {
+  Addressing
+};
+//# sourceMappingURL=addressing.js.map

package/dist/addressing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/jsonpointer.ts","../src/addressing.ts"],"sourcesContent":["/** Escape a single reference token per RFC 6901: ~ -> ~0, / -> ~1. */\r\nexport function encodeSegment(s: string): string {\r\n  return s.replace(/~/g, \"~0\").replace(/\\//g, \"~1\");\r\n}\r\n\r\n/** Unescape a single reference token per RFC 6901: ~1 -> /, then ~0 -> ~. */\r\nexport function decodeSegment(s: string): string {\r\n  return s.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\r\n}\r\n\r\n/** Build a JSON Pointer string. Empty segment list => \"\" (root). */\r\nexport function buildPointer(segments: ReadonlyArray<string | number>): string {\r\n  if (segments.length === 0) return \"\";\r\n  return \"/\" + segments.map((s) => encodeSegment(String(s))).join(\"/\");\r\n}\r\n\r\n/** Append one child key to a parent pointer, escaping the key exactly as `buildPointer` does. */\r\nexport function appendPointer(parent: string, key: string | number): string {\r\n  return parent + \"/\" + encodeSegment(String(key));\r\n}\r\n\r\n/** True when `path` is at or under `scope` (JSON Pointer prefix). Undefined scope = everywhere. */\r\nexport function isWithin(path: string, scope: string | undefined): boolean {\r\n  return scope === undefined || path === scope || path.startsWith(scope + \"/\");\r\n}\r\n\r\n/** Parse a JSON Pointer into decoded segments. \"\" => [] (root). */\r\nexport function parsePointer(pointer: string): string[] {\r\n  if (pointer === \"\") return [];\r\n  if (!pointer.startsWith(\"/\")) {\r\n    throw new Error(`Invalid JSON Pointer (must be \"\" or start with \"/\"): ${pointer}`);\r\n  }\r\n  return pointer.slice(1).split(\"/\").map(decodeSegment);\r\n}\r\n","import type { ArbNode, NodeId } from \"./types\";\r\nimport type { ArtifactTree } from \"./artifact-tree\";\r\nimport { buildPointer, parsePointer } from \"./jsonpointer\";\r\n\r\n/**\r\n * Resolves nodes by stable id and by JSON Pointer path.\r\n * `path` is DERIVED from the current structure (not stored), so it stays\r\n * consistent automatically — id is identity, path is current location.\r\n */\r\nexport class Addressing {\r\n  constructor(private readonly tree: ArtifactTree) {}\r\n\r\n  byId(id: NodeId): ArbNode | undefined {\r\n    return this.tree.get(id);\r\n  }\r\n\r\n  /** Compute the JSON Pointer for a node by walking parent links to the root. */\r\n  pathOf(id: NodeId): string {\r\n    const cur0 = this.tree.get(id);\r\n    if (!cur0) throw new Error(`Unknown node: ${id}`);\r\n    const segments: (string | number)[] = [];\r\n    let cur: ArbNode | undefined = cur0;\r\n    while (cur && cur.parentId !== null) {\r\n      segments.unshift(cur.key as string | number);\r\n      cur = this.tree.get(cur.parentId);\r\n    }\r\n    return buildPointer(segments);\r\n  }\r\n\r\n  /** Resolve a JSON Pointer to a node, or undefined if any segment is missing. */\r\n  byPath(pointer: string): ArbNode | undefined {\r\n    const segments = parsePointer(pointer);\r\n    let cur: ArbNode | undefined = this.tree.root();\r\n    for (const seg of segments) {\r\n      if (!cur) return undefined;\r\n      // parsePointer yields UNescaped segments and node keys are raw strings —\r\n      // they match childByKey's String(key) map keys directly.\r\n      cur = this.tree.childByKey(cur.id, seg);\r\n      if (!cur) return undefined;\r\n    }\r\n    return cur;\r\n  }\r\n}\r\n"],"mappings":";AACO,SAAS,cAAc,GAAmB;AAC/C,SAAO,EAAE,QAAQ,MAAM,IAAI,EAAE,QAAQ,OAAO,IAAI;AAClD;AAGO,SAAS,cAAc,GAAmB;AAC/C,SAAO,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG;AACjD;AAGO,SAAS,aAAa,UAAkD;AAC7E,MAAI,SAAS,WAAW,EAAG,QAAO;AAClC,SAAO,MAAM,SAAS,IAAI,CAAC,MAAM,cAAc,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG;AACrE;AAaO,SAAS,aAAa,SAA2B;AACtD,MAAI,YAAY,GAAI,QAAO,CAAC;AAC5B,MAAI,CAAC,QAAQ,WAAW,GAAG,GAAG;AAC5B,UAAM,IAAI,MAAM,wDAAwD,OAAO,EAAE;AAAA,EACnF;AACA,SAAO,QAAQ,MAAM,CAAC,EAAE,MAAM,GAAG,EAAE,IAAI,aAAa;AACtD;;;ACxBO,IAAM,aAAN,MAAiB;AAAA,EACtB,YAA6B,MAAoB;AAApB;AAAA,EAAqB;AAAA,EAArB;AAAA,EAE7B,KAAK,IAAiC;AACpC,WAAO,KAAK,KAAK,IAAI,EAAE;AAAA,EACzB;AAAA;AAAA,EAGA,OAAO,IAAoB;AACzB,UAAM,OAAO,KAAK,KAAK,IAAI,EAAE;AAC7B,QAAI,CAAC,KAAM,OAAM,IAAI,MAAM,iBAAiB,EAAE,EAAE;AAChD,UAAM,WAAgC,CAAC;AACvC,QAAI,MAA2B;AAC/B,WAAO,OAAO,IAAI,aAAa,MAAM;AACnC,eAAS,QAAQ,IAAI,GAAsB;AAC3C,YAAM,KAAK,KAAK,IAAI,IAAI,QAAQ;AAAA,IAClC;AACA,WAAO,aAAa,QAAQ;AAAA,EAC9B;AAAA;AAAA,EAGA,OAAO,SAAsC;AAC3C,UAAM,WAAW,aAAa,OAAO;AACrC,QAAI,MAA2B,KAAK,KAAK,KAAK;AAC9C,eAAW,OAAO,UAAU;AAC1B,UAAI,CAAC,IAAK,QAAO;AAGjB,YAAM,KAAK,KAAK,WAAW,IAAI,IAAI,GAAG;AACtC,UAAI,CAAC,IAAK,QAAO;AAAA,IACnB;AACA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/ag-ui.d.ts

@@ -0,0 +1,45 @@
+import { Json } from './types.js';
+import { ArtifactTree } from './artifact-tree.js';
+import { EventLog, MutationEvent } from './event-log.js';
+import './ids.js';
+import './clock.js';
+import './decompose.js';
+
+/** RFC 6902 operation (the subset Arbor emits). */
+type JsonPatchOp = {
+    op: "replace" | "add";
+    path: string;
+    value: Json;
+} | {
+    op: "remove";
+    path: string;
+} | {
+    op: "move";
+    from: string;
+    path: string;
+};
+interface AgUiStateSnapshot {
+    type: "STATE_SNAPSHOT";
+    snapshot: Json;
+}
+interface AgUiStateDelta {
+    type: "STATE_DELTA";
+    delta: JsonPatchOp[];
+}
+/** One mutation event as an RFC 6902 op, or null for pre-M7 events without paths. */
+declare function toJsonPatch(e: MutationEvent): JsonPatchOp | null;
+/** The full current state as an AG-UI STATE_SNAPSHOT event. */
+declare function snapshotEvent(tree: ArtifactTree): AgUiStateSnapshot;
+/** Retained events with seq >= sinceSeq as ONE AG-UI STATE_DELTA event (pathless
+ *  pre-M7 events are skipped). Returns the delta plus the next since-cursor.
+ *
+ *  Throws InvalidOpError when `sinceSeq` is below the log's compaction floor:
+ *  the events in [sinceSeq, baseSeq) are gone, and applying a gapped delta would
+ *  silently diverge the client. On this error the caller must re-send a fresh
+ *  `snapshotEvent` (and resume deltas from the current version) instead. */
+declare function deltaSince(log: EventLog, sinceSeq: number): {
+    event: AgUiStateDelta;
+    nextSeq: number;
+};
+
+export { type AgUiStateDelta, type AgUiStateSnapshot, type JsonPatchOp, deltaSince, snapshotEvent, toJsonPatch };

package/dist/ag-ui.js

@@ -0,0 +1,50 @@
+// src/errors.ts
+var ArborError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+  }
+  code;
+};
+var InvalidOpError = class extends ArborError {
+  constructor(message) {
+    super("INVALID_OP", message);
+  }
+};
+
+// src/ag-ui.ts
+function toJsonPatch(e) {
+  switch (e.kind) {
+    case "set":
+      return e.path === void 0 ? null : { op: "replace", path: e.path, value: e.after ?? null };
+    case "insert":
+      return e.path === void 0 ? null : { op: "add", path: e.path, value: e.after ?? null };
+    case "remove":
+      return e.path === void 0 ? null : { op: "remove", path: e.path };
+    case "move":
+      return e.fromPath === void 0 || e.toPath === void 0 ? null : { op: "move", from: e.fromPath, path: e.toPath };
+  }
+}
+function snapshotEvent(tree) {
+  return { type: "STATE_SNAPSHOT", snapshot: tree.toJson() };
+}
+function deltaSince(log, sinceSeq) {
+  if (sinceSeq < log.baseSeqValue()) {
+    throw new InvalidOpError(
+      `deltaSince: events [${sinceSeq}, ${log.baseSeqValue()}) were compacted away \u2014 send a fresh STATE_SNAPSHOT instead`
+    );
+  }
+  const delta = [];
+  for (const e of log.since(sinceSeq)) {
+    const op = toJsonPatch(e);
+    if (op) delta.push(op);
+  }
+  return { event: { type: "STATE_DELTA", delta }, nextSeq: log.length() };
+}
+export {
+  deltaSince,
+  snapshotEvent,
+  toJsonPatch
+};
+//# sourceMappingURL=ag-ui.js.map

package/dist/ag-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/ag-ui.ts"],"sourcesContent":["import type { NodeId } from \"./types\";\r\n\r\n/** A reference to a node: by stable id or by JSON Pointer path. */\r\nexport type Ref = { id: NodeId } | { path: string };\r\n\r\nexport class ArborError extends Error {\r\n  constructor(\r\n    public readonly code: string,\r\n    message: string,\r\n  ) {\r\n    super(message);\r\n    this.name = new.target.name;\r\n  }\r\n}\r\n\r\nexport class NodeNotFoundError extends ArborError {\r\n  constructor(public readonly ref: Ref) {\r\n    super(\"NODE_NOT_FOUND\", `Node not found: ${JSON.stringify(ref)}`);\r\n  }\r\n}\r\n\r\nexport class ScopeViolationError extends ArborError {\r\n  constructor(\r\n    public readonly targetPath: string,\r\n    public readonly scope: string,\r\n  ) {\r\n    super(\"SCOPE_VIOLATION\", `Access outside scope: ${targetPath} (scope: ${scope})`);\r\n  }\r\n}\r\n\r\nexport class StaleVersionError extends ArborError {\r\n  constructor(\r\n    public readonly id: NodeId,\r\n    public readonly expected: number,\r\n    public readonly actual: number,\r\n  ) {\r\n    super(\"STALE_VERSION\", `Stale version for ${id}: expected ${expected}, actual ${actual}`);\r\n  }\r\n}\r\n\r\nexport class InvalidOpError extends ArborError {\r\n  constructor(message: string) {\r\n    super(\"INVALID_OP\", message);\r\n  }\r\n}\r\n\r\nexport class ValidationError extends ArborError {\r\n  constructor(\r\n    public readonly type: string | undefined,\r\n    public readonly details: string,\r\n  ) {\r\n    super(\"VALIDATION_ERROR\", `Validation failed${type ? ` for type ${type}` : \"\"}: ${details}`);\r\n  }\r\n}\r\n","// AG-UI adapter — expose the artifact tree + event log as AG-UI shared-state\r\n// events (STATE_SNAPSHOT / STATE_DELTA with RFC 6902 JSON Patch ops). Zero-dep:\r\n// these are plain objects shaped like AG-UI events, no AG-UI SDK required.\r\nimport type { Json } from \"./types\";\r\nimport type { ArtifactTree } from \"./artifact-tree\";\r\nimport type { EventLog, MutationEvent } from \"./event-log\";\r\nimport { InvalidOpError } from \"./errors\";\r\n\r\n/** RFC 6902 operation (the subset Arbor emits). */\r\nexport type JsonPatchOp =\r\n  | { op: \"replace\" | \"add\"; path: string; value: Json }\r\n  | { op: \"remove\"; path: string }\r\n  | { op: \"move\"; from: string; path: string };\r\n\r\nexport interface AgUiStateSnapshot {\r\n  type: \"STATE_SNAPSHOT\";\r\n  snapshot: Json;\r\n}\r\n\r\nexport interface AgUiStateDelta {\r\n  type: \"STATE_DELTA\";\r\n  delta: JsonPatchOp[];\r\n}\r\n\r\n/** One mutation event as an RFC 6902 op, or null for pre-M7 events without paths. */\r\nexport function toJsonPatch(e: MutationEvent): JsonPatchOp | null {\r\n  switch (e.kind) {\r\n    case \"set\":\r\n      return e.path === undefined ? null : { op: \"replace\", path: e.path, value: e.after ?? null };\r\n    case \"insert\":\r\n      return e.path === undefined ? null : { op: \"add\", path: e.path, value: e.after ?? null };\r\n    case \"remove\":\r\n      return e.path === undefined ? null : { op: \"remove\", path: e.path };\r\n    case \"move\":\r\n      return e.fromPath === undefined || e.toPath === undefined\r\n        ? null\r\n        : { op: \"move\", from: e.fromPath, path: e.toPath };\r\n  }\r\n}\r\n\r\n/** The full current state as an AG-UI STATE_SNAPSHOT event. */\r\nexport function snapshotEvent(tree: ArtifactTree): AgUiStateSnapshot {\r\n  return { type: \"STATE_SNAPSHOT\", snapshot: tree.toJson() };\r\n}\r\n\r\n/** Retained events with seq >= sinceSeq as ONE AG-UI STATE_DELTA event (pathless\r\n *  pre-M7 events are skipped). Returns the delta plus the next since-cursor.\r\n *\r\n *  Throws InvalidOpError when `sinceSeq` is below the log's compaction floor:\r\n *  the events in [sinceSeq, baseSeq) are gone, and applying a gapped delta would\r\n *  silently diverge the client. On this error the caller must re-send a fresh\r\n *  `snapshotEvent` (and resume deltas from the current version) instead. */\r\nexport function deltaSince(log: EventLog, sinceSeq: number): { event: AgUiStateDelta; nextSeq: number } {\r\n  if (sinceSeq < log.baseSeqValue()) {\r\n    throw new InvalidOpError(\r\n      `deltaSince: events [${sinceSeq}, ${log.baseSeqValue()}) were compacted away — send a fresh STATE_SNAPSHOT instead`,\r\n    );\r\n  }\r\n  const delta: JsonPatchOp[] = [];\r\n  for (const e of log.since(sinceSeq)) {\r\n    const op = toJsonPatch(e);\r\n    if (op) delta.push(op);\r\n  }\r\n  return { event: { type: \"STATE_DELTA\", delta }, nextSeq: log.length() };\r\n}\r\n"],"mappings":";AAKO,IAAM,aAAN,cAAyB,MAAM;AAAA,EACpC,YACkB,MAChB,SACA;AACA,UAAM,OAAO;AAHG;AAIhB,SAAK,OAAO,WAAW;AAAA,EACzB;AAAA,EALkB;AAMpB;AA2BO,IAAM,iBAAN,cAA6B,WAAW;AAAA,EAC7C,YAAY,SAAiB;AAC3B,UAAM,cAAc,OAAO;AAAA,EAC7B;AACF;;;ACnBO,SAAS,YAAY,GAAsC;AAChE,UAAQ,EAAE,MAAM;AAAA,IACd,KAAK;AACH,aAAO,EAAE,SAAS,SAAY,OAAO,EAAE,IAAI,WAAW,MAAM,EAAE,MAAM,OAAO,EAAE,SAAS,KAAK;AAAA,IAC7F,KAAK;AACH,aAAO,EAAE,SAAS,SAAY,OAAO,EAAE,IAAI,OAAO,MAAM,EAAE,MAAM,OAAO,EAAE,SAAS,KAAK;AAAA,IACzF,KAAK;AACH,aAAO,EAAE,SAAS,SAAY,OAAO,EAAE,IAAI,UAAU,MAAM,EAAE,KAAK;AAAA,IACpE,KAAK;AACH,aAAO,EAAE,aAAa,UAAa,EAAE,WAAW,SAC5C,OACA,EAAE,IAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,EAAE,OAAO;AAAA,EACvD;AACF;AAGO,SAAS,cAAc,MAAuC;AACnE,SAAO,EAAE,MAAM,kBAAkB,UAAU,KAAK,OAAO,EAAE;AAC3D;AASO,SAAS,WAAW,KAAe,UAA8D;AACtG,MAAI,WAAW,IAAI,aAAa,GAAG;AACjC,UAAM,IAAI;AAAA,MACR,uBAAuB,QAAQ,KAAK,IAAI,aAAa,CAAC;AAAA,IACxD;AAAA,EACF;AACA,QAAM,QAAuB,CAAC;AAC9B,aAAW,KAAK,IAAI,MAAM,QAAQ,GAAG;AACnC,UAAM,KAAK,YAAY,CAAC;AACxB,QAAI,GAAI,OAAM,KAAK,EAAE;AAAA,EACvB;AACA,SAAO,EAAE,OAAO,EAAE,MAAM,eAAe,MAAM,GAAG,SAAS,IAAI,OAAO,EAAE;AACxE;","names":[]}

package/dist/arbor.d.ts

@@ -0,0 +1,73 @@
+import { Json } from './types.js';
+import { ArtifactTree } from './artifact-tree.js';
+import { Addressing } from './addressing.js';
+import { EventLog } from './event-log.js';
+import { Mutator } from './mutator.js';
+import { Replay } from './replay.js';
+import { SemanticIndex } from './semantic-index.js';
+import { ToolsetBinding, Toolset } from './toolset.js';
+import { TypeRegistry } from './type-registry.js';
+import { DecomposeDecision } from './decompose.js';
+import { IdGen } from './ids.js';
+import { Clock } from './clock.js';
+import { EmbeddingPort } from './embedding-port.js';
+import { VectorIndexPort } from './vector-index-port.js';
+import { StoragePort } from './storage.js';
+import { DeltaStoragePort } from './delta-storage.js';
+import './errors.js';
+import './navigator.js';
+
+/** Everything `createArbor`/`restoreArbor` need. All optional — sensible defaults. */
+interface ArborOpts {
+    /** Initial JSON for a fresh artifact (default {}). Ignored by restoreArbor. */
+    initial?: Json;
+    /** Node types: per-type validation, decompose override, embedText. */
+    registry?: TypeRegistry;
+    /** Base decompose policy (default sizeBasedDecision(200)); made type-aware when a registry is given. */
+    decompose?: DecomposeDecision;
+    idGen?: IdGen;
+    clock?: Clock;
+    /** Enables the semantic index (vectors default to MemoryVectorIndex). */
+    embedding?: EmbeddingPort;
+    vectors?: VectorIndexPort;
+    /** Whole-artifact persistence: enables save(); restoreArbor falls back to it. */
+    storage?: StoragePort;
+    /** Incremental persistence: enables saveDelta()/checkpoint(); restoreArbor prefers it. */
+    delta?: DeltaStoragePort;
+}
+/** A fully wired artifact: the live components plus lifecycle helpers. */
+interface Arbor {
+    readonly tree: ArtifactTree;
+    readonly addressing: Addressing;
+    readonly log: EventLog;
+    readonly mutator: Mutator;
+    readonly replay: Replay;
+    /** Present iff `embedding` was configured. */
+    readonly index?: SemanticIndex;
+    readonly vectors: VectorIndexPort;
+    /** A scoped agent-facing toolset over this artifact. */
+    toolset(binding?: ToolsetBinding): Toolset;
+    /** Whole-artifact snapshot to `storage`. */
+    save(): Promise<void>;
+    /** Append events since the last saveDelta/checkpoint to the delta journal. */
+    saveDelta(): Promise<void>;
+    /** Full snapshot to delta storage (clears the journal). `keepLast` first compacts
+     *  the log to a sliding window of that many events. */
+    checkpoint(opts?: {
+        keepLast?: number;
+    }): Promise<void>;
+}
+/** Build a fresh, fully wired artifact from `opts.initial` (default {}). */
+declare function createArbor(opts?: ArborOpts): Arbor;
+/**
+ * Restore a fully wired artifact from persistence: prefers `delta` (checkpoint +
+ * forward-replayed journal), falls back to `storage`, returns null when neither has
+ * data. Owns the restore invariants: a fresh (or caller-provided) vector index is
+ * upserted from the snapshot, the SemanticIndex is re-created (it re-seeds its stale
+ * queue from node meta), and the idGen is guarded against collisions with restored
+ * node ids. Use the SAME `decompose`/`registry` as the original run — journal-touched
+ * nodes are re-decomposed on delta restore.
+ */
+declare function restoreArbor(opts: ArborOpts): Promise<Arbor | null>;
+
+export { type Arbor, type ArborOpts, createArbor, restoreArbor };