@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/interactable.js

@@ -0,0 +1,1219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interactableModuleId = interactableModuleId;
+exports.namespaceInteractableFragment = namespaceInteractableFragment;
+exports.moduleInteractableFragment = moduleInteractableFragment;
+exports.composeInteractableModuleManifest = composeInteractableModuleManifest;
+exports.composeInteractableManifest = composeInteractableManifest;
+exports.worldImportsOf = worldImportsOf;
+exports.worldEventContractOf = worldEventContractOf;
+exports.validateFragmentAgainstWorld = validateFragmentAgainstWorld;
+exports.addInteractable = addInteractable;
+exports.parseInteractablePosition = parseInteractablePosition;
+exports.instanceOrdinalOf = instanceOrdinalOf;
+exports.subtractInteractableContribution = subtractInteractableContribution;
+exports.updateInteractable = updateInteractable;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const api_1 = require("./api");
+const config_1 = require("./config");
+const install_1 = require("./install");
+const module_validation_1 = require("./module-validation");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const INSTALL_ROOT = 'helix_interactables';
+const INSTALL_INDEX = 'installed.json';
+const CLIENT_GLUE = (0, node_path_1.join)('src', 'helix.interactables.generated.ts');
+function objectRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function parseJson(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function hash(value, length = 7) {
+    return (0, node_crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, length);
+}
+function pascalSlug(slug) {
+    return slug
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join('');
+}
+function grammarPrefix(slug, instance) {
+    const readable = `itx${pascalSlug(slug)}${instance}_`;
+    return readable.length <= 16
+        ? readable
+        : `itx${hash(`${slug}:${instance}`, 8)}_`;
+}
+function grammarName(prefix, original) {
+    const direct = `${prefix}${original}`;
+    if (direct.length <= 32)
+        return direct;
+    const suffix = `_${hash(original, 6)}`;
+    return `${prefix}${original.slice(0, 32 - prefix.length - suffix.length)}${suffix}`;
+}
+function mapNames(names, prefix) {
+    const result = {};
+    const used = new Set();
+    for (const name of names) {
+        const mapped = grammarName(prefix, name);
+        if (used.has(mapped)) {
+            throw new Error(`namespace collision after encoding "${name}" as "${mapped}"`);
+        }
+        used.add(mapped);
+        result[name] = mapped;
+    }
+    return result;
+}
+/** Stable public module id for one placement; long package ids retain a readable prefix plus a collision hash. */
+function interactableModuleId(id, instance) {
+    const direct = `itx.${id}.${instance}`;
+    if (direct.length <= 32)
+        return direct;
+    const suffix = hash(`${id}:${instance}`, 8);
+    return `itx.${id.slice(0, 18)}.${suffix}`;
+}
+function interactableBank(id, version, checksumSha256) {
+    return `itx:${id}@${version}#${checksumSha256.toLowerCase()}`;
+}
+function capReport(program, moduleId) {
+    const state = objectRecord(program.state);
+    const counts = {
+        rules: Array.isArray(program.rules) ? program.rules.length : 0,
+        roomVars: Object.keys(objectRecord(state.roomVars)).length,
+        playerVars: Object.keys(objectRecord(state.playerVars)).length,
+        timers: Object.keys(objectRecord(program.timers)).length,
+        phases: Array.isArray(objectRecord(program.states).phases)
+            ? objectRecord(program.states).phases.length
+            : 0,
+        zones: Array.isArray(program.zones) ? program.zones.length : 0,
+        events: Object.keys(objectRecord(program.events)).length,
+        actions: Object.keys(objectRecord(program.actions)).length,
+    };
+    const limits = {
+        rules: helix_manifest_1.MULTIPLAYER_CAPS.rules,
+        roomVars: helix_manifest_1.MULTIPLAYER_CAPS.roomVars,
+        playerVars: helix_manifest_1.MULTIPLAYER_CAPS.playerVars,
+        timers: helix_manifest_1.MULTIPLAYER_CAPS.timers,
+        phases: helix_manifest_1.MULTIPLAYER_CAPS.phases,
+        zones: helix_manifest_1.MULTIPLAYER_CAPS.zones,
+        events: helix_manifest_1.MULTIPLAYER_CAPS.events,
+        actions: helix_manifest_1.MULTIPLAYER_CAPS.actions,
+    };
+    const percentages = Object.fromEntries(Object.keys(counts).map((name) => [
+        name,
+        Math.round((counts[name] / limits[name]) * 1000) / 10,
+    ]));
+    const warnings = Object.keys(counts)
+        .filter((name) => percentages[name] > 75)
+        .map((name) => `${moduleId ? `Module ${moduleId}` : 'Composition'} uses ${counts[name]}/${limits[name]} ${name} (${percentages[name]}%), above the 75% warning threshold.`);
+    return { caps: { ...counts, limits, percentages }, warnings };
+}
+function renameRecord(value, names, rewrite) {
+    return Object.fromEntries(Object.entries(objectRecord(value)).map(([key, entry]) => [
+        names[key] ?? key,
+        rewrite(entry),
+    ]));
+}
+function containsNode(value, predicate) {
+    if (Array.isArray(value)) {
+        return value.some((entry) => containsNode(entry, predicate));
+    }
+    if (!value || typeof value !== 'object')
+        return false;
+    const node = value;
+    return (predicate(node) ||
+        Object.values(node).some((entry) => containsNode(entry, predicate)));
+}
+function transformedPoint(point, transform) {
+    if (!Array.isArray(point) ||
+        point.length !== 3 ||
+        point.some((entry) => typeof entry !== 'number')) {
+        return point;
+    }
+    const [x, y, z] = point;
+    const angle = (transform.yawDeg * Math.PI) / 180;
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const sx = x * transform.scale;
+    const sz = z * transform.scale;
+    return [
+        transform.position[0] + sx * cos + sz * sin,
+        transform.position[1] + y * transform.scale,
+        transform.position[2] - sx * sin + sz * cos,
+    ];
+}
+function namespaceInteractableFragment(wrapperValue, slug, instance, placement) {
+    const wrapper = objectRecord(wrapperValue);
+    const source = objectRecord(wrapper.multiplayer);
+    const unsupported = Object.keys(source).filter((key) => ![
+        'minPlayers',
+        'state',
+        'states',
+        'timers',
+        'zones',
+        'events',
+        'actions',
+        'rules',
+    ].includes(key));
+    if (unsupported.length) {
+        throw new Error(`Phase-1 interactable composition does not yet support multiplayer.${unsupported.join(', multiplayer.')} — refusing to drop fields`);
+    }
+    const prefix = grammarPrefix(slug, instance);
+    const state = objectRecord(source.state);
+    const states = objectRecord(source.states);
+    const sourceRules = Array.isArray(source.rules) ? source.rules : [];
+    const sourcePhases = Array.isArray(states.phases)
+        ? states.phases.map(String)
+        : [];
+    const hasStateMachine = Object.keys(states).length > 0;
+    if (hasStateMachine) {
+        if (Object.keys(objectRecord(states.joinPolicy)).length > 0) {
+            throw new Error('State-machine composition cannot lower joinPolicy without changing late-join semantics.');
+        }
+        if (containsNode(source, (node) => Object.prototype.hasOwnProperty.call(node, 'timeInState'))) {
+            throw new Error('State-machine composition cannot lower timeInState without a per-module phase clock.');
+        }
+        if (sourceRules.some((rule) => objectRecord(objectRecord(rule).when).on === 'stateExit')) {
+            throw new Error('State-machine composition cannot lower stateExit while preserving old-phase reads.');
+        }
+        if (sourceRules.some((rule) => {
+            const record = objectRecord(rule);
+            return (objectRecord(record.when).on === 'stateEnter' &&
+                containsNode(record.then, (node) => node.do === 'transitionTo'));
+        })) {
+            throw new Error('State-machine composition cannot lower a transitionTo cascade fired from stateEnter.');
+        }
+    }
+    const modulePhaseVar = grammarName(prefix, 'phase');
+    const modulePhaseInitializedVar = grammarName(prefix, 'phaseInitialized');
+    const moduleBootPhase = grammarName(prefix, 'phaseBoot');
+    const roomVars = mapNames(Object.keys(objectRecord(state.roomVars)), prefix);
+    const playerVars = mapNames(Object.keys(objectRecord(state.playerVars)), prefix);
+    const timers = mapNames(Object.keys(objectRecord(source.timers)), prefix);
+    const actions = mapNames(Object.keys(objectRecord(source.actions)), prefix);
+    const events = mapNames(Object.keys(objectRecord(source.events)), prefix);
+    const zones = mapNames((Array.isArray(source.zones) ? source.zones : [])
+        .map((zone) => String(objectRecord(zone).id ?? ''))
+        .filter(Boolean), prefix);
+    const phases = mapNames(sourcePhases, prefix);
+    const scoped = (value) => {
+        if (value === 'room.phase' && hasStateMachine) {
+            return `room.${modulePhaseVar}`;
+        }
+        if (value.startsWith('room.')) {
+            const name = value.slice(5);
+            return roomVars[name] ? `room.${roomVars[name]}` : value;
+        }
+        const dot = value.lastIndexOf('.');
+        if (dot > 0) {
+            const name = value.slice(dot + 1);
+            if (playerVars[name])
+                return `${value.slice(0, dot + 1)}${playerVars[name]}`;
+        }
+        return value;
+    };
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if (!value || typeof value !== 'object')
+            return value;
+        const raw = value;
+        const out = Object.fromEntries(Object.entries(raw).map(([key, entry]) => [key, rewrite(entry)]));
+        for (const key of ['var', 'target', 'list', 'map', 'order', 'index']) {
+            if (typeof out[key] === 'string')
+                out[key] = scoped(out[key]);
+        }
+        if (out.op === 'aggregate' &&
+            typeof out.field === 'string' &&
+            playerVars[out.field]) {
+            out.field = playerVars[out.field];
+        }
+        if (typeof out.var === 'string' &&
+            'ref' in out &&
+            playerVars[out.var]) {
+            out.var = playerVars[out.var];
+        }
+        if (typeof out.timer === 'string' && timers[out.timer]) {
+            out.timer = timers[out.timer];
+        }
+        if (typeof out.event === 'string' && events[out.event]) {
+            out.event = events[out.event];
+        }
+        if (typeof out.zone === 'string' && zones[out.zone]) {
+            out.zone = zones[out.zone];
+        }
+        if (out.on === 'action' &&
+            typeof out.name === 'string' &&
+            actions[out.name]) {
+            out.name = actions[out.name];
+        }
+        if (out.do === 'transitionTo' && typeof out.phase === 'string') {
+            return {
+                do: 'set',
+                target: `room.${modulePhaseVar}`,
+                to: phases[out.phase] ?? out.phase,
+            };
+        }
+        if (out.on === 'stateEnter' && typeof out.phase === 'string') {
+            return {
+                on: 'varReached',
+                scope: 'room',
+                var: modulePhaseVar,
+                cmp: '==',
+                value: phases[out.phase] ?? out.phase,
+            };
+        }
+        const phaseVar = (candidate) => objectRecord(candidate).var === `room.${modulePhaseVar}`;
+        if (phaseVar(out.a) && typeof out.b === 'string' && phases[out.b]) {
+            out.b = phases[out.b];
+        }
+        if (phaseVar(out.b) && typeof out.a === 'string' && phases[out.a]) {
+            out.a = phases[out.a];
+        }
+        return out;
+    };
+    const rewrittenZones = (Array.isArray(source.zones) ? source.zones : []).map((value) => {
+        const zone = rewrite(value);
+        const originalId = String(objectRecord(value).id ?? '');
+        if (zones[originalId])
+            zone.id = zones[originalId];
+        if ('center' in zone)
+            zone.center = transformedPoint(zone.center, placement);
+        if (Array.isArray(zone.size)) {
+            zone.size = zone.size.map((entry) => typeof entry === 'number' ? entry * placement.scale : entry);
+        }
+        if (typeof zone.radius === 'number')
+            zone.radius *= placement.scale;
+        return zone;
+    });
+    const initialPhase = String(states.initial ?? '');
+    const rewrittenRules = sourceRules.map((rule) => rewrite(rule));
+    const initializationRules = hasStateMachine
+        ? [
+            {
+                when: { on: 'tick' },
+                if: {
+                    op: 'and',
+                    of: [
+                        {
+                            op: '==',
+                            a: { var: `room.${modulePhaseInitializedVar}` },
+                            b: true,
+                        },
+                        {
+                            op: '==',
+                            a: { var: `room.${modulePhaseVar}` },
+                            b: moduleBootPhase,
+                        },
+                    ],
+                },
+                then: [
+                    {
+                        do: 'set',
+                        target: `room.${modulePhaseVar}`,
+                        to: phases[initialPhase] ?? initialPhase,
+                    },
+                ],
+            },
+            {
+                when: { on: 'tick' },
+                if: {
+                    op: '==',
+                    a: { var: `room.${modulePhaseInitializedVar}` },
+                    b: false,
+                },
+                then: [
+                    {
+                        do: 'set',
+                        target: `room.${modulePhaseInitializedVar}`,
+                        to: true,
+                    },
+                ],
+            },
+        ]
+        : [];
+    const multiplayer = {
+        ...(typeof source.minPlayers === 'number'
+            ? { minPlayers: source.minPlayers }
+            : {}),
+        state: {
+            roomVars: {
+                ...renameRecord(state.roomVars, roomVars, rewrite),
+                ...(hasStateMachine
+                    ? {
+                        [modulePhaseVar]: {
+                            type: 'string',
+                            default: moduleBootPhase,
+                            enum: [
+                                moduleBootPhase,
+                                ...sourcePhases.map((phase) => phases[phase] ?? phase),
+                            ],
+                        },
+                        [modulePhaseInitializedVar]: {
+                            type: 'boolean',
+                            default: false,
+                        },
+                    }
+                    : {}),
+            },
+            playerVars: renameRecord(state.playerVars, playerVars, rewrite),
+        },
+        timers: renameRecord(source.timers, timers, rewrite),
+        zones: rewrittenZones,
+        events: renameRecord(source.events, events, rewrite),
+        actions: renameRecord(source.actions, actions, rewrite),
+        rules: [...initializationRules, ...rewrittenRules],
+    };
+    const parity = objectRecord(wrapper.parity);
+    const sourceRuleIds = Array.isArray(parity.ruleIds)
+        ? parity.ruleIds.map(String)
+        : [];
+    const conceptualNamespace = `itx.${slug}.${instance}.`;
+    const adapterRuleIds = hasStateMachine
+        ? ['adapter.phase.enterInitial', 'adapter.phase.armInitial']
+        : [];
+    const warnings = [
+        `The deployed grammar forbids dots in identifiers, so conceptual namespace ${conceptualNamespace} is encoded as ${prefix}.`,
+        'The deployed rule schema has no rule-id field; rule provenance is recorded index-aligned in installed.json and cannot be embedded in multiplayer.rules.',
+        ...(hasStateMachine
+            ? [
+                `The deployed grammar has one global room state machine; ${slug} phases were compatibly lowered to namespaced room variable ${modulePhaseVar} with varReached entry edges. Unsupported phase semantics are rejected before composition.`,
+            ]
+            : []),
+    ];
+    return {
+        multiplayer,
+        namespace: conceptualNamespace,
+        grammarPrefix: prefix,
+        actionNames: actions,
+        ruleIds: [...adapterRuleIds, ...sourceRuleIds].map((id) => `${conceptualNamespace}${id}`),
+        warnings,
+    };
+}
+/**
+ * Turn one verified package fragment into a module-v1 manifest entry. Rules stay in the immutable bank;
+ * declarations remain bare/local and placement remains in installed.json for the trusted packer envelope.
+ */
+function moduleInteractableFragment(wrapperValue, id, version, checksumSha256, instance) {
+    const wrapper = objectRecord(wrapperValue);
+    const source = objectRecord(wrapper.multiplayer);
+    const supported = new Set([
+        'minPlayers',
+        'state',
+        'entities',
+        'states',
+        'timers',
+        'zones',
+        'events',
+        'actions',
+        'exports',
+        'imports',
+        'randomStreams',
+        'rules',
+    ]);
+    const unsupported = Object.keys(source).filter((key) => !supported.has(key));
+    if (unsupported.length) {
+        throw new Error(`Module composition does not support multiplayer.${unsupported.join(', multiplayer.')} — refusing to drop fields`);
+    }
+    const moduleId = interactableModuleId(id, instance);
+    const bank = interactableBank(id, version, checksumSha256);
+    const module = { id: moduleId, bank };
+    for (const field of [
+        'state',
+        'entities',
+        'states',
+        'timers',
+        'zones',
+        'events',
+        'actions',
+        'exports',
+        'imports',
+        'randomStreams',
+    ]) {
+        if (Object.prototype.hasOwnProperty.call(source, field)) {
+            module[field] = structuredClone(source[field]);
+        }
+    }
+    const sourceRules = Array.isArray(source.rules) ? source.rules : [];
+    const parity = objectRecord(wrapper.parity);
+    const parityIds = Array.isArray(parity.ruleIds) ? parity.ruleIds.map(String) : [];
+    const localRuleIds = sourceRules.map((rule, index) => {
+        const embedded = objectRecord(rule).id;
+        return typeof embedded === 'string' && embedded.length > 0
+            ? embedded
+            : parityIds[index];
+    });
+    if (localRuleIds.some((ruleId) => !ruleId) || new Set(localRuleIds).size !== localRuleIds.length) {
+        throw new Error(`${bank} must provide one stable unique rule id per bank rule (embedded id or parity.ruleIds)`);
+    }
+    const actions = Object.keys(objectRecord(source.actions));
+    const budget = capReport(source, moduleId);
+    return {
+        moduleId,
+        bank,
+        module,
+        minPlayers: typeof source.minPlayers === 'number' ? source.minPlayers : 1,
+        namespace: `itx.${id}.${instance}.`,
+        grammarPrefix: '',
+        actionNames: Object.fromEntries(actions.map((name) => [name, name])),
+        ruleIds: localRuleIds.map((ruleId) => `m:${moduleId}|id:${ruleId}`),
+        caps: budget.caps,
+        warnings: budget.warnings,
+    };
+}
+/** Add/replace no flat declarations: one module entry is the entire server-side composition unit. */
+function composeInteractableModuleManifest(worldValue, contribution, options = {}) {
+    const world = structuredClone(objectRecord(worldValue));
+    if (world.helixVersion !== '0.3') {
+        throw new Error(`add-interactable requires a helixVersion "0.3" world; found "${String(world.helixVersion ?? 'missing')}"`);
+    }
+    const host = objectRecord(world.multiplayer);
+    const modules = Array.isArray(host.modules) ? [...host.modules] : [];
+    if (options.replace) {
+        const index = modules.findIndex((entry) => objectRecord(entry).id === options.replace.moduleId);
+        if (index === -1) {
+            throw new Error(`update aborted: installed module "${options.replace.moduleId}" is missing from helix.json`);
+        }
+        const expectedWorld = structuredClone(world);
+        expectedWorld.multiplayer = {
+            ...host,
+            modules: modules.map((entry, at) => at === index ? options.replace.expected : entry),
+        };
+        const normalizedExpected = (0, helix_manifest_1.validateManifest)(expectedWorld);
+        if (!normalizedExpected.valid) {
+            throw new Error(`update aborted: vendored module "${options.replace.moduleId}" no longer validates:\n${normalizedExpected.errors.join('\n')}`);
+        }
+        const expectedModules = normalizedExpected.manifest.multiplayer?.modules ?? [];
+        if (canonicalJson(modules[index]) !== canonicalJson(expectedModules[index])) {
+            throw new Error(`update aborted: installed module "${options.replace.moduleId}" was edited in helix.json since install — refusing to overwrite hand-edited game logic`);
+        }
+        modules[index] = contribution.module;
+    }
+    else {
+        if (modules.some((entry) => objectRecord(entry).id === contribution.moduleId)) {
+            throw new Error(`multiplayer.modules collision: module "${contribution.moduleId}" is already declared`);
+        }
+        modules.push(contribution.module);
+    }
+    world.multiplayer = {
+        ...host,
+        authoritative: true,
+        minPlayers: Math.max(Number(host.minPlayers ?? 1), contribution.minPlayers),
+        modules,
+    };
+    const permissions = new Set(Array.isArray(world.permissions) ? world.permissions.map(String) : []);
+    permissions.add('multiplayer');
+    world.permissions = [...permissions];
+    if (typeof world.maxPlayers !== 'number')
+        world.maxPlayers = 8;
+    const moduleBanks = Object.fromEntries(modules.flatMap((entry) => {
+        const bank = objectRecord(entry).bank;
+        if (typeof bank !== 'string' || !bank.includes('#'))
+            return [];
+        const hashAt = bank.lastIndexOf('#');
+        return [[bank.slice(0, hashAt), bank.slice(hashAt + 1)]];
+    }));
+    const validated = (0, helix_manifest_1.validateManifest)(world, {
+        moduleBanks,
+    });
+    if (!validated.valid) {
+        throw new Error(`Composed world fails the real manifest validator:\n${(0, module_validation_1.labelModuleValidationErrors)(validated.errors, world)
+            .map((error) => `  - ${error}`)
+            .join('\n')}`);
+    }
+    return {
+        manifest: validated.manifest,
+        caps: contribution.caps,
+        warnings: [...contribution.warnings, ...validated.warnings],
+    };
+}
+function assertNoCollision(left, right, label) {
+    const collisions = Object.keys(right).filter((key) => key in left);
+    if (collisions.length) {
+        throw new Error(`${label} collision after namespacing: ${collisions.join(', ')}`);
+    }
+}
+function composeInteractableManifest(worldValue, contribution, alreadyInstalled) {
+    const world = structuredClone(objectRecord(worldValue));
+    if (world.helixVersion !== '0.3') {
+        throw new Error(`add-interactable requires a helixVersion "0.3" world; found "${String(world.helixVersion ?? 'missing')}"`);
+    }
+    const host = objectRecord(world.multiplayer);
+    const incomingState = objectRecord(contribution.state);
+    const hostState = objectRecord(host.state);
+    for (const scope of ['roomVars', 'playerVars']) {
+        assertNoCollision(objectRecord(hostState[scope]), objectRecord(incomingState[scope]), `multiplayer.state.${scope}`);
+    }
+    for (const key of ['timers', 'events', 'actions']) {
+        assertNoCollision(objectRecord(host[key]), objectRecord(contribution[key]), `multiplayer.${key}`);
+    }
+    const hostZones = Array.isArray(host.zones) ? host.zones : [];
+    const incomingZones = Array.isArray(contribution.zones)
+        ? contribution.zones
+        : [];
+    const zoneIds = new Set(hostZones.map((zone) => objectRecord(zone).id));
+    const zoneCollision = incomingZones.find((zone) => zoneIds.has(objectRecord(zone).id));
+    if (zoneCollision) {
+        throw new Error(`multiplayer.zones collision after namespacing: ${String(objectRecord(zoneCollision).id)}`);
+    }
+    if (contribution.states && (host.states || alreadyInstalled > 0)) {
+        throw new Error('The deployed grammar has one room-scoped state machine, so a stateful interactable cannot compose with an existing host/module state machine. This Phase-1 limitation is reported, not silently merged.');
+    }
+    const multiplayer = {
+        ...host,
+        authoritative: true,
+        minPlayers: Math.max(Number(host.minPlayers ?? 1), Number(contribution.minPlayers ?? 1)),
+        state: {
+            ...hostState,
+            roomVars: {
+                ...objectRecord(hostState.roomVars),
+                ...objectRecord(incomingState.roomVars),
+            },
+            playerVars: {
+                ...objectRecord(hostState.playerVars),
+                ...objectRecord(incomingState.playerVars),
+            },
+        },
+        ...(contribution.states ? { states: contribution.states } : {}),
+        timers: {
+            ...objectRecord(host.timers),
+            ...objectRecord(contribution.timers),
+        },
+        zones: [...hostZones, ...incomingZones],
+        events: {
+            ...objectRecord(host.events),
+            ...objectRecord(contribution.events),
+        },
+        actions: {
+            ...objectRecord(host.actions),
+            ...objectRecord(contribution.actions),
+        },
+        rules: [
+            ...(Array.isArray(host.rules) ? host.rules : []),
+            ...(Array.isArray(contribution.rules) ? contribution.rules : []),
+        ],
+    };
+    world.multiplayer = multiplayer;
+    const permissions = new Set(Array.isArray(world.permissions) ? world.permissions.map(String) : []);
+    permissions.add('multiplayer');
+    world.permissions = [...permissions];
+    if (typeof world.maxPlayers !== 'number')
+        world.maxPlayers = 8;
+    const validated = (0, helix_manifest_1.validateManifest)(world);
+    if (!validated.valid) {
+        throw new Error(`Composed world fails the real manifest validator:\n${validated.errors.map((error) => `  - ${error}`).join('\n')}`);
+    }
+    const normalized = validated.manifest;
+    const finalMp = objectRecord(normalized.multiplayer);
+    const budget = capReport(finalMp);
+    return { manifest: normalized, caps: budget.caps, warnings: budget.warnings };
+}
+function readInstallIndex(worldDir) {
+    const path = (0, node_path_1.join)(worldDir, INSTALL_ROOT, INSTALL_INDEX);
+    if (!(0, node_fs_1.existsSync)(path))
+        return { version: 1, instances: [] };
+    const parsed = objectRecord(parseJson((0, node_fs_1.readFileSync)(path, 'utf8'), (0, node_path_1.relative)(worldDir, path)));
+    return {
+        version: 1,
+        instances: Array.isArray(parsed.instances)
+            ? parsed.instances
+            : [],
+    };
+}
+function clientGlue(installed) {
+    const imports = installed.instances.map((instance, index) => `import * as module${index} from ${JSON.stringify(`../${instance.destination.replaceAll('\\', '/')}/${instance.entry}`)};`);
+    const rows = installed.instances.map((instance, index) => ({
+        ...instance,
+        moduleIndex: index,
+    }));
+    return `${imports.join('\n')}
+
+// GENERATED by \`helix add-interactable\` — edit placement through the install command/data record, not here.
+const records = ${JSON.stringify(rows, null, 2)} as const;
+const modules = [${installed.instances.map((_entry, index) => `module${index}`).join(', ')}];
+
+export const interactableInstances = records.map((record) => ({
+  ...record,
+  module: modules[record.moduleIndex],
+}));
+
+export async function registerInteractables(host: {
+  registerInteractionMode?: (namespace: string, mode: unknown, record: unknown) => unknown;
+  registerInteractableRenderer?: (namespace: string, renderer: unknown, record: unknown) => unknown;
+  [key: string]: unknown;
+}): Promise<void> {
+  for (const instance of interactableInstances) {
+    const entry = instance.module as { mode?: unknown; createRenderer?: (context: unknown) => unknown };
+    if (!entry.mode || typeof entry.createRenderer !== 'function') {
+      throw new Error(instance.id + '@' + instance.version + ' must export { mode, createRenderer, placement }');
+    }
+    await host.registerInteractionMode?.(instance.namespace, entry.mode, instance);
+    const renderer = await entry.createRenderer({ host, instance, placement: instance.placement });
+    await host.registerInteractableRenderer?.(instance.namespace, renderer, instance);
+  }
+}
+`;
+}
+async function defaultFetchBytes(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`download failed (${response.status}) for ${url}`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+function fileUrl(baseUrl, path) {
+    if (!baseUrl)
+        throw new Error(`registry returned no base URL for ${path}`);
+    return `${baseUrl.replace(/\/$/, '')}/${path
+        .split('/')
+        .map(encodeURIComponent)
+        .join('/')}`;
+}
+function referenceOf(item) {
+    if (item.kind !== 'home_item' ||
+        item.category !== 'interactable' ||
+        item.usage !== 'place') {
+        throw new Error(`${item.slug} is not a placeable home_item/interactable Marketplace item`);
+    }
+    const interactive = objectRecord(objectRecord(item.metadata?.derived).interactive);
+    const types = Array.isArray(interactive.types)
+        ? interactive.types.map(String)
+        : [];
+    if (!types.includes('interactable')) {
+        throw new Error(`${item.slug} does not declare interactive.types=["interactable"]`);
+    }
+    const reference = objectRecord(Array.isArray(interactive.references) ? interactive.references[0] : null);
+    if (reference.kind !== 'interactable-bundle' ||
+        typeof reference.id !== 'string' ||
+        typeof reference.version !== 'string' ||
+        typeof reference.checksumSha256 !== 'string' ||
+        !SHA256_RE.test(reference.checksumSha256)) {
+        throw new Error(`${item.slug} has no valid interactable-bundle reference`);
+    }
+    return reference;
+}
+async function resolveItem(api, ref) {
+    if (UUID_RE.test(ref)) {
+        return api.requestItem('GET', `/api/v1/universal-items/${ref}`);
+    }
+    const query = new URLSearchParams({
+        search: ref,
+        kind: 'home_item',
+        category: 'interactable',
+        limit: '50',
+    });
+    const response = await api.request('GET', `/api/v1/universal-items?${query.toString()}`);
+    const item = response.items?.find((candidate) => candidate.slug === ref);
+    if (!item) {
+        throw new Error(`No published interactable Marketplace item has slug "${ref}"`);
+    }
+    return item;
+}
+function sameTransform(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/** Every `from: "world"` import a fragment declares. Tolerant of malformed input: the validator reports shape. */
+function worldImportsOf(fragment) {
+    const multiplayer = fragment?.multiplayer;
+    const imports = Array.isArray(multiplayer?.imports) ? multiplayer.imports : [];
+    return imports.filter((entry) => !!entry &&
+        typeof entry === 'object' &&
+        entry.from === 'world' &&
+        typeof entry.event === 'string');
+}
+/** What a host world actually offers a bank: its declared `multiplayer.events` and the subset it `exports`. */
+function worldEventContractOf(world) {
+    const multiplayer = world?.multiplayer;
+    const events = multiplayer?.events && typeof multiplayer.events === 'object' && !Array.isArray(multiplayer.events)
+        ? multiplayer.events
+        : {};
+    const exports = Array.isArray(multiplayer?.exports)
+        ? multiplayer.exports.filter((entry) => typeof entry === 'string')
+        : [];
+    return { events, exports };
+}
+/**
+ * Validate a verified bank fragment against the world it is being installed into.
+ *
+ * `validateInteractableServerFragment` can only resolve a fragment's `from: "world"` imports when it
+ * is told which events the host exports; called bare, every such import fails as "world does not
+ * export …" and every `event.payload.*` reference as "declared fields: none" (helix-creator-cli#122).
+ * At install time the real host is known, so the fragment is checked against what the world will
+ * genuinely export, and a world that does not export an imported event is refused with the fix named.
+ */
+function validateFragmentAgainstWorld(fragment, world) {
+    const { events, exports } = worldEventContractOf(world);
+    const missing = worldImportsOf(fragment)
+        .map((entry) => entry.event)
+        .filter((event, index, all) => all.indexOf(event) === index)
+        .filter((event) => !exports.includes(event) || !(event in events));
+    if (missing.length) {
+        return {
+            valid: false,
+            errors: missing.map((event) => `world does not export "${event}": add it to multiplayer.events and multiplayer.exports of the world manifest before installing this bank`),
+        };
+    }
+    return (0, helix_manifest_1.validateInteractableServerFragment)(fragment, { worldEvents: events });
+}
+async function resolveVerifiedBundle(api, fetchBytes, ref, progress, world) {
+    progress(`Resolving Marketplace item ${ref}`);
+    const item = await resolveItem(api, ref);
+    const reference = referenceOf(item);
+    const bundle = await api.requestItem('GET', `/api/v1/instant-packages/${reference.id}/versions/${encodeURIComponent(reference.version)}`);
+    if (bundle.kind !== 'interactable' ||
+        bundle.slug !== reference.id ||
+        bundle.version !== reference.version ||
+        bundle.checksumSha256 !== reference.checksumSha256) {
+        throw new Error(`Marketplace reference does not match the active registry version for ${reference.id}@${reference.version}`);
+    }
+    const manifestResult = (0, helix_manifest_1.validateInteractablePackageManifest)(bundle.payload);
+    if (!manifestResult.valid) {
+        throw new Error(`Registry returned an invalid interactable manifest:\n${manifestResult.errors.map((error) => `  - ${error}`).join('\n')}`);
+    }
+    const packageManifest = manifestResult.manifest;
+    if (packageManifest.id !== reference.id ||
+        packageManifest.version !== reference.version) {
+        throw new Error('Registry payload identity does not match its package version');
+    }
+    const allFiles = [
+        ...bundle.codeFiles.map((file) => ({ ...file, base: bundle.codeBaseUrl })),
+        ...bundle.assetFiles.map((file) => ({ ...file, base: bundle.assetBaseUrl })),
+    ];
+    const seen = new Set();
+    for (const file of allFiles) {
+        if (!helix_manifest_1.BUNDLE_PATH_PATTERN.test(file.path) || seen.has(file.path)) {
+            throw new Error(`registry returned an unsafe or duplicate bundle path: ${file.path}`);
+        }
+        if (!file.checksumSha256 || !SHA256_RE.test(file.checksumSha256)) {
+            throw new Error(`registry returned no verified file checksum for ${file.path}`);
+        }
+        seen.add(file.path);
+    }
+    progress(`Downloading and verifying ${allFiles.length} bundle files`);
+    const downloaded = new Map();
+    for (const file of allFiles) {
+        const bytes = await fetchBytes(fileUrl(file.base, file.path));
+        if (bytes.length !== file.size) {
+            throw new Error(`${file.path} size mismatch: registry says ${file.size}, downloaded ${bytes.length}`);
+        }
+        const checksum = (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+        const expectedChecksum = file.checksumSha256;
+        if (checksum !== expectedChecksum.toLowerCase()) {
+            throw new Error(`${file.path} checksum mismatch: registry says ${file.checksumSha256}, downloaded ${checksum}`);
+        }
+        downloaded.set(file.path, bytes);
+    }
+    const aggregate = (0, node_crypto_1.createHash)('sha256')
+        .update((0, helix_manifest_1.canonicalBundleChecksumInput)(allFiles.map(({ path, size, checksumSha256 }) => ({
+        path,
+        size,
+        checksumSha256: checksumSha256,
+    }))))
+        .digest('hex');
+    if (aggregate !== reference.checksumSha256.toLowerCase()) {
+        throw new Error(`bundle checksum mismatch: Marketplace pins ${reference.checksumSha256}, downloaded bundle is ${aggregate}`);
+    }
+    const fragmentBytes = downloaded.get(packageManifest.server.fragment);
+    if (!fragmentBytes) {
+        throw new Error(`server fragment ${packageManifest.server.fragment} is absent from the verified bundle`);
+    }
+    if (!downloaded.has(packageManifest.client.entry)) {
+        throw new Error(`client entry ${packageManifest.client.entry} is absent from the verified bundle`);
+    }
+    const fragment = parseJson(fragmentBytes.toString('utf8'), packageManifest.server.fragment);
+    const fragmentResult = validateFragmentAgainstWorld(fragment, world);
+    if (!fragmentResult.valid) {
+        throw new Error(`Verified server fragment fails the world grammar:\n${fragmentResult.errors.map((error) => `  - ${error}`).join('\n')}`);
+    }
+    const budgetErrors = (0, helix_manifest_1.compareInteractableBudget)(packageManifest.budget, fragmentResult.budget);
+    if (budgetErrors.length)
+        throw new Error(budgetErrors.join('\n'));
+    return { item, reference, packageManifest, fragment, downloaded };
+}
+async function addInteractable(worldDir, ref, options = {}) {
+    const progress = options.onProgress ?? (() => undefined);
+    const apiUrl = options.apiUrl ?? options.credentials?.apiUrl ?? config_1.DEFAULT_API_URL;
+    const api = options.deps?.api ??
+        new api_1.HelixApi(apiUrl, options.credentials?.token ?? null);
+    const fetchBytes = options.deps?.fetchBytes ?? defaultFetchBytes;
+    const transform = {
+        position: options.placement?.position ?? [0, 0, 0],
+        yawDeg: options.placement?.yawDeg ?? 0,
+        scale: options.placement?.scale ?? 1,
+    };
+    if (transform.position.some((entry) => !Number.isFinite(entry)) ||
+        !Number.isFinite(transform.yawDeg) ||
+        !Number.isFinite(transform.scale) ||
+        transform.scale <= 0) {
+        throw new Error('placement position/yaw/scale must be finite and scale must be > 0');
+    }
+    const manifestPath = install_1.WORLD_MANIFEST_LOCATIONS.map((location) => (0, node_path_1.join)(worldDir, location)).find(node_fs_1.existsSync);
+    if (!manifestPath) {
+        throw new Error('no helix.json found in the world root or public/');
+    }
+    const world = parseJson((0, node_fs_1.readFileSync)(manifestPath, 'utf8'), (0, node_path_1.relative)(worldDir, manifestPath));
+    const installed = readInstallIndex(worldDir);
+    const { item, reference, packageManifest, fragment, downloaded } = await resolveVerifiedBundle(api, fetchBytes, ref, progress, world);
+    const previous = installed.instances.find((entry) => entry.itemId === item.id &&
+        entry.version === reference.version &&
+        entry.checksumSha256 === reference.checksumSha256 &&
+        sameTransform(entry.placement.transform, transform));
+    if (previous) {
+        if (previous.moduleId) {
+            const moduleContribution = moduleInteractableFragment(fragment, reference.id, reference.version, reference.checksumSha256, instanceOrdinalOf(previous.namespace));
+            if (moduleContribution.moduleId !== previous.moduleId || (previous.bank && previous.bank !== moduleContribution.bank)) {
+                throw new Error(`installed.json module identity for ${previous.namespace} does not match its verified bundle`);
+            }
+            const verified = composeInteractableModuleManifest(world, moduleContribution, {
+                replace: { moduleId: previous.moduleId, expected: moduleContribution.module },
+            });
+            return {
+                itemId: item.id,
+                id: reference.id,
+                version: reference.version,
+                checksumSha256: reference.checksumSha256,
+                destination: (0, node_path_1.join)(worldDir, previous.destination),
+                manifestPath,
+                clientGluePath: (0, node_path_1.join)(worldDir, CLIENT_GLUE),
+                moduleId: previous.moduleId,
+                bank: previous.bank ?? moduleContribution.bank,
+                namespace: previous.namespace,
+                grammarPrefix: previous.grammarPrefix,
+                caps: verified.caps,
+                warnings: verified.warnings,
+                noOp: true,
+            };
+        }
+        const composed = composeInteractableManifest(world, {}, installed.instances.length);
+        return {
+            itemId: item.id,
+            id: reference.id,
+            version: reference.version,
+            checksumSha256: reference.checksumSha256,
+            destination: (0, node_path_1.join)(worldDir, previous.destination),
+            manifestPath,
+            clientGluePath: (0, node_path_1.join)(worldDir, CLIENT_GLUE),
+            namespace: previous.namespace,
+            grammarPrefix: previous.grammarPrefix,
+            caps: composed.caps,
+            warnings: composed.warnings,
+            noOp: true,
+        };
+    }
+    const instance = installed.instances.filter((entry) => entry.id === reference.id).length + 1;
+    const moduleContribution = moduleInteractableFragment(fragment, reference.id, reference.version, reference.checksumSha256, instance);
+    const composed = composeInteractableModuleManifest(world, moduleContribution);
+    const destinationRel = (0, node_path_1.join)(INSTALL_ROOT, `${reference.id}@${reference.version}`);
+    const destination = (0, node_path_1.join)(worldDir, destinationRel);
+    const record = {
+        itemId: item.id,
+        itemInstanceId: null,
+        ownerUserId: null,
+        creatorId: item.creatorId ?? null,
+        id: reference.id,
+        version: reference.version,
+        checksumSha256: reference.checksumSha256,
+        entry: packageManifest.client.entry,
+        destination: destinationRel,
+        moduleId: moduleContribution.moduleId,
+        bank: moduleContribution.bank,
+        namespace: moduleContribution.namespace,
+        grammarPrefix: moduleContribution.grammarPrefix,
+        actionNames: moduleContribution.actionNames,
+        placement: { transform, definition: packageManifest.placement },
+        ruleIds: moduleContribution.ruleIds,
+    };
+    const nextIndex = {
+        version: 1,
+        instances: [...installed.instances, record],
+    };
+    for (const [path, bytes] of downloaded) {
+        const target = (0, node_path_1.join)(destination, ...path.split('/'));
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+        (0, node_fs_1.writeFileSync)(target, bytes);
+    }
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(worldDir, INSTALL_ROOT), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(worldDir, INSTALL_ROOT, INSTALL_INDEX), `${JSON.stringify(nextIndex, null, 2)}\n`);
+    (0, node_fs_1.writeFileSync)(manifestPath, `${JSON.stringify(composed.manifest, null, 2)}\n`);
+    const gluePath = (0, node_path_1.join)(worldDir, CLIENT_GLUE);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(gluePath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(gluePath, clientGlue(nextIndex));
+    return {
+        itemId: item.id,
+        id: reference.id,
+        version: reference.version,
+        checksumSha256: reference.checksumSha256,
+        destination,
+        manifestPath,
+        clientGluePath: gluePath,
+        moduleId: moduleContribution.moduleId,
+        bank: moduleContribution.bank,
+        namespace: moduleContribution.namespace,
+        grammarPrefix: moduleContribution.grammarPrefix,
+        caps: composed.caps,
+        warnings: composed.warnings,
+        noOp: false,
+    };
+}
+function parseInteractablePosition(value) {
+    const parts = value.split(',').map(Number);
+    if (parts.length !== 3 || parts.some((entry) => !Number.isFinite(entry))) {
+        throw new Error(`position must be x,y,z in metres; got "${value}"`);
+    }
+    return parts;
+}
+// ---- In-place update -------------------------------------------------------------------------
+// The vendored bundle on disk (interactable.json + the server fragment) is self-sufficient to
+// re-derive exactly what an instance installed. Module-v1 records compare the normalized module
+// declaration, then replace it in place so declared order and module id survive. Legacy records
+// retain the old subtract/re-prefix path so already-published flat worlds remain updateable.
+/** The instance ordinal survives ONLY inside the conceptual namespace (`itx.<id>.<n>.`). */
+function instanceOrdinalOf(namespace) {
+    const match = /^itx\.(.+)\.([1-9][0-9]*)\.$/.exec(namespace);
+    if (!match)
+        throw new Error(`installed.json namespace "${namespace}" is not of the form itx.<id>.<n>.`);
+    return Number(match[2]);
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+// Subtract a previously composed contribution. Named declarations (vars, timers, events, actions,
+// zones) are removed by their namespaced keys; rules by key-order-insensitive structural equality.
+// A contributed rule that no longer matches is reported, not guessed about — the world may carry
+// creator edits. The sticky compose side effects (authoritative, minPlayers, maxPlayers,
+// permissions, ajv defaults) are deliberately left in place; no pristine-host snapshot exists.
+function subtractInteractableContribution(worldValue, contribution) {
+    const world = structuredClone(objectRecord(worldValue));
+    const multiplayer = objectRecord(world.multiplayer);
+    const state = objectRecord(multiplayer.state);
+    const contributionState = objectRecord(contribution.state);
+    for (const scope of ['roomVars', 'playerVars']) {
+        const host = { ...objectRecord(state[scope]) };
+        for (const key of Object.keys(objectRecord(contributionState[scope])))
+            delete host[key];
+        state[scope] = host;
+    }
+    multiplayer.state = state;
+    for (const section of ['timers', 'events', 'actions']) {
+        const host = { ...objectRecord(multiplayer[section]) };
+        for (const key of Object.keys(objectRecord(contribution[section])))
+            delete host[key];
+        multiplayer[section] = host;
+    }
+    const contributedZoneIds = new Set((Array.isArray(contribution.zones) ? contribution.zones : []).map((zone) => objectRecord(zone).id));
+    multiplayer.zones = (Array.isArray(multiplayer.zones) ? multiplayer.zones : []).filter((zone) => !contributedZoneIds.has(objectRecord(zone).id));
+    const hostRules = Array.isArray(multiplayer.rules) ? [...multiplayer.rules] : [];
+    const missingRules = [];
+    for (const rule of Array.isArray(contribution.rules) ? contribution.rules : []) {
+        const needle = canonicalJson(rule);
+        const index = hostRules.findIndex((candidate) => canonicalJson(candidate) === needle);
+        if (index === -1)
+            missingRules.push(JSON.stringify(rule));
+        else
+            hostRules.splice(index, 1);
+    }
+    multiplayer.rules = hostRules;
+    world.multiplayer = multiplayer;
+    return { world, missingRules };
+}
+async function updateInteractable(worldDir, ref, options = {}) {
+    const progress = options.onProgress ?? (() => undefined);
+    const apiUrl = options.apiUrl ?? options.credentials?.apiUrl ?? config_1.DEFAULT_API_URL;
+    const api = options.deps?.api ??
+        new api_1.HelixApi(apiUrl, options.credentials?.token ?? null);
+    const fetchBytes = options.deps?.fetchBytes ?? defaultFetchBytes;
+    const manifestPath = install_1.WORLD_MANIFEST_LOCATIONS.map((location) => (0, node_path_1.join)(worldDir, location)).find(node_fs_1.existsSync);
+    if (!manifestPath) {
+        throw new Error('no helix.json found in the world root or public/');
+    }
+    const installed = readInstallIndex(worldDir);
+    const worldForContract = parseJson((0, node_fs_1.readFileSync)(manifestPath, 'utf8'), (0, node_path_1.relative)(worldDir, manifestPath));
+    const { item, reference, packageManifest, fragment, downloaded } = await resolveVerifiedBundle(api, fetchBytes, ref, progress, worldForContract);
+    const targets = installed.instances.filter((record) => record.itemId === item.id || record.id === reference.id);
+    if (!targets.length) {
+        throw new Error(`no installed instance of ${reference.id} in this world — vendor it first with: helix add-interactable ${ref}`);
+    }
+    const rebranded = targets.find((record) => record.id !== reference.id);
+    if (rebranded) {
+        throw new Error(`the Marketplace item now references a different package (${rebranded.id} → ${reference.id}) — that is a replacement, not an update; remove the instance by hand and re-add`);
+    }
+    const stale = targets.filter((record) => record.version !== reference.version ||
+        (record.checksumSha256 ?? '').toLowerCase() !== reference.checksumSha256.toLowerCase());
+    const worldNow = parseJson((0, node_fs_1.readFileSync)(manifestPath, 'utf8'), (0, node_path_1.relative)(worldDir, manifestPath));
+    if (!stale.length) {
+        const moduleTargets = targets
+            .filter((record) => typeof record.moduleId === 'string')
+            .map((record) => ({
+            record,
+            contribution: moduleInteractableFragment(fragment, reference.id, reference.version, reference.checksumSha256, instanceOrdinalOf(record.namespace)),
+        }));
+        let verifiedWorld = worldNow;
+        const moduleWarnings = [];
+        for (const { record, contribution } of moduleTargets) {
+            if (contribution.moduleId !== record.moduleId || (record.bank && record.bank !== contribution.bank)) {
+                throw new Error(`installed.json module identity for ${record.namespace} does not match its verified bundle`);
+            }
+            const verified = composeInteractableModuleManifest(verifiedWorld, contribution, {
+                replace: { moduleId: record.moduleId, expected: contribution.module },
+            });
+            verifiedWorld = verified.manifest;
+            moduleWarnings.push(...verified.warnings);
+        }
+        const composed = composeInteractableManifest(worldNow, {}, installed.instances.length);
+        return {
+            itemId: item.id,
+            id: reference.id,
+            fromVersions: [...new Set(targets.map((record) => record.version))],
+            version: reference.version,
+            checksumSha256: reference.checksumSha256,
+            destination: (0, node_path_1.join)(worldDir, targets[0].destination),
+            manifestPath,
+            clientGluePath: (0, node_path_1.join)(worldDir, CLIENT_GLUE),
+            instances: 0,
+            moduleBudgets: moduleTargets.map(({ contribution }) => ({
+                moduleId: contribution.moduleId,
+                bank: contribution.bank,
+                caps: contribution.caps,
+            })),
+            caps: moduleTargets[0]?.contribution.caps ?? composed.caps,
+            warnings: moduleTargets.length
+                ? [...new Set(moduleWarnings)]
+                : composed.warnings,
+            noOp: true,
+        };
+    }
+    let world = worldNow;
+    const warnings = [];
+    let caps = null;
+    const moduleBudgets = [];
+    const destinationRel = (0, node_path_1.join)(INSTALL_ROOT, `${reference.id}@${reference.version}`);
+    const oldDestinations = new Set(stale.map((record) => record.destination));
+    const updatedRecords = new Map();
+    for (const record of stale) {
+        const ordinal = instanceOrdinalOf(record.namespace);
+        const oldDir = (0, node_path_1.join)(worldDir, record.destination);
+        const oldManifestFile = (0, node_path_1.join)(oldDir, 'interactable.json');
+        if (!(0, node_fs_1.existsSync)(oldManifestFile)) {
+            throw new Error(`${(0, node_path_1.relative)(worldDir, oldManifestFile)} is missing — the vendored bundle is what reverses the install; restore it (or remove the instance by hand) before updating`);
+        }
+        const oldManifestResult = (0, helix_manifest_1.validateInteractablePackageManifest)(parseJson((0, node_fs_1.readFileSync)(oldManifestFile, 'utf8'), (0, node_path_1.relative)(worldDir, oldManifestFile)));
+        if (!oldManifestResult.valid) {
+            throw new Error(`vendored interactable.json for ${record.id}@${record.version} is invalid:\n${oldManifestResult.errors.map((error) => `  - ${error}`).join('\n')}`);
+        }
+        const oldFragmentFile = (0, node_path_1.join)(oldDir, ...oldManifestResult.manifest.server.fragment.split('/'));
+        if (!(0, node_fs_1.existsSync)(oldFragmentFile)) {
+            throw new Error(`${(0, node_path_1.relative)(worldDir, oldFragmentFile)} is missing — the vendored bundle is what reverses the install; restore it (or remove the instance by hand) before updating`);
+        }
+        const oldFragment = parseJson((0, node_fs_1.readFileSync)(oldFragmentFile, 'utf8'), (0, node_path_1.relative)(worldDir, oldFragmentFile));
+        if (record.moduleId) {
+            const previousModule = moduleInteractableFragment(oldFragment, record.id, record.version, record.checksumSha256, ordinal);
+            if (previousModule.moduleId !== record.moduleId || (record.bank && record.bank !== previousModule.bank)) {
+                throw new Error(`update aborted: installed.json module identity for ${record.namespace} does not match its vendored bundle`);
+            }
+            const nextModule = moduleInteractableFragment(fragment, reference.id, reference.version, reference.checksumSha256, ordinal);
+            const composed = composeInteractableModuleManifest(world, nextModule, {
+                replace: { moduleId: record.moduleId, expected: previousModule.module },
+            });
+            world = composed.manifest;
+            caps = composed.caps;
+            warnings.push(...composed.warnings);
+            moduleBudgets.push({
+                moduleId: nextModule.moduleId,
+                bank: nextModule.bank,
+                caps: nextModule.caps,
+            });
+            updatedRecords.set(record, {
+                ...record,
+                version: reference.version,
+                checksumSha256: reference.checksumSha256,
+                entry: packageManifest.client.entry,
+                destination: destinationRel,
+                moduleId: nextModule.moduleId,
+                bank: nextModule.bank,
+                grammarPrefix: nextModule.grammarPrefix,
+                actionNames: nextModule.actionNames,
+                placement: { transform: record.placement.transform, definition: packageManifest.placement },
+                ruleIds: nextModule.ruleIds,
+            });
+            progress(`Updated module ${nextModule.moduleId} ${record.version} → ${reference.version}`);
+            continue;
+        }
+        const oldContribution = namespaceInteractableFragment(oldFragment, record.id, ordinal, record.placement.transform);
+        const subtracted = subtractInteractableContribution(world, oldContribution.multiplayer);
+        if (subtracted.missingRules.length) {
+            throw new Error(`update aborted: ${subtracted.missingRules.length} rule(s) composed by ${record.namespace} were edited or removed in the world manifest since install — refusing to guess about hand-edited game logic. Restore them (or remove the instance by hand), then retry:\n${subtracted.missingRules.map((rule) => `  - ${rule}`).join('\n')}`);
+        }
+        const renamed = namespaceInteractableFragment(fragment, reference.id, ordinal, record.placement.transform);
+        const composed = composeInteractableManifest(subtracted.world, renamed.multiplayer, installed.instances.length - 1);
+        world = composed.manifest;
+        caps = composed.caps;
+        warnings.push(...renamed.warnings, ...composed.warnings);
+        updatedRecords.set(record, {
+            ...record,
+            version: reference.version,
+            checksumSha256: reference.checksumSha256,
+            entry: packageManifest.client.entry,
+            destination: destinationRel,
+            grammarPrefix: renamed.grammarPrefix,
+            actionNames: renamed.actionNames,
+            placement: { transform: record.placement.transform, definition: packageManifest.placement },
+            ruleIds: renamed.ruleIds,
+        });
+        progress(`Updated ${record.namespace} ${record.version} → ${reference.version}`);
+    }
+    const nextInstances = installed.instances.map((record) => updatedRecords.get(record) ?? record);
+    const nextIndex = { version: 1, instances: nextInstances };
+    const destination = (0, node_path_1.join)(worldDir, destinationRel);
+    for (const [path, bytes] of downloaded) {
+        const target = (0, node_path_1.join)(destination, ...path.split('/'));
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(target), { recursive: true });
+        (0, node_fs_1.writeFileSync)(target, bytes);
+    }
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(worldDir, INSTALL_ROOT), { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(worldDir, INSTALL_ROOT, INSTALL_INDEX), `${JSON.stringify(nextIndex, null, 2)}\n`);
+    (0, node_fs_1.writeFileSync)(manifestPath, `${JSON.stringify(world, null, 2)}\n`);
+    const gluePath = (0, node_path_1.join)(worldDir, CLIENT_GLUE);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(gluePath), { recursive: true });
+    (0, node_fs_1.writeFileSync)(gluePath, clientGlue(nextIndex));
+    const survivingDestinations = new Set(nextInstances.map((record) => record.destination));
+    for (const old of oldDestinations) {
+        if (!survivingDestinations.has(old))
+            (0, node_fs_1.rmSync)((0, node_path_1.join)(worldDir, old), { recursive: true, force: true });
+    }
+    return {
+        itemId: item.id,
+        id: reference.id,
+        fromVersions: [...new Set(stale.map((record) => record.version))],
+        version: reference.version,
+        checksumSha256: reference.checksumSha256,
+        destination,
+        manifestPath,
+        clientGluePath: gluePath,
+        instances: stale.length,
+        moduleBudgets,
+        caps: caps,
+        warnings: [...new Set(warnings)],
+        noOp: false,
+    };
+}
+//# sourceMappingURL=interactable.js.map