Merge pull request #9 from xiaolai/post-deploy-fixes

Post-deploy fixes: pin search_vec, add /office/policy to sidebar, doc push hazard

Author: xiaolai

.claude/rules/db-migrations.md

@@ -0,0 +1,68 @@
+# Database migrations — never use `drizzle-kit push` against prod
+
+The Neon-backed `web/` app has hand-authored SQL migrations in
+`web/src/db/migrations/*.sql`, plus DB-level features (FTS-generated
+columns, partial unique indexes, triggers) that **Drizzle's schema
+DSL cannot fully represent**. Running `pnpm drizzle-kit push` against
+a database with those features will **drop** them, because push
+diffs the DB against the schema files and treats anything not in the
+schema as something to remove.
+
+This is not theoretical. On 2026-05-06, `drizzle-kit push` was used to
+apply migrations 0018–0021 against prod (because `drizzle-kit migrate`
+was hanging over the HTTP-only Neon driver). The push **dropped
+`submissions.search_vec`** (the FTS-generated column added by
+migration `0003_fts`) and the matching `idx_submissions_search_vec`
+GIN index, breaking site search until restored manually.
+
+## The rule
+
+For ANY production schema change:
+
+1. **Add a numbered migration file** under
+   `web/src/db/migrations/<NNNN>_<slug>.sql` with the exact DDL.
+2. **Apply it via `psql` or via the Neon dashboard SQL editor**
+   pointed at the prod connection string. Never push against prod.
+3. **Update `_journal.json`** so the migration is recorded.
+4. **Mirror the change** in the relevant `web/src/db/schema/*.ts`
+   file so type inference works. Use `customType` for DB features
+   Drizzle's DSL can't express (FTS columns, generated columns,
+   trigger-maintained columns). The schema declaration is the
+   "leave this alone" signal to push, not the source of truth.
+
+## Why not just `drizzle-kit migrate`?
+
+Migrate uses transactions, which require websockets. The
+`@neondatabase/serverless` HTTP driver doesn't support them, so
+`migrate` hangs indefinitely under the default config. Switching the
+driver for migrations alone is more work than just using `psql`.
+
+If a future contributor needs migrate to work, the path is:
+
+- Set up a websocket-capable Neon connection in a one-off node
+  script that imports `@neondatabase/serverless` with
+  `neonConfig.webSocketConstructor = ws` set.
+- Use the `migrate()` helper from `drizzle-orm/neon-serverless/migrator`.
+
+But for one-off prod migrations, `psql` is faster and more auditable.
+
+## Existing things push will want to drop
+
+These DB-level features are not represented in
+`web/src/db/schema/*.ts` (or are represented as opaque types push
+can match against):
+
+- `submissions.search_vec` — `tsvector GENERATED ALWAYS AS (…) STORED`,
+  declared as opaque `tsvector` in `schema/content.ts` so push
+  matches.
+- `idx_submissions_search_vec` — GIN index over `search_vec`. Push
+  will recreate this with the same name once the column is in
+  schema.
+- The `score_after_vote_change` trigger and any other triggers
+  added by `0001_triggers` and friends — push doesn't manage
+  triggers, but won't drop them either as long as they're attached
+  to existing tables.
+
+If you add a new generated column or trigger-maintained column,
+update this rule and add the matching `customType` declaration in
+the schema.

web/src/app/(reader)/office/policy/page.tsx

@@ -1,11 +1,12 @@
 import Link from "next/link";
-import { ArrowLeft, Cpu, Shield } from "lucide-react";
+import { Cpu, Shield } from "lucide-react";
 import { count, gte, sql } from "drizzle-orm";
 
 import { db } from "@/db/client";
 import { policyDecisions } from "@/db/schema";
 import { POLICY_CATEGORIES } from "@/lib/moderation";
 import { getActiveSystemPrompt } from "@/lib/moderation/prompt-store";
+import { OfficeSidebar } from "@/components/prototype/OfficeSidebar";
 
 export const dynamic = "force-dynamic";
 
@@ -71,16 +72,9 @@ export default async function OfficePolicyPage() {
   const { version: activePromptVersion } = await getActiveSystemPrompt();
 
   return (
-    <div className="proto-page-narrow">
-      <nav className="office-breadcrumb">
-        <Link href="/office">
-          <span className="proto-inline-icon" aria-hidden>
-            <ArrowLeft size={12} />
-          </span>{" "}
-          the office
-        </Link>
-      </nav>
-
+    <div className="proto-page-aside">
+      <OfficeSidebar current="policy" />
+      <div className="proto-page-aside-content">
       <header className="proto-section">
         <div className="office-persona-head">
           <h1>Policy moderation</h1>
@@ -189,6 +183,7 @@ export default async function OfficePolicyPage() {
           </li>
         </ul>
       </section>
+      </div>
     </div>
   );
 }

web/src/components/prototype/OfficeSidebar.tsx

@@ -1,9 +1,14 @@
 import Link from "next/link";
-import { ScrollText, Volume2, BookOpen } from "lucide-react";
+import { ScrollText, Volume2, BookOpen, Shield } from "lucide-react";
 
-export type OfficeSidebarPage = "office" | "transparency" | "voice" | "rubric";
+export type OfficeSidebarPage =
+  | "office"
+  | "transparency"
+  | "voice"
+  | "rubric"
+  | "policy";
 
-/** Shared left-rail navigation for the four /office area pages.
+/** Shared left-rail navigation for the /office area pages.
  *  Pass the current page key so the active link gets aria-current="page"
  *  (which the .proto-page-aside-nav stylesheet picks up for the accent
  *  border + accent-ink color). */
@@ -36,6 +41,11 @@ export function OfficeSidebar({ current }: { current: OfficeSidebarPage }) {
             <BookOpen size={14} aria-hidden /> The rubric
           </Link>
         </li>
+        <li>
+          <Link href="/office/policy" aria-current={ariaCurrent("policy")}>
+            <Shield size={14} aria-hidden /> Policy moderation
+          </Link>
+        </li>
       </ul>
     </nav>
   );

web/src/db/schema/content.ts

@@ -11,6 +11,7 @@
  */
 
 import {
+  customType,
   index,
   integer,
   jsonb,
@@ -28,6 +29,28 @@ import {
 } from "./enums";
 import { users } from "./users";
 
+/**
+ * tsvector custom type for the FTS column on submissions. The
+ * actual column DDL is `tsvector GENERATED ALWAYS AS (…) STORED`
+ * (see migration 0003_fts.sql) — Drizzle has no first-class
+ * support for generated columns, so we declare the column here
+ * with `tsvector` only and rely on the migration's GENERATED
+ * clause for population.
+ *
+ * Without this declaration, `drizzle-kit push` sees a column that
+ * exists in the DB but not in the schema and DROPS it (which
+ * happened on 2026-05-06 when push was used to apply migrations
+ * 0018–0021 — search_vec went with it). Declaring it here keeps
+ * push's diff happy.
+ *
+ * If push ever tries to "fix" this column by dropping the GENERATED
+ * clause, that's a bigger problem — switch to migrate / psql for
+ * production schema changes.
+ */
+const tsvector = customType<{ data: string; driverData: string }>({
+  dataType: () => "tsvector",
+});
+
 export const submissions = pgTable(
   "submissions",
   {
@@ -64,6 +87,11 @@ export const submissions = pgTable(
     // discriminator if/when both coexist. Null for organic user posts.
     submitterKind: submitterKindEnum("submitter_kind").notNull().default("user"),
     sourceId: text("source_id"),
+    // Full-text search column — `tsvector GENERATED ALWAYS AS (…)
+    // STORED` per migration 0003_fts.sql. Declared here as `tsvector`
+    // only so drizzle-kit push doesn't see a phantom column to drop.
+    // The GENERATED clause is owned by the migration, not the schema.
+    searchVec: tsvector("search_vec"),
   },
   (t) => [
     index("idx_submissions_state_created").on(t.state, t.createdAt.desc()),