Roadmap

Current status, what exists today, and what is coming next.

Current Status: v0.2.0

SysMARA is in active early-stage development. The core architecture specification and validation system is functional and being used in real projects. The API is not yet stable — breaking changes may occur between minor versions.

What Exists Today

The following features are implemented and tested:

Specification System

• Six spec types: entities, capabilities, policies, invariants, modules, and flows.
• YAML-based spec files with Zod schema validation.
• Recursive file discovery — organize specs in flat directories or nested structures.
• Scaffolding with sysmara add for all spec types.

Validation and Diagnostics

• Full cross-validation of all inter-spec references.
• 30+ diagnostic codes covering duplicates, reference resolution, boundary violations, orphans, safety, and consistency.
• Module boundary enforcement with depends_on and forbidden_deps.
• Comprehensive health check via sysmara doctor (9 sections).

Graph and Analysis

• System graph generation with full relationship mapping.
• System map generation for AI agent discovery.
• Impact analysis with BFS traversal (depth 3, bidirectional).
• Change plan creation and rendering (terminal, markdown, JSON).
• Capability explanation with sysmara explain.

Runtime

• Minimal built-in HTTP server (SysmaraServer).
• Route registration mapping HTTP endpoints to capabilities.
• Actor extraction and policy enforcement.
• Built-in /health and /_sysmara/routes endpoints.
• Structured error hierarchy (SysmaraError, ValidationError, PolicyError, InvariantError).

CLI

• Full command set: init, add, validate, build, graph, compile, doctor, explain, impact, plan create, plan show, check boundaries.
• JSON output mode on all commands for tooling integration.

What Is Coming Next

The following items are planned. Priorities may shift based on community feedback and real-world usage.

Database Adapter System

A plugin system for connecting entity specs to database backends. This would allow SysMARA to generate data access code, validate schemas against actual database tables, and potentially manage migrations. The goal is not to replace existing ORMs but to bridge the gap between logical entity definitions and physical storage.

Status: Design phase. Evaluating how to keep this optional and database-agnostic.

Authentication Middleware Patterns

Reference implementations and patterns for common authentication scenarios: JWT validation, session-based auth, API key authentication, OAuth flows. These would be examples and optional middleware, not built-in authentication.

Status: Planned. Will be released as a separate package or documented patterns.

Plugin and Extension System

A formal plugin API that allows third-party extensions to:

• Add new spec types beyond the core six.
• Register custom diagnostic rules.
• Extend the compiler with new transformation passes.
• Add new CLI commands.

Status: Early design. The internal architecture already supports this pattern, but a stable public API needs to be defined.

IDE Integrations

Extensions for popular editors that provide:

• YAML autocompletion for spec files based on Zod schemas.
• Inline diagnostic display (red squiggles for errors, yellow for warnings).
• Go-to-definition for spec references (click an entity name in a capability to jump to the entity file).
• Hover information showing spec details and relationships.

Status: Planned. VS Code extension is the first target.

AI Agent SDK

A dedicated SDK for AI agents to interact with SysMARA projects programmatically. This would provide:

• Structured API for reading and modifying specs.
• Impact analysis before making changes.
• Automatic validation after changes.
• System map and graph access without CLI invocation.

Status: Planned. The current CLI with --json output serves as an interim solution.

Additional Diagnostic Rules

More diagnostic rules to catch common architectural issues:

• Detecting overly large modules (too many entities or capabilities).
• Warning about deep dependency chains.
• Identifying capabilities that could be split.
• Detecting naming convention violations.
• Checking for missing descriptions in specs.

Status: Ongoing. New rules are added regularly.

Performance Benchmarks

Published benchmarks for:

• Spec parsing speed at various project sizes (10, 100, 1000 specs).
• Graph construction time.
• Impact analysis traversal time.
• Runtime request handling overhead compared to raw Node.js HTTP.

Status: Planned. Internal benchmarks exist but are not yet published.

Production Hardening

Improvements for production use:

• Structured logging with configurable transports.
• Metrics export (Prometheus, OpenTelemetry).
• Rate limiting patterns.
• Request tracing and correlation IDs.
• Graceful degradation when specs cannot be loaded.

Status: Planned. The current server handles graceful shutdown but lacks observability features.

How to Influence the Roadmap

SysMARA's roadmap is shaped by real-world usage. If you are using SysMARA and have specific needs:

• Open an issue on GitHub describing your use case and what you need.
• Contribute — many of the items above are good candidates for community contributions. See the Contributing guide.
• Share feedback on what works well and what does not. Even bug reports help prioritize work.

Versioning Policy

While SysMARA is pre-1.0, minor versions (0.x.0) may include breaking changes. Patch versions (0.x.y) are backward-compatible bug fixes. Once SysMARA reaches 1.0, it will follow strict semantic versioning.

Pin your version in package.json and read the changelog before upgrading.