Metadata-Version: 2.4
Name: zeromodel-artifacts
Version: 1.1.0
Summary: ZeroModel canonical artifact reference, resolution, and content-addressed storage
Author-email: Ernan Hughes <ernanhughes@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ernanhughes/zeromodel
Project-URL: Repository, https://github.com/ernanhughes/zeromodel
Project-URL: Documentation, https://ernanhughes.github.io/zeromodel/
Keywords: visual-policy-map,vpm,artifact-identity,content-addressed-storage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: zeromodel==1.1.0

# 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:

```text
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.
