Skip to content

0064 — Worldgen pipeline cleanup (Group J)

Status

Accepted.

Context

Eight audit findings on the galaxy-generator pipeline. Zero critical; the cluster is doc clarification plus three real design fixes (phase ordering, Phase 13 invariant cross-checks, bang-import verification). Most of the work is making implicit invariants explicit at the right pipeline stage.

Decision

G-D2 — SpaceDock #2 placement: "Frontier-zone outer reaches"

The SpaceDock #2 placement spec uses two phrasings inconsistently across docs ("Frontier zone" vs "Frontier-zone outer reaches"). The canonical wording is "Frontier-zone outer reaches" — a distinct location class, not "anywhere in Frontier zone." Aligns with the ADR-0044 intent that SpaceDocks anchor specific narrative geography.

Doc fix only; no schema change.

G-D3 — Capital-sector-flag marker removal

The Sector.is_capital (or equivalent) column was marked 📐 Design-only in DATA_MODELS/galaxy.md, but Phase 6 of the worldgen pipeline reads and writes it as load-bearing state. Remove the Design-only marker. Doc-vs-code drift only; the column is in active use.

G-F3 — Phase 8.5 SCC re-verification

Phase 8 (long-distance tunnels) and Phase 9 (SCC formation checks) currently run in sequence: Phase 8 lands long-distance tunnels into the graph, then Phase 9 runs SCC verification on the result. The audit identified a case where Phase 8 introduces a tunnel that splits the Capital sector into a 20% minority strongly-connected component before Phase 9's SCC verification fires.

Insert Phase 8.5 SCC re-verification between Phase 8 and Phase 9:

  • After all long-distance tunnels land in Phase 8, Phase 8.5 runs a fresh SCC computation.
  • If the Capital sector is found to be in any non-majority component, Phase 8.5 rejects the tunnel set and falls through to a remediation pass: rebuild the long-distance tunnel set with the constraint that the Capital must remain in the majority SCC.
  • Phase 9 then runs on the verified-SCC graph and proceeds with formation checks.

Phase 8.5 is a new explicit step; the alternative — re-running Phase 9 after Phase 8 — was rejected because Phase 9 does formation-aware checks that don't fit a "verify and roll back" loop.

G-F4 — Phase 13 cross-check for WARP_SINK-inside-BUBBLE

Per ADR-0046, WARP_SINK formations must not be placed inside BUBBLE formations. Phase 9 enforces this internally; Phase 13 (final pre-deploy validation) had no equivalent cross-check, so anything introduced by Phases 10–12 (anchor placement, named-entity injection, bang-import) could violate the invariant without being caught.

Phase 13 gains an explicit validation step:

def phase_13_validate_warp_sink_invariant(galaxy):
    bubbles = SpecialFormation.objects.filter(type='BUBBLE')
    for sink in SpecialFormation.objects.filter(type='WARP_SINK'):
        for bubble in bubbles:
            if formation_intersects(sink, bubble):
                raise WorldgenInvariantViolation(
                    'warp_sink_inside_bubble',
                    sink_id=sink.id, bubble_id=bubble.id,
                )

Failure of this check rolls back the entire worldgen run; the operator dashboard surfaces the specific violating formation pair for diagnostic.

G-I3 — Bang-import verification at Phase 13

Bang-imported state (per ../OPERATIONS/bang-integration.md) crosses a translation boundary into the gameserver schema. Phase 13 gains a validation pass that confirms bang-emitted rows have populated all required gameserver fields per the per-entity translation tables in the bang-import-pipeline appendices:

  • For each bang-emitted entity (Sector, Warp, Port → Station, Planet, Nebula → Cluster), confirm the gameserver schema's required fields are non-null.
  • For each entity type with synthesized fields (e.g., commodity coverage per ADR-0062 E-D2), confirm synthesis ran.
  • For nexus_warp_sector (per ADR-0043), confirm the warp marker is placed and the per-region warp-knowledge-database hooks are wired.

Failure surfaces the offending entity ID and the missing fields. Phase 13 fails fast — bang-import errors prevent the universe from going live.

R-I4 — nexus_warp_gate_sector → nexus_warp_sector rename

Per ADR-0043 the field was renamed but the rename hadn't propagated to DATA_MODELS/galaxy.md. Doc fix: replace all references.

Add cross-link from worldgen docs that reference cluster/formation naming to ADR-0044, which specifies the bang-side determinism contract for naming.

R-V3 — Free-tier Nexus warp visibility filter

Per ADR-0043 the natural Nexus warp is latent by default — players don't see it until they personally discover it. The corp-shared map state surface (per the team / corp visibility rules) currently shares discovered map data wholesale, which can leak knowledge of an unrevealed Nexus warp to a free-tier player whose corp-mate has discovered it.

The visibility query filters the nexus_warp_sector marker on a per-viewer basis:

def map_visibility_for(viewer, region):
    base = corp_shared_map(viewer.corp_id, region)
    # Filter Nexus warp markers by viewer's personal discovery
    if not viewer.has_warp_knowledge_of(region.nexus_warp_sector):
        base.remove_marker('nexus_warp_sector', region.nexus_warp_sector)
    return base

The intersection rule: every map element shows for a viewer only if either (a) the viewer has personal discovery of it, or (b) it's a public element (sector existence, faction-controlled stations). The Nexus warp marker is not public — it requires personal discovery, regardless of corp share. Free-tier players who can't traverse the Nexus warp also can't piggyback on a Galactic Citizen corp-mate's discovery to see it on the map.

Consequences

  • Phase 8.5 is a new pipeline stage. Worldgen runtime increases marginally (one additional SCC computation); the remediation path adds re-runs of long-distance tunnel placement when Capital ends up in a minority component.
  • Phase 13 validation cost grows by two passes (WARP_SINK invariant, bang-import verification). Both are read-only graph walks; cost is bounded.
  • Map visibility filter runs per-viewer per-query. The performance cost is one extra check per Nexus warp per region per query — negligible at Launch scale.
  • Doc-only fixes (G-D2, G-D3, R-I4, R-O3) are zero-runtime-cost; they reduce ambiguity in the spec without changing behaviour.

Alternatives considered

  • Re-running Phase 9 after Phase 8 instead of inserting Phase 8.5. Rejected — Phase 9 does formation-aware work that doesn't fit a verify-and-rollback loop; a dedicated SCC-only re-verification is cheaper and clearer.
  • Bang-import verification as a post-deploy job instead of Phase 13. Rejected — defects at deploy time are dramatically more expensive than defects caught at worldgen-time.
  • Public Nexus warp markers on the map (no per-player filter). Rejected — defeats the ADR-0043 latent-by-default design intent and effectively makes the warp visible to all corp members regardless of subscription tier.