Modules

Explicit architecture boundaries that prevent uncontrolled coupling between subsystems

What are Modules?

Modules are architectural boundaries. They group related entities and capabilities into cohesive units and declare explicit dependency rules. A module says "I own these entities, I expose these capabilities, I may depend on these other modules, and I must never depend on these other modules."

Unlike informal package boundaries, SysMARA modules are enforced by the compiler and diagnostics engine. If a capability in the billing module references an entity from the users module, the system verifies that users is in billing's allowedDependencies. If it is not, a boundary violation diagnostic is emitted.

ModuleSpec Structure

interface ModuleSpec {
  name: string;                    // unique module name, e.g. "billing"
  description: string;             // what this module is responsible for
  entities: string[];              // entity names owned by this module
  capabilities: string[];          // capability names exposed by this module
  allowedDependencies: string[];   // modules this module may depend on
  forbiddenDependencies: string[]; // modules this module must never depend on
  owner?: string;                  // team or person responsible
}

Boundary Validation

The diagnostics engine performs several boundary checks:

Cross-Module Entity Access

When a capability references an entity, the engine looks up which module owns that entity. If the entity's module is not the same as the capability's module and is not in the capability module's allowedDependencies, a CAP_BOUNDARY_VIOLATION diagnostic is emitted.

Conflicting Dependencies

If a module lists the same name in both allowedDependencies and forbiddenDependencies, a MOD_CONFLICTING_DEP diagnostic is emitted.

Self-References

A module that lists itself in allowedDependencies triggers a MOD_SELF_DEP warning. A module that lists itself in forbiddenDependencies triggers a MOD_SELF_FORBIDDEN warning.

Undefined Dependencies

References to modules that do not exist trigger MOD_UNDEFINED_DEP (for allowed) or MOD_UNDEFINED_FORBIDDEN_DEP (for forbidden) diagnostics.

Cycle Detection

The boundary engine runs a depth-first search on the module dependency graph to detect circular dependencies. If module A depends on module B and module B depends on module A, a BOUNDARY_CIRCULAR_DEP diagnostic is emitted with the full cycle path.

Cycle detection prevents architectural spaghetti that makes impact analysis unreliable. If modules can depend on each other in cycles, the AI System Graph cannot provide accurate impact surfaces, and the Change Protocol cannot correctly classify risk.

Diagnostic Codes

Code	Severity	Description
`MOD_CONFLICTING_DEP`	error	Module lists a dependency in both allowed and forbidden
`MOD_SELF_DEP`	warning	Module lists itself as an allowed dependency
`MOD_SELF_FORBIDDEN`	warning	Module lists itself as a forbidden dependency
`MOD_UNDEFINED_DEP`	error	Module references an undefined allowed dependency
`MOD_UNDEFINED_FORBIDDEN_DEP`	warning	Module forbids an undefined dependency
`CAP_BOUNDARY_VIOLATION`	error	Capability crosses a module boundary without authorization
`CAP_BOUNDARY_UNDEFINED_MODULE`	error	Capability belongs to a module that does not exist
`BOUNDARY_CIRCULAR_DEP`	error	Circular dependency detected between modules

YAML Example: SaaS Billing Modules

modules:
  - name: users
    description: User registration, authentication, and profile management
    entities:
      - user
    capabilities:
      - create_user
      - get_user
    allowedDependencies: []
    forbiddenDependencies: []
    owner: platform-team

  - name: workspaces
    description: Workspace lifecycle, membership, and ownership management
    entities:
      - workspace
    capabilities:
      - create_workspace
      - get_workspace
      - transfer_workspace_owner
      - list_workspace_members
      - add_workspace_member
    allowedDependencies:
      - users
    forbiddenDependencies: []
    owner: platform-team

  - name: billing
    description: Subscription management, invoice generation, and payment processing
    entities:
      - subscription
      - invoice
    capabilities:
      - create_subscription
      - cancel_subscription
      - upgrade_subscription
      - downgrade_subscription
      - generate_invoice
      - void_invoice
      - get_invoice
    allowedDependencies:
      - users
      - workspaces
    forbiddenDependencies: []
    owner: billing-team

In this example, billing is allowed to depend on users and workspaces, so capabilities like create_subscription can reference the workspace entity. The users module has no allowed dependencies — it is a leaf module that other modules depend on but that does not depend on anything else.

Graph Relationships

Modules create several edge types in the AI System Graph:

entity:subscription --belongs_to--> module:billing (entity ownership)
module:billing --depends_on--> module:users (declared dependency)
module:billing --depends_on--> module:workspaces (declared dependency)

AI-Safe Change Workflows

Module boundaries are a first-class concern in the Change Protocol. When a change plan proposes adding a new capability, the plan generator checks whether the capability's entity references respect the owning module's boundary rules. When an AI agent proposes adding a new dependency between modules, the cycle detection engine verifies that the new edge does not create a circular dependency. This prevents AI agents from gradually eroding architecture boundaries through a series of individually-reasonable changes.