nerve/.knowledge/signal-routing.md

Sense compute → shell + scheduler (issue #318)

Stateful senses run compute(state) and return { state, trigger }. The worker persists state JSON and sends compute-result to the kernel. Optional side effects are shell commands only, executed in the sense worker. Workflows are not started from sense return values.

Flow

Sense worker: compute(state) → { state, trigger }
                    ↓
          persist state JSON (data/senses/<name>.json)
                    ↓
     trigger !== null → spawn shell command (cwd = nerve root)
                    ↓
          IPC compute-result → kernel (audit: shell-launch log)
                    ↓
          scheduler.onSenseCompleted(senseName) → dependents with `on: [senseName]`

Workflow runs: workflowManager.startWorkflow from CLI / daemon IPC only (nerve workflow trigger, HTTP when enabled).

Sense trigger shape

When trigger is non-null it must be a plain object validated by parseSenseTrigger() in packages/core/src/sense.ts:

• Exactly one property: command (non-empty string after trim)
• No kind field; no workflow fields

Invalid triggers are rejected when parsing the worker message.

Scheduling

Other senses list this sense under on in nerve.yaml to be scheduled when this sense completes a successful compute (see sense scheduler reverse-index in the daemon).