@uptimizr/db 2.0.1 → 2.1.0

package/llms.txt

@@ -19,7 +19,16 @@
 - Metric registry: moved to its own dependency-free package, [`@uptimizr/metrics`](../metrics) (ADR 0051 §1) — `METRIC_REGISTRY`, `getMetric`, `allMetrics`, `METRIC_IDS`, `FILTER_TARGETS`, one `MetricDefinition` per aggregation. This package depends on it; a new aggregation without a registry entry fails the build.
 - Neutral helpers: `toEventRow`, `formatUtcTimestamp`, api-key helpers (`parseApiKeyCapabilities`, `serializeApiKeyCapabilities`, `parseCapabilityList`, `hasCapability`, `toApiKeyColumns`, `toApiKeyRateLimit`), audit helpers (`serializeAuditParams`, `clampAuditTool`), `Project`/`ApiKeyRecord`/`ResolvedApiKey`/`ApiKeyCapability`/`AgentAuditEntry`/`SceneRepresentation*`/`SceneRegionRecord`/`SceneRegionSummary` types.
 - Scene registry: `duckdbUpsertSceneProxy`, `duckdbPutSceneRegions` (replaces a scene's region set atomically), `duckdbGetSceneRegions`, `duckdbListSceneRegions`.
+- Project metadata (ADR 0051 §5): `duckdbCreateAnnotation`/`duckdbListAnnotations`/`duckdbDeleteAnnotation`, `duckdbPutGlossaryEntry`/`duckdbListGlossary`/`duckdbDeleteGlossaryEntry`, `duckdbCreateSavedAnalysis`/`duckdbListSavedAnalyses`/`duckdbDeleteSavedAnalysis`, plus `METADATA_LIMITS`, `MetadataLimitError`, `clampMetadataLimit`, `parseSavedAnalysisQuery` and the `AnnotationRecord`/`GlossaryEntryRecord`/`SavedAnalysisRecord` types. These tables, plus `panel_specs` below, are the only writable surface besides events; every write needs the collector's `annotate` capability, and no accessor here can write, alter or delete an event.
+- Panel specs (ADR 0051 §7): `duckdbCreatePanelSpec`/`duckdbListPanelSpecs`/`duckdbUpdatePanelSpec`/`duckdbDeletePanelSpec`, `parsePanelSpec(json)`, the `PanelSpecRecord`/`CreatePanelSpecInput`/`UpdatePanelSpecInput` types, and `METADATA_LIMITS.panelSpecs` as the per-project cap. A fourth metadata table on the same `annotate`-gated, audited, bounded path, holding one closed JSON `spec` document per pinned panel — nothing about the chart or the query is promoted to a column, because no read path asks the database about it. Two differences from the other three: the listing is **oldest first** (these are grid positions, not a feed, so a new pin does not reshuffle the dashboard), and a spec can be **updated in place**, keeping its id and its original authorship. `parsePanelSpec` returns `null` for a column that is not a JSON object and the listing drops that row, so one bad spec cannot empty a dashboard. Migrations: DuckDB `0048_panel_specs` + `0049_panel_specs_idx`, Postgres `0020_panel_specs`, SQL Server `0022_panel_specs` + `0023_panel_specs_idx`, ClickHouse `0017_panel_specs`.
 - Numeric coercion at the store edge (ADR 0051 §2): `coerceRows(metric, rows)`, `numericColumns(rowSchema)`. Every `build*` tags its `QuerySpec` with the registry metric id and every store runner coerces there, so numeric columns reach consumers as JS numbers on DuckDB / ClickHouse / Postgres / SQL Server alike. Registry row schemas are strict `z.number()`; `null` stays `null` (no samples ≠ zero).
 - Result envelopes (`@uptimizr/db/summary`, ADR 0051 §2): `summarizeRows(metric, rows, ctx)`, `tableResult(metric, rows, ctx)`, `clusterCells(cells, opts)`, `wilsonInterval`, `resultFormatSchema` / `resultSummarySchema` / `tableResultSchema`. Build the collector's `format=table | summary` envelopes from the registry alone — pure, browser-safe, no I/O. The metric's `grain` picks the shape: `ranked` top rows + `rest`, `series` (first/last/min/max/trend/slope over the `axis: true` column), `clusters` (deterministic greedy merge of adjacent occupied cells above a density threshold; 8-neighbourhood in 2D, 26 in 3D), or `record` (the row plus its `rateOf` rates). Bounded by `limits.maxSummaryRows`. `reading` is templated from column semantics — no model. `total`/`share` only for additive units.
+- Spatial labelling (`@uptimizr/db/summary`, ADR 0051 §2 / sketch §B.2): `labelClusters(clusters, { axes, cellSize, scene })`, `labelPoint(point, scene, axes, threshold)`, `isWorldSpatialMetric(metric)`, `worldAxisMap(axes)`. Pass `SummaryContext.scene` = `{ id, regions: [{ id, bounds }], meshes: [{ name, aabb }] }` (the collector loads both from the scene registry once per request) and every cluster of a world-space grid gains `region` (smallest containing region by volume), `regions[]` (every containing id, ascending), `nearestMesh` (a proxy box containing the centroid, else the nearest box centre within `cellSize × 2`) and `distance` (world units, `0` when contained). A containing region upgrades `drill.region` from an ad-hoc box to the region id. Only voxel (`vx/vy/vz`) and ground-bin (`gx/gz`) grids are world-space; viewport and angular grids are left untouched. Missing proxy/regions → `null` plus a caveat naming what is missing, never a guess. Pure, deterministic (ties break by id/name), `O(clusters × boxes)` with an early exit.
+- Query DSL (ADR 0051 §3): `compileQuery(projectId, query, dialect, resolved?, tier?)`, `compileMetric(metric, projectId, options, dialect)`, `toBuilderOptions(query, resolved?, tier?)`, `builderFor(name)`. A validated `queryV1` document (grammar in `@uptimizr/schema`, registry validation in `@uptimizr/metrics`) compiles either onto the metric's own `build*` via `FILTER_TARGETS` — byte-identical to the canned endpoint's spec — or, for a metric that declares `genericGroupBy`, onto the shared `compileGenericGroupBy` at any grain it declares. `compileMetric` dispatches on `options.tier`. A store implements the DSL as `run<Engine>Query(compileMetric(…))`. Resolve a `filters.region` region id and a derived `cellSize` before compiling.
+- Compare / explain / order (ADR 0051 §3, #304), all pure: `compareRows(metric, current, previous, ctx)` joins two runs of the same spec on the dimension key into `{ current, previous, delta, deltaPct, significance? }`; `summarizeComparison` digests that into ranked movers with a templated reading; `twoProportionZ`, `welchT`, `wilsonScoreInterval`, `normalCdf`, `studentTTwoSided` are the statistics behind `significance`; `explainQuery(metric, spec, ctx)` renders the plan with parameters named but never valued, plus `warnings` for a silent capture channel, a below-minimum sample, missing spatial labels and truncation; `applyOrder` re-sorts a delegated result and `ORDER_AFTER_CAP_CAVEAT` says when that is not a bottom-N.
+- Session narrative (ADR 0051 §7): `buildSessionNarrative(events, opts)` + `renderSessionNarrativeText(narrative)` — pure compaction of one session's `AnyEvent[]` into an ordered, `maxEntries`-bounded account (scene changes, dwell above `minDwellMs`, interactions, perf dips below `fpsThreshold`, errors, capability changes, XR, end reason, closing totals entry), timestamps relative to the session start. Shapes and caps come from `@uptimizr/metrics` (`NARRATIVE_LIMITS`). An allow-list, not a redactor: never `visitorId`, `url`, `pageMeta`, `user`, positions/rays, or `device` beyond the engine; custom-event property keys only (ADR 0003).
+- Custom-event vocabulary (ADR 0051 §5): `buildCustomEventVocabulary(projectId, opts, dialect)` + `foldCustomEventVocabulary(rows)`. The query counts `custom` events and distinct sessions per developer-defined name and samples that name's 20 most recent `payload` documents; the pure fold derives the union of `props` keys with a coarse type (`string`/`number`/`boolean`/`null`/`mixed`) from them, because key enumeration over an open JSON object has no portable spelling across DuckDB / ClickHouse / Postgres / SQL Server. Stores call the fold, so the raw payload never leaves this layer and only key names and value kinds are ever reported (ADR 0003). Served as `GET /api/v1/vocabulary/custom-events` and inside the project context document.
+- Insight primitives (ADR 0051 §4, `src/insights/`): `buildMetricBuckets(projectId, { metric, bucket, since, until, scene }, dialect)` — the single dialect-authored per-bucket series both primitives consume — plus `computeBaseline`, `rankMovers`, `resolveBaselineWindow`/`resolveMoversWindows`, `BUCKET_MEASURES` / `BUCKETABLE_METRIC_IDS` / `MOVERS_DEFAULT_METRICS` / `MOVERS_MAX_METRICS`, and the pure statistics (`mean`, `median`, `medianAbsoluteDeviation`, `quantile`, `leastSquaresSlope`, `robustZ`). `detectAnomalies` (#306) scores the same series bucket by bucket — a rolling median/MAD for `spike`/`drop` and `cusumChangePoints` for `shift` — and `contributorDimensionFor` / `contributorWindows` / `attributeContributor` name the dimension value holding the excess, from an optional `groupBy` on `buildMetricBuckets` capped at `ANOMALY_MAX_CONTRIBUTOR_SCANS` extra scans per request. **No statistic runs in SQL** — five dialects disagree about `quantile`/`median`, so the query returns raw bucket values and TypeScript does the rest. A metric is bucketable only if `measures.ts` declares how its `comparable.primary` buckets; metrics defined by joins, window functions or caller-supplied predicates are excluded rather than approximated.
+- Significance and scene health (#307): `computeSignificance` picks the test from the measure — a two-proportion z with Wilson/Newcombe intervals for a declared rate, an exact Poisson conditional-binomial test for a bare count, Welch's t over the per-bucket values for a level (so `n` is the bucket count, never the event count) — and returns `{ a, b, effect, ci95, p, test, effectUnit, significant, powerNote }`. `computeSceneHealth` / `rankSceneHealth` / `HEALTH_FACTORS` score each scene 0-100 over six weighted factors normalised against the project's own preceding window, every factor carrying the metric id, raw value, baseline and weight behind it; `resolveHealthWindows` rounds `until` **up** (the one primitive that does, because no factor is a count). `BUCKET_MEASURE_VARIANTS` declares the named auxiliary series they read (a rate denominator, an FPS tail) — never caller input, and declaring one does not make a metric bucketable.
 - Parity: `PARITY_CASES`, `diffParity` (DuckDB-vs-ClickHouse cross-engine equality), `numericColumnsForSpec` (assert numeric types per engine).
 - `readDbSettings()` — environment-driven DuckDB settings with a local-dev default (`DUCKDB_PATH`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/db",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "OSS storage contracts (dialect-agnostic query layer, neutral event/metadata types) and the single-file DuckDB store for Uptimizr.",
   "keywords": [
     "uptimizr",
@@ -55,15 +55,15 @@
     "llms.txt"
   ],
   "dependencies": {
-    "@duckdb/node-api": "^1.5.5-r.4",
-    "zod": "^4.5.4",
-    "@uptimizr/metrics": "0.1.0",
-    "@uptimizr/schema": "1.1.0"
+    "@duckdb/node-api": "^1.5.5-r.5",
+    "zod": "^4.6.5",
+    "@uptimizr/metrics": "0.2.0",
+    "@uptimizr/schema": "1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "tsx": "^4.23.13",
-    "vitest": "^4.1.11"
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",