Track FSM integration API from Alpha 10.3 into later CCO 2.1 builds

[SimGamerJen]

Purpose

Track the Farm Sim Manager cross-mod integration API separately from CCO's stable and active development lines.

Baseline

• Frozen NPC-regeneration baseline: archive/v2.1.0.0-alpha10.3-regen-only
• FSM proof branch: integration/fsm-bootstrap-alpha10.3
• Current integration build identifier: 2.1.0.0-alpha.10.3-fsm.3
• Current integration API: 1.2

Isolation rules

• Do not modify the frozen Alpha 10.3 archive branch.
• Do not merge this proof work into stable 2.0.3.6.
• Do not mix it into the active crop-calendar development line until the FSM read-only, mutation and idempotence lifecycle is validated.
• The Alpha 10.3 regeneration core remains unchanged; the proof branch adds only the adapter plus its loader.

API v1.0 proof surface — accepted read-only boundary

Published on the shared mission object as g_currentMission.cropControlOverrideIntegration.

Capability-driven wrappers expose Alpha 10.3 functionality where present:

• buildNpcMapRegenerationPlan
• confirmNpcMapRegeneration
• updateNpcMapRegeneration (retained for compatibility; FSM must not drive the timer)
• getActiveContractCount
• getContractBoardSummary only when the underlying CCO build provides it

The Kinlaig read-only proof passed with 48 live/indexed fields, 7/7 source FieldUpdateTasks resolved, 44/44 NPC fields planned, zero overlaps, zero excluded/unverified/unresolved fields and confirmAllowed=true.

API v1.1 mutation lifecycle proof — accepted

API 1.1 added a supported lifecycle boundary so FSM never needs private CCO state:

• startNpcMapRegeneration(expected)
  • server/host only;
  • refuses while a regeneration is already active;
  • rebuilds the CCO plan immediately before start;
  • rejects zero-action, excluded or unverified plans;
  • compares expected FSM preflight counts against the rebuilt plan;
  • internally arms the CCO plan and calls the proven Alpha 10.3 confirm path.
• getNpcMapRegenerationStatus()
  • reports idle, applying or complete;
  • exposes lifecycle phase and summary counts without exposing the private plan/state tables;
  • lets FSM remain APPLYING through waitingForFieldTasks and refillingContracts, then transition to COMPLETE only after CCO clears its active state.

P5.1 proved the controlled mutation lifecycle on Kinlaig: 44 queued, 0 skipped, 44 field caches refreshed with 0 failures, 8 stale contracts removed, a 14-contract board rebuilt, save persistence verified, and Starting Farm fields remained outside the CCO mutation scope after save/reload.

CCO continues to service its own asynchronous regeneration from its mission update hook. FSM must poll status only and must not call updateNpcMapRegeneration() to advance CCO.

API v1.2 idempotence / equivalence proof surface

API 1.2 adds a supported semantic-equivalence boundary:

• getNpcMapRegenerationEquivalence()
  • rebuilds the current deterministic CCO plan;
  • compares each planned action against the live field state;
  • returns sanitized counts/rows only: alreadyMatching, needsMutation, unresolved, plus planned/NPC/excluded/unverified metadata;
  • never exposes CCO field/fruit object references or private plan/state tables.

Equivalence semantics are CCO-owned:

• planned crop: exact live fruit index + exact growth state must match;
• planned cultivated: live fruit must be UNKNOWN, growth state 0, and ground type CULTIVATED;
• missing runtime state is unresolved, never optimistically considered matching.

startNpcMapRegeneration(expected) now independently rebuilds and rechecks the equivalence immediately before start. If every planned action is already materialized (needsMutation=0, unresolved=0), it returns a successful public status with:

• state=complete
• phase=complete
• noOp=true
• queued=0
• staleContractsRemoved=0
• refillCycles=0
• reason=already-equivalent

In the all-equivalent case it does not arm the core regeneration plan, call the core confirm path, delete available contracts, enqueue fields, refresh field caches, or regenerate the contract board.

For the current proof implementation, any genuine non-zero drift still uses the proven full-map CCO regeneration lifecycle. Selective/partial-drift mutation is deliberately deferred until after P5.2 proves safe no-op behaviour.

FSM must consume this supported API rather than CCO private _npcMapRegenerationPlan / _npcMapRegenerationState fields.

P5.2 acceptance gate

Run against the saved/reloaded P5.1 Kinlaig artifact. Expected result is:

• planned=44
• alreadyMatching=44
• needsMutation=0
• unresolved=0
• noOp=true
• no field task enqueue
• no stale contract deletion
• no field cache refresh
• no contract refill cycle
• existing contract board untouched

If the cultivated field cannot be resolved from the live runtime ground-state property, P5.2 must fail safe as unresolved and the adapter should be corrected from runtime evidence rather than weakening equivalence semantics.

Forward-port gate

After P5.2 passes:

1. keep the public API contract stable, including API 1.2 equivalence/no-op semantics;
2. squash/identify the minimal adapter changes;
3. cherry-pick/port them into the then-current CCO 2.1 development branch;
4. adapt only the wrapper implementation if CCO internals have moved;
5. retain capability/API-version checks in FSM;
6. verify NPC regeneration, async settle/cache refresh, contract regeneration, save persistence, reload and second-run no-op behaviour;
7. preserve CCO ownership of field-state semantics and the async lifecycle — external consumers request/inspect supported API operations rather than driving internal timers/state;
8. only then evaluate a partial-drift optimization and automatic career-generation orchestration;
9. close this issue only after a contemporary 2.1 build carries the supported API and FSM has been revalidated against it.

This issue is the durable reminder that the FSM API must become part of later 2.1 builds once the Alpha 10.3 proof is accepted.

[SimGamerJen]

P6.0 — shared field-regeneration core extraction started

The accepted P5.1/P5.2 behaviour is now being refactored into a single canonical source module so FSM and CCO do not require parallel maintenance of the same regeneration algorithm.

Proof/refactor branch: refactor/field-regeneration-core-alpha10.3 (from integration/fsm-bootstrap-alpha10.3).

Shared source:

• scripts/shared/FieldRegenerationCore.lua
• core version 0.1.0
• core API 1
• source owner FS25_CropControlOverride

CCO host bridge:

• scripts/shared/CCOFieldRegenerationCoreBridge.lua
• attaches the shared engine after CCO policy methods are defined
• preserves all existing CCO-facing regeneration method names as delegated wrappers

P6.0 integration marker:

• public FSM integration API remains 1.2 (no contract change)
• build ID 2.1.0.0-alpha.10.3-fsm.4-core0.1
• API publication now reports the shared-core version/API/source
• publication is deliberately refused if the shared core failed to attach, so parity tests cannot silently exercise the legacy fallback

The shared core owns deterministic planning, seasonal growth-state resolution, equivalence/idempotence, field writes, cache refresh, contract safety/purge/refill and lifecycle completion. CCO supplies policy callbacks (crop permission and weights) plus diagnostics.

Isolation check against integration/fsm-bootstrap-alpha10.3: CropControlOverride.lua is unchanged. The only P6.0 changes are the shared core/bridge, Debug loader, integration adapter and P6_FIELD_REGENERATION_CORE.md parity protocol. Frozen/stable/current development branches remain untouched.

Next acceptance gate: rerun the accepted P5.2 Kinlaig save through this branch. Expected: 44 planned, 44 already matching, 0 mutation/unresolved, noOp=true, 0 queued, 0 contract deletion/refill, existing 14-contract board untouched. Then rerun a pre-P5.1 artifact for full mutation parity before FSM directly vendors the core.