@celilo/cli 0.13.3 → 0.14.1

package/src/db/schema.ts

@@ -1,5 +1,6 @@
 import { sql } from 'drizzle-orm';
 import {
+  index,
   integer,
   primaryKey,
   sqliteTable,
@@ -197,7 +198,7 @@ export const ipAllocations = sqliteTable('ip_allocations', {
     .references(() => modules.id, { onDelete: 'cascade' }),
   vmid: integer('vmid').notNull().unique(),
   containerIp: text('container_ip').notNull().unique(), // CIDR format (e.g., "10.0.10.10/24")
-  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal'>().notNull(),
+  zone: text('zone').$type<AllocatableZone>().notNull(),
   allocatedAt: integer('allocated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
@@ -210,7 +211,7 @@ export const ipReservations = sqliteTable('ip_reservations', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   ipStart: text('ip_start').notNull(), // Single IP or range start
   ipEnd: text('ip_end'), // NULL for single IP, end IP for range
-  zone: text('zone').$type<'dmz' | 'app' | 'secure' | 'secure-mgmt' | 'internal'>().notNull(),
+  zone: text('zone').$type<AllocatableZone>().notNull(),
   reason: text('reason').notNull(),
   reservedAt: integer('reserved_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
@@ -274,6 +275,17 @@ export const NETWORK_ZONES = [
  */
 export type NetworkZone = (typeof NETWORK_ZONES)[number];
 
+/**
+ * Zones an IP allocation or reservation can name: every NetworkZone except
+ * `external`, whose systems are addressed by the provider, not by our IPAM.
+ *
+ * Derived rather than hand-written for the same reason as NetworkZone above —
+ * the previous hand-written union was copied into two column definitions and a
+ * cast in machine-pool.ts, and the cast had already drifted (it was missing
+ * `secure-mgmt`, and its comment claimed the only difference was `external`).
+ */
+export type AllocatableZone = Exclude<NetworkZone, 'external'>;
+
 /**
  * Container services table
  * Stores container service providers (Proxmox, Digital Ocean, etc.)
@@ -503,6 +515,39 @@ export const portForwards = sqliteTable(
   }),
 );
 
+/**
+ * Trusted-source registry — the desired-state store for "this subnet may reach
+ * every managed zone", the sibling of `port_forwards` and for the same reason: a
+ * rule that lives only in the applied ruleset belongs to no module, so the next
+ * converge correctly removes it. The admin VPN sat in exactly that position and
+ * needed a shell script re-adding its rules every second.
+ *
+ * Distinct from a port forward: that publishes one backend on specific ports;
+ * this is a whole origin subnet permitted to initiate into the segmented tiers.
+ */
+export const trustedSources = sqliteTable(
+  'trusted_sources',
+  {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** The firewall host that renders this trust (config.firewallIp). */
+    firewallIp: text('firewall_ip').notNull(),
+    /** Subnet CIDR permitted to reach every managed zone. */
+    subnet: text('subnet').notNull(),
+    description: text('description').notNull().default(''),
+    /** Module that registered it — reach into every tier must never be anonymous. */
+    registeredBy: text('registered_by').notNull(),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    // One row per (firewall, subnet) — the store delete-then-inserts on this
+    // tuple so re-registering the same subnet is an idempotent upsert.
+    trustedSourceUnique: uniqueIndex('trusted_sources_unique_idx').on(
+      table.firewallIp,
+      table.subnet,
+    ),
+  }),
+);
+
 /**
  * DNS registration ledger — one row per (provider, fqdn) the framework
  * has successfully registered via dns_registrar.registerHost. Written
@@ -742,6 +787,312 @@ export const apiPrincipals = sqliteTable('api_principals', {
   updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
 });
 
+// ---------------------------------------------------------------------------
+// Alerting (openspec/changes/add-alerting)
+// ---------------------------------------------------------------------------
+
+/**
+ * Alert severity. Only `critical` pages.
+ *
+ * A check item's `warn` status always yields `warning`; a `fail` yields the
+ * monitor's configured severity. A monitor deliberately configured as
+ * `warning` therefore never pages even when its checks fail — the operator's
+ * "record this but don't wake me" knob. See design D6.
+ */
+export type AlertSeverity = 'warning' | 'critical';
+
+/** What a monitor runs. `module_hook` = a module's health_check hook. */
+export type MonitorKind = 'module_hook' | 'builtin_check';
+
+/**
+ * Whether a monitor run executed at all. The load-bearing distinction: a run
+ * that could not execute produces an empty failing set for reasons that say
+ * nothing about the underlying checks, so it must never resolve anything.
+ * See design D5.
+ */
+export type MonitorRunOutcome = 'success' | 'error';
+
+export type AlertState = 'pending' | 'firing' | 'acked' | 'suppressed' | 'resolved';
+
+/**
+ * People celilo can reach. Deliberately independent of any transport or
+ * module — a person exists before any notification module is deployed.
+ */
+export const people = sqliteTable('people', {
+  id: text('id').primaryKey(), // UUID
+  /** User-facing kebab-case name (e.g. "peter"). Never a UUID in CLI output. */
+  name: text('name').notNull().unique(),
+  /** IANA timezone (e.g. "America/Los_Angeles") — quiet hours are local to it. */
+  timezone: text('timezone').notNull(),
+  /** Quiet-hours window as local "HH:MM"; both null = always reachable. */
+  quietHoursStart: text('quiet_hours_start'),
+  quietHoursEnd: text('quiet_hours_end'),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/**
+ * A person's address on a transport, plus the policy for using it.
+ *
+ * Addresses live HERE, never in the transport module's config — otherwise
+ * adding a recipient would require redeploying the module. signal-cli holds
+ * one credential (its own registration); recipients are addresses, not
+ * credentials. See design D8.
+ */
+export const routes = sqliteTable(
+  'routes',
+  {
+    id: text('id').primaryKey(), // UUID
+    personId: text('person_id')
+      .notNull()
+      .references(() => people.id, { onDelete: 'cascade' }),
+    /** Module providing the `notification` capability. */
+    transportModuleId: text('transport_module_id')
+      .notNull()
+      .references(() => modules.id, { onDelete: 'cascade' }),
+    /** Transport-specific address (phone number, email, topic). */
+    address: text('address').notNull(),
+    /** Alerts below this severity are not delivered here. */
+    severityFloor: text('severity_floor').$type<AlertSeverity>().notNull().default('warning'),
+    /**
+     * Whether replies can arrive over this route — set from whether the
+     * transport implements `receive`. A route that cannot ack never stops
+     * escalation (spec: *Unidirectional transport cannot acknowledge*).
+     */
+    canAck: integer('can_ack', { mode: 'boolean' }).notNull().default(false),
+    enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+    verifiedAt: integer('verified_at', { mode: 'timestamp' }),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    uniqueAddress: unique().on(table.personId, table.transportModuleId, table.address),
+  }),
+);
+
+/**
+ * Named, reusable escalation policy. Steps reference ROUTES rather than
+ * people — "page Peter" is ambiguous about which transport to use.
+ */
+export const escalationPolicies = sqliteTable('escalation_policies', {
+  id: text('id').primaryKey(), // UUID
+  /** User-facing kebab-case name (e.g. "default", "critical"). */
+  name: text('name').notNull().unique(),
+  /**
+   * Reserved escape hatch (design D13): quiet hours otherwise defer ALL
+   * severities. Unused in MVP — the column exists so enabling it later is not
+   * a migration.
+   */
+  bypassQuietHours: integer('bypass_quiet_hours', { mode: 'boolean' }).notNull().default(false),
+  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+});
+
+/** One ordered step of an escalation policy. Delay is from escalation start. */
+export const escalationSteps = sqliteTable(
+  'escalation_steps',
+  {
+    policyId: text('policy_id')
+      .notNull()
+      .references(() => escalationPolicies.id, { onDelete: 'cascade' }),
+    /** 0-based order within the policy. */
+    stepIndex: integer('step_index').notNull(),
+    routeId: text('route_id')
+      .notNull()
+      .references(() => routes.id, { onDelete: 'cascade' }),
+    /** Minutes after escalation begins. Step 0 is normally 0. */
+    delayMinutes: integer('delay_minutes').notNull(),
+  },
+  (table) => ({
+    pk: primaryKey({ columns: [table.policyId, table.stepIndex] }),
+  }),
+);
+
+/**
+ * What gets checked, how often, and how failures are routed.
+ *
+ * The module manifest's `hooks.health_check.interval` is only a SUGGESTION;
+ * this row is the effective schedule and an operator edit survives module
+ * upgrades. See design D3.
+ */
+export const monitors = sqliteTable(
+  'monitors',
+  {
+    id: text('id').primaryKey(), // UUID
+    kind: text('kind').$type<MonitorKind>().notNull(),
+    /** Module id for `module_hook`; audit check name for `builtin_check`. */
+    target: text('target').notNull(),
+    intervalMinutes: integer('interval_minutes').notNull(),
+    /** Severity applied to `fail` items. Only `critical` pages. */
+    severity: text('severity').$type<AlertSeverity>().notNull().default('critical'),
+    /**
+     * False for monitors watching the alerting system itself — a cascading
+     * failure must not silence the component reporting it (design S4).
+     */
+    suppressible: integer('suppressible', { mode: 'boolean' }).notNull().default(true),
+    enabled: integer('enabled', { mode: 'boolean' }).notNull().default(true),
+    escalationPolicyId: text('escalation_policy_id').references(() => escalationPolicies.id, {
+      onDelete: 'set null',
+    }),
+    lastRunAt: integer('last_run_at', { mode: 'timestamp' }),
+    createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  },
+  (table) => ({
+    uniqueTarget: unique().on(table.kind, table.target),
+  }),
+);
+
+/**
+ * Record of each monitor execution. Exists so reconciliation can branch on
+ * whether the last run actually ran (design D5) — without a persisted
+ * outcome there is nothing to distinguish "found nothing wrong" from
+ * "couldn't look".
+ */
+export const monitorRuns = sqliteTable('monitor_runs', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  monitorId: text('monitor_id')
+    .notNull()
+    .references(() => monitors.id, { onDelete: 'cascade' }),
+  ranAt: integer('ran_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  outcome: text('outcome').$type<MonitorRunOutcome>().notNull(),
+  /** Populated when outcome is `error` (ssh failure, timeout, hook threw). */
+  errorMessage: text('error_message'),
+});
+
+/**
+ * A deliberate, time-boxed suppression source. Today only deploys create
+ * these — a deploy is the same suppression mechanism as a machine-down alert,
+ * with a window as the source instead of an ancestor alert (design D7).
+ */
+export const suppressionWindows = sqliteTable('suppression_windows', {
+  id: text('id').primaryKey(), // UUID
+  source: text('source').$type<'deploy'>().notNull(),
+  scopeModuleId: text('scope_module_id')
+    .notNull()
+    .references(() => modules.id, { onDelete: 'cascade' }),
+  startedAt: integer('started_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  /** Null while open. Set on deploy completion, including on failure. */
+  endsAt: integer('ends_at', { mode: 'timestamp' }),
+});
+
+/**
+ * The alert lifecycle. One row per alert key per firing episode: a resolve
+ * followed by a re-fire mints a new row, so history is preserved.
+ *
+ * `acked`, `suppressed`, and `silenced` are deliberately THREE separate
+ * concerns (design S5) — collapsing any two is how alerting systems become
+ * untrustworthy.
+ */
+export const alerts = sqliteTable(
+  'alerts',
+  {
+    id: text('id').primaryKey(), // UUID
+    /** Stable key, e.g. `module:caddy/check:cert-validity`. See design D4. */
+    key: text('key').notNull(),
+    /**
+     * Mirrors `key` while the alert is live; set to NULL on resolve. Backs the
+     * "one live alert per key" unique index below — SQLite treats NULLs in a
+     * unique index as distinct, so any number of resolved rows may share a key
+     * while at most one live row may hold it. Written only by the
+     * reconciliation code that sets `state`; the two must move together.
+     */
+    activeKey: text('active_key'),
+    monitorId: text('monitor_id')
+      .notNull()
+      .references(() => monitors.id, { onDelete: 'cascade' }),
+    state: text('state').$type<AlertState>().notNull().default('pending'),
+    severity: text('severity').$type<AlertSeverity>().notNull(),
+    firstFiredAt: integer('first_fired_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+    lastSeenAt: integer('last_seen_at', { mode: 'timestamp' })
+      .notNull()
+      .default(sql`(unixepoch())`),
+    /**
+     * Notification is withheld until this instant, so an ancestor firing
+     * moments later can establish suppression first, and so a failure that
+     * clears immediately never pages (design S1).
+     */
+    graceUntil: integer('grace_until', { mode: 'timestamp' }).notNull(),
+    /** Set when an ancestor ALERT is suppressing this one. */
+    suppressedByAlertId: text('suppressed_by_alert_id'),
+    /** Set when a suppression WINDOW (e.g. a deploy) is suppressing this one. */
+    suppressedByWindowId: text('suppressed_by_window_id').references(() => suppressionWindows.id, {
+      onDelete: 'set null',
+    }),
+    /** Escalation clock origin after suppression lifts — NOT firstFiredAt (S3). */
+    unsuppressedAt: integer('unsuppressed_at', { mode: 'timestamp' }),
+    /**
+     * True between un-suppression and the next SUCCESSFUL run. While set, the
+     * alert does not notify: if it recovered along with its ancestor it
+     * resolves quietly instead of paging (design S2).
+     */
+    awaitingConfirmation: integer('awaiting_confirmation', { mode: 'boolean' })
+      .notNull()
+      .default(false),
+    ackedBy: text('acked_by').references(() => people.id, { onDelete: 'set null' }),
+    ackedAt: integer('acked_at', { mode: 'timestamp' }),
+    /** Deliberate operator silence — distinct from suppression (S5). */
+    silencedUntil: integer('silenced_until', { mode: 'timestamp' }),
+    escalationStep: integer('escalation_step').notNull().default(0),
+    nextEscalationAt: integer('next_escalation_at', { mode: 'timestamp' }),
+    /**
+     * Quiet hours defer DELIVERY, never the escalation clock (D13). When a step
+     * falls due inside someone's window the step is still taken — the step
+     * index advances and the next one is scheduled — and only the message
+     * waits, held here until the window ends.
+     */
+    deferredUntil: integer('deferred_until', { mode: 'timestamp' }),
+    /** Route the deferred message is owed to. */
+    deferredRouteId: text('deferred_route_id').references(() => routes.id, {
+      onDelete: 'set null',
+    }),
+    escalationPolicyId: text('escalation_policy_id').references(() => escalationPolicies.id, {
+      onDelete: 'set null',
+    }),
+    message: text('message').notNull(),
+    details: text('details'),
+    resolvedAt: integer('resolved_at', { mode: 'timestamp' }),
+  },
+  (table) => ({
+    /**
+     * One live alert per key. Resolved rows are exempt so history accumulates:
+     * `activeKey` mirrors `key` while live and is NULL once resolved, and
+     * SQLite treats NULLs in a unique index as distinct.
+     */
+    liveKey: uniqueIndex('alerts_live_key_idx').on(table.activeKey),
+    keyLookup: index('alerts_key_idx').on(table.key),
+  }),
+);
+
+/**
+ * One outbound message, and the token that authorises a reply to it.
+ *
+ * Per DELIVERY, not per alert: the token identifies WHO replied, which is
+ * what "an ack from the secondary is broadcast to everyone paged" needs, and
+ * doubles as the audit trail (design D10).
+ */
+export const notificationDeliveries = sqliteTable('notification_deliveries', {
+  id: text('id').primaryKey(), // UUID
+  /** Short operator-typable token, unique across live deliveries. */
+  token: text('token').notNull().unique(),
+  kind: text('kind').$type<'alert' | 'interview'>().notNull(),
+  /**
+   * `alerts.id` when kind is `alert`; a BUS event id when kind is
+   * `interview`. Deliberately not a foreign key — the event bus is a separate
+   * SQLite database, so no FK can span it.
+   */
+  targetId: text('target_id').notNull(),
+  routeId: text('route_id')
+    .notNull()
+    .references(() => routes.id, { onDelete: 'cascade' }),
+  sentAt: integer('sent_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
+  expiresAt: integer('expires_at', { mode: 'timestamp' }).notNull(),
+  /** Set when a reply consumed this token. */
+  consumedAt: integer('consumed_at', { mode: 'timestamp' }),
+});
+
 /**
  * Type exports for use in application code
  */
@@ -785,3 +1136,21 @@ export type AspectApproval = typeof aspectApprovals.$inferSelect;
 export type NewAspectApproval = typeof aspectApprovals.$inferInsert;
 export type ApiPrincipal = typeof apiPrincipals.$inferSelect;
 export type NewApiPrincipal = typeof apiPrincipals.$inferInsert;
+export type Person = typeof people.$inferSelect;
+export type NewPerson = typeof people.$inferInsert;
+export type Route = typeof routes.$inferSelect;
+export type NewRoute = typeof routes.$inferInsert;
+export type EscalationPolicy = typeof escalationPolicies.$inferSelect;
+export type NewEscalationPolicy = typeof escalationPolicies.$inferInsert;
+export type EscalationStep = typeof escalationSteps.$inferSelect;
+export type NewEscalationStep = typeof escalationSteps.$inferInsert;
+export type Monitor = typeof monitors.$inferSelect;
+export type NewMonitor = typeof monitors.$inferInsert;
+export type MonitorRun = typeof monitorRuns.$inferSelect;
+export type NewMonitorRun = typeof monitorRuns.$inferInsert;
+export type SuppressionWindow = typeof suppressionWindows.$inferSelect;
+export type NewSuppressionWindow = typeof suppressionWindows.$inferInsert;
+export type Alert = typeof alerts.$inferSelect;
+export type NewAlert = typeof alerts.$inferInsert;
+export type NotificationDelivery = typeof notificationDeliveries.$inferSelect;
+export type NewNotificationDelivery = typeof notificationDeliveries.$inferInsert;