@company-semantics/contracts 83.1.0 → 84.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "83.1.0",
+  "version": "84.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 = 'e485ddbb7682' as const;
-export const SPEC_HASH_FULL = 'e485ddbb7682e98908329d4b788ce63dd32e00c23a6360e344d953ae9a42fc0e' as const;
+export const SPEC_HASH = '53f462b4c90b' as const;
+export const SPEC_HASH_FULL = '53f462b4c90ba419e71d55d82e19bb6a9836d95aeaaae6299b8124ac340320d8' as const;

package/src/api/generated.ts

@@ -3367,7 +3367,7 @@ export interface paths {
         };
         /**
          * What I owe and what happened, merged, newest first
-         * @description Actionable rows first, then informational rows newest-first — grouped, not chronologically interleaved. Only the informational half paginates.
+         * @description Actionable rows first (the same in every view), then the informational rows of the requested view (view: all | unread) — unread-and-unresolved first, each by latest activity. Grouped, not chronologically interleaved. Only the informational half paginates.
          */
         get: operations["listMyFeed"];
         put?: never;
@@ -3387,7 +3387,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Mark specific notifications read */
+        /**
+         * Mark selected notifications read
+         * @description Selected by ids or by view snapshot (asOf). Only the actor’s own rows.
+         */
         post: operations["markMyFeedRead"];
         delete?: never;
         options?: never;
@@ -3412,6 +3415,83 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/me/feed/unread": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Mark selected notifications unread
+         * @description Selected by ids or by view snapshot (asOf). Resolved and deleted rows are never marked unread.
+         */
+        post: operations["markMyFeedUnread"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/feed/delete": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Delete selected notifications, undoable by restore
+         * @description Soft-deletes the actor’s own selected rows under one opaque restoreKey. The entity a row is about is never touched.
+         */
+        post: operations["deleteMyFeedItems"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/feed/restore": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Undo a delete by its restoreKey
+         * @description Restores the rows one delete removed. A row whose condition already has a newer active row stays deleted and is counted as superseded.
+         */
+        post: operations["restoreMyFeedItems"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/me/feed/clear-resolved": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Delete every resolved notification, undoable by restore */
+        post: operations["clearMyFeedResolved"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/me/meetings/recordings/start": {
         parameters: {
             query?: never;
@@ -7715,6 +7795,62 @@ export interface components {
             unreadCount: number;
             truncated: boolean;
         };
+        FeedMutationResponse: {
+            affected: number;
+        };
+        FeedMarkReadRequest: {
+            selector: {
+                /** @constant */
+                kind: "ids";
+                notificationIds: string[];
+            } | {
+                /** @constant */
+                kind: "view";
+                /** @enum {string} */
+                view: "all" | "unread";
+                /** Format: date-time */
+                asOf: string;
+            };
+        };
+        FeedMarkUnreadRequest: {
+            selector: {
+                /** @constant */
+                kind: "ids";
+                notificationIds: string[];
+            } | {
+                /** @constant */
+                kind: "view";
+                /** @enum {string} */
+                view: "all" | "unread";
+                /** Format: date-time */
+                asOf: string;
+            };
+        };
+        FeedDeleteResponse: {
+            affected: number;
+            restoreKey: string;
+        };
+        FeedDeleteRequest: {
+            selector: {
+                /** @constant */
+                kind: "ids";
+                notificationIds: string[];
+            } | {
+                /** @constant */
+                kind: "view";
+                /** @enum {string} */
+                view: "all" | "unread";
+                /** Format: date-time */
+                asOf: string;
+            };
+        };
+        FeedRestoreResponse: {
+            restored: number;
+            superseded: number;
+        };
+        FeedRestoreRequest: {
+            restoreKey: string;
+        };
         /** @description Recording + work_item ids and the transcription session grant. */
         StartMeetingRecordingResponse: {
             /** @description ULID; unified trace key for the recording (INV-MTG-7). */
@@ -8740,7 +8876,10 @@ export interface components {
                 targetDocId: string;
                 targetDocTitle: string;
                 /** @enum {string} */
-                sourceClass: "board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy";
+                visibility: "hidden" | "shown";
+                /** @enum {string} */
+                classificationState: "unclassified" | "classified";
+                sourceClass: ("board_deck" | "board_minutes" | "investor_update" | "financial_brief" | "budget_forecast" | "okr_plan" | "annual_plan" | "all_hands" | "unit_strategy" | "roadmap" | "qbr" | "other" | "decoy") | null;
                 periodLabel: string | null;
                 seriesRole: ("current" | "history") | null;
                 relevance: number;
@@ -8750,9 +8889,42 @@ export interface components {
                 sharingBreadth: "restricted_few" | "group" | "domain" | "anyone" | "unknown";
                 sharedWithCount: number | null;
                 audienceFit: ("fits" | "widens") | null;
-                /** @enum {string} */
-                recommendedUse: "attached" | "direction_only" | "excluded";
+                recommendedUse: ("attached" | "direction_only" | "excluded") | null;
                 use: ("attached" | "direction_only" | "excluded") | null;
+                selectionSource: ("person" | "approval_default") | null;
+                personHoldReasons: ("relevance_override" | "treatment_selection" | "target_override" | "manual_add")[];
+                /** @enum {string} */
+                machineState: "fresh" | "refreshed" | "filtered_out" | "not_rediscovered" | "pending_classification" | "retired";
+                relevanceReasons: ({
+                    /** @constant */
+                    kind: "lexicon";
+                    /** @enum {string} */
+                    code: "title_term" | "folder_term" | "negative_title_term" | "negative_folder_term";
+                    term: string;
+                    count: number;
+                } | {
+                    /** @constant */
+                    kind: "signal";
+                    /** @enum {string} */
+                    code: "folder_probe_hit" | "title_probe_hit" | "version_churn" | "mime_class" | "size_band" | "dated_series" | "recent_edit" | "owner_unit_head" | "owner_executive" | "sharing_breadth" | "duplicate_title" | "personal_mime";
+                    value: number | null;
+                } | {
+                    /** @constant */
+                    kind: "evaluation";
+                    /** @enum {string} */
+                    code: "not_evaluated_t1" | "not_evaluated_t2" | "folder_unresolved" | "folder_truncated" | "explored_t1" | "explored_t2";
+                } | {
+                    /** @constant */
+                    kind: "model";
+                    /** @enum {string} */
+                    code: "title_path_score" | "peek_confirms" | "peek_contradicts";
+                    score: number | null;
+                })[];
+                targetAudience: ("restricted" | "unit" | "org_wide") | null;
+                attention: {
+                    t1: ("exploit" | "explore") | null;
+                    t2: ("exploit" | "explore") | null;
+                };
                 included: boolean;
                 treatmentUnresolved: boolean;
                 matchReason: string;
@@ -8795,6 +8967,9 @@ export interface components {
                 files: number;
                 filesIncluded: number;
                 filesNeedingChoice: number;
+                filesHidden: number;
+                filesNotRediscovered: number;
+                filesPendingClassification: number;
             };
             scopes: {
                 scopeKey: string;
@@ -8817,6 +8992,16 @@ export interface components {
                 highMicroUsd: string;
                 capMicroUsd: string;
             } | null;
+            discovery: {
+                foundThisRun: number;
+                retainedDecisions: number;
+                notRediscovered: number;
+                pendingClassification: number;
+                filesDropped: number;
+                coveragePercent: number;
+                /** @enum {string} */
+                scanOutcome: "complete" | "budget_exhausted" | "file_ceiling" | "stopped";
+            } | null;
         };
         SourceSyncApproveResponse: {
             /** Format: uuid */
@@ -15352,7 +15537,8 @@ export interface operations {
     };
     listMyFeed: {
         parameters: {
-            query?: {
+            query: {
+                view: "all" | "unread";
                 cursor?: string;
             };
             header?: never;
@@ -15379,14 +15565,20 @@ export interface operations {
             path?: never;
             cookie?: never;
         };
-        requestBody?: never;
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedMarkReadRequest"];
+            };
+        };
         responses: {
-            /** @description Read state applied to the actor’s own rows */
+            /** @description How many of the actor’s own rows were marked read */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["FeedMutationResponse"];
+                };
             };
         };
     };
@@ -15399,12 +15591,106 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Read state applied to the actor’s own rows */
+            /** @description How many of the actor’s own rows were marked read */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["FeedMutationResponse"];
+                };
+            };
+        };
+    };
+    markMyFeedUnread: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedMarkUnreadRequest"];
+            };
+        };
+        responses: {
+            /** @description How many of the actor’s own rows were marked unread */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedMutationResponse"];
+                };
+            };
+        };
+    };
+    deleteMyFeedItems: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedDeleteRequest"];
+            };
+        };
+        responses: {
+            /** @description How many rows were deleted, and the key that restores exactly them */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedDeleteResponse"];
+                };
+            };
+        };
+    };
+    restoreMyFeedItems: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["FeedRestoreRequest"];
+            };
+        };
+        responses: {
+            /** @description How many rows were restored, and how many a newer row superseded */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedRestoreResponse"];
+                };
+            };
+        };
+    };
+    clearMyFeedResolved: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description How many resolved rows were deleted, and the key that restores them */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FeedDeleteResponse"];
+                };
             };
         };
     };
@@ -17647,6 +17933,8 @@ export interface operations {
         requestBody: {
             content: {
                 "application/json": {
+                    /** @constant */
+                    visibility?: "shown";
                     /** @enum {string} */
                     use?: "attached" | "direction_only" | "excluded";
                     /** @enum {string} */

package/src/generated/openapi-routes.ts

@@ -103,8 +103,12 @@ export const openApiRoutes = {
   '/api/me/action-items': ['GET'],
   '/api/me/events': ['GET'],
   '/api/me/feed': ['GET'],
+  '/api/me/feed/clear-resolved': ['POST'],
+  '/api/me/feed/delete': ['POST'],
   '/api/me/feed/read': ['POST'],
   '/api/me/feed/read-all': ['POST'],
+  '/api/me/feed/restore': ['POST'],
+  '/api/me/feed/unread': ['POST'],
   '/api/me/md': ['GET'],
   '/api/me/meetings/recordings/start': ['POST'],
   '/api/me/meetings/recordings/{id}': ['DELETE'],

package/src/source-sync/README.md

@@ -107,6 +107,54 @@ way. This directory holds that shared spelling.
   domain is the largest trust change in the wave, and an empty body is
   indistinguishable from a mistaken or replayed body-less POST.
 
+## Relevance
+
+Doctrine: control ADR `source-discovery-relevance-funnel`. Vocabulary: ADR
+`source-discovery-relevance-vocabulary`. The sets live in `relevance.ts`.
+
+- **Two axes on the wire.**
+  - **Relevance** is the funnel's verdict: `visibility` is `shown` or
+    `hidden`.
+  - **Treatment** is a person's decision: `recommendedUse` (machine state,
+    null until classified), `use` (the committed treatment, null until
+    chosen) and `selectionSource` (`person` or `approval_default`, present
+    exactly when `use` is).
+
+  Neither axis changes the other. The disclosure question is asked only of
+  lines that cleared relevance.
+
+- **Hidden is not dropped.** `SOURCE_RELEVANCE_TIERS` includes `dropped` so the
+  backend can mirror it in persistence, but the item schema excludes it: a
+  dropped sighting never reaches the wire. A hidden line sits behind the
+  drawer, is never `included`, and a person can bring it into review with the
+  patch `{ visibility: "shown" }`. The patch changes exactly one field, so
+  promoting a line never also commits a treatment, and no client can hide a
+  line.
+- **Classification is separate from visibility.** `classificationState` is
+  `unclassified` (so `sourceClass` and `recommendedUse` are both null) or
+  `classified` (both non-null). A shown line can still be
+  `pending_classification` in its `machineState`.
+- **Reasons are a discriminated union.** `relevanceReasons` (≤ 8) is
+  `RelevanceReason`: `lexicon` (a product-owned `term` and a `count`),
+  `signal` (a `value` or null), `evaluation` (a code only) or `model` (a
+  `score` or null). Each kind has its own disjoint code set, and the app
+  switches over `kind`, then `code`, exhaustively. `relevance` is the fused
+  score, and `matchReason` is server copy rendered from the reasons
+  (deprecated).
+- **Holds and lifecycle travel on the item.** `personHoldReasons` are the
+  field-level barriers a person's actions placed on the line. `machineState`
+  is its lifecycle (`fresh`, `refreshed`, `filtered_out`, `not_rediscovered`,
+  `pending_classification`, `retired`). `attention` says which lane
+  (`exploit` or `explore`) earned each model tier's look.
+- **Attach shows its audience.** `targetAudience` is the audience Attach would
+  disclose to. Null means unknown and reads as "may widen".
+- **No single ambiguous total.** `discovery` on the set response carries the
+  last completed run's counts (found, retained decisions, not rediscovered,
+  pending classification, dropped, coverage and how the scan ended). It is
+  null before any run completes. `totals` adds `filesHidden`,
+  `filesNotRediscovered` and `filesPendingClassification`, counted by
+  `candidateTotalsOf` over distinct files.
+
 ## Public API
 
 - `SOURCE_CLASSES` / `SourceClass` — what kind of document a source is.
@@ -135,7 +183,16 @@ way. This directory holds that shared spelling.
   `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.
+  edit to one candidate item: exactly one of visibility (`shown` only), use,
+  class or target.
+- `SOURCE_RELEVANCE_TIERS`, `CLASSIFICATION_STATES`, `RELEVANCE_REASON_KINDS`,
+  `LEXICON_REASON_CODES`, `SIGNAL_REASON_CODES`, `EVALUATION_REASON_CODES`,
+  `MODEL_REASON_CODES`, `TARGET_AUDIENCES`, `ATTENTION_LANES`,
+  `CANDIDATE_MACHINE_STATES`, `SELECTION_SOURCES`, `PERSON_HOLD_REASONS`,
+  `SCAN_OUTCOMES` and their derived unions — the relevance vocabulary (see
+  Relevance).
+- `RelevanceReasonSchema` / `RelevanceReason` — why a candidate scored as it
+  did: a discriminated union on `kind`.
 - `SourceSyncAddCandidateRequestSchema` / `SourceSyncAddCandidateRequest` —
   "add one I missed": a provider file id picked in the provider's own search.
 - `SourceSyncApproveRequestSchema` / `SourceSyncApproveRequest` — approve the
@@ -210,4 +267,5 @@ way. This directory holds that shared spelling.
 
 `rules.ts` imports only `zod`, `../api/primitives` and `./vocabulary`.
 `upkeep.ts` and `reach.ts` import only `zod` and `../api/primitives`.
+`relevance.ts` imports only `zod`.
 `vocabulary.ts` itself has no imports.

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

@@ -5,8 +5,8 @@
  * backend answers with.
  *
  * INVARIANTS TESTED:
- * - A candidate patch changes something: an empty patch is refused, and an
- *   unknown key is an error, not surplus.
+ * - A candidate patch changes exactly one thing: an empty patch is refused, and
+ *   an unknown key is an error, not surplus.
  * - An approval echoes the revision the person reviewed and carries the spend
  *   cap as integer micro-USD; either one missing is refused.
  * - An approval answers PER SCOPE: one row per scope approved, each bound to its

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

@@ -16,6 +16,8 @@
  *   below, which fails typecheck if one is missing at the root).
  * - The same two checks hold for the Release D names: staleness findings,
  *   standing orders and the Drive-reach shapes.
+ * - Every runtime name `relevance.ts` declares is reachable from the root as
+ *   the same binding.
  * - `ACTION_ITEM_KINDS` at the root carries `sourceSync.approval_pending`.
  * - The root re-exports the domain barrel explicitly.
  *
@@ -66,6 +68,7 @@ import type {
   SourceSyncStandingOrdersResponse,
 } from "../../index";
 import * as reach from "../reach";
+import * as relevance from "../relevance";
 import * as rules from "../rules";
 import * as schemas from "../schemas";
 import * as upkeep from "../upkeep";
@@ -236,6 +239,17 @@ describe("source-sync Release C package surface", () => {
     }
   });
 
+  it("every discovery relevance set is exported from the package root", () => {
+    const root = rootBarrel as Record<string, unknown>;
+    const names = Object.keys(relevance);
+    expect(names.length).toBeGreaterThan(0);
+    for (const name of names) {
+      expect(root[name], `${name} at the root`).toBe(
+        (relevance as Record<string, unknown>)[name],
+      );
+    }
+  });
+
   it("exposes sourceSync.approval_pending in ACTION_ITEM_KINDS at the root", () => {
     expect(rootBarrel.ACTION_ITEM_KINDS).toContain(
       "sourceSync.approval_pending",

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

@@ -0,0 +1,119 @@
+/**
+ * The one file count for a candidate review.
+ *
+ * INVARIANTS TESTED:
+ * - Every total counts DISTINCT files (`sourceId`), never lines: a file routed to
+ *   two documents is two lines and one file in every total.
+ * - A file is hidden only when EVERY line of it is hidden; one shown line shows it.
+ * - A file is not rediscovered / pending classification when ANY line of it is.
+ */
+
+import { describe, expect, it } from "vitest";
+import { candidateTotalsOf, type CandidateTotalsInput } from "../index";
+
+function line(
+  sourceId: string,
+  overrides: Partial<CandidateTotalsInput> = {},
+): CandidateTotalsInput {
+  return {
+    sourceId,
+    included: true,
+    treatmentUnresolved: false,
+    visibility: "shown",
+    machineState: "fresh",
+    ...overrides,
+  };
+}
+
+describe("candidateTotalsOf", () => {
+  it("counts distinct files, never lines", () => {
+    expect(
+      candidateTotalsOf([
+        line("a", { treatmentUnresolved: true }),
+        line("a"),
+        line("b", { included: false, treatmentUnresolved: true }),
+        line("c"),
+      ]),
+    ).toEqual({
+      files: 3,
+      filesIncluded: 2,
+      filesNeedingChoice: 1,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 0,
+    });
+  });
+
+  it("a file is hidden only when every line of it is hidden", () => {
+    const hidden = { visibility: "hidden", included: false } as const;
+    const totals = candidateTotalsOf([
+      line("partly", hidden),
+      line("partly"),
+      line("wholly", hidden),
+      line("wholly", hidden),
+      line("shown"),
+    ]);
+    expect(totals.files).toBe(3);
+    expect(totals.filesHidden).toBe(1);
+    expect(totals.filesIncluded).toBe(2);
+  });
+
+  it("a file is not rediscovered or pending classification when any line of it is", () => {
+    const totals = candidateTotalsOf([
+      line("a", { machineState: "not_rediscovered" }),
+      line("a", { machineState: "refreshed" }),
+      line("b", { machineState: "pending_classification" }),
+      line("b"),
+      line("c", { machineState: "retired" }),
+    ]);
+    expect(totals.filesNotRediscovered).toBe(1);
+    expect(totals.filesPendingClassification).toBe(1);
+  });
+
+  it("a file routed to two documents counts once in every total", () => {
+    const facts = {
+      treatmentUnresolved: true,
+      visibility: "hidden",
+      machineState: "not_rediscovered",
+      included: false,
+    } as const;
+    const hiddenTwice = candidateTotalsOf([line("a", facts), line("a", facts)]);
+    expect(hiddenTwice).toEqual({
+      files: 1,
+      filesIncluded: 0,
+      filesNeedingChoice: 0,
+      filesHidden: 1,
+      filesNotRediscovered: 1,
+      filesPendingClassification: 0,
+    });
+    const shownTwice = candidateTotalsOf([
+      line("a", {
+        treatmentUnresolved: true,
+        machineState: "pending_classification",
+      }),
+      line("a", {
+        treatmentUnresolved: true,
+        machineState: "pending_classification",
+      }),
+    ]);
+    expect(shownTwice).toEqual({
+      files: 1,
+      filesIncluded: 1,
+      filesNeedingChoice: 1,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 1,
+    });
+  });
+
+  it("counts nothing for an empty review", () => {
+    expect(candidateTotalsOf([])).toEqual({
+      files: 0,
+      filesIncluded: 0,
+      filesNeedingChoice: 0,
+      filesHidden: 0,
+      filesNotRediscovered: 0,
+      filesPendingClassification: 0,
+    });
+  });
+});