Skip to content

Engineering and QA Consoles

  • Owner: NS5-010
  • Evidence: native source/mock and isolated local MySQL PASS; authenticated browser/target-role acceptance pending
  • Placement: existing Admin Setting page, separate Engineering and QA tabs
  • Visual authority: DESIGN and UI Foundation

Purpose and boundary

Inspect the current Web runtime through two finite read-only diagnostics. This is not a SQL console, a cross-environment control plane, a tenant-data viewer, a readiness dashboard or a QA fixture tool. The initial allowlist reuses existing runtime owners and adds no query, mutation or service runner.

The environment selector contains exactly the validated webRuntimeConfig().environment of the runtime serving this request. It does not register remote endpoints, infer an environment from the browser hostname, or offer a Production target while connected to QA. No environment configuration is changed by this source delivery. Additional environments or diagnostics require explicit scope.

Access

Both catalog and diagnostic GET requests resolve the existing Foundation session. Access requires accessMode = SYSTEM, roleState = RESOLVED and an explicit saved platform.engineering.diagnostics.read capability. Existing Admin, tenant, role and configuration permissions do not imply this capability. DIRECT and IMPERSONATION sessions cannot use this platform-runtime console even if a matching string is supplied.

The existing policy capability enumeration recognizes the new key; existing saved-capability resolution remains the authority. No role, user, tenant, grant, session resolver or schema is changed or seeded. An appropriately authorized SYSTEM account must receive the persisted grant through a separately authorized account-management operation before live use. Grant provisioning and actual account acceptance have not been executed here. The tab's client visibility check is not authorization.

Normal flow

Open Setting with an explicitly authorized account and select Engineering. The console reads the catalog, but does not automatically run a diagnostic. Select the current environment and a diagnostic, then choose Run diagnostic. The result displays the observed environment, observation time, allowlisted values and READ_ONLY effect. The tenant-selection control is not shown in this tab; existing selections and all other Admin workflows remain intact.

Diagnostic Existing owner Allowed output
runtime.identity apps/web/src/bootstrap/runtimeConfig.ts service, releaseId
runtime.lifecycle apps/web/src/bootstrap/lifecycle.ts boolean accepting

accepting = false is a successful observation, not a failed request. Neither true nor false proves DB readiness, migration compatibility, external reachability or a successful deployment.

HTTP contract

GET /api/engineering/diagnostics returns { data: { environments, diagnostics, effectState } }. The catalog contains one environment and the two fixed IDs above. To run a read, supply exactly one environment and one diagnosticId query parameter. Duplicate, extra, unknown, oversized or missing parameters are rejected; SQL, tenant identifiers, URLs and command bodies are not accepted.

A successful read returns { data: { environment, diagnosticId, effectState: "READ_ONLY", executionState: "SUCCEEDED", observedAt, output } }. Output is projected from known fields before passing through the existing observability redactor, then projected again at the UI boundary. Raw configuration, credentials, session objects, arbitrary exception text and unknown output fields are not serialized. All returned metadata is bounded; this is field omission plus the existing key redactor, not a claim to detect secrets deliberately stored inside approved metadata values.

Responses are no-store, vary by Cookie and carry a validated/generated correlation UUID. Only GET is exported. Existing routing supplies unsupported-method handling; no mutation method is introduced. Errors contain fixed codes/messages: 401 unauthenticated, 403 Engineering access denied, 400 invalid selection or environment mismatch, 503 session/diagnostic unavailable. The helper returns 499 for an already-cancelled authorized read. Actual local Next routing rejects unauthenticated reads with 401; authenticated routing remains unaccepted.

Recovery and lifecycle

Refresh environments rereads the current catalog and clears old results. Changing selection or closing the tab aborts the outstanding request and invalidates its generation; late success and failure callbacks cannot update a newer view. Each console instance has independent cancellation. A ten-second client timeout reports a read failure; Cancel read stops waiting and clears the result. Neither action cancels a business transaction because none was requested. A failed read is safe to retry. Authentication/authorization failure removes the catalog/tools from the current view.

The client uses the existing base-path-aware, same-origin requestData transport and shared SelectField, TextField and Button owners. No page-local CSS, HTML injection or replacement Admin framework is introduced. Browser rendering, keyboard behavior and real response timing remain unaccepted until executed in the configured workspace.

Access logging and effects

The handler emits fixed allow/deny outcomes, correlation UUID and authenticated actor/tenant UUIDs through the existing structured logger. Query text, output and exception text are not logged by this handler. This is best-effort operational telemetry, not a durable security audit receipt. A logger failure does not change the read result. Phase A adds no DB/data writer, provider call, fixture loader, service operation, release, production exposure or role/grant mutation. Existing session resolution retains its existing behavior; read-only here describes the diagnostic effect, not a new promise about internals of the existing authentication infrastructure.

Verification and remaining acceptance

The focused regressions exercise actual policy/redaction and handler functions with synthetic session/runtime inputs, strict projection, both lifecycle values, invalid requests, read cancellation and source wiring. Source/mock PASS does not establish target-role, DB, browser, durable audit or Production behavior. Exact executed tooling and remaining native acceptance are recorded only in NS5-010. Phase B uses the separate QA contract below.

QA fixtures — existing database, isolated test tenant

The owner selected separate the test data inside the existing DB. QA uses the existing database and a dedicated synthetic test tenant. No separate schema, generic SQL console, provider operation or remote target is added. Entry requires a DIRECT session with saved platform.qa.fixtures.manage, a local/qa Web runtime and exactly one active tenant-scoped QA_FIXTURE_NAMESPACE operation event. SYSTEM, IMPERSONATION, Production and unmarked tenants are denied by the server before fixture writes.

An authorized provisioning operation must create the dedicated test tenant and its namespace event with {version:1,revision:0,companyUuids:[]}. This console cannot provision markers, users or grants; adding a grant to an ordinary tenant does not enable QA data mutation. The marker is trusted server configuration and must never be provisioned on a business tenant. Temporary account/grant approval and authenticated acceptance remain pending in the owning Task.

QA-only grants expose Setting without adding ordinary Admin permissions. The QA tab appears after server access confirmation; checking/failure states provide retry, and a successful first check opens QA for a QA-only account. Scope changes discard availability. Engineering remains SYSTEM-only and separate from the fixture writer. Client visibility never replaces server authorization.

Dataset and actions

companies-v1 contains two synthetic Company records: QA sample supplier and QA sample customer. The existing Company transaction owner creates them with UUID-based unique legal names and the stable display labels above, reads them back and soft-deletes them. This preserves the legacy unique name constraint across clear/reload cycles. There are no customer rows in this dataset.

  • Check current state reads only the namespace's recorded UUIDs in the authenticated tenant and checks the expected sample names/count. It cannot list another tenant's data.
  • Load samples confirms intent, then creates the two records when the namespace is empty.
  • Clear samples confirms intent, then soft-deletes only the UUIDs recorded by that namespace. It does not purge the tenant or other Company rows. Repeated cycles retain historical soft-deleted records under existing Company retention semantics; this is not a physical database reset tool.

Each write carries only action, UUID operationId and expectedRevision. The existing transaction owner atomically claims the namespace via compare-and-set, invokes Company owners and records a QA_FIXTURE_APPLIED event with actor UUID/action/revision. A repeat of the most recent operation returns authoritative state without another write; stale or competing revisions return conflict. The browser must read current state after an unknown result before offering another mutation. No automatic write retry is performed. CAS protects competing requests to the same namespace.

HTTP, confirmation and recovery

GET /api/qa/fixtures returns {data:{dataset,revision,operationId,loaded,valid,companies}}. POST accepts exactly the three command fields above, verifies same-origin mutation provenance and uses the session's tenant/user UUIDs. Caller-supplied tenant, schema, environment, SQL, URL or extra query/body fields are rejected. Errors use fixed codes/messages; responses are no-store. Existing structured access telemetry never includes raw inputs, SQL or exceptions. The transaction event is the durable write receipt; telemetry failure cannot turn committed success into a failed response.

Shared Button/DataTable and the existing Admin confirmation provide loading, empty, invalid-data, error and busy states. Human confirmation has its own lifetime; only the subsequent network request has a ten-second deadline. Closing the console cancels pending reads/confirmation and suppresses late callbacks. A timeout or failed POST hides stale state and offers Check current state. It does not claim to roll back a request which the server may already have committed.

The actual local MySQL acceptance creates two disposable tenants, verifies load/clear/replay/stale revision/concurrent commands, denies the unmarked tenant, compares its sentinel, and removes all run-owned Company/email/event/tenant rows in finally with zero-row readback. It does not create accounts or change existing grants. Native route/component tests and DB acceptance do not substitute for authenticated browser, keyboard, visual or real saved-role proof.

Source: new-system/docs/pages/ENGINEERING_CONSOLE.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.