@company-semantics/contracts 86.0.0 → 86.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "86.0.0",
+  "version": "86.1.0",
   "private": false,
   "repository": {
     "type": "git",

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