@openparser/lineage 1.0.4 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @openparser/lineage
 
+## 1.0.5
+
+### Patch Changes
+
+- d46a558: Dotted field paths now round-trip keys containing periods and tildes without collisions, preventing review edits from targeting the wrong field.
+
 ## 1.0.4
 
 ## 1.0.3

package/dist/dotted-path.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Bijective JSON Pointer ↔ dotted UI path encoding.
+ *
+ * Segments are joined with `.`. Literal `.` and `~` inside a segment name are
+ * escaped after RFC 6901 tilde rules so a key containing `~2` (`~02`) never
+ * collides with an escaped dot (`~2`). `/` does not need dotted-layer escaping
+ * because `.` is the only segment separator.
+ *
+ * Ordinary keys without `.` or `~` round-trip unchanged (`vendor`, `items.0.amount`).
+ */
+/** Escape one dotted-path segment for joining with `.`. */
+export declare function encodeDottedPathSegment(segment: string): string;
+/** Decode one dotted-path segment produced by {@link encodeDottedPathSegment}. */
+export declare function decodeDottedPathSegment(segment: string): string;
+/** Split a dotted UI path into decoded segment names. */
+export declare function parseDottedPathSegments(path: string): string[];
+/** RFC 6901 pointer to bijective dotted UI path. */
+export declare function dottedPathFromPointer(pointer: string): string;
+/** Bijective dotted UI path back to an RFC 6901 pointer. */
+export declare function pointerFromDottedPath(dottedPath: string): string;
+//# sourceMappingURL=dotted-path.d.ts.map

package/dist/dotted-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotted-path.d.ts","sourceRoot":"","sources":["../src/dotted-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,2DAA2D;AAC3D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsB/D;AAED,yDAAyD;AACzD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9D;AAaD,oDAAoD;AACpD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGhE"}

package/dist/fields.d.ts

@@ -2,15 +2,13 @@ import type { JsonValue } from './common.js';
 import type { ConfidenceAssertion, ConfidenceKind } from './confidence.js';
 import type { LineageDocument } from './document.js';
 import type { Entity } from './entity.js';
+export { decodeDottedPathSegment, dottedPathFromPointer, encodeDottedPathSegment, parseDottedPathSegments, pointerFromDottedPath, } from './dotted-path.js';
 /** How a field's confidence came about, or that none was asserted at all. */
 export type ConfidenceOrigin = ConfidenceKind | 'not_reported';
 export type LineageField = {
     id: string;
     pointer: string;
-    /**
-     * Display-only dotted rendering of `pointer`. Lossy: a property whose name
-     * contains a dot is indistinguishable from nesting. Use `pointer` as the key.
-     */
+    /** Dotted UI rendering of `pointer`; bijective with {@link dottedPathFromPointer}. */
     dottedPath: string;
     value: JsonValue | undefined;
     confidence: ConfidenceAssertion | undefined;
@@ -25,20 +23,6 @@ export type LineageFieldTrace = {
     }>;
     activities: string[];
 };
-/**
- * RFC 6901 pointer to dotted display path, unescaping `~1` and `~0`.
- *
- * Display only. A property whose name contains a dot is indistinguishable from
- * nesting, so never use the result as a key.
- */
-export declare function dottedPathFromPointer(pointer: string): string;
-/**
- * Dotted display path back to an RFC 6901 pointer, escaping `~` and `/`.
- *
- * Only sound for paths `dottedPathFromPointer` could have produced: a property
- * name containing a dot round-trips as nesting. Prefer carrying the pointer.
- */
-export declare function pointerFromDottedPath(dottedPath: string): string;
 /**
  * The entity holding a field's current value at `pointer`.
  *

package/dist/fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGvC,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAcF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAMhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAe5C;AAgBD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,EAAE,CAS3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAmB/F"}
+{"version":3,"file":"fields.d.ts","sourceRoot":"","sources":["../src/fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGvC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC5C,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAcF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,EACpB,OAAO,EAAE,MAAM,GACd;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAe5C;AAgBD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,YAAY,EAAE,CAS3D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAmB/F"}

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export { LineageDocumentSchema, LineageDocumentShapeSchema, parseLineageDocument
 export { AttributionSchema, DigestSchema, ENTITY_KINDS, EntityKindSchema, EntitySchema, LocatorSchema, SelectorSchema, type Attribution, type Digest, type Entity, type EntityKind, type Locator, type Selector, } from './entity.js';
 export { LINEAGE_PROV_NAMESPACE, lineageIdToProvQualifiedName, toProvJson, type ProvJsonDocument, } from './prov.js';
 export { RELATION_TYPES, RelationSchema, RelationTypeSchema, type Relation, type RelationType, } from './relation.js';
-export { dottedPathFromPointer, fieldEntityByPointer, fieldTrace, fields, pointerFromDottedPath, type ConfidenceOrigin, type LineageField, type LineageFieldTrace, } from './fields.js';
+export { decodeDottedPathSegment, dottedPathFromPointer, encodeDottedPathSegment, parseDottedPathSegments, pointerFromDottedPath, } from './dotted-path.js';
+export { fieldEntityByPointer, fieldTrace, fields, type ConfidenceOrigin, type LineageField, type LineageFieldTrace, } from './fields.js';
 export { activityLabel } from './labels.js';
 export { entityAncestors, entityDescendants, topologicalEntityOrder } from './traverse.js';
 export { LineageValidationError, validateLineageGraph } from './validate.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,SAAS,GACf,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,QAAQ,GACd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,UAAU,EACV,KAAK,gBAAgB,GACtB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,UAAU,EACV,MAAM,EACN,qBAAqB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAExF,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,oBAAoB,EACpB,WAAW,EACX,iBAAiB,EACjB,oBAAoB,EACpB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,KAAK,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,SAAS,GACf,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,EACxB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,QAAQ,GACd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,UAAU,EACV,KAAK,gBAAgB,GACtB,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,MAAM,EACN,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAExF,OAAO,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -663,6 +663,58 @@ function flattenAttrs(attrs) {
   return out;
 }
 
+// src/dotted-path.ts
+var DOTTED_SEGMENT_DOT = "~2";
+var JSON_POINTER_ESCAPE = /~(?:0|1)/g;
+var INVALID_JSON_POINTER_ESCAPE = /~(?![01])/;
+var INVALID_DOTTED_PATH_ESCAPE = /~(?![02])/;
+function encodeDottedPathSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll(".", DOTTED_SEGMENT_DOT);
+}
+function decodeDottedPathSegment(segment) {
+  if (INVALID_DOTTED_PATH_ESCAPE.test(segment)) {
+    throw new Error(`Invalid dotted path escape in segment "${segment}"`);
+  }
+  let decoded = "";
+  for (let index = 0; index < segment.length; index += 1) {
+    if (segment[index] === "~" && index + 1 < segment.length) {
+      const code = segment[index + 1];
+      if (code === "0") {
+        decoded += "~";
+        index += 1;
+        continue;
+      }
+      if (code === "2") {
+        decoded += ".";
+        index += 1;
+        continue;
+      }
+    }
+    decoded += segment[index];
+  }
+  return decoded;
+}
+function parseDottedPathSegments(path) {
+  return path.split(".").filter(Boolean).map(decodeDottedPathSegment);
+}
+function encodeJsonPointerSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function decodeJsonPointerSegment(segment) {
+  if (INVALID_JSON_POINTER_ESCAPE.test(segment)) {
+    throw new Error(`Invalid JSON Pointer escape in segment "${segment}"`);
+  }
+  return segment.replace(JSON_POINTER_ESCAPE, (escape) => escape === "~1" ? "/" : "~");
+}
+function dottedPathFromPointer(pointer) {
+  if (pointer === "" || pointer === "/") return "";
+  return pointer.slice(1).split("/").map(decodeJsonPointerSegment).map(encodeDottedPathSegment).join(".");
+}
+function pointerFromDottedPath(dottedPath) {
+  if (dottedPath === "") return "";
+  return `/${parseDottedPathSegments(dottedPath).map(encodeJsonPointerSegment).join("/")}`;
+}
+
 // src/traverse.ts
 function buildForwardEdges(doc) {
   const edges = /* @__PURE__ */ new Map();
@@ -746,14 +798,6 @@ function fieldConfidence(entity) {
   if (!assertions || assertions.length === 0) return void 0;
   return assertions.find((assertion) => assertion.scope === "extraction") ?? assertions[0];
 }
-function dottedPathFromPointer(pointer) {
-  if (pointer === "" || pointer === "/") return "";
-  return pointer.replace(/^\//, "").split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~")).join(".");
-}
-function pointerFromDottedPath(dottedPath) {
-  if (dottedPath === "") return "";
-  return `/${dottedPath.split(".").map((segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`;
-}
 function fieldEntityByPointer(doc, pointer) {
   const matching = Object.entries(doc.entities).filter(([, entity]) => entity.path === pointer);
   if (matching.length === 0) return void 0;
@@ -852,8 +896,10 @@ export {
   TimestampSchema,
   TransformationSchema,
   activityLabel,
+  decodeDottedPathSegment,
   derivationId,
   dottedPathFromPointer,
+  encodeDottedPathSegment,
   entityAncestors,
   entityDescendants,
   fieldEntityByPointer,
@@ -861,6 +907,7 @@ export {
   fields,
   jsonValuesEqual,
   lineageIdToProvQualifiedName,
+  parseDottedPathSegments,
   parseLineageDocument,
   pointerFromDottedPath,
   safeParseLineageDocument,

package/dist/profile/index.js

@@ -10,6 +10,24 @@ function activityLabel(activity) {
   return activity.name ?? ACTIVITY_LABELS[activity.type] ?? activity.type;
 }
 
+// src/dotted-path.ts
+var DOTTED_SEGMENT_DOT = "~2";
+var JSON_POINTER_ESCAPE = /~(?:0|1)/g;
+var INVALID_JSON_POINTER_ESCAPE = /~(?![01])/;
+function encodeDottedPathSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll(".", DOTTED_SEGMENT_DOT);
+}
+function decodeJsonPointerSegment(segment) {
+  if (INVALID_JSON_POINTER_ESCAPE.test(segment)) {
+    throw new Error(`Invalid JSON Pointer escape in segment "${segment}"`);
+  }
+  return segment.replace(JSON_POINTER_ESCAPE, (escape) => escape === "~1" ? "/" : "~");
+}
+function dottedPathFromPointer(pointer) {
+  if (pointer === "" || pointer === "/") return "";
+  return pointer.slice(1).split("/").map(decodeJsonPointerSegment).map(encodeDottedPathSegment).join(".");
+}
+
 // src/traverse.ts
 function buildReverseEdges(doc) {
   const edges = /* @__PURE__ */ new Map();
@@ -50,10 +68,6 @@ function fieldConfidence(entity) {
   if (!assertions || assertions.length === 0) return void 0;
   return assertions.find((assertion) => assertion.scope === "extraction") ?? assertions[0];
 }
-function dottedPathFromPointer(pointer) {
-  if (pointer === "" || pointer === "/") return "";
-  return pointer.replace(/^\//, "").split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~")).join(".");
-}
 function toField(id, entity) {
   const pointer = fieldPointer(entity);
   const confidence = fieldConfidence(entity);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparser/lineage",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Zod schemas, validation, and helpers for lineage@1 complete data-derivation DAGs",
   "type": "module",
   "main": "./dist/index.js",

package/src/dotted-path.ts

@@ -0,0 +1,78 @@
+/**
+ * Bijective JSON Pointer ↔ dotted UI path encoding.
+ *
+ * Segments are joined with `.`. Literal `.` and `~` inside a segment name are
+ * escaped after RFC 6901 tilde rules so a key containing `~2` (`~02`) never
+ * collides with an escaped dot (`~2`). `/` does not need dotted-layer escaping
+ * because `.` is the only segment separator.
+ *
+ * Ordinary keys without `.` or `~` round-trip unchanged (`vendor`, `items.0.amount`).
+ */
+
+const DOTTED_SEGMENT_DOT = '~2';
+const JSON_POINTER_ESCAPE = /~(?:0|1)/g;
+const INVALID_JSON_POINTER_ESCAPE = /~(?![01])/;
+const INVALID_DOTTED_PATH_ESCAPE = /~(?![02])/;
+
+/** Escape one dotted-path segment for joining with `.`. */
+export function encodeDottedPathSegment(segment: string): string {
+  return segment.replaceAll('~', '~0').replaceAll('.', DOTTED_SEGMENT_DOT);
+}
+
+/** Decode one dotted-path segment produced by {@link encodeDottedPathSegment}. */
+export function decodeDottedPathSegment(segment: string): string {
+  if (INVALID_DOTTED_PATH_ESCAPE.test(segment)) {
+    throw new Error(`Invalid dotted path escape in segment "${segment}"`);
+  }
+  let decoded = '';
+  for (let index = 0; index < segment.length; index += 1) {
+    if (segment[index] === '~' && index + 1 < segment.length) {
+      const code = segment[index + 1];
+      if (code === '0') {
+        decoded += '~';
+        index += 1;
+        continue;
+      }
+      if (code === '2') {
+        decoded += '.';
+        index += 1;
+        continue;
+      }
+    }
+    decoded += segment[index];
+  }
+  return decoded;
+}
+
+/** Split a dotted UI path into decoded segment names. */
+export function parseDottedPathSegments(path: string): string[] {
+  return path.split('.').filter(Boolean).map(decodeDottedPathSegment);
+}
+
+function encodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function decodeJsonPointerSegment(segment: string): string {
+  if (INVALID_JSON_POINTER_ESCAPE.test(segment)) {
+    throw new Error(`Invalid JSON Pointer escape in segment "${segment}"`);
+  }
+  return segment.replace(JSON_POINTER_ESCAPE, (escape) => (escape === '~1' ? '/' : '~'));
+}
+
+/** RFC 6901 pointer to bijective dotted UI path. */
+export function dottedPathFromPointer(pointer: string): string {
+  if (pointer === '' || pointer === '/') return '';
+  return pointer
+    .slice(1)
+    .split('/')
+    .map(decodeJsonPointerSegment)
+    .map(encodeDottedPathSegment)
+    .join('.');
+}
+
+/** Bijective dotted UI path back to an RFC 6901 pointer. */
+export function pointerFromDottedPath(dottedPath: string): string {
+  if (dottedPath === '') return '';
+  return `/${parseDottedPathSegments(dottedPath).map(encodeJsonPointerSegment).join('/')}`;
+}

package/src/fields.ts

@@ -1,19 +1,25 @@
 import type { JsonValue } from './common';
 import type { ConfidenceAssertion, ConfidenceKind } from './confidence';
 import type { LineageDocument } from './document';
+import { dottedPathFromPointer } from './dotted-path';
 import type { Entity } from './entity';
 import { entityAncestors } from './traverse';
 
+export {
+  decodeDottedPathSegment,
+  dottedPathFromPointer,
+  encodeDottedPathSegment,
+  parseDottedPathSegments,
+  pointerFromDottedPath,
+} from './dotted-path';
+
 /** How a field's confidence came about, or that none was asserted at all. */
 export type ConfidenceOrigin = ConfidenceKind | 'not_reported';
 
 export type LineageField = {
   id: string;
   pointer: string;
-  /**
-   * Display-only dotted rendering of `pointer`. Lossy: a property whose name
-   * contains a dot is indistinguishable from nesting. Use `pointer` as the key.
-   */
+  /** Dotted UI rendering of `pointer`; bijective with {@link dottedPathFromPointer}. */
   dottedPath: string;
   value: JsonValue | undefined;
   confidence: ConfidenceAssertion | undefined;
@@ -39,35 +45,6 @@ function fieldConfidence(entity: Entity): ConfidenceAssertion | undefined {
   return assertions.find((assertion) => assertion.scope === 'extraction') ?? assertions[0];
 }
 
-/**
- * RFC 6901 pointer to dotted display path, unescaping `~1` and `~0`.
- *
- * Display only. A property whose name contains a dot is indistinguishable from
- * nesting, so never use the result as a key.
- */
-export function dottedPathFromPointer(pointer: string): string {
-  if (pointer === '' || pointer === '/') return '';
-  return pointer
-    .replace(/^\//, '')
-    .split('/')
-    .map((segment) => segment.replace(/~1/g, '/').replace(/~0/g, '~'))
-    .join('.');
-}
-
-/**
- * Dotted display path back to an RFC 6901 pointer, escaping `~` and `/`.
- *
- * Only sound for paths `dottedPathFromPointer` could have produced: a property
- * name containing a dot round-trips as nesting. Prefer carrying the pointer.
- */
-export function pointerFromDottedPath(dottedPath: string): string {
-  if (dottedPath === '') return '';
-  return `/${dottedPath
-    .split('.')
-    .map((segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1'))
-    .join('/')}`;
-}
-
 /**
  * The entity holding a field's current value at `pointer`.
  *

package/src/index.ts

@@ -106,11 +106,17 @@ export {
 } from './relation';
 
 export {
+  decodeDottedPathSegment,
   dottedPathFromPointer,
+  encodeDottedPathSegment,
+  parseDottedPathSegments,
+  pointerFromDottedPath,
+} from './dotted-path';
+
+export {
   fieldEntityByPointer,
   fieldTrace,
   fields,
-  pointerFromDottedPath,
   type ConfidenceOrigin,
   type LineageField,
   type LineageFieldTrace,