@lssm-tech/module.lssm-os-control-plane 2.1.2

package/README.md

@@ -0,0 +1,220 @@
+# `@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`
+
+## 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.

package/package.json

@@ -0,0 +1,236 @@
+{
+  "name": "@lssm-tech/module.lssm-os-control-plane",
+  "version": "2.1.2",
+  "description": "Tenant-safe application services and scheduling for the LSSM OS control plane.",
+  "type": "module",
+  "license": "MIT",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "package.json"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "publish:pkg:canary": "bun publish:pkg --tag canary",
+    "build": "bun run clean && bun run build:bundle && bun run build:types",
+    "build:bundle": "contractspec-bun-build transpile",
+    "build:types": "contractspec-bun-build types",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun run lint:fix",
+    "lint:fix": "node ../../../scripts/biome.cjs check --write .",
+    "lint:check": "node ../../../scripts/biome.cjs check .",
+    "pack:verify": "bun run build && node ./scripts/verify-pack.mjs",
+    "test": "bun test",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@lssm-tech/lib.builder-spec": "workspace:^",
+    "@lssm-tech/lib.contracts-spec": "workspace:^",
+    "@lssm-tech/lib.crypto-utils": "workspace:^",
+    "@lssm-tech/lib.lssm-os-runtime": "workspace:^",
+    "@lssm-tech/lib.lssm-os-spec": "workspace:^",
+    "@lssm-tech/lib.schema": "workspace:^",
+    "zod": "catalog:",
+    "@lssm-tech/lib.builder-runtime": "workspace:^",
+    "@lssm-tech/lib.contractspec-connect": "workspace:^"
+  },
+  "devDependencies": {
+    "@lssm-tech/tool.bun": "workspace:*",
+    "@lssm-tech/tool.typescript": "workspace:*",
+    "typescript": "catalog:"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./application": "./src/application.ts",
+    "./builder-handoff": "./src/builder-handoff.ts",
+    "./in-memory": "./src/in-memory.ts",
+    "./ports": "./src/ports.ts",
+    "./runtime-node-worker": "./src/runtime-node-worker.ts",
+    "./topology": "./src/topology-controller.ts",
+    "./types": "./src/types.ts",
+    "./worker": "./src/worker.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "browser": "./dist/browser/index.js",
+        "bun": "./dist/index.js",
+        "node": "./dist/node/index.js",
+        "default": "./dist/index.js"
+      },
+      "./application": {
+        "types": "./dist/application.d.ts",
+        "browser": "./dist/browser/application.js",
+        "bun": "./dist/application.js",
+        "node": "./dist/node/application.js",
+        "default": "./dist/application.js"
+      },
+      "./builder-handoff": {
+        "types": "./dist/builder-handoff.d.ts",
+        "browser": "./dist/browser/builder-handoff.js",
+        "bun": "./dist/builder-handoff.js",
+        "node": "./dist/node/builder-handoff.js",
+        "default": "./dist/builder-handoff.js"
+      },
+      "./in-memory": {
+        "types": "./dist/in-memory.d.ts",
+        "browser": "./dist/browser/in-memory.js",
+        "bun": "./dist/in-memory.js",
+        "node": "./dist/node/in-memory.js",
+        "default": "./dist/in-memory.js"
+      },
+      "./ports": {
+        "types": "./dist/ports.d.ts",
+        "browser": "./dist/browser/ports.js",
+        "bun": "./dist/ports.js",
+        "node": "./dist/node/ports.js",
+        "default": "./dist/ports.js"
+      },
+      "./runtime-node-worker": {
+        "types": "./dist/runtime-node-worker.d.ts",
+        "browser": "./dist/browser/runtime-node-worker.js",
+        "bun": "./dist/runtime-node-worker.js",
+        "node": "./dist/node/runtime-node-worker.js",
+        "default": "./dist/runtime-node-worker.js"
+      },
+      "./topology": {
+        "types": "./dist/topology-controller.d.ts",
+        "browser": "./dist/browser/topology-controller.js",
+        "bun": "./dist/topology-controller.js",
+        "node": "./dist/node/topology-controller.js",
+        "default": "./dist/topology-controller.js"
+      },
+      "./types": {
+        "types": "./dist/types.d.ts",
+        "browser": "./dist/browser/types.js",
+        "bun": "./dist/types.js",
+        "node": "./dist/node/types.js",
+        "default": "./dist/types.js"
+      },
+      "./worker": {
+        "types": "./dist/worker.d.ts",
+        "browser": "./dist/browser/worker.js",
+        "bun": "./dist/worker.js",
+        "node": "./dist/node/worker.js",
+        "default": "./dist/worker.js"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lssm-tech/contractspec.git",
+    "directory": "packages/modules/lssm-os-control-plane"
+  },
+  "homepage": "https://contractspec.io",
+  "contractspec": {
+    "catalog": {
+      "family": "solutions",
+      "kind": "module",
+      "status": "active",
+      "adoptionMode": "adoptable",
+      "stability": "experimental",
+      "platforms": [
+        "web",
+        "server"
+      ],
+      "runtimes": [
+        "bun",
+        "node",
+        "browser"
+      ],
+      "entrypoints": [
+        ".",
+        "./application",
+        "./builder-handoff",
+        "./in-memory",
+        "./ports",
+        "./runtime-node-worker",
+        "./types",
+        "./worker"
+      ],
+      "documentation": [
+        {
+          "title": "Module Lssm Os Control Plane documentation",
+          "url": "https://www.npmjs.com/package/%40lssm-tech%2Fmodule.lssm-os-control-plane",
+          "kind": "readme"
+        }
+      ],
+      "examples": [],
+      "replacements": [],
+      "capabilities": [
+        {
+          "id": "package.lssm.tech.module.lssm.os.control.plane",
+          "title": "Module Lssm Os Control Plane",
+          "description": "Tenant-safe application services and scheduling for the LSSM OS control plane.",
+          "status": "active",
+          "useCases": [
+            "Adopt tenant-safe application services and scheduling for the lssm os control plane"
+          ],
+          "aliases": [
+            "module",
+            "lssm",
+            "control",
+            "plane"
+          ],
+          "pythonEquivalents": [],
+          "canonicalImports": [
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/application",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/builder-handoff",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/in-memory",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/ports",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/runtime-node-worker",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/types",
+              "symbols": []
+            },
+            {
+              "from": "@lssm-tech/module.lssm-os-control-plane/worker",
+              "symbols": []
+            }
+          ],
+          "constraints": {
+            "platforms": [
+              "web",
+              "server"
+            ],
+            "runtimes": [
+              "bun",
+              "node",
+              "browser"
+            ],
+            "avoidWhen": [
+              "The @lssm-tech/module.lssm-os-control-plane package constraints do not match the target runtime or platform."
+            ],
+            "requires": [
+              "TypeScript"
+            ]
+          },
+          "alternatives": [],
+          "relationships": [],
+          "resolutionPriority": 50
+        }
+      ]
+    }
+  }
+}