Skip to content

KNAT Application Profile: Producer Brand

Purpose

This document defines the KNAT application profile for a Producer Brand — the engine-level authority responsible for bringing domains into existence and managing the objects within them.

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

  • identify and locate the producer authority for a given simulation
  • read its declared capabilities and operational health
  • discover the physics engines it has registered with the coordinator
  • observe its legitimacy regime and continuity thresholds
  • receive health signals as the economic policy layer matures

This profile intentionally does not model:

  • the domains the producer manages (regions, games, biologics each have their own surfaces)
  • the full economic policy layer (dust lifecycle, escrow, distribution — that surface will extend this profile as the janet-producer layer matures)
  • participant governance or legitimacy model internals
  • world-level clock or frame scheduling (those are the world brand's surface)

Those surfaces exist elsewhere in the system.

This profile exposes the authority identity and operational health of the producer itself.

Conceptual Model

The producer sits at the top of the domain hierarchy. It is not a region, a game, or a biologic — it is the thing that makes those things possible:

Producer Brand
    declares physics engines
    owns economic policy
    carries legitimacy regime

    → Region Brand     (spatial field)
    → Game Brand       (simulation sandbox)
    → Biologic Entity  (actor)

A producer brand is bespoke — it is not generated from a template. Each producer is shaped to the specific world or simulation it manages. ToyTownBrand in the Toytown downstream is the canonical example: it owns the world identity, terrain and climate engine registrations, and the JTL program, alongside producers: true and physics: true capability flags.

The KNAT surface of a producer is deliberately lean. It carries the label — the stable answer to "who is handling the check?" — plus enough health signal to determine that the producer is running and honoring its constraints. The deeper economic surfaces are not yet exposed here.

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

Structural surfaces — established at load time, stable at runtime:

spec              provenance and genome
identity          human-readable title and description
capabilities      what this producer brand is responsible for
regime            legitimacy model type and thresholds
registered_engines  coordinator-wired physics simulations

Live surfaces — updated by the runtime:

status      operational health (operational, capacity, slack, maintenance, constraints)
frame       current world tick

The economic policy surface — dust pool, escrow ledger, distribution policy — is not yet present. It will appear in a future extension to this profile.

Root Graph

A producer brand KNAT surface is rooted at:

/producer::<producer_id>/

Top-level families:

/producer::<producer_id>/
    /spec
    /engine
    /identity
    /capabilities
    /regime
    /registered_engines
    /status

The view field on the snapshot indicates whether the surface is complete (full) or policy-shaped (projected). The status family is the primary surface affected by view — agents without health-read authority may receive a projected snapshot without it.

Spec Surface

Provenance of the producer spec this instance was instantiated from. Static at runtime.

/producer::<producer_id>/spec/ref
/producer::<producer_id>/spec/genome
node type capabilities
ref String read
genome String read

genome provides deterministic identity across re-instantiations of the same producer spec. Same genome, same engine, same world = identical initial state.

Engine Surface

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

/producer::<producer_id>/engine/name
/producer::<producer_id>/engine/version
node type capabilities
name String read
version String read

Identity Surface

Human-readable identity of this producer. Derived from the spec meta block. Static at runtime.

/producer::<producer_id>/identity/title
/producer::<producer_id>/identity/description/<lang>
node type capabilities
title String read
description/<lang> String read

description is a map of ISO 639-1 language codes to strings (e.g. en, br). Consumers should read the language code matching the observer's locale.

Capabilities Surface

Feature flags advertising what this producer is responsible for. From BrandCapabilities in janet-brand. Structural — declared by the brand author and fixed at load time.

/producer::<producer_id>/capabilities/producers
/producer::<producer_id>/capabilities/physics
/producer::<producer_id>/capabilities/governance
node type capabilities meaning when true
producers Boolean read runs economic policy cycles (dust, escrow)
physics Boolean read owns physics engine registrations
governance Boolean read participates in legitimacy signaling

Read capabilities first when deciding which other surfaces to subscribe to. A producer with physics: false will have an empty registered_engines map. A producer with producers: false will have no economic policy output in future.

Regime Surface

Legitimacy regime governing this producer's institutional behavior. Optional — absent for producers without a declared regime. From RegimeType and LegitimacySchema in janet-brand.

/producer::<producer_id>/regime/type
/producer::<producer_id>/regime/c_min
/producer::<producer_id>/regime/continuity_carrier
node type capabilities notes
type String read regime classification
c_min Float read minimum continuity threshold
continuity_carrier String read named concept that must persist

type values from RegimeType:

x1_universalist          legitimacy through broad participation and inclusion
x2_stewardship_continuity  legitimacy through demonstrated infrastructure survival
x3_procedural            legitimacy through rule-following and formal process
x4_communitarian         legitimacy through group cohesion
x5_hierarchical          legitimacy through rank and assigned authority
x6_competitive           legitimacy through measurable performance

c_min is the survival threshold — the minimum continuity_confidence() value below which the producer's institutional outputs are flagged. continuity_carrier is the concept that must persist (e.g. "constitutional order", "supply stability").

When regime is absent, the producer has not declared a legitimacy model. This is valid — the common producer (genome: 0000000000000000) operates without a regime.

Registered Engines Surface

Physics engine registrations declared by this producer and wired by the coordinator. These are the simulation domains under this producer's physical authority. Structural — established at startup.

/producer::<producer_id>/registered_engines/<engine_id>/engine_type
/producer::<producer_id>/registered_engines/<engine_id>/locality
/producer::<producer_id>/registered_engines/<engine_id>/fiction_prefix
/producer::<producer_id>/registered_engines/<engine_id>/enabled
node type capabilities notes
engine_type String read coordinator engine selector
locality String (enum) read where the engine runs
fiction_prefix String read chem path prefix for outputs
enabled Boolean read

locality values from PhysicsLocality:

internal    runs in the coordinator process
external    runs in a separate executor process
remote      runs in executor; coordinator pushes census only

fiction_prefix is the chem path prefix where this engine's output lands. All chem keys written by a terrain_field engine for world::toytown/ will begin with world::toytown/terrain/. Use this to join engine registrations with the environment surfaces of domains they drive.

Only present when capabilities.physics is true.

Status Surface

Live operational health of this producer. From ProducerHealth in janet-brand. Present in full view; may be absent in projected view.

/producer::<producer_id>/status/operational
/producer::<producer_id>/status/capacity_utilization
/producer::<producer_id>/status/slack_available
/producer::<producer_id>/status/maintenance_required
/producer::<producer_id>/status/constraints_honored
node type capabilities
operational Boolean read, subscribe
capacity_utilization Float read, subscribe
slack_available Float read
maintenance_required Boolean read, subscribe
constraints_honored Boolean read, subscribe

Subscribe to operational and constraints_honored to receive alerts when the producer enters a degraded state. capacity_utilization and slack_available are the economic headroom indicators — they will become more meaningful as the dust lifecycle layer is exposed.

Not all producer instances populate all status fields. A minimal producer carrying only the label (no active economic policy) may omit capacity_utilization and slack_available.

Cross-Domain Joins

The producer KNAT surface is the root of the domain hierarchy.

Producer ↔ Region: A region's spec.ref traces back to the producer that authored and owns it. The fiction_prefix in registered_engines for a terrain_field or climate_field engine maps directly to the chem namespace in RegionRuntime.environment._namespace.

Producer ↔ Game: Games loaded as LoadedBrandObject trace back to the producer via their bundle's BundleId. The producer's capabilities.producers flag indicates whether economic contests (dust escrow) are available for games under this producer.

Producer ↔ World Frame: The frame field tracks the world clock. Join with the world brand's frame surface to confirm the producer is advancing in lockstep with the simulation.

Snapshot Format

The full producer KNAT snapshot is defined in defs/producers/runtime.json.

A snapshot represents all surfaces at a single frame. Consumers connecting cold receive a full snapshot before subscribing to incremental updates.

view field semantics:

  • "full" — all surfaces are present, including status
  • "projected" — policy-shaped; status may be absent; regime threshold details may be redacted

Minimal MVP Implementation

A minimal producer KNAT implementation exposes:

  1. spec (ref, genome)
  2. engine (name, version)
  3. identity (title)
  4. capabilities (producers, physics, governance)
  5. frame

This is the "carrying the label" surface — it answers "who is handling the check" without requiring any economic or physics wiring.

Progressive additions:

  • regime — legitimacy model (requires LegitimacySchema wiring)
  • registered_engines — physics engine roster (requires PhysicsRegistration wiring)
  • status — operational health (requires ProducerHealth integration)
  • (future) finance — dust pool, escrow summary, distribution policy (requires janet-producer integration)

Example Graph

ToyTownBrand (bespoke world brand, producers + physics enabled):

/producer::toytown/
    spec
        ref        "plantange:producers/toytown@v1"
        genome     "7071000000000000"

    engine
        name       "toytown-v1"
        version    "0.1.0"

    view           "full"

    identity
        title      "Toytown"
        description
            en     "Single-loop train world demonstrating emergent economic and narrative behaviour."

    capabilities
        producers   true
        physics     true
        governance  false

    regime
        type                    "x3_procedural"
        c_min                   0.45
        continuity_carrier      "constitutional order"

    registered_engines
        world::toytown/terrain
            engine_type     "terrain_field"
            locality        "internal"
            fiction_prefix  "world::toytown/terrain/"
            enabled         true
        world::toytown/climate
            engine_type     "climate_field"
            locality        "internal"
            fiction_prefix  "world::toytown/climate/"
            enabled         true

    status
        operational             true
        capacity_utilization    0.31
        slack_available         0.69
        maintenance_required    false
        constraints_honored     true

frame   4200

Common Producer (label-only, no physics, no regime):

/producer::common/
    spec
        ref        "plantange:producers/common@v1"
        genome     "0000000000000000"

    engine
        name       "janet-producer-v1"
        version    "1.0.0"

    view           "full"

    identity
        title      "Common Producer"
        description
            en     "A default producer to allow basic production of items without needing to define a specific producer for every item."
            br     "Um produtor padrão para permitir a produção básica de itens sem precisar definir um produtor específico para cada item."

    capabilities
        producers   false
        physics     false
        governance  false

    registered_engines  {}

    status
        operational   true

frame   4200

Future Extensions

When the janet-producer economic layer is exposed via KNAT, the following surfaces will extend this profile:

/producer::<id>/finance/central_pool           dust available for allocation
/producer::<id>/finance/total_minted           cumulative dust minted
/producer::<id>/finance/total_burned           cumulative dust burned
/producer::<id>/finance/net_supply             minted - burned
/producer::<id>/finance/total_escrowed         dust held in escrow
/producer::<id>/finance/turn_active            whether a frame is currently open
/producer::<id>/directives/<id>/kind           active ProducerDirective
/producer::<id>/distribution_policy/default    default distribution rule

These are intentionally excluded from the current profile.