@plasius/asset-contracts 0.6.0 → 0.8.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/adr-0012-model-resource-promotion-closure.md

@@ -0,0 +1,92 @@
+# ADR 0012: Model Resource Promotion Closure
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task 51; site Feature 1153 / Epic 1147
+
+## Context
+
+Released resource and texture qualifiers verify complete inventories and bytes,
+retain original resource identities and distinguish derived output. Conversion
+qualification evaluates raw canonical diagnostics. Typed GPU promotion already
+checks bytes, exact versions and GPU compatibility envelopes. ModelCandidate
+and its confirmation already enforce rights, security, fidelity, render and
+human gates. Published asset-pipeline owns orchestration. Missing composition
+must not create an alternate approval route or duplicate those contracts.
+
+## Decision
+
+Add opt-in createModelResourcePromotionRecord. Supply a typed model promotion,
+complete source inventory/bytes, existing output texture qualification inputs,
+raw diagnostic input, exact resource-to-package/path bindings and the existing
+candidate/confirmation. Reuse all existing factories and qualifiers. Snapshot
+inert metadata and both byte sets before awaiting; retain only frozen metadata
+in output, never bytes, Blobs or GPU objects. No dependency update is required.
+
+Qualify both complete packages, exact immutable distinct source/output
+identities, graph and candidate converter identity/version/source format, source
+entrypoint digest and converted output digest. Require re-evaluated diagnostic
+and loss arrays to equal candidate evidence. Bind every projected diagnostic
+resource and candidate LOD/collision/fidelity resource to a qualified file's
+path/hash/length/MIME; runtime resources use the output package and LOD0 names
+its entrypoint. Existing catalog candidates also match target asset/version.
+Explicit bindings avoid deriving trust from opaque URI strings.
+
+Require a passed review without blocking findings; use the existing candidate
+confirmation factory for rights/security/fidelity/render/human policy. Reuse
+createGpuAssetPromotionRecord for the exact copied output bytes and typed GPU
+envelope. Bind the HTTPS runtime URI suffix to assetId/version/entrypoint;
+existing credential/query/fragment restrictions still apply. These are local
+contract checks. Hosted services must authenticate approvers, verify signed
+tokens and validate evidence issuers; this library grants no approval authority.
+
+The separate package closureHash is SHA-256 over existing canonical GPU JSON
+serialization of version, qualified source/output, evaluated diagnostics and
+sorted resource bindings. It includes all file descriptors, original/derived
+lineage and authored reload metadata. It excludes promotion events and
+candidate/confirmation tokens so renewed approval does not change package
+identity. Preserve existing leaf/assembly processing closureHash semantics.
+
+Rollback requires locally qualified prior/current results through a private
+WeakSet, then requalifies target bytes and all independent gates. Compare exact
+prior package closure, manifest and runtime URI; enforce same asset/channel,
+distinct current/target versions and rollbackOfVersion=current.version. Emit
+both exact closure identities. No version, historical record or runtime pointer
+is mutated. Forward calls reject rollback metadata. JSON clones are not local
+qualification: reconstruct and requalify persisted inputs before use. The
+WeakSet is process/module-instance evidence only, not a durable signature or
+trusted history database. Hosted storage owns create-only immutable writes,
+verified historical records, concurrency control and pointer-last transactions.
+
+## NFRs, alternatives and limits
+
+Fixed inert metadata/count/character/depth and byte ceilings, sequential package
+qualification, native abort/default 10s deadline (1–60s), bounded underlying
+hashing, no network/retries/logging. A digest cannot be preempted; phase checks
+prevent late successful return. Normalize even hostile thrown proxies to fixed
+value-free errors. Authored package metadata and candidate content remain
+trusted data requiring privacy minimization; only diagnostic projections are
+public-safe. No raw forensic diagnostics or provider strings are retained.
+
+Tightening legacy factories would break staged construction. Copying pipeline
+or candidate policy would drift from released owners. Accepting structural or
+serialized history as qualified would lose the local byte-check evidence.
+Persisting bytes in a mutable qualification registry would add memory and
+lifecycle ownership; use bounded ephemeral copies and weak membership instead.
+
+This boundary does not parse internal model references, prove embedding or
+atlas algorithms, revalidate shader ABI policy (Task 23), supply animation
+schemas (Task 12), verify external signatures, or perform storage/promotion.
+Existing exact immutable assembly child refs stay in candidate evidence; their
+separate catalog packages remain hosted resolver responsibilities.
+
+Backend evaluator gpu.model.conversion.enabled controls adoption. Enabled
+callers use the opt-in composition; disabled/rollback adoption uses legacy
+factories. No flag service I/O/mutation or UI capability belongs in this library.
+Requirements-first tests cover complete real glTF/GLB fixtures, byte drift,
+evidence/resource/gate drift, exact rollback, deterministic hashes, immutable
+snapshots and malformed/limit/cancel/deadline cases. Qualify packed and public
+ESM/CJS/types/browser consumers and released asset-pipeline orchestration.
+Release additive minor through existing source PR/exact-main push CI and
+two-phase cd.yml/main/production hosted OIDC path, then verify registry
+integrity/provenance before Done. No site deployment is authorized by Task 51.

package/docs/adrs/index.md

@@ -10,3 +10,5 @@
 - [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)
+- [ADR 0012: Model Resource Promotion Closure](./adr-0012-model-resource-promotion-closure.md)

package/docs/tdrs/index.md

@@ -5,3 +5,5 @@
 - [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)
+- [TDR 0007: Model Resource Promotion Closure](./tdr-0007-model-resource-promotion-closure.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/docs/tdrs/tdr-0007-model-resource-promotion-closure.md

@@ -0,0 +1,63 @@
+# TDR 0007: Model Resource Promotion Qualification
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task 51; site Feature 1153
+- Decision: ADR 0012
+
+1. Read inert root/options records; reject getters, symbols, exotic/sparse
+   arrays, prototype keys and unknown fields. Snapshot all metadata, validate
+   existing candidate and confirmation, and copy both bounded byte inventories
+   before awaiting. Keep the original privately verified core graph.
+2. Qualify source inventory/bytes, then output graph/resources/derived metadata,
+   then re-evaluate raw canonical diagnostics with the released evaluator.
+3. Match immutable distinct asset/version identities; typed output manifest and
+   promotion manifest are equal with files sorted by path. Match graph and
+   candidate converter ID/version/source format, exact source and output hashes,
+   source provenance and diagnostics/losses. A warning is allowed only when the
+   candidate carries the same freshly evaluated warning; unsupported/failed or
+   unconsented loss never grants promotion.
+4. Validate unique explicit URI bindings to source/output file descriptors.
+   Compare every runtime LOD/collision/fidelity resource and projected diagnostic
+   resource exactly. LOD0 must bind the output entrypoint. Core still owns
+   embedded resources and original/derived graph relationships; no parser here.
+5. Require review passed with no blocking findings, existing candidate gates
+   and exact confirmation. Check typed GPU manifest equality, ABI envelopes and
+   canonical JSON file bytes through createGpuAssetPromotionRecord. Runtime URI
+   must end in /assetId/version/entrypoint and satisfy existing immutable HTTPS
+   policy. Hosted verifiers still authenticate signatures and approvers.
+6. SHA-256 canonicalize version/source/output/diagnostics/sorted bindings. Leave
+   events, candidate and confirmation out of package identity, allowing fresh
+   approval for the exact prior package. Retain candidate/confirmation alongside
+   the closure for callers' independent evidence checks.
+7. For rolled-back outcome require private local membership for both prior and
+   current; exact prior closure/manifest/runtime URI, same asset/channel, target
+   prior version and rollbackOfVersion=current version. Emit from/to exact
+   closure identities and never mutate history. Forward calls reject history.
+   Persisted JSON must be reconstructed and qualified again; storage owns
+   authenticated historical admission, immutable create-only writes and CAS.
+
+Limits: 1,024 public resource bindings; 262,144 metadata values; 2,097,152 UTF-16
+characters; depth 24; 2,048 characters/string and 128/key. Existing byte ceilings
+apply independently to source and output (16,384 files, 64 MiB/file,128 MiB per
+package). Copies are bounded and ephemeral; upstream qualifiers also copy
+payloads. No retained byte cache or mutable durable registry. Package phases
+are sequential; the final existing typed factory retains its bounded file-set
+hashing behavior. Default deadline 10s, configured integer1–60,000ms; cancellation
+and timer race cover async work, phase checks cover bounded synchronous work.
+No retry/I/O or logging. Value-free errors normalize hostile upstream proxies.
+
+NFR evidence: requirements-based real GLB header/JSON and source fixtures,
+exact hashes/bytes, positive warnings, stale diagnostics, missing/tampered
+resources, alias/identity/URI drift, review/rights/security/GPU/human gates,
+brand and rollback mismatch, fresh confirmation, deterministic inventory order,
+copy/freeze isolation, malformed/limits/deadlines/cancel and flag adoption tests.
+Run full Node24 frozen tests/privacy/coverage>=80% with all changed sources in
+LCOV, types/lint/build/tree/full/runtime audits/privacy/pack/drypublish. Isolated
+packed/public ESM/CJS/types/browser consumers use released asset-pipeline to
+verify state transitions still require review and approval. Accessibility/SEO
+N/A library; trusted metadata requires caller minimization; observability uses
+stable codes without logging. Existing package boundaries/API remain stable.
+Remote flag gpu.model.conversion.enabled uses backend evaluator; capability N/A.
+Release via approved cd.yml/main/production/OIDC with exact CI and public
+registry/provenance/consumer verification. No site/backend secretref change.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/asset-contracts",
-  "version": "0.6.0",
+  "version": "0.8.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,8 @@ 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-resource-promotion.js";
 export * from "./model-conversion-diagnostics.js";
 export {
   GPU_SHADER_STORE_FEATURE_FLAG,

package/src/model-resource-promotion.ts

@@ -0,0 +1,219 @@
+import { canonicalizeGpuContract, computeSha256 } from "@plasius/gpu-shader";
+import { assertImmutableAssetVersion } from "./asset-version.js";
+import { qualifyModelResourceManifest, MODEL_RESOURCE_MANIFEST_LIMITS, type ModelResourceManifestQualificationInput, type ModelResourceFileInput } from "./model-resource-manifest.js";
+import { qualifyModelTextureResources, type ModelTextureResourceQualificationInput, type QualifiedModelTextureResources } from "./model-texture-resources.js";
+import { qualifyModelConversionDiagnostics, type ModelConversionDiagnosticsInput, type QualifiedModelConversionDiagnostics } from "./model-conversion-diagnostics.js";
+import { createModelCandidate, createModelCandidateConfirmation, createModelResourceRef, type ModelCandidate, type ModelCandidateConfirmation, type ModelResourceRef } from "./model-resolution.js";
+import { createModelAssetManifest, createGpuAssetPromotionRecord, type AssetManifest, type AssetPromotionRecord, type ModelAssetManifest } from "./index.js";
+
+/** Hard ceilings supplement the existing per-package byte and graph limits. */
+export const MODEL_RESOURCE_PROMOTION_LIMITS = Object.freeze({ bindings: 1024, values: 262_144, characters: 2_097_152, depth: 24, timeoutMs: 60_000 });
+/** Explicit location of a public evidence resource inside one qualified package. */
+export interface ModelPromotionResourceBinding {
+  readonly resource: ModelResourceRef;
+  readonly package: "source" | "output";
+  readonly filePath: string;
+}
+/** Existing contracts composed without granting durable storage or signature authority. */
+export interface ModelResourcePromotionInput {
+  readonly promotion: AssetPromotionRecord<ModelAssetManifest>;
+  readonly source: Omit<ModelResourceManifestQualificationInput, "signal" | "timeoutMs">;
+  readonly output: ModelTextureResourceQualificationInput;
+  readonly diagnostics: ModelConversionDiagnosticsInput;
+  readonly resourceBindings: readonly ModelPromotionResourceBinding[];
+  readonly candidate: ModelCandidate;
+  readonly confirmation: ModelCandidateConfirmation;
+  readonly rollback?: { readonly prior: QualifiedModelResourcePromotion; readonly current: QualifiedModelResourcePromotion };
+}
+/** Native controls cover the entire composition, with no I/O, retries or pointer writes. */
+export interface ModelResourcePromotionOptions { readonly signal?: AbortSignal; readonly timeoutMs?: number }
+/** Frozen call-time evidence. Requalify persisted JSON; a clone has no local qualification brand. */
+export interface QualifiedModelResourcePromotion {
+  readonly contractVersion: 1;
+  readonly promotion: AssetPromotionRecord<ModelAssetManifest>;
+  readonly source: AssetManifest;
+  readonly output: QualifiedModelTextureResources;
+  readonly diagnostics: QualifiedModelConversionDiagnostics;
+  readonly resourceBindings: readonly ModelPromotionResourceBinding[];
+  readonly candidate: ModelCandidate;
+  readonly confirmation: ModelCandidateConfirmation;
+  /** Separate package closure digest; preserves legacy candidate leaf/assembly hash semantics. */
+  readonly closureHash: string;
+  readonly rollback?: { readonly fromVersion: string; readonly fromClosureHash: string; readonly toVersion: string; readonly toClosureHash: string };
+}
+/** Stable value-free failure; upstream exceptions and authored values are never included. */
+export class ModelResourcePromotionError extends TypeError {
+  constructor(public readonly code: "invalid-input" | "limit-exceeded" | "package-mismatch" | "evidence-mismatch" | "gate-blocked" | "rollback-mismatch" | "aborted" | "deadline-exceeded") {
+    super(`Invalid model resource promotion: ${code}`); this.name = "ModelResourcePromotionError";
+  }
+}
+const qualified = new WeakSet<object>();
+function fail(code: ModelResourcePromotionError["code"] = "invalid-input"): never { throw new ModelResourcePromotionError(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__", "constructor", "prototype"].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();
+  return Array.from({ length: value.length }, (_, i) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) fail();
+    return descriptor.value;
+  });
+}
+function snapshot(value: unknown, budget: { values: number; characters: number }, depth = 0): unknown {
+  if (--budget.values < 0 || depth > MODEL_RESOURCE_PROMOTION_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_RESOURCE_MANIFEST_LIMITS.files).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);
+}
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const byteLengthGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const bufferGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+function copyFiles(value: unknown): readonly ModelResourceFileInput[] {
+  let total = 0;
+  const files = array(value, MODEL_RESOURCE_MANIFEST_LIMITS.files).map((v) => {
+    const file = fields(v, ["path", "bytes", "contentType"]); const bytes = file.bytes;
+    if (typeof file.path !== "string" || typeof file.contentType !== "string" || !(bytes instanceof Uint8Array)
+      || Object.getPrototypeOf(bytes) !== Uint8Array.prototype || !(bufferGetter.call(bytes) instanceof ArrayBuffer)) fail();
+    const length = byteLengthGetter.call(bytes) as number;
+    total += length;
+    if (length > MODEL_RESOURCE_MANIFEST_LIMITS.fileBytes || total > MODEL_RESOURCE_MANIFEST_LIMITS.totalBytes) fail("limit-exceeded");
+    return { path: file.path, bytes, contentType: file.contentType };
+  });
+  return files.map((f) => ({ ...f, bytes: new Uint8Array(f.bytes) }));
+}
+const same = (a: unknown, b: unknown): boolean => canonicalizeGpuContract(a) === canonicalizeGpuContract(b);
+const entry = (m: AssetManifest) => m.files.find((f) => f.path === m.entrypoint)!;
+const identity = (m: AssetManifest): string => `${m.assetId}/${m.version}`;
+
+/**
+ * Qualifies complete source/output inventories and conversion lineage before
+ * composing existing typed promotion, rights, hard-gate and human confirmation
+ * contracts. Tokens remain trusted hosted assertions; this is not a signature
+ * verifier, parser, storage transaction or permission grant. Rollback rechecks
+ * target bytes/gates and requires locally qualified exact prior/current records.
+ */
+export async function createModelResourcePromotionRecord(input: ModelResourcePromotionInput, options: ModelResourcePromotionOptions = {}): Promise<QualifiedModelResourcePromotion> {
+  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_RESOURCE_PROMOTION_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, ["promotion", "source", "output", "diagnostics", "resourceBindings", "candidate", "confirmation", "rollback"]);
+    const budget = { values: MODEL_RESOURCE_PROMOTION_LIMITS.values, characters: MODEL_RESOURCE_PROMOTION_LIMITS.characters };
+    const snap = (v: unknown) => snapshot(v, budget);
+    const promotionInput = snap(root.promotion) as ModelResourcePromotionInput["promotion"];
+    const sourceInput = fields(root.source, ["manifest", "packageManifest", "files"]);
+    const outputInput = fields(root.output, ["manifest", "packageManifest", "files", "graph", "resources", "derived"]);
+    const sourceMetadata = { manifest: snap(sourceInput.manifest) as AssetManifest, packageManifest: snap(sourceInput.packageManifest) as ModelResourceManifestQualificationInput["packageManifest"] };
+    const outputMetadata = { manifest: snap(outputInput.manifest) as AssetManifest, packageManifest: snap(outputInput.packageManifest) as ModelTextureResourceQualificationInput["packageManifest"],
+      graph: outputInput.graph as ModelTextureResourceQualificationInput["graph"], resources: snap(outputInput.resources) as ModelTextureResourceQualificationInput["resources"], derived: snap(outputInput.derived) as ModelTextureResourceQualificationInput["derived"] };
+    const rawDiagnostics = snap(root.diagnostics);
+    const candidate = createModelCandidate(snap(root.candidate));
+    const confirmation = createModelCandidateConfirmation(snap(root.confirmation), candidate, candidate.resolutionId);
+    const bindings = array(snap(root.resourceBindings), MODEL_RESOURCE_PROMOTION_LIMITS.bindings).map((v): ModelPromotionResourceBinding => {
+      const b = fields(v, ["resource", "package", "filePath"]);
+      if ((b.package !== "source" && b.package !== "output") || typeof b.filePath !== "string") fail();
+      return Object.freeze({ resource: createModelResourceRef(b.resource), package: b.package, filePath: b.filePath });
+    }).sort((a, b) => a.resource.uri < b.resource.uri ? -1 : a.resource.uri > b.resource.uri ? 1 : 0);
+    const history = root.rollback === undefined ? undefined : fields(root.rollback, ["prior", "current"]);
+    if (history && (!qualified.has(history.prior as object) || !qualified.has(history.current as object))) fail("rollback-mismatch");
+    const prior = history?.prior as QualifiedModelResourcePromotion | undefined;
+    const current = history?.current as QualifiedModelResourcePromotion | undefined;
+    const sourceFiles = copyFiles(sourceInput.files); const outputFiles = copyFiles(outputInput.files);
+    check();
+    const interrupted = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new ModelResourcePromotionError("deadline-exceeded")), Math.max(1, timeoutMs - (performance.now() - started)));
+      onAbort = () => reject(new ModelResourcePromotionError("aborted"));
+      if (signal) AbortSignal.prototype.addEventListener.call(signal, "abort", onAbort, { once: true });
+    });
+    // Sequential package hashing limits digest concurrency. Every caller byte was
+    // copied above; only inert snapshots and the immutable core graph cross await.
+    const work = async () => {
+      const source = await qualifyModelResourceManifest({ ...sourceMetadata, files: sourceFiles, signal, timeoutMs }); check();
+      const output = await qualifyModelTextureResources({ ...outputMetadata, files: outputFiles }, { signal, timeoutMs }); check();
+      const diagnostics = await qualifyModelConversionDiagnostics(rawDiagnostics, { signal, timeoutMs }); check();
+      assertImmutableAssetVersion(source.version); assertImmutableAssetVersion(output.manifest.version);
+      if (identity(source) === identity(output.manifest) || !same(output.manifest, createModelAssetManifest({ ...promotionInput.manifest, files: [...promotionInput.manifest.files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0) })) || output.manifest.assetKind !== "model") fail("package-mismatch");
+      const converter = candidate.processingManifest.converter;
+      if (!diagnostics.technicalAccepted || !same(diagnostics.source, candidate.provenance)
+        || diagnostics.source.contentHash !== entry(source).sha256 || output.source.sourceContentHash !== entry(source).sha256
+        || converter.sourceContentHash !== entry(source).sha256 || converter.outputContentHash !== entry(output.manifest).sha256
+        || converter.id !== output.source.converterId || converter.version !== output.source.converterVersion
+        || converter.sourceFormat !== output.source.sourceFormat || !same(diagnostics.converter.diagnostics, converter.diagnostics) || !same(diagnostics.converter.losses, converter.losses)) fail("evidence-mismatch");
+      const byUri = new Map<string, ModelPromotionResourceBinding>();
+      for (const binding of bindings) {
+        const file = (binding.package === "source" ? source : output.manifest).files.find((f) => f.path === binding.filePath);
+        if (!file || byUri.has(binding.resource.uri) || file.sha256 !== binding.resource.sha256 || file.byteLength !== binding.resource.byteLength || file.contentType !== binding.resource.contentType) fail("evidence-mismatch");
+        byUri.set(binding.resource.uri, binding);
+      }
+      const requireResource = (resource: ModelResourceRef, outputOnly = false) => {
+        const binding = byUri.get(resource.uri);
+        if (!binding || !same(binding.resource, resource) || (outputOnly && binding.package !== "output")) fail("evidence-mismatch");
+        return binding;
+      };
+      for (const d of diagnostics.diagnostics) if (d.resource) requireResource(d.resource);
+      for (const lod of candidate.processingManifest.lods) requireResource(lod.resource, true);
+      if (candidate.processingManifest.collision.resource) requireResource(candidate.processingManifest.collision.resource, true);
+      for (const f of candidate.processingManifest.fidelityEvidence) if (f.evidenceResource) requireResource(f.evidenceResource, true);
+      if (requireResource(candidate.processingManifest.lods[0]!.resource, true).filePath !== output.manifest.entrypoint) fail("evidence-mismatch");
+      if (candidate.assetRef.disposition === "existing" && (candidate.assetRef.asset.assetId !== output.manifest.assetId || candidate.assetRef.asset.version !== output.manifest.version)) fail("evidence-mismatch");
+      if (promotionInput.sourceAdapter !== output.manifest.sourceAdapter || promotionInput.reviewReport.passed !== true || promotionInput.reviewReport.findings.some((f) => f.severity === "blocking")) fail("gate-blocked");
+      const expectedSuffix = `/${output.manifest.assetId}/${output.manifest.version}/${output.manifest.entrypoint}`;
+      const runtimeUri = new URL(promotionInput.runtimeManifestUri);
+      if (!runtimeUri.pathname.endsWith(expectedSuffix)) fail("evidence-mismatch");
+      const promotion = await createGpuAssetPromotionRecord(promotionInput, new Map(outputFiles.map((f) => [f.path, f.bytes]))); check();
+      // Promotion event/time/approver are intentionally outside this digest, so
+      // an exact rollback can reuse the same package with a new approval event.
+      const closure = { contractVersion: 1 as const, source, output, diagnostics, resourceBindings: Object.freeze(bindings), candidate, confirmation };
+      const closureHash = await computeSha256(new TextEncoder().encode(canonicalizeGpuContract({ contractVersion: 1, source, output, diagnostics, resourceBindings: bindings }))); check();
+      let rollback: QualifiedModelResourcePromotion["rollback"];
+      if (promotion.outcome === "rolled-back") {
+        if (!prior || !current || prior.promotion.assetId !== promotion.assetId || current.promotion.assetId !== promotion.assetId
+          || prior.promotion.runtimeChannel !== promotion.runtimeChannel || current.promotion.runtimeChannel !== promotion.runtimeChannel
+          || promotion.version !== prior.promotion.version || promotion.version === current.promotion.version || promotion.rollbackOfVersion !== current.promotion.version
+          || closureHash !== prior.closureHash || !same(promotion.manifest, prior.promotion.manifest)
+          || promotion.runtimeManifestUri !== prior.promotion.runtimeManifestUri) fail("rollback-mismatch");
+        rollback = Object.freeze({ fromVersion: current.promotion.version, fromClosureHash: current.closureHash, toVersion: prior.promotion.version, toClosureHash: prior.closureHash });
+      } else if (history || promotion.rollbackOfVersion !== undefined) fail("rollback-mismatch");
+      const result = Object.freeze({ ...closure, promotion, closureHash, ...(rollback ? { rollback } : {}) });
+      qualified.add(result); return result;
+    };
+    return await Promise.race([work(), interrupted]);
+  } catch (error) {
+    // Even a proxy thrown by an inert-input inspection must not escape with
+    // authored exception text. Never invoke an upstream error's accessors.
+    let code: unknown;
+    try { code = Object.getOwnPropertyDescriptor(error, "code")?.value; } catch { return fail(); }
+    if (["invalid-input", "limit-exceeded", "package-mismatch", "evidence-mismatch", "gate-blocked", "rollback-mismatch", "aborted", "deadline-exceeded"].includes(code as string)) return fail(code as ModelResourcePromotionError["code"]);
+    return fail();
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && onAbort) AbortSignal.prototype.removeEventListener.call(signal, "abort", onAbort);
+  }
+}