arborkit 1.0.0

package/dist/storage.d.ts

@@ -0,0 +1,39 @@
+import { NodeId, ArbNode } from './types.js';
+import { TreeDeps, ArtifactTree } from './artifact-tree.js';
+import { MutationEvent, EventLog } from './event-log.js';
+import { VectorIndexEntry, VectorIndexPort } from './vector-index-port.js';
+import './ids.js';
+import './clock.js';
+import './decompose.js';
+
+/** A JSON-serializable snapshot of an entire artifact: tree + event-log + vectors.
+ *  v2 adds `baseSeq` (the event-log compaction floor); v1 files restore with floor 0. */
+interface StoredArtifact {
+    version: 1 | 2;
+    rootId: NodeId;
+    nodes: ArbNode[];
+    events: MutationEvent[];
+    /** Absolute seq of the oldest retained event (compaction floor). Absent in v1 → 0. */
+    baseSeq?: number;
+    vectors: VectorIndexEntry[];
+}
+/** Persists/loads a StoredArtifact. Adapters: MemoryStorage, FileStorage (and DB-backed later). */
+interface StoragePort {
+    save(artifact: StoredArtifact): Promise<void>;
+    load(): Promise<StoredArtifact | null>;
+}
+/** Dump the live components into a StoredArtifact (v2). */
+declare function serializeArtifact(tree: ArtifactTree, log: EventLog, vectors: VectorIndexPort): Promise<StoredArtifact>;
+/** Rebuild a fresh tree + log from a StoredArtifact, and upsert its vectors into `vectors`. */
+declare function restoreArtifact(stored: StoredArtifact, deps: TreeDeps, vectors: VectorIndexPort): Promise<{
+    tree: ArtifactTree;
+    log: EventLog;
+}>;
+/** In-memory StoragePort: holds a deep-cloned bundle. */
+declare class MemoryStorage implements StoragePort {
+    private stored;
+    save(artifact: StoredArtifact): Promise<void>;
+    load(): Promise<StoredArtifact | null>;
+}
+
+export { MemoryStorage, type StoragePort, type StoredArtifact, restoreArtifact, serializeArtifact };

package/dist/storage.js

@@ -0,0 +1,378 @@
+// src/decompose.ts
+function kindOf(value, opaque) {
+  if (opaque) return "leaf";
+  return Array.isArray(value) ? "array" : "object";
+}
+
+// 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/artifact-tree.ts
+var ArtifactTree = class _ArtifactTree {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  deps;
+  nodes = /* @__PURE__ */ new Map();
+  rootId;
+  /** Lazily built per-parent key→childId maps for O(1) object-child lookup.
+   *  A cache OUTSIDE the nodes (ArbNode/StoredArtifact stay byte-identical);
+   *  invalidated on every child-set change, rebuilt on read. Arrays never
+   *  populate it (index lookup is already O(1)). */
+  keyMaps = /* @__PURE__ */ new Map();
+  static fromJson(json, deps) {
+    const tree = new _ArtifactTree(deps);
+    tree.rootId = tree.build(json, null, null);
+    return tree;
+  }
+  build(value, parentId, key, type) {
+    const opaque = this.deps.decision.isOpaque(value, type);
+    const kind = kindOf(value, opaque);
+    const id = this.deps.idGen.next();
+    const node = {
+      id,
+      parentId,
+      key,
+      kind,
+      content: kind === "leaf" ? value : null,
+      childIds: [],
+      meta: { version: 0, updatedAt: this.deps.clock.now(), embedding: { state: "none" } }
+    };
+    if (type !== void 0) node.type = type;
+    this.nodes.set(id, node);
+    if (kind === "object") {
+      for (const [k, v] of Object.entries(value)) {
+        node.childIds.push(this.build(v, id, k));
+      }
+    } else if (kind === "array") {
+      value.forEach((v, i) => {
+        node.childIds.push(this.build(v, id, i));
+      });
+    }
+    return id;
+  }
+  get(id) {
+    return this.nodes.get(id);
+  }
+  root() {
+    return this.nodes.get(this.rootId);
+  }
+  rootIdValue() {
+    return this.rootId;
+  }
+  /** O(1) child lookup: arrays by index, objects via a lazily built key map. */
+  childByKey(parentId, key) {
+    const parent = this.nodes.get(parentId);
+    if (!parent) return void 0;
+    if (parent.kind === "array") {
+      if (!/^(0|[1-9]\d*)$/.test(key)) return void 0;
+      const i = Number(key);
+      if (i >= parent.childIds.length) return void 0;
+      return this.nodes.get(parent.childIds[i]);
+    }
+    let map = this.keyMaps.get(parentId);
+    if (!map) {
+      map = /* @__PURE__ */ new Map();
+      for (const cid2 of parent.childIds) map.set(String(this.nodes.get(cid2).key), cid2);
+      this.keyMaps.set(parentId, map);
+    }
+    const cid = map.get(key);
+    return cid === void 0 ? void 0 : this.nodes.get(cid);
+  }
+  children(id) {
+    const n = this.nodes.get(id);
+    if (!n) return [];
+    return n.childIds.map((cid) => this.nodes.get(cid));
+  }
+  has(id) {
+    return this.nodes.has(id);
+  }
+  size() {
+    return this.nodes.size;
+  }
+  /** Reconstruct the JSON value rooted at `id` (defaults to the tree root). */
+  toJson(id = this.rootId) {
+    const n = this.nodes.get(id);
+    if (!n) throw new Error(`Unknown node: ${id}`);
+    if (n.kind === "leaf") return n.content;
+    if (n.kind === "array") return n.childIds.map((cid) => this.toJson(cid));
+    const obj = {};
+    for (const cid of n.childIds) {
+      const c = this.nodes.get(cid);
+      obj[String(c.key)] = this.toJson(cid);
+    }
+    return obj;
+  }
+  /** Replace the subtree value at `id` in place, keeping the node's id/key/parentId.
+   *  `clearType` explicitly un-types the node (used by type-aware revert). */
+  replaceValue(id, value, type, clearType = false) {
+    const node = this.nodes.get(id);
+    if (!node) throw new InvalidOpError(`Unknown node: ${id}`);
+    this.deleteDescendants(id);
+    this.keyMaps.delete(id);
+    const opaque = this.deps.decision.isOpaque(value, type);
+    const kind = kindOf(value, opaque);
+    node.kind = kind;
+    node.content = kind === "leaf" ? value : null;
+    node.childIds = [];
+    if (clearType) node.type = void 0;
+    else if (type !== void 0) node.type = type;
+    if (kind === "object") {
+      for (const [k, v] of Object.entries(value)) {
+        node.childIds.push(this.build(v, id, k));
+      }
+    } else if (kind === "array") {
+      value.forEach((v, i) => {
+        node.childIds.push(this.build(v, id, i));
+      });
+    }
+  }
+  /** Recursively remove all descendants of `id` from the node map (keeps `id` itself). */
+  deleteDescendants(id) {
+    const node = this.nodes.get(id);
+    if (!node) return;
+    for (const cid of node.childIds) {
+      this.deleteDescendants(cid);
+      this.nodes.delete(cid);
+      this.keyMaps.delete(cid);
+    }
+    node.childIds = [];
+  }
+  /** Deep, independent copy of the tree state for transaction rollback.
+   *  `restore` consumes the snapshot; do not reuse it afterwards. */
+  snapshot() {
+    const nodes = /* @__PURE__ */ new Map();
+    for (const [id, node] of this.nodes) {
+      nodes.set(id, structuredClone(node));
+    }
+    return { nodes, rootId: this.rootId };
+  }
+  /** Replace the tree state with a previously taken snapshot. The snapshot's
+   *  nodes are adopted BY REFERENCE — restore consumes the snapshot; do not
+   *  reuse it afterwards. */
+  restore(snap) {
+    this.nodes.clear();
+    this.keyMaps.clear();
+    for (const [id, node] of snap.nodes) {
+      this.nodes.set(id, node);
+    }
+    this.rootId = snap.rootId;
+  }
+  /** Insert a decomposed `value` as a child of `parentId`. For objects `keyOrIndex` is the string key; for arrays it is the insert index. Returns the new child's id. */
+  insertChild(parentId, keyOrIndex, value, type) {
+    const parent = this.nodes.get(parentId);
+    if (!parent) throw new InvalidOpError(`Unknown node: ${parentId}`);
+    if (parent.kind === "object") {
+      if (typeof keyOrIndex !== "string") {
+        throw new InvalidOpError("object insert requires a string key");
+      }
+      if (parent.childIds.some((cid2) => this.nodes.get(cid2).key === keyOrIndex)) {
+        throw new InvalidOpError(`key already exists: ${keyOrIndex}`);
+      }
+      const cid = this.build(value, parentId, keyOrIndex, type);
+      parent.childIds.push(cid);
+      this.keyMaps.delete(parentId);
+      return cid;
+    }
+    if (parent.kind === "array") {
+      if (typeof keyOrIndex !== "number") {
+        throw new InvalidOpError("array insert requires a numeric index");
+      }
+      const at = Math.max(0, Math.min(keyOrIndex, parent.childIds.length));
+      const cid = this.build(value, parentId, at, type);
+      parent.childIds.splice(at, 0, cid);
+      this.renumberArray(parentId);
+      return cid;
+    }
+    throw new InvalidOpError("cannot insert into a leaf node");
+  }
+  /** Remove `childId` (and its subtree) from `parentId`. Renumbers array siblings. */
+  removeChild(parentId, childId) {
+    const parent = this.nodes.get(parentId);
+    if (!parent) throw new InvalidOpError(`Unknown node: ${parentId}`);
+    const idx = parent.childIds.indexOf(childId);
+    if (idx < 0) throw new InvalidOpError(`${childId} is not a child of ${parentId}`);
+    this.deleteDescendants(childId);
+    this.nodes.delete(childId);
+    this.keyMaps.delete(childId);
+    parent.childIds.splice(idx, 1);
+    this.keyMaps.delete(parentId);
+    if (parent.kind === "array") this.renumberArray(parentId);
+  }
+  /** Move `id` under `newParentId` at `keyOrIndex`, preserving `id`. Renumbers affected arrays.
+   *  ALL validation happens before any mutation — a rejected move leaves the tree untouched. */
+  moveNode(id, newParentId, keyOrIndex) {
+    const node = this.nodes.get(id);
+    if (!node) throw new InvalidOpError(`Unknown node: ${id}`);
+    if (node.parentId === null) throw new InvalidOpError("cannot move the root");
+    const newParent = this.nodes.get(newParentId);
+    if (!newParent) throw new InvalidOpError(`Unknown node: ${newParentId}`);
+    if (newParent.kind === "leaf") throw new InvalidOpError("cannot move into a leaf node");
+    let anc = newParentId;
+    while (anc !== null) {
+      if (anc === id) throw new InvalidOpError("cannot move a node into itself or its own subtree");
+      anc = this.nodes.get(anc)?.parentId ?? null;
+    }
+    if (newParent.kind === "object") {
+      if (typeof keyOrIndex !== "string") throw new InvalidOpError("object move requires a string key");
+      if (newParent.childIds.some((cid) => cid !== id && this.nodes.get(cid).key === keyOrIndex)) {
+        throw new InvalidOpError(`key already exists: ${keyOrIndex}`);
+      }
+    }
+    const oldParent = this.nodes.get(node.parentId);
+    const oldIdx = oldParent.childIds.indexOf(id);
+    oldParent.childIds.splice(oldIdx, 1);
+    this.keyMaps.delete(oldParent.id);
+    this.keyMaps.delete(newParentId);
+    if (oldParent.kind === "array") this.renumberArray(oldParent.id);
+    if (newParent.kind === "object") {
+      node.parentId = newParentId;
+      node.key = keyOrIndex;
+      newParent.childIds.push(id);
+    } else {
+      const at = typeof keyOrIndex === "number" ? Math.max(0, Math.min(keyOrIndex, newParent.childIds.length)) : newParent.childIds.length;
+      node.parentId = newParentId;
+      newParent.childIds.splice(at, 0, id);
+      this.renumberArray(newParentId);
+    }
+  }
+  /** Set each array child's `key` to its current position. */
+  renumberArray(parentId) {
+    const parent = this.nodes.get(parentId);
+    if (!parent) return;
+    parent.childIds.forEach((cid, i) => {
+      this.nodes.get(cid).key = i;
+    });
+  }
+  /** All nodes in the tree (for serialization). */
+  allNodes() {
+    return [...this.nodes.values()];
+  }
+  /** Rebuild a tree from previously serialized nodes, preserving their ids. */
+  static fromStored(nodes, rootId, deps) {
+    const tree = new _ArtifactTree(deps);
+    for (const node of nodes) tree.nodes.set(node.id, node);
+    tree.rootId = rootId;
+    return tree;
+  }
+  /** All transitive descendant ids of `id` (depth-first), excluding `id` itself. */
+  descendantIds(id) {
+    const out = [];
+    const node = this.nodes.get(id);
+    if (!node) return out;
+    for (const cid of node.childIds) {
+      out.push(cid);
+      out.push(...this.descendantIds(cid));
+    }
+    return out;
+  }
+};
+
+// src/event-log.ts
+var EventLog = class _EventLog {
+  events = [];
+  baseSeq = 0;
+  // count of compacted-away events; events[0].seq === baseSeq
+  append(event) {
+    const full = { ...event, seq: this.baseSeq + this.events.length };
+    this.events.push(full);
+    return full;
+  }
+  entries() {
+    return this.events;
+  }
+  /** Absolute seq of the oldest retained event (0 until compaction). Versions below
+   *  this have been compacted away and are no longer reconstructable. */
+  baseSeqValue() {
+    return this.baseSeq;
+  }
+  /** The event at absolute `seq`, or undefined if compacted away / past the end. */
+  at(seq) {
+    const i = seq - this.baseSeq;
+    return i >= 0 && i < this.events.length ? this.events[i] : void 0;
+  }
+  since(seq) {
+    return this.events.filter((e) => e.seq >= seq);
+  }
+  /** Absolute next-seq / current version (unchanged across compaction). */
+  length() {
+    return this.baseSeq + this.events.length;
+  }
+  /** Drop events past absolute `length` — used to roll back a failed transaction.
+   *  Throws below the compaction floor: that history is gone and the log cannot roll
+   *  back past it — `compactTo` must never run inside a transaction. */
+  truncateTo(length) {
+    if (length < this.baseSeq) {
+      throw new InvalidOpError(
+        `cannot truncate to ${length}: events before ${this.baseSeq} were compacted away (compactTo must not run inside a transaction)`
+      );
+    }
+    this.events.length = length - this.baseSeq;
+  }
+  /** Compaction: drop every retained event with seq < `floorSeq` (history before it
+   *  becomes unreconstructable). `floorSeq` is clamped to [baseSeq, length()].
+   *  Returns the number of events dropped. Must NOT be called inside a Mutator
+   *  transaction (rollback would need the dropped events). */
+  compactTo(floorSeq) {
+    const floor = Math.max(this.baseSeq, Math.min(floorSeq, this.length()));
+    const drop = floor - this.baseSeq;
+    if (drop > 0) {
+      this.events.splice(0, drop);
+      this.baseSeq = floor;
+    }
+    return drop;
+  }
+  /** Rebuild a log from previously serialized events, preserving their seq + the
+   *  compaction floor. */
+  static fromStored(events, baseSeq = 0) {
+    const log = new _EventLog();
+    log.baseSeq = baseSeq;
+    for (const e of events) log.events.push({ ...e });
+    return log;
+  }
+};
+
+// src/storage.ts
+async function serializeArtifact(tree, log, vectors) {
+  return {
+    version: 2,
+    rootId: tree.rootIdValue(),
+    nodes: tree.allNodes(),
+    events: [...log.entries()],
+    baseSeq: log.baseSeqValue(),
+    vectors: await vectors.entries()
+  };
+}
+async function restoreArtifact(stored, deps, vectors) {
+  const tree = ArtifactTree.fromStored(stored.nodes, stored.rootId, deps);
+  const log = EventLog.fromStored(stored.events, stored.baseSeq ?? 0);
+  await vectors.upsert(stored.vectors);
+  return { tree, log };
+}
+var MemoryStorage = class {
+  stored = null;
+  async save(artifact) {
+    this.stored = structuredClone(artifact);
+  }
+  async load() {
+    return this.stored ? structuredClone(this.stored) : null;
+  }
+};
+export {
+  MemoryStorage,
+  restoreArtifact,
+  serializeArtifact
+};
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/decompose.ts","../src/errors.ts","../src/artifact-tree.ts","../src/event-log.ts","../src/storage.ts"],"sourcesContent":["import type { Json, NodeKind } from \"./types\";\r\n\r\n/** Policy deciding whether a value is stored whole (opaque leaf) or split into child nodes. */\r\nexport interface DecomposeDecision {\r\n  /** `type` is the optional registered node type (used by the by-type override in a later milestone). */\r\n  isOpaque(value: Json, type?: string): boolean;\r\n}\r\n\r\n/** UTF-8 byte length of the JSON serialization of a value. */\r\nexport function byteSize(value: Json): number {\r\n  return Buffer.byteLength(JSON.stringify(value), \"utf8\");\r\n}\r\n\r\n/** Structural kind of a value given whether it is being stored opaquely. */\r\nexport function kindOf(value: Json, opaque: boolean): NodeKind {\r\n  if (opaque) return \"leaf\";\r\n  return Array.isArray(value) ? \"array\" : \"object\";\r\n}\r\n\r\n/**\r\n * Default policy: scalars are always opaque leaves; containers stay opaque\r\n * while their serialized size is within `maxOpaqueBytes`, otherwise they split.\r\n */\r\nexport function sizeBasedDecision(maxOpaqueBytes: number): DecomposeDecision {\r\n  return {\r\n    isOpaque(value: Json): boolean {\r\n      if (value === null || typeof value !== \"object\") return true;\r\n      return byteSize(value) <= maxOpaqueBytes;\r\n    },\r\n  };\r\n}\r\n","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","import type { ArbNode, Json, NodeId } from \"./types\";\r\nimport type { IdGen } from \"./ids\";\r\nimport type { Clock } from \"./clock\";\r\nimport { type DecomposeDecision, kindOf } from \"./decompose\";\r\nimport { InvalidOpError } from \"./errors\";\r\n\r\nexport interface TreeDeps {\r\n  idGen: IdGen;\r\n  clock: Clock;\r\n  decision: DecomposeDecision;\r\n}\r\n\r\nexport interface TreeSnapshot {\r\n  nodes: Map<NodeId, ArbNode>;\r\n  rootId: NodeId;\r\n}\r\n\r\nexport class ArtifactTree {\r\n  private readonly nodes = new Map<NodeId, ArbNode>();\r\n  private rootId!: NodeId;\r\n  /** Lazily built per-parent key→childId maps for O(1) object-child lookup.\r\n   *  A cache OUTSIDE the nodes (ArbNode/StoredArtifact stay byte-identical);\r\n   *  invalidated on every child-set change, rebuilt on read. Arrays never\r\n   *  populate it (index lookup is already O(1)). */\r\n  private readonly keyMaps = new Map<NodeId, Map<string, NodeId>>();\r\n\r\n  private constructor(private readonly deps: TreeDeps) {}\r\n\r\n  static fromJson(json: Json, deps: TreeDeps): ArtifactTree {\r\n    const tree = new ArtifactTree(deps);\r\n    tree.rootId = tree.build(json, null, null);\r\n    return tree;\r\n  }\r\n\r\n  private build(value: Json, parentId: NodeId | null, key: string | number | null, type?: string): NodeId {\r\n    const opaque = this.deps.decision.isOpaque(value, type);\r\n    const kind = kindOf(value, opaque);\r\n    const id = this.deps.idGen.next();\r\n    const node: ArbNode = {\r\n      id,\r\n      parentId,\r\n      key,\r\n      kind,\r\n      content: kind === \"leaf\" ? value : null,\r\n      childIds: [],\r\n      meta: { version: 0, updatedAt: this.deps.clock.now(), embedding: { state: \"none\" } },\r\n    };\r\n    if (type !== undefined) node.type = type;\r\n    this.nodes.set(id, node);\r\n\r\n    if (kind === \"object\") {\r\n      for (const [k, v] of Object.entries(value as Record<string, Json>)) {\r\n        node.childIds.push(this.build(v, id, k));\r\n      }\r\n    } else if (kind === \"array\") {\r\n      (value as Json[]).forEach((v, i) => {\r\n        node.childIds.push(this.build(v, id, i));\r\n      });\r\n    }\r\n    return id;\r\n  }\r\n\r\n  get(id: NodeId): ArbNode | undefined {\r\n    return this.nodes.get(id);\r\n  }\r\n\r\n  root(): ArbNode {\r\n    return this.nodes.get(this.rootId)!;\r\n  }\r\n\r\n  rootIdValue(): NodeId {\r\n    return this.rootId;\r\n  }\r\n\r\n  /** O(1) child lookup: arrays by index, objects via a lazily built key map. */\r\n  childByKey(parentId: NodeId, key: string): ArbNode | undefined {\r\n    const parent = this.nodes.get(parentId);\r\n    if (!parent) return undefined;\r\n    if (parent.kind === \"array\") {\r\n      if (!/^(0|[1-9]\\d*)$/.test(key)) return undefined; // canonical RFC 6901 index: digits only, no leading zeros\r\n      const i = Number(key);\r\n      if (i >= parent.childIds.length) return undefined;\r\n      return this.nodes.get(parent.childIds[i]);\r\n    }\r\n    let map = this.keyMaps.get(parentId);\r\n    if (!map) {\r\n      map = new Map();\r\n      for (const cid of parent.childIds) map.set(String(this.nodes.get(cid)!.key), cid);\r\n      this.keyMaps.set(parentId, map);\r\n    }\r\n    const cid = map.get(key);\r\n    return cid === undefined ? undefined : this.nodes.get(cid);\r\n  }\r\n\r\n  children(id: NodeId): ArbNode[] {\r\n    const n = this.nodes.get(id);\r\n    if (!n) return [];\r\n    return n.childIds.map((cid) => this.nodes.get(cid)!);\r\n  }\r\n\r\n  has(id: NodeId): boolean {\r\n    return this.nodes.has(id);\r\n  }\r\n\r\n  size(): number {\r\n    return this.nodes.size;\r\n  }\r\n\r\n  /** Reconstruct the JSON value rooted at `id` (defaults to the tree root). */\r\n  toJson(id: NodeId = this.rootId): Json {\r\n    const n = this.nodes.get(id);\r\n    if (!n) throw new Error(`Unknown node: ${id}`);\r\n    if (n.kind === \"leaf\") return n.content;\r\n    if (n.kind === \"array\") return n.childIds.map((cid) => this.toJson(cid));\r\n    const obj: Record<string, Json> = {};\r\n    for (const cid of n.childIds) {\r\n      const c = this.nodes.get(cid)!;\r\n      obj[String(c.key)] = this.toJson(cid);\r\n    }\r\n    return obj;\r\n  }\r\n\r\n  /** Replace the subtree value at `id` in place, keeping the node's id/key/parentId.\r\n   *  `clearType` explicitly un-types the node (used by type-aware revert). */\r\n  replaceValue(id: NodeId, value: Json, type?: string, clearType = false): void {\r\n    const node = this.nodes.get(id);\r\n    if (!node) throw new InvalidOpError(`Unknown node: ${id}`);\r\n    this.deleteDescendants(id);\r\n    this.keyMaps.delete(id);\r\n    const opaque = this.deps.decision.isOpaque(value, type);\r\n    const kind = kindOf(value, opaque);\r\n    node.kind = kind;\r\n    node.content = kind === \"leaf\" ? value : null;\r\n    node.childIds = [];\r\n    if (clearType) node.type = undefined;\r\n    else if (type !== undefined) node.type = type;\r\n    if (kind === \"object\") {\r\n      for (const [k, v] of Object.entries(value as Record<string, Json>)) {\r\n        node.childIds.push(this.build(v, id, k));\r\n      }\r\n    } else if (kind === \"array\") {\r\n      (value as Json[]).forEach((v, i) => {\r\n        node.childIds.push(this.build(v, id, i));\r\n      });\r\n    }\r\n  }\r\n\r\n  /** Recursively remove all descendants of `id` from the node map (keeps `id` itself). */\r\n  private deleteDescendants(id: NodeId): void {\r\n    const node = this.nodes.get(id);\r\n    if (!node) return;\r\n    for (const cid of node.childIds) {\r\n      this.deleteDescendants(cid);\r\n      this.nodes.delete(cid);\r\n      this.keyMaps.delete(cid);\r\n    }\r\n    node.childIds = [];\r\n  }\r\n\r\n  /** Deep, independent copy of the tree state for transaction rollback.\r\n   *  `restore` consumes the snapshot; do not reuse it afterwards. */\r\n  snapshot(): TreeSnapshot {\r\n    const nodes = new Map<NodeId, ArbNode>();\r\n    for (const [id, node] of this.nodes) {\r\n      nodes.set(id, structuredClone(node));\r\n    }\r\n    return { nodes, rootId: this.rootId };\r\n  }\r\n\r\n  /** Replace the tree state with a previously taken snapshot. The snapshot's\r\n   *  nodes are adopted BY REFERENCE — restore consumes the snapshot; do not\r\n   *  reuse it afterwards. */\r\n  restore(snap: TreeSnapshot): void {\r\n    this.nodes.clear();\r\n    this.keyMaps.clear();\r\n    for (const [id, node] of snap.nodes) {\r\n      this.nodes.set(id, node);\r\n    }\r\n    this.rootId = snap.rootId;\r\n  }\r\n\r\n  /** Insert a decomposed `value` as a child of `parentId`. For objects `keyOrIndex` is the string key; for arrays it is the insert index. Returns the new child's id. */\r\n  insertChild(parentId: NodeId, keyOrIndex: string | number, value: Json, type?: string): NodeId {\r\n    const parent = this.nodes.get(parentId);\r\n    if (!parent) throw new InvalidOpError(`Unknown node: ${parentId}`);\r\n    if (parent.kind === \"object\") {\r\n      if (typeof keyOrIndex !== \"string\") {\r\n        throw new InvalidOpError(\"object insert requires a string key\");\r\n      }\r\n      if (parent.childIds.some((cid) => this.nodes.get(cid)!.key === keyOrIndex)) {\r\n        throw new InvalidOpError(`key already exists: ${keyOrIndex}`);\r\n      }\r\n      const cid = this.build(value, parentId, keyOrIndex, type);\r\n      parent.childIds.push(cid);\r\n      this.keyMaps.delete(parentId);\r\n      return cid;\r\n    }\r\n    if (parent.kind === \"array\") {\r\n      if (typeof keyOrIndex !== \"number\") {\r\n        throw new InvalidOpError(\"array insert requires a numeric index\");\r\n      }\r\n      const at = Math.max(0, Math.min(keyOrIndex, parent.childIds.length));\r\n      const cid = this.build(value, parentId, at, type);\r\n      parent.childIds.splice(at, 0, cid);\r\n      this.renumberArray(parentId);\r\n      return cid;\r\n    }\r\n    throw new InvalidOpError(\"cannot insert into a leaf node\");\r\n  }\r\n\r\n  /** Remove `childId` (and its subtree) from `parentId`. Renumbers array siblings. */\r\n  removeChild(parentId: NodeId, childId: NodeId): void {\r\n    const parent = this.nodes.get(parentId);\r\n    if (!parent) throw new InvalidOpError(`Unknown node: ${parentId}`);\r\n    const idx = parent.childIds.indexOf(childId);\r\n    if (idx < 0) throw new InvalidOpError(`${childId} is not a child of ${parentId}`);\r\n    this.deleteDescendants(childId);\r\n    this.nodes.delete(childId);\r\n    this.keyMaps.delete(childId);\r\n    parent.childIds.splice(idx, 1);\r\n    this.keyMaps.delete(parentId);\r\n    if (parent.kind === \"array\") this.renumberArray(parentId);\r\n  }\r\n\r\n  /** Move `id` under `newParentId` at `keyOrIndex`, preserving `id`. Renumbers affected arrays.\r\n   *  ALL validation happens before any mutation — a rejected move leaves the tree untouched. */\r\n  moveNode(id: NodeId, newParentId: NodeId, keyOrIndex: string | number): void {\r\n    const node = this.nodes.get(id);\r\n    if (!node) throw new InvalidOpError(`Unknown node: ${id}`);\r\n    if (node.parentId === null) throw new InvalidOpError(\"cannot move the root\");\r\n    const newParent = this.nodes.get(newParentId);\r\n    if (!newParent) throw new InvalidOpError(`Unknown node: ${newParentId}`);\r\n    if (newParent.kind === \"leaf\") throw new InvalidOpError(\"cannot move into a leaf node\");\r\n    // Moving into itself or its own subtree would create a parent-chain cycle:\r\n    // toJson silently drops the subtree and pathOf never terminates.\r\n    let anc: NodeId | null = newParentId;\r\n    while (anc !== null) {\r\n      if (anc === id) throw new InvalidOpError(\"cannot move a node into itself or its own subtree\");\r\n      anc = this.nodes.get(anc)?.parentId ?? null;\r\n    }\r\n    if (newParent.kind === \"object\") {\r\n      if (typeof keyOrIndex !== \"string\") throw new InvalidOpError(\"object move requires a string key\");\r\n      // Mirrors insertChild: a duplicate key silently shadows the existing child.\r\n      if (newParent.childIds.some((cid) => cid !== id && this.nodes.get(cid)!.key === keyOrIndex)) {\r\n        throw new InvalidOpError(`key already exists: ${keyOrIndex}`);\r\n      }\r\n    }\r\n\r\n    const oldParent = this.nodes.get(node.parentId)!;\r\n    const oldIdx = oldParent.childIds.indexOf(id);\r\n    oldParent.childIds.splice(oldIdx, 1);\r\n    this.keyMaps.delete(oldParent.id);\r\n    this.keyMaps.delete(newParentId);\r\n    if (oldParent.kind === \"array\") this.renumberArray(oldParent.id);\r\n\r\n    if (newParent.kind === \"object\") {\r\n      node.parentId = newParentId;\r\n      node.key = keyOrIndex;\r\n      newParent.childIds.push(id);\r\n    } else {\r\n      const at = typeof keyOrIndex === \"number\" ? Math.max(0, Math.min(keyOrIndex, newParent.childIds.length)) : newParent.childIds.length;\r\n      node.parentId = newParentId;\r\n      newParent.childIds.splice(at, 0, id);\r\n      this.renumberArray(newParentId);\r\n    }\r\n  }\r\n\r\n  /** Set each array child's `key` to its current position. */\r\n  private renumberArray(parentId: NodeId): void {\r\n    const parent = this.nodes.get(parentId);\r\n    if (!parent) return;\r\n    parent.childIds.forEach((cid, i) => {\r\n      this.nodes.get(cid)!.key = i;\r\n    });\r\n  }\r\n\r\n  /** All nodes in the tree (for serialization). */\r\n  allNodes(): ArbNode[] {\r\n    return [...this.nodes.values()];\r\n  }\r\n\r\n  /** Rebuild a tree from previously serialized nodes, preserving their ids. */\r\n  static fromStored(nodes: ArbNode[], rootId: NodeId, deps: TreeDeps): ArtifactTree {\r\n    const tree = new ArtifactTree(deps);\r\n    for (const node of nodes) tree.nodes.set(node.id, node);\r\n    tree.rootId = rootId;\r\n    return tree;\r\n  }\r\n\r\n  /** All transitive descendant ids of `id` (depth-first), excluding `id` itself. */\r\n  descendantIds(id: NodeId): NodeId[] {\r\n    const out: NodeId[] = [];\r\n    const node = this.nodes.get(id);\r\n    if (!node) return out;\r\n    for (const cid of node.childIds) {\r\n      out.push(cid);\r\n      out.push(...this.descendantIds(cid));\r\n    }\r\n    return out;\r\n  }\r\n}\r\n","import type { Json, NodeId } from \"./types\";\r\nimport { InvalidOpError } from \"./errors\";\r\n\r\nexport type OpKind = \"set\" | \"insert\" | \"remove\" | \"move\";\r\n\r\n/**\r\n * A recorded mutation. Carries enough to reverse it later (M7 replay):\r\n * - set:    before = old subtree value, after = new value\r\n * - insert: after = inserted value (inverse is remove of targetId)\r\n * - remove: before = removed subtree value (inverse is insert at parentId/key)\r\n * - move:   from/to capture old and new (parentId, key)\r\n */\r\nexport interface MutationEvent {\r\n  seq: number;\r\n  kind: OpKind;\r\n  targetId: NodeId;\r\n  parentId: NodeId | null;\r\n  key: string | number | null;\r\n  before?: Json;\r\n  after?: Json;\r\n  from?: { parentId: NodeId | null; key: string | number | null };\r\n  to?: { parentId: NodeId | null; key: string | number | null };\r\n  /** JSON Pointer of the affected node (set/insert: its path; remove: its pre-removal path). */\r\n  path?: string;\r\n  /** move: source path (before the move). */\r\n  fromPath?: string;\r\n  /** move: destination path (after the move). */\r\n  toPath?: string;\r\n  /** set/remove: the node's type BEFORE the op; insert/set: `nodeType` = type AFTER.\r\n   *  `null` = explicitly untyped; ABSENT = pre-M10 event (unknown — replay keeps the current type). */\r\n  nodeTypeBefore?: string | null;\r\n  nodeType?: string | null;\r\n  /** set/remove: the node's tags BEFORE the op ([] = untagged).\r\n   *  ABSENT = pre-M14 event (unknown — revert leaves the current tags alone). */\r\n  tagsBefore?: string[];\r\n  /** set/insert: the node's tags AFTER the op ([] = untagged). ABSENT = pre-M14. */\r\n  tags?: string[];\r\n  actor?: string;\r\n  ts: number;\r\n}\r\n\r\n/** Append-only log of mutations with monotonic, absolute seq. Supports compaction:\r\n *  events before `baseSeq` are dropped, but retained events keep their absolute seq\r\n *  and `length()` stays the absolute next-seq, so versions never shift. */\r\nexport class EventLog {\r\n  private readonly events: MutationEvent[] = [];\r\n  private baseSeq = 0; // count of compacted-away events; events[0].seq === baseSeq\r\n\r\n  append(event: Omit<MutationEvent, \"seq\">): MutationEvent {\r\n    const full: MutationEvent = { ...event, seq: this.baseSeq + this.events.length };\r\n    this.events.push(full);\r\n    return full;\r\n  }\r\n\r\n  entries(): readonly MutationEvent[] {\r\n    return this.events;\r\n  }\r\n\r\n  /** Absolute seq of the oldest retained event (0 until compaction). Versions below\r\n   *  this have been compacted away and are no longer reconstructable. */\r\n  baseSeqValue(): number {\r\n    return this.baseSeq;\r\n  }\r\n\r\n  /** The event at absolute `seq`, or undefined if compacted away / past the end. */\r\n  at(seq: number): MutationEvent | undefined {\r\n    const i = seq - this.baseSeq;\r\n    return i >= 0 && i < this.events.length ? this.events[i] : undefined;\r\n  }\r\n\r\n  since(seq: number): MutationEvent[] {\r\n    return this.events.filter((e) => e.seq >= seq);\r\n  }\r\n\r\n  /** Absolute next-seq / current version (unchanged across compaction). */\r\n  length(): number {\r\n    return this.baseSeq + this.events.length;\r\n  }\r\n\r\n  /** Drop events past absolute `length` — used to roll back a failed transaction.\r\n   *  Throws below the compaction floor: that history is gone and the log cannot roll\r\n   *  back past it — `compactTo` must never run inside a transaction. */\r\n  truncateTo(length: number): void {\r\n    if (length < this.baseSeq) {\r\n      throw new InvalidOpError(\r\n        `cannot truncate to ${length}: events before ${this.baseSeq} were compacted away (compactTo must not run inside a transaction)`,\r\n      );\r\n    }\r\n    this.events.length = length - this.baseSeq;\r\n  }\r\n\r\n  /** Compaction: drop every retained event with seq < `floorSeq` (history before it\r\n   *  becomes unreconstructable). `floorSeq` is clamped to [baseSeq, length()].\r\n   *  Returns the number of events dropped. Must NOT be called inside a Mutator\r\n   *  transaction (rollback would need the dropped events). */\r\n  compactTo(floorSeq: number): number {\r\n    const floor = Math.max(this.baseSeq, Math.min(floorSeq, this.length()));\r\n    const drop = floor - this.baseSeq;\r\n    if (drop > 0) {\r\n      this.events.splice(0, drop);\r\n      this.baseSeq = floor;\r\n    }\r\n    return drop;\r\n  }\r\n\r\n  /** Rebuild a log from previously serialized events, preserving their seq + the\r\n   *  compaction floor. */\r\n  static fromStored(events: MutationEvent[], baseSeq = 0): EventLog {\r\n    const log = new EventLog();\r\n    log.baseSeq = baseSeq;\r\n    for (const e of events) log.events.push({ ...e });\r\n    return log;\r\n  }\r\n}\r\n","import type { ArbNode, NodeId } from \"./types\";\r\nimport { ArtifactTree, type TreeDeps } from \"./artifact-tree\";\r\nimport { EventLog, type MutationEvent } from \"./event-log\";\r\nimport type { VectorIndexPort, VectorIndexEntry } from \"./vector-index-port\";\r\n\r\n/** A JSON-serializable snapshot of an entire artifact: tree + event-log + vectors.\r\n *  v2 adds `baseSeq` (the event-log compaction floor); v1 files restore with floor 0. */\r\nexport interface StoredArtifact {\r\n  version: 1 | 2;\r\n  rootId: NodeId;\r\n  nodes: ArbNode[];\r\n  events: MutationEvent[];\r\n  /** Absolute seq of the oldest retained event (compaction floor). Absent in v1 → 0. */\r\n  baseSeq?: number;\r\n  vectors: VectorIndexEntry[];\r\n}\r\n\r\n/** Persists/loads a StoredArtifact. Adapters: MemoryStorage, FileStorage (and DB-backed later). */\r\nexport interface StoragePort {\r\n  save(artifact: StoredArtifact): Promise<void>;\r\n  load(): Promise<StoredArtifact | null>;\r\n}\r\n\r\n/** Dump the live components into a StoredArtifact (v2). */\r\nexport async function serializeArtifact(\r\n  tree: ArtifactTree,\r\n  log: EventLog,\r\n  vectors: VectorIndexPort,\r\n): Promise<StoredArtifact> {\r\n  return {\r\n    version: 2,\r\n    rootId: tree.rootIdValue(),\r\n    nodes: tree.allNodes(),\r\n    events: [...log.entries()],\r\n    baseSeq: log.baseSeqValue(),\r\n    vectors: await vectors.entries(),\r\n  };\r\n}\r\n\r\n/** Rebuild a fresh tree + log from a StoredArtifact, and upsert its vectors into `vectors`. */\r\nexport async function restoreArtifact(\r\n  stored: StoredArtifact,\r\n  deps: TreeDeps,\r\n  vectors: VectorIndexPort,\r\n): Promise<{ tree: ArtifactTree; log: EventLog }> {\r\n  const tree = ArtifactTree.fromStored(stored.nodes, stored.rootId, deps);\r\n  const log = EventLog.fromStored(stored.events, stored.baseSeq ?? 0);\r\n  await vectors.upsert(stored.vectors);\r\n  return { tree, log };\r\n}\r\n\r\n/** In-memory StoragePort: holds a deep-cloned bundle. */\r\nexport class MemoryStorage implements StoragePort {\r\n  private stored: StoredArtifact | null = null;\r\n\r\n  async save(artifact: StoredArtifact): Promise<void> {\r\n    this.stored = structuredClone(artifact);\r\n  }\r\n\r\n  async load(): Promise<StoredArtifact | null> {\r\n    return this.stored ? structuredClone(this.stored) : null;\r\n  }\r\n}\r\n"],"mappings":"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","names":["cid"]}

package/dist/toolset.d.ts

@@ -0,0 +1,78 @@
+import { ArtifactTree } from './artifact-tree.js';
+import { Addressing } from './addressing.js';
+import { MutationEvent, EventLog } from './event-log.js';
+import { Mutator } from './mutator.js';
+import { SearchOpts, SearchResult, SemanticIndex } from './semantic-index.js';
+import { DescribeOpts, DescribeResult, GetOpts, GetResult, FindSelector, FindOpts, FindResult } from './navigator.js';
+import { Ref } from './errors.js';
+import { Json, NodeId } from './types.js';
+import './ids.js';
+import './clock.js';
+import './decompose.js';
+import './type-registry.js';
+import './embedding-port.js';
+import './vector-index-port.js';
+
+/** Every toolset call returns this — errors are structured, never thrown across the agent boundary. */
+type ToolResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+type PatchOp = {
+    op: "set";
+    value: Json;
+    ifVersion?: number;
+} | {
+    op: "insert";
+    key: string | number;
+    value: Json;
+    ifVersion?: number;
+} | {
+    op: "remove";
+    ifVersion?: number;
+} | {
+    op: "move";
+    to: Ref;
+    key: string | number;
+    ifVersion?: number;
+};
+interface ToolsetDeps {
+    tree: ArtifactTree;
+    addressing: Addressing;
+    log: EventLog;
+    mutator: Mutator;
+    index?: SemanticIndex;
+}
+interface ToolsetBinding {
+    owner?: string;
+    /** JSON Pointer prefix: writes must be at or under it (enforced by the Mutator). */
+    writeScope?: string;
+    /** JSON Pointer prefix: reads are confined to it. */
+    readScope?: string;
+}
+interface PatchResult {
+    id: NodeId;
+    path: string;
+    /** The affected node's version AFTER the op (remove: the parent's). Feed into the next ifVersion. */
+    version: number;
+}
+interface Toolset {
+    describe(ref?: Ref, opts?: DescribeOpts): Promise<ToolResult<DescribeResult>>;
+    get(ref: Ref, opts?: GetOpts): Promise<ToolResult<GetResult>>;
+    find(selector: FindSelector, opts?: FindOpts): Promise<ToolResult<FindResult>>;
+    search(query: string, opts?: SearchOpts): Promise<ToolResult<SearchResult>>;
+    patch(ref: Ref, op: PatchOp): Promise<ToolResult<PatchResult>>;
+    history(ref?: Ref, opts?: {
+        limit?: number;
+    }): Promise<ToolResult<MutationEvent[]>>;
+}
+/** A scoped, agent-facing bundle of tools returning structured results. */
+declare function makeToolset(deps: ToolsetDeps, binding?: ToolsetBinding): Toolset;
+
+export { type PatchOp, type PatchResult, type ToolResult, type Toolset, type ToolsetBinding, type ToolsetDeps, makeToolset };