kernelcanonicalOWNER-2026-07-10

Spatial Site Kernel · kernel-spatial-site

Owner directive (2026-07-10), canonical. "Define the Kernel (Code), the Cogni (understanding) and the Genome for this. … Make it possible to add runs on each Holon, Gaussian splatting is one, using 3d models is another, the Holonprint (how it is rendered) shoul dbe able to even use, genmodels, for videos, 3D, pixelstreaming, AR, Sensors, etc." [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:473,496]

Content

The Spatial Site Kernel is the code contract of the Spatial Site engine — the interfaces every slice, scenery and holonprint renderer must implement. The understanding of when and why to use each contract lives in cogni-spatial-site; the per-instance parameters live in the genome-spatial-site strand. The implemented reference kernel is the Royal Orbit engine package at HOS-Instance/packages/engine/src/engine/contracts.ts (byte-identical to the live v1 site engine in web/royal-orbit/src/engine/contracts.ts, see src-royalorbit).

1. HolonPrintRenderer — how a holon is rendered

The holonprint is "how it is rendered". Six methods are declared; gaussian-splatting is the implemented method (via spark-renderer / @sparkjsdev/spark); the other five are declared slots to be filled by later runs on each Holon.

type HolonPrintMethod =
  | 'gaussian-splatting'   // IMPLEMENTED — SplatMesh via [[spark-renderer]]
  | 'genmodel'             // declared slot: generative video/world models
  | 'mesh3d'               // declared slot: classic glTF/3D models
  | 'pixelstream'          // declared slot: server-rendered pixel streaming
  | 'ar'                   // declared slot: augmented reality anchors
  | 'sensors';             // declared slot: sensor-driven presence

interface HolonPrintRenderer {
  method: HolonPrintMethod;
  /** resolve + fetch an asset by manifest id (e.g. "dunes", "pod-gold") */
  load(assetId: string, tier: QualityTier): Promise<void>;
  /** draw into the scene for local progress p ∈ [0,1] at time t */
  render(p: number, time: number): void;
  /** free GPU + CPU resources */
  dispose(): void;
  /** what this renderer can do on this device (budget, tier, features) */
  capabilities(): { maxSplats: number; tier: QualityTier; webgl2: boolean };
}

The gaussian-splatting implementation binds to the splat asset manifest contract (SplatAssetEntry / SplatManifest, 32-byte antimatter15 .splat records) [src: HOS-Instance/packages/engine/src/engine/contracts.ts:17,30,164] and to schema-holonprint for the declarative form.

2. SceneEngine — slice / scenery lifecycle

The slice/scenery lifecycle is the existing Chapter interface — the implemented kernel of the live Royal Orbit site. A slice (owner word: "scenaries (Slices)" [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:471]) maps 1:1 onto a Chapter:

// IMPLEMENTED — src: HOS-Instance/packages/engine/src/engine/contracts.ts:110
export interface Chapter {
  id: ChapterId;
  /** manifest asset ids this chapter needs before it can show */
  assets: string[];
  /** camera keyframes in chapter-local progress */
  cameraKeys: CameraKey[];
  /** called once when assets are loaded (build meshes, set transforms) */
  mount(ctx: ChapterContext): Promise<void>;
  /** per-frame while chapter is active-ish. p = chapter-local [0,1], may be <0/>1 for adjacents */
  update(ctx: ChapterContext, p: number, time: number): void;
  /** called when scrolled >=2 chapters away */
  unmount(ctx: ChapterContext): void;
}

with ChapterContext supplying scene, camera, cached loadAsset(id) / disposeAsset(id), tier, and reducedMotion [src: HOS-Instance/packages/engine/src/engine/contracts.ts:99]. The site is "one fixed WebGL canvas (Gaussian splats via @sparkjsdev/spark) behind normal DOM sections. DOM sections define scroll length; a master Lenis+ScrollTrigger scrub produces pageProgress in [0,1]; chapters map sub-ranges of that progress to camera keyframes through their splat worlds" [src: HOS-Instance/packages/engine/src/engine/contracts.ts:6]. Each chapter owns a disjoint world-space slab along −Z (CHAPTER_SLABS) so adjacent slices can be co-resident during transitions [src: HOS-Instance/packages/engine/src/engine/contracts.ts:179]. The dawn→night THEME_ARC is the kernel-level color law of the biome [src: HOS-Instance/packages/engine/src/engine/contracts.ts:83].

3. BehaviorLoop — life inside a slice

Sceneries run "with Loops of behavior, so it shall literally be a drone flight over a live scenery" [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:461]. A BehaviorLoop is a deterministic, seeded simulation ticked independently of the render loop:

interface BehaviorLoop<S = unknown> {
  id: string;              // e.g. "caravan", "market", "falcon"
  tickHz: 10;              // fixed simulation rate, decoupled from rAF
  seed: number;            // deterministic — same seed, same life
  update(state: S, dt: number): S;   // pure state advance
  effects: string[];       // effect ids applied to the scene (dust, sparks, banners)
}

Instances and seeds are declared per slice in genome-spatial-site (see behavior_loops in the example strand). Determinism is mandatory so a regenerated instance replays identically — the genome regeneration principle [src: wiki/architecture/genome.md:13].

4. Engine modes

type EngineMode =
  | 'cinematic'   // scroll-scrubbed guided journey; full budget; behavior loops live
  | 'ambient'     // idle presence; reduced DPR + loop rate; camera drifts
  | 'suspended';  // tab hidden / reduced-motion / budget breach; loops paused, canvas frozen

Mode transitions are the kernel's obligation; the choice of mode per audience state is a cogni-spatial-site decision rule.

5. Performance gates

The kernel enforces the quality machinery of the implemented engine: quality tiers desktop | mobile, DPR step-down ladders (DPR_STEPS), and soft visible-splat ceilings SPLAT_BUDGET = { desktop: 700_000, mobile: 300_000 } [src: HOS-Instance/packages/engine/src/engine/contracts.ts:143,149]. Budgets and pass/fail thresholds are governed by bm-001-web-perf and bm-002-splat-budget; a slice that breaches budget must degrade (DPR step → asset tier → suspended mode), never stutter — "the experience should be pristine" [src: wiki/development/prompts-archive/by-topic/knowledge-management-and-concept-modeling.md:652].

Composition

See also

Linked from — 15 cards