@plasius/asset-contracts 0.5.0 → 0.7.0

package/docs/adrs/adr-0010-public-conversion-diagnostics.md

@@ -0,0 +1,61 @@
+# ADR 0010: Public Conversion Diagnostics
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task49; site Feature1153 / Epic1147
+
+## Context and decision
+
+Existing ModelConverterDiagnostic/ModelConversionLoss and signed processing,
+fidelity, rights, human review and promotion contracts already cover their
+boundaries. Model-core0.7.0 owns canonical strict/tolerant/forensic policy,
+applied repairs, unsupported data and loss consent. Its private diagnostics may
+contain original values, rawSource, private paths and free-form adapter text.
+They cannot be forwarded as public contract evidence.
+
+Add qualifyModelConversionDiagnostics as an opt-in async boundary. Lazy import
+the existing exact published core dependency and reuse its evaluator; do not
+implement another acceptance policy or format parser. Inert bounded snapshots
+precede the first await. Project fixed category codes/messages, exact public
+resource bindings and existing ModelProvenance. Root diagnostics use source
+identity; unmatched non-root paths and contradictory URI identities reject.
+Only recognized completed repairs expose core-owned rule IDs. Discard adapter
+codes/text/private paths, original values and forensic snapshots. Unknown
+adapter codes become fixed category codes; unknown repair rules still block.
+
+Explicit failure takes precedence, then unsupported, then canonical rejection,
+then warning/clean success. Denied loss remains blocking in the legacy converter
+loss array. Detailed output and existing-shape converter arrays are frozen.
+Technical acceptance is not approval. No existing gate or factory is weakened.
+
+## Alternatives, costs and limits
+
+Regex redaction cannot reliably scrub arbitrary provider text. Tightening
+legacy factories would break staged consumers. Copying the canonical evaluator
+would create policy drift. Requiring eager core loading would add avoidable
+first-load work. Lazy import is asynchronous and may load a bundler chunk; module
+loading cannot be cancelled, but the wait is bounded. Bounded synchronous work
+checks deadlines before/after and cannot be preempted. Resource/provenance
+binding is a trusted-caller assertion; byte evidence and promotion remain
+separate. No dependency versions change. Tasks12/23/50/51 retain animation,
+shader ABI, role and promotion-closure scope respectively.
+
+## Rollout, NFR and release
+
+Backend evaluator gpu.model.conversion.enabled controls consumer adoption;
+disabled/rollback callers retain legacy contracts. No service lookup or flag
+mutation in this library, no UI entitlement capability. Test both branches and
+rollback, malformed metadata, stable codes/serialization, privacy canaries,
+resource identity, mutation, limits, deadline/cancellation and real processing
+manifest composition. Existing independent gate tests remain active.
+
+Security/privacy use allowlisted output and value-free errors. Fixed work and
+input budgets, no retries/I/O/global state address reliability/performance and
+scalability; immutable typed JSON and reused factories address maintenance and
+testability. Fixed codes support safe observability without logging. UI/SEO and
+durable storage controls are N/A. Require Node24 frozen install, full tests and
+changed-source LCOV>=80%, types/lint/build, full/runtime audits, tree/privacy/pack
+and packed/public ESM/CJS/types/browser consumers. Update README/Unreleased/TDR.
+Release additive minor through PR, exact-main push CI, existing hosted
+cd.yml/main/production OIDC, registry bytes/provenance and consumer checks.
+No site deployment is authorized or required by this package-only Task.

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

@@ -9,3 +9,5 @@
 - [ADR 0007: Hosted OIDC Package Publication](./adr-0007-hosted-oidc-package-publication.md)
 - [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

@@ -4,3 +4,5 @@
 - [TDR 0002: Exact-Version Validation Routing](./tdr-0002-exact-version-validation-routing.md)
 - [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-0005-public-conversion-diagnostics.md

@@ -0,0 +1,51 @@
+# TDR 0005: Public Conversion Diagnostics
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task49 / site Feature1153
+- Decision: ADR0010
+
+## Input and evaluation
+
+Accept outcome completed/unsupported/failed, existing public source provenance,
+canonical GpuModelDiagnosticInput and exact private path/public resource bindings.
+Snapshot inert JSON (no getters, symbols, sparse arrays, exotic prototypes or
+cycles) with depth12/16,384values/2,048-characterstrings/262,144aggregatecharacters;
+records/arrays have hard1024member limits. Limit issues/resources to100. Reserve
+one issue slot for non-completed outcomes. Reject duplicate paths and conflicting
+resource declarations for a URI. Every non-root diagnostic needs a binding;
+root uses source. Reuse existing provenance/resource factories and fixed errors.
+
+After snapshot, lazy-import published exact model-core0.7.0 and evaluate canonical
+policy. Do not trust a caller-supplied accepted flag or re-evaluate repairs here.
+Project core categories into fixed public codes/text; only accepted repairs expose
+core rule IDs. Drop arbitrary source code/message/path, originalValue/rawSource.
+Explicit failed outcome wins, then unsupported kind/outcome, rejected policy,
+warning/clean success. Canonical consent controls loss severity; denied losses
+remain blocking for existing fidelity derivation. Return frozen version1 JSON
+with technicalAccepted, source, standard/mode, detailed diagnostics and exact
+legacy converter diagnostic/loss arrays. No approval/receipt is synthesized.
+
+Native AbortSignal and deadline1–60,000ms(default10,000) cover the operation.
+Race lazy import against bounded timer/abort; clean timer/listener in finally.
+Check deadlines around bounded synchronous snapshot/evaluation; neither loader
+nor synchronous JS can be cancelled mid-execution. No network/filesystem/logging,
+retry or callback dependency is added. Input references are caller assertions,
+not byte verification; Task48/51 retain manifest/promotion responsibilities.
+
+## Requirements-based validation and delivery
+
+Tests first cover status precedence, strict/tolerant/applied and unknown repairs,
+allowed/denied dropped+approximated loss, fixed messages/codes, forensic redaction,
+source/resource binding, JSON serialization and mutation isolation. Test invalid
+codes/kinds/shapes, accessors/prototypes/symbols/sparse/cyclic inputs, limits and
+options, cancellation/deadline and legacy array ceilings. Compose actual
+ModelProcessingManifest evidence and verify independent fidelity/hard/rights
+gates still reject missing or contradictory evidence. Preserve existing tests.
+
+Backend gpu.model.conversion.enabled adoption enabled/disabled/rollback branches
+are tested without live changes; no capability. No dependency versions change.
+Run Node24 frozen full gates, >=80%changed-source LCOV, pack/consumer/audit,
+then PR CI, merge, exact-main CI and approved hosted cd.yml/main/production OIDC.
+Verify registry immutable bytes/provenance/signatures and actual public consumers
+before Done. README/Unreleased and ADR/TDR indices ship with additive minor.

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.5.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,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-conversion-diagnostics.js";
 export {
   GPU_SHADER_STORE_FEATURE_FLAG,
   GPU_SHADER_STYLE_SELECTION_CAPABILITY,

package/src/model-conversion-diagnostics.ts

@@ -0,0 +1,185 @@
+import type { GpuModelDiagnosticInput, GpuModelDiagnosticMode, GpuModelDiagnosticStandard } from "@plasius/gpu-model-core";
+import {
+  createModelProvenance, createModelResourceRef,
+  type ModelProvenance, type ModelResourceRef, type ModelConverterDiagnostic, type ModelConversionLoss,
+} from "./model-resolution.js";
+
+/** Hard ceilings for public conversion evidence, including private input metadata. */
+export const MODEL_CONVERSION_DIAGNOSTIC_LIMITS = Object.freeze({ issues: 100, resources: 100, values: 16_384, depth: 12, string: 2048, characters: 262_144, timeoutMs: 60_000 });
+
+/** Exact private canonical path to an opaque, credential-free public resource. */
+export interface ModelConversionResourceBinding {
+  readonly path: string;
+  readonly resource: ModelResourceRef;
+}
+/** Canonical evaluator input; arbitrary adapter text is never projected. */
+export interface ModelConversionDiagnosticsInput {
+  readonly outcome: "completed" | "unsupported" | "failed";
+  readonly source: ModelProvenance;
+  readonly report: GpuModelDiagnosticInput;
+  readonly resources: readonly ModelConversionResourceBinding[];
+}
+/** Cancellation and deadline cover snapshotting, lazy import and evaluation. */
+export interface ModelConversionDiagnosticsOptions {
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+/** Stable public codes; adapter-supplied codes are never treated as this vocabulary. */
+export type ModelConversionDiagnosticCode = "conversion.warning" | "conversion.repair" | "conversion.loss.dropped" | "conversion.loss.approximated" | "conversion.unsupported" | "conversion.blocked" | "conversion.failed";
+/** Technical evidence only; this is never human, rights, security or promotion approval. */
+export interface QualifiedModelConversionDiagnostic extends ModelConverterDiagnostic {
+  readonly code: ModelConversionDiagnosticCode;
+  readonly resource?: ModelResourceRef;
+  readonly effect?: "dropped" | "approximated";
+  readonly fallback?: string;
+}
+/** Deterministic JSON projection plus legacy-compatible converter evidence fields. */
+export interface QualifiedModelConversionDiagnostics {
+  readonly contractVersion: 1;
+  readonly status: "succeeded" | "warning" | "unsupported" | "failed";
+  readonly technicalAccepted: boolean;
+  readonly standard: GpuModelDiagnosticStandard;
+  readonly mode: GpuModelDiagnosticMode;
+  readonly source: ModelProvenance;
+  readonly diagnostics: readonly QualifiedModelConversionDiagnostic[];
+  readonly converter: {
+    readonly diagnostics: readonly ModelConverterDiagnostic[];
+    readonly losses: readonly ModelConversionLoss[];
+  };
+}
+/** Fixed, value-free error; never includes adapter/provider exception text. */
+export class ModelConversionDiagnosticsError extends TypeError {
+  constructor(public readonly code: "invalid-input" | "limit-exceeded" | "unbound-resource" | "aborted" | "deadline-exceeded") {
+    super(`Invalid model conversion diagnostics: ${code}`);
+    this.name = "ModelConversionDiagnosticsError";
+  }
+}
+function fail(code: ModelConversionDiagnosticsError["code"] = "invalid-input"): never { throw new ModelConversionDiagnosticsError(code); }
+
+function fields(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length > 1024) fail("limit-exceeded");
+  for (const key of keys) {
+    if (typeof key !== "string" || key.length > 128 || ["__proto__", "prototype", "constructor"].includes(key)) fail();
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (!("value" in descriptor) || !descriptor.enumerable) fail();
+    result[key] = descriptor.value;
+  }
+  return result;
+}
+function only(record: Record<string, unknown>, keys: readonly string[]): void {
+  if (Object.keys(record).some((key) => !keys.includes(key))) fail();
+}
+function snapshot(value: unknown, budget: { values: number; characters: number }, depth = 0): unknown {
+  if (--budget.values < 0 || depth > MODEL_CONVERSION_DIAGNOSTIC_LIMITS.depth) fail("limit-exceeded");
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    budget.characters -= value.length;
+    if (value.length > MODEL_CONVERSION_DIAGNOSTIC_LIMITS.string || budget.characters < 0) fail("limit-exceeded");
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype || value.length > 1024) fail("limit-exceeded");
+    if (Reflect.ownKeys(value).length !== value.length + 1) fail();
+    const result = [];
+    for (let i = 0; i < value.length; i++) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) fail();
+      result.push(snapshot(descriptor.value, budget, depth + 1));
+    }
+    return Object.freeze(result);
+  }
+  const record = fields(value);
+  for (const key of Object.keys(record)) {
+    budget.characters -= key.length;
+    if (budget.characters < 0) fail("limit-exceeded");
+    record[key] = snapshot(record[key], budget, depth + 1);
+  }
+  return Object.freeze(record);
+}
+function legacy(value: QualifiedModelConversionDiagnostic): ModelConverterDiagnostic {
+  return Object.freeze({ severity: value.severity, code: value.code, message: value.message });
+}
+
+/**
+ * Evaluate canonical diagnostics and project fixed public text. Unknown adapter codes
+ * are intentionally discarded; unknown repair rules remain blocking in model-core.
+ * Exact path bindings are assertions by the trusted caller, not byte attestations.
+ */
+export async function qualifyModelConversionDiagnostics(input: unknown, options: ModelConversionDiagnosticsOptions = {}): Promise<QualifiedModelConversionDiagnostics> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let signal: AbortSignal | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    const start = performance.now();
+    const controls = fields(options);
+    only(controls, ["signal", "timeoutMs"]);
+    const timeoutMs = controls.timeoutMs === undefined ? 10_000 : controls.timeoutMs;
+    if (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MODEL_CONVERSION_DIAGNOSTIC_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() - start >= timeoutMs) fail("deadline-exceeded");
+    };
+    check();
+    const args = fields(snapshot(input, { values: MODEL_CONVERSION_DIAGNOSTIC_LIMITS.values, characters: MODEL_CONVERSION_DIAGNOSTIC_LIMITS.characters }));
+    only(args, ["outcome", "source", "report", "resources"]);
+    if (!["completed", "unsupported", "failed"].includes(args.outcome as string)) fail();
+    const source = createModelProvenance(args.source);
+    const reportInput = fields(args.report);
+    // Reserve room for the outcome diagnostic in legacy arrays limited to 100.
+    const maximumIssues = MODEL_CONVERSION_DIAGNOSTIC_LIMITS.issues - (args.outcome === "completed" ? 0 : 1);
+    if (!Array.isArray(reportInput.issues) || reportInput.issues.length > maximumIssues) fail("limit-exceeded");
+    if (!Array.isArray(args.resources) || args.resources.length > MODEL_CONVERSION_DIAGNOSTIC_LIMITS.resources) fail("limit-exceeded");
+    const resources = new Map<string, ModelResourceRef>();
+    const identities = new Map<string, string>();
+    for (const value of args.resources) {
+      const binding = fields(value);
+      only(binding, ["path", "resource"]);
+      if (typeof binding.path !== "string" || !binding.path.startsWith("/") || binding.path === "/" || resources.has(binding.path)) fail();
+      const resource = createModelResourceRef(binding.resource);
+      const identity = JSON.stringify(resource);
+      if (identities.has(resource.uri) && identities.get(resource.uri) !== identity) fail();
+      identities.set(resource.uri, identity);
+      resources.set(binding.path, resource);
+    }
+    check();
+    const interrupted = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(new ModelConversionDiagnosticsError("deadline-exceeded")), Math.max(1, timeoutMs - (performance.now() - start)));
+      onAbort = () => reject(new ModelConversionDiagnosticsError("aborted"));
+      if (signal) AbortSignal.prototype.addEventListener.call(signal, "abort", onAbort, { once: true });
+    });
+    const core = await Promise.race([import("@plasius/gpu-model-core"), interrupted]);
+    check();
+    const report = core.evaluateGpuModelDiagnostics(reportInput);
+    const diagnostics: QualifiedModelConversionDiagnostic[] = report.diagnostics.map((diagnostic) => {
+      const resource = resources.get(diagnostic.path);
+      if (diagnostic.path !== "/" && !resource) fail("unbound-resource");
+      const base = resource ? { resource } : {};
+      switch (diagnostic.kind) {
+        case "warning": return Object.freeze({ ...base, severity: "warning", code: "conversion.warning", message: "Conversion completed with an advisory." });
+        case "repair": return Object.freeze({ ...base, severity: "warning", code: "conversion.repair", message: "Conversion applied a canonical repair fallback.", fallback: diagnostic.ruleId });
+        case "loss": return Object.freeze({ ...base, severity: reportInput.allowLoss === true ? "warning" : "blocking", code: `conversion.loss.${diagnostic.effect}`, message: diagnostic.effect === "dropped" ? "Conversion dropped source data." : "Conversion approximated source data.", effect: diagnostic.effect });
+        case "unsupported": return Object.freeze({ ...base, severity: "blocking", code: "conversion.unsupported", message: "Conversion encountered unsupported data." });
+        case "blocking-error": return Object.freeze({ ...base, severity: "blocking", code: "conversion.blocked", message: "Conversion did not satisfy canonical validation policy." });
+      }
+    });
+    if (args.outcome !== "completed") diagnostics.push(Object.freeze({ severity: "blocking", code: args.outcome === "failed" ? "conversion.failed" : "conversion.unsupported", message: args.outcome === "failed" ? "Conversion failed." : "Conversion encountered unsupported data." }));
+    const technicalAccepted = args.outcome === "completed" && report.accepted;
+    const status = args.outcome === "failed" ? "failed" : args.outcome === "unsupported" || report.diagnostics.some((item) => item.kind === "unsupported") ? "unsupported" : !technicalAccepted ? "failed" : diagnostics.length ? "warning" : "succeeded";
+    const losses = diagnostics.filter((item) => item.effect !== undefined).map(legacy);
+    check();
+    return Object.freeze({ contractVersion: 1, status, technicalAccepted, standard: report.standard, mode: report.mode, source,
+      diagnostics: Object.freeze(diagnostics), converter: Object.freeze({ diagnostics: Object.freeze(diagnostics.filter((item) => item.effect === undefined).map(legacy)), losses: Object.freeze(losses) }) });
+  } catch (error) {
+    if (error instanceof ModelConversionDiagnosticsError) throw error;
+    return fail();
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && onAbort) AbortSignal.prototype.removeEventListener.call(signal, "abort", onAbort);
+  }
+}