@pascal-app/core 1.0.3 → 1.0.5

package/dist/contracts/reference-inventory.js

@@ -0,0 +1,952 @@
+const row = (r) => ({ extractor: 'path', remaps: [], ...r });
+const policy = (namespace, role, onDelete, onPreset) => ({ namespace, role, onDelete, onPreset });
+const CLONES = ['clone-scene-graph', 'clone-level-subtree'];
+const WALL_TOPOLOGY = ['wall-merge', 'wall-split', 'wall-topology'];
+/** Inline `MaterialSchema` fields; each carries a texture URL and a sibling `<field>Preset`. */
+const MATERIAL_FIELDS = [
+    'material',
+    'edgeMaterial',
+    'exteriorMaterial',
+    'fasciaMaterial',
+    'glassMaterial',
+    'interiorMaterial',
+    'panelMaterial',
+    'railingMaterial',
+    'sideMaterial',
+    'topMaterial',
+    'treadMaterial',
+    'wallMaterial',
+];
+const materialRows = MATERIAL_FIELDS.flatMap((field) => [
+    row({
+        kind: '*',
+        path: `${field}.texture.url`,
+        ...policy('asset', 'content', 'freeze', 'keep'),
+        note: 'Texture by URL; a dangling URL renders the untextured material.',
+    }),
+    row({
+        kind: '*',
+        path: `${field}Preset`,
+        ...policy('material', 'content', 'freeze', 'keep'),
+        note: 'Library material preset name.',
+    }),
+]);
+const measurementAnchorRows = (kind, prefix, remaps) => [
+    row({
+        kind,
+        path: `${prefix}.reference.nodeId`,
+        ...policy('node', 'host', 'freeze', 'materialize'),
+        remaps,
+        note: 'Feature anchor; `fallback` holds the materialized point that a freeze keeps.',
+    }),
+    row({
+        kind,
+        path: `${prefix}.reference.featureId`,
+        ...policy('surface', 'host', 'freeze', 'materialize'),
+        owner: `${prefix}.reference.nodeId`,
+        note: 'Measurement feature (face, edge or point) of the anchored node; owner-scoped, survives clone.',
+    }),
+];
+export const EXISTING_REFERENCES = [
+    // ─── Hierarchy ────────────────────────────────────────────────────
+    row({
+        kind: '*',
+        path: 'parentId',
+        ...policy('node', 'hierarchy', 'cascade', 'strip'),
+        remaps: [
+            ...CLONES,
+            'clone-nodes-into',
+            'scene-clipboard',
+            'level-duplication',
+            ...WALL_TOPOLOGY,
+        ],
+    }),
+    row({
+        kind: '*',
+        path: 'children[]',
+        ...policy('node', 'hierarchy', 'drop', 'keep'),
+        remaps: [
+            ...CLONES,
+            'clone-nodes-into',
+            'scene-clipboard',
+            'level-duplication',
+            ...WALL_TOPOLOGY,
+            'delete-nodes',
+        ],
+    }),
+    row({
+        kind: 'procedural-item',
+        path: 'attachments.@key',
+        ...policy('node', 'hierarchy', 'drop', 'keep'),
+        remaps: ['clone-scene-graph', 'clone-nodes-into'],
+        note: 'Record key: a hosted child id. The level-subtree clone keeps the old key.',
+    }),
+    row({
+        kind: 'procedural-item',
+        path: 'attachments.*',
+        ...policy('surface', 'internal', 'drop', 'keep'),
+        note: 'Recipe surface of this item that the keyed child sits on.',
+    }),
+    row({
+        kind: '#scene',
+        path: 'rootNodeIds[]',
+        ...policy('node', 'hierarchy', 'drop', 'keep'),
+        remaps: ['clone-scene-graph', 'delete-nodes'],
+    }),
+    // ─── Hosts and supports ───────────────────────────────────────────
+    row({
+        kind: '*',
+        path: 'wallId',
+        ...policy('node', 'host', 'cascade', 'strip'),
+        targetKinds: ['wall'],
+        dependents: ['side', 'wallT'],
+        remaps: [...CLONES, 'scene-clipboard', ...WALL_TOPOLOGY],
+        note: 'Items, procedural items, doors and windows hosted as wall children.',
+    }),
+    row({
+        kind: '*',
+        path: 'roofSegmentId',
+        ...policy('node', 'host', 'cascade', 'strip'),
+        targetKinds: ['roof-segment'],
+        dependents: ['roofFace', 'side'],
+        remaps: CLONES,
+        note: 'Roof accessories, and doors/windows/items on a segment wall face.',
+    }),
+    row({
+        kind: 'window',
+        path: 'corner.partnerId',
+        ...policy('node', 'connection', 'drop', 'strip'),
+        targetKinds: ['window'],
+        remaps: [...CLONES, 'scene-clipboard'],
+        note: "A corner window's other side: copied with it, the copy names the partner's copy; copied alone, or once its partner is deleted, the link is cleared.",
+    }),
+    row({
+        kind: 'window',
+        path: 'dormerId',
+        ...policy('node', 'host', 'cascade', 'strip'),
+        targetKinds: ['dormer'],
+        dependents: ['dormerFace'],
+        remaps: ['clone-scene-graph'],
+        note: 'Only the whole-graph clone remaps `dormerId`.',
+    }),
+    row({
+        kind: 'item',
+        path: 'blockFaceId',
+        ...policy('surface', 'host', 'cascade', 'strip'),
+        owner: 'parentId',
+        note: 'Block topology face id; owner-scoped, survives clone.',
+    }),
+    row({
+        kind: '*',
+        path: 'supportSlabId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        sentinels: ['ground'],
+        remaps: [...CLONES, 'delete-nodes'],
+        note: "'ground' pins the node to the level base; deleting the slab strips the field.",
+    }),
+    row({
+        kind: 'stair',
+        path: 'deckSlabId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        remaps: [...CLONES, 'delete-nodes'],
+    }),
+    row({
+        kind: 'fence',
+        path: 'supportSurfaceNodeId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        remaps: [...CLONES, 'clone-nodes-into', 'delete-nodes'],
+        note: 'A registered walking surface supporting a railing.',
+    }),
+    row({
+        kind: 'stair',
+        path: 'destinationSurfaceId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        remaps: [...CLONES, 'clone-nodes-into', 'delete-nodes'],
+        note: 'A registered top surface supporting a stair connection.',
+    }),
+    row({
+        kind: 'roof',
+        path: 'support.roofSegmentId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['roof-segment'],
+        remaps: CLONES,
+        note: "Only on the `support.kind: 'roof'` branch.",
+    }),
+    row({
+        kind: 'lean-to-extension',
+        path: 'hostRoofId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['roof'],
+        remaps: CLONES,
+    }),
+    row({
+        kind: 'lean-to-extension',
+        path: 'hostRoofSegmentId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['roof-segment'],
+        dependents: ['hostRoofEdge', 'hostRoofEdgeRange', 'hostKind', 'hostHeightOffset'],
+        remaps: CLONES,
+    }),
+    row({
+        kind: 'building',
+        path: 'groundLevelId',
+        ...policy('node', 'control', 'drop', 'keep'),
+        targetKinds: ['level'],
+        remaps: ['clone-scene-graph'],
+        note: 'The level at grade, the ground line of the stack. A level of another building, or a deleted one, is no ground level: the line is read off the elevations again (`groundLevelOf`).',
+    }),
+    row({
+        kind: 'lean-to-extension',
+        path: 'hostSlabId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        dependents: ['hostSlabEdgeIndex', 'hostSlabEdgeT', 'hostKind', 'hostHeightOffset'],
+        remaps: ['clone-scene-graph'],
+    }),
+    row({
+        kind: '*',
+        path: 'wallAttachment.wallId',
+        ...policy('node', 'host', 'freeze', 'strip'),
+        targetKinds: ['wall'],
+        dependents: [
+            'wallAttachment.side',
+            'wallAttachment.startUV',
+            'wallAttachment.endUV',
+            'wallAttachment.offset',
+        ],
+        remaps: ['clone-scene-graph'],
+        note: 'Duct and pipe runs drafted on a wall; the level-local path is the frozen pose.',
+    }),
+    row({
+        kind: '*',
+        path: 'hangerOverrides.*.hostId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['wall', 'ceiling'],
+        remaps: ['clone-scene-graph'],
+        note: 'Pinned hanger host; absent re-elects the nearest wall or ceiling.',
+    }),
+    row({
+        kind: 'downspout',
+        path: 'gutterId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['gutter'],
+        remaps: ['clone-scene-graph'],
+    }),
+    row({
+        kind: 'zone',
+        path: 'hostZoneId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: CLONES,
+        note: 'A mezzanine room: the room whose volume it stands in.',
+    }),
+    row({
+        kind: 'floor-opening',
+        path: 'hostZoneId',
+        ...policy('node', 'host', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: CLONES,
+        note: 'A hosted mezzanine opening cuts only that room’s plate.',
+    }),
+    row({
+        kind: 'downspout',
+        path: 'outletId',
+        ...policy('part', 'host', 'drop', 'strip'),
+        owner: 'gutterId',
+        note: "An entry of the gutter's `outlets[]`; owner-scoped, survives clone.",
+    }),
+    // ─── Parts and topology owned by the node ─────────────────────────
+    row({
+        kind: '*',
+        path: 'hangerOverrides.@key',
+        ...policy('part', 'internal', 'drop', 'keep'),
+        note: 'Hanger slot `<leg>:<index>`: an index key, not a lattice key (F3 replaces it).',
+    }),
+    row({
+        kind: 'block',
+        path: 'topology.edges[].vertexIds[]',
+        ...policy('part', 'internal', 'cascade', 'keep'),
+    }),
+    row({
+        kind: 'block',
+        path: 'topology.faces[].vertexIds[]',
+        ...policy('part', 'internal', 'cascade', 'keep'),
+    }),
+    // ─── Connections (explicit and derived) ───────────────────────────
+    // Shed joints are equality labels, not node references (B3). The lean-to
+    // assembly writes lean-to ids (`assembly.ts`); the bench roof-fit converter
+    // writes a source face id as both owner and sole neighbour, scoping a precut
+    // facet to itself. The roof system only compares them for equality.
+    row({
+        kind: 'roof-segment',
+        path: 'shedJointOwnerId',
+        ...policy('label', 'connection', 'drop', 'strip'),
+        note: 'Join label of this segment: a lean-to id or a source face id. Never resolved.',
+    }),
+    row({
+        kind: 'roof-segment',
+        path: 'shedJointNeighborIds[]',
+        ...policy('label', 'connection', 'drop', 'strip'),
+        note: 'Owner labels this segment may miter against; empty = any sibling.',
+    }),
+    row({
+        kind: 'wall',
+        path: '#linkedBy',
+        ...policy('node', 'connection', 'drop', 'strip'),
+        extractor: 'linked-by',
+        linkedBy: 'endpoint-match',
+        targetKinds: ['wall'],
+        note: 'Wall junctions: derived from coincident endpoints, never persisted; the reverse index must carry them.',
+    }),
+    row({
+        kind: 'fence',
+        path: '#linkedBy',
+        ...policy('node', 'connection', 'drop', 'strip'),
+        extractor: 'linked-by',
+        linkedBy: 'endpoint-match',
+        targetKinds: ['fence'],
+    }),
+    // ─── Membership ───────────────────────────────────────────────────
+    row({
+        kind: 'zone',
+        path: 'boundaryWallIds[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['wall'],
+        remaps: ['clone-scene-graph', ...WALL_TOPOLOGY],
+        note: 'The level-subtree and subtree clones copy the old wall ids into the cloned zone.',
+    }),
+    row({
+        kind: 'zone',
+        path: 'boundarySeparatorIds[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['separator'],
+        remaps: ['clone-scene-graph'],
+        note: 'Derived by the structure reconciler, which rewrites it on the next pass.',
+    }),
+    row({
+        kind: 'slab',
+        path: 'zoneIds[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: ['clone-scene-graph', 'clone-level-subtree'],
+        note: 'Rooms a derived plate carries; rewritten by the structure reconciler.',
+    }),
+    row({
+        kind: 'slab',
+        path: 'associatedZoneIds[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: ['clone-scene-graph'],
+        note: 'Rooms whose construction overlaps a manual slab, resolved once by the legacy migration.',
+    }),
+    row({
+        kind: 'ceiling',
+        path: 'zoneId',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: ['clone-scene-graph', 'clone-level-subtree'],
+        note: 'The room a derived ceiling covers; rewritten by the structure reconciler.',
+    }),
+    row({
+        kind: 'unit',
+        path: 'members[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['zone'],
+        remaps: ['clone-scene-graph', 'level-duplication', 'delete-nodes'],
+    }),
+    row({
+        kind: 'item',
+        path: 'collectionIds[]',
+        ...policy('collection', 'membership', 'drop', 'strip'),
+        remaps: ['clone-scene-graph'],
+        note: 'Node creation (`joinCollections`) adds a copy to the collections it names that exist and drops the rest.',
+    }),
+    row({
+        kind: '#scene',
+        path: 'collections.*.nodeIds[]',
+        ...policy('node', 'membership', 'drop', 'strip'),
+        remaps: ['clone-scene-graph', 'delete-nodes'],
+    }),
+    ...['fromLevelId', 'toLevelId'].map((path) => row({
+        kind: 'stair',
+        path,
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['level'],
+        remaps: ['clone-scene-graph', 'scene-clipboard'],
+        note: 'Pasting a stair re-derives both from the target level.',
+    })),
+    ...[
+        'fromLevelId',
+        'toLevelId',
+        'defaultLevelId',
+        'servedLevelIds[]',
+        'disabledLevelIds[]',
+        'serviceOnlyLevelIds[]',
+    ].map((path) => row({
+        kind: 'elevator',
+        path,
+        ...policy('node', 'membership', 'drop', 'strip'),
+        targetKinds: ['level'],
+        remaps: ['clone-scene-graph'],
+    })),
+    row({
+        kind: 'roof-segment',
+        path: 'shedJointScopeId',
+        ...policy('label', 'membership', 'drop', 'strip'),
+        note: 'Scope label for comparing seams across roof parents; producers write a level id today.',
+    }),
+    // ─── Control ──────────────────────────────────────────────────────
+    row({
+        kind: '#scene',
+        path: 'collections.*.controlNodeId',
+        ...policy('node', 'control', 'drop', 'strip'),
+        remaps: ['clone-scene-graph'],
+        note: 'Node deletion leaves it dangling.',
+    }),
+    row({
+        kind: 'construction-dimension',
+        path: 'controllingDimensionId',
+        ...policy('node', 'control', 'drop', 'strip'),
+        targetKinds: ['construction-dimension'],
+        remaps: [...CLONES, 'clone-nodes-into'],
+    }),
+    ...['stairId', 'elevatorId', 'openingId'].map((field) => row({
+        kind: '*',
+        path: `holeMetadata[].${field}`,
+        ...policy('node', 'control', 'drop', 'strip'),
+        targetKinds: [
+            field === 'stairId' ? 'stair' : field === 'elevatorId' ? 'elevator' : 'floor-opening',
+        ],
+        remaps: field === 'openingId' ? CLONES : ['clone-scene-graph'],
+        note: 'The cutter that owns this auto hole; its sync replaces only its own holes.',
+    })),
+    row({
+        kind: 'ceiling',
+        path: 'openingIds[]',
+        ...policy('node', 'control', 'drop', 'strip'),
+        targetKinds: ['floor-opening'],
+        remaps: ['clone-scene-graph'],
+        note: 'Openings that cut a derived ceiling; rewritten by the structure reconciler.',
+    }),
+    row({
+        kind: 'floor-opening',
+        path: 'ownerId',
+        ...policy('node', 'control', 'cascade', 'strip'),
+        remaps: CLONES,
+        note: 'The stair, elevator or plugin node that owns this opening and moves it with its pose.',
+    }),
+    row({
+        kind: 'floor-opening',
+        path: 'surfaceId',
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['slab', 'ceiling'],
+        remaps: ['clone-scene-graph'],
+        note: 'The surface an owned opening was migrated from; merge tie-break only.',
+    }),
+    ...[
+        ['legacyPlateCuts.@key', 'slab'],
+        ['legacyCeilingCuts.@key', 'ceiling'],
+    ].map(([path, target]) => row({
+        kind: 'floor-opening',
+        path,
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: [target],
+        remaps: target === 'slab' ? CLONES : ['clone-scene-graph'],
+        note: 'Record key: the legacy surface whose exact cut rings this opening keeps.',
+    })),
+    row({
+        kind: 'zone',
+        path: 'floor.sourceSlabId',
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        remaps: ['clone-scene-graph'],
+        note: 'The drawn slab this room’s floor was adopted from.',
+    }),
+    row({
+        kind: 'zone',
+        path: 'wallOverrides[].wallId',
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['wall'],
+        remaps: ['clone-scene-graph'],
+        note: 'A per-wall-face finish over the room’s wall material.',
+    }),
+    // ─── Measurements and dimensions ──────────────────────────────────
+    ...measurementAnchorRows('measurement', 'measurement.points[]', [
+        ...CLONES,
+        'clone-nodes-into',
+        'scene-clipboard',
+    ]),
+    ...measurementAnchorRows('measurement', 'measurement.base[]', [
+        ...CLONES,
+        'clone-nodes-into',
+        'scene-clipboard',
+    ]),
+    ...measurementAnchorRows('construction-dimension', 'anchors[]', [...CLONES, 'clone-nodes-into']),
+    // ─── Content: materials, assets, sources ──────────────────────────
+    row({
+        kind: '*',
+        path: 'slots.*',
+        ...policy('material', 'content', 'freeze', 'keep'),
+        extractor: 'prefixed',
+        prefix: 'scene:',
+        remaps: ['scene-clipboard'],
+        note: 'Scene palette entry; clone keeps material ids by design, paste mints new ones.',
+    }),
+    row({
+        kind: '*',
+        path: 'slots.*',
+        ...policy('material', 'content', 'freeze', 'keep'),
+        extractor: 'prefixed',
+        prefix: 'library:',
+        note: 'Library material; `#rrggbb` values are literal colours.',
+    }),
+    ...materialRows,
+    ...['legacyFaceMaterials.a', 'legacyFaceMaterials.b', 'foundation'].map((prefix) => row({
+        kind: '*',
+        path: `${prefix}.material.texture.url`,
+        ...policy('asset', 'content', 'freeze', 'keep'),
+        note: 'Texture by URL; a dangling URL renders the untextured material.',
+    })),
+    ...['legacyFaceMaterials.a', 'legacyFaceMaterials.b'].map((prefix) => row({
+        kind: 'wall',
+        path: `${prefix}.materialPreset`,
+        ...policy('material', 'content', 'freeze', 'keep'),
+        note: 'Library material preset name of the legacy per-face finish.',
+    })),
+    ...[
+        ['zone', 'floor.finish.*'],
+        ['zone', 'floor.regions[].finish.*'],
+        ['zone', 'ceiling.regions[].finish.*'],
+        ['ceiling', 'regions[].finish.*'],
+    ].map(([kind, path]) => row({
+        kind,
+        path,
+        ...policy('material', 'content', 'freeze', 'keep'),
+        note: 'A paint finish: a MaterialRef string, or this inline material record.',
+    })),
+    ...['asset.id', 'asset.src', 'asset.thumbnail', 'asset.floorPlanUrl'].map((path) => row({
+        kind: 'item',
+        path,
+        ...policy('asset', 'content', 'freeze', 'keep'),
+        note: 'Inline catalog asset (about 1 KB per item); F8 moves it to an asset reference.',
+    })),
+    ...['scan', 'guide'].map((kind) => row({ kind, path: 'url', ...policy('asset', 'content', 'freeze', 'keep') })),
+    row({
+        kind: 'scan',
+        path: 'captureSession.manifestUrl',
+        ...policy('asset', 'content', 'freeze', 'keep'),
+    }),
+    ...['captureSession.sessionId', 'captureSession.revisionId'].map((path) => row({
+        kind: 'scan',
+        path,
+        ...policy('source', 'content', 'freeze', 'keep'),
+        note: 'Capture provenance: stable across re-capture (R9).',
+    })),
+    ...['assembly.layers[].src', 'assembly.backing[].src'].map((path) => row({
+        kind: '*',
+        path,
+        ...policy('source', 'content', 'freeze', 'strip'),
+        note: 'Layer provenance (F2): a preset strips it so it never claims a source element.',
+    })),
+    ...['assembly.layers[].slot', 'assembly.backing[].slot'].map((path) => row({
+        kind: '*',
+        path,
+        ...policy('part', 'internal', 'drop', 'keep'),
+        note: "A key into the host's own `slots`; a missing key falls back to `layer:<id>`, then the role default.",
+    })),
+    row({
+        kind: '*',
+        path: 'assembly.presetId',
+        ...policy('asset', 'content', 'freeze', 'keep'),
+        note: 'The assembly preset a layer stack was made from.',
+    }),
+    // ─── Typed provenance (D5) ────────────────────────────────────────
+    row({
+        kind: '*',
+        path: 'provenance.refs[].id',
+        ...policy('source', 'content', 'freeze', 'strip'),
+        note: 'Source element the node reproduces, scoped by `ns`; stripped with its whole ref so presets never claim it. Clones keep it today (I-04 re-roles copies).',
+    }),
+    row({
+        kind: '*',
+        path: 'provenance.lineage.fromIds[]',
+        ...policy('label', 'internal', 'freeze', 'strip'),
+        note: 'Node ids this node was split, merged or copied from. History: compared, never dereferenced, kept when those nodes are deleted.',
+    }),
+];
+/** Candidate paths that are not references, with the reason. `kind: '*'` matches every kind. */
+export const NON_REFERENCES = [
+    { kind: '*', path: 'id', reason: "The node's own id: a definition, not a reference." },
+    {
+        kind: '*',
+        path: 'metadata.@key',
+        reason: 'Open record: its keys are discovered from source and classified in METADATA_*.',
+    },
+    { kind: '*', path: 'metadata.*', reason: 'See metadata.@key.' },
+    { kind: '*', path: 'slots.@key', reason: 'Slot id declared by the kind or its asset.' },
+    { kind: 'block', path: 'slotNames.@key', reason: 'Slot id declared by the block.' },
+    { kind: 'block', path: 'slotNames.*', reason: 'Display name.' },
+    ...[
+        ...MATERIAL_FIELDS,
+        'legacyFaceMaterials.a.material',
+        'legacyFaceMaterials.b.material',
+        'foundation.material',
+    ].map((field) => ({
+        kind: '*',
+        path: `${field}.id`,
+        reason: 'Optional label of an inline material; no reader dereferences it.',
+    })),
+    ...[
+        ['zone', 'floor.finish.@key'],
+        ['zone', 'floor.regions[].finish.@key'],
+        ['zone', 'ceiling.regions[].finish.@key'],
+        ['ceiling', 'regions[].finish.@key'],
+    ].map(([kind, path]) => ({ kind, path, reason: 'Field name of an inline material record.' })),
+    ...[
+        ['zone', 'floor.regions[].id'],
+        ['zone', 'ceiling.regions[].id'],
+        ['ceiling', 'regions[].id'],
+        ['wall', 'faceRegions[].id'],
+    ].map(([kind, path]) => ({ kind, path, reason: 'Defines a paint region key.' })),
+    { kind: 'block', path: 'topology.vertices[].id', reason: 'Defines a topology key.' },
+    { kind: 'block', path: 'topology.edges[].id', reason: 'Defines a topology key.' },
+    { kind: 'block', path: 'topology.faces[].id', reason: 'Defines a topology key.' },
+    ...['assembly.layers[].id', 'assembly.backing[].id'].map((path) => ({
+        kind: '*',
+        path,
+        reason: 'Defines an assembly layer key (the `#layer:<id>` address).',
+    })),
+    {
+        kind: 'gutter',
+        path: 'outlets[].id',
+        reason: 'Defines an outlet key (see downspout.outletId).',
+    },
+    { kind: '*', path: 'stack[].id', reason: 'Defines a cabinet compartment key.' },
+    {
+        kind: 'procedural-item',
+        path: 'recipe',
+        reason: 'Inline versioned recipe (R7 stores recipes above 24 KiB by hash).',
+    },
+    { kind: 'procedural-item', path: 'parameters.@key', reason: 'Recipe parameter name.' },
+    // Scripted nodes (an authored item, or a window or door built from code) share one `source`;
+    // a room's floor script keeps the same record on its zone, a wall face's script on its wall.
+    ...[
+        ['item', 'source'],
+        ['window', 'source'],
+        ['door', 'source'],
+        ['column', 'source'],
+        ['zone', 'floor.script'],
+        ['wall', 'finishScripts.a'],
+        ['wall', 'finishScripts.b'],
+    ].flatMap(([kind, source]) => [
+        ...['anchors', 'lights', 'params', 'parts', 'slots'].map((list) => ({
+            kind,
+            path: `${source}.manifest.${list}[].id`,
+            reason: "Defines a key in a scripted node's compiled manifest, read from its script.",
+        })),
+        { kind, path: `${source}.params.@key`, reason: 'Script parameter name.' },
+        { kind, path: `${source}.params.*`, reason: 'Script parameter value.' },
+        {
+            kind,
+            path: `${source}.images.thumbnail`,
+            reason: `Content hash of a project artifact, like ${source}.artifact; forks carry it.`,
+        },
+    ]),
+    { kind: 'scan', path: 'layers.@key', reason: 'Layer visibility flag name.' },
+    {
+        kind: 'site',
+        path: 'presentation.display.disciplines.@key',
+        reason: 'Discipline display filter names.',
+    },
+    {
+        kind: 'site',
+        path: 'presentation.display.families.@key',
+        reason: 'Family display filter names.',
+    },
+    { kind: 'site', path: 'frontEdge', reason: "Index of the lot polygon's street-facing edge." },
+    ...[
+        'boundaries',
+        'codeBasis',
+        'elevation',
+        'flood',
+        'parcel',
+        'soils',
+        'structures',
+        'utilities',
+        'wetlands',
+        'zoning',
+    ].flatMap((section) => [
+        { kind: 'site', path: `dossier.${section}.@key`, reason: 'Pascal Map dossier fact name.' },
+        { kind: 'site', path: `dossier.${section}.*`, reason: 'Pascal Map dossier fact value.' },
+    ]),
+    { kind: 'site', path: 'dossier.sections.@key', reason: 'Pascal Map dossier section name.' },
+    { kind: 'roof-segment', path: 'fasciaHighEdge', reason: 'Flag for the shed high-edge board.' },
+    ...['measurement.points[]', 'measurement.base[]', 'anchors[]'].flatMap((prefix) => [
+        { kind: '*', path: `${prefix}.reference.parameters.@key`, reason: 'Feature parameter name.' },
+        { kind: '*', path: `${prefix}.reference.parameters.*`, reason: 'Feature parameter value.' },
+    ]),
+];
+// ─── metadata.* ───────────────────────────────────────────────────────────
+//
+// `metadata` is an open record in the schema, so its references are found in
+// the code that reads and writes it (`discoverMetadataKeys` over every editor
+// source; the private generator does the same for importers). A discovered
+// key matches a row path without its `metadata.` prefix and `[]` segments,
+// and a key is also covered by any row beneath it (the scanner cannot see
+// record values or array elements).
+const meta = (path, r) => row({ kind: '*', path: `metadata.${path}`, ...r });
+export const METADATA_REFERENCES = [
+    meta('authorSceneState.buildingId', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        remaps: ['clone-scene-graph', 'clone-level-subtree'],
+        dependents: ['metadata.authorSceneState'],
+        note: 'The building that owns this conversion baseline; a partial copy cannot overwrite its source building.',
+    }),
+    meta('authorSceneState.ids.*', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        remaps: ['clone-scene-graph', 'clone-level-subtree'],
+        dependents: ['metadata.authorSceneState.nodes'],
+        note: 'Stable source-to-node identities and the corresponding authored baseline snapshot; whole graph clones remap the snapshot recursively.',
+    }),
+    meta('managedByLeanTo', {
+        ...policy('node', 'internal', 'cascade', 'strip'),
+        targetKinds: ['lean-to-extension'],
+        note: 'The lean-to that generated this roof, segment, column or gutter.',
+    }),
+    meta('nodeSelectionProxyId', {
+        ...policy('node', 'control', 'drop', 'strip'),
+        note: 'Selecting this node selects the proxy instead (lean-to parts, cabinet runs).',
+    }),
+    ...['leanToCornerJoints', 'leanToFreestandingCanopyJoints'].map((key) => meta(`${key}.*.neighborId`, {
+        ...policy('node', 'connection', 'drop', 'strip'),
+        targetKinds: ['lean-to-extension'],
+        note: 'Joined neighbour lean-to per side.',
+    })),
+    meta('automaticRunEndCapOwnerId', {
+        ...policy('node', 'internal', 'cascade', 'strip'),
+        targetKinds: ['duct-segment', 'pipe-segment'],
+        dependents: ['metadata.automaticRunEndCapEndpoint'],
+        note: 'The run whose open end this automatic cap closes.',
+    }),
+    meta('conicalSourceWallId', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['wall'],
+        note: 'The wall a conical roof was generated from.',
+    }),
+    meta('cabinetCornerDerivedRun.sourceRunId', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['cabinet'],
+        dependents: [
+            'metadata.cabinetCornerDerivedRun.side',
+            'metadata.cabinetCornerDerivedRun.turnSide',
+            'metadata.cabinetCornerDerivedRun.role',
+        ],
+    }),
+    meta('cabinetCornerDerivedRun.sourceModuleId', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['cabinet-module'],
+    }),
+    meta('cabinetCornerSourceLink.linkedRunIds[]', {
+        ...policy('node', 'connection', 'drop', 'strip'),
+        targetKinds: ['cabinet'],
+        dependents: ['metadata.cabinetCornerSourceLink.side'],
+        note: 'Deleting the last linked run drops the link (run-ops).',
+    }),
+    meta('cabinetPresetWidthDebtBySource.@key', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['cabinet-module'],
+        note: 'Record keyed by the source module id.',
+    }),
+    meta('partnerIds[]', {
+        ...policy('node', 'connection', 'drop', 'strip'),
+        dependents: ['metadata.altJoint'],
+        note: 'Fitting partners of an alternate joint.',
+    }),
+    meta('autoOffset.minted[]', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        note: 'Elbows and risers minted by an automatic offset; deleted on rewind.',
+    }),
+    meta('autoOffset.base[].id', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        note: 'Restore patches for the run and its partners.',
+    }),
+    meta('autoOffset.group', {
+        ...policy('label', 'internal', 'drop', 'strip'),
+        note: 'Offset group label.',
+    }),
+    meta('floorPlanUrl', { ...policy('asset', 'content', 'freeze', 'keep') }),
+    ...[
+        'expressID',
+        'globalId',
+        'hostWallExpressID',
+        'ifcHostExpressID',
+        'ifcSimplification.mergedExpressIDs[]',
+    ].map((key) => meta(key, {
+        ...policy('source', 'content', 'freeze', 'keep'),
+        note: 'IFC provenance written by the IFC converter.',
+    })),
+    meta('poolManagedOpenings[].poolId', {
+        ...policy('node', 'control', 'drop', 'strip'),
+        note: 'Pool plugin cuts on a slab: the pool item that owns each opening.',
+    }),
+    meta('plateHoleAuthoring', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        note: 'The plate whose manual hole a floor opening was converted from.',
+    }),
+    meta('pascalNodeId', {
+        ...policy('source', 'content', 'freeze', 'strip'),
+        note: 'Import provenance: the Pascal node id an IFC element carried in its Pascal property set, so a re-import keeps identity.',
+    }),
+    meta('sourceIds[]', {
+        ...policy('source', 'content', 'freeze', 'strip'),
+        note: 'Import provenance: the source element ids an importer recorded (the /next converter writes them); find_by_type filters on them.',
+    }),
+    meta('balcony.id', {
+        ...policy('node', 'internal', 'drop', 'strip'),
+        targetKinds: ['slab'],
+        note: 'The deck a balcony railing or deck belongs to.',
+    }),
+];
+const described = (reason, paths) => paths.map((path) => ({ path, reason }));
+/** Metadata keys found in editor sources that are not references. */
+export const METADATA_NON_REFERENCES = [
+    { path: 'metadata.roomBoundary', reason: 'Boolean opt-out from room boundary detection.' },
+    ...described("author_scene's provenance: the payload's own ids on walls and openings, a room's seed, a level's elevation, a slab's finish, a wall's colour, and on the building the stored payload, the report and when it was written; none of it names a node.", [
+        'authorScene',
+        'authorScene.at',
+        'authorScene.color',
+        'authorScene.elevation',
+        'authorScene.finish',
+        'authorScene.id',
+        'authorScene.payload',
+        'authorScene.report',
+        'authorScene.seed',
+    ]),
+    ...described("An artifact's kind as the MCP host stores it (item, window, door, column): artifact metadata, not a node's.", ['kind']),
+    ...described('Flag, enum, number or tag; names nothing.', [
+        'annotationObstacle',
+        'annotationRole',
+        'autoGutter',
+        'autoGutterSide',
+        'autoRidgeVent',
+        'cabinetAdjacencyRevision',
+        'cabinetLayoutRevision',
+        'cabinetPresetNominalWidth',
+        'deferParentRebuild',
+        'drawingCoordinationLocked',
+        'floor',
+        'floorOwnershipMigrated',
+        'floorReassignmentHeight',
+        'footprintApproximated',
+        'generatedBy',
+        'ifcDerived',
+        'ifcSplit',
+        'isFloorplanPreview',
+        'isNew',
+        'isTransient',
+        'leanToDrainageSide',
+        'leanToGutterArcStraightEnds',
+        'leanToGutterEaveY',
+        'leanToGutterMitres',
+        'leanToPostIndex',
+        'leanToPostSide',
+        'leanToRole',
+        'leanToRoofPlane',
+        'legacyAutoOpeningsMigrated',
+        'legacyRoomMigrationPending',
+        'locked',
+        'openingManaged',
+        'ownerOpeningTarget',
+        'plateMigration',
+        'plateMigration.demoted',
+        'porch',
+        'renderPass',
+        'role',
+        'showTrimPlanes',
+        'storyShell',
+        'suppressedDimensionSegmentIndexes',
+    ]),
+    ...described("The site's hand-set code facts (Bones' `codeOverrides`: state, county, wind, snow…): numbers, flags and place names. Core reads only its `state`, to tell a US site from another, and names no node.", ['codeOverrides']),
+    ...described('Read as a truthy flag only; no editor writer.', [
+        'arrayModifier',
+        'curvedWindowMaster',
+        'linkedArray',
+    ]),
+    ...described('The owner pose an owned floor opening last followed: values, not ids.', [
+        'ownerPose',
+        'ownerPose.footprint',
+        'ownerPose.position',
+        'ownerPose.rotation',
+        'ownerPose.runLength',
+        'ownerPose.width',
+    ]),
+    ...described('Display or authoring label written by the MCP tools.', ['name']),
+    ...described('IFC attribute copy: a value or IFC label, not an id.', [
+        'elevation',
+        'height',
+        'sillHeight',
+        'sourceColor',
+        'typeName',
+        'polygon',
+        'material',
+        'materialLayers',
+        'ifcName',
+        'ifcType',
+        'objectType',
+        'predefinedType',
+        'operationType',
+        'ifcSimplification.mergedWallCount',
+    ]),
+    ...described('MCP template descriptor metadata, not scene-node metadata.', ['id', 'description']),
+    ...described('A `holeMetadata` entry held in a local named `metadata`; inventoried as holeMetadata[].', ['stairId', 'elevatorId', 'openingId', 'source', 'metadata']),
+    ...described('A `holeMetadata` array held in a local named `metadata`: an array method.', [
+        'flatMap',
+    ]),
+    ...described('Print-export artifact metadata, not scene-node metadata.', ['status']),
+    ...described('Script build provenance metadata, not scene-node metadata.', ['mount']),
+    ...described('Derived floorplan drawing metadata, not scene-node metadata.', [
+        'at',
+        'buildingId',
+        'levelM',
+        'side',
+        'sitePlan',
+        'textSizePt',
+    ]),
+    ...described("A room's declaration of artificial light and mechanical ventilation (set_zone_intent): booleans, not ids.", ['daylight']),
+    ...described('Site-plan facts kept on the node: values, not ids.', [
+        'flatwork',
+        'flatworkDims',
+        'services',
+        'streetNames',
+        'terrainSample',
+    ]),
+    ...described('Registry extension key, not scene-node metadata.', ['pascal:editor/floorplan']),
+    ...described('Next.js page metadata export, not scene-node metadata.', [
+        'robots',
+        'robots.index',
+        'title',
+    ]),
+    ...described('An authored object: what it stands in for, as add_object was told.', ['reason']),
+    ...described('Balcony state: a snapshot, flag or label; names nothing.', [
+        'balcony.options',
+        'balcony.role',
+        'balcony.source',
+        'balcony.guardBoundaryIndices',
+        'balcony.hiddenByStyle',
+        'balcony.options.depth',
+        'balcony.options.railing',
+    ]),
+];
+const bare = (path) => path.replace(/^metadata\./, '').replace(/\[\]/g, '');
+/**
+ * Whether a discovered metadata key is classified: a row at that path, a
+ * dependent of a row, or a row beneath it.
+ */
+export function metadataKeyClassified(key, references, nonReferences) {
+    const paths = references.flatMap((r) => [r.path, ...(r.dependents ?? [])]).map(bare);
+    return (paths.some((p) => p === key || p.startsWith(`${key}.`)) ||
+        nonReferences.some((r) => bare(r.path) === key));
+}