SubstrateState: Application State Snapshot Reference

The SubstrateState object (also referred to as an SSF — Substrate Schema Format — document) is the primary data structure NSP returns when you read an application’s current state. Every GET /state response wraps one, every WebSocket state-change event carries one, and every action you dispatch consumes one as its pre-flight context. It represents a point-in-time snapshot of everything the probe could semantically label inside the target process, plus the action surface available at that moment.

capture_id

string

required

A UUIDv7 time-ordered unique identifier generated for each state capture. Because UUIDv7 embeds a millisecond-precision timestamp, a lexicographically larger capture_id is always a more recent capture — you can use this to detect and discard stale responses without parsing captured_at.

app_id

string

required

A stable semantic identifier for the application. On first detection NSP derives a candidate ID in the form {app-name}-{runtime}-{pid} (for example gmail-chrome-12847), then promotes it to a content-hash-based ID that persists across process restarts once the probe has confirmed the app’s identity. You should always use app_id — not pid — when you want to reference a specific application across sessions.

app_name

string

required

Human-readable display name assigned by the signature registry, for example "Gmail" or "Mission Planner". Suitable for logging and UI display; not intended for programmatic identity checks (use app_id for that).

pid

integer

required

The OS process ID of the target application at the time of this capture. Because PIDs are recycled by the OS after a process exits and a new one starts, pid is only stable for the lifetime of a single process. Prefer app_id for persistent references.

runtime

enum

required

The runtime environment detected for this application. Controls which probe strategy NSP uses and sets the baseline confidence ceiling.

Value	Runtime	Typical apps
`v8`	JavaScript / V8 (Chrome, Electron)	Gmail, Slack, VS Code, Notion
`jvm`	Java Virtual Machine	SAP ERP, IntelliJ IDEA, Jenkins
`clr`	.NET Common Language Runtime	Mission Planner, WPF/WinForms apps
`native`	Native C/C++ process	Bloomberg Terminal, Photoshop, AutoCAD
`unknown`	Classification pending or failed	—

schema_version

string

required

Semver string representing the version of the discovered schema for this application, for example "1.4.2". NSP bumps the version as it learns more about the app:

Patch (1.4.2 → 1.4.3): A label correction was learned; existing key meanings are unchanged.
Minor (1.4.x → 1.5.0): New state keys or actions were discovered; existing keys are unchanged.
Major (1.x → 2.0.0): Key names were restructured due to an app update. Rare — verify your hardcoded key names when this occurs.

captured_at

string

required

ISO 8601 UTC timestamp of when this snapshot was captured, for example "2026-07-20T13:00:00Z".

confidence

float

required

A quality score from 0.0 to 1.0 representing how completely the probe was able to semantically label the application’s state. NSP uses this score to gate which action reversibility tiers you can invoke:

Range	Meaning	Actions allowed
`0.00 – 0.39`	Probe initializing	None
`0.40 – 0.79`	Partial coverage	`read` only
`0.80 – 0.94`	Good coverage	`read` + `reversible_write`
`0.95 – 1.00`	Excellent coverage	All, including `irreversible_write`

context

object

required

Navigational context describing where within the application the probe was focused at capture time.

Show context fields

url

string | null

The current URL, populated for V8/browser-based applications. null for native or JVM apps that do not have a browser context, for example "https://mail.google.com/mail/u/0/#inbox".

view

string | null

The semantic view name assigned by NSP’s signature registry, for example "gmail_inbox" or "vscode_editor". More stable than window_title for programmatic use.

window_title

string | null

The OS-level window title string, for example "Inbox - Gmail". Useful for display or debugging; may change frequently for apps that embed dynamic data in the title bar.

window_id

string | null

A tab or window identifier scoped to the application, for example a Chrome tab ID. Enables you to disambiguate multiple windows of the same app running under a single PID.

location

string | null

A canonicalized path derived from url, for example "/inbox" or "/compose". Useful for routing logic without parsing the full URL.

objects

object

required

The semantic state of the application as a flat key-value map. All keys use dot-notation with bracket indexing — for example "inbox.emails[0].subject" — rather than nested JSON objects. This design lets you reference any value with a single stable string key and perform prefix queries without traversing a tree.Value types can be number, string, boolean, null, object, or array. Keys are stable across poll cycles for a given app_id and schema_version: the same key always refers to the same semantic concept.

{
  "inbox.unread_count": 47,
  "inbox.total_count": 1284,
  "inbox.emails[0].id": "msg_18821af3",
  "inbox.emails[0].from": "alice@example.com",
  "inbox.emails[0].subject": "Q3 Performance Report",
  "inbox.emails[0].is_read": false,
  "inbox.emails[0].has_attachments": true
}

To retrieve all keys belonging to a subtree, query by prefix — for example all keys starting with "inbox." give you the full inbox model.

actions

object

required

A map of action name to ActionSchema describing every action the probe has discovered on this substrate. Keys are the action names you pass to POST /action; values are the full schema objects including signature, reversibility, parameters, and per-action confidence.

probe_metadata

object

required

Internal telemetry from the probe run that produced this snapshot. Useful for diagnosing latency, cache behaviour, and probe tier selection.

Show probe_metadata fields

capture_latency_ms

integer

Time in milliseconds spent extracting raw state from the target process, from probe injection to raw object list.

labeling_latency_ms

integer

Time in milliseconds spent normalizing and semantically labeling the raw objects into SSF dot-notation keys.

total_latency_ms

integer

Total wall-clock time for the full capture pipeline: capture_latency_ms + labeling_latency_ms plus any queue wait.

raw_object_count

integer

Number of raw objects extracted from the process before filtering. High values relative to filtered_object_count indicate a noisy heap.

filtered_object_count

integer

Number of objects remaining after NSP’s semantic filter discards internals, framework scaffolding, and unlabeled nodes.

cache_hit

boolean

true if this snapshot was served from NSP’s local state cache rather than triggering a fresh probe run. Cache hits have near-zero capture_latency_ms.

probe_tier

string

The probe strategy used for this capture. For V8 apps this is either "aso_fast_path" (5–50 ms, primary) or "heap_snapshot" (fallback, ~47 s). For JVM apps: "jvmti". For CLR apps: "mmf_bridge". For native apps: "memory_read".

Full JSON Example

{
  "capture_id": "0196f4a2-3b5c-7d00-8e1f-9a0b2c3d4e5f",
  "app_id": "gmail-chrome-12847",
  "app_name": "Gmail",
  "pid": 12847,
  "runtime": "v8",
  "schema_version": "1.4.2",
  "captured_at": "2026-07-20T13:00:00Z",
  "confidence": 0.97,
  "context": {
    "url": "https://mail.google.com/mail/u/0/#inbox",
    "view": "gmail_inbox",
    "window_title": "Inbox - Gmail",
    "window_id": "tab_8821",
    "location": "/inbox"
  },
  "objects": {
    "inbox.unread_count": 47,
    "inbox.total_count": 1284,
    "inbox.emails[0].id": "msg_18821af3",
    "inbox.emails[0].from": "alice@example.com",
    "inbox.emails[0].subject": "Q3 Performance Report",
    "inbox.emails[0].is_read": false,
    "inbox.emails[0].has_attachments": true,
    "inbox.emails[0].thread_id": "thread_7af2b3"
  },
  "actions": {
    "send_reply": {
      "signature": "fn(thread_id: string, body: string, cc?: string[]) -> bool",
      "reversibility": "irreversible_write",
      "description": "Send a reply to an email thread",
      "confidence": 0.99,
      "parameters": [
        { "name": "thread_id", "type_name": "string", "required": true, "description": "Thread ID from inbox.emails[N].thread_id" },
        { "name": "body", "type_name": "string", "required": true, "description": "Reply body text" },
        { "name": "cc", "type_name": "array", "required": false, "description": "Optional CC email addresses" }
      ]
    },
    "archive": {
      "signature": "fn(email_id: string) -> bool",
      "reversibility": "reversible_write",
      "description": "Archive an email message",
      "confidence": 0.98,
      "parameters": [
        { "name": "email_id", "type_name": "string", "required": true, "description": "Email ID from inbox.emails[N].id" }
      ]
    }
  },
  "probe_metadata": {
    "capture_latency_ms": 28,
    "labeling_latency_ms": 23,
    "total_latency_ms": 51,
    "raw_object_count": 4821,
    "filtered_object_count": 8,
    "cache_hit": false,
    "probe_tier": "aso_fast_path"
  }
}

The Dot-Notation `objects` Format

NSP deliberately stores all application state as a flat key-value map rather than nested JSON. Every key is a dot-notation path that encodes the full hierarchy in a single string:

inbox.emails[0].subject   →  "Q3 Performance Report"
inbox.emails[1].subject   →  "Team standup notes"
flight.telemetry.altitude_m  →  42.7
flight.mode              →  "GUIDED"

This design has two practical benefits. First, you can retrieve any specific value with a single key lookup — no need to traverse a tree structure. Second, prefix queries let you pull an entire subtree by filtering keys that start with a common prefix (for example "inbox.emails[0]." to get all fields on the first email). Keys are stable across poll cycles for a given app_id and schema_version. When schema_version increments to a new minor or major version, new keys may appear and, in major-version cases, existing keys may be renamed — verify your key names against the updated schema when you detect a version change.

Endpoints

Data Models

Full JSON Example

The Dot-Notation `objects` Format

​Full JSON Example

​The Dot-Notation objects Format

Full JSON Example

The Dot-Notation `objects` Format