@uptimizr/db-postgres 1.0.2 → 2.0.1

package/AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md — @uptimizr/db-postgres
+
+> Packaged agent guide. For the human reference see [README.md](./README.md); for design
+> rationale see the project ADRs at https://github.com/RaananW/Uptimizr/tree/main/docs/adr.
+
+## What this package is
+
+The optional **single-tenant PostgreSQL store** for the Uptimizr collector — for self-hosters who
+already run Postgres and want a familiar, **multi-writer** relational backend instead of the
+default single-file DuckDB store (ADR 0020).
+
+It is a **re-home + dialect emitter, not a rewrite**. Every analytics aggregation is authored once
+in [`@uptimizr/db`](../db) against the dialect-agnostic query layer
+(`buildX(projectId, opts, dialect)` → `QuerySpec`) and rendered to Postgres SQL with the shared
+`postgresDialect` (also
+exported from `@uptimizr/db`). This package adds a pooled [`pg`](https://node-postgres.com)
+client, forward-only migrations, and metadata helpers that satisfy the same `CollectorStore`
+contract as DuckDB and ClickHouse.
+
+Server/Node only — no DOM imports. Single-tenant only: no `org_id`, no tenant isolation.
+
+## Install / select it
+
+The collector picks a store with `COLLECTOR_STORE`:
+
+```bash
+COLLECTOR_STORE=postgres \
+POSTGRES_URL=postgresql://uptimizr:uptimizr@localhost:5432/uptimizr \
+  npx -p @uptimizr/collector-server uptimizr serve
+```
+
+| Variable                           | Purpose                                                                                |
+| ---------------------------------- | -------------------------------------------------------------------------------------- |
+| `POSTGRES_URL` (or `DATABASE_URL`) | libpq connection URI (`?sslmode=require` etc. apply). The database must already exist. |
+| `POSTGRES_SCHEMA`                  | Schema the store's tables live in (default `public`; created on first boot).           |
+| `POSTGRES_POOL_MAX`                | Maximum pooled connections per collector process (default `10`).                       |
+
+Migrations run on store creation — idempotent, forward-only (ADR 0007) and serialized behind an
+advisory lock, so several collector instances may boot concurrently against one database.
+Postgres 14+ is supported (tested against 16).
+
+`uptimizr init` / `new-project` / `new-key` / `migrate` / `regions` all honour `COLLECTOR_STORE`,
+so export the store + connection variables before running them and the project you mint lives in
+Postgres. A local Postgres is available from [`infra/docker`](../../../infra/docker)
+(`pnpm stack:up`).
+
+## Canonical usage
+
+```ts
+import {
+  createPostgresClient,
+  migratePostgres,
+  insertEvents,
+  getSessionEvents,
+  resolveApiKey,
+  runPostgresQuery,
+} from "@uptimizr/db-postgres";
+import { buildPointerHeatmap, postgresDialect, type HeatmapBinRow } from "@uptimizr/db";
+
+const db = createPostgresClient(settings);
+await migratePostgres(db);
+
+await insertEvents(db, events); // validated upstream at the collector boundary
+const heat = await runPostgresQuery<HeatmapBinRow>(
+  db,
+  buildPointerHeatmap("project-id", { bins: 50 }, postgresDialect),
+);
+```
+
+The `CollectorStore` itself is assembled from these building blocks in the collector server
+(`oss/apps/collector-server/src/postgresStore.ts`, `createPostgresStore`) — this package stays a
+store-agnostic toolkit.
+
+## Rules for agents
+
+- **Never author an aggregation here.** A new aggregation is a pure
+  `buildX(projectId, opts, dialect)` builder in `@uptimizr/db` plus a `@uptimizr/metrics` registry
+  entry. This package only renders and runs.
+- **Migrations are forward-only, additive and idempotent** (ADR 0007). Append to
+  `POSTGRES_MIGRATIONS`; never edit a shipped migration. Keep the advisory lock so concurrent
+  collector boots stay safe.
+- `runPostgresQuery` must call `coerceRows(spec.metric, rows)` at the one point rows leave the
+  driver (ADR 0051 §2) — `pg` hands back `int8` / `numeric` as strings. `null` stays `null`: an
+  aggregate over an empty set is "no samples", not `0`.
+- Postgres has no `ASOF JOIN` and no MergeTree rollups; both are already closed at the **shared**
+  layer (`renderNearestRowJoin` and plain query-time `perf_daily` / `events_daily` views). Reuse
+  those helpers rather than hand-writing a per-query workaround.
+- Validate events upstream at the collector boundary; this layer assumes valid input.
+- API keys are only ever stored as **SHA-256 hashes** — never persist a raw key. Read capability
+  sets with `parseApiKeyCapabilities` and write them with `toApiKeyColumns` (from `@uptimizr/db`)
+  so ordering, validation and the per-key rate-limit columns stay consistent across engines.
+- **The audit log records key ids, never keys.** Serialize parameters with `serializeAuditParams`
+  and clamp the endpoint with `clampAuditTool` before they reach `recordAudit`.
+- Privacy (ADR 0003): no raw IPs, no PII. Raw per-session reads are gated by the collector's
+  `ENABLE_RAW_SESSION_RETENTION` **and** a `query:raw` capability — do not add a bypass here.
+- **Parity is the contract.** The shared `PARITY_EVENTS` / `PARITY_CASES` / `diffParity` harness in
+  `@uptimizr/db` proves every engine returns equal analytics. Extend the fixtures and golden when
+  you add an aggregation or event type, and document any genuine divergence.
+- Identifiers interpolated into DDL go through `assertSafeIdentifier` — never string-concatenate a
+  schema or table name from input.
+
+## Tests and parity
+
+`dialect.test.ts` is a pure unit suite (no server). `postgresParity.test.ts` /
+`postgresStore.test.ts` probe `POSTGRES_URL` (or `DATABASE_URL`) first and **skip when no server is
+reachable**, so the default `pnpm test` stays Docker-free; they use throwaway schemas dropped on
+teardown. Set **`POSTGRES_PARITY_REQUIRED=1`** to fail instead of skipping — that is what the
+"Store parity (Postgres)" CI job does (`pnpm test:parity:postgres` runs them locally with `.env`
+loaded).
+
+## More
+
+- Package reference: [README.md](./README.md)
+- Storage contracts + dialect layer: [`@uptimizr/db`](../db/AGENTS.md)
+- Collector configuration: https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md

package/README.md

@@ -98,8 +98,10 @@ selectPrefix: "SELECT TOP 1", selectSuffix: "" }`.
 | `client.ts`        | Pooled `pg` wrapper (UTC session, schema search path, plain-JS values). |
 | `migrations.ts`    | Forward-only DDL (events, node_samples, metadata, query-time views).    |
 | `events.ts`        | Batched multi-row inserts + replay-complete session reads.              |
-| `projects.ts`      | Project + API-key metadata (SHA-256 hashes).                            |
+| `projects.ts`      | Project + API-key metadata (SHA-256 hashes, capability sets).           |
+| `audit.ts`         | Agent audit log: record / list / prune (`agent_audit`).                 |
 | `sceneRegistry.ts` | Per-`(project, scene)` representation upserts/reads (`ON CONFLICT`).    |
+| `sceneRegions.ts`  | Named scene regions: replace-the-set writes in one transaction.         |
 | `queries.ts`       | `runPostgresQuery` — executes a rendered `QuerySpec`.                   |
 
 The `CollectorStore` itself is assembled from these building blocks in the

package/dist/audit.d.ts

@@ -0,0 +1,12 @@
+import { type AgentAuditEntry, type AgentAuditInput, type AuditQueryOptions } from "@uptimizr/db";
+import type { PostgresClient } from "./client.js";
+/** Append one audit row. */
+export declare function recordAudit(client: PostgresClient, entry: AgentAuditInput): Promise<void>;
+/** Read a project's audit rows, newest first, within an optional time range. */
+export declare function listAudit(client: PostgresClient, projectId: string, opts?: AuditQueryOptions): Promise<AgentAuditEntry[]>;
+/**
+ * Delete audit rows older than `cutoffMs` (epoch ms). Idempotent, so the
+ * collector can run it on a timer.
+ */
+export declare function pruneAudit(client: PostgresClient, cutoffMs: number): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EAEvB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA0ClD,4BAA4B;AAC5B,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB/F;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAC7B,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,eAAe,EAAE,CAAC,CAsB5B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF"}

package/dist/audit.js

@@ -0,0 +1,73 @@
+import { randomUUID } from "node:crypto";
+import { clampAuditTool, } from "@uptimizr/db";
+/**
+ * Agent audit log for the single-tenant Postgres store (#309, ADR 0051 §7).
+ *
+ * Mirrors the DuckDB accessors column-for-column. One row per authenticated
+ * request made with a non-dashboard API key; `params` is redacted and bounded by
+ * the caller before it arrives, and the subject is the key's **id**, never the
+ * key or its hash (ADR 0003).
+ */
+/** `timestamp` → epoch milliseconds. */
+const AT_MS = `(EXTRACT(EPOCH FROM at) * 1000)::bigint`;
+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.query(`INSERT INTO agent_audit (id, project_id, key_id, at, surface, tool_or_path, params,
+                              row_count, duration_ms, status)
+     VALUES ($1, $2, $3, to_timestamp($4::double precision / 1000) AT TIME ZONE 'utc',
+             $5, $6, $7, $8, $9, $10)`, [
+        randomUUID(),
+        entry.projectId,
+        entry.keyId,
+        entry.at?.getTime() ?? Date.now(),
+        entry.surface,
+        clampAuditTool(entry.toolOrPath),
+        entry.params,
+        entry.rowCount ?? null,
+        Math.trunc(entry.durationMs),
+        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 = $1"];
+    if (opts.since != null) {
+        params.push(Math.trunc(opts.since));
+        where.push(`at >= to_timestamp($${params.length}::double precision / 1000) AT TIME ZONE 'utc'`);
+    }
+    if (opts.until != null) {
+        params.push(Math.trunc(opts.until));
+        where.push(`at < to_timestamp($${params.length}::double precision / 1000) AT TIME ZONE 'utc'`);
+    }
+    const rows = await client.query(`SELECT id, project_id, key_id, ${AT_MS} AS at_ms, surface, tool_or_path, params,
+            row_count, duration_ms, status
+       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, so the
+ * collector can run it on a timer.
+ */
+export async function pruneAudit(client, cutoffMs) {
+    await client.query(`DELETE FROM agent_audit WHERE at < to_timestamp($1::double precision / 1000) AT TIME ZONE 'utc'`, [Math.trunc(cutoffMs)]);
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

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

package/dist/index.d.ts

@@ -18,6 +18,9 @@ export { insertEvents, getSessionEvents, streamSessionEvents, getSessionMeta } f
 export type { SessionMeta } from "./events.js";
 export { createProject, getProject, createApiKey, resolveApiKey, hashApiKey, apiKeyPrefix, generateApiKey, } from "./projects.js";
 export type { Project, ApiKeyRecord } from "./projects.js";
+export { recordAudit, listAudit, pruneAudit } from "./audit.js";
 export { upsertSceneProxy, getSceneRepresentation, listSceneRepresentations, } from "./sceneRegistry.js";
 export type { SceneRepresentation, SceneRepresentationKind, SceneRepresentationSummary, } from "./sceneRegistry.js";
+export { putSceneRegions, getSceneRegions, listSceneRegions } from "./sceneRegions.js";
+export type { SceneRegionRecord, SceneRegionSummary } from "./sceneRegions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEjF,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -15,5 +15,7 @@ export { POSTGRES_MIGRATIONS, migratePostgres } from "./migrations.js";
 export { runPostgresQuery } from "./queries.js";
 export { insertEvents, getSessionEvents, streamSessionEvents, getSessionMeta } from "./events.js";
 export { createProject, getProject, createApiKey, resolveApiKey, hashApiKey, apiKeyPrefix, generateApiKey, } from "./projects.js";
+export { recordAudit, listAudit, pruneAudit } from "./audit.js";
 export { upsertSceneProxy, getSceneRepresentation, listSceneRepresentations, } from "./sceneRegistry.js";
+export { putSceneRegions, getSceneRegions, listSceneRegions } from "./sceneRegions.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlG,OAAO,EACL,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGzE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlG,OAAO,EACL,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAuL1E,CAAC;AASF;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA0P1E,CAAC;AASF;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/migrations.js

@@ -213,6 +213,73 @@ export const POSTGRES_MIGRATIONS = [
       GROUP BY project_id, event_type, CAST(ts AS DATE);
     `,
     },
+    // --- 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 (mirrors the
+    // DuckDB store, so no engine needs a JSON type). Forward-only and additive:
+    // `0007_api_keys` is untouched and its column keeps feeding the read path as
+    // the fallback for any row this backfill has not reached.
+    {
+        id: "0011_api_keys_capabilities",
+        sql: /* sql */ `
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS capabilities text;
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS label text;
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS rate_limit_max bigint;
+      ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS rate_limit_window_ms bigint;
+    `,
+    },
+    // Idempotent backfill: promote each legacy single capability to a one-element
+    // set, exactly once. Guarded on NULL/'' so re-running on every boot is a no-op
+    // after the first (and never clobbers a key minted with a set).
+    {
+        id: "0012_api_keys_capabilities_backfill",
+        sql: /* sql */ `
+      UPDATE api_keys
+         SET capabilities = coalesce(nullif(capability, ''), 'query')
+       WHERE capabilities IS NULL OR capabilities = '';
+    `,
+    },
+    // 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.
+    {
+        id: "0013_agent_audit",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS agent_audit (
+        id            text PRIMARY KEY,
+        project_id    text NOT NULL,
+        key_id        text NOT NULL,
+        at            timestamp NOT NULL DEFAULT (now() AT TIME ZONE 'utc'),
+        surface       text NOT NULL DEFAULT 'http',
+        tool_or_path  text NOT NULL,
+        params        text NOT NULL DEFAULT '',
+        row_count     bigint,
+        duration_ms   bigint NOT NULL DEFAULT 0,
+        status        integer NOT NULL DEFAULT 200
+      );
+      CREATE INDEX IF NOT EXISTS agent_audit_project_at_idx ON agent_audit (project_id, at DESC);
+    `,
+    },
+    // Scene regions (ADR 0051 §2 / sketch §B.2): developer-named, labelled boxes
+    // that extend the scene registry (ADR 0014) with a vocabulary for *where*.
+    // 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: "0014_scene_regions",
+        sql: /* sql */ `
+      CREATE TABLE IF NOT EXISTS scene_regions (
+        project_id   text NOT NULL,
+        scene_id     text NOT NULL,
+        region_id    text NOT NULL,
+        label        text NOT NULL,
+        description  text,
+        bounds       text NOT NULL,
+        updated_at   timestamp NOT NULL DEFAULT (now() AT TIME ZONE 'utc'),
+        PRIMARY KEY (project_id, scene_id, region_id)
+      );
+    `,
+    },
 ];
 /**
  * Stable advisory-lock key that serializes concurrent boots of several

package/dist/migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAuB,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA+C;IAC7E,6EAA6E;IAC7E;QACE,EAAE,EAAE,aAAa;QACjB,GAAG,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KA2Cd;KACF;IACD;QACE,EAAE,EAAE,yBAAyB;QAC7B,GAAG,EAAE,SAAS,CAAC;;;KAGd;KACF;IACD,yEAAyE;IACzE,wEAAwE;IACxE,mDAAmD;IACnD;QACE,EAAE,EAAE,4BAA4B;QAChC,GAAG,EAAE,SAAS,CAAC;;;KAGd;KACF;IACD,6EAA6E;IAC7E,6EAA6E;IAC7E,4EAA4E;IAC5E,uEAAuE;IACvE,gEAAgE;IAChE;QACE,EAAE,EAAE,mBAAmB;QACvB,GAAG,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;KAed;KACF;IACD;QACE,EAAE,EAAE,uBAAuB;QAC3B,GAAG,EAAE,SAAS,CAAC;;;KAGd;KACF;IACD,8EAA8E;IAC9E;QACE,EAAE,EAAE,eAAe;QACnB,GAAG,EAAE,SAAS,CAAC;;;;;;KAMd;KACF;IACD,wEAAwE;IACxE,wEAAwE;IACxE;QACE,EAAE,EAAE,eAAe;QACnB,GAAG,EAAE,SAAS,CAAC;;;;;;;;;;KAUd;KACF;IACD,8EAA8E;IAC9E,4EAA4E;IAC5E,iEAAiE;IACjE;QACE,EAAE,EAAE,4BAA4B;QAChC,GAAG,EAAE,SAAS,CAAC;;;;;;;;;;;;;;;;;KAiBd;KACF;IACD,6EAA6E;IAC7E,+DAA+D;IAC/D,wEAAwE;IACxE,6EAA6E;IAC7E,6EAA6E;IAC7E,yEAAyE;IACzE;QACE,EAAE,EAAE,sBAAsB;QAC1B,GAAG,EAAE,SAAS,CAAC;;;;;;;;;;;;KAYd;KACF;IACD;QACE,EAAE,EAAE,wBAAwB;QAC5B,GAAG,EAAE,SAAS,CAAC;;;;;;;;;KASd;KACF;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,WAAW,CAAC,CAAC,SAAS;AAEjD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAsB,EACtB,QAA0B;IAE1B,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrD,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QACpC,MAAM,EAAE,CAAC,OAAO,CAAC,gCAAgC,kBAAkB,GAAG,CAAC,CAAC;QACxE,MAAM,EAAE,CAAC,OAAO,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QAC1D,KAAK,MAAM,SAAS,IAAI,mBAAmB,EAAE,CAAC;YAC5C,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"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"}

package/dist/projects.d.ts

@@ -1,4 +1,4 @@
-import { apiKeyPrefix, generateApiKey, hashApiKey, type ApiKeyCapability, type ApiKeyRecord, type Project, type ResolvedApiKey } from "@uptimizr/db";
+import { apiKeyPrefix, generateApiKey, hashApiKey, type ApiKeyRecord, type CreateApiKeyOptions, type Project, type ResolvedApiKey } from "@uptimizr/db";
 import type { PostgresClient } from "./client.js";
 export type { Project, ApiKeyRecord };
 export { hashApiKey, apiKeyPrefix, generateApiKey };
@@ -9,15 +9,19 @@ export declare function getProject(client: PostgresClient, id: string): Promise<
 /**
  * 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: PostgresClient, projectId: string, capability?: ApiKeyCapability): Promise<{
+export declare function createApiKey(client: PostgresClient, 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: PostgresClient, plaintext: string): Promise<ResolvedApiKey | null>;
 //# sourceMappingURL=projects.d.ts.map

package/dist/projects.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../src/projects.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,cAAc,EACd,UAAU,EACV,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAwBpD,sCAAsC;AACtC,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO1F;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAO5F;AAWD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,gBAA0B,GACrC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CAqBhD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAOhC"}
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../src/projects.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EACZ,cAAc,EACd,UAAU,EAIV,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAwBpD,sCAAsC;AACtC,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO1F;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAO5F;AAqCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,CAAC,CAqBhD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAehC"}

package/dist/projects.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { apiKeyPrefix, generateApiKey, hashApiKey, } from "@uptimizr/db";
+import { apiKeyPrefix, generateApiKey, hashApiKey, parseApiKeyCapabilities, toApiKeyColumns, toApiKeyRateLimit, } from "@uptimizr/db";
 export { hashApiKey, apiKeyPrefix, generateApiKey };
 /**
  * Project + API-key metadata for the single-tenant Postgres store (ADR 0020).
@@ -26,37 +26,67 @@ export async function getProject(client, id) {
     const row = rows[0];
     return row ? toProject(row) : null;
 }
+/** Columns every API-key read selects, mapped by {@link toApiKeyRecord}. */
+const API_KEY_COLS = `id, project_id, key_prefix, ${EPOCH_MS("created_at")} AS created_at_ms,
+               ${EPOCH_MS("revoked_at")} AS revoked_at_ms, capability, capabilities, label,
+               rate_limit_max, rate_limit_window_ms`;
+function toApiKeyRecord(row) {
+    return {
+        id: row.id,
+        projectId: row.project_id,
+        keyPrefix: row.key_prefix,
+        createdAt: new Date(row.created_at_ms),
+        revokedAt: row.revoked_at_ms == null ? null : new Date(row.revoked_at_ms),
+        capabilities: parseApiKeyCapabilities(row.capabilities, row.capability),
+        label: row.label ?? null,
+        // `bigint` arrives as a string from node-postgres; `toApiKeyRateLimit` coerces.
+        rateLimit: toApiKeyRateLimit(row.rate_limit_max == null ? null : Number(row.rate_limit_max), row.rate_limit_window_ms == null ? null : Number(row.rate_limit_window_ms)),
+    };
+}
 /**
  * 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 async function createApiKey(client, projectId, capability = "query") {
+export async function createApiKey(client, projectId, options = {}) {
     const key = generateApiKey();
-    const rows = await client.query(`INSERT INTO api_keys (id, project_id, key_hash, key_prefix, capability)
-     VALUES ($1, $2, $3, $4, $5)
-     RETURNING id, project_id, key_prefix, ${EPOCH_MS("created_at")} AS created_at_ms,
-               ${EPOCH_MS("revoked_at")} AS revoked_at_ms, capability`, [randomUUID(), projectId, hashApiKey(key), apiKeyPrefix(key), capability]);
-    const row = rows[0];
-    return {
-        key,
-        record: {
-            id: row.id,
-            projectId: row.project_id,
-            keyPrefix: row.key_prefix,
-            createdAt: new Date(row.created_at_ms),
-            revokedAt: row.revoked_at_ms == null ? null : new Date(row.revoked_at_ms),
-            capability: row.capability,
-        },
-    };
+    const cols = toApiKeyColumns(options);
+    const rows = await client.query(`INSERT INTO api_keys (id, project_id, key_hash, key_prefix, capability, capabilities,
+                           label, rate_limit_max, rate_limit_window_ms)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+     RETURNING ${API_KEY_COLS}`, [
+        randomUUID(),
+        projectId,
+        hashApiKey(key),
+        apiKeyPrefix(key),
+        cols.capabilities.split(",")[0],
+        cols.capabilities,
+        cols.label,
+        cols.rateLimitMax,
+        cols.rateLimitWindowMs,
+    ]);
+    return { key, record: toApiKeyRecord(rows[0]) };
 }
 /**
- * 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 async function resolveApiKey(client, plaintext) {
-    const rows = await client.query(`SELECT project_id, capability FROM api_keys WHERE key_hash = $1 AND revoked_at IS NULL`, [hashApiKey(plaintext)]);
+    const rows = await client.query(`SELECT ${API_KEY_COLS} FROM api_keys WHERE key_hash = $1 AND revoked_at IS NULL`, [hashApiKey(plaintext)]);
     const row = rows[0];
-    return row ? { projectId: row.project_id, capability: row.capability } : null;
+    if (!row)
+        return null;
+    const record = toApiKeyRecord(row);
+    return {
+        projectId: record.projectId,
+        keyId: record.id,
+        capabilities: record.capabilities,
+        label: record.label,
+        rateLimit: record.rateLimit,
+    };
 }
 //# sourceMappingURL=projects.js.map

package/dist/projects.js.map

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

package/dist/queries.d.ts

@@ -8,6 +8,12 @@ import type { PostgresClient } from "./client.js";
  * reuses with `@p1…`). The client's type parsers return plain-JS values
  * (64-bit integers and numerics as numbers, arrays as arrays), so rows match the
  * shapes produced by the DuckDB `runDuckdbQuery`.
+ *
+ * This is the single point where rows leave the `pg` driver, so it is where
+ * {@link coerceRows} runs (ADR 0051 §2): `pg` hands back `int8`/`numeric` as
+ * strings unless a type parser is registered for the OID, so the guarantee that a
+ * numeric column *is* a number belongs to the store, not to a parser
+ * registration that a future column type could sidestep.
  */
 export declare function runPostgresQuery<T>(client: PostgresClient, spec: QuerySpec): Promise<T[]>;
 //# sourceMappingURL=queries.d.ts.map

package/dist/queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAG/F"}
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAI/F"}

package/dist/queries.js

@@ -1,4 +1,4 @@
-import { toPositionalParams } from "@uptimizr/db";
+import { coerceRows, toPositionalParams } from "@uptimizr/db";
 /**
  * Execute a dialect-agnostic {@link QuerySpec} (rendered with `postgresDialect`)
  * against the Postgres store and return typed rows. The dialect emits named
@@ -7,9 +7,16 @@ import { toPositionalParams } from "@uptimizr/db";
  * reuses with `@p1…`). The client's type parsers return plain-JS values
  * (64-bit integers and numerics as numbers, arrays as arrays), so rows match the
  * shapes produced by the DuckDB `runDuckdbQuery`.
+ *
+ * This is the single point where rows leave the `pg` driver, so it is where
+ * {@link coerceRows} runs (ADR 0051 §2): `pg` hands back `int8`/`numeric` as
+ * strings unless a type parser is registered for the OID, so the guarantee that a
+ * numeric column *is* a number belongs to the store, not to a parser
+ * registration that a future column type could sidestep.
  */
 export async function runPostgresQuery(client, spec) {
     const { sql, values } = toPositionalParams(spec.query, spec.query_params, (i) => `$${i}`);
-    return client.query(sql, values);
+    const rows = await client.query(sql, values);
+    return coerceRows(spec.metric, rows);
 }
 //# sourceMappingURL=queries.js.map

package/dist/queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAkB,MAAM,cAAc,CAAC;AAGlE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,MAAsB,EAAE,IAAe;IAC/E,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1F,OAAO,MAAM,CAAC,KAAK,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAkB,MAAM,cAAc,CAAC;AAG9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAI,MAAsB,EAAE,IAAe;IAC/E,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;IAChD,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACvC,CAAC"}

package/dist/sceneRegions.d.ts

@@ -0,0 +1,18 @@
+import type { SceneRegionRecord, SceneRegionSummary } from "@uptimizr/db";
+import type { SceneRegion } from "@uptimizr/schema";
+import type { PostgresClient } from "./client.js";
+export type { SceneRegionRecord, SceneRegionSummary };
+/**
+ * Replace the whole region set of `(projectId, sceneId)` with `regions` and
+ * return the stored rows. The delete + inserts run in one transaction, so a
+ * concurrent reader never sees a half-replaced set.
+ */
+export declare function putSceneRegions(client: PostgresClient, projectId: string, sceneId: string, regions: readonly SceneRegion[]): Promise<SceneRegionRecord[]>;
+/** Read one scene's regions, ordered by region id (stable for callers/diffs). */
+export declare function getSceneRegions(client: PostgresClient, projectId: string, sceneId: string): Promise<SceneRegionRecord[]>;
+/**
+ * Project-wide region names (no boxes) — the whole spatial vocabulary in one
+ * read, for a scene/region picker or an agent's project context.
+ */
+export declare function listSceneRegions(client: PostgresClient, projectId: string): Promise<SceneRegionSummary[]>;
+//# sourceMappingURL=sceneRegions.d.ts.map

package/dist/sceneRegions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneRegions.d.ts","sourceRoot":"","sources":["../src/sceneRegions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAEpE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAC;AAiDtD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,WAAW,EAAE,GAC9B,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAuB9B;AAED,iFAAiF;AACjF,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAE9B;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAY/B"}

package/dist/sceneRegions.js

@@ -0,0 +1,64 @@
+const SELECT_COLS = `project_id, scene_id, region_id, label, description, bounds,
+       (EXTRACT(EPOCH FROM updated_at) * 1000)::bigint AS updated_at_ms`;
+function rowToRegion(row) {
+    return {
+        projectId: row.project_id,
+        sceneId: row.scene_id,
+        regionId: row.region_id,
+        label: row.label,
+        description: row.description,
+        bounds: JSON.parse(row.bounds),
+        updatedAt: new Date(row.updated_at_ms),
+    };
+}
+async function selectRegions(executor, projectId, sceneId) {
+    const rows = await executor.query(`SELECT ${SELECT_COLS} FROM scene_regions
+     WHERE project_id = $1 AND scene_id = $2
+     ORDER BY region_id`, [projectId, sceneId]);
+    return rows.map(rowToRegion);
+}
+/**
+ * Replace the whole region set of `(projectId, sceneId)` with `regions` and
+ * return the stored rows. The delete + inserts run in one transaction, so a
+ * concurrent reader never sees a half-replaced set.
+ */
+export async function putSceneRegions(client, projectId, sceneId, regions) {
+    return client.transaction(async (tx) => {
+        await tx.query(`DELETE FROM scene_regions WHERE project_id = $1 AND scene_id = $2`, [
+            projectId,
+            sceneId,
+        ]);
+        for (const region of regions) {
+            await tx.query(`INSERT INTO scene_regions
+           (project_id, scene_id, region_id, label, description, bounds, updated_at)
+         VALUES ($1, $2, $3, $4, $5, $6, (now() AT TIME ZONE 'utc'))`, [
+                projectId,
+                sceneId,
+                region.id,
+                region.label,
+                region.description ?? null,
+                JSON.stringify(region.bounds),
+            ]);
+        }
+        return selectRegions(tx, projectId, sceneId);
+    });
+}
+/** Read one scene's regions, ordered by region id (stable for callers/diffs). */
+export async function getSceneRegions(client, projectId, sceneId) {
+    return selectRegions(client, projectId, sceneId);
+}
+/**
+ * Project-wide region names (no boxes) — the whole spatial vocabulary in one
+ * read, for a scene/region picker or an agent's project context.
+ */
+export async function listSceneRegions(client, projectId) {
+    const rows = await client.query(`SELECT scene_id, region_id, label FROM scene_regions
+     WHERE project_id = $1
+     ORDER BY scene_id, region_id`, [projectId]);
+    return rows.map((row) => ({
+        sceneId: row.scene_id,
+        regionId: row.region_id,
+        label: row.label,
+    }));
+}
+//# sourceMappingURL=sceneRegions.js.map

package/dist/sceneRegions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneRegions.js","sourceRoot":"","sources":["../src/sceneRegions.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,GAAG;wEACoD,CAAC;AAEzE,SAAS,WAAW,CAAC,GAAc;IACjC,OAAO;QACL,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAS;QACtC,SAAS,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC;KACvC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,QAA0B,EAC1B,SAAiB,EACjB,OAAe;IAEf,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,KAAK,CAC/B,UAAU,WAAW;;wBAED,EACpB,CAAC,SAAS,EAAE,OAAO,CAAC,CACrB,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAsB,EACtB,SAAiB,EACjB,OAAe,EACf,OAA+B;IAE/B,OAAO,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QACrC,MAAM,EAAE,CAAC,KAAK,CAAC,mEAAmE,EAAE;YAClF,SAAS;YACT,OAAO;SACR,CAAC,CAAC;QACH,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,EAAE,CAAC,KAAK,CACZ;;qEAE6D,EAC7D;gBACE,SAAS;gBACT,OAAO;gBACP,MAAM,CAAC,EAAE;gBACT,MAAM,CAAC,KAAK;gBACZ,MAAM,CAAC,WAAW,IAAI,IAAI;gBAC1B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;aAC9B,CACF,CAAC;QACJ,CAAC;QACD,OAAO,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,MAAsB,EACtB,SAAiB,EACjB,OAAe;IAEf,OAAO,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAsB,EACtB,SAAiB;IAEjB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAC7B;;kCAE8B,EAC9B,CAAC,SAAS,CAAC,CACZ,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,OAAO,EAAE,GAAG,CAAC,QAAQ;QACrB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC,CAAC,CAAC;AACN,CAAC"}

package/llms.txt

@@ -0,0 +1,31 @@
+# @uptimizr/db-postgres
+
+> The optional single-tenant PostgreSQL store for the Uptimizr collector (ADR 0020) — a familiar,
+> multi-writer relational backend for teams that already run Postgres. A re-home + dialect
+> emitter, not a rewrite: every aggregation is authored once in `@uptimizr/db` and rendered with
+> the shared `postgresDialect`. Server/Node only; select it with `COLLECTOR_STORE=postgres`.
+
+## Docs
+
+- [Package reference](./README.md): when to use it, env vars, the row-store fit gaps and how they are closed, file layout.
+- [Agent guide](./AGENTS.md): rules, canonical usage, parity and the `POSTGRES_PARITY_REQUIRED` gate.
+- [Storage contracts + query layer](../db/README.md): `@uptimizr/db`, the `buildX`/`Dialect` layer, the parity harness.
+- [Collector configuration](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): `COLLECTOR_STORE` and the HTTP API.
+- [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): database choice (0002), privacy model (0003), migrations (0007), open-core storage boundary (0020), AI-first analytics layer (0051).
+
+## Environment
+
+- `COLLECTOR_STORE=postgres` selects this store.
+- `POSTGRES_URL` (or `DATABASE_URL`) — libpq URI; the database must already exist. Postgres 14+.
+- `POSTGRES_SCHEMA` (default `public`, created on first boot), `POSTGRES_POOL_MAX` (default `10`).
+- `POSTGRES_PARITY_REQUIRED=1` makes the live parity suites fail instead of skipping (the CI job sets it).
+
+## Key exports
+
+- Client: `createPostgresClient(settings)`, `assertSafeIdentifier`, types `PostgresClient` / `PostgresExecutor` / `PostgresRow`.
+- Migrations: `POSTGRES_MIGRATIONS`, `migratePostgres(client)` — forward-only, idempotent, advisory-locked (ADR 0007).
+- Queries: `runPostgresQuery(client, spec)` — rewrites named to positional params and coerces numeric columns at the driver edge (ADR 0051 §2).
+- Events: `insertEvents`, `getSessionEvents`, `streamSessionEvents`, `getSessionMeta`.
+- Metadata: `createProject`, `getProject`, `createApiKey`, `resolveApiKey`, `hashApiKey`, `apiKeyPrefix`, `generateApiKey` (keys stored only as SHA-256 hashes).
+- Audit: `recordAudit`, `listAudit`, `pruneAudit` (key ids, never keys).
+- Scene registry: `upsertSceneProxy`, `getSceneRepresentation`, `listSceneRepresentations`, `putSceneRegions`, `getSceneRegions`, `listSceneRegions`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimizr/db-postgres",
-  "version": "1.0.2",
+  "version": "2.0.1",
   "description": "Optional single-tenant PostgreSQL store for Uptimizr — composes the @uptimizr/db dialect-agnostic query layer and CollectorStore contract for self-hosters who already run Postgres and want a multi-writer relational backend.",
   "keywords": [
     "uptimizr",
@@ -36,12 +36,14 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "AGENTS.md",
+    "llms.txt"
   ],
   "dependencies": {
     "pg": "^8.23.0",
-    "@uptimizr/db": "1.0.2",
-    "@uptimizr/schema": "1.0.1"
+    "@uptimizr/db": "2.0.0",
+    "@uptimizr/schema": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",