@desplega.ai/agent-swarm 1.78.1 → 1.79.1

package/src/be/db.ts

@@ -34,10 +34,17 @@ import type {
   InboxMessage,
   InboxMessageStatus,
   InputValue,
+  KvEntry,
+  KvValueType,
   McpServer,
   McpServerScope,
   McpServerTransport,
   McpServerWithInstallInfo,
+  Page,
+  PageAuthMode,
+  PageContentType,
+  PageSnapshot,
+  PageVersion,
   PricingProvider,
   PricingRow,
   PricingTokenClass,
@@ -6237,6 +6244,255 @@ export function getWorkflowVersion(workflowId: string, version: number): Workflo
   return row ? rowToWorkflowVersion(row) : null;
 }
 
+// ============================================================================
+// Pages CRUD + version history
+// ----------------------------------------------------------------------------
+// DB-backed lightweight artifacts. Mirrors the workflow versioning pattern:
+// parent table `pages` holds the CURRENT state, history table `page_versions`
+// holds pre-update snapshots. snapshotPage() (src/pages/version.ts) MUST be
+// called BEFORE updatePage() so the snapshot freezes pre-update content.
+// ============================================================================
+
+type PageRow = {
+  id: string;
+  agentId: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  contentType: string;
+  authMode: string;
+  passwordHash: string | null;
+  body: string;
+  needsCredentials: string | null;
+  createdAt: string;
+  updatedAt: string;
+  view_count: number;
+};
+
+function rowToPage(row: PageRow): Page {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    slug: row.slug,
+    title: row.title,
+    description: row.description ?? undefined,
+    contentType: row.contentType as PageContentType,
+    authMode: row.authMode as PageAuthMode,
+    passwordHash: row.passwordHash ?? undefined,
+    body: row.body,
+    needsCredentials: row.needsCredentials
+      ? (JSON.parse(row.needsCredentials) as string[])
+      : undefined,
+    viewCount: typeof row.view_count === "number" ? row.view_count : 0,
+    createdAt: normalizeDateRequired(row.createdAt),
+    updatedAt: normalizeDateRequired(row.updatedAt),
+  };
+}
+
+export function createPage(data: {
+  agentId: string;
+  slug: string;
+  title: string;
+  description?: string;
+  contentType: PageContentType;
+  authMode: PageAuthMode;
+  passwordHash?: string;
+  body: string;
+  needsCredentials?: string[];
+}): Page {
+  const row = getDb()
+    .prepare<
+      PageRow,
+      [string, string, string, string | null, string, string, string | null, string, string | null]
+    >(
+      `INSERT INTO pages (agentId, slug, title, description, contentType, authMode, passwordHash, body, needsCredentials)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+    )
+    .get(
+      data.agentId,
+      data.slug,
+      data.title,
+      data.description ?? null,
+      data.contentType,
+      data.authMode,
+      data.passwordHash ?? null,
+      data.body,
+      data.needsCredentials ? JSON.stringify(data.needsCredentials) : null,
+    );
+  if (!row) throw new Error("Failed to create page");
+  return rowToPage(row);
+}
+
+export function getPage(id: string): Page | null {
+  const row = getDb().prepare<PageRow, [string]>("SELECT * FROM pages WHERE id = ?").get(id);
+  return row ? rowToPage(row) : null;
+}
+
+export function getPageBySlug(agentId: string, slug: string): Page | null {
+  const row = getDb()
+    .prepare<PageRow, [string, string]>("SELECT * FROM pages WHERE agentId = ? AND slug = ?")
+    .get(agentId, slug);
+  return row ? rowToPage(row) : null;
+}
+
+export function listPagesByAgent(agentId: string, limit = 100, offset = 0): Page[] {
+  return getDb()
+    .prepare<PageRow, [string, number, number]>(
+      "SELECT * FROM pages WHERE agentId = ? ORDER BY updatedAt DESC LIMIT ? OFFSET ?",
+    )
+    .all(agentId, limit, offset)
+    .map(rowToPage);
+}
+
+export function listAllPages(limit = 100, offset = 0): Page[] {
+  return getDb()
+    .prepare<PageRow, [number, number]>(
+      "SELECT * FROM pages ORDER BY updatedAt DESC LIMIT ? OFFSET ?",
+    )
+    .all(limit, offset)
+    .map(rowToPage);
+}
+
+/**
+ * Apply a patch to a page. Does NOT snapshot — caller must invoke
+ * `snapshotPage(id, agentId)` BEFORE calling this to preserve pre-update
+ * state (mirrors the workflow update pattern at src/http/workflows.ts:483).
+ *
+ * Always bumps `updatedAt` even if no other field changed (keeps the index
+ * useful for list ordering).
+ */
+export function updatePage(
+  id: string,
+  data: {
+    title?: string;
+    description?: string | null;
+    contentType?: PageContentType;
+    authMode?: PageAuthMode;
+    passwordHash?: string | null;
+    body?: string;
+    needsCredentials?: string[] | null;
+    slug?: string;
+  },
+): Page | null {
+  const updates: string[] = [];
+  const params: (string | number | null)[] = [];
+  if (data.title !== undefined) {
+    updates.push("title = ?");
+    params.push(data.title);
+  }
+  if (data.description !== undefined) {
+    updates.push("description = ?");
+    params.push(data.description ?? null);
+  }
+  if (data.contentType !== undefined) {
+    updates.push("contentType = ?");
+    params.push(data.contentType);
+  }
+  if (data.authMode !== undefined) {
+    updates.push("authMode = ?");
+    params.push(data.authMode);
+  }
+  if (data.passwordHash !== undefined) {
+    updates.push("passwordHash = ?");
+    params.push(data.passwordHash ?? null);
+  }
+  if (data.body !== undefined) {
+    updates.push("body = ?");
+    params.push(data.body);
+  }
+  if (data.needsCredentials !== undefined) {
+    updates.push("needsCredentials = ?");
+    params.push(data.needsCredentials ? JSON.stringify(data.needsCredentials) : null);
+  }
+  if (data.slug !== undefined) {
+    updates.push("slug = ?");
+    params.push(data.slug);
+  }
+  if (updates.length === 0) return getPage(id);
+  updates.push("updatedAt = ?");
+  params.push(new Date().toISOString());
+  params.push(id);
+  const row = getDb()
+    .prepare<PageRow, (string | number | null)[]>(
+      `UPDATE pages SET ${updates.join(", ")} WHERE id = ? RETURNING *`,
+    )
+    .get(...params);
+  return row ? rowToPage(row) : null;
+}
+
+export function deletePage(id: string): boolean {
+  // ON DELETE CASCADE on page_versions.pageId handles history cleanup.
+  const result = getDb().run("DELETE FROM pages WHERE id = ?", [id]);
+  return result.changes > 0;
+}
+
+/**
+ * Bump the `view_count` counter on a page by 1. Called from `pages-public.ts`
+ * on every successful 200 from `GET /p/:id` (HTML inline serve) and
+ * `GET /p/:id.json` (JSON metadata fetch). No-op when the page doesn't
+ * exist — caller already guards on `getPage(id)` before reaching the bump
+ * path, so this only fires for valid ids. Wrapped in try/catch by the
+ * caller so an unexpected DB error never breaks page serving.
+ */
+export function incrementPageViewCount(id: string): boolean {
+  const result = getDb().run("UPDATE pages SET view_count = view_count + 1 WHERE id = ?", [id]);
+  return result.changes > 0;
+}
+
+type PageVersionRow = {
+  id: string;
+  pageId: string;
+  version: number;
+  snapshot: string;
+  changedByAgentId: string | null;
+  createdAt: string;
+};
+
+function rowToPageVersion(row: PageVersionRow): PageVersion {
+  return {
+    id: row.id,
+    pageId: row.pageId,
+    version: row.version,
+    snapshot: JSON.parse(row.snapshot) as PageSnapshot,
+    changedByAgentId: row.changedByAgentId ?? undefined,
+    createdAt: normalizeDateRequired(row.createdAt),
+  };
+}
+
+export function createPageVersion(data: {
+  pageId: string;
+  version: number;
+  snapshot: PageSnapshot;
+  changedByAgentId?: string;
+}): PageVersion {
+  const row = getDb()
+    .prepare<PageVersionRow, [string, number, string, string | null]>(
+      `INSERT INTO page_versions (pageId, version, snapshot, changedByAgentId)
+       VALUES (?, ?, ?, ?) RETURNING *`,
+    )
+    .get(data.pageId, data.version, JSON.stringify(data.snapshot), data.changedByAgentId ?? null);
+  if (!row) throw new Error("Failed to create page version");
+  return rowToPageVersion(row);
+}
+
+export function getPageVersions(pageId: string): PageVersion[] {
+  return getDb()
+    .prepare<PageVersionRow, [string]>(
+      "SELECT * FROM page_versions WHERE pageId = ? ORDER BY version DESC",
+    )
+    .all(pageId)
+    .map(rowToPageVersion);
+}
+
+export function getPageVersion(pageId: string, version: number): PageVersion | null {
+  const row = getDb()
+    .prepare<PageVersionRow, [string, number]>(
+      "SELECT * FROM page_versions WHERE pageId = ? AND version = ?",
+    )
+    .get(pageId, version);
+  return row ? rowToPageVersion(row) : null;
+}
+
 // ============================================================================
 // Prompt Template Operations
 // ============================================================================
@@ -9439,3 +9695,295 @@ export function hasFirstCompletedTask(): boolean {
     .get();
   return row !== null;
 }
+
+// ============================================================================
+// KV store (kv_entries)
+// ============================================================================
+//
+// Namespaced key/value with lazy expire-on-read TTL. See:
+//   - src/be/migrations/061_kv_store.sql (schema)
+//   - src/http/kv.ts                     (REST surface + namespace resolution)
+//   - src/tools/kv/*                     (MCP surface)
+//
+// Conventions:
+//   - All sizing / regex validation happens at the HTTP / MCP boundary so the
+//     helpers below can assume well-formed inputs.
+//   - `value` is stored verbatim in TEXT; helpers decode based on value_type.
+//   - "now" is `unixepoch('subsec') * 1000` (unix-ms), consistent with the
+//     migration's DEFAULTs — using JS `Date.now()` for the few helpers that
+//     need to mention an explicit timestamp keeps the math identical at ms
+//     resolution.
+
+interface KvRow {
+  namespace: string;
+  key: string;
+  value: string;
+  value_type: KvValueType;
+  expires_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function decodeKvRow(row: KvRow): KvEntry {
+  let value: unknown;
+  if (row.value_type === "json") {
+    try {
+      value = JSON.parse(row.value);
+    } catch {
+      // Stored JSON is corrupt — surface as raw string rather than throwing
+      // on read; the row is still recoverable by the caller.
+      value = row.value;
+    }
+  } else if (row.value_type === "integer") {
+    value = Number(row.value);
+  } else {
+    value = row.value;
+  }
+  return {
+    namespace: row.namespace,
+    key: row.key,
+    value,
+    valueType: row.value_type,
+    expiresAt: row.expires_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function encodeKvValue(value: unknown, valueType: KvValueType): string {
+  if (valueType === "json") {
+    return JSON.stringify(value);
+  }
+  if (valueType === "integer") {
+    if (typeof value === "number") {
+      if (!Number.isInteger(value) || !Number.isSafeInteger(value)) {
+        throw new Error("integer value must be a JS-safe integer");
+      }
+      return String(value);
+    }
+    if (typeof value === "string" && /^-?\d+$/.test(value)) {
+      return value;
+    }
+    throw new Error("integer value must be a JS-safe integer");
+  }
+  // 'string'
+  if (typeof value !== "string") {
+    throw new Error("string value must be a string");
+  }
+  return value;
+}
+
+/**
+ * Get a single KV entry. Returns null if missing OR expired; expired rows are
+ * deleted inline (single-row DELETE WHERE) so the row count stays bounded over
+ * time without a background sweeper.
+ */
+export function getKv(namespace: string, key: string): KvEntry | null {
+  const row = getDb()
+    .prepare<KvRow, [string, string]>(
+      `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+         FROM kv_entries WHERE namespace = ? AND key = ?`,
+    )
+    .get(namespace, key);
+  if (!row) return null;
+  if (row.expires_at !== null && row.expires_at <= Date.now()) {
+    getDb()
+      .prepare<unknown, [string, string]>(`DELETE FROM kv_entries WHERE namespace = ? AND key = ?`)
+      .run(namespace, key);
+    return null;
+  }
+  return decodeKvRow(row);
+}
+
+/**
+ * Upsert a KV entry. Caller passes the decoded value + valueType; we encode
+ * before storing. `expiresAt` is unix-ms (NULL means no expiry).
+ *
+ * If the key already exists with a different `valueType` we still overwrite —
+ * INCR is the only collision-sensitive op and it does its own check.
+ */
+export function upsertKv(input: {
+  namespace: string;
+  key: string;
+  value: unknown;
+  valueType: KvValueType;
+  expiresAt?: number | null;
+}): KvEntry {
+  const encoded = encodeKvValue(input.value, input.valueType);
+  const expiresAt = input.expiresAt ?? null;
+  const now = Date.now();
+  const row = getDb()
+    .prepare<KvRow, [string, string, string, KvValueType, number | null, number, number]>(
+      `INSERT INTO kv_entries (namespace, key, value, value_type, expires_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(namespace, key) DO UPDATE SET
+         value = excluded.value,
+         value_type = excluded.value_type,
+         expires_at = excluded.expires_at,
+         updated_at = excluded.updated_at
+       RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+    )
+    .get(input.namespace, input.key, encoded, input.valueType, expiresAt, now, now);
+  if (!row) throw new Error("Failed to upsert kv entry");
+  return decodeKvRow(row);
+}
+
+/**
+ * Delete a KV entry. Returns true if a row was removed, false if nothing
+ * existed. Does not differentiate expired-but-not-yet-swept from never-existed.
+ */
+export function deleteKv(namespace: string, key: string): boolean {
+  const result = getDb()
+    .prepare<unknown, [string, string]>(`DELETE FROM kv_entries WHERE namespace = ? AND key = ?`)
+    .run(namespace, key);
+  return result.changes > 0;
+}
+
+export class KvTypeCollisionError extends Error {
+  readonly existingType: KvValueType;
+  constructor(existingType: KvValueType) {
+    super(`Cannot INCR a key with value_type '${existingType}'`);
+    this.name = "KvTypeCollisionError";
+    this.existingType = existingType;
+  }
+}
+
+/**
+ * Atomically increment an integer KV entry. Creates the entry (set to `by`)
+ * if it doesn't exist or has expired. Throws `KvTypeCollisionError` if the
+ * existing row's `value_type` is not 'integer' — the HTTP layer maps that to
+ * 409.
+ */
+export function incrKv(namespace: string, key: string, by: number): KvEntry {
+  if (!Number.isInteger(by) || !Number.isSafeInteger(by)) {
+    throw new Error("INCR `by` must be a JS-safe integer");
+  }
+  const database = getDb();
+  return database.transaction((): KvEntry => {
+    const existing = database
+      .prepare<KvRow, [string, string]>(
+        `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+           FROM kv_entries WHERE namespace = ? AND key = ?`,
+      )
+      .get(namespace, key);
+
+    const now = Date.now();
+    const expired =
+      existing?.expires_at !== null &&
+      existing !== null &&
+      existing.expires_at !== null &&
+      existing.expires_at <= now;
+
+    if (!existing || expired) {
+      // Insert (or replace if expired). `upsertKv` re-enters the prepared
+      // statement cache cheaply; inlining keeps this in one transaction.
+      const row = database
+        .prepare<KvRow, [string, string, string, number | null, number, number]>(
+          `INSERT INTO kv_entries (namespace, key, value, value_type, expires_at, created_at, updated_at)
+             VALUES (?, ?, ?, 'integer', ?, ?, ?)
+           ON CONFLICT(namespace, key) DO UPDATE SET
+             value = excluded.value,
+             value_type = excluded.value_type,
+             expires_at = excluded.expires_at,
+             updated_at = excluded.updated_at
+           RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+        )
+        .get(namespace, key, String(by), null, now, now);
+      if (!row) throw new Error("Failed to insert kv entry on INCR");
+      return decodeKvRow(row);
+    }
+
+    if (existing.value_type !== "integer") {
+      throw new KvTypeCollisionError(existing.value_type);
+    }
+
+    const current = Number(existing.value);
+    if (!Number.isSafeInteger(current)) {
+      throw new Error("Stored integer KV value is not a JS-safe integer");
+    }
+    const next = current + by;
+    if (!Number.isSafeInteger(next)) {
+      throw new Error("INCR would overflow JS-safe integer range");
+    }
+
+    const row = database
+      .prepare<KvRow, [string, number, string, string]>(
+        `UPDATE kv_entries SET value = ?, updated_at = ?
+           WHERE namespace = ? AND key = ?
+         RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+      )
+      .get(String(next), now, namespace, key);
+    if (!row) throw new Error("Failed to update kv entry on INCR");
+    return decodeKvRow(row);
+  })();
+}
+
+/**
+ * List entries in a namespace, optionally filtered by prefix. Expired rows
+ * are filtered out by the SELECT (no inline DELETE — listing should be a
+ * stable cursor; sweeping happens on point-reads instead).
+ *
+ * `limit` is capped by the caller (HTTP enforces ≤1000); helper does no extra
+ * bounds-check beyond what SQL accepts.
+ */
+export function listKv(
+  namespace: string,
+  opts: { prefix?: string; limit: number; offset: number },
+): KvEntry[] {
+  const now = Date.now();
+  if (opts.prefix !== undefined && opts.prefix.length > 0) {
+    // LIKE-escape `\` `%` `_` so a user-supplied prefix can't run wildcards.
+    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
+    const rows = getDb()
+      .prepare<KvRow, [string, number, string, number, number]>(
+        `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+           FROM kv_entries
+          WHERE namespace = ?
+            AND (expires_at IS NULL OR expires_at > ?)
+            AND key LIKE ? ESCAPE '\\'
+          ORDER BY key
+          LIMIT ? OFFSET ?`,
+      )
+      .all(namespace, now, `${escaped}%`, opts.limit, opts.offset);
+    return rows.map(decodeKvRow);
+  }
+  const rows = getDb()
+    .prepare<KvRow, [string, number, number, number]>(
+      `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+         FROM kv_entries
+        WHERE namespace = ?
+          AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY key
+        LIMIT ? OFFSET ?`,
+    )
+    .all(namespace, now, opts.limit, opts.offset);
+  return rows.map(decodeKvRow);
+}
+
+/**
+ * Count entries in a namespace (optionally with a prefix filter). Expired
+ * rows are excluded — same predicate as `listKv`.
+ */
+export function countKv(namespace: string, opts: { prefix?: string }): number {
+  const now = Date.now();
+  if (opts.prefix !== undefined && opts.prefix.length > 0) {
+    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
+    const row = getDb()
+      .prepare<{ n: number }, [string, number, string]>(
+        `SELECT COUNT(*) AS n FROM kv_entries
+          WHERE namespace = ?
+            AND (expires_at IS NULL OR expires_at > ?)
+            AND key LIKE ? ESCAPE '\\'`,
+      )
+      .get(namespace, now, `${escaped}%`);
+    return row?.n ?? 0;
+  }
+  const row = getDb()
+    .prepare<{ n: number }, [string, number]>(
+      `SELECT COUNT(*) AS n FROM kv_entries
+        WHERE namespace = ?
+          AND (expires_at IS NULL OR expires_at > ?)`,
+    )
+    .get(namespace, now);
+  return row?.n ?? 0;
+}

package/src/be/migrations/059_pages.sql

@@ -0,0 +1,34 @@
+-- DB-backed Pages (parent table) — lightweight artifacts stored in SQLite and
+-- served as HTML or JSON. Replaces PM2+localtunnel for static cases.
+--
+-- `body` stores agent-emitted content verbatim. For contentType='text/html',
+-- callers MAY pass either a fragment (`<h1>hi</h1>`) or a full document
+-- (`<!doctype html>...<html>...`). Step-3's `/p/:id` serving logic detects
+-- `<head>` and injects BROWSER_SDK_JS after it; if absent, it prepends.
+-- For contentType='application/json', the body is a JSON-render-compatible
+-- spec stored as a string (parsed at render time).
+--
+-- `needsCredentials` is reserved for follow-up credential capture work; the
+-- v1 renderer ignores it (Zod accepts, no UI prompt).
+--
+-- `authMode` CHECK constraint MUST stay in sync with PageAuthModeSchema in
+-- src/types.ts.
+
+CREATE TABLE IF NOT EXISTS pages (
+  id           TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  agentId      TEXT NOT NULL,
+  slug         TEXT NOT NULL,
+  title        TEXT NOT NULL,
+  description  TEXT,
+  contentType  TEXT NOT NULL CHECK (contentType IN ('text/html','application/json')),
+  authMode     TEXT NOT NULL DEFAULT 'public' CHECK (authMode IN ('public','authed','password')),
+  passwordHash TEXT,
+  body         TEXT NOT NULL,
+  needsCredentials TEXT,
+  createdAt    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updatedAt    TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (agentId, slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_pages_agentId ON pages(agentId);
+CREATE INDEX IF NOT EXISTS idx_pages_updatedAt ON pages(updatedAt DESC);

package/src/be/migrations/060_page_versions.sql

@@ -0,0 +1,19 @@
+-- DB-backed Pages (history table). Mirrors workflow_versions
+-- (008_workflow_redesign.sql:74-82) — parent table holds CURRENT state, this
+-- table holds the pre-update snapshot taken by snapshotPage() before each
+-- updatePage(). Head pointer is derived from MAX(version); no head_version
+-- column on the parent.
+--
+-- ON DELETE CASCADE: deleting a page removes its version history.
+
+CREATE TABLE IF NOT EXISTS page_versions (
+  id                  TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  pageId              TEXT NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+  version             INTEGER NOT NULL,
+  snapshot            TEXT NOT NULL,  -- JSON: PageSnapshot
+  changedByAgentId    TEXT,
+  createdAt           TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (pageId, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_page_versions_pageId ON page_versions(pageId);

package/src/be/migrations/061_kv_store.sql

@@ -0,0 +1,34 @@
+-- KV store: one table, namespaced. Namespace mirrors `agent_tasks.contextKey`
+-- (task:slack:..., task:trackers:..., task:agent:..., task:page:..., etc.)
+-- so the same string used to find sibling tasks for a Slack thread / PR /
+-- Linear issue also indexes KV state for that entity.
+--
+-- value_type:
+--   'json'    — `value` is the JSON-encoded payload (default; arbitrary shape).
+--   'string'  — `value` is the raw UTF-8 string verbatim.
+--   'integer' — `value` is the decimal-string form of a JS-safe integer.
+--               INCR uses this column; mixing with 'json'/'string' returns 409.
+--
+-- expires_at:
+--   Unix-ms (matches `unixepoch('subsec') * 1000`). NULL means never expires.
+--   Lazy expire on read: getKv DELETEs single expired rows; listKv filters in
+--   the SELECT but does not delete (keeps cursors stable). No background sweep.
+--
+-- WITHOUT ROWID: every read is by full PK (namespace, key); the rowid -> btree
+-- hop is wasted.
+
+CREATE TABLE IF NOT EXISTS kv_entries (
+  namespace   TEXT NOT NULL,
+  key         TEXT NOT NULL,
+  value       TEXT NOT NULL,
+  value_type  TEXT NOT NULL DEFAULT 'json'
+                CHECK (value_type IN ('json','string','integer')),
+  expires_at  INTEGER,
+  created_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+  updated_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+  PRIMARY KEY (namespace, key)
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS idx_kv_expires
+  ON kv_entries(expires_at)
+  WHERE expires_at IS NOT NULL;

package/src/be/migrations/062_pages_view_count.sql

@@ -0,0 +1,9 @@
+-- Adds a per-page view counter to the `pages` table. Bumped on every
+-- successful 200 from `GET /p/:id` (HTML inline serve) and `GET /p/:id.json`
+-- (JSON metadata fetch). 302/401/403/404 responses do NOT bump. No
+-- per-viewer dedup — Taras explicitly wanted a "super simple counter field".
+--
+-- Bump path: src/http/pages-public.ts → bumpViewCount() → incrementPageViewCount()
+-- in src/be/db.ts. Wrapped in try/catch so analytics never breaks page serving.
+
+ALTER TABLE pages ADD COLUMN view_count INTEGER NOT NULL DEFAULT 0;