%% SCRAP: architecture/03-architecture/word-acl/DESIGN
%% SOURCE: docs/working/architecture/03-architecture/word-acl/DESIGN.md
%% STATUS: CURRENT
%% FITS: dev-guide/ch-acl, cookbook/ch-acl
%% EDITORIAL: lifted — prose rewritten to press voice
%% PATENT: This subsystem describes potentially patentable mechanisms — the
%%   statistically-adaptive ACL TTL derived from SSM execution physics, the
%%   one-way pin ratchet, and the birth-time inheritance lattice. The prose below
%%   is descriptive only. It deliberately drafts NO patent claims (no
%%   independent or dependent claim language). Any claim drafting is reserved
%%   for Bob and patent counsel.

\section{Word-Level ACL System}

StarForth's word-level access control system combines a thin C infrastructure
layer with a pure-FORTH policy capsule, \texttt{ACL.4th}. The C layer supplies
four \texttt{DictEntry} fields for the hot path --- a TTL counter, an allow bit,
a mode, and a pin --- while all policy, all adaptive logic, and all inheritance
rules live as colon definitions in \texttt{ACL.4th}. A bootstrap superuser,
\texttt{zuse.4th}, provides the sole authenticated escalation path. The system
is implemented through Phase 6; Phase 7 (LithosAnanke parity) remains. The
implementation spans \texttt{capsules/ACL.4th}, \texttt{capsules/zuse.4th},
\texttt{src/word\_source/acl\_words.c}, and
\texttt{src/test\_runner/modules/acl\_words\_test.c}.

\subsection{Three Enforcement Dispositions}

Each dictionary word holds one of three dispositions:

\begin{tabular}{ll}
\toprule
State & Behavior \\
\midrule
\texttt{STRICT} & ACL re-checked on every execution \\
\texttt{TTL} & ACL cached; re-checked only when the TTL counter reaches zero \\
\texttt{PINNED} & Mode and decision frozen permanently; a one-way ratchet \\
\bottomrule
\end{tabular}

\subsection{Statistically Adaptive TTL}

%% PATENT: The adaptive-TTL mechanism below is patent-adjacent. Descriptive only.

The TTL is not a fixed value. It is derived and continuously updated from the
existing SSM execution physics. Hotter words (higher \texttt{execution\_heat})
earn longer TTLs, amortizing check cost over more executions. A sudden shift in
caller pattern or access rate, detected through the rolling window, shrinks the
TTL aggressively. Decay pulls a quiescent word's TTL back down so the next
burst re-validates early. The inference engine (Loops L5/L6) detects an
oscillating TTL and stabilizes it, using the same coefficient-of-variation
threshold logic already employed for window-width inference. \texttt{PINNED} is
the asymptote: once the adaptive process converges, the operator thumbtacks it
and the accumulator freezes permanently. A security word selects the mode per
word:

\begin{lstlisting}[language=Forth]
' MY-WORD ACL-STRICT      \ check every execution
' MY-WORD ACL-TTL-MODE    \ use adaptive TTL
' MY-WORD ACL-PIN         \ freeze -- mode and decision immutable forever
\end{lstlisting}

\subsection{The Pin Ratchet}

%% PATENT: The one-way pin ratchet is patent-adjacent. Descriptive only.

\texttt{ACL-PIN ( xt -- )} is a one-way ratchet. It transitions \texttt{STRICT}
or \texttt{TTL} to \texttt{PINNED} and never back. Once pinned, a word's
\texttt{acl\_mode} and \texttt{acl\_ttl} are immutable within that VM context,
and any attempt to alter a pinned word's ACL is silently ignored or errors,
depending on policy. Kernel primitive words --- \texttt{BIRTH}, \texttt{EXEC},
\texttt{BYE}, and the like --- are pinned by Mama at boot before the first
\texttt{BIRTH} fires.

\subsection{Inheritance at Birth}

%% PATENT: The birth-time inheritance lattice is patent-adjacent. Descriptive only.

When a child VM is born, ACL state propagates downward once:

\begin{lstlisting}[language=Forth]
acl_mode     = parent->acl_mode    \ policy propagates (STRICT or TTL)
acl_pinned   = 0                   \ always clear -- child owns its own lock
acl_ttl      = default             \ reset; child has no execution history
acl_decision = ALLOW               \ re-evaluated on first access
\end{lstlisting}

Two properties govern the design. The pin is contextual, not viral: a parent's
pinned words do not force the child to be pinned --- the child inherits the mode
as a starting point and may tighten, relax, or re-pin freely. The security
lattice flows downward at birth only; afterward each VM's ACL state is
independent, so a compromised child cannot bootstrap its way back to Mama's
pinned ACLs.

\subsection{Interpreter Hook: Two-Level Check}

The C interpreter reads only two fields per \texttt{DictEntry}:

\begin{lstlisting}[language=C]
if (vm->emergency_console) goto execute;   /* 100% bypass -- physical access */
if (entry->acl_ttl-- > 0) goto execute;    /* TTL good -- single decrement   */
acl_recheck(vm, entry);                    /* TTL=0: call FORTH ACL-RECHECK  */
if (!entry->acl_allow) goto reject;
\end{lstlisting}

The hot path costs one decrement and a branch --- essentially free. The cold
path calls \texttt{ACL-RECHECK} in \texttt{ACL.4th}, which recomputes the
adaptive TTL, updates \texttt{acl\_allow}, and resets the counter. The C side
never reasons about policy; it only reads the result.

\subsection{Two-Console Architecture}

Two permanent, independent console layers exist at all times.

The \textbf{emergency console} is always present. Its \texttt{emergency\_console}
flag (a \texttt{uint8\_t} in the \texttt{VM} struct) is written only by C ---
no FORTH word sets it --- and is checked first in the interpreter hot path,
producing a 100\% ACL bypass; \texttt{acl\_recheck()} saves and restores it for
re-entrancy protection. The \texttt{EMERGENCY\_CONSOLE\_ENABLED} build flag
(default 1) strips the interactive fallthrough when set to 0, calling the weak
\texttt{vm\_fault\_handler()} symbol instead (overridable for hardware reset,
watchdog, or debug probe). \texttt{BYE} returns to the emergency console; only
\texttt{panic} kills the VM; the prompt is \texttt{ok>}.

The \textbf{Zuse console} is omnipresent and awaits authentication. Its
\texttt{zuse\_session} flag (also a C-only \texttt{uint8\_t}) grants a full ACL
bypass when a Zuse session is active. The prompt is \texttt{zuse)ok>}. The two
consoles are completely independent --- setting one does not affect the other.

\subsection{Superuser: Zuse}

Named for Konrad Zuse, pioneer of programmable computers, Zuse is the bootstrap
superuser --- the sole entity that can own the Zuse console and mint user
credentials. It is defined in \texttt{capsules/zuse.4th} and loaded by
\texttt{ACL.4th} at capsule boot. For now it is software-only (no thumbdrive),
yet a capsule citizen from day one. Zuse's words are pinned by
\texttt{ACL-ZUSE-BOOT} at load time. \texttt{ACL-BOOT} runs first, then
\texttt{S" zuse.4th" EXEC}, both from within \texttt{ACL.4th} itself (Block
2067). In future, thumbdrive PKI (Ed25519 challenge-response) will replace the
software path, with \texttt{zuse.4th} becoming the bootstrapper that validates
the physical drive.

\subsection{CA Root}

The certificate-authority root is embedded in \texttt{ACL.4th} (Block 2066) as
the constants \texttt{ACL-CA-KEY-LO} and \texttt{ACL-CA-KEY-HI}. Because the
capsule hash serves as the root-of-trust fingerprint, any change to the CA key
changes the capsule hash, and the birth protocol detects the tampering. The key
is a zero placeholder until \texttt{tools/mkcapsule} embeds the real Ed25519 key
at build time.

\subsection{Security Model and No-Security Condition}

Security is opt-in through \texttt{init.4th}, gated by a single commented-out
line:

\begin{lstlisting}[language=Forth]
\ S" ACL.4th" EXEC
\end{lstlisting}

\begin{tabular}{lll}
\toprule
\texttt{ACL.4th} & \texttt{zuse.4th} & Result \\
\midrule
absent & absent & No security --- open dev mode \\
present & absent & ACL enforced; emergency REPL locked until Zuse provisioned \\
present & present & Full lockdown; Zuse owns the Zuse console \\
\bottomrule
\end{tabular}

Uncommenting the line enables full lockdown; leaving it commented keeps a
development build open.

\subsection{Self-Activating Capsule}

\texttt{ACL.4th} is self-activating --- \texttt{init.4th} needs only
\texttt{S" ACL.4th" EXEC}. Internally, Block 2066 holds the CA root placeholder
constants and Block 2067 calls \texttt{ACL-BOOT} and then
\texttt{S" zuse.4th" EXEC}. \texttt{ACL-BOOT} stamps default ACL entries onto
every existing dictionary word; after it runs, each subsequent \texttt{:}
definition receives an ACL entry through the defining-word hook, so no word can
exist without one.

\subsection{ACL.4th: Pure-FORTH Implementation}

The ACL table is a \texttt{CREATE}d FORTH array indexed by execution token
(XT); \texttt{'} (tick) yields the XT of any word, and the XT is simply a cell
value usable as a table key.

\begin{tabular}{lll}
\toprule
Word & Stack & Description \\
\midrule
\texttt{ACL-ENTRY} & \texttt{( xt -- addr )} & O(1) table lookup by XT \\
\texttt{ACL-MODE@} & \texttt{( xt -- mode )} & Read enforcement mode \\
\texttt{ACL-MODE!} & \texttt{( mode xt -- )} & Set mode (no-op if pinned) \\
\texttt{ACL-PINNED?} & \texttt{( xt -- flag )} & Test pin bit \\
\texttt{ACL-PIN} & \texttt{( xt -- )} & Set pin --- one-way, irreversible \\
\texttt{ACL-STRICT} & \texttt{( xt -- )} & Set STRICT mode (no-op if pinned) \\
\texttt{ACL-TTL-MODE} & \texttt{( xt -- )} & Set TTL mode (no-op if pinned) \\
\texttt{ACL-TTL@} & \texttt{( xt -- n )} & Read current TTL counter \\
\texttt{ACL-TTL!} & \texttt{( n xt -- )} & Write TTL counter \\
\texttt{ACL-ALLOW@} & \texttt{( xt -- flag )} & Read cached decision \\
\texttt{ACL-ALLOW!} & \texttt{( flag xt -- )} & Write decision \\
\texttt{ACL-INHERIT} & \texttt{( src dst -- )} & Copy mode, clear pin, reset ttl+decision \\
\texttt{ACL-RECHECK} & \texttt{( xt -- )} & Adaptive TTL recompute; update allow + new TTL \\
\texttt{ACL-INIT-PRIMITIVES} & \texttt{( -- )} & Bulk-initialize entries for all existing words \\
\bottomrule
\end{tabular}

A typical boot-time pin in \texttt{init.4th}:

\begin{lstlisting}[language=Forth]
' BIRTH  ACL-STRICT  ' BIRTH  ACL-PIN
' EXEC   ACL-STRICT  ' EXEC   ACL-PIN
' BYE    ACL-STRICT  ' BYE    ACL-PIN
\end{lstlisting}

\subsection{Bootstrap Sequence}

\begin{lstlisting}[language=Forth]
\ In init.4th (one line, opt-in toggle -- uncomment to enable):
S" ACL.4th" EXEC       \ self-activating: ACL-BOOT then loads zuse.4th

\ ACL.4th Block 2067 does internally:
ACL-BOOT               \ stamp default ACLs on all existing words
S" zuse.4th" EXEC      \ load and pin Zuse's words

\ Subsequent capsule loads get ACL entries via the : hook
S" doe.4th" EXEC
\end{lstlisting}

Every \texttt{:} definition after \texttt{ACL-BOOT} creates its own ACL entry at
definition time via the defining-word hook, so no word is ever born without one.

\subsection{Capsule Namespace}

\begin{tabular}{ll}
\toprule
File & Role \\
\midrule
\texttt{init.4th} & Mama VM personality (default); contains the opt-in toggle \\
\texttt{init-*.4th} & Alternate personalities \\
\texttt{doe.4th} & DoE experiment harness \\
\texttt{ACL.4th} & Word-level ACL subsystem; self-activating; loads \texttt{zuse.4th} \\
\texttt{zuse.4th} & Bootstrap superuser; words pinned by \texttt{ACL-ZUSE-BOOT} \\
\texttt{std-blob.4th} & Standard library layer (future) \\
\bottomrule
\end{tabular}

\subsection{Implementation Status}

Phases 1 through 6 are complete on \texttt{master}. Phase 1 added the four
\texttt{DictEntry} fields (\texttt{acl\_ttl}, \texttt{acl\_allow},
\texttt{acl\_mode}, \texttt{acl\_pinned}), the \texttt{emergency\_console} and
\texttt{zuse\_session} VM flags, the two-level interpreter check, and
\texttt{acl\_recheck()} with re-entrancy protection. Phase 2 delivered the
twelve C primitive words, the XT-indexed table, the field accessors, the pin
ratchet, the mode setters, \texttt{ACL-INHERIT}, \texttt{ACL-RECHECK},
\texttt{ACL-INIT-PRIMITIVES}, and the pinning of privileged words. Phase 3 made
\texttt{ACL.4th} self-activating with the CA placeholder and Zuse load. Phase 4
added the \texttt{init.4th} opt-in toggle. Phase 5 contributed POST tests in
\texttt{acl\_words\_test.c} (800/800 passing) covering pin monotonicity,
inheritance, emergency bypass, STRICT and TTL behavior, the adaptive
accumulator, and persistence of boot-time pins. Phase 6 added five Isabelle/HOL
proofs:

\begin{itemize}
  \item \texttt{ACL\_Pin\_Monotone.thy} --- the pin bit is set-only; no
    operation clears it once set.
  \item \texttt{ACL\_Inherit\_Clears\_Pin.thy} --- \texttt{ACL-INHERIT} always
    produces an entry with \texttt{acl\_pinned = 0}, regardless of source state.
  \item \texttt{ACL\_TTL\_Bounded.thy} --- the TTL counter is bounded above by
    \texttt{ACL-TTL-COMPUTE} output and cannot grow unboundedly.
  \item \texttt{ACL\_Emergency\_Bypass.thy} --- when
    \texttt{emergency\_console = 1}, the allow/deny decision is never consulted.
  \item \texttt{ACL\_No\_Escalation.thy} --- a child VM cannot produce a pinned
    entry with higher privilege than its inherited mode.
\end{itemize}

\subsection{Remaining Work}

Phase 7 (LithosAnanke parity) ports the subsystem to the
\texttt{lithosananke} branch: verifying that \texttt{ACL.4th} loads cleanly in
the freestanding kernel context, running \texttt{ACL-BOOT} at kernel boot before
the first \texttt{BIRTH}, wiring \texttt{vm->emergency\_console} and
\texttt{vm->zuse\_session} to the kernel REPL and Zuse authentication paths, and
achieving three-architecture acceptance (amd64, aarch64, riscv64 booting to
\texttt{ok>} with ACL active and no regressions), with acceptance logs
committed. Phase 8 (future) introduces thumbdrive PKI: Ed25519
challenge-response for the Zuse drive, build-time embedding of the real CA key
into Block 2066, CA-signed user minting with a home-block image, and a
deliberate no-software-recovery policy --- lose the drive and the administrator
mints a new one.

%% PATENT: Phase 8 PKI / thumbdrive authentication is patent-adjacent. Described
%%   descriptively only; no claim language drafted.
