@company-semantics/contracts 79.2.0 → 81.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "79.2.0",
+  "version": "81.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 = '7e0656a03459' as const;
+export const SPEC_HASH_FULL = '7e0656a03459e90e26051fe9aea403e95f0de11fea465f6a0f00ae5caf8b0aa7' as const;

package/src/api/generated.ts

@@ -7438,50 +7438,55 @@ export interface components {
         };
         OrgUsageResponse: {
             period: {
+                /** Format: date-time */
                 start: string;
+                /** Format: date-time */
                 end: string;
+                timezone: string;
             };
             summary: {
-                executions: number;
-                totalCostUsd: string;
-                totalTokens: number;
-                avgDurationMs: number;
-                failureRate: number;
+                requests: number;
+                tokens: number;
+                customerChargeMicros: string;
             };
             daily: {
                 date: string;
-                executions: number;
-                totalCostUsd: string;
-            }[];
-            byProfile: {
-                profile: string;
-                executions: number;
-                percentOfTotal: number;
-                totalCostUsd: string;
-                avgDurationMs: number;
-                failureRate: number;
+                requests: number;
+                customerChargeMicros: string;
             }[];
-            byUser: {
-                userId: string;
-                email: string;
-                executions: number;
-                totalCostUsd: string;
-                totalTokens: number;
-                favoriteProfile: string;
+            byFeature: {
+                requests: number;
+                tokens: number;
+                customerChargeMicros: string;
+                /** @enum {string} */
+                feature: "chat" | "chat_title" | "ingest_summarize" | "ingest_embedding" | "company_md_extraction" | "org_chart_import" | "org_structure_inference" | "source_sync_discovery" | "source_sync_digest" | "source_sync_synthesis" | "comment_agent_reply" | "slack_mention_reply" | "structure_review_interpret" | "retrieval_embedding" | "company_md_embedding" | "meeting_embedding" | "unattributed";
             }[];
             byModel: {
-                model: string;
+                requests: number;
+                tokens: number;
+                customerChargeMicros: string;
                 provider: string;
-                totalTokens: number;
-                estimatedCostUsd: string;
-                requestCount: number;
+                modelId: string;
             }[];
-            byFeature: {
-                feature: string;
-                totalTokens: number;
-                estimatedCostUsd: string;
-                requestCount: number;
+            byUser: {
+                requests: number;
+                tokens: number;
+                customerChargeMicros: string;
+                userId: string;
+                email: string | null;
             }[];
+            chatRuns: {
+                executions: number;
+                avgDurationMs: number;
+                failureRate: number;
+                byProfile: {
+                    profile: string;
+                    executions: number;
+                    percentOfTotal: number;
+                    avgDurationMs: number;
+                    failureRate: number;
+                }[];
+            };
         };
         AccountDeletionEligibilityResponse: {
             eligible: boolean;
@@ -8653,6 +8658,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 +8696,11 @@ export interface components {
                 };
             }[];
             withheldQuestionCount: number;
-            unresolvedTreatmentCount: number;
+            totals: {
+                files: number;
+                filesIncluded: number;
+                filesNeedingChoice: number;
+            };
             scopes: {
                 scopeKey: string;
                 /** @enum {string} */
@@ -14807,7 +14817,6 @@ export interface operations {
         parameters: {
             query?: {
                 period?: "current_month" | "last_30_days" | "last_7_days";
-                tz?: string;
             };
             header?: never;
             path: {

package/src/index.ts

@@ -1298,15 +1298,10 @@ export type {
   ImpersonationSseEvent,
 } from "./impersonation-events";
 
-// Usage tracking types (internal admin)
-// @see PRD-00166 for design rationale
+// AI features (INV-AI-ATTRIBUTION) and the internal-admin telemetry usage types
+export { AI_FEATURES, AI_FEATURE_LABELS } from "./usage/features";
 export type {
   AiFeature,
-  UsageSummary,
-  DailyUsage,
-  UsageByModel,
-  UsageByFeature,
-  UsageByUser,
   // Unified usage types (PRD-00276/277)
   UnifiedUsageSummary,
   UnifiedDailyUsage,

package/src/org/README.md

@@ -513,6 +513,7 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `decisions`
 - `identity`
 - `permissions`
+- `usage`
 
 **External packages:**
 

package/src/org/schemas.ts

@@ -12,7 +12,8 @@
  */
 import { z } from "zod";
 import { CursorPageSchema, IsoDateTime } from "../api/primitives";
-import { AI_PAUSE_REASONS } from "../billing/vocabulary";
+import { AI_PAUSE_REASONS, MoneyMicrosSchema } from "../billing/vocabulary";
+import { AI_FEATURES } from "../usage/features";
 import { OrgChartRoleSchema } from "../permissions/orgchart-roles";
 import { PositionRefSchema } from "../identity/position-ref";
 import {
@@ -1385,64 +1386,68 @@ export type AcknowledgeSystemEventResponse = z.infer<
 
 // ---------------------------------------------------------------------------
 // GET /api/orgs/:orgId/ai-usage
-// Matches UnifiedUsageResponse from usage/types.ts
+//
+// INV-USAGE-LEDGER: every request, token and dollar here is read from the
+// settled billing ledger (`billing_usage_events`) — one row per billed provider
+// call, whatever feature made it. A `request` is one settled billable provider
+// invocation (retries and fallbacks are separate requests), every amount is
+// the customer charge in integer micro-USD, and `tokens` is input + output +
+// cache read + cache write (reasoning is a subset of output, never added).
+// `chatRuns` alone comes from runtime telemetry: duration and failure
+// diagnostics for chat turns, carrying no money.
 // ---------------------------------------------------------------------------
 
-const UnifiedUsageSummarySchema = z.object({
-  executions: z.number(),
-  totalCostUsd: z.string(),
-  totalTokens: z.number(),
-  avgDurationMs: z.number(),
-  failureRate: z.number(),
-});
-
-const UnifiedDailyUsageSchema = z.object({
-  date: z.string(),
-  executions: z.number(),
-  totalCostUsd: z.string(),
+const OrgAiUsageTotalsSchema = z.object({
+  requests: z.number().int().min(0),
+  tokens: z.number().int().min(0),
+  customerChargeMicros: MoneyMicrosSchema,
 });
 
-const UnifiedProfileUsageSchema = z.object({
+const OrgChatRunProfileSchema = z.object({
   profile: z.string(),
-  executions: z.number(),
+  executions: z.number().int().min(0),
   percentOfTotal: z.number(),
-  totalCostUsd: z.string(),
   avgDurationMs: z.number(),
   failureRate: z.number(),
 });
 
-const UnifiedUserUsageSchema = z.object({
-  userId: z.string(),
-  email: z.string(),
-  executions: z.number(),
-  totalCostUsd: z.string(),
-  totalTokens: z.number(),
-  favoriteProfile: z.string(),
-});
-
-const UnifiedModelUsageSchema = z.object({
-  model: z.string(),
-  provider: z.string(),
-  totalTokens: z.number(),
-  estimatedCostUsd: z.string(),
-  requestCount: z.number(),
-});
-
-const UnifiedFeatureUsageSchema = z.object({
-  feature: z.string(),
-  totalTokens: z.number(),
-  estimatedCostUsd: z.string(),
-  requestCount: z.number(),
-});
-
 export const OrgUsageResponseSchema = z.object({
-  period: z.object({ start: z.string(), end: z.string() }),
-  summary: UnifiedUsageSummarySchema,
-  daily: z.array(UnifiedDailyUsageSchema),
-  byProfile: z.array(UnifiedProfileUsageSchema),
-  byUser: z.array(UnifiedUserUsageSchema),
-  byModel: z.array(UnifiedModelUsageSchema),
-  byFeature: z.array(UnifiedFeatureUsageSchema),
+  /** The org's billing window: `start`/`end` in UTC, days bucketed in `timezone`. */
+  period: z.object({
+    start: IsoDateTime,
+    end: IsoDateTime,
+    timezone: z.string(),
+  }),
+  summary: OrgAiUsageTotalsSchema,
+  daily: z.array(
+    z.object({
+      date: z.string(),
+      requests: z.number().int().min(0),
+      customerChargeMicros: MoneyMicrosSchema,
+    }),
+  ),
+  byFeature: z.array(
+    OrgAiUsageTotalsSchema.extend({ feature: z.enum(AI_FEATURES) }),
+  ),
+  byModel: z.array(
+    OrgAiUsageTotalsSchema.extend({
+      provider: z.string(),
+      modelId: z.string(),
+    }),
+  ),
+  /** Attributed usage only: system work (no user) counts in the totals, not here. */
+  byUser: z.array(
+    OrgAiUsageTotalsSchema.extend({
+      userId: z.string(),
+      email: z.string().nullable(),
+    }),
+  ),
+  chatRuns: z.object({
+    executions: z.number().int().min(0),
+    avgDurationMs: z.number(),
+    failureRate: z.number(),
+    byProfile: z.array(OrgChatRunProfileSchema),
+  }),
 });
 
 export type OrgUsageResponse = z.infer<typeof OrgUsageResponseSchema>;

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

package/src/usage/features.ts

@@ -0,0 +1,56 @@
+/**
+ * AI features — what work caused a billed model call (INV-AI-ATTRIBUTION).
+ *
+ * The CANONICAL list is the backend's Postgres `ai_feature` enum; this mirror
+ * is checked against it by a backend type test in both directions, so a value
+ * added on one side without the other cannot typecheck. Order follows the
+ * enum's (append-only) order.
+ *
+ * `unattributed` is a failure-containment state, not an accepted feature: a
+ * production model call that reached the billing gate with no attribution.
+ */
+export const AI_FEATURES = [
+  "chat",
+  "chat_title",
+  "ingest_summarize",
+  "ingest_embedding",
+  "company_md_extraction",
+  "org_chart_import",
+  "org_structure_inference",
+  "source_sync_discovery",
+  "source_sync_digest",
+  "source_sync_synthesis",
+  "comment_agent_reply",
+  "slack_mention_reply",
+  "structure_review_interpret",
+  "retrieval_embedding",
+  "company_md_embedding",
+  "meeting_embedding",
+  "unattributed",
+] as const;
+
+export type AiFeature = (typeof AI_FEATURES)[number];
+
+/**
+ * The one display name per feature, Sentence case. `satisfies` so a new
+ * feature cannot render as a raw enum value or go unlabeled.
+ */
+export const AI_FEATURE_LABELS = {
+  chat: "Chat",
+  chat_title: "Chat titles",
+  ingest_summarize: "Slack summaries",
+  ingest_embedding: "Slack indexing",
+  company_md_extraction: "Document extraction",
+  org_chart_import: "Org chart import",
+  org_structure_inference: "Org structure analysis",
+  source_sync_discovery: "Google Drive search",
+  source_sync_digest: "Google Drive file reading",
+  source_sync_synthesis: "Google Drive drafting",
+  comment_agent_reply: "Comment replies",
+  slack_mention_reply: "Slack replies",
+  structure_review_interpret: "Org review answers",
+  retrieval_embedding: "Search queries",
+  company_md_embedding: "Document indexing",
+  meeting_embedding: "Meeting indexing",
+  unattributed: "Unattributed",
+} as const satisfies Record<AiFeature, string>;

package/src/usage/types.ts

@@ -1,55 +1,12 @@
 /**
- * AI Usage Tracking Types (v1)
- * Internal admin usage visibility. Not org-facing in v1.
- * See PRD-00166 for design rationale and invariants.
+ * AI usage telemetry types — the internal-admin usage views (runtime
+ * executions). The org-facing AI usage page reads the billing ledger instead;
+ * its shape is `OrgUsageResponseSchema` in `org/schemas.ts` (INV-USAGE-LEDGER).
  */
 
-export type AiFeature =
-  | "chat"
-  | "chat_title"
-  | "ingest_summarize"
-  | "ingest_embedding"
-  | "company_md_extraction";
+import type { AiFeature } from "./features";
 
-export interface UsageSummary {
-  totalTokens: number;
-  totalInputTokens: number;
-  totalOutputTokens: number;
-  estimatedCostUsd: string;
-  requestCount: number;
-  periodStart: string; // UTC ISO8601
-  periodEnd: string; // UTC ISO8601
-}
-
-export interface DailyUsage {
-  date: string; // YYYY-MM-DD
-  totalTokens: number;
-  estimatedCostUsd: string;
-  requestCount: number;
-}
-
-export interface UsageByModel {
-  model: string;
-  provider: string;
-  totalTokens: number;
-  estimatedCostUsd: string;
-  requestCount: number;
-}
-
-export interface UsageByFeature {
-  feature: AiFeature;
-  totalTokens: number;
-  estimatedCostUsd: string;
-  requestCount: number;
-}
-
-export interface UsageByUser {
-  userId: string;
-  email: string;
-  totalTokens: number;
-  estimatedCostUsd: string;
-  requestCount: number;
-}
+export type { AiFeature };
 
 // ---------------------------------------------------------------------------
 // Unified Usage Response (PRD-00276/277)