@pdtf/schemas 3.6.0-dev.19 → 3.6.0-dev.21

package/src/utils/v4.js

@@ -0,0 +1,765 @@
+/**
+ * V3 ⇄ V4 decomposition and recomposition.
+ *
+ * Both directions are driven entirely by `src/schemas/v4/mapping.json`, which
+ * is emitted by `src/utils/generateV4Schemas.js` from the same constants that
+ * shape the V4 schemas.  Nothing here restates the generator's rules: change
+ * the decomposition and this module follows automatically.
+ *
+ *   decompose(v3Transaction)  ->  { Property, Title[], Transaction, Person[] }
+ *   recompose(entities)       ->  v3Transaction
+ *
+ * PDTF 1.x verified claims are JSON Pointers against V3; `resolveV3Pointer`
+ * maps such a pointer onto the entity and pointer that now carry it, which is
+ * what a claim-to-credential bridge needs.
+ */
+
+const mapping = require("../schemas/v4/mapping.json");
+
+// ---------------------------------------------------------------------------
+// Manifest access
+// ---------------------------------------------------------------------------
+const getRule = (id) => {
+  const rule = mapping.rules.find((r) => r.id === id);
+  if (!rule) throw new Error(`v4 mapping: no rule with id "${id}"`);
+  return rule;
+};
+
+/** Keys present in both Title source arrays (currently: titleNumber) */
+const SHARED_TITLE_KEYS = mapping.collisions
+  .filter((c) => c.entity === "Title")
+  .map((c) => c.key);
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+const isPlainObject = (v) =>
+  v !== null && typeof v === "object" && !Array.isArray(v);
+
+const pick = (obj, keys) =>
+  Object.fromEntries(
+    Object.entries(obj || {}).filter(([k]) => keys.includes(k))
+  );
+
+const omit = (obj, keys) =>
+  Object.fromEntries(
+    Object.entries(obj || {}).filter(([k]) => !keys.includes(k))
+  );
+
+/** Apply a rule's `keys` selector to a V3 node. */
+const selectKeys = (node, rule) => {
+  if (!rule.keys) return { ...(node || {}) };
+  return rule.keys.mode === "include"
+    ? pick(node, rule.keys.values)
+    : omit(node, rule.keys.values);
+};
+
+const isEmpty = (v) =>
+  v === undefined ||
+  (isPlainObject(v) && Object.keys(v).length === 0) ||
+  (Array.isArray(v) && v.length === 0);
+
+/** Assign only when there is something to assign, so we never fabricate nodes. */
+const assignIfPresent = (target, key, value) => {
+  if (!isEmpty(value)) target[key] = value;
+};
+
+// ---------------------------------------------------------------------------
+// Default identifiers
+//
+// Deterministic and derived from the transaction, so a decompose/recompose
+// cycle is stable and diffable.  Supply `idFactory` to mint real URNs/DIDs.
+// ---------------------------------------------------------------------------
+const didSafe = (value) => String(value).replace(/[^A-Za-z0-9._-]/g, "-");
+
+const defaultIdFactory = (transactionId) => {
+  // DID method-specific ids admit only [A-Za-z0-9._-], so ids are sanitised and
+  // segments joined with "-" rather than ":".
+  const base = didSafe(transactionId || "unknown");
+  return {
+    property: () => `urn:pdtf:property:${base}`,
+    transaction: () => `did:pdtf:transaction-${base}`,
+    title: (title, index) =>
+      `urn:pdtf:title:${base}:${title.titleNumber || `index-${index}`}`,
+    // V3's own `did` is used verbatim where present — it is the party's real
+    // identifier, stable across transactions and across two entries for one
+    // person who is both buying and selling. Everything below is a fallback for
+    // instances that carry none, and array position is the last resort because
+    // it is only stable for a fixed participants array.
+    person: (participant, index) =>
+      participant?.did ||
+      `did:pdtf:person-${base}-${
+        participant?.participantId ? didSafe(participant.participantId) : index
+      }`,
+    offer: (offerId) => `urn:pdtf:offer:${base}:${didSafe(offerId)}`,
+    gift: (donor) => `urn:pdtf:gift:${base}:${didSafe(donor)}`,
+    transactionRole: (participant) =>
+      `urn:pdtf:transactionrole:${base}:${didSafe(participant)}`,
+    representation: (representative, representedParty) =>
+      `urn:pdtf:representation:${base}:${didSafe(representative)}:${didSafe(
+        representedParty
+      )}`,
+    sellerCapacity: (seller) => `urn:pdtf:sellercapacity:${base}:${didSafe(seller)}`,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// decompose
+// ---------------------------------------------------------------------------
+const decompose = (v3, { idFactory } = {}) => {
+  const propertyPack = v3.propertyPack || {};
+  const ids = { ...defaultIdFactory(v3.transactionId), ...(idFactory || {}) };
+
+  const propertyRule = getRule("property");
+  const saleContextRule = getRule("transaction.saleContext");
+  const legalOwnersRule = getRule("transaction.saleContext.legalOwners");
+  const titlesRule = getRule("title.titlesToBeSold");
+  const ownershipsRule = getRule("title.ownershipsToBeTransferred");
+  const personRule = getRule("person");
+  const contextRule = getRule("transaction.participants");
+  const transactionRule = getRule("transaction");
+
+  // --- Property ------------------------------------------------------------
+  const property = selectKeys(propertyPack, propertyRule);
+  property.id = ids.property();
+
+  // --- Title ---------------------------------------------------------------
+  // The two source arrays are correlated by titleNumber, NOT by index: a V3
+  // instance may list them in different orders or list only one side.
+  const titleItems = propertyPack.titlesToBeSold || [];
+  const ownershipItems =
+    (propertyPack.ownership || {}).ownershipsToBeTransferred || [];
+
+  const correlateBy = titlesRule.instance.correlateBy;
+  const titles = [];
+  const byKey = new Map();
+
+  const upsert = (correlationValue) => {
+    const key =
+      correlationValue === undefined ? Symbol("uncorrelated") : correlationValue;
+    if (byKey.has(key)) return byKey.get(key);
+    const entity = {};
+    byKey.set(key, entity);
+    titles.push(entity);
+    return entity;
+  };
+
+  /**
+   * Merge one source array into the Title set.
+   *
+   * A correlation value repeated WITHIN one array would silently collapse two
+   * V3 entries into a single Title — the entries are valid V3 (neither array
+   * declares uniqueness) but a title number identifies a title, so this is
+   * malformed data. Failing loudly beats losing an entry.
+   */
+  const mergeSource = (items, rule, sourceName) => {
+    const seen = new Set();
+    items.forEach((item, index) => {
+      const correlationValue = item[correlateBy];
+      if (correlationValue !== undefined) {
+        if (seen.has(correlationValue)) {
+          throw new Error(
+            `v4 decompose: ${sourceName}[${index}] repeats ${correlateBy} "${correlationValue}". ` +
+              `${correlateBy} must be unique within an array — it is what correlates the two Title sources.`
+          );
+        }
+        seen.add(correlationValue);
+      }
+      Object.assign(upsert(correlationValue), selectKeys(item, rule));
+    });
+  };
+
+  // titlesToBeSold order leads; ownership-only titles are appended after.
+  mergeSource(titleItems, titlesRule, "propertyPack.titlesToBeSold");
+  mergeSource(
+    ownershipItems,
+    ownershipsRule,
+    "propertyPack.ownership.ownershipsToBeTransferred"
+  );
+
+  titles.forEach((title, index) => {
+    title.id = ids.title(title, index);
+  });
+
+  // --- Person + participant context ---------------------------------------
+  const participants = v3.participants || [];
+  const persons = [];
+  const personIndexById = new Map();
+  const participantContext = [];
+  // Keyed by roster position, not by person: one human both buying and selling
+  // holds one DID but two participant entries, and each carries its own
+  // relationship.
+  const relationalByIndex = [];
+
+  participants.forEach((participant, index) => {
+    const person = selectKeys(participant, personRule);
+    person.id = ids.person(participant, index);
+
+    // One party, one entry. A DID repeated within a transaction means the same
+    // party listed twice, which is a data error rather than two participations:
+    // a transaction is a single sale, so nobody is both its buyer and its
+    // seller. The same person across a sale and an onward purchase is two
+    // transactions, each with its own credentials, and needs nothing special.
+    if (personIndexById.has(person.id)) {
+      throw new Error(
+        `v4 decompose: participants[${index}] repeats did "${person.id}", already used by participants[${personIndexById.get(person.id)}]. ` +
+          "A party appears once per transaction; the same person in a related transaction belongs to that transaction's participants."
+      );
+    }
+    personIndexById.set(person.id, index);
+    persons.push(person);
+
+    participantContext.push({
+      participant: person.id,
+      ...selectKeys(participant, contextRule),
+    });
+    // Everything relational is kept aside for the credential pass below.
+    relationalByIndex[index] = participant;
+  });
+
+  // --- Transaction ---------------------------------------------------------
+  const transaction = selectKeys(v3, transactionRule);
+  transaction.id = ids.transaction();
+  transaction.property = property.id;
+
+  assignIfPresent(
+    transaction,
+    "titlesToBeSold",
+    titles.map((t) => t.id)
+  );
+  assignIfPresent(transaction, "participants", participantContext);
+
+  const saleContext = selectKeys(propertyPack.ownership, saleContextRule);
+  if (propertyPack.legalOwners !== undefined) {
+    saleContext[legalOwnersRule.entityPointer.split("/").pop()] =
+      propertyPack.legalOwners;
+  }
+  assignIfPresent(transaction, "saleContext", saleContext);
+
+  const entities = {
+    Property: property,
+    Title: titles,
+    Transaction: transaction,
+    Person: persons,
+  };
+
+  // The credentials are part of the round trip: role and every relationship
+  // live on them, so decompose produces them rather than leaving it to a
+  // separate call.
+  return {
+    ...entities,
+    ...projectRelationships(entities, { idFactory, relationalByIndex }),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// recompose
+// ---------------------------------------------------------------------------
+/** Role implied 1:1 by the existence of a credential of this type. */
+const ROLE_IMPLIED_BY_CREDENTIAL = {
+  SellerCapacity: "Seller",
+  Offer: "Buyer",
+  Gift: "Gift Donor",
+};
+
+/**
+ * Rebuild each participant's role and relationship fields from the credentials.
+ *
+ * Role is not stored on the roster: for SellerCapacity, Offer and Gift it is
+ * implied by the credential's existence, and Representation and TransactionRole
+ * carry it as their own discriminator. So revoking a credential removes the
+ * relationship AND the role it asserted, with no second copy left behind.
+ */
+const relationalFromCredentials = ({
+  Representation = [],
+  SellerCapacity = [],
+  Offer = [],
+  Gift = [],
+  TransactionRole = [],
+  roster = [],
+}) => {
+  // Rebuild actingFor with whichever identifier V3 used: did where the party
+  // has one, participantId otherwise.
+  const idOf = new Map(
+    roster
+      .filter((e) => e.did !== undefined || e.participantId !== undefined)
+      .map((e) => [e.participant, e.did ?? e.participantId])
+  );
+
+  const fieldsFor = new Map();
+  const into = (did) => {
+    if (!fieldsFor.has(did)) fieldsFor.set(did, {});
+    return fieldsFor.get(did);
+  };
+
+  for (const c of SellerCapacity) {
+    const to = into(c.seller);
+    to.role = ROLE_IMPLIED_BY_CREDENTIAL.SellerCapacity;
+    if (c.sellersCapacity !== undefined) to.sellersCapacity = c.sellersCapacity;
+    if (c.dateBecameOwnerOrAuthority !== undefined) {
+      to.dateBecameOwnerOrAuthority = c.dateBecameOwnerOrAuthority;
+    }
+  }
+  for (const c of Offer) {
+    const to = into(c.buyer);
+    to.role = ROLE_IMPLIED_BY_CREDENTIAL.Offer;
+    if (c.offerId !== undefined) to.offerId = c.offerId;
+  }
+  for (const c of Gift) {
+    const to = into(c.donor);
+    to.role = ROLE_IMPLIED_BY_CREDENTIAL.Gift;
+    if (c.offerId !== undefined) to.offerId = c.offerId;
+    if (c.giftDetails !== undefined) to.giftDetails = c.giftDetails;
+  }
+  for (const c of TransactionRole) {
+    const to = into(c.participant);
+    if (c.role !== undefined) to.role = c.role;
+  }
+  // Representation is the one that is not exclusive: a conveyancer instructed
+  // by two sellers holds two, merging into one actingFor array.
+  for (const c of Representation) {
+    const to = into(c.representative);
+    if (c.role !== undefined) to.role = c.role;
+    const representedId = idOf.get(c.representedParty);
+    if (representedId !== undefined) {
+      to.actingFor = [...(to.actingFor || []), representedId];
+    }
+  }
+
+  return roster.map((entry) => fieldsFor.get(entry.participant) || {});
+};
+
+const recompose = ({
+  Property,
+  Title,
+  Transaction,
+  Person,
+  Representation,
+  SellerCapacity,
+  Offer,
+  Gift,
+  TransactionRole,
+}) => {
+  const titles = Title || [];
+  const persons = Person || [];
+  const transaction = Transaction || {};
+
+  const propertyRule = getRule("property");
+  const saleContextRule = getRule("transaction.saleContext");
+  const legalOwnersRule = getRule("transaction.saleContext.legalOwners");
+  const titlesRule = getRule("title.titlesToBeSold");
+  const ownershipsRule = getRule("title.ownershipsToBeTransferred");
+  const transactionRule = getRule("transaction");
+
+  const legalOwnersKey = legalOwnersRule.entityPointer.split("/").pop();
+
+  // --- top level -----------------------------------------------------------
+  const v3 = {
+    $schema: mapping.source.v3SchemaId,
+    ...omit(transaction, [
+      "id",
+      "property",
+      "titlesToBeSold",
+      "participants",
+      "saleContext",
+    ]),
+  };
+
+  // --- participants --------------------------------------------------------
+  // Order comes from Transaction.participants, which is authoritative; the
+  // entity documents themselves carry no index.
+  const personById = new Map(persons.map((p) => [p.id, p]));
+  const roster = transaction.participants || [];
+  const relational = relationalFromCredentials({
+    Representation,
+    SellerCapacity,
+    Offer,
+    Gift,
+    TransactionRole,
+    roster,
+  });
+  const participants = roster.map((entry, index) => {
+    const person = personById.get(entry.participant) || {};
+    return {
+      ...omit(person, ["id"]),
+      ...omit(entry, ["participant"]),
+      ...(relational[index] || {}),
+    };
+  });
+  assignIfPresent(v3, "participants", participants);
+
+  // --- propertyPack --------------------------------------------------------
+  const propertyPack = omit(Property || {}, ["id"]);
+
+  // Split each Title back into the two source arrays it was merged from.
+  // A key shared by both sources is written to every array that gets an entry;
+  // a Title carrying *only* shared keys goes to the primarySource array alone.
+  const titlesOwned = titlesRule.keys.values;
+  const ownershipsOwned = ownershipsRule.keys.values;
+
+  const titlesToBeSold = [];
+  const ownershipsToBeTransferred = [];
+
+  // Transaction.titlesToBeSold is the authoritative order for Title entities.
+  const titleById = new Map(titles.map((t) => [t.id, t]));
+  const orderedTitles = (transaction.titlesToBeSold || []).map(
+    (id, index) => titleById.get(id) || titles[index]
+  );
+  const titleList = orderedTitles.length ? orderedTitles.filter(Boolean) : titles;
+
+  for (const title of titleList) {
+    const titlesPart = pick(title, titlesOwned);
+    const ownershipPart = pick(title, ownershipsOwned);
+
+    const hasTitlesOnly = Object.keys(omit(titlesPart, SHARED_TITLE_KEYS)).length > 0;
+    const hasOwnershipOnly =
+      Object.keys(omit(ownershipPart, SHARED_TITLE_KEYS)).length > 0;
+
+    if (hasTitlesOnly || !hasOwnershipOnly) titlesToBeSold.push(titlesPart);
+    if (hasOwnershipOnly) ownershipsToBeTransferred.push(ownershipPart);
+  }
+
+  assignIfPresent(propertyPack, "titlesToBeSold", titlesToBeSold);
+
+  // --- ownership + legalOwners --------------------------------------------
+  const saleContext = transaction.saleContext || {};
+  if (saleContext[legalOwnersKey] !== undefined) {
+    propertyPack[legalOwnersRule.v3Pointer.split("/").pop()] =
+      saleContext[legalOwnersKey];
+  }
+
+  const ownership = selectKeys(omit(saleContext, [legalOwnersKey]), {
+    keys: { mode: "exclude", values: [] },
+  });
+  assignIfPresent(ownership, "ownershipsToBeTransferred", ownershipsToBeTransferred);
+  assignIfPresent(propertyPack, "ownership", ownership);
+
+  assignIfPresent(v3, "propertyPack", propertyPack);
+
+  // Preserve V3 key order for the keys the transaction rule owns.
+  void transactionRule;
+  void propertyRule;
+  void saleContextRule;
+
+  return v3;
+};
+
+// ---------------------------------------------------------------------------
+// Relationship projections
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the relationship credentials — Representation, SellerCapacity, Offer,
+ * Gift and TransactionRole.
+ *
+ * Internal to decompose: the roster deliberately no longer carries the
+ * relational fields, so this cannot be run usefully against already-decomposed
+ * entities. Credentials come out of `decompose` alongside the other entities.
+ *
+ * These are the linking entities that EMBODY a party's role: a Representation
+ * says a conveyancer acts for a seller, a SellerCapacity says a person sells in
+ * a given capacity, an Offer says a person is the buyer. The role is the
+ * relationship, not a label on the participant.
+ *
+ * These add no information: everything they carry round-trips on
+ * Transaction.participants[], so `recompose` neither needs nor accepts them.
+ * They exist because a VC issuer signs, and a holder presents, one relationship
+ * at a time — "Suemme and Profitt act for Peter Hetherington-Smythe in this
+ * transaction" is a statement you want to hand over on its own, without
+ * disclosing the rest of the participant list.
+ *
+ * Cardinality is one entity per (representative, represented party) pair, so a
+ * conveyancer instructed jointly by two sellers yields two Representations, and
+ * two sellers who instruct separate conveyancers yield one each. Shape and
+ * cardinality are declared in `mapping.projections`.
+ */
+const projectRelationships = (
+  { Transaction },
+  { idFactory, relationalByIndex } = {}
+) => {
+  const transaction = Transaction || {};
+  const roster = transaction.participants || [];
+  // When called from decompose, the relational fields come from the V3
+  // participants; when called on already-decomposed entities they are whatever
+  // the roster still carries.
+  const participants = roster.map((entry, index) => ({
+    ...entry,
+    ...(relationalByIndex?.[index] || {}),
+    participant: entry.participant,
+  }));
+  const ids = {
+    ...defaultIdFactory(transaction.transactionId),
+    ...(idFactory || {}),
+  };
+
+  // actingFor names a party by did where one is minted, else by participantId.
+  const byParticipantId = new Map();
+  for (const p of participants) {
+    if (p.participantId !== undefined) byParticipantId.set(p.participantId, p);
+    if (p.did !== undefined) byParticipantId.set(p.did, p);
+  }
+  const Gift = [];
+
+  const Representation = [];
+  const SellerCapacity = [];
+  const Offer = [];
+  const TransactionRole = [];
+  const offers = transaction.offers || {};
+
+  participants.forEach((entry, index) => {
+    for (const actingForId of entry.actingFor || []) {
+      const represented = byParticipantId.get(actingForId);
+      if (!represented) {
+        throw new Error(
+          `v4 projection: participants[${index}] acts for unknown participantId "${actingForId}". ` +
+            "Every actingFor entry must name a participantId present on the transaction."
+        );
+      }
+      Representation.push({
+        id: ids.representation(entry.participant, represented.participant),
+        representative: entry.participant,
+        representedParty: represented.participant,
+        ...(entry.role !== undefined && { role: entry.role }),
+        transaction: transaction.id,
+      });
+    }
+
+    // A seller's role is embodied by this credential, so it is emitted for
+    // every seller — not only those who have declared a capacity yet.
+    if (entry.role === "Seller" || entry.sellersCapacity !== undefined) {
+      SellerCapacity.push({
+        id: ids.sellerCapacity(entry.participant),
+        seller: entry.participant,
+        ...(entry.sellersCapacity !== undefined && {
+          sellersCapacity: entry.sellersCapacity,
+        }),
+        ...(entry.dateBecameOwnerOrAuthority !== undefined && {
+          dateBecameOwnerOrAuthority: entry.dateBecameOwnerOrAuthority,
+        }),
+        transaction: transaction.id,
+      });
+    }
+
+    // Likewise a buyer's role is embodied by their offer. An offer that no
+    // participant references stays transaction data: Offer requires a buyer.
+    if (entry.giftDetails !== undefined || entry.role === "Gift Donor") {
+      Gift.push({
+        id: ids.gift(entry.participant),
+        donor: entry.participant,
+        ...(entry.offerId !== undefined && { offerId: entry.offerId }),
+        ...(entry.giftDetails !== undefined && { giftDetails: entry.giftDetails }),
+        transaction: transaction.id,
+      });
+    } else if (entry.offerId !== undefined) {
+      const { externalIds, ...offerFields } = offers[entry.offerId] || {};
+      Offer.push({
+        id: ids.offer(entry.offerId),
+        offerId: entry.offerId,
+        buyer: entry.participant,
+        ...offerFields,
+        transaction: transaction.id,
+      });
+    }
+  });
+
+  // Anyone left carrying a role that no specific credential embodies gets the
+  // catch-all, so every participant with a role has exactly one credential
+  // asserting it. That covers Lender, Landlord, Tenant, Gift Donor and Platform
+  // Support, which V3 records as a role and nothing more, and also a party
+  // whose specific relationship is not yet established.
+  const hasSpecificCredential = new Set([
+    ...Representation.map((r) => r.representative),
+    ...SellerCapacity.map((c) => c.seller),
+    ...Offer.map((o) => o.buyer),
+    ...Gift.map((g) => g.donor),
+  ]);
+
+  for (const entry of participants) {
+    if (entry.role === undefined) continue;
+    if (hasSpecificCredential.has(entry.participant)) continue;
+    TransactionRole.push({
+      id: ids.transactionRole(entry.participant),
+      participant: entry.participant,
+      role: entry.role,
+      transaction: transaction.id,
+    });
+  }
+
+  return { Representation, SellerCapacity, Offer, Gift, TransactionRole };
+};
+
+// ---------------------------------------------------------------------------
+// Array item identity
+// ---------------------------------------------------------------------------
+
+const ARRAY_KEYS_BY_POINTER = new Map(
+  mapping.arrayKeys.map(({ pointer, keys }) => [pointer, keys])
+);
+
+/**
+ * The candidate keys for items of the array at this V3 pointer, in precedence
+ * order, or [] if it has none. See mapping.arrayKeyScopes for what "canonical"
+ * and "vendor" mean.
+ */
+const arrayKeyFor = (arrayPointer) =>
+  ARRAY_KEYS_BY_POINTER.get(arrayPointer) || [];
+
+const getAtPointer = (root, segments) =>
+  segments.reduce((node, seg) => (node == null ? undefined : node[seg]), root);
+
+/**
+ * Resolve the best available identity for one array item.
+ *
+ * Candidates are tried in precedence order: the canonical key first, because it
+ * lives in the shared payload and any party can resolve it, then the
+ * vendor-scoped externalIds fallback if `source` was supplied. Every V3
+ * identifier is optional, so an item may carry neither.
+ */
+const resolveItemKey = (item, candidates, source) => {
+  for (const candidate of candidates) {
+    const pointer = candidate.pointer.replace("{source}", source ?? "");
+    if (candidate.scope === "vendor") {
+      if (!source) continue;
+      const value = item?.externalIds?.[source];
+      if (value !== undefined) {
+        return { key: pointer, value, scope: candidate.scope };
+      }
+      continue;
+    }
+    const field = candidate.pointer.slice(1);
+    const value = item?.[field];
+    if (value !== undefined) {
+      return { key: pointer, value, scope: candidate.scope };
+    }
+  }
+  return { key: null, value: null, scope: null };
+};
+
+/**
+ * Describe every array index a V3 pointer passes through, so an item can be
+ * addressed by identity instead of by position.
+ *
+ * A pointer like /propertyPack/documents/3/summary is only meaningful against
+ * one producer's ordering of that array — two parties editing it independently
+ * will disagree about index 3. Given the instance, this returns the identity of
+ * the item at each index:
+ *
+ *   identifyV3Pointer("/propertyPack/documents/3/summary", v3)
+ *   // [{ array: "/propertyPack/documents", index: 3,
+ *   //    key: "/documentId", value: "abc", scope: "canonical" }]
+ *
+ * Pass `source` to allow the vendor-scoped fallback for items that carry no
+ * canonical id but do carry an externalIds entry for that source:
+ *
+ *   identifyV3Pointer(pointer, v3, { source: "Moverly" })
+ *   // [{ ..., key: "/externalIds/Moverly", value: "file-1", scope: "vendor" }]
+ *
+ * A `vendor` result is only resolvable by a party that knows that namespace, so
+ * it should not be the identifier in a credential presented to a third party —
+ * check `scope` before relying on it. `key`, `value` and `scope` are all null
+ * where the array has no candidate key, or the item carries none of them.
+ */
+const identifyV3Pointer = (pointer, v3, { source } = {}) => {
+  const segments = pointer.split("/").filter(Boolean);
+  const out = [];
+  const templateParts = [];
+
+  for (let i = 0; i < segments.length; i += 1) {
+    const segment = segments[i];
+    if (!/^\d+$/.test(segment)) {
+      templateParts.push(segment);
+      continue;
+    }
+    const arrayPointer = `/${templateParts.join("/")}`;
+    const item = getAtPointer(v3, segments.slice(0, i + 1));
+    out.push({
+      array: arrayPointer,
+      index: Number(segment),
+      ...resolveItemKey(item, arrayKeyFor(arrayPointer), source),
+    });
+    templateParts.push("{index}");
+  }
+
+  return out;
+};
+
+// ---------------------------------------------------------------------------
+// Claim pointer resolution
+// ---------------------------------------------------------------------------
+const POINTER_SEGMENT = /\{index\}/g;
+
+/**
+ * Resolve a V3 JSON Pointer (as carried by a PDTF 1.x verified claim) to the
+ * V4 entity and pointer that now hold it, by longest-prefix match.
+ *
+ * Returns `{ entity, entityPointer, rule }`, or null if nothing matches.
+ * Where a V3 node is split across entities (participants), the more specific
+ * rule wins: a pointer at the node itself returns every candidate via
+ * `resolveV3PointerAll`.
+ */
+const matchRule = (pointer, rule) => {
+  const template = rule.v3Pointer;
+  if (template === "") return { matched: "", rest: pointer, indices: [] };
+
+  const parts = template.split("/").filter(Boolean);
+  const segs = pointer.split("/").filter(Boolean);
+  if (segs.length < parts.length) return null;
+
+  const indices = [];
+  for (let i = 0; i < parts.length; i += 1) {
+    if (parts[i] === "{index}") {
+      if (!/^\d+$/.test(segs[i])) return null;
+      indices.push(segs[i]);
+    } else if (parts[i] !== segs[i]) {
+      return null;
+    }
+  }
+  return {
+    matched: `/${segs.slice(0, parts.length).join("/")}`,
+    rest: segs.length > parts.length ? `/${segs.slice(parts.length).join("/")}` : "",
+    indices,
+  };
+};
+
+const resolveV3PointerAll = (pointer) => {
+  const results = [];
+  for (const rule of mapping.rules) {
+    const m = matchRule(pointer, rule);
+    if (!m) continue;
+
+    // Respect the rule's key selector for the first segment beyond the match.
+    const nextKey = m.rest.split("/").filter(Boolean)[0];
+    if (nextKey && rule.keys) {
+      const included =
+        rule.keys.mode === "include"
+          ? rule.keys.values.includes(nextKey)
+          : !rule.keys.values.includes(nextKey);
+      if (!included) continue;
+    }
+
+    let entityPointer = rule.entityPointer;
+    let n = 0;
+    entityPointer = entityPointer.replace(POINTER_SEGMENT, () => m.indices[n++]);
+
+    results.push({
+      entity: rule.entity,
+      entityPointer: `${entityPointer}${m.rest}`,
+      rule: rule.id,
+      specificity: rule.v3Pointer.split("/").filter(Boolean).length,
+    });
+  }
+  return results.sort((a, b) => b.specificity - a.specificity);
+};
+
+const resolveV3Pointer = (pointer) => resolveV3PointerAll(pointer)[0] || null;
+
+module.exports = {
+  mapping,
+  decompose,
+  recompose,
+  projectRelationships,
+  arrayKeyFor,
+  identifyV3Pointer,
+  resolveV3Pointer,
+  resolveV3PointerAll,
+};