@company-semantics/contracts 62.8.0 → 62.10.0

package/package.json

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

package/src/ingestion/README.md

@@ -19,18 +19,31 @@ attribute and supported-formats copy from the same data.
   hand-maintained — adding a format updates both automatically.
 - 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.
 
 <!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
 
 ## Public API
 
 - `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.
+- `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}.
 - `acceptExtensions` — All accepted filename extensions, in registry order.
+- `acceptFor` — Comma-joined extension string for the surface's file input `accept`.
 - `byMime` — Look up the entry for a canonical MIME; undefined means unsupported.
+- `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…
+- `supportedLabelFor` — "Supported: …" copy naming every label group the surface admits.
+- `surfaceAdmits` — True when the surface admits this registry format.
 
 <!-- END GENERATED: readme-public-api -->
 

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

@@ -31,14 +31,14 @@ describe("ingestion registry", () => {
   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,.xlsx,.odt,.pdf,.png,.jpg,.jpeg,.webp,.gif,.heic,.svg,.drawio,.mp3,.m4a,.wav,.aac,.mp4,.m4v,.mov",
+      ".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("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, PDF, Image, Diagram, Audio, Video",
+      "Supported: Text, Markdown, HTML, CSV, RTF, Word, PowerPoint, Excel, OpenDocument, EPUB, PDF, Image, Diagram, Audio, Video",
     );
   });
 });

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

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { INGESTION_FORMATS, byMime } from "../registry";
+import {
+  INGESTION_SURFACES,
+  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 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 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 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("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);
+      expect(maxBytesFor(key)).toBeLessThanOrEqual(
+        Math.max(...formatsFor(key).map((f) => f.maxBytes)),
+      );
+    }
+  });
+});

package/src/ingestion/index.ts

@@ -1,13 +1,19 @@
 /**
  * Ingestion Domain Barrel
  *
- * Re-exports the public document-ingestion format vocabulary.
+ * Re-exports the public document-ingestion format vocabulary and the
+ * per-surface views derived from it.
  * Import from '@company-semantics/contracts/ingestion'.
  *
- * @see ADR-CONT-075 for design rationale
+ * @see ADR-CONTRACTS-075 (registry), ADR-CONTRACTS-159 (surfaces)
  */
 
-export type { IngestionFormat } from "./types";
+export type {
+  IngestionFamily,
+  IngestionFormat,
+  IngestionSurface,
+  IngestionSurfaceKey,
+} from "./types";
 
 export {
   INGESTION_FORMATS,
@@ -17,3 +23,12 @@ export {
   INGEST_ACCEPT,
   SUPPORTED_LABEL,
 } from "./registry";
+
+export {
+  INGESTION_SURFACES,
+  formatsFor,
+  surfaceAdmits,
+  acceptFor,
+  supportedLabelFor,
+  maxBytesFor,
+} from "./surfaces";

package/src/ingestion/registry.ts

@@ -21,144 +21,203 @@ import type { IngestionFormat } from "./types";
 export const INGESTION_FORMATS: readonly IngestionFormat[] = [
   {
     mime: "text/plain",
+    family: "text",
     extensions: [".txt"],
     label: "Text",
     maxBytes: 10_000_000,
   },
   {
     mime: "text/markdown",
+    family: "text",
     extensions: [".md"],
     label: "Markdown",
     maxBytes: 10_000_000,
   },
   {
     mime: "text/html",
+    family: "text",
     extensions: [".html", ".htm"],
     label: "HTML",
     maxBytes: 10_000_000,
   },
   {
     mime: "text/csv",
+    family: "text",
     extensions: [".csv"],
     label: "CSV",
     maxBytes: 25_000_000,
   },
   {
     mime: "application/rtf",
+    family: "document",
     extensions: [".rtf"],
     label: "RTF",
     maxBytes: 25_000_000,
   },
   {
     mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    family: "document",
     extensions: [".docx"],
     label: "Word",
     maxBytes: 25_000_000,
   },
   {
     mime: "application/msword",
+    family: "document",
     extensions: [".doc"],
     label: "Word",
     maxBytes: 25_000_000,
   },
   {
     mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    family: "document",
     extensions: [".pptx"],
     label: "PowerPoint",
     maxBytes: 50_000_000,
   },
+  {
+    mime: "application/vnd.ms-powerpoint",
+    family: "document",
+    extensions: [".ppt"],
+    label: "PowerPoint",
+    maxBytes: 50_000_000,
+  },
   {
     mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    family: "document",
     extensions: [".xlsx"],
     label: "Excel",
     maxBytes: 50_000_000,
   },
+  {
+    mime: "application/vnd.ms-excel",
+    family: "document",
+    extensions: [".xls"],
+    label: "Excel",
+    maxBytes: 50_000_000,
+  },
   {
     mime: "application/vnd.oasis.opendocument.text",
+    family: "document",
     extensions: [".odt"],
     label: "OpenDocument",
     maxBytes: 25_000_000,
   },
+  {
+    mime: "application/vnd.oasis.opendocument.spreadsheet",
+    family: "document",
+    extensions: [".ods"],
+    label: "OpenDocument",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/vnd.oasis.opendocument.presentation",
+    family: "document",
+    extensions: [".odp"],
+    label: "OpenDocument",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/epub+zip",
+    family: "document",
+    extensions: [".epub"],
+    label: "EPUB",
+    maxBytes: 25_000_000,
+  },
   {
     mime: "application/pdf",
+    family: "document",
     extensions: [".pdf"],
     label: "PDF",
     maxBytes: 50_000_000,
   },
   {
     mime: "image/png",
+    family: "image",
     extensions: [".png"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
     mime: "image/jpeg",
+    family: "image",
     extensions: [".jpg", ".jpeg"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
     mime: "image/webp",
+    family: "image",
     extensions: [".webp"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
     mime: "image/gif",
+    family: "image",
     extensions: [".gif"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
     mime: "image/heic",
+    family: "image",
     extensions: [".heic"],
     label: "Image",
     maxBytes: 25_000_000,
   },
   {
     mime: "image/svg+xml",
+    family: "diagram",
     extensions: [".svg"],
     label: "Diagram",
     maxBytes: 10_000_000,
   },
   {
     mime: "application/vnd.jgraph.mxfile",
+    family: "diagram",
     extensions: [".drawio"],
     label: "Diagram",
     maxBytes: 10_000_000,
   },
   {
     mime: "audio/mpeg",
+    family: "audio",
     extensions: [".mp3"],
     label: "Audio",
     maxBytes: 500_000_000,
   },
   {
     mime: "audio/x-m4a",
+    family: "audio",
     extensions: [".m4a"],
     label: "Audio",
     maxBytes: 500_000_000,
   },
   {
     mime: "audio/wav",
+    family: "audio",
     extensions: [".wav"],
     label: "Audio",
     maxBytes: 500_000_000,
   },
   {
     mime: "audio/aac",
+    family: "audio",
     extensions: [".aac"],
     label: "Audio",
     maxBytes: 500_000_000,
   },
   {
     mime: "video/mp4",
+    family: "video",
     extensions: [".mp4", ".m4v"],
     label: "Video",
     maxBytes: 500_000_000,
   },
   {
     mime: "video/quicktime",
+    family: "video",
     extensions: [".mov"],
     label: "Video",
     maxBytes: 500_000_000,

package/src/ingestion/surfaces.ts

@@ -0,0 +1,91 @@
+/**
+ * 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
+ * `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.
+ *
+ * @see ADR-CONTRACTS-159 for design rationale
+ */
+
+import { INGESTION_FORMATS } from "./registry";
+import type {
+  IngestionFormat,
+  IngestionSurface,
+  IngestionSurfaceKey,
+} from "./types";
+
+/** 10 MiB — the org-chart ceiling (see the surface JSDoc below). */
+const ORG_CHART_MAX_BYTES = 10 * 1024 * 1024;
+
+/**
+ * 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.
+ */
+export const INGESTION_SURFACES: Readonly<
+  Record<IngestionSurfaceKey, IngestionSurface>
+> = {
+  "company-md": {
+    key: "company-md",
+    families: ["text", "document"],
+  },
+  "org-chart": {
+    key: "org-chart",
+    families: ["text", "document", "image", "diagram"],
+    maxBytes: ORG_CHART_MAX_BYTES,
+  },
+};
+
+/** 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));
+}
+
+/** True when the surface admits this registry format. */
+export function surfaceAdmits(
+  surface: IngestionSurfaceKey,
+  format: IngestionFormat,
+): boolean {
+  return INGESTION_SURFACES[surface].families.includes(format.family);
+}
+
+/** Comma-joined extension string for the surface's file input `accept`. */
+export function acceptFor(surface: IngestionSurfaceKey): string {
+  return formatsFor(surface)
+    .flatMap((entry) => [...entry.extensions])
+    .join(",");
+}
+
+/** "Supported: …" copy naming every label group the surface admits. */
+export function supportedLabelFor(surface: IngestionSurfaceKey): string {
+  const labels = [...new Set(formatsFor(surface).map((entry) => entry.label))];
+  return `Supported: ${labels.join(", ")}`;
+}
+
+/**
+ * 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.
+ */
+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);
+}

package/src/ingestion/types.ts

@@ -15,6 +15,18 @@
  * @see ADR-CONT-075 for design rationale
  */
 
+/**
+ * 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
+ * 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).
+ *
+ * @see ADR-CONTRACTS-159
+ */
+export type IngestionFamily =
+  "text" | "document" | "image" | "diagram" | "audio" | "video";
+
 /**
  * One accepted upload format, keyed by its canonical MIME type.
  *
@@ -24,10 +36,13 @@
  * - `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`).
+ * - `family` is the semantic family a surface selects on; 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). */
+  family: IngestionFamily;
   /** Lowercase, dot-prefixed filename extensions for this format. */
   extensions: readonly string[];
   /** Human display group label (e.g. `Word`, `Image`, `Audio`). */
@@ -35,3 +50,24 @@ export interface IngestionFormat {
   /** Per-format upload byte cap. */
   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.
+ *
+ * @see ADR-CONTRACTS-159
+ */
+export interface IngestionSurface {
+  /** The surface this declaration describes. */
+  key: IngestionSurfaceKey;
+  /** Families the surface admits; a format outside them is refused (415). */
+  families: readonly IngestionFamily[];
+  /**
+   * Surface-level byte ceiling. When set it caps every admitted format below
+   * its registry `maxBytes`; absent means the registry caps apply as-is.
+   */
+  maxBytes?: number;
+}