@desplega.ai/agent-swarm 2.4.1 → 2.4.2

package/src/apps/definition.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import { listScriptConnections } from "../be/script-connections";
 import { getScriptById } from "../be/scripts/db";
 import { getSavedScriptOwnerAgentId } from "../be/scripts/run-saved";
+import { APPS_JSON_COLUMN_MAX_BYTES_BOUNDS } from "../be/swarm-config-guard";
 import { checkQuickJSCompat, quickJSCompatWarnings } from "../scripts-runtime/quickjs-compat";
 import catalog from "./catalog.generated.json";
 import {
@@ -16,7 +17,13 @@ export const AppNameSchema = z.string().regex(/^[a-z][a-zA-Z0-9_]{0,39}$/, {
   message: "must start with a lowercase letter and contain only letters, numbers, or underscores",
 });
 
-export const ColumnKindSchema = z.enum(["string", "number", "boolean", "date", "enum"]);
+export const ColumnKindSchema = z.enum(["string", "number", "boolean", "date", "enum", "json"]);
+
+/**
+ * Column kinds allowed where values must stay scalar (user-config fields and
+ * element props) — `json` is model-column only.
+ */
+export const ScalarColumnKindSchema = ColumnKindSchema.exclude(["json"]);
 
 const ISO_8601_PREFIX = /^\d{4}-\d{2}-\d{2}(?:T.*)?$/;
 
@@ -24,6 +31,77 @@ export function isIso8601Date(value: string): boolean {
   return ISO_8601_PREFIX.test(value) && !Number.isNaN(Date.parse(value));
 }
 
+/** Default serialized-size cap for json column values AND defaults: 256 KB. */
+export const DEFAULT_JSON_COLUMN_MAX_BYTES = 256 * 1024;
+
+/**
+ * The serialized-size cap for json column values and defaults, read on every
+ * call — never at module load — so a stored `APPS_JSON_COLUMN_MAX_BYTES`
+ * override, injected over the process env on config reload, applies without
+ * a restart. Mirrors the retention knobs: a non-digit or out-of-range value
+ * falls back to the default, and the config API rejects writes outside the
+ * same `APPS_JSON_COLUMN_MAX_BYTES_BOUNDS`.
+ */
+export function jsonColumnMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.APPS_JSON_COLUMN_MAX_BYTES?.trim();
+  if (!raw || !/^\d+$/.test(raw)) return DEFAULT_JSON_COLUMN_MAX_BYTES;
+  const value = Number(raw);
+  const { min, max } = APPS_JSON_COLUMN_MAX_BYTES_BOUNDS;
+  return Number.isSafeInteger(value) && value >= min && value <= max
+    ? value
+    : DEFAULT_JSON_COLUMN_MAX_BYTES;
+}
+
+/** The cap as a message label: whole KB when it divides evenly (`256KB`), else bytes. */
+export function jsonColumnSizeLabel(bytes: number = jsonColumnMaxBytes()): string {
+  return bytes % 1024 === 0 ? `${bytes / 1024}KB` : `${bytes} bytes`;
+}
+
+export type JsonColumnValueIssue = "unserializable" | "non-finite" | "oversized";
+
+/**
+ * Why a value cannot live in a json column — not JSON-serializable, carrying a
+ * non-finite number anywhere inside it, or over `jsonColumnMaxBytes()` once
+ * serialized — or `null` when it fits. The single implementation of the cap:
+ * it serializes exactly once, flagging non-finite numbers on that same walk
+ * (a lenient parser turns `1e400` into `Infinity`, which `JSON.stringify`
+ * would quietly store as `null`), and each caller maps the reason to its own
+ * message.
+ */
+export function jsonColumnValueIssue(value: unknown): JsonColumnValueIssue | null {
+  let nonFinite = false;
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(value, (_key, entry: unknown) => {
+      if (typeof entry === "number" && !Number.isFinite(entry)) nonFinite = true;
+      return entry;
+    });
+  } catch {
+    return "unserializable"; // circular reference / BigInt / throwing toJSON
+  }
+  if (serialized === undefined) return "unserializable";
+  if (nonFinite) return "non-finite";
+  return Buffer.byteLength(serialized, "utf8") > jsonColumnMaxBytes() ? "oversized" : null;
+}
+
+/**
+ * The one per-kind check for a NON-null column value, shared by the row store,
+ * schema migrations and the sync engine so a value the store accepts is a
+ * value a migration directive or a projection accepts too. Null policy
+ * (required / hidden / nulling a projection) stays with each caller.
+ */
+export function isValidColumnValue(
+  column: Pick<ColumnDef, "kind" | "enum">,
+  value: unknown,
+): boolean {
+  if (column.kind === "string") return typeof value === "string";
+  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
+  if (column.kind === "boolean") return typeof value === "boolean";
+  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
+  if (column.kind === "json") return jsonColumnValueIssue(value) === null;
+  return typeof value === "string" && Boolean(column.enum?.includes(value));
+}
+
 export const SourceTransformSchema = z.enum(["slug", "lower", "upper", "cents", "date-parse"]);
 
 /** Column kind each transform may target — the sync engine projects into it. */
@@ -49,11 +127,23 @@ const ColumnDefSchema = z
     required: z.boolean().optional(),
     enum: z.array(z.string()).optional(),
     index: z.boolean().optional(),
-    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    default: z
+      .union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.record(z.string(), z.unknown()),
+        z.array(z.unknown()),
+      ])
+      .optional(),
     hidden: z.boolean().optional(),
     source: ColumnSourceBindingSchema.optional(),
   })
   .superRefine((column, ctx) => {
+    if (column.kind === "json" && column.index) {
+      ctx.addIssue({ code: "custom", path: ["index"], message: "json columns cannot be indexed" });
+    }
+
     if (column.kind === "enum") {
       if (!column.enum || column.enum.length === 0) {
         ctx.addIssue({ code: "custom", path: ["enum"], message: "enum values are required" });
@@ -71,6 +161,24 @@ const ColumnDefSchema = z
     }
 
     if (column.default === undefined) return;
+    if (column.kind === "json") {
+      // Structural checks only; the size cap is write-time (`jsonColumnDefaultSizeIssues`).
+      const issue = jsonColumnValueIssue(column.default);
+      if (issue === "unserializable") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["default"],
+          message: "json column default must be JSON-serializable",
+        });
+      } else if (issue === "non-finite") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["default"],
+          message: "json column default contains a non-finite number",
+        });
+      }
+      return;
+    }
     const valid =
       (column.kind === "string" && typeof column.default === "string") ||
       (column.kind === "number" &&
@@ -94,7 +202,7 @@ const ColumnDefSchema = z
 
 const UserConfigFieldSchema = z
   .object({
-    kind: ColumnKindSchema,
+    kind: ScalarColumnKindSchema,
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
     enum: z.array(z.string()).optional(),
     label: z.string().optional(),
@@ -276,7 +384,7 @@ const AppPageSchema = z
 
 const ElementPropDefSchema = z
   .object({
-    kind: ColumnKindSchema,
+    kind: ScalarColumnKindSchema,
     required: z.boolean().optional(),
     enum: z.array(z.string()).min(1).optional(),
     default: z.union([z.string(), z.number(), z.boolean()]).optional(),
@@ -439,6 +547,14 @@ export const AppDefinitionSchema = z
           });
           continue;
         }
+        if (columnDefinition.kind === "json") {
+          ctx.addIssue({
+            code: "custom",
+            path: ["queries", queryName, "filter", column],
+            message: "json columns cannot be filtered",
+          });
+          continue;
+        }
         if (typeof value === "object") continue;
         const valid =
           (columnDefinition.kind === "string" && typeof value === "string") ||
@@ -469,6 +585,12 @@ export const AppDefinitionSchema = z
           path: ["queries", queryName, "sort", "column"],
           message: `unknown or hidden column "${sortColumn}"`,
         });
+      } else if (sortColumn && model.columns[sortColumn]?.kind === "json") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["queries", queryName, "sort", "column"],
+          message: "json columns cannot be sorted",
+        });
       }
     }
   });
@@ -836,6 +958,31 @@ function syncActionIssues(
   return [{ path: `actions.${name}`, message: "no model declares a source to sync" }];
 }
 
+/**
+ * The serialized-size cap on json column defaults, applied on definition
+ * WRITES only. It lives outside `AppDefinitionSchema` on purpose: the schema
+ * also decodes persisted definitions (`decodeAppDefinition`, the row store's
+ * model lookup), and a cap lowered after an app was saved must not turn that
+ * app into one that "needs repair" on every read. Writing the definition
+ * again re-applies the current cap. An oversized default would otherwise be
+ * accepted only to fail every row create that relies on it.
+ */
+function jsonColumnDefaultSizeIssues(definition: AppDefinition): AppValidationIssue[] {
+  const issues: AppValidationIssue[] = [];
+  for (const [modelName, model] of Object.entries(definition.models)) {
+    for (const [columnName, column] of Object.entries(model.columns)) {
+      if (column.kind !== "json" || column.default === undefined) continue;
+      if (jsonColumnValueIssue(column.default) === "oversized") {
+        issues.push({
+          path: `models.${modelName}.columns.${columnName}.default`,
+          message: `json column default exceeds the ${jsonColumnSizeLabel()} size limit`,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
 export async function parseAppDefinition(
   input: unknown,
   elementContext: AppDefinitionParseContext = {},
@@ -871,6 +1018,7 @@ export async function parseAppDefinition(
   if (!parsed.success) return { success: false, issues: appDefinitionIssues(parsed.error) };
 
   const issues = [
+    ...jsonColumnDefaultSizeIssues(parsed.data),
     ...Object.keys(parsed.data.pages).flatMap((pageName) =>
       validatePage(parsed.data, catalog, pageName),
     ),

package/src/apps/row-store.ts

@@ -4,7 +4,9 @@ import {
   AppDefinitionSchema,
   type AppValidationIssue,
   type ColumnDef,
-  isIso8601Date,
+  isValidColumnValue,
+  jsonColumnSizeLabel,
+  jsonColumnValueIssue,
   type ModelDef,
 } from "./definition";
 import { upgradeAppDefinition } from "./format-upgrades";
@@ -94,6 +96,7 @@ export function appIndexKey(model: string, column: string, value: unknown, rowId
 
 function isIndexed(column: ColumnDef): boolean {
   if (column.hidden === true) return false;
+  if (column.kind === "json") return false;
   if (column.kind === "enum") return true;
   return column.index === true && (column.kind === "string" || column.kind === "boolean");
 }
@@ -111,11 +114,7 @@ function indexKeys(model: string, definition: ModelDef, row: AppRow): string[] {
 
 export function validValue(column: ColumnDef, value: unknown): boolean {
   if (value === null) return column.required !== true;
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
+  return isValidColumnValue(column, value);
 }
 
 function joinKeyColumnNames(definition: ModelDef): Set<string> {
@@ -185,7 +184,20 @@ function prepareValues(
   for (const [name, value] of Object.entries(prepared)) {
     if (!Object.hasOwn(definition.columns, name)) continue;
     const column = definition.columns[name]!;
-    if (!validValue(column, value)) {
+    if (column.kind === "json" && value !== null) {
+      // Asked directly so the value is serialized once and the size cap gets its own message.
+      const issue = jsonColumnValueIssue(value);
+      if (issue === "unserializable") {
+        issues.push({ path: `values.${name}`, message: "must be a valid json value" });
+      } else if (issue === "non-finite") {
+        issues.push({ path: `values.${name}`, message: "json value contains a non-finite number" });
+      } else if (issue === "oversized") {
+        issues.push({
+          path: `values.${name}`,
+          message: `json value exceeds the ${jsonColumnSizeLabel()} size limit`,
+        });
+      }
+    } else if (!validValue(column, value)) {
       issues.push({ path: `values.${name}`, message: `must be a valid ${column.kind} value` });
     }
   }

package/src/apps/schema-migrate.ts

@@ -8,6 +8,7 @@ import {
   type AppValidationIssue,
   type ColumnDef,
   isIso8601Date,
+  isValidColumnValue,
   type ModelDef,
   parseAppDefinition,
   type SourceDef,
@@ -23,7 +24,18 @@ import {
 } from "./row-store";
 import { invalidateChangedSyncStatus } from "./sync";
 
-const MigrationValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+/**
+ * Literal directive values (`set`, `map` targets, `else`): scalars, plus the
+ * objects and arrays a `json` column holds. The per-column kind check in
+ * `validateDirectiveValues` is what rejects a shape the target column cannot take.
+ */
+const MigrationValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+]);
 
 export const AppMigrationDirectiveSchema = z.union([
   z.object({ set: MigrationValueSchema }).strict(),
@@ -368,11 +380,7 @@ function isPurgeDirective(
 
 function columnAccepts(column: ColumnDef, value: unknown): boolean {
   if (value === null) return column.hidden === true || column.required !== true;
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
+  return isValidColumnValue(column, value);
 }
 
 function coerceValue(

package/src/apps/script-types.ts

@@ -69,6 +69,7 @@ function commentSafe(value: string): string {
 }
 
 function tsTypeForColumn(column: Pick<ColumnDef, "kind" | "enum">): string {
+  if (column.kind === "json") return "unknown";
   if (column.kind !== "enum") return column.kind === "date" ? "string" : column.kind;
   return column.enum?.map((value) => JSON.stringify(value)).join(" | ") || "string";
 }

package/src/apps/sync.ts

@@ -9,7 +9,7 @@ import {
   type AppDefinition,
   type AppValidationIssue,
   type ColumnDef,
-  isIso8601Date,
+  isValidColumnValue,
   type ModelDef,
   type SourceDef,
   type SourceTransform,
@@ -484,19 +484,6 @@ function applyTransform(value: unknown, transform: SourceTransform | undefined):
   }
 }
 
-/**
- * Mirrors the row-store's per-kind value check. Projections are pre-validated
- * here so one bad field nulls one column instead of throwing mid-reconcile and
- * leaving the pass half-applied.
- */
-function validForKind(column: ColumnDef, value: unknown): boolean {
-  if (column.kind === "string") return typeof value === "string";
-  if (column.kind === "number") return typeof value === "number" && Number.isFinite(value);
-  if (column.kind === "boolean") return typeof value === "boolean";
-  if (column.kind === "date") return typeof value === "string" && isIso8601Date(value);
-  return typeof value === "string" && Boolean(column.enum?.includes(value));
-}
-
 function projectRecord(args: {
   record: SourceRecord;
   bindings: Array<[string, ColumnDef]>;
@@ -518,7 +505,10 @@ function projectRecord(args: {
       );
       value = null;
     }
-    if (value !== null && !validForKind(column, value)) {
+    // Projections are pre-validated with the row store's own kind check so one
+    // bad field nulls one column instead of throwing mid-reconcile and leaving
+    // the pass half-applied.
+    if (value !== null && !isValidColumnValue(column, value)) {
       warn(
         args.warnings,
         `column "${name}": field "${binding.field}" produced a value that is not a valid ${column.kind}`,
@@ -530,9 +520,20 @@ function projectRecord(args: {
   return values;
 }
 
-/** A missing column and an explicit null are the same absence of a value. */
-function sameValue(existing: unknown, projected: unknown): boolean {
-  return Object.is(existing ?? null, projected ?? null);
+/**
+ * A missing column and an explicit null are the same absence of a value. A
+ * json column compares structurally — the value decoded from storage is never
+ * the same object as a fresh projection — every other kind by identity.
+ */
+function sameValue(
+  column: ModelDef["columns"][string] | undefined,
+  existing: unknown,
+  projected: unknown,
+): boolean {
+  const before = existing ?? null;
+  const after = projected ?? null;
+  if (column?.kind === "json") return Bun.deepEquals(before, after);
+  return Object.is(before, after);
 }
 
 // ---------------------------------------------------------------------------
@@ -701,7 +702,7 @@ function reconcile(args: {
         return;
       }
       const differs = Object.entries(values).some(
-        ([name, value]) => !sameValue(existing[name], value),
+        ([name, value]) => !sameValue(modelDef.columns[name], existing[name], value),
       );
       const updated = await patchAppRowUnlocked(appId, model, modelDef, existing.id, values, {
         allowSourceManaged: true,

package/src/be/db/tasks/read.ts

@@ -436,6 +436,118 @@ export async function getChildTasks(parentTaskId: string): Promise<AgentTask[]>
   return rows.map(rowToAgentTask);
 }
 
+/** Caps for {@link getTaskLineage}: a fan-out of thousands still answers in one bounded read. */
+export const TASK_LINEAGE_LIMITS = { maxNodes: 500, maxDepth: 30, maxAncestors: 50 } as const;
+
+/** One task in a lineage tree: the slim list row plus the workflow run it belongs to. */
+type TaskLineageNode = AgentTaskSummary & { workflowRunId?: string };
+
+interface TaskLineage {
+  /** The topmost ancestor reached (the session root unless `truncated`). */
+  rootTaskId: string;
+  /** Root first, then descendants; always holds the path root → `taskId`. */
+  tasks: TaskLineageNode[];
+  /** True when some ancestor or descendant is missing from `tasks`. */
+  truncated: boolean;
+}
+
+const LINEAGE_COLUMNS = `${LIST_COLUMNS.slim}, agent_tasks.workflowRunId,
+  (SELECT SUM(totalCostUsd) FROM session_costs WHERE session_costs.taskId = agent_tasks.id) AS totalCostUsd`;
+
+type TaskLineageRow = AgentTaskSummaryRow & { workflowRunId: string | null };
+
+function rowToTaskLineageNode(row: TaskLineageRow): TaskLineageNode {
+  return { ...rowToAgentTaskSummary(row), workflowRunId: row.workflowRunId ?? undefined };
+}
+
+/**
+ * The whole tree `taskId` belongs to, following `parentTaskId`: up to the
+ * topmost ancestor, then every descendant of that root breadth-first. The
+ * descendants of `taskId` itself are walked first, so a wide tree cut at
+ * `maxNodes` still shows the task's own subtree. Read-only and bounded: at
+ * most `maxAncestors` hops up, `maxDepth` levels down and about `2 * maxNodes`
+ * rows. Null when the task does not exist.
+ */
+export async function getTaskLineage(
+  taskId: string,
+  limits: { maxNodes?: number; maxDepth?: number; maxAncestors?: number } = {},
+): Promise<TaskLineage | null> {
+  const maxNodes = limits.maxNodes ?? TASK_LINEAGE_LIMITS.maxNodes;
+  const maxDepth = limits.maxDepth ?? TASK_LINEAGE_LIMITS.maxDepth;
+  const maxAncestors = limits.maxAncestors ?? TASK_LINEAGE_LIMITS.maxAncestors;
+  const db = getDbClient();
+  // Hops are counted, so a parentTaskId cycle stops at the cap instead of looping.
+  const path = await db.query<{ id: string; parentTaskId: string | null; hops: number }>(
+    `WITH RECURSIVE up(id, parentTaskId, hops) AS (
+         SELECT id, parentTaskId, 0 FROM agent_tasks WHERE id = ?
+         UNION ALL
+         SELECT t.id, t.parentTaskId, up.hops + 1 FROM agent_tasks t
+         JOIN up ON t.id = up.parentTaskId
+         WHERE up.hops < ?
+       )
+       SELECT id, parentTaskId, hops FROM up ORDER BY hops`,
+    [taskId, maxAncestors],
+  );
+  if (path.length === 0) return null;
+  const top = path[path.length - 1]!;
+  // A parent that no longer exists ends the walk like a root; a cap does not.
+  let truncated = top.hops === maxAncestors && top.parentTaskId !== null;
+
+  // LIMIT inside the recursive CTE stops the walk itself, not just the output.
+  const descendants = (startId: string) =>
+    db.query<TaskLineageRow>(
+      `WITH RECURSIVE down(id, depth) AS (
+           SELECT ?, 0
+           UNION ALL
+           SELECT t.id, down.depth + 1 FROM down
+           JOIN agent_tasks t ON t.parentTaskId = down.id
+           WHERE down.depth < ?
+           ORDER BY 2
+           LIMIT ?
+         )
+         SELECT ${LINEAGE_COLUMNS} FROM down
+         CROSS JOIN agent_tasks ON agent_tasks.id = down.id
+         ORDER BY down.depth, agent_tasks.createdAt, agent_tasks.rowid`,
+      [startId, maxDepth, maxNodes + 1],
+    );
+
+  const byId = new Map<string, TaskLineageNode>();
+  const add = (rows: TaskLineageRow[]) => {
+    for (const row of rows) {
+      if (!byId.has(row.id)) byId.set(row.id, rowToTaskLineageNode(row));
+    }
+  };
+  const ownSubtree = await descendants(taskId);
+  const fromRoot = top.id === taskId ? ownSubtree : await descendants(top.id);
+  add(fromRoot.slice(0, maxNodes));
+  add(ownSubtree.slice(0, maxNodes));
+
+  // The path root → task is always present, even past the depth or node cap.
+  const missing = path.map((row) => row.id).filter((id) => !byId.has(id));
+  if (missing.length > 0) {
+    add(
+      await db.query<TaskLineageRow>(
+        `SELECT ${LINEAGE_COLUMNS} FROM agent_tasks WHERE id IN (${missing.map(() => "?").join(", ")})`,
+        missing,
+      ),
+    );
+  }
+
+  // The caps cut the walk at many points (depth, node count, either walk), so
+  // ask the table directly: is any child of a returned task not returned?
+  if (!truncated) {
+    const ids = [...byId.keys()];
+    const list = ids.map(() => "?").join(", ");
+    const omitted = await db.get(
+      `SELECT 1 FROM agent_tasks WHERE parentTaskId IN (${list}) AND id NOT IN (${list}) LIMIT 1`,
+      [...ids, ...ids],
+    );
+    truncated = omitted !== undefined && omitted !== null;
+  }
+
+  return { rootTaskId: top.id, tasks: [...byId.values()], truncated };
+}
+
 /**
  * Returns true if `parentId` has at least one non-terminal child task with
  * `taskType = 'resume'`. Used by the heartbeat sweep as an idempotency guard:

package/src/be/db.ts

@@ -327,6 +327,7 @@ export {
   getSupersededTasksWithoutResume,
   getSupersededTasksWithUnsettledDependents,
   getTaskById,
+  getTaskLineage,
   getTaskStats,
   getTasksByAgentId,
   getTasksByStatus,
@@ -346,6 +347,7 @@ export {
   recordChatRelayError,
   resetTasksNotified,
   SUPERSEDED_RESUME_REPAIR_WINDOW_MS,
+  TASK_LINEAGE_LIMITS,
   type TaskFilters,
 } from "./db/tasks/read";
 

package/src/be/swarm-config-guard.ts

@@ -139,6 +139,16 @@ export const DB_RETENTION_TUNING_BOUNDS = {
   DB_RETENTION_MAX_STATEMENT_MS: { min: 25, max: 5_000 },
 } as const;
 
+/**
+ * Bounds for the Swarm Apps json column size cap (`APPS_JSON_COLUMN_MAX_BYTES`).
+ *
+ * `src/apps/definition.ts` reads the knob against exactly these at call time
+ * and falls back to its 256 KB default outside them; VALIDATED_KEYS below
+ * rejects out-of-range writes with the same numbers, so the config API cannot
+ * accept a cap the row store would silently ignore.
+ */
+export const APPS_JSON_COLUMN_MAX_BYTES_BOUNDS = { min: 1_024, max: 16_777_216 } as const;
+
 /** Build `{ KEY: validator }` entries accepting only boolean literals. */
 function booleanValidators(keys: string[]): Record<string, ConfigValidator> {
   const message = (key: string) =>
@@ -527,6 +537,11 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // an operator could save a 500ms tick budget, see it accepted, and have the
   // sweep keep running for the default 30000ms.
   ...boundedIntegerValidatorsFor(DB_RETENTION_TUNING_BOUNDS),
+  ...boundedIntegerValidators(
+    ["APPS_JSON_COLUMN_MAX_BYTES"],
+    APPS_JSON_COLUMN_MAX_BYTES_BOUNDS.min,
+    APPS_JSON_COLUMN_MAX_BYTES_BOUNDS.max,
+  ),
   ...boundedIntegerValidators(
     [
       "SESSION_LOG_RETENTION_DAYS",

package/src/http/apps.ts

@@ -8,10 +8,10 @@ import {
   type AppQueryDef,
   type AppValidationIssue,
   applyAppDefinitionPatch,
-  ColumnKindSchema,
   isIso8601Date,
   type ModelDef,
   parseAppDefinition,
+  ScalarColumnKindSchema,
   SORTABLE_SYSTEM_DATE_COLUMNS,
   SYSTEM_COLUMN_KINDS,
   scriptCompatWarnings,
@@ -216,7 +216,7 @@ const UserConfigValuesSchema = z.record(
  * on the wire anyway — the key can only ever be absent.
  */
 const AppUserConfigFieldSchema = z.object({
-  kind: ColumnKindSchema,
+  kind: ScalarColumnKindSchema,
   default: z.union([z.string(), z.number(), z.boolean()]).optional(),
   enum: z.array(z.string()).optional(),
   label: z.string().optional(),
@@ -785,6 +785,7 @@ async function resolveModel(
 }
 
 function parseFilterValue(raw: string, column: ModelDef["columns"][string]): unknown {
+  if (column.kind === "json") throw new Error("json columns cannot be filtered");
   if (column.kind === "number") {
     if (!DECIMAL_NUMBER_PATTERN.test(raw)) throw new Error("must be a decimal number");
     const value = Number(raw);
@@ -1017,6 +1018,15 @@ export async function selectAppRows(
   limit = 200,
   systemColumns = false,
 ) {
+  // Backstop for every caller: the REST route (`filter.<col>`) and the MCP
+  // tools (`equals.<col>`) reject json filters with their own paths first.
+  const jsonFilterIssues = filters.flatMap((filter) =>
+    Object.hasOwn(model.columns, filter.column) && model.columns[filter.column]!.kind === "json"
+      ? [{ path: `filter.${filter.column}`, message: "json columns cannot be filtered" }]
+      : [],
+  );
+  if (jsonFilterIssues.length > 0) throw new AppRowValidationError(jsonFilterIssues);
+
   // SQL narrows the scan; the `===` re-check keeps the exact filter semantics.
   const rows = (
     await listAppRows(
@@ -1046,6 +1056,9 @@ export async function selectAppRows(
         { path: "sort", message: "must be <column>:<asc|desc> for a known column" },
       ]);
     }
+    if (model.columns[column]?.kind === "json") {
+      throw new AppRowValidationError([{ path: "sort", message: "json columns cannot be sorted" }]);
+    }
     rows.sort((a, b) => {
       const result = compareValues(
         rowValue(a, column),