arborkit 1.0.0

package/dist/mutator.js

@@ -0,0 +1,244 @@
+// src/errors.ts
+var ArborError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+  }
+  code;
+};
+var NodeNotFoundError = class extends ArborError {
+  constructor(ref) {
+    super("NODE_NOT_FOUND", `Node not found: ${JSON.stringify(ref)}`);
+    this.ref = ref;
+  }
+  ref;
+};
+var ScopeViolationError = class extends ArborError {
+  constructor(targetPath, scope) {
+    super("SCOPE_VIOLATION", `Access outside scope: ${targetPath} (scope: ${scope})`);
+    this.targetPath = targetPath;
+    this.scope = scope;
+  }
+  targetPath;
+  scope;
+};
+var StaleVersionError = class extends ArborError {
+  constructor(id, expected, actual) {
+    super("STALE_VERSION", `Stale version for ${id}: expected ${expected}, actual ${actual}`);
+    this.id = id;
+    this.expected = expected;
+    this.actual = actual;
+  }
+  id;
+  expected;
+  actual;
+};
+var InvalidOpError = class extends ArborError {
+  constructor(message) {
+    super("INVALID_OP", message);
+  }
+};
+
+// src/jsonpointer.ts
+function isWithin(path, scope) {
+  return scope === void 0 || path === scope || path.startsWith(scope + "/");
+}
+
+// src/mutator.ts
+var Mutator = class {
+  constructor(tree, addressing, log, deps) {
+    this.tree = tree;
+    this.addressing = addressing;
+    this.log = log;
+    this.deps = deps;
+  }
+  tree;
+  addressing;
+  log;
+  deps;
+  resolve(ref) {
+    const node = "id" in ref ? this.addressing.byId(ref.id) : this.addressing.byPath(ref.path);
+    if (!node) throw new NodeNotFoundError(ref);
+    return node;
+  }
+  checkScope(node, writeScope) {
+    if (writeScope === void 0) return;
+    const path = this.addressing.pathOf(node.id);
+    if (!isWithin(path, writeScope)) throw new ScopeViolationError(path, writeScope);
+  }
+  checkVersion(node, ifVersion) {
+    if (ifVersion !== void 0 && node.meta.version !== ifVersion) {
+      throw new StaleVersionError(node.id, ifVersion, node.meta.version);
+    }
+  }
+  bump(node, owner) {
+    node.meta.version += 1;
+    node.meta.updatedAt = this.deps.clock.now();
+    if (owner !== void 0) node.meta.owner = owner;
+  }
+  set(ref, value, opts = {}) {
+    const node = this.resolve(ref);
+    this.checkScope(node, opts.writeScope);
+    this.checkVersion(node, opts.ifVersion);
+    const cloned = structuredClone(value);
+    const clearType = opts.type === null;
+    const type = clearType ? void 0 : opts.type ?? node.type;
+    this.deps.validate?.({ node, proposed: cloned, type, op: "set" });
+    const before = this.tree.toJson(node.id);
+    const typeBefore = node.type;
+    const tagsBefore = [...node.tags ?? []];
+    const orphaned = this.tree.descendantIds(node.id);
+    this.tree.replaceValue(node.id, cloned, type, clearType);
+    if (opts.tags !== void 0) node.tags = [...opts.tags];
+    this.bump(node, opts.owner);
+    this.deps.onChange?.(node);
+    if (this.deps.onChange) {
+      for (const id of this.tree.descendantIds(node.id)) {
+        const child = this.tree.get(id);
+        if (child) this.deps.onChange(child);
+      }
+    }
+    if (this.deps.onRemove) {
+      for (const id of orphaned) this.deps.onRemove(id);
+    }
+    this.log.append({
+      kind: "set",
+      targetId: node.id,
+      parentId: node.parentId,
+      key: node.key,
+      path: this.addressing.pathOf(node.id),
+      before,
+      after: cloned,
+      nodeTypeBefore: typeBefore ?? null,
+      nodeType: type ?? null,
+      tagsBefore,
+      tags: [...node.tags ?? []],
+      actor: opts.owner,
+      ts: this.deps.clock.now()
+    });
+  }
+  insert(parentRef, keyOrIndex, value, opts = {}) {
+    const parent = this.resolve(parentRef);
+    this.checkScope(parent, opts.writeScope);
+    this.checkVersion(parent, opts.ifVersion);
+    const cloned = structuredClone(value);
+    const type = opts.type === null ? void 0 : opts.type;
+    this.deps.validate?.({ node: null, proposed: cloned, type, op: "insert" });
+    const newId = this.tree.insertChild(parent.id, keyOrIndex, cloned, type);
+    const child = this.tree.get(newId);
+    if (opts.tags !== void 0) child.tags = [...opts.tags];
+    this.bump(parent, opts.owner);
+    this.deps.onChange?.(child);
+    if (this.deps.onChange) {
+      for (const id of this.tree.descendantIds(newId)) {
+        const desc = this.tree.get(id);
+        if (desc) this.deps.onChange(desc);
+      }
+    }
+    this.log.append({
+      kind: "insert",
+      targetId: newId,
+      parentId: parent.id,
+      key: child.key,
+      path: this.addressing.pathOf(newId),
+      after: cloned,
+      nodeType: child.type ?? null,
+      tags: [...child.tags ?? []],
+      actor: opts.owner,
+      ts: this.deps.clock.now()
+    });
+    return newId;
+  }
+  remove(ref, opts = {}) {
+    const node = this.resolve(ref);
+    if (node.parentId === null) throw new InvalidOpError("cannot remove the root");
+    this.checkScope(node, opts.writeScope);
+    this.checkVersion(node, opts.ifVersion);
+    const before = this.tree.toJson(node.id);
+    const path = this.addressing.pathOf(node.id);
+    const removedIds = [node.id, ...this.tree.descendantIds(node.id)];
+    const parent = this.tree.get(node.parentId);
+    const removedKey = node.key;
+    this.tree.removeChild(node.parentId, node.id);
+    this.bump(parent, opts.owner);
+    if (this.deps.onRemove) {
+      for (const id of removedIds) this.deps.onRemove(id);
+    }
+    this.deps.onChange?.(parent);
+    this.log.append({
+      kind: "remove",
+      targetId: node.id,
+      parentId: parent.id,
+      key: removedKey,
+      path,
+      before,
+      nodeTypeBefore: node.type ?? null,
+      tagsBefore: [...node.tags ?? []],
+      actor: opts.owner,
+      ts: this.deps.clock.now()
+    });
+  }
+  move(ref, toParentRef, keyOrIndex, opts = {}) {
+    const node = this.resolve(ref);
+    if (node.parentId === null) throw new InvalidOpError("cannot move the root");
+    const toParent = this.resolve(toParentRef);
+    this.checkScope(node, opts.writeScope);
+    this.checkScope(toParent, opts.writeScope);
+    this.checkVersion(node, opts.ifVersion);
+    const oldParentId = node.parentId;
+    const from = { parentId: node.parentId, key: node.key };
+    const fromPath = this.addressing.pathOf(node.id);
+    this.tree.moveNode(node.id, toParent.id, keyOrIndex);
+    const toPath = this.addressing.pathOf(node.id);
+    const bumped = /* @__PURE__ */ new Set();
+    for (const id of [node.id, oldParentId, toParent.id]) {
+      if (id !== null && !bumped.has(id)) {
+        const n = this.tree.get(id);
+        if (n) this.bump(n, opts.owner);
+        bumped.add(id);
+      }
+    }
+    if (this.deps.onChange) {
+      this.deps.onChange(node);
+      for (const id of this.tree.descendantIds(node.id)) {
+        const d = this.tree.get(id);
+        if (d) this.deps.onChange(d);
+      }
+      const oldP = oldParentId !== null ? this.tree.get(oldParentId) : void 0;
+      if (oldP) this.deps.onChange(oldP);
+      const newP = this.tree.get(toParent.id);
+      if (newP) this.deps.onChange(newP);
+    }
+    this.log.append({
+      kind: "move",
+      targetId: node.id,
+      parentId: toParent.id,
+      key: node.key,
+      from,
+      to: { parentId: toParent.id, key: node.key },
+      fromPath,
+      toPath,
+      actor: opts.owner,
+      ts: this.deps.clock.now()
+    });
+  }
+  /** Run `fn` atomically: if it throws, the tree, log, and any hooked index state are restored. */
+  transaction(fn) {
+    const snap = this.tree.snapshot();
+    const logLen = this.log.length();
+    const hookSnap = this.deps.onTxSnapshot?.();
+    try {
+      fn();
+    } catch (err) {
+      this.tree.restore(snap);
+      this.log.truncateTo(logLen);
+      if (this.deps.onTxRestore) this.deps.onTxRestore(hookSnap);
+      throw err;
+    }
+  }
+};
+export {
+  Mutator
+};
+//# sourceMappingURL=mutator.js.map

package/dist/mutator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/jsonpointer.ts","../src/mutator.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","/** 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, Json, NodeId } from \"./types\";\r\nimport type { Clock } from \"./clock\";\r\nimport type { ArtifactTree } from \"./artifact-tree\";\r\nimport type { Addressing } from \"./addressing\";\r\nimport type { EventLog, OpKind } from \"./event-log\";\r\nimport { type Ref, NodeNotFoundError, ScopeViolationError, StaleVersionError, InvalidOpError } from \"./errors\";\r\nimport { isWithin } from \"./jsonpointer\";\r\n\r\n/** Optional validation hook. Throws to reject a mutation. M3 plugs Zod in here. */\r\nexport type Validator = (input: { node: ArbNode | null; proposed: Json; type?: string; op: OpKind }) => void;\r\n\r\nexport interface MutatorDeps {\r\n  clock: Clock;\r\n  validate?: Validator;\r\n  /** Called after a node's content changes (set/insert) — e.g. to mark a semantic index stale. */\r\n  onChange?: (node: ArbNode) => void;\r\n  /** Called after a node is removed — e.g. to drop it from a semantic index. */\r\n  onRemove?: (nodeId: NodeId) => void;\r\n  /** Called at transaction start; the returned snapshot is passed to `onTxRestore` on rollback. */\r\n  onTxSnapshot?: () => unknown;\r\n  /** Called on transaction rollback with the snapshot from `onTxSnapshot`. */\r\n  onTxRestore?: (snapshot: unknown) => void;\r\n}\r\n\r\nexport interface MutateOpts {\r\n  owner?: string;\r\n  /** JSON Pointer prefix; the target must be at or under it. */\r\n  writeScope?: string;\r\n  /** Optimistic concurrency: reject unless the target's current version equals this. */\r\n  ifVersion?: number;\r\n  /** Register/override the node's type (drives validation and the decompose override).\r\n   *  `null` explicitly CLEARS the type (validation is skipped) — used by type-aware revert. */\r\n  type?: string | null;\r\n  /** Replace the node's tags (identity labels for exact `find` by tag). */\r\n  tags?: string[];\r\n}\r\n\r\nexport class Mutator {\r\n  constructor(\r\n    private readonly tree: ArtifactTree,\r\n    private readonly addressing: Addressing,\r\n    private readonly log: EventLog,\r\n    private readonly deps: MutatorDeps,\r\n  ) {}\r\n\r\n  private resolve(ref: Ref): ArbNode {\r\n    const node = \"id\" in ref ? this.addressing.byId(ref.id) : this.addressing.byPath(ref.path);\r\n    if (!node) throw new NodeNotFoundError(ref);\r\n    return node;\r\n  }\r\n\r\n  private checkScope(node: ArbNode, writeScope?: string): void {\r\n    if (writeScope === undefined) return;\r\n    const path = this.addressing.pathOf(node.id);\r\n    if (!isWithin(path, writeScope)) throw new ScopeViolationError(path, writeScope);\r\n  }\r\n\r\n  private checkVersion(node: ArbNode, ifVersion?: number): void {\r\n    if (ifVersion !== undefined && node.meta.version !== ifVersion) {\r\n      throw new StaleVersionError(node.id, ifVersion, node.meta.version);\r\n    }\r\n  }\r\n\r\n  private bump(node: ArbNode, owner?: string): void {\r\n    node.meta.version += 1;\r\n    node.meta.updatedAt = this.deps.clock.now();\r\n    if (owner !== undefined) node.meta.owner = owner;\r\n  }\r\n\r\n  set(ref: Ref, value: Json, opts: MutateOpts = {}): void {\r\n    const node = this.resolve(ref);\r\n    this.checkScope(node, opts.writeScope);\r\n    this.checkVersion(node, opts.ifVersion);\r\n    // Defensive copy: neither the tree nor the event log may alias the caller's\r\n    // live object — post-call mutation would silently rewrite state AND history.\r\n    const cloned = structuredClone(value);\r\n    const clearType = opts.type === null;\r\n    const type = clearType ? undefined : (opts.type ?? node.type);\r\n    this.deps.validate?.({ node, proposed: cloned, type, op: \"set\" });\r\n    const before = this.tree.toJson(node.id);\r\n    const typeBefore = node.type;\r\n    const tagsBefore = [...(node.tags ?? [])];\r\n    const orphaned = this.tree.descendantIds(node.id);\r\n    this.tree.replaceValue(node.id, cloned, type, clearType);\r\n    if (opts.tags !== undefined) node.tags = [...opts.tags];\r\n    this.bump(node, opts.owner);\r\n    this.deps.onChange?.(node);\r\n    if (this.deps.onChange) {\r\n      // replaceValue rebuilt the subtree: every descendant is a NEW node and\r\n      // must be announced too (text leaves are what the semantic index embeds).\r\n      for (const id of this.tree.descendantIds(node.id)) {\r\n        const child = this.tree.get(id);\r\n        if (child) this.deps.onChange(child);\r\n      }\r\n    }\r\n    if (this.deps.onRemove) {\r\n      for (const id of orphaned) this.deps.onRemove(id);\r\n    }\r\n    this.log.append({\r\n      kind: \"set\",\r\n      targetId: node.id,\r\n      parentId: node.parentId,\r\n      key: node.key,\r\n      path: this.addressing.pathOf(node.id),\r\n      before,\r\n      after: cloned,\r\n      nodeTypeBefore: typeBefore ?? null,\r\n      nodeType: type ?? null,\r\n      tagsBefore,\r\n      tags: [...(node.tags ?? [])],\r\n      actor: opts.owner,\r\n      ts: this.deps.clock.now(),\r\n    });\r\n  }\r\n\r\n  insert(parentRef: Ref, keyOrIndex: string | number, value: Json, opts: MutateOpts = {}): NodeId {\r\n    const parent = this.resolve(parentRef);\r\n    this.checkScope(parent, opts.writeScope);\r\n    this.checkVersion(parent, opts.ifVersion);\r\n    // Defensive copy: neither the tree nor the event log may alias the caller's\r\n    // live object — post-call mutation would silently rewrite state AND history.\r\n    const cloned = structuredClone(value);\r\n    const type = opts.type === null ? undefined : opts.type;\r\n    this.deps.validate?.({ node: null, proposed: cloned, type, op: \"insert\" });\r\n    const newId = this.tree.insertChild(parent.id, keyOrIndex, cloned, type);\r\n    const child = this.tree.get(newId)!;\r\n    if (opts.tags !== undefined) child.tags = [...opts.tags];\r\n    this.bump(parent, opts.owner);\r\n    this.deps.onChange?.(child);\r\n    if (this.deps.onChange) {\r\n      for (const id of this.tree.descendantIds(newId)) {\r\n        const desc = this.tree.get(id);\r\n        if (desc) this.deps.onChange(desc);\r\n      }\r\n    }\r\n    this.log.append({\r\n      kind: \"insert\",\r\n      targetId: newId,\r\n      parentId: parent.id,\r\n      key: child.key,\r\n      path: this.addressing.pathOf(newId),\r\n      after: cloned,\r\n      nodeType: child.type ?? null,\r\n      tags: [...(child.tags ?? [])],\r\n      actor: opts.owner,\r\n      ts: this.deps.clock.now(),\r\n    });\r\n    return newId;\r\n  }\r\n\r\n  remove(ref: Ref, opts: MutateOpts = {}): void {\r\n    const node = this.resolve(ref);\r\n    if (node.parentId === null) throw new InvalidOpError(\"cannot remove the root\");\r\n    this.checkScope(node, opts.writeScope);\r\n    this.checkVersion(node, opts.ifVersion);\r\n    const before = this.tree.toJson(node.id);\r\n    const path = this.addressing.pathOf(node.id);\r\n    const removedIds = [node.id, ...this.tree.descendantIds(node.id)];\r\n    const parent = this.tree.get(node.parentId)!;\r\n    const removedKey = node.key;\r\n    this.tree.removeChild(node.parentId, node.id);\r\n    this.bump(parent, opts.owner);\r\n    if (this.deps.onRemove) {\r\n      for (const id of removedIds) this.deps.onRemove(id);\r\n    }\r\n    // The parent's semantic unit (if any) lost content — re-hash it.\r\n    this.deps.onChange?.(parent);\r\n    this.log.append({\r\n      kind: \"remove\",\r\n      targetId: node.id,\r\n      parentId: parent.id,\r\n      key: removedKey,\r\n      path,\r\n      before,\r\n      nodeTypeBefore: node.type ?? null,\r\n      tagsBefore: [...(node.tags ?? [])],\r\n      actor: opts.owner,\r\n      ts: this.deps.clock.now(),\r\n    });\r\n  }\r\n\r\n  move(ref: Ref, toParentRef: Ref, keyOrIndex: string | number, opts: MutateOpts = {}): void {\r\n    const node = this.resolve(ref);\r\n    if (node.parentId === null) throw new InvalidOpError(\"cannot move the root\");\r\n    const toParent = this.resolve(toParentRef);\r\n    this.checkScope(node, opts.writeScope);\r\n    this.checkScope(toParent, opts.writeScope);\r\n    this.checkVersion(node, opts.ifVersion);\r\n    const oldParentId = node.parentId;\r\n    const from = { parentId: node.parentId, key: node.key };\r\n    const fromPath = this.addressing.pathOf(node.id);\r\n    this.tree.moveNode(node.id, toParent.id, keyOrIndex);\r\n    const toPath = this.addressing.pathOf(node.id);\r\n    // bump moved node + both parents (dedupe if old === new parent)\r\n    const bumped = new Set<NodeId>();\r\n    for (const id of [node.id, oldParentId, toParent.id]) {\r\n      if (id !== null && !bumped.has(id)) {\r\n        const n = this.tree.get(id);\r\n        if (n) this.bump(n, opts.owner);\r\n        bumped.add(id);\r\n      }\r\n    }\r\n    if (this.deps.onChange) {\r\n      // The moved subtree's ancestry changed (suppression status may flip), and\r\n      // both old and new locations' semantic units changed content.\r\n      this.deps.onChange(node);\r\n      for (const id of this.tree.descendantIds(node.id)) {\r\n        const d = this.tree.get(id);\r\n        if (d) this.deps.onChange(d);\r\n      }\r\n      const oldP = oldParentId !== null ? this.tree.get(oldParentId) : undefined;\r\n      if (oldP) this.deps.onChange(oldP);\r\n      const newP = this.tree.get(toParent.id);\r\n      if (newP) this.deps.onChange(newP);\r\n    }\r\n    this.log.append({\r\n      kind: \"move\",\r\n      targetId: node.id,\r\n      parentId: toParent.id,\r\n      key: node.key,\r\n      from,\r\n      to: { parentId: toParent.id, key: node.key },\r\n      fromPath,\r\n      toPath,\r\n      actor: opts.owner,\r\n      ts: this.deps.clock.now(),\r\n    });\r\n  }\r\n\r\n  /** Run `fn` atomically: if it throws, the tree, log, and any hooked index state are restored. */\r\n  transaction(fn: () => void): void {\r\n    const snap = this.tree.snapshot();\r\n    const logLen = this.log.length();\r\n    const hookSnap = this.deps.onTxSnapshot?.();\r\n    try {\r\n      fn();\r\n    } catch (err) {\r\n      this.tree.restore(snap);\r\n      this.log.truncateTo(logLen);\r\n      if (this.deps.onTxRestore) this.deps.onTxRestore(hookSnap);\r\n      throw err;\r\n    }\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/navigator.d.ts

@@ -0,0 +1,85 @@
+import { NodeId, NodeKind, Json, NodeMeta, ArbNode } from './types.js';
+import { ArtifactTree } from './artifact-tree.js';
+import { Addressing } from './addressing.js';
+import { Ref } from './errors.js';
+import './ids.js';
+import './clock.js';
+import './decompose.js';
+
+interface NodeSummary {
+    id: NodeId;
+    path: string;
+    key: string | number | null;
+    kind: NodeKind;
+    type?: string;
+}
+interface ChildSummary {
+    id: NodeId;
+    key: string | number | null;
+    kind: NodeKind;
+    type?: string;
+    hasChildren: boolean;
+    size: number;
+    preview: string;
+}
+interface DescribeOpts {
+    offset?: number;
+    limit?: number;
+}
+interface DescribeResult {
+    node: NodeSummary;
+    children: ChildSummary[];
+    truncated?: {
+        shown: number;
+        total: number;
+        nextOffset: number;
+    };
+}
+interface GetOpts {
+    maxDepth?: number;
+}
+interface GetResult {
+    id: NodeId;
+    path: string;
+    type?: string;
+    content: Json;
+    meta: NodeMeta;
+    truncated?: boolean;
+}
+interface FindSelector {
+    type?: string;
+    tag?: string;
+    pathPattern?: string;
+}
+interface FindOpts {
+    limit?: number;
+    /** JSON Pointer prefix: only nodes at/under it are hits — checked BEFORE the
+     *  limit is consumed, so out-of-scope matches never eat the budget. */
+    within?: string;
+}
+interface FindHit {
+    id: NodeId;
+    path: string;
+    type?: string;
+}
+interface FindResult {
+    hits: FindHit[];
+    /** True when the walk stopped at `limit` — there MAY be more matches (an exact-fit
+     *  final hit also reports true). */
+    truncated: boolean;
+}
+/** Read-only navigation over the artifact tree: describe (cheap listing) and get (bounded content). */
+declare class Navigator {
+    private readonly tree;
+    private readonly addressing;
+    constructor(tree: ArtifactTree, addressing: Addressing);
+    protected resolve(ref: Ref): ArbNode;
+    private summarize;
+    describe(ref?: Ref, opts?: DescribeOpts): DescribeResult;
+    get(ref: Ref, opts?: GetOpts): GetResult;
+    private matches;
+    /** Find nodes matching ALL provided selector fields (exact `type`, `tag` membership, glob `pathPattern`). */
+    find(selector: FindSelector, opts?: FindOpts): FindResult;
+}
+
+export { type ChildSummary, type DescribeOpts, type DescribeResult, type FindHit, type FindOpts, type FindResult, type FindSelector, type GetOpts, type GetResult, Navigator, type NodeSummary };

package/dist/navigator.js

@@ -0,0 +1,192 @@
+// src/errors.ts
+var ArborError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = new.target.name;
+  }
+  code;
+};
+var NodeNotFoundError = class extends ArborError {
+  constructor(ref) {
+    super("NODE_NOT_FOUND", `Node not found: ${JSON.stringify(ref)}`);
+    this.ref = ref;
+  }
+  ref;
+};
+
+// src/decompose.ts
+function byteSize(value) {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+
+// 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 appendPointer(parent, key) {
+  return parent + "/" + encodeSegment(String(key));
+}
+function isWithin(path, scope) {
+  return scope === void 0 || path === scope || path.startsWith(scope + "/");
+}
+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/path-glob.ts
+function matchSegments(pattern, path) {
+  if (pattern.length === 0) return path.length === 0;
+  const [head, ...rest] = pattern;
+  if (head === "**") {
+    for (let i = 0; i <= path.length; i++) {
+      if (matchSegments(rest, path.slice(i))) return true;
+    }
+    return false;
+  }
+  if (path.length === 0) return false;
+  if (head === "*" || head === path[0]) {
+    return matchSegments(rest, path.slice(1));
+  }
+  return false;
+}
+function compileGlob(pattern) {
+  const patternSegs = parsePointer(pattern);
+  return (path) => matchSegments(patternSegs, parsePointer(path));
+}
+
+// src/navigator.ts
+var DEFAULT_LIMIT = 100;
+var PREVIEW_MAX = 50;
+function previewOf(node) {
+  if (node.kind === "leaf") {
+    const s = JSON.stringify(node.content);
+    return s.length <= PREVIEW_MAX ? s : s.slice(0, PREVIEW_MAX) + "\u2026";
+  }
+  return node.kind === "array" ? `[${node.childIds.length} items]` : `{${node.childIds.length} keys}`;
+}
+var Navigator = class {
+  constructor(tree, addressing) {
+    this.tree = tree;
+    this.addressing = addressing;
+  }
+  tree;
+  addressing;
+  resolve(ref) {
+    const node = "id" in ref ? this.addressing.byId(ref.id) : this.addressing.byPath(ref.path);
+    if (!node) throw new NodeNotFoundError(ref);
+    return node;
+  }
+  summarize(node) {
+    return {
+      id: node.id,
+      key: node.key,
+      kind: node.kind,
+      type: node.type,
+      hasChildren: node.childIds.length > 0,
+      size: node.kind === "leaf" ? byteSize(node.content) : node.childIds.length,
+      preview: previewOf(node)
+    };
+  }
+  describe(ref = { path: "" }, opts = {}) {
+    const node = this.resolve(ref);
+    const all = this.tree.children(node.id);
+    const total = all.length;
+    const offset = opts.offset ?? 0;
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    const page = all.slice(offset, offset + limit);
+    const result = {
+      node: {
+        id: node.id,
+        path: this.addressing.pathOf(node.id),
+        key: node.key,
+        kind: node.kind,
+        type: node.type
+      },
+      children: page.map((c) => this.summarize(c))
+    };
+    const nextOffset = offset + page.length;
+    if (nextOffset < total) {
+      result.truncated = { shown: page.length, total, nextOffset };
+    }
+    return result;
+  }
+  get(ref, opts = {}) {
+    const node = this.resolve(ref);
+    const maxDepth = opts.maxDepth;
+    let truncated = false;
+    const reconstruct = (id, depth) => {
+      const n = this.tree.get(id);
+      if (n.kind === "leaf") return n.content;
+      if (maxDepth !== void 0 && depth >= maxDepth) {
+        truncated = true;
+        const label = n.kind === "array" ? `${n.childIds.length} items` : `${n.childIds.length} keys`;
+        return `[truncated: ${label}]`;
+      }
+      if (n.kind === "array") return n.childIds.map((cid) => reconstruct(cid, depth + 1));
+      const obj = {};
+      for (const cid of n.childIds) {
+        const c = this.tree.get(cid);
+        obj[String(c.key)] = reconstruct(cid, depth + 1);
+      }
+      return obj;
+    };
+    const content = reconstruct(node.id, 0);
+    const result = {
+      id: node.id,
+      path: this.addressing.pathOf(node.id),
+      type: node.type,
+      content,
+      meta: node.meta
+    };
+    if (truncated) result.truncated = true;
+    return result;
+  }
+  matches(node, sel, path, glob) {
+    if (sel.type !== void 0 && node.type !== sel.type) return false;
+    if (sel.tag !== void 0 && !(node.tags?.includes(sel.tag) ?? false)) return false;
+    if (glob !== void 0 && !glob(path)) return false;
+    return true;
+  }
+  /** Find nodes matching ALL provided selector fields (exact `type`, `tag` membership, glob `pathPattern`). */
+  find(selector, opts = {}) {
+    const limit = opts.limit ?? DEFAULT_LIMIT;
+    const within = opts.within;
+    const glob = selector.pathPattern !== void 0 ? compileGlob(selector.pathPattern) : void 0;
+    const hits = [];
+    let truncated = false;
+    const visit = (id, path) => {
+      if (hits.length >= limit) {
+        truncated = true;
+        return;
+      }
+      const node = this.tree.get(id);
+      if (this.matches(node, selector, path, glob)) {
+        if (isWithin(path, within)) {
+          hits.push({ id: node.id, path, type: node.type });
+        }
+      }
+      for (const cid of node.childIds) {
+        if (hits.length >= limit) {
+          truncated = true;
+          break;
+        }
+        const child = this.tree.get(cid);
+        visit(cid, appendPointer(path, child.key));
+      }
+    };
+    visit(this.tree.rootIdValue(), "");
+    return { hits, truncated };
+  }
+};
+export {
+  Navigator
+};
+//# sourceMappingURL=navigator.js.map

package/dist/navigator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/decompose.ts","../src/jsonpointer.ts","../src/path-glob.ts","../src/navigator.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","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","/** 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 { parsePointer } from \"./jsonpointer\";\r\n\r\n/** Match parsed segment arrays. `*` = one segment; `**` = zero or more segments. */\r\nfunction matchSegments(pattern: string[], path: string[]): boolean {\r\n  if (pattern.length === 0) return path.length === 0;\r\n  const [head, ...rest] = pattern;\r\n  if (head === \"**\") {\r\n    for (let i = 0; i <= path.length; i++) {\r\n      if (matchSegments(rest, path.slice(i))) return true;\r\n    }\r\n    return false;\r\n  }\r\n  if (path.length === 0) return false;\r\n  if (head === \"*\" || head === path[0]) {\r\n    return matchSegments(rest, path.slice(1));\r\n  }\r\n  return false;\r\n}\r\n\r\n/**\r\n * Parse a glob `pattern` ONCE and return a reusable matcher over JSON Pointer paths.\r\n * `*` matches exactly one path segment; `**` matches zero or more segments.\r\n */\r\nexport function compileGlob(pattern: string): (path: string) => boolean {\r\n  const patternSegs = parsePointer(pattern);\r\n  return (path: string) => matchSegments(patternSegs, parsePointer(path));\r\n}\r\n\r\n/**\r\n * Glob-match a JSON Pointer `path` against a `pattern`.\r\n * `*` matches exactly one path segment; `**` matches zero or more segments.\r\n * One-shot convenience over `compileGlob` — prefer compiling when matching many paths.\r\n */\r\nexport function matchGlob(pattern: string, path: string): boolean {\r\n  return compileGlob(pattern)(path);\r\n}\r\n","import type { ArbNode, Json, NodeId, NodeKind, NodeMeta } from \"./types\";\r\nimport type { ArtifactTree } from \"./artifact-tree\";\r\nimport type { Addressing } from \"./addressing\";\r\nimport { type Ref, NodeNotFoundError } from \"./errors\";\r\nimport { byteSize } from \"./decompose\";\r\nimport { compileGlob } from \"./path-glob\";\r\nimport { isWithin, appendPointer } from \"./jsonpointer\";\r\n\r\nconst DEFAULT_LIMIT = 100;\r\nconst PREVIEW_MAX = 50;\r\n\r\nexport interface NodeSummary {\r\n  id: NodeId;\r\n  path: string;\r\n  key: string | number | null;\r\n  kind: NodeKind;\r\n  type?: string;\r\n}\r\n\r\nexport interface ChildSummary {\r\n  id: NodeId;\r\n  key: string | number | null;\r\n  kind: NodeKind;\r\n  type?: string;\r\n  hasChildren: boolean;\r\n  size: number;\r\n  preview: string;\r\n}\r\n\r\nexport interface DescribeOpts {\r\n  offset?: number;\r\n  limit?: number;\r\n}\r\n\r\nexport interface DescribeResult {\r\n  node: NodeSummary;\r\n  children: ChildSummary[];\r\n  truncated?: { shown: number; total: number; nextOffset: number };\r\n}\r\n\r\nexport interface GetOpts {\r\n  maxDepth?: number;\r\n}\r\n\r\nexport interface GetResult {\r\n  id: NodeId;\r\n  path: string;\r\n  type?: string;\r\n  content: Json;\r\n  meta: NodeMeta;\r\n  truncated?: boolean;\r\n}\r\n\r\nexport interface FindSelector {\r\n  type?: string;\r\n  tag?: string;\r\n  pathPattern?: string;\r\n}\r\n\r\nexport interface FindOpts {\r\n  limit?: number;\r\n  /** JSON Pointer prefix: only nodes at/under it are hits — checked BEFORE the\r\n   *  limit is consumed, so out-of-scope matches never eat the budget. */\r\n  within?: string;\r\n}\r\n\r\nexport interface FindHit {\r\n  id: NodeId;\r\n  path: string;\r\n  type?: string;\r\n}\r\n\r\nexport interface FindResult {\r\n  hits: FindHit[];\r\n  /** True when the walk stopped at `limit` — there MAY be more matches (an exact-fit\r\n   *  final hit also reports true). */\r\n  truncated: boolean;\r\n}\r\n\r\nfunction previewOf(node: ArbNode): string {\r\n  if (node.kind === \"leaf\") {\r\n    const s = JSON.stringify(node.content);\r\n    return s.length <= PREVIEW_MAX ? s : s.slice(0, PREVIEW_MAX) + \"…\";\r\n  }\r\n  return node.kind === \"array\" ? `[${node.childIds.length} items]` : `{${node.childIds.length} keys}`;\r\n}\r\n\r\n/** Read-only navigation over the artifact tree: describe (cheap listing) and get (bounded content). */\r\nexport class Navigator {\r\n  constructor(\r\n    private readonly tree: ArtifactTree,\r\n    private readonly addressing: Addressing,\r\n  ) {}\r\n\r\n  protected resolve(ref: Ref): ArbNode {\r\n    const node = \"id\" in ref ? this.addressing.byId(ref.id) : this.addressing.byPath(ref.path);\r\n    if (!node) throw new NodeNotFoundError(ref);\r\n    return node;\r\n  }\r\n\r\n  private summarize(node: ArbNode): ChildSummary {\r\n    return {\r\n      id: node.id,\r\n      key: node.key,\r\n      kind: node.kind,\r\n      type: node.type,\r\n      hasChildren: node.childIds.length > 0,\r\n      size: node.kind === \"leaf\" ? byteSize(node.content) : node.childIds.length,\r\n      preview: previewOf(node),\r\n    };\r\n  }\r\n\r\n  describe(ref: Ref = { path: \"\" }, opts: DescribeOpts = {}): DescribeResult {\r\n    const node = this.resolve(ref);\r\n    const all = this.tree.children(node.id);\r\n    const total = all.length;\r\n    const offset = opts.offset ?? 0;\r\n    const limit = opts.limit ?? DEFAULT_LIMIT;\r\n    const page = all.slice(offset, offset + limit);\r\n    const result: DescribeResult = {\r\n      node: {\r\n        id: node.id,\r\n        path: this.addressing.pathOf(node.id),\r\n        key: node.key,\r\n        kind: node.kind,\r\n        type: node.type,\r\n      },\r\n      children: page.map((c) => this.summarize(c)),\r\n    };\r\n    const nextOffset = offset + page.length;\r\n    if (nextOffset < total) {\r\n      result.truncated = { shown: page.length, total, nextOffset };\r\n    }\r\n    return result;\r\n  }\r\n\r\n  get(ref: Ref, opts: GetOpts = {}): GetResult {\r\n    const node = this.resolve(ref);\r\n    const maxDepth = opts.maxDepth;\r\n    let truncated = false;\r\n    const reconstruct = (id: NodeId, depth: number): Json => {\r\n      const n = this.tree.get(id)!;\r\n      if (n.kind === \"leaf\") return n.content;\r\n      if (maxDepth !== undefined && depth >= maxDepth) {\r\n        truncated = true;\r\n        const label = n.kind === \"array\" ? `${n.childIds.length} items` : `${n.childIds.length} keys`;\r\n        return `[truncated: ${label}]`;\r\n      }\r\n      if (n.kind === \"array\") return n.childIds.map((cid) => reconstruct(cid, depth + 1));\r\n      const obj: Record<string, Json> = {};\r\n      for (const cid of n.childIds) {\r\n        const c = this.tree.get(cid)!;\r\n        obj[String(c.key)] = reconstruct(cid, depth + 1);\r\n      }\r\n      return obj;\r\n    };\r\n    const content = reconstruct(node.id, 0);\r\n    const result: GetResult = {\r\n      id: node.id,\r\n      path: this.addressing.pathOf(node.id),\r\n      type: node.type,\r\n      content,\r\n      meta: node.meta,\r\n    };\r\n    if (truncated) result.truncated = true;\r\n    return result;\r\n  }\r\n\r\n  private matches(node: ArbNode, sel: FindSelector, path: string, glob?: (path: string) => boolean): boolean {\r\n    if (sel.type !== undefined && node.type !== sel.type) return false;\r\n    if (sel.tag !== undefined && !(node.tags?.includes(sel.tag) ?? false)) return false;\r\n    if (glob !== undefined && !glob(path)) return false;\r\n    return true;\r\n  }\r\n\r\n  /** Find nodes matching ALL provided selector fields (exact `type`, `tag` membership, glob `pathPattern`). */\r\n  find(selector: FindSelector, opts: FindOpts = {}): FindResult {\r\n    const limit = opts.limit ?? DEFAULT_LIMIT;\r\n    const within = opts.within;\r\n    // The pattern is parsed ONCE per find; each node's path is built incrementally\r\n    // down the DFS (no per-node pathOf walk to the root).\r\n    const glob = selector.pathPattern !== undefined ? compileGlob(selector.pathPattern) : undefined;\r\n    const hits: FindHit[] = [];\r\n    let truncated = false;\r\n    const visit = (id: NodeId, path: string): void => {\r\n      if (hits.length >= limit) {\r\n        truncated = true;\r\n        return;\r\n      }\r\n      const node = this.tree.get(id)!;\r\n      if (this.matches(node, selector, path, glob)) {\r\n        if (isWithin(path, within)) {\r\n          hits.push({ id: node.id, path, type: node.type });\r\n        }\r\n      }\r\n      for (const cid of node.childIds) {\r\n        if (hits.length >= limit) {\r\n          truncated = true;\r\n          break;\r\n        }\r\n        const child = this.tree.get(cid)!;\r\n        visit(cid, appendPointer(path, child.key as string | number));\r\n      }\r\n    };\r\n    visit(this.tree.rootIdValue(), \"\");\r\n    return { hits, truncated };\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/path-glob.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse a glob `pattern` ONCE and return a reusable matcher over JSON Pointer paths.
+ * `*` matches exactly one path segment; `**` matches zero or more segments.
+ */
+declare function compileGlob(pattern: string): (path: string) => boolean;
+/**
+ * Glob-match a JSON Pointer `path` against a `pattern`.
+ * `*` matches exactly one path segment; `**` matches zero or more segments.
+ * One-shot convenience over `compileGlob` — prefer compiling when matching many paths.
+ */
+declare function matchGlob(pattern: string, path: string): boolean;
+
+export { compileGlob, matchGlob };

package/dist/path-glob.js

@@ -0,0 +1,40 @@
+// src/jsonpointer.ts
+function decodeSegment(s) {
+  return s.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+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/path-glob.ts
+function matchSegments(pattern, path) {
+  if (pattern.length === 0) return path.length === 0;
+  const [head, ...rest] = pattern;
+  if (head === "**") {
+    for (let i = 0; i <= path.length; i++) {
+      if (matchSegments(rest, path.slice(i))) return true;
+    }
+    return false;
+  }
+  if (path.length === 0) return false;
+  if (head === "*" || head === path[0]) {
+    return matchSegments(rest, path.slice(1));
+  }
+  return false;
+}
+function compileGlob(pattern) {
+  const patternSegs = parsePointer(pattern);
+  return (path) => matchSegments(patternSegs, parsePointer(path));
+}
+function matchGlob(pattern, path) {
+  return compileGlob(pattern)(path);
+}
+export {
+  compileGlob,
+  matchGlob
+};
+//# sourceMappingURL=path-glob.js.map

package/dist/path-glob.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/jsonpointer.ts","../src/path-glob.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 { parsePointer } from \"./jsonpointer\";\r\n\r\n/** Match parsed segment arrays. `*` = one segment; `**` = zero or more segments. */\r\nfunction matchSegments(pattern: string[], path: string[]): boolean {\r\n  if (pattern.length === 0) return path.length === 0;\r\n  const [head, ...rest] = pattern;\r\n  if (head === \"**\") {\r\n    for (let i = 0; i <= path.length; i++) {\r\n      if (matchSegments(rest, path.slice(i))) return true;\r\n    }\r\n    return false;\r\n  }\r\n  if (path.length === 0) return false;\r\n  if (head === \"*\" || head === path[0]) {\r\n    return matchSegments(rest, path.slice(1));\r\n  }\r\n  return false;\r\n}\r\n\r\n/**\r\n * Parse a glob `pattern` ONCE and return a reusable matcher over JSON Pointer paths.\r\n * `*` matches exactly one path segment; `**` matches zero or more segments.\r\n */\r\nexport function compileGlob(pattern: string): (path: string) => boolean {\r\n  const patternSegs = parsePointer(pattern);\r\n  return (path: string) => matchSegments(patternSegs, parsePointer(path));\r\n}\r\n\r\n/**\r\n * Glob-match a JSON Pointer `path` against a `pattern`.\r\n * `*` matches exactly one path segment; `**` matches zero or more segments.\r\n * One-shot convenience over `compileGlob` — prefer compiling when matching many paths.\r\n */\r\nexport function matchGlob(pattern: string, path: string): boolean {\r\n  return compileGlob(pattern)(path);\r\n}\r\n"],"mappings":";AAMO,SAAS,cAAc,GAAmB;AAC/C,SAAO,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG;AACjD;AAmBO,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;;;AC9BA,SAAS,cAAc,SAAmB,MAAyB;AACjE,MAAI,QAAQ,WAAW,EAAG,QAAO,KAAK,WAAW;AACjD,QAAM,CAAC,MAAM,GAAG,IAAI,IAAI;AACxB,MAAI,SAAS,MAAM;AACjB,aAAS,IAAI,GAAG,KAAK,KAAK,QAAQ,KAAK;AACrC,UAAI,cAAc,MAAM,KAAK,MAAM,CAAC,CAAC,EAAG,QAAO;AAAA,IACjD;AACA,WAAO;AAAA,EACT;AACA,MAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,MAAI,SAAS,OAAO,SAAS,KAAK,CAAC,GAAG;AACpC,WAAO,cAAc,MAAM,KAAK,MAAM,CAAC,CAAC;AAAA,EAC1C;AACA,SAAO;AACT;AAMO,SAAS,YAAY,SAA4C;AACtE,QAAM,cAAc,aAAa,OAAO;AACxC,SAAO,CAAC,SAAiB,cAAc,aAAa,aAAa,IAAI,CAAC;AACxE;AAOO,SAAS,UAAU,SAAiB,MAAuB;AAChE,SAAO,YAAY,OAAO,EAAE,IAAI;AAClC;","names":[]}