feat(ql3): establish 3.0 incubation baseline

packages/ql3-cluster-control/README.md

@@ -0,0 +1,80 @@
+# `@qinglong/cluster-control`
+
+This private workspace package is the composition root for the QingLong 3.0
+`cluster-control` profile artifact.
+
+It owns the readiness-first database lifecycle and exposes both the proven
+runtime pool and a public-contract PostgreSQL RunRepository to a caller-supplied
+stack factory. It depends only on public `@qinglong/runtime-core` and
+`@qinglong/cluster-postgres/runtime` exports, so the resident control plane does
+not load executable migration DDL. It must never deep-import the legacy root
+`back/**` tree.
+
+Public subpath exports now separate responsibilities:
+
+- `@qinglong/cluster-control/application` owns the probe listener, activation,
+  admission drain, runtime stack, Pool and listener shutdown order;
+- `@qinglong/cluster-control/availability` provides the one-way, timer-free
+  `ready -> unavailable` fence used by the PostgreSQL Pool error path;
+- `@qinglong/cluster-control/http` provides bounded `/livez`, `/readyz` and
+  fail-closed `/api/v3` admission transport;
+- `@qinglong/cluster-control/config` parses the Profile gate before reading the
+  runtime database credential/API credential pepper and defaults PostgreSQL to
+  verified TLS;
+- `@qinglong/cluster-control/api-credential` validates the versioned `ql3c`
+  bearer format and authenticates a stable subject with a constant-time,
+  peppered digest comparison;
+- `@qinglong/cluster-control/admission` resolves a route, authenticates a stable
+  principal, evaluates Policy and records the security decision before the HTTP
+  adapter is allowed to read the bounded request body;
+- `@qinglong/cluster-control/routes` compiles an immutable, bounded and
+  non-overlapping route table whose operation, permission, Project path
+  parameter and query allowlist are fixed at startup.
+- `@qinglong/cluster-control/run-routes` defines the first reviewed business
+  route: a Project-scoped `run.get` point query that returns only an explicit
+  low-sensitive DTO and masks cross-Project existence.
+- `@qinglong/cluster-control/production` is the only reviewed production route
+  composition, fixes the current allowlist to `run.get` and `run.cancel`, and
+  atomically derives the runtime Pool plus its availability fence from one
+  enabled configuration so deployments cannot miswire those authorities;
+- `@qinglong/cluster-control/s3-artifact-store` is a separately lazy-loaded,
+  cluster-only immutable Artifact adapter; neither the package root nor the
+  production API entrypoint loads the AWS SDK;
+- `@qinglong/cluster-control/worker-ingress` owns the separately gated TLS 1.3
+  mutual-TLS listener and exposes explicit secure-context reload without
+  acquiring database adapter or CA-signing authority;
+- `@qinglong/cluster-control/worker-ingress-config` loads bounded server
+  identity, 1–16 client CA certificates and an optional CRL after the Profile
+  gate, builds only the dedicated Worker HTTP/Pool options, and validates the
+  immutable S3 Artifact binding;
+- `@qinglong/cluster-control/worker-runtime-port` constructs the frozen
+  in-process offer/ACK/Artifact/completion/lease capability boundary without
+  exposing the runtime Pool;
+- `@qinglong/cluster-control/worker-ingress-production` combines that port with
+  the independent Worker credential/Session/attestation/audit Pool.
+
+The cluster assembly now supplies real PostgreSQL API Credential, Project
+Policy and write-only Security Audit repositories, plus a bounded recovery
+candidate source. After the caller's recovery reports safe convergence, the
+bootstrap independently verifies PostgreSQL has no orphaned or expired-lease
+Run/Attempt candidate; a false-safe summary cannot open admission. Admission accepts only a
+route resolver produced by the reviewed registry factory; a caller cannot
+silently replace it with an ad-hoc resolver. The tested vertical path is HTTP
+bearer authentication → fenced Project Policy → durable low-sensitive audit →
+bounded body/handler.
+
+The production application registers the reviewed `run.get` and `run.cancel`
+routes through one static allowlist and, when explicitly enabled, starts the
+independent 5801 mTLS Worker listener after readiness/recovery. Runtime
+Run/Attempt/Lease mutation stays behind the injected capability port;
+`ql3_worker_ingress` receives no such database grant. Artifact S3 support is
+loaded only on that enabled path, so disabled Cluster and all local Profiles do
+not load its provider.
+
+Identity/credential administration remains in the separate short-lived
+cluster-admin authority, and the resident HTTP surfaces retain bounded
+authentication overload shields. Remaining incubation gaps include Cluster
+Secret material provider/rotation, Remote Worker expiry/retry production
+lifecycle, audit retention/export/alerting and real multi-Pod
+operator/proxy/STONITH capacity evidence. The generic admission pipeline must
+not be wired to an allow-all authenticator or Policy in production.