The NomOS Machine ContractArchitecture & Causal Guarantees

Why Semantic Contracts Instead of Shell Access

The predominant architecture for coding and desktop AI agents is granting an LLM access to an unrestricted bash subshell. In that paradigm, safety relies entirely on probabilistic restraint: prompt directives instructing the model not to run dangerous commands. When errors occur, agents inspect process exit codes ($?) or parse unstructured terminal stdout.

This design has fatal vulnerabilities in workstation computing:

• Prompt Injection & Hallucination: An adversarial payload or confused reasoning model can emit destructive file manipulations or network exfiltration commands.
• False Proof of Success: An exit code of 0 indicates that a process exited cleanly, not that the system state was atomically committed, that settings survived crash boundaries, or that hardware accepted the configuration.
• Ambient Privilege Leakage: A shell inherits ambient environment variables ($PATH, $LD_PRELOAD, $HOME), making execution vulnerable to hijacked search paths and spoofed binaries.

Three Independent Identities & Invocation Authority

In NomOS, an Operation is never authorized simply because a caller knows its identifier and JSON schema. nom-api-runtime separates three distinct layers of identity before execution begins:

• Semantic Contract Revision: A deterministic content digest (SHA-256 hash) of the complete serialized semantic contract content (including identifiers, metadata, capability requirements, and schema definitions). It guarantees that client and system agree byte-for-byte on semantic contract content; it is not publisher authentication or a digital signature.
• Deployment Identity: The active, immutable NixOS system generation combined with the active Home Manager generation. Two generations may share a semantic contract revision while dispatching to different controller store paths.
• Acting Context: The kernel-level process credentials. nom-api-runtime resolves the acting user by calling getpwuid_r(geteuid()) to look up the process's effective UID directly through the system account database via Name Service Switch (NSS), rather than relying on direct /etc/passwd parsing. NomOS deliberately rejects caller-supplied environment variables ($USER, $HOME, $XDG_RUNTIME_DIR, or current working directory).

// Invocation Authority Resolution in nom-api-runtime:
1. Resolve effective UID through system account database via NSS: getpwuid_r(geteuid())
2. Derive trusted runtime paths directly from NSS passwd record:
   HOME            = passwd_entry.pw_dir
   XDG_RUNTIME_DIR = /run/user/<euid>
   USER_BUS_SOCKET = /run/user/<euid>/bus
3. Verify ownership: require /run/user/<euid> and bus socket owned strictly by <euid>
4. Match admitted NixOS deployment from /run/current-system and Home Manager profiles
5. Allocate private IPC pipe descriptor with single-use nonce for causal receipt
6. Launch fixed controller with reconstructed allowlisted environment (not general OS containerization)

Crash-Durable Persistence & The Three Storage Regions

For persistent-state operations modifying persistent settings (e.g., night-light.temperature.set modifying settings.nightlight.temperature), NomOS follows a strict atomic persistence sequence. Causal commit semantics are operation-specific (transient session adjustments or profile transitions follow their dedicated controller contracts). A mutation outcome is proven across the crash-durability boundary, conditional on successful filesystem and storage hardware fsync flush semantics (e.g., directory entry durability and storage write barrier guarantees):

State Mutation Sequence:
[Acquire Canonical Lock]
      ↓
[Write /home/user/.nomos/state.json.tmp]
      ↓
[fsync(temp_fd)]                      ← Region 1: Before commit point
      ↓
[os.replace(tmp_path, state.json)]     ← Region 2: The Ambiguous Window
      ↓
[fsync(containing_dir_fd)]             ← Region 3: Durable Commit Completed (storage barrier dependent)
      ↓
[Emit Private Causal Receipt over IPC Pipe]

NomOS explicitly models the three possible physical storage states:

• Region 1 (Failure before replacement): If the exclusion lock is contended, state validation fails, or writing the temp file errors out, NomOS proves the commit point was never reached. Outcome: failed with reason persistence-failed.
• Region 2 (The Ambiguous Window): Immediately before os.replace is invoked until fsync(dir) completes. If a power outage or SIGKILL interrupts execution here, the file may have been replaced on disk, but durability cannot be verified. NomOS refuses to report a false negative: outcome is strictly unknown with reason causal-proof-unavailable.
• Region 3 (Durable Commit): File synced, replaced, and containing directory synced (conditional on underlying filesystem and drive write cache fsync semantics). The storage controller emits a private, invocation-bound JSON receipt over the allocated pipe descriptor (verified with fresh nonce). It is a process-internal causal handshake, not a cryptographic attestation or digital signature. Outcome: established with effect persistent-state.

Closed Result Algebra & Refusal Envelopes

A NomOS mutation invocation produces exactly one of two self-contained JSON documents defined in canonical JSON Schema 2020-12:

1. InvocationError (Pre-launch Structural Refusal)

If input violates bounds, optional properties contain illegal types, or session authority cannot be resolved, execution halts before launching any controller. It returns an InvocationError. Crucially, this is not an outcome: failed, because the operation was never attempted.

2. OperationResult (Post-launch Causal Evaluation)

The outcome vocabulary in OperationResult is closed and strictly disjoint:

• established: Causally crossed the commit point. Must declare at least one verified effect (e.g. persistent-state, runtime-system). No failure reason allowed.
• failed: Controller proved the commit point was not crossed. Carries a closed reason code: persistence-failed, controller-unavailable, authorization-denied, or controller-rejected.
• unknown: No decisive proof reached the runtime receipt pipe. Carries causal-proof-unavailable or causal-proof-invalid.

Observed Evidence vs Saved Intent

A core architectural principle of NomOS is separating declared preference from runtime service state and physical hardware reality.

When an agent runs nom-inspect observe night-light:

• Declared Query (--query temperature): Reads what is durably stored in canonical configuration (e.g. temperature: 3800 K, on: false). This is declared human intent.
• Runtime Query (--query runtime): Queries the live systemd user daemon and compositor IPC. If Night Light is toggled off, runtime facts honestly report active: false and controllerTemperature: unavailable (night-light-inactive).
• Physical Display Output: Hardware display pipelines (CRTC gamma LUTs, external monitor firmware) cannot be reliably inspected without specialized photometers. The NomOS API states this limitation explicitly: it does not falsely claim proof of filtered physical photons.

Implementation Reality: What Ships vs Experimental

In accordance with NomOS verification rules, we provide exact transparency into what is currently implemented, what is experimental, and what remains future work: