@company-semantics/contracts 79.1.0 → 80.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "79.1.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 = 'c6eea14298b3' as const;
-export const SPEC_HASH_FULL = 'c6eea14298b3f6282e821b61fac860d7c18fbb8af4b5ecf660bc09665a215d9b' as const;
+export const SPEC_HASH = 'c2954b6d06a9' as const;
+export const SPEC_HASH_FULL = 'c2954b6d06a981632d4d61991aa61f16ee28485116ec66949fe08d64cbde4ceb' as const;

package/src/api/generated.ts

@@ -1666,6 +1666,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/analysis-workflows/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read one analysis workflow’s generic lifecycle envelope
+         * @description The domain-agnostic projection a client polls: identity, registered type, activity-free lifecycle state, start and completion times, the opaque domain progress and result payloads (null until the domain adapter supplies them), a closed failure class on a failed workflow, and the capabilities the surface may offer — canStop from the generic layer, canContinue as the domain declares it. Org-scoped: a workflow in another workspace answers 404.
+         */
+        get: operations["getAnalysisWorkflow"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/analysis-workflows/{id}/stop": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Request that an analysis workflow stop at its next safe boundary
+         * @description The one generic COMMAND. Records a cooperative stop request and moves a pending or running workflow to draining; nothing is aborted — the worker halts at a boundary the domain chooses. Answers 202 (acknowledged, not landed) when the request was accepted, and 200 with { stopped: false, reason: "not_running" } when the workflow is already draining or already settled, because a retry against a stopped workflow is a success. Runtime posture: intent write, impersonation allow (a stop only reduces spend). Org-scoped: a workflow in another workspace answers 404.
+         */
+        post: operations["stopAnalysisWorkflow"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/company-md/tree": {
         parameters: {
             query?: never;
@@ -6446,6 +6486,35 @@ export interface components {
             fingerprint: string;
             note?: string;
         };
+        AnalysisWorkflowProjectionResponse: {
+            /** Format: uuid */
+            id: string;
+            type: string;
+            /** @enum {string} */
+            state: "pending" | "running" | "draining" | "stopped" | "complete" | "failed";
+            startedAt: string | null;
+            completedAt: string | null;
+            progress: unknown | null;
+            result: unknown | null;
+            error?: string;
+            capabilities: {
+                canStop: boolean;
+                canContinue: boolean;
+            };
+        };
+        StopAnalysisWorkflowResponse: {
+            /** @constant */
+            stopped: true;
+            /** Format: uuid */
+            workflowId: string;
+            /** @constant */
+            state: "draining";
+        } | {
+            /** @constant */
+            stopped: false;
+            /** @constant */
+            reason: "not_running";
+        };
         CompanyMdListResponse: {
             items: {
                 id: string;
@@ -8584,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;
@@ -8621,7 +8691,11 @@ export interface components {
                 };
             }[];
             withheldQuestionCount: number;
-            unresolvedTreatmentCount: number;
+            totals: {
+                files: number;
+                filesIncluded: number;
+                filesNeedingChoice: number;
+            };
             scopes: {
                 scopeKey: string;
                 /** @enum {string} */
@@ -12121,6 +12195,87 @@ export interface operations {
             };
         };
     };
+    getAnalysisWorkflow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The workflow’s lifecycle envelope with its capabilities */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AnalysisWorkflowProjectionResponse"];
+                };
+            };
+            /** @description The workflow id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    stopAnalysisWorkflow: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Nothing to stop: the workflow is not running */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StopAnalysisWorkflowResponse"];
+                };
+            };
+            /** @description Stop requested; the workflow is draining */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StopAnalysisWorkflowResponse"];
+                };
+            };
+            /** @description The workflow id is not a uuid */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description No such workflow in this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     getCompanyMdTree: {
         parameters: {
             query?: {

package/src/generated/openapi-routes.ts

@@ -9,6 +9,8 @@ export const openApiRoutes = {
   '/api/account/deletion-eligibility': ['GET'],
   '/api/account/sessions': ['GET'],
   '/api/account/sessions/{sessionId}': ['DELETE'],
+  '/api/analysis-workflows/{id}': ['GET'],
+  '/api/analysis-workflows/{id}/stop': ['POST'],
   '/api/auth/consent/grant': ['POST'],
   '/api/billing/price-list': ['GET'],
   '/api/capabilities': ['GET'],

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