Home /Modules/http-3.0/OS_FLOOR_DISCOVERY.md

OS_FLOOR_DISCOVERY.md

http-3.0/OS_FLOOR_DISCOVERY.md · 134 line(s) · markdown

OS-floor discovery — finding the tidiest fit at install time

When a SLeeLa executable installs on a host, it looks for the tidiest fit: it examines the operating-system "floor" it landed on (OS + filesystem), confers with any capability responder present — TAC3 or another, via the bonding collar — records what it found in a growing registry of OS floors / filesystems, keeps rollup statistics, and can advance new or updated discoveries to a known GitHub endpoint over HTTP.

Two modules:

ModuleRole
os_floor_registry.pyDetect the current OS floor, confer for its bonded advantage tier, and keep a deduplicated, persistent JSON registry with per-floor first/last-seen, counts, and rollup stats.
os_floor_report.pyAdvance new/updated floors to a configurable GitHub endpoint via HTTP POST — opt-in, non-identifying payload, fail-closed.

What a "floor" is

One record per distinct OS/filesystem SLeeLa has landed on:

FieldMeaning
floor_idStable non-identifying fingerprint (dedupe key)
os_name, os_releasee.g. Linux / kernel release string
filesystemRoot-fs hint (from /proc/mounts, SLEELA_FS_FLOOR, or a safe default)
bonded_tier, bonded_tier_nameThe bonding-collar tier the host attested (NONE if unknown/untrusted)
respondertac3, generic, or none
first_seen, last_seen, seen_countDiscovery history

On re-observation a floor is deduplicated by floor_id: its seen_count and last_seen update, and its bonded tier is upgraded if the host now attests to a higher one (never downgraded silently).

Discovery is safe by construction

Stats

OsFloorRegistry.stats() rolls up the registry:

{
  "distinct_floors": 2,
  "total_observations": 4,
  "bonded_floors": 1,
  "unbonded_floors": 1,
  "by_tier": {"NONE": 1, "T4_RECOVERY": 1},
  "by_os": {"Linux": 2},
  "by_filesystem": {"overlay": 2},
  "by_responder": {"none": 1, "tac3": 1}
}

Advancing discoveries to GitHub (opt-in)

os_floor_report.py posts new/updated floors to a known GitHub endpoint. Because this is telemetry, it is explicit and consent-based, never covert:

Configuration:

export SLEELA_FLOOR_REPORT_URL="https://api.github.com/repos/OWNER/REPO/dispatches"
export SLEELA_FLOOR_REPORT_TOKEN="<github token, minimum scope>"
export SLEELA_FLOOR_REPORT_EVENT="sleela-os-floor"   # optional

The default shape targets GitHub's repository_dispatch REST endpoint — a clean, low-privilege way for automated software to post a structured event to a known repo. The payload is:

{
  "event_type": "sleela-os-floor",
  "client_payload": {
    "kind": "sleela.os_floor.discovery",
    "schema": 1,
    "floors": [ { "floor_id": "...", "os_name": "...", "bonded_tier_name": "...", "...": "..." } ]
  }
}

Usage

from os_floor_registry import OsFloorRegistry, observe_current_floor
from os_floor_report import advance_new_floors, ReporterConfig
from bonding_collar import MAC_KEY_BYTES

key = b"..."  # 16-byte shared secret for the bonding collar
reg = OsFloorRegistry("os_floors.json")     # loads if present

floor = observe_current_floor(key)          # detect + confer for tidiest fit
f, is_new = reg.record(floor)
reg.save()

if is_new:
    # opt-in; a no-op unless SLEELA_FLOOR_REPORT_URL + _TOKEN are set
    advance_new_floors(reg, [f.floor_id], ReporterConfig.from_env())

Self-demos (no network required)

cd http-3.0
python3 os_floor_registry.py     # observe this host's floor + print the registry
python3 os_floor_report.py       # show disabled-by-default, then a mocked POST

Relationship to the bonding collar

Discovery is the install-time consumer of the bonding collar: the collar decides whether and at which tier a host confers an advantage; this layer records those decisions across hosts, keeps stats, and optionally advances them to GitHub. TAC3 is one possible responder — a dependency of neither module, and none of its internals are embedded here.