Metadata-Version: 2.4
Name: meridian-storage-evidence
Version: 1.0.0
Summary: Meridian V1 evidence Catalog, audit, lineage, provenance, and OTel bridge contracts
Project-URL: Documentation, https://github.com/zephytiju/meridian-storage-evidence#readme
Project-URL: Issues, https://github.com/zephytiju/meridian-storage-evidence/issues
Project-URL: Repository, https://github.com/zephytiju/meridian-storage-evidence
Author: Meridian contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: meridian-storage-core==1.0.0
Requires-Dist: meridian-storage-semantics==1.0.0
Provides-Extra: test
Requires-Dist: build<2,>=1.2; extra == 'test'
Requires-Dist: hatchling==1.27.0; extra == 'test'
Requires-Dist: hypothesis<7,>=6.135; extra == 'test'
Requires-Dist: jsonschema<5,>=4.23; extra == 'test'
Requires-Dist: mypy<2,>=1.15; extra == 'test'
Requires-Dist: pytest-cov<8,>=6; extra == 'test'
Requires-Dist: pytest<10,>=8.3; extra == 'test'
Requires-Dist: ruff<1,>=0.11; extra == 'test'
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: Apache-2.0 -->

# meridian-storage-evidence

`meridian-storage-evidence` is the single Python distribution implementing the Meridian V1
`evidence` Catalog. It provides provider-neutral audit, lineage, provenance, telemetry, policy,
query-helper, and low-level OpenTelemetry bridge contracts. It never selects an Adapter, Engine,
endpoint, Collector, or deployment topology.

The package is licensed under Apache License 2.0 and targets Python 3.12 or newer. Its released
dependencies are pinned to `meridian-storage-core==1.0.0` and
`meridian-storage-semantics==1.0.0`.

## Install

```console
python -m pip install meridian-storage-evidence==1.0.0
```

## Mapping-first Catalog API

Core discovers `EvidenceCatalogProvider` through the `meridian_storage.catalogs` entry-point.
Consumer code uses the same mapping-first syntax as every other Meridian Catalog:

```python
evidence = meridian.catalog("evidence")

expression = evidence.append(
    resource="runtime.logs",
    data={
        "severity": "INFO",
        "body": "worker ready",
        "attributes": {"worker": worker_name},
    },
)
meridian.execute(expression)

rows = meridian.execute(
    evidence.query(
        resource="runtime.logs",
        where={"severity": {"eq": "INFO"}},
        limit=50,
    ),
).data
```

The exhaustive V1 surface is `append`, `create_resource`, `publish_schema`, and `query`. Audit,
lineage, provenance, and telemetry are profiles inside the one `evidence` Catalog—not additional
Catalog names.

## Typed helpers and operation hooks

Mapping inputs remain authoritative. Typed records add validation and deterministic serialization:

```python
from datetime import UTC, datetime

from meridian_storage.evidence import EvidenceMetadata, LogRecord

record = LogRecord(
    severity="INFO",
    body="worker ready",
    metadata=EvidenceMetadata(
        event_time=datetime.now(UTC),
        observed_time=datetime.now(UTC),
        tenant="tenant-a",
        scope={"environment": "production"},
    ),
)
expression = evidence.append(resource="runtime.logs", data=record)
```

`OperationEvidenceHooks` builds explicit append plans from Core `Operation`, `OperationContext`,
`OperationResult`, and normalized failures. It propagates request, execution, tenant, scope, trace,
and safe Adapter provenance without copying unrestricted request/response bodies. Required atomic
audit plans must pass `EvidenceHookPlan.validate_atomic_resolution` before publication or startup.

## OpenTelemetry boundary

`OTelEvidenceBridge` preserves OTel log, span, and metric fields and supplies a bounded queue,
timeouts, recursion suppression, and non-recursive health counters. The separate public
`meridian-storage-plugin-observability` package owns consumer-facing tracers, meters, structured
loggers, exporter wiring, and process-wide provider installation. Core deliberately has no
`Meridian.telemetry()` method.

## Policy and retention

`EvidencePolicy` handles required fields, deterministic redaction/drop/rejection, record and
attribute bounds, distinct-value cardinality budgets, access-scope inputs, atomicity, queue-failure
policy, and logical retention intent. `RetentionPolicyInput` does not configure storage, delete
Data, enable WORM, or implement a military/national-security profile. Those remain deployment and
future-profile concerns.

## Architecture boundary

Meridian has exactly five Catalogs: structured, object, cache, evidence, and streaming. Evidence
persistence belongs to independently released Adapters. Collector deployment, OTLP routing,
storage placement, retention execution, recovery, and lifecycle belong to MeridianConstructs and
deployment IaC. Public values contain logical Resource references only; they never expose provider
credentials, endpoints, or physical names.

The implementation authority is Meridian HLD revision 60 and Meridian Catalogs and Public
Interfaces revision 72, section 5.7. See [architecture](docs/architecture.md),
[contracts](docs/contracts.md), and [compatibility](docs/compatibility.md).

## Development

```console
python -m pip install '.[test]'
ruff format --check src tests scripts
ruff check src tests scripts
mypy src
python scripts/verify_contracts.py
pytest --cov=meridian_storage.evidence --cov-report=term-missing
python -m build --no-isolation
python scripts/verify_artifacts.py dist
```

Release builds are made twice under one `SOURCE_DATE_EPOCH`, compared byte-for-byte, verified,
described by a deterministic SPDX 2.3 SBOM, and attested by GitHub Actions.
