Events schema

Events are stored in events.jsonl as newline-delimited JSON. Each event represents a phase transition in the cognitive loop. Current event schema version: 1.3.0 (JSON schema).

Integrity contract (`events.jsonl`)

events.jsonl is the canonical append-only trace for an episode. Noēsis treats corruption as a hard integrity failure.

Reads fail closed: malformed records are not skipped.
iter_events() / read_events() raise EventLogIntegrityError when a line has invalid UTF-8, invalid JSON, or a non-object JSON value.
Appends are guarded: write_event() validates the existing log before writing and rejects append attempts if any existing record is corrupt (including corruption in the middle of the file).

Typical deterministic failures:

A truncated final line.
Invalid UTF-8 bytes in any record.
A malformed JSON record even when later lines are valid.

Event structure

Every event follows this base structure:

{
  "id": "evt_abc123",
  "phase": "plan",
  "agent_id": "meta_planner",
  "payload": { ... },
  "evidence_ids": ["event:observe:1"],
  "metrics": {
    "started_at": "2024-01-15T10:30:00.500Z",
    "completed_at": "2024-01-15T10:30:00.512Z",
    "duration_ms": 12.7
  },
  "caused_by": "evt_xyz789"
}

string

required

Unique event identifier.

phase

string

required

Event phase. Canonical values: start, observe, interpret, plan, direction, governance, action_candidate, act, reflect, learn, runtime, terminate, insight, memory, intuition, reason, error. Extensions may emit additional phases.

event_type

string

Subtype for phase="runtime" events (for example run.interrupt, run.checkpoint, run.resume, run.state_projection).

agent_id

string

Identifier of the component that emitted the event.

payload

object

required

Phase-specific payload data.

evidence_ids

array

Optional evidence references carried forward into the event record.

metrics

object

Timing metrics for the event.

Show Metrics properties

started_at

string

ISO 8601 timestamp when the phase started.

completed_at

string

ISO 8601 timestamp when the phase completed.

duration_ms

number

Duration in milliseconds.

caused_by

string

ID of the event that caused this one (for lineage tracking).

Event phases

Additional phases you may see:

start: episode initialization metadata.
intuition: advisory/intuition policy events.
memory: reads/writes performed by the memory port.
insight: computed insight metrics (alias of events —phase insight).
reason: reasoning traces from the planner.
runtime: lifecycle and projection evidence (run.* event types).
error: fatal errors.

observe

Captures the raw task and context at episode start.

{
  "phase": "observe",
  "payload": {
    "task": "Draft release notes for v1.2.0",
    "tags": {
      "priority": "high",
      "team": "platform"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "context": {
      "changelog_path": "CHANGELOG.md"
    }
  }
}

payload.task

string

required

The task or goal for the episode.

payload.tags

object

User-provided metadata tags.

payload.timestamp

string

required

ISO 8601 timestamp of observation.

payload.context

object

Additional context provided with the task.

intuition

Captures advisory/intervention/veto signals before interpretation and planning.

{
  "phase": "intuition",
  "payload": {
    "schema_version": "1.1.0",
    "kind": "hint",
    "advice": "Consider chunking the task input before execution.",
    "confidence": 0.6,
    "policy_id": "intuition.heuristic",
    "policy_version": "1.0.0",
    "policy_kind": "rules",
    "rationale": "task_length",
    "evidence_ids": ["event:observe:1"],
    "risk_level": "moderate",
    "salience_signals": ["task_complexity"],
    "strategy_hints": ["retrieve_more", "narrow_scope"],
    "scrutiny_level": "elevated",
    "target": "input",
    "scope": "episode",
    "blocking": false
  },
  "evidence_ids": ["event:observe:1"],
  "caused_by": "observe_event_id"
}

payload.kind

string

required

Directive kind: hint, intervention, veto.

payload.risk_level

string

Optional risk posture: low, moderate, high, critical.

payload.salience_signals

array

Optional salience cues: task_complexity, normalization_gap, policy_hint, safety_boundary.

payload.strategy_hints

array

Optional planning hints: conservative, verify_first, retrieve_more, narrow_scope.

payload.tool_constraints

array

Optional tool constraints: no_side_effects, read_only, require_double_check.

payload.scrutiny_level

string

Optional review level: normal, elevated, strict.

interpret

Summarizes signals extracted from the observed input.

{
  "phase": "interpret",
  "payload": {
    "signals": [
      {
        "type": "risk",
        "level": "medium",
        "description": "Production deployment mentioned"
      },
      {
        "type": "constraint",
        "description": "Requires changelog file"
      }
    ],
    "intent": "documentation_generation",
    "policy_id": "SafetyPolicy@1.0"
  }
}

payload.signals

array

required

List of detected signals.

Show Signal properties

type

string

required

Signal type: risk, constraint, opportunity, warning.

level

string

Signal level: low, medium, high, critical.

description

string

required

Human-readable signal description.

payload.intent

string

Classified intent of the task.

payload.policy_id

string

Policy that performed interpretation.

plan

Records the selected action steps and projection metadata used to rebuild state.json.

{
  "phase": "plan",
  "payload": {
    "steps": [
      "detect:Collect context",
      "act:Execute task"
    ],
    "step_records": [
      {
        "id": "step-1",
        "kind": "detect",
        "description": "Collect context",
        "status": "pending"
      },
      {
        "id": "step-2",
        "kind": "act",
        "description": "Execute task",
        "status": "pending"
      }
    ],
    "source": "planner.minimal",
    "rationale": "minimal planner"
  }
}

payload.steps

array

required

Compatibility labels in <kind>:<description> format. Legacy consumers may rely on this field.

payload.step_records

array

Structured plan records used for deterministic plan-state projection.

Show Step record properties

string

required

Unique step identifier.

kind

string

required

Step kind: detect, analyze, plan, act, verify, review.

description

string

required

Human-readable step description.

status

string

required

Step status: pending, running, done, skipped, failed, vetoed.

depends_on

array

Optional list of predecessor step IDs.

inputs

object

Optional structured inputs for the step.

outputs

object

Optional structured outputs for the step.

payload.source

string

Planner source identifier (for example, planner.minimal). Runtime-emitted plan events always include this.

payload.rationale

string

Optional planner rationale.

direction

Records policy directives (meta mode only).

{
  "phase": "direction",
  "payload": {
    "schema_version": "1.2.0",
    "directive_id": "dir_abc123",
    "legacy_directive_id": "11111111-1111-1111-1111-111111111111",
    "steps": ["meta:start", "intuition:risk-review"],
    "status": "applied",
    "reason": "heuristic-adjustment",
    "diff": [
      {
        "key": "plan.steps[0].description",
        "before": "Collect relevant context",
        "after": "Collect relevant context with risk review"
      }
    ],
    "applied": true,
    "policy_id": "planner.meta",
    "policy_version": "1.0.0",
    "policy_kind": "rules",
    "intuition_event_id": "evt_intuition",
    "risk_level": "high",
    "salience_signals": ["policy_hint"],
    "strategy_hints": ["verify_first"],
    "tool_constraints": ["read_only"],
    "scrutiny_level": "strict",
    "evidence_ids": ["event:observe:1"]
  },
  "evidence_ids": ["event:observe:1"],
  "caused_by": "plan_event_id"
}

payload.schema_version

string

required

Direction schema version (1.2.0 at time of writing).

payload.directive_id

string

required

Stable directive identifier derived from content.

payload.legacy_directive_id

string

Legacy UUID retained for compatibility.

payload.status

string

required

Directive status: applied, blocked, skipped.

payload.diff

array

Structured mutations with key, before, after.

payload.reason

string

required

Why the directive status was produced.

payload.policy_id

string

required

Policy that issued the directive (typically planner.meta).

payload.policy_version

string

required

Policy version for compatibility and replay diagnostics.

payload.policy_kind

string

required

Policy kind: llm, rules, hybrid.

payload.intuition_event_id

string

When present, links this directive back to the originating intuition event.

payload.risk_level

string

Optional steering carry-over: low, moderate, high, critical.

payload.scrutiny_level

string

Optional steering carry-over: normal, elevated, strict.

evidence_ids

array

Evidence propagated from intuition (payload.evidence_ids mirrors this when set).

governance

Records governance decisions (meta mode only).

{
  "phase": "governance",
  "payload": {
    "governance_id": "gov_def456",
    "decision_id": "dec_789",
    "decision": "allow",
    "rule_id": "rules.allow.default",
    "score": 0.95,
    "policy_id": "governance.rules",
    "policy_version": "1.0.0",
    "policy_kind": "rules",
    "details": {
      "checked_rules": ["rule1", "rule2"],
      "matched_rule": "rule1"
    }
  }
}

payload.governance_id

string

required

Unique governance event identifier.

payload.decision

string

required

Governance decision: allow, audit, veto.

payload.rule_id

string

Rule that determined the decision.

payload.score

number

Confidence score for the decision (0-1).

payload.policy_id

string

required

Governance policy identifier.

payload.details

object

Additional governance details.

act

Logs tool or adapter invocations. The runtime emits an action projection that is intentionally close to the persisted state.json action record so action outcomes are reconstructible from events.jsonl.

{
  "phase": "act",
  "payload": {
    "action_id": "act-2",
    "kind": "adapter",
    "tool": "adapter:core.minimal",
    "input_excerpt": "Execute goal: Draft release notes",
    "outcome": "ok",
    "result_status": "ok",
    "step_id": "step-2",
    "step_status": "done"
  }
}

payload.action_id

string

Action record identifier (for example act-1).

payload.kind

string

Action kind (for example tool).

payload.tool

string

Tool that was invoked.

payload.input_excerpt

string

required

Truncated input for logging.

payload.outcome

string

required

Compatibility status field for existing consumers.

payload.result_status

string

Canonical action status mirrored from state (ok, error, vetoed, etc.).

payload.outcome

string

required

Action outcome value.

payload.result_status

string

Canonical action status string from the action record (for example, ok).

payload.step_id

string

Plan step ID associated with this action.

payload.step_status

string

Resulting status for payload.step_id. This field is used to project final step status from act evidence.

payload.x-*

any

Extension keys from the action record. Only x- prefixed extension keys are emitted.

outcome and result_status currently carry the same status value. outcome is retained for compatibility with older consumers.

For runtime-emitted actions, state.json action timestamps are aligned to the event completion time before persistence, so state.outcomes.actions[n].timestamp == act_event.timestamp.

reflect

Evaluates outcomes against expectations.

{
  "phase": "reflect",
  "payload": {
    "success": true,
    "reason": "All planned steps completed successfully",
    "expected_outcomes": ["data_processed", "report_generated"],
    "actual_outcomes": ["data_processed", "report_generated"],
    "issues": [],
    "metrics": {
      "task_score": 0.95,
      "steps_completed": 3,
      "steps_total": 3
    }
  }
}

payload.success

boolean

required

Whether the episode succeeded.

payload.reason

string

required

Human-readable explanation of the outcome.

payload.expected_outcomes

array

List of expected outcomes.

payload.actual_outcomes

array

List of actual outcomes.

payload.issues

array

List of issues encountered.

payload.metrics

object

Evaluation metrics.

learn

Captures learning signals for future episodes. The minimal validator expects the following keys; runners may add extra detail.

{
  "phase": "learn",
  "payload": {
    "policy_id": "policy:core.meta",
    "basis": ["rules.veto.danger"],
    "proposal": [],
    "applied": false,
    "scope": "episode"
  }
}

payload.policy_id

string

required

Policy that produced the learning signal.

payload.basis

array

required

Reasons or evidence that drove the learning update.

payload.proposal

array

required

List of proposed updates (may be empty).

payload.applied

boolean

required

Whether the proposed updates were applied.

payload.scope

string

required

Update scope: session, episode, policy, global.

runtime (`run.*`)

Runtime events share phase="runtime" and use event_type as the stable subtype. The current lifecycle family includes run.interrupt, run.checkpoint, run.resume, and run.state_projection. run.state_projection is emitted whenever state is persisted so state.json outcome/link fields have explicit event evidence.

{
  "phase": "runtime",
  "event_type": "run.state_projection",
  "payload": {
    "kind": "run.state_projection",
    "status": "interrupted",
    "outcomes": {
      "status": "interrupted",
      "summary": "Awaiting approval",
      "metrics": {}
    },
    "links": {
      "events": "events.jsonl",
      "learn": "learn.jsonl"
    }
  },
  "caused_by": "evt_prev123"
}

payload.kind

string

required

Always run.state_projection for projection evidence records.

payload.status

string

required

Mirrors payload.outcomes.status for compatibility with existing consumers.

payload.outcomes

object

required

Trace-backed projection of persisted state outcome fields: status, summary, and metrics.

payload.links

object

required

Trace-backed projection of persisted state.json.links.

Non-terminal runs: events, learn
Terminal runs: events, learn, summary, manifest

caused_by

string

For runtime lifecycle/projection events, points to the latest prior event in the trace when available.

terminate

Marks the end of an episode.

{
  "phase": "terminate",
  "payload": {
    "status": "completed",
    "episode_id": "ep_2024_abc123_s0",
    "duration_ms": 5000
  }
}

payload.status

string

required

Final status: completed, errored, vetoed, aborted.

payload.episode_id

string

required

Episode identifier.

payload.duration_ms

number

required

Total episode duration in milliseconds.

Phase order (partial)

Current phases: start, observe, interpret, plan, direction, governance, action_candidate, act, reflect, learn, runtime, terminate, insight, memory, intuition, reason, error.

Required: start kicks off every episode; terminate marks completion.
Typical loop: observe → interpret → plan → (direction/governance in meta mode) → act → reflect → (learn optionally).
Optional tail: insight and memory may emit after terminate for scoring/persistence.
Partial order: phases follow the sequence above when present, but not every phase appears in every run.

Reading events

CLI

# All events
noesis events ep_abc123

# Filter by phase
noesis events ep_abc123 --phase act

# As JSON
noesis events ep_abc123 -j

Python

import noesis as ns
from noesis.trace.events import EventLogIntegrityError

try:
    events = list(ns.events.read("ep_abc123"))
except EventLogIntegrityError as exc:
    corruption = exc.corruption
    print(f"Corrupted trace at line {corruption.line_number}: {corruption.reason}")
    raise

# Filter
act_events = [e for e in events if e["phase"] == "act"]

# Reconstruct lineage
def get_chain(events, event_id):
    chain = []
    current = next((e for e in events if e["id"] == event_id), None)
    while current:
        chain.append(current)
        caused_by = current.get("caused_by")
        current = next((e for e in events if e["id"] == caused_by), None)
    return chain

Troubleshooting: verify plan derivability

Use the runtime projector to confirm state.json.plan is derivable from events.jsonl.

import noesis as ns
from noesis.runtime.plan_projection import project_plan_state

episode_id = "ep_01JH6Z2V9Q2K6Y6N0QZ7K2QW8C"
events = list(ns.events.read(episode_id))
projected = project_plan_state(events)
state = ns.state.read(episode_id)

assert projected is not None
assert projected.to_dict() == state["plan"]

If this assertion fails, inspect:

the latest plan payload for step_records and source
act payload entries for both step_id and step_status

If this exception is raised, treat the episode trace as untrusted until the underlying events.jsonl is repaired or replaced.

API reference

Schema reference

Configuration

Integrity contract (`events.jsonl`)

Event structure

Event phases

observe

intuition

interpret

plan

direction

governance

act

reflect

learn

runtime (`run.*`)

terminate

Phase order (partial)

Reading events

CLI

Python

Troubleshooting: verify plan derivability

Next steps

State schema

Cognitive loop

API reference

Schema reference

Configuration

​Integrity contract (events.jsonl)

​Event structure

​Event phases

​observe

​intuition

​interpret

​plan

​direction

​governance

​act

​reflect

​learn

​runtime (run.*)

​terminate

​Phase order (partial)

​Reading events

​CLI

​Python

​Troubleshooting: verify plan derivability

​Next steps

State schema

Cognitive loop

Integrity contract (`events.jsonl`)

Event structure

Event phases

observe

intuition

interpret

plan

direction

governance

act

reflect

learn

runtime (`run.*`)

terminate

Phase order (partial)

Reading events

CLI

Python

Troubleshooting: verify plan derivability

Next steps