Skip to content

README: Jook

Purpose

This document defines the KNAT application profile for a Jook — a world item that projects ambient influence over participants within its spatial perception field. Consent is implicit: proximity is consent.

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

  • observe the current census of participants within a jook's field
  • read the active ambient effects being applied by a jook
  • monitor census staleness and evaluation timing
  • join jook membership to other participant surfaces

This profile intentionally does not model:

  • frame-by-frame AwarenessState (frame-ephemeral, internal to the executor)
  • participant chem state or actor physics (those are biologic surfaces)
  • effect application outcomes on individual participants (governed by the participant's own surface)
  • region or world spatial topology upstream of the jook

Conceptual Model

A jook is a world item with a fixed location and field radius. Any participant within the field is perceived by the jook. The jook does not push effects to the participant's chem directly — it biases the environment within its radius.

World / Region
    provides spatial frame of reference

Jook
    owns field_radius spatial claim
    maintains proximity cohort (census)
    applies ambient effects to census members

Consent is implicit by proximity. Participants who enter the field are in the census; participants who leave are removed at the next cohort evaluation. There is no opt-in or opt-out mechanism at this surface.

Census vs. AwarenessState: The KNAT census is the stable membership list updated on the cohort evaluation schedule (every N frames). AwarenessState is an in-memory, frame-ephemeral record used by the executor and is not visible here.

Root Graph

A jook brand KNAT surface is rooted at:

/brand::<jook_id>/

Top-level families:

/brand::<jook_id>/
    /spec
    /engine
    /census
    /effects
    /frame

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

Spec Surface

Provenance of the jook instance. Static after instantiation.

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

ref is the registry or filesystem reference to the originating spec document. genome is the hex-encoded genome seed used during instantiation.

Engine Surface

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

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

Census Surface

The proximity cohort membership for this jook. Updated on the cohort evaluation schedule, not per-frame.

/brand::<jook_id>/census/cohort_id
/brand::<jook_id>/census/members
/brand::<jook_id>/census/member_count
/brand::<jook_id>/census/evaluated_at_frame
/brand::<jook_id>/census/staleness_frames
/brand::<jook_id>/census/is_stale
node type capabilities
cohort_id String read
members Array read
member_count Integer read
evaluated_at_frame Integer read
staleness_frames Integer read
is_stale Boolean read

Each member entry in members:

/brand::<jook_id>/census/members[]/participant_id
/brand::<jook_id>/census/members[]/perception_strength
node type capabilities
participant_id String read
perception_strength Number read

perception_strength is a linear falloff value: 1.0 at the jook center, 0.0 at the field boundary. It is computed at census evaluation time, not recalculated per frame.

is_stale is true whenever staleness_frames exceeds the jook's configured cohort evaluation interval. Stale census data should be treated as approximate.

Effects Surface

Aggregate view of ambient effects currently active on this jook. May be suppressed by projection policy.

/brand::<jook_id>/effects/active
node type capabilities
active Array read

Each entry in active:

/brand::<jook_id>/effects/active[]/name
/brand::<jook_id>/effects/active[]/effect_type
/brand::<jook_id>/effects/active[]/intensity
node type capabilities
name String read
effect_type String read
intensity Number read

Effect types: sound, light, rhythm_sync, attention_bias, metadata_exposure, or a custom string.

Frame Surface

/brand::<jook_id>/frame
node type capabilities
frame Integer read

Simulation frame number at snapshot time. Use to detect whether a census snapshot is current or lagging.

Cross-Domain Joins

From Via To
census/members[]/participant_id biologic surface participant location, role, chem state
census/cohort_id cohort surface cohort/v1/runtime census snapshot
spec/ref registry jook spec document (jook/v1/spec)

Snapshot Format

A full jook runtime snapshot matches the shape defined in jook/v1/runtime.json. Key points:

  • census.members contains only participants currently within field_radius
  • census.is_stale indicates whether the membership list may be outdated
  • effects.active lists the jook's configured ambient effects (not per-member application state)
  • AwarenessState is not in this surface — it is internal and frame-ephemeral