zeromodel-artifacts

Canonical artifact reference, resolution, and content-addressed storage for the ZeroModel workspace.

This package defines the stable, cross-package ArtifactRef identity and the ArtifactResolver / ArtifactStore protocols other packages (such as zeromodel-trust and zeromodel-navigation) use to persist and resolve their own artifacts, without each package inventing its own storage layer.

It reuses zeromodel.core's existing canonicalization and digest primitives (canonical_json_bytes, sha256_digest) rather than redefining them.

Report compilation and the compiled-report aggregate

On top of the storage kernel, this package also compiles typed external reports into deterministic, source-bound VPM artifacts (ReportAdapter, AdaptedReportDTO, compile_report()) and resolves the complete result as one coherent aggregate:

AdaptedReportDTO (persisted, resolvable)
ReportAdapterContractDTO (persisted, resolvable)
    ↓
CompiledReportArtifactDTO (aggregate root)
    ├── adapted_report_ref    -> AdaptedReportDTO
    ├── adapter_contract_ref  -> ReportAdapterContractDTO
    ├── score_table_ref       -> ScoreTable
    ├── layout_recipe_ref     -> LayoutRecipe
    └── vpm_artifact_ref      -> VPMArtifact

load_compiled_report_aggregate() resolves all five referenced artifacts and runs validate_compiled_report_aggregate(), which proves the collection is semantically closed - not merely that each object's own digest is valid, and not merely that the resolved objects agree with each other. A compiled report can reference a ScoreTable from one report, a LayoutRecipe from another, and a VPMArtifact from a third, each individually digest-valid; a VPM can even embed the correct ScoreTable and LayoutRecipe while its normalized pixels or row/column ordering are fabricated. Aggregate validation proves: every resolved object's store-level digest actually matches the ref the compiled report declares for it (not merely assumed from how the caller obtained the object); the resolved adapter contract's declared fields agree with what the compiled and adapted reports copied from it; the VPM's normalized_values/ row_order/column_order/provenance are exactly what build_vpm() would deterministically reproduce from the resolved ScoreTable/ LayoutRecipe; and every VPM view coordinate, raw value, and source binding is exactly what the compiled report's cell bindings claim. build_compiled_report_closure_receipt() produces an auditable, content-addressed receipt only after every check passes - never a partial result.

Compatibility between two compiled reports requires three independent identities to agree: compatibility_id (a human label), and two content digests: compatibility_schema_id (dimension ids, order, score semantics, and value/target ranges) and report_semantics_id (report kind, subject kind, dimension namespace, and duplicate-value policy - the layer that distinguishes, for example, a report over sentences from a structurally identical report over claims).

load_compiled_report_vpm(*, ref, resolver) is the one safe public path to a compiled report's rendered VPMArtifact - it is a thin wrapper around load_compiled_report_aggregate(...).vpm_artifact, so it always runs the full closure (including the deterministic-reconstruction check above) before returning anything. core_artifact_persistence.load_vpm_artifact remains available as an explicitly low-level Core loader (digest-only, no compiled-report context to close an aggregate against) for callers who genuinely have no compiled report to check against - it is not itself a safe rendering path for a compiled report's VPM.

A reference is the pair (artifact_kind, artifact_id), not the digest alone: CompiledReportArtifactDTO rejects a nested ref whose declared kind doesn't match its expected artifact kind even when the artifact_id genuinely matches stored content, and validate_compiled_report_aggregate re-asserts the same check as defense in depth. CompiledReportClosureReceiptDTO similarly cannot be constructed with an incomplete checks tuple or non-empty failure_codes, even with a receipt_id that correctly hashes that content - the type's promise that "every check passed" is enforced structurally, not left to its one legitimate builder.

Claims boundary: ZeroModel can persist and reload a complete adapted report, its governing adapter contract, and its compiled ScoreTable, LayoutRecipe, and VPMArtifact as one content-addressed aggregate, and verify that every subject, dimension, value, coordinate, source binding, declared contract semantic, and rendered pixel agrees across all five representations - including that the VPM's visible pixels were actually generated by its own embedded recipe, not merely digest-consistent with themselves. This does not include Trust-signed compiled reports (Trust integration is a call-site composition, not implemented here), cross-schema conversion, or automatic report repair.