@foundrynorth/compass-schema 1.0.20 → 1.0.21

package/dist/types/activity-feed.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared types for the order activity feed — the backbone for all
+ * post-submission visibility (contract alerts, fulfillment status,
+ * creative status, amendments, rate exception resolution).
+ */
+export declare const ACTIVITY_EVENT_TYPES: readonly ["fulfillment_stage_changed", "creative_status_changed", "creative_delivered", "signing_progress", "drawdown_alert", "renewal_reminder", "amendment_submitted", "rate_exception_resolved", "sla_hold_set", "sla_hold_cleared", "sla_milestone_at_risk", "sla_milestone_breached", "sla_evaluated"];
+export type ActivityEventType = (typeof ACTIVITY_EVENT_TYPES)[number];
+export declare const ACTIVITY_SEVERITIES: readonly ["info", "success", "warning", "action_needed"];
+export type ActivitySeverity = (typeof ACTIVITY_SEVERITIES)[number];
+export declare const ACTIVITY_SOURCE_SYSTEMS: readonly ["flux", "forge", "hubspot", "compass"];
+export type ActivitySourceSystem = (typeof ACTIVITY_SOURCE_SYSTEMS)[number];
+export declare const PENDING_ACTION_TYPES: readonly ["creative_revision_needed", "creative_rejected", "fulfillment_blocked", "rate_exception_pending", "sla_hold_active"];
+export type PendingActionType = (typeof PENDING_ACTION_TYPES)[number];
+/** The event envelope fn-flux sends to fn-legacy */
+export interface CompassStatusEvent {
+    schemaVersion: "v1";
+    eventId: string;
+    eventType: string;
+    idempotencyKey: string;
+    emittedAt: string;
+    payload: {
+        mediaOrderId: string;
+        lineItemId?: string | null;
+        hubspotCompanyId?: string | null;
+        title: string;
+        detail?: string | null;
+        severity: ActivitySeverity;
+        status?: string | null;
+        metadata?: Record<string, unknown> | null;
+    };
+}
+/** Resolution mapping: which events clear which pending actions */
+export declare const PENDING_ACTION_RESOLUTION_MAP: Record<PendingActionType, {
+    resolvedByEventType: ActivityEventType;
+    resolvedByStatuses: string[];
+}>;
+//# sourceMappingURL=activity-feed.d.ts.map

package/dist/types/activity-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-feed.d.ts","sourceRoot":"","sources":["../../src/types/activity-feed.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,oBAAoB,6SAcvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,eAAO,MAAM,mBAAmB,0DAKtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,eAAO,MAAM,uBAAuB,kDAK1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,oBAAoB,gIAMvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,oDAAoD;AACpD,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE;QACP,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,QAAQ,EAAE,gBAAgB,CAAC;QAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC3C,CAAC;CACH;AAED,mEAAmE;AACnE,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAChD,iBAAiB,EACjB;IAAE,mBAAmB,EAAE,iBAAiB,CAAC;IAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;CAAE,CAsBzE,CAAC"}

package/dist/types/activity-feed.js

@@ -0,0 +1,63 @@
+/**
+ * Shared types for the order activity feed — the backbone for all
+ * post-submission visibility (contract alerts, fulfillment status,
+ * creative status, amendments, rate exception resolution).
+ */
+export const ACTIVITY_EVENT_TYPES = [
+    "fulfillment_stage_changed",
+    "creative_status_changed",
+    "creative_delivered",
+    "signing_progress",
+    "drawdown_alert",
+    "renewal_reminder",
+    "amendment_submitted",
+    "rate_exception_resolved",
+    "sla_hold_set",
+    "sla_hold_cleared",
+    "sla_milestone_at_risk",
+    "sla_milestone_breached",
+    "sla_evaluated",
+];
+export const ACTIVITY_SEVERITIES = [
+    "info",
+    "success",
+    "warning",
+    "action_needed",
+];
+export const ACTIVITY_SOURCE_SYSTEMS = [
+    "flux",
+    "forge",
+    "hubspot",
+    "compass",
+];
+export const PENDING_ACTION_TYPES = [
+    "creative_revision_needed",
+    "creative_rejected",
+    "fulfillment_blocked",
+    "rate_exception_pending",
+    "sla_hold_active",
+];
+/** Resolution mapping: which events clear which pending actions */
+export const PENDING_ACTION_RESOLUTION_MAP = {
+    creative_revision_needed: {
+        resolvedByEventType: "creative_status_changed",
+        resolvedByStatuses: ["approved", "completed"],
+    },
+    creative_rejected: {
+        resolvedByEventType: "creative_status_changed",
+        resolvedByStatuses: ["approved"],
+    },
+    fulfillment_blocked: {
+        resolvedByEventType: "fulfillment_stage_changed",
+        resolvedByStatuses: ["pending_fulfillment", "running", "completed"],
+    },
+    rate_exception_pending: {
+        resolvedByEventType: "rate_exception_resolved",
+        resolvedByStatuses: ["approved", "auto_approved", "rejected"],
+    },
+    sla_hold_active: {
+        resolvedByEventType: "sla_hold_cleared",
+        resolvedByStatuses: ["clear"],
+    },
+};
+//# sourceMappingURL=activity-feed.js.map

package/dist/types/activity-feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-feed.js","sourceRoot":"","sources":["../../src/types/activity-feed.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,2BAA2B;IAC3B,yBAAyB;IACzB,oBAAoB;IACpB,kBAAkB;IAClB,gBAAgB;IAChB,kBAAkB;IAClB,qBAAqB;IACrB,yBAAyB;IACzB,cAAc;IACd,kBAAkB;IAClB,uBAAuB;IACvB,wBAAwB;IACxB,eAAe;CACP,CAAC;AAIX,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,MAAM;IACN,SAAS;IACT,SAAS;IACT,eAAe;CACP,CAAC;AAIX,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,MAAM;IACN,OAAO;IACP,SAAS;IACT,SAAS;CACD,CAAC;AAIX,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,0BAA0B;IAC1B,mBAAmB;IACnB,qBAAqB;IACrB,wBAAwB;IACxB,iBAAiB;CACT,CAAC;AAuBX,mEAAmE;AACnE,MAAM,CAAC,MAAM,6BAA6B,GAGtC;IACF,wBAAwB,EAAE;QACxB,mBAAmB,EAAE,yBAAyB;QAC9C,kBAAkB,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;KAC9C;IACD,iBAAiB,EAAE;QACjB,mBAAmB,EAAE,yBAAyB;QAC9C,kBAAkB,EAAE,CAAC,UAAU,CAAC;KACjC;IACD,mBAAmB,EAAE;QACnB,mBAAmB,EAAE,2BAA2B;QAChD,kBAAkB,EAAE,CAAC,qBAAqB,EAAE,SAAS,EAAE,WAAW,CAAC;KACpE;IACD,sBAAsB,EAAE;QACtB,mBAAmB,EAAE,yBAAyB;QAC9C,kBAAkB,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC;KAC9D;IACD,eAAe,EAAE;QACf,mBAAmB,EAAE,kBAAkB;QACvC,kBAAkB,EAAE,CAAC,OAAO,CAAC;KAC9B;CACF,CAAC"}

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@foundrynorth/compass-schema",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "Canonical Drizzle ORM schema for Foundry Compass (rough-waterfall database)",
-  "license": "UNLICENSED",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +20,7 @@
     "src"
   ],
   "scripts": {
+    "check": "tsc --noEmit",
     "build": "tsc",
     "prepublishOnly": "npm run build"
   },

package/src/schema.ts

@@ -105,6 +105,12 @@ import {
 import { createInsertSchema } from "drizzle-zod";
 import { z } from "zod";
 import type { IntelligenceData } from "./analyzeTypes.js";
+import {
+  ACTIVITY_EVENT_TYPES,
+  ACTIVITY_SEVERITIES,
+  ACTIVITY_SOURCE_SYSTEMS,
+  PENDING_ACTION_TYPES,
+} from "./types/activity-feed.js";
 
 export const users = pgTable("users", {
   id: varchar("id")
@@ -124,6 +130,38 @@ export type User = typeof users.$inferSelect;
 
 export const avatarRequestStatusEnum = pgEnum("avatar_request_status", ["pending", "processed", "rejected"]);
 
+// Activity feed enums (order activity feed + pending actions)
+export const activityEventTypeEnum = pgEnum(
+  "activity_event_type",
+  ACTIVITY_EVENT_TYPES as unknown as [string, ...string[]],
+);
+
+export const activitySeverityEnum = pgEnum(
+  "activity_severity",
+  ACTIVITY_SEVERITIES as unknown as [string, ...string[]],
+);
+
+export const activitySourceSystemEnum = pgEnum(
+  "activity_source_system",
+  ACTIVITY_SOURCE_SYSTEMS as unknown as [string, ...string[]],
+);
+
+export const pendingActionTypeEnum = pgEnum(
+  "pending_action_type",
+  PENDING_ACTION_TYPES as unknown as [string, ...string[]],
+);
+
+export const amendmentReasonEnum = pgEnum("amendment_reason", [
+  "budget_adjustment",
+  "flight_date_change",
+  "product_swap",
+  "add_line_items",
+  "remove_line_items",
+  "rate_renegotiation",
+  "client_request",
+  "other",
+]);
+
 // Vendor enums (must be declared before clerkUsers which references them)
 export const vendorFulfillmentStatusEnum = pgEnum("vendor_fulfillment_status", [
   "assigned",
@@ -208,6 +246,19 @@ export const userProfiles = pgTable("user_profiles", {
   photoUrl: text("photo_url"), // Profile photo (can sync from Clerk or custom upload)
   agencyAvatarUrl: text("agency_avatar_url"), // Hand-sketched avatar for proposals (Fal.ai)
   lastAvatarGeneratedAt: timestamp("last_avatar_generated_at"), // Rate limiting: non-admins can only generate 1/day
+  proposalPortraitRenderUrl: text("proposal_portrait_render_url"),
+  proposalPortraitCutoutUrl: text("proposal_portrait_cutout_url"),
+  proposalPortraitStatus: text("proposal_portrait_status"),
+  proposalPortraitPromptVersion: text("proposal_portrait_prompt_version"),
+  proposalPortraitSeed: integer("proposal_portrait_seed"),
+  proposalPortraitGeneratedAt: timestamp("proposal_portrait_generated_at"),
+  proposalPortraitSourcePhotoHash: text("proposal_portrait_source_photo_hash"),
+  proposalPortraitPreviewRenderUrl: text("proposal_portrait_preview_render_url"),
+  proposalPortraitPreviewCutoutUrl: text("proposal_portrait_preview_cutout_url"),
+  proposalPortraitPreviewPromptVersion: text("proposal_portrait_preview_prompt_version"),
+  proposalPortraitPreviewSeed: integer("proposal_portrait_preview_seed"),
+  proposalPortraitPreviewGeneratedAt: timestamp("proposal_portrait_preview_generated_at"),
+  proposalPortraitPreviewSourcePhotoHash: text("proposal_portrait_preview_source_photo_hash"),
 
   // Active Market Preference (overrides partner default)
   preferredMarketId: varchar("preferred_market_id"), // User's preferred market for planning
@@ -247,6 +298,19 @@ export const externalTeamMembers = pgTable("external_team_members", {
   title: text("title"),
   photoUrl: text("photo_url"),
   agencyAvatarUrl: text("agency_avatar_url"),
+  proposalPortraitRenderUrl: text("proposal_portrait_render_url"),
+  proposalPortraitCutoutUrl: text("proposal_portrait_cutout_url"),
+  proposalPortraitStatus: text("proposal_portrait_status"),
+  proposalPortraitPromptVersion: text("proposal_portrait_prompt_version"),
+  proposalPortraitSeed: integer("proposal_portrait_seed"),
+  proposalPortraitGeneratedAt: timestamp("proposal_portrait_generated_at"),
+  proposalPortraitSourcePhotoHash: text("proposal_portrait_source_photo_hash"),
+  proposalPortraitPreviewRenderUrl: text("proposal_portrait_preview_render_url"),
+  proposalPortraitPreviewCutoutUrl: text("proposal_portrait_preview_cutout_url"),
+  proposalPortraitPreviewPromptVersion: text("proposal_portrait_preview_prompt_version"),
+  proposalPortraitPreviewSeed: integer("proposal_portrait_preview_seed"),
+  proposalPortraitPreviewGeneratedAt: timestamp("proposal_portrait_preview_generated_at"),
+  proposalPortraitPreviewSourcePhotoHash: text("proposal_portrait_preview_source_photo_hash"),
   linkedinUrl: text("linkedin_url"),
   displayOrder: integer("display_order").default(0),
   createdAt: timestamp("created_at").notNull().defaultNow(),
@@ -1029,7 +1093,7 @@ export const plans = pgTable("plans", {
   contractId: uuid("contract_id"), // FK → contracts.id (nullable — links to annual contract)
 
   // Workflow mode: determines which UI sections and features are available
-  // 'research_backed' = full AnalyzeAndPlan flow (default, all existing plans)
+  // 'research_backed' = discovery mode — creates plan, runs analysis in background
   // 'direct_config' = configure products directly without research
   // 'aor_pitch' = agency-of-record pitch with proposal focus
   // 'io_entry' = direct insertion order entry from client PDF/XLSX
@@ -1762,6 +1826,7 @@ export const clerkUsers = pgTable("clerk_users", {
   createdAt: timestamp("created_at").notNull().defaultNow(),
   approvedAt: timestamp("approved_at"),
   approvedBy: text("approved_by"), // Admin who approved
+  compassVoiceWarmth: numeric("compass_voice_warmth").default("0.6"),
 });
 
 export const insertClerkUserSchema = createInsertSchema(clerkUsers).omit({
@@ -4707,6 +4772,39 @@ export const mediaOrderStatusEnum = pgEnum("media_order_status", [
   "completed",
 ]);
 
+export const salesInitiatives = pgTable(
+  "sales_initiatives",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    code: varchar("code").notNull().unique(),
+    name: varchar("name").notNull(),
+    description: text("description"),
+    hubspotValue: varchar("hubspot_value").notNull().unique(),
+    displayOrder: integer("display_order").notNull().default(0),
+    startsAt: date("starts_at"),
+    endsAt: date("ends_at"),
+    isActive: boolean("is_active").notNull().default(true),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("sales_initiatives_active_idx").on(table.isActive),
+    index("sales_initiatives_display_order_idx").on(table.displayOrder),
+  ],
+);
+
+export const insertSalesInitiativeSchema = createInsertSchema(
+  salesInitiatives,
+).omit({
+  id: true,
+  createdAt: true,
+  updatedAt: true,
+});
+export const updateSalesInitiativeSchema = insertSalesInitiativeSchema.partial();
+export type SalesInitiative = typeof salesInitiatives.$inferSelect;
+export type InsertSalesInitiative = z.infer<typeof insertSalesInitiativeSchema>;
+export type UpdateSalesInitiative = z.infer<typeof updateSalesInitiativeSchema>;
+
 export const mediaOrders = pgTable(
   "media_orders",
   {
@@ -4722,6 +4820,7 @@ export const mediaOrders = pgTable(
     hubspotDealId: text("hubspot_deal_id"),
     hubspotCompanyId: text("hubspot_company_id"),
     parentHubspotCompanyId: text("parent_hubspot_company_id"),
+    initiativeCode: varchar("initiative_code"),
 
     // Client header
     clientName: text("client_name").notNull(),
@@ -4749,6 +4848,8 @@ export const mediaOrders = pgTable(
     activatedAt: timestamp("activated_at"),
     completedAt: timestamp("completed_at"),
     returnReason: text("return_reason"),
+    amendmentReason: amendmentReasonEnum("amendment_reason"),
+    amendmentNotes: text("amendment_notes"),
     slaHold: boolean("sla_hold").default(false),
     clientTier: text("client_tier"),
 
@@ -4780,9 +4881,6 @@ export const mediaOrders = pgTable(
     // Order-level notes
     orderNotes: text("order_notes"),
 
-    // Sales initiative (links to sales_initiatives table)
-    initiativeCode: varchar("initiative_code"),
-
     // Billing fields
     navigaAdvertiserId: text("naviga_advertiser_id"),
     purchaseOrderNumber: text("purchase_order_number"),
@@ -4839,6 +4937,7 @@ export const mediaOrders = pgTable(
     index("media_orders_engagement_id_idx").on(table.engagementId),
     index("media_orders_partner_id_idx").on(table.partnerId),
     index("media_orders_hubspot_company_id_idx").on(table.hubspotCompanyId),
+    index("media_orders_hubspot_deal_id_idx").on(table.hubspotDealId),
     index("media_orders_status_idx").on(table.status),
     index("media_orders_vendor_id_idx").on(table.vendorId),
     index("media_orders_vendor_fulfillment_status_idx").on(table.vendorFulfillmentStatus),
@@ -4973,6 +5072,7 @@ export const mediaOrderLineItems = pgTable(
     // Fulfillment details (product-specific fields for HubSpot sync)
     fulfillmentDetails: jsonb("fulfillment_details"),
     creativeSource: varchar("creative_source"),
+    initiativeCode: varchar("initiative_code"),
 
     // Ad trafficking reference key (auto-generated naming convention)
     trafficKey: text("traffic_key"),
@@ -4994,9 +5094,11 @@ export const mediaOrderLineItems = pgTable(
   },
   (table) => [
     index("media_order_line_items_section_id_idx").on(table.sectionId),
+    index("media_order_line_items_sync_status_idx").on(table.syncStatus),
     index("idx_line_items_parent").on(table.parentLineItemId),
     index("media_order_line_items_location_id_idx").on(table.locationId),
     index("media_order_line_items_tracking_key_idx").on(table.trackingKey),
+    index("media_order_line_items_initiative_code_idx").on(table.initiativeCode),
   ]
 );
 
@@ -5217,6 +5319,30 @@ export const updateStribProductSchema = insertStribProductSchema.partial();
 export type StribProduct = typeof stribProducts.$inferSelect;
 export type InsertStribProduct = z.infer<typeof insertStribProductSchema>;
 
+export const salesInitiativeProducts = pgTable(
+  "sales_initiative_products",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    initiativeCode: varchar("initiative_code").notNull(),
+    stribProductId: uuid("strib_product_id")
+      .notNull()
+      .references(() => stribProducts.id, { onDelete: "cascade" }),
+    displayOrder: integer("display_order").notNull().default(0),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("sales_initiative_products_unique_idx").on(
+      table.initiativeCode,
+      table.stribProductId,
+    ),
+    index("sales_initiative_products_code_idx").on(table.initiativeCode),
+    index("sales_initiative_products_product_idx").on(table.stribProductId),
+  ],
+);
+
+export type SalesInitiativeProduct = typeof salesInitiativeProducts.$inferSelect;
+
 /**
  * strib_product_rates — tier-based pricing per product.
  * Different tiers depending on family: Digital uses open/advocacy/tier_1/tier_2/tier_3;
@@ -5555,6 +5681,7 @@ export const rateExceptionRequests = pgTable(
     escalationHistory: jsonb("escalation_history"), // Array of {level, at, by, reason}
     expiresAt: timestamp("expires_at"),
     approvalScope: varchar("approval_scope").notNull().default("request"), // "request" = affects this exception only; "catalog" = also updates global product rate
+    batchId: uuid("batch_id"), // Groups bulk rate exception requests submitted together
     createdAt: timestamp("created_at").notNull().defaultNow(),
     updatedAt: timestamp("updated_at").notNull().defaultNow(),
   },
@@ -5563,6 +5690,8 @@ export const rateExceptionRequests = pgTable(
     index("rate_exception_status_idx").on(table.status),
     index("rate_exception_requester_idx").on(table.requestedByUserId),
     index("rate_exception_plan_idx").on(table.planId),
+    index("rate_exception_batch_idx").on(table.batchId),
+    index("rate_exception_order_status_idx").on(table.mediaOrderId, table.status),
   ]
 );
 
@@ -5633,6 +5762,41 @@ export const slaConfig = pgTable("sla_config", {
 export type SlaConfig = typeof slaConfig.$inferSelect;
 export type InsertSlaConfig = typeof slaConfig.$inferInsert;
 
+// ─── SLA Snapshots ───────────────────────────────────────────────────────────
+
+/**
+ * sla_snapshots — Point-in-time SLA state from fn-flux evaluations.
+ * Each row captures the hold status, deadline, milestones, and profile
+ * for a given media order + fulfillment ticket pair.
+ */
+export const slaHoldStatusEnum = pgEnum("sla_hold_status", ["clear", "hold", "override"]);
+
+export const slaSnapshots = pgTable(
+  "sla_snapshots",
+  {
+    id: serial("id").primaryKey(),
+    mediaOrderId: text("media_order_id").notNull().references(() => mediaOrders.id),
+    ticketId: text("ticket_id").notNull(),
+    holdStatus: slaHoldStatusEnum("hold_status").notNull().default("clear"),
+    holdReason: text("hold_reason"),
+    slaDays: integer("sla_days").notNull(),
+    availableDays: numeric("available_days"),
+    slaDeadline: timestamp("sla_deadline"),
+    campaignStartDate: date("campaign_start_date"),
+    milestones: jsonb("milestones"),
+    profileName: text("profile_name"),
+    lastUpdatedAt: timestamp("last_updated_at").defaultNow(),
+  },
+  (table) => [
+    index("sla_snapshots_media_order_id_idx").on(table.mediaOrderId),
+    index("sla_snapshots_ticket_id_idx").on(table.ticketId),
+    uniqueIndex("sla_snapshots_order_ticket_uniq").on(table.mediaOrderId, table.ticketId),
+  ]
+);
+
+export type SlaSnapshot = typeof slaSnapshots.$inferSelect;
+export type InsertSlaSnapshot = typeof slaSnapshots.$inferInsert;
+
 // ─── Inventory Sync Audit Trail ─────────────────────────────────────────────
 
 /**
@@ -8205,3 +8369,131 @@ export const creativeDeliveries = pgTable("creative_deliveries", {
   assetCount: integer("asset_count").notNull().default(0),
   receivedAt: timestamp("received_at").defaultNow().notNull(),
 });
+
+// ─── Order Activity Feed ────────────────────────────────────────────────────
+
+export const orderActivityFeed = pgTable(
+  "order_activity_feed",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    mediaOrderId: varchar("media_order_id")
+      .notNull()
+      .references(() => mediaOrders.id),
+    lineItemId: varchar("line_item_id").references(() => mediaOrderLineItems.id),
+    eventType: activityEventTypeEnum("event_type").notNull(),
+    title: text("title").notNull(),
+    detail: text("detail"),
+    severity: activitySeverityEnum("severity").notNull(),
+    sourceSystem: activitySourceSystemEnum("source_system").notNull(),
+    externalId: text("external_id").notNull().unique(), // idempotency key — prevents duplicate event ingestion
+    status: text("status"), // intentionally untyped — values vary by eventType (creative vs fulfillment vs contract)
+    occurredAt: timestamp("occurred_at").notNull(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>(),
+  },
+  (table) => [
+    index("order_activity_feed_order_occurred_idx").on(
+      table.mediaOrderId,
+      table.occurredAt,
+    ),
+    index("order_activity_feed_line_item_idx").on(table.lineItemId),
+  ],
+);
+
+export type OrderActivityFeedEntry = typeof orderActivityFeed.$inferSelect;
+
+// ─── Pending Actions ────────────────────────────────────────────────────────
+
+export const pendingActions = pgTable(
+  "pending_actions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    mediaOrderId: varchar("media_order_id")
+      .notNull()
+      .references(() => mediaOrders.id),
+    lineItemId: varchar("line_item_id").references(() => mediaOrderLineItems.id),
+    actionType: pendingActionTypeEnum("action_type").notNull(),
+    message: text("message").notNull(),
+    activityFeedId: uuid("activity_feed_id")
+      .notNull()
+      .references(() => orderActivityFeed.id),
+    resolvedAt: timestamp("resolved_at"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("pending_actions_order_idx").on(table.mediaOrderId),
+    index("pending_actions_unresolved_idx").on(table.mediaOrderId).where(
+      sql`resolved_at IS NULL`,
+    ),
+  ],
+);
+
+export type PendingAction = typeof pendingActions.$inferSelect;
+
+// ─── Order Version Snapshots ────────────────────────────────────────────────
+
+export const orderVersionSnapshots = pgTable(
+  "order_version_snapshots",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    mediaOrderId: varchar("media_order_id")
+      .notNull()
+      .references(() => mediaOrders.id),
+    version: integer("version").notNull(),
+    amendmentReason: text("amendment_reason"),
+    amendmentNotes: text("amendment_notes"),
+    amendedBy: varchar("amended_by"),
+    snapshot: jsonb("snapshot").notNull().$type<Record<string, unknown>>(),
+    netInvestment: numeric("net_investment", { precision: 12, scale: 2 }),
+    lineItemCount: integer("line_item_count"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("order_version_snapshots_order_version_idx").on(
+      table.mediaOrderId,
+      table.version,
+    ),
+  ],
+);
+
+export type OrderVersionSnapshot = typeof orderVersionSnapshots.$inferSelect;
+
+// ─── User Milestones ────────────────────────────────────────────────────────
+
+export const userMilestones = pgTable(
+  "user_milestones",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: varchar("user_id").notNull(),
+    milestoneKey: text("milestone_key").notNull(),
+    shownAt: timestamp("shown_at").notNull().defaultNow(),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+  },
+  (table) => [
+    index("user_milestones_user_id_idx").on(table.userId),
+    unique("user_milestones_user_key_unique").on(table.userId, table.milestoneKey),
+  ],
+);
+
+export type UserMilestone = typeof userMilestones.$inferSelect;
+
+/** Shape of the ad_activity JSONB column in business_intel_cache */
+export interface BusinessIntelAdActivity {
+  google?: { active: boolean; adCount: number; lastSeen?: string };
+  meta?: { active: boolean; adCount: number; lastSeen?: string };
+}
+
+/** Shape of the seo_snapshot JSONB column in business_intel_cache */
+export interface BusinessIntelSeoSnapshot {
+  organicTraffic?: number;
+  topKeywords?: string[];
+  paidTrafficCost?: number;
+}
+
+/** Shape of the tech_signals JSONB column in business_intel_cache */
+export interface BusinessIntelTechSignals {
+  analytics?: string[];
+  advertising?: string[];
+  crm?: string[];
+  social?: string[];
+}

package/src/types/activity-feed.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared types for the order activity feed — the backbone for all
+ * post-submission visibility (contract alerts, fulfillment status,
+ * creative status, amendments, rate exception resolution).
+ */
+
+export const ACTIVITY_EVENT_TYPES = [
+  "fulfillment_stage_changed",
+  "creative_status_changed",
+  "creative_delivered",
+  "signing_progress",
+  "drawdown_alert",
+  "renewal_reminder",
+  "amendment_submitted",
+  "rate_exception_resolved",
+  "sla_hold_set",
+  "sla_hold_cleared",
+  "sla_milestone_at_risk",
+  "sla_milestone_breached",
+  "sla_evaluated",
+] as const;
+
+export type ActivityEventType = (typeof ACTIVITY_EVENT_TYPES)[number];
+
+export const ACTIVITY_SEVERITIES = [
+  "info",
+  "success",
+  "warning",
+  "action_needed",
+] as const;
+
+export type ActivitySeverity = (typeof ACTIVITY_SEVERITIES)[number];
+
+export const ACTIVITY_SOURCE_SYSTEMS = [
+  "flux",
+  "forge",
+  "hubspot",
+  "compass",
+] as const;
+
+export type ActivitySourceSystem = (typeof ACTIVITY_SOURCE_SYSTEMS)[number];
+
+export const PENDING_ACTION_TYPES = [
+  "creative_revision_needed",
+  "creative_rejected",
+  "fulfillment_blocked",
+  "rate_exception_pending",
+  "sla_hold_active",
+] as const;
+
+export type PendingActionType = (typeof PENDING_ACTION_TYPES)[number];
+
+/** The event envelope fn-flux sends to fn-legacy */
+export interface CompassStatusEvent {
+  schemaVersion: "v1";
+  eventId: string;
+  eventType: string;
+  idempotencyKey: string;
+  emittedAt: string;
+  payload: {
+    mediaOrderId: string;
+    lineItemId?: string | null;
+    hubspotCompanyId?: string | null;
+    title: string;
+    detail?: string | null;
+    severity: ActivitySeverity;
+    status?: string | null;
+    metadata?: Record<string, unknown> | null;
+  };
+}
+
+/** Resolution mapping: which events clear which pending actions */
+export const PENDING_ACTION_RESOLUTION_MAP: Record<
+  PendingActionType,
+  { resolvedByEventType: ActivityEventType; resolvedByStatuses: string[] }
+> = {
+  creative_revision_needed: {
+    resolvedByEventType: "creative_status_changed",
+    resolvedByStatuses: ["approved", "completed"],
+  },
+  creative_rejected: {
+    resolvedByEventType: "creative_status_changed",
+    resolvedByStatuses: ["approved"],
+  },
+  fulfillment_blocked: {
+    resolvedByEventType: "fulfillment_stage_changed",
+    resolvedByStatuses: ["pending_fulfillment", "running", "completed"],
+  },
+  rate_exception_pending: {
+    resolvedByEventType: "rate_exception_resolved",
+    resolvedByStatuses: ["approved", "auto_approved", "rejected"],
+  },
+  sla_hold_active: {
+    resolvedByEventType: "sla_hold_cleared",
+    resolvedByStatuses: ["clear"],
+  },
+};