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

package/dist/continuum/workflow.js

@@ -0,0 +1,592 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContinuumPublisher = exports.PublicListingPolicyError = void 0;
+exports.preflightContinuumPublicationIntent = preflightContinuumPublicationIntent;
+const node_os_1 = require("node:os");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const continuum_1 = require("../sceneElements/continuum");
+const semantic_1 = require("../sceneImport/semantic");
+const api_1 = require("../api");
+const objectUpload_1 = require("./objectUpload");
+const renditionManifest_1 = require("../vehicle/renditionManifest");
+const authoring_1 = require("./authoring");
+const identity_1 = require("./identity");
+const state_1 = require("./state");
+const cliAuthority_1 = require("./cliAuthority");
+const types_1 = require("./types");
+class PublicListingPolicyError extends Error {
+}
+exports.PublicListingPolicyError = PublicListingPolicyError;
+class ContinuumPublisher {
+    api;
+    checkpoints;
+    leaseTtlSeconds;
+    constructor(api, options = {}) {
+        this.api = api;
+        const root = options.stateDirectory ?? (0, node_path_1.join)((0, node_os_1.homedir)(), '.helix', 'continuum', 'jobs');
+        this.checkpoints = new state_1.ContinuumCheckpointStore(root);
+        this.leaseTtlSeconds = options.leaseTtlSeconds ?? 300;
+    }
+    async publish(input, conversion) {
+        const invocation = input;
+        input = { ...input, sourceDigest: input.sourceDigest.toLowerCase() };
+        (0, cliAuthority_1.transferCliPublicListingConfirmation)(invocation, input);
+        const normalized = preflight(input);
+        const normalizedIntent = sanitizedIntent(input);
+        const jobId = (0, state_1.publicationJobId)({
+            sourceDigest: input.sourceDigest, projectId: input.projectId,
+            intent: normalizedIntent, compilerVersion: types_1.CONTINUUM_CREATOR_COMPILER_VERSION,
+            contractVersion: types_1.CONTINUUM_CREATOR_CONTRACT,
+        });
+        return this.checkpoints.runExclusive(jobId, async () => {
+            const existing = await this.checkpoints.read(jobId);
+            if (existing?.receipt)
+                return normalizeReceipt(existing.receipt);
+            const listingPolicies = await this.authorizeListings(input);
+            const base = () => ({
+                schema: 'helix.creator.continuum-checkpoint/1', revision: 0, jobId,
+                sourceDigest: input.sourceDigest, projectId: input.projectId,
+                intentDigest: (0, state_1.canonicalIntentDigest)(normalizedIntent), objects: {}, listingIds: {},
+            });
+            let checkpoint = existing ?? base();
+            let objectsPublished = 0;
+            let objectsReused = Object.keys(checkpoint.objects).length;
+            let versionSealed = false;
+            for (const object of normalized.objects) {
+                if ((0, state_1.checkpointHasObject)(checkpoint, object.reference.cid))
+                    continue;
+                const record = await withThrottleBackoff(() => this.publishObject(object));
+                assertObjectReceipt(object.reference, record);
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.objects[object.reference.cid] = true; });
+                objectsPublished += 1;
+            }
+            if (!checkpoint.packageCreated) {
+                await this.api.createPackage(input.package, input.packagePublication);
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.packageCreated = true; });
+            }
+            if (!checkpoint.versionCreated) {
+                const created = await this.api.createPackageVersion(input.package.id, input.packageVersion);
+                const lifecycle = packageVersionLifecycle(created);
+                if (lifecycle === 'revoked') {
+                    throw new Error('The exact Continuum Package Version is revoked');
+                }
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => {
+                    state.versionCreated = true;
+                    if (lifecycle === 'sealed' || lifecycle === 'superseded') {
+                        state.sealed = true;
+                    }
+                });
+            }
+            if (!checkpoint.sealed) {
+                const leaseOwner = `creator:${jobId.slice(0, 24)}`;
+                let sealedWithCheckpointLease = false;
+                if (checkpoint.lease) {
+                    try {
+                        // Seal is idempotent for the same fence. This closes the crash window
+                        // after the server committed the seal but before the checkpoint write.
+                        await this.api.sealPackageVersion(input.package.id, input.packageVersion.version, {
+                            leaseOwner: checkpoint.lease.owner, fencingToken: checkpoint.lease.fencingToken,
+                            ...(input.stage === true ? { activate: false } : {}),
+                        });
+                        sealedWithCheckpointLease = true;
+                    }
+                    catch {
+                        // The old lease may simply have expired. Reacquire below with the
+                        // exact prior fence; the backend still rejects another worker's fence.
+                    }
+                }
+                if (!sealedWithCheckpointLease) {
+                    const lease = await this.api.acquirePackageVersionLease(input.package.id, input.packageVersion.version, {
+                        leaseOwner, ttlSeconds: this.leaseTtlSeconds, operationId: `creator-lease:${jobId}`,
+                        ...(checkpoint.lease ? { expectedFencingToken: checkpoint.lease.fencingToken } : {}),
+                    });
+                    checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.lease = { owner: leaseOwner, fencingToken: lease.fencingToken }; });
+                    await this.api.sealPackageVersion(input.package.id, input.packageVersion.version, {
+                        leaseOwner, fencingToken: lease.fencingToken,
+                        ...(input.stage === true ? { activate: false } : {}),
+                    });
+                }
+                versionSealed = true;
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.sealed = true; });
+            }
+            const packagePin = {
+                packageId: input.package.id,
+                version: input.packageVersion.version,
+                manifestCid: (0, helix_manifest_1.continuumPackageVersionCid)(input.packageVersion),
+            };
+            if (input.vaultAssetVersionPin && !checkpoint.vaultAssetVersionPinned) {
+                await this.api.pinVaultAssetVersionPackage(input.vaultAssetVersionPin.vaultAssetVersionId, packagePin);
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => {
+                    state.vaultAssetVersionPinned = true;
+                });
+            }
+            if (input.universalItemPin && !checkpoint.universalItemPinned) {
+                await this.api.pinUniversalItemPackage(input.universalItemPin.itemId, {
+                    packagePin,
+                    ...(input.universalItemPin.promoteToPublished
+                        ? { promoteToPublished: true }
+                        : {}),
+                });
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.universalItemPinned = true; });
+            }
+            let listingsCreated = 0;
+            for (const listing of input.listings) {
+                if (checkpoint.listingIds?.[listing.listing.id])
+                    continue;
+                await this.api.createListing(listing.listing);
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => {
+                    state.listingIds ??= {};
+                    state.listingIds[listing.listing.id] = true;
+                });
+                listingsCreated += 1;
+            }
+            if (input.world && !checkpoint.worldReleased) {
+                await this.api.publishWorldRelease(input.world.release.worldId, input.world);
+                checkpoint = await this.checkpoints.update(jobId, base, (state) => { state.worldReleased = true; });
+            }
+            const receipt = {
+                schema: 'helix.creator.continuum-receipt/1', jobId, status: 'complete',
+                sourceDigest: input.sourceDigest, packageId: input.package.id,
+                packageVersion: input.packageVersion.version,
+                manifestCid: (0, helix_manifest_1.continuumPackageVersionCid)(input.packageVersion),
+                objectCids: normalized.objects.map((entry) => entry.reference.cid).sort(),
+                ...(input.universalItemPin ? { universalItemId: input.universalItemPin.itemId } : {}),
+                ...(input.vaultAssetVersionPin
+                    ? {
+                        vaultAssetVersionId: input.vaultAssetVersionPin.vaultAssetVersionId,
+                    }
+                    : {}),
+                listingIds: input.listings.map((entry) => entry.listing.id),
+                ...(input.world ? { worldReleaseId: input.world.release.id } : {}),
+                actions: {
+                    objectsPublished, objectsReused, packageCreated: !existing?.packageCreated,
+                    versionCreated: !existing?.versionCreated, versionSealed,
+                    vaultAssetVersionPinned: Boolean(input.vaultAssetVersionPin && !existing?.vaultAssetVersionPinned),
+                    universalItemPinned: Boolean(input.universalItemPin && !existing?.universalItemPinned),
+                    listingsCreated,
+                    worldReleased: Boolean(input.world && !existing?.worldReleased),
+                },
+                policy: { listings: listingPolicies },
+                ...(conversion ? { conversion } : {}),
+            };
+            await this.checkpoints.update(jobId, base, (state) => { delete state.lease; state.receipt = receipt; });
+            return receipt;
+        });
+    }
+    async receipt(jobId) {
+        const receipt = (await this.checkpoints.read(jobId))?.receipt;
+        return receipt ? normalizeReceipt(receipt) : null;
+    }
+    /** Publish the immutable result of createPrivateBuildDraft -> freezeBuildDraft. */
+    async publishFrozenBuild(input) {
+        return this.publish({
+            projectId: input.projectId, sourceDigest: input.sourceDigest,
+            package: {
+                schema: 'helix.continuum.package/1', id: input.frozen.manifest.package.id,
+                type: 'build', name: input.name,
+            },
+            packageVersion: input.frozen.manifest, objects: input.objects, listings: input.listings ?? [],
+        });
+    }
+    async publishSourceMapWorld(input) {
+        const imported = (0, semantic_1.importSourceSceneMap)(input.source);
+        return this.publishImportedWorld(imported, input);
+    }
+    async publishScratchWorld(input) {
+        const imported = (0, authoring_1.importScratchScene)(input.source);
+        const audience = input.packagePublication?.visibility === 'public' ? 'public' : 'private';
+        return this.publishImportedWorld(imported, {
+            ...input,
+            objects: [...(input.objects ?? []), ...(0, authoring_1.scratchTerrainObjects)(input.source, audience)],
+        });
+    }
+    async publishImportedWorld(imported, input) {
+        const normalizedDigest = input.sourceDigest.toLowerCase();
+        const normalizedCompilation = normalizeWorldCompilation(input.compilation, input.projectId, normalizedDigest);
+        const compilation = (0, continuum_1.compileContinuumScenePackage)({ ...normalizedCompilation, document: imported.document });
+        if (!compilation.worldRelease)
+            throw new Error('world publication requires compilation.world');
+        assertPublishableSceneDocument(compilation.sceneDocument);
+        const rootObject = {
+            reference: compilation.packageVersion.root,
+            source: {
+                kind: 'inline', bytes: compilation.sceneDocumentBytes,
+                filename: `${compilation.sceneDocument.id}.continuum-scene.json`,
+                audience: input.packagePublication?.visibility === 'public' ? 'public' : 'private',
+            },
+        };
+        const publication = {
+            projectId: input.projectId, sourceDigest: normalizedDigest,
+            package: compilation.package, packageVersion: compilation.packageVersion,
+            packagePublication: input.packagePublication,
+            objects: [rootObject, ...(input.objects ?? [])], listings: input.listings ?? [],
+            world: {
+                release: compilation.worldRelease,
+                defaultRuntimeProfileId: input.defaultRuntimeProfileId,
+            },
+        };
+        (0, cliAuthority_1.transferCliPublicListingConfirmation)(input, publication);
+        return this.publish(publication, { scene: imported.receipt, compilation: compilation.report });
+    }
+    async authorizeListings(input) {
+        const policies = {};
+        for (const entry of input.listings) {
+            if (entry.listing.visibility !== 'public') {
+                policies[entry.listing.id] = 'not-public';
+                continue;
+            }
+            if ((0, cliAuthority_1.cliConfirmedPublicListing)(input, entry.listing.id)) {
+                policies[entry.listing.id] = 'allowed-cli';
+                continue;
+            }
+            throw new PublicListingPolicyError(`Public ${entry.listing.surface} Listing ${entry.listing.id} requires --confirm-public-listing on this CLI invocation. Nothing was listed.`);
+        }
+        return policies;
+    }
+    async publishObject(object) {
+        switch (object.source.kind) {
+            case 'inline': return this.api.putObject({ bytes: object.source.bytes, filename: object.source.filename, mediaType: object.reference.mediaType, audience: object.source.audience });
+            case 'file': return this.api.putObjectFromFile({ path: object.source.path, filename: object.source.filename, mediaType: object.reference.mediaType, audience: object.source.audience });
+            case 'universal-item-adoption': return this.api.adoptUniversalItemObject(object.source.assetId, object.source.contentSha256, object.source.audience);
+            case 'vault-adoption': return this.api.adoptVaultObject(object.source.vaultAssetVersionId, object.source.audience);
+            case 'instant-world-adoption': return this.api.adoptInstantWorldObject(object.source.buildId, object.source.contentSha256);
+            case 'existing': return object.reference;
+        }
+    }
+}
+exports.ContinuumPublisher = ContinuumPublisher;
+/**
+ * The backend's catch-all limiter is 600 requests per minute per IP and a scene-scale package is hundreds of
+ * objects at two or three requests each, so a 429 mid-publication is the expected shape, not a failure: wait out
+ * the window and continue. Every other error still surfaces at once; the checkpoint makes a later resume cheap.
+ */
+async function withThrottleBackoff(attempt, attempts = 8) {
+    for (let tried = 1;; tried += 1) {
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            const throttled = error instanceof api_1.ApiError && error.status === 429;
+            if (!throttled || tried >= attempts)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(60_000, 5_000 * tried)));
+        }
+    }
+}
+/** Keep checkpoint v1 readable after additive receipt action fields ship. */
+function normalizeReceipt(receipt) {
+    return {
+        ...receipt,
+        actions: {
+            ...receipt.actions,
+            vaultAssetVersionPinned: receipt.actions.vaultAssetVersionPinned ?? false,
+        },
+    };
+}
+/**
+ * The seal-side validation `ContinuumPublisher.publish` runs BEFORE it uploads or seals anything. Pure (no network), exported
+ * so a dry run can run the exact rules the real publish will hit (`provenance.source` length, Package Version shape,
+ * object closure, ...). It throws a TypeError whose message joins every refusal with "; ".
+ */
+function preflightContinuumPublicationIntent(input) {
+    return preflight(input);
+}
+function preflight(input) {
+    if (!/^[a-f0-9]{64}$/.test(input.sourceDigest))
+        throw new TypeError('sourceDigest must be one lowercase SHA-256 hex digest');
+    (0, identity_1.assertContinuumUuid)(input.package.id, 'Package id');
+    if (input.packagePublication?.slug && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.packagePublication.slug))
+        throw new TypeError('Package slug must be normalized lowercase kebab-case');
+    const packageValidation = (0, helix_manifest_1.validateContinuumPackageVersion)(input.packageVersion);
+    if (!packageValidation.valid)
+        throw new TypeError(packageValidation.errors.join('; '));
+    if (input.package.id !== input.packageVersion.package.id || input.package.type !== input.packageVersion.package.type)
+        throw new TypeError('Package identity and Package Version identity must match');
+    input.packageVersion.dependencies.forEach((dependency) => assertPackageReferenceUuid(dependency.package, `Package dependency ${dependency.slot}`));
+    input.packageVersion.scene?.children.forEach((child) => assertPackageReferenceUuid(child.scene, `child Scene ${child.mount}`));
+    if (input.packageVersion.build) {
+        assertPackageReferenceUuid(input.packageVersion.build.base, 'Build base');
+        input.packageVersion.build.slots.forEach((slot) => assertPackageReferenceUuid(slot.package, `Build slot ${slot.slot}`));
+    }
+    const listingIds = new Set();
+    for (const intent of input.listings) {
+        const listing = (0, helix_manifest_1.validateListing)(intent.listing);
+        if (!listing.valid)
+            throw new TypeError(listing.errors.join('; '));
+        (0, identity_1.assertContinuumUuid)(listing.listing.id, 'Listing id');
+        if (listingIds.has(listing.listing.id))
+            throw new TypeError(`duplicate Listing id ${listing.listing.id}`);
+        listingIds.add(listing.listing.id);
+        if (listing.listing.surface === 'vault') {
+            if (listing.listing.target.type !== 'package' || listing.listing.target.packageId !== input.package.id)
+                throw new TypeError('Vault Listing must target the Package being published');
+            if (listing.listing.visibility === 'public' && input.packagePublication?.visibility !== 'public')
+                throw new TypeError('A public Vault Listing requires packagePublication.visibility="public"');
+        }
+        else {
+            if (listing.listing.target.type !== 'universal-item')
+                throw new TypeError('Marketplace Listing must target a Universal Item');
+            if (!input.universalItemPin || input.universalItemPin.itemId !== listing.listing.target.universalItemId) {
+                throw new TypeError('Marketplace Listing requires an exact Universal Item Package pin for its target');
+            }
+            if (listing.listing.visibility === 'public' && !input.universalItemPin.promoteToPublished) {
+                throw new TypeError('A public Marketplace Listing requires explicit Universal Item promotion after Package seal');
+            }
+        }
+    }
+    if (input.universalItemPin)
+        (0, identity_1.assertContinuumUuid)(input.universalItemPin.itemId, 'Universal Item id');
+    if (input.vaultAssetVersionPin) {
+        const versionId = input.vaultAssetVersionPin.vaultAssetVersionId;
+        if (!versionId)
+            throw new TypeError('Vault Asset Version pin requires an id');
+        if (!input.objects.some((object) => object.source.kind === 'vault-adoption' &&
+            object.source.vaultAssetVersionId === versionId)) {
+            throw new TypeError('Vault Asset Version pin must name one adopted Package object source');
+        }
+    }
+    if (input.world) {
+        const release = (0, helix_manifest_1.validateWorldRelease)(input.world.release);
+        if (!release.valid)
+            throw new TypeError(release.errors.join('; '));
+        (0, identity_1.assertContinuumUuid)(release.release.id, 'World Release id');
+        (0, identity_1.assertContinuumUuid)(release.release.worldId, 'World id');
+        assertPackageReferenceUuid(release.release.rootScene, 'World root Scene');
+        release.release.gameplayPackages.forEach((entry, index) => assertPackageReferenceUuid(entry, `World gameplay Package ${index}`));
+        if (!release.release.runtimeProfiles.some((profile) => profile.id === input.world.defaultRuntimeProfileId))
+            throw new TypeError('defaultRuntimeProfileId must name a release runtime profile');
+        const defaultProfile = release.release.runtimeProfiles.find((profile) => profile.id === input.world.defaultRuntimeProfileId);
+        if (defaultProfile.platform !== 'web' || defaultProfile.renderer !== 'three-webgl2' || defaultProfile.contracts.continuum !== 1 || defaultProfile.contracts.scene !== 2) {
+            throw new TypeError('defaultRuntimeProfileId must select a web three-webgl2 profile using Continuum 1 and Scene 2');
+        }
+        if (!release.release.runtimePolicy.requiredCapabilities.length)
+            throw new TypeError('World Release requires at least one runtime capability');
+        for (const profile of release.release.runtimeProfiles) {
+            for (const phase of ['beforeSpawn', 'firstFrame']) {
+                if (!release.release.readySets.some((readySet) => readySet.runtimeProfileId === profile.id && readySet.phase === phase && readySet.cids.length)) {
+                    throw new TypeError(`Runtime Profile ${profile.id} requires a non-empty ${phase} ReadySet`);
+                }
+            }
+            const missing = release.release.runtimePolicy.requiredCapabilities.filter((capability) => !profile.capabilities.includes(capability));
+            if (missing.length)
+                throw new TypeError(`Runtime Profile ${profile.id} is missing required capabilities: ${missing.join(', ')}`);
+        }
+        const expectedManifestCid = (0, helix_manifest_1.continuumPackageVersionCid)(input.packageVersion);
+        if (release.release.rootScene.packageId !== input.package.id || release.release.rootScene.version !== input.packageVersion.version || release.release.rootScene.manifestCid !== expectedManifestCid) {
+            throw new TypeError('WorldRelease rootScene must reference the exact Package Version being published');
+        }
+    }
+    const required = ownedObjectReferences(input.packageVersion, input.objects);
+    const publications = new Map();
+    for (const object of input.objects) {
+        const current = publications.get(object.reference.cid);
+        if (current && !sameReference(current.reference, object.reference))
+            throw new TypeError(`CID ${object.reference.cid} has conflicting descriptors`);
+        publications.set(object.reference.cid, object);
+        if (object.source.kind === 'inline') {
+            if (object.source.bytes.byteLength !== object.reference.bytes || (0, helix_manifest_1.cidFromBytes)(object.source.bytes) !== object.reference.cid)
+                throw new TypeError(`inline bytes do not match ${object.reference.cid}`);
+            if (object.source.bytes.byteLength > objectUpload_1.CONTINUUM_OBJECT_UPLOAD_MAX_BYTES)
+                throw new TypeError(`object ${object.reference.cid} exceeds the 32 MiB binary upload limit`);
+        }
+        if (object.source.kind === 'file') {
+            if (!object.source.path || !object.source.filename)
+                throw new TypeError(`file source for ${object.reference.cid} must name a path and filename`);
+        }
+        if (object.source.kind === 'instant-world-adoption' && object.reference.cid !== `cid:sha256:${object.source.contentSha256.toLowerCase()}`) {
+            throw new TypeError(`Instant World adoption hash does not match ${object.reference.cid}`);
+        }
+        if (object.source.kind === 'universal-item-adoption' && object.reference.cid !== `cid:sha256:${object.source.contentSha256.toLowerCase()}`) {
+            throw new TypeError(`Universal Item adoption hash does not match ${object.reference.cid}`);
+        }
+        if (input.packagePublication?.visibility === 'public' && (object.source.kind === 'inline' || object.source.kind === 'file' || object.source.kind === 'universal-item-adoption' || object.source.kind === 'vault-adoption') && object.source.audience !== 'public') {
+            throw new TypeError(`public Package object ${object.reference.cid} must be ingested or adopted with public audience`);
+        }
+    }
+    for (const reference of required) {
+        const publication = publications.get(reference.cid);
+        if (!publication || !sameReference(publication.reference, reference))
+            throw new TypeError(`missing exact publication source for owned object ${reference.cid}`);
+    }
+    for (const cid of publications.keys())
+        if (!required.some((reference) => reference.cid === cid))
+            throw new TypeError(`object ${cid} is not in the Package-owned closure`);
+    assertVehicleRootRenditionsSealed(input, publications);
+    return { objects: [...publications.values()].sort((a, b) => a.reference.cid.localeCompare(b.reference.cid)) };
+}
+/**
+ * A vehicle root whose drawn renditions name bytes this Version does not seal would draw the PREVIOUS car for owners while
+ * its manifest says otherwise (`vehicle/renditionManifest.ts`). Refused before anything is uploaded.
+ */
+function assertVehicleRootRenditionsSealed(input, publications) {
+    const root = input.packageVersion.root;
+    if (input.packageVersion.package.type !== 'vehicle' || !root || !/vehicle-package\+json/.test(root.mediaType))
+        return;
+    const source = publications.get(root.cid)?.source;
+    let bytes = null;
+    try {
+        if (source?.kind === 'inline')
+            bytes = source.bytes;
+        else if (source?.kind === 'file')
+            bytes = (0, node_fs_1.readFileSync)(source.path);
+    }
+    catch {
+        return;
+    }
+    if (!bytes)
+        return;
+    let doc;
+    try {
+        doc = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch {
+        return;
+    }
+    const variants = input.packageVersion.variants.map((v) => ({ id: v.id, cid: v.object.cid, mediaType: v.object.mediaType, role: v.object.role }));
+    const problems = (0, renditionManifest_1.vehicleRenditionManifestProblems)(doc, variants);
+    if (problems.length)
+        throw new TypeError(`vehicle root would draw bytes this Version does not seal: ${problems.join('; ')} — ${renditionManifest_1.RENDITION_FIX}`);
+}
+function assertPackageReferenceUuid(reference, label) {
+    (0, identity_1.assertContinuumUuid)(reference.packageId, `${label} Package id`);
+}
+function packageVersionLifecycle(value) {
+    const unwrapped = value &&
+        typeof value === 'object' &&
+        'item' in value &&
+        value.item &&
+        typeof value.item === 'object'
+        ? value.item
+        : value;
+    if (!unwrapped || typeof unwrapped !== 'object')
+        return undefined;
+    const lifecycle = unwrapped.lifecycle;
+    return lifecycle === 'draft' ||
+        lifecycle === 'sealed' ||
+        lifecycle === 'superseded' ||
+        lifecycle === 'revoked'
+        ? lifecycle
+        : undefined;
+}
+function normalizeWorldCompilation(input, projectId, sourceDigest) {
+    if (!input.world)
+        throw new TypeError('world publication requires compilation.world');
+    (0, identity_1.assertContinuumUuid)(input.world.worldId, 'World id');
+    const packageId = identity_1.CONTINUUM_UUID_PATTERN.test(input.packageId)
+        ? input.packageId
+        : (0, identity_1.deterministicContinuumUuid)(`${types_1.CONTINUUM_CREATOR_CONTRACT}\0package\0${projectId}\0${sourceDigest}\0${input.packageId}`);
+    const releaseId = identity_1.CONTINUUM_UUID_PATTERN.test(input.world.releaseId)
+        ? input.world.releaseId
+        : (0, identity_1.deterministicContinuumUuid)(`${types_1.CONTINUUM_CREATOR_CONTRACT}\0release\0${projectId}\0${sourceDigest}\0${input.world.worldId}\0${input.world.releaseId}`);
+    return { ...input, packageId, world: { ...input.world, releaseId } };
+}
+/** Cheap authoring-side guard; the backend repeats the exact spatial proof authoritatively. */
+function assertPublishableSceneDocument(document) {
+    let hasShell = false;
+    let hasLight = false;
+    let hasSpawn = false;
+    let hasCollision = false;
+    const pending = document.roots.map((element) => ({ element, inherited: { role: 'exterior', collision: true } }));
+    while (pending.length) {
+        const { element, inherited } = pending.pop();
+        const role = element.properties?.role ?? inherited.role;
+        const collision = element.properties?.collision ?? inherited.collision;
+        const renderable = Boolean(element.sourceFallback) || ['wall', 'floor', 'ceiling', 'door', 'window', 'stairs', 'primitive', 'asset'].includes(element.type);
+        if (renderable && role !== 'interior' && role !== 'detail')
+            hasShell = true;
+        if (element.type === 'light')
+            hasLight = true;
+        if (element.type === 'gameplay-anchor' && /^spawn(?:[.:_-]|$)/i.test(element.anchor))
+            hasSpawn = true;
+        if (collision && (element.type === 'floor' || element.type === 'primitive' || (element.type === 'asset' && Boolean(element.collider)) || Boolean(element.sourceFallback)))
+            hasCollision = true;
+        if ('children' in element)
+            pending.push(...element.children.map((child) => ({ element: child, inherited: { role, collision } })));
+    }
+    if (!hasShell || !hasLight)
+        throw new TypeError('World Scene requires an exterior or structural renderable shell and authored lighting');
+    if (!hasSpawn)
+        throw new TypeError('World Scene requires an explicit spawn gameplay anchor');
+    if (!hasCollision)
+        throw new TypeError('World Scene requires authored collision beneath its spawn; the backend verifies exact clearance');
+}
+/** Strict bound on a role document read during closure planning; it lists
+ * receipts, so it is never anywhere near a cooked container. */
+const UNREAL_ROLE_DOCUMENT_MAX_BYTES = 16 * 1024 * 1024;
+function ownedObjectReferences(version, publications = []) {
+    const refs = [version.root, ...version.variants.map((variant) => variant.object)];
+    if (version.unrealWorld) {
+        // The cooked-file closure lives inside each role document's `files[].object`.
+        // Read the role document the caller is publishing (bounded), and require it
+        // to hash to the exact CID the descriptor pins, so the per-file objects the
+        // publication carries are provably Package-owned. There is no aggregate
+        // `unrealWorld.objects[]` field to consult.
+        const fileSourceByCid = new Map();
+        for (const publication of publications) {
+            if (publication.source.kind === 'file') {
+                fileSourceByCid.set(publication.reference.cid, publication.source.path);
+            }
+        }
+        for (const role of version.unrealWorld.roles) {
+            refs.push(role.manifest);
+            const path = fileSourceByCid.get(role.manifest.cid);
+            if (!path) {
+                throw new TypeError(`Unreal World role document ${role.manifest.cid} must be published from a local file`);
+            }
+            if (role.manifest.bytes > UNREAL_ROLE_DOCUMENT_MAX_BYTES) {
+                throw new TypeError(`Unreal World role document ${role.manifest.cid} exceeds the bounded role-document size`);
+            }
+            const bytes = (0, node_fs_1.readFileSync)(path);
+            if (bytes.byteLength !== role.manifest.bytes ||
+                (0, helix_manifest_1.cidFromBytes)(bytes) !== role.manifest.cid) {
+                throw new TypeError(`Unreal World role document ${path} does not match ${role.manifest.cid}`);
+            }
+            const parsed = (0, helix_manifest_1.validateUnrealCookedRoleManifest)(JSON.parse(bytes.toString('utf8')), { expectedRole: role.role });
+            if (!parsed.valid)
+                throw new TypeError(parsed.errors.join('; '));
+            refs.push(...parsed.unrealCookedRole.files.map((file) => file.object));
+        }
+    }
+    if (version.source)
+        refs.push(version.source);
+    if (version.material)
+        refs.push(...(0, helix_manifest_1.continuumMaterialObjectReferences)(version.material));
+    if (version.scene)
+        refs.push(version.scene.document, ...version.scene.objects);
+    if (version.runtimeModule)
+        refs.push(version.runtimeModule.publisherAttestation, version.runtimeModule.sourceAttestation);
+    const byCid = new Map();
+    for (const ref of refs) {
+        const current = byCid.get(ref.cid);
+        if (current && !sameReference(current, ref))
+            throw new TypeError(`owned CID ${ref.cid} has conflicting descriptors`);
+        byCid.set(ref.cid, ref);
+    }
+    return [...byCid.values()];
+}
+function sameReference(a, b) {
+    return a.cid === b.cid && a.bytes === b.bytes && a.mediaType === b.mediaType && a.role === b.role;
+}
+function assertObjectReceipt(expected, actual) {
+    if (expected.cid !== actual.cid || expected.bytes !== actual.bytes || expected.mediaType !== actual.mediaType)
+        throw new Error(`Continuum object receipt does not match ${expected.cid}`);
+}
+function sanitizedIntent(input) {
+    return {
+        projectId: input.projectId, package: input.package, packagePublication: input.packagePublication, packageVersion: input.packageVersion,
+        objects: input.objects.map((entry) => ({ reference: entry.reference, source: entry.source.kind === 'inline'
+                ? { kind: 'inline', filename: entry.source.filename, audience: entry.source.audience }
+                : entry.source.kind === 'file'
+                    ? { kind: 'file', filename: entry.source.filename, audience: entry.source.audience }
+                    : entry.source })).sort((a, b) => a.reference.cid.localeCompare(b.reference.cid)),
+        vaultAssetVersionPin: input.vaultAssetVersionPin,
+        universalItemPin: input.universalItemPin, listings: input.listings, world: input.world,
+        // Staging and activating are different operations on the same bytes, so resuming one
+        // must never silently complete the other. Included only when staging, so an ordinary
+        // publish keeps the job id it already had and its in-flight checkpoints stay valid.
+        ...(input.stage === true ? { stage: true } : {}),
+    };
+}
+//# sourceMappingURL=workflow.js.map