rumpk/core/ontology.nim

# SPDX-License-Identifier: LSL-1.0
# Copyright (c) 2026 Markus Maiwald
# Stewardship: Self Sovereign Society Foundation
#
# This file is part of the Nexus Sovereign Core.
# See legal/LICENSE_SOVEREIGN.md for license terms.

# SPEC-060: System Ontology - Nim Bindings
# Ground Zero Phase 2: Event System

## Event System Nim Bindings

# Kernel logging (freestanding-safe)
proc kprint(s: cstring) {.importc, cdecl.}
proc kprint_hex(n: uint64) {.importc, cdecl.}
proc kprintln(s: cstring) {.importc, cdecl.}

# Import STL from HAL
proc stl_init*() {.importc, cdecl.}
proc stl_emit*(
  kind: uint16,
  fiber_id: uint64,
  entity_id: uint64,
  cause_id: uint64,
  data0: uint64,
  data1: uint64,
  data2: uint64
): uint64 {.importc, cdecl.}
proc stl_lookup*(event_id: uint64): pointer {.importc, cdecl.}
proc stl_count*(): uint32 {.importc, cdecl.}

type
  QueryResult* = object
    count*: uint32
    events*: array[64, pointer]

proc stl_query_by_fiber*(fiber_id: uint64, result: var QueryResult) {.importc, cdecl.}
proc stl_query_by_kind*(kind: uint16, result: var QueryResult) {.importc, cdecl.}
proc stl_get_recent*(max_count: uint32, result: var QueryResult) {.importc, cdecl.}

type
  LineageResult* = object
    count*: uint32
    event_ids*: array[16, uint64]

proc stl_trace_lineage*(event_id: uint64, result: var LineageResult) {.importc, cdecl.}

## Event Types (Mirror from ontology.zig)
type
  EventKind* = enum
    EvNull = 0
    # Lifecycle
    EvSystemBoot = 1
    EvSystemShutdown = 2
    EvFiberSpawn = 3
    EvFiberTerminate = 4
    # Capability
    EvCapabilityGrant = 10
    EvCapabilityRevoke = 11
    EvCapabilityDelegate = 12
    # I/O
    EvChannelOpen = 20
    EvChannelClose = 21
    EvChannelRead = 22
    EvChannelWrite = 23
    # Memory
    EvMemoryAllocate = 30
    EvMemoryFree = 31
    EvMemoryMap = 32
    # Network
    EvNetworkPacketRx = 40
    EvNetworkPacketTx = 41
    # Security
    EvAccessDenied = 50
    EvPolicyViolation = 51

## High-level API for kernel use

proc emit_system_boot*(): uint64 =
  ## Emit system boot event
  return stl_emit(
    uint16(EvSystemBoot),
    0,  # fiber_id (kernel)
    0,  # entity_id
    0,  # cause_id
    0, 0, 0  # data
  )

proc emit_fiber_spawn*(fiber_id: uint64, parent_id: uint64, cause_id: uint64 = 0): uint64 =
  ## Emit fiber spawn event
  return stl_emit(
    uint16(EvFiberSpawn),
    parent_id,
    fiber_id,
    cause_id,
    0, 0, 0
  )

proc emit_capability_grant*(
  fiber_id: uint64,
  cap_type: uint8,
  object_id: uint64,
  slot: uint32,
  cause_id: uint64 = 0
): uint64 =
  ## Emit capability grant event
  return stl_emit(
    uint16(EvCapabilityGrant),
    fiber_id,
    object_id,
    cause_id,
    uint64(cap_type),
    uint64(slot),
    0
  )

proc emit_channel_write*(
  fiber_id: uint64,
  channel_id: uint64,
  bytes_written: uint64,
  cause_id: uint64 = 0
): uint64 =
  ## Emit channel write event
  return stl_emit(
    uint16(EvChannelWrite),
    fiber_id,
    channel_id,
    cause_id,
    bytes_written,
    0, 0
  )

proc emit_access_denied*(
  fiber_id: uint64,
  resource_id: uint64,
  attempted_perm: uint8,
  cause_id: uint64 = 0
): uint64 =
  ## Emit access denied event (security)
  return stl_emit(
    uint16(EvAccessDenied),
    fiber_id,
    resource_id,
    cause_id,
    uint64(attempted_perm),
    0, 0
  )

## Initialization
proc init_stl_subsystem*() =
  ## Initialize the STL subsystem (call from kmain)
  stl_init()
  kprintln("[STL] System Truth Ledger initialized")

## Query API
proc stl_print_summary*() =
  ## Print a summary of the STL ledger to the console
  kprintln("\n[STL] Event Summary:")
  let total = stl_count()
  kprint("[STL] Total Events: "); kprint_hex(uint64(total)); kprintln("")
  
  var res: QueryResult
  
  # Boot Events
  stl_query_by_kind(uint16(EvSystemBoot), res)
  kprint("[STL]   SystemBoot: "); kprint_hex(uint64(res.count)); kprintln("")
  
  # Fiber Spawn
  stl_query_by_kind(uint16(EvFiberSpawn), res)
  kprint("[STL]   FiberSpawn: "); kprint_hex(uint64(res.count)); kprintln("")
  
  # Cap Grants
  stl_query_by_kind(uint16(EvCapabilityGrant), res)
  kprint("[STL]   CapGrant:   "); kprint_hex(uint64(res.count)); kprintln("")
  
  # Demonstrate Lineage Tracing for the last event
  if total > 0:
    let last_id = uint64(total - 1) 
    var lineage: LineageResult
    stl_trace_lineage(last_id, lineage)
    
    kprint("[STL] Lineage Trace for Event "); kprint_hex(last_id); kprintln(":")
    for i in 0..<lineage.count:
      let eid = lineage.event_ids[i]
      let ev_ptr = stl_lookup(eid)
      if ev_ptr != nil:
        # We can't easily access fields of Event struct from Nim if it's packed in Zig
        # but we know kind is at offset 0 (2 bytes)
        let kind = cast[ptr uint16](ev_ptr)[]
        kprint("  <- ["); kprint_hex(eid); kprint("] Kind="); kprint_hex(uint64(kind)); kprintln("")
      else:
        kprint("  <- ["); kprint_hex(eid); kprintln("] (Lookup Failed)")

  kprintln("[STL] Summary complete.")