Platform Concepts

Understand the app, Module, Service, and System Plane boundaries behind the public Lenso lifecycle.

Lenso is an agent-ready modular application and microservice framework for Rust business systems. It starts with one exact application composition and keeps each boundary explicit as the product grows.

Core model

Concept	Current contract	Responsibility
App Composition	`lenso.app.json`	Locks the app revision, content digest, immutable Module Releases, dependencies, implementation bindings, and provenance.
Module	`lenso.module.v1`	Owns a stable business identity, typed Business API, events, runtime declarations, and optional Console Surfaces.
Provider Service	`lenso.service.v1` metadata and `lenso.provider.v1` runtime	Provides exact Module Releases from a separate Rust or TypeScript process while the Host owns runtime coordination.
Autonomous Service	`lenso.service.v2`	Uses the Rust runtime to own its Workloads, Service Store, identity, workflows, and operations.
System topology	`lenso.system.v2`	Names the exact Host, Services, Modules, Workloads, contracts, and management relationships in a mixed topology.
Console Service	Console API	Connects the exact topology, loads receipt-bound Surfaces, and reports direct object status.

The contracts compose; they do not replace one another. Moving a Support Ticket Module from linked delivery to a Provider does not rename its business identity or operations. An Autonomous Service adds an independently owned runtime boundary while keeping its declared contracts explicit.

Public lifecycle

The same four steps apply to developers, operators, and coding agents:

Compose an exact lenso.app.json from a product blueprint.
Run locally with lenso dev up; add --console-root to start an existing Console checkout with the Host and Provider Services.
Connect the signed local Service enrollment, exact lenso.system.v2 topology, and its Management Binding through the bundle produced by the connected local command.
Status each Service, Module, Surface, Adapter, and Workload directly.

Production release and deployment stay with external delivery systems. Console does not create, adopt, release, deploy, or repair the connected app.

Modules keep business identity

ModuleManifest is serializable declaration data. It names capabilities, Business API routes, runtime functions, events, lifecycle work, dependencies, and Console Surfaces. Executable handlers stay in either a linked binding or a Service implementation.

Operator UI is a digest-bound console_ui_esm artifact in the same immutable Module Release. Its generated client calls declared operations through Surface Gateway under an exact Surface Grant. Browser code receives neither Service credentials nor direct Store access.

Service capability tiers

Provider and Autonomous Service are different ownership levels, not two names for any out-of-process Module:

Provider keeps compatibility/process metadata in lenso.service.v1, installs exact lenso.module-release.v1 releases, and uses the Host-owned lenso.provider.v1 runtime at /lenso/provider/v1. It supports Rust and TypeScript.
Autonomous Service lenso.service.v2 is Service-owned and Rust only.

Current Rust Autonomous Service capabilities include direct HTTP/gRPC, Event Contracts, Durable Workflows, Workload Identity, Delegated Actor Context, and service-owned storage. TypeScript does not provide Autonomous Service parity.

See Service Capability Tiers for the exact support boundary.

Data Plane and System Plane stay separate

Business calls use declared Module or Service contracts. Autonomous Service traffic goes directly between Services; it does not pass through Console or a Host Provider proxy. Each receiving boundary verifies actor, tenant, deadline, idempotency, identity, and contract policy locally.

Console is the operator-facing System Plane. It validates the exact active enrollment, topology digest, Management Binding, and advertised Core contract before storing a connection. Its browser surfaces use the same-origin Console Service, which keeps target credentials server-side.

Status is object-specific

Every connected object reports one state with a direct reason:

connected: the exact contract and live target agree;
unavailable: the declared target cannot currently be observed;
incompatible: a protocol, contract, release, or artifact does not match;
unmanaged: no current Management Binding covers the object.

An unavailable Local Control Adapter leaves Workload observation unknown and rejects mutation without queueing or fallback. Console does not collapse these states into an app-wide score.

Continue with Host Quickstart for the complete lifecycle or Service System Plane for the mixed-topology connection model.