LS-SPEC-005 — Legend Knowledge (World & Era Intelligence Layer)

Status: Draft v1.2 — candidate site generation ownership (§1.3a) and mandatory determinism (§5.3, §14 INV-6) are authoritative. LS-SPEC-006 §1.1a's access-path resolution is now also confirmed and authoritative — no pending items remain from this decision. Governed by: LS-PLATFORM-ARCHITECTURE.md Depends on: an external Authentication system (consumed, not owned, for attributing community contributions), no game-specific or sport-specific system

Owns: The location hierarchy and its data fields, candidate site generation (§1.3a, authoritative as of v1.1), the visual-year/era system and era-integrity rules, the provenance/confidence model, the Build-My-Hometown reconstruction workflow, procedural-generation-when-data-is-insufficient rules (now formally deterministic, §5.3), community environment sharing/versioning/moderation, the historical-data curation pipeline, and licensing/copyright safeguards for historical reference material.

Explicitly does not own: Any sport or venue concept — no ballparks, football fields, or race tracks are defined here (owned by LS-SPEC-006 and each game's own venue spec). 3D asset construction, rendering, or UE5-specific detail (LS-SPEC-006 translates Legend Knowledge output into a World Manifest; this document only produces the truth that manifest is built from). Any single game's franchise/financial/attendance logic (each game's own specs, e.g., Diamond Legend's DL-SPEC-008).

Governing principle: Legend Knowledge tells the truth, marks its confidence, and never pretends otherwise. Every fact this system produces — a coordinate, a population figure, an architectural style, a claim about what existed in a place in a given year — carries an explicit provenance tier. A generated approximation presented without its confidence level is a defect, not an acceptable simplification.

0. Foundational Architecture Decisions

0.1 Game-Agnostic and Sport-Agnostic

This is a stronger constraint than the game-agnosticism established elsewhere in this project (LS-SPEC-001 through 004): Legend Knowledge has no concept of "venue," "franchise," or "team" at all. It answers "what did this place look like at this time," full stop — a question with the same answer whether it's eventually consumed for a ballpark, a football stadium, or something that isn't a sports venue at all. LS-SPEC-006 is where sport-adjacent concepts first appear.

0.2 No Population Floor, No Special-Cased Cities

Per your explicit requirement: a hierarchy entry for a town of 500 people is structurally identical to one for a city of 8 million — same schema, same fields (many simply sparser or lower-confidence for the smaller place). If an implementation requires a hardcoded branch for "if city == Cleveland," that implementation has failed this specification. This is elevated to a formal invariant (§14, INV-1).

0.3 Confidence Is Not an Afterthought Field — It's the Data Model's Backbone

Rather than location/era data having an optional "confidence" tag bolted on, every meaningful fact in this system is stored as a (value, provenance_tier, source_ref) triple (§2), not a bare value. This is a deliberate structural choice: it makes it impossible to accidentally query a fact without also seeing its confidence, rather than relying on every consumer to remember to check.

1. Location Hierarchy

1.1 Structure

Country → Region (State/Province) → SubRegion (County/Prefecture/District, optional) → Settlement (City/Town/Village) → Site

SubRegion is optional in the chain — some countries' administrative structure doesn't need it, some settlements are recorded without one when data is sparse (e.g., a Community Reconstruction town, §5). The hierarchy degrades gracefully rather than requiring every level to be populated.

1.2 Settlement Record

settlements
  id (pk)
  name
  country_id / region_id / subregion_id (fk, subregion nullable)
  coordinates (value, provenance_tier, source_ref)
  population_current (value, provenance_tier, source_ref, as_of_year)
  population_historical (array of {year, value, provenance_tier, source_ref} — a time series, not a single field, since population changes and this system cares about specific years)
  climate_profile (value, provenance_tier, source_ref)
  terrain (value, provenance_tier, source_ref — plains/hills/mountains/coastal/river-valley, etc.)
  waterways (array of {type: river/lake/coast, name, provenance_tier})
  regional_architecture (value, provenance_tier, source_ref — a reference into §3's era-tagged architecture family taxonomy)
  transportation_profile (value, provenance_tier, source_ref — rail access, road era, port access, etc.)
  economic_character (value, provenance_tier, source_ref — agricultural/industrial/commercial/mixed, and dominant industries where known)
  urban_rural_classification (value, provenance_tier, source_ref)
  regional_sports_interest (value, provenance_tier, source_ref — qualitative, informs but does not own any game's attendance modeling)
  catchment_population (derived — surrounding-area population within a configurable radius, computed from this settlement plus neighboring settlements' population time series)

1.3 Site Record

A Site is a specific point or parcel within a Settlement — where a venue would eventually sit (per LS-SPEC-006). A single, specific Site is created on demand only once a candidate has been chosen (§1.3a) — it is not itself the browsable object; §1.3a's candidates are.

1.3a Candidate Site Generation (Authoritative — Approved Studio Decision)

This section resolves what was flagged as an ownership gap in the LEGEND-WORLD-VERTICAL-SLICE-001 vertical-slice review. Legend Knowledge owns candidate site generation. Before a specific Site record is created, this spec generates a deterministic list of candidate site options for a given settlement — e.g., "riverfront," "downtown-adjacent," "suburban" — derived from that settlement's terrain, waterway, and transportation ProvenanceValue fields (§1.2), never sampled or randomized.

CandidateSiteRequest
  settlement_id: string
  venue_type: string        -- opaque, passed through from whatever game is asking

SiteCandidate
  candidate_id: string      -- ephemeral, not yet a persisted Site
  label: string
  characteristics: { terrain: ProvenanceValue, waterway_adjacent: boolean, transportation_access: ProvenanceValue }
  provenance_tier: ProvenanceTier   -- the weakest tier among the informing characteristics

Guaranteed non-empty result: every settlement, regardless of data richness, returns at least one candidate — a settlement with minimal terrain/waterway/transportation data returns exactly one generic candidate (label: "Site", provenance_tier: era_appropriate_procedural) rather than an empty list. This is required, not optional: an empty result would silently break franchise creation for exactly the sparse, small-settlement cases this system exists to support, which would violate §0.2's population-agnostic requirement in practice even though the schema itself never excludes small settlements.

Access path — this spec is never called directly by a game. Per LS-SPEC-006 §0.2's "one door" principle, a consuming game (Diamond Legend, via DL-SPEC-014) never calls this API directly. LS-SPEC-006 exposes a Candidate Site Request as part of its own Venue Integration Interface and calls this API internally on the game's behalf — see LS-SPEC-006 §1.1a. This spec's ownership is of the generation logic and data, not of the access path a game uses to reach it.

Selecting one candidate is what triggers actual Site record creation (§1.3) — the candidate itself remains ephemeral until chosen.

1.4 Fictional Locations

A fictional settlement (your "town of 5,000 in South Dakota" example, if not a real town) is a first-class settlements row with every field's provenance_tier set to fictional or era_appropriate_procedural (§2) rather than a structurally different kind of record — this is what makes "no special-casing" (§0.2, INV-1) actually achievable: fictional and real places share one schema, differing only in their data's confidence tier, not their shape.

2. Provenance and Confidence Model

2.1 The Six Tiers

2.2 Every Fact Carries Its Tier

As established in §0.3 — no consumer of Legend Knowledge (including LS-SPEC-006) can retrieve a value without also retrieving its tier and, where applicable, a source_ref pointing to what grounded it.

2.3 Transparency Requirement

Per your explicit instruction: if sufficient historical evidence doesn't exist for something a player is asking about, the system tells the player that plainly and offers a historically plausible interpretation tagged accordingly — it does not silently fill the gap and present the result as Verified Historical. This is enforced structurally (§2.2's mandatory tier field), not just as a UI convention that could be skipped.

3. Visual Year and Era System

3.1 Visual Year, Not a Generic Decade Theme

A franchise's environment is generated for an exact year (1948, not "the 1940s"), per your requirement. Every era-governed asset family (§3.2) carries an introduction year (and, where applicable, an obsolescence/decline year), not a bucketed decade tag.

3.2 Era-Governed Categories

Architecture, skylines, houses, factories, farms, streets, automobiles, trains/streetcars, public transportation, streetlights, utility infrastructure, advertisements, storefronts, clothing, construction materials, stadium/venue technology, scoreboards, lighting, parking, surrounding development — each category has its own asset-family taxonomy, each family tagged with an introduction era and (optionally) a decline/obsolescence era, stored as configuration (per this project's established data/engine separation discipline), not hardcoded per-category logic.

3.3 The Era Integrity Rule

An asset family cannot be selected for a given Visual Year if that year falls before the family's introduction era, unless the location's mode is explicitly set to an alternate/fantasy setting (which suspends this check entirely for that location, not partially). This is Invariant §14 INV-2 — a hard rule, not a soft preference the generation logic can override for convenience.

3.4 Regional Era Variation — The Location × Era Interaction

This is the requirement your own example (Tokyo 1948 ≠ Cleveland 1948) makes explicit, and it's the single most important design constraint in this section. Era-governed asset families are not globally available the moment they're "invented" — each family's availability is itself scoped per region (or per country, where regional granularity isn't warranted), not just per year:

asset_family_availability
  asset_family_id (fk)
  region_scope (a country, a region, or 'global' for genuinely universal technologies)
  introduction_year (value, provenance_tier, source_ref)
  decline_year (nullable, same structure)

A technology or architectural style available in the US Midwest by 1948 may not have reached postwar Tokyo by the same date, and vice versa — this table is what prevents the two locations from drawing on an identical asset pool for the same Visual Year. Building this as a single global era table, then applying it uniformly worldwide, would violate this requirement even though it would technically "work" for any single location tested in isolation — this is exactly the kind of failure mode your Cleveland-special-casing warning (§0.2) is guarding against in a different form.

4. Build My Hometown — Reconstruction Workflow

4.1 Input Types

Historical photographs, postcards, maps, descriptions, landmark names, approximate landmark locations, memories/local knowledge, public-domain historical references — accepted per your list, as a submission attached to a Settlement (or a new Settlement, if reconstructing a place not yet in the hierarchy).

4.2 Extraction, Not Reproduction — the Copyright Safeguard

This is a hard architectural boundary, not a policy note. The system extracts structured characteristics from a submitted reference — architectural style, building scale, landmark type and approximate location, industrial character, downtown layout, neighborhood pattern, presence of railroads/water towers/churches/grain elevators/factories, visible horizon/skyline character — and stores those extracted characteristics, tagged Community Reconstruction (§2.1). The original submitted image itself is never stored as, or converted into, a game texture or rendered asset. This mirrors the same extraction-not-reproduction discipline already required of this assistant's own copyright handling, applied here as a system architecture requirement rather than a per-response judgment call.

4.3 Small-Town Skyline

Per your explicit note: for a small settlement, "skyline" means the recognizable horizon and landmark silhouette (a water tower, a grain elevator, a church spire, a tree line), not a downtown skyscraper cluster — the extraction model (§4.2) treats horizon/landmark characteristics as a first-class output regardless of settlement size, not a scaled-down version of a big-city skyline concept.

4.4 Output

A Build My Hometown submission produces (or updates) a Settlement record with Community Reconstruction-tagged fields — ready for §7's community-sharing workflow, and consumable by LS-SPEC-006 exactly like any other provenance tier, since consumers always check the tier (§2.2) rather than assuming a fixed confidence level.

5. Procedural Generation — When Data Is Insufficient

5.1 When It Fires

For any Settlement/Visual Year combination where Verified Historical or Historically Grounded data doesn't cover a needed field, Legend Knowledge generates an Era-Appropriate Procedural value instead — drawing on §3's asset-family/era/region tables to produce something plausible for that location and year, never an arbitrary global default.

5.2 Transparency, Restated From §2.3

The generated result is tagged accordingly and the gap is surfaced to the player (per §2.3) — procedural generation is a legitimate, expected, load-bearing part of this system (most of the world's settlements will never have rich verified data), not a fallback to be hidden.

5.3 Determinism (Authoritative — Approved Studio Decision)

Procedural generation is deterministic — identical (settlement_id, visual_year, field) inputs always produce identical output. No runtime randomness is used anywhere in this process. This does not mean generation is monotonous or that every under-documented settlement looks identical: variation across different settlements/years is achieved through a fixed, reproducible derivation from the input identifiers themselves (e.g., a deterministic hash of settlement_id + visual_year selecting among era-appropriate options), not through true randomness. The distinction matters — "deterministic" and "varied" are not in tension; "deterministic" and "random" are. See §14 INV-6 for the formal statement, and LS-SPEC-006 §2.2a/§6.3 for how this extends through World Manifest generation.

6. Community Environments — Sharing, Versioning, Moderation

6.1 Sharing Model

A player's completed hometown reconstruction (§4) or fully custom environment profile may be published as a shareable template other players can use as a starting point for their own franchise's location.

6.2 Versioning

Every published community environment is versioned on edit, not overwritten — the same append-only discipline used throughout this project (DL-SPEC-003's "never delete," LS-SPEC-003's content versioning). A franchise that adopted an earlier version of a shared environment is not silently migrated to a later edit without an explicit action.

6.3 Moderation and Trust & Safety

Not owned here — consumed. LS-SPEC-002 already owns reporting, moderation, and trust & safety infrastructure (LS-SPEC-002 §9). A published community environment is moderatable content in exactly the shape LS-SPEC-002 already handles; this document does not build a second moderation system. The only thing owned locally is tagging shared environments with the appropriate Community Reconstruction/Player Interpretation provenance so they remain clearly distinguishable from Verified Historical data at every level of the hierarchy — never silently blended in as if equally authoritative.

7. Historical Data Curation Pipeline (Gap Identified — Not in Original Scope List)

Your list covers how players contribute data (§4) but not how Legend Knowledge's own Verified Historical / Historically Grounded baseline data actually gets in — the flagship-city seed data, era-technology introduction tables, and so on. This needs an explicit curation pipeline, distinct from player submission:

• A defined process for adding/updating Verified Historical entries (source citation required, source_ref populated, reviewed before promotion from a staging area to live data).
• A distinction between this curated pipeline and §4's player-submitted reconstruction — the former is how the studio's own baseline knowledge grows; the latter is how players fill gaps the studio hasn't (and likely never will, for most small settlements) covered.
• Without this, "Verified Historical" risks becoming a tier with no defined path to actually populate it at scale — worth resolving before implementation, not left implicit.

8. Sensitive History (Gap Identified)

Some Settlement/Visual Year combinations intersect real historical hardship — wartime periods, segregation-era United States, and similar. This system should handle such periods factually and respectfully: accurate regarding what existed (architecture, infrastructure, demographics as historically documented) without either sanitizing away difficult history or treating it as spectacle. This is a content-handling principle to carry into implementation and any AI-assisted generation (§4 of LS-SPEC-006), not a reason to exclude any real place or era from the system.

9. Legal and Licensing Safeguards

9.1 Photograph/Reference Copyright — Restated From §4.2

The core safeguard is architectural (§4.2): extraction, never reproduction.

9.2 Real Brand and Trademark Avoidance (Gap Identified)

Beyond photo copyright, a generated 1948 Cleveland storefront or billboard must not reproduce real, trademarked brand names or logos, even though the fact that commercial advertising existed in that era/place is Historically Grounded. Storefront/advertisement asset families (§3.2) should use era-appropriate but genuinely generic or fictional branding, the same principle DL-SPEC-017 §3.2 already applies to cosmetics never touching real IP, extended here to environmental generation.

9.3 Real People

Legend Knowledge stores facts about places, not profiles of real named individuals — population figures, architectural facts, and economic data are appropriate; the system has no reason to and should not generate content depicting specific real historical people.

10. Persistence and Versioning

Settlement records, once created, follow the same "never delete, only append/version" discipline as every other part of this project. A settlement's population-historical time series, once a data point is added, is never edited in place — corrections are new, dated entries superseding old ones, with the correction itself traceable (consistent with the append-only ledger pattern used since DL-SPEC-003).

11. APIs

12. Cross-Spec Consistency Notes

• LS-SPEC-006 is this document's sole consumer at the platform tier — no game should call Legend Knowledge's APIs directly, the same "consume through the layer above you" discipline established since DL-SPEC-013's Game Adapter pattern. §1.3a's candidate site generation is no exception — LS-SPEC-006 must proxy it, not expose it, per the fix flagged in §12.1.
• §6.3's reuse of LS-SPEC-002's moderation infrastructure should be confirmed jointly once both specs are further along, the same kind of check flagged for LS-SPEC-003's asset-library boundary with LS-SPEC-001.
• §4.2's extraction-not-reproduction principle is worth stating explicitly in any future AI-assisted generation tooling spec (LS-SPEC-006 §2.3) as well, not just here, since that's where a submitted photograph would actually be processed.

12.1 Access Path — Confirmed (Formerly Pending)

Candidate site generation (§1.3a) is accessed exclusively via LS-SPEC-006 §1.1a's pass-through, now confirmed as an authoritative architecture decision. LS-SPEC-006 acts only as an access gateway — it does not independently generate, rank, filter, reinterpret, or persist candidate sites. This spec remains the sole owner of the generation logic, the data, and the guaranteed-non-empty behavior.

13. Recommended Next Steps

1. Design the exact asset-family taxonomy and region-scoping granularity for §3.4 — this document establishes the shape of that data (region-scoped introduction years) but not its actual content, which is a substantial content-curation project in its own right.
2. Stand up §7's curation pipeline design before attempting to seed any flagship-city data, so the first real data entered has a defined, citable process behind it rather than being entered ad hoc.
3. Confirm §6.3's shared-infrastructure assumption with LS-SPEC-002 directly.

14. Acceptance Invariants

• INV-1: No implementation may contain settlement-specific special-case logic (e.g., a hardcoded branch for a specific city name). All settlements, real or fictional, of any population, are represented and processed through the identical schema and logic path.
• INV-2: No era-governed asset family may be selectable for a Settlement/Visual Year combination earlier than that family's region-scoped introduction year, unless that location is explicitly in an alternate/fantasy mode.
• INV-3: Every fact retrievable through this system's APIs carries a provenance tier; no API response contains a bare value without one.
• INV-4: No player-submitted reference image (§4) is ever stored as, or convertible into, a rendered game asset — only its extracted structured characteristics are retained.
• INV-5: Settlement records and their historical data are never deleted or edited in place — only appended/versioned, per §10.
• INV-6 (new, authoritative): All generation in this system — procedural generation (§5.3) and candidate site generation (§1.3a) — is fully deterministic. Identical inputs always produce identical outputs. No runtime randomness is used anywhere in Legend Knowledge.
• INV-7 (new, authoritative): Candidate site generation (§1.3a) never returns an empty result for any valid settlement_id.