@company-semantics/contracts 9.0.0 → 9.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -79,6 +79,8 @@
     "typecheck": "tsc -b --noEmit",
     "typecheck:ci": "tsc -p scripts/ci/tsconfig.json",
     "lint:md": "markdownlint-cli2 '**/*.md' '#node_modules'",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
     "lint:json": "node -e \"JSON.parse(require('fs').readFileSync('package.json'))\"",
     "prepare": "husky",
     "guard:export": "npx tsx scripts/ci/export-guard.ts",
@@ -113,13 +115,14 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^22.19.19",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.7",
     "markdownlint-cli2": "^0.22.1",
     "openapi-typescript": "^7.13.0",
+    "prettier": "^3.8.3",
     "tsx": "^4.22.4",
-    "typescript": "^5",
+    "typescript": "^5.8.3",
     "vitest": "^4.1.8",
     "yaml": "^2.9.0"
   },

package/src/__tests__/resource-keys.test.ts

@@ -1,55 +1,57 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect } from "vitest";
 import {
   toQueryKey,
   fromQueryKey,
   matchesResourceKey,
   type ResourceKey,
-} from '../resource-keys.js';
+} from "../resource-keys.js";
 
-const ORG_ID = '11111111-1111-4111-8111-111111111111';
+const ORG_ID = "11111111-1111-4111-8111-111111111111";
 
-describe('resource-keys: orgUnitOwners (org-scoped)', () => {
-  const key: ResourceKey = { type: 'orgUnitOwners', orgId: ORG_ID };
+describe("resource-keys: orgUnitOwners (org-scoped)", () => {
+  const key: ResourceKey = { type: "orgUnitOwners", orgId: ORG_ID };
 
-  it('toQueryKey produces [type, orgId] with no unitId', () => {
+  it("toQueryKey produces [type, orgId] with no unitId", () => {
     const qk = toQueryKey(key);
-    expect(qk).toEqual(['orgUnitOwners', ORG_ID]);
+    expect(qk).toEqual(["orgUnitOwners", ORG_ID]);
     // org-scoped: exactly two segments, no per-unit identity
     expect(qk).toHaveLength(2);
   });
 
-  it('roundtrips through fromQueryKey', () => {
+  it("roundtrips through fromQueryKey", () => {
     const parsed = fromQueryKey(toQueryKey(key));
     expect(parsed).toEqual(key);
-    expect('unitId' in parsed).toBe(false);
+    expect("unitId" in parsed).toBe(false);
   });
 
-  it('matchesResourceKey is org-scoped: rejects a different orgId', () => {
-    const other = '22222222-2222-4222-8222-222222222222';
+  it("matchesResourceKey is org-scoped: rejects a different orgId", () => {
+    const other = "22222222-2222-4222-8222-222222222222";
     expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
-    expect(matchesResourceKey(['orgUnitOwners', other], key)).toBe(false);
+    expect(matchesResourceKey(["orgUnitOwners", other], key)).toBe(false);
   });
 });
 
-describe('resource-keys: system-scoped internalAdmin* types', () => {
+describe("resource-keys: system-scoped internalAdmin* types", () => {
   const systemTypes = [
-    'internalAdminAiProviders',
-    'internalAdminPrompts',
-    'internalAdminAiRuntimeDefaults',
+    "internalAdminAiProviders",
+    "internalAdminPrompts",
+    "internalAdminAiRuntimeDefaults",
+    "factoryFloor",
+    "factorySnapshot",
   ] as const;
 
   for (const type of systemTypes) {
-    const key = { type, scope: 'system' } as ResourceKey;
+    const key = { type, scope: "system" } as ResourceKey;
 
     it(`${type}: toQueryKey produces [type, 'system']`, () => {
-      expect(toQueryKey(key)).toEqual([type, 'system']);
+      expect(toQueryKey(key)).toEqual([type, "system"]);
     });
 
     it(`${type}: roundtrips through fromQueryKey with scope: 'system'`, () => {
       const parsed = fromQueryKey(toQueryKey(key));
       expect(parsed).toEqual(key);
-      expect('orgId' in parsed).toBe(false);
-      expect('userId' in parsed).toBe(false);
+      expect("orgId" in parsed).toBe(false);
+      expect("userId" in parsed).toBe(false);
     });
 
     it(`${type}: matchesResourceKey accepts a matching system key`, () => {
@@ -57,8 +59,13 @@ describe('resource-keys: system-scoped internalAdmin* types', () => {
     });
   }
 
-  it('matchesResourceKey rejects a mismatched system type', () => {
-    const target: ResourceKey = { type: 'internalAdminPrompts', scope: 'system' };
-    expect(matchesResourceKey(['internalAdminAiProviders', 'system'], target)).toBe(false);
+  it("matchesResourceKey rejects a mismatched system type", () => {
+    const target: ResourceKey = {
+      type: "internalAdminPrompts",
+      scope: "system",
+    };
+    expect(
+      matchesResourceKey(["internalAdminAiProviders", "system"], target),
+    ).toBe(false);
   });
 });

package/src/admin/authz-simulate.ts

@@ -6,21 +6,21 @@
  * admins can debug denials by reading evaluator name + reason rather than
  * guessing. See PRD-00544 and feedback_decision_logic_must_be_visible.md.
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 export const SimulateRequest = z.object({
   actor: z.object({
-    type: z.enum(['user', 'agent']),
+    type: z.enum(["user", "agent"]),
     id: z.string().uuid(),
   }),
   scope: z.string(),
-  resource_kind: z.enum(['system', 'org', 'team', 'member', 'doc']),
+  resource_kind: z.enum(["system", "org", "team", "member", "doc"]),
   resource_id: z.string().uuid().optional(),
 });
 
 export type SimulateRequest = z.infer<typeof SimulateRequest>;
 
-export const SimulateResponse = z.discriminatedUnion('allow', [
+export const SimulateResponse = z.discriminatedUnion("allow", [
   z.object({
     allow: z.literal(true),
     matched_grant: z.unknown(),

package/src/admin/direct-grants.ts

@@ -6,7 +6,7 @@
  * body — it is set by the server from the authenticated actor (see PRD-00544
  * direct-grant-audit-trail and the `direct-grant-audit` CI guard).
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 export const DirectGrantCreate = z.object({
   subject_id: z.string().uuid(),
@@ -22,7 +22,7 @@ export const DirectGrant = z.object({
   org_id: z.string().uuid(),
   subject_id: z.string().uuid(),
   scope_pattern: z.string(),
-  source: z.literal('direct'),
+  source: z.literal("direct"),
   granted_by: z.string().uuid(),
   granted_at: z.string().datetime(),
   expires_at: z.string().datetime().nullable(),

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 = '6afa08fcbf29' as const;
-export const SPEC_HASH_FULL = '6afa08fcbf29128df63d59525891ef1f6e8eb0e49b8e289b09d0150ce35a862e' as const;
+export const SPEC_HASH = '1173d8fa2df9' as const;
+export const SPEC_HASH_FULL = '1173d8fa2df90dbf7a46608635f61e69939616ed509f6109bdf478fc1cd4a9c0' as const;

package/src/api/generated.ts

@@ -2696,6 +2696,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/factory/snapshot": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read the freshest software-factory PRD snapshot */
+        get: operations["factorySnapshot"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/internal-admin/impersonate/start": {
         parameters: {
             query?: never;
@@ -4800,6 +4817,52 @@ export interface components {
                 }[];
             }[];
         };
+        FactorySnapshotResponse: {
+            snapshot: {
+                /** Format: date-time */
+                generatedAt: string;
+                host: string;
+                counts: {
+                    ready: number;
+                    running: number;
+                    blocked: number;
+                    done: number;
+                };
+                /** @default [] */
+                prds: {
+                    id: string;
+                    title: string;
+                    repo: string;
+                    /** @enum {string} */
+                    status: "active" | "completed";
+                    /** @enum {string} */
+                    kanban: "ready" | "running" | "blocked" | "done";
+                    progress: number;
+                    running?: {
+                        executor: string | null;
+                        feature: string | null;
+                        startedAt: string | null;
+                        branch: string | null;
+                    };
+                    /** @default [] */
+                    blockedBy: {
+                        target: string;
+                        reason?: string;
+                    }[];
+                }[];
+                /** @default [] */
+                actors: {
+                    id: string;
+                    role: string;
+                    /** @enum {string} */
+                    status: "working" | "idle";
+                    workingOn?: string;
+                    feature?: string;
+                    detected: boolean;
+                }[];
+            } | null;
+            receivedAt: string | null;
+        };
         ImpersonationSessionResponse: {
             session: {
                 impersonationSessionId: string;
@@ -9324,6 +9387,40 @@ export interface operations {
             };
         };
     };
+    factorySnapshot: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Factory snapshot (freshest by generatedAt, null if none) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["FactorySnapshotResponse"];
+                };
+            };
+            /** @description Not authenticated */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Not an internal admin */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     startImpersonation: {
         parameters: {
             query?: never;

package/src/api/http/routes/ai-chat.ts

@@ -10,12 +10,12 @@
  *   import { buildCapabilityGraph } from '@company-semantics/contracts'
  */
 
-import { buildCapabilityGraph } from '../../../mcp/capability-graph'
+import { buildCapabilityGraph } from "../../../mcp/capability-graph";
 import type {
   MCPToolDescriptor,
   ToolDiscoveryResponse,
   CapabilityGraph,
-} from '../../../mcp/index'
+} from "../../../mcp/index";
 
 /**
  * Build a ToolDiscoveryResponse, optionally including the capability graph.
@@ -33,5 +33,5 @@ export function buildToolDiscoveryResponse(
   return {
     tools,
     ...(includeGraph && { graph: buildCapabilityGraph(tools) }),
-  }
+  };
 }

package/src/api/http/utils/resource-response.ts

@@ -1,4 +1,4 @@
-import type { ResourceResponse } from '../../../resource-response';
+import type { ResourceResponse } from "../../../resource-response";
 
 /**
  * Wrap resource data with version for cache invalidation.
@@ -6,6 +6,9 @@ import type { ResourceResponse } from '../../../resource-response';
  * @param version - MUST be entity.updatedAt or DB row version. NEVER Date.now().
  *   Using request time defeats invalidation — race conditions reappear.
  */
-export function resourceResponse<T>(data: T, version: number): ResourceResponse<T> {
+export function resourceResponse<T>(
+  data: T,
+  version: number,
+): ResourceResponse<T> {
   return { data, version };
 }

package/src/api/index.ts

@@ -6,11 +6,11 @@
  */
 
 // OpenAPI generated types (from openapi/backend.yaml)
-export type { paths, components, operations } from './generated'
+export type { paths, components, operations } from "./generated";
 
 // Spec hash (from openapi/backend.yaml SHA-256)
-export { SPEC_HASH, SPEC_HASH_FULL } from './generated-spec-hash'
+export { SPEC_HASH, SPEC_HASH_FULL } from "./generated-spec-hash";
 
 // Reusable API primitive schemas (CursorPage, ErrorResponse)
-export { CursorPageSchema, ErrorResponseSchema } from './primitives'
-export type { CursorPage, ErrorResponse } from './primitives'
+export { CursorPageSchema, ErrorResponseSchema } from "./primitives";
+export type { CursorPage, ErrorResponse } from "./primitives";

package/src/api/primitives.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { z } from "zod";
 
 /** Generic factory for cursor-paginated responses. */
 export function CursorPageSchema<T extends z.ZodTypeAny>(itemSchema: T) {
@@ -19,5 +19,9 @@ export const ErrorResponseSchema = z.object({
 });
 
 // Inferred types
-export type CursorPage<T> = { items: T[]; nextCursor: string | null; hasMore: boolean };
+export type CursorPage<T> = {
+  items: T[];
+  nextCursor: string | null;
+  hasMore: boolean;
+};
 export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

package/src/auth/README.md

@@ -12,6 +12,7 @@ Shared types for authentication flows across Company Semantics codebases. Define
 ## Public API
 
 **Types:**
+
 - `OTPErrorCode` — enum: `InvalidCode`, `Expired`, `AlreadyUsed`, `NotFound`
 - `AuthStartMode` — `'otp' | 'sso' | 'hybrid'`
 - `AuthStartResponse` — discriminated union describing auth flow entry point

package/src/auth/index.ts

@@ -11,10 +11,10 @@
  * Frontend uses these to provide specific user messaging (e.g., expired vs invalid).
  */
 export enum OTPErrorCode {
-  InvalidCode = 'invalid_code',
-  Expired = 'expired',
-  AlreadyUsed = 'already_used',
-  NotFound = 'not_found',
+  InvalidCode = "invalid_code",
+  Expired = "expired",
+  AlreadyUsed = "already_used",
+  NotFound = "not_found",
 }
 
 export type AuthStartMode = "otp" | "sso" | "hybrid";
@@ -22,4 +22,11 @@ export type AuthStartMode = "otp" | "sso" | "hybrid";
 export type AuthStartResponse =
   | { mode: "otp"; devOtp?: string }
   | { mode: "sso"; providers: string[]; redirectUrl: string }
-  | { mode: "hybrid"; providers: string[]; redirectUrl: string; recommendedProvider?: string; otpAllowed: true; devOtp?: string };
+  | {
+      mode: "hybrid";
+      providers: string[];
+      redirectUrl: string;
+      recommendedProvider?: string;
+      otpAllowed: true;
+      devOtp?: string;
+    };

package/src/autotune.ts

@@ -85,6 +85,10 @@ export type ControllerInput = {
  */
 export type ControllerOutput<Min extends number, Max extends number> = {
   readonly value: Bounded<Min, Max>;
-  readonly reason: 'deadband-hold' | 'window-hold' | 'adjusted' | 'bounded-clamp';
+  readonly reason:
+    | "deadband-hold"
+    | "window-hold"
+    | "adjusted"
+    | "bounded-clamp";
   readonly adjustmentWindowId: string;
 };

package/src/billing/index.ts

@@ -1 +1 @@
-export type { OrgPlanStatus, OrgBillingInfo } from './types';
+export type { OrgPlanStatus, OrgBillingInfo } from "./types";

package/src/billing/types.ts

@@ -10,7 +10,7 @@
 /**
  * Organization plan status.
  */
-export type OrgPlanStatus = 'active' | 'trialing' | 'past_due' | 'canceled';
+export type OrgPlanStatus = "active" | "trialing" | "past_due" | "canceled";
 
 /**
  * Read-only billing information for an organization.

package/src/chat/README.md

@@ -16,6 +16,7 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 ## Public API
 
 **Types:**
+
 - `ChatVisibility` — `'private' | 'public'` share visibility
 - `ChatSummary`, `ChatSummaryExtended` — list view models
 - `ChatShareInfo`, `SharedChatView`, `SharedChatMessage` — sharing types
@@ -25,11 +26,13 @@ Shared types for chat persistence, sharing, real-time events, and runtime profil
 - `ChatRuntimeProfileInfo` — profile metadata for UI rendering
 
 **SSE event types:**
+
 - `ChatCreatedEvent`, `ChatUpdatedEvent`, `ChatDeletedEvent` — domain events
 - `InvalidateChatEvent`, `InvalidateChatListEvent` — staleness signals
 - `ChatSseEvent` — union of all SSE event types
 
 **Runtime values:**
+
 - `CHAT_RUNTIME_PROFILES` — ordered array of profile info for UI rendering
 - `DEFAULT_CHAT_RUNTIME_PROFILE` — `'agentic'`
 

package/src/chat/__tests__/runtime-profile.test.ts

@@ -1,55 +1,75 @@
-import { describe, it, expect } from 'vitest'
-import { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from '../runtime-profile.js'
+import { describe, it, expect } from "vitest";
+import {
+  CHAT_RUNTIME_PROFILES,
+  DEFAULT_CHAT_RUNTIME_PROFILE,
+} from "../runtime-profile.js";
 
-describe('CHAT_RUNTIME_PROFILES golden snapshot', () => {
-  it('exact values are frozen', () => {
+describe("CHAT_RUNTIME_PROFILES golden snapshot", () => {
+  it("exact values are frozen", () => {
     expect(CHAT_RUNTIME_PROFILES).toStrictEqual([
-      { id: 'fast', label: 'Fast', description: 'Single-step, no tools', model: 'gpt-3.5-turbo' },
-      { id: 'balanced', label: 'Balanced', description: 'Multi-step with tools', model: 'gpt-4o' },
-      { id: 'agentic', label: 'Agentic', description: 'Agent loop, full reasoning', model: 'claude-sonnet-4-20250514' },
-    ])
-  })
-})
-
-describe('CHAT_RUNTIME_PROFILES invariants', () => {
-  it('covers all ChatRuntimeProfile values', () => {
-    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
-    expect(ids).toContain('fast')
-    expect(ids).toContain('balanced')
-    expect(ids).toContain('agentic')
-  })
-
-  it('has no duplicate profile IDs', () => {
-    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
-    expect(new Set(ids).size).toBe(ids.length)
-  })
-
-  it('all entries have non-empty label and description', () => {
+      {
+        id: "fast",
+        label: "Fast",
+        description: "Single-step, no tools",
+        model: "gpt-3.5-turbo",
+      },
+      {
+        id: "balanced",
+        label: "Balanced",
+        description: "Multi-step with tools",
+        model: "gpt-4o",
+      },
+      {
+        id: "agentic",
+        label: "Agentic",
+        description: "Agent loop, full reasoning",
+        model: "claude-sonnet-4-20250514",
+      },
+    ]);
+  });
+});
+
+describe("CHAT_RUNTIME_PROFILES invariants", () => {
+  it("covers all ChatRuntimeProfile values", () => {
+    const ids = CHAT_RUNTIME_PROFILES.map((p) => p.id);
+    expect(ids).toContain("fast");
+    expect(ids).toContain("balanced");
+    expect(ids).toContain("agentic");
+  });
+
+  it("has no duplicate profile IDs", () => {
+    const ids = CHAT_RUNTIME_PROFILES.map((p) => p.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("all entries have non-empty label and description", () => {
     for (const profile of CHAT_RUNTIME_PROFILES) {
-      expect(profile.label.length).toBeGreaterThan(0)
-      expect(profile.description.length).toBeGreaterThan(0)
+      expect(profile.label.length).toBeGreaterThan(0);
+      expect(profile.description.length).toBeGreaterThan(0);
     }
-  })
+  });
 
-  it('all entries have non-empty model strings', () => {
+  it("all entries have non-empty model strings", () => {
     for (const profile of CHAT_RUNTIME_PROFILES) {
-      expect(profile.model.length).toBeGreaterThan(0)
+      expect(profile.model.length).toBeGreaterThan(0);
     }
-  })
-})
-
-describe('DEFAULT_CHAT_RUNTIME_PROFILE', () => {
-  it('is agentic', () => {
-    expect(DEFAULT_CHAT_RUNTIME_PROFILE).toBe('agentic')
-  })
-
-  it('exists in CHAT_RUNTIME_PROFILES', () => {
-    const ids = CHAT_RUNTIME_PROFILES.map(p => p.id)
-    expect(ids).toContain(DEFAULT_CHAT_RUNTIME_PROFILE)
-  })
-
-  it('is a valid ChatRuntimeProfile value', () => {
-    const validIds = CHAT_RUNTIME_PROFILES.map(p => p.id) as readonly string[]
-    expect(validIds).toContain(DEFAULT_CHAT_RUNTIME_PROFILE)
-  })
-})
+  });
+});
+
+describe("DEFAULT_CHAT_RUNTIME_PROFILE", () => {
+  it("is agentic", () => {
+    expect(DEFAULT_CHAT_RUNTIME_PROFILE).toBe("agentic");
+  });
+
+  it("exists in CHAT_RUNTIME_PROFILES", () => {
+    const ids = CHAT_RUNTIME_PROFILES.map((p) => p.id);
+    expect(ids).toContain(DEFAULT_CHAT_RUNTIME_PROFILE);
+  });
+
+  it("is a valid ChatRuntimeProfile value", () => {
+    const validIds = CHAT_RUNTIME_PROFILES.map(
+      (p) => p.id,
+    ) as readonly string[];
+    expect(validIds).toContain(DEFAULT_CHAT_RUNTIME_PROFILE);
+  });
+});

package/src/chat/index.ts

@@ -49,7 +49,7 @@ export type {
   ChatMessage,
   ChatDetail,
   GetChatResponse,
-} from './types'
+} from "./types";
 
 // =============================================================================
 // Schemas (Zod runtime validation)
@@ -87,8 +87,14 @@ export {
   ChatMessageSchema,
   ChatDetailSchema,
   GetChatResponseSchema,
-} from './schemas'
+} from "./schemas";
 
 // Runtime profile types and constants
-export type { ChatRuntimeProfile, ChatRuntimeProfileInfo } from './runtime-profile'
-export { CHAT_RUNTIME_PROFILES, DEFAULT_CHAT_RUNTIME_PROFILE } from './runtime-profile'
+export type {
+  ChatRuntimeProfile,
+  ChatRuntimeProfileInfo,
+} from "./runtime-profile";
+export {
+  CHAT_RUNTIME_PROFILES,
+  DEFAULT_CHAT_RUNTIME_PROFILE,
+} from "./runtime-profile";