[EPAC-2304]: Lock bills SQLite artifact schema with a producer-to-consumer seam test#823
Merged
riddim-developer-bot[bot] merged 1 commit intoJun 14, 2026
Conversation
The bills SQLite artifact is an implicit contract between two binaries: the
bills-indexer writer (producer) and the bills serving repository (consumer).
Nothing fast verified the assembled contract, and the serving repo masked
drift with dynamic column-name fallbacks. As shipped, the served
BillVersion's title/chamber/published_on were always empty because the
indexer never writes those columns.
- Add TestBillsArtifactSeam: it drives the real producer binary offline to
write a real bills.db, then reads it with the real serving repository and
asserts GetBillDepth/GetBillVersionDiff/version reads return the promised
columns populated. Only the on-disk file crosses the seam, so neither
module imports the other's internals.
- Single-source the served bill_versions contract to {id, label, stage,
source_url}: label and stage both carry the publication stage name, and
source_url is the indexer's html_url. Drop the always-empty
title/chamber/published_on from the domain model and OpenAPI (no runtime
response change; they were already omitted as empty).
- Replace the serving repo's dynamic column fallbacks with fixed SQL for the
version and amendment reads, and remove the now-dead helpers.
- Add an offline fixture mode to the bills-indexer (BILLS_FIXTURE_BATCH) so
the seam test can drive the real writer without AWS.
- Run the bills module in the pr-build backend-tests gate so drift fails CI.
Record the decision in docs/architecture/bills-artifact-contract-epac2304.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scope
The bills SQLite artifact is an implicit contract between two separate Go binaries: the bills-indexer writer (producer,
backend/bills-indexer/internal/adapter/sqlite/writer.go) and the bills serving repository (consumer,backend/bills/internal/adapter/sqlite/repository.go). Nothing fast verified the assembled contract — only the staging smoke did, which cannot catch drift before deploy. The serving repo also masked drift with dynamic column-name fallbacks (columnExpr/firstColumn/…), so as shipped the servedBillVersion'stitle/chamber/published_onwere always empty (the indexer never writes those columns) and the versionlabelsilently fell back tostage.This PR locks that contract:
backend/bills/artifact_seam_test.go,TestBillsArtifactSeam). It drives the real producer binary in a new offline fixture mode to write a realbills.db, then opens that file with the real serving repository and assertsListBills,GetBillDepth, andGetBillVersionDiffreturn the promised columns populated — no NULL fallbacks. The two adapters areinternalto separate Go modules, so (per the issue's guidance) neither imports the other's internals; the only thing shared across the seam is the on-disk SQLite file, exactly as in production.bill_versionscontract. The servedBillVersionis now exactly{id, label, stage, source_url}, wherelabelandstageboth carry the LEGISinfo publication-type name (the indexer has no separate label column) andsource_urlis the indexer'shtml_url. The always-emptytitle,chamber, andpublished_onwere dropped from the domain model andbackend/openapi/openapi.json(schema + examples). The decision is recorded indocs/architecture/bills-artifact-contract-epac2304.md.columnExpr/firstColumn/tableColumns/orderExprhelpers are gone.BILLS_FIXTURE_BATCH) added to the bills-indexer so the seam test can drive the real writer without LEGISinfo or AWS. The deployed pipeline never sets it.billsmodule is now run inpr-build'sbackend-testsjob, so schema drift fails the required gate instead of in staging smoke or production.No runtime response change / no
Release-Note: the dropped version fields were already omitted from responses (always empty,omitempty), and iOS decodes every version field as optional. The served JSON is byte-identical; this is an API-spec + test/refactor change with no user-visible effect.Out of scope (documented follow-up): the served
BillAmendmentover-promises fields the indexer never writes; the consumer now reads only the producer-backedid/source_url(identical to today's production output) with fixed SQL, and the remaining contract trim/enrich is captured in the "Known limitation" section of the architecture note.Bugfix SPEC
Testing notes
go test ./backend/bills/... ./backend/bills-indexer/...(pass),go test -tags=integration ./...for bills (pass),go test ./...for the openapi module (pass),gofmt/go vetclean,actionlinton the workflow (pass).Screenshots
N/A — no UI change.
Related issue