@pdtf/schemas 3.6.0-dev.3 → 3.6.0-dev.32

package/src/utils/generateV4Schemas.js

@@ -0,0 +1,1561 @@
+#!/usr/bin/env node
+/**
+ * V4 Schema Generator — Dynamic Entity Decomposition
+ *
+ * Reads the canonical V3 combined.json and produces V4 entity schemas
+ * in src/schemas/v4/.  This replaces the old static-divergence approach
+ * (branch 263-*) with a generator that always derives V4 from the latest
+ * V3 state.
+ *
+ * Entity model:
+ *   Property   — physical facts about the property (address, construction, etc.)
+ *   Title      — register extract + flattened tenure/legal-interest details
+ *   Transaction — metadata, milestones, chain, saleContext (residual ownership facts)
+ *   Person     — natural person extracted from participants
+ *   Organisation — legal entity (company, firm, etc.)
+ *
+ * Relationship entities (credential-facing projections, not part of the
+ * reversible V3 mapping):
+ *   Representation  — professional representation (conveyancer↔party)
+ *   SellerCapacity  — legal capacity of a seller against a title (derived from
+ *                     the V3 participants "Seller" oneOf branch)
+ *   Offer           — buyer offer against a transaction
+ *   PropertyTitleLink — standing UPRN↔title relationship (HMLR for registered
+ *                     titles, the seller's conveyancer for unregistered land);
+ *                     the one credential that references no Transaction
+ *
+ * The run also emits src/schemas/v4/mapping.json — the machine-readable V3⇄V4
+ * pointer mapping consumed by src/utils/v4.js.  See
+ * docs/v4-mapping-and-recomposition.md.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const COMBINED_PATH = path.resolve(__dirname, "../schemas/v3/combined.json");
+const V4_DIR = path.resolve(__dirname, "../schemas/v4");
+const PKG_PATH = path.resolve(__dirname, "../../package.json");
+
+const combinedRaw = fs.readFileSync(COMBINED_PATH, "utf8");
+const combined = JSON.parse(combinedRaw);
+const pkg = JSON.parse(fs.readFileSync(PKG_PATH, "utf8"));
+const pp = combined.properties.propertyPack.properties;
+
+// ---------------------------------------------------------------------------
+// Provenance — records exactly which V3 input produced this V4 output, so
+// consumers can pin.
+//
+// The content hash is deliberately the ONLY identifier.  A commit sha would tie
+// generated output to git history: it could never be correct in the same commit
+// that changes combined.json, and it would churn on every rebase or cherry-pick
+// without the schema content differing at all.  To find the commit for a hash,
+// search the history for it.
+// ---------------------------------------------------------------------------
+const combinedSha256 = crypto
+  .createHash("sha256")
+  .update(combinedRaw)
+  .digest("hex");
+
+const SOURCE = {
+  packageName: pkg.name,
+  packageVersion: pkg.version,
+  v3SchemaId: combined.$id,
+  combinedPath: "src/schemas/v3/combined.json",
+  combinedSha256,
+};
+
+// ---------------------------------------------------------------------------
+// Decomposition plan constants
+//
+// These are the single definition of what each entity takes from V3.  Both the
+// schema generators below AND the generated mapping manifest read them, so the
+// manifest cannot drift from the schemas.  `verifyCoverage()` additionally
+// asserts at generation time that every V3 key is accounted for by exactly one
+// rule — adding a field to V3 with no home fails the build rather than silently
+// disappearing from the V4 round trip.
+// ---------------------------------------------------------------------------
+
+/** propertyPack keys that do NOT belong to Property */
+const PROPERTY_EXCLUDE = ["titlesToBeSold", "ownership", "legalOwners"];
+
+/** top-level keys that do NOT belong to Transaction */
+const TRANSACTION_EXCLUDE = ["propertyPack", "participants"];
+
+/**
+ * participants item keys that describe a *relationship*, not the person.
+ * They are transaction-scoped, so they are carried on Transaction.participants[]
+ * rather than on Person — see the "transaction.participants" mapping rule.
+ */
+const PERSON_RELATIONSHIP_FIELDS = [
+  "role",
+  "sellersCapacity",
+  "organisation",
+  "organisationReference",
+  // Identity and representation edges are scoped to this transaction: the same
+  // person may act in a different capacity, or for different parties, in another.
+  "participantId",
+  "actingFor",
+];
+
+/**
+ * Of those, the ones Transaction.participants[] actually keeps.
+ *
+ * did is the party's own identifier and becomes Person.id directly — V4 mints
+ * one only where V3 supplies none. participantId is the transaction-local
+ * fallback that actingFor may reference instead; organisation and
+ * organisationReference say which firm a party is at, which is true of them
+ * whether or not any relationship exists and is not revoked when one ends.
+ * Everything else moved to the credentials, so that revoking a credential
+ * actually removes the relationship it asserts rather than leaving a second
+ * copy behind on the transaction.
+ */
+const PARTICIPANT_ROSTER_FIELDS = [
+  "did",
+  "participantId",
+  "organisation",
+  "organisationReference",
+];
+
+/**
+ * Entities that participate in the derived, reversible V3 mapping.  Everything
+ * else in src/schemas/v4 (Organisation, Representation, SellerCapacity, Offer)
+ * is a credential-facing projection: useful for issuing VCs, but NOT required
+ * to reconstruct a V3 instance, and therefore not part of the round trip.
+ */
+const DERIVED_ENTITIES = ["Property", "Title", "Transaction", "Person"];
+
+/**
+ * Field names that identify an item within its array, in precedence order.
+ *
+ * A V3 JSON Pointer addresses array items by position — /propertyPack/documents/3
+ * — which is only meaningful against one producer's ordering.  Two parties
+ * editing the same array independently will disagree about index 3.  Where an
+ * array's items carry one of these fields, the manifest publishes it so a
+ * consumer can address the item by identity instead.
+ *
+ * This is a list of FIELD NAMES, not paths, so it does not need maintaining as
+ * V3 grows: a new array whose items carry `documentId` is keyed automatically.
+ * Arrays matching none of these are published too, under `unkeyedArrays`, so
+ * nothing is silently position-addressed.
+ *
+ * These are all CANONICAL keys: they live in the shared payload, so any party
+ * holding the transaction can resolve them. See EXTERNAL_IDS_CANDIDATE for the
+ * vendor-scoped fallback.
+ */
+const ARRAY_KEY_FIELDS = [
+  // Added to V3 for exactly this purpose
+  "participantId",
+  "documentId",
+  "searchId",
+  "surveyId",
+  "mediaId",
+  "contractId",
+  "signatureId",
+  // Pre-existing identifiers, usable as-is
+  "titleNumber",
+  "transactionId",
+  "photoId",
+  "certificateId",
+  "valuationId",
+  "lmkKey",
+  "improvementId",
+  "hmlrReference",
+  "partyNumber",
+  "uprn",
+  "refNumber",
+  "reportName",
+  "subCategory",
+  "itemName",
+  "roomName",
+  "dataLabel",
+  "day",
+];
+
+/**
+ * The relationship credentials.
+ *
+ * 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 — so these are what a VC issuer
+ * signs and a holder presents, one relationship at a time.
+ *
+ * They are built FROM the derived entities rather than from V3 directly and add
+ * no information, so `recompose` neither needs nor accepts them. V3's own
+ * `role` field is retained on Transaction.participants[] because it is V3 data
+ * that must round trip — the credentials embody it, they do not replace it.
+ */
+const CREDENTIAL_ENTITIES = [
+  "Representation",
+  "SellerCapacity",
+  "Offer",
+  "Gift",
+  "TransactionRole",
+];
+
+/**
+ * Role is not stored on the participant.  For three credential types it is
+ * implied 1:1 by the type itself — V3 puts sellersCapacity only on the Seller
+ * branch, giftDetails only on Giftor, and offerId on Buyer (and Giftor,
+ * whose offer link lives on the Gift credential instead, keeping this 1:1).
+ * Representation and TransactionRole each span several roles, so they carry
+ * role as their own discriminator: "what kind of representation is this" is a
+ * property of the representation, not a duplicated participant attribute.
+ */
+/**
+ * Standing credentials: assertions that are true independently of any sale, so
+ * they reference no Transaction (D32 as narrowed by D34 in spec 01).
+ *
+ * PropertyTitleLink says "this UPRN is related to this title". For a registered
+ * title HM Land Registry is the only issuer; for unregistered land, which HMLR
+ * holds nothing about, the seller's conveyancer issues it on the strength of the
+ * epitome of title. The two cases never overlap, so there is one issuer per
+ * fact. The seller *selects* from these links via Transaction.titlesToBeSold; a
+ * linked title that is not selected is related but not sold.
+ *
+ * V3 records no such link — it has one propertyPack and the titles being sold,
+ * nothing about which titles HMLR relates to the UPRN — so these are outside the
+ * round trip: decompose does not invent them and recompose does not need them.
+ */
+const STANDING_CREDENTIAL_ENTITIES = ["PropertyTitleLink"];
+
+/** Entities whose identifier is a DID; every other entity is a URN. */
+const DID_ENTITIES = ["Transaction", "Person", "Organisation"];
+
+const ROLE_IMPLIED_BY_CREDENTIAL = {
+  SellerCapacity: "Seller",
+  Offer: "Buyer",
+  Gift: "Giftor",
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const URN_PATTERN =
+  "^urn:[a-z0-9][a-z0-9-]{0,31}:[a-zA-Z0-9._~:/?#\\[\\]@!$&'()*+,;=-]+$";
+/**
+ * W3C DID Core ABNF:
+ *
+ *   did                = "did:" method-name ":" method-specific-id
+ *   method-name        = 1*( %x61-7A / DIGIT )
+ *   method-specific-id = *( *idchar ":" ) 1*idchar
+ *   idchar             = ALPHA / DIGIT / "." / "-" / "_" / pct-encoded
+ *
+ * The method-specific id may therefore contain colons, which matters: a did:web
+ * encodes its path that way, e.g.
+ * did:web:moverly.com:transactions:LnRdGiBUkLbnuNJ89p4CEj, and a port is
+ * percent-encoded as did:web:example.com%3A3000:... . An earlier pattern here
+ * disallowed both and so rejected every did:web carrying a path.
+ */
+const DID_IDCHAR = "(?:[a-zA-Z0-9._-]|%[0-9A-Fa-f]{2})";
+const DID_PATTERN = `^did:[a-z0-9]+:(?:${DID_IDCHAR}*:)*${DID_IDCHAR}+$`;
+
+const urnRef = (title, description) => ({
+  title,
+  description,
+  type: "string",
+  pattern: URN_PATTERN,
+});
+
+const didRef = (title, description) => ({
+  title,
+  description,
+  type: "string",
+  pattern: DID_PATTERN,
+});
+
+/**
+ * All data-bearing properties of a V3 node, including those contributed by its
+ * `oneOf` discriminator branches.
+ *
+ * V3 uses `discriminator` + `oneOf` to attach conditional field groups — e.g.
+ * `leaseholdInformation` only exists on the branch where `ownershipType` is
+ * "Leasehold", and `sellersCapacity` only where `role` is "Seller".  Reading
+ * `node.properties` alone silently drops every one of them, which also breaks
+ * the round trip.  Branch field sets are disjoint in V3, so first-branch-wins is
+ * safe; the discriminator key itself is kept from the base, where its enum is
+ * complete.
+ */
+const mergedProperties = (node) => {
+  const discriminator = node?.discriminator?.propertyName;
+  const out = { ...(node?.properties || {}) };
+  for (const branch of node?.oneOf || []) {
+    for (const [key, subschema] of Object.entries(branch.properties || {})) {
+      if (key === discriminator) continue;
+      if (!(key in out)) out[key] = subschema;
+    }
+  }
+  return out;
+};
+
+/**
+ * Find the participants `oneOf` branch whose discriminator (`role`) admits the
+ * given role, e.g. "Seller".  Used instead of a hard-coded branch index so the
+ * generator survives reordering of the V3 oneOf.
+ */
+const participantBranch = (role) =>
+  (combined.properties.participants.items.oneOf || []).find((b) =>
+    (b.properties?.role?.enum || []).includes(role)
+  );
+
+/** Strip overlay-specific metadata keys (e.g. baspi4Ref, ta6Required) */
+const cleanOverlayMeta = (obj) => {
+  if (Array.isArray(obj)) return obj.map(cleanOverlayMeta);
+  if (obj && typeof obj === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+      if (k.endsWith("Ref") || k.endsWith("Required")) continue;
+      out[k] = cleanOverlayMeta(v);
+    }
+    return out;
+  }
+  return obj;
+};
+
+const makeSchema = (id, title, description, properties, required = []) => ({
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: `https://trust.propdata.org.uk/schemas/v4/entities/${id}.json`,
+  type: "object",
+  title,
+  description,
+  "x-pdtf-source": SOURCE,
+  properties: cleanOverlayMeta(properties),
+  ...(required.length > 0 && { required }),
+});
+
+// ---------------------------------------------------------------------------
+// Property — everything in propertyPack except ownership & titlesToBeSold
+// ---------------------------------------------------------------------------
+const generateProperty = () => {
+  const physicalProps = Object.fromEntries(
+    Object.entries(pp).filter(([k]) => !PROPERTY_EXCLUDE.includes(k))
+  );
+
+  physicalProps.id = urnRef(
+    "Property URN",
+    "Uniform Resource Name identifier for the property"
+  );
+
+  const required = (
+    combined.properties.propertyPack.required || []
+  ).filter((r) => !PROPERTY_EXCLUDE.includes(r));
+
+  return makeSchema(
+    "property",
+    "Property Entity",
+    "Physical and environmental facts about a property — address, construction, fixtures, services, searches, documents. Excludes ownership, titles, and participants.",
+    physicalProps,
+    required
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Title — titlesToBeSold items + flattened tenure from ownershipsToBeTransferred
+// ---------------------------------------------------------------------------
+const generateTitle = () => {
+  const titleItemProps = { ...mergedProperties(pp.titlesToBeSold.items) };
+  const ownershipItems = pp.ownership.properties.ownershipsToBeTransferred?.items;
+
+  // Merge ownership-item fields (tenure type, leasehold details, etc.).  The
+  // tenure detail — leaseholdInformation, managedFreeholdOrCommonholdInformation,
+  // estateRentcharges, wholeFreeholdForSale, otherOwnershipDetails — lives on the
+  // ownershipType oneOf branches, so mergedProperties is required here.
+  Object.assign(titleItemProps, cleanOverlayMeta(mergedProperties(ownershipItems)));
+
+  // `titleNumber` is the one key present on BOTH sources.  It is the same fact
+  // in both and is what correlates the two arrays (their indices need not
+  // align), so it is set explicitly here rather than being decided by merge
+  // order.  See `collisions` in the generated mapping manifest.
+  titleItemProps.titleNumber = {
+    title: "Title Number",
+    description:
+      "HM Land Registry title number. In V3 this appears in both propertyPack.titlesToBeSold and propertyPack.ownership.ownershipsToBeTransferred; it is the key correlating the two.",
+    type: "string",
+  };
+
+  titleItemProps.id = urnRef(
+    "Title URN",
+    "Uniform Resource Name identifier for the title"
+  );
+
+  // First registration (spec 01 §9.1 Q5): the Title issued on registration is
+  // keyed by its new title number and lists the unregistered identifier it
+  // replaces, so links and transactions that name the old URN still resolve.
+  // Not in V3, so never emitted by decompose.
+  titleItemProps.alsoKnownAs = {
+    title: "Also Known As",
+    description:
+      "Earlier identifiers for this title — on first registration, the urn:pdtf:unregisteredTitle:{id} it was known by before a title number was issued.",
+    type: "array",
+    items: { type: "string", pattern: URN_PATTERN },
+    uniqueItems: true,
+  };
+
+  const required = [
+    ...new Set([
+      ...(pp.titlesToBeSold.items.required || []),
+      ...(ownershipItems?.required || []),
+    ]),
+  ];
+
+  return makeSchema(
+    "title",
+    "Title Entity",
+    "HM Land Registry title — register extract, tenure type, and legal interest details for a single title number.",
+    titleItemProps,
+    required
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Transaction — top-level metadata + saleContext (residual ownership facts)
+// ---------------------------------------------------------------------------
+const generateTransaction = () => {
+  const topLevel = Object.fromEntries(
+    Object.entries(combined.properties).filter(
+      ([k]) => k !== "$schema" && !TRANSACTION_EXCLUDE.includes(k)
+    )
+  );
+
+  topLevel.id = didRef(
+    "Transaction DID",
+    "Decentralised Identifier for the transaction"
+  );
+
+  topLevel.property = urnRef(
+    "Property Reference",
+    "URN referencing the Property entity associated with this transaction"
+  );
+
+  topLevel.titlesToBeSold = {
+    title: "Titles to be Sold",
+    description:
+      "Ordered URNs of the Title entities that V3 listed in propertyPack.titlesToBeSold. A title known only from propertyPack.ownership.ownershipsToBeTransferred is a Title entity but is NOT listed here, so recomposition can tell the two apart and rebuild each source array faithfully.",
+    type: "array",
+    minItems: 1,
+    items: urnRef("Title URN", "URN reference to a Title entity"),
+  };
+
+  // V3 `participants` is an ordered array; V4 Person/Organisation entities are
+  // id-keyed and therefore unordered.  This list is where the original array
+  // order lives, mirroring the titlesToBeSold pattern above, so recompose can
+  // rebuild participants[] deterministically without index fields leaking into
+  // the entity documents themselves.
+  topLevel.participants = {
+    title: "Participants",
+    description:
+      "Ordered roster of the parties to this transaction. Each entry references a Person or Organisation entity and carries only its transaction-scoped identity and firm; role and every relationship live on the credentials, so that revoking a credential removes what it asserts. The array order is the V3 participants order and is authoritative for recomposition.",
+    type: "array",
+    items: {
+      type: "object",
+      title: "Transaction Participant",
+      properties: {
+        participant: didRef(
+          "Participant DID",
+          "DID reference to the Person or Organisation entity"
+        ),
+        // Only the roster fields. Role and every relationship field live on the
+        // credentials, so that revoking one removes what it asserts.
+        ...cleanOverlayMeta(
+          Object.fromEntries(
+            Object.entries(mergedProperties(combined.properties.participants.items))
+              .filter(([k]) => PARTICIPANT_ROSTER_FIELDS.includes(k))
+          )
+        ),
+      },
+      required: ["participant"],
+    },
+  };
+
+  // Build saleContext from ownership fields (minus ownershipsToBeTransferred)
+  const ownershipFields = pp.ownership?.properties || {};
+  const saleContextFields = Object.fromEntries(
+    Object.entries(ownershipFields).filter(
+      ([k]) => k !== "ownershipsToBeTransferred"
+    )
+  );
+
+  // propertyPack.legalOwners is excluded from Property but has no entity of its
+  // own: it is an unidentified name list with no link to participants, so it
+  // cannot be correlated to Person/Organisation entities. It is a sale-level
+  // ownership fact of the same family as numberOfSellers / isLimitedCompanySale,
+  // so it is carried here to keep the round trip lossless.
+  if (pp.legalOwners) {
+    saleContextFields.legalOwners = pp.legalOwners;
+  }
+
+  topLevel.saleContext = {
+    title: "Sale Context",
+    description:
+      "Residual ownership/sale facts that apply at the transaction level (e.g. outstanding mortgage, Help to Buy equity loan status).",
+    type: "object",
+    properties: cleanOverlayMeta(saleContextFields),
+  };
+
+  const required = (combined.required || []).filter(
+    (r) => !["propertyPack", "participants"].includes(r)
+  );
+
+  return makeSchema(
+    "transaction",
+    "Transaction Entity",
+    "Transaction-level metadata — status, milestones, chain, contracts, offers, enquiries, and sale context.",
+    topLevel,
+    required
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Person — extracted from participants (minus role/sellersCapacity)
+// ---------------------------------------------------------------------------
+const generatePerson = () => {
+  const participantSchema = combined.properties.participants.items;
+  // NB `sellersCapacity` is not on items.properties at all — it lives on the
+  // "Seller" oneOf branch, so filtering it out here is a no-op; it is carried
+  // on Transaction.participants[] and by the SellerCapacity entity.
+  const personFields = Object.fromEntries(
+    Object.entries(participantSchema.properties).filter(
+      ([k]) => !PERSON_RELATIONSHIP_FIELDS.includes(k)
+    )
+  );
+
+  personFields.id = didRef(
+    "Person DID",
+    "Decentralised Identifier for the person"
+  );
+
+  const required = (participantSchema.required || []).filter(
+    (r) => !PERSON_RELATIONSHIP_FIELDS.includes(r)
+  );
+
+  return makeSchema(
+    "person",
+    "Person Entity",
+    "A natural person participating in a property transaction — name, contact details, address, verification status.",
+    personFields,
+    required
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Organisation — hand-authored but generated here for completeness
+// ---------------------------------------------------------------------------
+const generateOrganisation = () => {
+  const properties = {
+    id: didRef(
+      "Organisation DID",
+      "Decentralised Identifier for the organisation"
+    ),
+    name: {
+      title: "Organisation name",
+      description: "The legal / registered name of the organisation",
+      type: "string",
+      minLength: 1,
+    },
+    tradingName: {
+      title: "Trading name",
+      description:
+        "Trading name, if different from the registered legal name",
+      type: "string",
+    },
+    organisationType: {
+      title: "Organisation type",
+      type: "string",
+      enum: [
+        "Limited Company",
+        "Limited Liability Partnership",
+        "Partnership",
+        "Sole Trader",
+        "Public Limited Company",
+        "Charity",
+        "Public Body",
+        "Trust",
+        "Other",
+      ],
+    },
+    companiesHouseNumber: {
+      title: "Companies House registration number",
+      description:
+        "UK Companies House company registration number (or equivalent)",
+      type: "string",
+    },
+    vatNumber: {
+      title: "VAT registration number",
+      type: "string",
+    },
+    regulatoryIds: {
+      title: "Regulatory identifiers",
+      description:
+        "Identifiers for the professional / regulatory bodies the organisation is registered with",
+      type: "object",
+      properties: {
+        sraNumber: {
+          title: "Solicitors Regulation Authority (SRA) number",
+          type: "string",
+        },
+        clcNumber: {
+          title: "Council for Licensed Conveyancers (CLC) number",
+          type: "string",
+        },
+        ricsNumber: {
+          title: "Royal Institution of Chartered Surveyors (RICS) number",
+          type: "string",
+        },
+        fcaNumber: {
+          title: "Financial Conduct Authority (FCA) reference number",
+          type: "string",
+        },
+        tpoNumber: {
+          title: "The Property Ombudsman (TPO) membership number",
+          type: "string",
+        },
+        icoNumber: {
+          title: "Information Commissioner's Office (ICO) registration number",
+          type: "string",
+        },
+      },
+    },
+    registeredAddress: {
+      title: "Registered address",
+      type: "object",
+      properties: {
+        buildingNumber: { title: "Building number", type: "string" },
+        buildingName: { title: "Building name", type: "string" },
+        subBuilding: { title: "Sub building name", type: "string" },
+        street: { title: "Street", type: "string" },
+        line1: { title: "Address 1", type: "string" },
+        line2: { title: "Address 2", type: "string" },
+        line3: { title: "Address 3", type: "string" },
+        town: { title: "Town", type: "string" },
+        postcode: { title: "Postcode", type: "string" },
+        homeNation: {
+          title: "Home nation",
+          type: "string",
+          enum: ["England", "Wales", "Scotland", "Northern Ireland"],
+        },
+        countryCode: {
+          title: "Country code",
+          description: "ISO 3166-1 alpha-3 country code",
+          type: "string",
+          minLength: 3,
+          maxLength: 3,
+        },
+      },
+    },
+    phone: { title: "Primary phone number", type: "string" },
+    email: { title: "Primary email address", type: "string", format: "email" },
+    website: { title: "Website", type: "string", format: "uri" },
+    externalIds: { type: "object" },
+  };
+
+  return makeSchema(
+    "organisation",
+    "Organisation Entity",
+    "A legal entity (company, firm, partnership) participating in a property transaction.",
+    properties,
+    ["name"]
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Relationship entities — these are hand-authored, not derived from V3
+// ---------------------------------------------------------------------------
+const generateRepresentation = () => {
+  // Derived.  A Representation exists wherever a V3 participant declares
+  // `actingFor`, and its role is that participant's own role carried verbatim —
+  // so the enum cannot drift from V3, and no hand-maintained list of "which
+  // roles count as representation" is needed.
+  const participantProps = combined.properties.participants.items.properties;
+
+  return makeSchema(
+    "representation",
+    "Representation Entity",
+    "A professional representation relationship — one party instructed by another, e.g. a conveyancer acting for a seller. One entity per (representative, represented party) pair: a conveyancer instructed jointly by two sellers yields two, and sellers who instruct separate conveyancers yield one each.",
+    {
+      id: urnRef(
+        "Representation URN",
+        "Uniform Resource Name identifier for the representation"
+      ),
+      representative: didRef(
+        "Representative Reference",
+        "DID referencing the Person or Organisation who is instructed"
+      ),
+      representedParty: didRef(
+        "Represented Party Reference",
+        "DID referencing the Person or Organisation who instructed them"
+      ),
+      role: {
+        ...cleanOverlayMeta(participantProps.role),
+        description:
+          "The kind of representation this is — a property of the representation, not a duplicated participant attribute. The representative's firm is on the transaction roster.",
+      },
+      transaction: didRef(
+        "Transaction Reference",
+        "DID referencing the Transaction entity"
+      ),
+    },
+    ["representative", "representedParty", "role", "transaction"]
+  );
+};
+
+const generateSellerCapacity = () => {
+  // Derived, not hand-authored.  The seller-capacity fields live on the V3
+  // participants "Seller" oneOf branch, which the Person generator does not
+  // read, so they had no home in V4 at all.  Deriving them keeps the enum in
+  // step with V3 `capacity` — the previous hand-authored `capacityType` offered
+  // four values against V3's nine.
+  const sellerBranch = participantBranch("Seller") || { properties: {} };
+  const branchFields = Object.fromEntries(
+    Object.entries(sellerBranch.properties || {}).filter(([k]) => k !== "role")
+  );
+
+  return makeSchema(
+    "sellerCapacity",
+    "Seller Capacity Entity",
+    "The legal capacity in which a seller is selling a given title. Derived from the V3 participants 'Seller' branch (sellersCapacity, dateBecameOwnerOrAuthority).",
+    {
+      id: urnRef(
+        "Seller Capacity URN",
+        "Uniform Resource Name identifier for the seller capacity"
+      ),
+      seller: didRef(
+        "Seller Reference",
+        "DID referencing the Person or Organisation acting as seller"
+      ),
+      title: urnRef(
+        "Title Reference",
+        "URN referencing the Title entity being sold"
+      ),
+      ...branchFields,
+      transaction: didRef(
+        "Transaction Reference",
+        "DID referencing the Transaction entity"
+      ),
+    },
+    ["seller", "transaction"]
+  );
+};
+
+const generateTransactionRole = () => {
+  // The catch-all relationship credential.  Representation, SellerCapacity and
+  // Offer each carry a specific relationship; this one asserts only that a
+  // party takes a given role in a transaction, which is all V3 records for a
+  // Lender, Landlord, Tenant, Giftor or Platform Support. It is also what
+  // covers a party whose specific relationship is not yet established — a
+  // conveyancer instructed but with no actingFor recorded, say — so that every
+  // participant carrying a role has exactly one credential embodying it.
+  const participantProps = combined.properties.participants.items.properties;
+
+  return makeSchema(
+    "transactionRole",
+    "Transaction Role Entity",
+    "A party's role in a transaction, where no more specific relationship credential applies. Asserts participation in a role, not a relationship to another named party.",
+    {
+      id: urnRef(
+        "Transaction Role URN",
+        "Uniform Resource Name identifier for the transaction role"
+      ),
+      participant: didRef(
+        "Participant Reference",
+        "DID referencing the Person or Organisation holding the role"
+      ),
+      role: cleanOverlayMeta(participantProps.role),
+      transaction: didRef(
+        "Transaction Reference",
+        "DID referencing the Transaction entity"
+      ),
+    },
+    ["participant", "role", "transaction"]
+  );
+};
+
+const generateGift = () => {
+  // A gift is a linking relationship with legal consequence: whether the money
+  // is truly a gift rather than a loan, and whether the donor acquires an
+  // interest in or occupation of the property, are what a conveyancer must
+  // resolve before reporting to a lender. Separately revocable, and the role
+  // "Giftor" is implied by the credential's existence.
+  const giftBranch =
+    (combined.properties.participants.items.oneOf || []).find(
+      (b) => b.properties?.giftDetails
+    ) || { properties: {} };
+
+  return makeSchema(
+    "gift",
+    "Gift Entity",
+    "A gift of funds towards a purchase, made by a giftor. Implies the Giftor role.",
+    {
+      id: urnRef("Gift URN", "Uniform Resource Name identifier for the gift"),
+      donor: didRef(
+        "Donor Reference",
+        "DID referencing the Person or Organisation making the gift"
+      ),
+      offerId: {
+        ...cleanOverlayMeta(giftBranch.properties.offerId || { type: "string" }),
+        title: "Offer id",
+        description:
+          "The offer this gift is contributing towards, as keyed in Transaction.offers. Held here rather than on Offer so that an Offer credential always implies the Buyer role.",
+      },
+      giftDetails: cleanOverlayMeta(giftBranch.properties.giftDetails || { type: "object" }),
+      transaction: didRef(
+        "Transaction Reference",
+        "DID referencing the Transaction entity"
+      ),
+    },
+    ["donor", "transaction"]
+  );
+};
+
+const generateOffer = () => {
+  // Pull offer fields from V3 offers patternProperties where available
+  const v3OfferSchema =
+    combined.properties.offers?.patternProperties?.[".*"] ||
+    combined.properties.offers?.patternProperties?.[
+      Object.keys(combined.properties.offers?.patternProperties || {})[0]
+    ];
+
+  // The V3 offers object is keyed by an offer id, and participants on the
+  // "Buyer" branch reference it via `offerId`. Carrying that key here is what
+  // keeps the participant-to-offer link reconstructible.
+  const buyerBranch = participantBranch("Buyer");
+
+  const offerProps = {
+    id: urnRef("Offer URN", "Uniform Resource Name identifier for the offer"),
+    offerId: {
+      ...cleanOverlayMeta(buyerBranch?.properties?.offerId || { type: "string" }),
+      title: "Offer id",
+      description:
+        "The V3 offers object key for this offer, as referenced by participants[].offerId",
+    },
+    buyer: didRef(
+      "Buyer Reference",
+      "DID referencing the Person or Organisation making the offer"
+    ),
+    transaction: didRef(
+      "Transaction Reference",
+      "DID referencing the Transaction entity"
+    ),
+  };
+
+  // Merge fields from V3 offer schema if present
+  if (v3OfferSchema?.properties) {
+    const { externalIds, ...offerFields } = cleanOverlayMeta(
+      v3OfferSchema.properties
+    );
+    Object.assign(offerProps, offerFields);
+  } else {
+    // Fallback minimal fields
+    offerProps.amount = {
+      title: "Offer Amount",
+      description: "The monetary amount of the offer",
+      type: "number",
+      minimum: 0,
+    };
+    offerProps.status = {
+      title: "Offer Status",
+      description: "Current status of the offer",
+      type: "string",
+      enum: ["Pending", "Accepted", "Rejected", "Withdrawn"],
+    };
+  }
+
+  return makeSchema(
+    "offer",
+    "Offer Entity",
+    "An offer made by a prospective buyer in a property transaction.",
+    offerProps,
+    // V3 requires nothing of an offer, so requiring amount and status here
+    // would make a valid V3 instance produce an invalid Offer credential.
+    // Only the references the credential cannot exist without are required.
+    ["buyer", "transaction"]
+  );
+};
+
+const generatePropertyTitleLink = () => {
+  // Hand-authored: V3 has nothing to derive it from.  The first relationship
+  // credential with no `transaction` — it is standing, true of the UPRN and
+  // the title whether or not either is being sold (spec 01 D34).
+  //
+  // `basis` is part of what is asserted, not just how the issuer came by it:
+  // HMLR's UPRN-to-title data is neither complete nor wholly accurate, so a
+  // link is only ever "related as at this date, according to this source".
+  // How the issuer obtained it goes in the credential's own `evidence`
+  // (spec 02 §6) as usual.
+  const REGISTER = "Register Dataset";
+  const EPITOME = "Epitome of Title";
+  const dateField = (title, description) => ({
+    title,
+    description,
+    type: "string",
+    format: "date",
+  });
+
+  const schema = makeSchema(
+    "propertyTitleLink",
+    "Property–Title Link Entity",
+    "A standing assertion that a property (UPRN) is related to a title. Many-to-many: one UPRN can sit on several titles, and one title (a block freehold, say) can cover many UPRNs. Issued by HM Land Registry for a registered title, and by the seller's conveyancer, on the epitome of title, for unregistered land. References no Transaction: a Transaction selects the titles being sold from the linked titles through titlesToBeSold, and a linked title it does not select is related but not sold.",
+    {
+      id: urnRef(
+        "Property–Title Link URN",
+        "Uniform Resource Name identifier for the link, urn:pdtf:propertyTitleLink:{id}"
+      ),
+      property: urnRef(
+        "Property Reference",
+        "URN referencing the Property entity, urn:pdtf:uprn:{uprn}"
+      ),
+      title: urnRef(
+        "Title Reference",
+        "URN referencing the Title entity: urn:pdtf:titleNumber:{number} for a registered title, urn:pdtf:unregisteredTitle:{id} for unregistered land"
+      ),
+      basis: {
+        title: "Basis of the link",
+        description:
+          "What the link rests on, and the date it speaks as at. A registered title is linked on the register's own UPRN-to-title data; unregistered land on the epitome of title.",
+        type: "object",
+        properties: {
+          type: {
+            title: "Basis type",
+            type: "string",
+            enum: [REGISTER, EPITOME],
+          },
+          asOf: dateField(
+            "As at",
+            "The date the link speaks as at: the dataset's effective date, or the date the epitome was examined"
+          ),
+        },
+        required: ["type", "asOf"],
+        discriminator: { propertyName: "type" },
+        oneOf: [
+          {
+            properties: {
+              type: { type: "string", enum: [REGISTER] },
+              dataset: {
+                title: "Dataset",
+                description:
+                  "The register dataset the link is taken from, e.g. \"HMLR Title Number and UPRN Look Up\"",
+                type: "string",
+              },
+              datasetRelease: {
+                title: "Dataset release",
+                description:
+                  "The release the link is taken from, e.g. the full-file name of HMLR's monthly release (\"LR_UPRN_FULL_APR.csv\"). The dataset records no date per row, so asOf is the release date.",
+                type: "string",
+              },
+            },
+            required: ["dataset"],
+          },
+          {
+            properties: {
+              type: { type: "string", enum: [EPITOME] },
+              rootOfTitle: {
+                title: "Root of title",
+                description:
+                  "The good root of title the epitome starts from",
+                type: "object",
+                properties: {
+                  description: {
+                    title: "Description",
+                    description: "e.g. \"Conveyance on sale\"",
+                    type: "string",
+                  },
+                  date: dateField("Date", "Date of the root document"),
+                },
+              },
+              epitomeDigest: {
+                title: "Epitome digest",
+                description:
+                  "SHA-256 digest of the epitome of title as examined, in the form sha256:{hex} (spec 02 §6.6)",
+                type: "string",
+                pattern: "^sha256:[0-9a-f]{64}$",
+              },
+            },
+            required: ["rootOfTitle"],
+          },
+        ],
+      },
+    },
+    ["property", "title", "basis"]
+  );
+
+  // One issuer per fact, decided by registration status: a registered title is
+  // linked on the register, unregistered land on the epitome. The schema
+  // enforces the basis; the issuer (HMLR, or a conveyancer) is checked through
+  // the trust framework, since a credential subject cannot name its own signer.
+  schema.allOf = [
+    {
+      if: {
+        properties: { title: { type: "string", pattern: "^urn:pdtf:titleNumber:" } },
+        required: ["title"],
+      },
+      then: {
+        properties: {
+          basis: {
+            type: "object",
+            properties: { type: { type: "string", const: REGISTER } },
+          },
+        },
+      },
+    },
+    {
+      if: {
+        properties: { title: { type: "string", pattern: "^urn:pdtf:unregisteredTitle:" } },
+        required: ["title"],
+      },
+      then: {
+        properties: {
+          basis: {
+            type: "object",
+            properties: { type: { type: "string", const: EPITOME } },
+          },
+        },
+      },
+    },
+  ];
+  return schema;
+};
+
+// ---------------------------------------------------------------------------
+// Main — generate all schemas and write to src/schemas/v4/
+// ---------------------------------------------------------------------------
+const generators = {
+  Property: generateProperty,
+  Title: generateTitle,
+  Transaction: generateTransaction,
+  Person: generatePerson,
+  Organisation: generateOrganisation,
+  Representation: generateRepresentation,
+  TransactionRole: generateTransactionRole,
+  Gift: generateGift,
+  SellerCapacity: generateSellerCapacity,
+  Offer: generateOffer,
+  PropertyTitleLink: generatePropertyTitleLink,
+};
+
+if (!fs.existsSync(V4_DIR)) {
+  fs.mkdirSync(V4_DIR, { recursive: true });
+}
+
+const schemas = {};
+for (const [name, generate] of Object.entries(generators)) {
+  schemas[name] = generate();
+}
+
+// ---------------------------------------------------------------------------
+// Mapping manifest
+//
+// Emitted from the same run, from the same constants the generators used, so
+// it cannot drift from the schemas.  Rules are *prefix rewrites*: a V3 JSON
+// Pointer (as used by PDTF 1.x verified claims) is resolved by longest-prefix
+// match against `v3Pointer`, giving the target entity and the pointer within
+// it.  This covers pointers far deeper than anything enumerated here, which is
+// what claims actually carry.
+// ---------------------------------------------------------------------------
+
+const participantItems = combined.properties.participants.items;
+const participantBranchKeys = Object.keys(
+  mergedProperties(participantItems)
+).filter((k) => !(k in participantItems.properties));
+const participantContextKeys = [
+  ...PERSON_RELATIONSHIP_FIELDS,
+  ...participantBranchKeys.filter((k) => !PERSON_RELATIONSHIP_FIELDS.includes(k)),
+];
+const personKeys = Object.keys(participantItems.properties).filter(
+  (k) => !PERSON_RELATIONSHIP_FIELDS.includes(k)
+);
+
+const titlesKeys = Object.keys(mergedProperties(pp.titlesToBeSold.items));
+const ownershipItemKeys = Object.keys(
+  mergedProperties(pp.ownership.properties.ownershipsToBeTransferred?.items)
+);
+const titleCollisionKeys = titlesKeys.filter((k) =>
+  ownershipItemKeys.includes(k)
+);
+
+/**
+ * Vendor-scoped fallback, offered for any array whose items carry `externalIds`.
+ *
+ * `externalIds` answers "which of MY records is this?", not "which item are we
+ * both talking about?" — it is a per-source back-reference, so it is only
+ * resolvable by a party who knows that source's namespace, and an item written
+ * by someone else carries no entry for it at all. That makes it a usable last
+ * resort when the canonical key is absent (every V3 identifier is optional) but
+ * a poor primary key, which is why it always ranks below the canonical one and
+ * is labelled `vendor` so a consumer cannot mistake its scope.
+ *
+ * `{source}` is a placeholder the consumer fills with its own namespace.
+ */
+const EXTERNAL_IDS_CANDIDATE = {
+  pointer: "/externalIds/{source}",
+  scope: "vendor",
+};
+
+/**
+ * Walk V3 for every array of objects, pairing it with the candidate keys that
+ * identify its items, in precedence order.  Derived from the schema, so it
+ * cannot drift.
+ */
+const buildArrayKeys = () => {
+  const keyed = [];
+  const unkeyed = [];
+  const seen = new Set();
+
+  const walk = (node, pointer, depth) => {
+    if (!node || typeof node !== "object" || depth > 16) return;
+    if (seen.has(pointer)) return;
+    seen.add(pointer);
+
+    if (node.patternProperties) {
+      // Already addressed by key in V3 — offers, enquiries, externalIds.
+      for (const child of Object.values(node.patternProperties)) {
+        walk(child, `${pointer}/{key}`, depth + 1);
+      }
+      return;
+    }
+
+    if (node.type === "array" || node.items) {
+      const items = node.items || {};
+      const itemProps = mergedProperties(items);
+      const names = Object.keys(itemProps);
+      if (names.length > 0) {
+        const candidates = [];
+        const canonical = ARRAY_KEY_FIELDS.find((f) => names.includes(f));
+        if (canonical) {
+          candidates.push({ pointer: `/${canonical}`, scope: "canonical" });
+        }
+        if (names.includes("externalIds")) {
+          candidates.push(EXTERNAL_IDS_CANDIDATE);
+        }
+        if (candidates.length) keyed.push({ pointer, keys: candidates });
+        else unkeyed.push(pointer);
+      }
+      walk(items, `${pointer}/{index}`, depth + 1);
+      return;
+    }
+
+    for (const [name, child] of Object.entries(mergedProperties(node))) {
+      walk(child, `${pointer}/${name}`, depth + 1);
+    }
+  };
+
+  walk(combined, "", 0);
+  return { keyed, unkeyed };
+};
+
+const buildRules = () => [
+  // --- Title: merged from two V3 arrays -----------------------------------
+  {
+    id: "title.titlesToBeSold",
+    v3Pointer: "/propertyPack/titlesToBeSold/{index}",
+    entity: "Title",
+    entityPointer: "",
+    keys: { mode: "include", values: titlesKeys },
+    extensions: "passthrough",
+    instance: {
+      cardinality: "many",
+      orderedBy: { entity: "Transaction", pointer: "/titlesToBeSold" },
+      correlateBy: "titleNumber",
+      primarySource: true,
+    },
+    notes:
+      "Primary source: it takes any key the V3 schema does not define, and recomposition emits one entry per id in Transaction.titlesToBeSold.",
+  },
+  {
+    id: "title.ownershipsToBeTransferred",
+    v3Pointer: "/propertyPack/ownership/ownershipsToBeTransferred/{index}",
+    entity: "Title",
+    entityPointer: "",
+    keys: { mode: "include", values: ownershipItemKeys },
+    extensions: "drop",
+    instance: {
+      cardinality: "many",
+      orderedBy: { entity: "Transaction", pointer: "/titlesToBeSold" },
+      correlateBy: "titleNumber",
+      primarySource: false,
+    },
+    notes:
+      "Indices of the two source arrays are NOT assumed to correspond; they are correlated by titleNumber value.",
+  },
+
+  // --- Transaction: residual ownership + legal owners ----------------------
+  {
+    id: "transaction.saleContext.legalOwners",
+    v3Pointer: "/propertyPack/legalOwners",
+    entity: "Transaction",
+    entityPointer: "/saleContext/legalOwners",
+    instance: { cardinality: "single" },
+  },
+  {
+    id: "transaction.saleContext",
+    v3Pointer: "/propertyPack/ownership",
+    entity: "Transaction",
+    entityPointer: "/saleContext",
+    keys: { mode: "exclude", values: ["ownershipsToBeTransferred"] },
+    extensions: "passthrough",
+    instance: { cardinality: "single" },
+  },
+
+  // --- Property: everything else in propertyPack ---------------------------
+  {
+    id: "property",
+    v3Pointer: "/propertyPack",
+    entity: "Property",
+    entityPointer: "",
+    keys: { mode: "exclude", values: PROPERTY_EXCLUDE },
+    extensions: "passthrough",
+    instance: { cardinality: "single" },
+  },
+
+  // --- Participants: split person facts from relationship facts ------------
+  {
+    id: "transaction.participants",
+    v3Pointer: "/participants/{index}",
+    entity: "Transaction",
+    entityPointer: "/participants/{index}",
+    keys: { mode: "include", values: PARTICIPANT_ROSTER_FIELDS },
+    extensions: "drop",
+    instance: {
+      cardinality: "many",
+      orderedBy: { entity: "Transaction", pointer: "/participants" },
+    },
+    notes:
+      "The roster only: transaction-scoped identity and firm. The entity reference itself is at /participants/{index}/participant.",
+  },
+
+  // --- Participant relationship fields: each lives on its credential --------
+  // These rules are data-dependent: which credential holds a participant's
+  // role depends on the relationships that exist for them. resolveV3Pointer
+  // returns the candidates; pass the decomposed entities to narrow it.
+  {
+    id: "credential.sellerCapacity",
+    extensions: "drop",
+    v3Pointer: "/participants/{index}",
+    entity: "SellerCapacity",
+    entityPointer: "",
+    keys: { mode: "include", values: ["sellersCapacity", "dateBecameOwnerOrAuthority"] },
+    instance: { cardinality: "many", matchOn: "/seller" },
+    impliesRole: "Seller",
+  },
+  {
+    id: "credential.offer",
+    extensions: "drop",
+    v3Pointer: "/participants/{index}",
+    entity: "Offer",
+    entityPointer: "",
+    keys: { mode: "include", values: ["offerId"] },
+    instance: { cardinality: "many", matchOn: "/buyer" },
+    impliesRole: "Buyer",
+  },
+  {
+    id: "credential.gift",
+    extensions: "drop",
+    v3Pointer: "/participants/{index}",
+    entity: "Gift",
+    entityPointer: "",
+    keys: { mode: "include", values: ["giftDetails", "offerId"] },
+    instance: { cardinality: "many", matchOn: "/donor" },
+    impliesRole: "Giftor",
+  },
+  {
+    id: "credential.representation",
+    extensions: "drop",
+    v3Pointer: "/participants/{index}",
+    entity: "Representation",
+    entityPointer: "",
+    keys: { mode: "include", values: ["role", "actingFor"] },
+    fieldMap: { role: "/role", actingFor: "/representedParty" },
+    instance: { cardinality: "many", matchOn: "/representative" },
+    notes:
+      "actingFor becomes one Representation per represented party; its role is the credential's own discriminator.",
+  },
+  {
+    id: "credential.transactionRole",
+    extensions: "drop",
+    v3Pointer: "/participants/{index}",
+    entity: "TransactionRole",
+    entityPointer: "",
+    keys: { mode: "include", values: ["role"] },
+    instance: { cardinality: "many", matchOn: "/participant" },
+    notes:
+      "Carries role for the roles no specific credential covers, and for a party whose specific relationship is not yet established.",
+  },
+  {
+    id: "person",
+    v3Pointer: "/participants/{index}",
+    entity: "Person",
+    entityPointer: "",
+    keys: { mode: "include", values: personKeys },
+    extensions: "passthrough",
+    instance: {
+      cardinality: "many",
+      orderedBy: {
+        entity: "Transaction",
+        pointer: "/participants",
+        idField: "participant",
+      },
+    },
+  },
+
+  // --- Transaction: all remaining top-level V3 properties ------------------
+  {
+    id: "transaction",
+    v3Pointer: "",
+    entity: "Transaction",
+    entityPointer: "",
+    keys: { mode: "exclude", values: [...TRANSACTION_EXCLUDE, "$schema"] },
+    extensions: "passthrough",
+    instance: { cardinality: "single" },
+  },
+];
+
+/**
+ * Generation-time drift guard.  Every V3 key that can hold data must be claimed
+ * by at least one rule, and every key a rule claims must exist in the target
+ * entity schema.  A new V3 field with no home fails generation rather than
+ * silently disappearing from the round trip.
+ */
+const verifyCoverage = (rules) => {
+  const errors = [];
+
+  const claimedAt = (pointer) =>
+    rules.filter((r) => r.v3Pointer === pointer);
+
+  const claims = (rulesAtPointer, key) =>
+    rulesAtPointer.some(({ keys }) => {
+      if (!keys) return true;
+      return keys.mode === "include"
+        ? keys.values.includes(key)
+        : !keys.values.includes(key);
+    });
+
+  // A key is covered either by a rule at this node that admits it, or by a
+  // more specific rule rooted at the key itself (e.g. /propertyPack/ownership
+  // is covered by the rules that split it, not by the propertyPack rule).
+  const checkNode = (pointer, sourceKeys, label) => {
+    const rulesHere = claimedAt(pointer);
+    for (const key of sourceKeys) {
+      const childPrefix = `${pointer}/${key}`;
+      const coveredByChild = rules.some(
+        (r) => r.v3Pointer === childPrefix || r.v3Pointer.startsWith(`${childPrefix}/`)
+      );
+      if (!coveredByChild && !claims(rulesHere, key)) {
+        errors.push(`${label}: V3 key "${key}" is not claimed by any mapping rule`);
+      }
+    }
+  };
+
+  checkNode("", Object.keys(combined.properties).filter((k) => k !== "$schema"), "top level");
+  checkNode("/propertyPack", Object.keys(pp), "propertyPack");
+  checkNode("/participants/{index}", [...Object.keys(participantItems.properties), ...participantBranchKeys], "participants item");
+  checkNode("/propertyPack/titlesToBeSold/{index}", titlesKeys, "titlesToBeSold item");
+  checkNode("/propertyPack/ownership/ownershipsToBeTransferred/{index}", ownershipItemKeys, "ownershipsToBeTransferred item");
+  checkNode("/propertyPack/ownership", Object.keys(pp.ownership.properties), "ownership");
+
+  // Every included key must actually be present in the target entity schema.
+  const resolve = (schema, pointer) =>
+    pointer
+      .split("/")
+      .filter(Boolean)
+      .reduce(
+        (node, seg) =>
+          seg === "{index}" ? node?.items : node?.properties?.[seg],
+        schema
+      );
+
+  for (const rule of rules) {
+    if (rule.keys?.mode !== "include") continue;
+    const target = resolve(schemas[rule.entity], rule.entityPointer);
+    for (const key of rule.keys.values) {
+      // A rule may map a V3 key to a differently named target field, e.g.
+      // actingFor becomes Representation.representedParty.
+      const mapped = rule.fieldMap?.[key];
+      const field = mapped ? mapped.slice(1) : key;
+      if (!target?.properties?.[field]) {
+        errors.push(
+          `rule "${rule.id}": ${key}${mapped ? ` (as ${mapped})` : ""} is missing from ${rule.entity}${rule.entityPointer || " (root)"}`
+        );
+      }
+    }
+  }
+
+  if (errors.length) {
+    console.error("\n✗ V4 mapping coverage check failed:\n");
+    errors.forEach((e) => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+};
+
+const arrayKeys = buildArrayKeys();
+const rules = buildRules();
+verifyCoverage(rules);
+
+const mapping = {
+  mappingVersion: 1,
+  $id: "https://trust.propdata.org.uk/schemas/v4/mapping.json",
+  description:
+    "Generated mapping between PDTF V3 JSON Pointers and V4 entity documents. Do not edit by hand — regenerate with `npm run generate:v4`.",
+  generator: "src/utils/generateV4Schemas.js",
+  source: SOURCE,
+  entities: Object.fromEntries(
+    Object.entries(schemas).map(([name, schema]) => [
+      name,
+      {
+        $id: schema.$id,
+        kind: DERIVED_ENTITIES.includes(name)
+          ? "derived"
+          : CREDENTIAL_ENTITIES.includes(name) ||
+            STANDING_CREDENTIAL_ENTITIES.includes(name)
+          ? "credential"
+          : "standalone",
+        // Relationship credentials are either scoped to one Transaction (and
+        // carry `transaction`) or standing (and carry none) — D32 / D34.
+        ...(CREDENTIAL_ENTITIES.includes(name) && { scope: "transaction" }),
+        ...(STANDING_CREDENTIAL_ENTITIES.includes(name) && { scope: "standing" }),
+        idScheme: DID_ENTITIES.includes(name) ? "did" : "urn",
+      },
+    ])
+  ),
+  roundTrip: {
+    entities: [...DERIVED_ENTITIES, ...CREDENTIAL_ENTITIES],
+    note:
+      "All of these are required to reconstruct a V3 instance. The credentials are not redundant copies: role and every relationship live only on them, so that revoking a credential removes what it asserts rather than leaving a second copy on the transaction. Organisation and PropertyTitleLink are outside the round trip: V3 records a participant's firm only as free text, and records no UPRN-to-title link at all, so decompose does not invent either and recompose does not need them.",
+    roleImpliedByCredential: ROLE_IMPLIED_BY_CREDENTIAL,
+    strippedKeySuffixes: ["Ref", "Required"],
+    knownExceptions: [
+      "Overlay metadata keys (*Ref, *Required) are schema-level only and are stripped from V4; they never appear in instance data.",
+      "A Title carrying only keys shared by both source arrays recomposes into propertyPack.titlesToBeSold only (primarySource), not into ownershipsToBeTransferred.",
+      "propertyPack.ownership.ownershipsToBeTransferred is canonicalised on recomposition: entries are emitted in propertyPack.titlesToBeSold order rather than their original order. The array is correlated by titleNumber and its order carries no meaning in V3, so this is a deliberate normalisation — it removes the index-divergence class of bug rather than reproducing it. Entry CONTENT is preserved exactly.",
+      "An explicitly empty container recomposes as absent: propertyPack {}, propertyPack.ownership {} and propertyPack.titlesToBeSold [] are all valid V3 but carry no data, and the entity model has no place to record 'present but empty'. (participants [] is invalid V3 — minItems 1 — so it does not arise.)",
+      "recompose always emits $schema, set to source.v3SchemaId. An instance that omitted it gains one; this is a normalisation, since a V3 instance is expected to declare its schema.",
+      "The round trip restores deep equality, NOT byte equality: object key order is not preserved, because keys are regrouped by entity and reassembled. JSON attaches no meaning to key order, but do not compare a recomposed instance to the original by hashing or string equality — compare structurally, or canonicalise first (e.g. JCS) if you need a stable digest.",
+    ],
+  },
+  extensionPolicy: {
+    description:
+      "What each rule does with instance keys the V3 schema does not define — platform extensions such as an externalIds namespace or a vendor's own block. `passthrough` carries them into the entity and back out again on recomposition; `drop` discards them. Exactly one rule per V3 node is the sink, so an unknown key has a single, predictable home. verifyCoverage() guarantees every V3 SCHEMA key has a V4 home; this is the answer for everything outside the schema.",
+    values: ["passthrough", "drop"],
+  },
+  arrayKeys: arrayKeys.keyed,
+  arrayKeyScopes: {
+    canonical:
+      "Lives in the shared payload, so any party holding the transaction can resolve it. This is what claims and credentials should address.",
+    vendor:
+      "A per-source back-reference under externalIds. Resolvable only by a party that knows that source's namespace, and absent entirely on items that source did not write. Use as a fallback, never as the identifier in a credential presented to a third party.",
+  },
+  unkeyedArrays: {
+    description:
+      "Arrays of objects with no candidate key at all — neither a canonical identifier nor externalIds — so their items can only be addressed by position. Listed so the gap is visible rather than silent. Most are single-source provider payloads replaced wholesale, where position is stable in practice.",
+    pointers: arrayKeys.unkeyed,
+  },
+  projections: {
+    Representation: {
+      description:
+        "A professional representation relationship. Emitted once per (representative, represented party) pair, so a conveyancer instructed jointly by two sellers yields two, and sellers who instruct separate conveyancers yield one each.",
+      source: { entity: "Transaction", pointer: "/participants/{index}" },
+      emitWhen: "/actingFor is present and non-empty",
+      fanOut: "/actingFor",
+      resolveBy: "participantId",
+      fields: {
+        representative: "/participants/{index}/participant",
+        representedParty:
+          "/participants/{index}/actingFor/{n} resolved against /participants/*/participantId",
+        role: "/participants/{index}/role",
+        organisation: "/participants/{index}/organisation",
+        organisationReference: "/participants/{index}/organisationReference",
+        transaction: "/id",
+      },
+    },
+    SellerCapacity: {
+      description:
+        "The capacity in which a seller sells — the relationship that embodies the Seller role. Emitted once per participant whose role is Seller, whether or not a capacity has been declared yet.",
+      source: { entity: "Transaction", pointer: "/participants/{index}" },
+      emitWhen: "/role is \"Seller\", or /sellersCapacity is present",
+      fields: {
+        seller: "/participants/{index}/participant",
+        sellersCapacity: "/participants/{index}/sellersCapacity",
+        dateBecameOwnerOrAuthority:
+          "/participants/{index}/dateBecameOwnerOrAuthority",
+        transaction: "/id",
+      },
+      notes:
+        "V3 does not tie a seller's capacity to a particular title, so the optional `title` reference is left unset. A transaction selling more than one title therefore yields a capacity scoped to the transaction, not to a title.",
+    },
+    TransactionRole: {
+      description:
+        "A party's role where no more specific relationship credential applies — Lender, Landlord, Tenant, Giftor, Platform Support — or where the specific relationship is not yet established. Emitted so that every participant carrying a role has exactly one credential embodying it.",
+      source: { entity: "Transaction", pointer: "/participants/{index}" },
+      emitWhen:
+        "/role is present and no other credential names this participant as its role-bearer",
+      fields: {
+        participant: "/participants/{index}/participant",
+        role: "/participants/{index}/role",
+        organisation: "/participants/{index}/organisation",
+        organisationReference: "/participants/{index}/organisationReference",
+        transaction: "/id",
+      },
+    },
+    Offer: {
+      description:
+        "An offer made by a prospective buyer — the relationship that embodies the Buyer role. Emitted once per participant carrying an offerId, merged with that offer's data from Transaction.offers.",
+      source: { entity: "Transaction", pointer: "/participants/{index}" },
+      emitWhen: "/offerId is present",
+      fields: {
+        offerId: "/participants/{index}/offerId",
+        buyer: "/participants/{index}/participant",
+        "…": "the remaining fields from /offers/{offerId}",
+        transaction: "/id",
+      },
+      notes:
+        "An offer in Transaction.offers that no participant references stays transaction data and yields no credential, since Offer requires a buyer.",
+    },
+  },
+  standingCredentials: {
+    PropertyTitleLink: {
+      description:
+        "A standing UPRN-to-title link. Not projected from V3. A Transaction's titlesToBeSold selects the titles being sold from the titles linked to its property; see linkedTitles() in src/utils/v4.js.",
+      issuerByTitleScheme: {
+        "urn:pdtf:titleNumber:": {
+          issuer: "HM Land Registry",
+          basis: "Register Dataset",
+        },
+        "urn:pdtf:unregisteredTitle:": {
+          issuer: "Seller's conveyancer",
+          basis: "Epitome of Title",
+        },
+      },
+      supersession:
+        "On first registration the Title for the new title number lists the unregistered URN in alsoKnownAs. An HMLR link from the same UPRN to that title supersedes the conveyancer's link to the unregistered URN; the conveyancer's link stays in force until one exists.",
+    },
+  },
+  collisions: titleCollisionKeys.map((key) => ({
+    key,
+    entity: "Title",
+    sources: [
+      `/propertyPack/titlesToBeSold/{index}/${key}`,
+      `/propertyPack/ownership/ownershipsToBeTransferred/{index}/${key}`,
+    ],
+    rule: "same-fact",
+    resolution:
+      "Identical fact in both sources and the key that correlates them. Decomposition takes either; recomposition writes the value back to every source array it emits an entry for.",
+  })),
+  rules,
+};
+
+for (const [name, schema] of Object.entries(schemas)) {
+  fs.writeFileSync(
+    path.join(V4_DIR, `${name}.json`),
+    JSON.stringify(schema, null, 2) + "\n"
+  );
+  console.log(`✓ ${name}.json`);
+}
+
+fs.writeFileSync(
+  path.join(V4_DIR, "mapping.json"),
+  JSON.stringify(mapping, null, 2) + "\n"
+);
+console.log("✓ mapping.json");
+
+console.log(`\nAll V4 schemas written to ${V4_DIR}`);