The ONDEMANDENV Platform

1. The ContractsLib: A Legislature, Not a Registry

The contractsLib is a version-controlled TypeScript library that declares every service, every deployable version of every service, and every producer/consumer edge between them — with schema artifacts attached as children of the edges. This is the "living model" from the philosophy made literal: not a diagram of intent, but a compiled artifact that is the intent, and that fails to publish if the intent is inconsistent.

Think of it as the congress of your distributed system, not a service registry:

• Services send representatives: Each service's OdmdBuild, its OdmdEnver instances, and the producers/consumers each enver declares.
• Cross-ref edges are enacted law: Once wired, they define an obligation each side must implement. A producer owes its consumers a stable address and a schema-valid payload.
• tsc + odmdValidate() is the constitutional court: If the graph has a forbidden edge, the build fails. The ContractsLib package does not publish.
• Services are compelled to conform: At build time, a consumer downloads its upstream producer's schema artifact, generates types into __generated__/, and compiles against them. A handler that doesn't match its declared contract fails to compile — not at runtime, not in staging.

A service registry is passive: it records what services say about themselves. A legislature is active: it's where services negotiate, enact, and are bound. Your PRs to ContractsLib are legislation; its compiled output is law.

2. Enver (Environment Version): Phases Collapsed onto One Axis

An Enver is a complete, deployable version of a service's bounded context — its entire stack: infrastructure, dependencies, build pipeline, and monitoring. It is the unit of evolution: where the model, once compiled, becomes a running, disposable projection instead of a document about a system.

The core insight: development phases and deployment environments are the same axis. There is no separate "environment" concept. An enver is a phase.

Canonical progression: mock → dev → main. No forward references — a mock enver never consumes a dev producer.

Two kinds of enver:

• Branch envers — dynamic, update when their branch is pushed or a dependency changes. Used for mock, dev, and feature branches.
• Tag envers — immutable, fixed point-in-time. Used for production releases.

Each enver provides a complete SDLC context: unique endpoints, isolated infrastructure, automated build and deploy, built-in BDD, and per-enver monitoring. Clone one with a single commit message to get a full isolated copy for a feature branch.

3. Producer / Consumer: Typed Edges with Schema Artifacts

Services declare what they publish and what they depend on using OdmdCrossRefProducer and OdmdCrossRefConsumer in ContractsLib. These are the edges of the contract graph.

// In ContractsLib — producer declares a base URL + schema artifact child
export class OrderEnver extends OdmdEnverCdk {
  readonly orderApiBaseUrl = new OdmdCrossRefProducer(
    this, 'orderApiBaseUrl',
    { children: [{ pathPart: 'schema-url', s3artifact: true }] }
  );
}

// Consumer declares its dependency on the producer
export class PaymentEnver extends OdmdEnverCdk {
  readonly orderApiBaseUrl = new OdmdCrossRefConsumer(
    this, 'orderApiBaseUrl', orderEnver.orderApiBaseUrl
  );
}

At deploy time: Producers publish their base URL and schema artifact via OdmdShareOut (backed by AWS SSM Parameter Store). Consumers read them via OdmdShareIn or getSharedValue() during CDK synth.

Schema artifacts are the mechanism that makes compatibility deductive. A producer attaches an OpenAPI 3.1 or AsyncAPI 2.x document as a child of its base URL producer. At build time, a consumer's build.sh:

1. Downloads the upstream schema artifact from S3 via a SchemaTypeLoader utility (a platform-documented pattern your ContractsLib implements, not a class shipped in the base library).
2. Generates Zod types into lib/handlers/src/__generated__/ via json-schema-to-zod.
3. Compiles the handler against the generated types.

If the handler doesn't conform to the declared contract, tsc fails. The incompatibility is caught before any deployment.

4. Constellation: Emergent, Not Declared

A Constellation is the subgraph of envers reachable by following producer/consumer edges from any starting enver. Constellations are emergent — they come into existence when ContractsLib wiring is enacted, not when anything is declared. They have no names, no registry, no enumeration. This is the closest thing on the platform to the model "coming alive": a constellation is what the living model looks like once it's running, and it is provably consistent because every edge in it already compiled.

How a constellation forms:

1. Each service declares one or more envers in ContractsLib (mock, dev, main).
2. Each enver declares producers and consumers.
3. ContractsLib wires consumers to specific upstream producers (typically same-revision to same-revision).
4. The transitive closure of those edges is a constellation.

"Mock constellation" is informal shorthand for the constellation rooted at mock-revision envers. It is not a class, type, or stack-name token. Multiple constellations coexist in the same AWS accounts, distinguished only by their SRC_Rev_REF (branch or tag).

Dynamic Cloning: Full Environments on Demand

Every feature branch can have its own complete, isolated enver — a full SDLC clone with unique endpoints, dedicated infrastructure, and independent lifecycle. Creating one requires a single commit message:

git commit -m "feat: new recommendation engine

odmd: create@dev"

Each cloned enver is resource-isolated — unique naming prevents conflicts. Static envers (mock, dev, main) are unaffected. Multiple developers and AI agents can run parallel experiments simultaneously, each with full infrastructure control, without shared-environment coordination.

A complete environment — VPC, database, load balancing, monitoring — provisions automatically from the graph, with no manual setup. The cost of experimentation drops to near zero.