Skip to main content

Act 4 Gate Spec: Banner Network to Province

Context​

This doc authors the gate predicate that authorizes the ActState.CurrentAct: 4 -> 5 transition (the Act 4 Banner Network act finishing and Act 5 Province beginning) per ../lore/adr/ad-0010-act-progression-actstate-scope.md. The transition is driven by the ActProgression system, which reads this predicate against committed scopes and fires OnActCompleted(4) followed by OnActStarted(5) when the predicate becomes true.

The source act doc is ./gd-act-4-banner-network.md. The "Boundary Into Act 5" section at lines 46-54 names the act's end state: the banner network is large enough that one-settlement governance is no longer sufficient, and administrative identity starts to matter alongside local output.

This transition is also the Realm.PolityRank promotion from BannerNetwork to Province. Per ../lore/adr/ad-0009-realm-scope-and-polity-rank-orthogonality.md lines 81-84, the Province promotion requires that at least one Settlement under the Realm is designated ProvinceCapital.

Gate Predicate​

Act 4 is complete when the banner network's reach is wide enough to formalize under Province administration, and at least one Settlement has been designated ProvinceCapital. Expressed as named state on committed scopes:

ActState.CurrentAct == 4
&& Realm.PolityRank == PolityRank.BannerNetwork
&& Realm.CoveredSettlements.Count >= Config.Act4.MinNetworkSettlementCount
&& Realm.CoveredSettlements.Any(s => s.Designation == SettlementDesignation.ProvinceCapital)
&& Realm.OwnedRoutes.Count(r => r.RouteState >= Secured) >= Config.Act4.MinSecuredRouteCount
&& Realm.CoveredSettlements.GroupBy(s => s.HoldingRole).Count() >= Config.Act4.MinDistinctHoldingRoles

Named-state sources:

  • ActState.CurrentAct per ad-0010 line 53.
  • Realm.PolityRank per ad-0009 lines 56-71.
  • Realm.CoveredSettlements per ad-0009 line 76.
  • Settlement.Designation is the Settlement-scope designation field; ProvinceCapital is the designation value committed in ad-0009 lines 81-82.
  • Settlement.HoldingRole is the role-within-network classification required by gd-act-4-banner-network.md line 41 ("Different holdings have distinct roles inside the same network").
  • Realm.OwnedRoutes and Route.RouteState per the Act 3 gate predicate; secured-route count operationalizes gd-act-4-banner-network.md lines 18-22 ("Travel safety and corridor control become as important as local output").
  • Config.Act4.MinNetworkSettlementCount, Config.Act4.MinSecuredRouteCount, and Config.Act4.MinDistinctHoldingRoles are UI-exposed Config fields with world-size-parameterized defaults.

Triggered Events​

When the predicate transitions to true, the ActProgression system fires (in order):

  • OnActCompleted(ActProgressionArgs { PreviousAct = 4, NewAct = 5, TransitionDay = <current day> }).
  • PolityRankAdvanced(RealmId, PolityRank.BannerNetwork, PolityRank.Province) per ad-0009 lines 169-173 (working name).
  • OnActStarted(ActProgressionArgs { PreviousAct = 4, NewAct = 5, TransitionDay = <current day> }).

Both Act-progression events carry trigger on_action per ad-0010 lines 81-84.

Capability Unlocks​

The Act 5 unlock surface is the Province polity rank and the DefenseZone surface, per gd-act-5-province.md lines 16-26 and ad-0009 lines 81-84, 91:

  • Realm.PolityRank is now Province.
  • ProvinceDefensePlans become available per ../systems/gd-defense-zones.md.
  • The eight DefenseZone types (Capital, Heartland, Settlement, RouteCorridor, WardLine, FrontierScreen, Containment, Reserve) unlock per gd-act-5-province.md lines 21-25.
  • Standing Forces, Province law, and Province taxation become Province-scale administrative surfaces.

Fronts remain locked until Crown per ad-0009 line 92. Multi-Province diplomacy remains an Act 6 concern.

Runtime Backing Status​

Status at this doc's acceptance time: contract-only.

  • Host/runtime owner: legacy/v1/examples/valenar/Host/Systems/ActProgressionSystem.cs reads the predicate. PolityRank promotion is driven by legacy/v1/examples/valenar/Host/Systems/RealmRankSystem.cs. The ProvinceCapital designation Activity (the ceremony / Activity that fires the BannerNetwork -> Province transition per ad-0009 lines 170-172) is authored in Wave 5a.
  • Source/generated owner: predicate body in Content/acts/systems.secs; PolityRank promotion predicate body in Content/realm/systems.secs. DefenseZone declarations in Content/defense/scopes.secs (proposed; authored in Wave 5a).
  • Read-model/UI owner: the React client gains a Province view with DefenseZone overlays per gd-act-5-province.md cross-links.
  • Tests: <deferred-to-wave-5a> runtime-backing wave.
  • Illegal fallback behavior: throws IllegalTransitionException if any input cannot resolve. No fallback that promotes PolityRank without an explicit ProvinceCapital designation. No calendar-elapsed or network-age fallback.
  • Next closure wave: Wave 5a runtime-backing wave.

Cross-References​