@plasius/asset-contracts 0.3.1 → 0.4.0

package/docs/adrs/adr-0005-path-only-private-artifact-prevention-gates.md

@@ -0,0 +1,82 @@
+# ADR-0005: Path-Only Private-Artifact Prevention Gates
+
+## Status
+
+- Accepted
+- Date: 2026-07-15
+- Version: 1.0
+
+## Tags
+
+security, privacy, packaging, ci, compliance
+
+## Context
+
+Public source repositories and npm artifacts must never contain signed
+contributor agreements, acceptance registries, or similar personal records.
+An ignore rule cannot reject an already tracked path, while a broad package
+directory entry can silently expand a future release artifact.
+
+The prevention control must not increase exposure while evaluating a candidate
+repository. It therefore cannot open, hash, copy, diff, or log the contents of
+a suspected private artifact.
+
+## Decision
+
+Contributor agreements and acceptance records are stored only in an approved,
+access-controlled system outside source control.
+
+This package provides a zero-dependency Node.js path policy with three
+enforcement boundaries:
+
+1. `privacy:check` unions working-tree path metadata with `git ls-files
+   --cached`, without following symbolic links or reading candidate contents.
+   Ignored files remain visible, and a tracked deletion remains prohibited until
+   its removal is staged in the proposed index.
+2. `package.json.files` must equal a non-empty explicit allowlist. Broad entries
+   such as `.`, `*`, `**/*`, and `legal` fail closed; only the three public CLA
+   Markdown files may be selected from `legal/`.
+3. `pack:check` applies the private-path policy and an exact path/extension
+   allowlist to the path manifest returned by `npm pack --dry-run --json
+   --ignore-scripts`. Its isolated temporary npm cache is removed in a `finally`
+   boundary.
+
+The path policy rejects CSV files case-insensitively, CLA or contributor
+registries regardless of extension, signed-CLA storage directories, and paths
+that combine a privacy marker with a registry marker. It deliberately permits
+benign software terms such as `src/mcp-admin-registry.ts`.
+
+CI runs the repository gate before dependency installation and runs the policy
+tests plus package gate after build. Release preparation checks source before
+changing release metadata, CD checks the exact prepared commit before install,
+and `prepublishOnly` retains the package gate as a final local defense.
+
+Feature flags and capabilities do not apply: this mandatory privacy boundary
+must not be remotely bypassable.
+
+## Alternatives Considered
+
+- **Rely on `.gitignore` only**: rejected because ignore rules do not remove or
+  reject already tracked files and do not validate the proposed index.
+- **Scan file contents for personal data**: rejected for this boundary because
+  opening and reporting suspected records can increase exposure, while content
+  heuristics still have false positives and false negatives.
+- **Rely on `package.json.files` only**: rejected because directory entries can
+  expand over time and do not protect source-control state.
+- **Rely on the final package manifest only**: rejected because release
+  preparation and dependency installation must fail before packaging begins.
+
+## Consequences
+
+- Candidate repositories and npm path manifests fail closed on protected paths
+  without inspecting candidate contents.
+- Package selection is explicit, and generated/source/documentation roots are
+  constrained to their intended extensions.
+- New public path categories or private-artifact categories require an explicit
+  policy and regression-test update.
+- These controls are defense in depth, not a replacement for history cleanup,
+  registry remediation, secret scanning, access controls, or retention policy.
+
+## Related Decisions
+
+- [ADR 0001: Asset Contracts Package Boundary](./adr-0001-package-boundary.md)

package/docs/adrs/adr-0006-pvox-model-resolution-contracts.md

@@ -0,0 +1,168 @@
+# ADR 0006: Additive PVOX Model-Resolution Contracts
+
+## Status
+
+- Accepted
+- Date: 2026-08-20
+- Version: 1.0
+
+## Context
+
+Plasius-LTD/plasius-ltd-site Feature #2012 and Story #2013 require the hosted
+MCP service to acquire rights-cleared provider models, compile them to the
+texture-free Plasius voxel representation, render native PVOX evidence, obtain
+human confirmation, and atomically promote the immutable result. Asset-contracts
+Task #25 owns the shared serialized vocabulary and trust-boundary validation.
+
+The existing model-resolution family is already released. It describes the v1
+static-world GLB processing path, embeds mesh and texture ceilings in
+`ModelRequestSpec`, and is consumed by compatibility wrappers. Changing its
+types, constants, factories, state union, or runtime behavior would break those
+consumers. `ModelAssetRef`, however, is representation-neutral and remains the
+correct immutable catalog identity.
+
+PVOX introduces independently hashed pages, a sparse voxel hierarchy, localized
+surface and physical fields, native-render evidence, placement edit journals,
+and additional durable job states. An ingestion texture budget is meaningful
+while decoding a provider source but must never become a model-owned runtime
+texture limit.
+
+## Decision
+
+1. Add `pvox-model-resolution.ts` as a separate v2 family and re-export it from
+   the package root. Leave all v1 source and behavior unchanged.
+2. Preserve `ModelAssetRef`. Add a representation-discriminated
+   `ModelProcessingManifestV2` whose only admitted representation is `pvox`.
+3. Add `ModelRequestSpecV2`. Keep provider download, archive, file, and texture
+   decode ceilings in `sourceIngestionLimits`; keep fidelity, geometry,
+   capabilities, PVOX storage, hierarchy, spatial data, LOD, and residency
+   ceilings in `pvoxRuntimeProfile`. Reject legacy triangle/texture fields at
+   the v2 runtime boundary.
+4. Fix the public PVOX envelope to version 1.0 (`major: 1`, `minor: 0`) for
+   static/rigid content, with little-endian format policy owned
+   by `@plasius/gpu-model-voxel`, `.pvox`,
+   `application/vnd.plasius.pvox`, `PVOX` magic, 8-cubed bricks, 64-KiB pages,
+   a 256-byte header, 128-byte directory entries, at most 64 sections, depth
+   zero through eight, at most 2,624 pages, and at most 164 MiB. Every page is a
+   complete uncompressed 64-KiB hash unit. Metadata/LOD-structure pages have no
+   spatial scope; render/collision pages require LOD, partition, depth, and
+   Morton scope. The contracts package validates metadata, layout summaries,
+   hashes, bounds, scoped ordering, and cross-record binding; the voxel package
+   remains responsible for validating binary bytes and codecs. Technical
+   render-brick, logical-voxel, and encoded-sample counts are artifact-wide
+   sums across all retained LODs, and section count exactly matches the closed
+   static plus optional bond/collision registry.
+5. Require authenticated, credential-free PVOX resources only beneath the
+   exact resolution/candidate or immutable catalog/version MCP namespace. Do
+   not serialize provider URLs, signed storage URLs, source files, texture
+   resources, or credentials into PVOX runtime contracts.
+6. Represent every runtime capability as independent versioned evidence bound
+   to the PVOX binary closure. For the `world-editable-v1` request profile, require
+   rendering, collision, destruction, thermal, moisture, and fluid-boundary
+   capabilities. Enforce the complete governed property set for every localized
+   region/material, confidence at least 0.80, signed review for inferred values,
+   and no zero/default critical density, hardness, tensile/compressive/shear
+   strength, fracture, interior, ignition, or melting evidence. Bind an
+   independently attested complete region/palette inventory first, then require
+   physical evidence in canonical region/property order so omitted regions and
+   input-order-dependent digests fail closed. A supported destruction capability
+   additionally requires non-empty reviewed mass, bond-graph, and interior-layer
+   records.
+7. Require fidelity evidence to derive a passing decision from its recorded
+   geometry, silhouette, rendered, colour, and material thresholds. A supplied
+   `passed` label cannot contradict those measurements.
+8. Bind native PVOX render evidence to the processing manifest, PVOX root,
+   directory and page set, exact ordered four-view hashes, renderer version, and
+   an attestation. Require every non-overridable malware, source-format, PVOX,
+   fidelity, physical-property, renderer, and accessibility gate to pass.
+9. Keep binary, processing, assembly, render, evaluation, confirmation, edit,
+   and publication closures distinct. A leaf assembly closure hashes an empty
+   child list and never aliases the leaf binary closure. Bind compiler,
+   manifest, confirmation, and promotion records to separate source,
+   canonical-document, compilation-input, runtime-request-profile, artifact,
+   root, directory, page-set, and closure digests. Publish exact domain
+   separators, exact byte-order layouts, executable preimage encoders, and real
+   SHA-256 golden vectors. The normalized 256-byte root header includes section
+   count and one directory digest, requires zero reserved bytes, and never
+   double-hashes a header field. Contract factories cross-bind typed
+   attestations; authenticated hosts recompute digests and verify issuer tokens.
+   Fixed encoders reject extra own keys, malformed fixed tuples, non-byte-array
+   views, shared mutable byte storage, and inputs beyond governed work ceilings.
+10. Bind confirmation tokens and receipts to the exact v2 request and semantic
+   assessment, candidate identity, complete provenance and normalized rights
+   decision, PVOX binary/processing/assembly/evaluation closure hashes, ordered
+   view hashes, hard gates, fidelity, capability/physical-property, and complete
+   native renderer/settings/qualification evidence.
+   Allow an explicit override only for low semantic assurance; do not permit any
+   technical or governance gate to be overridden.
+11. Return blocked but valid evidence as a diagnostic candidate with stable
+   reason codes and no confirmation credential. Completed staged candidates
+   require a pointer-last promotion receipt covering credits, catalog row,
+   index snapshot, processing/assembly closures, confirmation and its exact
+   binding hash, and final ref.
+12. Validate placement edits as authenticated copy-on-write CAS operations.
+   Genesis binds the base artifact, page set, and root. A standalone later edit
+   requires complete authenticated current revision/root/journal/page state;
+   chain validation derives it after each edit, rejects replay and stale pages,
+   and forbids empty/no-op insert, remove, or replace transitions.
+13. Extend only the v2 lifecycle with `downloading`, `importing`, `voxelizing`,
+    `evaluating-fidelity`, and `awaiting-material-review`. Export a total,
+    deterministic mapping to v1 states for compatibility wrappers rather than
+    widening the v1 union.
+14. Validate unknown input through data-only, dense-array, closed-key factories
+    that reconstruct and deeply freeze output. Export 14 stable-id, strict,
+    self-contained JSON Schema 2020-12 descriptors from a separate schema
+    module for MCP construction, while retaining factories as the authoritative
+    relational validation boundary. Schema conditionals mirror durable-state
+    confirmation, promotion, final-reference, refinement, and reason-code rules;
+    confirmation timestamps cannot exceed the enclosing snapshot timestamp.
+
+## Consequences
+
+### Positive
+
+- Existing v1 consumers remain source- and behavior-compatible.
+- Hosted MCP, processing, rendering, catalog, and admin packages share one
+  immutable PVOX evidence vocabulary.
+- Source texture decoding is explicitly quarantined from the texture-free
+  runtime representation.
+- Candidate evidence cannot be transplanted across requests, sources, PVOX
+  closures, rights decisions, views, or renderers.
+- A low semantic match remains reviewable without weakening technical, rights,
+  security, accessibility, or physical-property admission.
+
+### Negative
+
+- V2 orchestration must project request semantics into the released v1 match
+  assessment while both families coexist.
+- Strict closed contracts require a future contract version for new serialized
+  physical fields, capability kinds, fidelity measurements, or binary envelope
+  versions.
+- The metadata contract cannot replace independent byte validation in
+  `@plasius/gpu-model-voxel` or authenticated resource authorization in the MCP
+  host.
+- Schema test tooling uses narrow audited transitive dependency overrides;
+  normal dependency maintenance must refresh those pins instead of weakening
+  the audit gate when upstream ranges change.
+
+## Alternatives Considered
+
+- Replace the v1 model-resolution types: rejected because it would silently
+  change released GLB behavior and exhaustive state handling.
+- Reuse v1 `maxTextureBytes` for PVOX: rejected because it conflates sandboxed
+  source decoding with texture-free runtime resources.
+- Store PVOX as another GLB processing output: rejected because PVOX has a
+  different binary, capability, fidelity, physical, mutation, and renderer
+  evidence model.
+- Permit semantic override of failed PVOX gates: rejected because confidence in
+  naming does not mitigate licensing, malware, format, fidelity, physical, or
+  renderer failure.
+
+## Related Decisions and Work
+
+- Plasius-LTD/plasius-ltd-site Epic #902
+- Plasius-LTD/plasius-ltd-site Feature #2012
+- Plasius-LTD/plasius-ltd-site Story #2013
+- Plasius-LTD/asset-contracts Task #25
+- [ADR 0002: Versioned Model Resolution Contracts](./adr-0002-model-resolution-contracts.md)
+- [TDR 0003: PVOX Validation and Confirmation Binding](../tdrs/tdr-0003-pvox-validation-and-confirmation-binding.md)

package/docs/adrs/adr-0007-hosted-oidc-package-publication.md

@@ -0,0 +1,41 @@
+# ADR 0007: Hosted OIDC Package Publication
+
+- Status: Accepted
+- Date: 2026-08-11
+
+## Context
+
+`@plasius/asset-contracts` must publish without a long-lived npm write token and
+must not accept CI evidence for a different source snapshot.
+
+## Decision
+
+Publication is phase-isolated: release-admission scripts run in a credential-free
+hosted job, and the write-capable release-preparation job starts from a fresh
+checkout with Git hooks disabled. Dependency installation, package validation,
+SBOM generation, and immutable tarball packing run in `validate_and_pack`
+without the `production` environment or OIDC permission. The final hosted
+`publish` job downloads only that sealed artifact, explicitly installs npm
+11.6.2, runs no repository dependency code, and publishes the tarball with
+lifecycle scripts disabled. It re-fetches current `main` immediately before the
+first release mutation and again immediately before npm publication. `.npmrc`
+contains no registry-auth placeholder, and release preparation returns the
+reviewed current `main` HEAD rather than package-file history.
+
+Use the GitHub-hosted `production` publish job and npm trusted publishing. The
+job proves the prepared SHA is still the exact remote `main` head, waits for a
+successful push-triggered `ci.yml` run for that SHA, enforces Node 24 with npm
+11.5.1 or newer, and publishes with provenance. Token fallbacks are prohibited.
+
+## Consequences
+
+Publication fails closed if npm's trusted-publisher binding is absent, `main`
+moves, exact-SHA CI has not succeeded, the runtime is unsupported, or OIDC is
+unavailable. An interrupted release may reuse its already-prepared version only
+while npm or the matching GitHub release remains incomplete; immutable tarball,
+tag, dist-tag, and exact-main checks still govern recovery.
+
+## Test implications
+
+Contract tests enforce the identity, source, CI, runtime, and provenance gates
+and reject legacy npm credential names.

package/docs/adrs/index.md

@@ -4,3 +4,6 @@
 - [ADR 0002: Model Resolution Contracts](./adr-0002-model-resolution-contracts.md)
 - [ADR 0003: WGSL Shader Asset Contracts](./adr-0003-wgsl-shader-asset-contracts.md)
 - [ADR 0004: Immutable Exact Asset Versions](./adr-0004-immutable-exact-asset-versions.md)
+- [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)

package/docs/tdrs/index.md

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

package/docs/tdrs/tdr-0003-pvox-validation-and-confirmation-binding.md

@@ -0,0 +1,208 @@
+# TDR 0003: PVOX Validation and Confirmation Binding
+
+## Status
+
+- Accepted
+- Date: 2026-08-20
+- Version: 1.0
+
+## Direction
+
+`src/pvox-model-resolution.ts` owns the additive serialized PVOX boundary. Its
+factories accept `unknown`, require plain objects with exact key sets, normalize
+through allow-listed reconstruction, validate cross-record invariants, and
+deeply freeze the result. Callers must not cast provider, database, queue, MCP,
+or decoded JSON payloads directly to exported interfaces.
+
+The module validates evidence describing a byte-verified PVOX artifact. It does
+not decode the PVOX binary. `@plasius/gpu-model-voxel` must independently parse
+and validate the complete byte stream, fixed records, section table, codecs,
+Morton order, page hashes, sizes, bounds, and trailing-byte absence before
+issuing compiler/validator evidence accepted by this contract family.
+
+## Request Routing
+
+`createModelRequestSpecV2` separates two budget domains:
+
+| Domain | Contract | Meaning |
+| --- | --- | --- |
+| Quarantined source | `ModelSourceIngestionLimitsV2` | Provider download, bounded expansion, entry/file counts, decoded texture bytes and decode dimensions |
+| Immutable runtime | `PvoxRuntimeRequestProfileV1` | Fidelity and capability profiles, geometry mode, artifact/pages/hierarchy/bricks/logical voxels/encoded surface records/partitions/LODs and CPU/GPU residency |
+
+PVOX runtime limits contain no triangle or texture field. Every request includes
+`rendering`; named `world-editable-v1` and `deformable-v1` profiles require their
+complete governed capability subsets. Public values may tighten the exported
+ceilings but cannot raise them.
+
+V2 matching can reuse the released `ModelMatchAssessment` while the families
+coexist, but a durable v2 resolution verifies that every candidate's embedded
+v1 assessment has the same normalized query and immutable request revision.
+
+## Artifact and Processing Validation
+
+Validation proceeds in this order:
+
+1. Validate the authenticated MCP artifact URI, declared digest, whole-page byte
+   length, fixed PVOX 1.0 `{major, minor}` constants, canonical coordinate
+   system, floor-centred bounds, and absolute 1,048,576-metre coordinate cap.
+2. Require a 256-byte header, 128-byte directory entries, at most 64 sections,
+   8-cubed bricks, and uncompressed 64-KiB pages. Validate contiguous page
+   indices/offsets and exact page coverage; partial final pages are invalid.
+3. Discriminate pages as metadata, LOD structure, render field, or collision
+   field. Metadata/LOD pages forbid spatial scope. Field pages require LOD,
+   partition, hierarchy depth, and fixed-width Morton range; ranges are ordered
+   and non-overlapping within `(kind, LOD, partition)`.
+4. Validate one to four contiguous LODs beginning at LOD0. LOD page slices must
+   reference render-field pages in the matching LOD scope.
+5. Recompute technical dimensions from bounds and bind whole-page byte count,
+   LOD, geometry mode, hierarchy, partition, logical-voxel, encoded-sample, and
+   resident counts. Depth zero is a root brick. Maximum partition extent must
+   fit `LOD0 cell × 8 × 2^depth`, permitting fidelity-driven small partitions.
+6. Enforce 524,288 render bricks, 268,435,456 logical voxels, 8,388,608 encoded
+   samples, 1,048,576 hierarchy nodes, 512 runs/local samples per brick, and a
+   10,384-byte encoded brick payload. Fixed-record feasibility includes the
+   hierarchy, brick descriptors, 128-byte render/collision masks, 16-byte
+   render samples, 4-byte collision samples, palette/evidence/interior/mass/
+   bond records, directory, and per-section alignment. These lower bounds must
+   fit the artifact; no limit silently degrades fidelity. Render brick,
+   logical-voxel, and sample totals cover all retained LODs, and section count
+   exactly matches the closed static plus optional bond/collision registry.
+7. Bind compiler source, canonical-document, compilation-input,
+   runtime-request-profile, and output hashes through PVOX, processing, and
+   confirmation records.
+8. Require exactly one assessment per known capability, bind each to the PVOX
+   binary closure, and require every requested capability to be supported.
+9. Bind an attested authoritative region/palette inventory to PVOX validation,
+   then bind physical evidence by `(regionId, materialId, property)` in region
+   index and governed-property order. Every declared material region must be
+   represented and satisfy every governed property for its supported
+   capabilities at confidence 0.80 or higher; inferred values require signed
+   review and critical density, hardness, tensile/compressive/shear strength,
+   interior, fracture, ignition, and melting values cannot be zero or defaulted.
+   Supported destruction also requires non-empty reviewed mass, bond-graph, and
+   interior-layer records.
+10. Derive fidelity outcome from governed profile formulas and the fixed
+    silhouette, contour, SSIM, colour, and material thresholds. Maximum surface
+    error is bounded by both three times the p99 ceiling and 1.5 LOD0 cells.
+11. Validate a canonical, acyclic single-root assembly graph and bind every
+    catalog/staged child to a PVOX binary closure and immutable manifest identity.
+    Leaves also receive a distinct, attested assembly-domain digest over their
+    own binary closure and an empty child list.
+
+The compiler evidence and processing manifest cannot prove the PVOX bytes by
+themselves. Their issuer must be an allow-listed, attested worker in the hosted
+pipeline, and the resource loader must revalidate artifact bytes and hashes.
+The synchronous factory does not authenticate issuer tokens. Hosted workers and
+resource loaders must use the exported executable preimage encoders to
+recompute applicable digests and verify each typed attestation against its
+allow-listed issuer. Producer-asserted hashes without successful attestation
+verification are not admission evidence.
+
+Hash-domain constants, `PVOX_HASH_PREIMAGE_LAYOUTS`, and executable byte
+encoders define the PVOX 1.0 preimages. Integers use the specified little-endian
+width, variable UTF-8/JSON inputs are length-prefixed, and digests are raw 32
+bytes. The root preimage includes one exact normalized 256-byte header: section
+count is stored in the header, directory hash appears once at bytes 176–207,
+and reserved bytes 208–255 must be zero. Binary closure includes source,
+canonical document, compilation input, runtime request profile, artifact, root,
+directory, and page-set hashes. Processing, empty-or-populated assembly, render,
+evaluation, confirmation, edit, and publication domains are separate. Fields
+holding their own digest/attestation/token are explicitly omitted from the
+corresponding canonical preimage to prevent self-reference.
+Fixed-layout preimage functions admit exact known own keys only, require exact
+six-component bounds and intrinsic non-shared `Uint8Array` byte inputs, and cap
+section, assembly, canonical-text, data-tree, and complete preimage work at
+governed limits.
+
+## Candidate and Confirmation Binding
+
+A v2 candidate is confirmable only when all of the following are true:
+
+- match assurance is `high` or `low` and its independent hard constraints pass;
+- rights status is `allowed` and rights/provenance/source hashes agree;
+- the staged or existing asset identity, kind, and content hash agree with the
+  PVOX processing manifest;
+- exactly four original views are ordered front, left, top, isometric and their
+  hashes agree with native PVOX render evidence;
+- typed render evidence binds its id, native PVOX LOD0 backend, processing
+  manifest and closure, PVOX content/root/directory/page set, renderer and
+  settings identity/version, renderer/camera qualification, timestamp, ordered
+  view hashes, evidence hash, and domain-separated attestation;
+- malware, source-format, PVOX, fidelity, physical-property, renderer, and
+  accessibility gates each appear exactly once, pass, and bind the artifact;
+- a candidate-level evaluation closure binds fidelity, physical, capability,
+  and render evidence;
+- the backend-issued confirmation subject matches the complete semantic
+  assessment, provenance, normalized rights decision/token/policy/licence/
+  attribution, immutable request and candidate, binary/processing/assembly/
+  evaluation closures, hard gates, views, and full renderer evidence.
+
+Evidence-valid but blocked candidates normalize to the diagnostic union member,
+carry stable blocking reason codes, and omit the confirmation binding/token.
+
+`createModelCandidateConfirmationV2` accepts `semanticRiskAccepted: true` only
+for a low-assurance candidate and requires it there. The field cannot bypass or
+alter any other decision because candidate construction has already required
+every hard gate and evidence relationship to pass. Confirmation time must not
+precede the latest evidence it approves.
+
+## Durable State Compatibility
+
+`MODEL_RESOLUTION_V2_STATES` is the authoritative v2 persistence vocabulary.
+`MODEL_RESOLUTION_V2_COMPATIBILITY_STATES` is total and deterministic. New
+acquisition/compilation states project as follows:
+
+| V2 state | V1 projection |
+| --- | --- |
+| `downloading` | `searching-providers` |
+| `importing` | `processing` |
+| `voxelizing` | `processing` |
+| `evaluating-fidelity` | `evaluating` |
+| `awaiting-material-review` | `evaluating` |
+
+All other states map to the same v1 spelling. Compatibility wrappers may expose
+the projection, but persistent v2 records retain the full state. Completed
+records require confirmation and a final immutable `ModelAssetRef`; unresolved,
+failed, and cancelled records require a bounded stable reason code. Completed
+staged candidates also require a pointer-last promotion receipt binding the
+proposal, confirmation and its binding hash, processing/assembly closures,
+credits, catalog row, index snapshot, pointer ETags, and final asset reference.
+Any resolution that carries confirmation must have an `updatedAt` timestamp no
+earlier than `confirmedAt`; strict schemas mirror the same state-dependent
+confirmation, promotion, final-reference, refinement, and terminal-reason rules.
+
+Placement edit journals use copy-on-write compare-and-swap. Genesis must start
+at revision zero, the canonical previous-journal hash, the authenticated base
+root, and the base page inventory. A standalone non-genesis entry is accepted
+only with authenticated current placement state covering revision, root,
+previous journal, and every current page hash. Chain validation derives this
+state after each operation, rejects replayed operation ids and stale pages, and
+requires chronological sequential revisions. Insert/remove/replace semantics
+forbid empty or unchanged endpoints.
+
+## Verification
+
+- TDD records the missing-export failure before implementation.
+- Boundary tests cover closed keys, immutable output, fixed format and limit
+  invariants, authenticated resources, page ordering/coverage, dimensions,
+  capability completeness, physical review, fidelity derivation, edit-journal
+  sequence, hard-gate completeness, cross-record hash binding, semantic
+  override rules, lifecycle projection, and terminal-state requirements.
+- Executable preimage tests use real SHA-256 golden vectors, exact root-header
+  bytes, mutation sensitivity, and zero-reserved-byte enforcement rather than
+  shape-only repeated-character digest fixtures.
+- Fourteen standalone JSON Schema 2020-12 roots live in
+  `pvox-model-resolution-schema.ts`; each has a stable contract-versioned `$id`,
+  a self-contained closed `$defs` graph, strict Ajv 2020 compilation, and
+  factory-output/invalid-sample parity coverage. Factories remain authoritative
+  for hash preimages, ordering, formulas, chronology, and cross-record identity.
+- The complete existing v1 suite remains green and `src/model-resolution.ts`
+  remains unchanged.
+- Build, typecheck, lint, npm audit, dependency audit, coverage, changed-source
+  LCOV inclusion, and packed-tarball ESM/CJS consumption remain delivery gates.
+
+## Related Decisions
+
+- [ADR 0006: Additive PVOX Model-Resolution Contracts](../adrs/adr-0006-pvox-model-resolution-contracts.md)
+- [ADR 0002: Versioned Model Resolution Contracts](../adrs/adr-0002-model-resolution-contracts.md)
+- Plasius-LTD/asset-contracts Task #25

package/legal/CLA.md

@@ -15,8 +15,11 @@ To protect the intellectual property of this project and ensure clarity of right
 
 ## Registry
 
-All signed CLAs are logged internally in the CLA registry (`CLA-REGISTRY.csv`).
+Signed agreements and acceptance records are stored in an access-controlled
+system outside source control. They must never be committed to a repository,
+included in a package, or copied into issues, pull requests, build logs, or
+other public artifacts.
 
 ## Questions?
 
-If you have any questions about which CLA to sign or how the process works, please email **[contributors@plasius.co.uk](mailtocontributors@plasius.co.uk)**.
+If you have any questions about which CLA to sign or how the process works, please email **[contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/asset-contracts",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Canonical contracts for Plasius asset jobs, model resolution, immutable WGSL shader assets, reviews, and promotion records.",
   "type": "module",
   "sideEffects": false,
@@ -17,7 +17,9 @@
     "CODE_OF_CONDUCT.md",
     "CONTRIBUTORS.md",
     "docs",
-    "legal"
+    "legal/CLA.md",
+    "legal/CORPORATE_CLA.md",
+    "legal/INDIVIDUAL_CLA.md"
   ],
   "exports": {
     ".": {
@@ -31,16 +33,18 @@
     "build": "tsup",
     "clean": "rimraf dist tsconfig.tsbuildinfo",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run && npm run test:privacy",
     "test:watch": "vitest",
+    "test:privacy": "node --test tests/private-artifact-policy.test.cjs",
     "test:coverage": "vitest run --coverage",
     "audit:eslint": "eslint . --max-warnings=0",
     "audit:deps": "npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true",
     "audit:npm": "npm audit --audit-level=high --omit=dev",
-    "audit:test": "vitest run --coverage",
+    "audit:test": "vitest run --coverage && npm run test:privacy",
     "audit:all": "npm run typecheck && npm run audit:eslint && npm run audit:deps && npm run audit:npm && npm run audit:test",
     "lint": "eslint . --max-warnings=0",
-    "pack:check": "node scripts/verify-public-package.cjs",
+    "privacy:check": "node scripts/verify-private-artifacts.cjs",
+    "pack:check": "npm run privacy:check && node scripts/verify-public-package.cjs",
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && npm run pack:check"
   },
@@ -71,6 +75,7 @@
     "@typescript-eslint/eslint-plugin": "^8.62.0",
     "@typescript-eslint/parser": "^8.59.3",
     "@vitest/coverage-v8": "^4.1.6",
+    "ajv": "^8.17.1",
     "eslint": "^10.3.0",
     "globals": "^17.6.0",
     "rimraf": "^6.1.3",
@@ -96,7 +101,11 @@
     "node": ">=24"
   },
   "overrides": {
-    "minimatch": "^10.2.1"
+    "brace-expansion": "5.0.9",
+    "esbuild": "^0.28.1",
+    "minimatch": "^10.2.1",
+    "nanoid": "3.3.18",
+    "postcss": "8.5.26"
   },
   "dependencies": {
     "@plasius/gpu-shader": "^0.1.1"

package/src/index.ts

@@ -35,6 +35,9 @@ export {
   assertImmutableAssetVersion,
 };
 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 {
   GPU_SHADER_STORE_FEATURE_FLAG,
   GPU_SHADER_STYLE_SELECTION_CAPABILITY,