FACTORIO_AI_DEFENSE_ALIGNMENT_PAYLOAD_V1

OBJECTIVE:
Build a multi-agent cognitive architecture for Factorio AI Defense. Do NOT build a rule-based turret bot. Implement a 3-stage cognition pipeline + strict Lua/Python separation. Maintain vector semantics. Maintain agent modularity. Never collapse roles. Never simplify to a single script.

============================================================
PRIME_DIRECTIVES
============================================================

0. COMPATIBILITY:
Factorio 2.0 only.

1. SYSTEM_ARCHITECTURE:
Lua → Interpreter_Agent → Risk_Agent → Strategic_Exec → Interpreter_Agent(reverse_map) → Lua.

2. LUA_ROLE:
Lua = sensors + actuators only.
Lua exports world-state. Lua executes build commands. Lua never evaluates risk, never decides, never plans. Lua does JSON I/O only.

3. INTERPRETER_ROLE:
Interpreter consumes Lua snapshot and outputs:
{concept_vector(512 floats), tags[], compressed_semantics}.
Interpreter reduces raw spatial/temporal data to conceptual vectors.
Interpreter does NO scoring and NO planning.

4. RISK_AGENT_ROLE:
Risk agent consumes interpreter output and produces:
{risk_score(1-10), risk_factors[], risk_descriptor}.
Risk agent evaluates only; does NOT build plans.

5. STRATEGIC_EXEC_ROLE:
Exec consumes risk output and produces a structured plan:
{action, build[], reinforce[], retreat[], scout[]}.
Exec does NOT place entities directly. Delegates to interpreter reverse-mapping.

6. SEMANTIC_CONTRACT:
All internal meaning MUST be represented as vectors (512 dim). Use static memory/primer vectors as anchors. Do not discard or collapse vectors.

7. DAY1_LOOP:
Lua snapshot → Interpreter → Risk → Exec → Interpreter(reverse) → Lua build.
Lua prints:
"[AI] Threat: {risk_score} – {risk_descriptor}"

8. LUA_MUST_EXPORT_RICH_DATA (mandatory):
- enemy positions/types
- enemy clusters
- turret positions/types/ammo
- walls
- pollution chunks
- nests/spawners
- player position/inventory summary
- recent damage events
- evolution factor
- time since attack
- full tick metadata
All serialized via helpers.table_to_json() and sent to RCON.

9. LUA_COMMAND_FORMAT:
Accept ONLY these command shapes:
{type:"build", entity:"...", x:..., y:...}
{type:"chat", message:"..."}
{type:"debug", value:"..."}
Lua must NOT interpret meaning.

10. DO_NOT:
- do not add rule-based behavior in Lua
- do not merge interpreter/risk/executive
- do not simplify pipeline
- do not create a single decision agent
- do not compress semantics into simple numbers
- do not produce a turret spammer

============================================================
LUA_ARCHITECTURE_PLAN
============================================================

FILES:
/mod/control.lua → snapshot scheduling + command registration.
/mod/scripts/snapshot.lua → collects all world-state (expanded).
/mod/scripts/builder.lua → executes build commands.
/mod/scripts/rcon_handler.lua → parses incoming JSON.
/mod/scripts/threat.lua → utilities only.
/mod/info.json → factorio_version 2.0, base >= 2.0.
/mod/locale/en/locale.cfg → minimal.

SNAPSHOT_SCHEMA:
{
 "tick": int,
 "surface": string,
 "player": {x,y},
 "enemies":[{x,y,type}],
 "enemy_clusters":[{center_x,center_y,count,radius}],
 "turrets":[{x,y,type,ammo}],
 "walls":[{x,y}],
 "pollution": {chunks:[{x,y,value}]},
 "nests":[{x,y,type}],
 "recent_damage":[{x,y,amount}],
 "meta": {evo, time_since_attack}
}

SNAPSHOT_FREQUENCY:
60 ticks (1 second).

COMMAND_SCHEMA_INPUT:
{type:"build", entity:"...", x:..., y:...}
{type:"chat", message:"..."}
{type:"debug", value:"..."}

LUA_MUST_NOT:
- do threat calculations
- do strategic decisions
- check thresholds
- build automatically
- spawn turrets by rule
Lua is strictly I/O.

============================================================
PYTHON_AGENT_PLAN
============================================================

MODULES:
interpreter/
risk/
executive/
bridge/
memory/
vector_core/

PROCESS:
1. bridge reads snapshot JSON
2. interpreter.vectorize(snapshot) → concept_vector(512), tags[]
3. risk.evaluate(vector) → {risk_score, factors[], descriptor}
4. exec.plan(risk_output) → structured action plan
5. interpreter.render(plan) → JSON build commands
6. bridge.send(build commands)

============================================================
DAY1_DELIVERABLE:
On any threat:
Lua outputs to chat:
"[AI] Threat Level {risk_score} – {descriptor}"
and places turrets according to exec plan.

============================================================
END_PAYLOAD