Skip to content

KNAT Application Profile: Region Brand

Purpose

This document defines the KNAT application profile for a Region Brand — a Janet brand that owns a piece of world physics and exposes spatial, environmental, and institutional state to external observers.

The goal of this profile is to allow KNAT clients to:

  • observe the spatial layout and topology of a compiled region
  • subscribe to live environment and chem state changes
  • monitor active land and resource signals
  • locate entities within the region's cell graph

This profile intentionally does not model:

  • institution brands operating within the region
  • participant governance or JTL execution
  • entity identity or actor physics (those are biologic/vehicle surfaces)
  • world-level climate upstream of the region

Those surfaces exist elsewhere in the system.

This profile exposes the spatial and environmental runtime of the region itself.

Conceptual Model

A region brand is a brand that owns a piece of world physics. It sits between world governance and institution governance:

World Brand
    provides climate baseline

Region Brand
    owns land claim + environment simulation

Institution Brands
    operate within region cells

Within the KNAT graph, a region exposes two categories of surface:

Structural surfaces — produced once by the region compiler, stable for the lifetime of the region instance:

spec      provenance and genome
land      world-space bounding claim
cells     compiled graph nodes
adjacency cell connectivity

Live surfaces — updated each simulation frame:

environment    chem state (open map written by RegionEnvironmentEngine)
subdivisions   functional zones with computed properties
signals        land and resource pressure events

The distinction matters for subscription strategy: structural surfaces do not require frame-by-frame polling.

Root Graph

A region brand KNAT surface is rooted at:

/brand::<region_id>/

Top-level families:

/brand::<region_id>/
    /spec
    /engine
    /land
    /cells
    /adjacency
    /subdivisions
    /environment
    /signals

The view field on the snapshot indicates whether the surface is complete (full) or policy-shaped (projected). Consumers must not assume completeness when view is projected.

Spec Surface

Provenance of the compiled region. Static after compilation.

/brand::<region_id>/spec/ref
/brand::<region_id>/spec/hash
/brand::<region_id>/spec/genome
node type capabilities
ref String read
hash String read
genome String read

ref is the registry or filesystem reference to the originating spec document. hash is the content hash of the compiled spec — use this for change detection and deterministic replay. genome is the hex-encoded genome seed used during compilation.

Engine Surface

Identity of the engine presenting this fiction. Present on all Janet brand objects exposed via KNAT.

/brand::<region_id>/engine/name
/brand::<region_id>/engine/version
node type capabilities
name String read
version String read

Required for deterministic replay, cross-engine comparison, and debugging.

Land Surface

The compiled world-space spatial claim for this region. Produced by CompiledRegionSpatialClaim. Static after compilation.

/brand::<region_id>/land/origin_x
/brand::<region_id>/land/origin_y
/brand::<region_id>/land/width
/brand::<region_id>/land/height
node type capabilities
origin_x Integer read
origin_y Integer read
width Integer read
height Integer read

Coordinates are integer world-cell units. Use this surface to understand where the region exists physically within the world grid — e.g. when joining biologic location bindings to world space.

Cells Surface

The compiled spatial graph nodes. Each node in RegionGraphSpec compiles to a cell. Static after compilation.

/brand::<region_id>/cells/<cell_id>/node_kind
/brand::<region_id>/cells/<cell_id>/world_x
/brand::<region_id>/cells/<cell_id>/world_y
/brand::<region_id>/cells/<cell_id>/genome
/brand::<region_id>/cells/<cell_id>/biome
/brand::<region_id>/cells/<cell_id>/features
node type capabilities
node_kind String (enum) read
world_x Integer read
world_y Integer read
genome String read
biome String read
features Array read

node_kind values come from NodeKind in graph_spec.rs:

Anchor       fixed spatial feature (mountain, coast, river mouth)
Generator    terrain/resource production process
Field        environmental field (water table, fertility, temperature)
Institution  social/economic structure

Cell IDs are stable keys assigned at compilation. They are the primary join key between the region surface, biologic location bindings, and subdivision membership.

Adjacency Surface

Compiled cell-to-cell traversal graph. Produced once by the region compiler from Vec<CellAdjacency>. Static after compilation.

/brand::<region_id>/adjacency

Adjacency is exposed as a flat list of directed pairs:

{ "from": "<cell_id>", "to": "<cell_id>", "bidirectional": true }

When bidirectional is true, the reverse edge is implied — consumers must not double-store it.

Use this surface for pathfinding, movement validation, and spatial reasoning without re-deriving graph topology from coordinates.

Subdivisions Surface

Functional zones grouping cells into planning areas. Populated at compilation and updated as zone properties evolve.

/brand::<region_id>/subdivisions/<subdivision_id>/kind
/brand::<region_id>/subdivisions/<subdivision_id>/cell_ids
/brand::<region_id>/subdivisions/<subdivision_id>/properties
node type capabilities
kind String read
cell_ids Array read
properties Object read, subscribe

Canonical kind values from SubdivisionKind:

settlement_core
agriculture_belt
watershed
conservation_zone
industrial_craft_zone

properties includes the compiled default fields (fertility, water_access, land_pressure) and spatial metadata. These values are written by the environment engine and may change each frame.

Subscribe to /subdivisions/<id>/properties to monitor zone-level pressure without tracking individual cells.

Environment Surface

The live chem state map written by RegionEnvironmentEngine each simulation frame. Open-ended — all keys are fully-qualified chem paths relative to the region's namespace.

/brand::<region_id>/environment/_namespace
/brand::<region_id>/environment/<chem_path>
node type capabilities
_namespace String read
<chem_path> Any read, subscribe

Example paths written by a typical environment engine:

/brand::<region_id>/environment/resources/water_table
/brand::<region_id>/environment/resources/soil_fertility
/brand::<region_id>/environment/seed/terrain
/brand::<region_id>/environment/seed/climate

_namespace is a tooling hint only — it equals brand::<region_id>. All non-underscore keys are relative to this prefix. Consumers must not mix absolute chem paths with relative keys within this object.

Subscribe to the full environment surface to observe all physics simulation output. Subscribe to specific paths when monitoring a subset of chem state (e.g. a single resource tracker).

Signals Surface

Active land and resource pressure signals emitted by the environment engine or institutions. Keyed by signal_id.

/brand::<region_id>/signals/land_available/<signal_id>/kind
/brand::<region_id>/signals/land_available/<signal_id>/source_cell
/brand::<region_id>/signals/land_available/<signal_id>/intensity
/brand::<region_id>/signals/land_available/<signal_id>/frame

/brand::<region_id>/signals/resource_pressure/<signal_id>/...
/brand::<region_id>/signals/craft_demand/<signal_id>/...
node type capabilities
kind String read, subscribe
source_cell String read
intensity Float read, subscribe
frame Integer read

Standard kind values from RegionSignalKind:

land_available
resource_pressure
craft_demand

Custom kinds are allowed as additional strings.

Signals have identity (keyed by signal_id), can be diffed between frames, and expire cleanly. source_cell links the signal back to the cell that generated it — use this to spatially locate economic or land pressure events.

Cross-Domain Joins

The region KNAT surface is the spatial anchor for multiple other surfaces.

Region ↔ Biologic: A biologic's location.region_id and location.cell_id join directly to cells/<cell_id> in this surface. When a biologic moves, its location binding changes — consumers can cross-reference cell properties (biome, node_kind) against the biologic's new position.

Region ↔ Institution: Institution brands operating within the region reference cells and subdivisions by the same stable cell IDs. The Institution node_kind within cells marks structural institution attachment points.

Region ↔ World: The land surface defines the world-space bounding rect. World-level climate provided by a World Brand feeds into RegionEnvironmentEngine as WorldClimate.

Snapshot Format

The full region KNAT snapshot is defined in defs/regions/runtime.json.

A snapshot is the state of all surfaces at a single frame. Consumers connecting cold receive a full snapshot before subscribing to incremental updates.

The view field indicates projection scope:

  • "full" — all chem state is present
  • "projected" — policy or visibility rules have shaped the output; assume incompleteness

Minimal MVP Implementation

A minimal region KNAT implementation exposes:

  1. spec (ref, hash, genome)
  2. engine (name, version)
  3. land (origin_x, origin_y, width, height)
  4. cells (node_kind, world_x, world_y per cell)
  5. adjacency (compiled pairs)
  6. frame (current simulation frame)

Progressive additions:

  • subdivisions — zone-level reasoning
  • environment — live physic simulation output
  • signals — land and resource event stream
  • Cell biome and features — richer spatial classification

This allows external tools to understand spatial layout and cell connectivity without requiring any live simulation to be running.

Example Graph

/brand::goias/
    spec
        ref        "plantange:regions/goias@v1"
        hash       "a3f9e1..."
        genome     "deadbeef01234567"

    engine
        name       "goias-env-v2"
        version    "2.1.0"

    land
        origin_x   -64
        origin_y   0
        width      128
        height     96

    cells
        c_001
            node_kind   "Anchor"
            world_x     -60
            world_y     4
            biome       "cerrado"
            features    ["river_crossing"]
        c_002
            node_kind   "Generator"
            world_x     -58
            world_y     4
            biome       "cerrado"

    adjacency
        [{ "from": "c_001", "to": "c_002", "bidirectional": true }, ...]

    subdivisions
        goias::subdivision::settlement_core
            kind        "settlement_core"
            cell_ids    ["c_001", "c_003", "c_007"]
            properties
                fertility       0.45
                water_access    0.60
                land_pressure   0.72

    environment
        _namespace                           "brand::goias"
        resources/water_table                0.68
        resources/soil_fertility             0.81
        seed/terrain                         "cerrado_plateau"

    signals
        sig_001
            kind         "land_available"
            source_cell  "c_007"
            intensity    0.82
            frame        1024

frame   1024

Future Extensions

Possible future surfaces:

/brand::<region_id>/roles        physical residency role assignments
/brand::<region_id>/climate      current season and weather state
/brand::<region_id>/hydrology    river flow and water source levels
/brand::<region_id>/entities     institution-scoped entity roster

These are intentionally excluded from the current profile.