@plasius/asset-contracts 0.4.5 → 0.5.0

package/docs/adrs/adr-0008-package-owned-issue-tracking.md

@@ -0,0 +1,62 @@
+# ADR 0008: Package-Owned Issue Tracking
+
+- Status: Accepted
+- Date: 2026-10-23
+- Tracking: site Task 1169; package Task 47; parent Feature 1153 / Epic 1147
+
+## Context
+
+GitHub Issues are enabled in `Plasius-LTD/asset-contracts`, but the README says
+otherwise and `package.json` directs npm bug reports to the site repository.
+That stale routing obscures package ownership. Feature 1153 also needs explicit
+package Tasks for model resource contracts before implementation begins.
+
+## Decision
+
+Use this repository's enabled Issues for package bugs, support, and implementation
+Tasks. Set `bugs.url` to `https://github.com/Plasius-LTD/asset-contracts/issues`
+and document the same route in the published README. Confidential vulnerability
+reports continue through `SECURITY.md`.
+
+The organisation `Plasius-LTD-site` Project governs work definition, acceptance,
+ownership, priority, and status. Epics, Features, and Stories remain in the site
+repository. Package implementation Tasks are native children of their owning
+Feature and Project members. Preserve historical issues and their links rather
+than migrating or duplicating them.
+
+Feature 1153 owns four follow-ups: package Tasks 48 (resource descriptors), 49
+(conversion diagnostics), 50 (texture/resource roles), and 51 (promotion manifest
+resource closure). The README links each exact Task. They begin as unassigned
+Backlog/P2/M Project work; their live Project fields remain authoritative.
+They must reuse and qualify existing public contracts and implement only
+evidenced gaps. Completed GPU/model-resolution contracts and separate animation
+and shader ABI Tasks retain their own scope.
+
+These Tasks inherit `gpu.model.conversion.enabled`, evaluated by the backend
+remote control plane for canonical adapter adoption. This documentation and
+metadata change adds no runtime evaluation, capability, or flag mutation. Future
+runtime Tasks must document enabled, disabled, and rollback behavior.
+
+## Alternatives
+
+Continuing the alternate site tracker would preserve stale routing and conflict
+with the repository-owned implementation Task policy. Disabling package Issues
+would unnecessarily change an already working tracker. Migrating historical
+issues would break continuity without helping the requested follow-up work.
+
+## Test and release implications
+
+Regression tests compare npm bug metadata with the owning repository, verify
+active README support/security links, and require all four follow-up links.
+Verify Issues remain enabled and read back each Project field and native parent.
+Run the existing frozen-install, tests, coverage, lint, types, build, package,
+privacy, and dependency gates; no source/API or dependency-version change is
+needed. npm's lockfile does not store `bugs.url`, so it need not change for this
+metadata correction.
+
+The support URL is public package metadata. Use a patch release through the
+existing PR, exact-main push CI, and hosted `cd.yml` / `production` npm OIDC path
+from ADR 0007. Verify registry support metadata, published documentation, package
+integrity/provenance, and ESM/CJS/declarations. Do not assume a documentation-only
+release exemption. A routing rollback is an ordinary reviewed metadata release;
+it must not remove existing issues or reopen the disabled-tracker claim.

package/docs/adrs/adr-0009-model-resource-manifest-qualification.md

@@ -0,0 +1,74 @@
+# ADR 0009: Additive Model Resource Manifest Qualification
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: package Task 48; site Feature 1153 / Epic 1147
+
+## Context
+
+The existing file and manifest factories validate descriptor syntax. They do
+not bind a model-core `ResourcePackageManifest` to the exact exported file set
+or prove that the declared entrypoint exists. Tightening the existing factories
+would change their public compatibility contract, including callers which
+construct descriptors before storage bytes exist.
+
+## Decision
+
+Add `qualifyModelResourceManifest` as a separate, opt-in asynchronous boundary.
+Reuse `AssetFileDescriptor`, `AssetManifest`, their existing factories, the
+published model-core package inventory type, and gpu-shader's SHA-256 helper.
+The qualifier requires one inventory entry and one byte payload for each
+descriptor, including the entrypoint. It checks portable relative paths,
+case-insensitive and file/directory collisions, canonical declared MIME types,
+safe integer byte lengths, actual lengths and SHA-256 digests. Output file
+order uses locale-independent code-unit comparison.
+
+Snapshot all metadata and byte inputs before the first hash. Apply fixed count,
+depth and byte ceilings, reject shared byte storage, and check cancellation and
+deadline around each bounded hash. Web Crypto cannot cancel an in-flight
+digest; a deadline is checked again before any successful return. No partial
+manifest is returned on failure. Errors contain fixed codes, not caller data.
+
+Keep roles, sourceAdapter and source/derived paths unchanged. Embedded resources
+remain inside their exported entrypoint; they are not invented as separate
+archive files. A verified model-core fixture independently checks embedded and
+external resource identity and source provenance. This boundary neither parses
+formats nor proves that a file internally references every required resource.
+Task 51 owns promotion/resource closure, Task 50 owns detailed role mapping,
+Task 12 owns animation/source relationship schemas and Task 23 owns shader ABI
+qualification. Typed model envelopes still use the existing specialized factory.
+
+Use exact published `@plasius/gpu-model-core@0.7.0` as a direct dependency because
+the public input declarations reference its inventory type. The import is
+type-only: no core parser, renderer or model runtime is loaded by this helper.
+The full qualification audit additionally found the pre-existing development
+AJV dependency `fast-uri@3.1.8` affected by newly published URI-normalization
+advisories. Raise its existing override floor from `^3.1.6` to `^3.1.9` and
+lock fixed `3.1.9`, retaining major 3. This targeted audit-blocker remediation
+does not add runtime URI processing. No other dependency versions change.
+
+## Alternatives and consequences
+
+Changing legacy factories would break staged descriptor construction. Parsing
+glTF/FBX here would duplicate adapter responsibilities. Treating descriptor
+hashes as byte evidence would allow mismatches to survive. The new boundary
+provides byte/inventory qualification only; storage, malware inspection,
+format validity and promotion remain downstream responsibilities. Qualification
+is evidence at call time, not an unforgeable promotion attestation.
+
+## Rollout, tests and release
+
+The backend remote evaluator owns `gpu.model.conversion.enabled`. Callers opt
+into this helper when enabled; disabled or rollback paths retain their existing
+factories. This library performs no live flag lookup or state mutation. There
+is no UI or entitlement capability. Tests cover enabled/disabled/rollback
+composition, legacy compatibility, canonical resource identity, malformed
+inputs, fixed budgets, cancellation, deadlines and mutation isolation.
+
+Update README, Unreleased changelog and TDR 0004. Require Node 24 frozen install,
+tests/privacy, coverage and changed-source LCOV, lint/types/build, audits, pack
+gates and packed/public ESM/CJS/types qualification. Release an additive minor
+version through the existing PR, exact-main push CI and hosted
+`cd.yml`/`production` OIDC path from ADR 0007. Verify public registry integrity
+and provenance before downstream adoption. This Task authorizes no site
+deployment or change to any existing release gate.

package/docs/adrs/index.md

@@ -7,3 +7,5 @@
 - [ADR 0005: Path-Only Private-Artifact Prevention Gates](./adr-0005-path-only-private-artifact-prevention-gates.md)
 - [ADR 0006: Additive PVOX Model-Resolution Contracts](./adr-0006-pvox-model-resolution-contracts.md)
 - [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)

package/docs/tdrs/index.md

@@ -3,3 +3,4 @@
 - [TDR 0001: WGSL Shader Asset Envelope Validation](./tdr-0001-wgsl-shader-asset-envelope-validation.md)
 - [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)

package/docs/tdrs/tdr-0004-model-resource-manifest-qualification.md

@@ -0,0 +1,70 @@
+# TDR 0004: Model Resource Manifest Qualification
+
+- Status: Accepted
+- Date: 2026-10-24
+- Tracking: asset-contracts Task 48; site Feature 1153
+- Decision: ADR 0009
+
+## Inputs and sequence
+
+1. Accept an existing base or typed model `AssetManifest`, the published
+   model-core `ResourcePackageManifest`, and exact exported `Uint8Array` files
+   with independent content-type declarations. Optional inputs are native
+   AbortSignal and a 1–60,000 ms deadline (default 10,000 ms).
+2. Reject exotic metadata records, accessors, symbols, prototype keys, sparse
+   arrays and unsupported root fields without executing metadata getters.
+   Snapshot metadata using fixed count/depth/string/key limits.
+3. Reuse the existing base or specialized model factory. Keep every existing
+   role, source adapter and specialized field. Do not tighten legacy factories.
+4. Require portable relative paths, unique case-insensitive names and no
+   file/directory prefix collision. The entrypoint must be a descriptor path.
+   Reject unsafe integer counts and fixed file/aggregate budget overruns.
+5. Require one canonical package entry per descriptor, unique bounded logical
+   ids, supported core inventory roles, and MIME declaration agreement when
+   the optional inventory declaration exists. Do not map core roles to storage
+   roles or infer content type from a filename.
+6. Require one actual payload per descriptor with exact byte length and MIME
+   declaration. Read byte lengths and buffers through typed-array intrinsics,
+   rejecting shared storage. Only after all budgets and actual lengths pass,
+   snapshot bytes before any asynchronous operation.
+7. Sequentially compute SHA-256 through gpu-shader's existing Web Crypto helper.
+   Check signal/deadline before and after every digest; compare exact lowercase
+   digests. Return no result on any failure. Sequential hashing avoids
+   unbounded concurrency; no filesystem, network, log, retry or caller callback
+   is introduced. Deadline expiration cannot interrupt the platform digest,
+   but it prevents a successful return after the operation finishes.
+8. Return frozen metadata and frozen descriptors sorted by UTF-16 code units.
+   The result is not a storage receipt or promotion attestation. A caller must
+   retain the qualified bytes unchanged at its own durable boundary.
+
+## Canonical fixture and source fidelity
+
+Tests import the published model-core package, independently verify a triangle
+document, and build its resource graph. The derived position buffer is embedded
+in a glTF data URI; the original PNG remains an external exported file. Compare
+each resource's byte content/hash with its payload and exported location, and
+bind document source provenance to the entrypoint digest. Embedded data is not
+listed as a fictitious archive file. The fixture does not grant production
+format-parser, texture-role or promotion-closure authority.
+
+## Rollout, compatibility and NFR evidence
+
+Callers compose this helper behind backend-evaluated
+`gpu.model.conversion.enabled`; disabled and rollback paths continue the legacy
+factory. Test that enabled qualification rejects mismatched bytes while both
+fallback paths preserve legacy behavior. No live control mutation is needed.
+Security/privacy tests cover malformed shapes, value-free failures, traversal,
+collisions, byte/hash/MIME drift, shared buffers and input mutation. Fixed
+budgets and sequential work address reliability/performance; frozen snapshots
+and exact inventory types address maintainability/testability. UI accessibility,
+SEO and storage/encryption controls are N/A to this in-memory library boundary.
+
+The public type requires exact `@plasius/gpu-model-core@0.7.0`; the import is
+type-only. A full-audit failure also requires the targeted development-only
+fast-uri override floor `^3.1.6` to `^3.1.9` and lock `3.1.8` to fixed `3.1.9`;
+retain the existing AJV/major-3 dependency contract and rerun all gates. No
+other dependency versions change. Require frozen Node 24 install,
+full tests/privacy/coverage and changed-source LCOV, lint/types/build, dependency
+tree/audits, packed ESM/CJS/types/browser-safe import, and public-registry
+artifact/provenance checks. Ship an additive minor release via existing
+`cd.yml`/`main`/`production` OIDC governance. Site adoption is separate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/asset-contracts",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Canonical contracts for Plasius asset jobs, model resolution, immutable WGSL shader assets, reviews, and promotion records.",
   "type": "module",
   "sideEffects": false,
@@ -66,7 +66,7 @@
     "url": "git+https://github.com/Plasius-LTD/asset-contracts.git"
   },
   "bugs": {
-    "url": "https://github.com/Plasius-LTD/plasius-ltd-site/issues"
+    "url": "https://github.com/Plasius-LTD/asset-contracts/issues"
   },
   "homepage": "https://github.com/Plasius-LTD/asset-contracts#readme",
   "devDependencies": {
@@ -103,12 +103,13 @@
   "overrides": {
     "brace-expansion": "5.0.12",
     "esbuild": "^0.28.1",
-    "fast-uri": "^3.1.6",
+    "fast-uri": "^3.1.9",
     "minimatch": "^10.2.1",
     "nanoid": "3.3.18",
     "postcss": "8.5.26"
   },
   "dependencies": {
+    "@plasius/gpu-model-core": "0.7.0",
     "@plasius/gpu-shader": "^0.1.10"
   }
 }

package/src/index.ts

@@ -38,6 +38,7 @@ export * from "./model-resolution.js";
 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 {
   GPU_SHADER_STORE_FEATURE_FLAG,
   GPU_SHADER_STYLE_SELECTION_CAPABILITY,

package/src/model-resource-manifest.ts

@@ -0,0 +1,198 @@
+import type { ResourcePackageManifest } from "@plasius/gpu-model-core";
+import { computeSha256 } from "@plasius/gpu-shader";
+import {
+  createAssetManifest, createModelAssetManifest,
+  type AssetManifest, type ModelAssetManifestInput,
+} from "./index.js";
+
+/** Fixed ceilings for the opt-in, in-memory model package qualification boundary. */
+export const MODEL_RESOURCE_MANIFEST_LIMITS = Object.freeze({
+  files: 16_384, fileBytes: 64 * 1024 * 1024, totalBytes: 128 * 1024 * 1024,
+  metadataValues: 262_144, metadataDepth: 16, timeoutMs: 60_000,
+});
+
+/** Exported file bytes and their independently supplied canonical MIME declaration. */
+export interface ModelResourceFileInput {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+}
+
+/** Complete exported inventory; embedded resources remain inside their owning file. */
+export interface ModelResourceManifestQualificationInput {
+  readonly manifest: AssetManifest;
+  readonly packageManifest: ResourcePackageManifest;
+  readonly files: readonly ModelResourceFileInput[];
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+
+/** Value-free failure, suitable for callers' bounded diagnostic projections. */
+export class ModelResourceManifestError extends TypeError {
+  constructor(public readonly code: "invalid-input" | "limit-exceeded" | "path-conflict" | "inventory-mismatch" | "content-mismatch" | "aborted" | "deadline-exceeded") {
+    super(`Invalid model resource manifest: ${code}`);
+    this.name = "ModelResourceManifestError";
+  }
+}
+function fail(code: ModelResourceManifestError["code"] = "invalid-input"): never {
+  throw new ModelResourceManifestError(code);
+}
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) fail();
+  const output: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  const keys = Reflect.ownKeys(value);
+  if (keys.length > MODEL_RESOURCE_MANIFEST_LIMITS.files) fail("limit-exceeded");
+  for (const key of keys) {
+    if (typeof key !== "string" || ["__proto__", "constructor", "prototype"].includes(key)) fail();
+    if (key.length > 128) fail("limit-exceeded");
+    const property = Object.getOwnPropertyDescriptor(value, key)!;
+    if (!("value" in property) || !property.enumerable) fail();
+    output[key] = property.value;
+  }
+  return output;
+}
+function list(value: unknown): unknown[] {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype) fail();
+  if (value.length > MODEL_RESOURCE_MANIFEST_LIMITS.files) fail("limit-exceeded");
+  if (Reflect.ownKeys(value).length !== value.length + 1) fail();
+  const output: unknown[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const property = Object.getOwnPropertyDescriptor(value, String(i));
+    if (!property || !("value" in property) || !property.enumerable) fail();
+    output.push(property.value);
+  }
+  return output;
+}
+function snapshot(value: unknown, budget: { remaining: number }, depth = 0): unknown {
+  if (--budget.remaining < 0 || depth > MODEL_RESOURCE_MANIFEST_LIMITS.metadataDepth) fail("limit-exceeded");
+  if (value === null || value === undefined || typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    if (value.length > 2048) fail("limit-exceeded");
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) fail();
+    return value;
+  }
+  if (Array.isArray(value)) return Object.freeze(list(value).map((item) => snapshot(item, budget, depth + 1)));
+  const fields = record(value);
+  for (const key of Object.keys(fields)) fields[key] = snapshot(fields[key], budget, depth + 1);
+  return Object.freeze(fields);
+}
+function path(value: unknown): string {
+  if (typeof value !== "string" || value.length > 1024 || !value.length) fail();
+  for (const part of value.split("/")) {
+    if (part.length > 255 || !/^[A-Za-z0-9_][A-Za-z0-9_.-]*$/u.test(part)
+      || part.endsWith(".") || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/iu.test(part)) fail();
+  }
+  return value;
+}
+function contentType(value: unknown): string {
+  if (typeof value !== "string" || value.length > 128
+    || !/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:; charset=utf-8)?$/u.test(value)) fail();
+  return value;
+}
+function uniquePaths(paths: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const value of paths) {
+    const normalized = path(value).toLowerCase();
+    if (seen.has(normalized)) fail("path-conflict");
+    seen.add(normalized);
+  }
+  for (const value of seen) {
+    for (let offset = value.indexOf("/"); offset !== -1; offset = value.indexOf("/", offset + 1)) {
+      if (seen.has(value.slice(0, offset))) fail("path-conflict");
+    }
+  }
+}
+
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const byteLengthGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const bufferGetter = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+
+/**
+ * Binds an exported model inventory to exact file bytes without parsing formats,
+ * fetching resources or changing legacy factories. Callers own remote rollout,
+ * content inspection and durable storage. The result is evidence at call time,
+ * not a promotion attestation. All inputs are copied before the first digest.
+ */
+export async function qualifyModelResourceManifest(input: ModelResourceManifestQualificationInput): Promise<AssetManifest> {
+  try { return await qualify(input); }
+  catch (error) {
+    if (error instanceof ModelResourceManifestError) throw error;
+    return fail();
+  }
+}
+
+async function qualify(input: ModelResourceManifestQualificationInput): Promise<AssetManifest> {
+  const started = performance.now();
+  const root = record(input);
+  if (Object.keys(root).some((key) => !["manifest", "packageManifest", "files", "signal", "timeoutMs"].includes(key))) fail();
+  const timeout = root.timeoutMs ?? 10_000;
+  if (typeof timeout !== "number" || !Number.isSafeInteger(timeout) || timeout < 1 || timeout > MODEL_RESOURCE_MANIFEST_LIMITS.timeoutMs) fail();
+  const signal = root.signal;
+  if (signal !== undefined && !(signal instanceof AbortSignal)) fail();
+  const check = (): void => {
+    if (signal?.aborted) fail("aborted");
+    if (performance.now() - started >= timeout) fail("deadline-exceeded");
+  };
+  check();
+  const budget = { remaining: MODEL_RESOURCE_MANIFEST_LIMITS.metadataValues };
+  const rawManifest = snapshot(root.manifest, budget) as AssetManifest;
+  const inventory = record(snapshot(root.packageManifest, budget));
+  if (Object.keys(inventory).some((key) => !["format", "entries"].includes(key))
+    || !["zip", "tar", "directory-manifest", "inline"].includes(inventory.format as string)) fail();
+  let manifest: AssetManifest;
+  try {
+    manifest = rawManifest.assetKind === "model"
+      ? createModelAssetManifest(rawManifest as ModelAssetManifestInput)
+      : createAssetManifest(rawManifest);
+  } catch { return fail(); }
+  uniquePaths(manifest.files.map((file) => file.path));
+  if (!manifest.files.some((file) => file.path === path(manifest.entrypoint))) fail("inventory-mismatch");
+  const descriptors = new Map(manifest.files.map((file) => [file.path, file]));
+  let total = 0;
+  for (const file of manifest.files) {
+    if (!Number.isSafeInteger(file.byteLength)) fail();
+    if (file.byteLength > MODEL_RESOURCE_MANIFEST_LIMITS.fileBytes) fail("limit-exceeded");
+    total += file.byteLength;
+    if (total > MODEL_RESOURCE_MANIFEST_LIMITS.totalBytes) fail("limit-exceeded");
+    contentType(file.contentType);
+  }
+  const entries = list(inventory.entries).map(record);
+  uniquePaths(entries.map((entry) => path(entry.path)));
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    if (Object.keys(entry).some((key) => !["id", "path", "role", "contentType"].includes(key))
+      || typeof entry.id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(entry.id)
+      || ids.has(entry.id) || !["mesh", "material", "texture", "animation", "auxiliary"].includes(entry.role as string)) fail();
+    ids.add(entry.id);
+    const descriptor = descriptors.get(entry.path as string);
+    if (!descriptor) fail("inventory-mismatch");
+    if (entry.contentType !== undefined && contentType(entry.contentType) !== descriptor.contentType) fail("content-mismatch");
+  }
+  if (entries.length !== descriptors.size) fail("inventory-mismatch");
+  const payloads = list(root.files).map((value) => {
+    const file = record(value);
+    if (Object.keys(file).length !== 3 || Object.keys(file).some((key) => !["path", "bytes", "contentType"].includes(key))) fail();
+    const filePath = path(file.path);
+    if (!(file.bytes instanceof Uint8Array) || Object.getPrototypeOf(file.bytes) !== Uint8Array.prototype
+      || !(bufferGetter.call(file.bytes) instanceof ArrayBuffer)) fail();
+    const descriptor = descriptors.get(filePath);
+    if (!descriptor) fail("inventory-mismatch");
+    if (byteLengthGetter.call(file.bytes) !== descriptor.byteLength || contentType(file.contentType) !== descriptor.contentType) fail("content-mismatch");
+    return { path: filePath, bytes: file.bytes, descriptor };
+  });
+  uniquePaths(payloads.map((file) => file.path));
+  if (payloads.length !== descriptors.size) fail("inventory-mismatch");
+  // Descriptor budgets and actual lengths were checked before allocating copies.
+  const copies = payloads.map((file) => ({ ...file, bytes: new Uint8Array(file.bytes) }));
+  for (const file of copies) {
+    check();
+    let hash: string;
+    try { hash = await computeSha256(file.bytes); } catch { return fail("content-mismatch"); }
+    check();
+    if (hash !== file.descriptor.sha256) fail("content-mismatch");
+  }
+  return Object.freeze({ ...manifest, files: Object.freeze([...manifest.files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) });
+}