SubstrateState: NSP's Core Live Application Snapshot

SubstrateState is the central data structure flowing through every NSP operation. Each time you call GET /state/{pid} or POST /action, you receive a SubstrateState — a typed, versioned JSON snapshot of exactly what a running application contains at the moment of capture. Every field is semantically labeled by the probe, normalized to the Substrate Schema Format (SSF), and stored with a confidence score that controls which actions you are permitted to execute against it.

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",
    "location": "/inbox",
    "view": "gmail_inbox",
    "window_title": "Inbox (47) - Gmail",
    "window_id": "tab_8821af3"
  },
  "objects": {
    "inbox.unread_count": 47,
    "inbox.total_count": 1284,
    "inbox.emails[0].id": "msg_18821af3",
    "inbox.emails[0].thread_id": "thread_7af2b3",
    "inbox.emails[0].from": "alice@example.com",
    "inbox.emails[0].subject": "Q3 Performance Report",
    "inbox.emails[0].snippet": "Please review the attached Q3 report...",
    "inbox.emails[0].is_read": false,
    "inbox.emails[0].has_attachments": true,
    "inbox.emails[0].received_at": "2026-07-20T09:15:00Z",
    "inbox.emails[1].id": "msg_17721b3f",
    "inbox.emails[1].from": "bob@example.com",
    "inbox.emails[1].subject": "Meeting tomorrow at 3pm",
    "inbox.emails[1].is_read": false
  },
  "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",
      "confidence": 0.99,
      "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": 12,
    "total_latency_ms": 51,
    "raw_object_count": 8472,
    "filtered_object_count": 23,
    "cache_hit": true,
    "probe_tier": "aso_fast"
  }
}

Fields

string (UUIDv7)

required

A time-ordered unique identifier for this state capture. UUIDv7 values are monotonically increasing — a higher capture_id is always more recent. Use this field to detect stale responses or deduplicate events from the WebSocket stream.

string

required

A stable semantic identifier for the application. The format on first detection is {app-name}-{runtime}-{pid} (for example, "gmail-chrome-12847"), and it is promoted to a content-hash-based ID that survives daemon restarts. You can safely store app_id in your agent and use it across sessions without tracking raw PIDs.

string

required

The human-readable display name of the application, such as "Gmail" or "Mission Planner". This value is assigned by the signature registry and is stable across captures.

integer

required

The OS process ID at the time of capture. Unlike app_id, the PID changes if the application restarts. Use app_id for stable references and pid only when you need to target a specific OS process.

enum

required

The runtime substrate the probe connected to. One of:

v8 — JavaScript/V8 (Chrome, Electron, Node.js)
jvm — Java Virtual Machine
clr — .NET Common Language Runtime
unknown — Runtime detected but not yet classified

string (semver)

required

The semantic version of the discovered schema for this application, for example "1.4.2". A version change means the schema registry learned something new:

Patch (1.4.2 → 1.4.3): A label correction was applied. 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. Rare — only occurs on major application updates.

If your agent hardcodes key names, verify they still exist whenever schema_version changes.

string (ISO 8601)

required

The UTC timestamp at which this snapshot was taken, for example "2026-07-20T13:00:00Z".

float (0.0–1.0)

required

The overall quality score for this capture, representing how certain the probe is in its semantic labels. Confidence gates which actions you are allowed to execute. See the confidence table below.

AppContext object

required

The navigational context of the application at capture time — where inside the app the user currently is.

Show AppContext fields

string | null

The full URL currently loaded in the application window. Populated for V8/browser apps; null for native runtimes.

string | null

The canonicalized path component of the URL, such as "/inbox" or "/compose".

string | null

The semantic view name assigned by the schema registry, such as "gmail_inbox" or "gmail_compose". More stable than url for routing logic in your agent.

string | null

The OS-level window title at capture time, such as "Inbox (47) - Gmail".

string | null

A stable identifier for the browser tab or OS window, such as "tab_8821af3". Useful for distinguishing multiple windows of the same application.

object

required

The semantic state of the application as a flat key-value map. All keys use dot-notation with array indexing (see key format below). Value types may be number, string, boolean, null, object, or array. This is the map you reference in verify_expression strings and SDK accessors.

object

required

A map of action name to ActionSchema. Each entry describes a callable action discovered from the application’s runtime, including its signature, reversibility tier, and typed parameter list. You pass the action name directly to POST /action.

object

required

Internal telemetry from the probe cycle that produced this snapshot.

Show probe_metadata fields

integer

Time in milliseconds spent reading raw data from the runtime.

integer

Time in milliseconds spent by the semantic labeling pipeline converting raw heap nodes into human-readable keys.

integer

End-to-end wall time in milliseconds from probe invocation to a complete SubstrateState.

integer

The number of objects extracted from the runtime heap before semantic filtering.

integer

The number of objects remaining after filtering out internals, duplicates, and noise. This corresponds to the number of keys in objects.

boolean

true if the action schema for this application was served from the schema registry cache rather than re-discovered during this probe cycle.

string

The probe strategy used for this capture. One of aso_fast, heap_snapshot, jvmti, or clr_mmf. The aso_fast tier is the V8 fast path and returns in 5–50ms; heap_snapshot is the fallback and takes up to 90 seconds.

Dot-Notation Key Format

All state in objects is stored as a flat map with dot-notation keys. Instead of navigating nested JSON, you reference a specific value with a precise path string:

"inbox.unread_count"          → scalar at the top-level inbox node
"inbox.emails[0].from"        → first email's sender
"inbox.emails[0].is_read"     → boolean field on the first email
"flight.altitude_m"           → numeric field in a different app

Keys are stable across poll cycles — for a given app_id and schema_version, the same key always refers to the same semantic concept. When you query POST /verify or write a verify_expression, you reference these exact key strings.

Confidence Score

Every SubstrateState includes a confidence value that controls which actions the NSP daemon will allow you to execute.

Range	Meaning	Action Gating
`0.00 – 0.39`	Probe initializing — labels not yet assigned	No actions allowed
`0.40 – 0.79`	Partial coverage — some objects labeled	Read-only (`read`) actions only
`0.80 – 0.94`	Good — most objects labeled	`reversible_write` actions allowed
`0.95 – 1.00`	Excellent — full semantic coverage	All actions including `irreversible_write`

If a POST /action request arrives when confidence is below the required threshold for that action’s reversibility tier, the daemon returns 503 confidence_too_low. You can force a fresh probe with ?fresh=true on GET /state/{pid} to attempt to raise confidence before acting.

Endpoints

Data Models

JSON Example

Fields

Dot-Notation Key Format

Confidence Score

​JSON Example

​Fields

​Dot-Notation Key Format

​Confidence Score

JSON Example

Fields

Dot-Notation Key Format

Confidence Score