@plasius/asset-contracts 0.5.0 → 0.6.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/index.md

@@ -9,3 +9,4 @@
 - [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)

package/docs/tdrs/index.md

@@ -4,3 +4,4 @@
 - [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)

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/package.json

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

package/src/index.ts

@@ -39,6 +39,7 @@ export * from "./pvox-hash-preimage.js";
 export * from "./pvox-model-resolution.js";
 export * from "./pvox-model-resolution-schema.js";
 export * from "./model-resource-manifest.js";
+export * from "./model-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);
+  }
+}