@company-semantics/contracts 9.1.0 → 9.2.0

package/src/ci-envelope/index.ts

@@ -32,7 +32,7 @@ export type {
   CIExecutionOutcome,
   // Core Envelope
   CIExecutionEnvelope,
-} from './types';
+} from "./types";
 
 // Constants (documentation/type-level, not runtime)
-export { ENVELOPE_TRANSITIONS } from './types';
+export { ENVELOPE_TRANSITIONS } from "./types";

package/src/ci-envelope/types.ts

@@ -22,7 +22,7 @@
  * Currently Claude-only, extensible for future actor types.
  */
 export type CIActorInfo = {
-  kind: 'claude';
+  kind: "claude";
   model: string;
 };
 
@@ -46,15 +46,15 @@ export type CISessionInfo = {
  * not here. This type defines vocabulary only.
  */
 export type ExecutionIntent =
-  | 'feature_extension'
-  | 'bug_fix'
-  | 'refactor_structural'
-  | 'guard_update'
-  | 'policy_update'
-  | 'schema_change'
-  | 'doc_update'
-  | 'cleanup'
-  | 'experimental';
+  | "feature_extension"
+  | "bug_fix"
+  | "refactor_structural"
+  | "guard_update"
+  | "policy_update"
+  | "schema_change"
+  | "doc_update"
+  | "cleanup"
+  | "experimental";
 
 /**
  * Intent declaration with optional ADR references.
@@ -73,7 +73,7 @@ export type CIIntentDeclaration = {
 /**
  * Change kind for scope declarations.
  */
-export type CIChangeKind = 'add' | 'modify' | 'delete';
+export type CIChangeKind = "add" | "modify" | "delete";
 
 /**
  * Execution scope defining affected repos and paths.
@@ -130,11 +130,11 @@ export type CIGuardPlan = {
  * Note: Transition validation logic lives in CI repo, not here.
  */
 export type CIEnvelopeStatus =
-  | 'proposed'
-  | 'validated'
-  | 'blocked'
-  | 'executing'
-  | 'finalized';
+  | "proposed"
+  | "validated"
+  | "blocked"
+  | "executing"
+  | "finalized";
 
 // =============================================================================
 // Outcome Types
@@ -145,7 +145,7 @@ export type CIEnvelopeStatus =
  */
 export type CIGuardViolation = {
   guardId: string;
-  severity: 'error' | 'warning';
+  severity: "error" | "warning";
   message: string;
   file?: string;
   line?: number;
@@ -208,9 +208,9 @@ export const ENVELOPE_TRANSITIONS: Record<
   CIEnvelopeStatus,
   readonly CIEnvelopeStatus[]
 > = {
-  proposed: ['validated', 'blocked'],
-  validated: ['executing', 'blocked'],
+  proposed: ["validated", "blocked"],
+  validated: ["executing", "blocked"],
   blocked: [],
-  executing: ['finalized', 'blocked'],
+  executing: ["finalized", "blocked"],
   finalized: [],
 } as const;

package/src/ci-results/index.ts

@@ -11,6 +11,6 @@ export type {
   GuardTier,
   GuardResultPayload,
   RepoCiResult,
-} from './repo-ci-result';
+} from "./repo-ci-result";
 
-export { assertRepoCiResultConsistent } from './repo-ci-result';
+export { assertRepoCiResultConsistent } from "./repo-ci-result";

package/src/ci-results/repo-ci-result.ts

@@ -6,11 +6,11 @@
  */
 
 export type GuardTier =
-  | 'structural'
-  | 'behavioral'
-  | 'invariants'
-  | 'evolution'
-  | 'meta';
+  | "structural"
+  | "behavioral"
+  | "invariants"
+  | "evolution"
+  | "meta";
 
 /**
  * Minimal structural shape of a guard orchestrator result payload.
@@ -22,7 +22,10 @@ export interface GuardResultPayload {
   readonly results: Readonly<
     Record<
       GuardTier,
-      { readonly errors: readonly unknown[]; readonly warnings: readonly unknown[] }
+      {
+        readonly errors: readonly unknown[];
+        readonly warnings: readonly unknown[];
+      }
     >
   >;
 }
@@ -39,7 +42,7 @@ export interface RepoCiResult {
   /** Sibling repo name without the 'company-semantics-' prefix. */
   readonly repo: string;
   /** pass when ci:local exited 0 and the guard artifact was produced; fail otherwise. */
-  readonly status: 'pass' | 'fail';
+  readonly status: "pass" | "fail";
   /**
    * Total errors across all guard tiers.
    * MUST equal the sum of guardResult.results[tier].errors.length across
@@ -59,11 +62,11 @@ export interface RepoCiResult {
 }
 
 const TIERS: readonly GuardTier[] = [
-  'structural',
-  'behavioral',
-  'invariants',
-  'evolution',
-  'meta',
+  "structural",
+  "behavioral",
+  "invariants",
+  "evolution",
+  "meta",
 ];
 
 /**

package/src/compatibility.ts

@@ -13,11 +13,11 @@
  */
 export interface Deprecation {
   /** Semver range (e.g., "0.12.x") */
-  range: string
+  range: string;
   /** Human-readable reason for deprecation */
-  reason: string
+  reason: string;
   /** Version in which support will be removed */
-  removeIn: string
+  removeIn: string;
 }
 
 /**
@@ -26,10 +26,10 @@ export interface Deprecation {
  */
 export const COMPATIBILITY = {
   /** Minimum version that all consumers should use */
-  minSupported: '0.14.0',
+  minSupported: "0.14.0",
 
   /** Versions that still work but should upgrade (with reasons) */
   deprecations: [] as Deprecation[],
-} as const
+} as const;
 
-export type Compatibility = typeof COMPATIBILITY
+export type Compatibility = typeof COMPATIBILITY;

package/src/content/index.ts

@@ -11,14 +11,20 @@ export {
   CompanyMdDocResponseSchema,
   CompanyMdShareResponseSchema,
   CompanyMdContextBankResponseSchema,
-} from './schemas';
+} from "./schemas";
 export type {
   CompanyMdListResponse,
   CompanyMdDocResponse,
   CompanyMdShareResponse,
   CompanyMdContextBankResponse,
-} from './schemas';
+} from "./schemas";
 
 // Drive response schemas (PRD-00448)
-export { DriveFileListResponseSchema, DriveFileContentResponseSchema } from './schemas';
-export type { DriveFileListResponse, DriveFileContentResponse } from './schemas';
+export {
+  DriveFileListResponseSchema,
+  DriveFileContentResponseSchema,
+} from "./schemas";
+export type {
+  DriveFileListResponse,
+  DriveFileContentResponse,
+} from "./schemas";

package/src/content/schemas.ts

@@ -9,8 +9,8 @@
  *  - company-md-sharing.ts (GET /api/company-md/docs/:slug/sharing)
  *  - drive.ts             (GET /api/drive/files, GET /api/drive/files/recent, etc.)
  */
-import { z } from 'zod';
-import { CursorPageSchema } from '../api/primitives';
+import { z } from "zod";
+import { CursorPageSchema } from "../api/primitives";
 
 // ---------------------------------------------------------------------------
 // Company.md Sub-schemas
@@ -23,7 +23,7 @@ const CompanyMdPersonSchema = z.object({
 
 const CompanyMdSourceSchema = z.object({
   label: z.string(),
-  sourceType: z.enum(['meeting', 'document', 'conversation', 'manual']),
+  sourceType: z.enum(["meeting", "document", "conversation", "manual"]),
   referencedAt: z.string(),
 });
 
@@ -36,11 +36,21 @@ const CompanyMdTreeNodeSchema = z.object({
   id: z.string(),
   slug: z.string(),
   title: z.string(),
-  level: z.enum(['root', 'department', 'team', 'context']),
+  level: z.enum(["root", "department", "team", "context"]),
   parentId: z.string().nullable(),
-  visibility: z.enum(['private', 'unit', 'org']),
+  visibility: z.enum(["private", "unit", "org"]),
   owningUnitId: z.string().nullable(),
-  type: z.enum(['company', 'department', 'team', 'cross_team', 'doc', 'goal', 'source', 'map', 'context_bank']),
+  type: z.enum([
+    "company",
+    "department",
+    "team",
+    "cross_team",
+    "doc",
+    "goal",
+    "source",
+    "map",
+    "context_bank",
+  ]),
   canEdit: z.boolean(),
   memberCount: z.number().int(),
   description: z.string().optional(),
@@ -53,16 +63,18 @@ const CompanyMdTreeNodeSchema = z.object({
 // ---------------------------------------------------------------------------
 
 /** Response for GET /api/company-md/tree */
-export const CompanyMdListResponseSchema = CursorPageSchema(CompanyMdTreeNodeSchema);
+export const CompanyMdListResponseSchema = CursorPageSchema(
+  CompanyMdTreeNodeSchema,
+);
 
 /** Response for GET /api/company-md/docs/:slug */
 export const CompanyMdDocResponseSchema = z.object({
   id: z.string(),
   slug: z.string(),
   title: z.string(),
-  level: z.enum(['root', 'department', 'team', 'context']),
+  level: z.enum(["root", "department", "team", "context"]),
   content: z.string(),
-  visibility: z.enum(['private', 'unit', 'org']),
+  visibility: z.enum(["private", "unit", "org"]),
   parentId: z.string().nullable(),
   owningUnitId: z.string().nullable(),
   owner: CompanyMdPersonSchema.nullable(),
@@ -71,7 +83,7 @@ export const CompanyMdDocResponseSchema = z.object({
   sources: z.array(CompanyMdSourceSchema),
   dependencies: z.array(CompanyMdDependencySchema),
   members: z.array(CompanyMdPersonSchema),
-  extractionStatus: z.enum(['pending', 'extracting', 'complete', 'failed']),
+  extractionStatus: z.enum(["pending", "extracting", "complete", "failed"]),
   /**
    * Populated only when `extractionStatus === 'failed'`. Carries the
    * diagnostic class/reason recorded by the worker on the latest
@@ -89,35 +101,35 @@ export const CompanyMdDocResponseSchema = z.object({
 // ---------------------------------------------------------------------------
 
 const AclEntrySchema = z.object({
-  principalType: z.enum(['user', 'unit']),
+  principalType: z.enum(["user", "unit"]),
   principalId: z.string(),
   principalName: z.string(),
-  accessLevel: z.enum(['viewer', 'commenter', 'editor']),
+  accessLevel: z.enum(["viewer", "commenter", "editor"]),
   grantedBy: z.object({ id: z.string(), name: z.string() }).nullable(),
   grantedAt: z.string(),
 });
 
 const AccessReasonSchema = z.object({
   source: z.enum([
-    'org_rbac',
-    'sharing_policy',
-    'unit_baseline',
-    'unit_delegation',
-    'acl_grant',
-    'doc_ownership',
+    "org_rbac",
+    "sharing_policy",
+    "unit_baseline",
+    "unit_delegation",
+    "acl_grant",
+    "doc_ownership",
   ]),
   detail: z.string(),
 });
 
 const EffectiveAccessSchema = z.object({
-  level: z.enum(['none', 'viewer', 'commenter', 'editor']),
+  level: z.enum(["none", "viewer", "commenter", "editor"]),
   reasons: z.array(AccessReasonSchema),
   canShare: z.boolean(),
 });
 
 /** Response for GET /api/company-md/docs/:slug/sharing */
 export const CompanyMdShareResponseSchema = z.object({
-  sharingPolicy: z.enum(['restricted', 'org_read', 'org_comment', 'org_edit']),
+  sharingPolicy: z.enum(["restricted", "org_read", "org_comment", "org_edit"]),
   acl: z.array(AclEntrySchema),
   effectiveAccess: EffectiveAccessSchema,
 });
@@ -130,7 +142,7 @@ const CompanyMdContextBankItemSchema = z.object({
   id: z.string(),
   slug: z.string(),
   title: z.string(),
-  visibility: z.enum(['private', 'unit', 'org']),
+  visibility: z.enum(["private", "unit", "org"]),
   updatedAt: z.string(),
 });
 
@@ -183,7 +195,13 @@ export const DriveFileContentResponseSchema = z.object({
 
 export type CompanyMdListResponse = z.infer<typeof CompanyMdListResponseSchema>;
 export type CompanyMdDocResponse = z.infer<typeof CompanyMdDocResponseSchema>;
-export type CompanyMdShareResponse = z.infer<typeof CompanyMdShareResponseSchema>;
-export type CompanyMdContextBankResponse = z.infer<typeof CompanyMdContextBankResponseSchema>;
+export type CompanyMdShareResponse = z.infer<
+  typeof CompanyMdShareResponseSchema
+>;
+export type CompanyMdContextBankResponse = z.infer<
+  typeof CompanyMdContextBankResponseSchema
+>;
 export type DriveFileListResponse = z.infer<typeof DriveFileListResponseSchema>;
-export type DriveFileContentResponse = z.infer<typeof DriveFileContentResponseSchema>;
+export type DriveFileContentResponse = z.infer<
+  typeof DriveFileContentResponseSchema
+>;

package/src/dispatch/index.ts

@@ -20,15 +20,15 @@
  */
 
 export const DISPATCH_DENY_CODES = [
-  'incremental_consent_required',
-  'write_tier_disabled',
-  'provider_access_denied',
-  'execution_budget_exceeded',
+  "incremental_consent_required",
+  "write_tier_disabled",
+  "provider_access_denied",
+  "execution_budget_exceeded",
 ] as const;
 
 export type DispatchDenyCode = (typeof DISPATCH_DENY_CODES)[number];
 
-export type ActionTier = 'SAFE' | 'EXTERNAL' | 'DESTRUCTIVE';
+export type ActionTier = "SAFE" | "EXTERNAL" | "DESTRUCTIVE";
 
 /**
  * The user has no active grant row in `incremental_consents` for the
@@ -59,14 +59,14 @@ export interface WriteTierDisabledMeta {
  * tier paused for this provider).
  */
 export type ProviderAccessDenyReason =
-  | 'provider-disabled'
-  | 'org-override'
-  | 'tier-SAFE-disabled'
-  | 'tier-EXTERNAL-disabled'
-  | 'tier-DESTRUCTIVE-disabled'
-  | 'write-tier-SAFE-globally-disabled'
-  | 'write-tier-EXTERNAL-globally-disabled'
-  | 'write-tier-DESTRUCTIVE-globally-disabled';
+  | "provider-disabled"
+  | "org-override"
+  | "tier-SAFE-disabled"
+  | "tier-EXTERNAL-disabled"
+  | "tier-DESTRUCTIVE-disabled"
+  | "write-tier-SAFE-globally-disabled"
+  | "write-tier-EXTERNAL-globally-disabled"
+  | "write-tier-DESTRUCTIVE-globally-disabled";
 
 export interface ProviderAccessDeniedMeta {
   reason: ProviderAccessDenyReason;
@@ -81,7 +81,7 @@ export interface ProviderAccessDeniedMeta {
  * recovery is always "start a new session / execution".
  */
 export interface ExecutionBudgetExceededMeta {
-  kind: 'token_uses' | 'time_window' | 'provider_calls' | 'rows_returned';
+  kind: "token_uses" | "time_window" | "provider_calls" | "rows_returned";
   executionId: string;
 }
 
@@ -95,5 +95,8 @@ export interface DispatchDenyMetaByCode {
 
 /** Narrow `unknown` to a `DispatchDenyCode` for error-code dispatch switches. */
 export function isDispatchDenyCode(code: unknown): code is DispatchDenyCode {
-  return typeof code === 'string' && (DISPATCH_DENY_CODES as readonly string[]).includes(code);
+  return (
+    typeof code === "string" &&
+    (DISPATCH_DENY_CODES as readonly string[]).includes(code)
+  );
 }

package/src/email/__tests__/registry.test.ts

@@ -1,121 +1,125 @@
-import { describe, it, expect } from 'vitest'
-import { EMAIL_KINDS, getEmailKindDefinition, isValidEmailKind } from '../registry.js'
+import { describe, it, expect } from "vitest";
+import {
+  EMAIL_KINDS,
+  getEmailKindDefinition,
+  isValidEmailKind,
+} from "../registry.js";
 
-describe('EMAIL_KINDS golden snapshot', () => {
-  it('exact values are frozen', () => {
+describe("EMAIL_KINDS golden snapshot", () => {
+  it("exact values are frozen", () => {
     expect(EMAIL_KINDS).toStrictEqual({
-      'auth.otp': {
-        kind: 'auth.otp',
-        subject: 'Your login code',
+      "auth.otp": {
+        kind: "auth.otp",
+        subject: "Your login code",
         plainTextRequired: true,
         htmlSupported: false,
       },
-      'auth.magic_link': {
-        kind: 'auth.magic_link',
-        subject: 'Your login link',
+      "auth.magic_link": {
+        kind: "auth.magic_link",
+        subject: "Your login link",
         plainTextRequired: true,
         htmlSupported: false,
       },
-      'org.invite': {
-        kind: 'org.invite',
-        subject: 'You have been invited to join a workspace',
+      "org.invite": {
+        kind: "org.invite",
+        subject: "You have been invited to join a workspace",
         plainTextRequired: true,
         htmlSupported: true,
       },
-      'org.leadership_granted': {
-        kind: 'org.leadership_granted',
+      "org.leadership_granted": {
+        kind: "org.leadership_granted",
         subject: "You've been added to a team",
         plainTextRequired: true,
         htmlSupported: true,
       },
-      'security.alert': {
-        kind: 'security.alert',
-        subject: 'Security alert for your account',
+      "security.alert": {
+        kind: "security.alert",
+        subject: "Security alert for your account",
         plainTextRequired: true,
         htmlSupported: false,
       },
-      'chat.shared': {
-        kind: 'chat.shared',
-        subject: 'A chat has been shared with you',
+      "chat.shared": {
+        kind: "chat.shared",
+        subject: "A chat has been shared with you",
         plainTextRequired: true,
         htmlSupported: true,
       },
-    })
-  })
-})
+    });
+  });
+});
 
-describe('EMAIL_KINDS registry invariants', () => {
-  it('every registry key matches its definition.kind field', () => {
+describe("EMAIL_KINDS registry invariants", () => {
+  it("every registry key matches its definition.kind field", () => {
     for (const [key, def] of Object.entries(EMAIL_KINDS)) {
-      expect(def.kind).toBe(key)
+      expect(def.kind).toBe(key);
     }
-  })
+  });
 
-  it('all subjects are non-empty strings', () => {
+  it("all subjects are non-empty strings", () => {
     for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.subject).toBe('string')
-      expect(def.subject.length).toBeGreaterThan(0)
+      expect(typeof def.subject).toBe("string");
+      expect(def.subject.length).toBeGreaterThan(0);
     }
-  })
+  });
 
-  it('all entries have required boolean fields plainTextRequired and htmlSupported', () => {
+  it("all entries have required boolean fields plainTextRequired and htmlSupported", () => {
     for (const def of Object.values(EMAIL_KINDS)) {
-      expect(typeof def.plainTextRequired).toBe('boolean')
-      expect(typeof def.htmlSupported).toBe('boolean')
+      expect(typeof def.plainTextRequired).toBe("boolean");
+      expect(typeof def.htmlSupported).toBe("boolean");
     }
-  })
-})
+  });
+});
 
-describe('getEmailKindDefinition', () => {
-  it('returns correct definition for auth.otp', () => {
-    const def = getEmailKindDefinition('auth.otp')
-    expect(def).toStrictEqual(EMAIL_KINDS['auth.otp'])
-  })
+describe("getEmailKindDefinition", () => {
+  it("returns correct definition for auth.otp", () => {
+    const def = getEmailKindDefinition("auth.otp");
+    expect(def).toStrictEqual(EMAIL_KINDS["auth.otp"]);
+  });
 
-  it('returns correct definition for auth.magic_link', () => {
-    const def = getEmailKindDefinition('auth.magic_link')
-    expect(def).toStrictEqual(EMAIL_KINDS['auth.magic_link'])
-  })
+  it("returns correct definition for auth.magic_link", () => {
+    const def = getEmailKindDefinition("auth.magic_link");
+    expect(def).toStrictEqual(EMAIL_KINDS["auth.magic_link"]);
+  });
 
-  it('returns correct definition for org.invite', () => {
-    const def = getEmailKindDefinition('org.invite')
-    expect(def).toStrictEqual(EMAIL_KINDS['org.invite'])
-  })
+  it("returns correct definition for org.invite", () => {
+    const def = getEmailKindDefinition("org.invite");
+    expect(def).toStrictEqual(EMAIL_KINDS["org.invite"]);
+  });
 
-  it('returns correct definition for security.alert', () => {
-    const def = getEmailKindDefinition('security.alert')
-    expect(def).toStrictEqual(EMAIL_KINDS['security.alert'])
-  })
+  it("returns correct definition for security.alert", () => {
+    const def = getEmailKindDefinition("security.alert");
+    expect(def).toStrictEqual(EMAIL_KINDS["security.alert"]);
+  });
 
-  it('returns correct definition for chat.shared', () => {
-    const def = getEmailKindDefinition('chat.shared')
-    expect(def).toStrictEqual(EMAIL_KINDS['chat.shared'])
-  })
+  it("returns correct definition for chat.shared", () => {
+    const def = getEmailKindDefinition("chat.shared");
+    expect(def).toStrictEqual(EMAIL_KINDS["chat.shared"]);
+  });
 
-  it('return value matches registry entry exactly', () => {
+  it("return value matches registry entry exactly", () => {
     for (const [key, expected] of Object.entries(EMAIL_KINDS)) {
-      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS)
-      expect(def).toBe(expected)
+      const def = getEmailKindDefinition(key as keyof typeof EMAIL_KINDS);
+      expect(def).toBe(expected);
     }
-  })
-})
+  });
+});
 
-describe('isValidEmailKind', () => {
-  it('returns true for all valid email kinds', () => {
+describe("isValidEmailKind", () => {
+  it("returns true for all valid email kinds", () => {
     for (const kind of Object.keys(EMAIL_KINDS)) {
-      expect(isValidEmailKind(kind)).toBe(true)
+      expect(isValidEmailKind(kind)).toBe(true);
     }
-  })
+  });
 
-  it('returns false for unknown string', () => {
-    expect(isValidEmailKind('unknown.kind')).toBe(false)
-  })
+  it("returns false for unknown string", () => {
+    expect(isValidEmailKind("unknown.kind")).toBe(false);
+  });
 
-  it('returns false for empty string', () => {
-    expect(isValidEmailKind('')).toBe(false)
-  })
+  it("returns false for empty string", () => {
+    expect(isValidEmailKind("")).toBe(false);
+  });
 
-  it('returns false for partial match', () => {
-    expect(isValidEmailKind('auth')).toBe(false)
-  })
-})
+  it("returns false for partial match", () => {
+    expect(isValidEmailKind("auth")).toBe(false);
+  });
+});

package/src/email/index.ts

@@ -11,13 +11,13 @@
 // Kind Types
 // =============================================================================
 
-export type { EmailKind, EmailPayloads, SendEmailInput } from './types'
+export type { EmailKind, EmailPayloads, SendEmailInput } from "./types";
 
 // =============================================================================
 // Definition Types
 // =============================================================================
 
-export type { EmailKindDefinition } from './registry'
+export type { EmailKindDefinition } from "./registry";
 
 // =============================================================================
 // Registry
@@ -27,4 +27,4 @@ export {
   EMAIL_KINDS,
   getEmailKindDefinition,
   isValidEmailKind,
-} from './registry'
+} from "./registry";