@company-semantics/contracts 98.0.0 → 99.1.0

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