Impact Analysis

Before you change anything, understand exactly what will be affected.

Why Impact Analysis Matters

In a system with dozens of entities, capabilities, and modules, changing one thing can have cascading effects. Renaming an entity might break capabilities that reference it, which in turn affects modules that contain those capabilities, which could violate invariants that govern those entities. Impact analysis traces these connections automatically so you can make informed decisions before writing code.

How It Works

SysMARA's impact analyzer performs a breadth-first search (BFS) traversal of the system graph starting from a target node. It follows edges in both directions — if entity A references entity B, then changing either A or B could affect the other. The traversal has a maximum depth of 3, meaning it will follow up to three hops from the starting node.

The bidirectional traversal is important because relationships in SysMARA are not always one-way. A capability references an entity, but if the entity changes, the capability is affected. A module contains capabilities, but if a capability changes, the module's boundary rules might need updating.

Traversal Rules

• Direction: Bidirectional — edges are followed regardless of which end is the source.
• Max depth: 3 hops from the target node.
• Deduplication: Each node is visited at most once. If the same capability is reachable via two paths, it appears once in the results.
• Target format: Targets are specified as type:name, for example entity:User or capability:CreateOrder.

CLI Usage

Use the sysmara impact command to run impact analysis:

npx sysmara impact entity User

This analyzes what would be affected if the User entity changes. You can analyze any spec type:

# Analyze impact of changing an entity
npx sysmara impact entity User

# Analyze impact of changing a capability
npx sysmara impact capability CreateOrder

Add the --json flag for machine-readable output:

npx sysmara impact entity User --json

What It Returns

The impact analysis returns an ImpactSurface — a structured result that lists every affected spec grouped by type. The surface includes:

• Affected modules — Modules that contain affected capabilities or entities.
• Affected capabilities — Capabilities that reference the changed spec or depend on something that does.
• Affected invariants — Invariants that govern the changed entity or related entities.
• Affected policies — Policies attached to affected capabilities.
• Affected routes — Routes that expose affected capabilities.
• Affected flows — Flows that include affected capabilities as steps.

Example Output

Consider a system where User is referenced by several capabilities and governed by an invariant:

$ npx sysmara impact entity User

Impact Analysis: entity:User
Depth: 3 hops

Affected Capabilities (3):
  - RegisterUser (depth 1)
  - UpdateUserProfile (depth 1)
  - CreateOrder (depth 2)

Affected Modules (2):
  - users (depth 1)
  - orders (depth 2)

Affected Invariants (1):
  - UserEmailUniqueness (depth 1)

Affected Policies (2):
  - RequireAuthentication (depth 2)
  - RequireAdminRole (depth 2)

Affected Flows (1):
  - UserOnboarding (depth 2)

Using Impact Analysis Before Making Changes

The recommended workflow is to run impact analysis before modifying any spec file:

1. Identify the change. Decide what you want to modify — perhaps adding a field to the User entity.
2. Run impact analysis. Execute sysmara impact entity User to see the blast radius.
3. Review the surface. Check which capabilities, modules, and invariants are affected. Are any of them critical?
4. Make the change. Edit the spec file with confidence, knowing what else might need updating.
5. Validate. Run sysmara validate and sysmara build to confirm nothing is broken.

Integration with Change Plans

Impact analysis is also used internally by the change plan system. When you create a change plan with sysmara plan create, the planner runs impact analysis automatically to include the affected surface in the plan document. See the Change Plans guide for details.

Depth and Performance

The maximum depth of 3 is a deliberate design choice. In most well-structured systems, three hops captures the meaningful blast radius without flooding the results with every node in the graph. If your impact surfaces are consistently very large, it may indicate that your modules are too tightly coupled and would benefit from clearer boundaries.