@growth-labs/cms 0.5.8 → 0.5.10

package/src/schema/insights-ingest.ts

@@ -13,6 +13,69 @@ import { z } from 'zod'
 // replay — run_attempt is the monotonic guard.
 
 // Reusable evidence/brief JSON shapes (stored as TEXT NOT NULL, zod-validated).
+export const InsightLaneSchema = z.enum([
+	'commission',
+	'refresh',
+	'optimize-ctr',
+	'consolidate',
+	'monitor',
+])
+
+export const InsightScoreBreakdownSchema = z.object({
+	actualCtr: z.number().min(0).max(1),
+	expectedCtr: z.number().min(0).max(1),
+	expectedClicksGain: z.number().nonnegative(),
+	laneWeight: z.number().min(0).max(1),
+	score: z.number().nonnegative(),
+	targetPosition: z.number().nonnegative(),
+	topicalFit: z.number().min(0).max(1),
+	winnabilityPrior: z.number().min(0).max(1),
+})
+
+export const InsightJudgeReasonCodeSchema = z.enum([
+	'no_coherent_intent',
+	'navigational_or_entity_locked',
+	'off_topic',
+	'already_covered',
+	'unwinnable',
+	'unsustainable_format',
+	'too_thin',
+	'accept',
+])
+
+export const InsightJudgeVerdictSchema = z.enum(['accept', 'reject', 'abstain'])
+
+export const InsightWinnabilityEvidenceSchema = z.object({
+	verdict: InsightJudgeVerdictSchema,
+	confidence: z.number().min(0).max(1),
+	serp_summary: z.string().min(1),
+})
+
+export const InsightJudgeEvidenceSchema = z.object({
+	verdict: InsightJudgeVerdictSchema,
+	reason_code: InsightJudgeReasonCodeSchema,
+	confidence: z.number().min(0).max(1),
+	intent_statement: z.string().min(1),
+	winnability: InsightWinnabilityEvidenceSchema.optional(),
+})
+
+export const InsightSemanticEvidenceSchema = z.object({
+	topicalFit: z.number().min(0).max(1),
+	disposition: z.enum(['reject', 'judge_only', 'advance']),
+	coverageSimilarity: z.number().min(-1).max(1),
+	coverageAligned: z.boolean(),
+	sharedConcepts: z.number().int().nonnegative(),
+	nearest: z
+		.array(
+			z.object({
+				title: z.string().min(1),
+				slug: z.string().min(1),
+				similarity: z.number().min(-1).max(1),
+			}),
+		)
+		.max(3),
+})
+
 export const InsightEvidenceDemandSchema = z.object({
 	query: z.string().min(1),
 	impressions: z.number().int().nonnegative(),
@@ -20,11 +83,21 @@ export const InsightEvidenceDemandSchema = z.object({
 	ctr: z.number().min(0).max(1),
 	position: z.number().nonnegative(),
 	trend: z.number(),
+	lane: InsightLaneSchema.optional(),
+	coveredBy: z.string().url().nullable().optional(),
+	coverageSource: z.enum(['page_join', 'semantic', 'lexical']).nullable().optional(),
+	scoreBreakdown: InsightScoreBreakdownSchema.optional(),
+	judge: InsightJudgeEvidenceSchema.optional(),
+	semantic: InsightSemanticEvidenceSchema.optional(),
 })
 
 export const InsightEvidenceOpportunitySchema = z.object({
 	basis: z.string().min(1),
 	source_count: z.number().int().nonnegative(),
+	lane: InsightLaneSchema.optional(),
+	scoreBreakdown: InsightScoreBreakdownSchema.optional(),
+	judge: InsightJudgeEvidenceSchema.optional(),
+	semantic: InsightSemanticEvidenceSchema.optional(),
 })
 
 export const InsightEvidenceSchema = z.union([
@@ -55,6 +128,22 @@ export const InsightBriefSchema = z.object({
 			url: z.string().url(),
 		}),
 	),
+	format: z.enum(['cornerstone', 'pillar', 'standalone']).optional(),
+	content_outline: z
+		.array(
+			z.object({
+				question: z.string().min(1),
+				demand: z
+					.object({
+						query: z.string().min(1),
+						impressions: z.number().int().nonnegative(),
+						position: z.number().nonnegative(),
+						trend: z.number(),
+					})
+					.optional(),
+			}),
+		)
+		.optional(),
 	/**
 	 * Which open-web discovery STREAM produced this opportunity row (the theater
 	 * split). REQUIRED here: Zod strips unknown brief keys, so without this field the
@@ -124,3 +213,8 @@ export const InsightsIngestPayloadSchema = z
 export type InsightsIngestPayload = z.infer<typeof InsightsIngestPayloadSchema>
 export type InsightsIngestMeta = z.infer<typeof InsightsIngestMetaSchema>
 export type InsightSuggestionRowPayload = z.infer<typeof InsightSuggestionRowSchema>
+export type InsightLane = z.infer<typeof InsightLaneSchema>
+export type InsightScoreBreakdown = z.infer<typeof InsightScoreBreakdownSchema>
+export type InsightJudgeReasonCode = z.infer<typeof InsightJudgeReasonCodeSchema>
+export type InsightJudgeVerdict = z.infer<typeof InsightJudgeVerdictSchema>
+export type InsightJudgeEvidence = z.infer<typeof InsightJudgeEvidenceSchema>

package/src/schema/migrations.ts

@@ -802,6 +802,15 @@ WHERE operation = 'publish' AND target_published_at IS NULL;
 		sql: `
 CREATE INDEX IF NOT EXISTS idx_content_revisions_published_slug
   ON content_revisions(json_extract(payload_json, '$.item.slug'));
+`,
+	},
+	{
+		id: '0022_content_insight_dismissal_reasons',
+		sql: `
+ALTER TABLE content_insight_dismissals
+  ADD COLUMN reason_code TEXT CHECK (reason_code IS NULL OR reason_code IN ('off_topic', 'already_covered', 'cant_win', 'wrong_format', 'not_now', 'other'));
+ALTER TABLE content_insight_dismissals
+  ADD COLUMN note TEXT CHECK (note IS NULL OR length(note) <= 500);
 `,
 	},
 ]

package/src/schema/types.ts

@@ -9,6 +9,8 @@
 // Nullability: a column declared NOT NULL maps to a required, non-nullable
 // field; a nullable column maps to `T | null` (D1 returns SQL NULL as JS null).
 
+import { z } from 'zod'
+
 /** content_items.type CHECK domain. */
 export type ContentType = 'article' | 'video' | 'podcast' | 'newsletter' | 'page'
 
@@ -417,6 +419,60 @@ export type InsightRunStatus = 'running' | 'completed' | 'partial' | 'failed'
 /** Beat facet — secondary topical facet (geographic theater lives in desk). */
 export type InsightBeat = 'defense' | 'intelligence' | 'diplomacy' | 'analysis'
 
+/** Insight Engine v2 editorial action lane. */
+export type InsightLane = 'commission' | 'refresh' | 'optimize-ctr' | 'consolidate' | 'monitor'
+
+/** Bounded scoring inputs carried with Insight Engine v2 evidence. */
+export interface InsightScoreBreakdown {
+	actualCtr: number
+	expectedCtr: number
+	expectedClicksGain: number
+	laneWeight: number
+	score: number
+	targetPosition: number
+	topicalFit: number
+	winnabilityPrior: number
+}
+
+export type InsightJudgeReasonCode =
+	| 'no_coherent_intent'
+	| 'navigational_or_entity_locked'
+	| 'off_topic'
+	| 'already_covered'
+	| 'unwinnable'
+	| 'unsustainable_format'
+	| 'too_thin'
+	| 'accept'
+
+export type InsightJudgeVerdict = 'accept' | 'reject' | 'abstain'
+
+export interface InsightWinnabilityEvidence {
+	verdict: InsightJudgeVerdict
+	confidence: number
+	serp_summary: string
+}
+
+export interface InsightJudgeEvidence {
+	verdict: InsightJudgeVerdict
+	reason_code: InsightJudgeReasonCode
+	confidence: number
+	intent_statement: string
+	winnability?: InsightWinnabilityEvidence
+}
+
+export interface InsightSemanticEvidence {
+	topicalFit: number
+	disposition: 'reject' | 'judge_only' | 'advance'
+	coverageSimilarity: number
+	coverageAligned: boolean
+	sharedConcepts: number
+	nearest: Array<{
+		title: string
+		slug: string
+		similarity: number
+	}>
+}
+
 /** Demand evidence chip (signal_type='demand'): the real GSC metric. */
 export interface InsightEvidenceDemand {
 	query: string
@@ -428,6 +484,12 @@ export interface InsightEvidenceDemand {
 	position: number
 	/** Impression delta vs the prior window (signed). */
 	trend: number
+	lane?: InsightLane
+	coveredBy?: string | null
+	coverageSource?: 'page_join' | 'semantic' | 'lexical' | null
+	scoreBreakdown?: InsightScoreBreakdown
+	judge?: InsightJudgeEvidence
+	semantic?: InsightSemanticEvidence
 }
 
 /** Opportunity evidence chip (signal_type='opportunity'): validated-research basis. */
@@ -436,6 +498,10 @@ export interface InsightEvidenceOpportunity {
 	basis: string
 	/** Count of cite-or-cut validated sources backing the idea. */
 	source_count: number
+	lane?: InsightLane
+	scoreBreakdown?: InsightScoreBreakdown
+	judge?: InsightJudgeEvidence
+	semantic?: InsightSemanticEvidence
 }
 
 /** content_insights.evidence — JSON stored as TEXT NOT NULL, zod-validated. */
@@ -463,6 +529,16 @@ export interface InsightBrief {
 		spokes: string[]
 	}
 	sources: Array<{ title: string; url: string }>
+	format?: 'cornerstone' | 'pillar' | 'standalone'
+	content_outline?: Array<{
+		question: string
+		demand?: {
+			query: string
+			impressions: number
+			position: number
+			trend: number
+		}
+	}>
 	/**
 	 * Which open-web discovery STREAM produced this opportunity row (the theater
 	 * split): 'competitor' (RSS competitor-watch) vs 'audience_question' (Google
@@ -532,12 +608,28 @@ export interface ContentInsightRunRow {
 	error: string | null
 }
 
+/** Editor-owned dismissal taxonomy (migration 0022). */
+export const InsightDismissalReasonCodeSchema = z.enum([
+	'off_topic',
+	'already_covered',
+	'cant_win',
+	'wrong_format',
+	'not_now',
+	'other',
+])
+
+export type InsightDismissalReasonCode = z.infer<typeof InsightDismissalReasonCodeSchema>
+
 /** A content_insight_dismissals row (PK (site_id, intent_key)). */
 export interface ContentInsightDismissalRow {
 	site_id: string
 	intent_key: string
 	dismissed_at: number
 	dismissed_by: string | null
+	/** NULL is a pre-0022 legacy dismissal. */
+	reason_code: InsightDismissalReasonCode | null
+	/** NULL is either legacy or an editor dismissal without a note. */
+	note: string | null
 }
 
 export type ContentPublicationOperation = 'publish' | 'rollback'