Crate ethos_core 

ethos-core

The Ethos product contract in Rust: canonical document model, deterministic serialization (c14n v1), fingerprints, stable error/warning codes, page-range configuration, and the trait boundaries between crates.

Normative references: schemas/*.json and docs/determinism-contract.md. Contract changes happen only via contract-change PRs with version bumps.

Feature layers (invariant 4: verify portability)

• grounding — the grounding::GroundingSource trait module alone. ethos-verify depends on ethos-core with default-features = false, features = ["grounding", "verify-types"] and therefore can never see parser internals. CI builds it that way to prove it.
• verify-types — verification report/config schema types + stable warning codes.
• full (default) — canonical model, c14n, fingerprints, geometry, config, traits.
• crop-element — source-only pre-alpha crop descriptor API, intentionally opt-in.

Modules

c14n

c14n v1 — the single canonical JSON serialization (determinism contract §2). No other crate hand-rolls output JSON (invariant 2).

codes

Stable warning codes (PRD §10). New codes are contract-change events; renames are breaking. Error codes live in crate::error (full feature) because only the parser emits them; warning codes are shared with verification reports (verify-types feature).

config

Parse configuration: page selection (--pages 1-5,9), resource limits, and the effective-config hash subset (determinism contract §7).

error

Stable error codes (PRD §10) and their CLI exit codes (docs/architecture.md). A PDF that cannot be parsed safely fails with one of these — never a panic. Code changes are contract-change events; exit codes are public API.

evidence_anchor

Evidence-anchor request/report schema types.

fingerprint

Fingerprints (determinism contract §6). The composite document fingerprint binds stable payload projection, source, config, and profile identity into one comparable value.

geom

Quantized geometry (determinism contract §4). Invariant 1: extraction emits these types — raw f64 tuples cannot cross the backend boundary.

grounding

The GroundingSource trait module (PRD §5.5) — the sole boundary between ethos-verify and any parser, Ethos included.

ids

Deterministic ID formatting/parsing (ids-v1, determinism contract §5). IDs are functions of canonical order — never random, never time-based.

model

Canonical document model (urn:ethos:schema:document:1). Field-for-field mirror of the schema; serialization through these types + crate::c14n is the only way Ethos emits the document artifact.

traits

Crate boundaries (Milestone A skeleton): the backend trait (EthosPdfBackend) and the layout trait. Invariant 3: only ethos-pdf implements the backend; public schemas and APIs never expose PDFium types — everything crossing this boundary is already normalized and quantized (invariant 1).

verify_types

Verification report/config schema types (urn:ethos:schema:verification-report:1, urn:ethos:schema:verification-config:1).

Constants

C14N_VERSION

c14n algorithm version implemented by c14n (when the full feature is on).

ID_SCHEME_VERSION

ID scheme version implemented by ids (when the full feature is on).

PROFILE_ID

The deterministic profile this crate is built to honor.

SCHEMA_VERSION

Canonical schema version emitted by this crate (all five schemas move in lockstep).