Skip to content

CIA Room Intelligence

The CIA (Creeps Intelligence Agency) is the canonical intelligence subsystem.

The CIA never makes decisions. It provides intelligence.

Boundaries

Scouts travel, observe visible rooms, submit observations through the CIA ingestion path, and retreat from immediate hostile creeps.

The CIA accepts visible-room observations, normalizes them, merges them into Memory.rooms[roomName].intelligence, preserves compact history, calculates confidence, and exposes read-only query helpers.

Consumers decide what to do with the intelligence. Expansion, defense, combat, spawning, remote mining, logistics, and route-risk policy do not live in the CIA.

Dossiers

Room dossiers are stored under existing room memory:

Memory.rooms[roomName].intelligence

The dossier preserves compatibility fields such as updatedAt, sources, controller, hostileSightings, hostileStructures, exits, roomStatus, and status.

Version 0.3.0 adds canonical dossier metadata:

  • roomName
  • firstObservedAt
  • observationCount
  • lastCompleteObservationAt
  • ownership
  • ownershipHistory
  • resourceSurvey
  • hostileCreeps
  • hostilesLastConfirmedAt
  • latestSummary
  • confidence
  • assessment
  • intelligenceFreshness
  • ciaEvents

Old room intelligence is supported lazily. New fields are optional in memory types and are populated by the next visible-room observation.

Observations

Owned rooms and scout-visible rooms use the same CIA ingestion path:

visible Room -> room observation -> CIA ingestion -> persistent dossier

The CIA records facts from the current visible room and keeps stable facts, such as source positions and previous ownership transitions, across later ticks.

Hostiles

hostileSightings reports hostiles present in the latest observation and remains compatible with earlier consumers.

hostileCreeps and hostileStructures retain compact per-object observations while the detail is strategically recent (at most 2,500 ticks old). Each record carries firstSeen, lastSeen, observationCount, position, owner where available, health, and presentInLatestObservation. Within that age window, all records present in the latest observation are retained, together with at most the four newest stale creep records and four newest stale structure records. Older per-object detail is discarded; the room's observation timestamps, latest counts, and aggregate assessment remain authoritative. Hostile sighting summaries persist only their count and tick, because names, owners, and structure types duplicate the current detailed records without serving an operational consumer.

This lets consumers distinguish:

  • no current vision
  • room observed with no current hostiles
  • room observed with current hostiles
  • stale hostile intelligence retained from an earlier observation

The CIA does not classify threats or choose responses.

Confidence

Confidence describes freshness, not desirability.

The initial model stores:

  • score: normalized 0..1
  • grade: unknown, confirmed, recent, or stale
  • age
  • observationCount
  • latestObservationComplete
  • domain freshness for ownership, hostiles, and resources
  • simple factors used to derive the score

Scouting may continue to use compatible observation timestamps, but confidence does not choose strategic scout targets.

Strategic Assessment

Version 0.3.1 adds an advisory strategic assessment to every known room dossier.

The CIA never makes decisions. It provides intelligence.

Assessments are stored at:

Memory.rooms[roomName].intelligence.assessment

The assessment uses a deterministic 0..100 scale for every category and the overall score:

  • 0 means no known strategic value or no known danger for threat.
  • 100 means very high known strategic value or very high known danger for threat.

Threat is intentionally directional: a higher threat score means the room is more dangerous, not more desirable. The overall score applies a threat penalty so a valuable but dangerous room does not look harmless.

Assessment categories:

  • economy: inherent economic usefulness and observed resources.
  • threat: hostile creeps, combat body parts, hostile structures, ownership, and retained hostile history.
  • logistics: coarse reachability from owned rooms, exits, and observed roads.
  • expansion: suitability as a future owned colony room.
  • remoteHarvest: suitability as an advisory remote energy candidate.
  • militaryValue: strategic military significance, not an attack order.

Primary recommendations are compact advisory labels:

  • owned
  • observe
  • refresh-intelligence
  • avoid
  • remote-harvest-candidate
  • expansion-candidate
  • strategic-watch
  • military-interest
  • low-value

The CIA refreshes assessments after observations and periodically as time passes, so age-sensitive confidence and freshness decay even when no scout has recent vision. Assessment refreshes do not change operational manager behavior.

With both an intelligence base lease and enhancement lease, CIA may refresh up to four additional assessments after 25 ticks rather than waiting for the ordinary 50-tick periodic threshold. The cheap request inspects at most 64 existing dossiers and requires either two early candidates or one whose current recommendation is strategically relevant. Missing assessments and observations that have changed remain ordinary baseline work. Enhanced assessment adds no new dossier fields or retained resolution, never invents observations, and does not create operations or make consumer decisions.

Freshness states are:

  • fresh
  • recent
  • stale
  • obsolete

Highway Deposit Intelligence

Version 0.4.2 retains ordinary scouting as the deduplicated union of rooms adjacent to owned colonies and adds a separate highway exception. A deterministic room-coordinate classifier and bounded breadth-first traversal build at most 16 highway candidates per eligible home, visit at most 60 exit edges per rebuild, and never exceed four room transitions from the owned-room root. The heap cache refreshes every 100 ticks or when ownership or active scout avoidance changes. Closed rooms, severe known threat, and temporary avoidance cannot silently become transit paths.

An admitted mission stores only its home, target, assigned tick, waypoint list, and current waypoint index on the scout. The shared room-transition workflow still owns edge approach, crossing, settlement, retreat, and blocked-room recovery. Once admitted, a highway chain keeps forward priority; after one completed highway mission, any pending ordinary adjacent refresh receives the next assignment so baseline CIA coverage cannot starve.

Scouting enhancement does not alter this frontier. When at least two existing authorized colony targets wait, one already-spawned Scout may compare at most four targets by current-room distance during its next assignment. The ordinary four-room route distance, 16 candidates per home, 60 traversal steps, four waypoints, avoidance rules, adjacent-refresh fairness, and Scout population all remain unchanged. Enhancement improves bounded target service; it cannot create dossiers outside the authorized frontier.

Visible deposits are recorded in resourceSurvey.deposits with type, ID, position, observation tick, current and last cooldown, and ticks to decay. Expired observations are removed rather than retained as history. The bounded Memory maintenance pass retains configured frontier rooms, active waypoint routes, unexpired deposits, and existing operational references; unrelated intelligence-only rooms remain eligible for pruning.

externalOperations/depositOpportunities derives advisory opportunities from these CIA facts without rescanning rooms. The 25-tick evaluator is admitted by the existing intelligence CPU work class and is measured under cpu.profile.sections.depositOpportunities. It estimates a rising-cooldown harvest window and yield, round-trip travel, spawn/workforce and carry burden, existing logistics capacity deficit, protected economy affordability, route risk, inventory demand, active Factory recipe demand, and cached executable Market value. Metal, Silicon, Biomass, and Mist have distinct base values.

Each result is candidate, eligible, or rejected, includes explicit blockers, and normalizes into a transient external operation with runtimeAuthority=advisory-only, no logistics route IDs, and no admitted objective. It cannot spawn creeps, add workforce or hauling demand, construct infrastructure, execute a Market deal, or activate deposit harvesting. Those runtime permissions remain 0.4.3 scope.

CIA Events

The CIA stores a bounded ciaEvents list per dossier. Events are advisory and read-only for consumers. Persistent events use a four-value tuple containing the tick, type code, previous value, and current value. Read helpers reconstruct the room name, type, severity, and summary used by debug output.

Events currently record meaningful assessment changes such as recommendation changes, threat band changes, freshness changes, and strategic score band changes. The list is capped at six events and events expire after 10,000 ticks. The existing versioned Memory migration applies these rules to at most ten rooms per tick; new observations and assessment refreshes enforce them thereafter.

ciaEvents is also CIA's first explicitly reconstructible class under the Memory Governor contract. On a due elevated-pressure request CIA inspects at most four dossiers and removes at most four events that are at least 5,000 ticks old. Critical pressure raises both bounds to eight and shortens the event grace to 1,000 ticks. A CIA-owned room cursor continues later without a full dossier scan. No missing CPU lease triggers this cleanup.

Only event-history entries are reclaimable. The dossier itself, latest and complete observation timestamps, current status, ownership and ownership history, sources and resource surveys, confidence, assessment, hostile facts, and operational references remain protected. When classification is uncertain, the owner preserves the state.

Read-Only Helpers

Use intelligence/agency helpers instead of reading raw memory when practical:

  • getRoomDossier(roomName)
  • getRoomConfidence(roomName)
  • getLatestHostileObservation(roomName)
  • getOwnershipHistory(roomName)
  • getResourceSurvey(roomName)
  • getStrategicAssessment(roomName)
  • getCiaEvents(roomName?)
  • isDossierStale(roomName)

These helpers must remain read-only. refreshRoomStrategicAssessment(roomName) is available for debug and maintenance flows that intentionally refresh the stored advisory assessment.