Methodology: the offline integration contract

Inputs are fixtures, outputs retain provenance

The bundled values are invented, with conspicuous synthetic series and issuer identifiers. They resemble selected public response structures so readers can inspect a working adapter without API credentials or an external service dependency. Pasting or importing a supported JSON payload runs the same local normalization path. The sample does not claim complete coverage of those providers' APIs, optional fields or response modes.

Each normalized row carries source, series, observation_date, value, unit, available_date, availability_basis, retrieved_at, revision_key and source_record. Period metadata is retained where a sortable date alone would mislead. The source_record field is a locator or accession, not embedded raw JSON. Keep the input separately to inspect transformations. Neither a locator nor fixture metadata proves that a real provider sent the record.

Three availability conventions remain different

FRED-shaped records use realtime_start for the selected day-level available_date and label the basis fred_realtime_date. The adapter is scoped to the documented V1 observation shape; newer API versions do not silently change that scope. It checks realtime_end chronology but selects latest eligible starts without reconstructing full validity intervals. The cutoff example does not certify a complete historical vintage archive or a release-time calendar.

World Bank-shaped records label availability as retrieval_time. Dataset lastupdated stays dataset metadata rather than becoming a per-row release date. An annual period such as 2023 is retained as observation_period with period_kind annual; the corresponding 2023-12-31 observation_date is a sortable key, not an invented publication event. SEC-shaped instant facts use filed for a day-only date with basis sec_filed_date and retain accession identity. No midnight release timestamp is invented.

Normalize carefully, validate before accepting

A supported missing token becomes null, while numeric zero remains zero. Invalid values are rejected rather than silently coerced into data. The adapter validates required dates, fields and units within its scope. Duplicate revision keys reject, whether their values agree or conflict. At cutoff selection, different values on the latest eligible date reject as ambiguous; equal-value ties use deterministic provenance ordering without claiming a temporal order.

Pagination validation checks expected page identities and consistent metadata before treating a batch as complete. The retry planner allows at most three attempts and accepts numeric delay inputs, not HTTP-date headers. A server delay above the local 60-second budget stops the plan instead of being shortened. A fully validated batch is the proposed commit boundary; the lab does not implement durable checkpoints, scheduled refreshes, credentials, webhook delivery or cloud-failure recovery.

Reproduction and production adaptation

The worked cases give fixed expected outcomes for vintage selection, two-page completeness, missing-versus-zero treatment and a 429 retry sequence. Tests of those outcomes establish software behavior for the supplied cases. They do not validate an investment strategy, certify a provider feed or prove that all upstream changes will be handled. Retain the input, adapter version, cutoff and diagnostics with each exported result.

A real integration requires current provider documentation, appropriate rights, protected authentication, request identification and limits, complete acquisition records and an operated deployment. SEC documentation also states that data.sec.gov does not support CORS; a browser fixture is not evidence that a live browser fetch will work. Any recurring production ingestion or monitoring must be managed in cloud infrastructure with durable evidence, independently of this publication and an operator's computer.

Keep in the decision record

• Preserve the availability basis instead of flattening all timestamps into one meaning.
• The lab supports selected fixture shapes, not entire provider API surfaces.
• Production delivery and durable operations require separate implementation evidence.

Source notes

1. FRED V1 observation response
2. World Bank API structures
3. SEC EDGAR API documentation

Primary specifications support the interface descriptions. All downloadable response fixtures are synthetic. Access and rights checks are dated in the source inventory.