@company-semantics/contracts 98.0.0 → 99.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "98.0.0",
+  "version": "99.0.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '51e9ee445972' as const;
-export const SPEC_HASH_FULL = '51e9ee445972ebf381cd85489343494ecdd81453574bbec8696a038ef4fd327f' as const;
+export const SPEC_HASH = '935ee995d53d' as const;
+export const SPEC_HASH_FULL = '935ee995d53d56538f0566bb3c1372041d5cb1def41f3b28db02716ad4d8c591' as const;

package/src/api/generated.ts

@@ -421,6 +421,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chats/{id}/branch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Make one version of a turn the active branch */
+        post: operations["selectChatBranch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/chats/{id}/pin": {
         parameters: {
             query?: never;
@@ -5719,6 +5736,10 @@ export interface components {
             title: string;
             isAutoGenerated: boolean;
         };
+        ChatBranchSelectRequest: {
+            /** Format: uuid */
+            messageId: string;
+        };
         ChatSseEvent: {
             /** @constant */
             v: 1;
@@ -5987,14 +6008,16 @@ export interface components {
         ChatMessageFeedbackResponse: {
             /** @enum {string} */
             rating: "up" | "down";
-            reason: string | null;
+            reason: ("incorrect" | "didnt_follow_instructions" | "not_helpful" | "missing_context" | "tool_or_workflow_issue" | "other") | null;
             /** Format: date-time */
             updatedAt: string;
         };
         PutChatMessageFeedbackRequest: {
             /** @enum {string} */
             rating: "up" | "down";
-            reason?: string;
+            /** @enum {string} */
+            reason?: "incorrect" | "didnt_follow_instructions" | "not_helpful" | "missing_context" | "tool_or_workflow_issue" | "other";
+            comment?: string;
         };
         WorkspaceAccessResponse: {
             hasAccess: boolean;
@@ -12463,6 +12486,32 @@ export interface operations {
             };
         };
     };
+    selectChatBranch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ChatBranchSelectRequest"];
+            };
+        };
+        responses: {
+            /** @description The chat with its new active branch */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GetChatResponse"];
+                };
+            };
+        };
+    };
     pinChat: {
         parameters: {
             query?: never;

package/src/chat/__tests__/runtime-profile.test.ts

@@ -81,13 +81,31 @@ function backendAgenticModelDefault(): string {
   );
 }
 
-/** The chat model the factory declares to the provider resolver. */
+/**
+ * The chat model the factory declares to the provider resolver. The factory's
+ * CHAT_DEFAULT_MODEL reads `modelFor('chat.default')`, so the id lives on the
+ * `chat.default` entry of the backend's model use-site registry.
+ *
+ * Until backend PRD-01163 lands on its origin/main, the resolved backend (a
+ * detached checkout such as the PR gate reads origin/main) has no registry and
+ * still declares the literal in factory.ts. Read whichever declaration the
+ * resolved backend actually has — parity is asserted either way. Drop the
+ * factory.ts branch once the registry is on backend main.
+ */
 function backendChatModelDefault(): string {
+  if (!backend!.exists("src/runtimes/models/use-sites.ts")) {
+    return extractDeclaration(
+      readBackendSource("src", "chat", "orchestrator", "factory.ts"),
+      /CHAT_DEFAULT_MODEL\s*=\s*['"]([^'"]+)['"]/,
+      "CHAT_DEFAULT_MODEL",
+      "src/chat/orchestrator/factory.ts",
+    );
+  }
   return extractDeclaration(
-    readBackendSource("src", "chat", "orchestrator", "factory.ts"),
-    /CHAT_DEFAULT_MODEL\s*=\s*['"]([^'"]+)['"]/,
-    "CHAT_DEFAULT_MODEL",
-    "src/chat/orchestrator/factory.ts",
+    readBackendSource("src", "runtimes", "models", "use-sites.ts"),
+    /['"]chat\.default['"]\s*:\s*\{\s*modelId:\s*['"]([^'"]+)['"]/,
+    "the 'chat.default' use-site modelId",
+    "src/runtimes/models/use-sites.ts",
   );
 }
 

package/src/generated/openapi-routes.ts

@@ -28,6 +28,7 @@ export const openApiRoutes = {
   '/api/chats/proactive/{eventId}': ['GET'],
   '/api/chats/resolve-launch': ['POST'],
   '/api/chats/{id}': ['DELETE', 'GET', 'PATCH'],
+  '/api/chats/{id}/branch': ['POST'],
   '/api/chats/{id}/generate-title': ['POST'],
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],

package/src/ingestion/README.md

@@ -1,49 +1,79 @@
 # ingestion/
 
-Shared vocabulary for the document-ingestion accept-set.
+Shared vocabulary for the one ingestion pipeline: formats, surfaces, providers.
 
 ## Purpose
 
-The single source of truth for which file formats the platform accepts for
-upload — their MIME types, filename extensions, human label groups, and
-per-format byte caps. The backend normalizer joins these entries with its
-private dispatch table; the app upload UI derives its file-input `accept`
-attribute and supported-formats copy from the same data.
+The single source of truth for which files the platform ingests and what each
+surface does with them. The format registry names every accepted format — its
+MIME type, filename extensions, family, class, human label group and byte cap.
+The surface declarations say, per consuming surface (company-md, org-chart,
+chat, profile-image), which treatment each admitted family gets and the byte
+ceiling. The provider vocabulary names the native types an external source
+(Google Drive) hands the pipeline and the registry format each exports to. The
+backend normalizer, discovery and the app upload UI derive everything they need
+from these three declarations.
 
 ## Invariants
 
 - `INGESTION_FORMATS` is the canonical list; `mime` is unique across entries.
-- Entries are ordered text → documents → images/diagrams → audio/video. The
+  Entries are ordered text → documents → images/diagrams → audio/video; the
   backend's MIME-order test and the derived UI strings depend on this order.
-- `INGEST_ACCEPT` and `SUPPORTED_LABEL` are **derived** from the registry, never
-  hand-maintained — adding a format updates both automatically.
+- Every format carries a `family` and a required `class` (`FormatClass`:
+  `docs | slides | sheets | pdf | text | image | diagram | audio | video`). No
+  consumer keeps its own extension → class table.
+- A surface (`INGESTION_SURFACES`) declares `treatments` — family →
+  `text | vision | transcript | store` — and a required `maxBytes`.
+  `familiesOf`, `formatsFor`, `surfaceAdmits`, `treatmentFor`, `acceptFor`,
+  `supportedLabelFor` and `maxBytesFor` are **derived** from that declaration.
+  Treatments are per family, never per format.
+- `vision` means the richest native form: images as images, a PDF as a binary
+  document, text-native formats as text.
+- A provider (`INGESTION_PROVIDERS`) declares its native types, their export
+  targets and labels, and its container MIMEs. `providerFormatsFor`,
+  `classOfMime`, `inventoryClassesFor` and `labelOfMime` are **derived**.
+- `acceptFor` emits extensions and MIMEs (".png,image/png,…"), so a
+  MIME-only matcher can use the same string as a file-input `accept`.
+- Nothing outside this domain names a MIME, an extension or a provider-native
+  type; consumers ask these helpers (ADR slug `single-ingestion-pipeline`).
 - No normalizer-routing fields here (`canonicalKind`, `normalizerKey` are
-  backend-only). This package stays pure vocabulary.
-- Every entry carries a `family`; `INGESTION_SURFACES` declares which families
-  each upload surface admits, and `formatsFor` / `acceptFor` /
-  `supportedLabelFor` / `maxBytesFor` are **derived** from that declaration
-  (ADR-CONTRACTS-159). A surface never re-spells a MIME.
+  backend-only). This package stays pure vocabulary
+  (ADR slug `ingestion-surface-treatments-and-providers`).
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
 
+- `FORMAT_CLASSES` — The coarse, provider-agnostic kind of a format, used wherever the system classes a file without reading it…
+- `FormatClass` _(type)_
 - `INGESTION_FORMATS` — The canonical public format registry.
-- `INGESTION_SURFACES` — The canonical surface declarations. - `company-md`: context-bank and goals extraction.
-- `INGEST_ACCEPT` — Comma-joined extension string for a file input's `accept` attribute.
+- `INGESTION_PROVIDERS` — Every provider's native types and container MIMEs, keyed by provider.
+- `INGESTION_SURFACES` — The canonical surface declarations. - `company-md`: context bank, goals extraction, Source Sync landing.
 - `IngestionFamily` _(type)_ — The semantic family a format belongs to.
 - `IngestionFormat` _(type)_ — One accepted upload format, keyed by its canonical MIME type.
-- `IngestionSurface` _(type)_ — What one upload surface consumes: the families it admits and, optionally, a byte ceiling tighter than the…
-- `IngestionSurfaceKey` _(type)_ — The upload surfaces that consume the registry.
-- `SUPPORTED_LABEL` — Human-readable supported-formats summary, derived from {@link humanLabels}.
+- `IngestionProvider` _(type)_ — One provider: its native types and the structural container MIMEs it lists.
+- `IngestionProviderKey` _(type)_ — External sources that hand the pipeline provider-native files.
+- `IngestionSurface` _(type)_ — One surface: the treatment it applies per admitted family, and its byte ceiling.
+- `IngestionSurfaceKey` _(type)_ — The surfaces that consume the registry.
+- `InventoryClass` _(type)_ — A Source Sync inventory class: a format class, or a provider shortcut row.
+- `ProviderFormat` _(type)_ — One MIME a provider can hand the pipeline, with the registry format it lands as.
+- `ProviderNativeFormat` _(type)_ — A provider-native type that is exported to a registry format before ingestion.
+- `TREATMENTS` — What a surface does with an admitted family.
+- `Treatment` _(type)_
 - `acceptExtensions` — All accepted filename extensions, in registry order.
-- `acceptFor` — Comma-joined extension string for the surface's file input `accept`.
+- `acceptFor` — The `<input accept>` value for a surface: per format, its extensions then its MIME…
 - `byMime` — Look up the entry for a canonical MIME; undefined means unsupported.
+- `classOfMime` — The class of a provider-listed MIME; null for containers and unknown types.
+- `familiesOf` — The families a surface admits, in canonical family order.
 - `formatsFor` — The registry formats a surface admits, in registry order.
 - `humanLabels` — Unique group labels for human display, in registry order.
-- `maxBytesFor` — The transport byte ceiling for a surface: the largest registry cap among its admitted formats, tightened to…
+- `inventoryClassesFor` — The inventory classes discovery can record for a provider feeding a surface, in canonical class order, plus…
+- `labelOfMime` — Display label for a MIME (provider-native first when a provider is given); null if unknown.
+- `maxBytesFor` — The transport byte ceiling: the largest registry cap among admitted formats, tightened to the (required)…
+- `providerFormatsFor` — Every MIME the provider can hand a surface (natives first, then registry order).
 - `supportedLabelFor` — "Supported: …" copy naming every label group the surface admits.
 - `surfaceAdmits` — True when the surface admits this registry format.
+- `treatmentFor` — What the surface does with this format; null = the surface refuses it.
 
 <!-- END GENERATED: readme-public-api -->
 

package/src/ingestion/__tests__/providers.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import {
+  INGESTION_PROVIDERS,
+  providerFormatsFor,
+  classOfMime,
+  inventoryClassesFor,
+  labelOfMime,
+} from "../providers";
+import { byMime } from "../registry";
+
+describe("ingestion providers", () => {
+  it("every Drive native type exports to a registry format", () => {
+    for (const n of INGESTION_PROVIDERS["google-drive"].nativeFormats) {
+      expect(byMime(n.exportsTo)).toBeDefined();
+    }
+  });
+
+  it("the company-md Drive net is the three Workspace types plus the company-md formats", () => {
+    const net = providerFormatsFor("google-drive", "company-md");
+    expect(net.slice(0, 3).map((pf) => pf.mime)).toEqual([
+      "application/vnd.google-apps.document",
+      "application/vnd.google-apps.presentation",
+      "application/vnd.google-apps.spreadsheet",
+    ]);
+    expect(net.map((pf) => pf.mime)).toContain("application/pdf");
+    expect(net.map((pf) => pf.mime)).not.toContain("image/png");
+    expect(new Set(net.map((pf) => pf.mime)).size).toBe(net.length);
+  });
+
+  it("pins the company-md inventory classes the DB CHECK carries today", () => {
+    expect(inventoryClassesFor("google-drive", "company-md")).toEqual([
+      "docs",
+      "slides",
+      "sheets",
+      "pdf",
+      "text",
+      "shortcut",
+    ]);
+  });
+
+  it("classes native, downloaded and container MIMEs", () => {
+    expect(
+      classOfMime("google-drive", "application/vnd.google-apps.spreadsheet"),
+    ).toBe("sheets");
+    expect(classOfMime("google-drive", "text/csv")).toBe("sheets");
+    expect(classOfMime("google-drive", "image/png")).toBe("image");
+    expect(
+      classOfMime("google-drive", "application/vnd.google-apps.folder"),
+    ).toBeNull();
+  });
+
+  it("labels native and registry MIMEs", () => {
+    expect(
+      labelOfMime("application/vnd.google-apps.document", "google-drive"),
+    ).toBe("Google Doc");
+    expect(labelOfMime("application/pdf")).toBe("PDF");
+    expect(labelOfMime("application/x-unknown")).toBeNull();
+  });
+});

package/src/ingestion/__tests__/registry.test.ts

@@ -1,12 +1,6 @@
 import { describe, it, expect } from "vitest";
-import {
-  INGESTION_FORMATS,
-  byMime,
-  acceptExtensions,
-  humanLabels,
-  INGEST_ACCEPT,
-  SUPPORTED_LABEL,
-} from "../registry";
+import { INGESTION_FORMATS, byMime, acceptExtensions } from "../registry";
+import { FORMAT_CLASSES } from "../types";
 
 describe("ingestion registry", () => {
   it("has a unique MIME per entry", () => {
@@ -28,17 +22,23 @@ describe("ingestion registry", () => {
     expect(byMime("application/x-unknown")).toBeUndefined();
   });
 
-  it("derives INGEST_ACCEPT from every extension in registry order", () => {
-    expect(INGEST_ACCEPT).toBe(acceptExtensions().join(","));
-    expect(INGEST_ACCEPT).toBe(
-      ".txt,.md,.html,.htm,.csv,.rtf,.docx,.doc,.pptx,.ppt,.xlsx,.xls,.odt,.ods,.odp,.epub,.pdf,.png,.jpg,.jpeg,.webp,.gif,.heic,.svg,.drawio,.mp3,.m4a,.wav,.aac,.mp4,.m4v,.mov",
-    );
+  it("every format carries a known class", () => {
+    for (const entry of INGESTION_FORMATS)
+      expect(FORMAT_CLASSES).toContain(entry.class);
   });
 
-  it("derives SUPPORTED_LABEL from the unique group labels", () => {
-    expect(SUPPORTED_LABEL).toBe(`Supported: ${humanLabels().join(", ")}`);
-    expect(SUPPORTED_LABEL).toBe(
-      "Supported: Text, Markdown, HTML, CSV, RTF, Word, PowerPoint, Excel, OpenDocument, EPUB, PDF, Image, Diagram, Audio, Video",
-    );
+  it("classes documents the way discovery does", () => {
+    expect(byMime("text/csv")!.class).toBe("sheets");
+    expect(byMime("application/epub+zip")!.class).toBe("docs");
+    expect(byMime("application/vnd.ms-powerpoint")!.class).toBe("slides");
+    expect(byMime("application/pdf")!.class).toBe("pdf");
+    expect(byMime("text/markdown")!.class).toBe("text");
+    expect(byMime("image/svg+xml")!.class).toBe("diagram");
+  });
+
+  it("admits HEIF and no longer lists drawio", () => {
+    expect(byMime("image/heif")?.family).toBe("image");
+    expect(byMime("application/vnd.jgraph.mxfile")).toBeUndefined();
+    expect(acceptExtensions()).not.toContain(".drawio");
   });
 });

package/src/ingestion/__tests__/surfaces.test.ts

@@ -1,64 +1,92 @@
 import { describe, it, expect } from "vitest";
-import { INGESTION_FORMATS, byMime } from "../registry";
+import { byMime } from "../registry";
+import { TREATMENTS } from "../types";
+import type { IngestionSurfaceKey } from "../types";
 import {
   INGESTION_SURFACES,
+  familiesOf,
+  treatmentFor,
   formatsFor,
-  surfaceAdmits,
   acceptFor,
-  supportedLabelFor,
   maxBytesFor,
 } from "../surfaces";
 
 describe("ingestion surfaces", () => {
-  it("every registry entry carries a family", () => {
-    for (const entry of INGESTION_FORMATS) {
-      expect(entry.family).toMatch(
-        /^(text|document|image|diagram|audio|video)$/,
-      );
+  it("every surface declares treatments only for real families and a positive ceiling", () => {
+    for (const key of Object.keys(
+      INGESTION_SURFACES,
+    ) as IngestionSurfaceKey[]) {
+      const s = INGESTION_SURFACES[key];
+      expect(s.key).toBe(key);
+      expect(s.maxBytes).toBeGreaterThan(0);
+      for (const [family, treatment] of Object.entries(s.treatments)) {
+        expect([
+          "text",
+          "document",
+          "image",
+          "diagram",
+          "audio",
+          "video",
+        ]).toContain(family);
+        expect(TREATMENTS).toContain(treatment);
+      }
+      expect(familiesOf(key).length).toBeGreaterThan(0);
     }
   });
 
-  it("every surface admits at least one format, in registry order", () => {
-    for (const key of Object.keys(INGESTION_SURFACES) as Array<
-      keyof typeof INGESTION_SURFACES
-    >) {
-      const formats = formatsFor(key);
-      expect(formats.length).toBeGreaterThan(0);
-      const order = formats.map((f) => INGESTION_FORMATS.indexOf(f));
-      expect(order).toEqual([...order].sort((a, b) => a - b));
-    }
+  it("company-md turns text and documents into text and refuses images and media", () => {
+    expect(treatmentFor("company-md", byMime("application/pdf")!)).toBe("text");
+    expect(treatmentFor("company-md", byMime("text/csv")!)).toBe("text");
+    expect(treatmentFor("company-md", byMime("image/png")!)).toBeNull();
+    expect(treatmentFor("company-md", byMime("audio/mpeg")!)).toBeNull();
+    expect(maxBytesFor("company-md")).toBe(50_000_000);
   });
 
-  it("company-md admits text and documents only", () => {
-    expect(surfaceAdmits("company-md", byMime("application/pdf")!)).toBe(true);
-    expect(surfaceAdmits("company-md", byMime("text/csv")!)).toBe(true);
-    expect(surfaceAdmits("company-md", byMime("image/png")!)).toBe(false);
-    expect(surfaceAdmits("company-md", byMime("audio/mpeg")!)).toBe(false);
-    expect(acceptFor("company-md")).toBe(
-      ".txt,.md,.html,.htm,.csv,.rtf,.docx,.doc,.pptx,.ppt,.xlsx,.xls,.odt,.ods,.odp,.epub,.pdf",
-    );
-    expect(supportedLabelFor("company-md")).toBe(
-      "Supported: Text, Markdown, HTML, CSV, RTF, Word, PowerPoint, Excel, OpenDocument, EPUB, PDF",
+  it("org-chart hands documents, images and diagrams to vision", () => {
+    expect(treatmentFor("org-chart", byMime("application/pdf")!)).toBe(
+      "vision",
     );
+    expect(treatmentFor("org-chart", byMime("image/heic")!)).toBe("vision");
+    expect(treatmentFor("org-chart", byMime("image/svg+xml")!)).toBe("vision");
+    expect(treatmentFor("org-chart", byMime("video/mp4")!)).toBeNull();
+    expect(maxBytesFor("org-chart")).toBe(10 * 1024 * 1024);
+  });
+
+  it("chat admits text, documents and images but never media", () => {
+    expect(treatmentFor("chat", byMime("text/markdown")!)).toBe("text");
+    expect(treatmentFor("chat", byMime("application/pdf")!)).toBe("vision");
+    expect(treatmentFor("chat", byMime("image/png")!)).toBe("vision");
+    expect(treatmentFor("chat", byMime("audio/mpeg")!)).toBeNull();
+    expect(maxBytesFor("chat")).toBe(5 * 1024 * 1024);
+  });
+
+  it("chat caps files per turn and only chat declares a per-turn count", () => {
+    expect(INGESTION_SURFACES.chat.maxFilesPerTurn).toBe(8);
+    for (const key of ["company-md", "org-chart", "profile-image"] as const) {
+      expect(INGESTION_SURFACES[key].maxFilesPerTurn).toBeUndefined();
+    }
   });
 
-  it("org-chart adds images and diagrams but never media", () => {
-    expect(surfaceAdmits("org-chart", byMime("image/heic")!)).toBe(true);
-    expect(surfaceAdmits("org-chart", byMime("image/svg+xml")!)).toBe(true);
-    expect(surfaceAdmits("org-chart", byMime("video/mp4")!)).toBe(false);
-    expect(acceptFor("org-chart")).toBe(
-      ".txt,.md,.html,.htm,.csv,.rtf,.docx,.doc,.pptx,.ppt,.xlsx,.xls,.odt,.ods,.odp,.epub,.pdf,.png,.jpg,.jpeg,.webp,.gif,.heic,.svg,.drawio",
+  it("profile-image stores images only", () => {
+    expect(familiesOf("profile-image")).toEqual(["image"]);
+    expect(treatmentFor("profile-image", byMime("image/heif")!)).toBe("store");
+    expect(acceptFor("profile-image")).toBe(
+      ".png,image/png,.jpg,.jpeg,image/jpeg,.webp,image/webp,.gif,image/gif,.heic,image/heic,.heif,image/heif",
     );
+    expect(maxBytesFor("profile-image")).toBe(5 * 1024 * 1024);
   });
 
-  it("derives the byte ceiling from the admitted formats and the surface cap", () => {
-    expect(maxBytesFor("company-md")).toBe(50_000_000);
-    expect(maxBytesFor("org-chart")).toBe(10 * 1024 * 1024);
-    for (const key of ["company-md", "org-chart"] as const) {
-      const ceiling = INGESTION_SURFACES[key].maxBytes ?? Infinity;
-      expect(maxBytesFor(key)).toBeLessThanOrEqual(ceiling);
+  it("acceptFor lists every admitted extension and MIME, in registry order", () => {
+    for (const key of Object.keys(
+      INGESTION_SURFACES,
+    ) as IngestionSurfaceKey[]) {
+      const tokens = acceptFor(key).split(",");
+      for (const f of formatsFor(key)) {
+        expect(tokens).toContain(f.mime);
+        for (const ext of f.extensions) expect(tokens).toContain(ext);
+      }
       expect(maxBytesFor(key)).toBeLessThanOrEqual(
-        Math.max(...formatsFor(key).map((f) => f.maxBytes)),
+        INGESTION_SURFACES[key].maxBytes,
       );
     }
   });

package/src/ingestion/index.ts

@@ -13,22 +13,40 @@ export type {
   IngestionFormat,
   IngestionSurface,
   IngestionSurfaceKey,
+  FormatClass,
+  InventoryClass,
+  Treatment,
+  IngestionProvider,
+  IngestionProviderKey,
+  ProviderNativeFormat,
 } from "./types";
 
+export { FORMAT_CLASSES, TREATMENTS } from "./types";
+
 export {
   INGESTION_FORMATS,
   byMime,
   acceptExtensions,
   humanLabels,
-  INGEST_ACCEPT,
-  SUPPORTED_LABEL,
 } from "./registry";
 
 export {
   INGESTION_SURFACES,
+  familiesOf,
+  treatmentFor,
   formatsFor,
   surfaceAdmits,
   acceptFor,
   supportedLabelFor,
   maxBytesFor,
 } from "./surfaces";
+
+export type { ProviderFormat } from "./providers";
+
+export {
+  INGESTION_PROVIDERS,
+  providerFormatsFor,
+  classOfMime,
+  inventoryClassesFor,
+  labelOfMime,
+} from "./providers";

package/src/ingestion/providers.ts

@@ -0,0 +1,141 @@
+/**
+ * Ingestion Providers
+ *
+ * Provider vocabulary: the native types an external source hands us (exported
+ * to a registry format before ingestion) and its structural container MIMEs.
+ * Discovery's net, the Drive picker filter, inventory classes and display
+ * labels all derive from this plus the surface declarations — no backend or
+ * app module keeps its own Workspace MIME table.
+ */
+import { INGESTION_FORMATS, byMime } from "./registry";
+import { surfaceAdmits } from "./surfaces";
+import {
+  FORMAT_CLASSES,
+  type FormatClass,
+  type IngestionFormat,
+  type IngestionProvider,
+  type IngestionProviderKey,
+  type IngestionSurfaceKey,
+  type InventoryClass,
+  type ProviderNativeFormat,
+} from "./types";
+
+/** Every provider's native types and container MIMEs, keyed by provider. */
+export const INGESTION_PROVIDERS: Readonly<
+  Record<IngestionProviderKey, IngestionProvider>
+> = {
+  "google-drive": {
+    key: "google-drive",
+    nativeFormats: [
+      {
+        mime: "application/vnd.google-apps.document",
+        label: "Google Doc",
+        exportsTo:
+          "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      },
+      {
+        mime: "application/vnd.google-apps.presentation",
+        label: "Google Slides",
+        exportsTo:
+          "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      },
+      {
+        mime: "application/vnd.google-apps.spreadsheet",
+        label: "Google Sheet",
+        exportsTo:
+          "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      },
+    ],
+    containerMimes: {
+      folder: "application/vnd.google-apps.folder",
+      shortcut: "application/vnd.google-apps.shortcut",
+    },
+  },
+};
+
+/** One MIME a provider can hand the pipeline, with the registry format it lands as. */
+export interface ProviderFormat {
+  /** The MIME as the provider lists it (native or a registry MIME). */
+  mime: string;
+  /** True for a provider-native type that is exported before ingestion. */
+  native: boolean;
+  /** The registry format the bytes arrive as (the export target for natives). */
+  format: IngestionFormat;
+  /** Display label: the native label, else the registry label. */
+  label: string;
+}
+
+function exportTarget(native: ProviderNativeFormat): IngestionFormat {
+  const target = byMime(native.exportsTo);
+  if (!target) {
+    throw new Error(
+      `ingestion provider: ${native.mime} exports to ${native.exportsTo}, which is not in INGESTION_FORMATS`,
+    );
+  }
+  return target;
+}
+
+/** Every MIME the provider can hand a surface (natives first, then registry order). */
+export function providerFormatsFor(
+  provider: IngestionProviderKey,
+  surface: IngestionSurfaceKey,
+): ProviderFormat[] {
+  const natives: ProviderFormat[] = INGESTION_PROVIDERS[
+    provider
+  ].nativeFormats.map((native) => ({
+    mime: native.mime,
+    native: true,
+    format: exportTarget(native),
+    label: native.label,
+  }));
+  const downloads: ProviderFormat[] = INGESTION_FORMATS.map((format) => ({
+    mime: format.mime,
+    native: false,
+    format,
+    label: format.label,
+  }));
+  return [...natives, ...downloads].filter((pf) =>
+    surfaceAdmits(surface, pf.format),
+  );
+}
+
+/** The class of a provider-listed MIME; null for containers and unknown types. */
+export function classOfMime(
+  provider: IngestionProviderKey,
+  mime: string,
+): FormatClass | null {
+  const native = INGESTION_PROVIDERS[provider].nativeFormats.find(
+    (n) => n.mime === mime,
+  );
+  if (native) return exportTarget(native).class;
+  return byMime(mime)?.class ?? null;
+}
+
+/**
+ * The inventory classes discovery can record for a provider feeding a surface,
+ * in canonical class order, plus "shortcut". The DB CHECK on
+ * source_inventory_items.mime_class is pinned to this.
+ */
+export function inventoryClassesFor(
+  provider: IngestionProviderKey,
+  surface: IngestionSurfaceKey,
+): InventoryClass[] {
+  const present = new Set(
+    providerFormatsFor(provider, surface).map((pf) => pf.format.class),
+  );
+  return [...FORMAT_CLASSES.filter((c) => present.has(c)), "shortcut"];
+}
+
+/** Display label for a MIME (provider-native first when a provider is given); null if unknown. */
+export function labelOfMime(
+  mime: string,
+  provider?: IngestionProviderKey,
+): string | null {
+  if (provider) {
+    const native = INGESTION_PROVIDERS[provider].nativeFormats.find(
+      (n) => n.mime === mime,
+    );
+    if (native) return native.label;
+  }
+  return byMime(mime)?.label ?? null;
+}

package/src/ingestion/registry.ts

@@ -2,15 +2,18 @@
  * Ingestion Format Registry
  *
  * THE single source of truth for the public document-ingestion accept-set. The
- * backend normalizer joins these entries with its private dispatch table; the
- * app derives its file-input `accept` attribute and supported-formats copy from
- * the helpers below. Neither side re-spells the extension or label list.
+ * backend normalizer joins these entries with its private dispatch table; each
+ * upload surface derives its file-input `accept` attribute and supported-formats
+ * copy from the surface helpers. Neither side re-spells the extension, label or
+ * class list.
  *
  * Invariants:
  * - Entries are ordered text → documents → images/diagrams → audio/video; the
  *   backend's MIME-order test and the derived UI strings depend on this order.
- * - `INGEST_ACCEPT` and `SUPPORTED_LABEL` are DERIVED, never hand-maintained —
- *   adding a format here updates both automatically.
+ * - Every entry declares its `class` (one of `FORMAT_CLASSES`); no consumer
+ *   keeps its own extension → class table.
+ * - `.drawio` is not listed: no normalizer can rasterize a raw `<mxfile>`, so
+ *   admitting it would be a lie. It returns when a rasterizer exists.
  *
  * @see ADR-CONT-075 for design rationale
  */
@@ -22,6 +25,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "text/plain",
     family: "text",
+    class: "text",
     extensions: [".txt"],
     label: "Text",
     maxBytes: 10_000_000,
@@ -29,6 +33,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "text/markdown",
     family: "text",
+    class: "text",
     extensions: [".md"],
     label: "Markdown",
     maxBytes: 10_000_000,
@@ -36,6 +41,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "text/html",
     family: "text",
+    class: "text",
     extensions: [".html", ".htm"],
     label: "HTML",
     maxBytes: 10_000_000,
@@ -43,6 +49,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "text/csv",
     family: "text",
+    class: "sheets",
     extensions: [".csv"],
     label: "CSV",
     maxBytes: 25_000_000,
@@ -50,6 +57,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/rtf",
     family: "document",
+    class: "docs",
     extensions: [".rtf"],
     label: "RTF",
     maxBytes: 25_000_000,
@@ -57,6 +65,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
     family: "document",
+    class: "docs",
     extensions: [".docx"],
     label: "Word",
     maxBytes: 25_000_000,
@@ -64,6 +73,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/msword",
     family: "document",
+    class: "docs",
     extensions: [".doc"],
     label: "Word",
     maxBytes: 25_000_000,
@@ -71,6 +81,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
     family: "document",
+    class: "slides",
     extensions: [".pptx"],
     label: "PowerPoint",
     maxBytes: 50_000_000,
@@ -78,6 +89,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.ms-powerpoint",
     family: "document",
+    class: "slides",
     extensions: [".ppt"],
     label: "PowerPoint",
     maxBytes: 50_000_000,
@@ -85,6 +97,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
     family: "document",
+    class: "sheets",
     extensions: [".xlsx"],
     label: "Excel",
     maxBytes: 50_000_000,
@@ -92,6 +105,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.ms-excel",
     family: "document",
+    class: "sheets",
     extensions: [".xls"],
     label: "Excel",
     maxBytes: 50_000_000,
@@ -99,6 +113,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.oasis.opendocument.text",
     family: "document",
+    class: "docs",
     extensions: [".odt"],
     label: "OpenDocument",
     maxBytes: 25_000_000,
@@ -106,6 +121,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.oasis.opendocument.spreadsheet",
     family: "document",
+    class: "sheets",
     extensions: [".ods"],
     label: "OpenDocument",
     maxBytes: 50_000_000,
@@ -113,6 +129,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/vnd.oasis.opendocument.presentation",
     family: "document",
+    class: "slides",
     extensions: [".odp"],
     label: "OpenDocument",
     maxBytes: 50_000_000,
@@ -120,6 +137,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/epub+zip",
     family: "document",
+    class: "docs",
     extensions: [".epub"],
     label: "EPUB",
     maxBytes: 25_000_000,
@@ -127,6 +145,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "application/pdf",
     family: "document",
+    class: "pdf",
     extensions: [".pdf"],
     label: "PDF",
     maxBytes: 50_000_000,
@@ -134,6 +153,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "image/png",
     family: "image",
+    class: "image",
     extensions: [".png"],
     label: "Image",
     maxBytes: 25_000_000,
@@ -141,6 +161,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "image/jpeg",
     family: "image",
+    class: "image",
     extensions: [".jpg", ".jpeg"],
     label: "Image",
     maxBytes: 25_000_000,
@@ -148,6 +169,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "image/webp",
     family: "image",
+    class: "image",
     extensions: [".webp"],
     label: "Image",
     maxBytes: 25_000_000,
@@ -155,6 +177,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "image/gif",
     family: "image",
+    class: "image",
     extensions: [".gif"],
     label: "Image",
     maxBytes: 25_000_000,
@@ -162,27 +185,31 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "image/heic",
     family: "image",
+    class: "image",
     extensions: [".heic"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
-    mime: "image/svg+xml",
-    family: "diagram",
-    extensions: [".svg"],
-    label: "Diagram",
-    maxBytes: 10_000_000,
+    mime: "image/heif",
+    family: "image",
+    class: "image",
+    extensions: [".heif"],
+    label: "Image",
+    maxBytes: 25_000_000,
   },
   {
-    mime: "application/vnd.jgraph.mxfile",
+    mime: "image/svg+xml",
     family: "diagram",
-    extensions: [".drawio"],
+    class: "diagram",
+    extensions: [".svg"],
     label: "Diagram",
     maxBytes: 10_000_000,
   },
   {
     mime: "audio/mpeg",
     family: "audio",
+    class: "audio",
     extensions: [".mp3"],
     label: "Audio",
     maxBytes: 500_000_000,
@@ -190,6 +217,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "audio/x-m4a",
     family: "audio",
+    class: "audio",
     extensions: [".m4a"],
     label: "Audio",
     maxBytes: 500_000_000,
@@ -197,6 +225,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "audio/wav",
     family: "audio",
+    class: "audio",
     extensions: [".wav"],
     label: "Audio",
     maxBytes: 500_000_000,
@@ -204,6 +233,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "audio/aac",
     family: "audio",
+    class: "audio",
     extensions: [".aac"],
     label: "Audio",
     maxBytes: 500_000_000,
@@ -211,6 +241,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "video/mp4",
     family: "video",
+    class: "video",
     extensions: [".mp4", ".m4v"],
     label: "Video",
     maxBytes: 500_000_000,
@@ -218,6 +249,7 @@ export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "video/quicktime",
     family: "video",
+    class: "video",
     extensions: [".mov"],
     label: "Video",
     maxBytes: 500_000_000,
@@ -238,16 +270,3 @@ export function acceptExtensions(): string[] {
 export function humanLabels(): string[] {
   return [...new Set(INGESTION_FORMATS.map((entry) => entry.label))];
 }
-
-/**
- * Comma-joined extension string for a file input's `accept` attribute.
- * Derived from {@link acceptExtensions} — never hand-maintained.
- */
-export const INGEST_ACCEPT: string = acceptExtensions().join(",");
-
-/**
- * Human-readable supported-formats summary, derived from {@link humanLabels}.
- * Names every accepted group (in registry order) so the copy can't undersell
- * what actually works.
- */
-export const SUPPORTED_LABEL: string = `Supported: ${humanLabels().join(", ")}`;

package/src/ingestion/surfaces.ts

@@ -1,58 +1,104 @@
 /**
  * Ingestion Surfaces
  *
- * Per-surface views of the single format registry. A surface names the
- * families it consumes; everything else — the formats, the file-input `accept`
- * string, the "Supported: …" copy, the transport byte ceiling — is DERIVED from
+ * Per-surface views of the single format registry. A surface declares a
+ * treatment per family it consumes plus a required byte ceiling; everything
+ * else — the families, the formats, the file-input `accept` string, the
+ * "Supported: …" copy, the transport byte ceiling — is DERIVED from
  * `INGESTION_FORMATS` through that declaration. No surface re-spells a MIME.
  *
  * Invariants:
  * - Every surface admits at least one registry format.
  * - `maxBytesFor` never exceeds the registry cap of any admitted format, and
- *   never exceeds the surface ceiling when one is declared.
+ *   never exceeds the surface ceiling.
  *
  * @see ADR-CONTRACTS-159 for design rationale
  */
 
 import { INGESTION_FORMATS } from "./registry";
 import type {
+  IngestionFamily,
   IngestionFormat,
   IngestionSurface,
   IngestionSurfaceKey,
+  Treatment,
 } from "./types";
 
-/** 10 MiB — the org-chart ceiling (see the surface JSDoc below). */
-const ORG_CHART_MAX_BYTES = 10 * 1024 * 1024;
+const MIB = 1024 * 1024;
+
+/** Canonical family order; `familiesOf` returns families in this order. */
+const FAMILY_ORDER: readonly IngestionFamily[] = [
+  "text",
+  "document",
+  "image",
+  "diagram",
+  "audio",
+  "video",
+];
 
 /**
  * The canonical surface declarations.
  *
- * - `company-md`: context-bank and goals extraction. Consumes text and
- *   documents; images, diagrams and media are not extracted on this surface
- *   yet, so the picker must not advertise them.
- * - `org-chart`: the HRIS / org-chart import. Consumes text and documents plus
- *   images and diagrams (a photographed or drawn chart goes to a vision-capable
- *   model natively). The 10 MiB ceiling bounds the bytes handed to that model
- *   per upload; the registry caps for its families would otherwise reach 50 MB.
+ * - `company-md`: context bank, goals extraction, Source Sync landing. Text and
+ *   documents become text. (Image/diagram vision on this surface is a later,
+ *   separate change: it needs its own extraction prompt and discovery eval.)
+ * - `org-chart`: HRIS / org-chart import. A photographed, drawn or PDF chart
+ *   goes to a vision-capable model natively; 10 MiB bounds the bytes per upload.
+ * - `chat`: chat composer attachments. Text becomes text; a PDF and images go
+ *   to the model natively. At most 8 files per turn. 5 MiB per file = the composer's per-file cap today;
+ *   the request body ceiling (base64, several files) is derived from it by the
+ *   chat PRD, not declared here. Audio/video are refused until a transcript
+ *   path is wired.
+ * - `profile-image`: avatar and org-logo uploads. Images are stored, never
+ *   extracted; 5 MiB matches the current avatar/logo cap.
  */
 export const INGESTION_SURFACES: Readonly<
   Record<IngestionSurfaceKey, IngestionSurface>
 > = {
   "company-md": {
     key: "company-md",
-    families: ["text", "document"],
+    treatments: { text: "text", document: "text" },
+    maxBytes: 50_000_000,
   },
   "org-chart": {
     key: "org-chart",
-    families: ["text", "document", "image", "diagram"],
-    maxBytes: ORG_CHART_MAX_BYTES,
+    treatments: {
+      text: "text",
+      document: "vision",
+      image: "vision",
+      diagram: "vision",
+    },
+    maxBytes: 10 * MIB,
+  },
+  chat: {
+    key: "chat",
+    treatments: { text: "text", document: "vision", image: "vision" },
+    maxBytes: 5 * MIB,
+    // The composer sets no maxFiles today (unbounded; only the 10 MiB body cap
+    // limits a turn). 8 bounds per-turn vision/billing cost and the derived body
+    // ceiling (8 × 5 MiB × 4/3 base64 + envelope, computed by the chat PRD) while
+    // covering the multi-screenshot case.
+    maxFilesPerTurn: 8,
+  },
+  "profile-image": {
+    key: "profile-image",
+    treatments: { image: "store" },
+    maxBytes: 5 * MIB,
   },
 };
 
-/** The registry formats a surface admits, in registry order. */
-export function formatsFor(surface: IngestionSurfaceKey): IngestionFormat[] {
-  const { families } = INGESTION_SURFACES[surface];
-  return INGESTION_FORMATS.filter((entry) => families.includes(entry.family));
+/** The families a surface admits, in canonical family order. */
+export function familiesOf(surface: IngestionSurfaceKey): IngestionFamily[] {
+  const { treatments } = INGESTION_SURFACES[surface];
+  return FAMILY_ORDER.filter((family) => treatments[family] !== undefined);
+}
+
+/** What the surface does with this format; null = the surface refuses it. */
+export function treatmentFor(
+  surface: IngestionSurfaceKey,
+  format: IngestionFormat,
+): Treatment | null {
+  return INGESTION_SURFACES[surface].treatments[format.family] ?? null;
 }
 
 /** True when the surface admits this registry format. */
@@ -60,13 +106,22 @@ export function surfaceAdmits(
   surface: IngestionSurfaceKey,
   format: IngestionFormat,
 ): boolean {
-  return INGESTION_SURFACES[surface].families.includes(format.family);
+  return treatmentFor(surface, format) !== null;
 }
 
-/** Comma-joined extension string for the surface's file input `accept`. */
+/** The registry formats a surface admits, in registry order. */
+export function formatsFor(surface: IngestionSurfaceKey): IngestionFormat[] {
+  return INGESTION_FORMATS.filter((entry) => surfaceAdmits(surface, entry));
+}
+
+/**
+ * The `<input accept>` value for a surface: per format, its extensions then its
+ * MIME (".png,image/png,.jpg,.jpeg,image/jpeg,…"). Both forms are valid in
+ * `accept`, and a MIME-only matcher (the chat composer) can use the same string.
+ */
 export function acceptFor(surface: IngestionSurfaceKey): string {
   return formatsFor(surface)
-    .flatMap((entry) => [...entry.extensions])
+    .flatMap((entry) => [...entry.extensions, entry.mime])
     .join(",");
 }
 
@@ -77,15 +132,13 @@ export function supportedLabelFor(surface: IngestionSurfaceKey): string {
 }
 
 /**
- * The transport byte ceiling for a surface: the largest registry cap among
- * its admitted formats, tightened to the surface ceiling when one is declared.
- * The per-format registry cap still applies underneath it.
+ * The transport byte ceiling: the largest registry cap among admitted formats,
+ * tightened to the (required) surface ceiling.
  */
 export function maxBytesFor(surface: IngestionSurfaceKey): number {
   const registryMax = formatsFor(surface).reduce(
     (max, entry) => Math.max(max, entry.maxBytes),
     0,
   );
-  const ceiling = INGESTION_SURFACES[surface].maxBytes;
-  return ceiling === undefined ? registryMax : Math.min(registryMax, ceiling);
+  return Math.min(registryMax, INGESTION_SURFACES[surface].maxBytes);
 }

package/src/ingestion/types.ts

@@ -7,7 +7,7 @@
  * private dispatch fields locally) and the app upload UI (which derives its
  * `accept` attribute and supported-formats copy from this).
  *
- * Types only — no runtime behavior. The backend-only normalizer routing
+ * Types plus the `FORMAT_CLASSES` and `TREATMENTS` vocabulary constants. The backend-only normalizer routing
  * (`canonicalKind`, `normalizerKey`) deliberately does NOT live here; it is an
  * implementation detail of the backend dispatch and would pollute the shared
  * vocabulary.
@@ -17,7 +17,7 @@
 
 /**
  * The semantic family a format belongs to. A SURFACE (an upload picker and the
- * route behind it) declares which families it consumes; the accept-set and the
+ * route behind it) declares a treatment per family it consumes; the accept-set and the
  * byte ceiling for that surface derive from the registry through this field.
  * Public and semantic — NOT the backend normalizer dispatch (`canonicalKind` /
  * `normalizerKey` stay backend-local, ADR-CONTRACTS-075).
@@ -27,6 +27,29 @@
 export type IngestionFamily =
   "text" | "document" | "image" | "diagram" | "audio" | "video";
 
+/**
+ * The coarse, provider-agnostic kind of a format, used wherever the system
+ * classes a file without reading it: the Source Sync inventory `mime_class`,
+ * the discovery topology mix, probe groups, and the spreadsheet `source_kind`.
+ * Declared ON the format entry — no consumer keeps an extension → class table.
+ * Canonical order (the inventory CHECK and every derived list follow it).
+ */
+export const FORMAT_CLASSES = [
+  "docs",
+  "slides",
+  "sheets",
+  "pdf",
+  "text",
+  "image",
+  "diagram",
+  "audio",
+  "video",
+] as const;
+export type FormatClass = (typeof FORMAT_CLASSES)[number];
+
+/** A Source Sync inventory class: a format class, or a provider shortcut row. */
+export type InventoryClass = FormatClass | "shortcut";
+
 /**
  * One accepted upload format, keyed by its canonical MIME type.
  *
@@ -35,14 +58,17 @@ export type IngestionFamily =
  * - `extensions` are lowercase, dot-prefixed (e.g. `.docx`).
  * - `label` is the human display GROUP and is intentionally shared across
  *   related formats (`.docx` + `.doc` are both `Word`; the rasters are all
- *   `Image`; `.svg` + `.drawio` are `Diagram`).
+ *   `Image`; `.svg` is `Diagram`).
  * - `family` is the semantic family a surface selects on; every entry has one.
+ * - `class` is the coarse class (one of `FORMAT_CLASSES`); every entry has one.
  */
 export interface IngestionFormat {
   /** Canonical MIME type (the registry key). */
   mime: string;
-  /** Semantic family the format belongs to (what a surface selects on). */
+  /** Semantic family the format belongs to (what a surface declares a treatment for). */
   family: IngestionFamily;
+  /** Coarse class for classing without reading (inventory, topology, probes). */
+  class: FormatClass;
   /** Lowercase, dot-prefixed filename extensions for this format. */
   extensions: readonly string[];
   /** Human display group label (e.g. `Word`, `Image`, `Audio`). */
@@ -51,23 +77,62 @@ export interface IngestionFormat {
   maxBytes: number;
 }
 
-/** The upload surfaces that consume the registry. */
-export type IngestionSurfaceKey = "company-md" | "org-chart";
-
 /**
- * What one upload surface consumes: the families it admits and, optionally, a
- * byte ceiling tighter than the registry caps of those families.
+ * What a surface does with an admitted family. The backend proves at load that
+ * it can perform every declared (surface, family, treatment) for every admitted
+ * format, or it refuses to start.
  *
- * @see ADR-CONTRACTS-159
+ * - `text`: normalize to text only (a PDF is text-extracted).
+ * - `vision`: hand the model the richest native form — images as image parts,
+ *   a PDF as a binary document, text-native formats (docx, csv, …) as text.
+ * - `transcript`: audio/video become a transcript.
+ * - `store`: bytes are kept as-is (after format-preserving preparation such as
+ *   HEIC → JPEG); nothing is extracted.
+ */
+export const TREATMENTS = ["text", "vision", "transcript", "store"] as const;
+export type Treatment = (typeof TREATMENTS)[number];
+
+/** The surfaces that consume the registry. */
+export type IngestionSurfaceKey =
+  "company-md" | "org-chart" | "chat" | "profile-image";
+
+/**
+ * One surface: the treatment it applies per admitted family, and its byte
+ * ceiling. `families` is derived (`familiesOf`), never declared.
  */
 export interface IngestionSurface {
   /** The surface this declaration describes. */
   key: IngestionSurfaceKey;
-  /** Families the surface admits; a format outside them is refused (415). */
-  families: readonly IngestionFamily[];
+  /** Admitted family → what the surface does with it. Absent family = refused (415). */
+  treatments: Readonly<Partial<Record<IngestionFamily, Treatment>>>;
+  /** Surface byte ceiling (required). Caps every admitted format below its registry `maxBytes`. */
+  maxBytes: number;
   /**
-   * Surface-level byte ceiling. When set it caps every admitted format below
-   * its registry `maxBytes`; absent means the registry caps apply as-is.
+   * Most files one turn may carry. Declared only on `chat` (required there,
+   * pinned by test); upload surfaces take one file per request and omit it.
    */
-  maxBytes?: number;
+  maxFilesPerTurn?: number;
+}
+
+/** External sources that hand the pipeline provider-native files. */
+export type IngestionProviderKey = "google-drive";
+
+/** A provider-native type that is exported to a registry format before ingestion. */
+export interface ProviderNativeFormat {
+  /** The provider's own MIME (e.g. a Google Workspace type). */
+  mime: string;
+  /** Human label for the native type (e.g. `Google Doc`). */
+  label: string;
+  /** Registry MIME the provider exports this type to. Must resolve via `byMime`. */
+  exportsTo: string;
+}
+
+/** One provider: its native types and the structural container MIMEs it lists. */
+export interface IngestionProvider {
+  /** The provider this declaration describes. */
+  key: IngestionProviderKey;
+  /** Native types the provider exports to registry formats. */
+  nativeFormats: readonly ProviderNativeFormat[];
+  /** Structural (non-file) MIMEs the provider lists: folders and shortcuts. */
+  containerMimes: { readonly folder: string; readonly shortcut: string };
 }