@agent-native/core 0.90.10 → 0.91.0

package/corpus/templates/analytics/docs/error-capture.md

@@ -0,0 +1,172 @@
+# Error capture
+
+First-party, Sentry-style exception tracking built into the analytics product.
+The browser SDK automatically captures uncaught exceptions and unhandled
+promise rejections, exposes a manual `captureException` / `captureMessage` API,
+and links every error to the **session replay** it happened in. Captured errors
+are grouped into **issues** by fingerprint and triaged under **Monitoring →
+Errors**.
+
+## How it works
+
+```
+Browser SDK  ──$exception──▶  /api/analytics/track  ──▶  error_issues + error_events
+(auto + manual capture)      (first-party ingest fork)     (grouped issues + occurrences)
+       │                                                          │
+       └── session replay id (localStorage) ───────────────────▶ linked to /sessions/<id>
+```
+
+- **Capture** happens in the analytics client SDK
+  (`@agent-native/core/client`), installed by `configureTracking`.
+- **Transport** reuses the existing first-party analytics ingest: exceptions are
+  sent as a dedicated `$exception` event using the same public-key auth and
+  `sendBeacon`/`keepalive` transport as pageviews. No extra endpoint, CORS, or
+  key to configure.
+- **Server** forks `$exception` events out of the analytics batch, parses the
+  stack, computes a stable fingerprint, upserts the grouped issue, appends the
+  occurrence, and links the session replay. The event is still recorded in
+  `analytics_events`, so existing alerting keeps working.
+
+## Enabling capture
+
+Templates already call `configureTracking`. Error capture **auto-enables**
+whenever a first-party analytics public key is configured (the same trigger as
+pageview tracking and session replay). To be explicit or to tune it:
+
+```ts
+import { configureTracking } from "@agent-native/core/client";
+
+configureTracking({
+  key: "anpk_...", // first-party analytics public key
+  endpoint: "https://analytics.example.com/api/analytics/track",
+  errorCapture: true, // or an options object; pass `false` to disable
+});
+```
+
+Options (`errorCapture` object form):
+
+| Option                       | Default     | Description                                   |
+| ---------------------------- | ----------- | --------------------------------------------- |
+| `release`                    | `undefined` | Build/release id attached to every exception. |
+| `environment`                | Vite `MODE` | Deployment environment (e.g. `production`).   |
+| `captureGlobalErrors`        | `true`      | Auto-capture `window.onerror`.                |
+| `captureUnhandledRejections` | `true`      | Auto-capture `unhandledrejection`.            |
+| `maxBreadcrumbs`             | `20`        | Breadcrumb ring-buffer size.                  |
+
+> Exceptions are only transmitted from non-local hostnames (same rule as the
+> rest of first-party analytics). In local dev the handlers still install, but
+> nothing is sent — use the **Send test error** button or the
+> `capture-test-error` action to exercise the pipeline end to end.
+
+## Automatic capture
+
+Once installed, the SDK listens for:
+
+- **`window.onerror`** — uncaught synchronous and asynchronous errors.
+- **`unhandledrejection`** — promise rejections with no `.catch`.
+
+Each is normalized into `{ type, message, stack, url, handled, level, … }`,
+redacted, deduped (identical signatures within a short window are dropped), and
+sent. The session replay recorder already logs these to the replay timeline, so
+auto-captured errors are **not** re-emitted onto the timeline to avoid
+double-counting.
+
+## Manual API (Sentry-style)
+
+```ts
+import { captureException, captureMessage } from "@agent-native/core/client";
+
+try {
+  doRiskyThing();
+} catch (err) {
+  captureException(err, {
+    level: "error",
+    tags: { area: "checkout", plan: "pro" },
+    extra: { cartId, itemCount },
+  });
+}
+
+captureMessage("Payment webhook retried", "warning");
+```
+
+- `captureException(error, context?)` — `context` accepts `tags` (low-cardinality
+  strings), `extra` (structured detail), and `level`
+  (`fatal | error | warning | info | debug`, default `error`).
+- `captureMessage(message, level?)` — capture a string as an exception-like
+  event (default level `info`).
+- `addErrorBreadcrumb({ category, message, level? })` — add a privacy-safe
+  breadcrumb to the bounded trail attached to the next captured error.
+
+Manual captures **are** surfaced on the active session replay timeline as a
+custom event, so they show up when you watch the replay.
+
+Both functions are safe to call before `configureTracking` runs (they no-op
+until transport is installed) and never throw back into your app.
+
+## Session replay linkage
+
+The SDK reads the current session replay id from `localStorage`
+(`agent-native.session_replay_id`) and attaches it to each exception. At ingest
+the server resolves it to the real recording (`sr_...`) and stores it on the
+occurrence and the issue (`lastSessionRecordingId`). In the Errors UI, each
+issue and occurrence with a linked replay shows a **Watch session replay** link
+straight to `/sessions/<recordingId>`, so you can watch what the user did right
+before the error.
+
+The link goes both ways. When you watch a recording and open its devtools
+**Console** panel, any captured error line (uncaught exceptions, unhandled
+rejections, manual `captureException`) gets a **View issue** link straight to
+its grouped issue detail (`/monitoring?view=errors&issue=<id>`) — how many users
+hit it, the stack trace, and recent occurrences. Resolution is exact, not
+heuristic: the `match-error-issues` action recomputes each console line's
+fingerprint with the same helpers used at ingest and looks it up under access
+scope, so a link only appears when the error was actually captured as an issue.
+
+## Privacy & redaction
+
+- Messages and stacks are scrubbed for credential-looking values
+  (`Authorization`, `Cookie`, `token`, `apiKey`, bearer/basic tokens, …) before
+  they leave the browser, reusing the same redaction as replay capture.
+- URLs are scrubbed of query strings/tokens.
+- Breadcrumbs are bounded (ring buffer) and only record navigation + explicit
+  messages — no DOM values or input contents.
+- Payloads are size-bounded (message, stack, tags, extra, breadcrumbs).
+
+## Data model
+
+Two additive, owner-scoped tables (`server/db/schema-errors.ts`):
+
+- **`error_issues`** — one row per fingerprint per owner scope. `ownableColumns()`
+  - `error_issue_shares`, so an org-scoped analytics key surfaces issues to the
+    whole org via `accessFilter` (mirrors `session_recordings`). Tracks status
+    (`unresolved | resolved | ignored`), counts, first/last seen, users affected,
+    culprit/title, and the last linked recording.
+- **`error_events`** — individual occurrences (owner-scoped like
+  `analytics_events`), pruned to a bounded retention per issue so occurrences
+  can't grow unbounded. Stores normalized stack frames, breadcrumbs, tags/extra,
+  and the resolved session recording.
+
+Grouping keys off error type + top in-app stack frame (function + normalized
+file, ignoring line/column so small edits don't split a group), falling back to
+a normalized message when there is no usable stack. A resolved issue is
+automatically **reopened** when it recurs; **ignored** issues stay muted.
+
+## How the agent triages issues
+
+The agent uses the same owner-scoped actions the UI does:
+
+- **`list-error-issues`** — list grouped issues, filter by status, search, sort
+  by last seen / event count / first seen.
+- **`get-error-issue`** — one issue with recent occurrences (parsed stack
+  frames, breadcrumbs, tags/extra) and links to the session replays where it
+  happened.
+- **`resolve-error-issue`** — set status (`unresolved` / `resolved` / `ignored`)
+  and optionally (re)assign a triage owner.
+- **`capture-test-error`** — generate a sample captured error to verify the
+  pipeline end to end.
+- **`match-error-issues`** — resolve a batch of session console error lines
+  (message/stack/source) to their captured issue ids, so a session recording can
+  deep-link to issue detail. Read-only; fingerprints match ingest exactly.
+
+New issues also raise a best-effort inbox notification (via
+`notifyWithDelivery`) so a fresh error surfaces without opening the dashboard.

package/corpus/templates/analytics/docs/uptime-monitoring.md

@@ -0,0 +1,150 @@
+# Uptime monitoring
+
+Uptime monitoring lets you create **monitors** — synthetic HTTP checks that ping
+a URL on a schedule and alert you (or others) when something is wrong:
+
+- the URL is **unreachable** or **times out**,
+- it returns a **non-expected status** (e.g. a `5xx` when you expect `2xx`),
+- it is **too slow** (a latency budget you set), or
+- its response body is **missing expected text** or **contains forbidden text**.
+
+It reuses the same notification pipeline as the analytics alert rules, so alerts
+land in the in-app inbox and can also fan out to email, Slack, and webhooks.
+
+The feature lives under **Monitoring → Uptime** (`/monitoring?view=uptime`). A
+selected monitor is reflected in the URL as `?view=uptime&monitor=<id>` so links
+are shareable and the agent can deep-link a monitor.
+
+## How a check works
+
+Each check runs on the server (`server/lib/uptime-monitors.ts`):
+
+1. Fetch the monitor's `url` with the configured `method`, headers, and body,
+   through an SSRF-safe path, with an `AbortController` timeout.
+2. Measure latency and read up to **512 KB** of the response body (skipped for
+   `HEAD`).
+3. Evaluate the **status matcher** and every **assertion**.
+4. Classify the result:
+   - `up` — status matches and all assertions pass.
+   - `degraded` — status matches but only a `max_latency_ms` assertion fails
+     (the endpoint responded, just too slowly). Alerts at `warning` severity.
+   - `down` — the status does not match, a content/header assertion fails, or
+     the request errored/timed out. Alerts at the monitor's configured severity.
+   - `error` — a configuration/SSRF problem prevented the check from running.
+
+### Status matcher
+
+`expectedStatus` accepts one of three shapes (stored as JSON):
+
+```jsonc
+{ "mode": "class", "classes": ["2xx", "3xx"] } // any 2xx or 3xx
+{ "mode": "list",  "codes": [200, 204] }        // exact codes
+{ "mode": "range", "min": 200, "max": 299 }     // inclusive range
+```
+
+### Assertions
+
+`assertions` is a JSON array. All assertions must pass for a check to be `up`.
+
+| type              | meaning                                          | fields            |
+| ----------------- | ------------------------------------------------ | ----------------- |
+| `body_contains`   | response body must contain the text              | `value`           |
+| `body_absent`     | response body must NOT contain the text          | `value`           |
+| `header_contains` | a response header must contain the text          | `header`, `value` |
+| `header_equals`   | a response header must equal the text            | `header`, `value` |
+| `max_latency_ms`  | response must arrive within N ms (else degraded) | `value` (number)  |
+
+## Alerting and recovery
+
+`evaluateAndNotifyMonitor` manages incidents like the analytics alert engine:
+
+- On a transition **into failure**, it opens a `monitor_incidents` row (one per
+  continuous failure streak) and calls `notifyWithDelivery` with a clear title
+  and body plus metadata
+  `{ kind: "uptime_monitor", monitorId, url, statusCode, latencyMs, failedAssertions }`.
+  The `inbox` channel is always included; `email`/`slack`/`webhook` are added
+  when configured, and email uses the monitor's `emailRecipients`.
+- While an incident is open it will not re-alert. After an incident resolves,
+  `cooldownMinutes` suppresses a fresh "down" alert for that window to prevent
+  flapping.
+- On **recovery**, it resolves the open incident and sends an informational
+  "recovered" notification (with downtime duration).
+
+A `lastStatus === "running"` claim guard (with a staleness timeout) ensures that
+concurrent sweeps never double-run the same monitor.
+
+## Security (SSRF)
+
+Because monitors fetch user-supplied URLs from the server, `runMonitorCheck`
+guards against SSRF:
+
+- Only `http:` / `https:` URLs are allowed.
+- Requests to loopback, link-local, private RFC1918 ranges, and cloud metadata
+  IPs are blocked — both by a literal pre-flight check and by DNS resolution of
+  the resolved host (including across redirects). Blocked hosts classify as
+  `error`, never a successful check.
+- Redirects are followed manually (max 5 hops) and each hop is re-validated; when
+  `followRedirects` is off, a `3xx` is returned as-is.
+- The response body read is capped at 512 KB before text assertions run.
+
+To monitor internal/private hosts in development or a self-hosted deployment,
+set `UPTIME_MONITOR_ALLOW_PRIVATE_HOSTS=1` (off by default).
+
+## Background job
+
+The sweep is registered by `server/plugins/uptime-monitor-jobs.ts` and runs
+`runDueMonitorsOnce()` (`server/jobs/uptime-monitors.ts`), which selects enabled
+monitors whose interval has elapsed, checks them, records results, opens/resolves
+incidents, and prunes old check results.
+
+Environment flags (mirrors the analytics alert job):
+
+| flag                                   | effect                                                              |
+| -------------------------------------- | ------------------------------------------------------------------- |
+| `UPTIME_MONITOR_JOBS`                  | `1` enables the in-process cron; `0` disables it.                   |
+| `RUN_BACKGROUND_JOBS`                  | fallback flag when `UPTIME_MONITOR_JOBS` is unset.                  |
+| (production)                           | on by default unless a flag is `0` or a platform scheduler owns it. |
+| `UPTIME_MONITOR_INTERVAL_MS`           | wake interval for the sweep (default 30s, min 10s).                 |
+| `UPTIME_MONITOR_SWEEP_LIMIT`           | max monitors processed per sweep (default 100).                     |
+| `UPTIME_MONITOR_RESULT_RETENTION_DAYS` | how long check results are kept (default 30).                       |
+| `UPTIME_MONITOR_ALLOW_PRIVATE_HOSTS`   | allow probing private/internal hosts.                               |
+
+The monitor tables (`monitors`, `monitor_check_results`, `monitor_incidents`)
+are created by the app migration list in `server/plugins/db.ts`, which runs at
+boot regardless of whether the cron is enabled — so the actions and UI always
+have their schema.
+
+## Managing monitors from the agent
+
+Every operation is an owner-scoped action, so the agent can create and triage
+monitors from chat exactly like the UI:
+
+| action              | method | what it does                                                                                                                                                        |
+| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `save-monitor`      | POST   | create or update a monitor (name, url, method, interval, timeout, expected status, assertions, redirects, severity, channels, email recipients, cooldown, enabled). |
+| `list-monitors`     | GET    | list monitors with latest status, latency, and 24h/7d uptime %.                                                                                                     |
+| `get-monitor`       | GET    | one monitor plus its recent check results and incidents.                                                                                                            |
+| `delete-monitor`    | POST   | delete a monitor and its results + incidents.                                                                                                                       |
+| `run-monitor-check` | POST   | run one check now, record it, and open/resolve incidents.                                                                                                           |
+
+Example prompts:
+
+- "Monitor https://example.com every 5 minutes and email me if it returns a 5xx
+  or the page stops containing 'Sign in'."
+- "Which monitors are down right now?" (→ `list-monitors`)
+- "Run a check on the marketing site now." (→ `run-monitor-check`)
+
+## Data model
+
+All three tables carry `ownableColumns()` (`owner_email` / `org_id` /
+`visibility`) and every read/write is scoped by owner + org.
+
+- **`monitors`** — configuration plus mutable status fields (`last_status`,
+  `last_checked_at`, `last_success_at`, `last_error`, `last_latency_ms`,
+  `last_status_code`, `consecutive_failures`).
+- **`monitor_check_results`** — one row per probe (`ok`, `status`, `status_code`,
+  `latency_ms`, `error`, `failed_assertions`), indexed on
+  `(monitor_id, checked_at)`; pruned by the sweep so it stays bounded.
+- **`monitor_incidents`** — one row per failure streak (`started_at`,
+  `resolved_at` null = ongoing, `cause`, `severity`, `notification_id`,
+  `checks_failed`).

package/corpus/templates/analytics/server/db/schema-errors.ts

@@ -0,0 +1,150 @@
+/**
+ * Error capture schema — OWNED BY THE ERROR CAPTURE FEATURE.
+ *
+ * Everything exported here is re-exported from ./schema.ts via `export *`, so
+ * these tables join the app's Drizzle schema namespace and are reachable as
+ * `schema.<table>` throughout the server. Keep all schema changes additive
+ * (never drop/rename/retype existing columns) per the storing-data rules.
+ *
+ * Two tables, Sentry-style:
+ *  - `error_issues`  — the grouped issue (one row per fingerprint per owner
+ *     scope). Ownable + shareable so an org-scoped analytics key surfaces its
+ *     issues to the whole org via `accessFilter`, mirroring session_recordings.
+ *  - `error_events`  — individual occurrences. High-volume, owner-scoped like
+ *     `analytics_events` (plain owner columns, not `ownableColumns()`), always
+ *     read behind an issue the caller already has access to, and pruned to a
+ *     bounded retention per issue so occurrences can't grow unbounded.
+ */
+import {
+  createSharesTable,
+  index,
+  integer,
+  now,
+  ownableColumns,
+  table,
+  text,
+  uniqueIndex,
+} from "@agent-native/core/db/schema";
+
+/**
+ * Grouped error issues. A stable `fingerprint` (error type + top meaningful
+ * stack frame, or message when there's no usable stack) collapses many
+ * occurrences into one triageable issue.
+ */
+export const errorIssues = table(
+  "error_issues",
+  {
+    id: text("id").primaryKey(),
+    /** Stable grouping key; unique per owner scope. */
+    fingerprint: text("fingerprint").notNull(),
+    /** Error class/name, e.g. "TypeError" or "Error" (or "Message"). */
+    type: text("type").notNull().default("Error"),
+    /** Human-readable issue title (type + first line of the message). */
+    title: text("title").notNull(),
+    /** Best-effort culprit — the top in-app frame ("fn (file:line)"). */
+    culprit: text("culprit"),
+    level: text("level", {
+      enum: ["fatal", "error", "warning", "info", "debug"],
+    })
+      .notNull()
+      .default("error"),
+    status: text("status", {
+      enum: ["unresolved", "resolved", "ignored"],
+    })
+      .notNull()
+      .default("unresolved"),
+    firstSeenAt: text("first_seen_at").notNull(),
+    lastSeenAt: text("last_seen_at").notNull(),
+    /** Lifetime occurrence count (monotonic; not affected by retention). */
+    eventCount: integer("event_count").notNull().default(0),
+    /** Approximate distinct users, recomputed over retained occurrences. */
+    usersAffected: integer("users_affected").notNull().default(0),
+    /** id of a representative occurrence for the detail view. */
+    sampleEventId: text("sample_event_id"),
+    /** Most recent linked session_recordings.id (sr_...), if any. */
+    lastSessionRecordingId: text("last_session_recording_id"),
+    /** Optional triage owner (email). */
+    assignee: text("assignee"),
+    /** Denormalized product dimensions for filtering/display. */
+    app: text("app"),
+    template: text("template"),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+    ...ownableColumns(),
+  },
+  (issue) => ({
+    scopeFingerprintUnique: uniqueIndex(
+      "error_issues_scope_fingerprint_idx",
+    ).on(issue.ownerEmail, issue.orgId, issue.fingerprint),
+    scopeLastSeenIdx: index("error_issues_scope_last_seen_idx").on(
+      issue.ownerEmail,
+      issue.orgId,
+      issue.lastSeenAt,
+    ),
+    scopeStatusIdx: index("error_issues_scope_status_idx").on(
+      issue.orgId,
+      issue.ownerEmail,
+      issue.status,
+      issue.lastSeenAt,
+    ),
+  }),
+);
+
+export const errorIssueShares = createSharesTable("error_issue_shares");
+
+/**
+ * Individual error occurrences (events). Owner-scoped like analytics_events.
+ * Always read behind an issue whose access the caller already resolved through
+ * `accessFilter`, and additionally filtered by owner scope for defense in
+ * depth. Pruned to a bounded retention per issue at ingest time.
+ */
+export const errorEvents = table(
+  "error_events",
+  {
+    id: text("id").primaryKey(),
+    issueId: text("issue_id").notNull(),
+    fingerprint: text("fingerprint").notNull(),
+    type: text("type").notNull().default("Error"),
+    message: text("message").notNull().default(""),
+    culprit: text("culprit"),
+    level: text("level", {
+      enum: ["fatal", "error", "warning", "info", "debug"],
+    })
+      .notNull()
+      .default("error"),
+    /** Normalized stack frames as JSON (ParsedStackFrame[]). */
+    stack: text("stack").notNull().default("[]"),
+    /** Bounded raw stack string kept for display fidelity. */
+    rawStack: text("raw_stack"),
+    handled: integer("handled", { mode: "boolean" }).notNull().default(true),
+    url: text("url"),
+    userId: text("user_id"),
+    anonymousId: text("anonymous_id"),
+    userKey: text("user_key"),
+    sessionId: text("session_id"),
+    /** Client replay id (localStorage) reported by the SDK. */
+    clientRecordingId: text("client_recording_id"),
+    /** Resolved session_recordings.id (sr_...) when a replay exists. */
+    sessionRecordingId: text("session_recording_id"),
+    release: text("release"),
+    environment: text("environment"),
+    tags: text("tags").notNull().default("{}"),
+    extra: text("extra").notNull().default("{}"),
+    breadcrumbs: text("breadcrumbs").notNull().default("[]"),
+    occurredAt: text("occurred_at").notNull(),
+    createdAt: text("created_at").notNull().default(now()),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    orgId: text("org_id"),
+  },
+  (event) => ({
+    issueOccurredIdx: index("error_events_issue_occurred_idx").on(
+      event.issueId,
+      event.occurredAt,
+    ),
+    scopeOccurredIdx: index("error_events_scope_occurred_idx").on(
+      event.ownerEmail,
+      event.orgId,
+      event.occurredAt,
+    ),
+  }),
+);

package/corpus/templates/analytics/server/db/schema-monitoring.ts

@@ -0,0 +1,177 @@
+/**
+ * Uptime monitoring schema — OWNED BY THE UPTIME MONITORING FEATURE.
+ *
+ * Everything exported here is re-exported from ./schema.ts via `export *`, so
+ * these tables join the app's Drizzle schema namespace and are reachable as
+ * `schema.<table>` throughout the server. Keep all schema changes additive
+ * (never drop/rename/retype existing columns) per the storing-data rules.
+ *
+ * Physical table creation + indexes are applied by the isolated migration list
+ * in server/plugins/uptime-monitor-jobs.ts (`uptime_monitor_migrations`), NOT
+ * by drizzle-kit. These Drizzle definitions must stay in lockstep with that
+ * DDL (snake_case column names, dialect-agnostic types).
+ *
+ * All three tables carry `ownableColumns()` (owner_email / org_id / visibility)
+ * and every read/write in server/lib/uptime-monitors.ts is scoped by
+ * owner_email + org_id, mirroring the analytics-alerts engine.
+ */
+import {
+  integer,
+  now,
+  ownableColumns,
+  table,
+  text,
+} from "@agent-native/core/db/schema";
+
+/**
+ * A single uptime check ("monitor"). Pings `url` on `intervalSeconds` and
+ * evaluates the response against a status matcher + a list of assertions.
+ */
+export const monitors = table("monitors", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  url: text("url").notNull(),
+  /** HTTP method used for the probe. */
+  method: text("method", {
+    enum: ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+  })
+    .notNull()
+    .default("GET"),
+  /** Extra request headers as a JSON object (`Record<string,string>`). */
+  requestHeaders: text("request_headers").notNull().default("{}"),
+  /** Optional request body (POST/PUT/PATCH). */
+  requestBody: text("request_body"),
+  intervalSeconds: integer("interval_seconds").notNull().default(300),
+  timeoutMs: integer("timeout_ms").notNull().default(15000),
+  /**
+   * Status matcher as JSON. One of:
+   *   { "mode": "class", "classes": ["2xx","3xx"] }
+   *   { "mode": "list",  "codes": [200,204] }
+   *   { "mode": "range", "min": 200, "max": 299 }
+   */
+  expectedStatus: text("expected_status")
+    .notNull()
+    .default('{"mode":"class","classes":["2xx"]}'),
+  /**
+   * JSON array of assertions. Each entry:
+   *   { "type": "body_contains" | "body_absent" | "header_contains" |
+   *             "header_equals" | "max_latency_ms",
+   *     "value": string | number, "header"?: string }
+   */
+  assertions: text("assertions").notNull().default("[]"),
+  followRedirects: integer("follow_redirects", { mode: "boolean" })
+    .notNull()
+    .default(true),
+  /** Alert severity when the monitor fails. */
+  severity: text("severity", { enum: ["warning", "critical"] })
+    .notNull()
+    .default("critical"),
+  /** Notification channels as JSON (e.g. ["inbox","email","slack","webhook"]). */
+  channels: text("channels").notNull().default('["inbox"]'),
+  /** Email recipients as JSON array of addresses. */
+  emailRecipients: text("email_recipients").notNull().default("[]"),
+  /** Minutes to suppress repeat alerts while an incident is ongoing. */
+  cooldownMinutes: integer("cooldown_minutes").notNull().default(15),
+  enabled: integer("enabled", { mode: "boolean" }).notNull().default(true),
+
+  // ---- Mutable status fields (updated by the runner) ----
+  /** up | down | degraded | error | unknown | running */
+  lastStatus: text("last_status"),
+  lastCheckedAt: text("last_checked_at"),
+  lastSuccessAt: text("last_success_at"),
+  lastError: text("last_error"),
+  lastLatencyMs: integer("last_latency_ms"),
+  lastStatusCode: integer("last_status_code"),
+  consecutiveFailures: integer("consecutive_failures").notNull().default(0),
+
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(),
+});
+
+/**
+ * Historical probe results. Bounded retention is enforced by the sweep job
+ * (server/jobs/uptime-monitors.ts) so this table cannot grow unbounded.
+ */
+export const monitorCheckResults = table("monitor_check_results", {
+  id: text("id").primaryKey(),
+  monitorId: text("monitor_id").notNull(),
+  checkedAt: text("checked_at").notNull(),
+  ok: integer("ok", { mode: "boolean" }).notNull(),
+  /** Classification for this probe: up | down | degraded | error. */
+  status: text("status").notNull().default("up"),
+  statusCode: integer("status_code"),
+  latencyMs: integer("latency_ms"),
+  error: text("error"),
+  /** JSON array of human-readable assertion failures. */
+  failedAssertions: text("failed_assertions").notNull().default("[]"),
+  createdAt: text("created_at").notNull().default(now()),
+  ...ownableColumns(),
+});
+
+/**
+ * One incident per continuous failure streak. `resolvedAt` null = ongoing.
+ * Mirrors analyticsAlertIncidents.
+ */
+export const monitorIncidents = table("monitor_incidents", {
+  id: text("id").primaryKey(),
+  monitorId: text("monitor_id").notNull(),
+  startedAt: text("started_at").notNull(),
+  resolvedAt: text("resolved_at"),
+  /** down | degraded — the classification at incident open. */
+  status: text("status").notNull().default("down"),
+  severity: text("severity").notNull().default("critical"),
+  /** Short summary of what failed (status code / failed assertions). */
+  cause: text("cause").notNull().default(""),
+  lastError: text("last_error"),
+  notificationId: text("notification_id"),
+  checksFailed: integer("checks_failed").notNull().default(1),
+  createdAt: text("created_at").notNull().default(now()),
+  ...ownableColumns(),
+});
+
+/**
+ * Owner-authored public status page. A status page bundles a set of the owner's
+ * monitors under a public `slug` (`/status/<slug>`) and renders their SAFE
+ * aggregate health (status, uptime %s, colored timelines) to anyone with the
+ * link — but only when `published` is true. The public read
+ * (server/lib/status-pages.ts `getPublicStatusPage`) strictly filters to
+ * published pages and the page owner's included monitors, and never leaks
+ * monitor URLs/headers/assertions/alert config unless a per-monitor "show URL"
+ * opt-in is set.
+ *
+ * `monitors` is a JSON array of
+ *   { monitorId: string; order: number; displayName?: string | null;
+ *     showUrl?: boolean }
+ * kept additive so page layout can grow without a join table migration.
+ */
+export const statusPages = table("status_pages", {
+  id: text("id").primaryKey(),
+  /** Public, globally-unique URL slug (`/status/<slug>`). */
+  slug: text("slug").notNull(),
+  title: text("title").notNull(),
+  description: text("description"),
+  /** Only published pages are readable by the unauthenticated public route. */
+  published: integer("published", { mode: "boolean" }).notNull().default(false),
+  // ---- Layout options ----
+  showUptimeBars: integer("show_uptime_bars", { mode: "boolean" })
+    .notNull()
+    .default(true),
+  showOverallUptime: integer("show_overall_uptime", { mode: "boolean" })
+    .notNull()
+    .default(true),
+  showResponseTime: integer("show_response_time", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  density: text("density", { enum: ["comfortable", "compact"] })
+    .notNull()
+    .default("comfortable"),
+  alignment: text("alignment", { enum: ["left", "center"] })
+    .notNull()
+    .default("left"),
+  /** JSON array of included monitors with order + optional display overrides. */
+  monitors: text("monitors").notNull().default("[]"),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(),
+});

package/corpus/templates/analytics/server/db/schema.ts

@@ -9,6 +9,12 @@ import {
   uniqueIndex,
 } from "@agent-native/core/db/schema";
 
+// Feature-owned schema modules. Re-exported so their tables join this app's
+// Drizzle schema namespace (schema.<table>). Each file is owned by a single
+// feature so parallel work never collides on this shared file.
+export * from "./schema-monitoring.js";
+export * from "./schema-errors.js";
+
 /**
  * Dashboards table — covers both Explorer and SQL dashboards. The
  * distinction lives in `kind` and the shape of the `config` JSON blob.