Modular LLM-ability system — extract the 8 per-feature abilities into an ordered registry (v0.40.0) #74

New Issue

2026-10-16T09:21:51+02:00

kamilkrzywda commented

2026-10-16 09:21:51 +02:00

Summary

Behavior-preserving refactor of server/engine.ts: extract the 8 per-feature LLM
abilities (takeovers, wars, hybrid, economy/trade-embargo, industry, nuclear, leaders,
ideology) into server/abilities/ as an ordered ABILITIES registry, so each ability
owns its own Ability<K> (field, default, validate, apply, schemaLine, constraint,
isMeaningful, stub, payload, optional stateFields) and engine.ts becomes a thin
orchestrator that loops the registry.

Guarantees (all verified)

Identical buildSystemPrompt string (byte-for-byte vs committed goldens).
Identical buildUserPrompt JSON (byte-for-byte vs committed goldens).
Identical applyTurnResult world-state mutations.
Deterministic stub.ts (byte-identical deterministicTurn JSON vs pre-refactor).
All unit tests green (16 files) + typecheck + lint + build.
server/engine.ts re-exports every name it used to, so server/index.ts and all
tests work with zero edits.
No new runtime deps; no @turf/@types/geojson in any .ts; shared/ stays dep-free.
Client (src/) untouched. Not deployed (deliberate — deploy only on request).

Layout

server/abilities/types.ts — Ability/AbilityField/AbilityCtx/UserPromptCtx (zero-arg stub()).
server/abilities/shared.ts — the 5 shared primitives (freshNationId, freshWarId, NEW_NATION_STATS, resolveNationRef, resolveRegionKey).
server/abilities/*.ts — the 8 ability modules + apply-helpers.ts.
server/abilities/index.ts — assembles the ordered ABILITIES registry + re-exports.
server/abilities/registry.test.ts — the contract tests (3 golden-prompt tests, registry order, default() freshness, isMeaningful, stateFields, composition, backward-compat re-export check).

Ships as v0.40.0.

## Summary Behavior-preserving refactor of `server/engine.ts`: extract the 8 per-feature LLM abilities (takeovers, wars, hybrid, economy/trade-embargo, industry, nuclear, leaders, ideology) into `server/abilities/` as an ordered `ABILITIES` registry, so each ability owns its own `Ability<K>` (field, default, validate, apply, schemaLine, constraint, isMeaningful, stub, payload, optional stateFields) and `engine.ts` becomes a thin orchestrator that loops the registry. ## Guarantees (all verified) - Identical `buildSystemPrompt` string (byte-for-byte vs committed goldens). - Identical `buildUserPrompt` JSON (byte-for-byte vs committed goldens). - Identical `applyTurnResult` world-state mutations. - Deterministic `stub.ts` (byte-identical `deterministicTurn` JSON vs pre-refactor). - All unit tests green (16 files) + typecheck + lint + build. - `server/engine.ts` re-exports every name it used to, so `server/index.ts` and all tests work with zero edits. - No new runtime deps; no `@turf`/`@types/geojson` in any `.ts`; `shared/` stays dep-free. - Client (`src/`) untouched. **Not deployed** (deliberate — deploy only on request). ## Layout - `server/abilities/types.ts` — `Ability`/`AbilityField`/`AbilityCtx`/`UserPromptCtx` (zero-arg `stub()`). - `server/abilities/shared.ts` — the 5 shared primitives (freshNationId, freshWarId, NEW_NATION_STATS, resolveNationRef, resolveRegionKey). - `server/abilities/*.ts` — the 8 ability modules + `apply-helpers.ts`. - `server/abilities/index.ts` — assembles the ordered `ABILITIES` registry + re-exports. - `server/abilities/registry.test.ts` — the contract tests (3 golden-prompt tests, registry order, default() freshness, isMeaningful, stateFields, composition, backward-compat re-export check). Ships as **v0.40.0**.

kamilkrzywda referenced this issue from a commit

2026-10-16 09:24:15 +02:00

refactor(#74) P1: capture golden prompt baselines for the ability-module refactor

kamilkrzywda referenced this issue from a commit

2026-10-16 09:24:15 +02:00

refactor(#74) P2: extract shared helpers to server/abilities + define the Ability type surface

kamilkrzywda referenced this issue from a commit

2026-10-16 09:24:15 +02:00

refactor(#74) P3: add the 8 ability modules + ABILITIES registry

kamilkrzywda referenced this issue from a commit

2026-10-16 09:24:15 +02:00

refactor(#74) P4: wire engine/stub/db through the ABILITIES registry