@uptimizr/collector-server 2.0.1 → 2.2.0

package/dist/routes/context.js

@@ -0,0 +1,306 @@
+/**
+ * The project **context document** — `GET /api/v1/context` (ADR 0051 §5, design
+ * sketch §E.1).
+ *
+ * Agents start blind. They know the *shape* of the read surface from the metric
+ * registry, but nothing about the project in front of them: what its scenes are
+ * called, which regions have names, which capture channels are even on, what the
+ * application calls its own events, whether raw retention is enabled, or how
+ * fresh the data is. Every one of those is a guess an agent would otherwise make
+ * badly — asking for `scene=lobby` when the scene is `main-hall`, reporting a
+ * zero from a disabled channel as a finding, filtering on a custom event name
+ * that does not exist.
+ *
+ * This route answers all of it in one read, assembled entirely from aggregates
+ * and registry rows the collector already serves. It is:
+ *
+ * - **bounded** — every list is capped (see the `MAX_*` constants), so the whole
+ *   document stays comfortably inside the budget a small local model can carry
+ *   in its system prompt; `context.test.ts` asserts the fixture project's
+ *   document is under 16 KB;
+ * - **cached** — briefly, per project ({@link CONTEXT_CACHE_TTL_MS}), because an
+ *   assistant re-reads it on every session start and it costs half a dozen
+ *   aggregate queries to build;
+ * - **read-only and aggregate-only** — no raw event, no session id, no prop
+ *   value, nothing a caller could not already read through the query API
+ *   (ADR 0003).
+ *
+ * It is deliberately **not** a registry metric: it is not an aggregation over
+ * the event stream with a row grain, it is a description of the project. It is
+ * described in the OpenAPI document by hand, alongside the other non-metric
+ * routes (`routes/meta.ts`).
+ */
+import { z } from "zod";
+import { EVENT_TYPES, SCHEMA_VERSION } from "@uptimizr/schema";
+import { allMetrics } from "@uptimizr/metrics";
+import { requireCapability } from "../auth.js";
+import { COLLECTOR_VERSION } from "../version.js";
+import { EMPTY_PROJECT_METADATA } from "../projectMetadata.js";
+/** How long a built document is reused for the same project. */
+export const CONTEXT_CACHE_TTL_MS = 30_000;
+/** The activity window the vocabulary, scenes and channels are computed over. */
+const CONTEXT_WINDOW_MS = 28 * 24 * 60 * 60 * 1000;
+/** The freshness window `dataQuality` reports. */
+const RECENT_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** Caps that keep the document bounded whatever the project contains. */
+const MAX_SCENES = 40;
+const MAX_REGIONS_PER_SCENE = 20;
+const MAX_CUSTOM_EVENTS = 25;
+const MAX_TOP_MESHES = 10;
+/** Distinct meshes counted before `vocabulary.meshes.count` saturates. */
+const MAX_COUNTED_MESHES = 200;
+const MAX_INPUT_ACTIONS = 25;
+const MAX_ANNOTATIONS = 10;
+const MAX_GLOSSARY = 50;
+/** One named region of a scene: the vocabulary a `region=` filter resolves against. */
+const regionSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+});
+const sceneSchema = z.object({
+    /** Developer-assigned scene id (ADR 0010) — the value of the `scene` filter. */
+    id: z.string(),
+    /** Display label from the scene registry, when one was registered. */
+    label: z.string().nullable(),
+    /** Named regions declared for this scene (ADR 0051 §2). */
+    regions: z.array(regionSchema),
+    /** Whether proxy geometry is registered, so spatial results can be labelled. */
+    proxy: z.boolean(),
+    /**
+     * Events recorded in this scene over the context window.
+     *
+     * The design sketch asks for `sessions28d`; no aggregation reports distinct
+     * sessions per scene, and inventing one is outside this change. Event volume
+     * is the honest, already-served stand-in and is named for what it is.
+     */
+    events28d: z.number().int(),
+});
+const captureChannelSchema = z.object({
+    /** Whether any event of this type was recorded over the context window. */
+    seen: z.boolean(),
+    /** Events of this type over the context window. Omitted when none were seen. */
+    events28d: z.number().int().optional(),
+});
+const customEventSchema = z.object({
+    name: z.string(),
+    count28d: z.number().int(),
+    sessions28d: z.number().int(),
+    /** Observed `props` keys mapped to a coarse type. Never prop *values*. */
+    props: z.record(z.string(), z.string()),
+});
+const glossarySchema = z.object({ term: z.string(), meaning: z.string() });
+const annotationSchema = z.object({
+    id: z.string(),
+    target: z.object({ kind: z.string(), id: z.string().nullable() }),
+    text: z.string(),
+    at: z.number().int(),
+});
+/**
+ * The context document. Declared as Zod so it validates on the way out like
+ * every other response, and so the OpenAPI description in `meta.ts` and this
+ * shape cannot drift apart silently.
+ */
+export const projectContextSchema = z.object({
+    /** Identity of the project and of the software serving it. */
+    project: z.object({
+        id: z.string(),
+        /** Storage engine behind this collector (`duckdb`, `clickhouse`, …). */
+        store: z.string(),
+        /** Event wire-format version (`@uptimizr/schema`). */
+        schemaVersion: z.string(),
+        /** Version of the running collector, or `unknown`. */
+        collectorVersion: z.string(),
+    }),
+    /** How fresh and how busy the project is — read this before quoting a zero. */
+    dataQuality: z.object({
+        /** Most recent event, epoch ms, or `null` when the project has no data. */
+        lastEventAt: z.number().int().nullable(),
+        sessions24h: z.number().int(),
+        events24h: z.number().int(),
+        retention: z.object({
+            /**
+             * Whether raw per-session event retention is enabled (ADR 0003). When
+             * `false` the session timeline / replay endpoint returns nothing — that is
+             * configuration, not missing data.
+             */
+            rawSessions: z.boolean(),
+        }),
+    }),
+    /** Which capture channels (ADR 0012) this project actually produces. */
+    capture: z.object({
+        channels: z.record(z.string(), captureChannelSchema),
+    }),
+    scenes: z.array(sceneSchema),
+    vocabulary: z.object({
+        customEvents: z.array(customEventSchema),
+        meshes: z.object({
+            /** Distinct interacted meshes observed, saturating at 200. */
+            count: z.number().int(),
+            /** The busiest mesh names, most-interacted first. */
+            top: z.array(z.string()),
+        }),
+        /** Developer-bound input action labels (#75, ADR 0023). */
+        inputActions: z.array(z.string()),
+    }),
+    definitions: z.object({
+        /** Saved funnel definitions. Always empty: funnels are caller-authored (ADR 0038). */
+        funnels: z.array(z.unknown()),
+        /** Saved segment definitions. Always empty until the metadata write path exists. */
+        segments: z.array(z.unknown()),
+        glossary: z.array(glossarySchema),
+    }),
+    annotations: z.object({
+        recent: z.array(annotationSchema),
+    }),
+    metrics: z.object({
+        /** Registry ids this collector serves. */
+        available: z.array(z.string()),
+        /**
+         * Metrics whose every capture channel was unseen over the window — they will
+         * return empty, and that is a capture setting rather than a finding.
+         */
+        disabledByCapture: z.array(z.string()),
+    }),
+    /** The window the 28-day figures were computed over, epoch ms. */
+    window: z.object({ since: z.number().int(), until: z.number().int() }),
+    /** When this document was built, epoch ms. Respect the cache TTL. */
+    generatedAt: z.number().int(),
+});
+/** Parse an engine-formatted timestamp into epoch ms, or `null`. */
+function toEpochMs(value) {
+    if (value == null)
+        return null;
+    const parsed = Date.parse(value.includes("T") ? value : value.replace(" ", "T") + "Z");
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * Build the document for one project. Pure orchestration over the store: every
+ * figure comes from an aggregate the collector already serves, so there is no
+ * new SQL here beyond the custom-event vocabulary.
+ */
+async function buildContext(store, config, metadata, projectId, now) {
+    const since = now - CONTEXT_WINDOW_MS;
+    const window = { since, until: now };
+    const recent = { since: now - RECENT_WINDOW_MS, until: now };
+    const [channelCounts, recentChannelCounts, recentSessions, sceneRows, representations, regionRows, customEvents, meshRows, inputActionRows, glossary, annotations,] = await Promise.all([
+        store.eventTypeCounts(projectId, window),
+        store.eventTypeCounts(projectId, recent),
+        store.listSessions(projectId, { ...recent, limit: 1000 }),
+        store.scenes(projectId, { ...window, limit: MAX_SCENES }),
+        store.listSceneRepresentations(projectId),
+        store.listSceneRegions(projectId),
+        store.customEventVocabulary(projectId, { ...window, limit: MAX_CUSTOM_EVENTS }),
+        store.topMeshes(projectId, { ...window, limit: MAX_COUNTED_MESHES }),
+        store.topInputActions(projectId, { ...window, limit: MAX_INPUT_ACTIONS }),
+        metadata.glossary(projectId),
+        metadata.recentAnnotations(projectId, MAX_ANNOTATIONS),
+    ]);
+    const countByType = new Map(channelCounts.map((row) => [row.event_type, row.count]));
+    const channels = {};
+    for (const type of EVENT_TYPES) {
+        const events = countByType.get(type) ?? 0;
+        channels[type] = events > 0 ? { seen: true, events28d: events } : { seen: false };
+    }
+    const labelByScene = new Map(representations.map((rep) => [rep.sceneId, rep.label]));
+    const proxyScenes = new Set(representations.map((rep) => rep.sceneId));
+    const regionsByScene = new Map();
+    for (const region of regionRows) {
+        const list = regionsByScene.get(region.sceneId) ?? [];
+        if (list.length >= MAX_REGIONS_PER_SCENE)
+            continue;
+        list.push({ id: region.regionId, label: region.label });
+        regionsByScene.set(region.sceneId, list);
+    }
+    const scenes = sceneRows.map((row) => ({
+        id: row.scene_id,
+        label: labelByScene.get(row.scene_id) ?? null,
+        regions: regionsByScene.get(row.scene_id) ?? [],
+        proxy: proxyScenes.has(row.scene_id),
+        events28d: row.events,
+    }));
+    const lastEventAt = sceneRows.reduce((latest, row) => {
+        const seen = toEpochMs(row.last_seen);
+        return seen != null && (latest == null || seen > latest) ? seen : latest;
+    }, null);
+    // A metric is "disabled by capture" when it declares source channels and NONE
+    // of them produced an event over the window. Derived rollups declare no
+    // channels and are never reported as disabled.
+    const served = allMetrics().filter((metric) => metric.endpoint != null);
+    const seen = (type) => (countByType.get(type) ?? 0) > 0;
+    const disabledByCapture = served
+        .filter((metric) => metric.sourceChannels.length > 0 && !metric.sourceChannels.some((c) => seen(c)))
+        .map((metric) => metric.id);
+    return {
+        project: {
+            id: projectId,
+            store: store.engine,
+            schemaVersion: SCHEMA_VERSION,
+            collectorVersion: COLLECTOR_VERSION,
+        },
+        dataQuality: {
+            lastEventAt,
+            sessions24h: recentSessions.length,
+            events24h: recentChannelCounts.reduce((total, row) => total + row.count, 0),
+            retention: { rawSessions: config.enableRawSessionRetention },
+        },
+        capture: { channels },
+        scenes,
+        vocabulary: {
+            customEvents: customEvents.map((row) => ({
+                name: row.name,
+                count28d: row.count,
+                sessions28d: row.sessions,
+                props: row.props,
+            })),
+            meshes: {
+                count: meshRows.length,
+                top: meshRows.slice(0, MAX_TOP_MESHES).map((row) => row.mesh),
+            },
+            inputActions: [...new Set(inputActionRows.map((row) => row.action))].slice(0, MAX_INPUT_ACTIONS),
+        },
+        definitions: {
+            funnels: [],
+            segments: [],
+            glossary: glossary.slice(0, MAX_GLOSSARY).map((entry) => ({ ...entry })),
+        },
+        annotations: {
+            recent: annotations.slice(0, MAX_ANNOTATIONS).map((entry) => ({
+                id: entry.id,
+                target: { kind: entry.target.kind, id: entry.target.id },
+                text: entry.text,
+                at: entry.at,
+            })),
+        },
+        metrics: {
+            available: served.map((metric) => metric.id),
+            disabledByCapture,
+        },
+        window,
+        generatedAt: now,
+    };
+}
+/**
+ * The project context route. Registered as its own plugin so the query plugin —
+ * which is the registry-metric surface, and is asserted against the registry
+ * route by route — stays exactly that.
+ */
+export const contextRoutes = async (app, { store, config, metadata = EMPTY_PROJECT_METADATA }) => {
+    const r = app.withTypeProvider();
+    /** Per-project document cache, cleared with the instance. */
+    const cache = new Map();
+    app.addHook("onClose", async () => cache.clear());
+    r.get("/api/v1/context", { schema: { response: { 200: projectContextSchema } } }, async (req, reply) => {
+        const resolved = await requireCapability(req, reply, store, "query");
+        if (!resolved)
+            return reply;
+        const projectId = resolved.projectId;
+        const now = Date.now();
+        const cached = cache.get(projectId);
+        if (cached && cached.expiresAt > now)
+            return cached.document;
+        const document = await buildContext(store, config, metadata, projectId, now);
+        cache.set(projectId, { expiresAt: now + CONTEXT_CACHE_TTL_MS, document });
+        return document;
+    });
+};
+//# sourceMappingURL=context.js.map

package/dist/routes/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/routes/context.ts"],"names":[],"mappings":"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"}

package/dist/routes/insights.d.ts

@@ -0,0 +1,36 @@
+/**
+ * **Insight primitives** — `GET /api/v1/insights/*` (ADR 0051 §4, sketch §D).
+ *
+ * Two registry metrics that answer the questions an agent otherwise re-derives
+ * from raw rows on every turn:
+ *
+ * - `insight_baseline` — what is normal for one metric in one scene;
+ * - `insight_movers` — what changed, ranked by how unusual the change is;
+ * - `insight_anomalies` — which buckets of one metric do not belong, and what
+ *   inside the metric accounts for them (#306).
+ *
+ * The plugin is deliberately thin (ADR 0005). Everything that decides an answer
+ * lives in `@uptimizr/db`'s pure `src/insights/`: which metrics have a portable
+ * bucket series, how the window resolves, and every statistic. This file does
+ * three things — validate at the boundary, fan the bucket reads out under a
+ * declared cap, and shape the envelope.
+ *
+ * It is a separate plugin rather than more routes in `query.ts` because it is a
+ * separate *kind* of read: a derived metric composed of other metrics' series,
+ * which needs its own error vocabulary (a metric can be unknown, not comparable,
+ * or comparable but not bucketable — three different 400s) and its own bounded
+ * fan-out. One registration line in `app.ts` is the whole coupling.
+ */
+import type { FastifyPluginAsync } from "fastify";
+import type { CollectorStore } from "../store.js";
+interface Options {
+    store: CollectorStore;
+}
+/**
+ * Insight API. Every route is scoped to the authenticated project and needs the
+ * ordinary `query` capability — an insight is a read of the project's own
+ * telemetry, nothing more.
+ */
+export declare const insightRoutes: FastifyPluginAsync<Options>;
+export {};
+//# sourceMappingURL=insights.d.ts.map

package/dist/routes/insights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.d.ts","sourceRoot":"","sources":["../../src/routes/insights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAkB,MAAM,SAAS,CAAC;AAmDlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,UAAU,OAAO;IACf,KAAK,EAAE,cAAc,CAAC;CACvB;AAuaD;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,kBAAkB,CAAC,OAAO,CAubrD,CAAC"}