@plasius/gpu-model-core 0.1.0 → 0.3.0

package/README.md

@@ -4,6 +4,137 @@ Canonical model document, resource graph, diagnostics, and adapter contracts.
 
 This repository is the dedicated package boundary defined by ADR 0094.
 
+## Diagnostics, repairs and conversion loss
+
+`evaluateGpuModelDiagnostics` validates a format adapter's completed report.
+It defaults to strict mode, rejecting every standard violation. Tolerant and
+forensic modes accept only supported rules with `repairApplied: true`, which
+attests that the adapter performed and verified the exact `action` exposed by
+`GPU_MODEL_REPAIR_RULES`. It does **not** parse a model or perform repairs.
+Continue to validate the repaired document with `validateGpuModelDocument`.
+
+```ts
+import { evaluateGpuModelDiagnostics } from "@plasius/gpu-model-core";
+
+const report = evaluateGpuModelDiagnostics({
+  standard: "gltf-glb",
+  mode: "tolerant",
+  issues: [{
+    kind: "violation",
+    ruleId: "missing-normals",
+    code: "NORMAL_REQUIRED",
+    path: "/meshes/0/primitives/0/attributes/NORMAL",
+    message: "Required normals were missing",
+    originalValue: null,
+    repairApplied: true, // Adapter already generated and validated normals.
+  }],
+});
+// report.accepted === true; report.repairs contains the complete repair record.
+```
+
+Blocking errors, repairs, unsupported data, warnings and loss are separate
+`kind` variants. Unknown rules and unsupported data block every mode. Repairs
+preserve `originalValue`, `action`, `severity`, `affectedPath`, `confidence`, and
+`ruleId`. The supported profiles are `gltf-glb`, `obj-mtl`, `fbx`, and `cad-bim`;
+OBJ cannot use the skin-weight repair rule. The exported policy text records
+the upstream rule; executable contract actions deliberately narrow ambiguous
+fallbacks: invalid primitives are dropped (never clamped), unavailable textures
+remain unresolved, and malformed material references use the canonical default.
+These three fallbacks require a `kind: "loss"` issue at the same path. Each loss
+states `effect: "dropped" | "approximated"`; any loss blocks acceptance unless
+`allowLoss: true` is explicitly supplied, including in strict mode.
+
+Forensic mode requires `rawSource`, a relevant, scrubbed JSON snapshot. Other
+modes reject that field to prevent unintended retention. Source evidence is
+separate from ordinary diagnostics and remains available even when conversion
+is rejected. Represent source NaN/Infinity as descriptive strings, not numbers.
+Never include credentials, signed URLs or unrelated personal data, and never
+log raw evidence or repair snapshots. The package performs no logging, I/O,
+persistence or credential detection. Use serialized JSON as the boundary for
+untrusted executable producers; JavaScript Proxies are not inert data.
+
+`GPU_MODEL_DIAGNOSTIC_LIMITS` bounds the entire input to 1 MiB of JSON UTF-8,
+4096 issues, 16384 JSON values, depth 12, 1024 members per evidence container
+and 65536 UTF-16 units per string. All ceilings apply together. Optional
+`maxEvidenceBytes` lowers the aggregate byte ceiling, including report fields
+and the limit itself. Overflow, unknown keys, getters, cycles, sparse arrays,
+exotic objects and malformed reports throw a static `GpuModelDiagnosticsError`
+without echoing caller data. Successful output is deeply frozen and owned by
+the package; caller objects remain mutable and unchanged.
+
+The parent `gpu.model.conversion.enabled` flag governs adapter adoption. Keep
+it disabled until adapter-specific conformance tests pass; rollback disables
+the flag and restores strict mode. This API changes no stored flag and adds no
+UI capability. Synthetic contract fixtures cover glTF, OBJ, FBX and CAD reports;
+actual parsing and geometry verification belong to their format adapters.
+See [ADR-0008](docs/adrs/adr-0008-bounded-adapter-diagnostics-and-repair-ledgers.md).
+
+## Canonical conversion resource graph
+
+`createGpuModelResourceGraph` projects a privately verified `GpuModelDocument`
+into a frozen dependency graph for resources, accessors, textures, materials,
+skeletons (including joints), skins, animations, provenance and conversion
+packages. It reuses the canonical values and immutable `Blob` payloads. Material
+bindings retain samplers and intended usage; texture values retain their hashes,
+MIME types, paths, colour spaces and export embedding policy.
+
+```ts
+import { createGpuModelResourceGraph, gpuModelResourceKey,
+  type GpuModelDocument } from "@plasius/gpu-model-core";
+
+declare const document: GpuModelDocument; // From the verification factory.
+const graph = createGpuModelResourceGraph(document, {
+  resources: document.resources.map(resource => ({
+    resourceId: resource.id,
+    location: { kind: "embedded" },
+    exportEmbeddingPolicy: "inherit-source",
+  })),
+  packages: [{ id: "conversion", members: document.resources.map(resource => ({
+    kind: "resource", id: resource.id,
+  })) }],
+});
+const conversion = graph.nodes.find(node =>
+  node.key === gpuModelResourceKey("package", "conversion"));
+```
+
+Supply exactly one binding per document resource. For external origins use
+`location: { kind: "external", relativePath: "textures/albedo.png" }`; the bytes
+must already have been resolved and verified. Paths use portable ASCII letters,
+digits, dots, underscores, hyphens and slash separators, with no absolute paths,
+traversal, URL syntax, device names or trailing dots. Components are at most 255
+characters and paths at most 1024. Case-insensitive duplicate paths and file versus
+directory collisions fail. Descriptors do not authorize network/file access.
+
+Resource export policies are `inherit-source`, `prefer-embedded`,
+`prefer-external` and `forbid-embedding`. The last requires an external origin.
+Exporters must satisfy resource and texture restrictions together, resolve
+preferences for the target, enforce destination-root confinement and validate
+their actual output. The graph neither writes packages nor proves export success.
+Asset catalogue admission and promotion remain owned by `@plasius/asset-contracts`.
+
+`gpuModelResourceKey(kind, id)` encodes a JSON tuple, independent of declaration
+order and locale. Logical IDs are distinct from byte-content hashes. Nodes and
+dependency keys are sorted; joint/animation sample order stays intact. Package
+members are typed references, may include packages, and must form a DAG. Missing,
+repeated or cyclic references fail with fixed `GpuModelResourceGraphError.code`
+values. Canonical document validation still owns scene and semantic references.
+Animation target associations remain in canonical values, outside dependency
+edges. This is a resource dependency graph, not a replacement scene graph.
+
+`GPU_MODEL_RESOURCE_GRAPH_LIMITS` caps 65536 nodes, 262144 dependency declarations
+(including repeated semantic dependencies before deduplication), and 256 packages.
+These ceilings may reject a large otherwise-valid canonical document. Construction
+performs no I/O, retries, logging or hashing; input accessors and malformed
+containers fail closed. Do not treat executable JavaScript Proxies as inert input.
+`isGpuModelResourceGraph` recognizes only locally constructed graphs. Structured
+clones must be rebuilt from a reverified document. The graph retains authored
+metadata and provenance: it is not a redaction boundary or a public logging format.
+
+Adoption inherits the remotely evaluated `gpu.model.conversion.enabled` flag;
+rollback disables conversion adoption and pins the prior package release. No
+stored flag or UI capability changes here. See
+[ADR-0009](docs/adrs/adr-0009-canonical-conversion-resource-graph.md).
+
 ## Implementation tracker
 
 The canonical conversion architecture is defined by [ADR 0094 in `plasius-ltd-site`](https://github.com/Plasius-LTD/plasius-ltd-site/blob/main/docs/adrs/adr-0094-gpu-model-family-and-canonical-proxy-conversion.md). The package implementation work is split into Project-tracked Tasks: