@company-semantics/contracts 80.0.0 → 81.0.0

package/package.json

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