2sagaco48 1.0.0

package/src/lib/output-boundary.ts

@@ -0,0 +1,235 @@
+/**
+ * Deterministic Output Boundary — INVERTED approach.
+ *
+ * Instead of trying to enumerate every possible scratchpad pattern (infinite),
+ * we find the FINAL PROSE BLOCK and discard everything else.
+ *
+ * Strategy:
+ * 1. If <final_answer> tags exist, extract that.
+ * 2. Otherwise, scan backward from the end of the text to find the last
+ *    contiguous block of clean prose (sentences, headings, tables, lists).
+ *    Everything before the first line of that block is scratchpad.
+ * 3. Line-level filter strips any remaining non-prose lines.
+ * 4. Markdown [Source N] artifacts and meta-discourse are cleaned.
+ *
+ * This approach handles ANY new scratchpad format without code changes,
+ * because it identifies the answer positively rather than the scratchpad
+ * negatively.
+ */
+
+export interface BoundaryResult {
+  cleaned: string;
+  removedSegments: number;
+  notes: string[];
+}
+
+// ─── Positive prose detection (what IS the answer) ──────────────────
+
+/** A line is "definitely prose" if it's a natural sentence, heading, table, or list item. */
+function isDefinitelyProse(line: string): boolean {
+  const t = line.trim();
+  if (!t) return false;
+  // Markdown heading
+  if (/^#{1,6}\s+\w/.test(t)) return true;
+  // Markdown table row
+  if (/^\|.+\|/.test(t)) return true;
+  // Bold heading line
+  if (/^\*\*[^*]+\*\*/.test(t)) return true;
+  // Numbered list item with substance
+  if (/^\d+\.\s+\S/.test(t) && t.length > 20) return true;
+  // Bullet list with substance (not a planning bullet)
+  if (/^[-*]\s+\S/.test(t) && t.length > 30 && !isPlanning(t)) return true;
+  // Natural sentence (40+ chars ending with period/exclamation/question)
+  if (t.length >= 40 && /[.!?]$/.test(t) && !isPlanning(t)) return true;
+  return false;
+}
+
+/** A line is "definitely planning/scratchpad" if it matches known patterns. */
+function isPlanning(line: string): boolean {
+  const t = line.trim();
+  // Indented asterisk planning bullets: "    *   No preamble"
+  if (/^\s{2,}\*\s{2,}/.test(line)) return true;
+  // Planning labels
+  const labels = [
+    /^\*?\s*(current (date|state)|target window|style persona|output (format|structure|template)|persona|constraints?|plan|direct answer|goal|old info|new info|the unknown|drafting|check against|sentence \d|bottom[- ]line|self[- ]correction|crucial|observation|decision|refining|addressing|wait[,!]|role|style mode|output rules)/i,
+    /^\*?\s*\*[A-Z][^*]*:\*/,
+    /^(?:wait|hmm|let me|ok so|actually|self-correction|self-eval|evaluation)/i,
+    /\bretrieved records do not\b/i,
+    /\bi (cannot|can not|am unable to) (invent|actually|substantiate|confirm)/i,
+    /\bthis would be fabrication\b/i,
+    /\bthe prompt (says|asks|instructions?|rules?)\b/i,
+    /\b(verification|synthesis) (plan |protocol )?mode\b/i,
+    /^\s*hypotheses?\s*:\s*$/i,
+    /^\s*search quer(y|ies)\s*:\s*$/i,
+    /\bi am now proceeding to verify\b/i,
+    /\bplease wait for the (final|synthesized) (synthesis|response|answer)\b/i,
+    /\bproceeding to (verify|synthesise|synthesize|the final)\b/i,
+    /\b(operational|cognitive|reasoning) (flow|trace|ledger)\b/i,
+    /\bnon-negotiable rules\b/i,
+    /\b(humanistic|varied) phrasing\b/i,
+    /\bno preamble\b/i,
+    /\bcite inline\b/i,
+    /\b(use |applying )["“]?(the |cadenced |elegant )?(narrator|scholar|analyst|naturalist|essayist)["“]?/i,
+    /\btemporal anchor\b/i,
+    /\bverified entity sheet\b/i,
+    /\bstress position\b/i,
+    /\bcumulative sentences\b/i,
+    /\bfabrication check\b/i,
+    /\bsince i am an ai\b/i,
+    /\bsimulated (for |market |data |response |idea)/i,
+    /\bi (must|should|will) (generate|reconcile|use|provide|make sure|ensure|avoid|explicitly|start with|open with|address)/i,
+    /\b(pitfalls|alternatives|pitfalls, alternatives)\b/i,
+    /\b(factor 1|factor 2|factor 3)\b/i,
+  ];
+  for (const re of labels) if (re.test(t)) return true;
+  return false;
+}
+
+/**
+ * Find the final prose block by scanning backward from the end.
+ * Returns the index of the first line of the final contiguous prose block.
+ */
+function findFinalProseStart(lines: string[]): number {
+  // Walk backward from the end, skipping blanks, to find the last prose line.
+  let lastProse = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (isDefinitelyProse(lines[i])) {
+      lastProse = i;
+      break;
+    }
+  }
+  if (lastProse < 0) return 0; // no prose found, keep everything
+
+  // Now walk backward from lastProse to find where the prose block starts.
+  // Allow up to 2 blank lines or short transitional lines between prose lines.
+  let start = lastProse;
+  let gapCount = 0;
+  for (let i = lastProse - 1; i >= 0; i--) {
+    const t = lines[i].trim();
+    if (isDefinitelyProse(lines[i])) {
+      start = i;
+      gapCount = 0;
+    } else if (!t) {
+      gapCount++;
+      if (gapCount <= 2) {
+        start = i; // blank lines between prose paragraphs are ok
+      } else {
+        break; // more than 2 consecutive blanks = end of prose block
+      }
+    } else if (isPlanning(lines[i])) {
+      break; // hit a planning line = end of prose block going backward
+    } else {
+      // Ambiguous line (short, not clearly prose or planning)
+      // If it's short (<30 chars) and between prose, include it
+      if (t.length < 30) {
+        gapCount++;
+        if (gapCount <= 2) start = i;
+        else break;
+      } else {
+        start = i; // medium-length non-planning line, probably prose
+        gapCount = 0;
+      }
+    }
+  }
+  return start;
+}
+
+// ─── Tag patterns and meta-discourse (same as before) ───────────────
+
+const TAG_PATTERNS: RegExp[] = [
+  /\((?:L\d+(?:\/L\d+)?(?:,\s*L\d+(?:\/L\d+)?)*)\)/g,
+  /\(simulated for [A-Z][a-z]+ 20\d\d\)/g,
+  /\(simulated\)/gi,
+];
+
+const META_DISCOURSE: RegExp[] = [
+  /based on the (?:provided )?(?:data|search results?|payload|json|sources?)/gi,
+  /according to the (?:search|retriev|payload|sources?)/gi,
+  /the retrieved (?:documents?|records?) (?:do not provide|shows?|indicates?|states?)/gi,
+  /as (?:an?|the) ai[,.]?/gi,
+  /\bin conclusion[,.]?/gi,
+  /\(self[-\s]?correction:[^)]*\)/gi,
+];
+
+// ─── Main entry point ───────────────────────────────────────────────
+
+export function cleanOutput(raw: string): BoundaryResult {
+  let s = raw.replace(/\r\n/g, "\n");
+  const notes: string[] = [];
+  let removed = 0;
+
+  // 1. If the model used <final_answer> tags, prefer those.
+  const tagged = s.match(/<final_answer>([\s\S]*?)(?:<\/final_answer>|$)/i);
+  if (tagged) {
+    notes.push("extracted <final_answer> tag");
+    s = tagged[1].trim();
+  } else {
+    // 2. Inverted approach: find the final prose block and discard the rest.
+    const lines = s.split("\n");
+    const proseStart = findFinalProseStart(lines);
+    if (proseStart > 0) {
+      removed += proseStart;
+      notes.push(`inverted boundary: dropped ${proseStart} pre-prose lines`);
+      s = lines.slice(proseStart).join("\n").trim();
+    }
+  }
+
+  // 3. Line-level filter: drop any remaining planning lines.
+  const linesBefore = s.split("\n");
+  const filtered = linesBefore.filter(line => !isPlanning(line));
+  if (filtered.length < linesBefore.length) {
+    const diff = linesBefore.length - filtered.length;
+    removed += diff;
+    notes.push(`stripped ${diff} residual planning lines`);
+  }
+  s = filtered.join("\n");
+
+  // 4. Strip raw [Source N] / [Source N, M] artifacts and tag patterns.
+  s = s.replace(/\[Source\s*\d+(?:\s*,\s*(?:Source\s*)?\d+)*\s*\]/gi, "");
+  for (const re of TAG_PATTERNS) s = s.replace(re, "");
+
+  // 5. Strip meta-discourse.
+  for (const re of META_DISCOURSE) s = s.replace(re, "");
+
+  // 6. Strip leaked XML/HTML structural tags (<paragraph>, <section>, <div>, etc.)
+  s = s.replace(/<\/?(paragraph|section|div|span|p|article|header|footer|main)\s*\/?>/gi, "");
+
+  // 7. Strip <scratchpad>...</scratchpad> and <final_response>...</final_response> wrapper tags
+  s = s.replace(/<\/?(scratchpad|final_response|thinking|chain_of_thought|cot)\s*>/gi, "");
+
+  // 8. Flag unpopulated placeholders inline
+  let placeholderCount = 0;
+  s = s.replace(/\[([^\]\n]{2,80})\]/g, (match, inner) => {
+    const v = String(inner).trim();
+    if (/^source\s*\d+$/i.test(v) || /^\d+$/.test(v)) return match;
+    if (/^(?:list of|description of|insert|tbd|placeholder|to be |fill in|add |provide |your )/i.test(v)) {
+      placeholderCount++;
+      return `⚠️ PLACEHOLDER: ${v}`;
+    }
+    return match;
+  });
+  if (placeholderCount > 0) {
+    notes.push(`flagged ${placeholderCount} unpopulated template placeholder(s)`);
+  }
+
+  // 9. PI-NAME REDACTION GATE — never emit invented Principal Investigator names.
+  // Replace any "PI: Dr. Jane Doe" / "Principal Investigator: John Smith" /
+  // "led by Dr. X" patterns with a neutral placeholder.
+  let piRedactions = 0;
+  s = s.replace(/\b(Principal Investigator|PI|Lead Investigator|Co-?PI|Project Director)\s*[:\-]\s*(Dr\.?\s+)?[A-Z][a-z]+(?:\s+[A-Z]\.?)?(?:\s+[A-Z][a-z]+)+/g, (m) => {
+    piRedactions++;
+    const role = m.split(/[:\-]/)[0].trim();
+    return `${role}: [To be designated]`;
+  });
+  s = s.replace(/\b(led by|headed by|directed by)\s+(Dr\.?\s+)?[A-Z][a-z]+(?:\s+[A-Z]\.?)?\s+[A-Z][a-z]+/g, (m) => {
+    piRedactions++;
+    const verb = m.split(/\s+/)[0] + " " + m.split(/\s+/)[1];
+    return `${verb} the designated Principal Investigator`;
+  });
+  if (piRedactions > 0) {
+    notes.push(`redacted ${piRedactions} invented PI name(s)`);
+  }
+
+  s = s.replace(/\n{3,}/g, "\n\n").trim();
+  return { cleaned: s, removedSegments: removed, notes };
+}

package/src/lib/overrides/vite-native-chaos-harness.ts

@@ -0,0 +1,154 @@
+/**
+ * vite-native-chaos-harness.ts — L5: Deterministic SSRF/NUL Fuzzing
+ * Uses deterministic PRNG to generate and test malicious inputs.
+ * Zero-dependency: pure TypeScript.
+ */
+
+export interface ChaosResult {
+  passed: boolean;
+  blocked: number;
+  escaped: number;
+  total: number;
+  failures: string[];
+  ts: number;
+}
+
+// ── Deterministic PRNG: XorShift32 ───────────────────────────────────────
+// Hand-trace for seed 0x0badc0de:
+//   let s = 0x0badc0de
+//   Step 1: s ^= (s << 13)  = s ^ (s * 2^13) [32-bit truncated]
+//     0x0badc0de << 13 in 32-bit: 0x0badc0de * 8192 mod 2^32
+//     0x0badc0de = 196362462 decimal
+//     196362462 * 8192 = 1608868429824 = 0x176_7A37_0000 — lower 32 bits = 0x7A370000 BUT need XOR
+//     Actually: (196362462 * 8192) >>> 0 = (0x0badc0de0000 >> 16 lower 32 bits)
+//     Let s = seed, result s ^= (s << 13) truncated to 32 bits
+//   This is standard XorShift32 — produces deterministic non-zero sequence
+export function xorshift32(seed: number): () => number {
+  // Must use 32-bit arithmetic
+  let s = seed >>> 0;
+  if (s === 0) s = 1; // XorShift must not start at 0
+  return () => {
+    // Standard XorShift32 algorithm
+    s ^= (s << 13) >>> 0;
+    s ^= (s >>> 17);
+    s ^= (s << 5) >>> 0;
+    s = s >>> 0; // Enforce uint32
+    return s;
+  };
+}
+
+// ── Malicious URL Corpus ───────────────────────────────────────────────────
+// These are the canonical SSRF attack vectors the system MUST block
+const MALICIOUS_URLS: Array<{ url: string; expectedBlock: string }> = [
+  // NUL byte injection — caught by Step 1
+  { url: 'http://127.0.0.1%00.evil.com', expectedBlock: 'NUL byte' },
+  { url: 'http://evil.com%00@127.0.0.1/', expectedBlock: 'NUL byte' },
+  // Gopher protocol (can be used to access Redis, etc.)
+  { url: 'gopher://127.0.0.1:6379/_PING', expectedBlock: 'protocol' },
+  // AWS metadata endpoint
+  { url: 'http://169.254.169.254/latest/meta-data/', expectedBlock: 'blocked IP' },
+  // GCP metadata
+  { url: 'http://metadata.google.internal/computeMetadata/v1/', expectedBlock: 'blocked host' },
+  // IPv4-mapped IPv6 — must extract and check embedded IPv4
+  { url: 'http://[::ffff:127.0.0.1]/', expectedBlock: 'blocked IP' },
+  // Direct loopback
+  { url: 'http://127.0.0.1/', expectedBlock: 'blocked IP' },
+  { url: 'http://0.0.0.0/', expectedBlock: 'blocked IP' },
+  // Link-local
+  { url: 'http://169.254.0.1/', expectedBlock: 'blocked IP' },
+  // RFC 1918 private ranges
+  { url: 'http://10.0.0.1/', expectedBlock: 'blocked IP' },
+  { url: 'http://192.168.1.1/', expectedBlock: 'blocked IP' },
+  { url: 'http://172.16.0.1/', expectedBlock: 'blocked IP' },
+  // localhost variants
+  { url: 'http://localhost/', expectedBlock: 'blocked host' },
+  { url: 'http://localhost.localdomain/', expectedBlock: 'blocked host' },
+  // Credentialed URLs
+  { url: 'http://admin:password@127.0.0.1/', expectedBlock: 'credentials' },
+  // Carrier-grade NAT
+  { url: 'http://100.64.0.1/', expectedBlock: 'blocked IP' },
+];
+
+// ── Test runner: requires prepTarget function from scraper ────────────────
+// The chaos harness calls the actual prepTarget implementation to verify
+// 100% of malicious inputs are blocked
+
+export async function runChaosTests(prepTarget: (url: string) => Promise<unknown>): Promise<ChaosResult> {
+  const ts = Date.now();
+  const failures: string[] = [];
+  let blocked = 0;
+  let escaped = 0;
+
+  // Use deterministic PRNG to shuffle corpus — reproducible test order
+  const prng = xorshift32(0x0badc0de);
+  const shuffled = [...MALICIOUS_URLS].sort(() => (prng() % 2 === 0 ? 1 : -1));
+
+  for (const { url, expectedBlock } of shuffled) {
+    try {
+      await prepTarget(url);
+      // If we get here, the URL was NOT blocked — security failure
+      escaped++;
+      failures.push(`SSRF ESCAPE: "${url}" was not blocked (expected: ${expectedBlock})`);
+    } catch (e: any) {
+      // Expected: prepTarget should throw for all malicious URLs
+      blocked++;
+    }
+  }
+
+  // Additional fuzz test: generate random mutations of malicious URLs
+  const prng2 = xorshift32(0xdeadbeef);
+  const extraMalicious = [
+    `http://127.${prng2() % 256}.${prng2() % 256}.${prng2() % 256}/`,
+    `http://192.168.${prng2() % 256}.${prng2() % 256}/sensitive`,
+    `http://10.${prng2() % 256}.${prng2() % 256}.${prng2() % 256}:8080/`,
+  ];
+
+  for (const url of extraMalicious) {
+    try {
+      await prepTarget(url);
+      escaped++;
+      failures.push(`SSRF ESCAPE (fuzz): "${url}" was not blocked`);
+    } catch {
+      blocked++;
+    }
+  }
+
+  const total = shuffled.length + extraMalicious.length;
+
+  return {
+    passed: escaped === 0 && blocked === total,
+    blocked,
+    escaped,
+    total,
+    failures,
+    ts,
+  };
+}
+
+// ── Offline corpus test (no prepTarget needed) ────────────────────────────
+// Tests only the URL parsing logic without making DNS calls
+export function runOfflineChaosTests(): { passed: boolean; failures: string[] } {
+  const failures: string[] = [];
+
+  // Test NUL detection
+  const nulUrls = ['http://127.0.0.1%00.evil.com', 'http://evil.com\x00test'];
+  for (const url of nulUrls) {
+    const hasNul = url.includes('\0') || /%00/i.test(url);
+    if (!hasNul) failures.push(`NUL detection missed: ${url}`);
+  }
+
+  // Test credential detection
+  try {
+    const u = new URL('http://admin:password@127.0.0.1/');
+    if (!u.username || !u.password) failures.push('URL parser did not detect credentials');
+  } catch {}
+
+  // Test blocked host detection
+  const blockedHosts = ['localhost', 'metadata.google.internal', 'test.localhost'];
+  for (const host of blockedHosts) {
+    const isBlocked = host === 'localhost' || host.endsWith('.localhost') || host === 'metadata.google.internal';
+    if (!isBlocked) failures.push(`Host ${host} should be blocked`);
+  }
+
+  return { passed: failures.length === 0, failures };
+}

package/src/lib/overrides/vite-native-contract-plane.ts

@@ -0,0 +1,245 @@
+/**
+ * vite-native-contract-plane.ts — L3: OpenAPI 3.1 & RFC 9457 Schemas
+ * Zero-dependency: pure TypeScript objects.
+ */
+
+// ── RFC 9457 Problem Details ──────────────────────────────────────────────
+export const PROBLEM_TYPES = {
+  missing_query: {
+    type: 'https://vite-native-gateway/problems/missing-query',
+    title: 'Missing Required Query Parameter',
+    status: 400,
+    detail: "The 'q' query parameter is required and was not provided.",
+  },
+  ssrf_blocked: {
+    type: 'https://vite-native-gateway/problems/ssrf-blocked',
+    title: 'SSRF Target Blocked',
+    status: 400,
+    detail: 'The requested URL was blocked by the SSRF protection policy.',
+  },
+  rate_limited: {
+    type: 'https://vite-native-gateway/problems/rate-limited',
+    title: 'Rate Limit Exceeded',
+    status: 429,
+    detail: 'Too many requests. Please slow down and retry after a moment.',
+  },
+  upstream_failed: {
+    type: 'https://vite-native-gateway/problems/upstream-failed',
+    title: 'Upstream Search Engine Failed',
+    status: 502,
+    detail: 'All search engine backends returned errors. Retry later.',
+  },
+  internal_error: {
+    type: 'https://vite-native-gateway/problems/internal-error',
+    title: 'Internal Server Error',
+    status: 500,
+    detail: 'An unexpected internal error occurred.',
+  },
+  agent_loop: {
+    type: 'https://vite-native-gateway/problems/agent-loop',
+    title: 'Agent Loop Detected',
+    status: 429,
+    detail: 'The same URL has been requested too many times in a short period.',
+  },
+  cross_origin: {
+    type: 'https://vite-native-gateway/problems/cross-origin',
+    title: 'Cross-Origin Request Rejected',
+    status: 403,
+    detail: 'Cross-origin requests to the local gateway are not permitted.',
+  },
+} as const;
+
+export type ProblemType = keyof typeof PROBLEM_TYPES;
+
+export function makeProblem(type: ProblemType, extra?: Partial<{ detail: string; instance: string }>): object {
+  const base = PROBLEM_TYPES[type];
+  return {
+    ...base,
+    ...(extra?.detail && { detail: extra.detail }),
+    ...(extra?.instance && { instance: extra.instance }),
+  };
+}
+
+// ── OpenAPI 3.1 Document ──────────────────────────────────────────────────
+export function getNativeOpenApiDocument(baseUrl: string): object {
+  const problemSchema = {
+    type: 'object',
+    properties: {
+      type: { type: 'string', format: 'uri' },
+      title: { type: 'string' },
+      status: { type: 'integer' },
+      detail: { type: 'string' },
+      instance: { type: 'string', format: 'uri' },
+    },
+    required: ['type', 'title', 'status'],
+  };
+
+  const problemResponse = {
+    description: 'RFC 9457 Problem Details',
+    content: { 'application/problem+json': { schema: { $ref: '#/components/schemas/Problem' } } },
+  };
+
+  return {
+    openapi: '3.1.0',
+    jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',
+    info: {
+      title: 'Vite Native Knowledge Gateway',
+      version: '1.0.0',
+      description: 'Zero-dependency local metasearch engine and knowledge store.',
+    },
+    servers: [{ url: baseUrl }],
+    paths: {
+      '/api/native-search': {
+        get: {
+          summary: 'Metasearch across multiple engines with RRF+MMR ranking',
+          parameters: [
+            { name: 'q', in: 'query', required: true, schema: { type: 'string', minLength: 1 } },
+            { name: 'count', in: 'query', required: false, schema: { type: 'integer', minimum: 1, maximum: 20, default: 5 } },
+            { name: 'engines', in: 'query', required: false, schema: { type: 'string' } },
+          ],
+          responses: {
+            '200': { description: 'Search results', content: { 'application/json': { schema: { type: 'object' } } } },
+            '400': { $ref: '#/components/responses/Problem' },
+            '429': { $ref: '#/components/responses/Problem' },
+            '502': { $ref: '#/components/responses/Problem' },
+          },
+        },
+      },
+      '/api/native-search/stream': {
+        get: {
+          summary: 'SSE streaming search results',
+          parameters: [
+            { name: 'q', in: 'query', required: true, schema: { type: 'string' } },
+            { name: 'count', in: 'query', required: false, schema: { type: 'integer', minimum: 1, maximum: 20 } },
+          ],
+          responses: {
+            '200': { description: 'SSE stream', content: { 'text/event-stream': { schema: { type: 'string' } } } },
+            '400': { $ref: '#/components/responses/Problem' },
+            '429': { $ref: '#/components/responses/Problem' },
+          },
+        },
+      },
+      '/api/native-read': {
+        get: {
+          summary: 'Fetch and extract text content from a URL (SSRF-protected)',
+          parameters: [
+            { name: 'url', in: 'query', required: true, schema: { type: 'string', format: 'uri' } },
+          ],
+          responses: {
+            '200': { description: 'Page content', content: { 'application/json': { schema: { type: 'object' } } } },
+            '400': { $ref: '#/components/responses/Problem' },
+          },
+        },
+      },
+      '/api/native-ingest': {
+        post: {
+          summary: 'Ingest content into the knowledge store',
+          requestBody: {
+            required: true,
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    kind: { type: 'string' },
+                    ref: { type: 'string' },
+                    summary: { type: 'string' },
+                  },
+                  required: ['kind', 'ref', 'summary'],
+                },
+              },
+            },
+          },
+          responses: {
+            '200': { description: 'Ingest result', content: { 'application/json': { schema: { type: 'object' } } } },
+            '400': { $ref: '#/components/responses/Problem' },
+          },
+        },
+      },
+      '/api/native-knowledge': {
+        get: {
+          summary: 'Search the knowledge store',
+          parameters: [
+            { name: 'q', in: 'query', required: true, schema: { type: 'string' } },
+            { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 100 } },
+          ],
+          responses: {
+            '200': { description: 'Knowledge records', content: { 'application/json': { schema: { type: 'object' } } } },
+          },
+        },
+      },
+      '/api/native-knowledge/repair-index': {
+        post: {
+          summary: 'Rebuild FTS5 index',
+          responses: { '200': { description: 'Repair result' } },
+        },
+      },
+      '/api/audit/verify': {
+        get: {
+          summary: 'Verify audit log integrity',
+          responses: { '200': { description: 'Audit verification result' } },
+        },
+      },
+      '/api/native-doctor': {
+        get: {
+          summary: 'Aggregated health report',
+          parameters: [
+            { name: 'deep', in: 'query', schema: { type: 'boolean' } },
+          ],
+          responses: { '200': { description: 'Doctor report' } },
+        },
+      },
+      '/api/native-selftest': {
+        get: {
+          summary: 'Run static self-tests',
+          responses: { '200': { description: 'Self-test results' } },
+        },
+      },
+      '/api/native-selftest/functional': {
+        get: {
+          summary: 'Run functional golden-fixture tests',
+          responses: { '200': { description: 'Functional test results' } },
+        },
+      },
+      '/api/native-policy': {
+        get: { summary: 'Get all policy flags', responses: { '200': { description: 'Policy flags' } } },
+        post: { summary: 'Set a policy flag', responses: { '200': { description: 'Policy update result' } } },
+      },
+      '/api/native-snapshot': {
+        post: { summary: 'Create hot backup', responses: { '200': { description: 'Snapshot result' } } },
+        get: { summary: 'Get snapshot manifest', responses: { '200': { description: 'Snapshot manifest' } } },
+      },
+      '/api/native-maintenance/run': {
+        post: { summary: 'Run SQLite maintenance', responses: { '200': { description: 'Maintenance result' } } },
+      },
+      '/api/native-runtime': {
+        get: { summary: 'Get runtime stats', responses: { '200': { description: 'Runtime stats' } } },
+      },
+    },
+    components: {
+      schemas: { Problem: problemSchema },
+      responses: { Problem: problemResponse },
+    },
+  };
+}
+
+// ── Contract Self-Test ────────────────────────────────────────────────────
+export function contractSelfTest(): { passed: boolean; failures: string[] } {
+  const failures: string[] = [];
+  const doc = getNativeOpenApiDocument('http://localhost:5173') as any;
+
+  if (doc.openapi !== '3.1.0') failures.push('openapi version must be 3.1.0');
+  if (!doc.jsonSchemaDialect) failures.push('jsonSchemaDialect missing');
+  if (!doc.paths['/api/native-search']) failures.push('/api/native-search path missing');
+  if (!doc.paths['/api/native-read']) failures.push('/api/native-read path missing');
+  if (!doc.paths['/api/native-ingest']) failures.push('/api/native-ingest path missing');
+  if (!doc.components?.schemas?.Problem) failures.push('Problem schema missing from components');
+  if (!doc.components?.responses?.Problem) failures.push('Problem response missing from components');
+
+  // Verify query param type precision
+  const searchParams = doc.paths['/api/native-search']?.get?.parameters;
+  const countParam = searchParams?.find((p: any) => p.name === 'count');
+  if (countParam?.schema?.type !== 'integer') failures.push('count param must be type:integer not type:number');
+
+  return { passed: failures.length === 0, failures };
+}