ActionSchema: Typed Action Descriptor for NSP Substrates

ActionSchema is the descriptor for every callable action discovered on a tracked application. The NSP probe extracts action schemas directly from the application’s runtime — reading JavaScript function signatures from the V8 heap, method descriptors from JVMTI, or managed method metadata from the CLR. You find action schemas inside the actions map of a SubstrateState and also via GET /schema/{pid}. Before calling POST /action, you should inspect the schema to know the required parameters and understand the reversibility tier.

JSON Example

{
  "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 (plain text or HTML)"
      },
      {
        "name": "cc",
        "type_name": "array",
        "required": false,
        "description": "Optional CC email addresses"
      }
    ]
  }
}

Fields

string

required

The full typed signature of the action in NSP’s fn(…) -> type notation. Required parameters appear without a ?; optional parameters are suffixed with ?. For example:

fn(thread_id: string, body: string, cc?: string[]) -> bool
fn(email_id: string) -> bool
fn(url: string) -> void

This string is informational — the daemon uses the parameters array for validation, not the signature string.

enum

required

The safety classification for this action. One of read, reversible_write, or irreversible_write. This value is a hard safety contract enforced by the daemon, not a suggestion. See the reversibility tiers table below for confidence requirements and verification rules.

string

required

A human-readable explanation of what the action does, generated by the schema discovery engine and stored in the schema registry.

float (0.0–1.0)

required

How certain the probe is that this action schema accurately maps to a real callable function in the application. A value of 0.99 means the mapping was confirmed via runtime introspection. Lower values may indicate the mapping was inferred heuristically.

array of ParameterSchema

required

The ordered list of parameters accepted by this action. You must supply all parameters with required: true in the parameters object of your POST /action request body.

Show ParameterSchema fields

string

required

The parameter name as it appears in the action’s function signature. Use this exact string as the key in your parameters object when calling POST /action.

string

required

The expected JSON type for this parameter. One of string, number, boolean, array, or object.

`type_name`	Accepted JSON	Example
`string`	JSON string	`"thread_7af2b3"`
`number`	JSON number (integer or float)	`42`, `3.14`
`boolean`	JSON boolean	`true`, `false`
`array`	JSON array	`["a@x.com", "b@x.com"]`
`object`	JSON object	`{"key": "value"}`

boolean

required

true if the parameter must be provided. If you omit a required parameter, the daemon returns 400 missing_parameters. Optional parameters (required: false) may be omitted entirely from your request body.

string | null

A human-readable description of what this parameter controls, often including where to find its value in the objects map — for example, "Thread ID from inbox.emails[N].thread_id".

Reversibility Tiers

Every action belongs to exactly one reversibility tier. The tier determines the minimum confidence required in the SubstrateState before the daemon will dispatch the action, and whether a verify_expression is mandatory.

Tier	Meaning	Min. Confidence	`verify_expression`
`read`	Reads data without modifying application state	0.0+	Optional
`reversible_write`	Modifies state in a way that can be undone (archive, label, star, draft)	0.80+	Optional
`irreversible_write`	Causes a permanent side effect that cannot be undone (send, delete, purchase)	0.95+	Required

If you call POST /action on an irreversible_write action without providing a verify_expression, the daemon immediately returns 400 missing_verify_expression — the action is never dispatched. This gate exists to prevent agents from performing irreversible operations without explicit post-action confirmation.

Endpoints

Data Models

JSON Example

Fields

Reversibility Tiers

​JSON Example

​Fields

​Reversibility Tiers

JSON Example

Fields

Reversibility Tiers