Docs

Verbs

A verb is an executable behavior definition. It turns reusable intent into a runtime action that can be shared, versioned, audited, and composed into multi-step automation.

Role in the Sociallux model

Atoms store state. Lexemes describe state. Verbs change state. Together they define the full lifecycle of your data model.

🗄️ Atoms

Flexible records that hold any shape of data.

📖 Lexemes

Schemas and meanings that describe atoms.

⚡ Verbs

Behaviors that create and modify atoms.

Verb types

Verbs are either primitive (single action) or composed (multi-step workflow).

⚙️

Primitive

Runs a single built-in action like atom.create or atom.assignLexeme. Primitive verbs are the building blocks for more complex behaviors.

Example: atom.create — creates a new atom with data and optional lexeme subscriptions.

🔗

Composed

Chains multiple primitive actions into a deterministic workflow. Each step can reference output from prior steps using dynamic token syntax.

Example: Create an atom, then immediately assign a lexeme to it — all in a single execution.

Structure

Verbs follow the same ownership and lifecycle conventions as atoms and lexemes, with execution-specific payload fields in data.

Field - key name in request/response payloads.

Description - what the field controls at runtime.

Default - applied value when omitted on create.

Field

name

string

Description

A short, human-readable label for the verb. Used in the UI and logs to identify behavior at a glance.

Default

Field

data.type

"primitive" | "composed"

Description

Execution mode. Primitive verbs run one action. Composed verbs run an ordered sequence of primitive steps.

Default

"primitive"

Field

data.action

string

Description

Required for primitive verbs. Names the action runtime to execute, such as atom.create or atom.assignLexeme.

Default

undefined

Field

data.params

Record<string, unknown>

Description

Optional template parameters for primitive execution. Request input is merged on top at execution time.

Default

{}

Field

data.steps

{ action: string; params?: Record<string, unknown> }[]

Description

Required for composed verbs. Each step runs in order, receives resolved params, and can reference prior step output.

Default

[]

Field

owner

ObjectId -> User

Description

The user that owns and controls the verb. Owner/admin permissions govern edit, share, visibility, and delete actions.

Default

required

Field

sharedWith

{ user: ObjectId, role: 'reader' | 'editor' }[]

Description

Explicit per-user access grants. Reader grants execution/read access. Editor grants update access.

Default

[]

Field

isPublic

boolean

Description

When true, anonymous and authenticated callers can read and execute the verb if no stricter guard blocks the action.

Default

false

Field

isSystem

boolean

Description

Marks protected platform verbs. Non-admin users cannot mutate or delete system verbs.

Default

false

Field

version

number

Description

Auto-incremented when mutable payload/share fields change. Useful for rollout tracking and stale-write detection.

Default

Field

deleted

boolean

Description

Soft-delete lifecycle flag. Deleted verbs are hidden from normal reads and can be restored by managers.

Default

false

FieldDescriptionDefault

name

string

A short, human-readable label for the verb. Used in the UI and logs to identify behavior at a glance.

data.type

"primitive" | "composed"

Execution mode. Primitive verbs run one action. Composed verbs run an ordered sequence of primitive steps.

"primitive"

data.action

string

Required for primitive verbs. Names the action runtime to execute, such as atom.create or atom.assignLexeme.

undefined

data.params

Record<string, unknown>

Optional template parameters for primitive execution. Request input is merged on top at execution time.

{}

data.steps

{ action: string; params?: Record<string, unknown> }[]

Required for composed verbs. Each step runs in order, receives resolved params, and can reference prior step output.

[]

owner

ObjectId -> User

The user that owns and controls the verb. Owner/admin permissions govern edit, share, visibility, and delete actions.

required

sharedWith

{ user: ObjectId, role: 'reader' | 'editor' }[]

Explicit per-user access grants. Reader grants execution/read access. Editor grants update access.

[]

isPublic

boolean

When true, anonymous and authenticated callers can read and execute the verb if no stricter guard blocks the action.

false

isSystem

boolean

Marks protected platform verbs. Non-admin users cannot mutate or delete system verbs.

false

version

number

Auto-incremented when mutable payload/share fields change. Useful for rollout tracking and stale-write detection.

deleted

boolean

Soft-delete lifecycle flag. Deleted verbs are hidden from normal reads and can be restored by managers.

false

Primitive actions

Built-in actions that primitive verbs can execute. Composed verbs chain these together using dynamic token mapping.

Action

atom.create

Parameters

data, lexemeIds, isPublic

Returns

{ atom: { id, version, lexemeIds, data, isPublic } }

Description

Creates a new atom with optional data, lexeme subscriptions, and visibility. The newly created atom id can be referenced in later steps.

Action

atom.assignLexeme

Parameters

atomId, lexemeId

Returns

{ atom: { id, lexemeIds }, assigned: boolean }

Description

Attaches a lexeme to an existing atom. Useful for staged enrichment or multi-step classification workflows.

ActionParametersReturnsDescription

atom.createdata, lexemeIds, isPublic{ atom: { id, version, lexemeIds, data, isPublic } }

Creates a new atom with optional data, lexeme subscriptions, and visibility. The newly created atom id can be referenced in later steps.

atom.assignLexemeatomId, lexemeId{ atom: { id, lexemeIds }, assigned: boolean }

Attaches a lexeme to an existing atom. Useful for staged enrichment or multi-step classification workflows.

Creation flow

How to design and create a verb, from intent to executable definition to first run.

Define verb intent

Decide whether your behavior is a single action (primitive) or a multi-step workflow (composed).

Choose action(s)

For primitives, pick one action like atom.create. For composed, build a sequence of actions.

Template parameters

Set up params using dynamic tokens ($input.*, $steps.*, $last.*) to wire together steps or accept request inputs.

POST to Verbs API

Create the verb via POST /verbs. The API persists it with ownership, version, and audit metadata.

Execute anytime

POST /verbs/:id/execute with input data. The verb definition is reused; only the input changes.

Execution model

Verb execution is synchronous and traceable. Each run returns both a final output and step-by-step trace details for debugging and audit.

Definition

A verb is defined as a stored record with a name, type (primitive or composed), and action/step details.

Input hydration

Execution starts with an input object from request body.input. Primitive params are built from verb data.params plus request input overrides.

Dynamic mapping

Composed step params can resolve values from $input.path (request), $steps.N.output.path (specific step), and $last.output.path (most recent step).

Deterministic order

Composed steps execute sequentially. The first failing step halts the run and returns a trace with failure details.

Trace + output

Every execution returns step-by-step trace entries and a final output payload so callers can inspect runtime effects.

Audit

Successful runs emit a VERB.EXECUTED audit event with actor, resource, type, and trace step count metadata.

Dynamic token mapping

In composed verbs, step parameters can reference the request input and prior step outputs using special token syntax.

$input.path

Reads values from the execution request input object. Example: $input.lexemeId

$steps.N.output.path

Reads output from a specific step by index. Example: $steps.0.output.atom.id reads the atom id created in step 0.

$last.output.path

Reads output from the most recently executed step. Useful when you don't know the exact step index.

Examples

These examples show common verb definitions used to drive atom creation and classification flows. See the Verbs API for execution details.

Primitive: create atom

One-step action that creates an atom using request-supplied data and optional lexeme links.

{
  "name": "Create atom",
  "data": {
    "type": "primitive",
    "action": "atom.create",
    "params": {
      "data": "$input.data",
      "lexemeIds": "$input.lexemeIds",
      "isPublic": "$input.isPublic"
    }
  }
}

Primitive: assign lexeme

Attaches a lexeme to an existing atom. Useful for staged enrichment flows.

{
  "name": "Assign lexeme to atom",
  "data": {
    "type": "primitive",
    "action": "atom.assignLexeme",
    "params": {
      "atomId": "$input.atomId",
      "lexemeId": "$input.lexemeId"
    }
  }
}

Composed: create and classify

Creates an atom, then uses the created id in step 2 to assign a lexeme in the same run.

{
  "name": "Create and classify atom",
  "data": {
    "type": "composed",
    "steps": [
      {
        "action": "atom.create",
        "params": {
          "data": "$input.data",
          "isPublic": "$input.isPublic"
        }
      },
      {
        "action": "atom.assignLexeme",
        "params": {
          "atomId": "$steps.0.output.atom.id",
          "lexemeId": "$input.lexemeId"
        }
      }
    ]
  }
}

Next steps

Ready to use verbs?

Verbs API reference

Learn how to create, list, and execute verbs.

Atoms API

Understand the atom model that verbs modify.