@company-semantics/contracts 97.0.0 → 99.0.0

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/chat/__tests__/turn-wire.test.ts

@@ -9,7 +9,11 @@
  * - A null group and a null rating parse: the turn stands alone / is unrated.
  * - The group is a uuid; anything else is refused.
  * - `turnKind` is CLOSED: an unknown kind is refused, never passed through.
- * - `myFeedback` is exactly `up`, `down` or null.
+ * - `myFeedback` is `{ rating, reason }` or null: the rating is exactly `up`
+ *   or `down`, the reason one of the CLOSED FEEDBACK_REASONS or null, and the
+ *   old bare-string shape is refused.
+ * - `alternatives` is REQUIRED; null means the turn has no sibling versions
+ *   (the shape of a present value is pinned in alternatives.test.ts).
  */
 import { describe, expect, it } from "vitest";
 import { userPrincipal } from "../../identity/agent";
@@ -27,7 +31,8 @@ const makeMessage = (over: Record<string, unknown> = {}) => ({
   author: { kind: "agent" as const },
   presentationGroupId: "3f2b8c1e-6d4a-4f7b-9a2e-1c5d8e9f0a1b",
   turnKind: "workflow_settlement" as const,
-  myFeedback: "up" as const,
+  alternatives: null,
+  myFeedback: { rating: "up" as const, reason: null },
   ...over,
 });
 
@@ -86,8 +91,42 @@ describe("ChatMessageSchema turn identity", () => {
 
   it("refuses a rating other than up, down or null", () => {
     expect(
-      ChatMessageSchema.safeParse(makeMessage({ myFeedback: "neutral" }))
-        .success,
+      ChatMessageSchema.safeParse(
+        makeMessage({ myFeedback: { rating: "neutral", reason: null } }),
+      ).success,
+    ).toBe(false);
+  });
+
+  it("refuses the bare-string rating shape", () => {
+    expect(
+      ChatMessageSchema.safeParse(makeMessage({ myFeedback: "up" })).success,
     ).toBe(false);
   });
+
+  it("parses a down rating with a closed reason", () => {
+    const parsed = ChatMessageSchema.parse(
+      makeMessage({ myFeedback: { rating: "down", reason: "incorrect" } }),
+    );
+    expect(parsed.myFeedback).toEqual({ rating: "down", reason: "incorrect" });
+  });
+
+  it("refuses a reason outside FEEDBACK_REASONS", () => {
+    expect(
+      ChatMessageSchema.safeParse(
+        makeMessage({ myFeedback: { rating: "down", reason: "rude" } }),
+      ).success,
+    ).toBe(false);
+  });
+});
+
+describe("ChatMessageSchema alternatives", () => {
+  it("refuses a message without alternatives", () => {
+    expect(ChatMessageSchema.safeParse(without("alternatives")).success).toBe(
+      false,
+    );
+  });
+
+  it("parses null alternatives: the turn has no siblings", () => {
+    expect(ChatMessageSchema.parse(makeMessage()).alternatives).toBeNull();
+  });
 });

package/src/chat/feedback.ts

@@ -0,0 +1,80 @@
+/**
+ * Chat message feedback (response-versions-and-feedback-reasons,
+ * ADR-CONTRACTS-228).
+ *
+ * Feedback MEASURES a message. It is never approval of anything the message
+ * proposed (chat-action-system rule 8): a thumbs-up does not authorize,
+ * confirm or execute.
+ *
+ * INVARIANTS:
+ * - FEEDBACK_REASONS is CLOSED and append-only.
+ * - A reason or a comment rides only a "down" rating.
+ * - LOAD ORDER: this module is a LEAF. It imports only zod and must NEVER
+ *   import `./schemas` (or any module that does) — `./schemas` imports this
+ *   file, and the reverse edge would reach its declarations in the temporal
+ *   dead zone.
+ */
+
+import { z } from "zod";
+
+/** The two ratings a reader can give a turn. */
+export const FEEDBACK_RATINGS = ["up", "down"] as const;
+export const FeedbackRatingSchema = z.enum(FEEDBACK_RATINGS);
+export type FeedbackRating = z.infer<typeof FeedbackRatingSchema>;
+
+/**
+ * Why a reader rated a turn down. CLOSED and append-only: a reason is a
+ * category the product can count, so free text belongs in `comment`, never
+ * here.
+ */
+export const FEEDBACK_REASONS = [
+  /** The answer states something false. */
+  "incorrect",
+  /** The answer ignored what the prompt asked for. */
+  "didnt_follow_instructions",
+  /** Accurate, but it did not help. */
+  "not_helpful",
+  /** The answer lacked context it should have had. */
+  "missing_context",
+  /** A tool call or launched workflow misbehaved. */
+  "tool_or_workflow_issue",
+  /** None of the above; the comment says why. */
+  "other",
+] as const;
+export const FeedbackReasonSchema = z.enum(FEEDBACK_REASONS);
+export type FeedbackReason = z.infer<typeof FeedbackReasonSchema>;
+
+/** Longest free-text comment a down rating may carry. */
+export const FEEDBACK_COMMENT_MAX = 2000;
+
+/**
+ * Body of PUT /api/chats/{id}/messages/{messageId}/feedback (operationId
+ * putChatMessageFeedback). Named after the generated operation's component so
+ * the backend can replace its route-local schema of the same name.
+ */
+export const PutChatMessageFeedbackRequestSchema = z
+  .object({
+    rating: FeedbackRatingSchema,
+    reason: FeedbackReasonSchema.optional(),
+    comment: z.string().max(FEEDBACK_COMMENT_MAX).optional(),
+  })
+  .refine(
+    (b) =>
+      b.rating === "down" ||
+      (b.reason === undefined && b.comment === undefined),
+    { message: "reason and comment ride only a down rating" },
+  );
+export type PutChatMessageFeedbackRequest = z.infer<
+  typeof PutChatMessageFeedbackRequestSchema
+>;
+
+/**
+ * The reader's own rating as `ChatMessage.myFeedback` carries it. `reason` is
+ * null on an up rating and on a down rating given without one. The comment is
+ * write-only — it is never projected back onto the transcript.
+ */
+export const ChatMessageMyFeedbackSchema = z.object({
+  rating: FeedbackRatingSchema,
+  reason: FeedbackReasonSchema.nullable(),
+});
+export type ChatMessageMyFeedback = z.infer<typeof ChatMessageMyFeedbackSchema>;

package/src/chat/index.ts

@@ -41,6 +41,10 @@ export type {
   ChatListResponse,
   CreateChatResponse,
   ChatMessage,
+  // Sibling versions of a turn and the branch-select request body
+  // (response-versions-and-feedback-reasons, ADR-CONTRACTS-228)
+  ChatMessageAlternatives,
+  ChatBranchSelectRequest,
   // Mentions on a chat turn (ADR-CONTRACTS-160): a PrincipalRef target, so the
   // agent is a legal mention target on the chat surface too.
   ChatMessageMention,
@@ -88,6 +92,8 @@ export {
   ChatListResponseSchema,
   CreateChatResponseSchema,
   ChatMessageSchema,
+  ChatMessageAlternativesSchema,
+  ChatBranchSelectRequestSchema,
   ChatMessageMentionSchema,
   ChatMentionableResponseSchema,
   // Participants: the role vocabulary, one participant row, and the list
@@ -155,6 +161,26 @@ export {
   isMessageActionAllowed,
 } from "./message-actions";
 
+// Feedback (response-versions-and-feedback-reasons): the rating vocabulary,
+// the CLOSED reasons a down rating may carry, the PUT feedback request body and
+// the reader's own rating as ChatMessage.myFeedback carries it. Feedback
+// measures a turn; it is never approval.
+export type {
+  FeedbackRating,
+  FeedbackReason,
+  PutChatMessageFeedbackRequest,
+  ChatMessageMyFeedback,
+} from "./feedback";
+export {
+  FEEDBACK_RATINGS,
+  FeedbackRatingSchema,
+  FEEDBACK_REASONS,
+  FeedbackReasonSchema,
+  FEEDBACK_COMMENT_MAX,
+  PutChatMessageFeedbackRequestSchema,
+  ChatMessageMyFeedbackSchema,
+} from "./feedback";
+
 // Runtime profile types and constants
 export type {
   ChatRuntimeProfile,

package/src/chat/message-actions.ts

@@ -18,8 +18,11 @@
  * - Regenerate is never offered on a workflow_launch, workflow_settlement,
  *   input_request_launch, proactive or refusal turn: it would ask the model for
  *   new prose without re-running the work.
- * - Regenerate and edit are offered only on the latest turn of the active
- *   branch; edit only to the reader who authored it.
+ * - Regenerate and edit are offered on ANY settled conversation turn, not only
+ *   the latest: both BRANCH (add a sibling version) and never delete, so an
+ *   older turn is as safe to act on as the latest. Edit only to the reader who
+ *   authored the prompt (response-versions-and-feedback-reasons).
+ * - Position (`isLatestOnActiveBranch`) is on the context but gates NOTHING.
  * - An input the schema does not recognize (an unknown kind or role) offers
  *   NOTHING. Unknown is never permissive.
  *
@@ -39,9 +42,9 @@ export const MESSAGE_ACTION_IDS = [
   "copy",
   /** Rate the turn up or down. Measures a message; never approves anything. */
   "feedback",
-  /** A new answer to the same request; supersedes the old one. Never re-runs work. */
+  /** A new answer to the same request; adds a sibling version. Never re-runs work. */
   "regenerate",
-  /** Rewrite the reader's own prompt; supersedes the branch after it. */
+  /** Rewrite the reader's own prompt; adds a sibling version of it. */
   "edit",
 ] as const;
 
@@ -60,17 +63,24 @@ export const MessageActionContextSchema = z.object({
    * flight or awaiting settlement delivery.
    */
   settled: z.boolean(),
-  /** The turn is the latest of its role on the active branch. */
+  /**
+   * The turn is the latest of its role on the active branch. Carried for the
+   * reader's orientation; it no longer gates any action — regenerate and edit
+   * branch, so they are offered on older turns too.
+   */
   isLatestOnActiveBranch: z.boolean(),
   /** The reader is the turn's author (a user turn they wrote). */
   authoredByReader: z.boolean(),
 });
 export type MessageActionContext = z.infer<typeof MessageActionContextSchema>;
 
-/** `always` is offered on every settled turn; `latest` only on the latest. */
+/**
+ * `always` is offered on every settled turn; `authored` only on a settled user
+ * turn the reader wrote.
+ */
 type ActionRule = {
   always: readonly MessageActionId[];
-  latest: readonly MessageActionId[];
+  authored: readonly MessageActionId[];
 };
 
 /**
@@ -81,28 +91,28 @@ type ActionRule = {
  */
 const TURN_ACTIONS = {
   conversation: {
-    user: { always: ["copy"], latest: ["edit"] },
-    assistant: { always: ["copy", "feedback"], latest: ["regenerate"] },
+    user: { always: ["copy"], authored: ["edit"] },
+    assistant: { always: ["copy", "feedback", "regenerate"], authored: [] },
   },
   workflow_launch: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   workflow_settlement: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   input_request_launch: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy", "feedback"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy", "feedback"], authored: [] },
   },
   proactive: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy"], authored: [] },
   },
   refusal: {
-    user: { always: ["copy"], latest: [] },
-    assistant: { always: ["copy"], latest: [] },
+    user: { always: ["copy"], authored: [] },
+    assistant: { always: ["copy"], authored: [] },
   },
 } as const satisfies Record<
   TurnKind,
@@ -114,24 +124,20 @@ const TURN_ACTIONS = {
  *
  * - Input that does not parse (unknown kind, unknown role) → [].
  * - Not settled → [].
- * - User turn → its `always`, plus `latest` iff latest on the active branch
- *   AND authored by the reader.
- * - Assistant turn → its `always`, plus `latest` iff latest on the active
- *   branch.
+ * - User turn → its `always`, plus `authored` iff authored by the reader.
+ * - Assistant turn → its `always`.
+ * - Position on the branch gates nothing.
  */
 export function messageActionsFor(
   ctx: MessageActionContext,
 ): readonly MessageActionId[] {
   const parsed = MessageActionContextSchema.safeParse(ctx);
   if (!parsed.success || !parsed.data.settled) return [];
-  const { role, turnKind, isLatestOnActiveBranch, authoredByReader } =
-    parsed.data;
+  const { role, turnKind, authoredByReader } = parsed.data;
   const rule: ActionRule = TURN_ACTIONS[turnKind][role];
-  const latest =
-    role === "user"
-      ? isLatestOnActiveBranch && authoredByReader
-      : isLatestOnActiveBranch;
-  return latest ? [...rule.always, ...rule.latest] : [...rule.always];
+  return role === "user" && authoredByReader
+    ? [...rule.always, ...rule.authored]
+    : [...rule.always];
 }
 
 /** Whether `action` is among `messageActionsFor(ctx)` — the backend's check. */

package/src/chat/schemas.ts

@@ -25,6 +25,7 @@ import {
   proactiveChatFields,
   TitleSourceSchema,
 } from "./enums";
+import { ChatMessageMyFeedbackSchema } from "./feedback";
 import { TurnKindSchema } from "./turn-kind";
 
 // The chat vocabulary and the SSE event contract, re-exported so this module
@@ -238,6 +239,41 @@ export const ChatDiscussionScopeSchema = z
   })
   .strict(); // an unknown key is an ERROR, not surplus
 
+/**
+ * The VERSIONS of one turn (response-versions-and-feedback-reasons,
+ * ADR-CONTRACTS-228). Regenerating an answer or editing a prompt never deletes
+ * the turn it replaces — it ADDS A SIBLING VERSION, and the reader picks which
+ * one the active branch runs through.
+ *
+ * `ids` lists every sibling, this one included, ORDERED BY CREATION — so the
+ * selector reads "2 / 3" from `position` / `total` and steps through `ids`
+ * without a second fetch. `position` is 1-based. The refinements make the three
+ * fields agree by construction: a client never has to reconcile a `total` that
+ * disagrees with the list it was sent.
+ */
+export const ChatMessageAlternativesSchema = z
+  .object({
+    position: z.number().int().min(1),
+    total: z.number().int().min(1),
+    ids: z.array(z.string().uuid()),
+  })
+  .refine((a) => a.ids.length === a.total, {
+    message: "ids.length must equal total",
+  })
+  .refine((a) => a.position <= a.total, {
+    message: "position must not exceed total",
+  });
+
+/**
+ * Request body that makes one version the active branch
+ * (response-versions-and-feedback-reasons). `messageId` names the SIBLING to
+ * select; the server re-checks it is a version of a turn in this chat — naming
+ * an id is a lookup, not authority.
+ */
+export const ChatBranchSelectRequestSchema = z.object({
+  messageId: z.string().uuid(),
+});
+
 export const ChatMessageSchema = z.object({
   id: z.string(),
   role: z.enum(["user", "assistant"]),
@@ -309,12 +345,26 @@ export const ChatMessageSchema = z.object({
    */
   turnKind: TurnKindSchema,
 
+  /**
+   * The sibling VERSIONS of this turn, when it has been regenerated (answer)
+   * or edited (prompt) — see {@link ChatMessageAlternativesSchema}. REQUIRED,
+   * and null means this turn has no siblings: every row has an answer, so there
+   * is no absence to make optional. The transcript carries the ACTIVE branch
+   * only; the other versions are reachable by id, never inlined.
+   */
+  alternatives: ChatMessageAlternativesSchema.nullable(),
+
   /**
    * The READER's current rating of this turn — the person this response was
    * projected for, never an aggregate of other participants. REQUIRED so a
    * reload restores the rating; null on user turns and on unrated turns.
+   *
+   * `{ rating, reason }` (response-versions-and-feedback-reasons): `reason` is
+   * one of the CLOSED FEEDBACK_REASONS, and only ever set on a down rating.
+   * Feedback MEASURES the turn — it is NOT APPROVAL of anything the turn
+   * proposed, and never authorizes, confirms or executes.
    */
-  myFeedback: z.enum(["up", "down"]).nullable(),
+  myFeedback: ChatMessageMyFeedbackSchema.nullable(),
 });
 
 // =============================================================================

package/src/chat/types.ts

@@ -30,6 +30,8 @@ import {
   ChatListResponseSchema,
   CreateChatResponseSchema,
   ChatMessageSchema,
+  ChatMessageAlternativesSchema,
+  ChatBranchSelectRequestSchema,
   ChatMessageMentionSchema,
   ChatMentionableResponseSchema,
   ChatParticipantRoleSchema,
@@ -227,6 +229,19 @@ export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>;
 /** Individual message in a chat response (GET /api/chats/:id). */
 export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
+/**
+ * The sibling versions of one turn — 1-based `position`, `total`, and every
+ * sibling id ordered by creation (response-versions-and-feedback-reasons).
+ */
+export type ChatMessageAlternatives = z.infer<
+  typeof ChatMessageAlternativesSchema
+>;
+
+/** Request body that makes one sibling version the active branch. */
+export type ChatBranchSelectRequest = z.infer<
+  typeof ChatBranchSelectRequestSchema
+>;
+
 /**
  * One mention on a chat turn — a `PrincipalRef` target, a nullable UTF-16
  * code-unit range into `content`, and a read-time display name.

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