Skip to content
Lexicon

Ecosystem Mode

Ecosystem Mode extends Lexicon for multi-repository platforms. It adds shared contracts, repository roles, cross-repo compatibility checks, and ecosystem-level governance.

When to Use Ecosystem Mode

Section titled “When to Use Ecosystem Mode”

Use Ecosystem Mode when your platform spans multiple repositories and you want to:

  • share contracts across repositories
  • assign roles to repositories (core library, SDK, adapter, application)
  • enforce dependency law across the ecosystem
  • detect cross-repo contract drift and compatibility breaks

Activating Ecosystem Mode

Section titled “Activating Ecosystem Mode”

Ecosystem Mode is activated by having a .lexicon/ecosystem.toml file. This can be configured during setup.

The ecosystem manifest:

  1. Preserves existing repo-local and workspace state
  2. Defines repository roles and shared contracts
  3. Creates ecosystem governance structures

Repository Roles

Section titled “Repository Roles”

Each repository in the ecosystem has a declared role:

  • core library — foundational code with strict stability requirements
  • runtime — execution environment with performance and safety contracts
  • interface definition — API surface declarations consumed by others
  • adapter / backend — implementations of shared traits
  • SDK — developer-facing libraries with compatibility constraints
  • plugin / extension — code operating within a host contract
  • application — end-user-facing code
  • experimental — exploratory code that cannot publish stable shared contracts

Shared Contracts

Section titled “Shared Contracts”

Shared contracts are referenced by multiple repositories:

  • API compatibility rules
  • data interchange invariants
  • trait semantics expected across implementations
  • wire format guarantees
  • plugin interface contracts

These are stored under .lexicon/ecosystem/contracts/ and can be validated across the ecosystem.

Impact Analysis

Section titled “Impact Analysis”

When a contract or API changes, the ecosystem model can estimate:

  • downstream repo impact
  • shared contract consumers affected
  • likely breaking change severity
  • compatibility risk

Upgrading from Workspace Mode

Section titled “Upgrading from Workspace Mode”

Migration from Workspace Mode is additive:

  • existing workspace architecture rules are preserved
  • ecosystem governance is added alongside existing configuration
  • no existing state is modified

lexicon verify continues to work at all scopes.