fix: refresh stale introspection so editor type stays correct

Architecture/cell-editing.md

@@ -72,6 +72,8 @@ Selection rules MUST remain centralized here:
 
 Do not duplicate datatype branching in callers.
 
+Every dispatched input MUST be wrapped by `ColumnTypeLabel` so the DB column type Studio believes the column has is surfaced inside the editor popover (see `Architecture/introspection.md` → "Cell Editor Type Label"). This makes schema drift visible instead of producing a silently wrong widget.
+
 ## Readonly And Writeability Rules
 
 A cell is editable only when both are true:

Architecture/introspection.md

@@ -31,10 +31,35 @@ The query MUST use:
 - `retry: false`
 - `retryOnMount: false`
 - `refetchOnReconnect: false`
-- `refetchOnWindowFocus: false`
-- `staleTime: Infinity`
+- `refetchOnWindowFocus: "always"`
+- `staleTime: 30_000` (30s)
 
-Automatic retry loops are forbidden for introspection because they can spam operation events, repeat expensive metadata work, and hide the real startup failure state from the user.
+Automatic retry loops are forbidden for introspection because they can spam operation events, repeat expensive metadata work, and hide the real startup failure state from the user. `refetchOnWindowFocus` is not a retry loop: `refetchOnWindowFocus: "always"` refires on every window focus even while data is still fresh — React Query v5 would normally treat plain `true` as "refetch only stale queries" and skip the focus refetch while data is fresh, hence the explicit `"always"` string. Combined with the 30s `staleTime` (which throttles background refetches otherwise), a focus event in practice re-introspects at most once each time the user returns to Studio, which is the intent of the refreshable schema contract below.
+
+## Refreshable Schema Contract
+
+Introspection is cached but MUST be refreshable so the cell editor re-renders with the correct column type when the live DB schema drifts (e.g. a column changed from boolean to varchar after Studio loaded).
+
+All refresh paths go through one shared mechanism in `ui/hooks/refresh-introspection.ts`:
+
+- `INTROSPECTION_QUERY_KEY` is the single React Query key for introspection.
+- `refreshIntrospection(queryClient)` invalidates the introspection cache and refetches any active observer.
+
+Three call sites share it:
+
+- `useIntrospection().refreshSchema` — backs the toolbar "Refresh schema" button.
+- the write-error self-heal path (see Self-Heal Contract below).
+- window-focus refetch (React Query built-in, enabled by `refetchOnWindowFocus: "always"` + `staleTime: 30_000`).
+
+The "Refresh schema" button MUST be a ShadCN `Button` with a ShadCN `Tooltip`, an `aria-label`, and a loading/disabled state while refetching.
+
+## Self-Heal Contract
+
+When a row write (insert/update) fails with a PostgreSQL type-mismatch error, Studio MUST additionally invalidate cached introspection and trigger a refetch so the editor can re-render with the correct column type.
+
+- Detection: `data/postgres-core/postgres-error.ts` matches SQLSTATE `42804` (`datatype_mismatch`) and `22P02` (`invalid_text_representation`) by reading the string `code` property carried on the `AdapterError` (the Postgres driver attaches the server `SqlState` there, and `createAdapterError` preserves it on the same object).
+- Wiring: `ui/hooks/refresh-introspection.ts` exports `selfHealOnWriteError({ error, queryClient })`, called from the row mutation error paths in `ui/hooks/use-active-table-rows-collection.ts` (`onUpdate`) and `ui/hooks/use-active-table-insert.ts`.
+- Non-swallowing: the original error MUST still be surfaced to the user (the `studio_operation_error` event and resulting toast still fire). The self-heal only additionally triggers a background introspection refetch.
 
 ## Data Fallback Contract
 
@@ -93,3 +118,10 @@ Changes to this subsystem MUST include tests for:
 - startup recovery UI rendering
 - adapter partial-success fallback when timezone lookup fails
 - single-emission behavior for `studio_launched`
+- introspection refetching when the window regains focus (proves `staleTime` is the 30s throttle and `refetchOnWindowFocus: "always"` refetches even while fresh data is still cached)
+- `refreshSchema` invalidating and triggering an introspection refetch
+- self-heal on a Postgres type-mismatch write error (SQLSTATE `42804` / `22P02`) without swallowing the user-facing error
+
+## Cell Editor Type Label
+
+The cell editor MUST surface the DB column type Studio believes a column has (via `ui/studio/input/ColumnTypeLabel.tsx`, composed around the input by `ui/studio/input/get-input.tsx`). This makes schema drift visible to the user instead of producing a silently wrong widget. The readable type string comes from `ui/lib/datatype-display.ts` (`formatDatatypeName`), which maps internal catalog names to common SQL aliases. The label uses standard ShadCN `Tooltip` composition; no non-standard UI is introduced.

FEATURES.md

@@ -16,6 +16,7 @@ A standalone `sslmode` without SSL file parameters is left in the connection str
 Studio introspects connected databases to build schemas, tables, columns, relationships, filter operators, and timezone metadata.
 This gives users an accurate live model of the database and keeps table navigation grounded in current structure.
 A fresh Studio mount performs this discovery once, while actual adapter or database-availability changes invalidate cached metadata and load it again.
+Introspection is refreshable, not frozen: cached schema is allowed to go stale and is re-introspected when the user returns to Studio (window focus), when the user clicks "Refresh schema", or when a row write fails with a PostgreSQL type-mismatch error.
 The MySQL adapter detects MariaDB servers via `select version()` and switches to a MariaDB-compatible tables query that returns one row per column and groups the result on the client, so introspection works on all supported MariaDB versions where `json_arrayagg` or JSON casts are unavailable and cannot be truncated by `group_concat_max_len`.
 
 ## Deployable Prisma Postgres Demo
@@ -47,6 +48,21 @@ destroys the preview service when the branch is deleted.
 Startup introspection failures show retryable diagnostics in both the sidebar and the main table panel instead of pretending the database has no tables.
 Studio keeps the last successful schema snapshot visible when a refresh fails, disables automatic retry loops for introspection, and falls back to `UTC` when PostgreSQL or MySQL timezone metadata is unavailable but table metadata succeeded.
 
+## Refreshable Schema
+
+Studio re-introspects the database schema when the user returns to the window, and a dedicated "Refresh schema" toolbar button (next to "Refresh table") triggers an explicit refresh with a loading state and tooltip.
+All refresh paths share one React Query key and a single `refreshIntrospection` helper, so the toolbar button, the write-error self-heal path, and window-focus refetch all invalidate the same cached introspection and refetch the active observer.
+
+## Self-Healing Editor on Type-Mismatch Write Errors
+
+When an insert or update fails with a PostgreSQL type-mismatch error (SQLSTATE `42804` datatype_mismatch or `22P02` invalid_text_representation), Studio invalidates cached introspection and refetches so the cell editor re-renders with the correct column type.
+The original error is still surfaced to the user via the normal operation-error toast and Console; the self-heal only additionally triggers a background schema refresh.
+
+## Cell Editor DB Type Label
+
+The cell editor popover shows the DB column type Studio believes the column has (for example "type: varchar"), with a tooltip explaining what to do if it no longer matches the live schema.
+This makes schema drift visible to the user instead of producing a silently wrong widget, and it stays accurate once the refresh/self-heal paths reload introspection.
+
 ## URL-Driven Navigation and Deep Linking
 
 View, schema, table, filter, sort, pagination, and row-search state are encoded in URL hash parameters.

data/postgres-core/index.ts

@@ -2,5 +2,6 @@ export * from "./adapter";
 export * from "./dml";
 export * from "./full-table-search";
 export * from "./introspection";
+export * from "./postgres-error";
 export * from "./sql-lint";
 export * from "./utility";

data/postgres-core/postgres-error.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import { AdapterError } from "../adapter";
+import {
+  getPostgresErrorCode,
+  isPostgresTypeMismatchError,
+  POSTGRES_DATATYPE_MISMATCH_CODE,
+  POSTGRES_INVALID_TEXT_REPRESENTATION_CODE,
+} from "./postgres-error";
+
+function createAdapterErrorWithCode(code: string): AdapterError {
+  const error = new AdapterError(`db error: ${code}`) as AdapterError & {
+    code?: string;
+  };
+  error.code = code;
+  error.adapterSource = "postgresql";
+  return error;
+}
+
+describe("getPostgresErrorCode", () => {
+  it("returns the string code attached to a driver/adapter error", () => {
+    expect(getPostgresErrorCode(createAdapterErrorWithCode("42804"))).toBe(
+      "42804",
+    );
+  });
+
+  it("returns undefined when the error has no code", () => {
+    expect(getPostgresErrorCode(new Error("no code"))).toBeUndefined();
+  });
+
+  it("returns undefined for non-string code values", () => {
+    expect(
+      getPostgresErrorCode({ code: 42, message: "numeric code" }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined for null/undefined input", () => {
+    expect(getPostgresErrorCode(null)).toBeUndefined();
+    expect(getPostgresErrorCode(undefined)).toBeUndefined();
+  });
+});
+
+describe("isPostgresTypeMismatchError", () => {
+  it("detects SQLSTATE 42804 (datatype_mismatch)", () => {
+    expect(
+      isPostgresTypeMismatchError(
+        createAdapterErrorWithCode(POSTGRES_DATATYPE_MISMATCH_CODE),
+      ),
+    ).toBe(true);
+  });
+
+  it("detects SQLSTATE 22P02 (invalid_text_representation)", () => {
+    expect(
+      isPostgresTypeMismatchError(
+        createAdapterErrorWithCode(POSTGRES_INVALID_TEXT_REPRESENTATION_CODE),
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match unrelated Postgres SQLSTATEs", () => {
+    expect(
+      isPostgresTypeMismatchError(createAdapterErrorWithCode("42P01")),
+    ).toBe(false);
+    expect(
+      isPostgresTypeMismatchError(createAdapterErrorWithCode("23505")),
+    ).toBe(false);
+  });
+
+  it("does not match errors without a SQLSTATE code", () => {
+    expect(isPostgresTypeMismatchError(new Error("network failure"))).toBe(
+      false,
+    );
+  });
+});

data/postgres-core/postgres-error.ts

@@ -0,0 +1,65 @@
+import type { AdapterError } from "../adapter";
+
+/**
+ * PostgreSQL SQLSTATE `datatype_mismatch`.
+ *
+ * Raised when an INSERT/UPDATE supplies a value whose type does not match
+ * the column's current type and Postgres cannot coerce it.
+ */
+export const POSTGRES_DATATYPE_MISMATCH_CODE = "42804";
+
+/**
+ * PostgreSQL SQLSTATE `invalid_text_representation`.
+ *
+ * Raised when a text value cannot be parsed into the target type, e.g. the
+ * editor sent `"true"`/`true` for a column whose live type is no longer
+ * boolean and the value cannot be cast.
+ */
+export const POSTGRES_INVALID_TEXT_REPRESENTATION_CODE = "22P02";
+
+const TYPE_MISMATCH_SQLSTATES = new Set<string>([
+  POSTGRES_DATATYPE_MISMATCH_CODE,
+  POSTGRES_INVALID_TEXT_REPRESENTATION_CODE,
+]);
+
+/**
+ * Returns the PostgreSQL SQLSTATE code carried on an error, if any.
+ *
+ * Postgres drivers (e.g. `postgres`) attach the server's `SqlState` as a
+ * string `code` property on the thrown/rejected error. `createAdapterError`
+ * mutates that same error object to add `adapterSource`/`query`, so the code
+ * survives onto the `AdapterError` that reaches mutation handlers. This
+ * mirrors the shape already read by lint diagnostics
+ * (`getPostgresErrorCode` in `./sql-lint`).
+ */
+export function getPostgresErrorCode(error: unknown): string | undefined {
+  if (
+    error == null ||
+    (typeof error !== "object" && typeof error !== "function")
+  ) {
+    return undefined;
+  }
+
+  const { code } = error as { code?: unknown };
+  return typeof code === "string" ? code : undefined;
+}
+
+/**
+ * Whether a write error is a PostgreSQL type-mismatch that warrants
+ * invalidating cached introspection so the cell editor re-renders with the
+ * correct column type.
+ *
+ * Used by the write-error self-heal path in the row mutation hooks. This only
+ * inspects the error; callers MUST still surface the original error to the
+ * user (e.g. via `studio_operation_error`).
+ */
+export function isPostgresTypeMismatchError(error: unknown): boolean {
+  const code = getPostgresErrorCode(error);
+  return code != null && TYPE_MISMATCH_SQLSTATES.has(code);
+}
+
+/**
+ * Type helper for documentation: the error reaching mutation handlers is an
+ * `AdapterError` carrying the driver's SQLSTATE `code`.
+ */
+export type PostgresWriteError = AdapterError & { code?: string };

ui/hooks/refresh-introspection.ts

@@ -0,0 +1,51 @@
+import type { QueryClient } from "@tanstack/react-query";
+
+import { isPostgresTypeMismatchError } from "../../data/postgres-core/postgres-error";
+
+/**
+ * Stable React Query key for the introspection query.
+ *
+ * The manual "refresh schema" action, the write-error self-heal path, and any
+ * future invalidation all go through this key so there is a single place that
+ * owns the cache identity of the DB schema.
+ */
+export const INTROSPECTION_QUERY_KEY: ["introspection"] = ["introspection"];
+
+/**
+ * Invalidate cached introspection and trigger a refetch of any active
+ * introspection query.
+ *
+ * This is the single shared mechanism used by:
+ * - the manual "refresh schema" button (via `useIntrospection().refreshSchema`)
+ * - the write-error self-heal path (via {@link selfHealOnWriteError})
+ *
+ * `invalidateQueries` marks the query stale and refetches active observers,
+ * so the editor re-renders with the freshly introspected column types.
+ */
+export async function refreshIntrospection(
+  queryClient: QueryClient,
+): Promise<void> {
+  await queryClient.invalidateQueries({
+    queryKey: INTROSPECTION_QUERY_KEY,
+    refetchType: "active",
+  });
+}
+
+/**
+ * Inspect a row-write (insert/update) error and, when it indicates the column
+ * type Studio cached no longer matches the live database schema, invalidate
+ * cached introspection so the cell editor re-renders with the correct type.
+ *
+ * The original error is NOT swallowed: callers still surface it to the user
+ * (e.g. via `studio_operation_error`). This helper only additionally triggers
+ * a background introspection refetch on Postgres SQLSTATE `42804`
+ * (`datatype_mismatch`) or `22P02` (`invalid_text_representation`).
+ */
+export function selfHealOnWriteError(args: {
+  error: unknown;
+  queryClient: QueryClient;
+}): void {
+  if (isPostgresTypeMismatchError(args.error)) {
+    void refreshIntrospection(args.queryClient);
+  }
+}