@plasius/asset-contracts 0.4.6 → 0.6.0

package/CHANGELOG.md

@@ -14,6 +14,46 @@
 - **Security**
   - (placeholder)
 
+## [0.6.0] - 2026-10-24
+
+- **Added**
+  - Opt-in public-safe canonical conversion diagnostics with fixed codes/text,
+    resource/source identity, explicit loss/fallback evidence and legacy converter
+    projections. Reuses lazy model-core evaluation; independent approval and
+    promotion gates remain required.
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.5.0] - 2026-10-24
+
+- **Added**
+  - Opt-in canonical model resource manifest qualification with deterministic
+    file order, complete inventory/entrypoint checks, exact byte/hash/MIME
+    binding, bounded snapshots and cancellation/deadline handling. Existing
+    manifest factories remain compatible.
+  - (placeholder)
+
+- **Changed**
+  - Add exact published `@plasius/gpu-model-core@0.7.0` for canonical public
+    inventory types; no runtime model parser import or other dependency update.
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - Update development-only fast-uri from 3.1.8 to fixed 3.1.9 after the full
+    qualification audit reported URI-normalization advisories; retain major 3.
+  - (placeholder)
+
 ## [0.4.6] - 2026-10-23
 
 - **Added**
@@ -307,3 +347,5 @@
 [0.4.4]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.4.4
 [0.4.5]: https://github.com/Plasius-LTD/asset-contracts/releases/tag/v0.4.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

package/README.md

@@ -27,6 +27,8 @@ The exported surface covers:
   helpers
 - asset job metadata contracts
 - manifest and file descriptor contracts
+- opt-in canonical model package inventory and exact-byte qualification
+- opt-in public-safe canonical conversion diagnostics and resource/source binding
 - screenshot plan definitions
 - review findings and review report contracts
 - immutable promotion record contracts
@@ -45,6 +47,126 @@ The exported surface covers:
 - generic manifest inference plus byte-verified typed promotion that preserves
   specialized manifest fields
 
+## Canonical Model Resource Qualification
+
+`qualifyModelResourceManifest` binds an existing `AssetManifest` to a published
+`@plasius/gpu-model-core` `ResourcePackageManifest` and the complete exported
+file bytes. Existing factories retain their staged-construction behavior.
+
+```ts
+import { qualifyModelResourceManifest } from "@plasius/asset-contracts";
+
+// Obtain manifest, packageManifest and exportedFiles from your trusted pipeline.
+const qualified = await qualifyModelResourceManifest({
+  manifest,
+  packageManifest,
+  files: exportedFiles, // [{ path, bytes: Uint8Array, contentType }]
+  signal: abortController.signal,
+  timeoutMs: 10_000,
+});
+```
+
+Every manifest path, canonical inventory path and payload path must correspond
+exactly, including the entrypoint. The qualifier checks actual byte lengths and
+SHA-256 digests, agreement of canonical MIME declarations, portable relative
+POSIX paths, case-insensitive collisions and file/directory conflicts. Optional
+inventory MIME declarations may be omitted; the descriptor and payload MIME
+declarations are required. It preserves roles, sourceAdapter, source/derived
+paths and specialized model metadata, returning frozen descriptors sorted by
+locale-independent code-unit order. Typed model inputs are also revalidated by
+`createModelAssetManifest`.
+
+Pass ordinary `Uint8Array` values backed by `ArrayBuffer`; use
+`new Uint8Array(nodeBuffer)` for Node buffers. Shared buffers, getters in
+metadata, exotic records and sparse arrays are rejected. Metadata and bytes
+are copied before the first hash. `MODEL_RESOURCE_MANIFEST_LIMITS` caps files
+at 16,384, each file at 64 MiB, total bytes at 128 MiB, metadata depth at 16 and
+metadata values at 262,144. Metadata strings are capped at 2,048 characters,
+keys at 128, paths at 1,024 and MIME declarations at 128. The default deadline
+is 10 seconds; callers may choose 1–60,000 ms. Cancellation and deadline checks
+surround each bounded digest; Web Crypto cannot cancel an in-flight digest.
+Failures use value-free `ModelResourceManifestError.code` values.
+
+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
+is qualification at call time; callers must preserve the exact bytes in their
+own immutable storage boundary.
+
+The backend remote evaluator owns `gpu.model.conversion.enabled`. Call this
+helper on the enabled adoption path; disabled and rollback paths retain the
+existing factory path. The package performs no flag lookup or live mutation,
+and adds no UI capability. The model-core dependency is exact published
+`0.7.0` for public type compatibility; its import here is type-only, with no
+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).
+
+## Public Conversion Diagnostics
+
+`qualifyModelConversionDiagnostics` adds an opt-in, version-1 JSON boundary over
+published model-core diagnostics. It reuses the canonical evaluator, loading it
+only when this async helper is called. Existing factories remain compatible.
+
+```ts
+import { qualifyModelConversionDiagnostics } from "@plasius/asset-contracts";
+
+const result = await qualifyModelConversionDiagnostics({
+  outcome: "completed", // or "unsupported" / "failed" from your trusted adapter
+  source: publicSourceProvenance, // existing ModelProvenance; original source hash
+  report: canonicalDiagnosticInput, // model-core GpuModelDiagnosticInput
+  resources: [{ path: "/meshes/0", resource: publicModelResourceRef }],
+}, { signal: abortController.signal, timeoutMs: 10_000 });
+// Only these existing diagnostic/loss fields belong in ModelConverterEvidence:
+const converterEvidence = { ...trustedConverterIdentity, ...result.converter };
+```
+
+Every non-root diagnostic path must match exactly one supplied resource binding.
+The root path `/` refers to `result.source`; no resource is fabricated. Resource
+references use existing credential-free `mcp://models/...` contracts and include
+hash, length and MIME identity. Conflicting references for one URI reject. These
+bindings and provenance are caller assertions, not proof that bytes were read.
+Use manifest qualification and independent promotion checks at their boundaries.
+
+Statuses are derived deterministically: explicit failure wins, then unsupported
+data/outcome, then canonical rejection, then warning or clean success. Loss
+requires canonical explicit consent; denied loss produces blocking legacy loss
+evidence. Only canonical accepted repairs receive a fallback rule id. Unknown
+repair rules remain blocking. Arbitrary adapter codes, messages, private paths,
+provider exceptions, original repair values and forensic rawSource are never
+serialized; unknown adapter codes map to fixed category codes. Public codes are
+`conversion.warning`, `conversion.repair`, `conversion.loss.dropped`,
+`conversion.loss.approximated`, `conversion.unsupported`, `conversion.blocked`
+and `conversion.failed`, with fixed bounded messages. Malformed input rejects
+with value-free `ModelConversionDiagnosticsError.code`.
+
+This projection is technical evidence only. `technicalAccepted` never replaces
+human approval, malware/security, rights, fidelity, confirmation or promotion
+receipts. `result.converter` contains the exact existing diagnostics/losses
+shape; the detailed `result.diagnostics` additionally binds resources and
+loss/fallback metadata. Preserve all independent evidence when composing it.
+
+Inputs must be inert JSON records; getters, exotic prototypes, sparse arrays,
+cycles, symbols and extra contract keys reject. Metadata is snapshotted before
+awaiting. Fixed ceilings are 100 issues/resources, depth 12, 16,384 values,
+2,048 characters per string and 262,144 total string characters. Non-completed
+outcomes reserve one issue slot for a terminal diagnostic, so accept at most
+99 issues. Arrays never exceed legacy 100-entry limits. Default deadline is
+10 seconds, configurable from 1–60,000 ms; cancellation/deadlines bound the
+lazy import wait and are checked around bounded synchronous evaluation. They
+cannot preempt JavaScript evaluation or cancel the platform module loader.
+No network, filesystem, logs, retries or persistent state are introduced.
+
+Use the backend-evaluated `gpu.model.conversion.enabled` adoption decision;
+disabled/rollback paths retain existing factories and diagnostics. No live flag
+lookup/mutation or UI capability is added. The already-published exact
+model-core0.7.0 dependency supplies evaluation without adding a parser or
+renderer. No dependency version changes are needed. See [ADR 0010](./docs/adrs/adr-0010-public-conversion-diagnostics.md)
+and [TDR 0005](./docs/tdrs/tdr-0005-public-conversion-diagnostics.md).
+
 ## Private Artifact Prevention
 
 Signed contributor agreements and contributor acceptance records are retained