# ZeroEcho Library

ZeroEcho is a layered cryptography library delivered as the `lib` module. It exposes a minimal core of cryptographic primitives and a higher-level SDK of composition tools. The design favors clear separation of responsibilities, safe defaults, and extensibility for future algorithms and pipelines.

## Layering

- Core (`zeroecho.core`): low-level cryptographic engine. This includes algorithm definitions, stateful contexts, registry and metadata, specification and SPI contracts, and selected helpers required by algorithms (e.g., I/O, marshalling, tagging, auditing, policies).
- SDK (`zeroecho.sdk`): developer-facing composition layer built on the core. It provides content abstractions, fluent builders (both generic and per-algorithm), utilities for multi-recipient or composed flows, and supporting helpers used by those builders.

## Package map (lib)

- zeroecho.core
  - alg: concrete algorithms and small shared helpers used by algorithms.
  - context: stateful operation interfaces (encryption, signatures, digests, MAC, agreement, KEM, and related variants).
  - spec / spi: specification objects and construction/factory contracts.
  - policy / audit / err / annotation: cross-cutting concerns within the core.
  - io / marshal / tag: helpers used by algorithms and contexts at runtime.
  - (root): provider/registry surface and core metadata.
- zeroecho.sdk
  - content: content abstractions, basic implementations, and export facilities.
  - builders: composition APIs, including generic builders and per-algorithm builders.
  - guard: utilities for multi-recipient and other composed workflows.
  - io / logging: supporting helpers used by the SDK layer and applications.

## Design principles

- Stratification: the core remains focused on algorithms and correctness; the SDK focuses on developer ergonomics and composition.
- Composability: data flows are constructed through builders and content abstractions with predictable, chainable behavior.
- Extensibility: new algorithms, formats, and flows can be added with minimal impact on existing code.
- Safety: role-based binding and policy checks promote safe defaults and clear intent.

## Intended use

Third-party applications depend on the `lib` module. Most integrations work at the SDK layer to compose data pipelines, while the core layer provides the cryptographic foundation and guarantees. The project’s structure and documentation aim to make entry points, responsibilities, and extension points explicit.