@company-semantics/contracts 9.1.0 → 9.2.0

package/src/meetings/schemas.ts

@@ -20,7 +20,7 @@
  * descriptions live in `.meta({ description })` — structured metadata, not
  * stringified JSON blobs on the schema.
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 // =============================================================================
 // Recording identity
@@ -33,8 +33,10 @@ import { z } from 'zod';
  */
 export const RecordingIdSchema = z
   .string()
-  .regex(/^[0-9A-HJKMNP-TV-Z]{26}$/, 'ULID required')
-  .meta({ description: 'ULID; unified trace key for the recording (INV-MTG-7).' });
+  .regex(/^[0-9A-HJKMNP-TV-Z]{26}$/, "ULID required")
+  .meta({
+    description: "ULID; unified trace key for the recording (INV-MTG-7).",
+  });
 export type RecordingId = z.infer<typeof RecordingIdSchema>;
 
 // =============================================================================
@@ -42,8 +44,9 @@ export type RecordingId = z.infer<typeof RecordingIdSchema>;
 // =============================================================================
 
 /** Which capture stream a chunk came from. Two channels: mic (channel 0) and system (channel 1). */
-export const RecordingSourceSchema = z.enum(['mic', 'system']).meta({
-  description: 'Capture stream identity. Mic = channel 0, system audio = channel 1.',
+export const RecordingSourceSchema = z.enum(["mic", "system"]).meta({
+  description:
+    "Capture stream identity. Mic = channel 0, system audio = channel 1.",
 });
 export type RecordingSource = z.infer<typeof RecordingSourceSchema>;
 
@@ -54,8 +57,10 @@ export type RecordingSource = z.infer<typeof RecordingSourceSchema>;
  * which the BrowserAudioDetector heuristic identifies (PRD-00655).
  */
 export const DetectedMeetingAppSchema = z
-  .enum(['zoom', 'teams', 'meet-browser', 'slack-huddle', 'manual'])
-  .meta({ description: 'Auto-detected meeting app that owns the system audio stream.' });
+  .enum(["zoom", "teams", "meet-browser", "slack-huddle", "manual"])
+  .meta({
+    description: "Auto-detected meeting app that owns the system audio stream.",
+  });
 export type DetectedMeetingApp = z.infer<typeof DetectedMeetingAppSchema>;
 
 /**
@@ -64,8 +69,11 @@ export type DetectedMeetingApp = z.infer<typeof DetectedMeetingAppSchema>;
  * the mac side stays provider-opaque).
  */
 export const TranscriptionProviderSchema = z
-  .enum(['deepgram', 'assemblyai', 'whisper-local'])
-  .meta({ description: 'Server-side selection of transcription provider; never crosses to mac.' });
+  .enum(["deepgram", "assemblyai", "whisper-local"])
+  .meta({
+    description:
+      "Server-side selection of transcription provider; never crosses to mac.",
+  });
 export type TranscriptionProvider = z.infer<typeof TranscriptionProviderSchema>;
 
 /**
@@ -76,20 +84,20 @@ export type TranscriptionProvider = z.infer<typeof TranscriptionProviderSchema>;
  */
 export const RecordingStatusSchema = z
   .enum([
-    'draft',
-    'recording',
-    'processing',
-    'finalized',
-    'failed',
-    'partial-transcript-network',
-    'cancelled',
+    "draft",
+    "recording",
+    "processing",
+    "finalized",
+    "failed",
+    "partial-transcript-network",
+    "cancelled",
   ])
-  .meta({ description: 'Coarse lifecycle state for a recording entity.' });
+  .meta({ description: "Coarse lifecycle state for a recording entity." });
 export type RecordingStatus = z.infer<typeof RecordingStatusSchema>;
 
 /** Quality signal emitted by the capture runtime. Used to surface degradation in the UI. */
-export const RecordingQualitySchema = z.enum(['clean', 'degraded']).meta({
-  description: 'Capture-runtime quality signal. `degraded` triggers a UI hint.',
+export const RecordingQualitySchema = z.enum(["clean", "degraded"]).meta({
+  description: "Capture-runtime quality signal. `degraded` triggers a UI hint.",
 });
 export type RecordingQuality = z.infer<typeof RecordingQualitySchema>;
 
@@ -102,10 +110,10 @@ export type RecordingQuality = z.infer<typeof RecordingQualitySchema>;
  * (`feedback_retrieval_default_off_for_noisy_sources`).
  */
 export const MeetingVisibilitySchema = z
-  .enum(['meeting_only', 'shared', 'org', 'finalized_private'])
+  .enum(["meeting_only", "shared", "org", "finalized_private"])
   .meta({
     description:
-      'Visibility band for the finalized meeting projection. Default `meeting_only`.',
+      "Visibility band for the finalized meeting projection. Default `meeting_only`.",
   });
 export type MeetingVisibility = z.infer<typeof MeetingVisibilitySchema>;
 
@@ -128,7 +136,9 @@ export const SourceSegmentSchema = z
     sampleRateHz: z.literal(16000),
     channels: z.literal(1),
   })
-  .meta({ description: 'Per-source continuous capture segment within a recording.' });
+  .meta({
+    description: "Per-source continuous capture segment within a recording.",
+  });
 export type SourceSegment = z.infer<typeof SourceSegmentSchema>;
 
 // =============================================================================
@@ -153,7 +163,10 @@ export const TranscriptChunkSchema = z
     speakerLabel: z.string().nullable().optional(),
     confidence: z.number().min(0).max(1).optional(),
   })
-  .meta({ description: 'A single transcript window (interim or final) from the provider.' });
+  .meta({
+    description:
+      "A single transcript window (interim or final) from the provider.",
+  });
 export type TranscriptChunk = z.infer<typeof TranscriptChunkSchema>;
 
 // =============================================================================
@@ -161,26 +174,26 @@ export type TranscriptChunk = z.infer<typeof TranscriptChunkSchema>;
 // =============================================================================
 
 const SessionOpenedEventSchema = z.object({
-  kind: z.literal('session_opened'),
+  kind: z.literal("session_opened"),
   recordingId: RecordingIdSchema,
   atMs: z.number().int().nonnegative(),
 });
 
 const ChunkBatchEventSchema = z.object({
-  kind: z.literal('chunk_batch'),
+  kind: z.literal("chunk_batch"),
   recordingId: RecordingIdSchema,
   chunks: z.array(TranscriptChunkSchema).min(1),
 });
 
 const QualityDegradedEventSchema = z.object({
-  kind: z.literal('quality_degraded'),
+  kind: z.literal("quality_degraded"),
   recordingId: RecordingIdSchema,
   reason: z.string().min(1),
   atMs: z.number().int().nonnegative(),
 });
 
 const SessionStoppedEventSchema = z.object({
-  kind: z.literal('session_stopped'),
+  kind: z.literal("session_stopped"),
   recordingId: RecordingIdSchema,
   atMs: z.number().int().nonnegative(),
   expectedLastSequence: z.number().int().nonnegative(),
@@ -196,7 +209,7 @@ const SessionStoppedEventSchema = z.object({
  * `quality_degraded` may interleave.
  */
 export const RecordingEventSchema = z
-  .discriminatedUnion('kind', [
+  .discriminatedUnion("kind", [
     SessionOpenedEventSchema,
     ChunkBatchEventSchema,
     QualityDegradedEventSchema,
@@ -204,7 +217,7 @@ export const RecordingEventSchema = z
   ])
   .meta({
     description:
-      'Event emitted by the capture runtime during a recording session (INV-MTG ordering).',
+      "Event emitted by the capture runtime during a recording session (INV-MTG ordering).",
   });
 export type RecordingEvent = z.infer<typeof RecordingEventSchema>;
 
@@ -228,7 +241,7 @@ export const TranscriptionSessionGrantSchema = z
     audioConfig: z.object({
       sampleRateHz: z.literal(16000),
       channels: z.literal(2),
-      encoding: z.literal('linear16'),
+      encoding: z.literal("linear16"),
       chunkMs: z.literal(200),
     }),
     capabilities: z.object({
@@ -239,9 +252,11 @@ export const TranscriptionSessionGrantSchema = z
   })
   .meta({
     description:
-      'Provider-agnostic grant the mac shell consumes. Mac never sees provider name (INV-MTG-15).',
+      "Provider-agnostic grant the mac shell consumes. Mac never sees provider name (INV-MTG-15).",
   });
-export type TranscriptionSessionGrant = z.infer<typeof TranscriptionSessionGrantSchema>;
+export type TranscriptionSessionGrant = z.infer<
+  typeof TranscriptionSessionGrantSchema
+>;
 
 // =============================================================================
 // Meeting metadata projection (finalized read model)
@@ -271,6 +286,8 @@ export const MeetingMetadataProjectionSchema = z
     transcriptAvailable: z.boolean(),
   })
   .meta({
-    description: 'Finalized read projection for a recording (excludes drafts).',
+    description: "Finalized read projection for a recording (excludes drafts).",
   });
-export type MeetingMetadataProjection = z.infer<typeof MeetingMetadataProjectionSchema>;
+export type MeetingMetadataProjection = z.infer<
+  typeof MeetingMetadataProjectionSchema
+>;

package/src/message-parts/README.md

@@ -18,6 +18,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 ## Public API
 
 **Types:**
+
 - `TextPart`, `SurfacePart`, `AssistantMessagePart` — core part unions
 - `ToolListPart`, `StatusPanelPart`, `ChartPart`, `TablePart` — surface part variants
 - `PreviewData`, `PreviewArtifact`, `PreviewPart` — action preview surfaces
@@ -27,6 +28,7 @@ Canonical vocabulary for structured assistant message output. Defines the type s
 - `IntegrationKey`, `IntegrationProvider` — integration identifiers
 
 **Runtime values:**
+
 - `CONFIRMATION_LABELS` — exhaustive map of ExecutionKind to human-readable labels
 - `getConfirmationLabel(kind, fallback)` — label lookup with fallback
 - `WireSurfaceBuilder` — factory for creating wire-format data parts

package/src/message-parts/__tests__/builder.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect } from "vitest";
 import {
   createPartBuilder,
   addText,
@@ -6,176 +6,176 @@ import {
   addPart,
   buildParts,
   getDroppedCount,
-} from '../builder.js'
-import type { SurfacePart, TextPart } from '../types.js'
+} from "../builder.js";
+import type { SurfacePart, TextPart } from "../types.js";
 
 const mockSurface: SurfacePart = {
-  type: 'tool-list',
+  type: "tool-list",
   tools: [],
-} as unknown as SurfacePart
+} as unknown as SurfacePart;
 
 const anotherSurface: SurfacePart = {
-  type: 'status-panel',
-  title: 'Status',
+  type: "status-panel",
+  title: "Status",
   entries: [],
-}
+};
 
 // =============================================================================
 // Builder Creation
 // =============================================================================
 
-describe('createPartBuilder', () => {
-  it('returns initial state with defaults', () => {
-    const state = createPartBuilder()
-    expect(state.parts).toEqual([])
-    expect(state.hasSurface).toBe(false)
-    expect(state.devMode).toBe(false)
-    expect(state.droppedCount).toBe(0)
-  })
-
-  it('returns state with devMode=true when passed true', () => {
-    const state = createPartBuilder(true)
-    expect(state.devMode).toBe(true)
-    expect(state.parts).toEqual([])
-    expect(state.hasSurface).toBe(false)
-    expect(state.droppedCount).toBe(0)
-  })
-})
+describe("createPartBuilder", () => {
+  it("returns initial state with defaults", () => {
+    const state = createPartBuilder();
+    expect(state.parts).toEqual([]);
+    expect(state.hasSurface).toBe(false);
+    expect(state.devMode).toBe(false);
+    expect(state.droppedCount).toBe(0);
+  });
+
+  it("returns state with devMode=true when passed true", () => {
+    const state = createPartBuilder(true);
+    expect(state.devMode).toBe(true);
+    expect(state.parts).toEqual([]);
+    expect(state.hasSurface).toBe(false);
+    expect(state.droppedCount).toBe(0);
+  });
+});
 
 // =============================================================================
 // NarrativeState (before any surface)
 // =============================================================================
 
-describe('NarrativeState', () => {
-  it('addText is accepted and appends text part', () => {
-    const state = createPartBuilder()
-    const result = addText(state, 'hello')
-    expect(result.accepted).toBe(true)
-    expect(result.state.parts).toEqual([{ type: 'text', text: 'hello' }])
-  })
-
-  it('multiple addText calls accumulate parts in order', () => {
-    let state = createPartBuilder()
-    state = addText(state, 'first').state
-    state = addText(state, 'second').state
-    state = addText(state, 'third').state
+describe("NarrativeState", () => {
+  it("addText is accepted and appends text part", () => {
+    const state = createPartBuilder();
+    const result = addText(state, "hello");
+    expect(result.accepted).toBe(true);
+    expect(result.state.parts).toEqual([{ type: "text", text: "hello" }]);
+  });
+
+  it("multiple addText calls accumulate parts in order", () => {
+    let state = createPartBuilder();
+    state = addText(state, "first").state;
+    state = addText(state, "second").state;
+    state = addText(state, "third").state;
     expect(state.parts).toEqual([
-      { type: 'text', text: 'first' },
-      { type: 'text', text: 'second' },
-      { type: 'text', text: 'third' },
-    ])
-  })
-
-  it('addSurface is accepted and transitions hasSurface to true', () => {
-    const state = createPartBuilder()
-    const result = addSurface(state, mockSurface)
-    expect(result.accepted).toBe(true)
-    expect(result.state.hasSurface).toBe(true)
-  })
-})
+      { type: "text", text: "first" },
+      { type: "text", text: "second" },
+      { type: "text", text: "third" },
+    ]);
+  });
+
+  it("addSurface is accepted and transitions hasSurface to true", () => {
+    const state = createPartBuilder();
+    const result = addSurface(state, mockSurface);
+    expect(result.accepted).toBe(true);
+    expect(result.state.hasSurface).toBe(true);
+  });
+});
 
 // =============================================================================
 // SurfaceState — THE CRITICAL INVARIANT
 // =============================================================================
 
-describe('SurfaceState (text after surface)', () => {
-  it('silently drops text in prod mode (devMode=false)', () => {
-    let state = createPartBuilder(false)
-    state = addSurface(state, mockSurface).state
-    const partsBefore = state.parts.length
-
-    const result = addText(state, 'dropped')
-    expect(result.accepted).toBe(false)
-    expect(result.state.droppedCount).toBe(1)
-    expect(result.state.parts.length).toBe(partsBefore)
-  })
-
-  it('throws invariant violation in dev mode (devMode=true)', () => {
-    let state = createPartBuilder(true)
-    state = addSurface(state, mockSurface).state
-
-    expect(() => addText(state, 'illegal')).toThrow('invariant violation')
-  })
-
-  it('addSurface after addSurface is always accepted', () => {
-    let state = createPartBuilder()
-    state = addSurface(state, mockSurface).state
-    const result = addSurface(state, anotherSurface)
-    expect(result.accepted).toBe(true)
-    expect(result.state.parts.length).toBe(2)
-  })
-
-  it('droppedCount accumulates across multiple drops in prod mode', () => {
-    let state = createPartBuilder(false)
-    state = addSurface(state, mockSurface).state
-
-    state = addText(state, 'drop1').state
-    state = addText(state, 'drop2').state
-    state = addText(state, 'drop3').state
-
-    expect(state.droppedCount).toBe(3)
-  })
-})
+describe("SurfaceState (text after surface)", () => {
+  it("silently drops text in prod mode (devMode=false)", () => {
+    let state = createPartBuilder(false);
+    state = addSurface(state, mockSurface).state;
+    const partsBefore = state.parts.length;
+
+    const result = addText(state, "dropped");
+    expect(result.accepted).toBe(false);
+    expect(result.state.droppedCount).toBe(1);
+    expect(result.state.parts.length).toBe(partsBefore);
+  });
+
+  it("throws invariant violation in dev mode (devMode=true)", () => {
+    let state = createPartBuilder(true);
+    state = addSurface(state, mockSurface).state;
+
+    expect(() => addText(state, "illegal")).toThrow("invariant violation");
+  });
+
+  it("addSurface after addSurface is always accepted", () => {
+    let state = createPartBuilder();
+    state = addSurface(state, mockSurface).state;
+    const result = addSurface(state, anotherSurface);
+    expect(result.accepted).toBe(true);
+    expect(result.state.parts.length).toBe(2);
+  });
+
+  it("droppedCount accumulates across multiple drops in prod mode", () => {
+    let state = createPartBuilder(false);
+    state = addSurface(state, mockSurface).state;
+
+    state = addText(state, "drop1").state;
+    state = addText(state, "drop2").state;
+    state = addText(state, "drop3").state;
+
+    expect(state.droppedCount).toBe(3);
+  });
+});
 
 // =============================================================================
 // addPart dispatch
 // =============================================================================
 
-describe('addPart', () => {
-  it('dispatches TextPart to addText behavior', () => {
-    const state = createPartBuilder()
-    const textPart: TextPart = { type: 'text', text: 'dispatched' }
-    const result = addPart(state, textPart)
-    expect(result.accepted).toBe(true)
-    expect(result.state.parts).toEqual([{ type: 'text', text: 'dispatched' }])
-  })
-
-  it('dispatches SurfacePart to addSurface behavior', () => {
-    const state = createPartBuilder()
-    const result = addPart(state, mockSurface)
-    expect(result.accepted).toBe(true)
-    expect(result.state.hasSurface).toBe(true)
-  })
-})
+describe("addPart", () => {
+  it("dispatches TextPart to addText behavior", () => {
+    const state = createPartBuilder();
+    const textPart: TextPart = { type: "text", text: "dispatched" };
+    const result = addPart(state, textPart);
+    expect(result.accepted).toBe(true);
+    expect(result.state.parts).toEqual([{ type: "text", text: "dispatched" }]);
+  });
+
+  it("dispatches SurfacePart to addSurface behavior", () => {
+    const state = createPartBuilder();
+    const result = addPart(state, mockSurface);
+    expect(result.accepted).toBe(true);
+    expect(result.state.hasSurface).toBe(true);
+  });
+});
 
 // =============================================================================
 // Finalization
 // =============================================================================
 
-describe('buildParts', () => {
-  it('returns array copy — mutating result does not affect builder', () => {
-    let state = createPartBuilder()
-    state = addText(state, 'text1').state
-    state = addSurface(state, mockSurface).state
-
-    const parts = buildParts(state)
-    parts.push({ type: 'text', text: 'injected' })
-
-    expect(buildParts(state)).toHaveLength(2)
-  })
-
-  it('preserves correct part ordering (text before surfaces)', () => {
-    let state = createPartBuilder()
-    state = addText(state, 'narrative').state
-    state = addSurface(state, mockSurface).state
-
-    const parts = buildParts(state)
-    expect(parts[0].type).toBe('text')
-    expect(parts[1].type).not.toBe('text')
-  })
-})
-
-describe('getDroppedCount', () => {
-  it('returns current droppedCount from state', () => {
-    let state = createPartBuilder(false)
-    state = addSurface(state, mockSurface).state
-    state = addText(state, 'dropped').state
-
-    expect(getDroppedCount(state)).toBe(1)
-  })
-
-  it('returns 0 when no drops have occurred', () => {
-    const state = createPartBuilder()
-    expect(getDroppedCount(state)).toBe(0)
-  })
-})
+describe("buildParts", () => {
+  it("returns array copy — mutating result does not affect builder", () => {
+    let state = createPartBuilder();
+    state = addText(state, "text1").state;
+    state = addSurface(state, mockSurface).state;
+
+    const parts = buildParts(state);
+    parts.push({ type: "text", text: "injected" });
+
+    expect(buildParts(state)).toHaveLength(2);
+  });
+
+  it("preserves correct part ordering (text before surfaces)", () => {
+    let state = createPartBuilder();
+    state = addText(state, "narrative").state;
+    state = addSurface(state, mockSurface).state;
+
+    const parts = buildParts(state);
+    expect(parts[0].type).toBe("text");
+    expect(parts[1].type).not.toBe("text");
+  });
+});
+
+describe("getDroppedCount", () => {
+  it("returns current droppedCount from state", () => {
+    let state = createPartBuilder(false);
+    state = addSurface(state, mockSurface).state;
+    state = addText(state, "dropped").state;
+
+    expect(getDroppedCount(state)).toBe(1);
+  });
+
+  it("returns 0 when no drops have occurred", () => {
+    const state = createPartBuilder();
+    expect(getDroppedCount(state)).toBe(0);
+  });
+});