@company-semantics/contracts 97.0.0 → 99.0.0

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 };
 }