@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/telemetry/testing/conformance.js

@@ -0,0 +1,764 @@
+"use strict";
+// =============================================================================
+// The telemetry slice's conformance suite (PP-4.6)
+// =============================================================================
+//
+// "Conformance suites travel with packages" (docs/specs/platform-packages.md):
+// the slice's invariants used to be enforced by tests that live in the
+// platform repository, so an app that consumed the package stopped being
+// checked. This suite is those invariants as a registered
+// `ConformanceSuite`, run in every app through `runPlatformConformance()`:
+//
+//   1  metric groups       every registered group is well formed, and computes
+//                          against an empty schema with everything `skipped`
+//   2  route permissions   every route declares exactly its permissions
+//   3  doctor read-only    no telemetry Doctor check can write, enqueue or audit
+//   4  no secrets          the connection and config responses never carry a
+//                          stored password
+//   5  queue rule          the app's cron scan covers the slice's cron
+//   6  boot without store  the module boots with no GreptimeDB and every
+//                          dashboard route answers its documented response
+//   9  extensions          the dashboard panels and assistant tools the app
+//                          registered are well formed (ids, names, no clash with
+//                          a platform name), and every group presentation names
+//                          only what its group declares (PP-14.18)
+//   10 facade surface      what an extension receives to read the store is a
+//                          frozen query facade and nothing more: no client, pool
+//                          or store (PP-14.18)
+//
+// EVERYTHING IS DISCOVERED, nothing is a hand-kept list of routes, groups or
+// checks: groups from `metricGroupRegistry`, routes from the Nest metadata of
+// the controllers `TelemetryModule.forRoot` builds, Doctor checks from the
+// providers that inject the `DoctorCheckRegistry`. The expectations below are
+// rules (a permission per route SHAPE) so a new route that matches no rule is
+// itself a finding.
+//
+// Check 7 (web/API permission parity) runs in the web test suite
+// (`apps/web/src/__tests__/config/telemetryParity.test.ts`) and check 8 (infra
+// drift) is `platform-infra sync --check` in CI; checks 9 and 10 are above.
+//
+// Each check is also an exported function over its input, so the package proves
+// it FAILS on a deliberately broken fixture (`test/telemetry/conformance.spec.ts`).
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryConformanceSuite = exports.CONFORMANCE_SECRETS = exports.bootStubApp = exports.TELEMETRY_CRON_FILE = void 0;
+exports.checkMetricGroups = checkMetricGroups;
+exports.checkMetricGroupsOnEmptySchema = checkMetricGroupsOnEmptySchema;
+exports.discoverRoutes = discoverRoutes;
+exports.checkRoutePermissions = checkRoutePermissions;
+exports.discoverDoctorChecks = discoverDoctorChecks;
+exports.checkDoctorReadOnly = checkDoctorReadOnly;
+exports.checkCronCoverage = checkCronCoverage;
+exports.checkNoSecretsInResponses = checkNoSecretsInResponses;
+exports.checkBootsWithoutTelemetry = checkBootsWithoutTelemetry;
+exports.checkRegisteredExtensions = checkRegisteredExtensions;
+exports.checkFacadeSurface = checkFacadeSurface;
+const common_1 = require("@nestjs/common");
+const constants_1 = require("@nestjs/common/constants");
+const config_1 = require("@nestjs/config");
+const core_1 = require("@nestjs/core");
+const telemetry_1 = require("@marinoscar/platform-contract/telemetry");
+const index_1 = require("../../doctor/index");
+const index_2 = require("../../testing/index");
+const telemetry_ai_enabled_guard_1 = require("../assistant/telemetry-ai-enabled.guard");
+const telemetry_connection_test_service_1 = require("../connection/telemetry-connection-test.service");
+const telemetry_dashboard_service_1 = require("../dashboard/telemetry-dashboard.service");
+const ports_1 = require("../ports");
+const telemetry_query_errors_1 = require("../query/telemetry-query.errors");
+const telemetry_permissions_1 = require("../telemetry.permissions");
+const telemetry_module_1 = require("../telemetry.module");
+const metric_group_1 = require("../metrics/metric-group");
+const metric_catalog_helpers_1 = require("../metrics/metric-catalog.helpers");
+const metric_presentation_1 = require("../metrics/metric-presentation");
+const metric_unit_registry_1 = require("../metrics/metric-unit.registry");
+const telemetry_assistant_tool_registry_1 = require("../assistant/telemetry-assistant-tool.registry");
+const dashboard_panels_1 = require("../dashboard/panels/dashboard-panels");
+const telemetry_query_facade_1 = require("../query/telemetry-query-facade");
+const greptime_dialect_1 = require("../stores/greptime/greptime.dialect");
+const telemetry_2 = require("@marinoscar/platform-contract/telemetry");
+const metric_catalog_1 = require("../metrics/metric-catalog");
+const metric_group_registry_1 = require("../metrics/metric-group.registry");
+const stub_ports_1 = require("./stub-ports");
+const FILE_GROUPS = 'metric-groups';
+const FILE_ROUTES = 'routes';
+const FILE_DOCTOR = 'doctor';
+const FILE_CRON = 'cron';
+const FILE_SECRETS = 'no-secrets';
+const FILE_BOOT = 'boot';
+const FILE_EXTENSIONS = 'extensions';
+const FILE_FACADE = 'facade';
+const finding = (file, message) => ({ file, message });
+const lines = (findings) => findings.map((f) => `${f.file}: ${f.message}`);
+// ---- check 1: metric groups ---------------------------------------------------------
+/**
+ * Check 1, static half: every group has a unique id matching
+ * {@link METRIC_GROUP_ID_PATTERN} and a non-empty label; family, ratio and table
+ * keys are unique across groups; every unit is registered (`registerMetricUnit`); every filter
+ * key is a `METRIC_FILTER_COLUMNS` key; every entry names the group that holds it;
+ * a group's presentation names only tiles, charts and tables the group declares.
+ *
+ * @param groups - the groups to check.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkMetricGroups(groups) {
+    const out = [];
+    const filters = new Set(Object.keys(metric_catalog_helpers_1.METRIC_FILTER_COLUMNS));
+    const ids = new Map();
+    const keys = new Map();
+    for (const group of groups) {
+        const where = `group "${group.id}"`;
+        ids.set(group.id, (ids.get(group.id) ?? 0) + 1);
+        if (typeof group.id !== 'string' || !metric_group_registry_1.METRIC_GROUP_ID_PATTERN.test(group.id)) {
+            out.push(finding(FILE_GROUPS, `${where}: id must match ${metric_group_registry_1.METRIC_GROUP_ID_PATTERN}`));
+        }
+        if (typeof group.label !== 'string' || group.label.trim() === '')
+            out.push(finding(FILE_GROUPS, `${where}: label is empty`));
+        const entries = [
+            ...group.families.map((f) => ({ kind: 'family', key: f.key, group: f.group, units: [f.unit], filters: f.filters })),
+            ...(group.ratios ?? []).map((r) => ({ kind: 'ratio', key: r.key, group: r.group, units: [r.unit], filters: [] })),
+            ...(group.tables ?? []).map((t) => ({
+                kind: 'table',
+                key: t.key,
+                group: t.group,
+                units: [...t.parts.map((p) => p.unit), ...(t.derived ?? []).map((d) => d.unit)],
+                filters: t.filters,
+            })),
+        ];
+        for (const entry of entries) {
+            const name = `${where}: ${entry.kind} "${entry.key}"`;
+            const owner = keys.get(entry.key);
+            if (owner !== undefined)
+                out.push(finding(FILE_GROUPS, `${name} key is already used by group "${owner}"; keys are unique across groups`));
+            keys.set(entry.key, group.id);
+            if (entry.group !== group.id)
+                out.push(finding(FILE_GROUPS, `${name} declares group "${entry.group}"`));
+            for (const unit of entry.units) {
+                if (!(0, metric_unit_registry_1.isMetricUnit)(unit))
+                    out.push(finding(FILE_GROUPS, `${name} has unit "${unit}", which is not registered (registerMetricUnit)`));
+            }
+            for (const filter of entry.filters) {
+                if (!filters.has(filter))
+                    out.push(finding(FILE_GROUPS, `${name} has filter "${filter}"; expected one of ${[...filters].join(', ')}`));
+            }
+        }
+    }
+    for (const [id, count] of ids) {
+        if (count > 1)
+            out.push(finding(FILE_GROUPS, `group id "${id}" is declared ${count} times`));
+    }
+    for (const group of groups) {
+        try {
+            (0, metric_presentation_1.assertPresentation)(group);
+        }
+        catch (error) {
+            out.push(finding(FILE_GROUPS, error.message));
+        }
+    }
+    return out;
+}
+/**
+ * Check 1, dynamic half: every group computes against an EMPTY schema (the
+ * store has no metric table) without throwing, reporting everything in
+ * `skipped` and nothing as a tile, series or table. A group that errors, or one
+ * that renders a number out of nothing, would break the dashboard of a fresh stack.
+ *
+ * @param groups - the groups; each must be registered in `metricGroupRegistry` (the computation reads it).
+ * @param compute - what runs one group; default `computeMetricGroup` with an empty schema. A test passes a broken one.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+async function checkMetricGroupsOnEmptySchema(groups, compute = (id) => (0, metric_group_1.computeMetricGroup)({
+    group: id,
+    window: { from: new Date(0), to: new Date(3_600_000), previousFrom: new Date(-3_600_000), bucketSeconds: 60 },
+    filters: {},
+    tables: (0, metric_catalog_1.metricTablesOf)({ tables: [] }),
+    runner: { maybe: async () => null },
+    now: new Date(3_600_000),
+})) {
+    const out = [];
+    for (const group of groups) {
+        const where = `group "${group.id}"`;
+        let result;
+        try {
+            result = await compute(group.id);
+        }
+        catch (error) {
+            out.push(finding(FILE_GROUPS, `${where}: computing against an empty schema threw: ${error.message}`));
+            continue;
+        }
+        if (result.available)
+            out.push(finding(FILE_GROUPS, `${where}: reports available with no metric table in the store`));
+        if (result.tiles.length + result.series.length + result.tables.length > 0) {
+            out.push(finding(FILE_GROUPS, `${where}: renders tiles, series or tables with no metric table in the store`));
+        }
+        const skipped = new Set(result.skipped);
+        const keys = [...group.families.map((f) => f.key), ...(group.ratios ?? []).map((r) => r.key), ...(group.tables ?? []).map((t) => t.key)];
+        for (const key of keys) {
+            if (!skipped.has(key))
+                out.push(finding(FILE_GROUPS, `${where}: "${key}" is not reported in skipped with no metric table in the store`));
+        }
+    }
+    return out;
+}
+const trimSlashes = (value) => value.replace(/^\/+|\/+$/g, '');
+/**
+ * Every route of `controllers`, from `@Controller`/`@Get`/... metadata and the
+ * permissions recorded by the package's test host (`createTestPlatformHost`).
+ *
+ * @param controllers - controller classes, e.g. `TelemetryModule.forRoot(...).controllers`.
+ * @returns the routes, in declaration order.
+ *
+ * @stability experimental
+ */
+function discoverRoutes(controllers) {
+    const routes = [];
+    for (const controller of controllers) {
+        const prefix = trimSlashes(String(Reflect.getMetadata(constants_1.PATH_METADATA, controller) ?? ''));
+        const controllerGuards = Reflect.getMetadata(constants_1.GUARDS_METADATA, controller) ?? [];
+        for (const name of Object.getOwnPropertyNames(controller.prototype)) {
+            const handler = controller.prototype[name];
+            if (typeof handler !== 'function' || !Reflect.hasMetadata(constants_1.METHOD_METADATA, handler))
+                continue;
+            const own = trimSlashes(String(Reflect.getMetadata(constants_1.PATH_METADATA, handler) ?? ''));
+            routes.push({
+                method: common_1.RequestMethod[Reflect.getMetadata(constants_1.METHOD_METADATA, handler)] ?? 'UNKNOWN',
+                path: [prefix, own].filter(Boolean).join('/'),
+                permissions: Reflect.getMetadata(index_2.TEST_REQUIRED_PERMISSIONS_KEY, handler),
+                guards: [...controllerGuards, ...(Reflect.getMetadata(constants_1.GUARDS_METADATA, handler) ?? [])],
+                handler,
+            });
+        }
+    }
+    return routes;
+}
+const { READ, WRITE, QUERY } = telemetry_permissions_1.TELEMETRY_PERMISSIONS;
+const { AI_USE, SYSTEM_SETTINGS_READ, SYSTEM_SETTINGS_WRITE } = telemetry_permissions_1.TELEMETRY_HOST_PERMISSIONS;
+/**
+ * The permissions each route SHAPE must declare. A rule per shape, not per
+ * path: the routes are discovered, and one that matches no rule is a finding.
+ */
+const ROUTE_RULES = [
+    { shape: /^(GET) admin\/telemetry\/(config|status)$/, permissions: [READ] },
+    { shape: /^PUT admin\/telemetry\/config$/, permissions: [WRITE] },
+    { shape: /^(POST) admin\/telemetry\/(query|export)$/, permissions: [QUERY] },
+    { shape: /^GET admin\/telemetry\/schema$/, permissions: [QUERY] },
+    { shape: /^GET admin\/telemetry\/dashboard\/[a-z-]+(\/:[a-z]+)?$/, permissions: [QUERY] },
+    { shape: /^GET admin\/telemetry\/connection$/, permissions: [READ] },
+    { shape: /^(PUT|DELETE) admin\/telemetry\/connection$/, permissions: [WRITE] },
+    { shape: /^POST admin\/telemetry\/connection\/test$/, permissions: [WRITE] },
+    { shape: /^GET admin\/telemetry\/store$/, permissions: [READ] },
+    { shape: /^PUT admin\/telemetry\/store$/, permissions: [WRITE] },
+    { shape: /^GET admin\/telemetry\/stack$/, permissions: [SYSTEM_SETTINGS_READ] },
+    { shape: /^POST admin\/telemetry\/stack\/deploy$/, permissions: [SYSTEM_SETTINGS_WRITE] },
+    { shape: /^POST admin\/telemetry\/assistant\/stream$/, permissions: [QUERY, AI_USE], guard: telemetry_ai_enabled_guard_1.TelemetryAiEnabledGuard },
+    // `@Auth()` only: any signed-in user may ask whether telemetry is on.
+    { shape: /^GET telemetry\/config$/, permissions: [] },
+];
+/** Every permission string the slice may enforce: exactly these, never a variant. */
+const KNOWN_PERMISSIONS = new Set([...Object.values(telemetry_permissions_1.TELEMETRY_PERMISSIONS), ...Object.values(telemetry_permissions_1.TELEMETRY_HOST_PERMISSIONS)]);
+/**
+ * Check 2: every route under `admin/telemetry` and `telemetry` declares exactly
+ * the permissions its shape requires (the table in the slice README, heading
+ * "Permissions and settings"), every permission is one of the slice's exact
+ * strings, no route is public, the assistant route sits behind the AI-enabled
+ * guard, and every rule matches at least one route (a renamed route fails here
+ * rather than silently dropping out of the check).
+ *
+ * @param routes - the routes, from {@link discoverRoutes}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkRoutePermissions(routes) {
+    const out = [];
+    const matched = new Set();
+    for (const route of routes) {
+        const name = `${route.method} /${route.path}`;
+        if (!/^(admin\/)?telemetry(\/|$)/.test(route.path)) {
+            out.push(finding(FILE_ROUTES, `${name}: a route outside admin/telemetry and telemetry in the telemetry module`));
+            continue;
+        }
+        if (route.permissions === undefined) {
+            out.push(finding(FILE_ROUTES, `${name}: declares no access decorator, so it is public`));
+            continue;
+        }
+        for (const permission of route.permissions) {
+            if (!KNOWN_PERMISSIONS.has(permission))
+                out.push(finding(FILE_ROUTES, `${name}: enforces "${permission}", which is not a telemetry permission string`));
+        }
+        const rule = ROUTE_RULES.find((candidate) => candidate.shape.test(`${route.method} ${route.path}`));
+        if (!rule) {
+            out.push(finding(FILE_ROUTES, `${name}: matches no permission rule; add the route's shape to the conformance suite`));
+            continue;
+        }
+        matched.add(rule.shape);
+        const actual = [...route.permissions].sort().join(', ');
+        const expected = [...rule.permissions].sort().join(', ');
+        if (actual !== expected) {
+            out.push(finding(FILE_ROUTES, `${name}: declares [${actual}] but must declare [${expected}]`));
+        }
+        if (rule.guard && !route.guards.includes(rule.guard)) {
+            out.push(finding(FILE_ROUTES, `${name}: is not behind ${rule.guard.name}`));
+        }
+    }
+    for (const rule of ROUTE_RULES) {
+        if (!matched.has(rule.shape))
+            out.push(finding(FILE_ROUTES, `no route matches ${rule.shape}: it was renamed or removed`));
+    }
+    return out;
+}
+// ---- check 3: the Doctor stays read-only --------------------------------------------
+/** Constructor dependencies a Doctor check must never have (classes, and tokens injected with `@Inject`). */
+const FORBIDDEN_DOCTOR_DEPENDENCIES = [
+    { dependency: telemetry_connection_test_service_1.TelemetryConnectionTestService, why: 'the connection test audits every attempt, and a Doctor run must not write' },
+    { dependency: telemetry_dashboard_service_1.TelemetryDashboardService, why: 'its reads are audited' },
+    { dependency: ports_1.TELEMETRY_AUDIT_SINK, why: 'a check records no audit row' },
+    { dependency: ports_1.TELEMETRY_JOBS, why: 'a check enqueues no job' },
+];
+const nameOf = (dependency) => typeof dependency === 'function' ? dependency.name : String(dependency?.description ?? dependency);
+/**
+ * The providers that register themselves as Doctor checks: classes with a
+ * `run` method whose constructor injects the `DoctorCheckRegistry`.
+ *
+ * @param providers - a module's provider list, e.g. `TelemetryModule.forRoot(...).providers`.
+ * @returns the check classes.
+ *
+ * @stability experimental
+ */
+function discoverDoctorChecks(providers) {
+    return providers.filter((provider) => {
+        if (typeof provider !== 'function')
+            return false;
+        const params = Reflect.getMetadata('design:paramtypes', provider) ?? [];
+        return typeof provider.prototype?.run === 'function' && params.includes(index_1.DoctorCheckRegistry);
+    });
+}
+/**
+ * Check 3: no Doctor check of the slice injects the audited connection test,
+ * the audited dashboard service, the audit sink or the jobs port. The check
+ * reads the constructor's `design:paramtypes` and `@Inject` tokens
+ * (`self:paramtypes`).
+ *
+ * @param checks - the check classes, from {@link discoverDoctorChecks}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkDoctorReadOnly(checks) {
+    const out = [];
+    for (const check of checks) {
+        const types = Reflect.getMetadata('design:paramtypes', check) ?? [];
+        const tokens = (Reflect.getMetadata('self:paramtypes', check) ?? []).map((entry) => entry.param);
+        for (const { dependency, why } of FORBIDDEN_DOCTOR_DEPENDENCIES) {
+            if (types.includes(dependency) || tokens.includes(dependency)) {
+                out.push(finding(FILE_DOCTOR, `${check.name} injects ${nameOf(dependency)}: ${why}`));
+            }
+        }
+    }
+    return out;
+}
+// ---- check 5: the queue rule ---------------------------------------------------------
+/**
+ * The slice's cron, relative to its source root.
+ *
+ * @stability experimental
+ */
+exports.TELEMETRY_CRON_FILE = 'tasks/telemetry-retention.task.ts';
+/**
+ * Check 5: the app's `cron-enqueue-only` scan roots hold the slice's retention
+ * cron, so the queue rule ("a `@Cron` only enqueues") is enforced on it. Runs
+ * the cron suite's own scan over `roots` and looks for the file.
+ *
+ * @param roots - the roots the app's cron suite scans.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkCronCoverage(roots) {
+    const report = index_2.cronEnqueueOnlySuite.check({ sourceRoots: roots }, { exempt: [], minCronFiles: 1 });
+    const covered = report.scannedFiles.cronFiles?.some((file) => file === exports.TELEMETRY_CRON_FILE || file.endsWith(`/${exports.TELEMETRY_CRON_FILE}`));
+    return covered
+        ? []
+        : [
+            finding(FILE_CRON, `the cron scan roots do not contain ${exports.TELEMETRY_CRON_FILE}: add the slice's source root (packages/platform-api/src/telemetry) to the cron-enqueue-only sourceRoots`),
+        ];
+}
+/**
+ * Boots `TelemetryModule.forRoot` with the stub ports, the package's test host,
+ * the Doctor module and an `OTEL_ENABLED=false` configuration. Nothing listens
+ * on a port; requests go through Fastify's `inject`.
+ *
+ * @param input - what the stubs and the configuration hold.
+ * @returns the initialised application; the caller closes it.
+ *
+ * @stability experimental
+ */
+const bootStubApp = async (input) => {
+    const host = (0, index_2.createTestPlatformHost)();
+    const { module } = (0, stub_ports_1.createStubTelemetryPorts)(input.ports);
+    // Loaded here, not at the top, so importing this entry needs no Fastify adapter until a check boots the module.
+    const { FastifyAdapter } = require('@nestjs/platform-fastify');
+    let ConformanceAppModule = class ConformanceAppModule {
+    };
+    ConformanceAppModule = __decorate([
+        (0, common_1.Module)({
+            imports: [
+                config_1.ConfigModule.forRoot({
+                    isGlobal: true,
+                    ignoreEnvFile: true,
+                    load: [() => ({ otel: { enabled: false }, ...(input.greptime ? { greptime: input.greptime } : {}) })],
+                }),
+                index_1.DoctorModule.forRoot({ host, supportBundle: false }),
+                telemetry_module_1.TelemetryModule.forRoot({ host, imports: [module], ...(input.store ? { store: input.store } : {}) }),
+            ],
+        })
+    ], ConformanceAppModule);
+    const app = await core_1.NestFactory.create(ConformanceAppModule, new FastifyAdapter(), { logger: false });
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+    return app;
+};
+exports.bootStubApp = bootStubApp;
+/**
+ * The passwords check 4 seeds. Distinctive on purpose: a substring match can
+ * only be the secret.
+ *
+ * @stability experimental
+ */
+exports.CONFORMANCE_SECRETS = {
+    storedReader: 'conformance-stored-reader-secret-7f3a',
+    storedAdmin: 'conformance-stored-admin-secret-91c2',
+    environmentReader: 'conformance-env-reader-secret-5d08',
+    environmentAdmin: 'conformance-env-admin-secret-b64e',
+};
+/**
+ * Check 4: `GET /admin/telemetry/connection`, `/config` and `/store` never carry
+ * a stored password. Boots the module with known passwords in the
+ * credential store (and in the `greptime` deployment default), a stored custom
+ * connection row, and asserts none of the four appears in the serialised
+ * responses. `TELEMETRY_CONNECTION_CARRIES_NO_SECRET` (the contract's
+ * compile-time proof that the connection type has no field able to hold one)
+ * must still be `true`.
+ *
+ * @param createApp - builds the app; default {@link bootStubApp}. A test passes a leaky one.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+async function checkNoSecretsInResponses(createApp = exports.bootStubApp) {
+    const out = [];
+    if (telemetry_1.TELEMETRY_CONNECTION_CARRIES_NO_SECRET !== true) {
+        out.push(finding(FILE_SECRETS, 'TELEMETRY_CONNECTION_CARRIES_NO_SECRET is not true: the connection type can hold a secret'));
+    }
+    const app = await createApp({
+        ports: {
+            credentials: { reader: exports.CONFORMANCE_SECRETS.storedReader, admin: exports.CONFORMANCE_SECRETS.storedAdmin },
+            rows: {
+                telemetry_connection: { host: 'db.conformance.test', pgPort: 4003, database: 'public', readerUser: 'reader', adminUser: 'admin' },
+            },
+        },
+        greptime: {
+            host: 'greptimedb',
+            pgPort: 4003,
+            database: 'public',
+            readerUser: 'reader',
+            readerPassword: exports.CONFORMANCE_SECRETS.environmentReader,
+            adminUser: 'admin',
+            adminPassword: exports.CONFORMANCE_SECRETS.environmentAdmin,
+            available: true,
+        },
+    });
+    try {
+        for (const url of ['/admin/telemetry/connection', '/admin/telemetry/config', '/admin/telemetry/store']) {
+            const response = await app.inject({ method: 'GET', url, headers: { [index_2.TEST_PERMISSIONS_HEADER]: telemetry_permissions_1.TELEMETRY_PERMISSIONS.READ } });
+            if (response.statusCode !== 200) {
+                out.push(finding(FILE_SECRETS, `GET ${url} answered ${response.statusCode}, not 200, so it proves nothing`));
+                continue;
+            }
+            for (const [name, secret] of Object.entries(exports.CONFORMANCE_SECRETS)) {
+                if (response.body.includes(secret))
+                    out.push(finding(FILE_SECRETS, `GET ${url} carries the ${name} password`));
+            }
+        }
+    }
+    finally {
+        await app.close();
+    }
+    return out;
+}
+/** The query parameters a route requires, with a valid value each, from its `@ApiQuery` metadata. */
+function requiredQuery(handler) {
+    const parameters = (Reflect.getMetadata('swagger/apiParameters', handler) ?? []);
+    const query = {};
+    for (const parameter of parameters) {
+        if (parameter.in !== 'query' || !parameter.required)
+            continue;
+        query[parameter.name] = String((parameter.enum ?? parameter.schema?.enum ?? ['x'])[0]);
+    }
+    return query;
+}
+/**
+ * Check 6: `TelemetryModule.forRoot` boots with `OTEL_ENABLED=false`, no
+ * GreptimeDB and an empty configuration, and every dashboard route answers
+ * with its documented response: `200` (a route that reads only memory) or `503`
+ * with `details.reason` `TELEMETRY_NOT_CONFIGURED`. Never a `500`.
+ *
+ * @param createApp - builds the app; default {@link bootStubApp}.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+async function checkBootsWithoutTelemetry(createApp = exports.bootStubApp) {
+    const out = [];
+    let app;
+    try {
+        app = await createApp({});
+    }
+    catch (error) {
+        return [finding(FILE_BOOT, `TelemetryModule.forRoot did not boot without a telemetry store: ${error.message}`)];
+    }
+    try {
+        const controllers = (stubModule().controllers ?? []);
+        const dashboard = controllers.find((controller) => Reflect.getMetadata(constants_1.PATH_METADATA, controller) === 'admin/telemetry/dashboard');
+        const routes = dashboard ? discoverRoutes([dashboard]).filter((route) => route.method === 'GET') : [];
+        if (routes.length === 0)
+            out.push(finding(FILE_BOOT, 'no dashboard route found to exercise'));
+        for (const route of routes) {
+            // A parameterised route (`panels/:id`) is exercised with a panel the platform registers.
+            const url = `/${route.path.replace(/\/:id$/, `/${telemetry_2.DASHBOARD_PANELS[0]}`)}`;
+            const response = await app.inject({
+                method: 'GET',
+                url,
+                query: requiredQuery(route.handler),
+                headers: { [index_2.TEST_PERMISSIONS_HEADER]: telemetry_permissions_1.TELEMETRY_PERMISSIONS.QUERY },
+            });
+            const body = (response.body ? safeJson(response.body) : undefined);
+            const documented = response.statusCode === 200 ||
+                (response.statusCode === 503 && body?.details?.reason === telemetry_query_errors_1.TELEMETRY_ERROR_REASONS.NOT_CONFIGURED);
+            if (!documented) {
+                out.push(finding(FILE_BOOT, `GET ${url} answered ${response.statusCode}${body?.details?.reason ? ` (${body.details.reason})` : ''} with no telemetry store; expected 200 or 503 TELEMETRY_NOT_CONFIGURED`));
+            }
+        }
+    }
+    finally {
+        await app.close();
+    }
+    return out;
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Check 9: the dashboard panels and assistant tools are well formed. A panel
+ * has an id matching the panel pattern, a label, a finite order and a `data`
+ * function, and the platform's `api` and `logs` are still registered (an app
+ * cannot have replaced them). A tool has a name matching the tool pattern that
+ * is not one of the platform's eight, a description, a zod OBJECT schema and a
+ * `run` function. Registration already enforces all of this; the check keeps it
+ * true for a registry filled any other way.
+ *
+ * @param extensions - the registered panels and tools; default the live registries.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkRegisteredExtensions(extensions = {
+    panels: dashboard_panels_1.dashboardPanelRegistry.list(),
+    tools: telemetry_assistant_tool_registry_1.telemetryAssistantToolRegistry.list(),
+}) {
+    const out = [];
+    const panelIds = new Set();
+    for (const panel of extensions.panels) {
+        const where = `dashboard panel "${panel.id}"`;
+        if (!telemetry_2.DASHBOARD_PANEL_ID_PATTERN.test(panel.id))
+            out.push(finding(FILE_EXTENSIONS, `${where}: id must match ${telemetry_2.DASHBOARD_PANEL_ID_PATTERN}`));
+        if (panelIds.has(panel.id))
+            out.push(finding(FILE_EXTENSIONS, `${where}: id is registered twice`));
+        panelIds.add(panel.id);
+        if (typeof panel.label !== 'string' || panel.label.trim() === '')
+            out.push(finding(FILE_EXTENSIONS, `${where}: label is empty`));
+        if (typeof panel.order !== 'number' || !Number.isFinite(panel.order))
+            out.push(finding(FILE_EXTENSIONS, `${where}: order is not a finite number`));
+        if (typeof panel.data !== 'function')
+            out.push(finding(FILE_EXTENSIONS, `${where}: has no data function`));
+    }
+    for (const builtin of telemetry_2.DASHBOARD_PANELS) {
+        if (!panelIds.has(builtin) || !(0, dashboard_panels_1.isBuiltinDashboardPanel)(builtin)) {
+            out.push(finding(FILE_EXTENSIONS, `the platform panel "${builtin}" is not registered`));
+        }
+    }
+    const toolNames = new Set();
+    for (const tool of extensions.tools) {
+        const where = `assistant tool "${tool.name}"`;
+        if (!telemetry_2.TELEMETRY_ASSISTANT_TOOL_NAME_PATTERN.test(tool.name)) {
+            out.push(finding(FILE_EXTENSIONS, `${where}: name must match ${telemetry_2.TELEMETRY_ASSISTANT_TOOL_NAME_PATTERN}`));
+        }
+        if (telemetry_2.BUILTIN_TELEMETRY_ASSISTANT_TOOLS.includes(tool.name)) {
+            out.push(finding(FILE_EXTENSIONS, `${where}: is one of the platform's own tool names`));
+        }
+        if (toolNames.has(tool.name))
+            out.push(finding(FILE_EXTENSIONS, `${where}: name is registered twice`));
+        toolNames.add(tool.name);
+        if (typeof tool.description !== 'string' || tool.description.trim() === '')
+            out.push(finding(FILE_EXTENSIONS, `${where}: description is empty`));
+        if (tool.inputSchema?.type !== 'object') {
+            out.push(finding(FILE_EXTENSIONS, `${where}: inputSchema is not a zod object schema`));
+        }
+        if (typeof tool.run !== 'function')
+            out.push(finding(FILE_EXTENSIONS, `${where}: has no run function`));
+    }
+    return out;
+}
+// ---- check 10: what an extension receives ---------------------------------------------------
+/**
+ * Check 10: the guarded query facade an extension is handed to read the store
+ * has exactly the members `query`, `sql` and `dialect`, is frozen, and exposes
+ * nothing that looks like a client, pool, connection, store or service. Builds
+ * a facade over a stub query service and inspects it.
+ *
+ * @param make - builds the facade to inspect; default `createQueryFacade` over a stub. A test passes a leaky one.
+ * @returns the violations; empty means conformant.
+ *
+ * @stability experimental
+ */
+function checkFacadeSurface(make = () => (0, telemetry_query_facade_1.createQueryFacade)({ run: async () => ({ columns: [], rows: [], rowCount: 0, truncated: false, elapsedMs: 0 }) }, 'conformance', {
+    source: 'panel',
+    dialect: greptime_dialect_1.GREPTIME_SQL_DIALECT,
+})) {
+    const out = [];
+    const facade = make();
+    const keys = Object.keys(facade).sort();
+    if (keys.join(',') !== 'dialect,query,sql') {
+        out.push(finding(FILE_FACADE, `the query facade has members [${keys.join(', ')}]; expected exactly [dialect, query, sql]`));
+    }
+    if (!Object.isFrozen(facade))
+        out.push(finding(FILE_FACADE, 'the query facade is not frozen: an extension could replace its members'));
+    for (const key of keys) {
+        if (/client|pool|conn|store|service|settings|schema|run/i.test(key)) {
+            out.push(finding(FILE_FACADE, `the query facade exposes "${key}", which looks like a client or a service`));
+        }
+    }
+    return out;
+}
+// ---- the suite ------------------------------------------------------------------------
+/** The module the sync checks inspect: the real routes and providers, the package's test host, no ports bound. */
+function stubModule() {
+    return telemetry_module_1.TelemetryModule.forRoot({ host: (0, index_2.createTestPlatformHost)(), imports: [] });
+}
+function check(_context, options) {
+    const module = stubModule();
+    const routes = discoverRoutes((module.controllers ?? []));
+    const doctorChecks = discoverDoctorChecks(module.providers ?? []);
+    const groups = options.metricGroups ?? metric_group_registry_1.metricGroupRegistry.list();
+    return {
+        scanned: {
+            metricGroups: groups.length,
+            routes: routes.length,
+            doctorChecks: doctorChecks.length,
+            dashboardPanels: dashboard_panels_1.dashboardPanelRegistry.list().length,
+            assistantTools: telemetry_assistant_tool_registry_1.telemetryAssistantToolRegistry.list().length,
+        },
+        scannedFiles: {},
+        findings: [
+            ...checkMetricGroups(groups),
+            ...checkRoutePermissions(routes),
+            ...checkDoctorReadOnly(doctorChecks),
+            ...checkRegisteredExtensions(),
+            ...checkFacadeSurface(),
+            ...(options.cronSourceRoots ? checkCronCoverage(options.cronSourceRoots) : []),
+        ],
+    };
+}
+const findingsIn = (report, file) => lines(report.findings.filter((f) => f.file === file));
+function cases(options) {
+    return [
+        {
+            // The failure this guards: the discovery breaks and every case below passes over nothing.
+            name: 'discovers the groups, routes and Doctor checks, so a broken scan cannot pass vacuously',
+            run: (report, expect) => {
+                expect(report.scanned.metricGroups).toBeGreaterThanOrEqual(6);
+                expect(report.scanned.routes).toBeGreaterThanOrEqual(21);
+                expect(report.scanned.doctorChecks).toBeGreaterThanOrEqual(5);
+                expect(report.scanned.dashboardPanels).toBeGreaterThanOrEqual(2);
+            },
+        },
+        {
+            name: '1. every metric group has a unique id, a label, known units and filters, and unique keys',
+            run: (report, expect) => expect(findingsIn(report, FILE_GROUPS)).toEqual([]),
+        },
+        {
+            name: '1. every metric group computes against an empty schema with everything skipped',
+            run: async (_report, expect) => expect(lines(await checkMetricGroupsOnEmptySchema(options.metricGroups ?? metric_group_registry_1.metricGroupRegistry.list()))).toEqual([]),
+        },
+        {
+            name: '2. every route declares exactly its permissions, and none is public',
+            run: (report, expect) => expect(findingsIn(report, FILE_ROUTES)).toEqual([]),
+        },
+        {
+            name: '3. no Doctor check can write, enqueue or audit',
+            run: (report, expect) => expect(findingsIn(report, FILE_DOCTOR)).toEqual([]),
+        },
+        {
+            name: '9. the dashboard panels and assistant tools are well formed, and no tool takes a platform name',
+            run: (report, expect) => expect(findingsIn(report, FILE_EXTENSIONS)).toEqual([]),
+        },
+        {
+            name: '10. an extension reads the store only through the frozen query facade, never a client',
+            run: (report, expect) => expect(findingsIn(report, FILE_FACADE)).toEqual([]),
+        },
+        {
+            name: '4. the connection and config responses never carry a stored password',
+            run: async (_report, expect) => expect(lines(await checkNoSecretsInResponses())).toEqual([]),
+        },
+        ...(options.cronSourceRoots
+            ? [
+                {
+                    name: "5. the app's cron scan covers the telemetry retention cron",
+                    run: (report, expect) => expect(findingsIn(report, FILE_CRON)).toEqual([]),
+                },
+            ]
+            : [
+                {
+                    name: '5. cron coverage: skipped, no cronSourceRoots given',
+                    run: () => undefined,
+                },
+            ]),
+        {
+            name: '6. boots without a telemetry store and every dashboard route answers its documented response',
+            run: async (_report, expect) => expect(lines(await checkBootsWithoutTelemetry())).toEqual([]),
+        },
+    ];
+}
+/**
+ * The suite behind `runPlatformConformance({ suites: { telemetry } })`: the
+ * telemetry slice's invariants 1 to 6 (see this file's header). Registered in
+ * {@link conformanceSuites} when `@marinoscar/platform-api/telemetry/testing`
+ * is imported.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+exports.telemetryConformanceSuite = {
+    id: 'telemetry',
+    title: 'the telemetry slice keeps its invariants',
+    description: 'Metric groups are well formed and degrade to skipped, every route declares exactly its permissions, Doctor checks are read-only, responses carry no secret, the cron is enqueue-only, and the module boots without a store.',
+    check,
+    cases,
+};
+if (!index_2.conformanceSuites.has(exports.telemetryConformanceSuite.id))
+    index_2.conformanceSuites.register(exports.telemetryConformanceSuite);
+//# sourceMappingURL=conformance.js.map