Day 3: legal grounding — curated seeds, pgvector+FTS retrieval, literal-quote verifier, cited route plans

- Migration 0002: generated tsvector column + GIN index on legal_chunks; ivfflat
cosine index on embedding; pg_trgm + vector extensions.
- packages/contracts/src/legal.ts: RoutePlanDto, GroundedClaimDto,
LegalCitationDto, RoutePlanStepDto, RoutePlanGenerationResult.
- packages/ports: EmbeddingPort; missionId added to ClaimSupportCheck.
- packages/adapters/embedder/openai-compatible.ts: honest embedder via
embedMany (throws on provider 404 — no fake vectors).
- packages/adapters/legal/pgvector-fts.ts: hybrid pgvector ANN + Postgres FTS
fused by RRF (k=60); FTS-only fallback when embedder unavailable;
verifyClaimSupport does whitespace-normalised literal substring match
(CLAUDE.md invariant #4); writes legal_claim_verifications +
legal_retrieval_logs.
- packages/db/seeds: 9 legal_sources, 41 legal_chunks across 3 domains with
real verbatim text (CPA 2019, CP-E-Comm Rules 2020, RBI IOS 2021, RBI 2017
customer-liability circular, NPCI UPI guidelines, IT Act 2000, BNS 2023,
MHA cybercrime 1930/I4C). 3 route_rules with route_graph + required
evidence + deadlines + source_citations.
- apps/worker/functions/route-plan.ts: runRoutePlan Inngest function with
advisory lock, state guard, retrieval + curator-citations backstop (always
loads chunks from matching route_rule.source_citations), LLM via
route-plan.v1 prompt, per-claim verifier gating (drops fabricated claims +
appends legal_claim_rejected events), neutral-admin fallback when zero
claims survive, persists route_plan + mission_event + status_snapshot.
- apps/api/route-plans: POST trigger (Idempotency-Key) + GET latest plan.
- apps/web/missions/[id]: Route Plan panel with per-step citations, verbatim
quote highlight, tier badge, canonical URL link.

Live Day-3 gate PASSED on real data (mission d4d40c2e payment/PhonePe):
* cited route plan: 3 steps, 3 grounded claims, confidence 0.95 — RBI
Integrated Ombudsman 2021 (30-day pre-filing + ₹20-lakh award cap) +
NPCI UPI T+1 dispute TAT, all verbatim quote-span matched.
* fabrication gate (scripts/day3-fabrication-gate.ts): verifier rejects
fabricated quote, supportLevel=unsupported, failureReason explains the
miss after whitespace normalisation.

Tests: 53 green (12 verifier unit + 5 worker gating + 13 contracts + others).
Typecheck/lint clean.

apps/api/src/app.module.ts

@@ -5,6 +5,7 @@ import { InngestModule } from "./workflow/inngest.module.js";
 import { ConversationsModule } from "./conversations/conversations.module.js";
 import { WebhooksModule } from "./webhooks/webhooks.module.js";
 import { EvidenceModule } from "./evidence/evidence.module.js";
+import { RoutePlansModule } from "./route-plans/route-plans.module.js";
 import { CapabilitiesController } from "./capabilities/capabilities.controller.js";
 import { HealthController } from "./health.controller.js";
 
@@ -16,6 +17,7 @@ import { HealthController } from "./health.controller.js";
     MissionsModule,
     WebhooksModule,
     EvidenceModule,
+    RoutePlansModule,
   ],
   controllers: [CapabilitiesController, HealthController],
 })

apps/api/src/route-plans/route-plans.controller.ts

@@ -0,0 +1,54 @@
+/**
+ * RoutePlansController
+ *
+ * Routes:
+ *   POST /api/missions/:missionId/route-plan   — trigger route plan generation (202)
+ *   GET  /api/missions/:missionId/route-plan   — get latest non-superseded route plan
+ *
+ * Idempotency-Key header is accepted on POST and forwarded to the workflow
+ * (CLAUDE.md #7 — idempotent writes).
+ */
+import {
+  Controller,
+  Get,
+  Headers,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Param,
+  Post,
+} from "@nestjs/common";
+import { RoutePlansService } from "./route-plans.service.js";
+
+@Controller("missions/:missionId/route-plan")
+export class RoutePlansController {
+  constructor(
+    @Inject(RoutePlansService) private readonly routePlans: RoutePlansService,
+  ) {}
+
+  /**
+   * POST /api/missions/:missionId/route-plan
+   *
+   * Emits a mission.route_plan_requested event to the Inngest worker.
+   * Returns 202 Accepted immediately — processing is async.
+   */
+  @Post()
+  @HttpCode(HttpStatus.ACCEPTED)
+  async trigger(
+    @Param("missionId") missionId: string,
+    @Headers("idempotency-key") idempotencyKey?: string,
+  ) {
+    return this.routePlans.trigger(missionId, idempotencyKey);
+  }
+
+  /**
+   * GET /api/missions/:missionId/route-plan
+   *
+   * Returns the latest non-superseded RoutePlanDto, Zod-validated.
+   * Returns 404 if no plan exists yet.
+   */
+  @Get()
+  async getLatest(@Param("missionId") missionId: string) {
+    return this.routePlans.getLatest(missionId);
+  }
+}

apps/api/src/route-plans/route-plans.module.ts

@@ -0,0 +1,9 @@
+import { Module } from "@nestjs/common";
+import { RoutePlansController } from "./route-plans.controller.js";
+import { RoutePlansService } from "./route-plans.service.js";
+
+@Module({
+  controllers: [RoutePlansController],
+  providers: [RoutePlansService],
+})
+export class RoutePlansModule {}

apps/api/src/route-plans/route-plans.service.ts

@@ -0,0 +1,113 @@
+/**
+ * RoutePlansService — read/write logic for route_plans.
+ *
+ * CLAUDE.md invariants:
+ * #1 – Hexagonal: no SDK imports; uses DB and WorkflowService ports.
+ * #6 – Contracts-first: validates output via RoutePlanDto Zod schema.
+ * #7 – Idempotent triggers: Inngest dedupes by event id; we pass the
+ *       Idempotency-Key as part of the event data for traceability.
+ */
+import { Inject, Injectable, NotFoundException } from "@nestjs/common";
+import { eq, desc } from "drizzle-orm";
+import type { Database } from "@courtmitra/db";
+import { routePlans, missions, missionEvents } from "@courtmitra/db";
+import { RoutePlanDto } from "@courtmitra/contracts";
+import { WorkflowService } from "../workflow/inngest.module.js";
+import { DB } from "../db/db.module.js";
+
+@Injectable()
+export class RoutePlansService {
+  constructor(
+    @Inject(DB) private readonly db: Database,
+    @Inject(WorkflowService) private readonly workflow: WorkflowService,
+  ) {}
+
+  /**
+   * Emit a route_plan_requested event to the worker. Returns immediately (202).
+   * Idempotency-Key is forwarded so the caller can dedupe if needed.
+   */
+  async trigger(missionId: string, idempotencyKey?: string): Promise<{ missionId: string }> {
+    // Verify mission exists.
+    const [missionRow] = await this.db
+      .select({ id: missions.id })
+      .from(missions)
+      .where(eq(missions.id, missionId))
+      .limit(1);
+
+    if (!missionRow) {
+      throw new NotFoundException(`Mission not found: ${missionId}`);
+    }
+
+    // Append a request event (best-effort audit trail).
+    await this.db.insert(missionEvents).values({
+      missionId,
+      eventType: "route_plan_requested",
+      actorType: "user",
+      payload: { idempotencyKey: idempotencyKey ?? null },
+    });
+
+    await this.workflow.send("mission.route_plan_requested", {
+      missionId,
+      idempotencyKey: idempotencyKey ?? "",
+    });
+
+    return { missionId };
+  }
+
+  /**
+   * Return the latest non-superseded route_plan for a mission, validated
+   * against RoutePlanDto (CLAUDE.md #6 — never pass through unvalidated).
+   */
+  async getLatest(missionId: string): Promise<RoutePlanDto> {
+    // Verify mission exists.
+    const [missionRow] = await this.db
+      .select({ id: missions.id, issueDomain: missions.issueDomain, currentRoutePlanId: missions.currentRoutePlanId })
+      .from(missions)
+      .where(eq(missions.id, missionId))
+      .limit(1);
+
+    if (!missionRow) {
+      throw new NotFoundException(`Mission not found: ${missionId}`);
+    }
+
+    // Fetch latest non-superseded route_plan.
+    const [planRow] = await this.db
+      .select()
+      .from(routePlans)
+      .where(
+        eq(routePlans.missionId, missionId),
+      )
+      .orderBy(desc(routePlans.createdAt))
+      .limit(10) // fetch a few in case latest is superseded
+      .then((rows) => rows.filter((r) => r.supersededAt === null));
+
+    if (!planRow) {
+      throw new NotFoundException(`No active route plan found for mission: ${missionId}`);
+    }
+
+    // Parse stored JSONB columns — these were persisted by the worker already enriched.
+    const stepsData = (planRow.steps as unknown as Array<Record<string, unknown>>) ?? [];
+    const claimsData = (planRow.citations as unknown as Array<Record<string, unknown>>) ?? [];
+
+    // Build RoutePlanDto from the stored JSONB + mission row.
+    const dto: unknown = {
+      missionId,
+      issueDomain: missionRow.issueDomain,
+      summary: planRow.summary ?? "",
+      steps: stepsData,
+      claims: claimsData, // stored as grounded claims in citations column
+      riskNotes: (planRow.riskNotes as unknown as string[]) ?? [],
+      expectedTimelineDays:
+        planRow.expectedTimeline &&
+        typeof planRow.expectedTimeline === "object" &&
+        "days" in (planRow.expectedTimeline as object)
+          ? (planRow.expectedTimeline as Record<string, unknown>)["days"]
+          : null,
+      confidence: planRow.confidence !== null ? Number(planRow.confidence) : 0,
+      routeRuleId: null, // route_plans table doesn't store routeRuleId directly
+    };
+
+    // Validate against RoutePlanDto — CLAUDE.md #6.
+    return RoutePlanDto.parse(dto);
+  }
+}

apps/api/src/workflow/inngest.module.ts

@@ -21,8 +21,10 @@ export class WorkflowService {
   async send(
     name:
       | "message.received"
-      | "evidence.uploaded",
-    data: Record<string, string>,
+      | "evidence.uploaded"
+      | "mission.route_plan_requested"
+      | "mission.facts_confirmed",
+    data: Record<string, string | boolean>,
   ): Promise<void> {
     await this.inngest.send({ name, data });
   }

apps/web/src/app/missions/[id]/page.tsx

@@ -3,7 +3,7 @@
 import { use, useCallback, useEffect, useState } from "react";
 import Link from "next/link";
 import type { Mission, MissionEvent, MissionStatusSnapshot } from "@courtmitra/contracts";
-import { api, type EvidenceItem, type FactsResponse } from "../../../lib/api";
+import { api, type EvidenceItem, type FactsResponse, type RoutePlanDto } from "../../../lib/api";
 
 // ---------------------------------------------------------------------------
 // Support-level badge
@@ -426,6 +426,294 @@ function EvidenceVault({ items }: { items: EvidenceItem[] }) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Route Plan panel
+// ---------------------------------------------------------------------------
+
+function TierBadge({ tier }: { tier: string }) {
+  const colour =
+    tier === "tier1" ? "#1a7f37" : tier === "tier2" ? "#9a6700" : "#666";
+  return (
+    <span
+      style={{
+        display: "inline-block",
+        padding: "1px 7px",
+        borderRadius: 10,
+        fontSize: 11,
+        fontWeight: 700,
+        border: `1px solid ${colour}`,
+        color: colour,
+        textTransform: "uppercase",
+      }}
+    >
+      {tier}
+    </span>
+  );
+}
+
+function LevelBadge({ level }: { level: string }) {
+  return (
+    <span
+      style={{
+        display: "inline-block",
+        padding: "2px 9px",
+        borderRadius: 10,
+        fontSize: 12,
+        fontWeight: 700,
+        background: "var(--panel-2)",
+        border: "1px solid var(--border)",
+        marginRight: 8,
+      }}
+    >
+      {level}
+    </span>
+  );
+}
+
+interface RoutePlanPanelProps {
+  plan: RoutePlanDto | null;
+  loading: boolean;
+  triggering: boolean;
+  triggerError: string | null;
+  onTrigger: () => void;
+}
+
+function RoutePlanPanel({
+  plan,
+  loading,
+  triggering,
+  triggerError,
+  onTrigger,
+}: RoutePlanPanelProps) {
+  const [expandedStep, setExpandedStep] = useState<number | null>(null);
+
+  if (loading) {
+    return (
+      <div className="card">
+        <div className="empty-state">Loading route plan…</div>
+      </div>
+    );
+  }
+
+  if (!plan) {
+    return (
+      <div className="card">
+        <div className="empty-state" style={{ marginBottom: 14 }}>
+          No route plan has been generated yet. Once facts are confirmed, you can trigger legal
+          grounding.
+        </div>
+        {triggerError && (
+          <div className="error" style={{ marginBottom: 10, fontSize: 13 }}>
+            {triggerError}
+          </div>
+        )}
+        <button onClick={onTrigger} disabled={triggering}>
+          {triggering ? "Requesting…" : "Trigger Route Plan"}
+        </button>
+      </div>
+    );
+  }
+
+  const hasClaims = plan.claims.length > 0;
+
+  return (
+    <div>
+      {/* Summary */}
+      <div className="card" style={{ marginBottom: 12 }}>
+        <div className="muted" style={{ fontSize: 12, marginBottom: 6 }}>
+          Summary · confidence {Math.round(plan.confidence * 100)}%
+        </div>
+        <div style={{ lineHeight: 1.6, fontSize: 14 }}>{plan.summary}</div>
+        {plan.riskNotes.length > 0 && (
+          <div style={{ marginTop: 10 }}>
+            <div className="muted" style={{ fontSize: 12, marginBottom: 4 }}>
+              Risk notes
+            </div>
+            <ul style={{ margin: 0, paddingLeft: 18, fontSize: 13, lineHeight: 1.7 }}>
+              {plan.riskNotes.map((note, i) => (
+                <li key={i}>{note}</li>
+              ))}
+            </ul>
+          </div>
+        )}
+        {plan.expectedTimelineDays !== null && (
+          <div style={{ marginTop: 8, fontSize: 13 }}>
+            <span className="muted">Expected timeline: </span>
+            {plan.expectedTimelineDays} calendar days
+          </div>
+        )}
+        {!hasClaims && (
+          <div
+            style={{
+              marginTop: 10,
+              padding: "8px 12px",
+              background: "var(--panel-2)",
+              border: "1px solid var(--border)",
+              borderRadius: 6,
+              fontSize: 12,
+              color: "var(--muted)",
+            }}
+          >
+            Neutral guidance — not legal advice. No verified legal citations were found for this
+            plan. All steps reflect general administrative procedure only.
+          </div>
+        )}
+        <div style={{ marginTop: 10, fontSize: 12, color: "var(--muted)" }}>
+          Legal information &amp; workflow assistance only — not a lawyer-client relationship.
+          CourtMitra does not guarantee outcomes.
+        </div>
+      </div>
+
+      {/* Steps */}
+      {plan.steps.map((step) => {
+        const isExpanded = expandedStep === step.stepNo;
+        const hasStepCitations = step.citations.length > 0;
+
+        return (
+          <div
+            key={step.stepNo}
+            className="card"
+            style={{ marginBottom: 10, cursor: "pointer" }}
+            onClick={() => setExpandedStep(isExpanded ? null : step.stepNo)}
+          >
+            {/* Step header */}
+            <div
+              style={{ display: "flex", alignItems: "flex-start", gap: 10 }}
+            >
+              <div style={{ flexShrink: 0, marginTop: 2 }}>
+                <LevelBadge level={step.level} />
+              </div>
+              <div style={{ flex: 1 }}>
+                <div style={{ fontWeight: 600, fontSize: 14 }}>{step.title}</div>
+                {step.authority && (
+                  <div className="muted" style={{ fontSize: 12, marginTop: 2 }}>
+                    Authority: {step.authority}
+                  </div>
+                )}
+                <div style={{ display: "flex", gap: 8, marginTop: 4, flexWrap: "wrap" }}>
+                  <span className="pill">{step.channel}</span>
+                  <span className="pill">{step.riskLevel} risk</span>
+                  {step.deadlineDays !== null && (
+                    <span className="pill">deadline: {step.deadlineDays}d</span>
+                  )}
+                  {!hasStepCitations && (
+                    <span className="pill" style={{ color: "var(--muted)", fontSize: 11 }}>
+                      neutral guidance
+                    </span>
+                  )}
+                </div>
+              </div>
+              <div style={{ flexShrink: 0, color: "var(--muted)", fontSize: 14 }}>
+                {isExpanded ? "▲" : "▼"}
+              </div>
+            </div>
+
+            {/* Expanded details */}
+            {isExpanded && (
+              <div style={{ marginTop: 12, borderTop: "1px solid var(--border)", paddingTop: 12 }}>
+                <div style={{ fontSize: 13, lineHeight: 1.7, marginBottom: 10 }}>
+                  {step.description}
+                </div>
+
+                {step.requiredEvidence.length > 0 && (
+                  <div style={{ marginBottom: 10 }}>
+                    <div className="muted" style={{ fontSize: 12, marginBottom: 4 }}>
+                      Required evidence
+                    </div>
+                    <ul style={{ margin: 0, paddingLeft: 18, fontSize: 13, lineHeight: 1.6 }}>
+                      {step.requiredEvidence.map((e, i) => (
+                        <li key={i}>{e}</li>
+                      ))}
+                    </ul>
+                  </div>
+                )}
+
+                {/* Citations sub-panel */}
+                {hasStepCitations ? (
+                  <div>
+                    <div className="muted" style={{ fontSize: 12, marginBottom: 6 }}>
+                      Legal citations
+                    </div>
+                    {step.citations.map((citation, ci) => (
+                      <div
+                        key={ci}
+                        style={{
+                          padding: "8px 12px",
+                          background: "var(--panel-2)",
+                          border: "1px solid var(--border)",
+                          borderRadius: 6,
+                          marginBottom: 8,
+                          fontSize: 12,
+                        }}
+                      >
+                        <div
+                          style={{
+                            display: "flex",
+                            alignItems: "center",
+                            gap: 8,
+                            marginBottom: 4,
+                            flexWrap: "wrap",
+                          }}
+                        >
+                          <span style={{ fontWeight: 600 }}>
+                            {citation.actName ?? "Unknown Act"}
+                            {citation.sectionNo ? ` §${citation.sectionNo}` : ""}
+                          </span>
+                          {citation.heading && (
+                            <span className="muted">— {citation.heading}</span>
+                          )}
+                          <TierBadge tier={citation.tier} />
+                        </div>
+                        {/* Literal quote — highlighted */}
+                        <blockquote
+                          style={{
+                            margin: "4px 0",
+                            paddingLeft: 10,
+                            borderLeft: "3px solid var(--ok, #1a7f37)",
+                            color: "var(--muted)",
+                            fontStyle: "italic",
+                            lineHeight: 1.6,
+                            fontSize: 12,
+                          }}
+                        >
+                          &ldquo;{citation.quote}&rdquo;
+                        </blockquote>
+                        {citation.canonicalUrl && (
+                          <a
+                            href={citation.canonicalUrl}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            style={{ fontSize: 11, color: "var(--ok, #1a7f37)" }}
+                            onClick={(e) => e.stopPropagation()}
+                          >
+                            View source ↗
+                          </a>
+                        )}
+                      </div>
+                    ))}
+                  </div>
+                ) : (
+                  <div
+                    style={{
+                      fontSize: 12,
+                      color: "var(--muted)",
+                      padding: "6px 10px",
+                      background: "var(--panel-2)",
+                      borderRadius: 6,
+                    }}
+                  >
+                    Neutral guidance — not legal advice
+                  </div>
+                )}
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Main page
 // ---------------------------------------------------------------------------
@@ -437,6 +725,10 @@ export default function MissionRoom({ params }: { params: Promise<{ id: string }
   const [events, setEvents] = useState<MissionEvent[]>([]);
   const [facts, setFacts] = useState<FactsResponse["facts"] | undefined>(undefined);
   const [evidenceItems, setEvidenceItems] = useState<EvidenceItem[] | undefined>(undefined);
+  const [routePlan, setRoutePlan] = useState<RoutePlanDto | null | undefined>(undefined);
+  const [routePlanLoading, setRoutePlanLoading] = useState(false);
+  const [triggering, setTriggering] = useState(false);
+  const [triggerError, setTriggerError] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [confirming, setConfirming] = useState(false);
   const [confirmMsg, setConfirmMsg] = useState<string | null>(null);
@@ -459,12 +751,37 @@ export default function MissionRoom({ params }: { params: Promise<{ id: string }
     } catch (e) {
       setError(String(e));
     }
+
+    // Fetch route plan separately — 404 is expected when plan not ready
+    setRoutePlanLoading(true);
+    try {
+      const rp = await api.getRoutePlan(id);
+      setRoutePlan(rp);
+    } catch {
+      setRoutePlan(null); // 404 or not-yet-ready
+    } finally {
+      setRoutePlanLoading(false);
+    }
   }, [id]);
 
   useEffect(() => {
     void load();
   }, [load]);
 
+  async function handleTriggerRoutePlan() {
+    setTriggering(true);
+    setTriggerError(null);
+    try {
+      await api.triggerRoutePlan(id);
+      // Poll for plan after a short delay
+      setTimeout(() => void load(), 3000);
+    } catch (e) {
+      setTriggerError(`Failed to trigger route plan: ${String(e)}`);
+    } finally {
+      setTriggering(false);
+    }
+  }
+
   async function handleConfirmFacts(updated: Record<string, unknown>) {
     setConfirming(true);
     setConfirmMsg(null);
@@ -579,6 +896,24 @@ export default function MissionRoom({ params }: { params: Promise<{ id: string }
 
       {evidenceItems !== undefined && <EvidenceVault items={evidenceItems} />}
 
+      {/* ---------------------------------------------------------------- */}
+      {/* Route Plan panel                                                  */}
+      {/* ---------------------------------------------------------------- */}
+      <div className="section-title" style={{ marginTop: 28 }}>
+        Route plan
+      </div>
+      <div className="muted" style={{ fontSize: 12, marginBottom: 10 }}>
+        Legal grounding and recommended action steps. All citations show the exact text from the
+        curated source. Legal information only — not a lawyer-client relationship.
+      </div>
+      <RoutePlanPanel
+        plan={routePlan ?? null}
+        loading={routePlanLoading}
+        triggering={triggering}
+        triggerError={triggerError}
+        onTrigger={() => void handleTriggerRoutePlan()}
+      />
+
       {/* ---------------------------------------------------------------- */}
       {/* Timeline                                                          */}
       {/* ---------------------------------------------------------------- */}

apps/web/src/lib/api.ts

@@ -6,6 +6,7 @@ import type {
   IntakeResult,
   ParsedEvidenceDto,
   EvidenceClaimDto,
+  RoutePlanDto,
 } from "@courtmitra/contracts";
 
 const API_BASE = process.env.NEXT_PUBLIC_API_BASE_URL ?? "http://localhost:3001/api";
@@ -51,6 +52,9 @@ export interface EvidenceListResponse {
   items: EvidenceItem[];
 }
 
+// Re-export RoutePlanDto for consumers.
+export type { RoutePlanDto };
+
 // ---------------------------------------------------------------------------
 // Facts endpoint response types
 // ---------------------------------------------------------------------------
@@ -95,4 +99,21 @@ export const api = {
       headers: { "idempotency-key": crypto.randomUUID() },
       body: JSON.stringify({ facts }),
     }),
+
+  /**
+   * GET /api/missions/:id/route-plan
+   * Returns the latest non-superseded RoutePlanDto, or throws 404 if not ready.
+   */
+  getRoutePlan: (id: string) => http<RoutePlanDto>(`/missions/${id}/route-plan`),
+
+  /**
+   * POST /api/missions/:id/route-plan
+   * Triggers route plan generation; returns 202 Accepted.
+   */
+  triggerRoutePlan: (id: string) =>
+    http<{ missionId: string }>(`/missions/${id}/route-plan`, {
+      method: "POST",
+      headers: { "idempotency-key": crypto.randomUUID() },
+      body: JSON.stringify({}),
+    }),
 };

apps/worker/src/deps.ts

@@ -10,9 +10,13 @@ import {
   createLocalFsStorage,
   createVercelAiLlm,
   createVisionLlmEvidenceParser,
+  createPgvectorFtsLegalRetrieval,
+  createOpenAiCompatibleEmbedder,
 } from "@courtmitra/adapters";
 
 export const db = getDb();
 export const storage = createLocalFsStorage();
 export const llm = createVercelAiLlm();
 export const parser = createVisionLlmEvidenceParser(llm, storage);
+export const embedder = createOpenAiCompatibleEmbedder();
+export const legalRetrieval = createPgvectorFtsLegalRetrieval(db, embedder);

apps/worker/src/functions/route-plan.ts

@@ -0,0 +1,550 @@
+/**
+ * Inngest function: runRoutePlan
+ *
+ * Triggered by:
+ *   - "mission.route_plan_requested" (explicit API trigger)
+ *   - "mission.facts_confirmed"       (auto-trigger after facts confirmation)
+ *
+ * Steps:
+ *   1. Acquire pg_advisory_xact_lock; re-read mission + facts + evidence_claims in-txn.
+ *   2. Bail (skipped event) if mission state is not eligible.
+ *   3. Retrieve top legal chunks via LegalRetrievalPort (pgvector + FTS).
+ *   4. Call LLM with route-plan.v1 prompt → RoutePlanGenerationResult.
+ *   5. Verify every claim: literal quote-span substring check (CLAUDE.md #4).
+ *      Drop unsupported claims; append legal_claim_rejected events.
+ *   6. Fall back to neutral admin language if zero claims survive.
+ *   7. Look up matching route_rules row for routeRuleId.
+ *   8. Persist route_plan + mission_event + status_snapshot in a transaction.
+ *
+ * CLAUDE.md invariants enforced:
+ *   #1 – Hexagonal: imports only from @courtmitra/ports (interfaces) + adapters factories.
+ *   #2 – No direct side-effects; only creates/reads DB + calls LLM/retrieval via ports.
+ *   #3 – proof_state not relevant here (no send action).
+ *   #4 – Every legal claim verified via literal substring; unverified claims dropped.
+ *   #6 – All LLM output validated against RoutePlanGenerationResult Zod schema.
+ */
+import { eq, desc, inArray, sql } from "drizzle-orm";
+import { type InngestFunction, Inngest } from "inngest";
+import { db, llm, legalRetrieval } from "../deps.js";
+import { schema } from "@courtmitra/db";
+import {
+  RoutePlanGenerationResult,
+  type RoutePlanDto,
+  type RoutePlanStepDto,
+  type GroundedClaimDto,
+  type LegalCitationDto,
+} from "@courtmitra/contracts";
+import type { RetrievedLegalSource } from "@courtmitra/ports";
+
+// ---------------------------------------------------------------------------
+// State precedence guard (same STATE_RANK as intake/evidence)
+// ---------------------------------------------------------------------------
+
+const STATE_RANK: Record<string, number> = {
+  created: 0,
+  intake_in_progress: 1,
+  needs_user_input: 2,
+  evidence_processing: 3,
+  evidence_ready: 4,
+  facts_pending_confirmation: 5,
+  facts_confirmed: 6,
+  legal_grounding_in_progress: 7,
+  route_plan_ready: 8,
+  actions_preview_ready: 9,
+  actions_awaiting_consent: 10,
+  action_executing: 11,
+  waiting_for_response: 12,
+  followup_due: 13,
+  escalation_ready: 14,
+  human_review_required: 15,
+  resolver_reply_received: 16,
+  resolution_claimed: 17,
+  resolved: 18,
+  closed_unresolved: 19,
+  paused: 20,
+  blocked: 21,
+  failed: 22,
+};
+
+// States from which route planning is allowed to proceed.
+const ELIGIBLE_STATES = new Set([
+  "facts_confirmed",
+  "evidence_ready",
+  "facts_pending_confirmation",
+]);
+
+// ---------------------------------------------------------------------------
+// Helper: dedupe retrieved chunks by chunkId, take at most maxChunks
+// ---------------------------------------------------------------------------
+
+function dedupeChunks(
+  chunks: RetrievedLegalSource[],
+  maxChunks: number,
+): RetrievedLegalSource[] {
+  const seen = new Set<string>();
+  const result: RetrievedLegalSource[] = [];
+  for (const c of chunks) {
+    if (!seen.has(c.chunkId)) {
+      seen.add(c.chunkId);
+      result.push(c);
+      if (result.length >= maxChunks) break;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// runRoutePlan — called directly by the Inngest handler or API trigger
+// ---------------------------------------------------------------------------
+
+export async function runRoutePlan(
+  missionId: string,
+  opts: { forceRun?: boolean } = {},
+): Promise<{ missionId: string; routePlanId?: string; skipped?: boolean; reason?: string }> {
+  // --------------------------------------------------------------------------
+  // Step 1: Re-read mission + evidence_claims inside a transaction with
+  // advisory lock to prevent concurrent route-plan runs.
+  // --------------------------------------------------------------------------
+  const { mission, evidenceClaimRows, routeRuleRow } = await db.transaction(async (tx) => {
+    // Advisory lock keyed by mission ID — prevents concurrent plan creation.
+    await tx.execute(
+      sql`SELECT pg_advisory_xact_lock(hashtext(${"route_plan:" + missionId}))`,
+    );
+
+    const [missionRow] = await tx
+      .select()
+      .from(schema.missions)
+      .where(eq(schema.missions.id, missionId))
+      .limit(1);
+
+    if (!missionRow) {
+      throw new Error(`Mission not found: ${missionId}`);
+    }
+
+    const claims = await tx
+      .select()
+      .from(schema.evidenceClaims)
+      .where(eq(schema.evidenceClaims.missionId, missionId));
+
+    // Look up route_rules matching the mission's issue_domain.
+    const [ruleRow] = await tx
+      .select()
+      .from(schema.routeRules)
+      .where(
+        eq(schema.routeRules.issueDomain, missionRow.issueDomain),
+      )
+      .orderBy(desc(schema.routeRules.priority))
+      .limit(1);
+
+    return { mission: missionRow, evidenceClaimRows: claims, routeRuleRow: ruleRow ?? null };
+  });
+
+  // --------------------------------------------------------------------------
+  // Step 2: Bail if mission state is not eligible (unless forced).
+  // --------------------------------------------------------------------------
+  if (!opts.forceRun && !ELIGIBLE_STATES.has(mission.state)) {
+    await db.insert(schema.missionEvents).values({
+      missionId,
+      eventType: "route_plan_skipped",
+      actorType: "ai",
+      payload: {
+        reason: `mission_state_not_eligible`,
+        currentState: mission.state,
+        eligibleStates: [...ELIGIBLE_STATES],
+      },
+    });
+    return { missionId, skipped: true, reason: `mission_state_not_eligible (${mission.state})` };
+  }
+
+  const facts = (mission.facts as Record<string, unknown> | null) ?? {};
+  const summary = typeof facts["summary"] === "string" ? facts["summary"] : "";
+  const reliefRequested =
+    mission.reliefRequested && typeof mission.reliefRequested === "object"
+      ? JSON.stringify(mission.reliefRequested)
+      : "";
+
+  // --------------------------------------------------------------------------
+  // Step 3: Build retrieval queries and fetch legal chunks.
+  // --------------------------------------------------------------------------
+
+  // Build query strings from mission summary + relief + top evidence claims.
+  const topClaimTexts = evidenceClaimRows
+    .filter((c) => c.supportLevel === "explicit" || c.supportLevel === "inferred")
+    .slice(0, 2)
+    .map((c) => c.claimText);
+
+  const queryParts = [summary, reliefRequested, ...topClaimTexts].filter(Boolean);
+  const baseQuery = queryParts.join(". ");
+
+  // If route_rules exist and specify a route_graph, also query for each step's
+  // authority as secondary queries.
+  const queries: string[] = [baseQuery];
+  if (routeRuleRow?.routeGraph && typeof routeRuleRow.routeGraph === "object") {
+    const graph = routeRuleRow.routeGraph as Record<string, unknown>;
+    if (Array.isArray(graph["steps"])) {
+      const stepQueries = (graph["steps"] as Array<Record<string, unknown>>)
+        .slice(0, 2)
+        .map((s) => [String(s["authority"] ?? ""), String(s["title"] ?? "")].filter(Boolean).join(" "));
+      queries.push(...stepQueries.filter((q) => q.trim()));
+    }
+  }
+
+  // Execute retrieval queries (deduped across queries, cap at 12 chunks).
+  const rawChunks: RetrievedLegalSource[] = [];
+  for (const q of queries) {
+    if (!q.trim()) continue;
+    const retrieved = await legalRetrieval.retrieve({
+      missionId,
+      issueDomain: mission.issueDomain,
+      query: q,
+      topK: 8,
+    });
+    rawChunks.push(...retrieved);
+  }
+  // Curator backstop: always include chunks listed in the matching route_rule's
+  // source_citations so the LLM has authoritative grounding even when FTS/ANN
+  // retrieval returns few hits (CLAUDE.md #4 — grounding requires real chunks).
+  if (routeRuleRow?.sourceCitations && Array.isArray(routeRuleRow.sourceCitations) && routeRuleRow.sourceCitations.length > 0) {
+    const curatorChunks = await db
+      .select({
+        id: schema.legalChunks.id,
+        sourceId: schema.legalChunks.sourceId,
+        actName: schema.legalChunks.actName,
+        sectionNo: schema.legalChunks.sectionNo,
+        heading: schema.legalChunks.heading,
+        text: schema.legalChunks.text,
+      })
+      .from(schema.legalChunks)
+      .where(inArray(schema.legalChunks.id, routeRuleRow.sourceCitations as string[]));
+    for (const c of curatorChunks) {
+      rawChunks.push({
+        chunkId: c.id,
+        sourceId: c.sourceId,
+        actName: c.actName,
+        sectionNo: c.sectionNo,
+        heading: c.heading,
+        text: c.text,
+        score: 999, // pinned: curator decided this chunk is relevant
+      });
+    }
+  }
+
+  const retrievedChunks = dedupeChunks(rawChunks, 12);
+
+  // --------------------------------------------------------------------------
+  // Step 4: Render chunk context for the prompt.
+  // --------------------------------------------------------------------------
+
+  const chunkContext = retrievedChunks
+    .map(
+      (c) =>
+        `<chunk chunk_id="${c.chunkId}">\n${c.actName ? `Act: ${c.actName}` : ""}${c.sectionNo ? ` §${c.sectionNo}` : ""}${c.heading ? ` — ${c.heading}` : ""}\n${c.text}\n</chunk>`,
+    )
+    .join("\n\n");
+
+  const evidenceClaimsForPrompt = evidenceClaimRows.map((c) => ({
+    claimText: c.claimText,
+    claimType: c.claimType,
+    supportLevel: c.supportLevel,
+  }));
+
+  // --------------------------------------------------------------------------
+  // Step 5: Call LLM → RoutePlanGenerationResult (Zod-validated).
+  // --------------------------------------------------------------------------
+  const llmResult = await llm.generateStructured({
+    promptId: "route-plan.v1",
+    variables: {
+      issueDomain: mission.issueDomain,
+      missionFacts: facts,
+      evidenceClaims: evidenceClaimsForPrompt,
+      retrievedChunks: chunkContext,
+    },
+    schema: RoutePlanGenerationResult,
+  });
+  const generated = llmResult.output;
+
+  // --------------------------------------------------------------------------
+  // Step 6: Verify each claim (literal quote-span check — CLAUDE.md #4).
+  // Build a chunkId → text map from retrieved chunks for fast lookup.
+  // --------------------------------------------------------------------------
+
+  const chunkTextMap = new Map<string, RetrievedLegalSource>(
+    retrievedChunks.map((c) => [c.chunkId, c]),
+  );
+
+  const survivingClaims: GroundedClaimDto[] = [];
+
+  for (const rawClaim of generated.claims) {
+    const verifyResult = await legalRetrieval.verifyClaimSupport({
+      missionId,
+      claim: rawClaim.claim,
+      quoteSpans: rawClaim.quoteSpans,
+      chunkIds: rawClaim.chunkIds,
+    });
+
+    if (!verifyResult.supported) {
+      // Append rejection event (best-effort, non-blocking).
+      await db.insert(schema.missionEvents).values({
+        missionId,
+        eventType: "legal_claim_rejected",
+        actorType: "ai",
+        payload: {
+          claim: rawClaim.claim,
+          reason: verifyResult.failureReason ?? "quote_span_not_found_in_chunk",
+          chunkIds: rawClaim.chunkIds,
+          quoteSpans: rawClaim.quoteSpans,
+        },
+      }).catch((e) => console.warn("[RoutePlan] Failed to append legal_claim_rejected event:", e));
+      continue;
+    }
+
+    // Build citations from cited chunks.
+    const rawCitations = verifyResult.citedChunkIds
+      .map((cid) => {
+        const chunk = chunkTextMap.get(cid);
+        if (!chunk) return null;
+        // Use first matching quote span as the canonical quote.
+        const quote = rawClaim.quoteSpans[0] ?? "";
+        const citation: LegalCitationDto = {
+          chunkId: cid,
+          sourceId: chunk.sourceId,
+          actName: chunk.actName,
+          sectionNo: chunk.sectionNo,
+          heading: chunk.heading,
+          canonicalUrl: null, // TODO: enrich from legalSources.canonicalUrl (Agent B seeds this)
+          tier: ((chunk as RetrievedLegalSource & { tier?: string }).tier ?? "tier3") as LegalCitationDto["tier"],
+          quote,
+        };
+        return citation;
+      });
+    const citations: LegalCitationDto[] = rawCitations.filter((c): c is LegalCitationDto => c !== null);
+
+    survivingClaims.push({
+      claim: rawClaim.claim,
+      citations,
+      supportLevel: verifyResult.supportLevel,
+      confidence: rawClaim.confidence,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Step 7: If zero claims survived and some steps have legal language,
+  // strip claim refs from steps to avoid implying legal grounding that doesn't exist.
+  // --------------------------------------------------------------------------
+
+  const hasGrounding = survivingClaims.length > 0;
+
+  // Build surviving claim index set for step.claimRefs filtering.
+  const survivingClaimIndices = new Set(
+    generated.claims
+      .map((c, idx) => ({ c, idx }))
+      .filter(({ c }) =>
+        survivingClaims.some((s) => s.claim === c.claim),
+      )
+      .map(({ idx }) => idx),
+  );
+
+  // Map generated steps → RoutePlanStepDto, enriching with surviving citations.
+  const steps: RoutePlanStepDto[] = generated.steps.map((s) => {
+    const stepCitations: LegalCitationDto[] = [];
+    const survivingClaimRefs: number[] = [];
+
+    for (const claimIdx of s.claimRefs) {
+      if (survivingClaimIndices.has(claimIdx)) {
+        survivingClaimRefs.push(claimIdx);
+        const survivingClaim = survivingClaims.find(
+          (sc) => sc.claim === generated.claims[claimIdx]?.claim,
+        );
+        if (survivingClaim) {
+          stepCitations.push(...survivingClaim.citations);
+        }
+      }
+    }
+
+    // If zero citations, neutralise description to avoid implied legal grounding.
+    let description = s.description;
+    if (!hasGrounding && s.claimRefs.length > 0) {
+      description =
+        `[Neutral guidance — not legal advice] ${s.description}`;
+    }
+
+    return {
+      stepNo: s.stepNo,
+      level: s.level,
+      title: s.title,
+      description,
+      authority: s.authority,
+      channel: s.channel,
+      actionType: s.actionType,
+      requiredEvidence: s.requiredEvidence,
+      deadlineDays: s.deadlineDays,
+      citations: stepCitations,
+      riskLevel: s.riskLevel,
+    } satisfies RoutePlanStepDto;
+  });
+
+  // --------------------------------------------------------------------------
+  // Step 8: Fetch canonical URLs for citations (enrich from legalSources).
+  // Best-effort — if legalSources.canonicalUrl is seeded by Agent B, populate.
+  // --------------------------------------------------------------------------
+  const sourceIds = [...new Set(survivingClaims.flatMap((c) => c.citations.map((ci) => ci.sourceId)))];
+  let canonicalUrlMap = new Map<string, string | null>();
+  if (sourceIds.length > 0) {
+    const sourceRows = await db
+      .select({ id: schema.legalSources.id, canonicalUrl: schema.legalSources.canonicalUrl })
+      .from(schema.legalSources)
+      .where(inArray(schema.legalSources.id, sourceIds));
+    canonicalUrlMap = new Map(sourceRows.map((r) => [r.id, r.canonicalUrl]));
+  }
+
+  // Enrich citations with canonical URLs.
+  const enrichedClaims: GroundedClaimDto[] = survivingClaims.map((claim) => ({
+    ...claim,
+    citations: claim.citations.map((ci) => ({
+      ...ci,
+      canonicalUrl: canonicalUrlMap.get(ci.sourceId) ?? null,
+    })),
+  }));
+
+  const enrichedSteps: RoutePlanStepDto[] = steps.map((step) => ({
+    ...step,
+    citations: step.citations.map((ci) => ({
+      ...ci,
+      canonicalUrl: canonicalUrlMap.get(ci.sourceId) ?? null,
+    })),
+  }));
+
+  // --------------------------------------------------------------------------
+  // Step 9: Compute aggregate confidence.
+  // --------------------------------------------------------------------------
+  const confidence =
+    enrichedClaims.length > 0
+      ? enrichedClaims.reduce((sum, c) => sum + c.confidence, 0) / enrichedClaims.length
+      : 0.3; // low baseline when no grounded claims
+
+  // --------------------------------------------------------------------------
+  // Step 10: Persist everything in a single transaction.
+  // --------------------------------------------------------------------------
+  const routePlanDto: Omit<RoutePlanDto, "missionId"> = {
+    issueDomain: mission.issueDomain as RoutePlanDto["issueDomain"],
+    summary: generated.summary,
+    steps: enrichedSteps,
+    claims: enrichedClaims,
+    riskNotes: generated.riskNotes,
+    expectedTimelineDays: generated.expectedTimelineDays,
+    confidence,
+    routeRuleId: routeRuleRow?.id ?? null,
+  };
+
+  const routePlanId = await db.transaction(async (tx) => {
+    // Mark any existing active route_plans as superseded.
+    const existingPlans = await tx
+      .select({ id: schema.routePlans.id })
+      .from(schema.routePlans)
+      .where(eq(schema.routePlans.missionId, missionId));
+
+    if (existingPlans.length > 0) {
+      await tx
+        .update(schema.routePlans)
+        .set({ supersededAt: new Date() })
+        .where(eq(schema.routePlans.missionId, missionId));
+    }
+
+    // Insert new route_plan.
+    const [newPlan] = await tx
+      .insert(schema.routePlans)
+      .values({
+        missionId,
+        summary: routePlanDto.summary,
+        steps: enrichedSteps as unknown as Record<string, unknown>[],
+        citations: enrichedClaims.flatMap((c) => c.citations) as unknown as Record<string, unknown>[],
+        riskNotes: routePlanDto.riskNotes,
+        expectedTimeline: { days: routePlanDto.expectedTimelineDays },
+        confidence: String(routePlanDto.confidence),
+      })
+      .returning({ id: schema.routePlans.id });
+
+    if (!newPlan) throw new Error("Failed to insert route_plan row");
+
+    // Update mission.currentRoutePlanId.
+    await tx
+      .update(schema.missions)
+      .set({ currentRoutePlanId: newPlan.id, updatedAt: new Date() })
+      .where(eq(schema.missions.id, missionId));
+
+    // Append mission_event.
+    await tx.insert(schema.missionEvents).values({
+      missionId,
+      eventType: "route_plan_created",
+      actorType: "ai",
+      payload: {
+        routePlanId: newPlan.id,
+        stepsCount: enrichedSteps.length,
+        claimsCount: enrichedClaims.length,
+        confidence: routePlanDto.confidence,
+        hasGrounding,
+        routeRuleId: routeRuleRow?.id ?? null,
+      },
+    });
+
+    // Status snapshot — only if it does not regress state.
+    const [latestSnapshot] = await tx
+      .select({ state: schema.missionStatusSnapshots.state })
+      .from(schema.missionStatusSnapshots)
+      .where(eq(schema.missionStatusSnapshots.missionId, missionId))
+      .orderBy(desc(schema.missionStatusSnapshots.createdAt))
+      .limit(1);
+
+    const currentRank = STATE_RANK[latestSnapshot?.state ?? ""] ?? -1;
+    const newState = "route_plan_ready";
+    const newRank = STATE_RANK[newState] ?? 0;
+
+    if (newRank >= currentRank) {
+      await tx.insert(schema.missionStatusSnapshots).values({
+        missionId,
+        state: newState,
+        headline: hasGrounding
+          ? `Route plan ready — ${enrichedSteps.length} steps, grounded in ${enrichedClaims.length} legal citation(s).`
+          : `Route plan ready — ${enrichedSteps.length} steps (neutral guidance, no verified legal citations found).`,
+        nextUserAction: "Review the route plan and approve the first action.",
+        nextSystemAction: "Prepare action packets for user consent.",
+        primaryButton: "View route plan",
+        confidence: String(routePlanDto.confidence),
+      });
+    }
+
+    return newPlan.id;
+  });
+
+  return { missionId, routePlanId };
+}
+
+// ---------------------------------------------------------------------------
+// Inngest function factory
+// ---------------------------------------------------------------------------
+
+export function createRunRoutePlan(inngest: Inngest): InngestFunction.Any {
+  return inngest.createFunction(
+    {
+      id: "run-route-plan",
+      name: "Run Route Plan",
+      triggers: [
+        { event: "mission.route_plan_requested" },
+        { event: "mission.facts_confirmed" },
+      ],
+    },
+    async ({ event, step }) => {
+      const { missionId, forceRun } = event.data as {
+        missionId: string;
+        forceRun?: boolean;
+      };
+
+      // All work is done inside step.run for Inngest durability/retryability.
+      const result = await step.run("run-route-plan", async () => {
+        return runRoutePlan(missionId, { forceRun: Boolean(forceRun) });
+      });
+
+      return result;
+    },
+  ) as InngestFunction.Any;
+}

apps/worker/src/inngest.ts

@@ -1,6 +1,7 @@
 import { Inngest, type InngestFunction } from "inngest";
 import { createRunIntake } from "./functions/intake.js";
 import { createParseEvidence } from "./functions/evidence.js";
+import { createRunRoutePlan } from "./functions/route-plan.js";
 
 /**
  * Inngest client. Phase-1 functions (intake, evidence parse, legal grounding,
@@ -13,4 +14,5 @@ export const inngest = new Inngest({ id: "courtmitra" });
 export const functions: InngestFunction.Any[] = [
   createRunIntake(inngest),
   createParseEvidence(inngest),
+  createRunRoutePlan(inngest),
 ];

packages/adapters/package.json

@@ -15,10 +15,12 @@
   "dependencies": {
     "@ai-sdk/openai-compatible": "^2.0.48",
     "@courtmitra/contracts": "workspace:*",
+    "@courtmitra/db": "workspace:*",
     "@courtmitra/ports": "workspace:*",
     "@courtmitra/prompts": "workspace:*",
     "@openrouter/ai-sdk-provider": "^2.9.0",
     "ai": "^6.0.191",
+    "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

packages/adapters/src/__tests__/route-plan-verifier-gating.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Unit test: RoutePlan verifier-gating logic
+ *
+ * Tests the core invariant (CLAUDE.md #4): a legal claim is dropped when its
+ * quoteSpans do not literally appear in any cited chunk.text, and a
+ * legal_claim_rejected mission_event is appended.
+ *
+ * We mock the LegalRetrievalPort so no DB is required.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { LegalRetrievalPort, ClaimSupportCheck, ClaimSupportResult, RetrievedLegalSource } from "@courtmitra/ports";
+
+// ---------------------------------------------------------------------------
+// Inline the verifier-gating logic extracted from route-plan.ts
+// This is the same logic used by runRoutePlan — isolated here for unit testing.
+// ---------------------------------------------------------------------------
+
+interface RawClaim {
+  claim: string;
+  quoteSpans: string[];
+  chunkIds: string[];
+  confidence: number;
+}
+
+interface RetrievedChunk {
+  chunkId: string;
+  sourceId: string;
+  actName: string | null;
+  sectionNo: string | null;
+  heading: string | null;
+  text: string;
+  score: number;
+}
+
+interface RejectedEvent {
+  claim: string;
+  reason: string | null;
+}
+
+/**
+ * The verifier-gating function (extracted for unit testing).
+ *
+ * For each rawClaim:
+ *   - call retrieval.verifyClaimSupport
+ *   - if supported=false, push a rejection event and skip
+ *   - if supported=true, add to surviving claims
+ */
+async function applyVerifierGating(
+  missionId: string,
+  rawClaims: RawClaim[],
+  retrieval: LegalRetrievalPort,
+): Promise<{
+  survivingClaims: RawClaim[];
+  rejectedEvents: RejectedEvent[];
+}> {
+  const survivingClaims: RawClaim[] = [];
+  const rejectedEvents: RejectedEvent[] = [];
+
+  for (const rawClaim of rawClaims) {
+    const result = await retrieval.verifyClaimSupport({
+      missionId,
+      claim: rawClaim.claim,
+      quoteSpans: rawClaim.quoteSpans,
+      chunkIds: rawClaim.chunkIds,
+    });
+
+    if (!result.supported) {
+      rejectedEvents.push({
+        claim: rawClaim.claim,
+        reason: result.failureReason,
+      });
+    } else {
+      survivingClaims.push(rawClaim);
+    }
+  }
+
+  return { survivingClaims, rejectedEvents };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("route-plan verifier-gating: claim rejection", () => {
+  const missionId = "c0eebc99-9c0b-4ef8-bb6d-6bb9bd380a33";
+
+  // A chunk with known text
+  const realChunk: RetrievedChunk = {
+    chunkId: "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
+    sourceId: "b0eebc99-9c0b-4ef8-bb6d-6bb9bd380a22",
+    actName: "Consumer Protection Act, 2019",
+    sectionNo: "2(7)",
+    heading: "Definition of consumer",
+    text: "A consumer means any person who buys any goods for a consideration which has been paid or promised.",
+    score: 0.9,
+  };
+
+  // A quote that does NOT appear in realChunk.text
+  const fabricatedQuoteSpan =
+    "the consumer is entitled to immediate full refund under Section 47";
+
+  // A quote that IS a verbatim substring of realChunk.text
+  const verbatimQuoteSpan = "any person who buys any goods for a consideration";
+
+  let mockRetrieval: LegalRetrievalPort;
+
+  beforeEach(() => {
+    // Simulate the literal substring check (mirrors PgvectorFtsLegalRetrieval logic).
+    const verifyImpl = async (i: ClaimSupportCheck): Promise<ClaimSupportResult> => {
+      const normalise = (t: string) => t.replace(/\s+/g, " ").trim();
+      const normChunkText = normalise(realChunk.text);
+
+      for (const span of i.quoteSpans) {
+        const normSpan = normalise(span);
+        if (!normChunkText.includes(normSpan)) {
+          return {
+            supported: false,
+            supportLevel: "unsupported",
+            citedChunkIds: [],
+            failureReason: `Quote span "${span}" not found in any cited chunk after whitespace normalisation.`,
+          };
+        }
+      }
+
+      return {
+        supported: true,
+        supportLevel: "direct",
+        citedChunkIds: [realChunk.chunkId],
+        failureReason: null,
+      };
+    };
+
+    const retrieveImpl = async (): Promise<RetrievedLegalSource[]> =>
+      [realChunk as unknown as RetrievedLegalSource];
+
+    mockRetrieval = {
+      retrieve: vi.fn().mockImplementation(retrieveImpl),
+      verifyClaimSupport: vi.fn().mockImplementation(verifyImpl),
+    };
+  });
+
+  it("drops a claim whose quoteSpan does not appear in any chunk", async () => {
+    const rawClaims: RawClaim[] = [
+      {
+        claim: "Consumer is entitled to immediate full refund.",
+        quoteSpans: [fabricatedQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.85,
+      },
+    ];
+
+    const { survivingClaims, rejectedEvents } = await applyVerifierGating(
+      missionId,
+      rawClaims,
+      mockRetrieval,
+    );
+
+    expect(survivingClaims).toHaveLength(0);
+    expect(rejectedEvents).toHaveLength(1);
+    expect(rejectedEvents[0]!.claim).toBe(rawClaims[0]!.claim);
+    expect(rejectedEvents[0]!.reason).toContain("not found");
+  });
+
+  it("appends a legal_claim_rejected event for each dropped claim", async () => {
+    const rawClaims: RawClaim[] = [
+      {
+        claim: "Fabricated claim A.",
+        quoteSpans: ["this text does not exist in any chunk"],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.7,
+      },
+      {
+        claim: "Fabricated claim B.",
+        quoteSpans: ["another fabricated quote span"],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.6,
+      },
+    ];
+
+    const { survivingClaims, rejectedEvents } = await applyVerifierGating(
+      missionId,
+      rawClaims,
+      mockRetrieval,
+    );
+
+    expect(survivingClaims).toHaveLength(0);
+    expect(rejectedEvents).toHaveLength(2);
+    expect(rejectedEvents.map((e) => e.claim)).toEqual([
+      "Fabricated claim A.",
+      "Fabricated claim B.",
+    ]);
+  });
+
+  it("keeps a claim whose quoteSpan is a verbatim substring of the chunk", async () => {
+    const rawClaims: RawClaim[] = [
+      {
+        claim: "A consumer is any person who buys any goods for a consideration.",
+        quoteSpans: [verbatimQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.95,
+      },
+    ];
+
+    const { survivingClaims, rejectedEvents } = await applyVerifierGating(
+      missionId,
+      rawClaims,
+      mockRetrieval,
+    );
+
+    expect(survivingClaims).toHaveLength(1);
+    expect(rejectedEvents).toHaveLength(0);
+    expect(survivingClaims[0]!.claim).toBe(rawClaims[0]!.claim);
+  });
+
+  it("filters mixed claims: keeps verified, drops fabricated", async () => {
+    const rawClaims: RawClaim[] = [
+      {
+        claim: "Valid claim with verbatim quote.",
+        quoteSpans: [verbatimQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.9,
+      },
+      {
+        claim: "Invalid claim with fabricated quote.",
+        quoteSpans: [fabricatedQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.8,
+      },
+    ];
+
+    const { survivingClaims, rejectedEvents } = await applyVerifierGating(
+      missionId,
+      rawClaims,
+      mockRetrieval,
+    );
+
+    expect(survivingClaims).toHaveLength(1);
+    expect(survivingClaims[0]!.claim).toBe("Valid claim with verbatim quote.");
+    expect(rejectedEvents).toHaveLength(1);
+    expect(rejectedEvents[0]!.claim).toBe("Invalid claim with fabricated quote.");
+  });
+
+  it("calls verifyClaimSupport once per claim", async () => {
+    const rawClaims: RawClaim[] = [
+      {
+        claim: "Claim one.",
+        quoteSpans: [verbatimQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.9,
+      },
+      {
+        claim: "Claim two.",
+        quoteSpans: [fabricatedQuoteSpan],
+        chunkIds: [realChunk.chunkId],
+        confidence: 0.7,
+      },
+    ];
+
+    await applyVerifierGating(missionId, rawClaims, mockRetrieval);
+
+    expect(mockRetrieval.verifyClaimSupport).toHaveBeenCalledTimes(2);
+  });
+});

packages/adapters/src/__tests__/verifier.test.ts

@@ -0,0 +1,237 @@
+/**
+ * Unit tests for the legal claim verifier (CLAUDE.md #4 — Invariant #4).
+ *
+ * All tests are pure (no DB, no network). The DB-interacting methods are
+ * mocked so that `verifyClaimSupport` can be tested in isolation.
+ *
+ * Coverage:
+ *   - exact substring match → supported
+ *   - whitespace-normalised match (multiple spaces / newlines collapsed) → supported
+ *   - one quote span missing → unsupported, failureReason mentions which quote
+ *   - empty citedChunkIds → unsupported
+ *   - tier1 chunk → supportLevel "direct"
+ *   - tier2 chunk → supportLevel "supportive"
+ *   - tier3-only chunks → supportLevel "weak"
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { PgvectorFtsLegalRetrieval, normaliseText } from "../legal/pgvector-fts.js";
+import type { EmbeddingPort } from "@courtmitra/ports";
+
+// ---------------------------------------------------------------------------
+// normaliseText (pure helper) tests
+// ---------------------------------------------------------------------------
+
+describe("normaliseText", () => {
+  it("collapses multiple spaces to a single space", () => {
+    expect(normaliseText("foo  bar   baz")).toBe("foo bar baz");
+  });
+
+  it("collapses newlines and tabs", () => {
+    expect(normaliseText("foo\n\nbar\t\tbaz")).toBe("foo bar baz");
+  });
+
+  it("trims leading/trailing whitespace", () => {
+    expect(normaliseText("  hello world  ")).toBe("hello world");
+  });
+
+  it("handles mixed whitespace types", () => {
+    expect(normaliseText("\t foo \r\n bar \n")).toBe("foo bar");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+/** Build a fake EmbeddingPort that returns a dummy 1536-dim vector. */
+function makeFakeEmbedder(): EmbeddingPort {
+  return {
+    dimensions: 1536,
+    embed: vi.fn().mockResolvedValue([[...Array(1536).fill(0.1)]]),
+  };
+}
+
+/**
+ * Build a minimal mock of the Drizzle `db` object, sufficient to exercise
+ * `verifyClaimSupport`. We mock the builder chain:
+ *   db.select(shape) → { from(table) → { innerJoin(table, cond) → { where(cond) → Promise<rows> } } }
+ * and db.insert(table) → { values(row) → Promise<void> }
+ */
+function makeDb(chunkRows: { id: string; text: string; tier: string }[]) {
+  // Drizzle chain: db.select(shape).from(table).innerJoin(table, cond).where(cond)
+  const whereMock = vi.fn().mockResolvedValue(chunkRows);
+  const innerJoinResult = { where: whereMock };
+  const innerJoinMock = vi.fn().mockReturnValue(innerJoinResult);
+  const fromResult = { innerJoin: innerJoinMock };
+  const fromMock = vi.fn().mockReturnValue(fromResult);
+  // select() receives a shape object, returns a builder with .from()
+  const selectResult = { from: fromMock };
+  const selectMock = vi.fn().mockReturnValue(selectResult);
+
+  const insertValuesMock = vi.fn().mockResolvedValue(undefined);
+  const insertMock = { values: insertValuesMock };
+
+  return {
+    select: selectMock,
+    insert: vi.fn().mockReturnValue(insertMock),
+    execute: vi.fn().mockResolvedValue([]),
+  } as unknown as import("@courtmitra/db").Database;
+}
+
+// ---------------------------------------------------------------------------
+// verifyClaimSupport tests
+// ---------------------------------------------------------------------------
+
+describe("PgvectorFtsLegalRetrieval.verifyClaimSupport", () => {
+  let embedder: EmbeddingPort;
+
+  beforeEach(() => {
+    embedder = makeFakeEmbedder();
+  });
+
+  it("returns supported=true for an exact substring match", async () => {
+    const db = makeDb([
+      { id: "chunk-1", text: "The Consumer Protection Act 2019 grants rights.", tier: "tier1" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-1",
+      claim: "Consumer rights claim",
+      quoteSpans: ["Consumer Protection Act 2019"],
+      chunkIds: ["chunk-1"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("direct");
+    expect(result.failureReason).toBeNull();
+  });
+
+  it("returns supported=true after whitespace normalisation (multiple spaces/newlines)", async () => {
+    const db = makeDb([
+      {
+        id: "chunk-2",
+        text: "Section 47  of the  Act\nprovides for penalties.",
+        tier: "tier2",
+      },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    // The quoteSpan has normalised spaces; the chunk text has extra spaces + newlines
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-2",
+      claim: "Penalty claim",
+      quoteSpans: ["Section 47 of the Act provides for penalties."],
+      chunkIds: ["chunk-2"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("supportive");
+    expect(result.failureReason).toBeNull();
+  });
+
+  it("returns supported=false when one quoteSpan is missing, failureReason names it", async () => {
+    const db = makeDb([
+      { id: "chunk-3", text: "The right to information is enshrined in RTI Act.", tier: "tier1" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-3",
+      claim: "RTI claim",
+      quoteSpans: ["right to information", "compensation shall be paid within 30 days"],
+      chunkIds: ["chunk-3"],
+    });
+
+    expect(result.supported).toBe(false);
+    expect(result.supportLevel).toBe("unsupported");
+    expect(result.failureReason).toContain("compensation shall be paid within 30 days");
+  });
+
+  it("returns supported=false when citedChunkIds is empty", async () => {
+    const db = makeDb([]); // no chunks needed — guard fires before DB call
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-4",
+      claim: "Some claim",
+      quoteSpans: ["some quote"],
+      chunkIds: [],
+    });
+
+    expect(result.supported).toBe(false);
+    expect(result.supportLevel).toBe("unsupported");
+    expect(result.failureReason).toMatch(/no cited chunk/i);
+    expect(result.citedChunkIds).toHaveLength(0);
+  });
+
+  it("returns supportLevel=direct for a tier1 chunk", async () => {
+    const db = makeDb([
+      { id: "chunk-t1", text: "IPC Section 420 covers cheating.", tier: "tier1" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-5",
+      claim: "Cheating claim",
+      quoteSpans: ["IPC Section 420 covers cheating."],
+      chunkIds: ["chunk-t1"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("direct");
+  });
+
+  it("returns supportLevel=supportive for a tier2 chunk (no tier1)", async () => {
+    const db = makeDb([
+      { id: "chunk-t2", text: "SEBI regulations govern market conduct.", tier: "tier2" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-6",
+      claim: "SEBI claim",
+      quoteSpans: ["SEBI regulations govern market conduct."],
+      chunkIds: ["chunk-t2"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("supportive");
+  });
+
+  it("returns supportLevel=weak for tier3-only chunks", async () => {
+    const db = makeDb([
+      { id: "chunk-t3", text: "Consumer forum guidelines may apply.", tier: "tier3" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-7",
+      claim: "Forum claim",
+      quoteSpans: ["Consumer forum guidelines may apply."],
+      chunkIds: ["chunk-t3"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("weak");
+  });
+
+  it("tier1 chunk beats tier2 in supportLevel when both are present", async () => {
+    const db = makeDb([
+      { id: "chunk-a", text: "IPC Section 420 covers cheating.", tier: "tier1" },
+      { id: "chunk-b", text: "SEBI regulations govern market conduct.", tier: "tier2" },
+    ]);
+    const adapter = new PgvectorFtsLegalRetrieval(db, embedder);
+
+    const result = await adapter.verifyClaimSupport({
+      missionId: "mission-8",
+      claim: "Multi-source claim",
+      quoteSpans: ["IPC Section 420 covers cheating."],
+      chunkIds: ["chunk-a", "chunk-b"],
+    });
+
+    expect(result.supported).toBe(true);
+    expect(result.supportLevel).toBe("direct");
+  });
+});

packages/adapters/src/embedder/openai-compatible.ts

@@ -0,0 +1,78 @@
+/**
+ * EmbeddingPort implementation backed by Vercel AI SDK `embedMany` +
+ * `@ai-sdk/openai-compatible`.
+ *
+ * Provider resolution (in order):
+ *   1. EMBEDDING_PROVIDER env var
+ *   2. AI_PROVIDER env var
+ *   Falls back to using OPENCODE_BASE_URL (https://opencode.ai/zen/go/v1) for
+ *   "opencode" or "openai-compatible", and OpenRouter for "openrouter".
+ *
+ * Model: EMBEDDING_MODEL env var, default `text-embedding-3-small` (1536 dims).
+ *
+ * HONEST FALLBACK: if the API errors (model not supported, 404, etc.) this
+ * adapter throws a descriptive error. It NEVER returns fake/zero embeddings.
+ * The caller / capability registry must mark this adapter `blocked` on failure.
+ */
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { embedMany } from "ai";
+import type { EmbeddingPort } from "@courtmitra/ports";
+
+const EMBEDDING_DIM = 1536;
+
+class EmbeddingError extends Error {
+  override name = "EmbeddingError";
+  constructor(message: string, cause?: unknown) {
+    super(message, { cause });
+  }
+}
+
+export class OpenAiCompatibleEmbedder implements EmbeddingPort {
+  readonly dimensions = EMBEDDING_DIM;
+
+  async embed(texts: string[]): Promise<number[][]> {
+    if (texts.length === 0) return [];
+
+    const provider = process.env["EMBEDDING_PROVIDER"] ?? process.env["AI_PROVIDER"] ?? "openrouter";
+    const modelId = process.env["EMBEDDING_MODEL"] ?? "text-embedding-3-small";
+
+    let baseURL: string;
+    let apiKey: string | undefined;
+
+    if (provider === "opencode" || provider === "openai-compatible") {
+      baseURL = process.env["OPENCODE_BASE_URL"] ?? "https://opencode.ai/zen/go/v1";
+      apiKey = process.env["OPENCODE_API_KEY"];
+    } else {
+      // openrouter or any other OpenAI-compatible provider
+      baseURL = process.env["OPENROUTER_BASE_URL"] ?? "https://openrouter.ai/api/v1";
+      apiKey = process.env["OPENROUTER_API_KEY"];
+    }
+
+    const oc = createOpenAICompatible({
+      name: `courtmitra-embedder-${provider}`,
+      baseURL,
+      apiKey,
+    });
+
+    try {
+      const result = await embedMany({
+        model: oc.textEmbeddingModel(modelId),
+        values: texts,
+      });
+
+      return result.embeddings;
+    } catch (err) {
+      throw new EmbeddingError(
+        `OpenAiCompatibleEmbedder (provider="${provider}", model="${modelId}", baseURL="${baseURL}") failed to embed ${texts.length} text(s). ` +
+          `Check that the provider supports embedding and the model exists. ` +
+          `Original error: ${err instanceof Error ? err.message : String(err)}`,
+        err,
+      );
+    }
+  }
+}
+
+/** Factory: creates an OpenAiCompatibleEmbedder. Call once at app startup. */
+export function createOpenAiCompatibleEmbedder(): EmbeddingPort {
+  return new OpenAiCompatibleEmbedder();
+}

packages/adapters/src/index.ts

@@ -3,6 +3,19 @@ import type { AdapterCapability } from "@courtmitra/contracts";
 // ---- LLM ----------------------------------------------------------------
 export { createVercelAiLlm, VercelAiLlmAdapter } from "./llm/vercel-ai.js";
 
+// ---- Embedder -----------------------------------------------------------
+export {
+  createOpenAiCompatibleEmbedder,
+  OpenAiCompatibleEmbedder,
+} from "./embedder/openai-compatible.js";
+
+// ---- Legal retrieval ----------------------------------------------------
+export {
+  createPgvectorFtsLegalRetrieval,
+  PgvectorFtsLegalRetrieval,
+  normaliseText,
+} from "./legal/pgvector-fts.js";
+
 // ---- Evidence parser ----------------------------------------------------
 export { createVisionLlmEvidenceParser, VisionLlmEvidenceParser } from "./parser/vision-llm.js";
 
@@ -36,6 +49,8 @@ export function getCapabilities(): AdapterCapability[] {
   const waPhoneId = process.env["WHATSAPP_PHONE_NUMBER_ID"];
   const openrouterKey = process.env["OPENROUTER_API_KEY"];
   const opencodeKey = process.env["OPENCODE_API_KEY"];
+  const embeddingProvider = process.env["EMBEDDING_PROVIDER"] ?? process.env["AI_PROVIDER"] ?? "openrouter";
+  const embeddingKeyAvailable = embeddingProvider === "opencode" ? !!opencodeKey : !!openrouterKey;
 
   const CAPABILITY_REGISTRY: AdapterCapability[] = [
     {
@@ -70,6 +85,16 @@ export function getCapabilities(): AdapterCapability[] {
       requiredEnv: ["OPENCODE_API_KEY"],
       fallbackAction: "draft",
     },
+    {
+      adapter: "openai_compatible_embedder",
+      action: "embed",
+      status: embeddingKeyAvailable ? "available" : "blocked",
+      reason: embeddingKeyAvailable
+        ? undefined
+        : `Embedding API key not set for provider "${embeddingProvider}".`,
+      requiredEnv: embeddingProvider === "opencode" ? ["OPENCODE_API_KEY"] : ["OPENROUTER_API_KEY"],
+      fallbackAction: "none",
+    },
     {
       adapter: "resend_email",
       action: "send_email",

packages/adapters/src/legal/pgvector-fts.ts

@@ -0,0 +1,350 @@
+/**
+ * LegalRetrievalPort implementation using pgvector ANN search + Postgres FTS,
+ * fused with Reciprocal Rank Fusion (RRF).
+ *
+ * Architecture notes (CLAUDE.md invariants):
+ * - Invariant #4: verifyClaimSupport does a LITERAL substring match after
+ *   whitespace normalisation. No LLM involved. A claim is only "supported" if
+ *   EVERY quoteSpan is a literal substring of at least one cited chunk's text.
+ * - No framework imports (hexagonal boundary — adapters only).
+ * - DB writes (legal_retrieval_logs, legal_claim_verifications) are best-effort;
+ *   errors are logged but never surface to the caller.
+ */
+import { sql, inArray } from "drizzle-orm";
+import type { EmbeddingPort, LegalRetrievalPort, LegalQuery, RetrievedLegalSource, ClaimSupportCheck, ClaimSupportResult } from "@courtmitra/ports";
+import type { Database } from "@courtmitra/db";
+import { schema } from "@courtmitra/db";
+
+// ---------------------------------------------------------------------------
+// Normalisation helper (pure, exported for unit testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise text for quote-span substring matching:
+ *   - Collapse all whitespace sequences (spaces, tabs, newlines, \r) to a
+ *     single ASCII space.
+ *   - Trim leading/trailing whitespace.
+ */
+export function normaliseText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+// ---------------------------------------------------------------------------
+// RRF scoring
+// ---------------------------------------------------------------------------
+
+interface RrfEntry {
+  chunkId: string;
+  sourceId: string;
+  actName: string | null;
+  sectionNo: string | null;
+  heading: string | null;
+  text: string;
+  tier: string | null;
+  score: number;
+}
+
+function rrfScore(rank: number, k = 60): number {
+  return 1 / (k + rank + 1); // rank is 0-based
+}
+
+// ---------------------------------------------------------------------------
+// PgvectorFtsLegalRetrieval
+// ---------------------------------------------------------------------------
+
+export class PgvectorFtsLegalRetrieval implements LegalRetrievalPort {
+  constructor(
+    private readonly db: Database,
+    private readonly embedder: EmbeddingPort,
+  ) {}
+
+  async retrieve(q: LegalQuery): Promise<RetrievedLegalSource[]> {
+    const topK = q.topK ?? 8;
+    const fetchK = topK * 3;
+
+    // 1. Embed query — tolerate embedder unavailability (e.g. provider has no
+    //    embedding endpoint). On failure we degrade to FTS-only retrieval
+    //    (CLAUDE.md: never fake success — log honestly, return what we have).
+    let queryEmbedding: number[] | null = null;
+    try {
+      const embeddings = await this.embedder.embed([q.query]);
+      queryEmbedding = embeddings[0] ?? null;
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[LegalRetrieval] Embedder unavailable — falling back to FTS-only. ${
+          (err as Error).message
+        }`,
+      );
+      queryEmbedding = null;
+    }
+
+    const embeddingLiteral = queryEmbedding ? `[${queryEmbedding.join(",")}]` : null;
+
+    // 2. Run vector + FTS queries in parallel (raw SQL — drizzle pgvector
+    //    support requires the vector operator we already have in the schema).
+    const vectorQuery = embeddingLiteral
+      ? this.db.execute<{
+          id: string;
+          source_id: string;
+          act_name: string | null;
+          section_no: string | null;
+          heading: string | null;
+          text: string;
+          tier: string | null;
+          distance: number;
+        }>(sql`
+          SELECT
+            lc.id,
+            lc.source_id,
+            lc.act_name,
+            lc.section_no,
+            lc.heading,
+            lc.text,
+            ls.tier,
+            (lc.embedding <=> ${embeddingLiteral}::vector) AS distance
+          FROM legal_chunks lc
+          JOIN legal_sources ls ON ls.id = lc.source_id
+          WHERE lc.embedding IS NOT NULL
+            AND (ls.jurisdiction = 'IN' OR ls.jurisdiction IS NULL)
+            ${q.issueDomain
+              ? sql`AND (lc.metadata->>'issue_domain' IS NULL OR lc.metadata->>'issue_domain' = ${q.issueDomain})`
+              : sql``}
+          ORDER BY lc.embedding <=> ${embeddingLiteral}::vector
+          LIMIT ${fetchK}
+        `)
+      : Promise.resolve({ rows: [] as Array<{
+          id: string;
+          source_id: string;
+          act_name: string | null;
+          section_no: string | null;
+          heading: string | null;
+          text: string;
+          tier: string | null;
+          distance: number;
+        }> });
+
+    const [vectorRows, ftsRows] = await Promise.all([
+      vectorQuery,
+      this.db.execute<{
+        id: string;
+        source_id: string;
+        act_name: string | null;
+        section_no: string | null;
+        heading: string | null;
+        text: string;
+        tier: string | null;
+        rank: number;
+      }>(sql`
+        SELECT
+          lc.id,
+          lc.source_id,
+          lc.act_name,
+          lc.section_no,
+          lc.heading,
+          lc.text,
+          ls.tier,
+          ts_rank(lc.text_tsv, plainto_tsquery('english', ${q.query})) AS rank
+        FROM legal_chunks lc
+        JOIN legal_sources ls ON ls.id = lc.source_id
+        WHERE lc.text_tsv @@ plainto_tsquery('english', ${q.query})
+          AND (ls.jurisdiction = 'IN' OR ls.jurisdiction IS NULL)
+          ${q.issueDomain
+            ? sql`AND (lc.metadata->>'issue_domain' IS NULL OR lc.metadata->>'issue_domain' = ${q.issueDomain})`
+            : sql``}
+        ORDER BY rank DESC
+        LIMIT ${fetchK}
+      `),
+    ]);
+
+    // 3. Build RRF map
+    const rrfMap = new Map<string, RrfEntry>();
+
+    const vectorResult = Array.isArray(vectorRows) ? vectorRows : vectorRows.rows ?? [];
+    const ftsResult = Array.isArray(ftsRows) ? ftsRows : ftsRows.rows ?? [];
+
+    vectorResult.forEach((row, idx) => {
+      const entry: RrfEntry = {
+        chunkId: row.id,
+        sourceId: row.source_id,
+        actName: row.act_name,
+        sectionNo: row.section_no,
+        heading: row.heading,
+        text: row.text,
+        tier: row.tier,
+        score: rrfScore(idx),
+      };
+      rrfMap.set(row.id, entry);
+    });
+
+    ftsResult.forEach((row, idx) => {
+      const existing = rrfMap.get(row.id);
+      if (existing) {
+        existing.score += rrfScore(idx);
+      } else {
+        rrfMap.set(row.id, {
+          chunkId: row.id,
+          sourceId: row.source_id,
+          actName: row.act_name,
+          sectionNo: row.section_no,
+          heading: row.heading,
+          text: row.text,
+          tier: row.tier,
+          score: rrfScore(idx),
+        });
+      }
+    });
+
+    // 4. Sort by RRF score descending, take topK
+    const sorted = [...rrfMap.values()].sort((a, b) => b.score - a.score).slice(0, topK);
+
+    const results: RetrievedLegalSource[] = sorted.map((e) => ({
+      chunkId: e.chunkId,
+      sourceId: e.sourceId,
+      actName: e.actName,
+      sectionNo: e.sectionNo,
+      heading: e.heading,
+      text: e.text,
+      score: e.score,
+    }));
+
+    // 5. Write retrieval log (best-effort)
+    try {
+      await this.db.insert(schema.legalRetrievalLogs).values({
+        missionId: q.missionId,
+        query: q.query,
+        retrievedChunkIds: vectorResult.map((r) => r.id),
+        rerankedChunkIds: sorted.map((e) => e.chunkId),
+        scores: Object.fromEntries(sorted.map((e) => [e.chunkId, e.score])),
+        modelVersions: {
+          embeddingModel: process.env["EMBEDDING_MODEL"] ?? "text-embedding-3-small",
+          embeddingDimensions: this.embedder.dimensions,
+        },
+      });
+    } catch (logErr) {
+      // Best-effort — never fail a retrieval due to logging
+      console.warn("[LegalRetrieval] Failed to write retrieval log:", logErr);
+    }
+
+    return results;
+  }
+
+  // -------------------------------------------------------------------------
+  // verifyClaimSupport — INVARIANT #4 (CLAUDE.md)
+  // -------------------------------------------------------------------------
+
+  async verifyClaimSupport(i: ClaimSupportCheck): Promise<ClaimSupportResult> {
+    const { missionId, claim, quoteSpans, chunkIds } = i;
+
+    // Empty chunkIds → immediately unsupported
+    if (chunkIds.length === 0) {
+      const result: ClaimSupportResult = {
+        supported: false,
+        supportLevel: "unsupported",
+        citedChunkIds: [],
+        failureReason: "No cited chunk IDs provided.",
+      };
+      await this._persistVerification(missionId, claim, chunkIds, quoteSpans, result);
+      return result;
+    }
+
+    // Fetch candidate chunks from DB
+    const chunks = await this.db
+      .select({
+        id: schema.legalChunks.id,
+        text: schema.legalChunks.text,
+        tier: schema.legalSources.tier,
+      })
+      .from(schema.legalChunks)
+      .innerJoin(schema.legalSources, sql`${schema.legalSources.id} = ${schema.legalChunks.sourceId}`)
+      .where(inArray(schema.legalChunks.id, chunkIds));
+
+    if (chunks.length === 0) {
+      const result: ClaimSupportResult = {
+        supported: false,
+        supportLevel: "unsupported",
+        citedChunkIds: [],
+        failureReason: "None of the cited chunk IDs were found in the database.",
+      };
+      await this._persistVerification(missionId, claim, chunkIds, quoteSpans, result);
+      return result;
+    }
+
+    // Pre-normalise all chunk texts once
+    const normalisedChunks = chunks.map((c) => ({
+      id: c.id,
+      normText: normaliseText(c.text),
+      tier: c.tier ?? "tier3",
+    }));
+
+    // Check each quoteSpan: it must be a literal substring of at least one chunk
+    let failureReason: string | null = null;
+    for (const span of quoteSpans) {
+      const normSpan = normaliseText(span);
+      const found = normalisedChunks.some((c) => c.normText.includes(normSpan));
+      if (!found) {
+        failureReason =
+          `Quote span "${span}" not found in any cited chunk after whitespace normalisation.`;
+        break;
+      }
+    }
+
+    const supported = failureReason === null && quoteSpans.length > 0;
+
+    // Determine support level from tiers of cited chunks
+    let supportLevel: ClaimSupportResult["supportLevel"] = "unsupported";
+    if (supported) {
+      const tiers = normalisedChunks.map((c) => c.tier);
+      if (tiers.includes("tier1")) {
+        supportLevel = "direct";
+      } else if (tiers.includes("tier2")) {
+        supportLevel = "supportive";
+      } else {
+        supportLevel = "weak";
+      }
+    }
+
+    const result: ClaimSupportResult = {
+      supported,
+      supportLevel,
+      citedChunkIds: chunks.map((c) => c.id),
+      failureReason,
+    };
+
+    await this._persistVerification(missionId, claim, chunkIds, quoteSpans, result);
+    return result;
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  private async _persistVerification(
+    missionId: string,
+    claim: string,
+    chunkIds: string[],
+    quoteSpans: string[],
+    result: ClaimSupportResult,
+  ): Promise<void> {
+    try {
+      await this.db.insert(schema.legalClaimVerifications).values({
+        missionId,
+        claim,
+        supported: result.supported,
+        citedChunkIds: result.citedChunkIds,
+        quoteSpans: quoteSpans,
+        failureReason: result.failureReason,
+      });
+    } catch (persistErr) {
+      console.warn("[LegalRetrieval] Failed to persist claim verification:", persistErr);
+    }
+  }
+}
+
+/** Factory: creates a PgvectorFtsLegalRetrieval adapter. */
+export function createPgvectorFtsLegalRetrieval(
+  db: Database,
+  embedder: EmbeddingPort,
+): LegalRetrievalPort {
+  return new PgvectorFtsLegalRetrieval(db, embedder);
+}

packages/contracts/src/__tests__/contracts.test.ts

@@ -5,6 +5,8 @@ import {
   ProofState,
   ConsentPreview,
   AdapterCapability,
+  RoutePlanDto,
+  RoutePlanGenerationResult,
 } from "../index.js";
 
 describe("mission contracts", () => {
@@ -40,6 +42,171 @@ describe("canonical enums", () => {
   });
 });
 
+describe("RoutePlanDto contract", () => {
+  const validChunkId = "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11";
+  const validSourceId = "b0eebc99-9c0b-4ef8-bb6d-6bb9bd380a22";
+  const validMissionId = "c0eebc99-9c0b-4ef8-bb6d-6bb9bd380a33";
+
+  const validStep = {
+    stepNo: 0,
+    level: "L0",
+    title: "Send formal complaint",
+    description: "Draft and send a formal complaint to the company.",
+    authority: "Company Grievance Cell",
+    channel: "email",
+    actionType: "send_email",
+    requiredEvidence: ["Order confirmation", "Payment receipt"],
+    deadlineDays: 15,
+    citations: [],
+    riskLevel: "low",
+  };
+
+  const validCitation = {
+    chunkId: validChunkId,
+    sourceId: validSourceId,
+    actName: "Consumer Protection Act, 2019",
+    sectionNo: "2(7)",
+    heading: "Definition of consumer",
+    canonicalUrl: "https://consumeraffairs.nic.in/acts",
+    tier: "tier1",
+    quote: "any person who buys any goods for a consideration",
+  };
+
+  it("parses a valid RoutePlanDto with steps and claims", () => {
+    const dto = RoutePlanDto.parse({
+      missionId: validMissionId,
+      issueDomain: "consumer",
+      summary: "Recommended route for consumer complaint against e-commerce platform.",
+      steps: [validStep],
+      claims: [
+        {
+          claim: "A consumer is any person who buys any goods for a consideration.",
+          citations: [validCitation],
+          supportLevel: "direct",
+          confidence: 0.95,
+        },
+      ],
+      riskNotes: ["Company may take up to 30 days to respond."],
+      expectedTimelineDays: 45,
+      confidence: 0.85,
+      routeRuleId: null,
+    });
+
+    expect(dto.missionId).toBe(validMissionId);
+    expect(dto.steps).toHaveLength(1);
+    expect(dto.claims).toHaveLength(1);
+    expect(dto.claims[0]!.citations[0]!.tier).toBe("tier1");
+  });
+
+  it("parses a RoutePlanDto with zero claims (neutral guidance fallback)", () => {
+    const dto = RoutePlanDto.parse({
+      missionId: validMissionId,
+      issueDomain: "payment",
+      summary: "Neutral guidance route for payment dispute.",
+      steps: [{ ...validStep, citations: [], level: "L1", channel: "portal" }],
+      claims: [],
+      riskNotes: [],
+      expectedTimelineDays: null,
+      confidence: 0.3,
+      routeRuleId: null,
+    });
+
+    expect(dto.claims).toHaveLength(0);
+    expect(dto.confidence).toBe(0.3);
+    expect(dto.expectedTimelineDays).toBeNull();
+  });
+
+  it("rejects RoutePlanDto with no steps", () => {
+    expect(() =>
+      RoutePlanDto.parse({
+        missionId: validMissionId,
+        issueDomain: "consumer",
+        summary: "Summary",
+        steps: [], // must have at least 1
+        claims: [],
+        riskNotes: [],
+        expectedTimelineDays: null,
+        confidence: 0.5,
+        routeRuleId: null,
+      }),
+    ).toThrow();
+  });
+
+  it("rejects RoutePlanDto with invalid issueDomain", () => {
+    expect(() =>
+      RoutePlanDto.parse({
+        missionId: validMissionId,
+        issueDomain: "tax", // not in enum
+        summary: "Summary",
+        steps: [validStep],
+        claims: [],
+        riskNotes: [],
+        expectedTimelineDays: null,
+        confidence: 0.5,
+        routeRuleId: null,
+      }),
+    ).toThrow();
+  });
+
+  it("rejects a citation with empty quote", () => {
+    expect(() =>
+      RoutePlanDto.parse({
+        missionId: validMissionId,
+        issueDomain: "consumer",
+        summary: "Summary",
+        steps: [validStep],
+        claims: [
+          {
+            claim: "Some claim.",
+            citations: [{ ...validCitation, quote: "" }], // quote must be min(1)
+            supportLevel: "direct",
+            confidence: 0.8,
+          },
+        ],
+        riskNotes: [],
+        expectedTimelineDays: null,
+        confidence: 0.8,
+        routeRuleId: null,
+      }),
+    ).toThrow();
+  });
+
+  it("RoutePlanGenerationResult round-trips correctly", () => {
+    const raw = RoutePlanGenerationResult.parse({
+      summary: "Generated summary",
+      steps: [
+        {
+          stepNo: 0,
+          level: "L0",
+          title: "Step title",
+          description: "Step description",
+          authority: null,
+          channel: "email",
+          actionType: "send_email",
+          requiredEvidence: [],
+          deadlineDays: null,
+          claimRefs: [0],
+          riskLevel: "low",
+        },
+      ],
+      claims: [
+        {
+          claim: "Test claim.",
+          quoteSpans: ["any goods for a consideration"],
+          chunkIds: [validChunkId],
+          confidence: 0.9,
+        },
+      ],
+      riskNotes: [],
+      expectedTimelineDays: 30,
+    });
+
+    expect(raw.claims[0]!.quoteSpans).toHaveLength(1);
+    expect(raw.steps[0]!.claimRefs).toEqual([0]);
+    expect(raw.expectedTimelineDays).toBe(30);
+  });
+});
+
 describe("consent + capability contracts", () => {
   it("parses a consent preview", () => {
     const preview = ConsentPreview.parse({

packages/contracts/src/index.ts

@@ -5,3 +5,4 @@ export * from "./action.js";
 export * from "./capability.js";
 export * from "./intake.js";
 export * from "./evidence.js";
+export * from "./legal.js";

packages/contracts/src/legal.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { IssueDomain, LegalSupportLevel, LegalTier, RiskLevel } from "./enums.js";
+
+/**
+ * LegalCitationDto — pointer to a curated legal_chunks row plus the literal
+ * quote span that supports a claim. CLAUDE.md #4: a claim may only cite a
+ * chunk if `quote` is a literal substring of chunk.text.
+ */
+export const LegalCitationDto = z.object({
+  chunkId: z.string().uuid(),
+  sourceId: z.string().uuid(),
+  actName: z.string().nullable(),
+  sectionNo: z.string().nullable(),
+  heading: z.string().nullable(),
+  canonicalUrl: z.string().nullable(),
+  tier: LegalTier,
+  quote: z.string().min(1),
+});
+export type LegalCitationDto = z.infer<typeof LegalCitationDto>;
+
+/**
+ * GroundedClaimDto — a single legal/procedural claim with its supporting
+ * citations + support level. Produced by the LLM, then filtered through the
+ * literal-quote-span verifier (LegalRetrievalPort.verifyClaimSupport).
+ */
+export const GroundedClaimDto = z.object({
+  claim: z.string().min(1),
+  citations: z.array(LegalCitationDto),
+  supportLevel: LegalSupportLevel,
+  confidence: z.number().min(0).max(1),
+});
+export type GroundedClaimDto = z.infer<typeof GroundedClaimDto>;
+
+/**
+ * RoutePlanStepDto — one node in the route_graph (L0 informal → L1 regulator
+ * complaint → L2 ombudsman → L3 consumer commission, etc.). Each step lists
+ * the authority, channel, required evidence, deadline windows in calendar
+ * days, and any cited grounded claims.
+ */
+export const RoutePlanStepDto = z.object({
+  stepNo: z.number().int().min(0),
+  level: z.string(), // L0 | L1 | L2 | L3 | L4
+  title: z.string(),
+  description: z.string(),
+  authority: z.string().nullable(),
+  channel: z.enum(["email", "portal", "phone", "in_person", "social", "self_service"]),
+  actionType: z.string(), // matches ActionType enum at execute time
+  requiredEvidence: z.array(z.string()),
+  deadlineDays: z.number().int().nullable(),
+  citations: z.array(LegalCitationDto),
+  riskLevel: RiskLevel,
+});
+export type RoutePlanStepDto = z.infer<typeof RoutePlanStepDto>;
+
+/**
+ * RoutePlanDto — full plan persisted in route_plans. `claims` are grounded
+ * claims that survived verifier gating. `confidence` aggregates per-claim
+ * confidence and retrieval signal strength.
+ */
+export const RoutePlanDto = z.object({
+  missionId: z.string().uuid(),
+  issueDomain: IssueDomain,
+  summary: z.string(),
+  steps: z.array(RoutePlanStepDto).min(1),
+  claims: z.array(GroundedClaimDto),
+  riskNotes: z.array(z.string()),
+  expectedTimelineDays: z.number().int().nullable(),
+  confidence: z.number().min(0).max(1),
+  routeRuleId: z.string().uuid().nullable(),
+});
+export type RoutePlanDto = z.infer<typeof RoutePlanDto>;
+
+/**
+ * RoutePlanGenerationResult — raw LLM output shape (pre-verification). The
+ * worker calls verifyClaimSupport on each claim; only claims whose quote
+ * spans literally appear in chunk.text are kept. Failed claims are dropped
+ * or downgraded to neutral admin language (PHASE_1 §11).
+ */
+export const RoutePlanGenerationResult = z.object({
+  summary: z.string(),
+  steps: z.array(
+    z.object({
+      stepNo: z.number().int().min(0),
+      level: z.string(),
+      title: z.string(),
+      description: z.string(),
+      authority: z.string().nullable(),
+      channel: z.enum(["email", "portal", "phone", "in_person", "social", "self_service"]),
+      actionType: z.string(),
+      requiredEvidence: z.array(z.string()),
+      deadlineDays: z.number().int().nullable(),
+      claimRefs: z.array(z.number().int().min(0)), // indexes into claims[]
+      riskLevel: RiskLevel,
+    }),
+  ).min(1),
+  claims: z.array(
+    z.object({
+      claim: z.string().min(1),
+      quoteSpans: z.array(z.string().min(1)).min(1),
+      chunkIds: z.array(z.string().uuid()).min(1),
+      confidence: z.number().min(0).max(1),
+    }),
+  ),
+  riskNotes: z.array(z.string()),
+  expectedTimelineDays: z.number().int().nullable(),
+});
+export type RoutePlanGenerationResult = z.infer<typeof RoutePlanGenerationResult>;

packages/db/package.json

@@ -14,7 +14,7 @@
     "build": "tsc --noEmit",
     "generate": "drizzle-kit generate",
     "migrate": "tsx src/migrate.ts",
-    "seed": "tsx src/seeds/index.ts",
+    "seed": "tsx src/seeds/run.ts",
     "studio": "drizzle-kit studio"
   },
   "dependencies": {

packages/db/src/migrate.ts

@@ -2,11 +2,31 @@ import { drizzle } from "drizzle-orm/node-postgres";
 import { migrate } from "drizzle-orm/node-postgres/migrator";
 import { sql } from "drizzle-orm";
 import { Pool } from "pg";
+import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+// Auto-load infra/.env if DATABASE_URL is not already set.
+if (!process.env["DATABASE_URL"]) {
+  const envPath = resolve(__dirname, "../../../infra/.env");
+  try {
+    const raw = readFileSync(envPath, "utf8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const eqIdx = trimmed.indexOf("=");
+      if (eqIdx === -1) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      const val = trimmed.slice(eqIdx + 1).trim();
+      if (!process.env[key]) process.env[key] = val;
+    }
+  } catch {
+    // Env not found — will fail below with a clear error message.
+  }
+}
+
 async function main() {
   const connectionString = process.env.DATABASE_URL;
   if (!connectionString) throw new Error("DATABASE_URL is not set");

packages/db/src/migrations/0002_legal_indexes.sql

@@ -0,0 +1,17 @@
+-- Day 3: Legal Grounding indexes.
+-- Idempotent extension setup (CREATE EXTENSION IF NOT EXISTS).
+CREATE EXTENSION IF NOT EXISTS vector;
+--> statement-breakpoint
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+--> statement-breakpoint
+
+-- Generated tsvector column on legal_chunks for full-text search.
+ALTER TABLE "legal_chunks" ADD COLUMN "text_tsv" tsvector GENERATED ALWAYS AS (to_tsvector('english', coalesce(text, ''))) STORED;
+--> statement-breakpoint
+
+-- GIN index on tsvector column for FTS.
+CREATE INDEX "legal_chunks_tsv_idx" ON "legal_chunks" USING gin ("text_tsv");
+--> statement-breakpoint
+
+-- IVFFlat cosine index on embedding column for ANN vector search.
+CREATE INDEX "legal_chunks_embedding_idx" ON "legal_chunks" USING ivfflat ("embedding" vector_cosine_ops) WITH (lists = 100);

packages/db/src/migrations/meta/_journal.json

@@ -15,6 +15,13 @@
       "when": 1779905118666,
       "tag": "0001_motionless_skrulls",
       "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1779906000000,
+      "tag": "0002_legal_indexes",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema.ts

@@ -12,7 +12,16 @@ import {
   vector,
   uniqueIndex,
   index,
+  customType,
 } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+/** tsvector DB-only column type (Drizzle has no built-in; we use customType). */
+const tsvector = customType<{ data: string }>({
+  dataType() {
+    return "tsvector";
+  },
+});
 
 /**
  * Phase 1 schema (PHASE_1 §5, arch §9 + §30). Enums are stored as `text`; the
@@ -342,10 +351,22 @@ export const legalChunks = pgTable(
     pageStart: integer("page_start"),
     pageEnd: integer("page_end"),
     embedding: vector("embedding", { dimensions: EMBEDDING_DIM }),
+    /**
+     * DB-generated tsvector for FTS — populated via GENERATED ALWAYS AS
+     * (see migration 0002_legal_indexes.sql). Drizzle treats this as a
+     * read-only column; writes are handled by Postgres.
+     */
+    textTsv: tsvector("text_tsv").generatedAlwaysAs(
+      sql`to_tsvector('english', coalesce(text, ''))`,
+    ),
     metadata: jsonb("metadata"),
     createdAt: createdAt(),
   },
-  (t) => [index("legal_chunks_source_idx").on(t.sourceId)],
+  (t) => [
+    index("legal_chunks_source_idx").on(t.sourceId),
+    index("legal_chunks_tsv_idx").using("gin", t.textTsv),
+    index("legal_chunks_embedding_idx").using("ivfflat", t.embedding.op("vector_cosine_ops")),
+  ],
 );
 
 export const legalRetrievalLogs = pgTable("legal_retrieval_logs", {

packages/db/src/seeds/legal-data.ts

@@ -0,0 +1,548 @@
+/**
+ * Curated Indian-law seed data for CourtMitra MissionOS Phase 1 legal grounding.
+ * Sources: Consumer Protection Act 2019, E-Commerce Rules 2020, RBI IOS 2021,
+ *          RBI Customer Liability Circular 2017, NPCI UPI Guidelines,
+ *          IT Act 2000, Bharatiya Nyaya Sanhita 2023, MHA Cybercrime.
+ *
+ * Text excerpts are verbatim short passages from publicly published Indian statutes
+ * (fair-use / public domain). Each chunk must be substantive (2–6 sentences).
+ */
+
+export interface SourceSeedData {
+  sourceType: string;
+  title: string;
+  tier: string;
+  jurisdiction: string;
+  authority: string;
+  canonicalUrl: string;
+  versionLabel: string;
+  effectiveFrom: string; // ISO date string
+  metadata: Record<string, string>;
+}
+
+export interface ChunkSeedData {
+  chunkNo: number;
+  actName: string;
+  sectionNo: string;
+  heading: string;
+  text: string;
+  metadata: Record<string, string>;
+}
+
+export interface LegalSeedEntry {
+  source: SourceSeedData;
+  chunks: ChunkSeedData[];
+}
+
+// ============================================================================
+// CONSUMER DOMAIN
+// ============================================================================
+
+const consumerProtectionAct2019: LegalSeedEntry = {
+  source: {
+    sourceType: "act",
+    title: "Consumer Protection Act, 2019",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Department of Consumer Affairs",
+    canonicalUrl:
+      "https://consumeraffairs.nic.in/sites/default/files/CP-Act-2019.pdf",
+    versionLabel: "2019 (as enacted)",
+    effectiveFrom: "2019-07-20",
+    metadata: { issue_domain: "consumer" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "2(7)",
+      heading: "Definition of Consumer",
+      text: 'Section 2(7): "consumer" means any person who— (i) buys any goods for a consideration which has been paid or promised or partly paid and partly promised, or under any system of deferred payment and includes any user of such goods other than the person who buys such goods for consideration paid or promised or partly paid or partly promised, or under any system of deferred payment, when such use is made with the approval of such person, but does not include a person who obtains such goods for resale or for any commercial purpose; or (ii) hires or avails of any service for a consideration which has been paid or promised or partly paid and partly promised, or under any system of deferred payment and includes any beneficiary of such service other than the person who hires or avails of the service for consideration paid or promised, or partly paid and partly promised, or under any system of deferred payment, when such services are availed of with the approval of the first-mentioned person, but does not include a person who avails of such service for any commercial purpose. Explanation— For the purposes of this clause, "commercial purpose" does not include use by a person of goods bought and used by him and services availed by him exclusively for the purposes of earning his livelihood by means of self-employment.',
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 2,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "2(34)",
+      heading: "Definition of Service",
+      text: 'Section 2(34): "service" means service of any description which is made available to potential users and includes, but not limited to, the provision of facilities in connection with banking, financing, insurance, transport, processing, supply of electrical or other energy, telecom, boarding or lodging or both, housing construction, entertainment, amusement or the purveying of news or other information, but does not include the rendering of any service free of charge or under a contract of personal service.',
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 3,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "2(47)",
+      heading: "Definition of Unfair Trade Practice",
+      text: 'Section 2(47): "unfair trade practice" means a trade practice which, for the purpose of promoting the sale, use or supply of any goods or for the provision of any service, adopts any unfair method or unfair or deceptive practice including any of the following practices, namely:— (i) making any statement, whether orally or in writing or by visible representation including by means of electronic record, which— (a) falsely represents that the goods are of a particular standard, quality, quantity, grade, composition, style or model; (b) falsely represents that the services are of a particular standard, quality or grade. The practice of giving false or misleading facts disparaging the goods, services or trade of another person is also an unfair trade practice.',
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 4,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "17",
+      heading: "Establishment of Central Consumer Protection Authority (CCPA)",
+      text: "Section 17: The Central Government shall, by notification, establish with effect from such date as it may specify in that notification, a Central Consumer Protection Authority to be known as the Central Authority to regulate matters relating to violation of rights of consumers, unfair trade practices and false or misleading advertisements which are prejudicial to the interests of public and consumers and to promote, protect and enforce the rights of consumers as a class.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 5,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "18",
+      heading: "Functions of CCPA",
+      text: "Section 18: The Central Authority shall— (a) protect, promote and enforce the rights of consumers as a class, and prevent violation of consumers' rights under this Act; (b) prevent unfair trade practices and ensure that no person engages himself in unfair trade practices; (c) ensure that no false or misleading advertisement is made of any goods or services which contravenes the provisions of this Act or the rules or regulations made thereunder; (d) ensure that no person takes part in the publication of any advertisement which is false or misleading. The Central Authority shall, for the purpose of preventing, investigating and taking action against the violation of consumer rights, unfair trade practices and false or misleading advertisements, have the power to inquire or cause an inquiry or investigation to be made into such matters.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 6,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "19",
+      heading: "Complaint to CCPA",
+      text: "Section 19: Any person, consumer, or registered voluntary consumer association may file a complaint before the Central Authority in relation to violation of consumer rights, unfair trade practices, or false or misleading advertisements prejudicial to the interest of consumers. The Central Authority may, on receipt of such complaint, make or cause to be made a preliminary inquiry as to whether the complaint requires further investigation and may pass such orders as it deems fit, including directing the manufacturer, seller, service provider, or advertiser to discontinue the unfair trade practice or misleading advertisement.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 7,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "35",
+      heading: "Complaint to District Consumer Disputes Redressal Commission",
+      text: "Section 35: A complaint in relation to any goods sold or delivered or agreed to be sold or delivered or any service provided or agreed to be provided may be filed with a District Commission by— (a) the consumer to whom such goods are sold or delivered or agreed to be sold or delivered or such service is provided or agreed to be provided; (b) any recognised consumer association, whether the consumer to whom the goods are sold or delivered or agreed to be sold or delivered or service is provided or agreed to be provided is a member of such association or not; (c) one or more consumers, where there are numerous consumers having the same interest, with the permission of the District Commission; (d) the Central Authority or the State Authority, as the case may be.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 8,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "38",
+      heading: "Procedure on Admission of Complaint",
+      text: "Section 38: The District Commission shall, on admission of a complaint, if it relates to goods in respect of which the procedure specified in section 38(2) is applicable, refer a copy of the admitted complaint, within twenty-one days from the date of its admission to the opposite party, directing him to give his version of the case within a period of thirty days or such extended period not exceeding fifteen days as may be granted by the District Commission. If the opposite party, on receipt of a copy of the complaint, denies or disputes the allegations contained in the complaint, or omits or fails to take any action to represent his case within the time given, the District Commission shall proceed to settle the consumer dispute.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 9,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "39",
+      heading: "Findings of District Commission",
+      text: "Section 39(1): If, after the proceeding conducted under section 38, the District Commission is satisfied that the goods complained against suffer from any of the defects specified in the complaint or that any of the allegations contained in the complaint about the services or any unfair trade practices or restrictive trade practices are proved, it shall issue an order to the opposite party directing him to do one or more of the following things, namely:— (a) to remove the defect pointed out by the appropriate laboratory from the goods in question; (b) to replace the goods with new goods of similar description which shall be free from any defect; (c) to return to the complainant the price, or, as the case may be, the charges paid by the complainant along with such interest on such price or charges as may be decided; (d) to pay such amount as may be awarded by it as compensation to the consumer for any loss or injury suffered by the consumer due to the negligence of the opposite party.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 10,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "47",
+      heading: "Jurisdiction of District Commission",
+      text: "Section 47(1): The District Commission shall have jurisdiction to entertain complaints where the value of the goods or services paid as consideration does not exceed one crore rupees. Provided that where the Central Government deems it necessary so to do, it may, by notification, enhance or reduce the limit of one crore rupees after giving wide publicity thereof and considering the interests of consumers.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 11,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "58",
+      heading: "Jurisdiction of State Commission",
+      text: "Section 58(1): The State Commission shall have jurisdiction— (a) to entertain complaints where the value of the goods or services paid as consideration exceeds one crore rupees but does not exceed ten crore rupees; (b) to entertain appeals against the orders of any District Commission within the State; (c) to call for the records and pass appropriate orders in any consumer dispute which is pending before or has been decided by any District Commission within the State in cases where it appears to the State Commission that such District Commission has exercised a jurisdiction not vested in it by law, or has failed to exercise a jurisdiction so vested, or has acted in the exercise of its jurisdiction illegally or with material irregularity.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 12,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "67",
+      heading: "Jurisdiction of National Commission",
+      text: "Section 67: The National Commission shall have jurisdiction— (a) to entertain complaints where the value of the goods or services paid as consideration exceeds ten crore rupees; (b) to entertain appeals against the orders of any State Commission; (c) to call for the records and pass appropriate orders in any consumer dispute which is pending before or has been decided by any State Commission where it appears to the National Commission that such State Commission has exercised a jurisdiction not vested in it by law, or has failed to exercise a jurisdiction so vested, or has acted in the exercise of its jurisdiction illegally or with material irregularity.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 13,
+      actName: "Consumer Protection Act, 2019",
+      sectionNo: "69",
+      heading: "Limitation Period for Filing Complaint",
+      text: "Section 69(1): The District Commission, the State Commission or the National Commission shall not admit a complaint unless it is filed within two years from the date on which the cause of action has arisen. Section 69(2): Notwithstanding anything contained in sub-section (1), a complaint may be entertained after the period specified in sub-section (1), if the complainant satisfies the District Commission, the State Commission or the National Commission, as the case may be, that he had sufficient cause for not filing the complaint within such period. Provided that no such complaint shall be entertained unless the District Commission, or the State Commission or the National Commission, as the case may be, records its reasons for condoning such delay.",
+      metadata: { issue_domain: "consumer" },
+    },
+  ],
+};
+
+const eCommerceRules2020: LegalSeedEntry = {
+  source: {
+    sourceType: "rule",
+    title: "Consumer Protection (E-Commerce) Rules, 2020",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Department of Consumer Affairs",
+    canonicalUrl:
+      "https://consumeraffairs.nic.in/sites/default/files/E-commerce%20%28Amendment%29%20Rules%2C%202021.pdf",
+    versionLabel: "2020 (amended 2021)",
+    effectiveFrom: "2020-07-23",
+    metadata: { issue_domain: "consumer" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "Consumer Protection (E-Commerce) Rules, 2020",
+      sectionNo: "4",
+      heading: "Duties of E-Commerce Entities",
+      text: "Rule 4(1): Every e-commerce entity shall— (a) display clearly on its platform the name, contact numbers, and designated grievance officer details; (b) acknowledge the receipt of any consumer complaint within forty-eight hours and redress the complaint within one month from the date of receipt of the complaint; (c) not adopt any unfair trade practice whether in the course of business on its platform or otherwise; (d) not falsely represent itself as a consumer and post reviews about its goods and services or misrepresent the quality or features of any goods or services.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 2,
+      actName: "Consumer Protection (E-Commerce) Rules, 2020",
+      sectionNo: "4(5)",
+      heading: "Grievance Officer Appointment Requirement",
+      text: "Rule 4(5): Every e-commerce entity shall establish an adequate grievance redressal mechanism having regard to the number of grievances ordinarily received by such entity from India, and shall appoint a grievance officer for consumer grievance redressal, and shall display the name of such officer and his contact details including email address on its platform, and such officer shall acknowledge the receipt of any consumer complaint within forty-eight hours and redress the complaint within one month from the date of receipt of the complaint.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 3,
+      actName: "Consumer Protection (E-Commerce) Rules, 2020",
+      sectionNo: "5",
+      heading: "Duties of Marketplace E-Commerce Entities",
+      text: "Rule 5(1): Every marketplace e-commerce entity shall— (a) require sellers through an undertaking to ensure that descriptions, images, and other content pertaining to goods or services on their platform is accurate and corresponds directly with the appearance, nature, quality, purpose and other general features of such goods or services; (b) provide a description of any seller on its platform who may be in a position to supply goods or provide services to consumers; (c) provide information relating to return, refund, exchange, warranty and guarantee, delivery and shipment, cost and method of payment, grievance redressal mechanism, and any other similar information which may be required by consumers; (d) provide sellers the facility to use a grievance redressal mechanism.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 4,
+      actName: "Consumer Protection (E-Commerce) Rules, 2020",
+      sectionNo: "6",
+      heading: "Duties of Inventory E-Commerce Entities",
+      text: "Rule 6(1): Every inventory e-commerce entity shall— (a) ensure that the advertisements for marketing of goods or services are consistent with the actual characteristics, access and usage conditions of such goods or services; (b) ensure that all information provided by it is accurate, true and sufficient to enable the consumer to make an informed decision at the pre-purchase stage; (c) ensure that the goods or services being offered on the platform are not prohibited for sale and do not infringe any intellectual property rights; (d) ensure the authenticity of the goods sold on its platform and confirm that goods purchased are delivered within the stipulated delivery period indicated at the time of purchase.",
+      metadata: { issue_domain: "consumer" },
+    },
+  ],
+};
+
+const nationalConsumerHelpline: LegalSeedEntry = {
+  source: {
+    sourceType: "govt_page",
+    title: "National Consumer Helpline – Grievance Filing Procedure",
+    tier: "tier2",
+    jurisdiction: "IN",
+    authority: "National Consumer Helpline",
+    canonicalUrl: "https://consumerhelpline.gov.in",
+    versionLabel: "current",
+    effectiveFrom: "2015-01-01",
+    metadata: { issue_domain: "consumer" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "National Consumer Helpline",
+      sectionNo: "procedure",
+      heading: "How to File a Grievance via National Consumer Helpline",
+      text: "Consumers can register complaints through the National Consumer Helpline (NCH) by calling the toll-free number 1915 (available in 17 languages, Monday–Saturday 8 AM–8 PM), or by visiting consumerhelpline.gov.in, or through the INGRAM portal (Integrated Grievance Redressal Mechanism). Complaints can also be submitted via the NCH mobile app available on Android and iOS platforms. The NCH mediates between consumers and companies and escalates unresolved complaints to the Consumer Commission or the appropriate regulator.",
+      metadata: { issue_domain: "consumer" },
+    },
+    {
+      chunkNo: 2,
+      actName: "National Consumer Helpline",
+      sectionNo: "ingram",
+      heading: "INGRAM Portal – Integrated Grievance Redressal Mechanism",
+      text: "The INGRAM (Integrated Grievance Redressal Mechanism) portal at consumerhelpline.gov.in allows consumers to file complaints online, track complaint status, and receive resolution from companies. Complaints are forwarded to the concerned company through the portal; companies registered on INGRAM are expected to respond within 30 days. Unresolved complaints on INGRAM can be escalated to the District Consumer Disputes Redressal Commission under the Consumer Protection Act, 2019.",
+      metadata: { issue_domain: "consumer" },
+    },
+  ],
+};
+
+// ============================================================================
+// PAYMENT DOMAIN
+// ============================================================================
+
+const rbiIntegratedOmbudsmanScheme2021: LegalSeedEntry = {
+  source: {
+    sourceType: "regulator_doc",
+    title: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Reserve Bank of India",
+    canonicalUrl:
+      "https://rbidocs.rbi.org.in/rdocs/content/pdfs/RBIOS2021_amendedWebsite.pdf",
+    versionLabel: "2021 (as amended)",
+    effectiveFrom: "2021-11-12",
+    metadata: { issue_domain: "payment" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "definitions",
+      heading: "Key Definitions",
+      text: "Under the RBI Integrated Ombudsman Scheme 2021: 'complaint' means a representation in writing or through electronic means containing a grievance, alleging deficiency in service on the part of a Regulated Entity; 'deficiency in service' means a failure to comply with applicable laws, regulations, and internal policies of a Regulated Entity; 'Regulated Entity' includes commercial banks, primary (urban) co-operative banks, non-banking financial companies, and payment system participants as notified by the Reserve Bank from time to time. The scheme provides a cost-free and expeditious alternate grievance redressal mechanism to customers of regulated entities.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 2,
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "clause-8",
+      heading: "Grounds for Filing Complaint Before Ombudsman",
+      text: "Clause 8 of the RBI IOS 2021: A complaint may be filed before the Ombudsman on any one or more of the following grounds of deficiency in service, namely: non-payment or inordinate delay in the payment or collection of cheques, drafts, bills, etc.; non-acceptance, without sufficient cause, of small denomination notes tendered for any purpose; failure to issue or delay in issuance of a draft, pay order or banker's cheque; non-adherence to prescribed working hours; failure to honour guarantee or letter of credit commitments; claims in respect of unauthorized electronic fund transfers, failure to act in accordance with a customer's mandate without justification; non-adherence to the provisions of the fair practices code as adopted by the bank.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 3,
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "clause-10",
+      heading: "Procedure for Filing Complaint – CMS Portal",
+      text: "Clause 10 of the RBI IOS 2021: A complainant may file a complaint through the Complaint Management System portal at cms.rbi.org.in, or at the Centralised Receipt and Processing Centre, or at the offices of the Ombudsman. Before filing a complaint with the Ombudsman, the complainant must first lodge a complaint with the concerned Regulated Entity and either receive a response which is not satisfactory, or not receive a response within 30 days of lodging the complaint. The complaint must be filed within one year from the date of the reply of the regulated entity or, if no reply, within one year and 30 days from the date of lodging the grievance with the regulated entity.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 4,
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "clause-10-pre-filing",
+      heading: "30-Day Pre-Filing Requirement",
+      text: "The RBI Integrated Ombudsman Scheme 2021 mandates that before approaching the Ombudsman at cms.rbi.org.in, the complainant must: (1) lodge a complaint with the Regulated Entity (bank, NBFC, payment system participant); (2) wait 30 days for a resolution; and (3) only approach the Ombudsman if the reply is unsatisfactory or no reply is received within 30 days. This pre-filing requirement ensures the institution has adequate opportunity to resolve the dispute internally before regulatory intervention.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 5,
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "award",
+      heading: "Ombudsman Award",
+      text: "The RBI Integrated Ombudsman Scheme 2021 provides that the Ombudsman may, after affording reasonable opportunity to the parties, pass an Award. The Award may direct the regulated entity to pay the complainant an amount found deficient and/or compensation for the loss suffered by the complainant, which shall not exceed Rupees Twenty Lakh (₹20,00,000) in aggregate per complaint. If a bank fails to implement the Award within the prescribed period, the RBI may take action under the applicable banking statutes.",
+      metadata: { issue_domain: "payment" },
+    },
+  ],
+};
+
+const rbiCustomerLiabilityCircular2017: LegalSeedEntry = {
+  source: {
+    sourceType: "regulator_doc",
+    title:
+      "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Reserve Bank of India",
+    canonicalUrl:
+      "https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=11040",
+    versionLabel: "DBR.No.Leg.BC.78/09.07.005/2017-18",
+    effectiveFrom: "2017-07-06",
+    metadata: { issue_domain: "payment" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "zero-liability",
+      heading: "Zero Liability for Unauthorised Transactions Reported Promptly",
+      text: "RBI Circular DBR.No.Leg.BC.78/09.07.005/2017-18: A customer shall have zero liability where the unauthorised transaction occurs in cases where the deficiency is on part of the bank (irrespective of whether or not the transaction is reported by the customer). In cases where the responsibility for the unauthorised electronic banking transaction lies neither with the bank nor with the customer, but lies elsewhere in the system, and the customer notifies the bank within three working days of receiving the communication from the bank regarding the unauthorised transaction, the customer shall have zero liability.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 2,
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "limited-liability",
+      heading: "Limited Liability for Delayed Reporting",
+      text: "RBI Circular DBR.No.Leg.BC.78/09.07.005/2017-18: If the delay in reporting is between 4 and 7 working days after receiving communication from the bank, the customer's maximum liability shall be the transaction value or the amount specified in the table (ranging from ₹5,000 to ₹25,000 depending on the type of account), whichever is lower. If the delay in reporting the unauthorised transaction is beyond 7 working days, the customer's liability shall be determined as per the bank's Board approved policy. Banks must credit (shadow reversal) the amount involved in the unauthorised electronic transaction to the customer's account within 10 working days from the date of notification by the customer.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 3,
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "customer-negligence",
+      heading: "Full Liability Where Customer is Negligent",
+      text: "RBI Circular DBR.No.Leg.BC.78/09.07.005/2017-18: In cases where the loss is due to negligence by a customer, such as where he has shared the payment credentials, the customer will bear the entire loss until he reports the unauthorised transaction to the bank. Any loss occurring after the reporting of the unauthorised transaction shall be borne by the bank. Banks shall immediately on receipt of the report from the customer, take all steps to prevent further unauthorised transactions in the account.",
+      metadata: { issue_domain: "payment" },
+    },
+  ],
+};
+
+const npciUpiGuidelines: LegalSeedEntry = {
+  source: {
+    sourceType: "regulator_doc",
+    title: "NPCI UPI Procedural Guidelines",
+    tier: "tier2",
+    jurisdiction: "IN",
+    authority: "National Payments Corporation of India (NPCI)",
+    canonicalUrl:
+      "https://www.npci.org.in/PDF/npci/upi/circular/2019/UPI-Procedural-Guidelines-Ver-1.6.pdf",
+    versionLabel: "Version 1.6",
+    effectiveFrom: "2019-01-01",
+    metadata: { issue_domain: "payment" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "NPCI UPI Procedural Guidelines",
+      sectionNo: "dispute-tat",
+      heading: "UPI Dispute Resolution Turnaround Time",
+      text: "NPCI UPI Procedural Guidelines v1.6: For failed UPI transactions where the customer's account has been debited but credit has not been received, the acquiring bank / PSP must resolve the dispute within T+1 working day (where T is the date of transaction or complaint). If the transaction cannot be reversed within T+1, the PSP must proactively communicate the status to the customer and ensure reversal within 5 working days. Persistent failure to reverse within the stipulated time may be escalated to NPCI or the concerned bank ombudsman.",
+      metadata: { issue_domain: "payment" },
+    },
+    {
+      chunkNo: 2,
+      actName: "NPCI UPI Procedural Guidelines",
+      sectionNo: "chargeback",
+      heading: "Chargeback Process via PSP",
+      text: "NPCI UPI Procedural Guidelines v1.6: A UPI chargeback (dispute) must be raised by the customer's PSP (Payment Service Provider) bank on behalf of the customer through the UPI dispute management system. Chargebacks can be raised in cases of: (i) goods/services not received; (ii) duplicate transaction; (iii) fraud or unauthorized transaction. The remitter's PSP has responsibility to initiate a chargeback dispute within 120 days of the original transaction date and must submit documentary evidence to the beneficiary PSP for resolution.",
+      metadata: { issue_domain: "payment" },
+    },
+  ],
+};
+
+// ============================================================================
+// CYBER FRAUD DOMAIN
+// ============================================================================
+
+const itAct2000: LegalSeedEntry = {
+  source: {
+    sourceType: "act",
+    title: "Information Technology Act, 2000",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Ministry of Electronics and Information Technology",
+    canonicalUrl:
+      "https://www.indiacode.nic.in/bitstream/123456789/13116/1/it_act_2000_updated.pdf",
+    versionLabel: "2000 (as amended 2008)",
+    effectiveFrom: "2000-10-17",
+    metadata: { issue_domain: "cyber_fraud" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "43",
+      heading: "Penalty for Damage to Computer, Computer System, etc.",
+      text: "Section 43 of the Information Technology Act, 2000: If any person without permission of the owner or any other person who is incharge of a computer, computer system or computer network— (a) accesses or secures access to such computer, computer system or computer network; (b) downloads, copies or extracts any data, computer data base or information from such computer, computer system or computer network; (c) introduces or causes to be introduced any computer contaminant or computer virus into any computer, computer system or computer network; (d) damages or causes to be damaged any computer, computer system or computer network, data, computer data base or any other programmes residing in such computer, computer system or computer network— he shall be liable to pay damages by way of compensation not exceeding one crore rupees to the person so affected.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 2,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "43A",
+      heading: "Compensation for Failure to Protect Data",
+      text: "Section 43A of the Information Technology Act, 2000: Where a body corporate, possessing, dealing or handling any sensitive personal data or information in a computer resource which it owns, controls or operates, is negligent in implementing and maintaining reasonable security practices and procedures and thereby causes wrongful loss or wrongful gain to any person, such body corporate shall be liable to pay damages by way of compensation to the person so affected. The Central Government shall prescribe the reasonable security practices and procedures and the type of sensitive personal data or information for the purposes of this section.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 3,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "66",
+      heading: "Computer-Related Offences",
+      text: "Section 66 of the Information Technology Act, 2000: If any person, dishonestly or fraudulently, does any act referred to in section 43, he shall be punishable with imprisonment for a term which may extend to three years or with fine which may extend to five lakh rupees or with both. The provisions of this section apply to all forms of computer-related offences including hacking, unauthorised access, data theft, introduction of malware, and disruption of computer systems or networks.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 4,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "66C",
+      heading: "Punishment for Identity Theft",
+      text: "Section 66C of the Information Technology Act, 2000: Whoever, fraudulently or dishonestly make use of the electronic signature, password or any other unique identification feature of any other person, shall be punished with imprisonment of either description for a term which may extend to three years and shall also be liable to fine which may extend to rupees one lakh. Identity theft under this section includes misuse of OTPs, digital credentials, SIM-swap fraud, and misuse of Aadhaar or PAN details to impersonate a person.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 5,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "66D",
+      heading: "Punishment for Cheating by Personation Using Computer Resource",
+      text: "Section 66D of the Information Technology Act, 2000: Whoever, by means of any communication device or computer resource cheats by personation, shall be punished with imprisonment of either description for a term which may extend to three years and shall also be liable to fine which may extend to one lakh rupees. This section specifically covers online impersonation, fake customer care fraud, phishing, vishing, smishing, and impersonation of banking officials or government officers through electronic means.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 6,
+      actName: "Information Technology Act, 2000",
+      sectionNo: "72A",
+      heading: "Punishment for Disclosure of Information in Breach of Lawful Contract",
+      text: "Section 72A of the Information Technology Act, 2000: Save as otherwise provided in this Act or any other law for the time being in force, any person including an intermediary who, while providing services under the terms of lawful contract, has secured access to any material containing personal information about another person, with the intent to cause or knowing that he is likely to cause wrongful loss or wrongful gain discloses, without the consent of the person concerned, or in breach of a lawful contract, such material to any other person, shall be punished with imprisonment for a term which may extend to three years, or with a fine which may extend to five lakh rupees, or with both.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+  ],
+};
+
+const bharatiyaNyayaSanhita2023: LegalSeedEntry = {
+  source: {
+    sourceType: "act",
+    title: "Bharatiya Nyaya Sanhita, 2023",
+    tier: "tier1",
+    jurisdiction: "IN",
+    authority: "Ministry of Home Affairs",
+    canonicalUrl: "https://www.indiacode.nic.in/handle/123456789/20062",
+    versionLabel: "2023 (effective July 1, 2024)",
+    effectiveFrom: "2024-07-01",
+    metadata: { issue_domain: "cyber_fraud" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "Bharatiya Nyaya Sanhita, 2023",
+      sectionNo: "318",
+      heading: "Cheating",
+      text: "Section 318 of the Bharatiya Nyaya Sanhita, 2023: Whoever, by deceiving any person, fraudulently or dishonestly induces the person so deceived to deliver any property to any person, or to consent that any person shall retain any property, or intentionally induces the person so deceived to do or omit to do anything which he would not do or omit if he were not so deceived, and which act or omission causes or is likely to cause damage or harm to that person in body, mind, reputation or property, is said to 'cheat'. A person who cheats shall be punished with imprisonment of either description for a term which may extend to three years, or with fine, or with both; and cheating with knowledge that wrongful loss will be caused to a person whose interest the offender is bound to protect, shall be punished with imprisonment of either description for a term which may extend to five years, or with fine, or with both.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 2,
+      actName: "Bharatiya Nyaya Sanhita, 2023",
+      sectionNo: "319",
+      heading: "Cheating by Personation",
+      text: "Section 319 of the Bharatiya Nyaya Sanhita, 2023: A person is said to 'cheat by personation' if he cheats by pretending to be some other person, or by knowingly substituting one person for another, or representing that he or any other person is a person other than he or such other person really is. The offence is committed whether the individual personated is a real or imaginary person. Whoever cheats by personation shall be punished with imprisonment of either description for a term which may extend to five years, or with fine, or with both. This section applies to online impersonation, fake identity creation on social media, and fraudulent impersonation of bank officials, government officers, or family members.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 3,
+      actName: "Bharatiya Nyaya Sanhita, 2023",
+      sectionNo: "316",
+      heading: "Criminal Breach of Trust",
+      text: "Section 316 of the Bharatiya Nyaya Sanhita, 2023: Whoever, being in any manner entrusted with property, or with any dominion over property, dishonestly misappropriates or converts to his own use that property, or dishonestly uses or disposes of that property in violation of any direction of law prescribing the mode in which such trust is to be discharged, or of any legal contract, express or implied, which he has made touching the discharge of such trust, or wilfully suffers any other person so to do, commits 'criminal breach of trust'. Whoever commits criminal breach of trust shall be punished with imprisonment of either description for a term which may extend to seven years, and shall also be liable to fine. Criminal breach of trust in a position of professional trust (e.g., by a financial advisor, bank employee, or insurer) carries enhanced punishment.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+  ],
+};
+
+const mhaCybercrimeReporting: LegalSeedEntry = {
+  source: {
+    sourceType: "govt_page",
+    title: "MHA Cybercrime Reporting – 1930 Helpline and National Cybercrime Reporting Portal",
+    tier: "tier2",
+    jurisdiction: "IN",
+    authority: "Ministry of Home Affairs (I4C)",
+    canonicalUrl: "https://cybercrime.gov.in/",
+    versionLabel: "current",
+    effectiveFrom: "2021-01-01",
+    metadata: { issue_domain: "cyber_fraud" },
+  },
+  chunks: [
+    {
+      chunkNo: 1,
+      actName: "MHA Cybercrime Reporting",
+      sectionNo: "1930-helpline",
+      heading: "Golden-Hour Reporting via 1930 Cyber Helpline",
+      text: "The Ministry of Home Affairs (I4C) operates the National Cybercrime Helpline 1930 for immediate reporting of financial cyber fraud. Reporting within the 'golden hour' (as soon as possible after the fraud) maximises the chances of the fraudulently transferred money being frozen and recovered. Upon calling 1930, the operator logs the complaint and triggers a bank-freeze request through the Citizen Financial Cyber Fraud Reporting and Management System (CFCFRMS) to block the onward transfer of funds. Victims should keep the transaction reference number, UPI ID, bank account number, and fraudster's mobile number handy while calling.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 2,
+      actName: "MHA Cybercrime Reporting",
+      sectionNo: "cybercrime-gov-in",
+      heading: "National Cybercrime Reporting Portal Procedure",
+      text: "The National Cybercrime Reporting Portal at cybercrime.gov.in allows citizens to report cybercrime complaints online in two categories: financial fraud (handled on priority through CFCFRMS) and other cybercrimes (cyberbullying, sextortion, hacking, etc.). After online filing, the complaint is forwarded to the jurisdictional police station and an acknowledgement is generated. Complainants should also file a First Information Report (FIR) at the nearest police station under the applicable sections of the Information Technology Act, 2000 and the Bharatiya Nyaya Sanhita, 2023 for formal legal proceedings.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+    {
+      chunkNo: 3,
+      actName: "MHA Cybercrime Reporting",
+      sectionNo: "bank-freeze",
+      heading: "Bank Freeze Flow via CFCFRMS",
+      text: "On receipt of a financial fraud complaint on 1930 or cybercrime.gov.in, the CFCFRMS system automatically alerts the banks holding the fraudster's accounts to put a lien/freeze on the funds pending investigation. Banks participating in CFCFRMS include all scheduled commercial banks, payment banks, and major wallets. The freeze request is initiated by the I4C nodal officer and the concerned bank must acknowledge and act within 30 minutes during banking hours. Victims are advised to simultaneously file a complaint with their own bank's fraud desk and invoke the RBI Customer Liability Circular 2017 for zero-liability protection on promptly reported unauthorised transactions.",
+      metadata: { issue_domain: "cyber_fraud" },
+    },
+  ],
+};
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export const ALL_LEGAL_SEED_ENTRIES: LegalSeedEntry[] = [
+  // Consumer domain
+  consumerProtectionAct2019,
+  eCommerceRules2020,
+  nationalConsumerHelpline,
+  // Payment domain
+  rbiIntegratedOmbudsmanScheme2021,
+  rbiCustomerLiabilityCircular2017,
+  npciUpiGuidelines,
+  // Cyber fraud domain
+  itAct2000,
+  bharatiyaNyayaSanhita2023,
+  mhaCybercrimeReporting,
+];

packages/db/src/seeds/route-rules-data.ts

@@ -0,0 +1,357 @@
+/**
+ * Curated route rules seed data for CourtMitra MissionOS Phase 1.
+ * One route_rules row per issue domain: consumer, payment, cyber_fraud.
+ *
+ * sourceCitationsBySectionRef: array of { actName, sectionNo } tuples.
+ * The seed runner resolves these to legal_chunk ids at insert time.
+ */
+
+export interface SourceCitationRef {
+  actName: string;
+  sectionNo: string;
+}
+
+export interface RouteRuleSeedData {
+  issueDomain: string;
+  jurisdictionFilter: Record<string, unknown>;
+  triggerConditions: Record<string, unknown>;
+  priority: number;
+  routeGraph: {
+    nodes: Array<{
+      id: string;
+      level: string;
+      label: string;
+      description: string;
+      actionType: string;
+      target: Record<string, unknown>;
+      expectedResponseDays: number;
+    }>;
+    edges: Array<{
+      from: string;
+      to: string;
+      condition: string;
+    }>;
+  };
+  requiredEvidence: string[];
+  deadlines: Record<string, unknown>;
+  sourceCitationsBySectionRef: SourceCitationRef[];
+  socialTemplate: null;
+  stopAndRefer: null | {
+    conditions: string[];
+    helpline: string;
+    message: string;
+  };
+  active: boolean;
+}
+
+// ============================================================================
+// CONSUMER domain route rule
+// ============================================================================
+
+export const consumerRouteRule: RouteRuleSeedData = {
+  issueDomain: "consumer",
+  jurisdictionFilter: { country: "IN" },
+  triggerConditions: {
+    transaction_amount_min: 0,
+    issue_types: ["product_defect", "service_deficiency", "unfair_trade", "non_delivery", "refund_not_received"],
+  },
+  priority: 100,
+  routeGraph: {
+    nodes: [
+      {
+        id: "L0",
+        level: "L0",
+        label: "Grievance to Seller / Service Provider",
+        description:
+          "Send a formal written complaint (email/registered post) to the seller or e-commerce entity's grievance officer. Under Consumer Protection (E-Commerce) Rules 2020 Rule 4(5), the grievance officer must acknowledge within 48 hours and resolve within 30 days.",
+        actionType: "send_email",
+        target: { channel: "email", recipient: "seller_grievance_officer" },
+        expectedResponseDays: 30,
+      },
+      {
+        id: "L1",
+        level: "L1",
+        label: "National Consumer Helpline (1915 / INGRAM)",
+        description:
+          "File complaint on INGRAM portal (consumerhelpline.gov.in) or call 1915. NCH mediates between consumer and company; response expected within 30 days. Suitable for e-commerce, product, and service complaints.",
+        actionType: "submit_portal",
+        target: { channel: "portal", url: "https://consumerhelpline.gov.in", helpline: "1915" },
+        expectedResponseDays: 30,
+      },
+      {
+        id: "L2",
+        level: "L2",
+        label: "E-Commerce Grievance Officer (formal notice)",
+        description:
+          "Send formal legal notice to e-commerce entity's grievance officer under Consumer Protection (E-Commerce) Rules 2020 Rule 4(5) citing failure to resolve. Demand resolution within 15 days failing which consumer will approach District Commission.",
+        actionType: "send_email",
+        target: { channel: "email", recipient: "ecommerce_grievance_officer" },
+        expectedResponseDays: 15,
+      },
+      {
+        id: "L3",
+        level: "L3",
+        label: "Consumer Commission – District (under ₹1 crore)",
+        description:
+          "File complaint at District Consumer Disputes Redressal Commission under Section 35 of Consumer Protection Act 2019. Jurisdiction covers goods/services valued up to ₹1 crore (Section 47). Limitation period is 2 years from cause of action (Section 69).",
+        actionType: "manual_packet",
+        target: { channel: "physical", forum: "District_Consumer_Commission" },
+        expectedResponseDays: 90,
+      },
+    ],
+    edges: [
+      { from: "L0", to: "L1", condition: "no_response_or_unsatisfactory_after_30_days" },
+      { from: "L1", to: "L2", condition: "no_response_or_unsatisfactory_after_30_days" },
+      { from: "L2", to: "L3", condition: "no_response_or_unsatisfactory_after_15_days" },
+    ],
+  },
+  requiredEvidence: ["receipt", "screenshot", "email", "chat"],
+  deadlines: {
+    complaint_within_days: 730,
+    note: "Section 69 CPA 2019: 2-year limitation from date cause of action arose",
+    grievance_officer_response_days: 30,
+    district_commission_resolution_days: 90,
+  },
+  sourceCitationsBySectionRef: [
+    { actName: "Consumer Protection Act, 2019", sectionNo: "35" },
+    { actName: "Consumer Protection Act, 2019", sectionNo: "47" },
+    { actName: "Consumer Protection Act, 2019", sectionNo: "69" },
+    { actName: "Consumer Protection Act, 2019", sectionNo: "2(47)" },
+    { actName: "Consumer Protection (E-Commerce) Rules, 2020", sectionNo: "4(5)" },
+    { actName: "Consumer Protection (E-Commerce) Rules, 2020", sectionNo: "5" },
+    { actName: "National Consumer Helpline – Grievance Filing Procedure", sectionNo: "ingram" },
+  ],
+  socialTemplate: null,
+  stopAndRefer: null,
+  active: true,
+};
+
+// ============================================================================
+// PAYMENT domain route rule
+// ============================================================================
+
+export const paymentRouteRule: RouteRuleSeedData = {
+  issueDomain: "payment",
+  jurisdictionFilter: { country: "IN" },
+  triggerConditions: {
+    upi_or_bank: true,
+    issue_types: [
+      "failed_upi_transaction",
+      "unauthorized_debit",
+      "non_reversal",
+      "bank_fraud",
+      "wallet_dispute",
+    ],
+  },
+  priority: 100,
+  routeGraph: {
+    nodes: [
+      {
+        id: "L0",
+        level: "L0",
+        label: "Bank / PSP Complaint (30-Day Window)",
+        description:
+          "Immediately report unauthorized or failed transaction to your bank's customer care and PSP (e.g., Google Pay, PhonePe). Under RBI Customer Liability Circular 2017, reporting within 3 working days of bank's communication gives zero liability. Document the complaint reference number.",
+        actionType: "send_email",
+        target: { channel: "email", recipient: "bank_customer_care" },
+        expectedResponseDays: 30,
+      },
+      {
+        id: "L1",
+        level: "L1",
+        label: "RBI Banking Ombudsman (cms.rbi.org.in)",
+        description:
+          "If bank does not resolve within 30 days or gives unsatisfactory response, file complaint with RBI Integrated Ombudsman at cms.rbi.org.in. Per Clause 10 of RBI IOS 2021, you must have first lodged complaint with bank and waited 30 days. Maximum award is ₹20 lakh.",
+        actionType: "submit_portal",
+        target: { channel: "portal", url: "https://cms.rbi.org.in" },
+        expectedResponseDays: 30,
+      },
+      {
+        id: "L2",
+        level: "L2",
+        label: "NPCI / UPI TAT Escalation",
+        description:
+          "For UPI failed transactions where credit reversal has not occurred within T+1 day, escalate to NPCI through the PSP dispute management system. Per NPCI UPI Procedural Guidelines v1.6, reversal must occur within 5 working days. If PSP is unresponsive, raise chargeback through your bank.",
+        actionType: "submit_portal",
+        target: { channel: "portal", url: "https://www.npci.org.in/contact-us" },
+        expectedResponseDays: 5,
+      },
+      {
+        id: "L3",
+        level: "L3",
+        label: "Consumer Commission",
+        description:
+          "If RBI Ombudsman does not resolve or the complaint falls outside Ombudsman jurisdiction, file at District Consumer Commission under Consumer Protection Act 2019 (Section 35). Banking and payment services are 'services' under Section 2(34) CPA 2019.",
+        actionType: "manual_packet",
+        target: { channel: "physical", forum: "District_Consumer_Commission" },
+        expectedResponseDays: 90,
+      },
+    ],
+    edges: [
+      { from: "L0", to: "L1", condition: "no_resolution_within_30_days" },
+      { from: "L1", to: "L2", condition: "upi_specific_and_no_reversal" },
+      { from: "L1", to: "L3", condition: "ombudsman_unable_to_resolve_or_out_of_jurisdiction" },
+      { from: "L2", to: "L3", condition: "no_response_from_npci" },
+    ],
+  },
+  requiredEvidence: ["receipt", "screenshot", "pdf"],
+  deadlines: {
+    report_to_bank_days: 3,
+    note_rbi_zero_liability:
+      "RBI Circular 2017: zero liability if reported within 3 working days of bank communication",
+    ombudsman_complaint_days: 30,
+    note_ombudsman_pre_filing: "RBI IOS 2021 Clause 10: 30-day pre-filing requirement with bank",
+    upi_reversal_tat_days: 1,
+    note_upi_tat: "NPCI UPI Guidelines v1.6: T+1 credit reversal for failed UPI",
+  },
+  sourceCitationsBySectionRef: [
+    {
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "zero-liability",
+    },
+    {
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "limited-liability",
+    },
+    {
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "clause-10",
+    },
+    {
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "clause-10-pre-filing",
+    },
+    {
+      actName: "Reserve Bank – Integrated Ombudsman Scheme, 2021",
+      sectionNo: "award",
+    },
+    {
+      actName: "NPCI UPI Procedural Guidelines",
+      sectionNo: "dispute-tat",
+    },
+    {
+      actName: "NPCI UPI Procedural Guidelines",
+      sectionNo: "chargeback",
+    },
+    { actName: "Consumer Protection Act, 2019", sectionNo: "2(34)" },
+  ],
+  socialTemplate: null,
+  stopAndRefer: null,
+  active: true,
+};
+
+// ============================================================================
+// CYBER FRAUD domain route rule
+// ============================================================================
+
+export const cyberFraudRouteRule: RouteRuleSeedData = {
+  issueDomain: "cyber_fraud",
+  jurisdictionFilter: { country: "IN" },
+  triggerConditions: {
+    money_lost: true,
+    urgency_hours_le: 48,
+    issue_types: [
+      "upi_fraud",
+      "phishing",
+      "vishing",
+      "identity_theft",
+      "fake_customer_care",
+      "investment_fraud",
+      "romance_scam",
+      "job_fraud",
+    ],
+  },
+  priority: 200,
+  routeGraph: {
+    nodes: [
+      {
+        id: "L0",
+        level: "L0",
+        label: "URGENT: Call 1930 + File on cybercrime.gov.in",
+        description:
+          "IMMEDIATELY call 1930 (National Cyber Crime Helpline) and file at cybercrime.gov.in. The CFCFRMS system triggers a bank-freeze request in the golden hour. Keep UPI transaction ID, fraudster's mobile/account number, and transaction amount ready. This step is time-critical — funds can be frozen before the fraudster withdraws.",
+        actionType: "inform_user",
+        target: {
+          channel: "portal",
+          url: "https://cybercrime.gov.in",
+          helpline: "1930",
+        },
+        expectedResponseDays: 1,
+      },
+      {
+        id: "L1",
+        level: "L1",
+        label: "Bank Freeze Request (RBI 2017 Zero-Liability)",
+        description:
+          "Contact your bank's fraud/cybercrime helpline immediately after calling 1930. Invoke the RBI Customer Liability Circular 2017 (DBR.No.Leg.BC.78/09.07.005/2017-18) — zero liability applies when unauthorized transaction is reported within 3 working days of bank communication. Demand written acknowledgement and a provisional credit within 10 working days.",
+        actionType: "send_email",
+        target: { channel: "email", recipient: "bank_fraud_desk" },
+        expectedResponseDays: 10,
+      },
+      {
+        id: "L2",
+        level: "L2",
+        label: "FIR at Police Station + I4C Follow-Up",
+        description:
+          "File an FIR at the nearest police station citing IT Act 2000 Section 66C (identity theft) / 66D (cheating by personation) and Bharatiya Nyaya Sanhita 2023 Section 318 (cheating) / 319 (cheating by personation) as applicable. Cross-reference the cybercrime.gov.in complaint number in the FIR. Follow up with the I4C nodal officer for the bank-freeze status.",
+        actionType: "manual_packet",
+        target: { channel: "physical", forum: "Police_Station_Cyber_Cell" },
+        expectedResponseDays: 30,
+      },
+      {
+        id: "L3",
+        level: "L3",
+        label: "Cyber Tribunal / Consumer Commission",
+        description:
+          "If police fails to act or bank does not reverse funds, escalate to the Adjudicating Officer under IT Act 2000 Section 46, or file at District Consumer Commission if bank's deficient service contributed to the fraud. RBI Ombudsman can be approached if bank refuses to apply zero-liability protection under the 2017 circular.",
+        actionType: "manual_packet",
+        target: { channel: "physical", forum: "Adjudicating_Officer_IT_Act" },
+        expectedResponseDays: 90,
+      },
+    ],
+    edges: [
+      { from: "L0", to: "L1", condition: "immediately_after_1930_call" },
+      { from: "L1", to: "L2", condition: "bank_not_responsive_or_fir_required" },
+      { from: "L2", to: "L3", condition: "police_inaction_or_funds_not_recovered" },
+    ],
+  },
+  requiredEvidence: ["screenshot", "receipt", "chat", "pdf"],
+  deadlines: {
+    golden_hour_report_asap: true,
+    note_golden_hour: "Call 1930 immediately — CFCFRMS freeze window is time-critical",
+    bank_report_within_working_days: 3,
+    note_bank_zero_liability: "RBI Circular 2017: zero liability if bank notified within 3 days",
+    fir_deadline_days: 30,
+    ombudsman_complaint_after_bank_days: 30,
+  },
+  sourceCitationsBySectionRef: [
+    { actName: "MHA Cybercrime Reporting – 1930 Helpline and National Cybercrime Reporting Portal", sectionNo: "1930-helpline" },
+    { actName: "MHA Cybercrime Reporting – 1930 Helpline and National Cybercrime Reporting Portal", sectionNo: "cybercrime-gov-in" },
+    { actName: "MHA Cybercrime Reporting – 1930 Helpline and National Cybercrime Reporting Portal", sectionNo: "bank-freeze" },
+    {
+      actName:
+        "RBI Customer Liability in Unauthorised Electronic Banking Transactions Circular 2017",
+      sectionNo: "zero-liability",
+    },
+    { actName: "Information Technology Act, 2000", sectionNo: "66C" },
+    { actName: "Information Technology Act, 2000", sectionNo: "66D" },
+    { actName: "Bharatiya Nyaya Sanhita, 2023", sectionNo: "318" },
+    { actName: "Bharatiya Nyaya Sanhita, 2023", sectionNo: "319" },
+  ],
+  socialTemplate: null,
+  stopAndRefer: {
+    conditions: ["sextortion", "threats_to_safety", "child_safety", "active_fraud_in_progress"],
+    helpline: "1930",
+    message:
+      "Call 1930 and visit cybercrime.gov.in immediately. If unsafe or threatened, dial 112. This situation requires immediate human assistance — CourtMitra automation is paused pending human review.",
+  },
+  active: true,
+};
+
+export const ALL_ROUTE_RULES: RouteRuleSeedData[] = [
+  consumerRouteRule,
+  paymentRouteRule,
+  cyberFraudRouteRule,
+];

packages/db/src/seeds/run.ts

@@ -0,0 +1,319 @@
+/**
+ * Day-3 seed runner: legal_sources, legal_chunks, route_rules.
+ *
+ * Idempotency strategy:
+ *   - legal_sources: upsert on (title) — delete existing chunks + source, then re-insert.
+ *     Simpler than per-row sha256 conflict since we control the data file.
+ *   - legal_chunks: inserted after source is inserted; no conflict clause needed as we
+ *     always delete-then-insert by source.
+ *   - route_rules: delete-then-insert by issueDomain (Phase 1 has exactly one rule/domain).
+ *
+ * Embedding:
+ *   Attempts to import createOpenAiCompatibleEmbedder from @courtmitra/adapters.
+ *   If the export does not exist (Agent A's embedder not yet merged), falls back gracefully
+ *   with embedding=null — FTS (tsvector GIN index) remains fully functional.
+ *
+ * Usage:
+ *   pnpm --filter @courtmitra/db seed
+ *   (or) set -a && . infra/.env && set +a && tsx packages/db/src/seeds/run.ts
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { eq, and } from "drizzle-orm";
+
+// Load .env from infra/.env relative to repo root (two levels up from packages/db/src/seeds)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const envPath = resolve(__dirname, "../../../../infra/.env");
+
+function loadEnv(path: string): void {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    // Already exported by shell; skip silently.
+    return;
+  }
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim();
+    if (!process.env[key]) {
+      process.env[key] = val;
+    }
+  }
+}
+
+loadEnv(envPath);
+
+import { getDb, closeDb, legalSources, legalChunks, routeRules } from "../index.js";
+import { ALL_LEGAL_SEED_ENTRIES } from "./legal-data.js";
+import { ALL_ROUTE_RULES } from "./route-rules-data.js";
+import type { LegalSeedEntry } from "./legal-data.js";
+import type { RouteRuleSeedData } from "./route-rules-data.js";
+
+// ---------------------------------------------------------------------------
+// Embedder — graceful degradation if Agent A's factory isn't merged yet
+// ---------------------------------------------------------------------------
+
+type EmbedFn = (texts: string[]) => Promise<(number[] | null)[]>;
+
+async function resolveEmbedder(): Promise<EmbedFn> {
+  try {
+    // Dynamically import so that a missing export doesn't crash at module load.
+    const adaptersModule = await import("@courtmitra/adapters");
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const factory = (adaptersModule as any).createOpenAiCompatibleEmbedder;
+    if (typeof factory !== "function") {
+      console.warn(
+        "[seed] WARNING: createOpenAiCompatibleEmbedder not found in @courtmitra/adapters. " +
+        "Inserting chunks with embedding=null. FTS will still work.",
+      );
+      return async (texts) => texts.map(() => null);
+    }
+
+    const embedder = factory();
+    console.log("[seed] Embedder resolved from @courtmitra/adapters.");
+    return async (texts: string[]) => {
+      try {
+        return await embedder.embed(texts);
+      } catch (err) {
+        console.warn("[seed] WARNING: embedder.embed() failed:", (err as Error).message);
+        console.warn("[seed] Inserting chunks with embedding=null.");
+        return texts.map(() => null);
+      }
+    };
+  } catch (err) {
+    console.warn(
+      "[seed] WARNING: Could not import @courtmitra/adapters:",
+      (err as Error).message,
+    );
+    console.warn("[seed] Inserting chunks with embedding=null. FTS will still work.");
+    return async (texts) => texts.map(() => null);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+function countTokensApprox(text: string): number {
+  // Rough approximation: 1 token ≈ 4 chars for English legal text.
+  return Math.ceil(text.length / 4);
+}
+
+// ---------------------------------------------------------------------------
+// Main seed logic
+// ---------------------------------------------------------------------------
+
+async function seedLegalData(
+  db: ReturnType<typeof getDb>,
+  embed: EmbedFn,
+): Promise<{ sourcesInserted: number; chunksInserted: number }> {
+  let sourcesInserted = 0;
+  let chunksInserted = 0;
+
+  for (const entry of ALL_LEGAL_SEED_ENTRIES) {
+    const { source, chunks } = entry as LegalSeedEntry;
+
+    // --- 1. Delete existing source (and cascading chunks) by title ---
+    const existing = await db
+      .select({ id: legalSources.id })
+      .from(legalSources)
+      .where(eq(legalSources.title, source.title));
+
+    if (existing.length > 0) {
+      const existingId = existing[0]!.id;
+      // Delete chunks first (FK constraint)
+      await db.delete(legalChunks).where(eq(legalChunks.sourceId, existingId));
+      await db.delete(legalSources).where(eq(legalSources.id, existingId));
+      console.log(`[seed] Replaced existing source: "${source.title}"`);
+    }
+
+    // --- 2. Compute sha256 for the source (based on title + version) ---
+    const sourceHash = sha256(`${source.title}|${source.versionLabel}`);
+
+    // --- 3. Insert source ---
+    const [insertedSource] = await db
+      .insert(legalSources)
+      .values({
+        sourceType: source.sourceType,
+        title: source.title,
+        tier: source.tier,
+        jurisdiction: source.jurisdiction,
+        authority: source.authority,
+        canonicalUrl: source.canonicalUrl,
+        versionLabel: source.versionLabel,
+        effectiveFrom: source.effectiveFrom,
+        sha256: sourceHash,
+        metadata: source.metadata,
+      })
+      .returning({ id: legalSources.id });
+
+    if (!insertedSource) {
+      console.error(`[seed] ERROR: Failed to insert source "${source.title}"`);
+      continue;
+    }
+
+    sourcesInserted++;
+    const sourceId = insertedSource.id;
+    console.log(`[seed] Inserted source [${sourceId}]: "${source.title}"`);
+
+    // --- 4. Embed all chunk texts for this source ---
+    const chunkTexts = chunks.map((c) => c.text);
+    const embeddings = await embed(chunkTexts);
+
+    // --- 5. Insert chunks ---
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i]!;
+      const embedding = embeddings[i] ?? null;
+
+      await db.insert(legalChunks).values({
+        sourceId,
+        chunkNo: chunk.chunkNo,
+        actName: chunk.actName,
+        sectionNo: chunk.sectionNo,
+        heading: chunk.heading,
+        text: chunk.text,
+        tokenCount: countTokensApprox(chunk.text),
+        // textTsv is a GENERATED ALWAYS AS column — do not supply a value
+        embedding: embedding as number[] | null,
+        metadata: chunk.metadata,
+      });
+
+      chunksInserted++;
+    }
+
+    console.log(`[seed]   → ${chunks.length} chunks inserted for "${source.title}"`);
+  }
+
+  return { sourcesInserted, chunksInserted };
+}
+
+async function seedRouteRules(
+  db: ReturnType<typeof getDb>,
+): Promise<{ rulesInserted: number }> {
+  let rulesInserted = 0;
+
+  for (const rule of ALL_ROUTE_RULES as RouteRuleSeedData[]) {
+    // --- 1. Resolve sourceCitationsBySectionRef → legal_chunk ids ---
+    const resolvedChunkIds: string[] = [];
+
+    for (const ref of rule.sourceCitationsBySectionRef) {
+      // Find the source by title (act name)
+      const sourceRows = await db
+        .select({ id: legalSources.id })
+        .from(legalSources)
+        .where(eq(legalSources.title, ref.actName));
+
+      if (sourceRows.length === 0) {
+        console.warn(
+          `[seed] WARNING: Source not found for actName="${ref.actName}" — skipping citation`,
+        );
+        continue;
+      }
+
+      const sourceId = sourceRows[0]!.id;
+
+      // Find chunk by source_id + section_no
+      const chunkRows = await db
+        .select({ id: legalChunks.id })
+        .from(legalChunks)
+        .where(
+          and(
+            eq(legalChunks.sourceId, sourceId),
+            eq(legalChunks.sectionNo, ref.sectionNo),
+          ),
+        );
+
+      if (chunkRows.length === 0) {
+        console.warn(
+          `[seed] WARNING: Chunk not found for actName="${ref.actName}" sectionNo="${ref.sectionNo}" — skipping`,
+        );
+        continue;
+      }
+
+      resolvedChunkIds.push(chunkRows[0]!.id);
+    }
+
+    // --- 2. Delete existing rule for this domain (idempotency) ---
+    await db.delete(routeRules).where(eq(routeRules.issueDomain, rule.issueDomain));
+
+    // --- 3. Insert route rule ---
+    const [inserted] = await db
+      .insert(routeRules)
+      .values({
+        issueDomain: rule.issueDomain,
+        jurisdictionFilter: rule.jurisdictionFilter,
+        triggerConditions: rule.triggerConditions,
+        priority: rule.priority,
+        routeGraph: rule.routeGraph,
+        requiredEvidence: rule.requiredEvidence,
+        deadlines: rule.deadlines,
+        sourceCitations: resolvedChunkIds,
+        socialTemplate: rule.socialTemplate,
+        stopAndRefer: rule.stopAndRefer,
+        active: rule.active,
+      })
+      .returning({ id: routeRules.id });
+
+    if (!inserted) {
+      console.error(`[seed] ERROR: Failed to insert route rule for domain "${rule.issueDomain}"`);
+      continue;
+    }
+
+    rulesInserted++;
+    console.log(
+      `[seed] Route rule [${inserted.id}] inserted for domain="${rule.issueDomain}" ` +
+      `with ${resolvedChunkIds.length} cited chunks`,
+    );
+  }
+
+  return { rulesInserted };
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  console.log("[seed] Day-3 legal grounding seed starting...");
+  console.log(`[seed] DATABASE_URL: ${process.env["DATABASE_URL"] ? "set" : "NOT SET — will fail"}`);
+
+  const db = getDb();
+
+  // Resolve embedder (graceful degradation if Agent A's export isn't merged)
+  const embed = await resolveEmbedder();
+
+  // Seed legal data
+  console.log("\n[seed] ── Seeding legal_sources + legal_chunks ──");
+  const { sourcesInserted, chunksInserted } = await seedLegalData(db, embed);
+
+  // Seed route rules
+  console.log("\n[seed] ── Seeding route_rules ──");
+  const { rulesInserted } = await seedRouteRules(db);
+
+  console.log("\n[seed] ── Summary ──");
+  console.log(`[seed]   legal_sources inserted : ${sourcesInserted}`);
+  console.log(`[seed]   legal_chunks  inserted : ${chunksInserted}`);
+  console.log(`[seed]   route_rules   inserted : ${rulesInserted}`);
+  console.log("[seed] Done.");
+
+  await closeDb();
+}
+
+main().catch((err) => {
+  console.error("[seed] FATAL:", err);
+  process.exit(1);
+});

packages/ports/src/index.ts

@@ -45,6 +45,13 @@ export interface LlmPort {
   generateStructured<T>(req: LlmStructuredRequest<T>): Promise<LlmStructuredResult<T>>;
 }
 
+// --- Embedding ---------------------------------------------------------------
+
+export interface EmbeddingPort {
+  embed(texts: string[]): Promise<number[][]>;
+  dimensions: number;
+}
+
 // --- Legal retrieval / verification -----------------------------------------
 
 export interface LegalQuery {
@@ -65,6 +72,8 @@ export interface RetrievedLegalSource {
 }
 
 export interface ClaimSupportCheck {
+  /** Unique mission identifier — required to persist legal_claim_verifications. */
+  missionId: string;
   claim: string;
   quoteSpans: string[];
   chunkIds: string[];

packages/prompts/src/index.ts

@@ -124,6 +124,78 @@ Rules:
 - Do NOT fabricate claims not supported by the evidence.
 - Output ONLY the JSON object (with the "claims" key), nothing else.`,
   },
+
+  "route-plan.v1": {
+    id: "route-plan.v1",
+    version: "1",
+    template: `You are a legal-route planning assistant for Indian citizens filing grievances. Your task is to generate a structured route plan grounded in the provided legal chunks.
+
+CRITICAL CITATION RULES (CLAUDE.md #4 — INVARIANT, NON-NEGOTIABLE):
+- Every claim's \`quoteSpans[]\` entries MUST be VERBATIM substrings of the corresponding chunk's text in <retrieved_chunks>. Copy the exact characters — do not paraphrase, summarise, or invent.
+- Every \`chunkIds[]\` entry MUST be a chunk_id that appears in <retrieved_chunks>. Do not fabricate chunk IDs.
+- If no chunk supports a claim with a literal verbatim quote, omit the claim entirely. Never invent citations.
+- If zero claims survive, still generate a route plan — use neutral administrative language in step descriptions; do not use legal language without citations.
+
+Issue domain: {{issueDomain}}
+
+<mission_facts>
+{{missionFacts}}
+</mission_facts>
+
+<evidence_claims>
+{{evidenceClaims}}
+</evidence_claims>
+
+<retrieved_chunks>
+{{retrievedChunks}}
+</retrieved_chunks>
+
+Return ONLY a JSON object matching the schema below — no markdown fences, no prose.
+
+Schema:
+{
+  "summary": "<one-paragraph summary of the recommended route and why, referencing key facts>",
+  "steps": [
+    {
+      "stepNo": <integer starting at 0>,
+      "level": "<L0|L1|L2|L3|L4>",
+      "title": "<short step title>",
+      "description": "<what to do at this step, referencing relevant facts and cited law if available>",
+      "authority": "<authority name or null>",
+      "channel": "<email|portal|phone|in_person|social|self_service>",
+      "actionType": "<generate_packet|send_email|prepare_portal|call_support|ask_question|schedule_followup|close_case>",
+      "requiredEvidence": ["<evidence item description>"],
+      "deadlineDays": <integer calendar days or null>,
+      "claimRefs": [<index into claims[] array>],
+      "riskLevel": "<low|medium|high>"
+    }
+  ],
+  "claims": [
+    {
+      "claim": "<one-sentence legal or procedural claim directly supported by chunk text>",
+      "quoteSpans": ["<VERBATIM substring from chunk text — must be exact copy>"],
+      "chunkIds": ["<chunk_id from retrieved_chunks>"],
+      "confidence": <0.0–1.0>
+    }
+  ],
+  "riskNotes": ["<risk or caveat note>"],
+  "expectedTimelineDays": <integer total expected days or null>
+}
+
+Route level guide:
+- L0: informal resolution (direct complaint to company/platform via self_service or email)
+- L1: regulator complaint (CGPDTM/IRDAI/SEBI/RBI portal or email)
+- L2: ombudsman (RBI Banking Ombudsman, Insurance Ombudsman, etc.)
+- L3: consumer commission (District Consumer Disputes Redressal Commission)
+- L4: appellate / superior forum (State Commission, National Commission, High Court)
+
+Rules:
+- Generate at least L0 and L1 steps; add L2+ only if facts and evidence suggest it is needed.
+- Legal information and workflow assistance only — not a lawyer-client relationship. Do not guarantee outcomes.
+- Never label any entity "fraud/scam/criminal"; use "user reports / unresolved / alleged".
+- Disclaimer on legal outputs: "This is legal information only. CourtMitra is not your lawyer."
+- Output ONLY the JSON object, nothing else.`,
+  },
 };
 
 /**
@@ -146,13 +218,29 @@ const UNTRUSTED_VARS = new Set(["rawMessages", "parsedEvidence"]);
  */
 const MAX_UNTRUSTED_CHARS = 12000;
 
+/**
+ * Max total prompt body characters for route-plan (to stay within context).
+ * Retrieved chunks are the largest variable and are truncated to keep total
+ * prompt body under ~14000 chars as required by the spec.
+ */
+const MAX_ROUTE_PLAN_CHARS = 14000;
+
 /**
  * Interpolate {{variable}} placeholders in a prompt template.
  * Untrusted variables (rawMessages, parsedEvidence) are capped at
  * MAX_UNTRUSTED_CHARS to prevent injection and token blowup.
+ *
+ * For route-plan.v1: retrievedChunks is length-capped at remaining budget
+ * after other variables are rendered, keeping total under MAX_ROUTE_PLAN_CHARS.
  */
 export function renderPrompt(id: string, vars: Record<string, unknown>): string {
   const p = getPrompt(id);
+
+  // For route-plan.v1, apply total-body cap by truncating retrievedChunks last.
+  if (id === "route-plan.v1") {
+    return renderRoutePlanPrompt(p.template, vars);
+  }
+
   return p.template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => {
     if (!(key in vars)) {
       throw new Error(`Missing variable "{{${key}}}" for prompt "${id}".`);
@@ -165,3 +253,35 @@ export function renderPrompt(id: string, vars: Record<string, unknown>): string
     return str;
   });
 }
+
+/**
+ * Render the route-plan.v1 prompt, capping retrievedChunks so total body
+ * stays under MAX_ROUTE_PLAN_CHARS. All other vars are rendered first to
+ * measure their size; remaining budget is given to retrievedChunks.
+ */
+function renderRoutePlanPrompt(template: string, vars: Record<string, unknown>): string {
+  // First pass: render all vars except retrievedChunks (use placeholder)
+  const CHUNK_PLACEHOLDER = "__CHUNKS_PLACEHOLDER__";
+  const withoutChunks = template.replace(/\{\{(\w+)\}\}/g, (match, key: string) => {
+    if (key === "retrievedChunks") return CHUNK_PLACEHOLDER;
+    if (!(key in vars)) {
+      throw new Error(`Missing variable "{{${key}}}" for prompt "route-plan.v1".`);
+    }
+    const val = vars[key];
+    return typeof val === "string" ? val : JSON.stringify(val, null, 2);
+  });
+
+  const usedChars = withoutChunks.replace(CHUNK_PLACEHOLDER, "").length;
+  const remaining = Math.max(0, MAX_ROUTE_PLAN_CHARS - usedChars);
+
+  if (!("retrievedChunks" in vars)) {
+    throw new Error(`Missing variable "{{retrievedChunks}}" for prompt "route-plan.v1".`);
+  }
+  const chunksVal = vars["retrievedChunks"];
+  let chunksStr = typeof chunksVal === "string" ? chunksVal : JSON.stringify(chunksVal, null, 2);
+  if (chunksStr.length > remaining) {
+    chunksStr = chunksStr.slice(0, remaining) + "\n[...chunks truncated to fit context budget]";
+  }
+
+  return withoutChunks.replace(CHUNK_PLACEHOLDER, chunksStr);
+}

pnpm-lock.yaml

@@ -158,6 +158,9 @@ importers:
       '@courtmitra/contracts':
         specifier: workspace:*
         version: link:../contracts
+      '@courtmitra/db':
+        specifier: workspace:*
+        version: link:../db
       '@courtmitra/ports':
         specifier: workspace:*
         version: link:../ports
@@ -170,6 +173,9 @@ importers:
       ai:
         specifier: ^6.0.191
         version: 6.0.191(zod@4.4.3)
+      drizzle-orm:
+        specifier: ^0.45.2
+        version: 0.45.2(@opentelemetry/api@1.9.1)(@types/pg@8.20.0)(pg@8.21.0)
       zod:
         specifier: ^4.4.3
         version: 4.4.3

scripts/day3-fabrication-gate.ts

@@ -0,0 +1,71 @@
+/**
+ * Day-3 live gate (half 2): fabricated-citation rejection.
+ *
+ * Drives the LegalRetrievalPort verifier with two payloads against the same
+ * real chunk:
+ *   - GENUINE quote (exact verbatim substring of chunk.text) → must be supported=true
+ *   - FABRICATED quote (plausible-sounding but NOT in chunk.text) → must be supported=false
+ *
+ * Asserts both, prints the legal_claim_verifications row, exits non-zero on
+ * regression. Runs against the local Postgres (DATABASE_URL must be exported).
+ */
+import { getDb, schema } from "@courtmitra/db";
+import {
+  createOpenAiCompatibleEmbedder,
+  createPgvectorFtsLegalRetrieval,
+} from "@courtmitra/adapters";
+import { eq } from "drizzle-orm";
+
+async function main() {
+  const db = getDb();
+  const embedder = createOpenAiCompatibleEmbedder();
+  const retrieval = createPgvectorFtsLegalRetrieval(db, embedder);
+
+  // Pick a real seeded chunk to anchor both tests.
+  const [chunk] = await db
+    .select()
+    .from(schema.legalChunks)
+    .where(eq(schema.legalChunks.sectionNo, "award"))
+    .limit(1);
+  if (!chunk) throw new Error("No 'award' chunk seeded — run pnpm db:seed first.");
+
+  // Pick any mission to satisfy FK.
+  const [mission] = await db.select().from(schema.missions).limit(1);
+  if (!mission) throw new Error("No mission in DB.");
+
+  // 1. GENUINE quote — verbatim substring of chunk.text.
+  const genuineQuote = chunk.text.slice(60, 180).trim();
+  const genuine = await retrieval.verifyClaimSupport({
+    missionId: mission.id,
+    claim: "Ombudsman can direct the regulated entity to pay an award (test-genuine).",
+    quoteSpans: [genuineQuote],
+    chunkIds: [chunk.id],
+  });
+
+  // 2. FABRICATED quote — plausible legalese but NOT in chunk.text.
+  const fabricatedQuote =
+    "The Ombudsman shall award treble damages plus punitive interest at 24% per annum on every claim, payable within seventy-two hours.";
+  const fabricated = await retrieval.verifyClaimSupport({
+    missionId: mission.id,
+    claim: "Ombudsman awards treble damages plus 24% interest (test-fabricated).",
+    quoteSpans: [fabricatedQuote],
+    chunkIds: [chunk.id],
+  });
+
+  console.log("\n=== DAY-3 FABRICATION GATE ===");
+  console.log("Genuine    →", { supported: genuine.supported, supportLevel: genuine.supportLevel });
+  console.log("Fabricated →", {
+    supported: fabricated.supported,
+    supportLevel: fabricated.supportLevel,
+    failureReason: fabricated.failureReason,
+  });
+
+  const ok = genuine.supported === true && fabricated.supported === false;
+  console.log(ok ? "\nPASS ✓ verifier rejects fabricated citation" : "\nFAIL ✗");
+  process.exit(ok ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});