BranchPy
Log in

Docs-Builder

# Event Catalog

Version: 1.1.1
Last Updated: January 23, 2026

Overview

Complete reference for all BranchPy event types, schemas, and usage examples. All events share a common base schema with topic-specific payload fields.

Base Schema

All events include these required fields:

{
  "type": "string",           // Event type (e.g., "sae.start", "validation.done")
  "ts": "ISO8601",            // Timestamp (auto-added if missing)
  "level": "string",          // Level: "debug" | "info" | "warn" | "error"
  "topic": "string",          // Topic/category (see Event Topics)
  "source": "string",         // Source component (optional)
  "correlation_id": "string"  // UUID for tracing (auto-generated if missing)
}

Field Descriptions:

Field Type Required Description
type string Yes Event type identifier
ts string Yes ISO 8601 timestamp (auto-generated if omitted)
level string Yes Severity: debug, info, warn, error
topic string Yes Category for filtering (see topics below)
source string No Originating component name
correlation_id string Yes UUID for tracing (auto-generated if omitted)

Event Levels

Level Description Use Case
debug Verbose diagnostic information Development, troubleshooting
info Normal operational events Audit trail, monitoring
warn Warning conditions (recoverable) Potential issues, performance
error Error conditions (non-fatal) Failures, exceptions

Event Topics

Topic Description
audit User actions and system changes
sae Static analysis engine operations
validation Validation checks and policy enforcement
cfg Control Flow Graph extraction
daemon WebSocket daemon lifecycle
compare Run-to-run comparison operations
system System-level messages and errors
stats Performance metrics and telemetry
lint Linting operations
policy Policy enforcement events
general Uncategorized or generic events

1. Audit Events

Topic: audit
Description: User actions and system changes for compliance and forensics

Event Types

audit.edit

File edited in editor.

Schema:

{
  "type": "audit.edit",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "audit",
  "source": "editor",
  "correlation_id": "a1b2c3d4-...",
  "file": "game/scenes/intro.rpy",
  "user": "developer@example.com"
}

Fields:

  • file: Relative path to edited file
  • user: Email or username of editor

audit.save

File saved to disk.

Schema:

{
  "type": "audit.save",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "audit",
  "source": "editor",
  "correlation_id": "a1b2c3d4-...",
  "file": "game/scenes/intro.rpy",
  "user": "developer@example.com"
}

Fields:

  • file: Relative path to saved file
  • user: Email or username of user

audit.analyze

Analysis operation triggered.

Schema:

{
  "type": "audit.analyze",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "audit",
  "source": "cli",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "user": "developer@example.com",
  "command": "branchpy analyze"
}

Fields:

  • project: Absolute path to project
  • user: Email or username
  • command: CLI command executed

audit.command

CLI command executed.

Schema:

{
  "type": "audit.command",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "audit",
  "source": "cli",
  "correlation_id": "a1b2c3d4-...",
  "command": "branchpy compare --base run1 --head run2",
  "user": "developer@example.com",
  "exit_code": 0
}

Fields:

  • command: Full command string
  • user: Email or username
  • exit_code: Command exit code (0 = success)

2. SAE Events

Topic: sae
Description: Static Analysis Engine operations and results

Event Types

sae.start

SAE analysis started.

Schema:

{
  "type": "sae.start",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "sae",
  "source": "solver",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project"
}

Fields:

  • project: Absolute path to analyzed project

sae.done

SAE analysis completed.

Schema:

{
  "type": "sae.done",
  "ts": "2026-01-23T14:30:15Z",
  "level": "info",
  "topic": "sae",
  "source": "solver",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "labels": 123,
  "pruned": 7,
  "warnings": 2,
  "duration_ms": 15234
}

Fields:

  • project: Absolute path to project
  • labels: Number of labels analyzed
  • pruned: Number of edges pruned
  • warnings: Number of warnings generated
  • duration_ms: Analysis duration in milliseconds

sae.edge_pruned

Edge marked as infeasible during analysis.

Schema:

{
  "type": "sae.edge_pruned",
  "ts": "2026-01-23T14:30:10Z",
  "level": "debug",
  "topic": "sae",
  "source": "solver",
  "correlation_id": "a1b2c3d4-...",
  "from_label": "scene1",
  "to_label": "scene2",
  "reason": "Condition always false"
}

Fields:

  • from_label: Source label
  • to_label: Target label
  • reason: Pruning rationale

3. Validation Events

Topic: validation
Description: Validation checks and policy enforcement

Event Types

validation.start

Validation check started.

Schema:

{
  "type": "validation.start",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "validation",
  "source": "validator",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "rules": ["no_dead_ends", "max_depth"]
}

Fields:

  • project: Absolute path to project
  • rules: List of validation rules to check

validation.done

Validation check completed.

Schema:

{
  "type": "validation.done",
  "ts": "2026-01-23T14:30:20Z",
  "level": "info",
  "topic": "validation",
  "source": "validator",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "errors": 3,
  "warnings": 5,
  "passed": 12
}

Fields:

  • project: Absolute path to project
  • errors: Number of validation errors
  • warnings: Number of validation warnings
  • passed: Number of rules passed

validation.error

Validation error found.

Schema:

{
  "type": "validation.error",
  "ts": "2026-01-23T14:30:15Z",
  "level": "error",
  "topic": "validation",
  "source": "validator",
  "correlation_id": "a1b2c3d4-...",
  "rule": "no_dead_ends",
  "message": "Dead end found at label 'bad_end'",
  "location": "game/scenes/intro.rpy:45"
}

Fields:

  • rule: Validation rule name
  • message: Error description
  • location: File path and line number

4. CFG Events

Topic: cfg
Description: Control Flow Graph extraction operations

Event Types

cfg.start

CFG extraction started.

Schema:

{
  "type": "cfg.start",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "cfg",
  "source": "extractor",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project"
}

Fields:

  • project: Absolute path to project

cfg.done

CFG extraction completed.

Schema:

{
  "type": "cfg.done",
  "ts": "2026-01-23T14:30:10Z",
  "level": "info",
  "topic": "cfg",
  "source": "extractor",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "labels": 120,
  "edges": 450,
  "duration_ms": 8234
}

Fields:

  • project: Absolute path to project
  • labels: Number of labels extracted
  • edges: Number of edges extracted
  • duration_ms: Extraction duration in milliseconds

5. Daemon Events

Topic: daemon
Description: WebSocket daemon lifecycle events

Event Types

daemon.started

Daemon process started.

Schema:

{
  "type": "daemon.started",
  "ts": "2026-01-23T14:00:00Z",
  "level": "info",
  "topic": "daemon",
  "source": "daemon_manager",
  "correlation_id": "a1b2c3d4-...",
  "pid": 12345,
  "port": 8000,
  "version": "1.1.1"
}

Fields:

  • pid: Process ID
  • port: WebSocket port
  • version: Daemon version

daemon.stopped

Daemon process stopped.

Schema:

{
  "type": "daemon.stopped",
  "ts": "2026-01-23T18:00:00Z",
  "level": "info",
  "topic": "daemon",
  "source": "daemon_manager",
  "correlation_id": "a1b2c3d4-...",
  "pid": 12345,
  "uptime_seconds": 14400,
  "exit_code": 0
}

Fields:

  • pid: Process ID
  • uptime_seconds: Daemon uptime in seconds
  • exit_code: Exit code (0 = clean shutdown)

daemon.error

Daemon error occurred.

Schema:

{
  "type": "daemon.error",
  "ts": "2026-01-23T14:30:00Z",
  "level": "error",
  "topic": "daemon",
  "source": "daemon_manager",
  "correlation_id": "a1b2c3d4-...",
  "pid": 12345,
  "message": "Failed to bind to port 8000: Address already in use"
}

Fields:

  • pid: Process ID (if available)
  • message: Error description

6. Compare Events

Topic: compare
Description: Run-to-run comparison operations

Event Types

compare.start

Comparison started.

Schema:

{
  "type": "compare.start",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "compare",
  "source": "comparator",
  "correlation_id": "a1b2c3d4-...",
  "base": "analyze-2026-01-22_10-00-00",
  "head": "analyze-2026-01-23_14-30-00"
}

Fields:

  • base: Base run ID
  • head: Head run ID

compare.done

Comparison completed.

Schema:

{
  "type": "compare.done",
  "ts": "2026-01-23T14:30:25Z",
  "level": "info",
  "topic": "compare",
  "source": "comparator",
  "correlation_id": "a1b2c3d4-...",
  "base": "analyze-2026-01-22_10-00-00",
  "head": "analyze-2026-01-23_14-30-00",
  "changes": 15,
  "added": 3,
  "removed": 2,
  "modified": 10
}

Fields:

  • base: Base run ID
  • head: Head run ID
  • changes: Total number of changes
  • added: Number of added elements
  • removed: Number of removed elements
  • modified: Number of modified elements

7. System Events

Topic: system
Description: System-level messages and errors

Event Types

error

General system error.

Schema:

{
  "type": "error",
  "ts": "2026-01-23T14:30:30Z",
  "level": "error",
  "topic": "system",
  "source": "file_loader",
  "correlation_id": "a1b2c3d4-...",
  "message": "Failed to load config: file not found",
  "file": ".branchpy/config.json",
  "error_type": "FileNotFoundError"
}

Fields:

  • message: Error description
  • file: File path (if applicable)
  • error_type: Exception class name

info

General informational message.

Schema:

{
  "type": "info",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "system",
  "source": "server",
  "correlation_id": "a1b2c3d4-...",
  "message": "Server started on port 8000"
}

Fields:

  • message: Information message

8. Stats Events

Topic: stats
Description: Performance metrics and telemetry

Event Types

stats.memory

Memory usage statistics.

Schema:

{
  "type": "stats.memory",
  "ts": "2026-01-23T14:30:00Z",
  "level": "debug",
  "topic": "stats",
  "source": "profiler",
  "correlation_id": "a1b2c3d4-...",
  "rss_mb": 256.5,
  "vms_mb": 512.3,
  "percent": 12.3
}

Fields:

  • rss_mb: Resident Set Size in MB
  • vms_mb: Virtual Memory Size in MB
  • percent: Memory usage percentage

stats.timing

Operation timing statistics.

Schema:

{
  "type": "stats.timing",
  "ts": "2026-01-23T14:30:00Z",
  "level": "debug",
  "topic": "stats",
  "source": "profiler",
  "correlation_id": "a1b2c3d4-...",
  "operation": "sae_analysis",
  "duration_ms": 15234
}

Fields:

  • operation: Operation name
  • duration_ms: Duration in milliseconds

9. Lint Events

Topic: lint
Description: Linting operations

Event Types

lint.start

Linting started.

Schema:

{
  "type": "lint.start",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "lint",
  "source": "linter",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project"
}

Fields:

  • project: Absolute path to project

lint.done

Linting completed.

Schema:

{
  "type": "lint.done",
  "ts": "2026-01-23T14:30:05Z",
  "level": "info",
  "topic": "lint",
  "source": "linter",
  "correlation_id": "a1b2c3d4-...",
  "project": "/path/to/project",
  "errors": 2,
  "warnings": 8
}

Fields:

  • project: Absolute path to project
  • errors: Number of lint errors
  • warnings: Number of lint warnings

10. Policy Events

Topic: policy
Description: Policy enforcement events

Event Types

policy.violated

Policy violation detected.

Schema:

{
  "type": "policy.violated",
  "ts": "2026-01-23T14:30:00Z",
  "level": "warn",
  "topic": "policy",
  "source": "policy_engine",
  "correlation_id": "a1b2c3d4-...",
  "policy": "max_depth",
  "message": "Maximum depth exceeded: 15 > 10",
  "location": "game/scenes/intro.rpy:45"
}

Fields:

  • policy: Policy name
  • message: Violation description
  • location: File path and line number

policy.applied

Policy successfully applied.

Schema:

{
  "type": "policy.applied",
  "ts": "2026-01-23T14:30:00Z",
  "level": "info",
  "topic": "policy",
  "source": "policy_engine",
  "correlation_id": "a1b2c3d4-...",
  "policy": "max_depth",
  "project": "/path/to/project"
}

Fields:

  • policy: Policy name
  • project: Absolute path to project

JSON Schema (Formal)

Formal JSON Schema definition for event validation:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "BranchPy Event",
  "type": "object",
  "required": ["type", "ts", "level", "topic", "correlation_id"],
  "properties": {
    "type": {
      "type": "string",
      "description": "Event type (e.g., 'sae.start', 'validation.done')"
    },
    "ts": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp"
    },
    "level": {
      "type": "string",
      "enum": ["debug", "info", "warn", "error"],
      "description": "Event severity level"
    },
    "topic": {
      "type": "string",
      "enum": [
        "audit",
        "sae",
        "daemon",
        "policy",
        "validation",
        "cfg",
        "stats",
        "compare",
        "lint",
        "system",
        "general"
      ],
      "description": "Event topic/category"
    },
    "source": {
      "type": "string",
      "description": "Source component (optional)"
    },
    "correlation_id": {
      "type": "string",
      "format": "uuid",
      "description": "Correlation ID for tracing (auto-generated if missing)"
    }
  },
  "additionalProperties": true
}

Source References

Based on:

  • docs/v1.1.0/Events/events.schema.md
  • branchpy/server/events/helpers.py
  • branchpy/server/events/bus.py

Last Updated: January 23, 2026
Version: 1.1.1