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

package/docs/v4-mapping-and-recomposition.md

@@ -139,8 +139,11 @@ position that could diverge from another producer's.
 
 1. **Overlay metadata** (`*Ref`, `*Required` keys) is stripped from V4. It is
    schema-level only and never appears in instance data.
-2. A `Title` carrying only keys shared by both source arrays recomposes into
-   `titlesToBeSold` only, not into `ownershipsToBeTransferred`.
+2. `Transaction.titlesToBeSold` lists the titles V3 listed under
+   `propertyPack.titlesToBeSold`. A title known only from
+   `ownershipsToBeTransferred` is a `Title` entity but is not listed there, which
+   is how recomposition tells the two apart — and why a title whose only listed
+   key is `titleNumber` still gets its entry back.
 3. **`ownershipsToBeTransferred` order is canonicalised** to `titlesToBeSold`
    order. The array is correlated by `titleNumber` and its order carries no
    meaning in V3, so this is a deliberate normalisation that removes the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdtf/schemas",
-  "version": "3.6.0-dev.21",
+  "version": "3.6.0-dev.23",
   "description": "Property Data Trust Framework Schemas and Utilities",
   "main": "index.js",
   "files": [

package/src/schemas/v3/combined.json

@@ -49618,11 +49618,15 @@
                 "intendedUse": {
                   "type": "string",
                   "title": "Intended use of property",
+                  "description": "The primary purpose of the purchase: who will occupy the property, and on what basis. Secondary activities (a home office, a lodger, pets, alterations) are recorded in the separate fields below and are never values of this field, so a home-worker is \"Owner occupied\" with intendsBusiness true.",
                   "enum": [
                     "Owner occupied",
                     "Buy-to-let",
                     "Holiday let",
-                    "Second home"
+                    "Second home",
+                    "Family member occupied",
+                    "Development or renovation",
+                    "Business or mixed-use premises"
                   ]
                 },
                 "firstTimeBuyer": {
@@ -49671,6 +49675,11 @@
                   "title": "Buyer has pets",
                   "description": "Relevant to lease and covenant pet restriction assessment"
                 },
+                "petDetails": {
+                  "type": "string",
+                  "title": "Pets or other animals",
+                  "description": "The pets, horses or other animals the buyer intends to keep at the property, and how many (e.g. \"2 dogs, 1 cat\")"
+                },
                 "intendsSublet": {
                   "type": "boolean",
                   "title": "Buyer intends to sublet",
@@ -49695,6 +49704,16 @@
                   "title": "Buyer intends significant alterations",
                   "description": "Relevant to covenant, planning and building regulations assessment"
                 },
+                "alterationDescription": {
+                  "type": "string",
+                  "title": "Planned alterations",
+                  "description": "What the buyer intends to alter, extend or develop"
+                },
+                "vehicleRequirements": {
+                  "type": "string",
+                  "title": "Vehicles to keep at the property",
+                  "description": "Any caravan, motorhome, commercial vehicle or boat the buyer intends to keep at the property. Relevant to parking and use covenants"
+                },
                 "financingMethod": {
                   "type": "string",
                   "title": "Primary financing method",

package/src/schemas/v3/compactSkeleton.txt

@@ -4518,11 +4518,14 @@
       requiresMortgage
       isAdditionalProperty
       hasPets
+      petDetails
       intendsSublet
       subletType
       intendsBusiness
       businessType
       intendsAlterations
+      alterationDescription
+      vehicleRequirements
       financingMethod
       helpToBuyEquityLoan
       armedForcesHelpToBuy

package/src/schemas/v3/pdtf-transaction.json

@@ -41645,11 +41645,15 @@
                 "intendedUse": {
                   "type": "string",
                   "title": "Intended use of property",
+                  "description": "The primary purpose of the purchase: who will occupy the property, and on what basis. Secondary activities (a home office, a lodger, pets, alterations) are recorded in the separate fields below and are never values of this field, so a home-worker is \"Owner occupied\" with intendsBusiness true.",
                   "enum": [
                     "Owner occupied",
                     "Buy-to-let",
                     "Holiday let",
-                    "Second home"
+                    "Second home",
+                    "Family member occupied",
+                    "Development or renovation",
+                    "Business or mixed-use premises"
                   ]
                 },
                 "firstTimeBuyer": {
@@ -41701,6 +41705,11 @@
                   "title": "Buyer has pets",
                   "description": "Relevant to lease and covenant pet restriction assessment"
                 },
+                "petDetails": {
+                  "type": "string",
+                  "title": "Pets or other animals",
+                  "description": "The pets, horses or other animals the buyer intends to keep at the property, and how many (e.g. \"2 dogs, 1 cat\")"
+                },
                 "intendsSublet": {
                   "type": "boolean",
                   "title": "Buyer intends to sublet",
@@ -41732,6 +41741,16 @@
                   "title": "Buyer intends significant alterations",
                   "description": "Relevant to covenant, planning and building regulations assessment"
                 },
+                "alterationDescription": {
+                  "type": "string",
+                  "title": "Planned alterations",
+                  "description": "What the buyer intends to alter, extend or develop"
+                },
+                "vehicleRequirements": {
+                  "type": "string",
+                  "title": "Vehicles to keep at the property",
+                  "description": "Any caravan, motorhome, commercial vehicle or boat the buyer intends to keep at the property. Relevant to parking and use covenants"
+                },
                 "financingMethod": {
                   "type": "string",
                   "title": "Primary financing method",

package/src/schemas/v3/skeleton.json

@@ -5780,11 +5780,14 @@
         "requiresMortgage": "variant",
         "isAdditionalProperty": "boolean",
         "hasPets": "boolean",
+        "petDetails": "string",
         "intendsSublet": "boolean",
         "subletType": "string",
         "intendsBusiness": "boolean",
         "businessType": "string",
         "intendsAlterations": "boolean",
+        "alterationDescription": "string",
+        "vehicleRequirements": "string",
         "financingMethod": "string",
         "helpToBuyEquityLoan": "boolean",
         "armedForcesHelpToBuy": "boolean",

package/src/schemas/v4/Gift.json

@@ -6,10 +6,10 @@
   "description": "A gift of funds towards a purchase, made by a gift donor. Implies the Gift Donor role.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Offer.json

@@ -6,10 +6,10 @@
   "description": "An offer made by a prospective buyer in a property transaction.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {
@@ -130,11 +130,15 @@
         "intendedUse": {
           "type": "string",
           "title": "Intended use of property",
+          "description": "The primary purpose of the purchase: who will occupy the property, and on what basis. Secondary activities (a home office, a lodger, pets, alterations) are recorded in the separate fields below and are never values of this field, so a home-worker is \"Owner occupied\" with intendsBusiness true.",
           "enum": [
             "Owner occupied",
             "Buy-to-let",
             "Holiday let",
-            "Second home"
+            "Second home",
+            "Family member occupied",
+            "Development or renovation",
+            "Business or mixed-use premises"
           ]
         },
         "firstTimeBuyer": {
@@ -186,6 +190,11 @@
           "title": "Buyer has pets",
           "description": "Relevant to lease and covenant pet restriction assessment"
         },
+        "petDetails": {
+          "type": "string",
+          "title": "Pets or other animals",
+          "description": "The pets, horses or other animals the buyer intends to keep at the property, and how many (e.g. \"2 dogs, 1 cat\")"
+        },
         "intendsSublet": {
           "type": "boolean",
           "title": "Buyer intends to sublet",
@@ -217,6 +226,16 @@
           "title": "Buyer intends significant alterations",
           "description": "Relevant to covenant, planning and building regulations assessment"
         },
+        "alterationDescription": {
+          "type": "string",
+          "title": "Planned alterations",
+          "description": "What the buyer intends to alter, extend or develop"
+        },
+        "vehicleRequirements": {
+          "type": "string",
+          "title": "Vehicles to keep at the property",
+          "description": "Any caravan, motorhome, commercial vehicle or boat the buyer intends to keep at the property. Relevant to parking and use covenants"
+        },
         "financingMethod": {
           "type": "string",
           "title": "Primary financing method",

package/src/schemas/v4/Organisation.json

@@ -6,10 +6,10 @@
   "description": "A legal entity (company, firm, partnership) participating in a property transaction.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Person.json

@@ -6,10 +6,10 @@
   "description": "A natural person participating in a property transaction — name, contact details, address, verification status.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "name": {

package/src/schemas/v4/Property.json

@@ -6,10 +6,10 @@
   "description": "Physical and environmental facts about a property — address, construction, fixtures, services, searches, documents. Excludes ownership, titles, and participants.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "address": {

package/src/schemas/v4/Representation.json

@@ -6,10 +6,10 @@
   "description": "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.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {

package/src/schemas/v4/SellerCapacity.json

@@ -6,10 +6,10 @@
   "description": "The legal capacity in which a seller is selling a given title. Derived from the V3 participants 'Seller' branch (sellersCapacity, dateBecameOwnerOrAuthority).",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {

package/src/schemas/v4/Title.json

@@ -6,10 +6,10 @@
   "description": "HM Land Registry title — register extract, tenure type, and legal interest details for a single title number.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "titleNumber": {

package/src/schemas/v4/Transaction.json

@@ -6,10 +6,10 @@
   "description": "Transaction-level metadata — status, milestones, chain, contracts, offers, enquiries, and sale context.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "transactionId": {
@@ -984,11 +984,15 @@
                 "intendedUse": {
                   "type": "string",
                   "title": "Intended use of property",
+                  "description": "The primary purpose of the purchase: who will occupy the property, and on what basis. Secondary activities (a home office, a lodger, pets, alterations) are recorded in the separate fields below and are never values of this field, so a home-worker is \"Owner occupied\" with intendsBusiness true.",
                   "enum": [
                     "Owner occupied",
                     "Buy-to-let",
                     "Holiday let",
-                    "Second home"
+                    "Second home",
+                    "Family member occupied",
+                    "Development or renovation",
+                    "Business or mixed-use premises"
                   ]
                 },
                 "firstTimeBuyer": {
@@ -1040,6 +1044,11 @@
                   "title": "Buyer has pets",
                   "description": "Relevant to lease and covenant pet restriction assessment"
                 },
+                "petDetails": {
+                  "type": "string",
+                  "title": "Pets or other animals",
+                  "description": "The pets, horses or other animals the buyer intends to keep at the property, and how many (e.g. \"2 dogs, 1 cat\")"
+                },
                 "intendsSublet": {
                   "type": "boolean",
                   "title": "Buyer intends to sublet",
@@ -1071,6 +1080,16 @@
                   "title": "Buyer intends significant alterations",
                   "description": "Relevant to covenant, planning and building regulations assessment"
                 },
+                "alterationDescription": {
+                  "type": "string",
+                  "title": "Planned alterations",
+                  "description": "What the buyer intends to alter, extend or develop"
+                },
+                "vehicleRequirements": {
+                  "type": "string",
+                  "title": "Vehicles to keep at the property",
+                  "description": "Any caravan, motorhome, commercial vehicle or boat the buyer intends to keep at the property. Relevant to parking and use covenants"
+                },
                 "financingMethod": {
                   "type": "string",
                   "title": "Primary financing method",
@@ -1396,7 +1415,7 @@
     },
     "titlesToBeSold": {
       "title": "Titles to be Sold",
-      "description": "Array of URNs referencing Title entities to be sold in this transaction",
+      "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": {

package/src/schemas/v4/TransactionRole.json

@@ -6,10 +6,10 @@
   "description": "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.",
   "x-pdtf-source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "properties": {
     "id": {

package/src/schemas/v4/mapping.json

@@ -5,10 +5,10 @@
   "generator": "src/utils/generateV4Schemas.js",
   "source": {
     "packageName": "@pdtf/schemas",
-    "packageVersion": "3.6.0-dev.21",
+    "packageVersion": "3.6.0-dev.23",
     "v3SchemaId": "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json",
     "combinedPath": "src/schemas/v3/combined.json",
-    "combinedSha256": "1c6c5812f73a36d3674d5fb7b5eb1f6ce524d09c4195e281e078b9e41ea94f6d"
+    "combinedSha256": "21df4c6fb2117e9913eb9b16e48c9e6fe5f9ae9988af99e22bfcd4ef4bc6ceab"
   },
   "entities": {
     "Property": {
@@ -93,6 +93,13 @@
       "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": [
     {
       "pointer": "/participants",
@@ -883,6 +890,7 @@
           "covenantAnalysis"
         ]
       },
+      "extensions": "passthrough",
       "instance": {
         "cardinality": "many",
         "orderedBy": {
@@ -892,7 +900,7 @@
         "correlateBy": "titleNumber",
         "primarySource": true
       },
-      "notes": "Primary source: a Title carrying only shared keys recomposes to this array."
+      "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",
@@ -913,6 +921,7 @@
           "otherOwnershipDetails"
         ]
       },
+      "extensions": "drop",
       "instance": {
         "cardinality": "many",
         "orderedBy": {
@@ -944,6 +953,7 @@
           "ownershipsToBeTransferred"
         ]
       },
+      "extensions": "passthrough",
       "instance": {
         "cardinality": "single"
       }
@@ -961,6 +971,7 @@
           "legalOwners"
         ]
       },
+      "extensions": "passthrough",
       "instance": {
         "cardinality": "single"
       }
@@ -979,6 +990,7 @@
           "organisationReference"
         ]
       },
+      "extensions": "drop",
       "instance": {
         "cardinality": "many",
         "orderedBy": {
@@ -990,6 +1002,7 @@
     },
     {
       "id": "credential.sellerCapacity",
+      "extensions": "drop",
       "v3Pointer": "/participants/{index}",
       "entity": "SellerCapacity",
       "entityPointer": "",
@@ -1008,6 +1021,7 @@
     },
     {
       "id": "credential.offer",
+      "extensions": "drop",
       "v3Pointer": "/participants/{index}",
       "entity": "Offer",
       "entityPointer": "",
@@ -1025,6 +1039,7 @@
     },
     {
       "id": "credential.gift",
+      "extensions": "drop",
       "v3Pointer": "/participants/{index}",
       "entity": "Gift",
       "entityPointer": "",
@@ -1043,6 +1058,7 @@
     },
     {
       "id": "credential.representation",
+      "extensions": "drop",
       "v3Pointer": "/participants/{index}",
       "entity": "Representation",
       "entityPointer": "",
@@ -1065,6 +1081,7 @@
     },
     {
       "id": "credential.transactionRole",
+      "extensions": "drop",
       "v3Pointer": "/participants/{index}",
       "entity": "TransactionRole",
       "entityPointer": "",
@@ -1099,6 +1116,7 @@
           "verification"
         ]
       },
+      "extensions": "passthrough",
       "instance": {
         "cardinality": "many",
         "orderedBy": {
@@ -1121,6 +1139,7 @@
           "$schema"
         ]
       },
+      "extensions": "passthrough",
       "instance": {
         "cardinality": "single"
       }

package/src/utils/generateV4Schemas.js

@@ -398,7 +398,7 @@ const generateTransaction = () => {
   topLevel.titlesToBeSold = {
     title: "Titles to be Sold",
     description:
-      "Array of URNs referencing Title entities to be sold in this transaction",
+      "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"),
@@ -973,6 +973,7 @@ const buildRules = () => [
     entity: "Title",
     entityPointer: "",
     keys: { mode: "include", values: titlesKeys },
+    extensions: "passthrough",
     instance: {
       cardinality: "many",
       orderedBy: { entity: "Transaction", pointer: "/titlesToBeSold" },
@@ -980,7 +981,7 @@ const buildRules = () => [
       primarySource: true,
     },
     notes:
-      "Primary source: a Title carrying only shared keys recomposes to this array.",
+      "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",
@@ -988,6 +989,7 @@ const buildRules = () => [
     entity: "Title",
     entityPointer: "",
     keys: { mode: "include", values: ownershipItemKeys },
+    extensions: "drop",
     instance: {
       cardinality: "many",
       orderedBy: { entity: "Transaction", pointer: "/titlesToBeSold" },
@@ -1012,6 +1014,7 @@ const buildRules = () => [
     entity: "Transaction",
     entityPointer: "/saleContext",
     keys: { mode: "exclude", values: ["ownershipsToBeTransferred"] },
+    extensions: "passthrough",
     instance: { cardinality: "single" },
   },
 
@@ -1022,6 +1025,7 @@ const buildRules = () => [
     entity: "Property",
     entityPointer: "",
     keys: { mode: "exclude", values: PROPERTY_EXCLUDE },
+    extensions: "passthrough",
     instance: { cardinality: "single" },
   },
 
@@ -1032,6 +1036,7 @@ const buildRules = () => [
     entity: "Transaction",
     entityPointer: "/participants/{index}",
     keys: { mode: "include", values: PARTICIPANT_ROSTER_FIELDS },
+    extensions: "drop",
     instance: {
       cardinality: "many",
       orderedBy: { entity: "Transaction", pointer: "/participants" },
@@ -1046,6 +1051,7 @@ const buildRules = () => [
   // returns the candidates; pass the decomposed entities to narrow it.
   {
     id: "credential.sellerCapacity",
+    extensions: "drop",
     v3Pointer: "/participants/{index}",
     entity: "SellerCapacity",
     entityPointer: "",
@@ -1055,6 +1061,7 @@ const buildRules = () => [
   },
   {
     id: "credential.offer",
+    extensions: "drop",
     v3Pointer: "/participants/{index}",
     entity: "Offer",
     entityPointer: "",
@@ -1064,6 +1071,7 @@ const buildRules = () => [
   },
   {
     id: "credential.gift",
+    extensions: "drop",
     v3Pointer: "/participants/{index}",
     entity: "Gift",
     entityPointer: "",
@@ -1073,6 +1081,7 @@ const buildRules = () => [
   },
   {
     id: "credential.representation",
+    extensions: "drop",
     v3Pointer: "/participants/{index}",
     entity: "Representation",
     entityPointer: "",
@@ -1084,6 +1093,7 @@ const buildRules = () => [
   },
   {
     id: "credential.transactionRole",
+    extensions: "drop",
     v3Pointer: "/participants/{index}",
     entity: "TransactionRole",
     entityPointer: "",
@@ -1098,6 +1108,7 @@ const buildRules = () => [
     entity: "Person",
     entityPointer: "",
     keys: { mode: "include", values: personKeys },
+    extensions: "passthrough",
     instance: {
       cardinality: "many",
       orderedBy: {
@@ -1115,6 +1126,7 @@ const buildRules = () => [
     entity: "Transaction",
     entityPointer: "",
     keys: { mode: "exclude", values: [...TRANSACTION_EXCLUDE, "$schema"] },
+    extensions: "passthrough",
     instance: { cardinality: "single" },
   },
 ];
@@ -1236,6 +1248,11 @@ const mapping = {
       "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:

package/src/utils/v4.js

@@ -46,12 +46,69 @@ const omit = (obj, keys) =>
     Object.entries(obj || {}).filter(([k]) => !keys.includes(k))
   );
 
-/** Apply a rule's `keys` selector to a V3 node. */
+/**
+ * Every key any rule at this V3 pointer claims by name. Anything outside it is
+ * an extension: a platform's own block, or an externalIds namespace the schema
+ * does not define.
+ */
+const claimedKeysAt = (v3Pointer) => {
+  const claimed = new Set();
+  for (const rule of mapping.rules) {
+    if (rule.v3Pointer !== v3Pointer || rule.keys?.mode !== "include") continue;
+    for (const key of rule.keys.values) claimed.add(key);
+  }
+  return claimed;
+};
+
+const CLAIMED_BY_POINTER = new Map();
+const claimedFor = (v3Pointer) => {
+  if (!CLAIMED_BY_POINTER.has(v3Pointer)) {
+    CLAIMED_BY_POINTER.set(v3Pointer, claimedKeysAt(v3Pointer));
+  }
+  return CLAIMED_BY_POINTER.get(v3Pointer);
+};
+
+/**
+ * Apply a rule's `keys` selector to a V3 node.
+ *
+ * An exclude-mode rule takes everything it does not exclude, extensions
+ * included. An include-mode rule names its keys, so extensions would fall
+ * through the gap — which is why each V3 node nominates exactly one rule as its
+ * extension sink (`extensions: "passthrough"` in the manifest). Without that,
+ * whether a platform's own keys survived depended on which mode happened to
+ * claim their parent.
+ */
 const selectKeys = (node, rule) => {
   if (!rule.keys) return { ...(node || {}) };
-  return rule.keys.mode === "include"
-    ? pick(node, rule.keys.values)
-    : omit(node, rule.keys.values);
+  if (rule.keys.mode === "exclude") return omit(node, rule.keys.values);
+
+  const selected = pick(node, rule.keys.values);
+  if (rule.extensions === "passthrough") {
+    const claimed = claimedFor(rule.v3Pointer);
+    for (const [key, value] of Object.entries(node || {})) {
+      if (!claimed.has(key)) selected[key] = value;
+    }
+  }
+  return selected;
+};
+
+/**
+ * A hole in a V3 array — an index written before an earlier one exists — is
+ * skipped by forEach, which would silently shift every later item and lose its
+ * position. Refuse instead: the position is data here, and a quiet shift is
+ * worse than a stop.
+ */
+const assertDense = (array, label) => {
+  if (!Array.isArray(array)) return array;
+  for (let i = 0; i < array.length; i += 1) {
+    if (!(i in array)) {
+      throw new Error(
+        `v4 decompose: ${label} has a hole at index ${i} (length ${array.length}). ` +
+          "Array position carries meaning here, so the gap must be filled or the entry removed before decomposing."
+      );
+    }
+  }
+  return array;
 };
 
 const isEmpty = (v) =>
@@ -153,17 +210,19 @@ const decompose = (v3, { idFactory } = {}) => {
    * malformed data. Failing loudly beats losing an entry.
    */
   const mergeSource = (items, rule, sourceName) => {
-    const seen = new Set();
+    const seen = new Map();
+    assertDense(items, sourceName);
     items.forEach((item, index) => {
       const correlationValue = item[correlateBy];
       if (correlationValue !== undefined) {
         if (seen.has(correlationValue)) {
           throw new Error(
-            `v4 decompose: ${sourceName}[${index}] repeats ${correlateBy} "${correlationValue}". ` +
+            `v4 decompose: ${sourceName}[${index}] repeats ${correlateBy} "${correlationValue}", ` +
+              `already used by ${sourceName}[${seen.get(correlationValue)}]. ` +
               `${correlateBy} must be unique within an array — it is what correlates the two Title sources.`
           );
         }
-        seen.add(correlationValue);
+        seen.set(correlationValue, index);
       }
       Object.assign(upsert(correlationValue), selectKeys(item, rule));
     });
@@ -171,6 +230,10 @@ const decompose = (v3, { idFactory } = {}) => {
 
   // titlesToBeSold order leads; ownership-only titles are appended after.
   mergeSource(titleItems, titlesRule, "propertyPack.titlesToBeSold");
+  // Which titles V3 actually listed under titlesToBeSold, as opposed to knowing
+  // only from ownership. Without this, a title whose sole titlesToBeSold key is
+  // titleNumber is indistinguishable from one that was never listed there.
+  const listedUnderTitles = new Set(titles);
   mergeSource(
     ownershipItems,
     ownershipsRule,
@@ -182,7 +245,7 @@ const decompose = (v3, { idFactory } = {}) => {
   });
 
   // --- Person + participant context ---------------------------------------
-  const participants = v3.participants || [];
+  const participants = assertDense(v3.participants || [], "participants");
   const persons = [];
   const personIndexById = new Map();
   const participantContext = [];
@@ -225,7 +288,7 @@ const decompose = (v3, { idFactory } = {}) => {
   assignIfPresent(
     transaction,
     "titlesToBeSold",
-    titles.map((t) => t.id)
+    titles.filter((t) => listedUnderTitles.has(t)).map((t) => t.id)
   );
   assignIfPresent(transaction, "participants", participantContext);
 
@@ -392,31 +455,41 @@ const recompose = ({
   const propertyPack = omit(Property || {}, ["id"]);
 
   // Split each Title back into the two source arrays it was merged from.
-  // A key shared by both sources is written to every array that gets an entry;
-  // a Title carrying *only* shared keys goes to the primarySource array alone.
+  // Transaction.titlesToBeSold says which titles V3 listed under titlesToBeSold,
+  // so an entry is emitted for every one of them — including a title whose only
+  // key there was titleNumber, which is every transaction between the seller
+  // naming the title and the deeds arriving.
   const titlesOwned = titlesRule.keys.values;
   const ownershipsOwned = ownershipsRule.keys.values;
+  const schemaKeys = new Set([...titlesOwned, ...ownershipsOwned, "id"]);
 
   const titlesToBeSold = [];
   const ownershipsToBeTransferred = [];
 
-  // Transaction.titlesToBeSold is the authoritative order for Title entities.
   const titleById = new Map(titles.map((t) => [t.id, t]));
-  const orderedTitles = (transaction.titlesToBeSold || []).map(
-    (id, index) => titleById.get(id) || titles[index]
-  );
-  const titleList = orderedTitles.length ? orderedTitles.filter(Boolean) : titles;
+  const listedIds = transaction.titlesToBeSold || [];
+  const listed = listedIds.map((id) => titleById.get(id)).filter(Boolean);
+  // Ordered by the listed titles first, then any known only from ownership.
+  const titleList = [...listed, ...titles.filter((t) => !listedIds.includes(t.id))];
 
   for (const title of titleList) {
-    const titlesPart = pick(title, titlesOwned);
     const ownershipPart = pick(title, ownershipsOwned);
-
-    const hasTitlesOnly = Object.keys(omit(titlesPart, SHARED_TITLE_KEYS)).length > 0;
-    const hasOwnershipOnly =
+    const hasOwnership =
       Object.keys(omit(ownershipPart, SHARED_TITLE_KEYS)).length > 0;
 
-    if (hasTitlesOnly || !hasOwnershipOnly) titlesToBeSold.push(titlesPart);
-    if (hasOwnershipOnly) ownershipsToBeTransferred.push(ownershipPart);
+    if (listed.includes(title)) {
+      const titlesPart = pick(title, titlesOwned);
+      // Extension keys go back to the rule that took them (titlesToBeSold is
+      // the declared sink); see mapping.extensionPolicy.
+      if (titlesRule.extensions === "passthrough") {
+        for (const [key, value] of Object.entries(title)) {
+          if (!schemaKeys.has(key)) titlesPart[key] = value;
+        }
+      }
+      titlesToBeSold.push(titlesPart);
+    }
+
+    if (hasOwnership) ownershipsToBeTransferred.push(ownershipPart);
   }
 
   assignIfPresent(propertyPack, "titlesToBeSold", titlesToBeSold);