@company-semantics/contracts 86.0.0 → 87.0.0

package/src/chat/types.ts

@@ -8,7 +8,6 @@
 
 import { z } from "zod";
 import {
-  ChatVisibilitySchema,
   TitleSourceSchema,
   InvalidationReasonSchema,
   ChatChangedFieldSchema,
@@ -17,9 +16,6 @@ import {
   ChatSummaryExtendedSchema,
   ProactiveChatResolutionSchema,
   TitleGenerationResponseSchema,
-  ChatShareInfoSchema,
-  SharedChatViewSchema,
-  SharedChatMessageSchema,
   BaseEventSchema,
   ChatCreatedEventSchema,
   ChatUpdatedEventSchema,
@@ -33,13 +29,11 @@ import {
   ChatByInteractionResponseSchema,
   ChatListResponseSchema,
   CreateChatResponseSchema,
-  CreateShareResponseSchema,
-  ListSharesResponseSchema,
-  UpdateShareResponseSchema,
   ChatMessageSchema,
   ChatMessageMentionSchema,
   ChatMentionableResponseSchema,
   ChatParticipantRoleSchema,
+  ChatGrantableRoleSchema,
   ChatParticipantSchema,
   ChatParticipantsResponseSchema,
   ChatDetailSchema,
@@ -48,17 +42,6 @@ import {
   ChatPageContextSchema,
 } from "./schemas";
 
-// =============================================================================
-// Visibility
-// =============================================================================
-
-/**
- * Chat share visibility.
- * - private: Token exists but access requires authentication as chat owner
- * - public: Token grants anonymous access to anyone with the link
- */
-export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>;
-
 // =============================================================================
 // Chat Summary
 // =============================================================================
@@ -68,53 +51,6 @@ export type ChatVisibility = z.infer<typeof ChatVisibilitySchema>;
  */
 export type ChatSummary = z.infer<typeof ChatSummarySchema>;
 
-// =============================================================================
-// Share Types
-// =============================================================================
-
-/**
- * Chat share record with snapshot metadata.
- *
- * CRITICAL INVARIANT (SNAPSHOT-1):
- * A chat share must never expose messages with sequenceNumber > messageCountAtShare.
- * Enforced in ChatShareService.viewSharedChat() only.
- */
-export type ChatShareInfo = z.infer<typeof ChatShareInfoSchema>;
-
-/**
- * Shared chat view returned to viewers.
- * Messages are limited by the snapshot boundary.
- */
-export type SharedChatView = z.infer<typeof SharedChatViewSchema>;
-
-/**
- * Individual message in a shared chat view.
- */
-export type SharedChatMessage = z.infer<typeof SharedChatMessageSchema>;
-
-// =============================================================================
-// API Request/Response Types
-// =============================================================================
-
-/**
- * Request to create a new share for a chat.
- */
-export interface CreateShareRequest {
-  chatId: string;
-  visibility: ChatVisibility;
-  /** Optional: send email notification to this address */
-  recipientEmail?: string;
-}
-
-/**
- * Request to update an existing share.
- */
-export interface UpdateShareRequest {
-  visibility?: ChatVisibility;
-  /** If true, update snapshot to include new messages added since share creation */
-  updateSnapshot?: boolean;
-}
-
 // =============================================================================
 // Chat Lifecycle Types
 // =============================================================================
@@ -288,15 +224,6 @@ export type ChatListResponse = z.infer<typeof ChatListResponseSchema>;
 /** Response for POST /api/chats */
 export type CreateChatResponse = z.infer<typeof CreateChatResponseSchema>;
 
-/** Response for POST /api/chats/:chatId/shares */
-export type CreateShareResponse = z.infer<typeof CreateShareResponseSchema>;
-
-/** Response for GET /api/chats/:chatId/shares */
-export type ListSharesResponse = z.infer<typeof ListSharesResponseSchema>;
-
-/** Response for PATCH /api/shares/:shareId */
-export type UpdateShareResponse = z.infer<typeof UpdateShareResponseSchema>;
-
 /** Individual message in a chat response (GET /api/chats/:id). */
 export type ChatMessage = z.infer<typeof ChatMessageSchema>;
 
@@ -316,12 +243,33 @@ export type ChatMentionableResponse = z.infer<
 // =============================================================================
 
 /**
- * What one person is to a chat: `owner` or `participant`. Participation, not an
- * access band — there is no `viewer` and no per-participant scope, because a
- * chat you can read half of is not a thing this surface models.
+ * What one person is to a chat: `owner`, `participant` (Collaborate) or
+ * `viewer` (Read only). Whole-chat access, never a per-participant scope
+ * (ADR-CONTRACTS-206).
  */
 export type ChatParticipantRole = z.infer<typeof ChatParticipantRoleSchema>;
 
+/** A role a share can grant: `participant` (Collaborate) or `viewer` (Read only). */
+export type ChatGrantableRole = z.infer<typeof ChatGrantableRoleSchema>;
+
+/**
+ * Request for POST /api/chats/:chatId/participants — sharing the chat with one
+ * org member at a grantable role. A request-only type (no runtime schema), like
+ * the other chat requests.
+ */
+export interface AddChatParticipantRequest {
+  userId: string;
+  role: ChatGrantableRole;
+}
+
+/**
+ * Request for PATCH /api/chats/:chatId/participants/:userId — the owner moving
+ * someone between Read only and Collaborate.
+ */
+export interface UpdateChatParticipantRequest {
+  role: ChatGrantableRole;
+}
+
 /**
  * One ACTIVE participant of a chat — a user id, a role, a read-time display
  * name and when they joined. Never a `PrincipalRef`: the agent takes part in

package/src/generated/openapi-routes.ts

@@ -21,13 +21,12 @@ export const openApiRoutes = {
   '/api/chats/mentionable': ['GET'],
   '/api/chats/proactive/{eventId}': ['GET'],
   '/api/chats/resolve-launch': ['POST'],
-  '/api/chats/{chatId}/shares': ['GET', 'POST'],
   '/api/chats/{id}': ['DELETE', 'GET', 'PATCH'],
   '/api/chats/{id}/generate-title': ['POST'],
   '/api/chats/{id}/messages': ['POST'],
   '/api/chats/{id}/messages/{messageId}': ['DELETE'],
   '/api/chats/{id}/participants': ['GET', 'POST'],
-  '/api/chats/{id}/participants/{userId}': ['DELETE'],
+  '/api/chats/{id}/participants/{userId}': ['DELETE', 'PATCH'],
   '/api/chats/{id}/pin': ['DELETE', 'POST'],
   '/api/chats/{id}/start-fresh': ['POST'],
   '/api/comments': ['GET'],
@@ -186,8 +185,6 @@ export const openApiRoutes = {
   '/api/reporting/positions/{positionId}/manager': ['PUT'],
   '/api/scope/check': ['GET'],
   '/api/scope/check-batch': ['POST'],
-  '/api/shared/{token}': ['GET'],
-  '/api/shares/{shareId}': ['DELETE', 'PATCH'],
   '/api/source-sync/candidate-sets/current': ['GET'],
   '/api/source-sync/candidate-sets/{setId}/approve': ['POST'],
   '/api/source-sync/candidate-sets/{setId}/items': ['POST'],

package/src/guards/config.ts

@@ -197,7 +197,7 @@ export interface ScriptsDepsBaseline {
 
   /**
    * If true, violations are errors. If false, violations are warnings.
-   * @default false
+   * @default true (company-semantics-ci ADR-CI-254)
    */
   strict?: boolean;
 }

package/src/index.ts

@@ -587,13 +587,7 @@ export type {
 // Chat domain types
 // @see PRD-00142 for share chat design rationale
 export type {
-  ChatVisibility,
   ChatSummary,
-  ChatShareInfo,
-  SharedChatView,
-  SharedChatMessage,
-  CreateShareRequest,
-  UpdateShareRequest,
   // Chat lifecycle types
   TitleSource,
   ChatListFilters,
@@ -637,6 +631,9 @@ export type {
   // Participation, not an ACL entity — two roles, one owner, and the agent is
   // mentionable but never a member.
   ChatParticipantRole,
+  ChatGrantableRole,
+  AddChatParticipantRequest,
+  UpdateChatParticipantRequest,
   ChatParticipant,
   ChatParticipantsResponse,
   // Chat continuity (chat-continuity-wire-vocabulary): the subject a chat
@@ -675,6 +672,7 @@ export {
   // Multi-party chat: the role vocabulary, one participant row, and the list
   // envelope for GET /api/chats/:chatId/participants.
   ChatParticipantRoleSchema,
+  ChatGrantableRoleSchema,
   ChatParticipantSchema,
   ChatParticipantsResponseSchema,
   // Chat continuity: the closed subject-kind and continuation-reason

package/src/mcp/__tests__/README.md

@@ -0,0 +1,29 @@
+# mcp/\_\_tests\_\_/
+
+## Purpose
+
+Locks the MCP vocabulary claims the compiler alone does not.
+
+- `capability-graph.test.ts` — `buildCapabilityGraph` derives edges from
+  `produces`/`consumes` resource flow.
+- `resource-types-fixture.ts` — a COMPILED module, not a `*.test.ts`:
+  `src/tsconfig.json` excludes test files and vitest does not typecheck, so a
+  `satisfies ResourceType[]` written in a test would never be checked. Here
+  `tsc -b` checks that the nine original members and the five agent-reference
+  members (`company_md.doc`, `company_md.thread`, `org.member`, `org.unit`,
+  `work.item`) are all `ResourceType` members, and that no union member is
+  left unlisted.
+- `resources.test.ts` — the runtime half: fourteen distinct members, each
+  `<domain>.<kind>`.
+
+## Invariants
+
+- These assert VOCABULARY and SHAPE, never behavior.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest` and the sibling modules under test.

package/src/mcp/__tests__/resource-types-fixture.ts

@@ -0,0 +1,50 @@
+/**
+ * Compile-time fixture for the `ResourceType` union (ADR slug
+ * mcp-resource-types-cover-agent-references).
+ *
+ * WHY A COMPILED MODULE AND NOT `resources.test.ts`. `src/tsconfig.json`
+ * excludes every `*.test.ts` file and vitest does not typecheck, so a
+ * `satisfies` written inside a test file is never checked. This file is not a
+ * `*.test.ts`, so `tsc -b` compiles it: a literal that stops being a
+ * `ResourceType` member fails `pnpm typecheck`. `resources.test.ts` imports the
+ * arrays to prove the runtime half (count, uniqueness).
+ */
+
+import type { ResourceType } from "../resources";
+
+/** The nine members the union carried before agent-reference kinds were added. */
+export const ORIGINAL_RESOURCE_TYPES = [
+  "integration.connection",
+  "slack.channel",
+  "slack.channel_scope",
+  "slack.coverage",
+  "ingestion.job",
+  "knowledge.fingerprint",
+  "org.status",
+  "system.status",
+  "system.runtime",
+] as const satisfies readonly ResourceType[];
+
+/** The resource kinds the agent is handed a reference to (control INV-AGENT-GROUND-3). */
+export const AGENT_REFERENCE_RESOURCE_TYPES = [
+  "company_md.doc",
+  "company_md.thread",
+  "org.member",
+  "org.unit",
+  "work.item",
+] as const satisfies readonly ResourceType[];
+
+/** All fourteen members. */
+export const ALL_RESOURCE_TYPES = [
+  ...ORIGINAL_RESOURCE_TYPES,
+  ...AGENT_REFERENCE_RESOURCE_TYPES,
+] as const satisfies readonly ResourceType[];
+
+/**
+ * Exhaustiveness: every `ResourceType` member is listed above. If a member is
+ * added to the union without being listed here, this assignment fails.
+ */
+type Unlisted = Exclude<ResourceType, (typeof ALL_RESOURCE_TYPES)[number]>;
+export const NO_UNLISTED_RESOURCE_TYPES: [Unlisted] extends [never]
+  ? true
+  : never = true;

package/src/mcp/__tests__/resources.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import type { ResourceType } from "../resources";
+import {
+  AGENT_REFERENCE_RESOURCE_TYPES,
+  ALL_RESOURCE_TYPES,
+  NO_UNLISTED_RESOURCE_TYPES,
+  ORIGINAL_RESOURCE_TYPES,
+} from "./resource-types-fixture";
+
+describe("ResourceType", () => {
+  it("keeps the nine original members", () => {
+    expect(ORIGINAL_RESOURCE_TYPES).toHaveLength(9);
+  });
+
+  it("covers every resource kind the agent is handed a reference to", () => {
+    // Checked by the editor only (test files are not typechecked); the
+    // compiled twin is AGENT_REFERENCE_RESOURCE_TYPES in the fixture.
+    const agentReferences = [
+      "company_md.doc",
+      "company_md.thread",
+      "org.member",
+      "org.unit",
+      "work.item",
+    ] satisfies ResourceType[];
+    expect([...AGENT_REFERENCE_RESOURCE_TYPES]).toEqual(agentReferences);
+  });
+
+  it("has fourteen distinct members, all listed", () => {
+    expect(ALL_RESOURCE_TYPES).toHaveLength(14);
+    expect(new Set(ALL_RESOURCE_TYPES).size).toBe(14);
+    expect(NO_UNLISTED_RESOURCE_TYPES).toBe(true);
+  });
+
+  it("namespaces every member as <domain>.<kind>", () => {
+    for (const resource of ALL_RESOURCE_TYPES) {
+      expect(resource).toMatch(/^[a-z_]+\.[a-z_]+$/);
+    }
+  });
+});

package/src/mcp/resources.ts

@@ -8,6 +8,11 @@
  * This is a CLOSED union — new resource types represent architectural
  * additions that require a contracts release and downstream consumer updates.
  * Unlike ToolIntegration, resource types are not extensible via (string & {}).
+ *
+ * Since the ADR with slug mcp-resource-types-cover-agent-references, a member
+ * also exists for every resource kind the agent is handed a reference to (page
+ * context entity, citation entityId), so backend tool meta `consumes` can serve
+ * as the dereference registry (control INV-AGENT-GROUND-3).
  */
 export type ResourceType =
   | "integration.connection"
@@ -18,4 +23,14 @@ export type ResourceType =
   | "knowledge.fingerprint"
   | "org.status"
   | "system.status"
-  | "system.runtime";
+  | "system.runtime"
+  /** A company-md document; consumed by id (uuid), or by company-md path for page context. */
+  | "company_md.doc"
+  /** A company-md comment thread; consumed by id (uuid). */
+  | "company_md.thread"
+  /** An org member; consumed by users.id (uuid). */
+  | "org.member"
+  /** An org unit; consumed by org_units.id (uuid). */
+  | "org.unit"
+  /** A work item; consumed by id (uuid). */
+  | "work.item";

package/src/notifications/__tests__/__snapshots__/monospace-budget.test.ts.snap

@@ -3,6 +3,10 @@
 exports[`monospace budget > overhangs only where content is atomic 1`] = `
 [
   "Device: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
+  "https://app.companysemantics.ai/chat/abc123",
+  "https://app.companysemantics.ai/chat/long456",
+  "https://app.companysemantics.ai/chat/preview789",
+  "https://app.companysemantics.ai/chat/short123",
   "https://app.companysemantics.ai/doc/handbook",
   "https://app.companysemantics.ai/doc/handbook?request=req_123",
   "https://app.companysemantics.ai/doc/handbook?request=req_456",
@@ -16,9 +20,5 @@ exports[`monospace budget > overhangs only where content is atomic 1`] = `
   "https://app.companysemantics.ai/org/unit/42",
   "https://app.companysemantics.ai/owner-transfer/accept/tok123",
   "https://app.companysemantics.ai/owner-transfer/accept/tok456",
-  "https://app.companysemantics.ai/share/abc123",
-  "https://app.companysemantics.ai/share/long456",
-  "https://app.companysemantics.ai/share/preview789",
-  "https://app.companysemantics.ai/share/short123",
 ]
 `;