@company-semantics/contracts 9.0.0 → 9.2.0

package/src/ci-envelope/__tests__/transitions.test.ts

@@ -1,82 +1,82 @@
-import { describe, it, expect } from 'vitest'
-import { ENVELOPE_TRANSITIONS } from '../types.js'
-import type { CIEnvelopeStatus } from '../types.js'
+import { describe, it, expect } from "vitest";
+import { ENVELOPE_TRANSITIONS } from "../types.js";
+import type { CIEnvelopeStatus } from "../types.js";
 
 const ALL_STATUSES: CIEnvelopeStatus[] = [
-  'proposed',
-  'validated',
-  'blocked',
-  'executing',
-  'finalized',
-]
+  "proposed",
+  "validated",
+  "blocked",
+  "executing",
+  "finalized",
+];
 
-describe('ENVELOPE_TRANSITIONS terminal states', () => {
-  it('blocked is terminal (empty transition array)', () => {
-    expect(ENVELOPE_TRANSITIONS['blocked']).toEqual([])
-  })
+describe("ENVELOPE_TRANSITIONS terminal states", () => {
+  it("blocked is terminal (empty transition array)", () => {
+    expect(ENVELOPE_TRANSITIONS["blocked"]).toEqual([]);
+  });
 
-  it('finalized is terminal (empty transition array)', () => {
-    expect(ENVELOPE_TRANSITIONS['finalized']).toEqual([])
-  })
+  it("finalized is terminal (empty transition array)", () => {
+    expect(ENVELOPE_TRANSITIONS["finalized"]).toEqual([]);
+  });
 
-  it('only blocked and finalized are terminal', () => {
+  it("only blocked and finalized are terminal", () => {
     const nonTerminal = ALL_STATUSES.filter(
-      (s) => s !== 'blocked' && s !== 'finalized'
-    )
+      (s) => s !== "blocked" && s !== "finalized",
+    );
     for (const state of nonTerminal) {
-      expect(ENVELOPE_TRANSITIONS[state].length).toBeGreaterThan(0)
+      expect(ENVELOPE_TRANSITIONS[state].length).toBeGreaterThan(0);
     }
-  })
-})
+  });
+});
 
-describe('ENVELOPE_TRANSITIONS state machine', () => {
-  it('proposed can transition to validated and blocked', () => {
-    expect(ENVELOPE_TRANSITIONS['proposed']).toContain('validated')
-    expect(ENVELOPE_TRANSITIONS['proposed']).toContain('blocked')
-  })
+describe("ENVELOPE_TRANSITIONS state machine", () => {
+  it("proposed can transition to validated and blocked", () => {
+    expect(ENVELOPE_TRANSITIONS["proposed"]).toContain("validated");
+    expect(ENVELOPE_TRANSITIONS["proposed"]).toContain("blocked");
+  });
 
-  it('validated can transition to executing and blocked', () => {
-    expect(ENVELOPE_TRANSITIONS['validated']).toContain('executing')
-    expect(ENVELOPE_TRANSITIONS['validated']).toContain('blocked')
-  })
+  it("validated can transition to executing and blocked", () => {
+    expect(ENVELOPE_TRANSITIONS["validated"]).toContain("executing");
+    expect(ENVELOPE_TRANSITIONS["validated"]).toContain("blocked");
+  });
 
-  it('executing can transition to finalized and blocked', () => {
-    expect(ENVELOPE_TRANSITIONS['executing']).toContain('finalized')
-    expect(ENVELOPE_TRANSITIONS['executing']).toContain('blocked')
-  })
+  it("executing can transition to finalized and blocked", () => {
+    expect(ENVELOPE_TRANSITIONS["executing"]).toContain("finalized");
+    expect(ENVELOPE_TRANSITIONS["executing"]).toContain("blocked");
+  });
 
-  it('proposed cannot transition to executing or finalized directly', () => {
-    expect(ENVELOPE_TRANSITIONS['proposed']).not.toContain('executing')
-    expect(ENVELOPE_TRANSITIONS['proposed']).not.toContain('finalized')
-  })
-})
+  it("proposed cannot transition to executing or finalized directly", () => {
+    expect(ENVELOPE_TRANSITIONS["proposed"]).not.toContain("executing");
+    expect(ENVELOPE_TRANSITIONS["proposed"]).not.toContain("finalized");
+  });
+});
 
-describe('ENVELOPE_TRANSITIONS exhaustiveness', () => {
-  it('has entries for all 5 CIEnvelopeStatus values', () => {
+describe("ENVELOPE_TRANSITIONS exhaustiveness", () => {
+  it("has entries for all 5 CIEnvelopeStatus values", () => {
     for (const status of ALL_STATUSES) {
-      expect(ENVELOPE_TRANSITIONS).toHaveProperty(status)
+      expect(ENVELOPE_TRANSITIONS).toHaveProperty(status);
     }
-  })
+  });
 
-  it('every transition target is a valid CIEnvelopeStatus', () => {
+  it("every transition target is a valid CIEnvelopeStatus", () => {
     for (const state of ALL_STATUSES) {
       for (const target of ENVELOPE_TRANSITIONS[state]) {
-        expect(ALL_STATUSES).toContain(target)
+        expect(ALL_STATUSES).toContain(target);
       }
     }
-  })
-})
+  });
+});
 
-describe('ENVELOPE_TRANSITIONS forward progression', () => {
-  it('no state can transition to proposed (initial state only)', () => {
+describe("ENVELOPE_TRANSITIONS forward progression", () => {
+  it("no state can transition to proposed (initial state only)", () => {
     for (const state of ALL_STATUSES) {
-      expect(ENVELOPE_TRANSITIONS[state]).not.toContain('proposed')
+      expect(ENVELOPE_TRANSITIONS[state]).not.toContain("proposed");
     }
-  })
+  });
 
-  it('no state can transition to itself (no self-loops)', () => {
+  it("no state can transition to itself (no self-loops)", () => {
     for (const state of ALL_STATUSES) {
-      expect(ENVELOPE_TRANSITIONS[state]).not.toContain(state)
+      expect(ENVELOPE_TRANSITIONS[state]).not.toContain(state);
     }
-  })
-})
+  });
+});

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)
+  );
 }