Legend World Vertical Slice — Settlement → Stadium → World Manifest

Status: v2.2 — a second stale reference fixed this session: the flow table's Stage 2 entry still read "Candidate Site Generation → UNOWNED," left over from before LS-SPEC-005 §1.3a's ownership was confirmed. Corrected to cite LS-SPEC-005 §1.3a directly, consistent with the rest of this document. No content or contract change beyond this and the §7 cache-key citation fix (v2.1). Fully reconciled against authoritative LS-SPEC-005 (v1.3), LS-SPEC-006 (v1.5), and DL-SPEC-014 (v1.5). No unresolved ownership conflicts remain.

Role boundary: This document defines what must exist and how it must behave — data shapes, request/response contracts, validation rules, invariants, failure states, and acceptance tests. It contains no code, no database migrations, no UI, and no claims about what already exists in the live Diamond Legend codebase, per explicit instruction. Lovable owns translating this into an actual implementation, reconciled against whatever a future real audit finds.

Authoritative inputs: LS-SPEC-005 (v1.3), LS-SPEC-006 (v1.5), DL-SPEC-014 (v1.5), DL-MASTER (v1.1), DL-DEPENDENCY-MAP.md.

Explicitly does not redesign: Any ownership boundary already established in LS-SPEC-005, LS-SPEC-006, or DL-SPEC-014. Every contract below is a direct, faithful translation of something those documents authoritatively own, made concrete enough to implement without guessing.

Scope: The minimum viable vertical slice — real settlement → candidate sites → owner site selection → stadium footprint → World Manifest request/response → persistent franchise world. Population-agnostic throughout: every contract below uses one schema and one code path regardless of settlement size, per LS-SPEC-005 §0.2/INV-1.

0. Status of the Two Prior Recommendations and the §1.1a Consequence — All Confirmed

• Candidate site generation belongs to LS-SPEC-005 (§1.3a) — confirmed.
• Deterministic world generation is mandatory across the Legend Knowledge / Legend World Engine pipeline (LS-SPEC-005 §5.3/§14 INV-6, LS-SPEC-006 §2.2a/§6.4) — confirmed.
• LS-SPEC-006 §1.1a (Candidate Site Request pass-through) — confirmed as an authoritative architecture decision. The access path is fixed: Diamond Legend / DL-SPEC-014 → LS-SPEC-006 Venue Integration Interface → LS-SPEC-005 Legend Knowledge. LS-SPEC-006 remains only an access gateway — it does not independently generate, rank, filter, reinterpret, or persist candidate sites; LS-SPEC-005 remains sole owner of that logic and data.

1. Vertical Slice Flow, Mapped to Owning Spec

1. Real Settlement Selection        → LS-SPEC-005 (data), DL-SPEC-014 §2.1 (owner-facing decision)
2. Candidate Site Generation         → LS-SPEC-005 §1.3a (authoritative)
3. Owner Site Selection              → DL-SPEC-014 §2 (existing)
4. Stadium Footprint Construction    → DL-SPEC-014 §3 (existing)
5. World Manifest Request/Response   → LS-SPEC-006 §1 (existing)
6. Persistent Franchise World        → LS-SPEC-005 §10 + LS-SPEC-006 §5.3/§8 + DL-SPEC-014 §11 (existing, composed)

2. Stage 1 — Real Settlement Selection

2.1 Contract: Settlement Search

SettlementSearchQuery
  text_query: string                    -- free-text name search
  country_filter: string | null
  region_filter: string | null

SettlementSummary                       -- population-agnostic: identical shape for every settlement
  settlement_id: string
  name: string
  country_name: string
  region_name: string
  coordinates: { value: {lat, lng}, provenance_tier: ProvenanceTier, source_ref: string | null }
  population_current: { value: number | null, provenance_tier: ProvenanceTier, source_ref: string | null, as_of_year: number | null }
  urban_rural_classification: { value: string | null, provenance_tier: ProvenanceTier }

ProvenanceTier is the six-value enum from LS-SPEC-005 §2.1, used identically everywhere in this document — never optional, per LS-SPEC-005 INV-3.

2.2 Validation

• text_query must be non-empty.
• A search returning zero results is not an error state (§8.1) — it means no matching settlement exists yet, which is a normal outcome for an obscure or fictional location, not a failure.

2.3 Population-Agnostic Requirement, Stated as a Contract Constraint

The SettlementSummary shape above is returned identically whether population_current.value is 8,000,000 or 500 or null (a fictional settlement with no population data yet). No field may be conditionally omitted based on population size. This is the literal contract-level enforcement of LS-SPEC-005 §0.2/INV-1 — a compact test for "did we accidentally special-case a big city" is: does this schema ever branch on population? It must not.

2.4 Fictional Settlement Creation

If no matching settlement exists, per LS-SPEC-005 §1.4 a new settlement record may be created with every field's provenance_tier set to fictional (owner-declared) or left for §4's procedural fallback to fill in. This uses the identical SettlementSummary shape — a fictional settlement is not a different type, only different provenance values.

3. Stage 2 — Candidate Site Generation (Authoritative — LS-SPEC-005 §1.3a)

3.0 Ownership and Access Path — Confirmed

Candidate site generation is owned by LS-SPEC-005 (§1.3a). Access is via LS-SPEC-006 §1.1a's pass-through — DL-SPEC-014 sends a CandidateSiteRequest to LS-SPEC-006, which calls LS-SPEC-005 internally and returns the result unmodified, never independently generating, ranking, filtering, reinterpreting, or persisting candidates itself.

3.1 Contract

CandidateSiteRequest              -- what DL-SPEC-014 sends to LS-SPEC-006 (§1.1a)
  settlement_id: string
  venue_type: string              -- opaque, per LS-SPEC-006 §1.2 — "baseball_park" for this slice

SiteCandidate                     -- generated by LS-SPEC-005 §1.3a, passed through unmodified by LS-SPEC-006
  candidate_id: string            -- ephemeral, not yet a persisted Site
  label: string                   -- e.g. "Riverfront", "Downtown-adjacent", "Suburban"
  characteristics: { terrain: ProvenanceValue, waterway_adjacent: boolean, transportation_access: ProvenanceValue }
  provenance_tier: ProvenanceTier  -- the weakest tier among the characteristics informing this candidate

ProvenanceValue is shorthand throughout this document for the {value, provenance_tier, source_ref} triple established in LS-SPEC-005 §2.2.

3.2 Deterministic Generation Rule (Now Mandatory, Not Conditional)

Given identical settlement_id + venue_type, the same ordered list of SiteCandidate records must be produced every time — no randomness, per LS-SPEC-005 §14 INV-6, which is now an authoritative invariant, not a slice-local proposal. Candidates are derived from the settlement's terrain/waterway/transportation ProvenanceValue fields (LS-SPEC-005 §1.2) via a fixed rule set (e.g., "if a waterway exists, offer a riverfront candidate"), not sampled.

3.3 Sparse-Data Fallback

If a settlement has minimal or no terrain/waterway/transportation data (a fictional or under-documented settlement), exactly one generic SiteCandidate (label: "Site", provenance_tier: era_appropriate_procedural) must always be returned — never zero candidates, per LS-SPEC-005 §14 INV-7, now authoritative. A zero-candidate outcome would block franchise creation entirely for the majority of settlements this system is meant to support (small towns with sparse data), which would violate LS-SPEC-005 §0.2's population-agnostic requirement in practice even if not in schema.

4. Stage 3 — Owner Site Selection

4.1 Contract

SiteSelectionRequest
  settlement_id: string
  chosen_candidate_id: string           -- from §3's SiteCandidate list

SiteSelectionResponse
  site_id: string                       -- now a persisted LS-SPEC-005 §1.3 Site record

4.2 Persistence Trigger

Selecting a candidate is the point a Site record is actually created per LS-SPEC-005 §1.3 ("created on demand") — the candidates in §3 are ephemeral proposals; only the chosen one becomes a real, persisted Site.

5. Stage 4 — Stadium Footprint Construction

5.1 Contract, Directly From DL-SPEC-014 §3.1

FieldGeometryInput
  home_plate_orientation: number         -- owner-selectable, degrees
  foul_line_distance_left: number        -- owner-configurable, within bounds (§5.2)
  foul_line_distance_right: number
  center_field_distance: number
  wall_height_by_section: { section_id: string, height: number }[]

FieldGeometryFixed                       -- never owner-configurable, per DL-SPEC-014 §3.1/INV-6
  base_path_distance: 90                 -- feet, fixed by rule
  pitching_distance: 60.5                -- feet, fixed by rule

5.2 Validation Rules

• foul_line_distance_left/right and center_field_distance must fall within a configured min/max bound (bounds themselves are DL-SPEC-014's to define numerically — not specified here, since this document doesn't set baseball-design constants, only the validation contract shape).
• wall_height_by_section must cover the full boundary with no gaps (every section of the fair-territory polygon has a defined height).
• The resulting fair-territory shape must be non-self-intersecting (DL-SPEC-014 §3.2's geometric-validity requirement, made concrete here as a specific, testable check).
• FieldGeometryFixed values are never accepted as input — any request attempting to override them is rejected, not silently ignored (silently ignoring a rule violation is worse than rejecting it, since it could mislead the owner into thinking their input mattered).

5.3 Venue Footprint Derivation

VenueFootprint                          -- the exact LS-SPEC-006 §1.1 payload
  fair_territory_polygon: {lat_offset, lng_offset}[]   -- derived from FieldGeometryInput + FieldGeometryFixed
  orientation_vector: {x, y}             -- derived from home_plate_orientation

Derivation from FieldGeometryInput/FieldGeometryFixed to VenueFootprint must be a pure, deterministic function (LS-SPEC-005 §14 INV-6, extended through this document) — identical geometry input always produces an identical polygon.

6. Stage 5 — World Manifest Request/Response

6.1 Request Contract — Exact VenueWorldRequest Shape

VenueWorldRequest                        -- LS-SPEC-006 §1.1, made field-exact for this slice
  location: settlement_id (string)
  visual_year: integer
  venue_type: "baseball_park"
  site: site_id (string)                 -- from §4's SiteSelectionResponse
  venue_footprint: VenueFootprint         -- from §5.3
  world_mode: "frozen_era" | "living_world"

6.2 Response Contract — World Manifest, Fields Relevant to This Slice

WorldManifest
  settlement_id: string
  visual_year: integer
  terrain: ProvenanceValue
  climate: ProvenanceValue
  environment_zones: ZoneAssignment[]
  architecture_families: { family_id: string, provenance_tier: ProvenanceTier }[]
  venue_orientation: {x, y}
  horizon_characteristics: ProvenanceValue
  provenance_summary: { overall_confidence: ProvenanceTier, low_confidence_fields: string[] }

ZoneAssignment
  zone_type: string                      -- LS-SPEC-006 §3.1 taxonomy
  placement: {lat_offset, lng_offset}
  content_asset_family_ids: string[]
  provenance_tier: ProvenanceTier

6.3 Determinism (Authoritative — LS-SPEC-006 §6.4)

Identical VenueWorldRequest must always produce a byte-identical WorldManifest — this is the specific instance of LS-SPEC-006 §6.4's general determinism guarantee that makes §9's acceptance tests possible as exact-match assertions rather than approximate ones.

6.4 Era-Integrity Enforcement, Restated as a Response-Time Guarantee

No content_asset_family_ids entry in any ZoneAssignment, and no entry in architecture_families, may violate LS-SPEC-005 §3.3's era-integrity rule for the given settlement_id/visual_year combination — this is LS-SPEC-006's existing responsibility (§3.3), restated here as a testable postcondition on the response rather than a new rule.

7. Stage 6 — Persistent Franchise World

7.1 What Persists, and Where — Composed From Existing Ownership

7.2 Referential Integrity Contract

• A stadiums record's settlement_id/site_id must reference an existing, persisted LS-SPEC-005 record — never a dangling reference, never an inline copy of settlement data (this document does not permit denormalizing settlement facts onto the stadium record; DL-SPEC-014 already reads them fresh through LS-SPEC-006 per that spec's own "one door" rule, LS-SPEC-006 §0.2).
• A cached WorldManifest is keyed by (settlement_id, visual_year, site_id, orientation_bucket) — corrected during the final stadium/world audit to match LS-SPEC-006 §8.2's confirmed cache-key fix (orientation_bucket added in LS-SPEC-006 v1.3, this document's citation of the 3-part key predated that fix). A franchise's stadium record references this key, not a private copy of the manifest.

7.3 What "Persistent Franchise World" Means Operationally

Once this slice completes, re-fetching the franchise's world (e.g., on app reload) must reproduce an identical presentation without re-running generation — the persisted stadiums record plus a cache lookup against the (settlement_id, visual_year, site_id, orientation_bucket) key is sufficient; nothing about this stage requires re-deriving the World Manifest from scratch.

8. Failure States

9. Acceptance Tests

Applied to this specific vertical slice's exact stages, using the seven test cases already established in LS-SPEC-006 §10.

9.1 Determinism-Specific Tests (Now Mandatory, Not Conditional)

• Running the identical VenueWorldRequest twice must produce byte-identical WorldManifest responses.
• Running §3's candidate site generation twice for the identical settlement must produce an identical, identically-ordered SiteCandidate[].

9.2 Population-Agnosticism Test

• Run the full six-stage pipeline for Cleveland (population millions) and the fictional 5,000-person town side by side, asserting every response schema at every stage is structurally identical between the two runs — only field values and provenance_tier values may differ, never the shape.

10. Invariants

• INV-1: No contract in this document's schemas may vary in shape based on settlement population — only in field values and provenance tiers (restates LS-SPEC-005 INV-1 at the contract level).
• INV-2: SiteCandidate[] (§3) is never empty for any valid settlement_id.
• INV-3: FieldGeometryFixed values (§5.1) are never accepted as owner input under any request.
• INV-4: Every WorldManifest field traceable to LS-SPEC-005 carries its provenance_tier — no bare values reach this slice's response (restates LS-SPEC-005 INV-3).
• INV-5 (authoritative, not conditional): Identical inputs to any generation step in this slice (candidate sites, footprint derivation, World Manifest) produce identical outputs, always, per LS-SPEC-005 §14 INV-6 and LS-SPEC-006 §2.2a/§6.4.
• INV-6: A stadiums record's location references are never denormalized copies — always live references resolved through LS-SPEC-006, per §7.2.
• INV-7: No era-integrity violation (LS-SPEC-005 §3.3) may appear in a returned WorldManifest under any input.

11. Explicit Non-Goals

This document does not: redefine any LS-SPEC-005/006/014 ownership; specify UI layout or visual design; specify actual database types/indexes/migration syntax (those are Lovable's implementation decisions, constrained by but not dictated by the field-level contracts above); address Living World mode's time-progression mechanics (LS-SPEC-006 §4.2) beyond what's needed for initial franchise creation; address multiplayer world consistency (LS-SPEC-006 §7) — this slice is single-franchise-creation scoped.

12. Recommended Next Steps

1. This document is now stable and reconciled — no ownership items remain pending. It's ready to serve as the reference contract for the next engineering task on this system.
2. Once a real Diamond Legend codebase audit is possible, reconcile this document's contracts against whatever already exists — this document was written without that audit, on explicit instruction to proceed as logic/architecture only. Not performed this session, per direct instruction not to attempt Supabase/Lovable access.
3. This document's six stages are a reasonable unit for phased delivery, but phasing/sequencing implementation work is an engineering-management decision for whoever plans the Lovable build, not something this document prescribes.