Skip to content

[EPAC-2304]: Lock bills SQLite artifact schema with a producer-to-consumer seam test#823

Merged
riddim-developer-bot[bot] merged 1 commit into
mainfrom
symphony/epac-2304-lock-bills-sqlite-artifact-schema-with-a-produce
Jun 14, 2026
Merged

[EPAC-2304]: Lock bills SQLite artifact schema with a producer-to-consumer seam test#823
riddim-developer-bot[bot] merged 1 commit into
mainfrom
symphony/epac-2304-lock-bills-sqlite-artifact-schema-with-a-produce

Conversation

@riddim-developer-bot

Copy link
Copy Markdown
Contributor

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 served BillVersion's title/chamber/published_on were always empty (the indexer never writes those columns) and the version label silently fell back to stage.

This PR locks that contract:

  • Seam test (backend/bills/artifact_seam_test.go, TestBillsArtifactSeam). It drives the real producer binary in a new offline fixture mode to write a real bills.db, then opens that file with the real serving repository and asserts ListBills, GetBillDepth, and GetBillVersionDiff return the promised columns populated — no NULL fallbacks. The two adapters are internal to 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.
  • Single-sourced bill_versions contract. The served BillVersion is now exactly {id, label, stage, source_url}, where label and stage both carry the LEGISinfo publication-type name (the indexer has no separate label column) and source_url is the indexer's html_url. The always-empty title, chamber, and published_on were dropped from the domain model and backend/openapi/openapi.json (schema + examples). The decision is recorded in docs/architecture/bills-artifact-contract-epac2304.md.
  • Dead fallbacks removed. The version and amendment reads now use fixed SQL against the producer's real columns; the columnExpr/firstColumn/tableColumns/orderExpr helpers are gone.
  • Offline producer mode (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.
  • CI gate. The bills module is now run in pr-build's backend-tests job, 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 BillAmendment over-promises fields the indexer never writes; the consumer now reads only the producer-backed id/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

  • Spec: N/A — architecture/test hardening, not a bug fix.
  • Trace ID: N/A

Testing notes

  • Automated tests run: go test ./backend/bills/... ./backend/bills-indexer/... (pass), go test -tags=integration ./... for bills (pass), go test ./... for the openapi module (pass), gofmt/go vet clean, actionlint on the workflow (pass).
  • Manual verification: N/A — backend-only change, no UI surface. The seam test is the verification; it builds a real artifact and reads it back through the serving repository.

Screenshots

N/A — no UI change.

Related issue

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.
@riddim-developer-bot riddim-developer-bot Bot enabled auto-merge (squash) June 14, 2026 20:21
@riddim-developer-bot riddim-developer-bot Bot merged commit 48d67e2 into main Jun 14, 2026
62 checks passed
@riddim-developer-bot riddim-developer-bot Bot deleted the symphony/epac-2304-lock-bills-sqlite-artifact-schema-with-a-produce branch June 14, 2026 20:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants