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

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SamplingBroker.js — Particle Realms Protocol sampling (MCP inspired): lets a TOOL handler request a nested LLM completion mid execution (the inverse of a normal OS.ai() call). Every sample enters the full AI executor, which creates a model neutral Navi task and applies Covenant disclosure, resource, tool firewall, verification, and receipt policy. There is no raw AI Hub fallback. A hard recursion depth guard prevents sampling loops. Classes SamplingBroker.js — Particle Realms Protocol sampling (MCP inspired): lets a TOOL handler request a nested LLM completion mid execution (the inverse of a normal OS.ai() call). Every sample enters the full AI executor, which creates a model neutral Navi task and applies Covenant disclosure, resource, tool firewall, verification, and receipt policy. There is no raw AI Hub fallback. A hard recursion depth guard prevents sampling loops. Method Signature Summary A tool handler requests a bounded, receipted Navi task during execution. <! 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/protocol/ToolRegistry.js
Classes
class ToolRegistry
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ToolRegistry.js — Particle Realms Protocol tool catalog. Distinct from kernel.toolDriver (the low level execute/history engine, see webgpu os/kernel/ToolDriver.js) and kernel.toolRouter (the AI Tool Firewall, see webgpu os/kernel/tools/ToolRouter.js): this is the per app CATALOG that says "this app opts this already registered tool into AI discovery", so the AI Hub's two pass execution loop (Phase 9) knows which tools are legal for a given app's request. Declaring a tool here never bypasses ToolRouter's firewall — it only makes the tool visible/offered. Classes ToolRegistry.js — Particle Realms Protocol tool catalog. Distinct from kernel.toolDriver (the low level execute/history engine, see webgpu os/kernel/ToolDriver.js) and kernel.toolRouter (the AI Tool Firewall, see webgpu os/kernel/tools/ToolRouter.js): this is the per app CATALOG that says "this app opts this already registered tool into AI discovery", so the AI Hub's two pass execution loop (Phase 9) knows which tools are legal for a given app's request. Declaring a tool here never bypasses ToolRouter's firewall — it only makes the tool visible/offered. Method Signature Summary Declare that offers (already registered with kernel.toolDriver) to the AI Hub. <! 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/schema/BinaryPack.js
Classes
class BinaryPackError extends Error
Functions
pack(value)
unpack(buf)
packToBase64(value)
unpackBase64(str)
packedSize(value)
packEqual(a, b)
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: BinaryPack.js — custom binary codec, zero external dependencies. Wire format: MessagePack specification (https://msgpack.org/index.html) Implemented from spec only — not copied from any library. API: pack(value) → Uint8Array unpack(buf) → value packToBase64(value) → string (base64 encoded packed bytes) unpackBase64(str) → value Supported types: null / undefined → nil boolean → true / false integer (safe) → positive/negative fixint, uint8 32, int8 32 float → float64 string → fixstr / str8 / str16 / str32 Uint8Array → bin8 / bin16 / bin32 Array → fixarray / array16 / array32 Object (plain) → fixmap / map16 / map32 Byte layout (big endian throughout, per spec): 0x00–0x7f positive fixint 0x80–0x8f fixmap (N = low nibble) 0x90–0x9f fixarray (N = low nibble) 0xa0–0xbf fixstr (N = low 5 bits) 0xc0 nil 0xc2 false 0xc3 true 0xc4–0xc6 bin8 / bin16 / bin32 0xca float32 (encode uses float64 for precision) 0xcb float64 0xcc–0xcf uint8 / uint16 / uint32 / uint64 0xd0–0xd3 int8 / int16 / int32 / int64 0xd9–0xdb str8 / str16 / str32 0xdc–0xdd array16 / array32 0xde–0xdf map16 / map32 0xe0–0xff negative fixint int64/uint64 are encoded as float64 when v 2^32 (JS safe integer limit). Classes Method Signature Summary Functions Encode any JS value to a Uint8Array (MessagePack wire format). Decode a Uint8Array or ArrayBuffer from MessagePack wire format. Pack and base64 encode — useful for JSON embedding and localStorage. Decode a base64 encoded pack string. Return the packed byte size of a value without keeping the buffer. Compare two values by structural equality using pack → byte comparison. <! HUMAN NOTES Notes & Examples Command Bus Pattern The OS uses a capability gated command bus for inter app


structural equality using pack → byte comparison. <! 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/schema/OsSchemas.js
Functions
initOsSchemas()
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OsSchemas.js — all OS level schema definitions. Registers schemas into the shared SchemaRegistry singleton. Call initOsSchemas() once during KernelBootstrap. Registered names: os.AppManifest — app discovery manifest (manifest.json) os.AppSetting — one settings descriptor inside a manifest os.ModManifest — mod discovery manifest os.ModHook — one hook entry in a mod manifest os.IPCMessage — IPC channel message envelope os.VFSNode — virtual filesystem node metadata os.GPUSurface — GPU surface descriptor os.VRAMEntry — per app VRAM usage report os.ProcessEntry — process table entry os.PermissionCheck — permission check result os.Particle — particle struct for binary packing (6 × f32) os.ParticleBatch — array of particles os.NetPeerMessage — envelope sent between OS peers via NetDriver os.AppAICapabilityManifest — Particle Realms Protocol tool/resource/prompt/root declaration 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/schema/SchemaRegistry.js
Classes
class SchemaRegistry
Constants
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SchemaRegistry.js — named schema store with validation and binary packing. Acts as the central authority for all schema definitions in the OS. Schemas are registered by name and resolved by $ref. Features: Named schema registration and lookup validate(name, data) → { valid, errors } assert(name, data) → throws SchemaValidationError if invalid pack(name, data) → Uint8Array (validates then binary packs) unpack(name, buf) → value (binary unpacks then validates) packAny(data) → Uint8Array (binary packs without schema) unpackAny(buf) → value (binary unpacks without validation) Usage: import { schemaRegistry as sr } from './SchemaRegistry.js'; sr.define('myapp.MyType', { type: 'object', required: ['id'], properties: { id: { type: 'string' } } }); sr.assert('myapp.MyType', { id: 'abc' }); const bytes = sr.pack('myapp.MyType', { id: 'abc' }); Classes Method Signature Summary Register a named schema. Chainable. Return the schema for , or null. Check whether a named schema is registered. List all registered schema names. List registered versions without changing the selected default. Remove a schema. Validate data against a named schema. Validate and throw SchemaValidationError if invalid. Validate then binary pack data using MessagePack format. Binary unpack then validate. Binary pack without schema validation. Binary unpack without schema validation. Constants Re exports <! 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:


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


class SchemaValidationError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: SchemaValidator.js — JSON Schema (subset) validator, zero dependencies. Supported keywords: type string number integer boolean null array object 'any' properties { key: schema } required string[] additionalProperties boolean schema (false = deny unknown keys) items schema (all elements) or schema[] (positional) minLength / maxLength / pattern (string) minimum / maximum / exclusiveMinimum / exclusiveMaximum / multipleOf (number) minItems / maxItems (array) minProperties / maxProperties (object) const exact value match enum allowed values list oneOf / anyOf / allOf / not nullable shorthand — wraps schema as oneOf:[schema,{type:'null'}] $ref string — resolved via refResolver(name) Usage: const v = new SchemaValidator(refResolver); const { valid, errors } = v.validate(data, schema); v.assert(data, schema, 'MyContext'); // throws SchemaValidationError Classes SchemaValidator.js — JSON Schema (subset) validator, zero dependencies. Supported keywords: type string number integer boolean null array object 'any' properties { key: schema } required string[] additionalProperties boolean schema (false = deny unknown keys) items schema (all elements) or schema[] (positional) minLength / maxLength / pattern (string) minimum / maximum / exclusiveMinimum / exclusiveMaximum / multipleOf (number) minItems / maxItems (array) minProperties / maxProperties (object) const exact value match enum allowed values list oneOf / anyOf / allOf / not nullable shorthand — wraps schema as oneOf:[schema,{type:'null'}] $ref string — resolved via refResolver(name) Usage: const v = new SchemaValidator(refResolver); const { valid, errors } = v.validate(data, schema); v.assert(data, schema, 'MyContext'); // throws


Usage: const v = new SchemaValidator(refResolver); const { valid, errors } = v.validate(data, schema); v.assert(data, schema, 'MyContext'); // throws SchemaValidationError Method Signature Summary Method Signature Summary Validate data against schema. Validate and throw SchemaValidationError if invalid. Constants — Fluent schema type builders for ergonomic schema authoring. import { t } from './SchemaValidator.js'; const schema = t.obj({ name: t.str({ minLength: 1 }), age: t.int({ minimum: 0 }) }, ['name']); <! 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


readVersionedStorageRecord(storage, contract, { normalizeLegacy, normalizeCurrent })

writeVersionedStorageRecord(storage, contract, value, normalizers)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Versioned, schema specific localStorage records shared by the OS shell. Readers accept the one historical unversioned shape that each preference used before schema versioning. Writers always publish the current envelope and must successfully preflight the existing value before touching storage. Unsupported or corrupt records are therefore quarantined in place. Functions Strictly read a versioned shell preference without ever rewriting it. Preflight the old record, then atomically replace its one localStorage key. 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/schema/index.js
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: kernel/schema/index.js — barrel export for the OS schema system. Usage (anywhere in the OS): import { schemaRegistry, t, pack, unpack } from '../schema/index.js'; Re exports , , , , , , , , , , , , <! 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/state/AppStateChannelAdapter.js
Classes
class AppStateChannelAdapter
Functions
createAppStateChannelAdapter(options)
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 CSE backed State Channel authority for an app owned AppStateEngine key. AppStateEngine remains the source of truth and its expectedVersion is the compare and swap fence for every accepted intent. Method Signature Summary 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/state/AppStateEngine.js
Classes
class AppStateEngine
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AppStateEngine — app scoped CSE state exposed through guarded syscalls. Logical values are immutable EntityRegistry versions. Every successful write is HLC stamped and appended to a shared hash chained EventLog. Apps never receive the registry or log directly; Syscalls injects the authenticated appId so a caller cannot address another app's state. 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/storylets/AIStoryletFactory.js
Classes
class AIStoryletFactory
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AIStoryletFactory.js — defines the OS's AI pipeline storylets via the existing createStorylet() from engine/gameplay/narrative/StoryGraph.js. Each storylet gates on the request worldState's and advances it; Phase 9's two pass execution loop drives StoryletRuntime.tick() with these. Pipeline phases: received → classified → contextGathered → capabilitiesNegotiated → tierChosen → planned → executed → finalized (+ 'malformed' → repair) Handlers are injected (not hardcoded) so the factory stays a pure catalog; every handler receives the worldState and returns a storylet result ({ phase, facts?, observations?, ... } — see StoryletEffectsApplier). Classes Method Signature Summary Classify an incoming OS.ai() goal (task type, risk, scope). Gather app context/resources for the request (within declared roots). Negotiate short lived capabilities for the tools/resources the plan needs. Choose the model tier (fast/balanced/deep) for the task. First pass: call the planner model to produce a structured plan. Second pass: call the finalizer model over executed tool results. Repair malformed structured output (bad JSON) instead of failing the task. The full standard pipeline set, in one call. @param {object} handlers keyed by short name. <! 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/storylets/AdversarialFixtures.js
Constants
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AdversarialFixtures.js — the canned adversarial test list for the Phase 14 storylet harness. Two families: 1. DESCRIPTOR fixtures — malformed/poisoned storylet DEFINITIONS that must fail StoryletDescriptorSanitizer.scan (prompt injection, bad id, wrong handler types). 2. WORLDSTATE fixtures — hostile task states a well formed storylet must handle safely: missing tools, poisoned resource/descriptor text, hidden params, a changed attestation hash, a bad mass ratio, an exploding joint. These are DATA only; the runner decides pass/fail. means the storylet must NOT trigger (or must trigger and return a rejecting result) — never silently proceed as if the state were trustworthy. Constants — Poisoned/malformed storylet definitions — must fail sanitization. — Hostile task worldStates — a well formed storylet must handle each safely. <! 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: NaviTaskEpisodeRuntime.js — deterministic, resumable task episodes for onboarding, approvals, recovery, provider failure, handoff, and long builds. Episode actions are data only proposals. This runtime cannot execute tools, grant authority, force fire Storylets, or choose a random transition. Classes Method Signature Summary Functions 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/storylets/OSEventGraphAdapter.js
Classes
class OSEventGraphAdapter
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: OSEventGraphAdapter.js — minimal shim satisfying StoryGraph's expected EventGraph collaborator (engine/gameplay/core/ EventGraph.js doesn't exist yet). Fired storylet events are: 1. re emitted on the kernel event bus as , 2. kept in a bounded in memory log, and 3. forwarded to the Task Ledger's event/observation log once Phase 8 attaches it via setLedger(). Classes OSEventGraphAdapter.js — minimal shim satisfying StoryGraph's expected EventGraph collaborator (engine/gameplay/core/ EventGraph.js doesn't exist yet). Fired storylet events are: 1. re emitted on the kernel event bus as , 2. kept in a bounded in memory log, and 3. forwarded to the Task Ledger's event/observation log once Phase 8 attaches it via setLedger(). Method Signature Summary Phase 8: attach the Task Ledger so storylet events land in its observation log. StoryGraph collaborator contract: emit({ type, data, tags, description }). <! 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletDescriptorSanitizer.js — validates a storylet definition before registration. Reuses Phase 5's DescriptorSanitizer for prompt injection text scanning (no parallel scanner) and adds storylet specific structural checks (id shape, handler types, sane numeric gates). Classes Method Signature Summary Throw if the config fails the scan. Returns the config for chaining. <! 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletEffectsApplier.js — applies a storylet execute() result into the Task Ledger / Fact Store instead of game consequences/memories. Facts are monotonic canonical strings (engine/state/facts) — never deleted, only tombstoned — so an AI task's effect history stays audit stable. Classes Method Signature Summary Apply one fired storylet result for a request. Recognized result fields: facts: [[predicate, ...args]] — recorded in the Fact Store observations: [any] — recorded to the Task Ledger phase: string — the worldState phase to advance to <! 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletEligibilityBridge.js — layers doctrine preconditions on top of StoryGraph's built in cooldown/maxFires gating by COMPOSING them into a storylet config's canTrigger — no duplicate eligibility engine. Doctrine gates only ever NARROW eligibility (canTrigger && doctrine), never widen it. Doctrine fields: preconditions: [(worldState) = boolean] — all must pass allowedTools: [string] — worldState.requestedTool must be listed (if set) allowedResources: [string] — worldState.requestedResource must match a prefix (if set) capabilityRequired: string — checked via kernel.permissions (RuleGraph) Classes StoryletEligibilityBridge.js — layers doctrine preconditions on top of StoryGraph's built in cooldown/maxFires gating by COMPOSING them into a storylet config's canTrigger — no duplicate eligibility engine. Doctrine gates only ever NARROW eligibility (canTrigger && doctrine), never widen it. Doctrine fields: preconditions: [(worldState) = boolean] — all must pass allowedTools: [string] — worldState.requestedTool must be listed (if set) allowedResources: [string] — worldState.requestedResource must match a prefix (if set) capabilityRequired: string — checked via kernel.permissions (RuleGraph) Method Signature Summary Evaluate doctrine gates alone. @returns {{ eligible:boolean, reason:string null }} <! 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 ·


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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletFailureHandler.js — storylet chain rollback: delegates to the generic time/RollbackEngine.js (the single Saga.js wrapper — forward + compensating actions, irreversible pivot) and adds storylet specific logging + kernel eventing. If a step fails before the pivot, completed steps are compensated in reverse; past the pivot the failure is surfaced (FAILED PIVOTED) for repair instead of silently undone. Classes Method Signature Summary Run a storylet chain as a saga. Convenience: build a saga step from a storylet + runtime, using trusted forced execution as the forward action. This method is for kernel authored recovery chains, never model authored Storylets. Re exports <! 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/storylets/StoryletRuntime.js
Classes
class StoryletRuntime
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletRuntime.js — thin facade constructing from engine/gameplay/narrative/StoryGraph.js; exposes register/registerAll/tick/ getAll. Forced execution is intentionally named as a trusted test/recovery operation so it is never advertised as a model authored Storylet ability. Here "worldState" is AI task/goal state (an OS.ai() request's pipeline phase), not game state. Classes Method Signature Summary Re exports <! 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/storylets/StoryletTestRunner.js
Classes
class StoryletTestRunner
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletTestRunner.js — the Phase 14 storylet test harness. Runs a storylet definition against fixture worldStates on an ISOLATED StoryletRuntime (never the live kernel.storylets graph) and reports trigger/execute outcomes. Also runs the canned adversarial suite (AdversarialFixtures): poisoned descriptors must fail sanitization, and hostile worldStates must be handled safely (rejected or refused — never silently obeyed). Classes Method Signature Summary Run one storylet against a set of fixture worldStates. Descriptor suite — every poisoned/malformed definition must fail sanitization, and every well formed control must pass. Adversarial worldState suite — a well formed storylet run against hostile task states. A case passes when its trigger matches AND, when is set, the fired result rejects (result.ok===false, a / , or a flag) rather than silently proceeding. <! 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: StoryletVersionManager.js — tracks versions of registered storylet definitions so a definition can be upgraded in place and rolled back if the new version misbehaves. Purely in memory version history keyed by storylet id; the runtime re registers whichever config version is current. Classes StoryletVersionManager.js — tracks versions of registered storylet definitions so a definition can be upgraded in place and rolled back if the new version misbehaves. Purely in memory version history keyed by storylet id; the runtime re registers whichever config version is current. Method Signature Summary Record a new version of a storylet config. Returns the version entry. The most recently recorded version entry, or null. Full version history (metadata only — no config functions). Roll back: drop the latest version and return the previous entry (the caller re registers its config with the runtime). Null if no previous. <! 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


parseWebGpuOsTerminalCommand(raw, { surface = 'interactive' } = {})

formatWebGpuOsTerminalHelp({ surface = 'interactive', json = false } = {})

terminalCommandError(code, message, suggestion = '')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Canonical WebGPU OS terminal grammar shared by the interactive Terminal app and the read only AI tool bridge. This is intentionally not a host shell. Functions 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/time/CausalClock.js
Classes
class CausalClock
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CausalClock.js — thin wrapper over engine/state/causal/HLC.js (Hybrid Logical Clock). Orders AI task events causally while staying readable as wall time. Per CSE rule 11: a timestamp NEVER establishes authority — the commit gate decides truth; this only orders. Classes Method Signature Summary Timestamp a LOCAL event (advances the clock). Current timestamp without advancing. Merge a REMOTE timestamp so local time never regresses behind a cause. Compare two {l,c} timestamps. Returns 1 0 1. Convenience: shallow copy with an stamp attached. <! 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/time/CheckpointManager.js
Classes
class CheckpointManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CheckpointManager.js — wraps engine/state/integrity/Checkpoint.js (makeCheckpoint/verifyCheckpoint) over the shared OS event log. Checkpoints summarize history without pretending it never existed: each links to its predecessor and pins the event log head + state root at that point. Classes Method Signature Summary Create a checkpoint pinned to the current event log head. Verify a checkpoint against a freshly computed state root (+ optional predecessor). <! 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/time/CooldownManager.js
Classes
class CooldownManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CooldownManager.js — wraps engine/state/consistency/Reservation.js (ReservationManager over a USORegistry + BoundedCounterEscrow). Cooldowns are reservations: reserving a scarce AI resource (model budget, tool slot) creates a single use output that is consumed on commit or released on expiry — it can never be honored twice. Escrows divide a budget among holders for coordination free local spending. Classes Method Signature Summary The shared single spend registry — Phase 9's CommitCoordinator binds to this. <! 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/time/DependencyScheduler.js
Classes
class DependencyScheduler
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: DependencyScheduler.js — dependency ordered task readiness (Kahn style). Tracks tasks with dependency edges and answers "what can run now?": a task is ready once every dependency has completed. Cycles are rejected at add time so a plan can never deadlock on itself. Classes Method Signature Summary Add a task with dependencies. Throws if it would create a cycle. Tasks whose dependencies are all DONE and which haven't started. True when every task is DONE. Tasks permanently blocked: pending but depending (transitively) on a FAILED task. Re exports <! 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/time/ExpirationManager.js
Classes
class ExpirationManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ExpirationManager.js — TTL tracking for short lived AI artifacts (capabilities, elicitations, pending approvals). Sweep based (no timers per item): callers invoke sweep() periodically or before authorization checks; expired items run their onExpire callback exactly once and are removed. Classes ExpirationManager.js — TTL tracking for short lived AI artifacts (capabilities, elicitations, pending approvals). Sweep based (no timers per item): callers invoke sweep() periodically or before authorization checks; expired items run their onExpire callback exactly once and are removed. Method Signature Summary Track an item for . Re tracking an id replaces its TTL. True if the id is tracked and past its expiry (sweep may not have run yet). True if the id is tracked and still valid. Stop tracking without firing onExpire. Remove all expired items, invoking each onExpire once. @returns {string[]} expired ids <! 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/time/FactConflictResolver.js
Classes
class FactConflictResolver
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FactConflictResolver.js — detects and resolves conflicting live facts on the monotonic FactStore. Detection reuses the CSE constraint helpers (engine/state/facts/Constraints.js: validateFacts/atMostOne/ mutuallyExclusive) — no parallel constraint engine. Resolution tombstones losers via a caller supplied preference; a constraint never repairs on its own (CSE law), so resolution here is an explicit, logged act. Classes Method Signature Summary At most one live fact whose predicate matches (single source of truth). Two exact facts must never be live at once. Add a raw Constraints.js constraint object. Detect violations against the current live projection. Resolve conflicts among live facts sharing a predicate: keep the fact selects, tombstone the rest. Explicit and logged — never silent. <! 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/time/FactInvalidationEngine.js
Classes
class FactInvalidationEngine
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FactInvalidationEngine.js — namespaced rules layered on the monotonic FactStore (engine/state/facts): adding a fact whose predicate has invalidation rules TOMBSTONES (never deletes) currently live facts with the listed predicates. e.g. rule('planReady', ['planDraft']) — a new planReady fact revokes any live planDraft facts. History stays intact. Classes FactInvalidationEngine.js — namespaced rules layered on the monotonic FactStore (engine/state/facts): adding a fact whose predicate has invalidation rules TOMBSTONES (never deletes) currently live facts with the listed predicates. e.g. rule('planReady', ['planDraft']) — a new planReady fact revokes any live planDraft facts. History stays intact. Method Signature Summary Declare: adding a fact invalidates live facts with these predicates. Add a fact and apply its invalidation rules. Predicate of a canonical fact string: 'p(a,b)' → 'p'; bare fact → itself. <! 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


class IdempotencyCapacityError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: IdempotencyManager.js — bounded process local replay for settled tool and storylet results. Concurrent callers for one key share a single execution. Durable mutation replay safety is provided by the task graph dispatch fence, not by this TTL/LRU cache. Classes Method Signature Summary Method Signature Summary The underlying CSE registry — Phase 9's CommitCoordinator binds to this. Canonical key for a tool/storylet request. Record the first settled result for a key (no op returning the prior on replay). Run once while a key is in flight, then replay its settled result within the bounded cache window. After eviction, reads may execute again; mutations must be protected by their durable pre dispatch fence. Outcome unknown results are never treated as settled cache authority. Reserve a new execution single flight slot before a caller commits an external durable dispatch fence. Cache replay, same key join, and global capacity rejection are decided here, before that fence is written. Content free diagnostics; never exposes keys or provider receipts. 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/time/ParallelTaskScheduler.js
Classes
class ParallelTaskScheduler
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParallelTaskScheduler.js — executes async tasks respecting dependency order (via DependencyScheduler) with a bounded concurrency limit. A failed task marks its transitive dependents blocked rather than aborting unrelated branches. 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/time/ReplayEngine.js
Classes
class ReplayEngine
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ReplayEngine.js — rebuild materialized state by folding the hash chained EventLog through a reducer (event sourcing), optionally starting from a CheckpointManager checkpoint. The chain is verified BEFORE replay: tampered history refuses to replay rather than materializing a lie. Classes ReplayEngine.js — rebuild materialized state by folding the hash chained EventLog through a reducer (event sourcing), optionally starting from a CheckpointManager checkpoint. The chain is verified BEFORE replay: tampered history refuses to replay rather than materializing a lie. Method Signature Summary Replay only the events AFTER a checkpoint's covered range. <! 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/time/RetryManager.js
Classes
class RetryManager
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: RetryManager.js — bounded exponential backoff retry with jitter for transient AI/tool failures. Retries are attempts, not new intents: pair with IdempotencyManager keys so a retried effect is never applied twice. Classes Method Signature Summary Backoff delay for a (1 based) attempt number. <! 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/time/RollbackEngine.js
Classes
class RollbackEngine
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: RollbackEngine.js — the generic compensation runner: wraps engine/state/workflow/Saga.js (forward + compensating actions, irreversible pivot). Domain layers (e.g. storylets/StoryletFailureHandler.js) build on this rather than re wrapping Saga themselves. Classes Method Signature Summary Run steps as a saga: failure before the pivot compensates completed steps in reverse; failure at/after the pivot surfaces FAILED PIVOTED. Re exports <! 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/time/TickClock.js
Classes
class TickClock
Re-exports
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TickClock.js — thin wrapper over engine/state/time/TimeModel.js (TIME MODES/createTimeSource). Manages NAMED time sources: an AI task only "has time" if it subscribes to a source, and each source advances per its mode (causal steps, oscillator dt, irreversible change, observation, …) — never a global . Classes Method Signature Summary Create (or replace) a named time source. Advance a named source per its mode. Throws on unknown source. Re exports <! 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


selectTimeConsensus(samples, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Disciplined civil time authority. Network samples are transient observations. A consensus decision is accepted only after collapsing endpoints into independent operator groups, finding a majority interval, and combining the surviving offsets by uncertainty. The CSE records semantic transitions; it never treats timestamps as authority. Classes Method Signature Summary Functions Select one robust time estimate from already filtered source samples. Each operator gets at most one vote even when it exposes many hostnames. 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/time/TimeEngine.js
Classes
class TimeEngine
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TimeEngine.js — Phase 7 facade (kernel.timeEngine) composing the Time Engine's CSE wrappers around ONE shared, hash chained EventLog: authority TimeAuthority (NTP consensus + slew) — disciplined physical time causal CausalClock (HLC) — causal ordering ticks TickClock (TimeModel sources) — per mode progression eventLog engine/state EventLog — the single OS AI log (Phase 9's AuditLog views the same log) timeline TimelineExporter — tamper evident export checkpoints CheckpointManager — compaction + restore replay ReplayEngine — event sourced rebuild idempotency IdempotencyManager — at most once effects cooldowns CooldownManager — reservations + escrow rollback RollbackEngine (Saga) — compensation scheduler Dependency/ParallelTaskScheduler — ordered execution retry RetryManager — bounded backoff expiry ExpirationManager — TTL sweep facts engine/state FactStore (direct reuse — no FactRegistry) invalidation/conflicts — rules layered on the monotonic FactStore Classes Method Signature Summary New dependency scheduler for one plan (per request, not shared). New bounded concurrency runner for one plan (per request, not shared). Append an HLC stamped event to the shared OS AI event log. <! 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/time/TimelineExporter.js
Classes
class TimelineExporter
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TimelineExporter.js — export view over engine/state/integrity/EventLog.js (append only, hash chained). Filters + serializes a range of the SHARED OS event log (the same log Phase 9's AuditLog views — one log, not two) with the chain verification result attached, so an exported timeline is tamper evident. Classes TimelineExporter.js — export view over engine/state/integrity/EventLog.js (append only, hash chained). Filters + serializes a range of the SHARED OS event log (the same log Phase 9's AuditLog views — one log, not two) with the chain verification result attached, so an exported timeline is tamper evident. 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/tools/CapabilityAttenuator.js
Classes
class CapabilityAttenuator
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CapabilityAttenuator.js — thin wrapper over engine/state Capability.attenuate() for narrowing a capability before handing it to a single tool call. Never widens a capability (attenuate() itself enforces this). Classes Method Signature Summary Attenuate a capability so it only authorizes a single named tool. Attenuate a capability so it only authorizes use within a single OS.ai() request. <! 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/tools/ContextTaintTracker.js
Classes
class ContextTaintTracker
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ContextTaintTracker.js — tracks which OS.ai() request contexts have absorbed untrusted (tool/webpage/model) content, so prompt assembly can keep the CSE prompt injection boundary visible downstream instead of silently blending untrusted text into "instructions". Classes ContextTaintTracker.js — tracks which OS.ai() request contexts have absorbed untrusted (tool/webpage/model) content, so prompt assembly can keep the CSE prompt injection boundary visible downstream instead of silently blending untrusted text into "instructions". Method Signature Summary Wrap untrusted content with explicit delimiters for prompt assembly. <! 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/tools/HiddenParameterDetector.js
Classes
class HiddenParameterDetector
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: HiddenParameterDetector.js — flags AI supplied tool call arguments that are NOT declared in the tool's schema (potential smuggled/hidden parameters) and prototype pollution shaped keys. 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/tools/MetadataRugPullDetector.js
Classes
class MetadataRugPullDetector
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 Method Signature Summary Record/compare a tool's current descriptor. <! 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/tools/ToolCallSchemaValidator.js
Classes
class ToolCallSchemaValidator
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ToolCallSchemaValidator.js — validates AI supplied tool call arguments against the tool's declared JSON schema, reusing the existing webgpu os/kernel/schema/SchemaValidator.js (no parallel validator). 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/tools/ToolPermissionChecker.js
Classes
class ToolPermissionChecker
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ToolPermissionChecker.js — gates AI initiated tool calls through kernel.permissions (RuleGraph), on top of (not instead of) the per tool AffordanceRegistry.capabilityRequired check done by ToolRouter. Classes ToolPermissionChecker.js — gates AI initiated tool calls through kernel.permissions (RuleGraph), on top of (not instead of) the per tool AffordanceRegistry.capabilityRequired check done by ToolRouter. Method Signature Summary Blanket check: may this app route tool calls through the AI Hub at all? Same as canExecuteTools() but throws (via Permissions.require) when denied + enforcing. Per tool capability declared by the tool's affordance (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 Architecture · Security Model


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

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ToolResultIngestAdapter.js — the single chokepoint every AI invoked tool result passes through on its way into the world model. Delegates to engine/state/worldmodel/UntrustedBoundary.js (no parallel wrapper); a tool result is always trusted:false and can never mint authority. Classes Method Signature Summary Ingest a tool execution result as an untrusted observation. <! 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/tools/ToolRouter.js
Classes
class ToolRouter
Functions
boundedAIValue(value, output = '')
Notes & Examples
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ToolRouter.js — AI Tool Firewall. The single entrypoint the AI Hub's tool calling loop uses to run a registered tool on behalf of an app. Delegates actual tool registration/execution/history to the existing ToolDriver.js (kernel.toolDriver) — this class never duplicates that machinery, it wraps it with the checks an AI initiated call needs before it's safe to run: permission check, rug pull detection, hidden parameter detection, schema validation, and affordance/capability gating. Every result is then ingested through the CSE prompt injection boundary (ToolResultIngestAdapter → engine/state UntrustedBoundary) before it's handed back — a tool result is observation, never authority. Classes Method Signature Summary Create an object identity capability for one exact Faculty invocation. The token has no writable surface. It is deliberately not serializable into a signed capability or exposed through app syscalls. Rebuild an unresolved meter from encrypted operation evidence after restart. Bind the opaque meter to the signed capability and exact resource lease. Run one kernel verifier with every trusted boundary receipt charged to its reserved lane. Attach one kernel authored resource receipt. Values returned by a tool handler are never inspected for accounting and cannot call this method through the app syscall surface. Kernel only Navi Faculty entrypoint. This method is intentionally absent from Syscalls and AppRegistrationScope. It enters the same firewall as callForAI, but carries an out of band, object identity branded one shot authorization created by NaviFacultyService. Run a tool on behalf of an app's AI request, through the full firewall pipeline, then delegate execution to


shot authorization created by NaviFacultyService. Run a tool on behalf of an app's AI request, through the full firewall pipeline, then delegate execution to ToolDriver. Consume and independently bind one exact Faculty grant at dispatch. Tool schemas exposed to the AI (delegates to ToolDriver). 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


packages/AppCompiler.js

packages/AppCompiler.js
Classes
class AppCompiler
class CompatGuestApp
Functions
buildFilesMap()
Constants
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: AppCompiler.js — compile an ingested source bundle into a signed . Two paths: 1. NATIVE — the folder already has a valid + JS entry. Files are packaged as is under . 2. AUTO — any HTML/WebGPU app. We probe it (engine/compat), generate a compatibility profile, an embedded source module ( ), and a bootloader entry ( ) that calls at mount time. A normal WebGPU app → an engine native, signed OS app. Output uses PackageBuilder.buildV2 (signed + encrypted + merkle + cert). With a developer (self signed) key the package verifies as the community/unofficial tier; a root issued cert promotes it to trusted. Classes Method Signature Summary The bootloader entry class shipped as . The shared CompatGuestApp bootloader class body. Identical text is emitted by PackageLoader's self heal path so old and new packages behave the same. Beyond booting the guest, the bootloader INJECTS lifecycle commands into the OS CommandBus at mount (capability gated via ) and tears them down on unmount — the build time "command injection" + interception seam. Embed the guest files + profile as . Functions Constants <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier.


packages/AppCompiler.js

developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/CapabilityMap.js

classifyPermissions({ signals, declared = [], granted = [] } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: CapabilityMap.js — OS adaptive bridge between the compat static probe and the kernel's capability vocabulary. The kernel's RuleGraph is the single source of truth for what capabilities exist ( ) and how risky each one is ( ). This module classifies EVERY known capability into one disposition and, for the statically detectable ones, maps a compat probe signal ( / ) onto it. Dispositions: 'free' — universally allowed by the default rule graph; never emitted (the app already has it). 'auto' — detectable + low/medium risk → auto added when the probe sees it. 'suggest' — detectable + high risk → SURFACED for review, never silently added. 'declare' — grantable but not statically inferable → author opts in. 'system' — privileged / system trust → never auto added under any path. 'runtime' — kernel mediated ephemeral consent token → never accepted from or emitted into an application manifest. Least privilege is preserved: only 'auto' caps are granted without review; high risk and privileged caps always require an explicit decision. IMPORTANT — this is a BUILD TIME ADVISORY layer, not a security boundary. Static source scanning has unavoidable false negatives (minification, obfuscation, dynamically constructed API calls, runtime behavior that differs from source). The authoritative gate is the kernel's runtime complete mediation stack: default deny + per call + the . Auto added caps only ever cover low/medium risk APIs, so a missed or spoofed signal cannot silently escalate to a high risk capability. A module load guard logs any kernel capability that is missing a disposition, so the table can never silently drift behind a newly added kernel cap; the Security Doctor surfaces the same check


packages/CapabilityMap.js

capability that is missing a disposition, so the table can never silently drift behind a newly added kernel cap; the Security Doctor surfaces the same check ( ) at boot. Functions Resolve a capability's disposition string ('free' 'auto' 'suggest' 'declare' 'system' 'runtime' 'unknown'). Risk level for a cap, read from the kernel's CAPABILITY LABELS (default 'medium'). Run every detector against probe signals. Detectors are wrapped so a single malformed signal or detector bug can never throw during a build — a failing detector is treated as "not detected" and a one time warning is logged. (Static detection is best effort UX; the kernel's runtime guard remains the authoritative boundary — see module header.) Returns: detected capability strings Classify a probe against what is already declared/granted and produce the final permission list + a reconciliation report. Parameters: (object) — No description in source JSDoc. (string[]) — — author/manifest declared caps (native path) (string[]) — — caps already decided elsewhere (e.g. the Returns: {{ permissions:string[], detected:string[], autoAdded:string[], Kernel capabilities that have no disposition in this table (should be empty). Capabilities classified here that no longer exist in the kernel vocabulary (stale entries). Self audit for the Security Doctor / boot self test. Returns coverage counts and any drift (kernel caps with no disposition, or table entries that are no longer kernel caps). is true only when there is no drift in either direction. Constants — Disposition + (for detectable caps) a predicate, keyed by the exact capability string from KNOWN CAPABILITIES. A bare string is shorthand for (no detector). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted


packages/CapabilityMap.js

A bare string is shorthand for (no detector). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Secu


packages/FolderIngestor.js

packages/FolderIngestor.js
Classes
class FolderIngestor
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FolderIngestor.js — turn any developer source into a { files, entry } bundle that AppCompiler can package. Sources: • Directory picker (File System Access ) • <input type="file" webkitdirectory FileList • A single HTML File • A (Uint8Array/ArrayBuffer/File) via Zip.parse • The OS VFS (a folder path or single file) via StorageManager • A remote URL (single file HTML; CORS aware) Output: { files: Map<string, string Uint8Array , entry: string, sourceType: string, name: string } Text files are decoded to strings; binary files stay as Uint8Array. Classes Method Signature Summary Native directory picker (Chromium). Walks the whole tree. From an <input type="file" webkitdirectory (or multiple files) FileList. A single HTML file. A archive (File Uint8Array ArrayBuffer). A VFS folder path or single file, via a StorageManager. A remote single file HTML app. Resolution order: 1. The WebGPU OS browser extension's proxy fetch bridge — fetches the page cross origin with a real browser session, no CORS limits, no external service. Used automatically when the extension is detected. 2. A direct (works only for CORS enabled / same origin URLs). 3. An explicit CORS proxy passed via . <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a


packages/FolderIngestor.js

tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/Gzip.js

packages/Gzip.js
Functions
async gzip(input)
async gunzip(input, opts = {})
async gunzipText(input, opts = {})
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Gzip.js — gzip compress/decompress via the browser native Compression Streams API. This is the SAME approach uses for the runtime bundle ( ) and its loader: gzip the payload, then (optionally) AES GCM it, and decompress in browser with . No custom container format — a payload is just . gzip carries its own whole stream CRC 32 (validated by DecompressionStream), and we layer per file SHA 256 + a signed Merkle root on top, so integrity is covered. Functions Gzip compress a string or bytes. Parameters: (string Uint8Array ArrayBuffer) — No description in source JSDoc. Gunzip to bytes, with a decompressed size cap (zip bomb guard). Parameters: (Uint8Array ArrayBuffer) — No description in source JSDoc. Gunzip to a UTF 8 string. <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/Gzip.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


packages/PackageBuilder.js

packages/PackageBuilder.js
Classes
class PackageBuilder
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageBuilder.js — build a signed .prpkg from a folder of files. Output format (JSON envelope — zip support planned): { format: 'prpkg v1', manifest: { ... }, // manifest.json with files hash map blockmap: { files: {...} }, // sha256 per file signature: { pubKey, sig }, // ECDSA P 256 over blockmap JSON files: { path: content } // all file contents as strings } Usage: const pkg = await PackageBuilder.build({ id: 'os.my app', name: 'My App', version: '1.0.0', publisher: 'local', entry: 'files/app.html', permissions: ['gpu'], files: { 'files/app.html': '<html ...' } }, cryptoDriver); Classes Method Signature Summary Build a signed .prpkg package object. Serialize a pkg envelope to a JSON string (for download/storage). Deserialize a JSON string back to a pkg envelope. Create a Blob download for a built package. Trigger a browser download of a built package. Fail fast on unsafe package ids, versions, entry paths, and file paths. Read the optional Faculty binding without invoking accessors. Build a v2 artifact: an encrypted gzip container (gzip of a JSON payload {manifest, blockmap, files}) plus a public JSON envelope that the OS uses to cross verify the decrypted payload. Same codec the bundler uses. Download a v2 build: writes both (binary) and (envelope). Build a v3 artifact as a JHC1 binary container. The manifest, blockmap, file hashes, and a raw ECDSA P 256 signature over the JHC1 root hash are embedded in the canonical manifest. The resulting artifact is a single self describing binary file. Download a v3 build as a single self contained file. Build a hot patch from a base package to a target package. Ships ONLY the added/changed files (full content) + the list of removed


packages/PackageBuilder.js

single self contained file. Build a hot patch from a base package to a target package. Ships ONLY the added/changed files (full content) + the list of removed paths, and carries the TARGET package's SIGNED manifest/blockmap/signature/ cert. The OS reconstructs base+delta and verifies the result against that signed metadata, so a delta is exactly as tamper evident as a full package. Both inputs are parsed pkg objects ({ manifest, blockmap, signature, cert, files }). The target MUST already be signed (its envelope's signature/cert). Return an adaptive coder that uses TokenCodec when it is smaller than raw text. Verify an offline policy before it is allowed to influence build work. Convert a DER ECDSA P 256 signature to raw 64 byte r s for JHC1. Trigger a browser download of a delta as . Download a v2 build as a SINGLE self contained (envelope embedded). <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/PackageBuilder.js

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


packages/PackageCrypto.js

packages/PackageCrypto.js
Classes
class PackageCrypto
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageCrypto.js — AES GCM payload encryption for .prpkg v2 containers. SECURITY NOTE (acknowledged in the plan): in a browser the decryption key must ship with the OS, so this encryption is OBFUSCATION / a licensing and guard hook — NOT true secrecy. Package authenticity comes from the ECDSA signature + the ring 0 trust chain (Phase 2), not from this encryption. Container binary layout ( v2): bytes 0..5 magic "PRPKG2" byte 6 version (0x02) byte 7 flags (bit0 = encrypted) bytes 8..19 AES GCM IV (12 bytes) [only if encrypted] bytes 20.. ciphertext (AES GCM, tag appended) or plaintext gzip if not encrypted The inner plaintext is gzip(JSON{manifest, blockmap, files}) — the same gzip codec the bundler uses, decompressed in browser via DecompressionStream('gzip'). ── Single file layout ( , embeds the envelope) ────────────────────── A v2 package historically shipped as TWO files (the binary container + a sidecar envelope). fuses both into ONE self describing , so there is a single artifact to move around and verify: bytes 0..5 magic "PRPKGS" byte 6 version (0x01) byte 7 reserved (0x00) bytes 8..11 envelope length (uint32, little endian) bytes 12.. envelope JSON (UTF 8) then the full PRPKG2 container bytes (as produced by seal()) reverses it. The envelope is the PUBLIC, signed metadata; the embedded container is cross verified against it by PackageVerifier.parseV2 (manifest + blockmap equality, signed blockmap.manifestHash, AES GCM AAD = id@version, and the ECDSA signature) — so tampering with either half is detected. Classes Method Signature Summary Provide ring 0 key material (raw bytes) — called by TrustStore when available. Wrap raw zip bytes into an encrypted v2 container. Unwrap


packages/PackageCrypto.js

Signature Summary Provide ring 0 key material (raw bytes) — called by TrustStore when available. Wrap raw zip bytes into an encrypted v2 container. Unwrap a v2 container back into raw zip bytes. Fuse a public envelope object + a PRPKG2 container into ONE self describing file (see the layout note at the top of this module). True if the bytes start with the PRPKGS single file magic. Split a single file back into { envelope, container }. True if the bytes start with the JHC1 magic (PRPKG v3 container). True if the bytes start with the PRPKG2 magic. <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/PackageLoader.js

packages/PackageLoader.js
Classes
class PackageLoader
class CompatGuestApp
Notes & Examples
Basic loading
Trust tiers and capabilities
Dependency resolution
Sandboxing and permissions
Hot reload (development)
Error handling
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageLoader.js — load an installed .prpkg app's entry module from OPFS. Installed packages live at: /os/packages/installed/{appId}/{version}/files/{relPath} Loading strategy: 1. Gather every file under the package's files/ dir. 2. Apply enabled PatchManager overlays (file overlay layer) on top of base files. 3. Build a blob URL module graph: each JS module's relative import/export specifiers are rewritten to the blob URL of the corresponding packaged file, resolved in dependency order (best effort for cycles). 4. import() the entry blob URL and return the module namespace. Why rewrite specifiers instead of an import map? Import maps must exist before the first module loads; we resolve packages at runtime, so we inline the graph by rewriting relative specifiers to blob URLs. Blob URLs are retained for the lifetime of the loaded app and revoked when the package is reloaded or removed. Classes Method Signature Summary True if a service worker is controlling this page and can serve package files. Immutable native URL: <os base / jhc apps /{appId}/{rootHash}/files/{rel}. Load (or reload) an installed app's entry module namespace. The canonical compat bootloader entry (files/index.js), regenerated at load time so stale packages keep working without a republish. Rather than ing ./ compat source.js (cross module binding through this loader's blob graph rewriter proved fragile — the rewritten/relative import failed to bind, yielding "profile/ compat is not defined"), we INLINE the source module's content directly and strip its keywords so its / / become locals in the same scope. The result is a single self contained module with NO imports for the linker to touch. is the raw ./ compat


packages/PackageLoader.js

keywords so its / / become locals in the same scope. The result is a single self contained module with NO imports for the linker to touch. is the raw ./ compat source.js content. Release blob URLs for an app (call on remove). Gather an installed package's files (patch overlay aware) WITHOUT building a blob graph or importing — used by the isolated package realm, which ships the raw files into an opaque origin iframe and builds the graph there. <! HUMAN NOTES Notes & Examples Loads and verifies signed bundles at runtime. Handles trust tier checks, capability grants, sandbox initialization, and dependency resolution. Basic loading Trust tiers and capabilities Dependency resolution Sandboxing and permissions Hot reload (development) Error handling See also: Package Trust Tiers · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/PackageManager.js

packages/PackageManager.js
Classes
class PackageManager
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageManager.js — install, remove, update, verify, repair, rollback .prpkg packages. Package lifecycle: download/pick → stage → verify → install → register → (update → rollback) Storage layout: /os/packages/installed/{appId}/{version}/ ← active package files /os/packages/staging/{appId}/{version}/ ← in progress installs /os/packages/rollback/{appId}/{version}/ ← previous version for rollback /os/packages/locks/{appId}.lock.json ← prevents concurrent installs /os/packages/chunks/sha256 {hash} ← chunk cache (CacheDriver) Classes Method Signature Summary Re register previously installed (non builtin) packages into AppRegistry on boot so they survive reload and appear/launch like built ins. Map a prpkg manifest → AppRegistry app manifest shape (resolvedEntry = pkg:<id ). Load an installed package's entry module namespace (used by Desktop for pkg:<id ). Revoke the blob URLs created for an installed package's module graph. Called by the shell when a package app's window closes (lifecycle cleanup). No op for built ins / apps that were never package loaded. Gather an installed package's raw files for isolated realm execution. This OS instance's publisher identity. Give to the issuer tool ( ) to mint a root signed cert that makes your packages verify as TRUSTED. Import a root issued publisher cert ( ). It is only stored if it actually matches THIS OS's signing identity (otherwise it's useless here). Map a trust verdict → a user facing trust tier (label + badge). trusted → root chained, fully trusted community → self signed and pinned/accepted on this device (unofficial) unverified → self signed, not yet pinned quarantined → blocked (integrity/provenance/high risk) Trust tier for an


packages/PackageManager.js

pinned/accepted on this device (unofficial) unverified → self signed, not yet pinned quarantined → blocked (integrity/provenance/high risk) Trust tier for an installed app id. The stored publisher cert, but only if it matches the current signing identity. Synchronous trust profile for the syscall guard (default deny egress). Built ins / unknown apps are trusted; installed packages carry their verdict. restricted → network requires explicit grant (no auto allow) blocked → quarantined: hard deny network/egress capabilities Phase 2 execution policy for an app id — decides the runtime realm an app's code may use, based on its trust verdict: 'shared' → may run in the shared OS origin (built ins + root trusted) 'isolated' → must run in an opaque origin sandbox iframe (pinned/untrusted) 'none' → must NOT run (quarantined); inspect/export/remove only Built ins and unknown ids (no cached verdict) resolve to 'shared'. Register a consent handler the shell can override with a nice modal. Signature: async (info) = boolean (true = user accepts the install) info = { appId, publisher, fingerprint, permissions, verdict, scan, publisherChanged } Single verify → trust/pin → provenance → scan → policy choke point. A future kernel guard can subscribe/override here. Does NOT prompt — returns a verdict the caller (install) acts on. Prompt for install consent (shell handler if set, else a confirm() fallback). Validate the id, version, entry, and every file path in a package before consent/storage. Install a local package from a binary container + optional envelope. Auto detects v3 JHC1, v2 PRPKG2, and single file PRPKGS formats. Used by the Package Manager's drop two files flow (offline, no URL needed). Backward compatible alias for installLocal. Install a SINGLE file (envelope embedded — no


packages/PackageManager.js

the Package Manager's drop two files flow (offline, no URL needed). Backward compatible alias for installLocal. Install a SINGLE file (envelope embedded — no sidecar). Auto detects v3 JHC1, v2 PRPKGS single file, and legacy PRPKG2 single file. Apply a hot patch to an already installed package. Reads the installed base payload, reconstructs the target file set (base − removed + changed), then routes through the normal install() — which verifies EVERY file hash, the merkle root, the signed manifestHash, the publisher signature and the rotating cert's chain to root + validity window, and stages/swaps with rollback. A forged or stale delta simply fails verification and is rejected, leaving the installed copy untouch


packages/PackageRegistry.js

packages/PackageRegistry.js
Classes
class PackageRegistry
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageRegistry.js — IndexedDB backed registry of installed packages. Each record in the 'packages' store: { id: 'os.shader lab', name: 'Shader Lab', version: '1.0.0', activeRootHash: 'a1b2c3d4...', // content addressed install directory rollbackRootHash: '...', // previous activation root hash rollbackVersion: null, rollbackAvailable: false, publisher: 'local', installedAt: 1234567890, updatedAt: 1234567890, entryPath: '/os/packages/installed/os.shader lab/a1b2c3d4.../files/app.html', manifest: { ...full manifest... }, format: 'prpkg v1', trustVerdict: 'trusted', pinned: false, pinnedVersion: null, sourceUrl: null, // URL to check for updates } Classes PackageRegistry.js — IndexedDB backed registry of installed packages. Each record in the 'packages' store: { id: 'os.shader lab', name: 'Shader Lab', version: '1.0.0', activeRootHash: 'a1b2c3d4...', // content addressed install directory rollbackRootHash: '...', // previous activation root hash rollbackVersion: null, rollbackAvailable: false, publisher: 'local', installedAt: 1234567890, updatedAt: 1234567890, entryPath: '/os/packages/installed/os.shader lab/a1b2c3d4.../files/app.html', manifest: { ...full manifest... }, format: 'prpkg v1', trustVerdict: 'trusted', pinned: false, pinnedVersion: null, sourceUrl: null, // URL to check for updates } Method Signature Summary <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust


packages/PackageRegistry.js

issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/PackageScanner.js

packages/PackageScanner.js
Classes
class PackageScanner
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageScanner.js — heuristic static pre scan of package contents. This is an EARLY WARNING badge, not a guarantee: novel obfuscation will evade heuristics. The real containment is default deny egress + sandboxed execution (see PermissionPortal / guardSyscalls). The scanner flags the patterns seen in real 2025–2026 supply chain payloads: heavy obfuscation, base64 blobs, dynamic code execution, credential/secret access, network exfiltration, and payloads hidden inside non code assets. scan(pkg) → { risk: 'low' 'medium' 'high', findings: [{ level, code, file, msg }] } Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture 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


packages/PackageVerifier.js

packages/PackageVerifier.js
Classes
class PackageVerifier
Notes & Examples
Packaging & trust tiers
Packaging & trust tiers
Command Bus Pattern

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PackageVerifier.js — verifies .prpkg package integrity. Verification steps: 1. Validate manifest schema (format, required fields) 2. Verify each file's SHA 256 hash against blockmap 3. Verify ECDSA P 256 publisher signature over blockmap hash The publisher key fingerprint is stored in the manifest. Trusted publishers are managed by kernel.permissions. Classes Method Signature Summary Compute SHA 256 of a string or ArrayBuffer. Returns hex string. Compute SHA 256 of every file in a files map { path → content(string) }. Returns { path → sha256hex } record. Fingerprint (16 hex chars) of a base64 raw public key — the SAME scheme the OS identity uses: SHA 256(raw key)[:16]. Used to detect fingerprint spoofing. Compute a binary Merkle root over a { path → sha256 } map — a single tamper evident hash covering EVERY file. Domain separated leaves/nodes ("leaf:"/"node:") defend against second preimage attacks; the last node is duplicated for odd levels. Stored in the (signed) blockmap as . Verify a parsed package object. Decrypt + unzip a v2 container and cross verify it against its public JSON envelope. Returns a unified pkg object compatible with verify() and install(): { format, manifest, blockmap, signature, cert, files, ... }. Throws if cross verification fails (container hash, manifest, or blockmap disagree with the envelope) — this is the "double verify" guarantee. Parse a SINGLE file (envelope embedded ahead of the container). Splits it, then runs the exact same cross verification as parseV2 — so a one file package is just as tamper evident as the two file form. True if the bytes are a single file (embedded envelope) . Auto detect package format and parse into a unified pkg object.


packages/PackageVerifier.js

tamper evident as the two file form. True if the bytes are a single file (embedded envelope) . Auto detect package format and parse into a unified pkg object. Supports: prpkg v3 JHC1 binary, prpkg v2 binary, single file PRPKGS, and JSON envelopes (v1/v2/v3 with optional remote container fetch). Parse a v3 binary container (JHC1 format). Returns a unified pkg object compatible with verify() and install(). Schema validate a hot patch envelope. Reconstruct the full target package from a delta + the installed base files (base − removed + changed). Returns a pkg object shaped for verify()/install(). It does NOT trust the delta: the caller runs the normal verification, which checks every file hash, the merkle root, the signed manifestHash, the publisher signature and the cert's chain to root + validity window — so a forged/stale delta cannot reconstruct a package that verifies. Verify a single downloaded chunk against its expected sha256. <! HUMAN NOTES Notes & Examples Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. See also: Security & Trust Model · WebGPU OS Architecture Packaging & trust tiers OS apps ship as signed bundles (V2: signed + encrypted + merkle + cert). A developer (self signed) key verifies as the community / unofficial tier; a root issued cert promotes it to trusted , and capability grants scale with the tier. Example: Loading a package with trust check See also: Security & Trust Model · WebGPU OS Architecture Command Bus Pattern The OS uses a capability gated command bus for inter app and system communication. Apps register command handlers; the


packages/PackageVerifier.js

OS Architecture 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