@agent-native/core 0.122.1 → 0.122.2

package/corpus/templates/analytics/server/lib/first-party-unbounded-panel-repair.ts

@@ -0,0 +1,169 @@
+import type { Dialect } from "@agent-native/core/db";
+
+import type { DashboardPanelLike } from "./dashboard-time-scope.js";
+
+const POSTGRES_DATE_BOUND =
+  "to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')";
+const SQLITE_DATE_BOUND = "date('now', '-365 days')";
+
+/**
+ * Fixes for first-party dashboard panels found, via a full-org audit
+ * (2026-07-25), reading `analytics_events` with no date bound at all in some
+ * or all of their scan units — a full 6.7M-row table scan on every render.
+ * Unlike the id-keyed replacements in first-party-metric-catalog.ts (which
+ * repair one specific dashboard's known panel ids), these are matched purely
+ * by exact SQL text so the same fix applies wherever the identical broken
+ * query was cloned into a different dashboard under a different panel id.
+ * Each entry only changes the added bound (`AND event_date >= ...365 days`,
+ * or the exact same bound already live on the repaired canonical dashboard
+ * for the retention-cohort case) — never the query's selected columns,
+ * grouping, or business logic.
+ */
+export type UnboundedFirstPartyPanelFix = {
+  legacySql: string;
+  sql: string;
+};
+
+function dialectBoundedSql(sql: string, dialect: Dialect): string {
+  return dialect === "postgres"
+    ? sql
+    : sql.split(POSTGRES_DATE_BOUND).join(SQLITE_DATE_BOUND);
+}
+
+export const UNBOUNDED_FIRST_PARTY_PANEL_FIXES: readonly UnboundedFirstPartyPanelFix[] =
+  [
+    {
+      legacySql:
+        "SELECT event_date AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY event_date ORDER BY date",
+      sql: "SELECT event_date AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') GROUP BY event_date ORDER BY date",
+    },
+    {
+      legacySql:
+        "SELECT COALESCE(NULLIF(signed_in, ''), 'unknown') AS signed_in, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY COALESCE(NULLIF(signed_in, ''), 'unknown') ORDER BY signed_in",
+      sql: "SELECT COALESCE(NULLIF(signed_in, ''), 'unknown') AS signed_in, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') GROUP BY COALESCE(NULLIF(signed_in, ''), 'unknown') ORDER BY signed_in",
+    },
+    {
+      legacySql:
+        "SELECT COALESCE(NULLIF(app, ''), 'unknown') AS app, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' GROUP BY COALESCE(NULLIF(app, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+      sql: "SELECT COALESCE(NULLIF(app, ''), 'unknown') AS app, COUNT(*) AS count FROM analytics_events WHERE event_name = 'session status' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') GROUP BY COALESCE(NULLIF(app, ''), 'unknown') ORDER BY count DESC LIMIT 20",
+    },
+    {
+      legacySql:
+        "SELECT COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli started'",
+      sql: "SELECT COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli started' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')",
+    },
+    {
+      legacySql:
+        "SELECT COUNT(DISTINCT anonymous_id) AS count FROM analytics_events WHERE event_name LIKE 'skills_cli %'",
+      sql: "SELECT COUNT(DISTINCT anonymous_id) AS count FROM analytics_events WHERE event_name LIKE 'skills_cli %' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')",
+    },
+    {
+      legacySql:
+        "SELECT COUNT(DISTINCT session_id) AS count FROM analytics_events WHERE event_name = 'skills_cli install completed'",
+      sql: "SELECT COUNT(DISTINCT session_id) AS count FROM analytics_events WHERE event_name = 'skills_cli install completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')",
+    },
+    {
+      legacySql:
+        "WITH started AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli started'), completed AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli install completed') SELECT CASE WHEN started.n = 0 THEN 0 ELSE ROUND(completed.n * 100.0 / started.n) END AS rate FROM started, completed",
+      sql: "WITH started AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli started' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')), completed AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli install completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')) SELECT CASE WHEN started.n = 0 THEN 0 ELSE ROUND(completed.n * 100.0 / started.n) END AS rate FROM started, completed",
+    },
+    {
+      legacySql:
+        "WITH steps AS (SELECT 1 AS step_order, 'Started' AS step, COUNT(DISTINCT session_id) AS count FROM analytics_events WHERE event_name = 'skills_cli started' UNION ALL SELECT 2, 'Skills prompted', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills prompted' UNION ALL SELECT 3, 'Skills selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills selected' UNION ALL SELECT 4, 'Clients selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli clients selected' UNION ALL SELECT 5, 'Scope selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli scope selected' UNION ALL SELECT 6, 'Install completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli install completed' UNION ALL SELECT 7, 'Completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli completed') SELECT step, count FROM steps ORDER BY step_order",
+      sql: "WITH steps AS (SELECT 1 AS step_order, 'Started' AS step, COUNT(DISTINCT session_id) AS count FROM analytics_events WHERE event_name = 'skills_cli started' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 2, 'Skills prompted', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills prompted' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 3, 'Skills selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 4, 'Clients selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli clients selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 5, 'Scope selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli scope selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 6, 'Install completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli install completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 7, 'Completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')) SELECT step, count FROM steps ORDER BY step_order",
+    },
+    {
+      legacySql:
+        "SELECT trim(s) AS skill, COUNT(*) AS count FROM analytics_events, LATERAL unnest(string_to_array(properties::jsonb ->> 'selected', ',')) AS s WHERE event_name = 'skills_cli skills selected' AND (properties::jsonb ->> 'selected') <> '' GROUP BY trim(s) ORDER BY count DESC LIMIT 30",
+      sql: "SELECT trim(s) AS skill, COUNT(*) AS count FROM analytics_events, LATERAL unnest(string_to_array(properties::jsonb ->> 'selected', ',')) AS s WHERE event_name = 'skills_cli skills selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND (properties::jsonb ->> 'selected') <> '' GROUP BY trim(s) ORDER BY count DESC LIMIT 30",
+    },
+    {
+      legacySql:
+        "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli started' GROUP BY substr(timestamp, 1, 10) ORDER BY date",
+      sql: "SELECT substr(timestamp, 1, 10) AS date, COUNT(*) AS count FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND event_name = 'skills_cli started' GROUP BY substr(timestamp, 1, 10) ORDER BY date",
+    },
+    {
+      legacySql:
+        "SELECT COALESCE(NULLIF(properties::jsonb ->> 'cli', ''), 'unknown') AS cli, COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli started' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'cli', ''), 'unknown') ORDER BY count DESC",
+      sql: "SELECT COALESCE(NULLIF(properties::jsonb ->> 'cli', ''), 'unknown') AS cli, COUNT(*) AS count FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND event_name = 'skills_cli started' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'cli', ''), 'unknown') ORDER BY count DESC",
+    },
+    {
+      legacySql:
+        "SELECT COALESCE(NULLIF(properties::jsonb ->> 'platform', ''), 'unknown') AS platform, COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli started' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'platform', ''), 'unknown') ORDER BY count DESC",
+      sql: "SELECT COALESCE(NULLIF(properties::jsonb ->> 'platform', ''), 'unknown') AS platform, COUNT(*) AS count FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND event_name = 'skills_cli started' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'platform', ''), 'unknown') ORDER BY count DESC",
+    },
+    {
+      legacySql:
+        "SELECT COALESCE(NULLIF(properties::jsonb ->> 'scope', ''), 'unknown') AS scope, COUNT(*) AS count FROM analytics_events WHERE event_name = 'skills_cli scope selected' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'scope', ''), 'unknown') ORDER BY count DESC",
+      sql: "SELECT COALESCE(NULLIF(properties::jsonb ->> 'scope', ''), 'unknown') AS scope, COUNT(*) AS count FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND event_name = 'skills_cli scope selected' GROUP BY COALESCE(NULLIF(properties::jsonb ->> 'scope', ''), 'unknown') ORDER BY count DESC",
+    },
+    {
+      legacySql:
+        "SELECT trim(c) AS client, COUNT(*) AS count FROM analytics_events, LATERAL unnest(string_to_array(properties::jsonb ->> 'clients', ',')) AS c WHERE event_name = 'skills_cli clients selected' AND (properties::jsonb ->> 'clients') <> '' GROUP BY trim(c) ORDER BY count DESC LIMIT 30",
+      sql: "SELECT trim(c) AS client, COUNT(*) AS count FROM analytics_events, LATERAL unnest(string_to_array(properties::jsonb ->> 'clients', ',')) AS c WHERE event_name = 'skills_cli clients selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') AND (properties::jsonb ->> 'clients') <> '' GROUP BY trim(c) ORDER BY count DESC LIMIT 30",
+    },
+    {
+      legacySql:
+        "WITH steps AS (SELECT 1 AS step_order, 'Started' AS step, COUNT(DISTINCT session_id) AS reached FROM analytics_events WHERE event_name = 'skills_cli started' UNION ALL SELECT 2, 'Skills prompted', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills prompted' UNION ALL SELECT 3, 'Skills selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills selected' UNION ALL SELECT 4, 'Clients selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli clients selected' UNION ALL SELECT 5, 'Scope selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli scope selected' UNION ALL SELECT 6, 'Install completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli install completed' UNION ALL SELECT 7, 'Completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli completed'), start_total AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli started') SELECT steps.step, steps.reached, CASE WHEN start_total.n = 0 THEN 0 ELSE ROUND(steps.reached * 100.0 / start_total.n) END AS pct_of_start FROM steps, start_total ORDER BY steps.step_order",
+      sql: "WITH steps AS (SELECT 1 AS step_order, 'Started' AS step, COUNT(DISTINCT session_id) AS reached FROM analytics_events WHERE event_name = 'skills_cli started' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 2, 'Skills prompted', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills prompted' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 3, 'Skills selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli skills selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 4, 'Clients selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli clients selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 5, 'Scope selected', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli scope selected' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 6, 'Install completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli install completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') UNION ALL SELECT 7, 'Completed', COUNT(DISTINCT session_id) FROM analytics_events WHERE event_name = 'skills_cli completed' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')), start_total AS (SELECT COUNT(DISTINCT session_id) AS n FROM analytics_events WHERE event_name = 'skills_cli started' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')) SELECT steps.step, steps.reached, CASE WHEN start_total.n = 0 THEN 0 ELSE ROUND(steps.reached * 100.0 / start_total.n) END AS pct_of_start FROM steps, start_total ORDER BY steps.step_order",
+    },
+    {
+      legacySql: "SELECT COUNT(*) AS value FROM analytics_events",
+      sql: "SELECT COUNT(*) AS value FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')",
+    },
+    {
+      legacySql:
+        "SELECT COUNT(DISTINCT session_id) AS value FROM analytics_events",
+      sql: "SELECT COUNT(DISTINCT session_id) AS value FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')",
+    },
+    {
+      legacySql:
+        "SELECT event_name AS label, COUNT(*) AS value FROM analytics_events GROUP BY event_name ORDER BY value DESC LIMIT 8",
+      sql: "SELECT event_name AS label, COUNT(*) AS value FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') GROUP BY event_name ORDER BY value DESC LIMIT 8",
+    },
+    {
+      legacySql:
+        "SELECT CASE WHEN signed_in = 'true' THEN 'Signed In' ELSE 'Anonymous' END AS user_type, COUNT(*) AS events FROM analytics_events GROUP BY signed_in",
+      sql: "SELECT CASE WHEN signed_in = 'true' THEN 'Signed In' ELSE 'Anonymous' END AS user_type, COUNT(*) AS events FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') GROUP BY signed_in",
+    },
+    {
+      legacySql:
+        "SELECT timestamp, event_name, app, signed_in FROM analytics_events ORDER BY timestamp DESC LIMIT 50",
+      sql: "SELECT timestamp, event_name, app, signed_in FROM analytics_events WHERE event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD') ORDER BY timestamp DESC LIMIT 50",
+    },
+    {
+      legacySql:
+        "WITH base AS (SELECT NULLIF(user_key, '') AS user_key, event_date AS event_date, user_id FROM analytics_events WHERE event_name = 'session status' AND signed_in = 'true' AND NULLIF(user_key, '') IS NOT NULL AND lower(COALESCE(NULLIF(template, ''), NULLIF(properties::jsonb ->> 'templateId', ''), NULLIF(properties::jsonb ->> 'agent_native_template', ''), NULLIF(properties::jsonb ->> 'agentNativeTemplate', ''), NULLIF(app, ''), NULLIF(properties::jsonb ->> 'agent_native_app', ''), NULLIF(properties::jsonb ->> 'agentNativeApp', ''), 'unknown')) <> 'docs' AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))), first_seen AS (SELECT user_key, MIN(event_date) AS cohort_date FROM base GROUP BY user_key), anchor_dates AS (SELECT DISTINCT cohort_date AS date FROM first_seen WHERE cohort_date <= to_char(CURRENT_DATE - INTERVAL '14 days', 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')))), cohort_windows AS (SELECT a.date, f.user_key, f.cohort_date FROM anchor_dates a JOIN first_seen f ON f.cohort_date >= to_char(a.date::date - INTERVAL '6 days', 'YYYY-MM-DD') AND f.cohort_date <= a.date), cohort_sizes AS (SELECT date, COUNT(DISTINCT user_key) AS users FROM cohort_windows GROUP BY date), periods AS (SELECT '1-7d return' AS period UNION ALL SELECT '7-14d return' AS period), retained AS (SELECT cw.date, '1-7d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date > cw.cohort_date AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY cw.date UNION ALL SELECT cw.date, '7-14d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date >= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY cw.date) SELECT cs.date, p.period, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs CROSS JOIN periods p LEFT JOIN retained r ON r.date = cs.date AND r.period = p.period WHERE cs.users >= 5 ORDER BY cs.date, p.period",
+      sql: "WITH base AS (SELECT NULLIF(user_key, '') AS user_key, event_date AS event_date, user_id FROM analytics_events WHERE event_name = 'session status' AND signed_in = 'true' AND NULLIF(user_key, '') IS NOT NULL AND lower(COALESCE(NULLIF(template, ''), NULLIF(properties::jsonb ->> 'templateId', ''), NULLIF(properties::jsonb ->> 'agent_native_template', ''), NULLIF(properties::jsonb ->> 'agentNativeTemplate', ''), NULLIF(app, ''), NULLIF(properties::jsonb ->> 'agent_native_app', ''), NULLIF(properties::jsonb ->> 'agentNativeApp', ''), 'unknown')) <> 'docs' AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io')) AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD')), first_seen AS (SELECT user_key, MIN(event_date) AS cohort_date FROM base GROUP BY user_key), anchor_dates AS (SELECT DISTINCT cohort_date AS date FROM first_seen WHERE cohort_date <= to_char(CURRENT_DATE - INTERVAL '14 days', 'YYYY-MM-DD') AND (cohort_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND cohort_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))))), cohort_windows AS (SELECT a.date, f.user_key, f.cohort_date FROM anchor_dates a JOIN first_seen f ON f.cohort_date >= to_char(a.date::date - INTERVAL '6 days', 'YYYY-MM-DD') AND f.cohort_date <= a.date), cohort_sizes AS (SELECT date, COUNT(DISTINCT user_key) AS users FROM cohort_windows GROUP BY date), periods AS (SELECT '1-7d return' AS period UNION ALL SELECT '7-14d return' AS period), retained AS (SELECT cw.date, '1-7d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date > cw.cohort_date AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') GROUP BY cw.date UNION ALL SELECT cw.date, '7-14d return' AS period, COUNT(DISTINCT cw.user_key) AS retained FROM cohort_windows cw JOIN base b ON b.user_key = cw.user_key AND b.event_date >= to_char(cw.cohort_date::date + INTERVAL '7 days', 'YYYY-MM-DD') AND b.event_date <= to_char(cw.cohort_date::date + INTERVAL '14 days', 'YYYY-MM-DD') GROUP BY cw.date) SELECT cs.date, p.period, COALESCE(r.retained, 0) AS retained_users, cs.users AS cohort_users, COALESCE(r.retained::float / NULLIF(cs.users, 0), 0) AS rate FROM cohort_sizes cs CROSS JOIN periods p LEFT JOIN retained r ON r.date = cs.date AND r.period = p.period WHERE cs.users >= 5 ORDER BY cs.date, p.period",
+    },
+    {
+      legacySql:
+        "WITH offsets AS (SELECT (ROW_NUMBER() OVER (ORDER BY event_date) - 1)::int AS n FROM analytics_events LIMIT 800), signup_events AS (SELECT event_date AS date, COALESCE(NULLIF(template, ''), NULLIF(properties::jsonb ->> 'templateId', ''), NULLIF(properties::jsonb ->> 'agent_native_template', ''), NULLIF(properties::jsonb ->> 'agentNativeTemplate', ''), NULLIF(app, ''), NULLIF(properties::jsonb ->> 'agent_native_app', ''), NULLIF(properties::jsonb ->> 'agentNativeApp', ''), 'unknown') AS template FROM analytics_events WHERE event_name = 'signup' AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))), bounds AS (SELECT MIN(date::date) AS start_date, MAX(date::date) AS end_date FROM signup_events), dates AS (SELECT to_char(bounds.start_date + offsets.n, 'YYYY-MM-DD') AS date FROM bounds CROSS JOIN offsets WHERE bounds.start_date IS NOT NULL AND bounds.start_date + offsets.n <= bounds.end_date), templates AS (SELECT DISTINCT template FROM signup_events), daily AS (SELECT date, template, COUNT(*) AS count FROM signup_events GROUP BY date, template) SELECT dates.date, templates.template, COALESCE(daily.count, 0) AS count FROM dates CROSS JOIN templates LEFT JOIN daily ON daily.date = dates.date AND daily.template = templates.template ORDER BY dates.date, templates.template",
+      sql: "WITH signup_events AS (SELECT event_date AS date, COALESCE(NULLIF(template, ''), NULLIF(properties::jsonb ->> 'templateId', ''), NULLIF(properties::jsonb ->> 'agent_native_template', ''), NULLIF(properties::jsonb ->> 'agentNativeTemplate', ''), NULLIF(app, ''), NULLIF(properties::jsonb ->> 'agent_native_app', ''), NULLIF(properties::jsonb ->> 'agentNativeApp', ''), 'unknown') AS template FROM analytics_events WHERE event_name = 'signup' AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '30d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '30 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '180d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '180 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '365d' AND event_date >= to_char(CURRENT_DATE - INTERVAL '365 days', 'YYYY-MM-DD'))) AND ('{{emailFilter}}' IN ('', 'all') OR ('{{emailFilter}}' = 'exclude_builder' AND lower(coalesce(user_id, '')) NOT LIKE '%@builder.io') OR ('{{emailFilter}}' = 'only_builder' AND lower(coalesce(user_id, '')) LIKE '%@builder.io'))), bounds AS (SELECT MIN(date::date) AS start_date, MAX(date::date) AS end_date FROM signup_events), dates AS (SELECT to_char(d, 'YYYY-MM-DD') AS date FROM bounds, generate_series(bounds.start_date, bounds.end_date, INTERVAL '1 day') AS d WHERE bounds.start_date IS NOT NULL), templates AS (SELECT DISTINCT template FROM signup_events), daily AS (SELECT date, template, COUNT(*) AS count FROM signup_events GROUP BY date, template) SELECT dates.date, templates.template, COALESCE(daily.count, 0) AS count FROM dates CROSS JOIN templates LEFT JOIN daily ON daily.date = dates.date AND daily.template = templates.template ORDER BY dates.date, templates.template",
+    },
+  ];
+
+export function repairUnboundedFirstPartyPanels(
+  config: Record<string, unknown>,
+  dialect: Dialect = "postgres",
+): { config: Record<string, unknown>; changed: boolean } {
+  if (!Array.isArray(config.panels)) return { config, changed: false };
+
+  const fixBySql = new Map(
+    UNBOUNDED_FIRST_PARTY_PANEL_FIXES.map((fix) => [fix.legacySql, fix.sql]),
+  );
+  let changed = false;
+  const panels = config.panels.map((rawPanel) => {
+    if (!rawPanel || typeof rawPanel !== "object") return rawPanel;
+    const panel = rawPanel as DashboardPanelLike & Record<string, unknown>;
+    if (panel.source !== "first-party" || typeof panel.sql !== "string") {
+      return rawPanel;
+    }
+    const fixedSql = fixBySql.get(panel.sql);
+    if (fixedSql === undefined) return rawPanel;
+    changed = true;
+    return { ...panel, sql: dialectBoundedSql(fixedSql, dialect) };
+  });
+  if (!changed) return { config, changed: false };
+  return { config: { ...config, panels }, changed: true };
+}

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

@@ -8,7 +8,10 @@ import {
 // startup so the dashboard / analysis share actions know where to dispatch.
 import "../db/index.js";
 import * as schema from "../db/schema.js";
-import { repairPersistedFirstPartyDashboardQueries } from "../lib/first-party-dashboard-repair.js";
+import {
+  repairPersistedFirstPartyDashboardQueries,
+  repairUnboundedFirstPartyPanelsAcrossDashboards,
+} from "../lib/first-party-dashboard-repair.js";
 
 /**
  * Every Drizzle table exported from schema.ts. Filters out type-only and
@@ -1284,6 +1287,29 @@ const runAnalyticsMigrations = runMigrations(
         ALTER TABLE dashboard_report_subscriptions ADD COLUMN IF NOT EXISTS last_capture_error TEXT;
       `,
     },
+    // First-party dashboard panel result cache. Same shape/pattern as
+    // bigquery_cache above, short TTL (set in first-party-analytics-cache.ts)
+    // since this is the app's own live data, not an immutable warehouse
+    // result. See first-party-analytics-cache.ts for why this exists: panel
+    // queries had no cache at all, so every dashboard render and every daily
+    // report screenshot recomputed from scratch and stacked concurrent load
+    // on the same rows, which is what was blowing report/panel timeouts.
+    {
+      version: 124,
+      name: "first-party-analytics-cache-table",
+      sql: `CREATE TABLE IF NOT EXISTS first_party_analytics_cache (
+      key TEXT PRIMARY KEY,
+      sql TEXT NOT NULL,
+      result TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      expires_at TEXT NOT NULL
+    )`,
+    },
+    {
+      version: 125,
+      name: "first-party-analytics-cache-expires-idx",
+      sql: `CREATE INDEX IF NOT EXISTS first_party_analytics_cache_expires_at_idx ON first_party_analytics_cache (expires_at)`,
+    },
   ],
   { table: "analytics_migrations" },
 );
@@ -1312,6 +1338,20 @@ export default async (nitroApp: any): Promise<void> => {
       err instanceof Error ? err.message : err,
     );
   }
+  try {
+    const repairedCount =
+      await repairUnboundedFirstPartyPanelsAcrossDashboards();
+    if (repairedCount > 0) {
+      console.info(
+        `[db] Repaired ${repairedCount} dashboard(s) with unbounded first-party panel SQL.`,
+      );
+    }
+  } catch (err) {
+    console.warn(
+      "[db] Failed to repair unbounded first-party panels across dashboards (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  }
   try {
     const summary = await ensureAdditiveColumns({
       db: getDbExec(),

package/corpus/templates/analytics/shared/dashboard-report-timeouts.ts

@@ -1,3 +1,6 @@
-export const FIRST_PARTY_ANALYTICS_QUERY_TIMEOUT_MS = 30_000;
-export const DASHBOARD_REPORT_ACTION_TIMEOUT_MS = 38_000;
-export const DASHBOARD_REPORT_READY_TIMEOUT_MS = 60_000;
+// These three must stay ordered with headroom (DB timeout < action timeout <
+// page-ready timeout) so the innermost layer's own, more specific error
+// surfaces before an outer layer gives up for an unrelated reason.
+export const FIRST_PARTY_ANALYTICS_QUERY_TIMEOUT_MS = 45_000;
+export const DASHBOARD_REPORT_ACTION_TIMEOUT_MS = 50_000;
+export const DASHBOARD_REPORT_READY_TIMEOUT_MS = 75_000;

package/corpus/templates/design/actions/edit-design.ts

@@ -18,6 +18,7 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import {
   readLiveSourceFile,
+  SourceWorkspaceEditConflictError,
   writeInlineSourceFile,
   type SourceWorkspaceFile,
 } from "../server/source-workspace.js";
@@ -303,36 +304,28 @@ export default defineAction({
       );
     }
 
-    // Read the LIVE base (collab text when present, else the SQL row) right
-    // before transforming, and carry its versionHash through to the write
-    // below. writeInlineSourceFile re-reads the live text immediately before
-    // its own applyText/DB write and rejects if it no longer matches this
-    // hash — closing the race window where a concurrent editor/agent write
-    // lands between this read and the persist (the same stale-diff-base bug
-    // fixed for insert-design-native-asset.ts and insert-asset.ts: a diff
-    // computed from a stale base, char-diffed into a collab doc that has
-    // since moved on, corrupts or drops the other writer's change).
-    const workspaceFile: SourceWorkspaceFile = {
-      id: file.id,
-      designId: file.designId,
-      filename: file.filename ?? "",
-      fileType: file.fileType ?? "html",
-      content: file.content,
-      createdAt: null,
-      updatedAt: null,
-    };
-    const live = await readLiveSourceFile(workspaceFile);
-    const base = live.content;
-
     const resolvedMode =
       mode ??
       (replacementContent !== undefined ? "replace-file" : "search-replace");
-    const { content: nextContent, applied } =
-      resolvedMode === "replace-file"
-        ? { content: replacementContent ?? "", applied: 0 }
-        : applySearchReplaceEdits(base, edits ?? []);
-    const changed = nextContent !== base;
 
+    // A concurrent human/agent write can land between reading the live file
+    // and persisting this edit (writeInlineSourceFile throws
+    // SourceWorkspaceEditConflictError when that happens — see its own
+    // comment for the CAS/collab details). search-replace edits are anchored
+    // to specific text rather than a stale full snapshot, so on conflict we
+    // can just re-read the fresh content and reapply the SAME edits against
+    // it instead of forcing the agent to make a separate get-design-snapshot
+    // round trip and guess again. replace-file sends a full document computed
+    // from a point-in-time snapshot — retrying that blind could silently
+    // clobber whatever the concurrent writer did, so it still fails closed on
+    // the first conflict.
+    const MAX_EDIT_CONFLICT_RETRIES = 2;
+
+    let live: Awaited<ReturnType<typeof readLiveSourceFile>>;
+    let base = "";
+    let nextContent = "";
+    let applied = 0;
+    let changed = false;
     let creativeContext:
       | {
           contextMode: "off" | "auto" | "pinned";
@@ -352,7 +345,43 @@ export default defineAction({
         }
       | undefined;
 
-    if (changed) {
+    for (let attempt = 0; ; attempt += 1) {
+      // Refetch the SQL content on retries — readLiveSourceFile only falls
+      // back to this when no collab doc exists yet, so a conflict caused by
+      // a plain SQL writer (no live collab session) needs a fresh row here
+      // or every retry would recompute the exact same stale versionHash.
+      const currentContent =
+        attempt === 0
+          ? file.content
+          : (
+              await db
+                .select({ content: schema.designFiles.content })
+                .from(schema.designFiles)
+                .where(eq(schema.designFiles.id, file.id))
+                .limit(1)
+            )[0]?.content;
+
+      const workspaceFile: SourceWorkspaceFile = {
+        id: file.id,
+        designId: file.designId,
+        filename: file.filename ?? "",
+        fileType: file.fileType ?? "html",
+        content: currentContent,
+        createdAt: null,
+        updatedAt: null,
+      };
+      live = await readLiveSourceFile(workspaceFile);
+      base = live.content;
+
+      ({ content: nextContent, applied } =
+        resolvedMode === "replace-file"
+          ? { content: replacementContent ?? "", applied: 0 }
+          : applySearchReplaceEdits(base, edits ?? []));
+      changed = nextContent !== base;
+      creativeContext = undefined;
+
+      if (!changed) break;
+
       const previous =
         contextModeOverride === "off"
           ? null
@@ -439,6 +468,15 @@ export default defineAction({
           content: nextContent,
           expectedVersionHash: live.versionHash,
         });
+      } catch (error) {
+        if (
+          error instanceof SourceWorkspaceEditConflictError &&
+          resolvedMode === "search-replace" &&
+          attempt < MAX_EDIT_CONFLICT_RETRIES
+        ) {
+          continue;
+        }
+        throw error;
       } finally {
         agentLeaveDocument(file.id);
       }
@@ -448,6 +486,7 @@ export default defineAction({
         artifactId: designId,
         ...creativeContext,
       });
+      break;
     }
 
     return {

package/corpus/templates/design/changelog/2026-07-25-design-edits-retry-concurrent-changes.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-25
+---
+
+Design edits now retry safely when another collaborator changes the file.

package/corpus/templates/design/server/source-workspace.ts

@@ -331,7 +331,11 @@ export async function writeInlineSourceFile(args: {
       args.expectedVersionHash &&
       args.expectedVersionHash !== current.versionHash
     ) {
-      throw new Error(
+      // Typed so callers can catch-and-retry the same way they already do for
+      // the other two conflict sites below (see apply-shader-fill.ts /
+      // apply-component-prop-edit.ts / edit-design.ts) instead of only
+      // matching on message text.
+      throw new SourceWorkspaceEditConflictError(
         "Source file changed since it was read. Re-read the file and retry.",
       );
     }

package/corpus/templates/forms/.agents/skills/form-responses/SKILL.md

@@ -48,14 +48,16 @@ status, visibility, and an "Open editor" action.
 
 ## Exporting Responses
 
-Use `export-responses` to export to CSV or JSON:
+Use `export-responses` to export to CSV or JSON. The export is uploaded to
+configured file storage (never written to local disk — serverless hosts have
+a read-only filesystem) and the action returns the resulting file URL:
 
 ```bash
 # CSV export (default)
-pnpm action export-responses --form <form-id> --output data/export.csv
+pnpm action export-responses --form <form-id>
 
 # JSON export
-pnpm action export-responses --form <form-id> --output data/export.json --format json
+pnpm action export-responses --form <form-id> --format json
 ```
 
 The CSV includes headers derived from field labels. Array values (multiselect) are joined with semicolons.
@@ -113,7 +115,7 @@ To analyze responses, the workflow is:
 | ---------------------- | ---------------------------------------------------------------------------- |
 | "@Form setup?"         | `preview-form --formId <id>` and answer from the returned fields/settings    |
 | "How many responses?"  | `response-insights --formId <id>` and report `summary.responses`             |
-| "Export to CSV"        | `export-responses --form <id> --output data/export.csv`                      |
+| "Export to CSV"        | `export-responses --form <id>`                                               |
 | "Submissions by day"   | `response-insights --formId <id> --days 30`                                  |
 | "Summarize feedback"   | `response-insights`, then `list-responses` if more detail is needed          |
 | "Average rating"       | `list-responses`, compute from rating fields and state the sampled row count |

package/corpus/templates/forms/actions/create-form.ts

@@ -9,7 +9,10 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import { assertIntegrationUrlsAllowed } from "../server/lib/integrations.js";
-import { assertValidFields } from "../server/lib/validate-fields.js";
+import {
+  assertValidFields,
+  normalizeFieldIds,
+} from "../server/lib/validate-fields.js";
 import type { FormField, FormSettings } from "../shared/types.js";
 import { assertPublishableForm } from "./lib/assert-publishable-form.js";
 
@@ -88,6 +91,7 @@ export default defineAction({
         fields = args.fields as unknown as FormField[];
       }
     }
+    fields = normalizeFieldIds(fields) as FormField[];
     assertValidFields(fields);
 
     const defaultSettings: FormSettings = {

package/corpus/templates/forms/actions/export-responses.ts

@@ -1,6 +1,6 @@
-import fs from "fs";
-
 import { defineAction } from "@agent-native/core";
+import { uploadFile } from "@agent-native/core/file-upload";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { assertAccess } from "@agent-native/core/sharing";
 import { eq, desc } from "drizzle-orm";
 import { z } from "zod";
@@ -12,7 +12,6 @@ export default defineAction({
   description: "Export form responses to CSV or JSON file.",
   schema: z.object({
     form: z.string().describe("Form ID (required)"),
-    output: z.string().optional().describe("Output file path"),
     format: z.enum(["csv", "json"]).optional().describe("Export format"),
   }),
   http: false,
@@ -28,10 +27,10 @@ export default defineAction({
       .orderBy(desc(schema.responses.submittedAt));
 
     const fields = JSON.parse(form.fields);
-    const fmt =
-      args.format || (args.output?.endsWith(".json") ? "json" : "csv");
-    const outputPath =
-      args.output || `data/export-${formId}.${fmt === "json" ? "json" : "csv"}`;
+    const fmt = args.format || "csv";
+    const filename = `export-${formId}.${fmt === "json" ? "json" : "csv"}`;
+    const ownerEmail = getRequestUserEmail() ?? undefined;
+    let fileBody: string;
 
     if (fmt === "json") {
       const data = responses.map((r) => ({
@@ -42,7 +41,7 @@ export default defineAction({
         clientSurface: r.clientSurface ?? null,
         ...JSON.parse(r.data),
       }));
-      fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
+      fileBody = JSON.stringify(data, null, 2);
     } else {
       const headers = [
         "ID",
@@ -74,17 +73,29 @@ export default defineAction({
       // with a single quote so spreadsheets treat it as literal text.
       const neutralize = (cell: string) =>
         /^[=+\-@\t\r]/.test(cell) ? `'${cell}` : cell;
-      const csv = [headers, ...rows]
+      fileBody = [headers, ...rows]
         .map((row) =>
           row
             .map((cell: string) => `"${neutralize(cell).replace(/"/g, '""')}"`)
             .join(","),
         )
         .join("\n");
+    }
+
+    const uploaded = await uploadFile({
+      data: Buffer.from(fileBody, "utf8"),
+      mimeType: fmt === "json" ? "application/json" : "text/csv",
+      filename,
+      ownerEmail,
+    }).catch(() => null);
 
-      fs.writeFileSync(outputPath, csv);
+    if (!uploaded) {
+      throw new Error(
+        "Export was generated but not saved because file storage is not configured. " +
+          "Connect or reconnect Builder.io in Settings → File uploads, or register a custom provider.",
+      );
     }
 
-    return `Exported ${responses.length} responses to ${outputPath}`;
+    return `Exported ${responses.length} responses to ${uploaded.url}`;
   },
 });

package/corpus/templates/forms/actions/update-form.ts

@@ -6,7 +6,10 @@ import { z } from "zod";
 import { getDb, schema } from "../server/db/index.js";
 import { assertIntegrationUrlsAllowed } from "../server/lib/integrations.js";
 import { invalidatePublicFormCache } from "../server/lib/public-form-ssr.js";
-import { assertValidFields } from "../server/lib/validate-fields.js";
+import {
+  assertValidFields,
+  normalizeFieldIds,
+} from "../server/lib/validate-fields.js";
 import type { FormField, FormSettings } from "../shared/types.js";
 import { assertPublishableForm } from "./lib/assert-publishable-form.js";
 
@@ -81,6 +84,7 @@ export default defineAction({
       } else {
         parsedFields = args.fields;
       }
+      parsedFields = normalizeFieldIds(parsedFields);
       assertValidFields(parsedFields);
       updates.fields = JSON.stringify(parsedFields);
     }

package/corpus/templates/forms/changelog/2026-07-25-fields-can-be-created-without-ids.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-25
+---
+
+Forms can create and update fields without manually supplied IDs.

package/corpus/templates/forms/changelog/2026-07-25-response-exports-use-file-storage.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-25
+---
+
+Response exports now save to file storage and return a downloadable URL.

package/corpus/templates/forms/server/lib/validate-fields.ts

@@ -6,6 +6,49 @@
 export const FIELD_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
 const CONDITIONAL_OPERATORS = new Set(["equals", "not_equals", "contains"]);
 
+/**
+ * Generates a safe id for a whole-array field replacement (create-form,
+ * update-form) when the model omits one — the #1 create-form failure in
+ * the 2026-07-25 reliability sweep ("field #1 has an invalid id undefined").
+ * Never used by patch-form-fields: there a missing id on an upsert op is
+ * ambiguous (new field vs. a forgotten reference to an existing one), so it
+ * must keep failing loud rather than risk silently creating a duplicate.
+ * Ids are slugified from `label` through the same FIELD_ID_PATTERN charset
+ * `assertValidFields` enforces, so a generated id can never fail that check.
+ */
+export function normalizeFieldIds(fields: unknown): unknown {
+  if (!Array.isArray(fields)) return fields;
+  const usedIds = new Set(
+    fields
+      .map((f) =>
+        f && typeof f === "object" ? (f as Record<string, unknown>).id : null,
+      )
+      .filter(
+        (id): id is string =>
+          typeof id === "string" && FIELD_ID_PATTERN.test(id),
+      ),
+  );
+  return fields.map((field) => {
+    if (field == null || typeof field !== "object") return field;
+    const f = field as Record<string, unknown>;
+    if (typeof f.id === "string" && FIELD_ID_PATTERN.test(f.id)) return field;
+    const label = typeof f.label === "string" ? f.label : "";
+    const base =
+      label
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .slice(0, 40) || "field";
+    let candidate = base;
+    let suffix = 1;
+    while (usedIds.has(candidate)) {
+      candidate = `${base}_${++suffix}`;
+    }
+    usedIds.add(candidate);
+    return { ...f, id: candidate };
+  });
+}
+
 export function assertValidFields(fields: unknown): void {
   if (!Array.isArray(fields)) {
     throw new Error("fields must be an array");