@company-semantics/contracts 13.17.0 → 13.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "13.17.0",
+  "version": "13.18.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -64,6 +64,10 @@
       "types": "./src/impersonation/index.ts",
       "default": "./src/impersonation/index.ts"
     },
+    "./ingestion": {
+      "types": "./src/ingestion/index.ts",
+      "default": "./src/ingestion/index.ts"
+    },
     "./schemas/guard-result.schema.json": "./schemas/guard-result.schema.json"
   },
   "types": "./src/index.ts",

package/src/index.ts

@@ -779,3 +779,8 @@ export * from "./meetings";
 // AccessLevel / OrgChartRole / AccessSource — see ADR-CTRL-084..088.
 // No consumers in this PRD; cutover starts in AUTH-002 (PRD-00670).
 export * from "./permissions";
+
+// Document-ingestion accept-set vocabulary — see ADR-CONT-075.
+// Single source of truth for upload formats; the backend normalizer joins its
+// private dispatch fields locally, the app derives its accept-set + copy.
+export * from "./ingestion";

package/src/ingestion/README.md

@@ -0,0 +1,35 @@
+# ingestion/
+
+Shared vocabulary for the document-ingestion accept-set.
+
+## 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.
+
+## Invariants
+
+- `INGESTION_FORMATS` is the canonical list; `mime` is unique across entries.
+- 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.
+- No normalizer-routing fields here (`canonicalKind`, `normalizerKey` are
+  backend-only). This package stays pure vocabulary.
+
+## Public API
+
+- `IngestionFormat` — `{ mime, extensions, label, maxBytes }`.
+- `INGESTION_FORMATS: readonly IngestionFormat[]`.
+- `byMime(mime)`, `acceptExtensions()`, `humanLabels()`.
+- `INGEST_ACCEPT: string` — comma-joined extensions for an `accept` attribute.
+- `SUPPORTED_LABEL: string` — human-readable supported-formats summary.
+
+## Dependencies
+
+None beyond `./types`. (The backend registry at
+`company-semantics-backend/src/orgs/ingestion/normalize/format-registry.ts`
+consumes this and adds its private dispatch fields.)

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import {
+  INGESTION_FORMATS,
+  byMime,
+  acceptExtensions,
+  humanLabels,
+  INGEST_ACCEPT,
+  SUPPORTED_LABEL,
+} from "../registry";
+
+describe("ingestion registry", () => {
+  it("has a unique MIME per entry", () => {
+    const mimes = INGESTION_FORMATS.map((e) => e.mime);
+    expect(new Set(mimes).size).toBe(mimes.length);
+  });
+
+  it("uses lowercase, dot-prefixed extensions", () => {
+    for (const entry of INGESTION_FORMATS) {
+      for (const ext of entry.extensions) {
+        expect(ext).toMatch(/^\.[a-z0-9]+$/);
+      }
+    }
+  });
+
+  it("byMime resolves a known format and rejects unknown", () => {
+    expect(byMime("application/pdf")?.label).toBe("PDF");
+    expect(byMime("audio/mpeg")?.label).toBe("Audio");
+    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,.xlsx,.odt,.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",
+    );
+  });
+});

package/src/ingestion/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Ingestion Domain Barrel
+ *
+ * Re-exports the public document-ingestion format vocabulary.
+ * Import from '@company-semantics/contracts/ingestion'.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+export type { IngestionFormat } from "./types";
+
+export {
+  INGESTION_FORMATS,
+  byMime,
+  acceptExtensions,
+  humanLabels,
+  INGEST_ACCEPT,
+  SUPPORTED_LABEL,
+} from "./registry";

package/src/ingestion/registry.ts

@@ -0,0 +1,194 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+import type { IngestionFormat } from "./types";
+
+/** The canonical public format registry. */
+export const INGESTION_FORMATS: readonly IngestionFormat[] = [
+  {
+    mime: "text/plain",
+    extensions: [".txt"],
+    label: "Text",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/markdown",
+    extensions: [".md"],
+    label: "Markdown",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/html",
+    extensions: [".html", ".htm"],
+    label: "HTML",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "text/csv",
+    extensions: [".csv"],
+    label: "CSV",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/rtf",
+    extensions: [".rtf"],
+    label: "RTF",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    extensions: [".docx"],
+    label: "Word",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/msword",
+    extensions: [".doc"],
+    label: "Word",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    extensions: [".pptx"],
+    label: "PowerPoint",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    extensions: [".xlsx"],
+    label: "Excel",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "application/vnd.oasis.opendocument.text",
+    extensions: [".odt"],
+    label: "OpenDocument",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "application/pdf",
+    extensions: [".pdf"],
+    label: "PDF",
+    maxBytes: 50_000_000,
+  },
+  {
+    mime: "image/png",
+    extensions: [".png"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/jpeg",
+    extensions: [".jpg", ".jpeg"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/webp",
+    extensions: [".webp"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/gif",
+    extensions: [".gif"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/heic",
+    extensions: [".heic"],
+    label: "Image",
+    maxBytes: 25_000_000,
+  },
+  {
+    mime: "image/svg+xml",
+    extensions: [".svg"],
+    label: "Diagram",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "application/vnd.jgraph.mxfile",
+    extensions: [".drawio"],
+    label: "Diagram",
+    maxBytes: 10_000_000,
+  },
+  {
+    mime: "audio/mpeg",
+    extensions: [".mp3"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/x-m4a",
+    extensions: [".m4a"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/wav",
+    extensions: [".wav"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "audio/aac",
+    extensions: [".aac"],
+    label: "Audio",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "video/mp4",
+    extensions: [".mp4", ".m4v"],
+    label: "Video",
+    maxBytes: 500_000_000,
+  },
+  {
+    mime: "video/quicktime",
+    extensions: [".mov"],
+    label: "Video",
+    maxBytes: 500_000_000,
+  },
+];
+
+/** Look up the entry for a canonical MIME; undefined means unsupported. */
+export function byMime(mime: string): IngestionFormat | undefined {
+  return INGESTION_FORMATS.find((entry) => entry.mime === mime);
+}
+
+/** All accepted filename extensions, in registry order. */
+export function acceptExtensions(): string[] {
+  return INGESTION_FORMATS.flatMap((entry) => [...entry.extensions]);
+}
+
+/** Unique group labels for human display, in registry order. */
+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/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Ingestion Format Types
+ *
+ * The public vocabulary for the document-ingestion accept-set: which file
+ * formats the platform accepts for upload, their human label groups, and the
+ * per-format byte caps. Shared by the backend normalizer (which adds its own
+ * 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
+ * (`canonicalKind`, `normalizerKey`) deliberately does NOT live here; it is an
+ * implementation detail of the backend dispatch and would pollute the shared
+ * vocabulary.
+ *
+ * @see ADR-CONT-075 for design rationale
+ */
+
+/**
+ * One accepted upload format, keyed by its canonical MIME type.
+ *
+ * Invariants:
+ * - `mime` is unique across the registry.
+ * - `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`).
+ */
+export interface IngestionFormat {
+  /** Canonical MIME type (the registry key). */
+  mime: string;
+  /** Lowercase, dot-prefixed filename extensions for this format. */
+  extensions: readonly string[];
+  /** Human display group label (e.g. `Word`, `Image`, `Audio`). */
+  label: string;
+  /** Per-format upload byte cap. */
+  maxBytes: number;
+}