@plasius/asset-contracts 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -14,6 +14,40 @@
 - **Security**
   - (placeholder)
 
+## [0.8.0] - 2026-10-24
+
+- **Added**
+  - Opt-in model promotion composition binds complete source/output resource
+    bytes, conversion diagnostics and existing approval gates, with exact prior
+    package rollback and immutable source/derived lineage.
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.7.0] - 2026-10-24
+
+- **Added**
+  - Opt-in reloadable canonical texture/material resource qualification, exact
+    storage role/MIME mapping and separate GPU upload/atlas source bindings.
+    Preserves authored metadata and original resource identity through JSON reload.
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.6.0] - 2026-10-24
 
 - **Added**
@@ -349,3 +383,5 @@
 [0.4.6]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.4.6
 [0.5.0]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.5.0
 [0.6.0]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.6.0
+[0.7.0]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.7.0
+[0.8.0]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.8.0

package/README.md

@@ -11,6 +11,52 @@
 Canonical contracts for Plasius asset jobs, model resolution, immutable WebGPU
 shader assets, screenshot plans, reviews, and promotion records.
 
+## Model resource promotion closure
+
+`createModelResourcePromotionRecord(input, options?)` composes a typed
+`AssetPromotionRecord<ModelAssetManifest>`, complete source and output byte
+inventories, raw conversion diagnostics, explicit public resource bindings,
+and existing `ModelCandidate` / `ModelCandidateConfirmation` evidence. The
+output uses the existing texture/resource qualification input. Source and
+output must have distinct immutable asset/version identities. Runtime URIs
+end in `/assetId/version/entrypoint` and satisfy existing immutable HTTPS rules.
+
+The boundary verifies all file paths/hashes/lengths/MIME, original/derived
+lineage, converter/source/output identity, re-evaluated diagnostics and runtime
+resource bindings before calling `createGpuAssetPromotionRecord`. Review must
+pass without blocking findings; existing rights, security, fidelity, render,
+GPU envelope and human confirmation contracts remain required. Every runtime
+LOD/collision/fidelity resource and projected diagnostic resource needs one
+`{ resource, package: "source" | "output", filePath }` binding to verified bytes.
+
+The frozen result retains `promotion`, `source`, qualified `output`, evaluated
+`diagnostics`, sorted `resourceBindings`, `candidate`, `confirmation` and a
+separate deterministic `closureHash`. This package digest includes both complete
+inventories and lineage; it preserves existing candidate leaf/assembly hash
+semantics. No bytes or Blobs are retained. Raw provider diagnostic text is
+excluded; authored package and candidate metadata remain trusted content that
+callers must minimize before public distribution.
+
+For `outcome: "rolled-back"`, supply `rollback: { prior, current }` with results
+qualified by this same installed module instance. Requalify the exact prior
+source/output bytes and approval gates; target version/manifest/closure/runtime
+URI must match `prior`, and `rollbackOfVersion` must equal `current`'s distinct
+version for the same asset/channel. The result names both exact closure hashes.
+New independent confirmation is allowed without changing package identity.
+Forward calls reject rollback metadata. A JSON clone has no local qualification
+brand: reconstruct and qualify its original inputs before using it as history.
+
+This function performs no storage or pointer changes. Hosted services own
+signature/issuer verification, authenticated immutable history, create-only
+version admission and pointer-last concurrency control. Local qualification
+does not prove embedded model references, derivation algorithms or GPU matrix
+policy; existing downstream gates still apply. Fixed metadata/byte limits,
+abort and a default 10s deadline (configurable 1–60s) bound work. Errors contain
+fixed codes only. Backend `gpu.model.conversion.enabled` controls opt-in caller
+adoption; disabled/rollback adoption retains existing factories. Capability N/A
+for this package-only API. See [ADR0012](./docs/adrs/adr-0012-model-resource-promotion-closure.md)
+and [TDR0007](./docs/tdrs/tdr-0007-model-resource-promotion-closure.md).
+
 ## Install
 
 ```bash
@@ -28,6 +74,7 @@ The exported surface covers:
 - asset job metadata contracts
 - manifest and file descriptor contracts
 - opt-in canonical model package inventory and exact-byte qualification
+- reloadable canonical texture/material metadata and explicit upload/atlas roles
 - opt-in public-safe canonical conversion diagnostics and resource/source binding
 - screenshot plan definitions
 - review findings and review report contracts
@@ -91,8 +138,8 @@ Embedded resources remain inside their owning entrypoint; list only actual
 exported files. This helper checks bytes and declarations, not internal format
 references, MIME sniffing, malware, rendering, storage or promotion authority.
 Keep source provenance in the canonical document and do not substitute derived
-hashes for original source hashes. Detailed role mapping, animation/source
-relationships and promotion closure remain separately tracked work. The result
+hashes for original source hashes. Role qualification is available through the additive helper below; animation/source
+relationships remain adapter-owned; promotion composition uses the opt-in closure boundary above. The result
 is qualification at call time; callers must preserve the exact bytes in their
 own immutable storage boundary.
 
@@ -105,6 +152,71 @@ runtime parser or renderer loading. Downstream adoption must use a released
 package. See [ADR 0009](./docs/adrs/adr-0009-model-resource-manifest-qualification.md)
 and [TDR 0004](./docs/tdrs/tdr-0004-model-resource-manifest-qualification.md).
 
+## Reloadable Texture and Resource Roles
+
+`qualifyModelTextureResources` composes exact byte/inventory qualification with
+published model-core's verified material/texture graph. It keeps authored
+metadata and source image identity separate from derived GPU uploads/atlases.
+
+```ts
+import { qualifyModelTextureResources } from "@plasius/asset-contracts";
+
+const reload = await qualifyModelTextureResources({
+  manifest, packageManifest, files: exportedFiles,
+  graph: verifiedCanonicalGraph,
+  resources: [
+    { resourceId: "source-image", filePath: "textures/source.png" },
+    { resourceId: "embedded-buffer", filePath: "model.gltf" },
+  ], // Exactly one binding per graph resource.
+  derived: [
+    { role: "gpu-upload", filePath: "derived/upload.bin", sourceResourceIds: ["source-image"] },
+    { role: "texture-atlas", filePath: "derived/atlas.png", sourceResourceIds: ["source-image"] },
+  ], // Or [] when no derivative is exported.
+}, { signal: abortController.signal, timeoutMs: 10_000 });
+// Persist JSON.stringify(reload) alongside the qualified immutable bytes.
+```
+
+Use existing storage roles: canonical texture → texture with PNG/JPEG/WebP/KTX2
+MIME; material/animation → metadata with application/json; mesh → model or
+binary; auxiliary → binary or JSON metadata. Uploads require auxiliary/binary
+buffer files, atlases texture/image files. See TDR 0006 for the exact MIME table.
+Missing/duplicate resources, incompatible roles/MIME, unknown roles, graph
+clones and source/output collisions reject. External files match graph path,
+hash, byte length and MIME; embedded resources name the owning model entrypoint
+and retain their independent resource hash. List only actual exported files.
+
+The frozen version-1 result contains manifest, original source provenance,
+resources, canonical materials/textures and derived records. Authored usage,
+color space, sampler, binding transform, embedding policy and sourceMetadata
+survive JSON reload. Original image IDs and bytes are never replaced by atlas
+hashes or upload paths. No Blob payload or renderer allocation is serialized.
+Adapters own model-internal references, derivation algorithms and image content
+inspection; qualification does not attest those operations or grant promotion.
+Task 12 animation schemas and Task 23 shader ABI remain separate;
+promotion composition uses the opt-in closure boundary above.
+
+This is **trusted package metadata**, including names, extensions, original
+paths and authored sourceMetadata. Minimize/sanitize that data before public
+distribution; use the separate public diagnostics API for technical responses.
+Serialized graphs lose their private brand: verify reloaded canonical resources
+and reconstruct a graph through core before qualifying again. Produce graphs
+with the same installed model-core instance and matching module format (ESM
+import with ESM, require with CJS). The normal named guard import preserves that
+identity; unused exports remain tree-shakeable through sideEffects=false.
+
+Inputs/bytes are snapshotted before awaiting. Fixed ceilings are 16,384 resource
+bindings, 4,096 derivatives, 65,536 graph nodes, shared 262,144 metadata values,
+2,097,152 UTF-16 characters, depth 16 and 2,048 characters/string. Existing file
+limits also apply. Default deadline 10 seconds, allowed range 1–60,000 ms;
+cancellation/deadline reject without a partial result. In-flight Web Crypto
+cannot be cancelled. ModelTextureResourceError.code is value-free.
+
+The backend evaluator gpu.model.conversion.enabled controls caller adoption;
+disabled/rollback paths retain legacy factories. No lookup/mutation or UI
+capability is introduced. Dependencies and legacy factories are unchanged.
+See [ADR 0011](./docs/adrs/adr-0011-reloadable-texture-resource-roles.md) and
+[TDR 0006](./docs/tdrs/tdr-0006-reloadable-texture-resource-roles.md).
+
 ## Public Conversion Diagnostics
 
 `qualifyModelConversionDiagnostics` adds an opt-in, version-1 JSON boundary over