feat(core): add Venue entity, storage, migration v14 (PR A — base of stack)

[ibanner56]

PR A — Venue entity core (base of a stacked set)

Adds a first-class Venue entity to CallersCompendium so many programs can be held at the same venue, with address/contact/schedule edited in one place. This is Phase 1 of the venue rollout and the base of a stacked PR set:

• PR A (this one): core model, storage, schema migration, repository, serialization, tests.
• PR B (later): settings toggle + editor/picker UI.
• PR C (later): on-screen display labels, export wiring, and docs.

It mirrors the existing PublishedSource vertical slice end-to-end (model → table → migration → repository → serialization → tests).

Schema version note: originally authored as a 12 → 13 migration, this was rebased to 13 → 14 because #455 landed its own schema v13 (a dance_links performance index) on main first. The venue migration now applies additively on top of that as v14; the implementation, onUpgrade ladder, migration test, and fixtures all reflect v14.

What's included

• model/venue.dart — @immutable Venue: required id + name, 20 nullable normalized strings (address1/2, city, stateProv, country, postalCode, plus4, website, sponsor, eventName, time, genericSchedule, price, notes, contact1/2 name/phone/email). _normalize (empty/whitespace → null), copyWith with clear* flags, ==/hashCode, and a computed displayName getter (the app-side equivalent of CC's VenueDisplay_c — computed, never stored). FileMaker plumbing (zc_*/zi_*, SiteID, numeric zk_VenueID) is dropped; the app mints its own uuid PK.
• tables.dart — new Venues table (VenueRow) + a nullable programs.venue_id soft reference (no DB foreign key).
• database.dart — schema bump 13 → 14 with a documented, purely-additive onUpgrade step (createTable(venues) + addColumn(programs.venueId) + a programs_venue_id lookup index); no data back-fill and no derived-index rebuild (venues don't feed dance_fts/dance_figures).
• venue_repository.dart — upsert / getById / listAll (by name, case-insensitive) / delete guarded (transactional COUNT, index-backed) to throw while any program still references the venue. Registered in the repositories facade.
• program.dart / program_repository.dart — venueId carried through the model, copyWith (venueId + clearVenueId), duplicate(), equality, and persistence. A non-null venueId is validated against an existing venue inside the write transaction (single writes) or a preloaded id set (batch restore/import), so the repo can't persist a dangling reference.
• Serialization (archive_codec.dart / archive_service.dart / imports/compendium_archive_import.dart) — programs export/import venueId; bundles embed a top-level venues array (omitted when empty, tolerated when absent for older bundles). Both the full-DB backup/restore path and the community-import path upsert venues before programs (with id remapping on import) and safely null a dangling venueId (venue absent from both bundle and DB) rather than leaving it orphaned. A venue-bearing archive is stamped envelope v2 so pre-venue readers surface the "newer than supported" warning instead of silently dropping venue data; venue-less archives stay v1-compatible.

Security (OWASP)

archive_codec import treats shared/community bundles as untrusted: the venues array must be a list of objects; every field is type-checked; missing/extra fields are tolerated; malformed entries are rejected per-entity (recorded as a structured error, the rest still load) rather than crashing the import. A blank venue name is rejected as a FormatException so it's caught by the per-entity decode guard instead of escaping as an uncaught Error. Within a single crafted bundle, duplicate venue ids collapse to one (last-seen wins), mirroring duplicate-program handling.

Tests (Phase-5, scoped to the above)

• test/model/venue_test.dart — validation, normalize, copyWith clear-flags, displayName.
• test/storage/venue_repository_test.dart — CRUD + delete-guard.
• Migration: checked-in test/storage/fixtures/v13.sqlite (+ re-runnable generate_v13_fixture.dart) and a v13 → v14 group in migration_test.dart asserting the venues table, programs.venue_id column, and programs_venue_id index appear and user_version == 14 (plus a fresh-schema check that the index exists on onCreate).
• Serialization/import round-trip: a program with venueId + an embedded venue survives export→import (both backup/restore and community-import paths); a legacy bundle with no venues array still imports cleanly; a dangling venueId is nulled; undo removes imported venues (guarded); malformed/oversized/mistyped venue input is rejected per-entity.

Release note

The schema bump 13 → 14 is additive and rides a MINOR release. No UI writes venueId yet (that's Phase 3); the codec and tests exercise it programmatically. Follow-ups tracked in #456 (share-bundle venue gathering + re-import dedupe key).

Verification

build_runner regen committed; dart analyze clean (core + app); targeted + full compendium_core suite green; CI schema-migration gate satisfied (13 → 14 with fixture/test evidence).

Please do not merge — holding for human review.

[Copilot]

Pull request overview

Introduces the core Venue entity and integrates it with programs, persistence, migrations, and archive serialization.

Changes:

• Adds Venue modeling, storage, repository APIs, and program references.
• Migrates databases from schema v12 to v13.
• Adds archive import/export support and comprehensive tests.

Reviewed changes

Copilot reviewed 17 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/compendium_core/lib/compendium_core.dart	Exports Venue APIs.
packages/compendium_core/lib/src/model/program.dart	Adds venueId support.
packages/compendium_core/lib/src/model/venue.dart	Defines the Venue model.
packages/compendium_core/lib/src/serialization/archive_codec.dart	Serializes venues and links.
packages/compendium_core/lib/src/serialization/archive_service.dart	Exports and restores venues.
packages/compendium_core/lib/src/serialization/compendium_archive.dart	Adds venues to archives.
packages/compendium_core/lib/src/storage/database.dart	Adds schema-v13 migration.
packages/compendium_core/lib/src/storage/database.g.dart	Regenerates Drift bindings.
packages/compendium_core/lib/src/storage/repositories/program_repository.dart	Persists program venue links.
packages/compendium_core/lib/src/storage/repositories/repositories.dart	Registers VenueRepository.
packages/compendium_core/lib/src/storage/repositories/venue_repository.dart	Implements Venue CRUD.
packages/compendium_core/lib/src/storage/tables.dart	Defines venue storage schema.
packages/compendium_core/test/model/venue_test.dart	Tests Venue behavior.
packages/compendium_core/test/serialization/archive_codec_test.dart	Tests venue JSON handling.
packages/compendium_core/test/serialization/archive_service_test.dart	Tests venue restoration.
packages/compendium_core/test/storage/fixtures/generate_v12_fixture.dart	Generates the migration fixture.
packages/compendium_core/test/storage/fixtures/v12.sqlite	Provides a v12 database fixture.
packages/compendium_core/test/storage/migration_test.dart	Tests v12-to-v13 migration.
packages/compendium_core/test/storage/venue_repository_test.dart	Tests Venue persistence and deletion.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 24 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:175

• knownVenueIds is caller-supplied through the public create/update API, so passing {'ghost'} currently bypasses the only database existence check and persists a dangling soft reference. A previously valid set can likewise become stale outside the restore transaction. Keep the optimization behind a repository-owned, transaction-scoped batch API (or otherwise make the validated set unforgeable) so public writes cannot opt out of referential integrity.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)
          : await (_db.select(_db.venues)

[Copilot]

Pull request overview

Copilot reviewed 24 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:174

• knownVenueIds bypasses the in-transaction existence check, so the soft-reference guarantee is no longer atomic on the bulk paths. For example, after the importer builds this set, VenueRepository.delete can delete an as-yet-unreferenced venue before a later program write; this branch still returns true and persists a dangling venue_id. Any caller can also pass a set containing an ID that never existed. Keep the preload and all program writes in one database transaction, or expose a repository-owned bulk operation that validates the snapshot within the same transaction instead of accepting an arbitrary public set.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)

[Copilot]

Pull request overview

Copilot reviewed 24 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:175

• knownVenueIds is a caller-controlled existence assertion: create(programWithVenue('ghost'), knownVenueIds: {'ghost'}) now persists a dangling reference even when venues has no such row. It can also become stale in CompendiumArchiveImporter, whose venue inserts and program writes are separate transactions, if a guarded delete interleaves between them. Keep the preload and writes inside one repository-owned transaction/bulk API rather than letting the public create/update methods bypass the database check with an arbitrary set.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)
          : await (_db.select(_db.venues)

[Copilot]

Pull request overview

Copilot reviewed 24 out of 26 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:174

• knownVenueIds is caller-controlled but is treated as proof that the row exists, so create(programWithGhost, knownVenueIds: {'ghost'}) persists a dangling reference and bypasses the repository's advertised integrity guarantee. The community importer also computes this set outside an enclosing transaction, allowing a concurrent venue delete between minting and program writes. Keep this optimization behind a repository-owned bulk operation that loads/validates the IDs and performs all writes in one transaction, rather than exposing an unchecked set on each public write.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)

[Copilot]

Pull request overview

Copilot reviewed 25 out of 27 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:175

• knownVenueIds bypasses the in-transaction existence read, but a preloaded set does not lock those rows. CompendiumArchiveImporter.commit inserts venues and programs in separate transactions, so VenueRepository.delete can remove a newly inserted venue after this set is built and before a program write; this branch then accepts the stale ID and persists a dangling soft reference. The same public parameter also lets any caller provide IDs that never existed. Please keep the venue/program bulk phase in one database transaction (as ArchiveRestorer does), or use a batch API whose snapshot and writes share that transaction rather than trusting an arbitrary set.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)
          : await (_db.select(_db.venues)

[Copilot]

Pull request overview

Copilot reviewed 25 out of 27 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:174

• The bulk fast path no longer participates in the database existence check. CompendiumArchiveImporter commits each venue before later program writes, so a concurrent guarded delete can remove a just-added venue while it has no references; this stale set still returns true and the program is then persisted with a dangling venueId. A caller can also supply an arbitrary set directly. Keep the venue preload and all dependent writes in one database transaction (or use a restrictive FK/batch repository API) so the advertised app-layer integrity guarantee remains atomic.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)

[Copilot]

Pull request overview

Copilot reviewed 26 out of 29 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:147

• knownVenueIds bypasses the repository's existence check rather than merely batching it: any caller can pass {'ghost'} and persist venueId == 'ghost' even when no such row exists. Since ProgramRepository is exported, this invalidates the documented app-layer integrity guarantee. Keep the trusted ID snapshot inside a repository-owned bulk operation/transaction instead of exposing it on the public single-row API.

  Future<void> create(Program program, {Set<String>? knownVenueIds}) =>
      _upsert(program, knownVenueIds: knownVenueIds);

  /// Updates an existing program. See [create] for [knownVenueIds].
  Future<void> update(Program program, {Set<String>? knownVenueIds}) =>
      _upsert(program, knownVenueIds: knownVenueIds);

[Copilot]

Pull request overview

Copilot reviewed 26 out of 29 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

packages/compendium_core/lib/src/storage/repositories/program_repository.dart:174

• knownVenueIds is a public caller-supplied set, so it bypasses the repository's existence check rather than optimizing it: create(program, knownVenueIds: {'ghost'}) persists a dangling soft reference. A preloaded set can also become stale unless its load and all writes share one transaction (the community importer does not). Keep this bypass internal to a repository-owned batch operation that preloads and writes in one transaction, or enforce the relationship with a database constraint; otherwise the documented app-layer integrity guarantee is not upheld.

      final venueExists = knownVenueIds != null
          ? knownVenueIds.contains(venueId)

packages/compendium_core/lib/src/imports/compendium_archive_import.dart:390

• This ignores the archive's declared wire version. A valid v2 archive with an empty venues list and null venueId values is classified as v1 because requiredSchemaVersion only inspects content; on a provenance-matched re-import, the receiver's old venue link is then preserved instead of honoring v2's explicit null. Include archive.schemaVersion >= archiveSchemaVersionVenues in this capability check (while retaining the content check for programmatically constructed archives).

      final archiveCarriesVenueLinks =
          requiredSchemaVersion(archive) >= archiveSchemaVersionVenues;