@lssm-tech/module.lssm-os-control-plane
Application-service composition for the LSSM OS control plane.
It coordinates validation, plan compilation, Connect authorization requests, exact-digest apply, work-order scheduling, tenant-safe status projections, Builder handoff receipts, drift, and replay through injected ports. The module does not own policy authority, provider credentials, or provider SDKs.
Public entrypoints
@lssm-tech/module.lssm-os-control-plane@lssm-tech/module.lssm-os-control-plane/application@lssm-tech/module.lssm-os-control-plane/worker@lssm-tech/module.lssm-os-control-plane/builder-handoff@lssm-tech/module.lssm-os-control-plane/ports@lssm-tech/module.lssm-os-control-plane/in-memory@lssm-tech/module.lssm-os-control-plane/runtime-node-worker@lssm-tech/module.lssm-os-control-plane/topology@lssm-tech/module.lssm-os-control-plane/builder-candidate-local
Workspace and published resolution
Development exports resolve the exact public subpaths directly to TypeScript source, so clean-checkout consumers can typecheck before dependency builds.
publishConfig.exports retains the compiled Bun, Node, browser, and declaration paths. The pack verifier applies that projection only in disposable staging; never copy the published export map into the workspace manifest.
Runtime Node V2 worker
LssmOsRuntimeNodeWorkerV2 composes the signed Runtime Node V2 contracts into one fail-closed executable loop. It verifies the exact Connect-issued work order, delegates signed eligibility authority to the injected durable claim port, resumes only an exact ordered durable receipt prefix, routes each step to the exact qualified provider binding, and completes from the authoritative receipt/evidence set.
Every injected asynchronous operation shares one absolute monotonic deadline. Provider, receipt, or completion outcomes that cannot be proven are returned as
indeterminate; the worker never fabricates a failed or successful terminal receipt after an unresolved provider effect. Provider adapters, Connect verification, trusted time, durable work-order state, and durable receipt state remain injected ports. No provider SDK or credential material enters this module.
The V1 LssmOsControlPlaneWorker remains available unchanged. Adopters opt in to the V2 worker through the dedicated subpath and must provide the authoritative Runtime Node ports from @lssm-tech/lib.lssm-os-runtime.
Governed topology controller
LssmOsTopologyControllerV1 evaluates an exact active topology, signed scale policy, and current capacity observation through injected ports. It initializes an observed transition durably, advances non-effect lifecycle evidence with exact-state CAS, requires fresh Connect and V3 operation verification before creating authorized evidence, and delegates at most one observable step to Runtime Node V3. Generic callers cannot promote simulated state into an authority-bearing state. Rejected, blocked, indeterminate, and manual-custody evidence is admitted only when an injected verifier returns the exact closed receipt. Verifier denial, throw, timeout, or substitution leaves durable topology state unchanged. The controller never mints a Connect decision, work order, claim, fence, or provider receipt. If an effect succeeds but its topology receipt cannot be confirmed durably, the controller first CAS-transitions the exact V3 operation into durable indeterminate custody with the receipt ref. Failure to obtain that custody is reported separately and is never described as durable.
proposeScaleTransition is the governed bridge from evaluation to transition admission. It re-evaluates the active topology and observation, enforces the signed replica, budget, quota, freeze, direction, and reversible-transition bounds, binds the exact decision and observation digests to a semantically valid transition plan, and admits only one observed transition through the topology state port. It does not authorize or execute the plan; those steps still require fresh Connect verification and Runtime Node V3 operation, claim, attempt, and fence authority.
createDeterministicScalePlannerV1 is the reference policy evaluator behind that port. It owns dependency output graphs, accepts one exact stable and fresh capacity window, applies hysteresis, cooldown, freeze mode, replica, provider quota, tenant concurrency, drain, backlog, and daily-cost bounds, and invokes an injected exact policy verifier before history or target resolution. It asks the target resolver only for an already-qualified reversible topology digest. A changing decision is recorded through an injected durable
recordIfLatest history CAS before it is returned; concurrent controllers either receive that exact replay or fail closed. The planner does not provision, sign policy, mint Runtime Node authority, or treat a scale decision as execution permission.
recordObservedProfileTransition additionally verifies the complete T0–T3 recipe before admission. Cache and broker promotion/removal must match the exact source and target topology profiles, preserve the authoritative SQL component, tenant scope, residency, classification, and encryption policy, and change only the declared cache or queue role. Same-kind vertical and horizontal plans retain this profile binding. This makes database-only fallback an exact governed recipe instead of an environment-driven transport switch.
T0↔T1 moves use explicit promote_state_backend or demote_state_backend
plans. Those plans must replace both the SQLite/in-process authority and queue roles with their PostgreSQL counterparts (or the exact reverse), preserve the data policy and scope, and declare the full migration, drain, rollback, and decommission lifecycle. Other transition classes continue to reject any authority-store substitution.
Queue admission authority
Authorization and scheduling validate the exact externally verified decision, verdict, source-plan digest, tenant/workspace/environment, and current desired and observed revisions before enqueueing. Time is read again after verification and state reads, so expiry during those reads blocks admission. Authorization requests also bind the returned decision to the requested actor. Workers retain their independent pre-effect validation; queue admission does not replace execution fencing or atomic provider custody.
Reference work-order ownership
The in-memory queue snapshots admissions and returned records. Exact admission retries preserve the existing lifecycle; changed plan, authorization, execution, idempotency or retry-limit bindings are rejected. Scope tuples are encoded without delimiter ambiguity. Completion/retry requires an active fenced claim, and exhausted orders cannot be claimed again. This adapter remains a local reference, not a persistent production queue.
Legacy worker outcome custody
The legacy worker completes every explicit terminal executor result, including failure. A thrown apply call or nonterminal return is recorded as indeterminate and is not automatically retried: an external effect may have occurred before an acknowledgement was lost. Resolve that evidence through the runtime reconciliation path before admitting new work. Queue completion errors propagate to the host.
Builder handoff interoperability
Handoff verification reuses Builder's canonical payload digest, excluding the derived packet ID and digest field. Real Builder-produced packets can enter review without translation. The original LSSM OS id-inclusive sha256: digest remains readable after exact recomputation for compatibility; new helper output uses Builder's format. Both paths require the expected digest and plan match. Acceptance remains plan-only and never grants apply authority.
Canonical packet IDs are recomputed from the same payload before review acceptance, so changing only the packet ID cannot redirect an otherwise valid handoff.
Builder Runtime Node execution loads a digest-bound patch payload, matches tenant/workspace/environment and delivery plan, and delegates to the existing governed patch service only within the injected active-claim callback. It does not mint work orders or permits. Runtime coordinator fencing and the provider lifecycle receipt adapter remain required before live activation.
The apply-only Builder provider adapter keeps patch generation and receipt persistence/verification within the active claim callback. Returned Runtime Node receipts must match the execution and reference the candidate ID, patch hash and head revision. Compensation/observation remain explicitly unqualified. Durable receipt storage and actual claim fencing remain host ports.
Builder Runtime Node receipt persistence now adapts the existing scoped RuntimeWorkOrderReceiptPort. It binds candidate ID/hash/head to the execution, requires append plus readback, and returns the original receipt for an identical step replay. A changed candidate under the same step is a conflict. Tests use a store fixture; production SQL durability and active-claim integration still need qualification. Candidate creation success does not mean release approval.
The Builder receipt writer is tested against the existing file-backed SQLite Runtime Node order/receipt ports: the database is closed and reopened, identical replay returns one receipt, changed candidates conflict, and cross-tenant lookup is empty. Authority-verifier callbacks remain test fixtures; this validates SQL persistence/replay, not production authority or distributed execution fencing.
The Builder provider checks for an existing exact-step receipt inside the active claim before invoking patch generation. Verified replay returns that receipt without generating a second candidate. Read/verification failures stop execution; they are not treated as an absent receipt. Payload and scope admission still run before replay. This relies on host claim fencing for concurrent execution safety.
Worker retries receiving already_claimed can reconcile durable terminal receipts and finish an unconfirmed completion write, but cannot execute missing provider steps. Those return active_claim_requires_reconciliation. This prevents duplicate active worker effects; it does not prove that an expired executor has stopped.
The root barrel now exports createBuilderRuntimeProvider, its configuration types, BuilderRuntimePatchPayload, and createBuilderRuntimeReceiptWriter. The existing active-claim coordinator and durable receipt contracts remain mandatory; additive discoverability does not supply production implementations.
createBuilderProviderReceipt is an additive data-construction export shared by V2 and V3 receipt persistence. Its digest is not an authorization or proof of storage. Hosts must use the appropriate durable authority owner and verify persisted readback before treating the constructed receipt as evidence.
Builder candidate host
BuilderCandidateHost implements the existing Builder candidate service with canonical operation state, Connect V3 issuance, restart-safe issued-order reads, and Durable Queue V2 admission. Configure current member/project resolution and immutable profile/lifecycle material; browser request IDs are correlation only. Prepare records the accepted operation. Approve persists the signed standard and cleanup lifecycle with its budget reservations. Execute separately verifies admission authority, advances the operation by CAS and admits the exact envelope. Interrupted queue admission can resume; it is not pristine co-atomic admission.
Successful candidate output requires a digest-valid terminal receipt linked to the persisted provider receipt and verified retained patch/bundle bytes. Queue status reads recheck exact admission evidence. Missing, stale, conflicting or unavailable evidence never becomes a successful candidate or release. Agent Host owns provider effects and stricter dispatch verification. Installation still requires concrete durable stores, qualified profiles, signing keys and current policy; there is no default authority or model.
Candidate payloads may bind their reviewed Builder plan through builderPlanRef. That signed payload field is checked against the Runtime Node plan digest while Connect plan-packet, delivery-plan and quality-plan references retain their own identities. Legacy payloads without builderPlanRef retain the original delivery- plan digest check. Changing the new reference changes the signed payload digest; it cannot substitute another plan under an existing work order.
Builder provider receipts now report failed when the canonical patch risk assessment contains required_check_failed. Successful generation and retained patch bytes cannot override a failed required QA gate. Other review-required risk reasons remain review outcomes; they do not silently authorize release. Historical immutable receipts are not rewritten. A replay whose recomputed result conflicts with existing evidence must reconcile rather than replace it.
./builder-candidate-local supplies the local-owner BuilderCandidateHost
targets. createBuilderLocalTargets re-resolves the server project profile (plan, member, binding, path, revision and bound checks) before and after the injected issuance-store read and derives deterministic operation, order, claim, lease, step and budget-reservation identities, standard and emergency-cleanup order drafts and the Connect pre-mutation request. builderLocalAdmission
rejects substituted payloads and rebuilds the exact Durable Queue V2 envelope and outbox reference from the issued order. Configuration is narrowed to
BuilderCandidateLocalPlanningConfiguration (clock, queue binding/profile/ requirements, project resolver); hosts keep storage, migrations and keys.
Builder handoff acceptance consumes the lower LSSM-OS metadata-only planning protocol. Published handoff functions, digest compatibility, receipt status and Connect authority checks remain unchanged. Governed patch execution still belongs to its existing Builder owner.
Canonical ownership and compatibility
The existing module identity and all nine published entry maps remain at packages/domains/builder/control-plane. Builder candidate orchestration, Connect binding, governed patch inputs and durable full receipts stay canonical here. Generic scheduling, state ports, workers, topology orchestration and plan-only handoff acceptance are canonical in @lssm-tech/lib.lssm-os-runtime/control-plane; the original module entries forward to those same functions and classes. This does not narrow targets.resolve or BuilderRuntimePatchPayload.input, change policy, or introduce a platform-to-domain exception.
The original inventory row remains one package. Packed declaration compatibility, source checking and affected-consumer qualification remain mandatory. No runtime authority is created by the move.
