arborkit 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.1.0 — 2026-07-05
+
+- **New patch op: `edit`** — exact-substring surgery on string-valued nodes:
+  `patch(ref, { op: "edit", old, new, replaceAll?, ifVersion? })`. `old` must occur
+  exactly once in the node's string value (or set `replaceAll`); on a miss or an
+  ambiguous match the op fails with a structured `INVALID_OP` that reports the
+  occurrence count, so an agent can re-quote a larger fragment and retry.
+  Replacement is literal (no `$&`-style pattern expansion). Scope and `ifVersion`
+  are enforced *before* any content inspection — out-of-scope probes get an
+  identical `SCOPE_VIOLATION` whether or not `old` matches, leaking nothing.
+- Under the hood `edit` is pure sugar over `set`: the event log records an ordinary
+  `set` with full before/after, so replay, revert, delta persistence, and the AG-UI
+  adapter need no changes.
+- Motivation: output tokens are ~5× input price on current Claude models. An agent
+  quoting `old`/`new` fragments (~100 output tokens) instead of regenerating a whole
+  block (~1500) is the dominant cost lever for agent-driven editing. Pattern: `get`
+  the node first, quote `old` from the live value — the Claude Code `Edit`-tool
+  semantics.
+
+## 1.0.1 — 2026-07-03
+
+- **Fix: cross-entry `instanceof` breakage.** 1.0.0 was built without code splitting, so every
+  subpath entry (`arborkit/errors`, `arborkit/toolset`, …) bundled its own copies of shared
+  classes — mixing root and subpath imports broke `instanceof` (e.g. the toolset degraded
+  `SCOPE_VIOLATION` results to generic `ERROR` against a `Mutator` imported from another entry).
+  Splitting is now enabled; shared chunks give one class identity across all entries.
+- Chunk files stay private: the `"./*"` wildcard export is replaced by an explicit per-module
+  exports map, so hash-named chunks are not importable. All documented entry points are unchanged.
+
 ## 1.0.0 — 2026-07-03
 
 First public release of Arbor as `arborkit`. The milestone arc:

package/README.md

@@ -44,6 +44,14 @@ const home = await tools.get({ path: "/pages/home" }); // home.value.content ===
 const refused = await tools.patch({ path: "/plan" }, { op: "set", value: "hacked" });
 // refused.ok === false — out of scope; violations are returned, never thrown
 
+// Agent edits — surgical substring replacement instead of regenerating a block:
+// get the node first, quote `old` from the live value (Claude Code Edit semantics).
+await tools.patch({ path: "/pages/home" }, { op: "set", value: { title: "Home", html: "<p>Bonus: 100% do 2000 PLN</p>" } });
+const edited = await tools.patch(
+  { path: "/pages/home/html" },
+  { op: "edit", old: "100% do 2000 PLN", new: "150% do 3000 PLN" },
+); // unique-or-fail: an ambiguous `old` returns INVALID_OP with the occurrence count
+
 // Semantic search — mutations only mark nodes stale; reindex() embeds:
 await arbor.index!.reindex();
 const found = await arbor.index!.search("home page"); // { results, staleCount }

package/dist/addressing.js

@@ -1,55 +1,7 @@
-// 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;
-  }
-};
+import {
+  Addressing
+} from "./chunk-M72UOSPG.js";
+import "./chunk-VG5BEOBI.js";
 export {
   Addressing
 };

package/dist/addressing.js.map

@@ -1 +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":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ag-ui.js

@@ -1,47 +1,9 @@
-// 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() };
-}
+import {
+  deltaSince,
+  snapshotEvent,
+  toJsonPatch
+} from "./chunk-BYXJ5B5F.js";
+import "./chunk-V3HDDWER.js";
 export {
   deltaSince,
   snapshotEvent,

package/dist/ag-ui.js.map

@@ -1 +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":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}