@uptimizr/db 1.0.2 → 2.0.1

package/AGENTS.md

@@ -9,7 +9,9 @@ The OSS storage contracts plus the single-file **DuckDB** store (ADR 0020):
 
 - **DuckDB** — one persisted `.duckdb` file holding both events and metadata. A wide `events`
   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).
+  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.
 - **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
@@ -64,12 +66,112 @@ every tool (collector + CLIs) shares one canonical file regardless of cwd.
 - A new aggregation = a pure `buildX(projectId, opts, dialect)` builder returning a `QuerySpec`
   (`{ query, query_params }`), run with `runDuckdbQuery`. Keep builders pure, dialect-agnostic,
   and unit-tested without a live database; add a `PARITY_CASES` entry so both engines stay equal.
+- **A new aggregation is not done until it has a metric-registry entry** (see below). The build
+  fails without one.
 - Validate events upstream at the collector boundary; this layer assumes valid input.
 - API keys are only ever stored as SHA-256 hashes — never persist raw keys.
+- **Key capabilities are a set, not a role** (ADR 0051 §7): `ingest`, `query`, `annotate`,
+  `query:raw`, persisted as a canonical comma-separated token list in `api_keys.capabilities`.
+  Always read it with `parseApiKeyCapabilities(capabilities, capability)` so a key issued before
+  the set existed still resolves via the legacy singular column; always write it with
+  `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).
+- **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()`.
 - **Single-writer store.** DuckDB allows only one read-write process per file; assume a single
   collector per `.duckdb` file. Back up = copy the file. Multi-writer / horizontal scale is the
   optional ClickHouse scale tier, not this package.
 
+## Metric registry (ADR 0051 §1)
+
+[`@uptimizr/metrics`](../metrics) is the semantic layer over the aggregations: one
+`MetricDefinition` per exported `build*` (plus two builder-less resource entries — `session_meta`,
+`scene_representation`) declaring id, title, agent-facing description, builder, collector endpoint,
+`grain`, `dimensions`, `filters`, the output `row` Zod schema, per-column semantics (unit /
+measure / label / axis / `rateOf`), row `limits`, `interpretation`, `caveats`, `sourceChannels`
+(the ADR 0012 capture dials that must be on for the metric to have data), `related` metrics,
+`comparable` semantics and a `category`. `DimensionId` / `FilterId` are closed unions declared
+once; `FILTER_TARGETS` maps each filter to the `query/types.ts` option field it drives.
+
+```ts
+import { getMetric, allMetrics, METRIC_IDS } from "@uptimizr/metrics";
+```
+
+Its own **package**, not a subpath here, because this one depends on the ~37 MB
+`@duckdb/node-api` native binding and the registry's consumers (`@uptimizr/agent-core`,
+`@uptimizr/mcp`, `@uptimizr/react`) can never use a database driver. `@uptimizr/metrics` imports
+**only** `zod` plus a type-only `@uptimizr/schema` declaration, performs no I/O and holds no store
+or dialect reference.
+
+### Numeric coercion at the store edge (ADR 0051 §2)
+
+Numeric columns are strict `z.number()` — the schema describes the API, not the wire. Every
+`build*` tags its `QuerySpec` with the metric id, and each store's runner (`runDuckdbQuery`,
+`runClickhouseQuery`, `runPostgresQuery`, `runMssqlQuery`) calls `coerceRows(spec.metric, rows)` at
+the one point rows leave the driver, so a string-encoded 64-bit integer or decimal becomes a number
+before any consumer sees it. `null` passes through — an aggregate over an empty set is "no
+samples", not `0`, which is why nine perf/resource metrics declare nullable columns.
+
+- **Do not** reintroduce `z.coerce.number()` in `registry.ts`: a registry test proves that
+  string-encoded rows _fail_ the strict schema and _pass_ after `coerceRows`, which is what pins
+  the work to the edge.
+- A new store must call `coerceRows` in its runner; the parity suite asserts
+  `typeof === "number"` for every registry-numeric column on every engine (`numericColumnsForSpec`).
+- Junk in a numeric column throws under a test runner and is left untouched with a one-per-column
+  warning in production (`coerceRows(..., { strict })` pins either).
+
+**Rules for agents:**
+
+- A `build*` aggregation added here must also be added to `AGGREGATION_BUILDER_NAMES` in
+  `@uptimizr/metrics`, and given a registry entry. Missing the entry is a **compile error**
+  (`NoUnregisteredAggregations` names the missing builder); missing the list entry fails this
+  package's `registry.test.ts` at runtime and names it too.
+- **Never import `@uptimizr/db` from `@uptimizr/metrics`.** The dependency runs one way only —
+  that is the whole point of the split. The builder-name list is literal data for that reason.
+- The 20 ids that are already `@uptimizr/agent-core` tool names (`top_meshes`, `perf_summary`,
+  `list_sessions`, …) are frozen — renaming one breaks every MCP client.
+- `row` must match what the SQL actually projects, not what `types.ts` declares. It is also the
+  collector's **response schema**, so an undeclared column is stripped from the API and a `null` in
+  a non-nullable one is a 500. Four suites enforce this: `@uptimizr/metrics`' `registry.test.ts`
+  (coverage, internal consistency), this package's `registry.test.ts` (the builder link, plus `row`
+  parsing against real DuckDB output over the parity fixtures and the string-encoded ClickHouse
+  shape through `coerceRows`), the collector's `registryRoutes.test.ts` (endpoint exists;
+  querystring keys === `filters`) and its `queryResponseSchemas.test.ts` (every endpoint, against a
+  seeded store, an empty one, and the in-memory store).
+
+### Result envelopes (ADR 0051 §2, `@uptimizr/db/summary`)
+
+`summarizeRows(metric, rows, ctx)` and `tableResult(metric, rows, ctx)` build the collector's
+`format=table | summary` envelopes. Pure, registry-driven, browser-safe; the collector calls them
+from one `preSerialization` hook, so no route handler knows they exist.
+
+```ts
+import { summarizeRows, tableResult, clusterCells, wilsonInterval } from "@uptimizr/db/summary";
+```
+
+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`.
+
+**Rules for agents:**
+
+- A metric's summary comes from its **column semantics**, never from a per-metric special case. If a
+  metric summarises badly, fix its `unit` / `measure` / `label` / `axis` / `rateOf` declarations.
+- A `bucket`-grain metric must declare exactly one `axis: true` column, and no other grain may
+  declare one (`@uptimizr/metrics`' `registry.test.ts`). `label` cannot stand in — `mesh_trend`
+  labels rows by mesh.
+- **`reading` is templated, never model-written**, and must never contain `undefined` or `NaN`; run
+  every value through `format.ts`'s total formatters.
+- Report `total`/`share` only for an **additive** unit. Summing FPS, a ratio or a percentile across
+  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).
+- 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.
+
 ## Cross-engine parity (ADR 0020)
 
 The dialect-agnostic aggregations (`buildX(projectId, opts, dialect)`) are rendered per engine

package/README.md

@@ -7,10 +7,17 @@ The OSS storage contracts plus the single-file **DuckDB** store:
   table (hot fields like camera `position`/`direction`, pointer `screen`, `mesh`, `fps` promoted to
   columns; the full event preserved as JSON in `payload` so reads stay replay-complete) plus a
   dedicated `node_samples` table for high-cardinality `node_transform` rows, and `projects` /
-  `api_keys` (stored only as SHA-256 hashes, with `query` / `ingest` capability).
+  `api_keys` (stored only as SHA-256 hashes, each carrying a **capability set** —
+  `query` / `query:raw` / `annotate` / `ingest` — an optional label and an optional per-key rate
+  limit), plus an `agent_audit` trail of what each key asked for (ADR 0051 §7).
 - **Engine-neutral contracts** — the dialect-agnostic query layer (`buildX` + `Dialect`), the
   neutral event-row mappers (`toEventRow`, `toNodeSampleRow`, `formatUtcTimestamp`), and the
-  metadata types (`Project`, `ApiKeyRecord`, `ResolvedApiKey`, `SceneRepresentation*`).
+  metadata types (`Project`, `ApiKeyRecord`, `ResolvedApiKey`, `SceneRepresentation*`,
+  `SceneRegionRecord` / `SceneRegionSummary`).
+- **Scene registry metadata** — `scene_representations` (one proxy per scene) and
+  `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.
 
 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
@@ -63,6 +70,95 @@ CLIs all share one canonical file regardless of which package they run from. The
 its backend with `COLLECTOR_STORE` (`duckdb` by default; `clickhouse` and `memory` are also wired in
 `@uptimizr/collector-server`).
 
+## Metric registry (`@uptimizr/metrics`)
+
+The semantic layer over these aggregations — **what every aggregation means** — lives in its own
+package, [`@uptimizr/metrics`](../metrics). It is a `Readonly<Record<MetricId, MetricDefinition>>`
+with one entry per exported `build*` aggregation (plus two builder-less "resource" entries for the
+session descriptor and the scene representation), declaring the metric's id, title, agent-facing
+description, the builder behind it, its collector endpoint, result `grain`, group-by `dimensions`,
+accepted `filters`, the output `row` schema (Zod), per-column semantics (unit, measure, label,
+`rateOf`), row `limits`, how to read the result (`interpretation`), the `caveats` that make it
+untrustworthy, the capture channels that feed it (`sourceChannels`, ADR 0012), `related` metrics
+and comparison semantics. `DimensionId` and `FilterId` are closed unions declared once, and
+`FILTER_TARGETS` maps each filter to the option field in `query/types.ts` it drives. (ADR 0051 §1.)
+
+```ts
+import { METRIC_REGISTRY, getMetric, allMetrics } from "@uptimizr/metrics";
+
+const metric = getMetric("top_meshes");
+metric?.endpoint; // { method: "GET", path: "/api/v1/meshes/top" }
+metric?.row.parse(row); // validates one result row
+```
+
+It is a **separate package**, not a subpath of this one, because this package depends on
+`@duckdb/node-api` — a ~37 MB native binding — while the registry's consumers
+(`@uptimizr/agent-core`, `@uptimizr/mcp`, `@uptimizr/react`) run in a browser or over `npx` and
+can never use a database driver. `@uptimizr/metrics` imports nothing but `zod` and a _type-only_
+declaration from `@uptimizr/schema`, so it is pure data with no I/O.
+
+### Numbers are numbers (ADR 0051 §2)
+
+Every numeric column in a `row` schema is a strict `z.number()`, because that is what the collector
+actually emits. Engines disagree about the wire — ClickHouse renders 64-bit integers and decimals
+as JSON **strings** over HTTP, `pg` returns `int8`/`numeric` as strings without a type parser — so
+each store's query runner normalises them at the single point rows leave its driver:
+
+```ts
+import { coerceRows, numericColumns } from "@uptimizr/db";
+
+coerceRows("top_meshes", [{ mesh: "box", count: "42" }]); // [{ mesh: "box", count: 42 }]
+numericColumns(getMetric("top_meshes")!.row); // ["count"]
+```
+
+`build*` aggregations tag their `QuerySpec` with the metric id, so `runDuckdbQuery`,
+`runClickhouseQuery`, `runPostgresQuery` and `runMssqlQuery` each apply `coerceRows` with no work
+at the call site. `null` stays `null` — an aggregate over an empty set is "no samples", never `0`.
+A value that is neither a number, `null`, nor a finite numeric string **throws** under a test runner
+and is left untouched with a one-per-column warning in production; pass `{ strict }` to pin either.
+The parity suites assert `typeof === "number"` for every registry-numeric column on every engine.
+
+> **A new aggregation is not done until it has a registry entry.** Add the `build*` name to
+> `AGGREGATION_BUILDER_NAMES` and a `MetricDefinition` to `METRIC_REGISTRY` in
+> `@uptimizr/metrics`; its `NoUnregisteredAggregations` guard fails to typecheck and names the
+> missing builder. This package's `src/__tests__/registry.test.ts` then asserts at runtime that
+> `AGGREGATION_BUILDER_NAMES` is exactly the set of `build*` exports, and parses every `row`
+> schema against real DuckDB output over the parity fixtures; the collector's
+> `registryRoutes.test.ts` asserts that every `endpoint.path` is served and that its Zod
+> querystring keys equal the registry `filters`.
+
+### Result envelopes (`@uptimizr/db/summary`, ADR 0051 §2)
+
+The registry knows enough about a metric to **summarise** it, so the collector's
+`format=table | summary` envelopes are built here rather than in a route handler. Pure, browser-safe
+functions with no store and no I/O — published on their own subpath for the same reason the registry
+is, and re-exported from the package root for Node consumers:
+
+```ts
+import { summarizeRows, tableResult, clusterCells } from "@uptimizr/db/summary";
+
+tableResult("top_meshes", rows, { range, filters, limit });
+// { meta: { metric, range, filters, sampleSize, rows, truncated, limits }, rows }
+
+summarizeRows("top_meshes", rows, { range, filters });
+// { kind: "ranked", total, measure, top: [{ label, value, share, … }], rest, reading, caveats, … }
+```
+
+The metric's `grain` picks the shape: `ranked` top rows for a leaderboard, a `series`
+(first/last/min/max/trend/slope over the column flagged `axis`) for a time bucket, merged `clusters`
+for a `bin`/`voxel` grid (`clusterCells` — a deterministic greedy merge of adjacent occupied cells
+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`.
+
+Two invariants worth knowing before extending it:
+
+- **`reading` is templated, not generated.** It is assembled from `ColumnSemantics` alone, so the
+  same rows always produce the same sentence. Every number goes through total formatters — a
+  `reading` containing `undefined` or `NaN` is a test failure.
+- **Shares are only claimed where they are true.** `total`, `share` and the Wilson `confidence` note
+  appear only when the measure's unit is additive; an FPS or ratio measure reports `null` and says
+  so in the `reading` rather than summing values that cannot be summed.
+
 ## Extending
 
 - **New columns / tables:** append a migration to `DUCKDB_MIGRATIONS`. Forward-only and additive —
@@ -73,7 +169,8 @@ its backend with `COLLECTOR_STORE` (`duckdb` by default; `clickhouse` and `memor
   `QuerySpec` (`{ query, query_params }`) using the `Dialect` fragments (never hard-code
   engine-specific SQL). Run it with `runDuckdbQuery(db, buildX(..., duckdbDialect))`; the scale
   path runs the _same_ builder with `clickhouseDialect`. Add a `PARITY_CASES` entry so both engines
-  stay provably equal. Builders are pure and unit-tested without a live database.
+  stay provably equal, **and a `METRIC_REGISTRY` entry so consumers know what it means**. Builders
+  are pure and unit-tested without a live database.
 
 ## Develop
 

package/dist/cli/createProject.js

@@ -3,6 +3,7 @@ import { createApiKey as duckdbCreateApiKey, createProject as duckdbCreateProjec
 import { createDuckdbClient } from "../duckdb/client.js";
 import { migrateDuckdb } from "../duckdb/migrations.js";
 import { readDbSettings } from "../env.js";
+import { parseCapabilityList } from "../metadata.js";
 /**
  * Create a project and issue an API key, then print the pair. Unlike `seed.ts`
  * (which writes the single demo project into the root `.env`), this CLI is meant
@@ -12,20 +13,36 @@ import { readDbSettings } from "../env.js";
  *
  * ```bash
  * pnpm --filter @uptimizr/db run new-project -- "My Scene"
+ * pnpm --filter @uptimizr/db run new-project -- --capabilities query,query:raw "My Scene"
  * ```
  *
+ * The key is read-only (`query`) by default. Session replay and the live
+ * per-session follow additionally need `query:raw` (#309, ADR 0051 §7), which
+ * the collector only honours when `ENABLE_RAW_SESSION_RETENTION` is on
+ * (ADR 0003).
+ *
  * Targets the OSS DuckDB store.
  */
 async function main() {
-    const name = process.argv
-        .slice(2)
-        .filter((arg) => arg !== "--")
-        .join(" ")
-        .trim() || "Playground Project";
+    const args = process.argv.slice(2).filter((arg) => arg !== "--");
+    let capabilities = ["query"];
+    const words = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--capabilities" || arg.startsWith("--capabilities=")) {
+            const value = arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : args[++i];
+            if (!value)
+                throw new Error("Missing value for --capabilities");
+            capabilities = parseCapabilityList(value);
+            continue;
+        }
+        words.push(arg);
+    }
+    const name = words.join(" ").trim() || "Playground Project";
     const db = await createDuckdbClient(readDbSettings().duckdb.path);
     await migrateDuckdb(db);
     const project = await duckdbCreateProject(db, name);
-    const { key } = await duckdbCreateApiKey(db, project.id);
+    const { key } = await duckdbCreateApiKey(db, project.id, { capabilities });
     await db.close();
     printResult(project.id, project.name, key);
 }

package/dist/cli/createProject.js.map

@@ -1 +1 @@
-{"version":3,"file":"createProject.js","sourceRoot":"","sources":["../../src/cli/createProject.ts"],"names":[],"mappings":";AACA,OAAO,EACL,YAAY,IAAI,kBAAkB,EAClC,aAAa,IAAI,mBAAmB,GACrC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GACR,OAAO,CAAC,IAAI;SACT,KAAK,CAAC,CAAC,CAAC;SACR,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC;SAC7B,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,IAAI,oBAAoB,CAAC;IAEpC,MAAM,EAAE,GAAG,MAAM,kBAAkB,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,aAAa,CAAC,EAAE,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,kBAAkB,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB,EAAE,IAAY,EAAE,MAAc;IAClE,OAAO,CAAC,KAAK,CAAC,sBAAsB,SAAS,KAAK,IAAI,GAAG,CAAC,CAAC;IAC3D,OAAO,CAAC,KAAK,CAAC,kDAAkD,MAAM,EAAE,CAAC,CAAC;IAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"createProject.js","sourceRoot":"","sources":["../../src/cli/createProject.ts"],"names":[],"mappings":";AACA,OAAO,EACL,YAAY,IAAI,kBAAkB,EAClC,aAAa,IAAI,mBAAmB,GACrC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAyB,MAAM,gBAAgB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IACjE,IAAI,YAAY,GAAuB,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,GAAG,KAAK,gBAAgB,IAAI,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;YAClE,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YAC9E,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;YAChE,YAAY,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,oBAAoB,CAAC;IAE5D,MAAM,EAAE,GAAG,MAAM,kBAAkB,CAAC,cAAc,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,aAAa,CAAC,EAAE,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,MAAM,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,kBAAkB,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IAC3E,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;IACjB,WAAW,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAAC,SAAiB,EAAE,IAAY,EAAE,MAAc;IAClE,OAAO,CAAC,KAAK,CAAC,sBAAsB,SAAS,KAAK,IAAI,GAAG,CAAC,CAAC;IAC3D,OAAO,CAAC,KAAK,CAAC,kDAAkD,MAAM,EAAE,CAAC,CAAC;IAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/cli/seed.js

@@ -133,14 +133,24 @@ async function main() {
     const baseName = args[0] ?? "Demo Project";
     const db = await createDuckdbClient(readDbSettings().duckdb.path);
     await migrateDuckdb(db);
+    // Local development seed: the demo projects back the playground + dashboard,
+    // whose session replay and live-follow read raw per-session streams
+    // (`query:raw`, #309, ADR 0051 §7) and whose "Register scene regions" button is
+    // a metadata write (`annotate`). The collector still only honours `query:raw`
+    // when `ENABLE_RAW_SESSION_RETENTION` is on, which the repo's `.env.example`
+    // sets for local dev. This is the same owner set `uptimizr init` /
+    // `uptimizr new-project` mint, and the one `scripts/playground-new.mjs` and
+    // `scripts/scene-new.mjs` already ask for. Narrower, agent-scoped keys come
+    // from `uptimizr new-key`, which still defaults to `query` alone.
+    const devCapabilities = { capabilities: ["query", "query:raw", "annotate"] };
     const viewer = await createProject(db, `${baseName} (Viewer)`);
-    const viewerKey = (await createApiKey(db, viewer.id)).key;
+    const viewerKey = (await createApiKey(db, viewer.id, devCapabilities)).key;
     const walkable = await createProject(db, `${baseName} (Walkable)`);
-    const walkableKey = (await createApiKey(db, walkable.id)).key;
+    const walkableKey = (await createApiKey(db, walkable.id, devCapabilities)).key;
     const showcase = await createProject(db, `${baseName} (Showcase)`);
-    const showcaseKey = (await createApiKey(db, showcase.id)).key;
+    const showcaseKey = (await createApiKey(db, showcase.id, devCapabilities)).key;
     const gallery = await createProject(db, `${baseName} (Gallery)`);
-    const galleryKey = (await createApiKey(db, gallery.id)).key;
+    const galleryKey = (await createApiKey(db, gallery.id, devCapabilities)).key;
     await db.close();
     console.log(`✓ project created: ${viewer.id} (${viewer.name})`);
     console.log(`  API key (store securely, shown once): ${viewerKey}`);

package/dist/cli/seed.js.map

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

package/dist/duckdb/audit.d.ts

@@ -0,0 +1,13 @@
+import { type AgentAuditEntry, type AgentAuditInput, type AuditQueryOptions } from "../metadata.js";
+import type { DuckdbClient } from "./client.js";
+/** Append one audit row. */
+export declare function recordAudit(client: DuckdbClient, entry: AgentAuditInput): Promise<void>;
+/** Read a project's audit rows, newest first, within an optional time range. */
+export declare function listAudit(client: DuckdbClient, projectId: string, opts?: AuditQueryOptions): Promise<AgentAuditEntry[]>;
+/**
+ * Delete audit rows older than `cutoffMs` (epoch ms). Idempotent — deleting an
+ * already-empty range is a no-op — so the collector can run it on a timer.
+ * Returns nothing; the caller only needs to know it did not throw.
+ */
+export declare function pruneAudit(client: DuckdbClient, cutoffMs: number): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/duckdb/audit.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA6ChD,4BAA4B;AAC5B,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB7F;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAC7B,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,eAAe,EAAE,CAAC,CAqB5B;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF"}

package/dist/duckdb/audit.js

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { clampAuditTool, } from "../metadata.js";
+const AUDIT_COLS = `id, project_id, key_id, epoch_ms("at") AS at_ms, surface, tool_or_path,
+            params, row_count, duration_ms, status`;
+function toEntry(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        keyId: row.key_id,
+        at: new Date(Number(row.at_ms)),
+        surface: row.surface,
+        toolOrPath: row.tool_or_path,
+        params: row.params,
+        rowCount: row.row_count == null ? null : Number(row.row_count),
+        durationMs: Number(row.duration_ms),
+        status: Number(row.status),
+    };
+}
+/** Append one audit row. */
+export async function recordAudit(client, entry) {
+    await client.run(`INSERT INTO agent_audit (id, project_id, key_id, "at", surface, tool_or_path, params,
+                              row_count, duration_ms, status)
+     VALUES ($id, $projectId, $keyId, make_timestamp($atUs), $surface, $toolOrPath, $params,
+             CAST($rowCount AS BIGINT), $durationMs, $status)`, {
+        id: randomUUID(),
+        projectId: entry.projectId,
+        keyId: entry.keyId,
+        atUs: (entry.at?.getTime() ?? Date.now()) * 1000,
+        surface: entry.surface,
+        toolOrPath: clampAuditTool(entry.toolOrPath),
+        params: entry.params,
+        rowCount: entry.rowCount ?? null,
+        durationMs: Math.trunc(entry.durationMs),
+        status: Math.trunc(entry.status),
+    });
+}
+/** Read a project's audit rows, newest first, within an optional time range. */
+export async function listAudit(client, projectId, opts = {}) {
+    const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100), 1), 1000);
+    const params = { projectId };
+    const where = ["project_id = $projectId"];
+    if (opts.since != null) {
+        where.push(`"at" >= make_timestamp($since)`);
+        params.since = Math.trunc(opts.since) * 1000;
+    }
+    if (opts.until != null) {
+        where.push(`"at" < make_timestamp($until)`);
+        params.until = Math.trunc(opts.until) * 1000;
+    }
+    const rows = await client.all(`SELECT ${AUDIT_COLS}
+       FROM agent_audit
+      WHERE ${where.join(" AND ")}
+      ORDER BY "at" DESC
+      LIMIT ${limit}`, params);
+    return rows.map(toEntry);
+}
+/**
+ * Delete audit rows older than `cutoffMs` (epoch ms). Idempotent — deleting an
+ * already-empty range is a no-op — so the collector can run it on a timer.
+ * Returns nothing; the caller only needs to know it did not throw.
+ */
+export async function pruneAudit(client, cutoffMs) {
+    await client.run(`DELETE FROM agent_audit WHERE "at" < make_timestamp($cutoff)`, {
+        cutoff: Math.trunc(cutoffMs) * 1000,
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/duckdb/audit.js.map

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

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,CAmUxE,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,CAoaxE,CAAC;AAEF;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE"}

package/dist/duckdb/migrations.js

@@ -331,6 +331,103 @@ export const DUCKDB_MIGRATIONS = [
       ALTER TABLE events ADD COLUMN IF NOT EXISTS near DOUBLE;
     `,
     },
+    // --- Agent-scoped keys (#309, ADR 0051 §7) --------------------------------
+    // The singular `capability` column becomes a capability *set*, stored as a
+    // canonical comma-separated token list in a plain text column (every engine
+    // stores and compares text natively — no JSON type needed). Forward-only and
+    // additive: `0027_api_keys_capability` stays untouched and keeps feeding the
+    // read path as the fallback for any row this backfill has not reached.
+    {
+        id: "0031_api_keys_capabilities",
+        sql: /* sql */ `
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS capabilities VARCHAR;
+    `,
+    },
+    // Idempotent backfill: promote each legacy single capability to a one-element
+    // set, exactly once. Guarded on NULL/'' so re-running the migration on every
+    // boot is a no-op after the first (and never clobbers a key minted with a set).
+    {
+        id: "0032_api_keys_capabilities_backfill",
+        sql: /* sql */ `
+      UPDATE api_keys
+         SET capabilities = coalesce(nullif(capability, ''), 'query')
+       WHERE capabilities IS NULL OR capabilities = '';
+    `,
+    },
+    // Operator-supplied key name (`uptimizr new-key --label "weekly-report-agent"`).
+    {
+        id: "0033_api_keys_label",
+        sql: /* sql */ `
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS label VARCHAR;
+    `,
+    },
+    // Optional per-key request budget. NULL on either half falls back to the
+    // collector's global COLLECTOR_RATE_LIMIT_* defaults.
+    {
+        id: "0034_api_keys_rate_limit_max",
+        sql: /* sql */ `
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS rate_limit_max BIGINT;
+    `,
+    },
+    {
+        id: "0035_api_keys_rate_limit_window_ms",
+        sql: /* sql */ `
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS rate_limit_window_ms BIGINT;
+    `,
+    },
+    // Agent audit log: one row per authenticated request made with a non-dashboard
+    // key. `params` is bounded and redacted before it is written (never the key);
+    // rows expire after AUDIT_RETENTION_DAYS. Metadata, not events — no event type
+    // is added (`@uptimizr/schema` untouched).
+    //
+    // `at` is a DuckDB keyword, so it is double-quoted here and in every accessor
+    // (`duckdb/audit.ts`). The column name matches the other three engines, where
+    // it needs no quoting.
+    {
+        id: "0036_agent_audit",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS agent_audit (
+        id            VARCHAR PRIMARY KEY,
+        project_id    VARCHAR NOT NULL,
+        key_id        VARCHAR NOT NULL,
+        "at"          TIMESTAMP NOT NULL DEFAULT now(),
+        surface       VARCHAR NOT NULL DEFAULT 'http',
+        tool_or_path  VARCHAR NOT NULL,
+        params        VARCHAR NOT NULL DEFAULT '',
+        row_count     BIGINT,
+        duration_ms   BIGINT NOT NULL DEFAULT 0,
+        status        INTEGER NOT NULL DEFAULT 200
+      );
+    `,
+    },
+    {
+        id: "0037_agent_audit_idx",
+        sql: /* sql */ `
+      CREATE INDEX IF NOT EXISTS agent_audit_project_at_idx
+        ON agent_audit (project_id, "at");
+    `,
+    },
+    // Scene regions (ADR 0051 §2 / sketch §B.2): developer-named, labelled boxes
+    // that extend the scene registry (ADR 0014) with a vocabulary for *where* —
+    // "the entrance", "the checkout counter". One row per region, keyed by
+    // (project, scene, region); regions may overlap. `bounds` is JSON text (the
+    // `[minX,…,maxZ]` tuple) parsed by the row mapper, exactly as
+    // `scene_representations.bounds` is.
+    {
+        id: "0038_scene_regions",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS scene_regions (
+        project_id   VARCHAR NOT NULL,
+        scene_id     VARCHAR NOT NULL,
+        region_id    VARCHAR NOT NULL,
+        label        VARCHAR NOT NULL,
+        description  VARCHAR,
+        bounds       VARCHAR NOT NULL,
+        updated_at   TIMESTAMP NOT NULL DEFAULT now(),
+        PRIMARY KEY (project_id, scene_id, region_id)
+      );
+    `,
+    },
 ];
 /**
  * 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/projects.d.ts

@@ -1,4 +1,4 @@
-import { apiKeyPrefix, generateApiKey, hashApiKey, type ApiKeyCapability, type ApiKeyRecord, type Project, type ResolvedApiKey } from "../metadata.js";
+import { apiKeyPrefix, generateApiKey, hashApiKey, type ApiKeyRecord, type CreateApiKeyOptions, type Project, type ResolvedApiKey } from "../metadata.js";
 import type { DuckdbClient } from "./client.js";
 export type { Project, ApiKeyRecord };
 export { hashApiKey, apiKeyPrefix, generateApiKey };
@@ -9,15 +9,19 @@ export declare function getProject(client: DuckdbClient, id: string): Promise<Pr
 /**
  * Issue a new API key for a project. Returns both the record and the plaintext
  * key — the plaintext is shown to the caller exactly once and never stored.
+ *
+ * The legacy singular `capability` column is written alongside the set (its
+ * first token) so a collector still running older code keeps resolving the key.
  */
-export declare function createApiKey(client: DuckdbClient, projectId: string, capability?: ApiKeyCapability): Promise<{
+export declare function createApiKey(client: DuckdbClient, projectId: string, options?: CreateApiKeyOptions): Promise<{
     key: string;
     record: ApiKeyRecord;
 }>;
 /**
- * Resolve a plaintext API key to its (non-revoked) project id and capability, or
- * `null` when the key is unknown or revoked. The collector uses this to
- * authenticate and scope read requests at the boundary.
+ * Resolve a plaintext API key to its (non-revoked) project id, key id,
+ * capability set and per-key rate limit, or `null` when the key is unknown or
+ * revoked. The collector uses this to authenticate and scope requests at the
+ * boundary, and to attribute audit rows to a key without ever logging the key.
  */
 export declare function resolveApiKey(client: DuckdbClient, plaintext: string): Promise<ResolvedApiKey | null>;
 //# sourceMappingURL=projects.d.ts.map