schemas-validation-explainability.md

Schemas, validation, and explainability

Neuron-JS exposes machine-checkable contracts for stored or AI-generated rules before runtime, then produces a compact explanation object after execution.

Use this page for NJS-GROWTH-03 adoption work: validate generated JSON, run deterministic decisions, and persist explainable outputs for review or audit trails.

Contract files

The package ships JSON Schema files in schemas/:

• script.schema.json: script, rule, condition, action, and parameter definitions.
• execution-context.schema.json: runtime context with messages and mutable state.
• execution-output.schema.json: normalized execution summary.
• validation-error.schema.json: path-level validation errors.
• explanation-trace.schema.json: stable explain output for audits and snapshots.

The same schema files are also published on the documentation site under /schemas/*.schema.json.

Validate before runtime

Use validateScript before executing stored or generated rules. This catches missing fields and malformed element contracts before the engine tries to instantiate plugins.

import { validateScript } from '@sebasoft/neuron-js';

const validation = validateScript(script);

if (!validation.ok) {
  console.error(validation.errors);
  throw new Error('Invalid Neuron-JS script');
}

Validation errors use JSONPath-like paths so humans and coding agents can repair the exact field.

[
  {
    "path": "$.rules[0].actions",
    "code": "required_array",
    "message": "Expected array at $.rules[0].actions."
  }
]

Run deterministic decisions

After validation, execute with the normal Synapse engine.

import { Neuron, Synapse, validateExecutionContext, validateScript } from '@sebasoft/neuron-js';

const scriptValidation = validateScript(script);
const contextValidation = validateExecutionContext(context);

if (!scriptValidation.ok || !contextValidation.ok) {
  throw new Error('Invalid Neuron-JS input');
}

const result = new Synapse(new Neuron()).execute(script, context);

Normalize execution output

Use summarizeExecutionOutput when logs, automation workflows, or tests need a stable result object.

import { summarizeExecutionOutput, validateExecutionOutput } from '@sebasoft/neuron-js';

const output = summarizeExecutionOutput(result);
const outputValidation = validateExecutionOutput(output);

Example output:

{
  "ok": true,
  "rulesExecuted": 1,
  "messages": ["Applied 16% discount: -20"]
}

Explain an execution

Use explainExecution after a run to produce an audit-friendly trace.

import { explainExecution, validateExecutionExplanation } from '@sebasoft/neuron-js';

const explanation = explainExecution({ script, result });
const explanationValidation = validateExecutionExplanation(explanation);

Example explanation shape:

{
  "scriptId": "pricing-rules-demo",
  "ok": true,
  "rulesEvaluated": 1,
  "rulesExecuted": 1,
  "messages": ["Applied 16% discount: -20"],
  "trace": [
    {
      "step": 1,
      "type": "script_received",
      "message": "Script pricing-rules-demo contains 1 rule(s)."
    },
    {
      "step": 2,
      "type": "rule_available",
      "ruleId": "vip-order-discount",
      "message": "Rule vip-order-discount has 1 condition(s) and 1 action(s)."
    },
    {
      "step": 3,
      "type": "execution_completed",
      "ruleId": "vip-order-discount",
      "message": "Execution completed with 1 rule(s) executed."
    }
  ]
}

Verify official examples

The repository test suite validates the official example scripts and contexts, and snapshot-tests a pricing-rules explanation trace.

yarn test tests/contracts/schemas-validation-explainability.test.ts

Run all examples separately:

yarn examples