@company-semantics/contracts 79.2.0 → 80.0.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = 'c8b7d9ff0c4f' as const;
-export const SPEC_HASH_FULL = 'c8b7d9ff0c4fda27f5db2cc4afa34e2b80015a930d36e2a6d5106987285b503a' as const;
+export const SPEC_HASH = 'c2954b6d06a9' as const;
+export const SPEC_HASH_FULL = 'c2954b6d06a981632d4d61991aa61f16ee28485116ec66949fe08d64cbde4ceb' as const;

package/src/api/generated.ts

@@ -8653,6 +8653,7 @@ export interface components {
                 /** @enum {string} */
                 recommendedUse: "attached" | "direction_only" | "excluded";
                 use: ("attached" | "direction_only" | "excluded") | null;
+                included: boolean;
                 treatmentUnresolved: boolean;
                 matchReason: string;
                 unreadableReason: ("unsupported_type" | "needs_ocr" | "unsupported_kind") | null;
@@ -8690,7 +8691,11 @@ export interface components {
                 };
             }[];
             withheldQuestionCount: number;
-            unresolvedTreatmentCount: number;
+            totals: {
+                files: number;
+                filesIncluded: number;
+                filesNeedingChoice: number;
+            };
             scopes: {
                 scopeKey: string;
                 /** @enum {string} */

package/src/source-sync/README.md

@@ -127,10 +127,13 @@ way. This directory holds that shared spelling.
 - `SourceSyncDiscoveryRunResponseSchema` / `SourceSyncDiscoveryRunResponse` —
   the discovery run started, and the workflow narrating it.
 - `SourceSyncCandidateItemSchema` / `SourceSyncCandidateItem` — one source
-  proposed for one target document.
+  proposed for one target document, with the server's `included`.
 - `SourceSyncCandidateSetResponseSchema` / `SourceSyncCandidateSetResponse` —
-  the draft set under review: its revision, items, presented questions and
-  cost estimate.
+  the draft set under review: its revision, items, presented questions,
+  distinct-file `totals` and cost estimate.
+- `SourceSyncCandidateTotalsSchema` / `SourceSyncCandidateTotals` and
+  `candidateTotalsOf(items)` — THE file count: distinct `sourceId`, never lines
+  (ADR-CONTRACTS-195).
 - `SourceSyncCandidateItemPatchSchema` / `SourceSyncCandidateItemPatch` — one
   edit to one candidate item (use, class or target); never empty.
 - `SourceSyncAddCandidateRequestSchema` / `SourceSyncAddCandidateRequest` —

package/src/source-sync/__tests__/schemas.test.ts

@@ -15,6 +15,7 @@
 
 import { describe, expect, it } from "vitest";
 import {
+  candidateTotalsOf,
   SourceSyncCandidateItemSchema,
   SourceSyncCandidateSetResponseSchema,
   SourceSyncDiscoveryRunResponseSchema,
@@ -50,6 +51,7 @@ function candidateItem(overrides: Record<string, unknown> = {}) {
     audienceFit: "fits",
     recommendedUse: "direction_only",
     use: null,
+    included: true,
     treatmentUnresolved: false,
     matchReason: "A board deck for the current quarter.",
     unreadableReason: null,
@@ -96,7 +98,7 @@ function candidateSet(overrides: Record<string, unknown> = {}) {
     items: [candidateItem()],
     questions: [presentedQuestion()],
     withheldQuestionCount: 0,
-    unresolvedTreatmentCount: 0,
+    totals: { files: 1, filesIncluded: 1, filesNeedingChoice: 0 },
     scopes: [],
     estimate: {
       lowMicroUsd: "250000",
@@ -279,3 +281,16 @@ describe("SourceSyncDiscoveryRunResponseSchema", () => {
     ).toBe(true);
   });
 });
+
+describe("candidateTotalsOf", () => {
+  it("counts distinct files, never lines", () => {
+    expect(
+      candidateTotalsOf([
+        { sourceId: "a", included: true, treatmentUnresolved: true },
+        { sourceId: "a", included: true, treatmentUnresolved: false },
+        { sourceId: "b", included: false, treatmentUnresolved: true },
+        { sourceId: "c", included: true, treatmentUnresolved: false },
+      ]),
+    ).toEqual({ files: 3, filesIncluded: 2, filesNeedingChoice: 1 });
+  });
+});

package/src/source-sync/candidate-totals.ts

@@ -0,0 +1,42 @@
+/**
+ * THE ONE FILE COUNT for a candidate review: distinct `sourceId`, never lines.
+ *
+ * A file routed to two company.md documents is two lines and ONE file. The
+ * server computes `SourceSyncCandidateSetResponse.totals` with this over every
+ * line the reader may see; a client that overlays an optimistic edit recomputes
+ * with the same function, so no surface counts "files" its own way.
+ */
+
+import type {
+  SourceSyncCandidateItem,
+  SourceSyncCandidateTotals,
+} from "./schemas";
+
+/** The item facts the count reads. */
+export type CandidateTotalsInput = Pick<
+  SourceSyncCandidateItem,
+  "sourceId" | "included" | "treatmentUnresolved"
+>;
+
+/**
+ * Included when any of the file's lines is; in need of a choice when any
+ * included line's treatment is unresolved.
+ */
+export function candidateTotalsOf(
+  items: readonly CandidateTotalsInput[],
+): SourceSyncCandidateTotals {
+  const files = new Set<string>();
+  const included = new Set<string>();
+  const needingChoice = new Set<string>();
+  for (const item of items) {
+    files.add(item.sourceId);
+    if (!item.included) continue;
+    included.add(item.sourceId);
+    if (item.treatmentUnresolved) needingChoice.add(item.sourceId);
+  }
+  return {
+    files: files.size,
+    filesIncluded: included.size,
+    filesNeedingChoice: needingChoice.size,
+  };
+}

package/src/source-sync/index.ts

@@ -48,6 +48,7 @@ export type {
   SourceSyncDiscoveryRunResponse,
   SourceSyncCandidateItem,
   SourceSyncCandidateSetResponse,
+  SourceSyncCandidateTotals,
   SourceSyncCandidateItemPatch,
   SourceSyncAddCandidateRequest,
   SourceSyncApproveRequest,
@@ -69,6 +70,7 @@ export {
   SourceSyncDiscoveryRunResponseSchema,
   SourceSyncCandidateItemSchema,
   SourceSyncCandidateSetResponseSchema,
+  SourceSyncCandidateTotalsSchema,
   SourceSyncCandidateItemPatchSchema,
   SourceSyncAddCandidateRequestSchema,
   SourceSyncApproveRequestSchema,
@@ -139,3 +141,6 @@ export {
   SourceSyncReachUpgradeRequestSchema,
   SourceSyncReachUpgradeResponseSchema,
 } from "./reach";
+
+export type { CandidateTotalsInput } from "./candidate-totals";
+export { candidateTotalsOf } from "./candidate-totals";

package/src/source-sync/schemas.ts

@@ -118,6 +118,12 @@ export const SourceSyncCandidateItemSchema = z.object({
   recommendedUse: z.enum(SOURCE_USES),
   /** What the person has chosen; null until they (or an accepted default) decide. */
   use: z.enum(SOURCE_USES).nullable(),
+  /**
+   * Whether this line is in the set that approval would land — the SERVER's
+   * answer, never derived from `use`. A decoy, a series' history or a line a
+   * person left out is false while its `use` is still null.
+   */
+  included: z.boolean(),
   /** True while a `widens` item — or one whose fit is not computed yet — has no person-chosen use: approval is refused until none remain. */
   treatmentUnresolved: z.boolean(),
   /** Product-owned copy saying why this file was proposed. Never model-authored prose. */
@@ -128,6 +134,16 @@ export const SourceSyncCandidateItemSchema = z.object({
     .nullable(),
 });
 
+/** Distinct-file totals over every line of a candidate set the caller may see. */
+export const SourceSyncCandidateTotalsSchema = z.object({
+  /** Files in the review: at least one line, included or left out. */
+  files: z.number().int().min(0),
+  /** Files with at least one included line. */
+  filesIncluded: z.number().int().min(0),
+  /** Files with at least one included line whose treatment is unresolved. */
+  filesNeedingChoice: z.number().int().min(0),
+});
+
 /** The draft set under review. `revision` moves on every edit and is echoed on approve. */
 export const SourceSyncCandidateSetResponseSchema = z.object({
   setId: z.string().uuid(),
@@ -138,7 +154,12 @@ export const SourceSyncCandidateSetResponseSchema = z.object({
   /** The low-confidence routing, class and treatment questions, as presented. */
   questions: z.array(DecisionQuestionPresentationSchema).max(50),
   withheldQuestionCount: z.number().int().min(0),
-  unresolvedTreatmentCount: z.number().int().min(0),
+  /**
+   * The review's top-level totals, counted by DISTINCT FILE (`sourceId`) — never
+   * by line. A file routed to two documents is two lines and one file. Every
+   * surface reads these rather than counting `items`, which may be capped.
+   */
+  totals: SourceSyncCandidateTotalsSchema,
   /** Every scope of the set the caller may see, and where its approval stands. */
   scopes: z.array(SourceSyncScopeApprovalProjectionSchema).max(500),
   /** A RANGE, and the cap that is the promise. Null until the estimator has run. */
@@ -378,6 +399,9 @@ export type SourceSyncCandidateItem = z.infer<
 export type SourceSyncCandidateSetResponse = z.infer<
   typeof SourceSyncCandidateSetResponseSchema
 >;
+export type SourceSyncCandidateTotals = z.infer<
+  typeof SourceSyncCandidateTotalsSchema
+>;
 export type SourceSyncCandidateItemPatch = z.infer<
   typeof SourceSyncCandidateItemPatchSchema
 >;