Roadmap — SysMARA Framework Development Plan

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

Current Status: v0.8.3

SysMARA is in active early-stage development. The core architecture specification, validation system, database adapter layer, flow execution engine, AI bootstrap workflow, and production-quality scaffolding are 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.

Database Adapter System (v0.3.0)

A pluggable adapter system for connecting entity specs to database backends. Supports multiple ORMs and includes a built-in AI-first ORM.

  • Adapter interface and registry: A DatabaseAdapter interface with generateSchema(), generateMigration(), and generateRepository() methods. Adapters are registered and looked up by name through the adapter registry.
  • Prisma adapter: Generates schema.prisma files from entity specs with model definitions, relation detection, and typed repository classes per capability.
  • Drizzle adapter: Generates TypeScript-first schema.ts table definitions with provider-specific column mappings (PostgreSQL, MySQL, SQLite) and typed repositories.
  • TypeORM adapter: Generates @Entity() decorated TypeScript classes with @Column, @ManyToOne, @PrimaryGeneratedColumn decorators and typed repositories.
  • SysMARA ORM: An AI-first ORM where schema is the system graph, every query is scoped to a capability, invariants are enforced as DB constraints, every operation is logged as structured JSON, and migrations are impact-aware with risk classification. See SysMARA ORM.
  • CLI commands: sysmara db generate, sysmara db migrate, sysmara db status.
  • Configuration: Database adapter settings in the database section of sysmara.config.yaml.

Flow Execution Engine (v0.4.0)

A production-ready flow executor that makes declared flows actually run — not just validate.

  • FlowExecutor: Executes multi-step flows with pluggable capability handlers, context threading between steps, and structured execution records.
  • Saga compensation: On step failure with onFailure: "compensate", runs compensation capabilities in reverse order for all previously completed steps.
  • Retry with exponential backoff: Steps with onFailure: "retry" are retried up to a configurable number of times with exponentially increasing delays.
  • Condition evaluation: Safe recursive descent expression parser (no eval()) for step conditions like context.input.role === "admin".
  • AI-readable execution log: Every execution produces structured JSON records with summaries including success rate, average duration, and recent failures.
  • Flow validation: Validates that all step actions reference existing capabilities before execution.
  • CLI commands: sysmara flow list, sysmara flow validate, sysmara flow run, sysmara flow log.

Scaffold Generator (v0.7.1)

Automatic generation of starter TypeScript implementation files from YAML specs, integrated into the build pipeline.

  • Entity stubs: Typed interfaces with runtime validation helpers from entity specs.
  • Capability handlers: Handler functions with typed I/O imports, policy/invariant TODOs.
  • Policy enforcers: Enforcement functions with condition comments from specs.
  • Invariant validators: Validation functions referencing entity types.
  • Module services: Service classes with method stubs per capability.
  • Safe generation: Files written once, never overwritten on re-run.
  • CLI: sysmara scaffold standalone or integrated into sysmara build (step 5).

File Nodes & Owns Edges in System Graph (v0.7.2)

The system graph now models generated artifacts as first-class nodes, matching the formal definition G = (V, E, τv, τe).

  • File nodes: Each capability now generates three file nodes in the system graph — routes/*.ts, tests/*.test.ts, and metadata/*.json.
  • owns edges: Module → file edges connect each module to the generated files of its capabilities, enabling precise file-level impact analysis.
  • affectedFiles in impact analysis: ImpactSurface now includes an affectedFiles array listing concrete file paths affected by a change.
  • Impact formatter: Terminal output now displays an "Affected Files" section showing which generated files are impacted.

Smarter Schema Generation & Persisted DB Output (v0.8.3)

Two real-world papercuts reported by AI agents running sysmara db generate and reading back what they expected to be on disk. Both are fixed and back-compatible.

  • sysmara db generate persists output: The command previously logged "Generated N file(s)" but only returned content via --json — nothing was written to disk. It now writes to database.outputDir from sysmara.config.yaml (default ./app/database), with the existing generatedDir as fallback. The --json payload now includes the absolute paths of every written file. The same fix applies to sysmara db migrate.
  • Smarter column-type inference for string fields: The sysmara-orm schema generator no longer collapses every type: string field to VARCHAR(255). Four additive heuristics, all gated to keep existing specs unchanged:
    • Description-flagged JSON — if a string field's description mentions JSON, JSONB, Record<…>, or T[] arrays, it emits JSONB (PostgreSQL) / JSON (MySQL).
    • Long-text by name — common names (description, content, body, notes, recommendation, summary, excerpt, bio, markdown, html, text, message) and suffixes (*_html, *_md, *_content, *_body, *_description, *_text, *_notes) emit TEXT instead of VARCHAR(255).
    • maxLength constraint sizing — { type: maxLength, value: 320 } now produces VARCHAR(320) so RFC-compliant emails fit.
    • *_at date promotion — fields declared as type: date ending in _at become TIMESTAMPTZ on PostgreSQL and DATETIME(3) on MySQL. SQLite still uses TEXT.

Scaffolding & Runtime Fixes (v0.8.0)

Major improvements to scaffolded code quality based on real-world AI agent testing. Projects generated from a single prompt now work correctly out of the box.

  • Header-based actor extraction: Both sysmara start and the generated app/server.ts read X-Actor-Id and X-Actor-Roles HTTP headers to identify the caller. Previously all requests were treated as anonymous.
  • List handlers fixed: Scaffolded list_* handlers now read filters from ctx.query (query parameters) instead of ctx.body, which is null for GET requests.
  • Policy violations return 403: Scaffolded policy enforcement now throws ForbiddenError (HTTP 403) instead of a generic Error that was caught as 500 INTERNAL_ERROR.
  • Status transition scaffolding: Operations like publish_post, archive_post, submit_post_for_review, approve_comment, reject_comment now generate proper find-and-update-status logic instead of falling through to a read-only findById.
  • Association scaffolding: Operations like tag_post and untag_post now generate proper create/delete logic on the association entity.
  • Generated server parses real specs: The generated app/server.ts now calls parseSpecDirectory() and passes real specs to the ORM, instead of empty arrays.
  • Pagination in list handlers: Scaffolded list handlers support ?limit=N&offset=N&order_by=field&order_dir=ASC|DESC query parameters (default limit 50). SysmaraRepository.findMany() also accepts pagination options.
  • tsconfig.json generation: sysmara init now generates a tsconfig.json configured for ES2022/NodeNext — projects have a proper TypeScript build setup out of the box.
  • Status transition and association route inference in generated server: The generated app/server.ts now maps status-transition capabilities (publish_, approve_, etc.) to PATCH /:id/<verb> and association capabilities (tag_, untag_, etc.) to POST /:id/<verb>.

Real Database Drivers & Auto-Start (v0.7.0)

Full database connectivity and zero-config server startup — closing the gap from YAML specs to a running HTTP API.

  • Real database drivers: PostgreSQL (pg), MySQL (mysql2), and SQLite (better-sqlite3) as optional peer dependencies. In-memory fallback when no driver is installed.
  • sysmara start command: Parses specs, connects to the database, applies schema (CREATE TABLE IF NOT EXISTS), auto-wires every capability to an HTTP route based on naming conventions, and starts the server. Zero boilerplate.
  • Server entry point generation: sysmara build generates app/server.ts — a standalone runnable entry point that imports all scaffolded handlers and registers routes.
  • ORM lifecycle: connect(), disconnect(), applySchema(), isConnected() — full database connection management.
  • Auto route inference: Capability names map to HTTP methods and paths automatically (e.g., create_user → POST /users, get_user → GET /users/:id).
  • Config parser upgrade: Uses the yaml package instead of a hand-rolled parser, supporting full YAML including nested objects and arrays.

AI Bootstrap Guide (v0.4.10)

A complete protocol for AI agents to turn a single human prompt into a fully working SysMARA project — from npx @sysmara/core init to a running server.

  • BOOTSTRAP.md: Standalone protocol document that AI agents read to understand how to scaffold a complete project from a product description.
  • One-Prompt Workflow: Step-by-step instructions with copy-paste AI prompts for each stage — spec generation, validation, build, implementation, and server startup.
  • Three example projects: Complete generated specs for a SaaS Task Manager (5 entities, 15 capabilities), E-Commerce API (6 entities, 16 capabilities), and Blog Platform (6 entities, 21 capabilities).
  • AI Agent Guide: Documentation explaining SysMARA from an AI agent's perspective, including spec reading order, modification protocol, and the "why this works" philosophy.

What Is Coming Next

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

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.