applyProviderErrorContext(error, context = {})

providerResponseModel(value, fallback = '')

providerModelAttribution({ provider = '', requestedModel = '', responseModel = '' } = {})

canonicalProviderToolCalls(payload, providerTools = [], transport = 'provider-native')

createProviderToolStreamAccumulator(providerTools = [], transport = 'provider-native-stream')

buildOpenAICompatibleBody(spec, providerDefinition = null)

providerHttpError(json, status, provider = '', responseMetadata = null)

providerOutputError(code, provider, message, retryable = true, responseMetadata = null)

providerChoiceError(json, status, provider = '', responseMetadata = null)

assertUsableProviderOutput({ message = '', reasoning = '', toolCalls = [], provider = '', strictOutput = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Pure OpenAI compatible request/response helpers shared by the privileged extension transport and the browser direct mobile fallback. This module performs no storage, network, DOM, or chrome. work. Functions Stable public diagnosis family; never contains provider controlled text. Attach only bounded, structured clone safe diagnostic correlation fields. Normalize a provider model identifier without trusting arbitrary text. Keep the requested route separate from provider reported attribution. remains backward compatible, but modelEvidence makes an omitted or dynamic alias explicitly non concrete so callers cannot mistake a request fallback for observed provider output. Normalize the provider facing projection of locally authoritative OS tools. These definitions help a model form typed calls; they never grant execution authority, which remains with the descriptor hash, graph validator, and ToolRouter after the provider response returns. Convert completed native provider calls into one provider neutral batch. Accumulate provider tool call stream fragments without executing partial arguments. ID/name conflicts and malformed mixed batches fail atomically. Construct the only provider originated Error shape allowed to cross the AI bridge. Endpoint URLs, headers, response bodies, request content, and keys are deliberately excluded. Retryability is asserted only for unambiguous transient HTTP classes; every other status remains unclassified so the Navi broker can apply its own fail closed policy. Return a bounded structured clone safe view of an AI provider failure. Constants — Pure OpenAI compatible request/response helpers shared by the privileged extension transport and the browser


safe view of an AI provider failure. Constants — Pure OpenAI compatible request/response helpers shared by the privileged extension transport and the browser direct mobile fallback. This module performs no storage, network, DOM, or chrome. work. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ResidentService.js — manages the resident SecureMesh node (offscreen document). Exposed via the bridge router (service name ) so the trusted OS page can query/toggle it, and via dedicated messages for the popup. Keeps an offscreen document alive (MV3's persistent WebRTC capable context) using a chrome.alarms keep alive that respawns the service worker to re ensure the doc exists. Privacy: this only ever stores the PUBLIC cert bundle the OS page pushes (pub key, name, room) — never the identity private key. It is OFF by default and fully user controlled. Real background mesh reachability is NOT attempted here (keep an OS tab open for that); this is a lightweight cert vault + keepalive responder. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: RuleService.js — declarativeNetRequest dynamic rule manager for the OS bridge. Runs in the extension background service worker context. User added rules use IDs = 50000 to avoid colliding with the built in frame unblock rules (IDs 100 102). Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Validate and compact one AI Echo browser semantic request before it crosses the extension boundary. Unknown fields fail closed so the protocol cannot silently grow into a generic page execution channel. Packaged Chrome scripting entry point. This function is intentionally self contained because chrome.scripting serializes the function body into the target tab; it cannot close over extension service worker state. Constants <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TabService.js — chrome.tabs wrapper for the OS bridge. Runs in the extension background service worker context. Constants — TabService.js — chrome.tabs wrapper for the OS bridge. Runs in the extension background service worker context. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Exact OS origins trusted with privileged browser bridge authority. Functions Constants — Exact OS origins trusted with privileged browser bridge authority. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WebMCPBridgeRuntime.js clean room, versioned adapter between AI Echo and the browser's evolving WebMCP surface. Page owned metadata and results are always untrusted. The extension never exposes callbacks, Window objects, or credentials across the OS bridge. Functions Validate one bridge request before any page script is dispatched. Packaged Chrome scripting entry point. It deliberately feature detects the origin trial API, because WebMCP is still a Community Group draft and the browser execution helper is not yet part of the portable specification. Constants — WebMCPBridgeRuntime.js clean room, versioned adapter between AI Echo and the browser's evolving WebMCP surface. Page owned metadata and results are always untrusted. The extension never exposes callbacks, Window objects, or credentials across the OS bridge. <! HUMAN NOTES Notes & Examples No hand authored notes yet. Add page notes in or a reusable block in — see API Reference Standard.


drivers/AudioDriver.js

drivers/AudioDriver.js
Classes
class AudioDriver
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AudioDriver.js — the OS audio server (kernel service). Provides system wide audio output routing, a per app volume mixer, output device switching, OS level media transport (navigator.mediaSession), and opt in spatial (window position) panning. Mirrors the kernel service pattern of AmbientEngine / ThemeEngine: created in KernelBootstrap, exposed via createAudioSyscalls() in Syscalls.js, guarded per app in guardSyscalls(). ── Two routing models ────────────────────────────────────────────────────────── 1. Shared context routing (true central mix): apps hand the driver an <audio /<video element (attachElement) or an AudioNode built in the OS context (context() + attachNode). The driver builds: source → sessionGain → analyser → stereoPanner → masterGain → destination(setSinkId) 2. Cooperative sessions: apps that keep their own AudioContext register with an onVolume(effective, muted) / onPan(pan) callback. The driver cannot touch their nodes, so it calls the callback whenever the user changes master/app volume, mute, or pan, and the app applies it to its own graph. Everything no ops safely before the first user gesture (autoplay policy) and on browsers without setSinkId / mediaSession. ── Events ────────────────────────────────────────────────────────────────────── kernel.events.emit('os:audio change', { type }) // 'sessions' 'master' 'devices' 'spatial' Classes Method Signature Summary Desktop calls this to let the driver locate a window for spatial panning. Lazily create the shared context + master chain. Returns the context or null. Returns the shared AudioContext (creating it if needed). For app node routing. Register a controllable audio source. Ensure a session's shared context


drivers/AudioDriver.js

or null. Returns the shared AudioContext (creating it if needed). For app node routing. Register a controllable audio source. Ensure a session's shared context node chain exists; returns its input GainNode. Route an <audio /<video element through a session (shared context mixing). Route an arbitrary AudioNode (built in the OS context) through a session. RMS output level (0..1) for a shared context session, else 0. Invoke a transport action on a session ('play' 'pause' 'next' 'prev' 'seek'). Most recently updated session that has playback metadata. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/CryptoDriver.js

drivers/CryptoDriver.js
Classes
class CryptoDriver
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CryptoDriver.js — OS level cryptographic identity driver. Wraps CollabIdentity (ECDSA P 256) and exposes a simple API: Persistent key pair stored in IndexedDB (survives page reload) Same fingerprint = same user across sessions sign(data) → ECDSA signature bytes verify(pubKeyRaw, data, sig) → boolean publicKeyRaw / fingerprint → identity Used by: kernel/Syscalls.js → syscalls.crypto. chat room → signed messages (tamper evident + authenticated) future game systems → anti cheat signed receipts, session proofs Classes Method Signature Summary Initialise — loads or generates the persistent ECDSA P 256 identity. True if SubtleCrypto is available and the identity was created successfully. True if the key pair will survive page reload (IndexedDB). 65 byte raw ECDSA P 256 public key. 16 hex char SHA 256 fingerprint of the public key. Sign a string with ECDSA P 256. Verify an ECDSA P 256 signature. Compute a 16 char fingerprint from any raw public key. Useful for displaying who sent a signed message. Sign raw bytes with ECDSA P 256. Counterpart to sign() for binary payloads. Verify an ECDSA P 256 signature over raw bytes. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually


drivers/CryptoDriver.js

only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/EmbeddedParticleNode.js

drivers/EmbeddedParticleNode.js
Classes
class EmbeddedParticleNode
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes One embedded Particle node per browser profile. Resident availability and temporary supernode/witness roles are facets of this same node identity. Method Signature Summary <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/NetDriver.js

drivers/NetDriver.js
Classes
class NetDriver
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: NetDriver.js — Phase 5 network driver for WebGPU OS. Tiered transport (fastest wins): Tier 1 — BroadcastChannel (same origin tabs, <1ms, always available) Tier 2 — WebRTC full mesh via CollabCore + pinned Particle V2 signaling (cross machine). BitTorrent remains an explicit, off by default hard fallback. Public API (mirrored by kernel/Syscalls.js net namespace): connect(roomId, opts) — join a named room disconnect() — leave current room send(channel, data) — broadcast to all peers sendTo(peerId, channel, data) — unicast to specific peer on(channel, cb) — subscribe to incoming channel messages off(channel, cb) — unsubscribe peers() — list connected peers { id, transport } isConnected() — true if at least one peer stats() — transport statistics selfId — this peer's UUID Classes Method Signature Summary Current room id (null when disconnected). Used by mesh sync packet scoping. Join a named room. Starts BroadcastChannel fast channel immediately. Optionally starts WebRTC mesh if opts.webrtc === true. Leave the current room and tear down all transports. Broadcast a message to all peers on a named channel. Send a message to a specific peer. Subscribe to incoming messages on a channel. Unsubscribe from a channel. Dispatch a message received out of band (e.g. via an app layer supernode relay) to LOCAL listeners only — it is NOT re broadcast to the mesh. Used so relayed, already encrypted payloads are handled exactly like directly received ones. Force an immediate discovery re announce on the WebRTC signaling tiers so a known peer can be found without waiting for the periodic announce cycle. No op when WebRTC isn't active (BroadcastChannel peers are always live). List all currently


drivers/NetDriver.js

peer can be found without waiting for the periodic announce cycle. No op when WebRTC isn't active (BroadcastChannel peers are always live). List all currently connected peers. Transport statistics. Destroy the driver entirely (called by KernelBootstrap on shutdown). <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/NetworkDriver.js

drivers/NetworkDriver.js
Classes
class NetworkDriver
Constants
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: drivers/NetworkDriver.js — kernel driver backing / / (network plan Phase 6 webgpu os wiring, previously deferred — see C:\Users\btspa\.windsurf\plans\particle network layer 2bf6f0.md). Thin glue only: delegates to engine/network's already complete client side modules (identity, routes/MasterServerList, the shared pinned ParticleNetworkDaemon, syncManager, workstation) and reads/writes the SAME localStorage backed config already uses ( / ), so any app calling these syscalls sees the exact same state the Control Panel shows — one source of truth, not a second copy. Security model (see kernel/RuleGraph.js): / are low risk status/config visibility; actually opens a Masterserver session and can attach/signal on routes (declaration gated, high risk); changes what syncs where (medium risk). Every live session method requires to have been called first for that url — apps cannot attach/signal/discover on a session they never opened, even though the underlying WebSocket may be SHARED with other OS features via the V2 daemon registry (or the V1 registry only for explicit compatibility endpoints). Classes Method Signature Summary Load/generate the OS's profile + device identity signers. Safe to call multiple times. Compatibility adapter for the legacy namespace. Read only public contract inventory. No implementation functions escape. Verify or validate an app supplied record through an explicit allowlist. The concrete descriptor and its methods never cross the syscall boundary. Register a signed, currently valid authority lease for Navi semantic replication. This is a kernel/Realm runtime hook, not an app syscall. The issuing key must directly control both the issuer ID and Realm ID. Revoke


drivers/NetworkDriver.js

semantic replication. This is a kernel/Realm runtime hook, not an app syscall. The issuing key must directly control both the issuer ID and Realm ID. Revoke a currently registered Navi replication authority lease. Verify an exact Navi replication target against the live fenced lease and monotonic per resource sequence head. No lease is minted by this method. Open (or reuse) a real WebRTC mesh session for a route. Requires init() to have completed. Acquire a scoped consumer lease. App/room sessions stay cold until the first lease and close after the final release plus a short idle grace. Create a signed app scoped authority election using this device identity. Unified, secret free identity, route, protocol, and reachability projection. Foreground only public mesh presence. The browser owns the WebRTC transports, so closing/discarding this OS tab always ends the node. Send one application message over the route's direct peer channel. Broadcast one application message to the connected mesh neighbors. Subscribe to otherwise unclaimed route messages. Send one chunk's fragments to a peer over an open mesh session. / come from a Manifest.js chunk entry. Verify, cache, and advertise a chunk this live browser endpoint can serve. Fetch and assemble a signed manifest using verified chunks from many peers. Low level: relay an already built CarrierPacket (see CarrierPacket.js/SealedPacket.js) to a specific next hop. High level: build a multi hop sealed onion packet addressed to (in order) and send it to the first hop, using ECDH keys this node has already learned via CarrierIdentity announces. Rejects if any hop hasn't announced a key yet (they must be a currently joined mesh peer — see listCarrierRecipients). peerIds currently joined to this mesh session that have announced a


drivers/NetworkDriver.js

a key yet (they must be a currently joined mesh peer — see listCarrierRecipients). peerIds currently joined to this mesh session that have announced a carrier recipient key (i.e. can be used as an onion hop). Query every registered endpoint discovery source concurrently. Verify and retain a signed reconnect ticket for unified discovery. Create the standard authenticated SSE lease source for a connected V3 route. Push the current shared workstation over an already connected, already attached route. Constants <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss cal


drivers/NetworkPersistence.js

async saveStateChannelCheckpoint(sandbox, channelId, checkpoint)

async saveStateChannelOutbox(sandbox, channelId, intents, maxEntries = 512)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: drivers/NetworkPersistence.js — OS integration persistence for engine/network's intentionally storage agnostic modules (network plan §15/§38 persistence gap: "EventLog is in memory only" / "PeerTicketStore is in memory only... callers are responsible for persisting"). engine/network never imports webgpu os/storage/AppSandbox.js (same layering rule as drivers/ResidentBootstrapSource.js) — this file is the glue that reads/writes an AppSandbox instance using the snapshot/hydrate/ replay functions those modules already expose: engine/network/groupLedger/GroupLedger.js: replayGroupLedger() engine/network/peerTickets/PeerTicketStore.js: snapshotPeerTicketStore()/hydratePeerTicketStore() AppSandbox encrypts everything at rest (AES 256 GCM, device+app bound key) and is isolated per appId (webgpu os/storage/AppSandbox.js) — callers should pass the sandbox of THE APP THAT OWNS THIS DATA (e.g. a future groups/chat app), not some shared "network" pseudo app, so the sandbox's per app isolation guarantee stays meaningful. Functions Persist a group ledger's full replayable state: its static config (groupId/founders/mode/threshold) plus . Cheap to call after every / — it's a full snapshot, not an incremental diff, so there's nothing to get out of sync. Parameters: (object) — an initialized webgpu os/storage/AppSandbox.js instance (object) — from engine/network/groupLedger/GroupLedger.js's createGroupLedger() Load and replay a previously saved group ledger. Returns: a live ledger, or null if nothing is saved for groupId groupIds this sandbox currently has a saved ledger for. Forget a saved group ledger. Does not affect any already live in memory ledger object. Persist a peer ticket store (full


drivers/NetworkPersistence.js

currently has a saved ledger for. Forget a saved group ledger. Does not affect any already live in memory ledger object. Persist a peer ticket store (full snapshot — see PeerTicketStore.js's snapshotPeerTicketStore). Load a previously saved peer ticket store, or a fresh empty one if none is saved. Persist one complete, fenced State Channel authority checkpoint. Bounded pending intents survive tab reload until a receipt is observed. Adapter consumed by StateChannelAuthorityCoordinator. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/ProfileDriver.js

class ProfileSchemaVersionError extends Error

assertSupportedProfileSchemaVersion(value, { allowMissing = true, label = 'profile record' } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ProfileDriver.js — OS level multi user profile + per profile identity. SecureMesh Phase 1. Lawful, user owned identity: profile = OS created account + per profile ECDSA P 256 keypair + random (hashed) install id + user held recovery code. Privacy rules baked in: NO hardware/browser fingerprinting feeds identity. is a SHA 256 of a RANDOM, user resettable install id (never the raw id, never any device characteristics). The private key is NEVER stored raw. The working signing key is held as a NON EXTRACTABLE WebCrypto key (cannot be exfiltrated). A separate copy is stored encrypted (AES GCM, PBKDF2 from recovery code) purely for user triggered export / portability. Storage: IndexedDB store (CryptoKey objects are structured cloneable); active profile id + random install id live in the generic store. This driver is additive — the legacy global CryptoDriver identity is left untouched. Apps opt into per user identity via . Classes Method Signature Summary Method Signature Summary Return a snapshot signer for the active or specifically stored Passport. Create a new OS user profile with a fresh ECDSA P 256 identity. Generate a keypair + non extractable working key + recovery wrapped copy. Import a profile bundle; needs the recovery code to unlock the private key. Rotate a Passport key while preserving its stable ID and signed lineage. The legacy method name remains for syscall/UI compatibility. Terminally revoke a Passport key without erasing its ownership history. Regenerate the random install id — re derives every profile's device hash. Functions Reject records from a newer writer before normalization can discard fields. Missing versions are accepted as the legacy v1 shape and migrated


drivers/ProfileDriver.js

hash. Functions Reject records from a newer writer before normalization can discard fields. Missing versions are accepted as the legacy v1 shape and migrated explicitly. Constants <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/RealmNetworkFeatureFlags.js

drivers/RealmNetworkFeatureFlags.js
Classes
class RealmNetworkFeatureFlags
Functions
createRealmNetworkFeatureFlags(options)
Constants
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Persisted rollout gates for the additive Realm Network upgrade. Realm Network Alpha ships with every completed slice active. Version 2 stores only explicit user overrides, so later default changes cannot erase a deliberate opt out. Callers may inject a storage compatible object in tests; the driver uses localStorage in the OS. Classes Method Signature Summary Functions Constants — Persisted rollout gates for the additive Realm Network upgrade. Realm Network Alpha ships with every completed slice active. Version 2 stores only explicit user overrides, so later default changes cannot erase a deliberate opt out. Callers may inject a storage compatible object in tests; the driver uses localStorage in the OS. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large


drivers/RealmNetworkFeatureFlags.js

this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/ResidentBootstrapSource.js

createResidentBootstrapSource({ browserBridge } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: drivers/ResidentBootstrapSource.js — OS integration adapter wiring the browser extension's resident cert vault (browser extension/services/ ResidentService.js) into engine/network/dht/BootstrapSource.js's interface (network plan §37/§47/§48). intentionally has no dependency (same layering rule as the deferred wiring — see BootstrapSource.js's header comment) — this file is the OS side glue the plan called out as the natural adapter, kept honest about what the resident node actually does today: The resident node is a lightweight, OFF BY DEFAULT cert vault + a chrome.alarms keepalive heartbeat living in an MV3 offscreen document. It does NOT run a real WebRTC/Masterserver client and does NOT answer DISCOVER while no OS tab is open (see ResidentService.js's own header comment). Do not oversell this as "background reachability" anywhere in the UI (network plan §42's "never overstate privacy/reachability"). What it DOES give a bootstrap attempt: a small piece of persisted memory that survives an OS tab closing — "the last identity this browser saved for room X" — which is a legitimate (if modest) bootstrap hint once a new tab reopens, and a place to advertise our current identity so it's still there next time. Functions Parameters: (object) — No description in source JSDoc. (object) — the shared BrowserBridgeClient singleton Returns: a BootstrapSource ({ id, scan, advertise }) <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native


drivers/ResidentBootstrapSource.js

granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


drivers/WebSurfaceDriver.js

drivers/WebSurfaceDriver.js
Classes
class WebSurfaceDriver
Notes & Examples
Shared GPU device

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WebSurfaceDriver.js — Render any cross origin website as a live WebGPU texture. ── How it works ───────────────────────────────────────────────────────────── 1. Creates an <iframe that loads the target URL (browser renders it normally) 2. User clicks "Share Tab" once via getDisplayMedia({ preferCurrentTab: true }) 3. Element Capture API restricts the stream to just the iframe's pixels 4. HTMLVideoElement.srcObject = stream → live video feed of the website 5. device.importExternalTexture({ source: videoEl }) → WebGPU texture every frame Result: any cross origin URL renders as a live GPU texture surface inside the OS. ── Browser support ─────────────────────────────────────────────────────────── getDisplayMedia: all major browsers Element Capture: Chrome 116+ (RestrictionTarget.fromElement) importExternalTexture: Chrome/Edge (WebGPU) ── Security model ──────────────────────────────────────────────────────────── User must approve screen share once (one time gesture, can be re used) iframe is sandboxed; cross origin website cannot access our JS We only get pixels, not DOM of the foreign page Mouse/keyboard relay is optional (events forwarded to iframe element) Classes Method Signature Summary Feature detection. Create a new web surface for a URL. Returns a WebSurface object with a .texture getter usable each frame. Request screen share permission (one time user gesture). Call this in response to a user click. After approval all surfaces attach automatically. Destroy a surface by ID. Relay a pointer event from the WebGPU panel UV coords to the iframe. Destroy the driver — releases all surfaces and stops capture. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems


drivers/WebSurfaceDriver.js

UV coords to the iframe. Destroy the driver — releases all surfaces and stops capture. <! HUMAN NOTES Notes & Examples Shared GPU device Engine subsystems should reuse the cached wrapper returned by . The wrapper owns the native , its queue, granted features, limits, and device loss callbacks. Resources created by one native device cannot be used by another, so pass the shared wrapper or native device into each subsystem that needs GPU access. Example: Acquire the shared engine device Request a feature only when the application cannot run without it. automatically requests the engine's supported optional feature set, while reports the features actually granted to the device. Feature and limit checks Device loss Gotchas: First acquisition defines requirements: caches the wrapper. Supply mandatory features and limits on the first call. Native access: use and when a subsystem needs WebGPU primitives. Recovery: this module reports device loss but does not expose an in place API. Re bootstrap all device owned resources together. Limits: check the granted before large allocations. (Source: ) See also: GPU Device Sharing · Virtual GPU · GpuFormats


kernel/AmbientEngine.js

kernel/AmbientEngine.js
Classes
class AmbientEngine
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AmbientEngine.js — Desktop background rendering service. Owns a fixed full screen DOM layer (z index: 10) that sits permanently behind every panel and shell element. Supports CSS gradients, solid colors, static images, video, and extensible driver plug ins registered by mods. Exposes the same before/after hook middleware pattern as ThemeEngine so mods can intercept and customize background changes. ThemeEngine drives this automatically via setFromTheme() when the accent or wallpaper preset changes. Mods (or the user) can bypass ThemeEngine entirely with apply() for fully custom backgrounds. ── Modder API ──────────────────────────────────────────────────────────── const amb = syscalls.ambient; // Register a totally custom renderer (canvas, WebGPU, Three.js …) amb.registerDriver('webgpu scene', { apply(layer, config) { layer.innerHTML = ''; const canvas = document.createElement('canvas'); canvas.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;'; layer.appendChild(canvas); // … render into canvas … }, destroy(layer) { layer.innerHTML = ''; } }); // Before hook — middleware: modify config before the layer receives it amb.before('my mod', (cfg, next) = next({ ...cfg, opacity: 0.7 }), 'Dim'); // After hook — react after background is applied amb.after('my mod', (cfg) = console.log('Ambient applied:', cfg)); // Apply custom backgrounds amb.apply({ type: 'css', value: 'linear gradient(135deg, ff0080, 7928ca)' }); amb.apply({ type: 'color', value: ' 1a0533' }); amb.apply({ type: 'image', src: '/bg.jpg', size: 'cover', position: 'center' }); amb.apply({ type: 'video', src: '/bg.mp4', bg: ' 000' }); amb.apply({ type: 'webgpu scene', ... }); // custom driver // Set opacity


kernel/AmbientEngine.js

position: 'center' }); amb.apply({ type: 'video', src: '/bg.mp4', bg: ' 000' }); amb.apply({ type: 'webgpu scene', ... }); // custom driver // Set opacity of the ambient layer (0–1) amb.setOpacity(0.85); // Export / import config JSON const json = amb.export(); amb.import(json); // Subscribe to changes kernel.events.on('os:ambient change', ({ config }) = { … }); Classes Method Signature Summary Insert the ambient layer into the document. Call once after Desktop mounts. Restore the persisted ambient config on boot. Preview: push a config to the layer immediately. No hooks, no save, no event — safe for live dragging/hover previews. Apply: full pipeline — before hooks → layer → save → after hooks → event. Called by ThemeEngine whenever the accent or wallpaper preset changes. Bypasses the hook chain — ThemeEngine owns the state here. Set the global opacity of the ambient layer (0 = invisible, 1 = full). Enable/disable the reactive FX overlay (FxBus). Suspend compute heavy custom backgrounds while foreground GPU work runs. React to a FxBus frame: paint a soft accent glow on the FX overlay whose intensity tracks the frame's energy. Never touches the wallpaper layer. Fade the FX overlay back to neutral. Register a custom driver for a new wallpaper type. driver = { apply(layer, config), destroy?(layer) } Inject CSS keyframe rules for animated backgrounds. Tear down the currently active custom driver, if any. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS


kernel/AmbientEngine.js

Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/AppRegistrationScope.js

scopeToolSyscalls(kernel, appId, raw = kernel?.syscalls?.tools)

scopeProtocolSyscalls(kernel, appId, raw = kernel?.syscalls?.protocol)

scopeCommandSyscalls(kernel, appId, raw = kernel?.syscalls?.cmd)

cleanupAppRegistrations(kernel, appId, { logger = console } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Authenticated app wrappers for registration bearing syscall namespaces. Identity binding is independent of permission enforcement mode: developer mode may relax capability checks, but it never relaxes ownership. Functions <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/AppRegistry.js

class AppManifestValidationError extends Error

validateAppManifest(manifest, { mode = APPMANIFESTVALIDATION.STRICT, registry = schemaRegistry, logger = console, } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AppRegistry.js — fully dynamic, fetch based app discovery. NO apps are hardcoded here. Discovery works as follows: 1. Fetch apps/index.json → array of folder names, e.g. ["calculator","notepad",…] 2. For each folder, fetch apps/<folder /manifest.json 3. Resolve manifest.entry against the manifest URL (absolute URL) 4. Register and emit 'change' so the shell re renders live To add a new app: create apps/<name /manifest.json + apps/<name /YourApp.js, then add "<name " to apps/index.json. No JS edits required. Manifest shape (see docs/APP MANIFEST SPEC.md): appId, name, entry, icon, category, surface, defaultWidth, defaultHeight, permissions, description, version, settings[] Classes Method Signature Summary Method Signature Summary Compiled in entry module for an app (bundled builds), or undefined. Scan apps/index.json, fetch each manifest, register all found apps. Safe to call multiple times — re scans and merges. Register an app whose entry module is already compiled into the bundle. The module namespace is stored on the manifest (manifest. module) so the shell mounts it directly instead of import() ing a URL. Re fetch a single app's manifest (e.g. after hot reload). Remove a registered app (e.g. uninstalled). Apps that declare a specific capability (what they PROVIDE). Apps that require a specific permission. Full map of capability → app manifests that provide it. Apps that should be auto mounted at boot (tray/background surface or autoMount flag). Search apps by name, description, keywords, or capability. Summary report: for each app, list its declared permissions and provided capabilities. True if an app with this appId is registered. Source priority for an appId: bundled=3,


kernel/AppRegistry.js

for each app, list its declared permissions and provided capabilities. True if an app with this appId is registered. Source priority for an appId: bundled=3, package=2, raw=1, unknown=0. Find the best app that provides a capability. Sorted: highest source priority first, then alphabetically by appId. Register an app from an external source (e.g. PackageManager after install). source: 'package' (priority 2) 'raw' (priority 1) Silently skips if a higher priority source already owns this appId. Returns true if registered, false if skipped. Incrementally discover additional app folders without clearing existing registrations. Safe to call after PackageManager installs a new app — already registered higher priority apps are automatically skipped by priority dedup in loadManifest. Subscribe to registry events: 'register', 'update', 'unregister', 'ready'. Functions Validate an authority bearing manifest after removing registry only fields. Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/CommandBus.js

kernel/CommandBus.js
Classes
class CommandBus
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CommandBus.js — OS wide addressable command registry. Every syscall namespace, app, and service can register handlers for dot namespaced command strings: pkg.install patch.apply gpu.profile.start browser.tabs.list Dispatch flow: caller → cmd.dispatch('pkg.install', { url }) → handler → result All dispatches are logged to /os/logs/commands.log (async, non blocking). Usage: kernel.cmd.register('pkg.install', async ({ url }, ctx) = { ... }); const result = await kernel.cmd.dispatch('pkg.install', { url: '...' }); Classes CommandBus.js — OS wide addressable command registry. Every syscall namespace, app, and service can register handlers for dot namespaced command strings: pkg.install patch.apply gpu.profile.start browser.tabs.list Dispatch flow: caller → cmd.dispatch('pkg.install', { url }) → handler → result All dispatches are logged to /os/logs/commands.log (async, non blocking). Usage: kernel.cmd.register('pkg.install', async ({ url }, ctx) = { ... }); const result = await kernel.cmd.dispatch('pkg.install', { url: '...' }); Method Signature Summary Register a command handler. Register an app owned command. The authenticated owner is stored outside caller controlled metadata and may replace only its own existing entry. Register multiple commands from a { command: handler } object. Returns a single function that unregisters all of them. Register a command alias. Unregister a command. Remove a command only when it belongs to the authenticated caller. Remove every command owned by one authenticated app. Unregister ALL commands registered with a given tag (e.g. all of an app's commands). Check if a command is registered (including wildcard fallback). Resolve a command to its


kernel/CommandBus.js

commands registered with a given tag (e.g. all of an app's commands). Check if a command is registered (including wildcard fallback). Resolve a command to its registered key. Order: exact → alias → namespace wildcards (pkg.install → pkg. → ) Dispatch a command. Returns the handler's result. Dispatch without throwing — returns { ok, result, error }. List all registered commands with metadata. List commands matching a prefix (e.g. 'pkg'). List all registered aliases as { alias, canonical } pairs. Last N dispatch records (default 50). Optionally filter by command name or caller appId. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/FxBus.js

kernel/FxBus.js
Classes
class FxBus
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FxBus.js — the OS "FX Bridge". A normalized pipeline that lets apps (and the OS itself) publish a lightweight "vibe" — a dominant accent color, optional palette, an energy level, and an optional beat/mood — which the desktop reacts to (ambient tint/pulse, accent glow) and which external sinks (WLED / Home Assistant / Hue via a relay) can later subscribe to. Producers: Explicit: an app calls (capability ). Sandboxed iframe guests call , routed over the existing postMessage RPC bridge. Automatic: samples a provided surface (canvas/img/video) and extracts the dominant color, so an app can drive effects with no code. Consumers subscribe to the kernel event . The built in consumer is AmbientEngine.fxTint(); more sinks can be added without touching producers. Frames are normalized and rate limited (coalesced to one emit per minInterval) so a chatty producer cannot flood the desktop or thrash the compositor. Classes Method Signature Summary Subscribe the built in desktop sink (ambient tint). Safe to call once. Publish an FX frame from (may be null for OS/anonymous sources). Last frame for an app, or the last emitted frame overall when appId omitted. Subscribe to emitted frames. Returns an unsubscribe fn. Set a provider that returns the surface to sample — an HTMLCanvasElement, <img , <video , or null. The shell can point this at the focused app's canvas. (Cross origin / sandboxed guest canvases are unreadable by design; those guests publish explicitly instead.) Begin sampling the provider surface every and publishing its vibe. Extract a vibe (dominant accent + small palette + energy) from a drawable source. Returns null on failure (e.g. a cross origin tainted canvas). <! HUMAN NOTES


kernel/FxBus.js

Extract a vibe (dominant accent + small palette + energy) from a drawable source. Returns null on failure (e.g. a cross origin tainted canvas). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/GpuDeviceBroker.js

kernel/GpuDeviceBroker.js
Classes
class GpuDeviceBroker
Functions
bucketLimits(limits)
bucketAdapterInfo(info)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GpuDeviceBroker.js — per app GPU device facades, quotas, and adapter redaction. WHY a facade and not a Proxy of the real GPUDevice? Host objects with internal slots (GPUDevice/GPUQueue) fail brand checks when a Proxy is handed back to other WebGPU APIs (notably ). So we hand apps a forwarding facade : a plain object that forwards to the real device and ALWAYS returns real host objects (real GPUBuffer/GPUTexture/encoder/queue). The only host API that consumes the device object itself is — untrusted apps should get their canvas via (configured by the OS with the REAL device), so they never need to pass the facade anywhere. If an untrusted app does configure a canvas itself with the facade it fails closed (safe). POLICY: trusted / built in apps receive the RAW device (zero compatibility risk). Untrusted (unverified) apps receive a facade that: tracks + quota checks every createBuffer / createTexture (via VRAMTracker), counts pipelines / shader modules / queue submits per app, enforces a command submit budget (anti runaway), partitions the shader module cache per app (no cross app cache sharing), fails closed after device loss until the broker re issues a fresh facade. Classes Method Signature Summary True when a real GPU device is present. Get the device object an app should use. Invalidate all facades (called on device loss). Apps must re acquire. Drop one app's facade + accounting (call on app close). Functions Bucket GPUSupportedLimits into a coarse, plain object. Reduces fingerprint entropy (exact limits vary per GPU/driver) while keeping values usable. Returns a plain object with the same keys apps read. Redact a rich adapter info report down to a coarse, low entropy summary


kernel/GpuDeviceBroker.js

while keeping values usable. Returns a plain object with the same keys apps read. Redact a rich adapter info report down to a coarse, low entropy summary for untrusted apps. Keeps the vendor bucket and capability booleans; drops the precise renderer string, driver version, device id, and exact limits. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/GpuInfo.js

async gatherGpuInfo(adapter, device = null, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GpuInfo.js — rich, consolidated GPU adapter reporting for the OS. Browsers expose the GPU through several uneven channels; the most accurate picture comes from combining them (this mirrors what the engine's VGPUMemoryTracker / GPU Profiler do, minus the heavy VRAM probe): 1. WebGPU → vendor / architecture / device / description 2. → same, legacy async fallback 3. → some implementations expose it here 4. WebGL → the UNMASKED renderer string is usually the only place the real model name (e.g. "AMD Radeon RX 6700 XT") appears, since Chrome hides it from adapter.info. 5. / → capability flags + key device limits returns ONE structured report plus best effort adapter preference probes. Everything is best effort and never throws — missing channels just leave their fields empty. Functions Coarse vendor label from any descriptive string. Best human readable adapter name from the combined channels. Gather a full GPU report from a WebGPU adapter (+ optional device). Parameters: (GPUAdapter null) — No description in source JSDoc. (GPUDevice null) — No description in source JSDoc. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/KernelBootstrap.js

kernel/KernelBootstrap.js
Classes
class KernelBootstrap
class KernelEventBus
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes KernelBootstrap — the OS kernel layer. Owns: The single shared WebGPU device (if available). The central task scheduler (kernel owned RAF). The event bus. GPU device lost fan out to all registered apps. The syscall surface exposed to apps. Tier 2 note: In Tier 2 this becomes a Rust native host service; the kernel.syscalls shape must remain stable across tiers. Method Signature Summary Factory — initialise and return a ready kernel. Provision the one OS owned executable Faculty that applications may ask the kernel to install automatically. The public gateway deliberately accepts only the exact active Navi and exact built in Faculty identity. Execute one planner selected tool through an installed deterministic Faculty. This is deliberately kernel internal: apps receive the narrow naviFaculty gateway and cannot prepare, mint, consume, or settle grants. Re open the immutable Faculty receipt before projecting learning evidence. A successful looking provider or tool result is never sufficient: the exact runtime descriptor, verifier profile, Navi, task, operation, and signed receipt must all agree with the authoritative Faculty Store. Mirror a terminal continuity outcome onto every dependent Navi service. pins all dependents to synchronously, but they are only re bound after continuity publishes. If the rebind ends before that point, those services keep a transient state that nothing will ever resolve: the authority recovery net refuses to run while continuity is unavailable, so every later request waits out its full transient budget and then fails on a state that cannot change.


kernel/KernelBootstrap.js

net refuses to run while continuity is unavailable, so every later request waits out its full transient budget and then fails on a state that cannot change. Publishing the same terminal state keeps the dependents honest and lets callers fail fast with an actionable reason. This is only for outcomes with no follow up bind. A pre change boundary is deliberately left transient because its committing Profile event will bind the next operator. Install always on Navi services after the operator ProfileDriver is ready. Engine Compatibility runtime — boots compat wrapped guest apps (HTML/WebGPU packages) through a probe→heal→interpose→run pipeline. Exposed as , the syscall, and (the fallback used by auto generated package bootloader entries). Build the capability bridge handed to a sandboxed (iframe) compat guest. Exposes ONLY scoped storage + mediated network — no kernel/syscall access. storage → per app encrypted AppSandbox (os.sandbox.<appId ), localStorage keys namespaced 'ls:'. Persists across sessions; purge clears it. net → host origin fetch gated by the app's network.fetch permission; a denied app simply has no network. Responses are serialised. Snapshot the OS theme tokens a guest can adopt (read from live CSS vars). Register a per frame tick callback. Returns an unregister function. Stop the kernel RAF loop and drain network/manifestation authority before all lower authority. Current smoothed FPS. Current frame count. Built in, always on unified search providers (work even when their app is closed): • calc — evaluate a math expression typed into the palette • files — fuzzy search the virtual filesystem and open the hit in Files Open Files focused on a VFS entry (deep link via the subsurface nav pipeline). Call after the desktop shell has mounted to the DOM. Mounts the


kernel/KernelBootstrap.js

the hit in Files Open Files focused on a VFS entry (deep link via the subsurface nav pipeline). Call after the desktop shell has mounted to the DOM. Mounts the PermissionPortal and attaches it to the kernel permissions layer. Create a ctx object with verified kernel level trust. Pass to commandBus.dispatch() from trusted kernel subsystems that need full capability access. Minimal synchronous event bus for kernel internal use. Apps should use kernel.syscalls.ipc for cross app messaging. Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based


kernel/LaunchCoordinator.js

kernel/LaunchCoordinator.js
Classes
class LaunchCoordinator
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Route validated launch intents through the existing desktop and subsurface services. Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/LaunchIntent.js

parseLaunchUrl(input, { baseUrl = globalThis.location?.href ?? 'https://localhost/webgpu-os/', scopePath = DEFAULTLAUNCHSCOPE, } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Canonical, untrusted input boundary for browser and operating system launches. Classes Method Signature Summary Functions Parse a canonical launch URL. Non launch URLs inside the shell return null; malformed URLs under /open/ throw so callers can log a security rejection. Constants — Canonical, untrusted input boundary for browser and operating system launches. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/ModRegistry.js

kernel/ModRegistry.js
Classes
class ModRegistry
Constants
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ModRegistry.js — dynamic mod discovery, mirroring AppRegistry. Scans mods/index.json → per mod mods/<folder /manifest.json Imports the mod entry and registers its hooks into PatchBus. Mod manifest shape: modId — unique reverse domain id, e.g. "com.example.dark plus" name — display name version — semver string author — author name description — one line description targets — array of appIds to patch, or [" "] for all apps entry — relative path to mod JS module (default export = mod object) entryOverride — boolean, if true this mod completely replaces the app entry enabled — boolean (default true), false to disable without removing Adding a new mod: 1. Create mods/<name /manifest.json 2. Create mods/<name /YourMod.js (default export: mod object) 3. Add "<name " to mods/index.json No kernel or app code changes required. Classes Method Signature Summary Register a mod whose entry module is already compiled into the bundle. Register a mod that was installed as a (its entry module was loaded from OPFS by PackageManager/PackageLoader). Wires it into PatchBus like a dev tree mod. Idempotent per modId. Unregister a mod (e.g. on package removal). Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/OsLogger.js

kernel/OsLogger.js
Classes
class OsLogger
Functions
projectLogMetadata(value)
Constants
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OsLogger.js — in memory ring buffer logger for the OS kernel and apps. Levels: debug < info < warn < error Keeps the last MAX ENTRIES entries in memory. Listeners (e.g. Log Viewer) are notified on each write. Optionally flushes to /os/logs/os.log via StorageManager (non blocking). Classes Method Signature Summary Return last entries, optionally filtered by level/source. Subscribe to new log entries. Returns unsubscribe fn. Functions Produce an accessor free, bounded, closed projection for a log entry. Unknown fields and nested objects are omitted instead of serialized. Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/PatchBus.js

kernel/PatchBus.js
Classes
class PatchBus
Constants
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PatchBus.js — Android style mod / patch bus for WebGPU OS. Provides: beforeMount / afterMount / beforeUnmount / afterUnmount hooks UI injection — mods append DOM into any app panel CSS injection — scoped to the app's panel element automatically Manifest patch — mods can widen panels, add permissions, change defaults Entry override — a mod can fully replace an app's module Syscall intercept — middleware chain on any syscall namespace.method Hook execution order: mods registered first run first (FIFO per phase). Syscall interceptors are chained: each calls next() to delegate down. ── Mod object API (default export from mod entry file) ───────────────────── beforeMount(container, syscalls, manifest) → void Promise afterMount(container, syscalls, appInstance, manifest) → void Promise beforeUnmount(appInstance, manifest) → void Promise afterUnmount(manifest) → void Promise injectUI(container, manifest) → HTMLElement null injectCSS(manifest) → string null patchManifest(manifest) → Partial<Manifest interceptSyscall(syscallPath, args, next) → any None of these are required — implement only what you need. Classes PatchBus.js — Android style mod / patch bus for WebGPU OS. Provides: beforeMount / afterMount / beforeUnmount / afterUnmount hooks UI injection — mods append DOM into any app panel CSS injection — scoped to the app's panel element automatically Manifest patch — mods can widen panels, add permissions, change defaults Entry override — a mod can fully replace an app's module Syscall intercept — middleware chain on any syscall namespace.method Hook execution order: mods registered first run first (FIFO per phase). Syscall interceptors are chained: each calls next() to delegate down.


kernel/PatchBus.js

namespace.method Hook execution order: mods registered first run first (FIFO per phase). Syscall interceptors are chained: each calls next() to delegate down. ── Mod object API (default export from mod entry file) ───────────────────── beforeMount(container, syscalls, manifest) → void Promise afterMount(container, syscalls, appInstance, manifest) → void Promise beforeUnmount(appInstance, manifest) → void Promise afterUnmount(manifest) → void Promise injectUI(container, manifest) → HTMLElement null injectCSS(manifest) → string null patchManifest(manifest) → Partial<Manifest interceptSyscall(syscallPath, args, next) → any None of these are required — implement only what you need. Method Signature Summary Register a mod object against one or more app IDs. Merge all manifest patches from applicable mods. Mods returning a patch object get deep merged in registration order. If any mod declares { entryOverride: true }, the LAST such mod's own replaces the app's entry (like forking the app). Wrap a syscalls object with a middleware chain for all registered interceptors targeting this app. Interceptor signature: (syscallPath, args, next) = result Call next(args) to pass through to the next interceptor / original. Each mod's injectUI(container, manifest) may return an HTMLElement which is appended as an overlay into the app's container. Each mod's injectCSS(manifest) returns a CSS string. It is scoped to the panel via [data panel id="..."] automatically. Constants <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example:


kernel/PatchBus.js

handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/PermissionPortal.js

kernel/PermissionPortal.js
Classes
class PermissionPortal
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PermissionPortal.js — user facing permission prompt. Appears as a stacked card above the taskbar whenever an app requests a capability that is not yet decided. Multiple requests queue and show one at a time (FIFO). Each card: ┌──────────────────────────────────────┐ │ 🔒 os.my app wants permission │ │ Access camera │ │ Risk: ● High │ │ [Deny] [Allow Once] [Allow Always] │ └──────────────────────────────────────┘ Usage (kernel internal — apps call syscalls.permissions.request()): const portal = new PermissionPortal(); portal.mount(document.body); const granted = await portal.ask(appId, capability, manifest); Classes Method Signature Summary Ask the user for permission. Returns Promise<boolean . If the same capability is already in the queue, returns a new promise that resolves to the same answer. Queue depth — for debugging <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/PermissionStore.js

kernel/PermissionStore.js
Classes
class PermissionStore
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PermissionStore.js — IDB backed persistence of user permission decisions. Decisions are keyed as in the 'permissions' IDB store. Each record: { appId, capability, decision: 'allow' 'deny', scope: 'once' 'always', ts } 'once' decisions are in memory only (not persisted). 'always' decisions are stored and reloaded on next boot. Classes PermissionStore.js — IDB backed persistence of user permission decisions. Decisions are keyed as in the 'permissions' IDB store. Each record: { appId, capability, decision: 'allow' 'deny', scope: 'once' 'always', ts } 'once' decisions are in memory only (not persisted). 'always' decisions are stored and reloaded on next boot. Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/Permissions.js

class PermissionDeniedError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Permissions.js — capability gating backed by RuleGraph. Phase 4: enforces manifest declared permissions via a declarative RuleGraph. Phase 1 mode: audit only (log violations, never block) — set enforcing=false. Tier 2: delegates to WASI capability broker (same check() interface). Usage: kernel.permissions.registerApp(appId, manifest) kernel.permissions.check(appId, 'gpu.compute') → { granted, reason } kernel.permissions.require(appId, 'gpu.compute') → throws if denied + enforcing Classes Method Signature Summary Register an app manifest so condition based rules can read its permissions. Call this as each app is discovered by AppRegistry. Check whether appId can use capability. Check and throw if denied + enforcing mode is on. Safe to call inside syscall handlers. List all capabilities granted to an app (from the known vocabulary). check() without side effects — no audit log, no console output. Access the underlying RuleGraph to add project specific rules. Attach a PermissionPortal (set by kernel after shell mounts). Without a portal, requestAsync() auto denies unknown capabilities. Attach a PermissionStore (set by kernel at boot after IDB is ready). Attach a StorageManager so grant/revoke decisions are mirrored to /user/preferences/permissions.json as a human readable, non authoritative projection. Authority is changed only through the Permissions service. Load persisted decisions from IDB into overrides. Call this once at boot after setStore(). Async version of check(). If the decision is already known (manifest rule OR saved override), resolves immediately. Otherwise, shows the PermissionPortal to ask the user. 'Allow Always' persists to IDB; 'Allow Once' / 'Deny' stay in


kernel/Permissions.js

OR saved override), resolves immediately. Otherwise, shows the PermissionPortal to ask the user. 'Allow Always' persists to IDB; 'Allow Once' / 'Deny' stay in memory. Forget a persisted decision (and remove in memory override). Forget all saved decisions for an app. Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/ProcessTable.js

kernel/ProcessTable.js
Classes
class ProcessTable
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ProcessTable.js — tracks all running app panel instances. Each entry maps an appId to its runtime handle: { appId, panelId, manifestPath, panel, resources, startedAt, parentAppId, cpuMs, memoryBytes, networkBytes, diskBytes, lastSampleAt } Phase 4 extends this with per app VRAM quotas, capability sets, and "destroy on policy breach" enforcement. Phase 5 adds full system monitoring (CPU%, memory, network I/O, disk I/O). Classes Method Signature Summary Start periodic sampling of process metrics Stop sampling (for cleanup) Sample CPU, memory, network, disk for all processes Estimate CPU usage based on panel activity ( RAF calls, event handlers ) Estimate memory usage (DOM nodes approx size + JS heap share) Get network stats from kernel network tracker Get disk stats from kernel storage tracker Record network activity for an app (called by network layer) Record disk activity for an app (called by storage layer) Get system wide statistics Register a running app. Unregister and clean up a running app. Get process tree with parent child relationships Returns the entry for an app, or null. Returns true if the app is running. Returns an array snapshot of all running app entries. Returns live process handles for trusted shell internals. is intentionally sanitized for syscalls, tools, and UI data views. Window management code needs the live panel handle, so it must opt into this method instead of assuming contains DOMPanel references. Subscribe to register/unregister events. Returns an unsubscribe fn. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes


kernel/ProcessTable.js

Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/ProvenanceChecker.js

kernel/ProvenanceChecker.js
Classes
class ProvenanceChecker
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ProvenanceChecker.js — SLSA inspired build provenance validation. Signatures prove WHO built a package; provenance proves HOW. The 2026 TanStack attack shipped packages with valid signatures from a hijacked builder, so we validate a provenance block and (critically) that the declared source materials actually match the packaged files. Provenance block shape (in the envelope): { sourceRef: 'git@… <commit ' 'webgpu os/devtools', builderId: 'webgpu os/devtools' 'ci/github', builtAt: ISO timestamp, buildParams:{ … }, materials: [ { path: 'files/app.js', sha256: '…' }, … ] } Returns a verdict { ok, level, builderId, warnings[] }: level 0 — no provenance (allowed, but lowers trust → risk badge) level 1 — provenance present + materials match packaged files level 2 — level 1 AND builder is a recognized trusted builder Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/RuleGraph.js

kernel/RuleGraph.js
Classes
class RuleGraph
Functions
buildDefaultRuleGraph()
Constants
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: RuleGraph.js — declarative capability based permissions engine. Rules are evaluated in registration order; the LAST matching rule wins (CSS like specificity — more specific rules override general ones). Capabilities follow a dot namespace convention: fs.read, fs.write, gpu.compute, gpu.acquireSurface, net.send, net.on, ai.infer, ui.notify, ipc.emit, … Wildcard matching: 'fs. ' matches any capability starting with 'fs.' ' ' matches everything Condition functions receive (appId, capability, manifest) and return bool. A rule with a condition is only applied when the condition is true. Usage: const graph = new RuleGraph() .allow('fs. ') .deny('net. ') .allowIf('gpu.compute', (id, cap, mf) = mf.permissions?.includes('gpu.compute')); const { granted, reason } = graph.check('os.calculator', 'fs.read', manifest); Classes RuleGraph.js — declarative capability based permissions engine. Rules are evaluated in registration order; the LAST matching rule wins (CSS like specificity — more specific rules override general ones). Capabilities follow a dot namespace convention: fs.read, fs.write, gpu.compute, gpu.acquireSurface, net.send, net.on, ai.infer, ui.notify, ipc.emit, … Wildcard matching: 'fs. ' matches any capability starting with 'fs.' ' ' matches everything Condition functions receive (appId, capability, manifest) and return bool. A rule with a condition is only applied when the condition is true. Usage: const graph = new RuleGraph() .allow('fs. ') .deny('net. ') .allowIf('gpu.compute', (id, cap, mf) = mf.permissions?.includes('gpu.compute')); const { granted, reason } = graph.check('os.calculator', 'fs.read', manifest); Method Signature Summary Allow for (string, array, or ' ' for


kernel/RuleGraph.js

const { granted, reason } = graph.check('os.calculator', 'fs.read', manifest); Method Signature Summary Allow for (string, array, or ' ' for all). Deny for . Allow for all apps where returns true. Deny for all apps where returns true. Evaluate the rule graph for an app+capability pair. Check many capabilities at once. Return all capabilities that an app is currently granted (from the registered rule set). Only works for the known set of you pass in. Functions Build the default OS wide RuleGraph. Apps with explicit manifest.permissions entries unlock restricted capabilities. Constants — Human readable label for each capability (used by PermissionPortal). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/RuntimeModeManager.js

kernel/RuntimeModeManager.js
Classes
class RuntimeModeManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: RuntimeModeManager.js — Runtime ↔ Developer mode switch. Modes: 'runtime' — enforcing permissions, no debug surface, production like 'developer' — enforcing permissions, bounded diagnostics, hot reload enabled Effects applied on mode change: runtime → permissions.setEnforcing(true), window. DEV = false developer → permissions.setEnforcing(true), window. DEV = true Developer mode is never an authority bypass. Entering it requires a trusted system principal and a live browser user activation; the kernel object and private services are never projected onto . Persisted in IDB kv store under key 'os.runtimeMode'. Emits kernel event 'os:mode change' with { mode, prev }. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/SearchManager.js

kernel/SearchManager.js
Classes
class SearchManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SearchManager.js — unified OS search backend for the command palette. Aggregates "app elements" from three kinds of sources, on top of the apps / subsurfaces / deep links the palette already indexes: 1. Quick Actions (static) — declared in a manifest's array. Each is a runnable item. If it carries a , the palette dispatches it on the CommandBus; otherwise it is delivered to the app as an app action (the app is opened/focused first, then receives ui:app action / reads pendingActions). 2. Live content providers — a running app registers a query callback via ui.registerSearchProvider(id, { label, query }). returns result items { id, label, sublabel?, icon?, run } where run() performs the action. Providers are same realm closures, so run() can call straight back into the app. 3. Commands (opt in) — CommandBus commands registered with meta.search:true become searchable; selecting dispatches them (no arg). Opt in keeps destructive commands out of search by default. Events: ui:app action { appId, actionId, args } — a manifest app action was invoked. Classes SearchManager.js — unified OS search backend for the command palette. Aggregates "app elements" from three kinds of sources, on top of the apps / subsurfaces / deep links the palette already indexes: 1. Quick Actions (static) — declared in a manifest's array. Each is a runnable item. If it carries a , the palette dispatches it on the CommandBus; otherwise it is delivered to the app as an app action (the app is opened/focused first, then receives ui:app action / reads pendingActions). 2. Live content providers — a running app registers a query callback via ui.registerSearchProvider(id, { label, query }). returns result items { id,


kernel/SearchManager.js

2. Live content providers — a running app registers a query callback via ui.registerSearchProvider(id, { label, query }). returns result items { id, label, sublabel?, icon?, run } where run() performs the action. Providers are same realm closures, so run() can call straight back into the app. 3. Commands (opt in) — CommandBus commands registered with meta.search:true become searchable; selecting dispatches them (no arg). Opt in keeps destructive commands out of search by default. Events: ui:app action { appId, actionId, args } — a manifest app action was invoked. Method Signature Summary Register a live search provider. Returns an unregister fn. Run every provider against the query; returns grouped results (errors swallowed). Flatten every visible app's manifest into runnable descriptors. Take (and clear) actions queued for an app that is mounting now. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/SecurityDoctor.js

kernel/SecurityDoctor.js
Functions
scoreSecurityFindings(findings)
async runSecurityDoctor(kernel)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SecurityDoctor.js — in browser security posture report (no Node required). Aggregates the OS's runtime security signals into a single graded report: syscall guard coverage (reuses auditSyscallGuards) complete capability policy coverage (reuses auditCapabilityMap) permission enforcement state package trust posture (quarantined / untrusted installed packages) update supply chain policy (signed + trusted for auto) GPU containment (per app broker + VRAM quotas) shell CSP delivery (Report Only vs enforcing, inline script regressions) browser extension presence Each finding has a severity ('critical' 'high' 'medium' 'low' 'info') and a pass flag. returns a structured report suitable for logging or rendering in a Security Doctor panel. Functions <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/SessionStore.js

kernel/SessionStore.js
Classes
class SessionStore
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SessionStore.js — OS wide, encrypted per origin session + credential store. One machine bound, AES 256 GCM encrypted IndexedDB store (via AppSandbox, db ) shared by every app and the compat layer. It replaces the Browser app's localStorage local vault/cookie stores so logins and per site policy are managed OS wide and consistently encrypted. Record kinds (one IDB key each): policy:<origin → 'persist' 'isolated' per site session policy sess:<origin → { cookies:{k:v}, local:{k:v}, t } agent captured data vault → the Browser vault blob (itself master password encrypted; stored here so all apps share one OS wide vault) IMPORTANT — what this can and cannot do: We CANNOT read a cross origin live frame's real cookies (browser isolation), and Set Cookie is a forbidden header. So "persistence" is policy driven: • 'isolated' (default) → frame loads (ephemeral, sessionless) • 'persist' → frame drops so the browser keeps its cookies natively across reloads + restarts Captured data only comes from surfaces we CONTROL (proxied / srcdoc / compat sandbox documents) via an injected agent — never scraped from a live cross origin frame. Classes Method Signature Summary Lazily open the encrypted sandbox. Safe to call repeatedly. 'persist' (keep logins) 'isolated' (default — credentialless, sessionless). Map of origin → policy for every origin with a non default policy. { cookies, local, t } or null. Merge save captured cookies/localStorage for an origin. Origins that have either a policy or captured data. Wipe everything (policies, captured sessions, vault). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps


kernel/SessionStore.js

sessions, vault). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/SigningLineage.js

async authorizeRotation(lineage, signerFingerprint, pinnedFingerprint, crypto)

async createGenesisLineage(appId, pubKeyRaw, crypto, flags = 0)

async appendRotation(lineage, newPubKeyRaw, signWithCurrent, crypto, opts = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SigningLineage.js — publisher signing key rotation lineage (proof of rotation). Models the Android APK Signature Scheme v3 "proof of rotation" idea in our ECDSA P 256 world: a singly linked list of publisher keys, ordered oldest → newest, where EACH ancestor key signs the NEXT key's payload. This proves that a new key is endorsed by the previous one, so an app update signed by a fresh key is provably the same publisher identity as the version a user already pinned — "reuse the same identity with new keys, still isolated per update." Two independent guarantees (kept separate, exactly like APK v3): 1. File integrity / self verification — the CURRENT key signs the version's Merkle root (PackageBuilder.buildV2). That is unchanged and lives outside this module: a package always verifies against its own files. 2. Identity continuity — THIS module. The lineage is carried inside the signed package envelope (so it is covered by the current key's signature and cannot be stripped/swapped in transit), and proves the head key descends from the previously pinned key. Lineage shape ( ): { format: 'prlineage v1', appId: 'community.my app', nodes: [ { pubKey:<b64 , fingerprint:<hex , flags:<uint , rotatedAt:<iso }, ... ], // oldest → newest links: [ <b64 sig , ... ] // links[i] = nodes[i] signing canonical(nodes[i+1]); length = nodes.length 1 } Node flags (self trusted old certs, bitfield): FLAG INSTALL (1) — this (old) key may still authorize fresh installs FLAG UPDATE (2) — this (old) key may still sign updates Default for new rotations is 0 (strict): only the head key installs/updates; ancestors are accepted ONLY to prove continuity to a pinned fingerprint. SECURITY: this verifier is FAIL


kernel/SigningLineage.js

is 0 (strict): only the head key installs/updates; ancestors are accepted ONLY to prove continuity to a pinned fingerprint. SECURITY: this verifier is FAIL CLOSED. Any malformed structure, fingerprint mismatch, or broken link signature ⇒ { valid:false }. Callers fall back to the existing publisher change quarantine path on invalid/absent lineage. fingerprintOf:(pubRaw:Uint8Array)= Promise<string , sign?:(data:string)= Promise<Uint8Array null }} CryptoLike Functions Canonical signed payload for a lineage node — the bytes an ancestor key signs to endorse this successor node. Binds the successor's key, fingerprint, flags, the appId, and the PREVIOUS node's fingerprint, so a link cannot be replayed onto a different app or spliced into a different chain. Verify a lineage end to end. FAIL CLOSED. Parameters: (object) — No description in source JSDoc. (CryptoLike) — No description in source JSDoc. Returns: {Promise<{ valid:boolean, reason?:string, root?:string, head?:string, Decide whether an update may proceed via key rotation. FAIL CLOSED. Accepts iff the lineage is valid, its head equals the package's current signer fingerprint, and the previously pinned fingerprint appears in the chain (i.e. the head provably descends from the key the user already trusts). Parameters: (object) — — from the package envelope (string) — — fingerprint of the key that signed THIS package (string) — — the user's currently pinned fingerprint for this app/publisher (CryptoLike) — No description in source JSDoc. Returns: } Build the genesis (single node) lineage for a brand new publisher key. Parameters: (string) — No description in source JSDoc. (Uint8Array) — No description in source JSDoc. (CryptoLike) — No description in source JSDoc. (number) — No description in source JSDoc. Append a


kernel/SigningLineage.js

source JSDoc. (Uint8Array) — No description in source JSDoc. (CryptoLike) — No description in source JSDoc. (number) — No description in source JSDoc. Append a rotation: the CURRENT head key signs the NEW key's node, proving the new key inherits the identity. The caller supplies a bound to the OLD/head private key (the dev's safely kept key), so private keys never enter this module. Parameters: (object) — — existing valid lineage (Uint8Array) — — the freshly generated next key ((data:string)= Promise<Uint8Array null ) — — signs with the head key (CryptoLike) — No description in source JSDoc. Returns: the extended lineage (new node + new link appended) Constants — SigningLineage.js — publisher signing key rotation linea


kernel/SubsurfaceManager.js

kernel/SubsurfaceManager.js
Classes
class SubsurfaceManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SubsurfaceManager.js — kernel navigation service for app SUBSURFACES. A "surface" is an app's top level display mode (window / overlay / tray — see manifest.surface). A "subsurface" is a navigable sub location inside an app (a tab, section, or view), declared in the manifest as: "subsurfaces": [ { "id": "mixer", "label": "Volume Mixer", "icon": "🎚", "keywords": ["volume"] }, ... ] This service is the OS level registry/tracker for deep linking into those: Active tracking: which subsurface each running app currently shows. Pending nav: a deep link target stashed for an app that is still launching (the app reads it on mount via ui.pendingNavigate). Recents + Pins: persisted deep link shortcuts (the "small UI shortcuts"), surfaced in the command palette / Start Menu. NOTE: This is distinct from SurfaceManager.js, which allocates WebGPU canvases. Events emitted on kernel.events: ui:navigate subsurface { appId, subsurfaceId, args } — a deep link was requested ui:subsurface change { appId, subsurfaceId } — an app reported its active sub os:deeplinks change {} — pins/recents changed Classes Method Signature Summary The subsurfaces declared by a single app (from its manifest). Flatten every visible app's subsurfaces into searchable deep link descriptors. Resolve a single {appId, subId} into a full descriptor (or null). Pins + recents, each enriched with display descriptors (stale entries dropped). <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level


kernel/SubsurfaceManager.js

register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/SurfaceManager.js

kernel/SurfaceManager.js
Classes
class SurfaceManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SurfaceManager.js — allocates and manages one WebGPU canvas surface per panel. Checks permissions (gpu.acquireSurface) and VRAM quotas before allocating. Classes Each app gets an exclusive <canvas + GPUCanvasContext bound to the kernel's GPU device. The SurfaceManager handles: Canvas creation and insertion into the panel body GPUCanvasContext.configure() with the preferred format ResizeObserver wiring so the canvas tracks panel resize Clean release (unconfigure + canvas removal) on panel close Quota admission happens before GPUCanvasContext creation/configuration. Method Signature Summary Allocate a WebGPU canvas surface for inside . Returns a surface descriptor or null if WebGPU is unavailable. Release the surface for , unconfiguring the context and removing the canvas. Get an allocated surface by panelId. List all active surfaces. Number of active surfaces. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on capabilities. Commands can be local (same app), cross app (with permission), or system level (elevated). Example: Command registration and invocation See also: WebGPU OS Architecture · Security Model


kernel/Syscalls.js

kernel/Syscalls.js
Functions
createSyscalls(kernel)
guardSyscalls(kernel, appId, syscalls)
auditSyscallGuards(kernel)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Syscalls.js — the stable Tier 1 ↔ Tier 2 contract boundary. Every app sees ONLY this surface. In Tier 1 (browser) each method delegates to the corresponding engine module. In Tier 2 (Rust + Wasmtime) each method becomes a WASI capability table entry. ⚠ Never expose engine internals directly to apps. If an app needs a new capability, add a method here first; never let apps import from ../../engine/. Syscall namespaces: kernel.fs — virtual filesystem (IndexedDB + ProjectManager) kernel.gpu — GPU stats, resource budgets, device info kernel.ipc — cross app event bus kernel.ai — inference handle (AGI driver, Phase 6) kernel.net — networking (collab driver, Phase 5) kernel.crypto — ECDSA P 256 identity, sign/verify (CryptoDriver) kernel.ui — notifications, modals, panels Functions Wrap a syscalls object with per app permission enforcement. Only restricted capabilities are guarded — universally open ones (fs. , ipc. , ui. ) are skipped since they are always granted and the overhead is unnecessary. Parameters: (object) — No description in source JSDoc. (string) — No description in source JSDoc. (object) — — the panelSyscalls built by Desktop. launchPanel Returns: a new syscalls object with guarded methods Inventory every syscall method and classify it as guarded / open / unguarded. Build only: no syscall is invoked. Use at boot (dev mode) or in tests to catch privileged methods added without a capability guard. Parameters: (object) — No description in source JSDoc. Returns: } <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the kernel routes commands based on