@pascal-app/core 1.0.3 → 1.0.5

package/dist/store/derived-node-guard.d.ts

@@ -0,0 +1,84 @@
+import type { AnyNode, AnyNodeId, CeilingNode, SlabNode } from '../schema/index.js';
+/**
+ * Derived construction — floor plates and auto ceilings — is written by the
+ * structure reconciler, load migrations, history restore and host-patch
+ * application. Every other writer states *intent* (walls, separators, zones)
+ * and lets the reconciler derive the construction.
+ *
+ * The capability is this module-private token. It is deliberately NOT
+ * re-exported from the package index, so no caller outside `@pascal-app/core`
+ * can mint a write that bypasses the guard — the sanctioned entry points
+ * (`applyStructureReconciliation`, `detachDerivedNode`) hold it instead.
+ */
+export declare const DERIVED_WRITER_TOKEN: unique symbol;
+export type DerivedWriteOptions = {
+    /** Internal capability. Only core's reconciler paths can supply it. */
+    derivedWriter?: typeof DERIVED_WRITER_TOKEN;
+};
+export type DerivedSurfaceNode = SlabNode | CeilingNode;
+export type DerivedWriteOperation = 'create' | 'update' | 'delete';
+/** Thrown when a caller without the derived-writer capability writes derived construction. */
+export declare class DerivedNodeWriteError extends Error {
+    readonly operation: DerivedWriteOperation;
+    readonly nodeId: string;
+    readonly fields: readonly string[];
+    readonly code = "derived_node_write_refused";
+    constructor(operation: DerivedWriteOperation, nodeId: string, fields: readonly string[], message: string);
+}
+/**
+ * A slab or ceiling the reconciler owns. `boundary: 'auto'` is the current
+ * marker; `autoFromWalls: true` is the legacy one still present in scenes that
+ * have not been through the load migrations.
+ */
+export declare function isDerivedNode(node: AnyNode | null | undefined): node is DerivedSurfaceNode;
+/** Names the protected fields a patch would actually change on `current`. */
+export declare function derivedFieldViolations(current: DerivedSurfaceNode, data: Partial<AnyNode>, nodes?: Readonly<Record<string, AnyNode>>): string[];
+export type DerivedNodeChanges = {
+    create?: readonly {
+        node: AnyNode;
+    }[];
+    update?: readonly {
+        id: AnyNodeId;
+        data: Partial<AnyNode>;
+    }[];
+};
+type MutableDerivedChanges = {
+    create?: Array<{
+        node: AnyNode;
+        parentId?: AnyNodeId;
+    }>;
+    update?: Array<{
+        id: AnyNodeId;
+        data: Partial<AnyNode>;
+    }>;
+    delete?: AnyNodeId[];
+};
+export declare function convertDerivedPlateHoleWrites<T extends MutableDerivedChanges>(nodes: Readonly<Record<string, AnyNode>>, changes: T, options?: DerivedWriteOptions): T & MutableDerivedChanges;
+/** In-app writers retain authored edits without taking ownership from the reconciler. */
+export declare function filterDerivedNodeWrites<T extends DerivedNodeChanges>(nodes: Readonly<Record<string, AnyNode>>, changes: T, options?: DerivedWriteOptions): T;
+/**
+ * State-aware refusal guard for MCP bridges. In-app mutation boundaries use
+ * filterDerivedNodeWrites so a plugin cannot crash the scene with a derived write.
+ *
+ * Base construction remains editable; room plate finishes and elevations are intent
+ * on the owning zone or level.
+ */
+export declare function assertDerivedNodeWrites(nodes: Readonly<Record<string, AnyNode>>, changes: DerivedNodeChanges, options?: DerivedWriteOptions): void;
+/** The patch that converts a derived surface into an ordinary authored one. */
+export declare function derivedDetachPatch(node: DerivedSurfaceNode): Partial<AnyNode>;
+/**
+ * Explicit deletion of derived construction is an intent edit, not a refusal:
+ * removing a room's auto ceiling means "this room has no ceiling"
+ * (`hasCeiling: false`), removing its plate means "no floor" (`hasFloor:
+ * false`). Returns the zone updates that record it, so the reconciler does not
+ * simply rebuild what the user deleted.
+ *
+ * Cascaded descendants (deleting the level that owns the plate) carry no
+ * intent — the zone is going away with them.
+ */
+export declare function derivedDeletionIntent(nodes: Readonly<Record<string, AnyNode>>, ids: readonly AnyNodeId[]): {
+    id: AnyNodeId;
+    data: Partial<AnyNode>;
+}[];
+export {};
+//# sourceMappingURL=derived-node-guard.d.ts.map

package/dist/store/derived-node-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-node-guard.d.ts","sourceRoot":"","sources":["../../src/store/derived-node-guard.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAY,MAAM,WAAW,CAAA;AAKpF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,EAAE,OAAO,MAAwC,CAAA;AAElF,MAAM,MAAM,mBAAmB,GAAG;IAChC,uEAAuE;IACvE,aAAa,CAAC,EAAE,OAAO,oBAAoB,CAAA;CAC5C,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAA;AAEvD,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAElE,8FAA8F;AAC9F,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,QAAQ,CAAC,SAAS,EAAE,qBAAqB;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;IALpC,QAAQ,CAAC,IAAI,gCAA+B;IAE5C,YACW,SAAS,EAAE,qBAAqB,EAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,MAAM,EAAE,EAClC,OAAO,EAAE,MAAM,EAIhB;CACF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,IAAI,kBAAkB,CAI1F;AAkCD,6EAA6E;AAC7E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,EACtB,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CAyEV;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IACrC,MAAM,CAAC,EAAE,SAAS;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,EAAE,CAAA;CAC9D,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC3B,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,CAAA;IACvD,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,CAAC,CAAA;IACzD,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;CACrB,CAAA;AAyBD,wBAAgB,6BAA6B,CAAC,CAAC,SAAS,qBAAqB,EAC3E,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,mBAAmB,GAC5B,CAAC,GAAG,qBAAqB,CAiP3B;AAgHD,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,kBAAkB,EAClE,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,mBAAmB,GAC5B,CAAC,CAgDH;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CA2CN;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAM7E;AAQD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,GAAG,EAAE,SAAS,SAAS,EAAE,GACxB;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,EAAE,CAe7C"}

package/dist/store/derived-node-guard.js

@@ -0,0 +1,586 @@
+import { floorPlateAtGroundContact, floorPlateHoldsUnderside, supportDerivedFloorHeight, } from '../lib/floor-foundation-datum.js';
+import { expandFloorIntentChanges, floorIntentConflicts } from '../lib/floor-intent-changes.js';
+import { ownFloorIntentChanges } from '../lib/own-floor-intent.js';
+import { union } from '../lib/polygon-boolean.js';
+import { FloorOpeningNode, generateId } from '../schema/index.js';
+import { DEFAULT_SLAB_ELEVATION } from '../schema/nodes/slab.js';
+/**
+ * Derived construction — floor plates and auto ceilings — is written by the
+ * structure reconciler, load migrations, history restore and host-patch
+ * application. Every other writer states *intent* (walls, separators, zones)
+ * and lets the reconciler derive the construction.
+ *
+ * The capability is this module-private token. It is deliberately NOT
+ * re-exported from the package index, so no caller outside `@pascal-app/core`
+ * can mint a write that bypasses the guard — the sanctioned entry points
+ * (`applyStructureReconciliation`, `detachDerivedNode`) hold it instead.
+ */
+export const DERIVED_WRITER_TOKEN = Symbol('pascal.derived-writer');
+/** Thrown when a caller without the derived-writer capability writes derived construction. */
+export class DerivedNodeWriteError extends Error {
+    operation;
+    nodeId;
+    fields;
+    code = 'derived_node_write_refused';
+    constructor(operation, nodeId, fields, message) {
+        super(message);
+        this.operation = operation;
+        this.nodeId = nodeId;
+        this.fields = fields;
+        this.name = 'DerivedNodeWriteError';
+    }
+}
+/**
+ * A slab or ceiling the reconciler owns. `boundary: 'auto'` is the current
+ * marker; `autoFromWalls: true` is the legacy one still present in scenes that
+ * have not been through the load migrations.
+ */
+export function isDerivedNode(node) {
+    if (!node)
+        return false;
+    if (node.type !== 'slab' && node.type !== 'ceiling')
+        return false;
+    return node.boundary === 'auto' || node.autoFromWalls === true;
+}
+/** Fields whose value the reconciler owns on a derived surface. */
+const PROTECTED_FIELDS = {
+    slab: [
+        'elevation',
+        'plateRole',
+        'support',
+        'railing',
+        'polygon',
+        'zoneIds',
+        'boundary',
+        'autoFromWalls',
+        'parentId',
+    ],
+    ceiling: ['polygon', 'zoneId', 'boundary', 'autoFromWalls', 'parentId'],
+};
+function equal(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * The holes the reconciler cut for the room face, in order. Authored holes
+ * (manual cut-outs, stair and elevator openings) stay editable on a derived
+ * surface — the kernel re-applies them on every pass — so only the `room`
+ * entries are protected.
+ */
+function roomHoles(node) {
+    const holes = (node.holes ?? []);
+    const metadata = (node.holeMetadata ?? []);
+    return holes.filter((_, index) => metadata[index]?.source === 'room');
+}
+/** Names the protected fields a patch would actually change on `current`. */
+export function derivedFieldViolations(current, data, nodes) {
+    const patch = data;
+    const node = current;
+    const fixedUndersideEdit = nodes &&
+        current.type === 'slab' &&
+        current.plateRole === 'base' &&
+        floorPlateHoldsUnderside(nodes, current) &&
+        typeof patch.elevation === 'number' &&
+        typeof patch.thickness === 'number' &&
+        Math.abs(patch.elevation -
+            patch.thickness -
+            ((current.floorHeight ?? current.elevation) - current.thickness)) <= 1e-6;
+    const violations = PROTECTED_FIELDS[current.type].filter((field) => Object.hasOwn(patch, field) &&
+        !equal(patch[field], node[field]) &&
+        !(field === 'elevation' && fixedUndersideEdit));
+    if (current.type === 'slab')
+        for (const field of current.plateRole === 'base'
+            ? ['fillToTerrain']
+            : ['floorHeight', 'foundation'])
+            if (Object.hasOwn(patch, field) && !equal(patch[field], node[field]))
+                violations.push(field);
+    if (current.type === 'slab' && current.support === 'open')
+        for (const field of ['elevation', 'thickness', 'recessed', 'fillToTerrain'])
+            if (Object.hasOwn(patch, field) && !equal(patch[field], node[field]))
+                violations.push(field);
+    if (current.type === 'slab' &&
+        (current.plateRole === 'platform' || current.plateRole === 'sunken'))
+        for (const field of ['thickness', 'recessed', 'fillToTerrain', 'slots'])
+            if (Object.hasOwn(patch, field) && !equal(patch[field], node[field]))
+                violations.push(field);
+    if (current.type === 'slab' && (current.plateRole || current.support === 'open')) {
+        for (const field of ['material', 'materialPreset', 'recessed'])
+            if (Object.hasOwn(patch, field) && !equal(patch[field], node[field]))
+                violations.push(field);
+        if ((current.plateRole === 'base' || current.support === 'open') &&
+            Object.hasOwn(patch, 'slots')) {
+            const slots = patch.slots;
+            if ([...new Set([...Object.keys(current.slots ?? {}), ...Object.keys(slots ?? {})])].some((key) => !(current.support === 'open' ? ['underside'] : ['edge', 'riser', 'underside']).includes(key) && !equal(slots?.[key], current.slots?.[key])))
+                violations.push('slots');
+        }
+    }
+    if ((Object.hasOwn(patch, 'holes') || Object.hasOwn(patch, 'holeMetadata')) &&
+        !equal(roomHoles({ ...node, ...patch }), roomHoles(node))) {
+        violations.push('holes');
+    }
+    if (current.type === 'slab' &&
+        (Object.hasOwn(patch, 'holes') || Object.hasOwn(patch, 'holeMetadata'))) {
+        const proposed = { ...current, ...data };
+        const manual = (surface) => surface.holes.filter((_, index) => (surface.holeMetadata[index]?.source ?? 'manual') === 'manual');
+        if (!equal(manual(current), manual(proposed)) && !violations.includes('holes'))
+            violations.push('holes');
+    }
+    return violations;
+}
+function managedPoolOpenings(metadata) {
+    const value = metadata?.poolManagedOpenings;
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((entry) => {
+        const candidate = entry;
+        if (typeof candidate?.poolId !== 'string' || !Array.isArray(candidate.polygon))
+            return [];
+        const polygon = candidate.polygon;
+        if (!polygon.every((point) => Array.isArray(point) && point.length >= 2 && point.slice(0, 2).every(Number.isFinite)))
+            return [];
+        return [
+            {
+                poolId: candidate.poolId,
+                polygon: polygon.map((point) => point.slice(0, 2)),
+            },
+        ];
+    });
+}
+export function convertDerivedPlateHoleWrites(nodes, changes, options) {
+    if (options?.derivedWriter === DERIVED_WRITER_TOKEN || !changes.update?.length)
+        return changes;
+    const create = [...(changes.create ?? [])];
+    const update = [...changes.update];
+    const deleted = new Set(changes.delete ?? []);
+    const poolDesired = new Map();
+    const poolTouched = new Set();
+    const poolKey = (levelId, ownerId) => JSON.stringify([levelId, ownerId]);
+    for (const op of changes.update) {
+        const slab = nodes[op.id];
+        if (slab?.type !== 'slab' || !slab.parentId)
+            continue;
+        const patch = op.data;
+        for (const entry of managedPoolOpenings(slab.metadata))
+            poolTouched.add(poolKey(slab.parentId, entry.poolId));
+        if (!Object.hasOwn(patch, 'metadata'))
+            continue;
+        for (const entry of managedPoolOpenings(patch.metadata)) {
+            const key = poolKey(slab.parentId, entry.poolId);
+            poolTouched.add(key);
+            poolDesired.set(key, {
+                levelId: slab.parentId,
+                ownerId: entry.poolId,
+                polygon: entry.polygon,
+            });
+        }
+    }
+    let converted = false;
+    for (const key of poolTouched) {
+        const desired = poolDesired.get(key);
+        const [levelId, ownerId] = JSON.parse(key);
+        const existing = Object.values(nodes)
+            .filter((node) => node.type === 'floor-opening' &&
+            node.parentId === levelId &&
+            node.source === 'plugin:pool' &&
+            node.ownerId === ownerId)
+            .sort((a, b) => a.id.localeCompare(b.id));
+        for (const extra of existing.slice(desired ? 1 : 0))
+            deleted.add(extra.id);
+        if (desired) {
+            const old = existing[0];
+            if (old) {
+                if (holeKey(old.polygon) !== holeKey(desired.polygon) ||
+                    old.cutsAdjacent ||
+                    old.legacyPlateCuts)
+                    update.push({
+                        id: old.id,
+                        data: { polygon: desired.polygon, cutsAdjacent: false, legacyPlateCuts: undefined },
+                    });
+            }
+            else {
+                const node = FloorOpeningNode.parse({
+                    id: generateId('floor-opening'),
+                    parentId: levelId,
+                    name: 'Pool opening',
+                    polygon: desired.polygon,
+                    source: 'plugin:pool',
+                    ownerId,
+                    cutsAdjacent: false,
+                });
+                create.push({ node, parentId: levelId });
+            }
+        }
+        converted = true;
+    }
+    for (const [opIndex, op] of changes.update.entries()) {
+        const slab = nodes[op.id];
+        if (!isDerivedNode(slab) || slab.type !== 'slab' || !slab.parentId)
+            continue;
+        const patch = op.data;
+        if (!Object.hasOwn(patch, 'holes') && !Object.hasOwn(patch, 'holeMetadata'))
+            continue;
+        const holes = patch.holes ?? slab.holes;
+        const pluginWrite = Object.hasOwn(patch, 'metadata');
+        const sameGeometry = holes.length === slab.holes.length &&
+            (equal(holes, slab.holes) || equal(holes.map(holeKey).sort(), slab.holes.map(holeKey).sort()));
+        const unmaterializedAuthoredOpening = sameGeometry &&
+            !pluginWrite &&
+            Object.values(nodes).some((node) => node.type === 'floor-opening' &&
+                node.source === 'manual' &&
+                node.metadata?.plateHoleAuthoring === slab.id &&
+                !slab.holeMetadata.some((entry) => entry.source === 'floor-opening' && entry.openingId === node.id));
+        if (sameGeometry && !unmaterializedAuthoredOpening) {
+            const data = { ...patch };
+            delete data.holes;
+            delete data.holeMetadata;
+            update[opIndex] = { ...op, data: data };
+            converted = true;
+            continue;
+        }
+        const ownedMetadataByHole = new Map(slab.holes.flatMap((hole, index) => {
+            const entry = slab.holeMetadata[index];
+            return entry && entry.source !== 'manual' ? [[holeKey(hole), entry]] : [];
+        }));
+        const proposedMetadata = patch.holeMetadata ?? slab.holeMetadata;
+        const metadata = holes.map((hole, index) => {
+            const entry = proposedMetadata[index];
+            return (entry?.source ?? 'manual') === 'manual'
+                ? (ownedMetadataByHole.get(holeKey(hole)) ?? entry)
+                : entry;
+        });
+        if (!equal(metadata, patch.holeMetadata)) {
+            update[opIndex] = {
+                ...op,
+                data: { ...patch, holeMetadata: metadata },
+            };
+            converted = true;
+        }
+        const managed = managedPoolOpenings(patch.metadata ?? slab.metadata);
+        const managedKeys = new Set(managed.map((entry) => holeKey(entry.polygon)));
+        const roomKeys = new Set(slab.holes.flatMap((hole, index) => slab.holeMetadata[index]?.source === 'room' ? [holeKey(hole)] : []));
+        const poolWrite = Object.hasOwn(patch, 'metadata') &&
+            (managed.length > 0 || managedPoolOpenings(slab.metadata).length > 0);
+        const currentOpenings = new Map();
+        for (const entry of slab.holeMetadata) {
+            if (entry.source !== 'floor-opening' || !entry.openingId)
+                continue;
+            const opening = nodes[entry.openingId];
+            if (opening?.type === 'floor-opening' && opening.source === 'manual')
+                currentOpenings.set(opening.id, opening);
+        }
+        for (const node of Object.values(nodes)) {
+            if (node.type !== 'floor-opening' || node.source !== 'manual')
+                continue;
+            if (node.metadata?.plateHoleAuthoring === slab.id)
+                currentOpenings.set(node.id, node);
+        }
+        const retainedIds = new Set(metadata.flatMap((entry) => entry?.source === 'floor-opening' && entry.openingId ? [entry.openingId] : []));
+        const pending = [...currentOpenings.values()].filter((opening) => !retainedIds.has(opening.id));
+        const authored = holes.flatMap((polygon, index) => (metadata[index]?.source ?? 'manual') === 'manual' &&
+            !managedKeys.has(holeKey(polygon)) &&
+            !roomKeys.has(holeKey(polygon))
+            ? [{ polygon, openingId: metadata[index]?.openingId }]
+            : []);
+        let manualConverted = false;
+        for (const { polygon, openingId } of authored) {
+            const exact = [...currentOpenings.values()].find((opening) => opening.id === openingId || holeKey(opening.polygon) === holeKey(polygon));
+            const old = exact ?? pending.shift();
+            if (old) {
+                const index = pending.findIndex((candidate) => candidate.id === old.id);
+                if (index >= 0)
+                    pending.splice(index, 1);
+                if (holeKey(old.polygon) !== holeKey(polygon))
+                    update.push({ id: old.id, data: { polygon, cutsAdjacent: false } });
+            }
+            else if (!create.some((entry) => entry.node.type === 'floor-opening' &&
+                entry.node.parentId === slab.parentId &&
+                holeKey(entry.node.polygon) === holeKey(polygon))) {
+                const hostZoneId = slab.support === 'open' && slab.zoneIds?.length === 1 ? slab.zoneIds[0] : undefined;
+                const node = FloorOpeningNode.parse({
+                    id: generateId('floor-opening'),
+                    parentId: slab.parentId,
+                    name: 'Floor opening',
+                    polygon,
+                    ...(hostZoneId ? { hostZoneId } : {}),
+                    metadata: { plateHoleAuthoring: slab.id },
+                    cutsAdjacent: false,
+                });
+                create.push({ node, parentId: slab.parentId });
+            }
+            manualConverted = true;
+        }
+        const managedHoles = (surfaceHoles, surfaceMetadata) => surfaceHoles.flatMap((hole, index) => surfaceMetadata[index]?.source === 'stair' || surfaceMetadata[index]?.source === 'elevator'
+            ? [{ hole, metadata: surfaceMetadata[index] }]
+            : []);
+        const systemWrite = !equal(managedHoles(slab.holes, slab.holeMetadata), managedHoles(holes, metadata));
+        if (!pluginWrite && !poolWrite && !systemWrite)
+            for (const opening of pending) {
+                deleted.add(opening.id);
+                manualConverted = true;
+            }
+        const hasManual = holes.some((polygon, index) => (metadata[index]?.source ?? 'manual') === 'manual' &&
+            !managedKeys.has(holeKey(polygon)) &&
+            !roomKeys.has(holeKey(polygon)));
+        const hasManaged = holes.some((polygon, index) => (metadata[index]?.source ?? 'manual') === 'manual' && managedKeys.has(holeKey(polygon)));
+        const preservedOpenings = pluginWrite || poolWrite || systemWrite
+            ? slab.holes.flatMap((hole, index) => {
+                const entry = slab.holeMetadata[index];
+                return entry &&
+                    entry.source !== 'manual' &&
+                    !holes.some((candidate) => holeKey(candidate) === holeKey(hole))
+                    ? [{ hole, metadata: entry }]
+                    : [];
+            })
+            : [];
+        if (!manualConverted && !hasManual && !hasManaged && !preservedOpenings.length)
+            continue;
+        const retained = holes.flatMap((hole, index) => (metadata[index]?.source ?? 'manual') === 'manual'
+            ? []
+            : [{ hole, metadata: metadata[index] ?? { source: 'manual' } }]);
+        retained.push(...preservedOpenings);
+        update[opIndex] = {
+            ...op,
+            data: {
+                ...patch,
+                holes: retained.map((entry) => entry.hole),
+                holeMetadata: retained.map((entry) => entry.metadata),
+            },
+        };
+        converted = true;
+    }
+    return converted
+        ? { ...changes, create, update, delete: [...deleted] }
+        : changes;
+}
+const warnedFields = new Set();
+function warnFilteredFields(nodeId, fields) {
+    if (process.env.NODE_ENV === 'production' || process.env.NODE_ENV === 'test')
+        return;
+    const fresh = fields.filter((field) => !warnedFields.has(`${nodeId}:${field}`));
+    if (!fresh.length)
+        return;
+    for (const field of fresh)
+        warnedFields.add(`${nodeId}:${field}`);
+    try {
+        console.warn(`[Scene] Preserved derived ownership of ${fresh.join(', ')} on ${nodeId}`);
+    }
+    catch {
+        // Diagnostics must not turn a filtered plugin write into a scene failure.
+    }
+}
+function holeKey(hole) {
+    return JSON.stringify(union([hole]));
+}
+function mergeRoomHoles(current, patch) {
+    const rooms = current.holes.flatMap((hole, index) => {
+        const metadata = current.holeMetadata[index];
+        return metadata?.source === 'room' ? [{ hole, metadata, key: holeKey(hole) }] : [];
+    });
+    if (!rooms.length)
+        return patch;
+    const holes = [];
+    const holeMetadata = [];
+    const emitted = new Set();
+    const proposedHoles = Object.hasOwn(patch, 'holes') ? (patch.holes ?? []) : current.holes;
+    const proposedMetadata = Object.hasOwn(patch, 'holeMetadata')
+        ? (patch.holeMetadata ?? [])
+        : current.holeMetadata;
+    for (const [index, hole] of proposedHoles.entries()) {
+        const key = holeKey(hole);
+        const room = rooms.find((entry) => entry.key === key);
+        if (room) {
+            if (emitted.has(room.key))
+                continue;
+            emitted.add(room.key);
+            holes.push(room.hole);
+            holeMetadata.push(room.metadata);
+        }
+        else {
+            holes.push(hole);
+            holeMetadata.push(proposedMetadata[index] ?? { source: 'manual' });
+        }
+    }
+    for (const room of rooms) {
+        if (emitted.has(room.key))
+            continue;
+        emitted.add(room.key);
+        holes.push(room.hole);
+        holeMetadata.push(room.metadata);
+    }
+    return { ...patch, holes, holeMetadata };
+}
+const createdNodes = (create) => new Map((create ?? []).map(({ node }) => [node.id, node]));
+/**
+ * Construction copied together with the level and rooms it stands for (a
+ * duplicated level) stays derived: the reconciler adopts it for the copied
+ * rooms, as it does a loaded scene's, instead of building a second plate
+ * beside a manual copy.
+ */
+function arrivesWithItsLevel(node, created) {
+    return (created.get(node.parentId ?? '')?.type === 'level' &&
+        linkedZoneIds(node).every((id) => created.get(id)?.type === 'zone'));
+}
+function groundPlateRebases(nodes, changes) {
+    // Inserting a storey below a ground plate changes its construction model:
+    // retain thickness, remove the foundation, and rest its underside upstairs.
+    const movedLevels = new Set(changes.update?.flatMap(({ id, data }) => nodes[id]?.type === 'level' && 'level' in data && data.level !== nodes[id].level ? [id] : []));
+    if (!movedLevels.size)
+        return new Set();
+    const draft = {
+        ...nodes,
+        ...Object.fromEntries(changes.create?.map(({ node }) => [node.id, node]) ?? []),
+    };
+    for (const { id, data } of changes.update ?? [])
+        if (movedLevels.has(id))
+            draft[id] = { ...draft[id], ...data };
+    return new Set(changes.update?.flatMap(({ id, data }) => {
+        const plate = nodes[id];
+        if (plate?.type !== 'slab' ||
+            plate.plateRole !== 'base' ||
+            !movedLevels.has(plate.parentId) ||
+            !floorPlateAtGroundContact(nodes, plate) ||
+            floorPlateAtGroundContact(draft, plate))
+            return [];
+        const patch = data;
+        const reference = supportDerivedFloorHeight(draft, plate);
+        return Object.hasOwn(patch, 'floorHeight') &&
+            patch.floorHeight === undefined &&
+            patch.foundation?.type === 'none' &&
+            (patch.thickness === undefined || patch.thickness === plate.thickness) &&
+            patch.referenceFloorElevation === reference &&
+            typeof patch.elevation === 'number' &&
+            Math.abs(patch.elevation - (reference - DEFAULT_SLAB_ELEVATION + plate.thickness)) <= 1e-6
+            ? [id]
+            : [];
+    }));
+}
+/** In-app writers retain authored edits without taking ownership from the reconciler. */
+export function filterDerivedNodeWrites(nodes, changes, options) {
+    if (options?.derivedWriter === DERIVED_WRITER_TOKEN)
+        return changes;
+    if (changes.update) {
+        const own = ownFloorIntentChanges(nodes, changes.update);
+        const update = own.conflicts.length ? [] : expandFloorIntentChanges(nodes, own.updates);
+        changes = { ...changes, update };
+    }
+    const created = createdNodes(changes.create);
+    const rebases = groundPlateRebases(nodes, changes);
+    return {
+        ...changes,
+        ...(changes.create && {
+            create: changes.create.map((op) => {
+                if (!isDerivedNode(op.node) || arrivesWithItsLevel(op.node, created))
+                    return op;
+                const node = { ...op.node };
+                const fields = ['plateRole', 'boundary', 'zoneIds', 'zoneId', 'autoFromWalls'];
+                warnFilteredFields(op.node.id, fields.filter((field) => Object.hasOwn(node, field)));
+                for (const field of fields)
+                    delete node[field];
+                return { ...op, node: node };
+            }),
+        }),
+        ...(changes.update && {
+            update: changes.update.flatMap((op) => {
+                const current = nodes[op.id];
+                if (!isDerivedNode(current))
+                    return [op];
+                const fields = derivedFieldViolations(current, op.data, nodes).filter((field) => field !== 'holes' && !(field === 'elevation' && rebases.has(op.id)));
+                let data = { ...op.data };
+                for (const field of fields)
+                    delete data[field];
+                if (Object.hasOwn(data, 'holes') || Object.hasOwn(data, 'holeMetadata')) {
+                    const merged = mergeRoomHoles(current, data);
+                    for (const field of ['holes', 'holeMetadata']) {
+                        const proposed = Object.hasOwn(data, field) ? data[field] : current[field];
+                        if (Object.hasOwn(merged, field) && !equal(merged[field], proposed))
+                            fields.push(field);
+                    }
+                    data = merged;
+                }
+                warnFilteredFields(op.id, fields);
+                const node = current;
+                if (Object.entries(data).every(([field, value]) => equal(value, node[field])))
+                    return [];
+                return [{ ...op, data: data }];
+            }),
+        }),
+    };
+}
+/**
+ * State-aware refusal guard for MCP bridges. In-app mutation boundaries use
+ * filterDerivedNodeWrites so a plugin cannot crash the scene with a derived write.
+ *
+ * Base construction remains editable; room plate finishes and elevations are intent
+ * on the owning zone or level.
+ */
+export function assertDerivedNodeWrites(nodes, changes, options) {
+    if (options?.derivedWriter === DERIVED_WRITER_TOKEN)
+        return;
+    const own = ownFloorIntentChanges(nodes, changes.update ?? []);
+    const conflicts = [
+        ...own.conflicts,
+        ...floorIntentConflicts(nodes, expandFloorIntentChanges(nodes, own.updates), changes.create?.map(({ node }) => node)),
+    ];
+    if (conflicts.length)
+        throw Object.assign(new Error(conflicts.map((c) => c.message).join(' ')), {
+            code: 'room_floor_conflict',
+            conflicts,
+        });
+    const created = createdNodes(changes.create);
+    const rebases = groundPlateRebases(nodes, changes);
+    for (const { node } of changes.create ?? []) {
+        if (!isDerivedNode(node) || arrivesWithItsLevel(node, created))
+            continue;
+        throw new DerivedNodeWriteError('create', node.id, node.type === 'slab' ? ['boundary', 'zoneIds'] : ['boundary', 'zoneId'], `Refusing to create the derived ${node.type} ${node.id}. Floor plates and auto ceilings are derived from rooms: create walls and a zone (spaceRole: "room") and the structure reconciler builds them.`);
+    }
+    for (const { id, data } of changes.update ?? []) {
+        const current = nodes[id];
+        if (!isDerivedNode(current))
+            continue;
+        const fields = derivedFieldViolations(current, data, nodes).filter((field) => !(field === 'elevation' && rebases.has(id)));
+        if (fields.length === 0)
+            continue;
+        throw new DerivedNodeWriteError('update', id, fields, current.type === 'slab' && current.plateRole === 'base'
+            ? `Refusing to change ${fields.join(', ')} on the derived slab ${id} (base plate). Use set_floor_foundation to change its floor height.`
+            : `Refusing to change ${fields.join(', ')} on the derived ${current.type} ${id}. The structure reconciler owns it: edit the room zone's intent instead, or convert the surface to manual with detachDerivedNode.`);
+    }
+}
+/** The patch that converts a derived surface into an ordinary authored one. */
+export function derivedDetachPatch(node) {
+    return (node.type === 'slab'
+        ? { autoFromWalls: false, boundary: undefined, zoneIds: undefined, plateRole: undefined }
+        : { autoFromWalls: false, boundary: undefined, zoneId: undefined });
+}
+/** The zone ids whose construction intent a derived surface stands for. */
+function linkedZoneIds(node) {
+    const ids = node.type === 'slab' ? (node.zoneIds ?? []) : node.zoneId ? [node.zoneId] : [];
+    return [...new Set(ids)];
+}
+/**
+ * Explicit deletion of derived construction is an intent edit, not a refusal:
+ * removing a room's auto ceiling means "this room has no ceiling"
+ * (`hasCeiling: false`), removing its plate means "no floor" (`hasFloor:
+ * false`). Returns the zone updates that record it, so the reconciler does not
+ * simply rebuild what the user deleted.
+ *
+ * Cascaded descendants (deleting the level that owns the plate) carry no
+ * intent — the zone is going away with them.
+ */
+export function derivedDeletionIntent(nodes, ids) {
+    const deleted = new Set(ids);
+    const intent = new Map();
+    for (const id of ids) {
+        const node = nodes[id];
+        if (!isDerivedNode(node))
+            continue;
+        const field = node.type === 'ceiling' ? 'hasCeiling' : 'hasFloor';
+        for (const zoneId of linkedZoneIds(node)) {
+            const zone = nodes[zoneId];
+            if (zone?.type !== 'zone' || deleted.has(zone.id))
+                continue;
+            if (zone[field] === false)
+                continue;
+            intent.set(zone.id, { ...intent.get(zone.id), [field]: false });
+        }
+    }
+    return [...intent].map(([id, data]) => ({ id, data: data }));
+}