@uptimizr/db 2.0.1 → 2.1.0

package/AGENTS.md

@@ -11,7 +11,9 @@ The OSS storage contracts plus the single-file **DuckDB** store (ADR 0020):
   table (hot fields promoted to columns; the full event preserved as JSON in `payload` so reads
   stay replay-complete) plus `projects` / `api_keys` (stored only as SHA-256 hashes, each key
   carrying a capability set, an optional label and an optional per-key rate limit) and the
-  `agent_audit` trail.
+  `agent_audit` trail, the scene registry (`scene_representations`, `scene_regions`) and the
+  project-metadata tables `annotations` / `glossary` / `saved_analyses` (ADR 0051 §5) and
+  `panel_specs` (ADR 0051 §7).
 - **Engine-neutral contracts** — the dialect-agnostic query layer (`buildX` + `Dialect`), the
   neutral event-row mapper (`toEventRow`, `formatUtcTimestamp`), and the metadata types
   (`Project`, `ApiKeyRecord`, `SceneRepresentation*`). An optional, separately-licensed
@@ -77,6 +79,24 @@ every tool (collector + CLIs) shares one canonical file regardless of cwd.
   `toApiKeyColumns()` so ordering, validation and the per-key rate-limit columns stay consistent
   across all four engines. `query:raw` is only ever honoured by a collector running with
   `ENABLE_RAW_SESSION_RETENTION` (ADR 0003).
+- **Metadata tables are writable; the events table is not.** `annotations`, `glossary`,
+  `saved_analyses` and `panel_specs` are the only rows a request can write besides events
+  (ADR 0051 §5/§7/§9). Their accessors enforce the per-project caps in `METADATA_LIMITS` at write
+  time and throw `MetadataLimitError` when a project is full — the collector turns that into a
+  `409`. Never add a path that updates or deletes an event row.
+- **`panel_specs` is the one metadata table with an in-place update** (ADR 0051 §7). A spec is one
+  closed JSON document — a metric id, a chart name, some column names — that no read path queries
+  into, stored beside only what the store must filter (`project_id`), order (`created_at`) and
+  address (`id`). `duckdbCreatePanelSpec` / `duckdbListPanelSpecs` / `duckdbUpdatePanelSpec` /
+  `duckdbDeletePanelSpec` are the accessors; `parsePanelSpec` maps the JSON column back and returns
+  `null` for a row that is not an object, which the listing drops rather than failing the whole
+  grid on. Two things differ from the other three tables and must stay that way: the listing is
+  **oldest first**, because these are grid positions rather than a feed and a new pin must not
+  reshuffle somebody's dashboard, and an update keeps the row's id **and its original
+  `authorKind` / `authorKeyId`** — who pinned a panel is a fact about when it appeared, and an edit
+  does not change it. 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`.
 - **The audit log records key ids, never keys.** `agent_audit` rows carry `key_id`; serialize
   parameters with `serializeAuditParams()` (drops credential-shaped keys, bounds the document)
   before they reach a store, and clamp the endpoint with `clampAuditTool()`.
@@ -105,6 +125,26 @@ Its own **package**, not a subpath here, because this one depends on the ~37 MB
 **only** `zod` plus a type-only `@uptimizr/schema` declaration, performs no I/O and holds no store
 or dialect reference.
 
+### Custom-event vocabulary (ADR 0051 §5)
+
+`buildCustomEventVocabulary` is the one aggregation whose SQL output is **not** what the API serves.
+Key _enumeration_ over an open JSON object is the single JSON operation the four supported engines
+have no portable spelling for (`json_keys` / `JSONExtractKeys` / `jsonb_object_keys` / `OPENJSON`),
+and `Dialect.jsonText` cannot express it — it reads a value at a _known_ path. So the query does what
+SQL is good at (counts and distinct sessions per `custom` event name, plus that name's most recent
+`payload` documents, bounded by `CUSTOM_EVENT_VOCABULARY_SAMPLE_ROWS` = 20 per name), and
+`foldCustomEventVocabulary(rows)` — pure, unit-tested, no dialect — turns the sampled payloads into
+one row per name with the union of prop keys and a coarse type each.
+
+- Every store calls the fold in its `customEventVocabulary` method. The **raw payload never leaves
+  the store layer**: the collector serves the folded rows, and only key names and value kinds, never
+  a prop value (ADR 0003).
+- The registry `row` for `custom_event_vocabulary` therefore describes the **folded** row; the parity
+  case compares the counts and the sampling shape and excludes `sample_payload`, which is engine
+  formatted (Postgres normalises it through `jsonb`).
+- Do not add a `jsonKeys` member to `Dialect` to "fix" this without a good reason: four dialects would
+  have to agree on key ordering, type coercion and NULL handling for a discovery read.
+
 ### Numeric coercion at the store edge (ADR 0051 §2)
 
 Numeric columns are strict `z.number()` — the schema describes the API, not the wire. Every
@@ -148,14 +188,42 @@ samples", not `0`, which is why nine perf/resource metrics declare nullable colu
 from one `preSerialization` hook, so no route handler knows they exist.
 
 ```ts
-import { summarizeRows, tableResult, clusterCells, wilsonInterval } from "@uptimizr/db/summary";
+import {
+  summarizeRows,
+  tableResult,
+  clusterCells,
+  labelClusters,
+  labelPoint,
+  isWorldSpatialMetric,
+  wilsonInterval,
+} from "@uptimizr/db/summary";
 ```
 
+The **Zod mirrors** of the envelopes (`tableResultSchema`, `resultSummarySchema`,
+`resultEnvelopeSchema`, `resultFormatSchema`) are still exported from the same subpath, but they
+are now defined in [`@uptimizr/metrics`](../metrics) and re-exported here: `@uptimizr/agent-core`
+and `@uptimizr/mcp` describe the same envelopes in their tool output schemas and may not depend on
+this package. Change a shape **there**, never here.
+
 The `grain` selects the shape — `ranked` (top rows + `rest`), `series` (first/last/min/max/trend/
 slope over the `axis` column), `clusters` (`clusterCells`: deterministic greedy merge of adjacent
 occupied cells above a density threshold, 8-neighbourhood in 2D / 26 in 3D), or `record` (the single
 row plus its `rateOf` rates). Everything is bounded by `limits.maxSummaryRows`.
 
+### Spatial labelling (`labels.ts`, ADR 0051 §2 / sketch §B.2)
+
+Pass a `SummaryContext.scene` — `{ id, regions: [{ id, bounds }], meshes: [{ name, aabb }] }`, which
+the collector loads from the scene registry once per request — and every cluster of a **world-space**
+grid is labelled: `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 also upgrades
+`drill.region` from an ad-hoc world box to the region **id**, which `?region=` resolves server-side.
+
+`isWorldSpatialMetric(metric)` says whether a metric is worth loading a scene for: only the voxel
+(`vx/vy/vz`) and ground-bin (`gx/gz`) grids are world-space — the viewport pointer/UV bins and the
+angular view-direction grid are not, and are left untouched. Cost is `O(clusters × boxes)` with a
+per-axis early exit; `spatialLabels.test.ts` holds the largest shape under 50 ms.
+
 **Rules for agents:**
 
 - A metric's summary comes from its **column semantics**, never from a per-metric special case. If a
@@ -169,8 +237,164 @@ row plus its `rateOf` rates). Everything is bounded by `limits.maxSummaryRows`.
   rows is meaningless, and a share derived from it is worse than none.
 - Clustering must stay a pure function of the cell _set_: accumulate in sorted coordinate order so a
   reordered input is bit-identical (`summary.test.ts` rotates every fixture).
+- Labelling must stay a pure function of the region/mesh _sets_ too: break every tie by id or name
+  ascending, never by array order, and report `null` rather than a far-away guess.
 - Adding `format` to a metric's `filters` and to the collector's querystring is one change — the
   collector's `registryRoutes.test.ts` fails if they drift.
+- The collector's `format` default is **`full`** and must stay that way — it is what keeps the
+  feature invisible to the dashboard. The generated agent tools apply their own `table` default
+  and send it explicitly (`DEFAULT_TOOL_FORMAT` in `@uptimizr/agent-core`).
+
+## Query DSL (ADR 0051 §3)
+
+`compileQuery(projectId, query, dialect)` turns a validated `queryV1` document (the Zod grammar in
+`@uptimizr/schema`, the registry validation in `@uptimizr/metrics`) into an ordinary `QuerySpec`, by
+way of the metric's **existing** builder: the registry names the `build*`, `FILTER_TARGETS` names the
+option field each filter drives, and the builder renders what it has always rendered.
+
+```ts
+import { compileMetric, compileQuery, toBuilderOptions } from "@uptimizr/db";
+
+// A store's whole DSL implementation:
+runMetric: (projectId, metric, options) =>
+  runDuckdbQuery(db, compileMetric(metric, projectId, options, duckdbDialect));
+```
+
+- **No second SQL path.** The spec a DSL query compiles to is byte-identical to the one the canned
+  endpoint runs — `src/__tests__/queryDsl.test.ts` asserts that for every aggregation on all four
+  dialects, and `PARITY_CASES` carries `dsl:*` cases that execute compiled specs against the same
+  golden. Everything parity already proves about a builder holds for the DSL.
+- **It does not validate.** By the time a query reaches `compileQuery` it has passed
+  `queryV1Schema` and `validateQuery`. The two `throw`s are guards against a caller skipping that.
+- **Two values must be resolved first**, by whoever has a store: a `filters.region` given as a
+  registered region id (→ its bounds) and a spatial `cellSize` derived from the scene's extent. Pass
+  them as the `QueryResolution` argument.
+- **The generic tier is the second compiler**, not a second _path_: `compileGenericGroupBy`
+  (`query/dsl/generic.ts`) renders `SELECT <dims>, <measures> … GROUP BY <dims>` for a metric that
+  declares `genericGroupBy`, at any grain it declares. Everything variable in that SQL comes from
+  registry data — the event types, the scope predicate, the measures, each dimension's expression —
+  and every caller-supplied value is a bound parameter. `compileMetric` dispatches on
+  `options.tier`, which only `toBuilderOptions` sets, so a store calling `runMetric` with a plain
+  option bag keeps the delegated behaviour it has always had.
+- **Four pure layers sit on top**, none of which runs a query: `compareRows` /
+  `summarizeComparison` (join two runs of the same spec on the dimension key),
+  `twoProportionZ` / `welchT` (is the difference real — pinned to published table values in
+  `querySignificance.test.ts`), `explainQuery` (the plan and its warnings), and `applyOrder`
+  (an honest re-sort of a delegated result, with `ORDER_AFTER_CAP_CAVEAT` when the builder's own
+  cap had already chosen the rows).
+- **`explain` shows the SQL because there is nothing in it to redact.** `explainSpec` lists
+  parameters by name and logical type and never by value; the SQL text carries placeholders only,
+  which is exactly the property a reader uses `explain` to check.
+
+## Session narrative (ADR 0051 §7)
+
+`buildSessionNarrative(events, opts)` compacts one session's `AnyEvent[]` into an ordered,
+bounded account of what it did; `renderSessionNarrativeText(narrative)` renders it as one line per
+entry. Both are **pure** — no store, no request, no I/O — and live in `src/narrative/`.
+
+```ts
+import { buildSessionNarrative, renderSessionNarrativeText } from "@uptimizr/db";
+
+const narrative = buildSessionNarrative(events, { minDwellMs: 2000, maxEntries: 200 });
+narrative.entries; // ordered { tMs, kind, summary, refs }, ending with the `summary` entry
+narrative.totals; // { events, durationMs, scenes, meshes, interactions, dips, errors }
+console.log(renderSessionNarrativeText(narrative));
+```
+
+Shapes, defaults and hard caps live in `@uptimizr/metrics` (`NARRATIVE_LIMITS`,
+`sessionNarrativeEntrySchema`) so the collector route, the generated `session_narrative` tool and
+this implementation cannot drift.
+
+**It is an allow-list, not a redactor** (ADR 0003). It reads only: relative timestamps, scene ids,
+mesh names, interaction kinds and input sources, custom-event/input-action names, FPS, truncated
+runtime-error messages, diagnostic category/severity, capability transitions, and the rendering
+engine. It never reads `visitorId`, `url`, `pageMeta`, `user`, any position/ray/UV, any other
+`device` field, or custom-event property values (keys only, unless `includeCustomProps`). Keep it
+that way when adding an event type — adding a field to the switch is a privacy decision.
+
+### Insight primitives (ADR 0051 §4, `src/insights/`)
+
+`baseline`, `movers`, `anomalies`, `significance` and `scene_health` — "what is normal here",
+"what changed", "_when_ did it go wrong", "is that change real" and "which scene should I look at
+first" — as five derived registry metrics. The shape of the directory is the design:
+
+```ts
+import {
+  buildMetricBuckets, // the ONE dialect-authored query both primitives consume
+  computeBaseline,
+  rankMovers,
+  resolveBaselineWindow,
+  resolveMoversWindows,
+  BUCKET_MEASURES, // metric id -> how its primary column buckets
+  BUCKETABLE_METRIC_IDS,
+  MOVERS_DEFAULT_METRICS,
+  MOVERS_MAX_METRICS,
+  detectAnomalies, // #306: robust z per bucket + CUSUM change-points
+  contributorDimensionFor, // the ONE dimension a metric's excess may be split by
+  contributorWindows, // the windows attribution is allowed to re-scan
+  attributeContributor,
+  ANOMALY_MAX_CONTRIBUTOR_SCANS,
+  // --- significance / scene health (#307) ---
+  computeSignificance, // picks the test from the measure: proportions / Poisson / Welch
+  computeSceneHealth, // six weighted factors, each traceable to its metric
+  rankSceneHealth,
+  resolveHealthWindows,
+  HEALTH_FACTORS, // the fixed factor catalog, with default weights
+  BUCKET_MEASURE_VARIANTS, // named auxiliary series: a rate denominator, an FPS tail
+} from "@uptimizr/db";
+```
+
+**Rules for agents:**
+
+- **No statistic may be computed in SQL.** Five dialects disagree about `quantile`, `median` and
+  `stddev`; an insight that changes with the storage engine is not an insight. The query returns raw
+  per-bucket values and `stats.ts` does the rest in TypeScript.
+- `buildMetricBuckets` lives in `src/insights/`, **not** in `query/aggregations.ts`. The `build*`
+  exports of that module are the registry's closed list of _metrics_, each of which must have its own
+  entry and endpoint; this is the shared _input_ of two metrics and has neither.
+- A metric is bucketable only if it has an entry in `measures.ts`, and that entry's `column` must be
+  the metric's `comparable.primary` (asserted in `src/__tests__/insights.test.ts`). Widening the
+  catalog is additive: add the measure, add a parity case, done.
+- A metric may also declare **named auxiliary series** (`BUCKET_MEASURE_VARIANTS`): a rate
+  denominator, an FPS tail, the numerator of a ratio whose metric has no headline series at all.
+  A variant is **never** caller input — `significance` picks `denominator` from the registry and
+  `scene_health` reads a fixed factor catalog — and declaring one does **not** make the metric
+  bucketable: `isBucketableMetric` still answers about the metric's own headline column, so
+  `baseline` and `movers` keep rejecting `jank_rate` and `xr_abandonment` as before.
+- **Which test `significance` runs is derived, not configured**: a declared rate (a `rateOf`
+  headline column plus a `denominator` variant) gets a two-proportion z with Wilson/Newcombe
+  intervals, a `count`/`sessions` aggregate gets an exact Poisson rate test, and everything else
+  gets Welch's t over the per-bucket values. Welch's `n` is the **bucket count**, never the event
+  count: samples inside one day are not independent.
+- **Every `scene_health` factor must stay traceable.** A factor row carries the metric id, the raw
+  value, the project baseline it was compared with and the weight it took. A factor that could not
+  be measured reports `score: null` with a reason and is excluded from the mean — never defaulted
+  to 50, and never dropped from the row.
+- **Never approximate a series to widen the catalog.** Funnels, cohort metrics and anything defined
+  by the relationship between consecutive events have no faithful per-bucket form; a `400` naming the
+  ids that do is a better answer than a plausible wrong number.
+- Predicates come from a **closed vocabulary** over promoted columns, with constant values bound as
+  parameters. Do not add a free-SQL escape hatch.
+- Window bounds snap **down** to whole buckets, so the day or hour in progress is excluded and a
+  default reference really is an equal window. `resolveHealthWindows` is the deliberate exception
+  (it rounds `until` **up**): every health factor is a rate or a percentile, which a partial bucket
+  does not distort, and flooring would make the score answer about yesterday.
+- `movers` reports a sub-`minSample` delta with `aboveMinSample: false` and ranks it below every
+  gated mover. It must never be dropped — "we cannot tell" and "nothing changed" are different
+  answers — and never reported as a finding.
+- Cost is bounded by `MOVERS_MAX_METRICS` (one grouped scan per scanned metric). Raising it is a
+  deliberate change, not a default.
+- `anomalies` (#306) adds **one** piece of per-dialect SQL and no more: an optional `groupBy` on
+  `buildMetricBuckets` that adds one promoted column to the `SELECT`/`GROUP BY`. The column comes
+  from the measure's own `splitBy`, a compile-time union — never from request input — and the shape
+  has its own `metricBuckets:split*` parity cases on all four engines.
+- `anomalies`' `z` divides by the MAD **rescaled to a standard deviation** (`MAD_TO_SIGMA`), because
+  `sensitivity` is a threshold and an uncalibrated one reports ordinary days. `movers` divides by the
+  raw MAD because it ranks. Do not "unify" them without moving the default with it.
+- Attribution is capped at `ANOMALY_MAX_CONTRIBUTOR_SCANS` extra grouped scans per request, whatever
+  the data looks like. The cap, not the data, is what bounds the endpoint.
+- `significance` and `scene_health` (ADR 0051 §4) slot in here the same way: a new pure module over
+  the same bucket series.
 
 ## Cross-engine parity (ADR 0020)
 
@@ -203,7 +427,8 @@ service). The scale tier reuses the same exported `PARITY_CASES`/golden to run
    `day` strings (`YYYY-MM-DD`) render identically and are compared.
 
 When adding an aggregation or event type, extend `PARITY_EVENTS`/`PARITY_CASES` with golden so both
-engines stay covered.
+engines stay covered. The `metricBuckets:*` cases cover the insight bucket series — one per aggregate
+shape its measure catalog can render, which is what makes `baseline`/`movers` portable.
 
 ## More
 

package/README.md

@@ -18,6 +18,12 @@ The OSS storage contracts plus the single-file **DuckDB** store:
   `scene_regions` (named, labelled boxes per scene, keyed `(project_id, scene_id, region_id)`).
   `duckdbPutSceneRegions` replaces a scene's whole set in one transaction; `duckdbGetSceneRegions`
   / `duckdbListSceneRegions` read it back.
+- **Project metadata** (ADR 0051 §5) — `annotations`, `glossary` and `saved_analyses`: notes,
+  definitions and saved questions written by a project's own people and agents. These are the only
+  rows a request can write besides events; the collector gates each write behind the `annotate`
+  capability and audits it, and nothing on this path can write, alter or delete an event. The
+  accessors enforce the per-project caps in `METADATA_LIMITS` and throw `MetadataLimitError` when a
+  project is full.
 
 This package carries **no ClickHouse/Postgres dependency**. Optional scale adapters such as
 `@uptimizr/db-clickhouse` compose these contracts behind the same interface. Server/Node only — no
@@ -150,6 +156,13 @@ for a `bin`/`voxel` grid (`clusterCells` — a deterministic greedy merge of adj
 above a density threshold, 8-neighbourhood in 2D and 26 in 3D), and the `record` itself plus its
 `rateOf` rates for a single-row metric. Everything is capped at `limits.maxSummaryRows`.
 
+The Zod mirrors of the envelopes — `tableResultSchema(row)`, `resultSummarySchema`,
+`resultEnvelopeSchema(full, row)`, `resultFormatSchema` — are exported from the same subpath as
+always, but are **defined in [`@uptimizr/metrics`](../metrics)** and re-exported here.
+`@uptimizr/agent-core` and `@uptimizr/mcp` describe the same envelopes in their tool output
+schemas and cannot depend on this package (it carries the DuckDB driver), so the shapes have one
+definition, in the package both sides already share.
+
 Two invariants worth knowing before extending it:
 
 - **`reading` is templated, not generated.** It is assembled from `ColumnSemantics` alone, so the

package/dist/duckdb/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/duckdb/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAoaxE,CAAC;AAEF;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/duckdb/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA6kBxE,CAAC;AAEF;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE"}

package/dist/duckdb/migrations.js

@@ -428,6 +428,175 @@ export const DUCKDB_MIGRATIONS = [
       );
     `,
     },
+    // Project metadata (ADR 0051 §5 / sketch §E.2): the three tables that let a
+    // person or an agent leave something behind — a note on a spike, a definition
+    // of a name, a question worth re-asking. Metadata only: the `events` table is
+    // untouched and no event type exists for any of this.
+    //
+    // `since`/`until` are nullable TIMESTAMPs (a standing note has neither);
+    // `author_kind` is the collector's decision ('user' | 'agent'), `author_key_id`
+    // the id of the API key that carried the write — never the key or its hash.
+    {
+        id: "0039_annotations",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS annotations (
+        id            VARCHAR PRIMARY KEY,
+        project_id    VARCHAR NOT NULL,
+        target_kind   VARCHAR NOT NULL,
+        target_id     VARCHAR,
+        since         TIMESTAMP,
+        until         TIMESTAMP,
+        text          VARCHAR NOT NULL,
+        author_kind   VARCHAR NOT NULL DEFAULT 'user',
+        author_key_id VARCHAR,
+        created_at    TIMESTAMP NOT NULL DEFAULT now(),
+        updated_at    TIMESTAMP NOT NULL DEFAULT now()
+      );
+    `,
+    },
+    {
+        id: "0040_annotations_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS annotations_project_created_idx
+        ON annotations (project_id, created_at);
+    `,
+    },
+    // Glossary: what a name means *in this project*. Keyed by (project, term), so
+    // a write is an idempotent upsert and the term is the identity.
+    {
+        id: "0041_glossary",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS glossary (
+        project_id  VARCHAR NOT NULL,
+        term        VARCHAR NOT NULL,
+        meaning     VARCHAR NOT NULL,
+        updated_at  TIMESTAMP NOT NULL DEFAULT now(),
+        PRIMARY KEY (project_id, term)
+      );
+    `,
+    },
+    // Saved analyses: a titled question plus what was concluded from it. `query`
+    // is JSON text the collector stores but does not interpret (the DSL lands
+    // separately); it is bounded at the edge before it gets here.
+    {
+        id: "0042_saved_analyses",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS saved_analyses (
+        id            VARCHAR PRIMARY KEY,
+        project_id    VARCHAR NOT NULL,
+        title         VARCHAR NOT NULL,
+        query         VARCHAR NOT NULL DEFAULT '{}',
+        conclusion    VARCHAR,
+        author_kind   VARCHAR NOT NULL DEFAULT 'user',
+        author_key_id VARCHAR,
+        created_at    TIMESTAMP NOT NULL DEFAULT now()
+      );
+    `,
+    },
+    {
+        id: "0043_saved_analyses_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS saved_analyses_project_created_idx
+        ON saved_analyses (project_id, created_at);
+    `,
+    },
+    // --- Conditional subscriptions (#311, ADR 0051 §6 / sketch §F.1–F.2) ------
+    // One row per standing question: which registry metric, over what window, with
+    // what predicate, and where a firing is delivered. The declaration itself is a
+    // closed Zod union validated at the request boundary and never queried *into*,
+    // so it lives in one JSON `config` column; the scalars beside it are exactly
+    // what the store must filter (`project_id`, `enabled`), order (`created_at`) or
+    // update (`last_fired_at`, `last_error`, `failures`).
+    //
+    // `webhook_secret` is the shared HMAC key. It is deliberately NOT hashed — a
+    // one-way digest cannot sign an outbound body — and is the one column no read
+    // path ever selects into a record: `duckdb/subscriptions.ts` reads it only in
+    // `getWebhookSecret`, and every API response carries a masked placeholder.
+    {
+        id: "0044_subscriptions",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS subscriptions (
+        id             VARCHAR PRIMARY KEY,
+        project_id     VARCHAR NOT NULL,
+        name           VARCHAR NOT NULL,
+        metric         VARCHAR NOT NULL,
+        config         VARCHAR NOT NULL,
+        webhook_secret VARCHAR,
+        enabled        BOOLEAN NOT NULL DEFAULT TRUE,
+        created_at     TIMESTAMP NOT NULL DEFAULT now(),
+        updated_at     TIMESTAMP NOT NULL DEFAULT now(),
+        last_fired_at  TIMESTAMP,
+        last_error     VARCHAR,
+        failures       BIGINT NOT NULL DEFAULT 0
+      );
+    `,
+    },
+    {
+        id: "0045_subscriptions_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS subscriptions_project_idx
+        ON subscriptions (project_id, created_at);
+    `,
+    },
+    // The bounded firing log: `{ subscriptionId, at, payload }`, last 100 per
+    // subscription. The trim runs in the same transaction as the insert
+    // (`recordSubscriptionEvent`), so the bound is never observed broken.
+    //
+    // `at` is a DuckDB keyword, so it is double-quoted here and in every accessor.
+    // The column name matches the other three engines, where it needs no quoting.
+    {
+        id: "0046_subscription_events",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS subscription_events (
+        id              VARCHAR PRIMARY KEY,
+        subscription_id VARCHAR NOT NULL,
+        project_id      VARCHAR NOT NULL,
+        "at"            TIMESTAMP NOT NULL DEFAULT now(),
+        payload         VARCHAR NOT NULL DEFAULT '{}'
+      );
+    `,
+    },
+    {
+        id: "0047_subscription_events_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS subscription_events_sub_at_idx
+        ON subscription_events (subscription_id, "at");
+    `,
+    },
+    // --- Declarative panel specs (#315, ADR 0051 §7 / sketch §G.3) ------------
+    // What an agent leaves behind when an answer is worth keeping: a query, a
+    // chart name and a one-line reading. The spec is a closed document validated
+    // at the request boundary and never queried *into*, so — like a
+    // subscription's `config` — it lives in one JSON column and nothing about it
+    // is promoted to a column of its own.
+    //
+    // `author_kind` / `author_key_id` mirror the other three metadata tables: the
+    // collector's decision about who wrote the row, and the id of the key that
+    // carried it (never the key or its hash). `updated_at` earns its place
+    // because a spec is the one metadata row that is genuinely *edited* —
+    // retitling a pinned panel or widening it to full span should keep the panel
+    // where it is rather than mint a new one at the top of the grid.
+    {
+        id: "0048_panel_specs",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS panel_specs (
+        id            VARCHAR PRIMARY KEY,
+        project_id    VARCHAR NOT NULL,
+        spec          VARCHAR NOT NULL,
+        author_kind   VARCHAR NOT NULL DEFAULT 'user',
+        author_key_id VARCHAR,
+        created_at    TIMESTAMP NOT NULL DEFAULT now(),
+        updated_at    TIMESTAMP NOT NULL DEFAULT now()
+      );
+    `,
+    },
+    {
+        id: "0049_panel_specs_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS panel_specs_project_created_idx
+        ON panel_specs (project_id, created_at);
+    `,
+    },
 ];
 /**
  * Apply all DuckDB migrations in order. Idempotent — safe to run on every boot.

package/dist/duckdb/migrations.js.map

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

package/dist/duckdb/panelSpecs.d.ts

@@ -0,0 +1,29 @@
+import { type CreatePanelSpecInput, type MetadataListOptions, type PanelSpecRecord, type UpdatePanelSpecInput } from "../metadata.js";
+import type { DuckdbClient } from "./client.js";
+/**
+ * Pin one panel and return the stored row.
+ *
+ * Refuses with {@link MetadataLimitError} once the project holds
+ * {@link METADATA_LIMITS.panelSpecs} panels. The cap is lower than the other
+ * metadata tables' on purpose: every spec is a query the dashboard runs on
+ * every load, so the bound is about what a grid can usefully hold.
+ */
+export declare function createPanelSpec(client: DuckdbClient, projectId: string, input: CreatePanelSpecInput): Promise<PanelSpecRecord>;
+/**
+ * A project's pinned panels, **oldest first**.
+ *
+ * The opposite order to the other metadata listings, and deliberately so: these
+ * are grid positions, not a feed. Newest-first would move every panel down the
+ * dashboard each time somebody pinned one, which is exactly the instability a
+ * person notices and a saved layout cannot survive.
+ */
+export declare function listPanelSpecs(client: DuckdbClient, projectId: string, opts?: MetadataListOptions): Promise<PanelSpecRecord[]>;
+/**
+ * Replace one panel's spec, keeping its id, its place in the grid and its
+ * original authorship. Returns `null` when the id is unknown (or belongs to
+ * another project — the two are deliberately indistinguishable).
+ */
+export declare function updatePanelSpec(client: DuckdbClient, projectId: string, id: string, input: UpdatePanelSpecInput): Promise<PanelSpecRecord | null>;
+/** Unpin one panel. Returns whether a row was removed. */
+export declare function deletePanelSpec(client: DuckdbClient, projectId: string, id: string): Promise<boolean>;
+//# sourceMappingURL=panelSpecs.d.ts.map

package/dist/duckdb/panelSpecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panelSpecs.d.ts","sourceRoot":"","sources":["../../src/duckdb/panelSpecs.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0EhD;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAuB1B;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,eAAe,EAAE,CAAC,CAc5B;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAajC;AAED,0DAA0D;AAC1D,wBAAsB,eAAe,CACnC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,OAAO,CAAC,CAYlB"}

package/dist/duckdb/panelSpecs.js

@@ -0,0 +1,104 @@
+import { randomUUID } from "node:crypto";
+import { METADATA_LIMITS, MetadataLimitError, clampMetadataLimit, parsePanelSpec, } from "../metadata.js";
+const PANEL_SPEC_COLS = `id, project_id, spec, author_kind, author_key_id,
+       epoch_ms(created_at) AS created_at_ms, epoch_ms(updated_at) AS updated_at_ms`;
+/**
+ * Map one row, or `null` when its `spec` column is not a JSON object.
+ *
+ * A row that cannot be parsed cannot be drawn, and a listing that threw on one
+ * would take the whole dashboard grid down with it. Dropping it is the same
+ * choice ADR 0041's remote-panel loader makes for a module that fails to
+ * import: one bad entry never blocks the rest.
+ */
+function rowToPanelSpec(row) {
+    const spec = parsePanelSpec(row.spec);
+    if (spec == null)
+        return null;
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        spec,
+        authorKind: row.author_kind,
+        authorKeyId: row.author_key_id,
+        createdAt: new Date(Number(row.created_at_ms)),
+        updatedAt: new Date(Number(row.updated_at_ms)),
+    };
+}
+/** `SELECT count(*)` as a plain number, whatever width the driver returns. */
+async function countRows(client, sql, params) {
+    const rows = await client.all(sql, params);
+    return Number(rows[0]?.n ?? 0);
+}
+/** Read one row back by id, for the create/update paths. */
+async function readOne(client, id) {
+    const rows = await client.all(`SELECT ${PANEL_SPEC_COLS} FROM panel_specs WHERE id = $id`, { id });
+    // Written on this connection a moment ago, from a document that serialized,
+    // so both the row and its parse are guaranteed here.
+    return rowToPanelSpec(rows[0]);
+}
+/**
+ * Pin one panel and return the stored row.
+ *
+ * Refuses with {@link MetadataLimitError} once the project holds
+ * {@link METADATA_LIMITS.panelSpecs} panels. The cap is lower than the other
+ * metadata tables' on purpose: every spec is a query the dashboard runs on
+ * every load, so the bound is about what a grid can usefully hold.
+ */
+export async function createPanelSpec(client, projectId, input) {
+    const count = await countRows(client, `SELECT count(*) AS n FROM panel_specs WHERE project_id = $projectId`, { projectId });
+    if (count >= METADATA_LIMITS.panelSpecs) {
+        throw new MetadataLimitError("panelSpecs", METADATA_LIMITS.panelSpecs);
+    }
+    const id = randomUUID();
+    await client.run(`INSERT INTO panel_specs
+       (id, project_id, spec, author_kind, author_key_id, created_at, updated_at)
+     VALUES ($id, $projectId, $spec, $authorKind, $authorKeyId, now(), now())`, {
+        id,
+        projectId,
+        spec: JSON.stringify(input.spec),
+        authorKind: input.authorKind,
+        authorKeyId: input.authorKeyId,
+    });
+    return readOne(client, id);
+}
+/**
+ * A project's pinned panels, **oldest first**.
+ *
+ * The opposite order to the other metadata listings, and deliberately so: these
+ * are grid positions, not a feed. Newest-first would move every panel down the
+ * dashboard each time somebody pinned one, which is exactly the instability a
+ * person notices and a saved layout cannot survive.
+ */
+export async function listPanelSpecs(client, projectId, opts = {}) {
+    const limit = clampMetadataLimit(opts.limit, METADATA_LIMITS.panelSpecs, METADATA_LIMITS.panelSpecs);
+    const rows = await client.all(`SELECT ${PANEL_SPEC_COLS}
+       FROM panel_specs WHERE project_id = $projectId
+      ORDER BY created_at ASC, id ASC
+      LIMIT ${limit}`, { projectId });
+    return rows.map(rowToPanelSpec).filter((record) => record !== null);
+}
+/**
+ * Replace one panel's spec, keeping its id, its place in the grid and its
+ * original authorship. Returns `null` when the id is unknown (or belongs to
+ * another project — the two are deliberately indistinguishable).
+ */
+export async function updatePanelSpec(client, projectId, id, input) {
+    const before = await countRows(client, `SELECT count(*) AS n FROM panel_specs WHERE project_id = $projectId AND id = $id`, { projectId, id });
+    if (before === 0)
+        return null;
+    await client.run(`UPDATE panel_specs SET spec = $spec, updated_at = now()
+      WHERE project_id = $projectId AND id = $id`, { projectId, id, spec: JSON.stringify(input.spec) });
+    return readOne(client, id);
+}
+/** Unpin one panel. Returns whether a row was removed. */
+export async function deletePanelSpec(client, projectId, id) {
+    const before = await countRows(client, `SELECT count(*) AS n FROM panel_specs WHERE project_id = $projectId AND id = $id`, { projectId, id });
+    if (before === 0)
+        return false;
+    await client.run(`DELETE FROM panel_specs WHERE project_id = $projectId AND id = $id`, {
+        projectId,
+        id,
+    });
+    return true;
+}
+//# sourceMappingURL=panelSpecs.js.map