Read-Only Runtime System Information

NAP-SYSTEM

Read-Only Runtime System Information

draft

NAP ID: NAP-SYSTEM Domain: system Depends: none. Web binding (NIP-5D): window.napplet.system; domain presence signals availability.

Description

NAP-SYSTEM gives a napplet read-only access to runtime status snapshots. It is for diagnostics, settings panes, support views, and adaptive UI. It reports what the runtime knows about NAP support, services, relays, caches, storage surfaces, media surfaces, and napplet-scoped resources.

The runtime owns aggregation. A napplet asks a narrow accessor for one category; the runtime decides which internal sources to query, how fresh the answer is, and which details are safe to reveal. NAP-SYSTEM does not grant access to any capability it reports.

API Surface

Operation	Parameters	Result	Wire
naps	none	list of SystemNapStatus	system.naps / system.naps.result
services	none	list of SystemServiceStatus	system.services / system.services.result
relays	none	list of SystemRelayStatus	system.relays / system.relays.result
eventCache	none	SystemStorageStatus	system.eventCache / system.eventCache.result
media	none	SystemMediaStatus	system.media / system.media.result
nappletStorage	none	SystemStorageStatus	system.nappletStorage / system.nappletStorage.result
scopes	none	list of SystemScopeSummary	system.scopes / system.scopes.result
scope	name (tstr)	SystemScopeStatus	system.scope / system.scope.result

Schemas

Enumerations:

Name	Values
SystemHealth	ok, degraded, unavailable, unknown

SystemNapStatus:

Field	Type	Required	Description
domain	tstr	yes	NAP domain.
supported	bool	yes	Whether the domain is supported for this napplet.
required	bool	no	Whether the domain is required by this napplet.
protocols	list of tstr	no	Supported numbered protocol identifiers.
health	SystemHealth	no	Runtime health for this domain.

SystemServiceStatus:

Field	Type	Required	Description
name	tstr	yes	Runtime-defined service name.
available	bool	yes	Whether the service is available.
health	SystemHealth	yes	Service health.
message	tstr	no	Optional diagnostic text.

SystemRelayStatus:

Field	Type	Required	Description
url	tstr	yes	Relay URL.
read	bool	yes	Whether reads are available.
write	bool	yes	Whether writes are available.
connected	bool	yes	Whether the runtime is currently connected.
health	SystemHealth	yes	Relay health.
latencyMs	number	no	Measured latency in milliseconds.

SystemStorageStatus:

Field	Type	Required	Description
available	bool	yes	Whether the storage surface is available.
health	SystemHealth	yes	Storage health.
bytesUsed	uint	no	Approximate bytes used.
bytesQuota	uint	no	Approximate byte quota.
itemCount	uint	no	Approximate stored item count.
persistent	bool	no	Whether storage is expected to persist.
message	tstr	no	Optional diagnostic text.

SystemMediaStatus:

Field	Type	Required	Description
available	bool	yes	Whether the media surface is available.
health	SystemHealth	yes	Overall media health.
audioOutput	SystemHealth	no	Audio-output health.
audioInput	SystemHealth	no	Audio-input health.
videoInput	SystemHealth	no	Video-input health.
playback	SystemHealth	no	Playback health.
activeSessions	uint	no	Active media session count.
message	tstr	no	Optional diagnostic text.

SystemScopeSummary:

Field	Type	Required	Description
name	tstr	yes	Scope name, such as storage, media, relay, or cache.
available	bool	yes	Whether the scope is available.
health	SystemHealth	yes	Scope health.

SystemScopeStatus:

Field	Type	Required	Description
name	tstr	yes	Scope name.
available	bool	yes	Whether the scope is available.
health	SystemHealth	yes	Scope health.
details	map of tstr to any JSON value	yes	Runtime-defined details scoped to this napplet.

Each method returns a snapshot. The runtime MAY cache, redact, or synthesize fields. Omitted optional fields mean "not reported", not zero.

naps() returns NAP support visible to this napplet. It MAY include global runtime support, per-napplet grants, and numbered protocol support.

services() returns named runtime service availability and health. Service names are runtime-defined and need not map one-to-one to NAP domains.

relays() returns connected relay status. It reports relay transport health, not user relay preferences. User relay preferences belong to NAP-IDENTITY.

eventCache() returns runtime event-cache details, such as approximate size, quota, persistence, and health.

media() returns runtime media status: playback, capture availability, active sessions, and health. It does not grant camera, microphone, screen, or playback control.

nappletStorage() returns storage details scoped to the requesting napplet, such as NAP-STORAGE usage, quota, persistence, and health.

scopes() lists napplet-scoped diagnostic areas available through scope(name).

scope(name) returns details scoped to this napplet. Examples include NAP-STORAGE usage for the current napplet, per-napplet media sessions, scoped relay budgets, or scoped cache entries. The details object is runtime-defined; the stable contract is the accessor, scope name, and read-only status envelope.

Global vs Scoped

Global accessors describe runtime-wide systems as redacted for this napplet:

Accessor	Reports
naps()	NAP support, grants, and numbered protocol support
services()	runtime service availability and health
relays()	connected relay health
eventCache()	event-cache health, usage, and persistence
media()	media subsystem health and active session count

Scoped accessors describe only resources attributable to the requesting napplet:

Accessor	Reports
nappletStorage()	NAP-STORAGE-style usage for this napplet
scopes()	which scoped areas can be queried
scope(name)	runtime-defined details for one scoped area

The runtime MUST NOT expose another napplet's scoped details through NAP-SYSTEM.

Wire Protocol

system.* messages use the NIP-5D wire format ({ "type": "domain.action", ...payload }).

Type	Direction	Payload fields
system.naps	napplet -> runtime	id
system.naps.result	runtime -> napplet	id, naps?, error?
system.services	napplet -> runtime	id
system.services.result	runtime -> napplet	id, services?, error?
system.relays	napplet -> runtime	id
system.relays.result	runtime -> napplet	id, relays?, error?
system.eventCache	napplet -> runtime	id
system.eventCache.result	runtime -> napplet	id, status?, error?
system.media	napplet -> runtime	id
system.media.result	runtime -> napplet	id, status?, error?
system.nappletStorage	napplet -> runtime	id
system.nappletStorage.result	runtime -> napplet	id, status?, error?
system.scopes	napplet -> runtime	id
system.scopes.result	runtime -> napplet	id, scopes?, error?
system.scope	napplet -> runtime	id, name
system.scope.result	runtime -> napplet	id, scope?, error?

Key design notes:

• Every operation is read-only.
• Request/result pairs use id for correlation.
• There is no push surface. Napplets that need fresh status call the accessor again.
• The runtime MAY redact, bucket, or omit sensitive fields.
• The runtime MAY return stale-but-useful status if live probing is expensive.

Examples

NAP support:

-> { "type": "system.naps", "id": "n1" }
<- {
     "type": "system.naps.result",
     "id": "n1",
     "naps": [
       { "domain": "shell", "supported": true, "required": true, "health": "ok" },
       { "domain": "storage", "supported": true, "health": "ok" },
       { "domain": "inc", "supported": true, "protocols": ["NAP-4"], "health": "ok" }
     ]
   }

Relay and event-cache status:

-> { "type": "system.relays", "id": "r1" }
<- {
     "type": "system.relays.result",
     "id": "r1",
     "relays": [
       { "url": "wss://relay.example.com", "read": true, "write": true, "connected": true, "health": "ok", "latencyMs": 82 }
     ]
   }

-> { "type": "system.eventCache", "id": "c1" }
<- {
     "type": "system.eventCache.result",
     "id": "c1",
     "status": { "available": true, "health": "ok", "bytesUsed": 7340032, "persistent": true }
   }

Scoped storage status for this napplet:

-> { "type": "system.nappletStorage", "id": "s1" }
<- {
     "type": "system.nappletStorage.result",
     "id": "s1",
     "status": { "available": true, "health": "ok", "bytesUsed": 4096, "itemCount": 12 }
   }

-> { "type": "system.scope", "id": "s2", "name": "media" }
<- {
     "type": "system.scope.result",
     "id": "s2",
     "scope": {
       "name": "media",
       "available": true,
       "health": "ok",
       "details": { "activeSessions": 1 }
     }
   }

Error Handling

Result messages include an error string when the runtime cannot fulfill the request. Common errors: "unsupported", "policy denied", "unavailable", "unknown scope", and "probe failed".

When a result includes error, it SHOULD still include a conservative fallback when possible, such as available: false with health: "unknown".

Runtime Behavior

• The runtime MUST respond to every request with a result message carrying the same id.
• The runtime MUST NOT mutate runtime state to answer a system accessor, except for incidental measurement work required to produce the snapshot.
• The runtime MUST aggregate system details itself. Napplets MUST NOT be required to call lower-level NAPs to assemble a system view.
• The runtime MUST scope scope(name) to the requesting napplet.
• The runtime MUST NOT expose another napplet's scoped storage, cache, media, relay, or service details.
• The runtime MAY redact URLs, counts, byte totals, service names, latency, or health messages by policy.
• The runtime MAY rate-limit system accessors.
• The runtime MAY return approximate values.

Security Considerations

System information is a fingerprinting and privacy surface. NAP-SYSTEM is read-only, but it can reveal runtime topology, relay choices, storage size, media availability, and service health.

• The runtime SHOULD expose the least detail needed for the requesting napplet.
• The runtime SHOULD bucket or omit exact byte counts and latency values when exact values are not needed.
• The runtime MUST NOT expose private event contents, storage keys, stored values, media metadata, raw backing-store data, or another napplet's scoped data.
• The runtime MUST NOT treat system.naps as an authorization mechanism. Capability authorization remains with NAP-SHELL and runtime policy.
• Napplets MUST treat system snapshots as advisory. A status can change immediately after it is read.

Implementations

• None yet.

Changelog

• 58a8d69 - Introduced NAP-SYSTEM as a read-only runtime diagnostics surface.

• 840acf1 - Removed browser-specific storage diagnostics so NAP-SYSTEM stays projection-neutral.

• 149e5a4 - Adopted injected-domain availability and linked the current upstream web binding.