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

package/src/utils/generateV4Schemas.js

@@ -0,0 +1,1341 @@
+#!/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
+ *
+ * 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 Gift Donor, and offerId on Buyer (and Gift Donor,
+ * 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.
+ */
+const ROLE_IMPLIED_BY_CREDENTIAL = {
+  SellerCapacity: "Seller",
+  Offer: "Buyer",
+  Gift: "Gift Donor",
+};
+
+// ---------------------------------------------------------------------------
+// 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"
+  );
+
+  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:
+      "Array of URNs referencing Title entities to be sold in this transaction",
+    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, Gift Donor 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
+  // "Gift Donor" 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 gift donor. Implies the Gift Donor 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"]
+  );
+};
+
+// ---------------------------------------------------------------------------
+// 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,
+};
+
+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 },
+    instance: {
+      cardinality: "many",
+      orderedBy: { entity: "Transaction", pointer: "/titlesToBeSold" },
+      correlateBy: "titleNumber",
+      primarySource: true,
+    },
+    notes:
+      "Primary source: a Title carrying only shared keys recomposes to this array.",
+  },
+  {
+    id: "title.ownershipsToBeTransferred",
+    v3Pointer: "/propertyPack/ownership/ownershipsToBeTransferred/{index}",
+    entity: "Title",
+    entityPointer: "",
+    keys: { mode: "include", values: ownershipItemKeys },
+    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"] },
+    instance: { cardinality: "single" },
+  },
+
+  // --- Property: everything else in propertyPack ---------------------------
+  {
+    id: "property",
+    v3Pointer: "/propertyPack",
+    entity: "Property",
+    entityPointer: "",
+    keys: { mode: "exclude", values: PROPERTY_EXCLUDE },
+    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 },
+    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",
+    v3Pointer: "/participants/{index}",
+    entity: "SellerCapacity",
+    entityPointer: "",
+    keys: { mode: "include", values: ["sellersCapacity", "dateBecameOwnerOrAuthority"] },
+    instance: { cardinality: "many", matchOn: "/seller" },
+    impliesRole: "Seller",
+  },
+  {
+    id: "credential.offer",
+    v3Pointer: "/participants/{index}",
+    entity: "Offer",
+    entityPointer: "",
+    keys: { mode: "include", values: ["offerId"] },
+    instance: { cardinality: "many", matchOn: "/buyer" },
+    impliesRole: "Buyer",
+  },
+  {
+    id: "credential.gift",
+    v3Pointer: "/participants/{index}",
+    entity: "Gift",
+    entityPointer: "",
+    keys: { mode: "include", values: ["giftDetails", "offerId"] },
+    instance: { cardinality: "many", matchOn: "/donor" },
+    impliesRole: "Gift Donor",
+  },
+  {
+    id: "credential.representation",
+    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",
+    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 },
+    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"] },
+    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)
+          ? "credential"
+          : "standalone",
+        idScheme: name === "Property" || name === "Title" ? "urn" : "did",
+      },
+    ])
+  ),
+  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 is the one entity outside the round trip.",
+    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.",
+    ],
+  },
+  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, Gift Donor, 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.",
+    },
+  },
+  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}`);