@instruktlabs/kiln 1.2.1 → 1.2.3

package/lib/material-library-node.js

@@ -4,10 +4,18 @@ import { lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile } from
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import sharp from 'sharp';
 import { DataTexture } from 'three';
-import { assertMaterialJson, canonicalMaterialJson, MATERIAL_LIBRARY_LIMITS, MATERIAL_LIBRARY_SLOTS, MATERIAL_LIBRARY_USAGE, materialLibraryHashSchema, materialLibraryIdSchema, materialLibraryResourceId, materialManifestSchema, materialNormalDerivationSchema, materialPngDimensions, validateMaterialRecordShape, validateMaterialManifest, } from "./material-library.js";
+import { assertMaterialJson, canonicalMaterialJson, MATERIAL_LIBRARY_LIMITS, MATERIAL_LIBRARY_SLOTS, MATERIAL_LIBRARY_USAGE, materialLibraryHashSchema, materialLibraryIdSchema, materialLibraryResourceId, materialManifestSchema, materialNormalDerivationSchema, materialPngDimensions, validateMaterialRecordShape, validateMaterialManifest, validateMaterialManifestAny, validateMaterialRecordShapeAny, materialManifestV2Schema, materialRecordDependencyPins, } from "./material-library.js";
+import { canonicalizePortableSamplerV1 } from "./portable-sampler.js";
+import { applyPortableSamplerV1 } from "./portable-sampler-runtime.js";
+import { compileProceduralTextureSpecV3 } from "./procedural-texture-v3.js";
+import { admitProceduralTextureSpecV3, PROCEDURAL_TEXTURE_V3_COMPILER_ID, } from "./procedural-texture-v3-contract.js";
+import { admitTextureAtlasSpecV1, compileTextureAtlasSpecV1 } from "./texture-atlas-pixels.js";
+import { TEXTURE_ATLAS_COMPILER_ID } from "./texture-atlas-contract.js";
 import { compileProceduralTextureSpecV2, normalMapFromHeight } from "./procedural-texture.js";
+import { canonicalizeProceduralTextureSpecV2, } from "./procedural-material-v2.js";
 import { loadTexture } from "./textures.js";
 import { DEFAULT_TEXTURE_RESOLVER } from "./texture-resolver.js";
+import { PORTABLE_MATERIAL_V3_LIMITS } from "./procedural-material-v3.js";
 const digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
 const encoder = { name: 'sharp', version: sharp.versions.sharp };
 function revisionHash(manifest) {
@@ -231,7 +239,7 @@ export function validateMaterialLibraryPayload(value) {
         throw new Error('Material resource payload exceeds byte or pixel budget');
     return payload;
 }
-export async function createMaterialLibraryPayload(records) {
+async function createMaterialLibraryPayloadV1(records) {
     const snapshots = records.map(snapshot);
     for (const record of snapshots)
         await verifyMaterialRecordV1(record);
@@ -246,7 +254,7 @@ export async function createMaterialLibraryPayload(records) {
         })),
     });
 }
-export async function decodeMaterialLibraryPayload(value) {
+async function decodeMaterialLibraryPayloadV1(value) {
     const payload = validateMaterialLibraryPayload(value);
     const records = payload.records.map((wire) => ({
         manifest: structuredClone(wire.manifest),
@@ -266,6 +274,7 @@ export async function createMaterialLibraryTextureResolver(records, fallback = D
         for (const map of record.manifest.maps)
             maps.set(materialLibraryResourceId(record.manifest, map.slot), { record, map });
     return Object.freeze({
+        pinnedMaterialMaps: createPinnedMaterialMapPort(snapshots),
         describeApprovedTexture(id) {
             const entry = typeof id === 'string' ? maps.get(id) : undefined;
             return entry
@@ -282,7 +291,7 @@ export async function createMaterialLibraryTextureResolver(records, fallback = D
                 name: id,
             });
             texture.userData['kilnMaterialResource'] = {
-                schemaVersion: 1,
+                schemaVersion: entry.record.manifest.schemaVersion,
                 materialId: entry.record.manifest.materialId,
                 revisionId: entry.record.manifest.revisionId,
                 resourceId: id,
@@ -292,8 +301,59 @@ export async function createMaterialLibraryTextureResolver(records, fallback = D
                     ? { physicalSizeMeters: { ...entry.record.manifest.physicalSizeMeters } }
                     : {}),
             };
+            if ('sampler' in entry.map)
+                applyPortableSamplerV1(texture, entry.map.sampler);
+            if ('recipe' in entry.map && entry.map.recipe?.kind === 'atlas')
+                texture.userData['kilnAtlas'] = {
+                    spec: structuredClone(entry.map.recipe.spec),
+                    manifest: structuredClone(entry.map.recipe.manifest),
+                };
             return texture;
         },
+        async preparePortableTexture(id, context) {
+            context?.signal?.throwIfAborted();
+            const entry = typeof id === 'string' ? maps.get(id) : undefined;
+            if (!entry) {
+                if (!fallback.preparePortableTexture)
+                    throw new Error('Portable texture preparation unavailable');
+                return fallback.preparePortableTexture(id, context);
+            }
+            const { record, map } = entry;
+            return {
+                descriptor: {
+                    resourceId: id,
+                    usage: map.usage,
+                    allowedSlots: [map.slot],
+                    colorSpace: map.colorSpace,
+                    width: map.width,
+                    height: map.height,
+                    encodedByteLength: map.bytes,
+                    imageSha256: map.sha256,
+                },
+                bytes: record.files[map.file].slice(),
+                userData: {
+                    ...('recipe' in map && map.recipe?.kind === 'atlas'
+                        ? {
+                            kilnAtlas: {
+                                spec: structuredClone(map.recipe.spec),
+                                manifest: structuredClone(map.recipe.manifest),
+                            },
+                        }
+                        : {}),
+                    kilnMaterialResource: {
+                        schemaVersion: record.manifest.schemaVersion,
+                        materialId: record.manifest.materialId,
+                        revisionId: record.manifest.revisionId,
+                        resourceId: id,
+                        map: structuredClone(map),
+                        sources: structuredClone(record.manifest.sources),
+                        ...(record.manifest.physicalSizeMeters
+                            ? { physicalSizeMeters: structuredClone(record.manifest.physicalSizeMeters) }
+                            : {}),
+                    },
+                },
+            };
+        },
         materialRecipe: (id, overrides) => fallback.materialRecipe(id, overrides),
     });
 }
@@ -333,20 +393,42 @@ export class FileMaterialLibrary {
             throw new Error('Invalid material library file');
         return new Uint8Array(await readFile(path));
     }
-    async read(materialId, revisionId) {
+    async readManifest(materialId, revisionId) {
         materialLibraryIdSchema.parse(materialId);
         materialLibraryHashSchema.parse(revisionId);
         const dir = await this.path(materialId, revisionId.slice(7));
-        const manifest = materialManifestSchema.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await this.file(dir, 'manifest.json', MATERIAL_LIBRARY_LIMITS.maxManifestBytes))));
+        const manifest = validateMaterialManifestIdentityAny(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await this.file(dir, 'manifest.json', MATERIAL_LIBRARY_LIMITS.maxManifestBytes))));
         if (manifest.materialId !== materialId || manifest.revisionId !== revisionId)
             throw new Error('Material identity mismatch');
+        return manifest;
+    }
+    /** Host-only file materialization after metadata admission; pixel/recipe verification is deferred. */
+    async readRecordFiles(materialId, revisionId) {
+        const manifest = await this.readManifest(materialId, revisionId);
+        const dir = await this.path(materialId, revisionId.slice(7));
         const files = {};
         for (const map of manifest.maps)
             files[map.file] = await this.file(dir, map.file, MATERIAL_LIBRARY_LIMITS.maxMapBytes);
         const record = { manifest, files };
-        await verifyMaterialRecordV1(record);
+        validateMaterialRecordShapeAny(record);
+        for (const map of manifest.maps)
+            if (digest(files[map.file]) !== map.sha256)
+                throw new Error('Material integrity hash mismatch');
         return record;
     }
+    async read(materialId, revisionId) {
+        const root = await this.readManifest(materialId, revisionId);
+        if (root.schemaVersion === 1) {
+            const record = (await this.readRecordFiles(materialId, revisionId));
+            await verifyMaterialRecordV1(record);
+            return record;
+        }
+        const closure = await resolveMaterialRecordClosure([root], {
+            readManifest: this.readManifest.bind(this),
+            read: this.readRecordFiles.bind(this),
+        });
+        return closure.find((record) => record.manifest.materialId === materialId && record.manifest.revisionId === revisionId);
+    }
     async list() {
         const manifests = [];
         for (const material of await readdir(await this.path(), { withFileTypes: true })) {
@@ -362,12 +444,27 @@ export class FileMaterialLibrary {
         }
         return manifests.sort((a, b) => a.materialId.localeCompare(b.materialId) || a.revisionId.localeCompare(b.revisionId));
     }
-    async import(records) {
+    async import(records, options) {
         if (!Array.isArray(records) || !records.length || records.length > 100)
             throw new Error('Material import requires 1..100 records');
-        const snapshots = records.map(snapshot);
-        for (const record of snapshots)
-            await verifyMaterialRecordV1(record);
+        let snapshots;
+        if (records.every((record) => record.manifest.schemaVersion === 1) && !options?.materials) {
+            snapshots = records.map(snapshot);
+            for (const record of snapshots)
+                await verifyMaterialRecordV1(record);
+        }
+        else {
+            const candidates = [...records, ...(options?.materials ?? [])];
+            if (new Set(candidates.map((record) => identity(record.manifest))).size > 1024)
+                throw new Error('Material import context count limit exceeded');
+            const context = await resolveMaterialRecordClosure(records.map((r) => r.manifest), recordClosureReader(candidates, this), {
+                maxRecords: 1024,
+                maxBytes: 256 * 1024 * 1024,
+                maxPixels: 1024 * MATERIAL_LIBRARY_LIMITS.maxRecordPixels,
+            });
+            const admitted = new Map(context.map((record) => [identity(record.manifest), record]));
+            snapshots = records.map((record) => admitted.get(identity(record.manifest)));
+        }
         for (const record of snapshots) {
             const { manifest, files } = record;
             const dest = await this.path(manifest.materialId, manifest.revisionId.slice(7));
@@ -400,3 +497,586 @@ export class FileMaterialLibrary {
         return snapshots.map((record) => record.manifest);
     }
 }
+export function validateMaterialManifestIdentityAny(value) {
+    const manifest = validateMaterialManifestAny(value);
+    if (revisionHash(manifest) !== manifest.revisionId)
+        throw new Error('Material identity hash mismatch');
+    return manifest;
+}
+function snapshotAny(record) {
+    validateMaterialRecordShapeAny(record);
+    return {
+        manifest: structuredClone(record.manifest),
+        files: Object.fromEntries(Object.entries(record.files).map(([name, bytes]) => [name, bytes.slice()])),
+    };
+}
+const identity = (manifest) => `${manifest.materialId}/${manifest.revisionId}`;
+export async function resolveMaterialRecordClosure(roots, reader, limits = {
+    maxRecords: MATERIAL_LIBRARY_LIMITS.maxPayloadRecords,
+    maxBytes: MATERIAL_LIBRARY_LIMITS.maxPayloadBytes,
+    maxPixels: MATERIAL_LIBRARY_LIMITS.maxPayloadPixels,
+}) {
+    for (const n of Object.values(limits))
+        if (!Number.isSafeInteger(n) || n < 1)
+            throw new Error('Invalid material closure limits');
+    const manifests = new Map(), active = new Set();
+    let bytes = 0, pixels = 0;
+    const visit = async (value) => {
+        const manifest = validateMaterialManifestIdentityAny(value), key = identity(manifest);
+        if (active.has(key))
+            throw new Error('Material dependency cycle');
+        const existing = manifests.get(key);
+        if (existing) {
+            if (canonicalMaterialJson(existing) !== canonicalMaterialJson(manifest))
+                throw new Error('Conflicting material dependency identity');
+            return;
+        }
+        manifests.set(key, structuredClone(manifest));
+        active.add(key);
+        for (const map of manifest.maps) {
+            bytes += map.bytes;
+            pixels += map.width * map.height;
+        }
+        if (manifests.size > limits.maxRecords || bytes > limits.maxBytes || pixels > limits.maxPixels)
+            throw new Error('Material closure count/byte/pixel limit exceeded');
+        for (const pin of materialRecordDependencyPins(manifest)) {
+            const child = await reader.readManifest(pin.resourceId, pin.revisionId);
+            if (child.materialId !== pin.resourceId ||
+                child.revisionId !== pin.revisionId ||
+                pin.sha256 !== pin.revisionId)
+                throw new Error('Material dependency pin mismatch');
+            await visit(child);
+        }
+        active.delete(key);
+    };
+    for (const root of roots)
+        await visit(root);
+    const records = [];
+    for (const [key, manifest] of manifests) {
+        const record = snapshotAny(await reader.read(manifest.materialId, manifest.revisionId));
+        if (identity(record.manifest) !== key ||
+            canonicalMaterialJson(record.manifest) !== canonicalMaterialJson(manifest))
+            throw new Error('Material closure manifest changed during read');
+        validateMaterialManifestIdentityAny(record.manifest);
+        for (const map of record.manifest.maps)
+            if (digest(record.files[map.file]) !== map.sha256)
+                throw new Error('Material integrity hash mismatch');
+        records.push(record);
+    }
+    for (const record of records)
+        await verifyMaterialRecordContents(record, { materials: records });
+    return records;
+}
+function recordClosureReader(records, fallback) {
+    const byId = new Map();
+    const duplicates = new Map();
+    for (const record of records) {
+        const key = identity(record.manifest), existing = byId.get(key);
+        if (existing &&
+            canonicalMaterialJson(existing.manifest) !== canonicalMaterialJson(record.manifest))
+            throw new Error('Conflicting material record identity');
+        if (!existing)
+            byId.set(key, record);
+        else if (existing !== record)
+            duplicates.set(key, [...(duplicates.get(key) ?? []), record]);
+    }
+    return {
+        async readManifest(id, revision) {
+            const record = byId.get(`${id}/${revision}`);
+            if (record)
+                return record.manifest;
+            if (fallback)
+                return fallback.readManifest(id, revision);
+            throw new Error(`Missing pinned material revision: ${id} at ${revision}`);
+        },
+        async read(id, revision) {
+            const key = `${id}/${revision}`, record = byId.get(key);
+            if (record) {
+                // Deferred until the complete metadata graph is admitted, before dedup reuse.
+                for (const candidate of [record, ...(duplicates.get(key) ?? [])]) {
+                    const manifest = validateMaterialRecordShapeAny(candidate);
+                    if (canonicalMaterialJson(manifest) !== canonicalMaterialJson(record.manifest))
+                        throw new Error('Conflicting material record identity');
+                    for (const map of manifest.maps)
+                        if (digest(candidate.files[map.file]) !== map.sha256)
+                            throw new Error('Conflicting material record encoded integrity hash');
+                }
+                return record;
+            }
+            if (fallback)
+                return fallback.readRecordFiles(id, revision);
+            throw new Error(`Missing pinned material revision: ${id} at ${revision}`);
+        },
+    };
+}
+/** The input closure is admitted and encoded-verified before this capability is constructed. */
+function createPinnedMaterialMapPort(records) {
+    const entries = new Map();
+    for (const record of records) {
+        validateMaterialRecordShapeAny(record);
+        validateMaterialManifestIdentityAny(record.manifest);
+        for (const map of record.manifest.maps) {
+            if (digest(record.files[map.file]) !== map.sha256)
+                throw new Error('Material integrity hash mismatch');
+            entries.set(`${identity(record.manifest)}/${materialLibraryResourceId(record.manifest, map.slot)}`, { record, map });
+        }
+    }
+    const find = (resourceId, pin) => {
+        if (typeof resourceId !== 'string' || pin.sha256 !== pin.revisionId)
+            return undefined;
+        return entries.get(`${pin.resourceId}/${pin.revisionId}/${resourceId}`);
+    };
+    const describe = (resourceId, pin) => {
+        const entry = find(resourceId, pin);
+        if (!entry)
+            return undefined;
+        const { record, map } = entry;
+        return {
+            materialId: record.manifest.materialId,
+            revisionId: record.manifest.revisionId,
+            resourceId: resourceId,
+            slot: map.slot,
+            usage: map.usage,
+            colorSpace: map.colorSpace,
+            width: map.width,
+            height: map.height,
+            encodedByteLength: map.bytes,
+            imageSha256: map.sha256,
+            ...('pixelHash' in map ? { decodedPixelHash: map.pixelHash } : {}),
+        };
+    };
+    return {
+        describePinnedMaterialMap: describe,
+        async resolvePinnedMaterialMapPixels(resourceId, pin, context) {
+            context?.signal?.throwIfAborted();
+            const descriptor = describe(resourceId, pin), entry = find(resourceId, pin);
+            if (!descriptor || !entry)
+                throw new Error('Missing verified pinned-library map; approved resources cannot be atlas sources');
+            const { data, info } = await sharp(entry.record.files[entry.map.file], {
+                limitInputPixels: MATERIAL_LIBRARY_LIMITS.maxRecordPixels,
+                failOn: 'warning',
+            })
+                .ensureAlpha()
+                .raw()
+                .toBuffer({ resolveWithObject: true });
+            context?.signal?.throwIfAborted();
+            if (info.width !== descriptor.width ||
+                info.height !== descriptor.height ||
+                info.channels !== 4)
+                throw new Error('Pinned material decoded dimensions mismatch');
+            const decodedPixelHash = digest(data);
+            if (descriptor.decodedPixelHash && descriptor.decodedPixelHash !== decodedPixelHash)
+                throw new Error('Pinned material pixel hash mismatch');
+            return { descriptor, pixels: Uint8Array.from(data), decodedPixelHash };
+        },
+    };
+}
+async function verifyMaterialRecordContents(record, options) {
+    if (record.manifest.schemaVersion === 1)
+        return verifyMaterialRecordV1(record);
+    const manifest = validateMaterialRecordShapeAny(record);
+    validateMaterialManifestIdentityAny(manifest);
+    const pins = new Set(materialRecordDependencyPins(manifest).map((pin) => `${pin.resourceId}/${pin.revisionId}`));
+    pins.add(identity(manifest));
+    const resources = createPinnedMaterialMapPort((options?.materials ?? [record]).filter((candidate) => pins.has(identity(candidate.manifest))));
+    admitMaterialManifestRecipes(manifest, resources);
+    for (const map of manifest.maps) {
+        const bytes = record.files[map.file];
+        if (digest(bytes) !== map.sha256)
+            throw new Error('Material integrity hash mismatch');
+        const { data, info } = await sharp(bytes, {
+            limitInputPixels: MATERIAL_LIBRARY_LIMITS.maxRecordPixels,
+            failOn: 'warning',
+        })
+            .ensureAlpha()
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+        if (info.width !== map.width ||
+            info.height !== map.height ||
+            info.channels !== 4 ||
+            digest(data) !== map.pixelHash)
+            throw new Error('Material decoded pixel hash/dimensions mismatch');
+        const recipe = map.recipe;
+        if (!recipe)
+            continue;
+        if (recipe.kind === 'atlas') {
+            const compiled = await compileTextureAtlasSpecV1(recipe.spec, { resources });
+            if (canonicalMaterialJson(compiled.manifest) !== canonicalMaterialJson(recipe.manifest) ||
+                digest(compiled.pixels) !== map.pixelHash)
+                throw new Error('Atlas recipe/manifest/pixel hash mismatch');
+        }
+        else {
+            const compiled = recipe.spec.schemaVersion === 3
+                ? compileProceduralTextureSpecV3(recipe.spec)
+                : materialPixels(recipe.spec, recipe.derive);
+            if (compiled.recipeHash !== recipe.recipeHash || digest(compiled.pixels) !== recipe.pixelHash)
+                throw new Error('Procedural recipe/pixel hash mismatch');
+        }
+    }
+}
+/** Verify the complete immutable dependency closure; admission precedes byte snapshots and PNG decode. */
+export async function verifyMaterialRecord(record, options) {
+    if (record.manifest.schemaVersion === 1)
+        return verifyMaterialRecordV1(record);
+    await resolveMaterialRecordClosure([record.manifest], recordClosureReader([record, ...(options?.materials ?? [])]));
+}
+function admitMaterialManifestRecipes(manifest, resources) {
+    let texels = 0, work = 0, allocation = 0, encoded = 0;
+    for (const map of manifest.maps) {
+        encoded += map.bytes;
+        const recipe = map.recipe;
+        if (recipe?.kind === 'procedural') {
+            if (recipe.spec.schemaVersion === 3) {
+                const a = admitProceduralTextureSpecV3(recipe.spec);
+                texels += a.spec.width * a.spec.height;
+                work += a.estimatedWorkUnits;
+                allocation += a.conservativePixelAllocationBytes;
+            }
+            else {
+                texels += recipe.spec.size ** 2;
+                work += recipe.spec.size ** 2 * recipe.spec.layers.length * 16;
+                allocation += recipe.spec.size ** 2 * 12;
+            }
+        }
+        else if (recipe?.kind === 'atlas') {
+            const a = admitTextureAtlasSpecV1(recipe.spec, { resources });
+            texels += a.spec.width * a.spec.height + a.budget.sourceTexels;
+            work += a.budget.workUnits;
+            allocation += a.budget.conservativePixelAllocationBytes;
+            encoded += a.budget.encodedBytes;
+        }
+        else {
+            texels += map.width * map.height;
+            work += map.width * map.height * 12 + map.bytes * 8;
+            allocation += map.width * map.height * 12 + map.bytes * 2;
+        }
+    }
+    if (texels > PORTABLE_MATERIAL_V3_LIMITS.maxTexels ||
+        work > PORTABLE_MATERIAL_V3_LIMITS.maxWork ||
+        allocation > PORTABLE_MATERIAL_V3_LIMITS.maxTransientBytes ||
+        encoded > PORTABLE_MATERIAL_V3_LIMITS.maxEncodedBytes)
+        throw new Error('Material recipe aggregate texel/work/allocation/encoded budget exceeded');
+}
+export function validateMaterialLibraryPayloadAny(value) {
+    assertMaterialJson(value);
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid material resource payload');
+    if (value['schemaVersion'] === 1)
+        return validateMaterialLibraryPayload(value);
+    const payload = value;
+    if (Object.keys(payload).some((k) => !['schemaVersion', 'records'].includes(k)) ||
+        payload.schemaVersion !== 2 ||
+        !Array.isArray(payload.records) ||
+        payload.records.length > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+        throw new Error('Invalid material resource payload');
+    let bytes = 0, pixels = 0;
+    const seen = new Set();
+    for (const wire of payload.records) {
+        if (!wire ||
+            typeof wire !== 'object' ||
+            Object.keys(wire).some((k) => !['manifest', 'files'].includes(k)))
+            throw new Error('Invalid material resource record');
+        const manifest = validateMaterialManifestIdentityAny(wire.manifest), key = identity(manifest);
+        if (seen.has(key))
+            throw new Error('Duplicate material resource revision');
+        seen.add(key);
+        if (!wire.files ||
+            typeof wire.files !== 'object' ||
+            Array.isArray(wire.files) ||
+            Object.keys(wire.files).length !== manifest.maps.length)
+            throw new Error('Material payload inventory mismatch');
+        for (const map of manifest.maps) {
+            const encoded = wire.files[map.file];
+            if (typeof encoded !== 'string' ||
+                encoded.length !== Math.ceil(map.bytes / 3) * 4 ||
+                !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded))
+                throw new Error('Invalid material map base64');
+            bytes += map.bytes;
+            pixels += map.width * map.height;
+        }
+    }
+    if (bytes > MATERIAL_LIBRARY_LIMITS.maxPayloadBytes ||
+        pixels > MATERIAL_LIBRARY_LIMITS.maxPayloadPixels)
+        throw new Error('Material resource payload exceeds byte/pixel budget');
+    return payload;
+}
+export async function createMaterialLibraryPayload(records) {
+    if (records.every((r) => r.manifest.schemaVersion === 1))
+        return createMaterialLibraryPayloadV1(records);
+    // Admit metadata before snapshots, encoding or recipe/pixel compilation.
+    let bytes = 0, pixels = 0;
+    if (records.length > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+        throw new Error('Material payload record limit exceeded');
+    for (const record of records)
+        for (const map of validateMaterialManifestIdentityAny(record.manifest).maps) {
+            bytes += map.bytes;
+            pixels += map.width * map.height;
+        }
+    if (bytes > MATERIAL_LIBRARY_LIMITS.maxPayloadBytes ||
+        pixels > MATERIAL_LIBRARY_LIMITS.maxPayloadPixels)
+        throw new Error('Material payload byte/pixel budget exceeded');
+    const admitted = await resolveMaterialRecordClosure(records.map((r) => r.manifest), recordClosureReader(records));
+    const byIdentity = new Map(admitted.map((r) => [identity(r.manifest), r]));
+    const snapshots = records.map((r) => byIdentity.get(identity(r.manifest)));
+    return validateMaterialLibraryPayloadAny({
+        schemaVersion: 2,
+        records: snapshots.map((r) => ({
+            manifest: r.manifest,
+            files: Object.fromEntries(Object.entries(r.files).map(([name, bytes]) => [
+                name,
+                Buffer.from(bytes).toString('base64'),
+            ])),
+        })),
+    });
+}
+export async function decodeMaterialLibraryPayload(value) {
+    const payload = validateMaterialLibraryPayloadAny(value);
+    if (payload.schemaVersion === 1)
+        return decodeMaterialLibraryPayloadV1(payload);
+    const wires = payload.records.map((w) => ({
+        manifest: validateMaterialManifestIdentityAny(w.manifest),
+        files: { ...w.files },
+    }));
+    const byIdentity = new Map(wires.map((w) => [identity(w.manifest), w]));
+    const reader = {
+        async readManifest(id, revision) {
+            const wire = byIdentity.get(`${id}/${revision}`);
+            if (!wire)
+                throw new Error('Missing pinned material revision');
+            return wire.manifest;
+        },
+        async read(id, revision) {
+            const wire = byIdentity.get(`${id}/${revision}`);
+            if (!wire)
+                throw new Error('Missing pinned material revision');
+            return {
+                manifest: wire.manifest,
+                files: Object.fromEntries(Object.entries(wire.files).map(([name, encoded]) => [
+                    name,
+                    new Uint8Array(Buffer.from(encoded, 'base64')),
+                ])),
+            };
+        },
+    };
+    const admitted = await resolveMaterialRecordClosure(wires.map((w) => w.manifest), reader);
+    const result = new Map(admitted.map((r) => [identity(r.manifest), r]));
+    return wires.map((w) => result.get(identity(w.manifest)));
+}
+export async function createMaterialRecordV2(draft, options) {
+    assertMaterialJson(draft, true);
+    if (!draft || typeof draft !== 'object' || Array.isArray(draft))
+        throw new Error('Invalid material draft');
+    exactKeys(draft, [
+        'schemaVersion',
+        'materialId',
+        'name',
+        'tags',
+        'tileable',
+        'physicalSizeMeters',
+        'parameters',
+        'sources',
+        'maps',
+    ]);
+    const input = draft;
+    if (input['schemaVersion'] !== 2 ||
+        !Array.isArray(input['maps']) ||
+        input['maps'].length < 1 ||
+        input['maps'].length > 5)
+        throw new Error('V2 material requires schemaVersion2 and1..5 maps');
+    const candidates = options?.materials ?? [];
+    if (candidates.length > MATERIAL_LIBRARY_LIMITS.maxPayloadRecords)
+        throw new Error('Material source closure count limit exceeded');
+    const records = candidates.length
+        ? await resolveMaterialRecordClosure(candidates.map((r) => r.manifest), recordClosureReader(candidates))
+        : [];
+    const resources = createPinnedMaterialMapPort(records), prepared = [];
+    let texels = 0, work = 0, allocation = 0, encoded = 0;
+    for (const value of input['maps']) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error('Invalid material map draft');
+        exactKeys(value, [
+            'slot',
+            'sourceId',
+            'transforms',
+            'normalConvention',
+            'channelPacking',
+            'sampler',
+            'bytes',
+            'originalFile',
+            'procedural',
+            'derive',
+            'atlas',
+        ]);
+        const raw = value, slot = raw['slot'];
+        if (!MATERIAL_LIBRARY_SLOTS.includes(slot))
+            throw new Error('Unsupported material map slot');
+        const sampler = canonicalizePortableSamplerV1(raw['sampler']);
+        if (['bytes', 'procedural', 'atlas'].filter((k) => raw[k] !== undefined).length !== 1)
+            throw new Error('Supply exactly one map bytes/procedural/atlas source');
+        if (raw['procedural'] !== undefined) {
+            const spec = raw['procedural'];
+            if (spec.schemaVersion === 3) {
+                if (raw['derive'] !== undefined)
+                    throw new Error('V3 normal derivation is unsupported');
+                const a = admitProceduralTextureSpecV3(spec);
+                if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot])
+                    throw new Error('Procedural usage mismatch');
+                texels += a.spec.width * a.spec.height;
+                work += a.estimatedWorkUnits;
+                allocation += a.conservativePixelAllocationBytes;
+                prepared.push({ raw, slot, sampler, procedural: a.spec });
+            }
+            else {
+                const canonical = canonicalizeProceduralTextureSpecV2(spec);
+                if (canonical.usage !== MATERIAL_LIBRARY_USAGE[slot])
+                    throw new Error('Procedural usage mismatch');
+                texels += canonical.size ** 2;
+                work += canonical.size ** 2 * canonical.layers.length * 16;
+                allocation += canonical.size ** 2 * 12;
+                prepared.push({ raw, slot, sampler, procedural: canonical });
+            }
+        }
+        else if (raw['atlas'] !== undefined) {
+            if (raw['derive'] !== undefined)
+                throw new Error('Atlas derivation unsupported');
+            const a = admitTextureAtlasSpecV1(raw['atlas'], { resources });
+            if (a.spec.usage !== MATERIAL_LIBRARY_USAGE[slot] ||
+                canonicalMaterialJson(a.spec.sampler) !== canonicalMaterialJson(sampler))
+                throw new Error('Atlas usage/sampler mismatch');
+            texels += a.spec.width * a.spec.height + a.budget.sourceTexels;
+            work += a.budget.workUnits;
+            allocation += a.budget.conservativePixelAllocationBytes;
+            encoded += a.budget.encodedBytes;
+            prepared.push({ raw, slot, sampler, atlas: a.spec });
+        }
+        else {
+            if (raw['derive'] !== undefined || !(raw['bytes'] instanceof Uint8Array))
+                throw new Error('Invalid external map bytes/derivation');
+            const bytes = raw['bytes'];
+            if (bytes.length > MATERIAL_LIBRARY_LIMITS.maxMapBytes)
+                throw new Error('Material map encoded byte limit');
+            const d = materialPngDimensions(bytes);
+            if (d.width < 1 || d.height < 1 || d.width > 4096 || d.height > 4096)
+                throw new Error('Material map dimensions limit');
+            texels += d.width * d.height;
+            encoded += bytes.length;
+            work += d.width * d.height * 12 + bytes.length * 8;
+            allocation += d.width * d.height * 12 + bytes.length * 2;
+            prepared.push({ raw, slot, sampler, bytes });
+        }
+    }
+    if (texels > 4 * 1024 * 1024 ||
+        work > PORTABLE_MATERIAL_V3_LIMITS.maxWork ||
+        allocation > 64 * 1024 * 1024 ||
+        encoded > 16 * 1024 * 1024)
+        throw new Error('Material aggregate texel/work/allocation limit exceeded');
+    const maps = [], files = {}, pins = new Map();
+    for (const item of prepared) {
+        const { raw, slot, sampler } = item;
+        let bytes, pixelHash, recipe;
+        if (item.procedural !== undefined) {
+            const spec = item.procedural;
+            const compiled = spec.schemaVersion === 3
+                ? compileProceduralTextureSpecV3(spec)
+                : materialPixels(spec, raw['derive']);
+            const d = compiled.spec.schemaVersion === 3
+                ? { width: compiled.spec.width, height: compiled.spec.height }
+                : { width: compiled.spec.size, height: compiled.spec.size };
+            pixelHash = digest(compiled.pixels);
+            bytes = new Uint8Array(await sharp(compiled.pixels, { raw: { ...d, channels: 4 } })
+                .png({ compressionLevel: 9, adaptiveFiltering: false })
+                .toBuffer());
+            recipe = {
+                kind: 'procedural',
+                compilerId: compiled.spec.schemaVersion === 3
+                    ? PROCEDURAL_TEXTURE_V3_COMPILER_ID
+                    : 'kiln.procedural-texture.v2',
+                spec: compiled.spec,
+                recipeHash: compiled.recipeHash,
+                pixelHash,
+                encoder,
+                ...(raw['derive']
+                    ? {
+                        derive: structuredClone(raw['derive']),
+                    }
+                    : {}),
+            };
+        }
+        else if (item.atlas !== undefined) {
+            const compiled = await compileTextureAtlasSpecV1(item.atlas, { resources });
+            pixelHash = compiled.manifest.decodedPixelHash;
+            bytes = new Uint8Array(await sharp(compiled.pixels, {
+                raw: { width: compiled.spec.width, height: compiled.spec.height, channels: 4 },
+            })
+                .png({ compressionLevel: 9, adaptiveFiltering: false })
+                .toBuffer());
+            recipe = {
+                kind: 'atlas',
+                compilerId: TEXTURE_ATLAS_COMPILER_ID,
+                spec: compiled.spec,
+                manifest: compiled.manifest,
+                encoder,
+            };
+            for (const r of compiled.spec.regions)
+                if (r.source.kind === 'resource')
+                    pins.set(`${r.source.pin.resourceId}/${r.source.pin.revisionId}`, r.source.pin);
+        }
+        else {
+            bytes = item.bytes.slice();
+            const decoded = await sharp(bytes, {
+                limitInputPixels: MATERIAL_LIBRARY_LIMITS.maxRecordPixels,
+                failOn: 'warning',
+            })
+                .ensureAlpha()
+                .raw()
+                .toBuffer();
+            pixelHash = digest(decoded);
+        }
+        const d = materialPngDimensions(bytes), file = `${slot}.png`;
+        if (files[file])
+            throw new Error('Duplicate material map slot');
+        files[file] = bytes;
+        maps.push({
+            slot,
+            file,
+            ...d,
+            sha256: digest(bytes),
+            bytes: bytes.length,
+            usage: MATERIAL_LIBRARY_USAGE[slot],
+            colorSpace: slot === 'baseColor' || slot === 'emissive' ? 'srgb' : 'linear',
+            sampler,
+            pixelHash,
+            sourceId: raw['sourceId'],
+            transforms: structuredClone(raw['transforms']),
+            ...(slot === 'normal'
+                ? {
+                    normalConvention: (raw['normalConvention'] ??
+                        (recipe ? 'opengl' : undefined)),
+                }
+                : {}),
+            ...(slot === 'metallicRoughness'
+                ? {
+                    channelPacking: (raw['channelPacking'] ??
+                        (recipe
+                            ? 'r-occlusion-g-roughness-b-metallic'
+                            : undefined)),
+                }
+                : {}),
+            ...(raw['originalFile'] ? { originalFile: raw['originalFile'] } : {}),
+            ...(recipe ? { recipe } : {}),
+        });
+    }
+    const manifest = materialManifestV2Schema.parse({
+        ...input,
+        schemaVersion: 2,
+        revisionId: `sha256:${'0'.repeat(64)}`,
+        tags: input['tags'] ?? [],
+        parameters: input['parameters'] ?? {},
+        maps,
+        dependencies: [...pins.values()],
+    });
+    manifest.revisionId = revisionHash(manifest);
+    const record = { manifest, files };
+    await verifyMaterialRecord(record, { materials: [...records, record] });
+    return record;
+}