@company-semantics/contracts 85.3.0 → 86.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "85.3.0",
+  "version": "86.1.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 = '2e58fba933bb' as const;
-export const SPEC_HASH_FULL = '2e58fba933bbbd6356dcac9c8e3f4735c6c7556dd205e4fe9ac6d18be8517395' as const;
+export const SPEC_HASH = '4ec580fdf79a' as const;
+export const SPEC_HASH_FULL = '4ec580fdf79abef6f817c1afee788dc61a640b4f903b3f5181d0c3a7fc934709' as const;

package/src/api/generated.ts

@@ -5334,7 +5334,7 @@ export interface components {
             pageContext?: {
                 route: string;
                 /** @enum {string} */
-                view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                view: "chat" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
                 /** @enum {string} */
                 scope: "none" | "me" | "team" | "org";
                 entity?: {
@@ -5380,7 +5380,7 @@ export interface components {
             pageContext?: {
                 route: string;
                 /** @enum {string} */
-                view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                view: "chat" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
                 /** @enum {string} */
                 scope: "none" | "me" | "team" | "org";
                 entity?: {
@@ -5426,7 +5426,7 @@ export interface components {
             pageContext?: {
                 route: string;
                 /** @enum {string} */
-                view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                view: "chat" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
                 /** @enum {string} */
                 scope: "none" | "me" | "team" | "org";
                 entity?: {
@@ -8516,7 +8516,7 @@ export interface components {
             surface: {
                 route: string;
                 /** @enum {string} */
-                view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                view: "chat" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
                 /** @enum {string} */
                 scope: "none" | "me" | "team" | "org";
                 entity?: {
@@ -8563,7 +8563,7 @@ export interface components {
                 route?: {
                     route: string;
                     /** @enum {string} */
-                    view: "chat" | "chats" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
+                    view: "chat" | "company-md" | "execution-detail" | "internal-admin" | "notifications" | "org-settings" | "org-work" | "settings" | "team-md" | "teams" | "teamwork" | "teamwork-member" | "timeline" | "upgrade" | "user-md" | "work";
                     /** @enum {string} */
                     scope: "none" | "me" | "team" | "org";
                     entity?: {
@@ -9625,7 +9625,7 @@ export interface components {
                 /** Format: date-time */
                 lastObservedAt: string;
                 dismissedAt: string | null;
-                fingerprint?: string;
+                fingerprint: string;
             }[];
         };
         SourceSyncFinding: {
@@ -9650,11 +9650,11 @@ export interface components {
             /** Format: date-time */
             lastObservedAt: string;
             dismissedAt: string | null;
-            fingerprint?: string;
+            fingerprint: string;
         };
         SourceSyncDismissFindingRequest: {
             note?: string;
-            expectedFingerprint?: string;
+            expectedFingerprint: string;
         };
         SourceSyncStandingOrdersResponse: {
             orders: {

package/src/chat/README.md

@@ -65,7 +65,7 @@ A chat can belong to a SUBJECT — the durable case a hand-off to chat is about
 - `CHAT_DISCUSSION_REQUEST_TYPES` — The kinds of durable input request a turn can be scoped to.
 - `CHAT_PAGE_ENTITY_TYPES` — What kind of thing the reader has open, when they have one open.
 - `CHAT_PAGE_SCOPES` — The route parser's four URL scopes: unscoped, `/me/*`, `/team/*`, `/@:org/*`.
-- `CHAT_PAGE_VIEWS` — The app route parser's seventeen `type` values, projected onto the wire.
+- `CHAT_PAGE_VIEWS` — The app route parser's sixteen `type` values, projected onto the wire.
 - `CHAT_RUNTIME_PROFILES` — Ordered list of available profiles for UI rendering.
 - `CONVERSATION_SUBJECT_KINDS` — The kinds of subject a chat can continue.
 - `ChatByInteractionResponse` _(type)_ — Response for GET /api/chats/by-interaction/:interactionId

package/src/chat/__tests__/page-context.test.ts

@@ -211,9 +211,10 @@ describe("ChatPageContext is the ceiling on both axes", () => {
     expect(ChatPageContextSchema.safeParse(VALID).success).toBe(true);
     expect(
       ChatPageContextSchema.safeParse({
-        route: "/new",
+        route: "/chat/abc",
         view: "chat",
         scope: "none",
+        entity: { type: "chat", id: "abc" },
       }).success,
     ).toBe(true);
   });

package/src/chat/schemas.ts

@@ -509,7 +509,7 @@ export const ChatMentionableResponseSchema = z.object({
 // =============================================================================
 
 /**
- * The app route parser's seventeen `type` values, projected onto the wire.
+ * The app route parser's sixteen `type` values, projected onto the wire.
  *
  * A PROJECTION, not a parallel vocabulary: keep it in step with
  * `company-semantics-app/src/platform/route-parser.ts`. A view the parser can
@@ -519,7 +519,6 @@ export const ChatMentionableResponseSchema = z.object({
  */
 export const CHAT_PAGE_VIEWS = [
   "chat",
-  "chats",
   "company-md",
   "execution-detail",
   "internal-admin",

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/org/__tests__/view-scopes.test.ts

@@ -14,7 +14,6 @@ describe("VIEW_SCOPE_MAP golden snapshot", () => {
       teams: null,
       chat: null,
       settings: null,
-      chats: null,
       "my-work": null,
       "user-md": null,
       "team-md": null,
@@ -37,7 +36,6 @@ describe("getViewScope", () => {
   it("returns null for public views", () => {
     expect(getViewScope("chat")).toBeNull();
     expect(getViewScope("settings")).toBeNull();
-    expect(getViewScope("chats")).toBeNull();
     expect(getViewScope("upgrade")).toBeNull();
     // teams is membership-derived, not scope-gated (ADR-CONTRACTS-062).
     expect(getViewScope("teams")).toBeNull();

package/src/org/view-scopes.ts

@@ -35,7 +35,6 @@ export const VIEW_SCOPE_MAP = {
   teams: null,
   chat: null,
   settings: null,
-  chats: null,
   "my-work": null,
   "user-md": null,
   // Stubs for the viewer's team.md (/team/md) and the org's work (/@org/work);

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

@@ -27,6 +27,7 @@ import {
 const FINDING_ID = "d3b42536-f7a8-4b3a-9eb5-e3f4a5b6c7d8";
 const SOURCE_ID = "3f1a2b4c-5d6e-4f70-8192-a3b4c5d6e7f8";
 const DOC_ID = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d";
+const FINGERPRINT = "0123456789abcdef0123456789abcdef";
 
 function finding(overrides: Record<string, unknown> = {}) {
   return {
@@ -41,6 +42,7 @@ function finding(overrides: Record<string, unknown> = {}) {
     firstObservedAt: "2026-09-19T10:00:00Z",
     lastObservedAt: "2026-09-20T10:00:00Z",
     dismissedAt: null,
+    fingerprint: FINGERPRINT,
     ...overrides,
   };
 }
@@ -100,12 +102,28 @@ describe("staleness findings", () => {
       SourceSyncFindingsResponseSchema.safeParse({ findings: [finding()] })
         .success,
     ).toBe(true);
+    expect(
+      SourceSyncDismissFindingRequestSchema.safeParse({
+        expectedFingerprint: FINGERPRINT,
+      }).success,
+    ).toBe(true);
+    expect(
+      SourceSyncDismissFindingRequestSchema.safeParse({
+        expectedFingerprint: FINGERPRINT,
+        dismissedByLabel: "Dana Reyes",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("a finding carries its fingerprint and a dismissal must send it back", () => {
+    const { fingerprint: _f, ...without } = finding();
+    expect(SourceSyncFindingSchema.safeParse(without).success).toBe(false);
     expect(SourceSyncDismissFindingRequestSchema.safeParse({}).success).toBe(
-      true,
+      false,
     );
     expect(
       SourceSyncDismissFindingRequestSchema.safeParse({
-        dismissedByLabel: "Dana Reyes",
+        expectedFingerprint: "0f3c9a",
       }).success,
     ).toBe(false);
   });

package/src/source-sync/upkeep.ts

@@ -56,9 +56,9 @@ export const SourceSyncFindingSchema = z.object({
   dismissedAt: IsoDateTime.nullable(),
   /**
    * What the finding says right now, as the reader saw it. A dismissal sends it
-   * back as `expectedFingerprint`. Optional while the backend starts sending it.
+   * back as `expectedFingerprint`. The backend sends it on every finding.
    */
-  fingerprint: z.string().length(32).optional(),
+  fingerprint: z.string().length(32),
 });
 
 export const SourceSyncFindingsResponseSchema = z.object({
@@ -68,15 +68,15 @@ export const SourceSyncFindingsResponseSchema = z.object({
 /**
  * Dismiss one finding. Who dismissed it is the authenticated caller.
  * `expectedFingerprint` is the finding's fingerprint as the caller rendered it:
- * when present, a finding that moved since is refused as changed. Optional
- * during the expand step of the backend decision
- * `findings-lifecycle-is-domain-agnostic`; required once dismissal becomes
- * compare-and-set.
+ * a finding that moved since is refused as changed. Required in the contract
+ * ahead of the backend: every typed sender must send it before the backend's
+ * own route schema requires it and dismissal becomes compare-and-set (backend
+ * decision `findings-lifecycle-is-domain-agnostic`; control PRD-01064).
  */
 export const SourceSyncDismissFindingRequestSchema = z
   .object({
     note: z.string().max(500).optional(),
-    expectedFingerprint: z.string().length(32).optional(),
+    expectedFingerprint: z.string().length(32),
   })
   .strict();