@plasius/asset-contracts 0.6.0 → 0.7.0

package/docs/adrs/adr-0011-reloadable-texture-resource-roles.md

@@ -0,0 +1,92 @@
+# ADR 0011: Reloadable Texture and Resource Roles
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task 50; site Feature 1153 / Epic 1147
+
+## Context
+
+Released AssetFileRole already defines model, binary, texture and metadata.
+Task 48 qualifies exact file inventory/bytes, and model-core 0.7.0 owns verified
+resources, material-to-texture references and authored interpretation metadata.
+Neither boundary maps the canonical inventory to storage roles or records
+separate GPU upload/atlas exports while retaining original resource identities.
+Legacy descriptor construction must remain compatible.
+
+## Decision
+
+Add opt-in async qualifyModelTextureResources. Compose the existing
+qualifyModelResourceManifest and accept only a privately branded model-core
+GpuModelResourceGraph. Reuse canonical materials/textures, including samplers,
+color spaces, usages, transforms, embedding policy and authored sourceMetadata.
+Never reimplement the canonical schemas or parse a model format here.
+
+Use the matching module-format core guard through a normal named import. A
+new graph is already immutable/verified. Dynamically importing ESM from the
+CJS build would select a different private WeakSet and reject legitimate CJS
+require-created graphs. This correctness requirement makes lazy loading this
+guard inappropriate. Core remains external; bundlers can remove unused exports
+with sideEffects=false. Existing diagnostic evaluation retains its dynamic
+import. Consumers must produce graphs using the same installed core instance
+and module format as this package (ESM import with ESM, require with CJS).
+
+Map canonical mesh entries to model/binary, material/animation to JSON metadata,
+texture to supported image texture, and auxiliary to binary or JSON metadata.
+Existing role values are unchanged. Explicit source bindings match every graph
+resource exactly once. External files match graph path/hash/length/MIME;
+embedded resources retain independent identity and name their owning model
+entrypoint. Do not invent separate embedded archive entries or replace source
+hashes with entrypoint hashes. Preserve original conversion provenance.
+
+A derived record has gpu-upload or texture-atlas semantics, a distinct exported
+file path and unique original sourceResourceIds. Uploads use auxiliary/binary
+buffer files; atlases use texture/image files and image sources. Reject missing
+sources, output collisions, source overwrite, unknown roles and incompatible
+MIME declarations. Output is frozen deterministic version-1 JSON with no Blob
+or renderer allocation. Canonical material/texture arrays retain their order.
+
+## Limits and trust
+
+Snapshot caller metadata and exact bytes before awaiting. Reuse Task 48 path,
+collision, byte/hash and inventory gates. Apply fixed resource/derived/graph,
+metadata value/character/depth and deadline limits. Honor native cancellation;
+use no I/O, retries, mutable registry, arbitrary callbacks or logging. Hashing
+cannot be interrupted inside Web Crypto; checks prevent successful late return.
+Errors expose fixed codes only. Synchronous bounded work is checked before and
+after; it cannot be preempted by a JavaScript timer.
+
+Authored sourceMetadata, material names/extensions and original texture paths
+are deliberately preserved trusted package content. The output is NOT a
+public-safe diagnostics response. Adapters must minimize/sanitize authored
+metadata before public distribution; use Task 49's separate diagnostic
+projection for public technical messages. Core-brand validation cannot be
+replaced by shape checks or serialization; reloaded canonical payloads must be
+verified again by core before a new graph is created.
+
+Embedded ownership, internal model references and derivation algorithms remain
+trusted adapter assertions. Exact byte qualification does not prove semantic
+format validity, inspect derived image signatures, verify a GPU upload layout,
+attest an atlas algorithm, or authorize promotion. Tasks 12/23/51 retain
+animation metadata, shader ABI and promotion closure. No existing approval gate
+changes. No dependency/version/peer/override changes are required.
+
+## Alternatives, rollout and delivery
+
+Adding storage role enums would duplicate existing roles and break closed
+consumers. Tightening legacy factories would break staged construction.
+Flattening derived output over authored textures would lose reload fidelity.
+Copying core schemas or accepting a structural graph would discard verification.
+
+The backend evaluator for gpu.model.conversion.enabled controls consumer
+adoption. Enabled callers opt into this qualifier; disabled/rollback callers
+retain existing factories. The library performs no flag lookup/mutation. No UI
+or entitlement capability applies. Test both branches and rollback.
+
+Require requirements-first round-trip/contract tests, malformed input/role/MIME
+and missing/duplicate identity cases, deterministic/frozen output, cancellation,
+deadline and bounded metadata tests. Run Node 24 frozen install, full tests and
+privacy, coverage >=80% and changed-source LCOV, lint/types/build, audits/tree,
+privacy/pack and packed/public ESM/CJS/types/browser consumers. Release additive
+minor through source PR, exact-main push CI and existing two-phase
+cd.yml/main/production hosted OIDC governance (ADR 0007), then verify registry
+integrity/provenance. Site adoption/deployment remains separate.

package/docs/adrs/index.md

@@ -10,3 +10,4 @@
 - [ADR 0008: Package-Owned Issue Tracking](./adr-0008-package-owned-issue-tracking.md)
 - [ADR 0009: Additive Model Resource Manifest Qualification](./adr-0009-model-resource-manifest-qualification.md)
 - [ADR 0010: Public Conversion Diagnostics](./adr-0010-public-conversion-diagnostics.md)
+- [ADR 0011: Reloadable Texture and Resource Roles](./adr-0011-reloadable-texture-resource-roles.md)

package/docs/tdrs/index.md

@@ -5,3 +5,4 @@
 - [TDR 0003: PVOX Validation and Confirmation Binding](./tdr-0003-pvox-validation-and-confirmation-binding.md)
 - [TDR 0004: Model Resource Manifest Qualification](./tdr-0004-model-resource-manifest-qualification.md)
 - [TDR 0005: Public Conversion Diagnostics](./tdr-0005-public-conversion-diagnostics.md)
+- [TDR 0006: Reloadable Texture and Resource Qualification](./tdr-0006-reloadable-texture-resource-roles.md)

package/docs/tdrs/tdr-0006-reloadable-texture-resource-roles.md

@@ -0,0 +1,91 @@
+# TDR 0006: Reloadable Texture and Resource Qualification
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task 50; site Feature 1153
+- Decision: ADR 0011
+
+## Sequence and role policy
+
+1. Read inert root/options records without executing getters. Verify the graph
+   with the matching ESM/CJS core instance's private brand, not a shape cast.
+2. Snapshot inventory, resource bindings and derived records with shared fixed
+   budgets before awaiting. Reject unknown fields, accessors, symbols, prototype
+   keys, sparse/exotic arrays, non-finite values and malformed IDs.
+3. Invoke existing qualifyModelResourceManifest, which synchronously snapshots
+   manifest metadata and all bounded exact byte payloads before its first hash.
+   Race the operation against native cancellation/deadline and clean listeners.
+4. Map every inventory entry to an existing storage role and MIME policy:
+
+| Canonical role | Storage role | MIME policy |
+| --- | --- | --- |
+| mesh | model | model/*, application/json, application/octet-stream, text/plain |
+| mesh | binary | application/octet-stream, application/vnd.plasius.gpu-buffer |
+| material or animation | metadata | application/json |
+| texture | texture | image/png, image/jpeg, image/webp, image/ktx2 |
+| auxiliary | binary or metadata | buffer MIME for binary; application/json for metadata |
+
+5. Require exactly one binding per graph resource. For external resources,
+   compare exact graph path, verified content hash/length/MIME and appropriate
+   image/buffer role. Embedded resources bind only the model entrypoint and
+   retain their independent hash/length/MIME rather than the container's hash.
+6. Validate each derived output's distinct existing file and original source
+   IDs. gpu-upload requires auxiliary/binary with buffer MIME. texture-atlas
+   requires texture with image MIME and image sources. Never overwrite a bound
+   source file or reassign a source identity to derived bytes. Multiple authored
+   texture interpretations may share one original image resource.
+7. Bound canonical authored material/texture/provenance metadata, retain its
+   already immutable values and emit JSON without Blob payloads. Sort resource
+   bindings by resourceId, derivatives by path and source-ID sets by UTF-16
+   code units. Preserve canonical array order and original provenance.
+
+This is declarative role qualification, not a parser, MIME sniffer, GPU-layout
+validator or promotion attestation. Derived records are optional (empty array);
+caller-declared derivation/embedding is not cryptographic algorithm evidence.
+
+## Fixed limits and errors
+
+Resource bindings: 16,384; derived records: 4,096; core graph nodes: 65,536.
+Shared metadata budgets: 262,144 values, 2,097,152 UTF-16 characters, depth 16,
+2,048 characters/string and 128/key; arrays at most 16,384. IDs use 128-character
+canonical tokens. The existing byte qualifier also applies its own limits:
+16,384 files, 64 MiB/file, 128 MiB total and portable-path rules. Default deadline
+10 seconds, configurable integer 1–60,000 ms. Cancellation/timer cover the
+async boundary and checks surround bounded synchronous phases. Web Crypto work
+cannot be interrupted but never yields a successful result after cancellation
+or expiry. Work is sequential and introduces no retry or storage/network I/O.
+
+ModelTextureResourceError exposes invalid-input, limit-exceeded,
+unverified-graph, package-mismatch, resource-mismatch, role-mismatch, aborted or
+deadline-exceeded. Upstream errors are normalized without caller values.
+
+## Verification, rollout and limitations
+
+Synthetic fixtures independently verify core image/buffer bytes; canonical
+material references require a real UV accessor. Compare external hashes and
+reloaded material JSON with core metadata; serialize and reconstruct canonical
+materials/textures, then verify core accepts the reloaded document. An embedded
+image fixture uses an actual data URI without a fictitious exported source
+image. Derivative hashes differ from the source identity. Test duplicate/missing
+resources, role/MIME drift, unknown roles, graph clone rejection, multiple
+interpretations, getters/proxies, mutation isolation, limits, deadline/abort and
+legacy enabled/disabled/rollback composition. Qualify both typed model and
+legacy envelopes; do not modify shader ABI or animation schemas.
+
+Trusted authored sourceMetadata is intentionally preserved; callers own privacy
+minimization before distribution. Public diagnostics use the separate Task 49
+projection. UI accessibility/SEO/browser UI and durable storage controls are N/A
+here. Security/privacy: value-free failures, bounded inert input and exact bytes.
+Performance/reliability: fixed budgets, sequential hashing, no GPU allocation,
+I/O or retry. Maintainability/testability: existing schemas/qualifier reuse and
+immutable deterministic JSON. Compatibility: additive API, unchanged legacy
+factories, dependency versions and existing approval gates.
+
+The source-of-truth backend evaluator gpu.model.conversion.enabled controls
+adoption. Disable/rollback retains legacy factories; no service call or mutation
+inside this package and capability N/A. Normal module-format core guard import
+preserves private brand identity across ESM/CJS. Verify packed/public ESM/CJS
+consumers with their matching core entry and browser bundling/execution. Release
+through existing PR/exact-main CI/cd.yml/production hosted OIDC route, verify
+public registry integrity/provenance and dependency signatures. No site release
+or backend secretref mutation is authorized by this Task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/asset-contracts",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Canonical contracts for Plasius asset jobs, model resolution, immutable WGSL shader assets, reviews, and promotion records.",
   "type": "module",
   "sideEffects": false,

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./pvox-hash-preimage.js";
 export * from "./pvox-model-resolution.js";
 export * from "./pvox-model-resolution-schema.js";
 export * from "./model-resource-manifest.js";
+export * from "./model-texture-resources.js";
 export * from "./model-conversion-diagnostics.js";
 export {
   GPU_SHADER_STORE_FEATURE_FLAG,

package/src/model-texture-resources.ts

@@ -0,0 +1,215 @@
+import { isGpuModelResourceGraph } from "@plasius/gpu-model-core";
+import type {
+  GpuModelMaterial, GpuModelTexture, GpuModelProvenance, GpuModelResourceGraph,
+  GpuModelResourceLocation, GpuModelTextureEmbeddingPolicy,
+} from "@plasius/gpu-model-core";
+import { qualifyModelResourceManifest, ModelResourceManifestError, type ModelResourceManifestQualificationInput } from "./model-resource-manifest.js";
+import type { AssetManifest, AssetFileDescriptor } from "./index.js";
+
+/** Hard ceilings for the additive package role boundary; callers cannot raise them. */
+export const MODEL_TEXTURE_RESOURCE_LIMITS = Object.freeze({ resources: 16_384, derived: 4096, nodes: 65_536, values: 262_144, characters: 2_097_152, depth: 16, timeoutMs: 60_000 });
+/** An embedded resource names its owning entrypoint; external resources name their exact graph path. */
+export interface ModelTextureResourceBinding { readonly resourceId: string; readonly filePath: string }
+/** Declarative derived output; source identities remain independent of output hashes and paths. */
+export interface ModelDerivedTextureResource {
+  readonly role: "gpu-upload" | "texture-atlas";
+  readonly filePath: string;
+  readonly sourceResourceIds: readonly string[];
+}
+/** Existing exact-byte inventory plus a privately verified canonical graph and explicit export bindings. */
+export interface ModelTextureResourceQualificationInput extends Omit<ModelResourceManifestQualificationInput, "signal" | "timeoutMs"> {
+  readonly graph: GpuModelResourceGraph;
+  readonly resources: readonly ModelTextureResourceBinding[];
+  readonly derived: readonly ModelDerivedTextureResource[];
+}
+/** Deadline and cancellation cover hashing and bounded synchronous qualification. */
+export interface ModelTextureResourceQualificationOptions { readonly signal?: AbortSignal; readonly timeoutMs?: number }
+/** JSON resource identity without a Blob, renderer allocation or credential-bearing URL. */
+export interface QualifiedModelTextureResource extends ModelTextureResourceBinding {
+  readonly kind: "image" | "buffer";
+  readonly contentHash: string;
+  readonly byteLength: number;
+  readonly mimeType: string;
+  readonly location: GpuModelResourceLocation;
+  readonly exportEmbeddingPolicy: GpuModelTextureEmbeddingPolicy;
+}
+/** Trusted package metadata, including authored sourceMetadata; not a public-safe diagnostic projection. */
+export interface QualifiedModelTextureResources {
+  readonly contractVersion: 1;
+  readonly manifest: AssetManifest;
+  readonly source: GpuModelProvenance;
+  readonly resources: readonly QualifiedModelTextureResource[];
+  readonly materials: readonly GpuModelMaterial[];
+  readonly textures: readonly GpuModelTexture[];
+  readonly derived: readonly ModelDerivedTextureResource[];
+}
+/** Fixed, value-free errors. No caller metadata or upstream exception text is exposed. */
+export class ModelTextureResourceError extends TypeError {
+  constructor(public readonly code: "invalid-input" | "limit-exceeded" | "unverified-graph" | "package-mismatch" | "resource-mismatch" | "role-mismatch" | "aborted" | "deadline-exceeded") {
+    super(`Invalid model texture resources: ${code}`); this.name = "ModelTextureResourceError";
+  }
+}
+function fail(code: ModelTextureResourceError["code"] = "invalid-input"): never { throw new ModelTextureResourceError(code); }
+function fields(value: unknown, allowed?: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const keys = Reflect.ownKeys(value);
+  if (keys.length > 1024) fail("limit-exceeded");
+  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of keys) {
+    if (typeof key !== "string" || key.length > 128 || ["__proto__", "prototype", "constructor"].includes(key) || (allowed && !allowed.includes(key))) fail();
+    const property = Object.getOwnPropertyDescriptor(value, key)!;
+    if (!("value" in property) || !property.enumerable) fail();
+    result[key] = property.value;
+  }
+  return result;
+}
+function array(value: unknown, maximum: number): unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) fail();
+  if (value.length > maximum) fail("limit-exceeded");
+  if (Reflect.ownKeys(value).length !== value.length + 1) fail();
+  const result: unknown[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const property = Object.getOwnPropertyDescriptor(value, String(i));
+    if (!property || !("value" in property) || !property.enumerable) fail();
+    result.push(property.value);
+  }
+  return result;
+}
+function snapshot(value: unknown, budget: { values: number; characters: number }, depth = 0): unknown {
+  if (--budget.values < 0 || depth > MODEL_TEXTURE_RESOURCE_LIMITS.depth) fail("limit-exceeded");
+  if (value === null || value === undefined || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    budget.characters -= value.length;
+    if (value.length > 2048 || budget.characters < 0) fail("limit-exceeded");
+    return value;
+  }
+  if (Array.isArray(value)) return Object.freeze(array(value, MODEL_TEXTURE_RESOURCE_LIMITS.resources).map((v) => snapshot(v, budget, depth + 1)));
+  const result = fields(value);
+  for (const key of Object.keys(result)) {
+    budget.characters -= key.length;
+    if (budget.characters < 0) fail("limit-exceeded");
+    result[key] = snapshot(result[key], budget, depth + 1);
+  }
+  return Object.freeze(result);
+}
+function token(value: unknown): string {
+  if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value)) fail();
+  return value;
+}
+const compare = (a: string, b: string): number => a < b ? -1 : a > b ? 1 : 0;
+const imageMime = (value: string): boolean => ["image/png", "image/jpeg", "image/webp", "image/ktx2"].includes(value);
+const bufferMime = (value: string): boolean => ["application/octet-stream", "application/vnd.plasius.gpu-buffer"].includes(value);
+function storageRole(role: unknown, file: AssetFileDescriptor): void {
+  const valid = role === "texture" ? file.role === "texture" && imageMime(file.contentType)
+    : role === "material" || role === "animation" ? file.role === "metadata" && file.contentType === "application/json"
+      : role === "mesh" ? (file.role === "binary" && bufferMime(file.contentType)) || (file.role === "model" && (file.contentType.startsWith("model/") || ["application/json", "application/octet-stream", "text/plain"].includes(file.contentType)))
+        : role === "auxiliary" && ((file.role === "binary" && bufferMime(file.contentType)) || (file.role === "metadata" && file.contentType === "application/json"));
+  if (!valid) fail("role-mismatch");
+}
+
+/**
+ * Qualify reload metadata without parsing formats, allocating GPU objects or
+ * replacing authored resource identities. Metadata is trusted package content;
+ * adapters must sanitize it before public use. This is not promotion evidence.
+ */
+export async function qualifyModelTextureResources(input: ModelTextureResourceQualificationInput, options: ModelTextureResourceQualificationOptions = {}): Promise<QualifiedModelTextureResources> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let signal: AbortSignal | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    const started = performance.now();
+    const controls = fields(options, ["signal", "timeoutMs"]);
+    const timeoutMs = controls.timeoutMs === undefined ? 10_000 : controls.timeoutMs;
+    if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MODEL_TEXTURE_RESOURCE_LIMITS.timeoutMs) fail();
+    signal = controls.signal as AbortSignal | undefined;
+    const aborted = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted")!.get!;
+    const check = () => {
+      if (signal !== undefined && aborted.call(signal)) fail("aborted");
+      if (performance.now() - started >= timeoutMs) fail("deadline-exceeded");
+    };
+    check();
+    const root = fields(input, ["manifest", "packageManifest", "files", "graph", "resources", "derived"]);
+    const graph = root.graph;
+    if (!isGpuModelResourceGraph(graph)) fail("unverified-graph");
+    if (graph.nodes.length > MODEL_TEXTURE_RESOURCE_LIMITS.nodes) fail("limit-exceeded");
+    const budget = { values: MODEL_TEXTURE_RESOURCE_LIMITS.values, characters: MODEL_TEXTURE_RESOURCE_LIMITS.characters };
+    const inventory = snapshot(root.packageManifest, budget) as ModelResourceManifestQualificationInput["packageManifest"];
+    const bindings = array(snapshot(root.resources, budget), MODEL_TEXTURE_RESOURCE_LIMITS.resources).map((value) => {
+      const binding = fields(value, ["resourceId", "filePath"]);
+      return Object.freeze({ resourceId: token(binding.resourceId), filePath: tokenPath(binding.filePath) });
+    });
+    const derived = array(snapshot(root.derived, budget), MODEL_TEXTURE_RESOURCE_LIMITS.derived).map((value) => {
+      const record = fields(value, ["role", "filePath", "sourceResourceIds"]);
+      if (record.role !== "gpu-upload" && record.role !== "texture-atlas") fail("role-mismatch");
+      const ids = array(record.sourceResourceIds, MODEL_TEXTURE_RESOURCE_LIMITS.resources).map(token);
+      if (!ids.length || new Set(ids).size !== ids.length) fail("resource-mismatch");
+      return Object.freeze({ role: record.role, filePath: tokenPath(record.filePath), sourceResourceIds: Object.freeze(ids.sort(compare)) });
+    });
+    check();
+    const interrupted = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new ModelTextureResourceError("deadline-exceeded")), Math.max(1, timeoutMs - (performance.now() - started)));
+      onAbort = () => reject(new ModelTextureResourceError("aborted"));
+      if (signal) AbortSignal.prototype.addEventListener.call(signal, "abort", onAbort, { once: true });
+    });
+    // The existing qualifier snapshots metadata AND byte payloads synchronously
+    // before its first digest. Promise.race owns both rejection paths immediately.
+    const manifest = await Promise.race([
+      qualifyModelResourceManifest({ manifest: root.manifest as AssetManifest, files: root.files as ModelResourceManifestQualificationInput["files"], packageManifest: inventory, signal, timeoutMs }),
+      interrupted,
+    ]);
+    check();
+    const files = new Map(manifest.files.map((file) => [file.path, file]));
+    const roles = new Map(inventory.entries.map((entry) => [entry.path, entry.role]));
+    for (const entry of inventory.entries) storageRole(entry.role, files.get(entry.path)!);
+    const resources = new Map(graph.nodes.filter((node) => node.kind === "resource").map((node) => [node.id, node.value]));
+    if (bindings.length !== resources.size || new Set(bindings.map((b) => b.resourceId)).size !== bindings.length) fail("resource-mismatch");
+    const resourceFiles = new Set<string>();
+    const qualified = bindings.map((binding): QualifiedModelTextureResource => {
+      const value = resources.get(binding.resourceId); const file = files.get(binding.filePath);
+      if (!value || !file) fail("resource-mismatch");
+      const { resource, location, exportEmbeddingPolicy } = value;
+      if (location.kind === "external") {
+        if (binding.filePath !== location.relativePath || file.sha256 !== resource.contentHash || file.byteLength !== resource.byteLength || file.contentType !== resource.mimeType) fail("resource-mismatch");
+        if (resource.kind === "image" ? roles.get(file.path) !== "texture" : file.role !== "binary") fail("role-mismatch");
+      } else if (binding.filePath !== manifest.entrypoint || file.role !== "model") fail("resource-mismatch");
+      resourceFiles.add(binding.filePath);
+      return Object.freeze({ ...binding, kind: resource.kind, contentHash: resource.contentHash, byteLength: resource.byteLength, mimeType: resource.mimeType, location, exportEmbeddingPolicy });
+    });
+    const outputFiles = new Set<string>();
+    for (const output of derived) {
+      const file = files.get(output.filePath);
+      if (!file || outputFiles.has(output.filePath) || resourceFiles.has(output.filePath)) fail("resource-mismatch");
+      outputFiles.add(output.filePath);
+      for (const id of output.sourceResourceIds) {
+        const source = resources.get(id);
+        if (!source || (output.role === "texture-atlas" && source.resource.kind !== "image")) fail("resource-mismatch");
+      }
+      if (output.role === "gpu-upload" ? file.role !== "binary" || !bufferMime(file.contentType) || roles.get(file.path) !== "auxiliary"
+        : file.role !== "texture" || !imageMime(file.contentType) || roles.get(file.path) !== "texture") fail("role-mismatch");
+    }
+    const materials = graph.nodes.filter((node) => node.kind === "material").map((node) => node.value);
+    const textures = graph.nodes.filter((node) => node.kind === "texture").map((node) => node.value);
+    const source = graph.nodes.find((node) => node.kind === "provenance")!;
+    if (source.kind !== "provenance") fail();
+    // Bound authored metadata without substituting a new material/texture schema.
+    snapshot({ materials, textures, source: source.value }, budget);
+    check();
+    return Object.freeze({ contractVersion: 1, manifest, source: source.value,
+      resources: Object.freeze(qualified.sort((a, b) => compare(a.resourceId, b.resourceId))),
+      materials: Object.freeze(materials), textures: Object.freeze(textures),
+      derived: Object.freeze(derived.sort((a, b) => compare(a.filePath, b.filePath))) });
+  } catch (error) {
+    if (error instanceof ModelTextureResourceError) throw error;
+    if (error instanceof ModelResourceManifestError) return fail(error.code === "aborted" || error.code === "deadline-exceeded" || error.code === "limit-exceeded" ? error.code : "package-mismatch");
+    return fail();
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && onAbort) AbortSignal.prototype.removeEventListener.call(signal, "abort", onAbort);
+  }
+}
+function tokenPath(value: unknown): string {
+  // Full portable-path and collision checks are reused from the byte qualifier.
+  if (typeof value !== "string" || !value.length || value.length > 1024) fail();
+  return value;
+}