%% SCRAP: architecture/PHYSICS_SIGNAL_MAP
%% SOURCE: docs/working/architecture/PHYSICS_SIGNAL_MAP.adoc
%% STATUS: WORKING
%% FITS: dev-guide/app-physics, cookbook/app-physics
%% EDITORIAL: lifted — prose rewritten to press voice

\section{Physics Signal Inventory}

This inventory enumerates the telemetry the physics-driven scheduler can sense
today, drawn from two sources: the L4Re microkernel (through the StarshipOS loader
stack) and the in-process StarForth VM. It defines the input stage of the
scheduler. The guiding metaphor is an operational amplifier: the positive input
ties to real host signals, the negative input ties to VM-internal counters, and a
Bayesian inference loop stabilizes the gain. The metaphor is a modeling device for
the control architecture, not a literal circuit.

\subsection{L4Re and Microkernel Signals}

\paragraph{Kernel Interface Page (KIP).} The KIP exposes a high-resolution monotonic
clock (\texttt{l4\_kip\_clock\_ns()}) for timing when no RTC is present, a kernel
build fingerprint for correlating inference data with kernel revisions, the
scheduling granularity (an upper bound on how fine-grained the physics scheduler can
react), physical memory descriptors (how much RAM can be earmarked for in-RAM
inference buffers), and platform/SMP information. SMP availability doubles as a noise
hook: work can be scheduled on sibling cores to inject controlled jitter and keep the
model honest.

\paragraph{Scheduler object.} \texttt{l4\_scheduler\_info()} reports the online CPU
bitmap and maximum CPU count, bounding how many physics loops run in parallel.
\texttt{l4\_sched\_param\_t} (priority and quantum) records the loader's configured
timeslice as a prior per VM. The scheduler-class flags reveal whether fixed-priority
or weighted-fair-queue scheduling is active, which shapes how aggressively words may
be heated or cooled. \texttt{l4\_sched\_cpu\_set()} pins the main or physics worker
thread to a core subset during experiments.

\paragraph{Loader and environment capabilities.} The loader script
(\texttt{quark.lua}) wires named capabilities the runtime can tap: \texttt{vbus\_storage}
for block-device enumeration and driver statistics (queue depth, error counts);
\texttt{ahci\_chan} for completion-interrupt rates and per-port error registers;
\texttt{rtc\_ns} for wall-clock sync; \texttt{cons\_mux} for console input cadence as
a proxy for interactive heat; \texttt{L4.Env.log} for scheduler and hardware warnings
that should bias temperature decay; and \texttt{L4.Env.vesa} for framebuffer
refresh/blit latency.

\paragraph{Further kernel APIs.} \texttt{l4\_thread\_control()} and
\texttt{l4\_thread\_ex\_regs()} expose per-thread UTCB pointers and instruction
pointers for correlating VM stalls with kernel scheduling; \texttt{l4\_ipc\_error()}
surfaces IPC failure codes that could feed entropy penalties for fault-prone words;
and virtual IRQ devices can be counted to derive environmental noise injected into the
VM.

\subsection{StarForth VM Signals}

\paragraph{Core runtime state.} \texttt{DictEntry.entropy} is the per-word execution
counter, the baseline for macro temperature. \texttt{DictEntry.physics} holds the
tunable knobs (temperature, last-active timestamp, mass). The data and return stack
pointers (\texttt{VM.dsp}, \texttt{VM.rsp}) report stack depth, whose steep excursions
imply turbulent execution and feed variance estimates. Mode and state fields reveal
interpret-versus-compile state and the currently executing word. The \texttt{error}
and \texttt{halted} flags are binary fault signals that spike entropy decay when they
flip. Log volume and severity mix are themselves telemetry: heavy warnings can cool
risky words.

\paragraph{Profiler and instrumentation.} \texttt{WordProfile} supplies per-word total
time, call count, and min/avg/max latency --- a direct feed for \texttt{avg\_latency\_ns}
and Bayesian likelihoods. \texttt{MemoryProfile} supplies read/write counts and bytes
as a mass-energy proxy for memory-thrashing words. The profiler counters (VM cycles,
dictionary lookups, stack ops, allocations) seed default temperatures and heat
capacities. \texttt{profiler\_word\_count()} stays available even without detailed
profiling, and \texttt{vm\_debug\_dump\_state()} provides a structured post-mortem the
Bayesian tool can parse to reset priors after a crash.

\paragraph{Block and storage subsystem.} Block-subsystem globals report working-set
size, dirty-block counts, and block-allocation-map churn. \texttt{blkio\_info()}
exposes device geometry and the read-only bit, informing whether a cooling word should
migrate to RAM or disk tiers. \texttt{blkio\_read}/\texttt{write} return codes give
immediate error feedback. Cache slots track hit/miss rate and write-back frequency to
infer subsystem momentum.

\subsection{Op-Amp Signal Flow}

The signal flow follows the amplifier metaphor in five stages:

\begin{enumerate}
  \item \textbf{Positive input (microkernel)} --- real-world noise: CPU availability,
        I/O latency, RTC drift, IRQ storms.
  \item \textbf{Negative input (VM)} --- internal state: entropy, latency, stack
        tension, storage dirty set.
  \item \textbf{Amplifier} --- the Bayesian inference loop adjusts priors and updates
        word physics.
  \item \textbf{Output} --- updated \texttt{DictPhysics} structs and scheduler hints
        that modulate execution order and block placement.
  \item \textbf{Feedback} --- the observation window width is adjusted by variance (a
        gauge study) and the cycle repeats.
\end{enumerate}

\subsection{Messaging and IPC Considerations}

The pub/sub backbone is shared-memory-first: a ring buffer with sequence counters
inside a dedicated analytics heap (10~MiB by default). Producers write events, flip a
counter, and continue, with no blocking semantics inside the VM. On L4Re, where IPC is
synchronous, IPC serves only as a notification channel --- a publisher pokes a
notification thread that drains the ring and forwards to subscribers; virtual IRQs
offer an alternative non-blocking wakeup. On Linux the same API is backed by condition
variables or eventfd behind a common shim, keeping the VM path identical across
platforms. All state stays resident in a fixed-size analytics heap with no dynamic
expansion. That heap is separate from the 5~MiB VM arena (\texttt{VM\_MEMORY\_SIZE}),
so the dictionary, stacks, and block-subsystem budgets remain untouched.

\subsection{Host Snapshot Shim and Analytics Heap}

Phase~1 ships a concrete implementation. \texttt{physics\_runtime\_init()} reserves the
analytics heap (10~MiB default) whose layout the HOLA contract documents, publishing
the header and region descriptors HOLA consumes. \texttt{physics\_host\_snapshot()}
abstracts POSIX and L4Re scheduler probes and feeds ring-buffer events on channel
\texttt{0x00000002} via \texttt{physics\_analytics\_publish\_event()}. The heap header,
event records, and mailbox schema live in \texttt{include/physics\_runtime.h}; the
runtime lives in \texttt{src/physics\_runtime.c}. The interface is deliberately
ABI-stable so governance tooling can mirror it without pulling in C sources. On the
POSIX path, Phase~1 additionally captures Linux PSI values mapped into
\texttt{psi\_*\_avg\{10,60,300\}\_milli}, \texttt{/proc/stat} total and idle jiffies,
and cgroup~v2 CPU and memory usage where available; flag bits advertise which sources
were populated.

\subsection{Conventions and Constraints}

Several conventions govern the inference loop. The observation window combines a
time-based heartbeat with event-count triggers: events act as ``excitement'' that
boosts entropy, while publish and decay operations cool at roughly half that rate
(tunable). All computation uses 64-bit fixed-point integers. Physics snapshots can
optionally be persisted into FORTH block storage and reloaded during \texttt{(INIT)}
to simulate a warm boot or replay a training sequence. Descriptor inheritance flows
from module, vocabulary, and VM defaults down to individual words, so sensible priors
seed at multiple levels; every tier exposes the same attribute schema --- temperature,
latency, mass, state flags, ACL hints, pub/sub mask, and pinned flag. VM-level rollups
mirror per-word metrics and define operating bands (\texttt{COLD}, \texttt{WARM},
\texttt{HOT}, \texttt{CRITICAL}) that governance and the scheduler shim can respond to.
Isabelle captures the formal state machine, invariants, and IPC-handshake proofs;
HOLA defines the shared-memory layout and control protocol consumed by both the VM
and external analyzers.

A primitive seed table (\texttt{physics\_metadata\_apply\_seed()}) installs initial
priors for high-impact primitives --- control flow, I/O, block subsystem, save-system
--- so temperature and latency estimates do not start at absolute zero; governance
tooling can extend or override the table once the Bayesian loop is in place.

\subsection{Immediate Research Tasks}

\begin{enumerate}
  \item Prototype a thin KIP/scheduler shim exposing the listed signals to userland C
        with no filesystem: on L4Re via \texttt{l4re\_kip()}, on POSIX via a stub that
        feeds monotonic time and scheduler defaults.
  \item Inventory the IO-server (vbus) protocol to pull queue-depth and error counters
        for AHCI, NVMe, and virtio backends.
  \item Define the shared-memory layout between the VM and the Bayesian analyzer,
        defaulting to a 10~MiB heap (header, $\sim$6~MiB event ring, $\sim$3~MiB
        summary/scratch, padding), honoring the platform split between POSIX and L4Re
        messaging.
  \item Extend the profiler to snapshot \texttt{MemoryProfile} deltas without enabling
        full verbose mode, keeping overhead low.
  \item Derive initial priors for key primitives (control, I/O, block) from handcrafted
        knowledge plus the loader's priority and quantum configuration.
\end{enumerate}

%% TODO(bob): The source "Morning Pickup Notes" list ends with an unresolved item
%% ("Something else I can't recall") and a reminder to generate formal docs for the
%% Governance Repository. Confirm what the missing item was before this scrap is
%% promoted to a finished chapter.