Metadata-Version: 2.5
Name: edgar-transport-contracts
Version: 0.1.0
Summary: Producer-owned EDGAR wire contracts: closed vocabularies, bridge v3, KPI driver rows and typed refs shared across the edgar_updater to ai-excel-addin boundary
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.11
Requires-Dist: pydantic<3,>=2.10
Description-Content-Type: text/markdown

# edgar-transport-contracts

Producer-owned wire contracts for the `edgar_updater` → `ai-excel-addin`
boundary (design `edgar-to-build-model-e2e-type-and-transport-contract-design-2026-10-22.md`,
ratified §4 Q1–Q8; `S-XREPO-1`). This package is the **one owner** of every
closed wire vocabulary and structural invariant on that boundary: both repos
pin it by version and neither re-declares a member of a contract set.

Shapes and validators only — no behaviour, no I/O, no imports from
`edgar_api`, `edgar_parser` or `packages/edgar_shared`. Its sole dependency is
`pydantic>=2.10,<3`.

Contents:

- `enums` — `NonGaapOutputMetricId`, `NonGaapAdjustmentRole`,
  `BridgeGranularity`, `OmittedTableStage` / `OmittedTableReason` (ratified 5)
  with `LEGACY_OMITTED_TABLE_REASONS` for the tolerant reader, `KpiGapReason`
  (6 + `financials_unavailable`), `NonGaapMetricFamily`, `BridgeFailureReason`.
- `measure` — `MeasureUnit`, `Scale`, `ScaleProvenance`, `MeasureType`,
  `ScaledQuantity`, `EvidencedBlank`.
- `period` — one `TypedPeriod` (`annual|quarterly|ytd|ttm` +
  `temporal_kind`) with `canonical_label()`.
- `dimensions` — `DimensionAxis`, `XbrlFactRef`, and the one
  `serialize_dimensions` / `parse_dimensions` (`|`-joined, escaped) form.
- `kpi` — `KpiDriverRowsV2`, `TypedKpiObservation`, `OmittedTable`,
  `KpiLaneGap`, `ReaderRecord`.
- `tables` — `FilingTableEnvelope` and `TableBinding` / `ColumnBinding` /
  `RowBinding` / `CellRef`, published as `extra="forbid"` models.
- `non_gaap_bridge` — `IssuerNonGaapBridgeV3` (`canonical_output_metric` +
  `output_metric_slug`, `effective_metric_key`, producer-minted `bridge_id`,
  `granularity`, typed `closure: BridgeClosureState`, flattened `subtotals` —
  no `chained_from`) and `IssuerNonGaapBridgeResponseV3`.
  Its `rounding_consistent` diagnostic preserves the printed-equation residual
  within the half-ulp budget; like other ordinary diagnostics, it does not carry
  metric-context fields (`effective_metric_key`, `period`, or `label`).
- `canonicalize` — `OUTPUT_METRIC_SURFACE_FORMS` and
  `classify_adjustment_role`, beside the enums they feed.
- `version` — `CONTRACT_VERSIONS` and `version_refusal(received, expected)`.
- `golden` — the 13-issuer golden pack skeleton and its
  `golden.load(issuer, kind)` loader (contents land in `S-XREPO-5`).

Install for development from the producer repo root:
`pip install -e packages/edgar_transport_contracts`. Run its tests with
`.venv/bin/python -m pytest packages/edgar_transport_contracts/tests -q`.
