@growth-labs/cms 0.8.19 → 0.8.23

package/src/lib/publish-timezone.ts

@@ -0,0 +1,154 @@
+/**
+ * Publication-timezone helpers — ONE implementation, shared by the schedule
+ * route and the Publish tab.
+ *
+ * Why this module exists: the editor types a wall-clock time and expects the
+ * post to go out at that time in the publication's timezone. That only holds
+ * if the digits the UI DISPLAYS and the zone it SAVES agree. When they
+ * disagreed, every resave shifted `publish_at` by the zone offset — including
+ * an incidental resave that never touched the field (the 2026-09-08 P0). So
+ * display and entry must use the same converter as the server, not a second
+ * copy of the arithmetic.
+ */
+
+/** Fronts default; the server falls back to this when no zone is configured. */
+export const PUBLISH_TIMEZONE_FALLBACK = 'Europe/Paris'
+
+/** `YYYY-MM-DDTHH:MM` exactly — the shape the date and time inputs produce. */
+const LOCAL_DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
+
+type LocalDateTimeParts = { year: number; month: number; day: number; hour: number; minute: number }
+
+export function parseLocalDateTime(value: string): LocalDateTimeParts | null {
+	const match = LOCAL_DATE_TIME_RE.exec(value)
+	if (!match) return null
+	const [, y, m, d, h, min] = match
+	const parts: LocalDateTimeParts = {
+		year: Number.parseInt(y, 10),
+		month: Number.parseInt(m, 10),
+		day: Number.parseInt(d, 10),
+		hour: Number.parseInt(h, 10),
+		minute: Number.parseInt(min, 10),
+	}
+	if (
+		!Number.isInteger(parts.year) ||
+		parts.month < 1 ||
+		parts.month > 12 ||
+		parts.day < 1 ||
+		parts.day > 31 ||
+		parts.hour < 0 ||
+		parts.hour > 23 ||
+		parts.minute < 0 ||
+		parts.minute > 59
+	) {
+		return null
+	}
+	const dateCheck = new Date(Date.UTC(parts.year, parts.month - 1, parts.day))
+	if (
+		dateCheck.getUTCFullYear() !== parts.year ||
+		dateCheck.getUTCMonth() + 1 !== parts.month ||
+		dateCheck.getUTCDate() !== parts.day
+	) {
+		return null
+	}
+	return parts
+}
+
+export function getZonedParts(instantMs: number, timeZone: string): LocalDateTimeParts | null {
+	if (!isValidTimeZone(timeZone)) return null
+	const formatter = new Intl.DateTimeFormat('en-US', {
+		timeZone,
+		hour12: false,
+		year: 'numeric',
+		month: '2-digit',
+		day: '2-digit',
+		hour: '2-digit',
+		minute: '2-digit',
+		second: '2-digit',
+	})
+	const values = { year: '', month: '', day: '', hour: '', minute: '', second: '' }
+	for (const part of formatter.formatToParts(new Date(instantMs))) {
+		if (part.type in values) values[part.type as keyof typeof values] = part.value
+	}
+	const year = Number.parseInt(values.year, 10)
+	const month = Number.parseInt(values.month, 10)
+	const day = Number.parseInt(values.day, 10)
+	const hour = Number.parseInt(values.hour, 10)
+	const minute = Number.parseInt(values.minute, 10)
+	if (![year, month, day, hour, minute].every(Number.isFinite)) return null
+	return { year, month, day, hour, minute }
+}
+
+export function isValidTimeZone(timeZone: string): boolean {
+	try {
+		new Intl.DateTimeFormat('en-US', { timeZone }).format(new Date())
+		return true
+	} catch {
+		return false
+	}
+}
+
+export function getTimeZoneOffsetMs(instantMs: number, timeZone: string): number | null {
+	const zoned = getZonedParts(instantMs, timeZone)
+	if (!zoned) return null
+	const asUtc = Date.UTC(zoned.year, zoned.month - 1, zoned.day, zoned.hour, zoned.minute, 0)
+	return asUtc - instantMs
+}
+
+export function parseLocalDateTimeInZoneToUnixSeconds(
+	value: string,
+	timeZone: string,
+): number | null {
+	const target = parseLocalDateTime(value)
+	if (!target) return null
+	const targetUtcMs = Date.UTC(
+		target.year,
+		target.month - 1,
+		target.day,
+		target.hour,
+		target.minute,
+		0,
+	)
+	let candidateMs = targetUtcMs
+	for (let i = 0; i < 5; i += 1) {
+		const offsetMs = getTimeZoneOffsetMs(candidateMs, timeZone)
+		if (offsetMs === null) return null
+		const next = targetUtcMs - offsetMs
+		if (Math.abs(next - candidateMs) < 1000) {
+			candidateMs = next
+			break
+		}
+		candidateMs = next
+	}
+	const resolved = getZonedParts(candidateMs, timeZone)
+	if (
+		!resolved ||
+		resolved.year !== target.year ||
+		resolved.month !== target.month ||
+		resolved.day !== target.day ||
+		resolved.hour !== target.hour ||
+		resolved.minute !== target.minute
+	) {
+		return null
+	}
+	return Math.floor(candidateMs / 1000)
+}
+
+/**
+ * Inverse of `parseLocalDateTimeInZoneToUnixSeconds`: render an instant as the
+ * wall-clock digits an editor in `timeZone` would read, split for the date and
+ * time inputs. Returns null when the zone is unusable, so callers can fall back
+ * rather than silently display a wrong hour.
+ */
+export function formatInstantInZone(
+	instantMs: number,
+	timeZone: string,
+): { date: string; time: string } | null {
+	const parts = getZonedParts(instantMs, timeZone)
+	if (!parts) return null
+	const pad = (n: number, width = 2) => String(n).padStart(width, '0')
+	return {
+		date: `${pad(parts.year, 4)}-${pad(parts.month)}-${pad(parts.day)}`,
+		time: `${pad(parts.hour)}:${pad(parts.minute)}`,
+	}
+}

package/src/providers/null.ts

@@ -69,6 +69,12 @@ export const nullAnalytics: AnalyticsProvider = {
 			},
 		})
 	},
+	// Podcast listening analytics is a host opt-in: null (not an empty
+	// envelope) so the route 404s and the panel reports "not available"
+	// instead of rendering silent zeros for a site that has none.
+	async getPodcastListening() {
+		return null
+	},
 }
 
 export const nullSubscriptions: SubscriptionsProvider = {

package/src/providers/types.ts

@@ -89,6 +89,51 @@ export interface ArticleAnalyticsDetail {
 	funnel?: ArticleFunnelStages
 }
 
+export interface PodcastListeningEpisode {
+	slug: string
+	title?: string
+	/** Real press-play attempts (user-initiated audio_play; autoplay excluded). */
+	plays: number
+	/** Distinct sessions that played this episode. */
+	listeners: number
+	reached10: number
+	reached25: number
+	reached50: number
+	reached75: number
+	reached90: number
+	completes: number
+	/** completes / plays; 0 when plays is 0. */
+	completionRate: number
+	/**
+	 * Total seconds actually listened. Null means NOT MEASURED — no
+	 * `audio_played` rows exist for this episode in the range — and the UI
+	 * must render "—", never a silent zero.
+	 */
+	totalListeningSeconds: number | null
+	/** totalListeningSeconds / listeners; null when either input is unmeasured. */
+	avgListeningSecondsPerListener: number | null
+}
+
+export interface PodcastListening {
+	episodes: PodcastListeningEpisode[]
+	totals: {
+		/** Episodes with at least one real play in the range. */
+		episodes: number
+		plays: number
+		/**
+		 * Distinct sessions across every episode, deduplicated — never the sum
+		 * of per-episode listeners, which would double-count a session that
+		 * listened to two episodes.
+		 */
+		listeners: number
+		completes: number
+		completionRate: number
+		totalListeningSeconds: number | null
+	}
+	/** Echo of the requested window, ISO 8601 instants. */
+	range: { from: string; to: string }
+}
+
 export interface AnalyticsProvider {
 	getKpis(range: DateRange): Promise<ProviderResult<Record<string, number | null>>>
 	getReadsTimeSeries(range: DateRange): Promise<ProviderResult<Array<{ t: number; reads: number }>>>
@@ -99,6 +144,13 @@ export interface AnalyticsProvider {
 		range: DateRange,
 	): Promise<ProviderResult<Array<{ source: string; sessions: number }>>>
 	getArticleDetail(slug: string, range: DateRange): Promise<ProviderResult<ArticleAnalyticsDetail>>
+	/**
+	 * Per-episode podcast listening analytics. Null means this site has no
+	 * podcast listening analytics at all (the null provider) — the CMS hides
+	 * the panel. A site that implements it but fails to read its source
+	 * throws, so the route surfaces a loud error instead of zeros.
+	 */
+	getPodcastListening(input: { from: string; to: string }): Promise<PodcastListening | null>
 }
 
 export interface SubscriptionMember {

package/src/routes/ai.ts

@@ -23,7 +23,12 @@ import {
 } from '../engine/ai-prompts.js'
 import { applyAiWrite, parseLockedFields } from '../engine/ai-writeback.js'
 import { buildOgCardSpec } from '../engine/og-render.js'
-import { type ContentItemRecord, getContentItem } from '../engine/publisher.js'
+import {
+	type ContentItemRecord,
+	canonicalEditStatement,
+	getContentItem,
+	updateContentItem,
+} from '../engine/publisher.js'
 import type { LlmDispatchResult } from '../providers/types.js'
 import { canPerformContentAction } from './authz-matrix.js'
 import type { CmsRouteConfig } from './config.js'
@@ -207,6 +212,8 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		if (result.status === 'unavailable') {
 			return llmUnavailableResponse({ reason: result.reason }, { dek: null, written: false })
 		}
+		// An editor-triggered dek is a human-initiated canonical change.
+		if (result.written) await canonicalEditStatement(ctx.db, idResult.id).run()
 		return json({
 			dek: result.dek,
 			written: result.written,
@@ -322,16 +329,19 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 
 		if (writeResult.written) {
 			const now = Math.floor(Date.now() / 1000)
-			await ctx.db
-				.prepare(
-					`UPDATE article_content
+			// An editor-triggered write-back is a human-initiated canonical change.
+			await ctx.db.batch([
+				ctx.db
+					.prepare(
+						`UPDATE article_content
 					SET ai_takeaways = ?,
 						ai_takeaways_at = ?,
 						ai_takeaways_model = ?
 					WHERE content_id = ?`,
-				)
-				.bind(JSON.stringify(takeaways), now, 'llm-dispatch', id)
-				.run()
+					)
+					.bind(JSON.stringify(takeaways), now, 'llm-dispatch', id),
+				canonicalEditStatement(ctx.db, id),
+			])
 		}
 
 		return json({
@@ -392,10 +402,9 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		})
 
 		if (writeResult.written) {
-			await ctx.db
-				.prepare('UPDATE content_items SET description = ?, updated_at = unixepoch() WHERE id = ?')
-				.bind(description, id)
-				.run()
+			// Through the editor's own save path, so it is a canonical edit. The
+			// existing category is passed through so the save changes nothing else.
+			await updateContentItem(ctx.db, id, { description, primaryCategory: item.channel })
 		}
 
 		return json({
@@ -478,12 +487,15 @@ export function createAiRoutes(config: CmsRouteConfig): AiRouteHandlers {
 		})
 
 		if (writeResult.written) {
-			await ctx.db
-				.prepare(
-					'UPDATE content_items SET ai_og_image_id = ?, updated_at = unixepoch() WHERE id = ?',
-				)
-				.bind(imageKey, id)
-				.run()
+			// An editor-triggered write-back is a human-initiated canonical change.
+			await ctx.db.batch([
+				ctx.db
+					.prepare(
+						'UPDATE content_items SET ai_og_image_id = ?, updated_at = unixepoch() WHERE id = ?',
+					)
+					.bind(imageKey, id),
+				canonicalEditStatement(ctx.db, id),
+			])
 		}
 
 		return json({

package/src/routes/analytics.ts

@@ -21,6 +21,7 @@ export interface AnalyticsRouteHandlers {
 	topContent(ctx: RouteContext): Promise<Response>
 	trafficSources(ctx: RouteContext): Promise<Response>
 	articleDetail(ctx: RouteContext): Promise<Response>
+	podcastListening(ctx: RouteContext): Promise<Response>
 }
 
 /** Parse ?range=<Nd> from the request URL, defaulting to 30d. */
@@ -74,5 +75,25 @@ export function createAnalyticsRoutes(config: AnalyticsRouteConfig): AnalyticsRo
 			const slug = url.searchParams.get('slug') ?? ''
 			return json(await providers.analytics.getArticleDetail(slug, range))
 		},
+
+		// Podcast listening panel — same publisher gate and ?range=<Nd> window
+		// as the other analytics handlers, but NOT a ProviderResult envelope:
+		// the provider returns null when the site has no podcast listening
+		// analytics at all, which this route answers with a 404 the screen
+		// renders as an explicit "not available" state. A provider that is
+		// implemented but fails throws — the route 500s loudly, never zeros.
+		async podcastListening(ctx: RouteContext): Promise<Response> {
+			const denied = await config.authz.requirePublisher(ctx)
+			if (denied) return denied
+			const range = parseRange(ctx.request.url)
+			const listening = await providers.analytics.getPodcastListening({
+				from: new Date(range.from * 1000).toISOString(),
+				to: new Date(range.to * 1000).toISOString(),
+			})
+			if (!listening) {
+				return json({ error: 'podcast listening analytics is not available' }, 404)
+			}
+			return json(listening)
+		},
 	}
 }

package/src/routes/content.ts

@@ -66,6 +66,12 @@ import { invalidateMediaCaptureStatements, softDeleteContent } from '../engine/s
 import { normalizeSourceSections } from '../engine/source-sections.js'
 import { TagInputError } from '../engine/taxonomy.js'
 import type { ValidationError } from '../engine/validator/index.js'
+import { VideoSourceNotIngestableError } from '../engine/video-source.js'
+import {
+	isValidTimeZone,
+	PUBLISH_TIMEZONE_FALLBACK,
+	parseLocalDateTimeInZoneToUnixSeconds,
+} from '../lib/publish-timezone.js'
 import type { MediaSourceResolution } from '../providers/types.js'
 import { parseLayoutEnvelope } from '../schema/layout.js'
 import { parsePortableTextEnvelope } from '../schema/portable-text.js'
@@ -74,6 +80,8 @@ import { type ContentAction, canPerformContentAction } from './authz-matrix.js'
 import type { CmsRouteConfig } from './config.js'
 import { resolveConfig } from './config.js'
 import { json, type RouteContext, requireId } from './context.js'
+import type { FoundryPublishOptions } from './foundry-publish.js'
+import { isFoundryMachineContext } from './machine-context.js'
 import type { DispatchWebhookHook } from './webhooks.js'
 
 export type { DispatchWebhookHook }
@@ -141,6 +149,11 @@ function mediaSourceProviderErrorResponse(error: unknown): Response | null {
 	return json({ error: failure.message, reason: failure.code }, failure.status)
 }
 
+function videoSourceNotIngestableResponse(error: unknown): Response | null {
+	if (!(error instanceof VideoSourceNotIngestableError)) return null
+	return json({ error: error.message, reason: 'video_source_not_ingestable' }, 400)
+}
+
 function verifiedMediaDurationConflictResponse(error: unknown): Response | null {
 	if (!(error instanceof VerifiedMediaDurationConflictError)) return null
 	return json(
@@ -226,6 +239,14 @@ export interface ContentRouteConfig extends CmsRouteConfig {
 	videoSourceProductionEnabled?: boolean
 	/** Internal machine-route constraint: atomically update only in this status. */
 	updateStatusConstraint?: ContentStatus
+	/**
+	 * Internal (Foundry machine route, M3-18): replaces ONLY the publish action's
+	 * commit step (publishContent + createRevision) with the caller's — publishOne
+	 * with the publication's live surfaces. Every other step of the native publish
+	 * action (readiness, body guard, dek, tag check, activity log, takeaways, FAQ,
+	 * the content.published webhook) runs unchanged, through the same handler.
+	 */
+	publishCommit?: (ctx: RouteContext, input: { contentId: string; now: number }) => Promise<void>
 	/**
 	 * Optional webhook dispatcher hook (P7 Task 9). Fired at each content
 	 * lifecycle transition (publish, unpublish, schedule, archive, create, etc.).
@@ -240,11 +261,23 @@ export interface ContentRouteConfig extends CmsRouteConfig {
 	 * when absent so callers without a workspace concept still produce a scoped row.
 	 */
 	activeWorkspaceId?: string
+	/**
+	 * Per-publication opt-in for the Foundry machine route's publish transition
+	 * (M3-18). Omitted, or `autoPublish` anything but `true`, keeps that route
+	 * draft-only and byte-identical to the v1 route. Read only by routes/foundry-publish.ts.
+	 */
+	foundryPublish?: FoundryPublishOptions
+	/**
+	 * This publication's canonical host for the Foundry route family, declared
+	 * statically (the integration's `foundryCanonicalHost`, so it reaches every
+	 * request whatever the host's per-request hooks set). Once a host is declared
+	 * here or in `foundryPublish.canonicalHost`, the Foundry route verifies only
+	 * the host-bound `foundry-cms-v2` string and never the legacy dot form.
+	 * Read only by routes/foundry-publish.ts.
+	 */
+	foundryCanonicalHost?: string
 }
 
-const PUBLISH_TIMEZONE_FALLBACK = 'Europe/Paris'
-const LOCAL_DATE_TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/
-
 type ContentType = 'article' | 'video' | 'podcast' | 'newsletter' | 'page'
 
 /**
@@ -420,6 +453,8 @@ const NEXTCLOUD_SHARE_HOSTS = ['drive.fulcrum-portal.com']
 const NEXTCLOUD_SHARE_PATH_RE = /^\/s\/([A-Za-z0-9_-]+)(?:\/download)?\/?$/
 const NEXTCLOUD_DIRECT_PATH_RE = /^\/public\.php\/dav\/files\/[A-Za-z0-9_-]+$/
 
+const NEXTCLOUD_SHARE_NOISE_PARAMS: ReadonlySet<string> = new Set(['dir', 'editing', 'openfile'])
+
 export function normaliseNextcloudShareUrl(value: string): string {
 	let url: URL
 	try {
@@ -438,13 +473,19 @@ export function normaliseNextcloudShareUrl(value: string): string {
 	) {
 		return value
 	}
-	const onlyDirQuery =
-		url.search === '' || (url.searchParams.get('dir') !== null && url.searchParams.size === 1)
+	// Nextcloud's copy-link output adds page-navigation noise -- `?dir=/` from a
+	// folder listing, `?dir=/&editing=false&openfile=true` from the viewer --
+	// none of which changes the file a share serves. Any other parameter may
+	// select a different resource, so the URL is kept and the publisher's
+	// ingest guard refuses it (HomeFronts 2026-10-01T18:05Z).
+	const onlyNoiseQuery =
+		url.search === '' ||
+		[...url.searchParams.keys()].every((key) => NEXTCLOUD_SHARE_NOISE_PARAMS.has(key))
 	if (NEXTCLOUD_DIRECT_PATH_RE.test(url.pathname)) {
-		return url.search === '' ? value : onlyDirQuery ? `https://${host}${url.pathname}` : value
+		return url.search === '' ? value : onlyNoiseQuery ? `https://${host}${url.pathname}` : value
 	}
 	const share = NEXTCLOUD_SHARE_PATH_RE.exec(url.pathname)
-	if (!share || !onlyDirQuery) return value
+	if (!share || !onlyNoiseQuery) return value
 	return `https://${host}/public.php/dav/files/${share[1]}`
 }
 
@@ -677,119 +718,6 @@ const ContributorsReplaceSchema = z.object({
 
 // --- timezone-aware local-datetime parsing (ported verbatim) --------------
 
-type LocalDateTimeParts = { year: number; month: number; day: number; hour: number; minute: number }
-
-function parseLocalDateTime(value: string): LocalDateTimeParts | null {
-	const match = LOCAL_DATE_TIME_RE.exec(value)
-	if (!match) return null
-	const [, y, m, d, h, min] = match
-	const parts: LocalDateTimeParts = {
-		year: Number.parseInt(y, 10),
-		month: Number.parseInt(m, 10),
-		day: Number.parseInt(d, 10),
-		hour: Number.parseInt(h, 10),
-		minute: Number.parseInt(min, 10),
-	}
-	if (
-		!Number.isInteger(parts.year) ||
-		parts.month < 1 ||
-		parts.month > 12 ||
-		parts.day < 1 ||
-		parts.day > 31 ||
-		parts.hour < 0 ||
-		parts.hour > 23 ||
-		parts.minute < 0 ||
-		parts.minute > 59
-	) {
-		return null
-	}
-	const dateCheck = new Date(Date.UTC(parts.year, parts.month - 1, parts.day))
-	if (
-		dateCheck.getUTCFullYear() !== parts.year ||
-		dateCheck.getUTCMonth() + 1 !== parts.month ||
-		dateCheck.getUTCDate() !== parts.day
-	) {
-		return null
-	}
-	return parts
-}
-
-function getZonedParts(instantMs: number, timeZone: string): LocalDateTimeParts | null {
-	const formatter = new Intl.DateTimeFormat('en-US', {
-		timeZone,
-		hour12: false,
-		year: 'numeric',
-		month: '2-digit',
-		day: '2-digit',
-		hour: '2-digit',
-		minute: '2-digit',
-		second: '2-digit',
-	})
-	const values = { year: '', month: '', day: '', hour: '', minute: '', second: '' }
-	for (const part of formatter.formatToParts(new Date(instantMs))) {
-		if (part.type in values) values[part.type as keyof typeof values] = part.value
-	}
-	const year = Number.parseInt(values.year, 10)
-	const month = Number.parseInt(values.month, 10)
-	const day = Number.parseInt(values.day, 10)
-	const hour = Number.parseInt(values.hour, 10)
-	const minute = Number.parseInt(values.minute, 10)
-	if (![year, month, day, hour, minute].every(Number.isFinite)) return null
-	return { year, month, day, hour, minute }
-}
-
-function isValidTimeZone(timeZone: string): boolean {
-	try {
-		new Intl.DateTimeFormat('en-US', { timeZone }).format(new Date())
-		return true
-	} catch {
-		return false
-	}
-}
-
-function getTimeZoneOffsetMs(instantMs: number, timeZone: string): number | null {
-	const zoned = getZonedParts(instantMs, timeZone)
-	if (!zoned) return null
-	const asUtc = Date.UTC(zoned.year, zoned.month - 1, zoned.day, zoned.hour, zoned.minute, 0)
-	return asUtc - instantMs
-}
-
-function parseLocalDateTimeInZoneToUnixSeconds(value: string, timeZone: string): number | null {
-	const target = parseLocalDateTime(value)
-	if (!target) return null
-	const targetUtcMs = Date.UTC(
-		target.year,
-		target.month - 1,
-		target.day,
-		target.hour,
-		target.minute,
-		0,
-	)
-	let candidateMs = targetUtcMs
-	for (let i = 0; i < 5; i += 1) {
-		const offsetMs = getTimeZoneOffsetMs(candidateMs, timeZone)
-		if (offsetMs === null) return null
-		const next = targetUtcMs - offsetMs
-		if (Math.abs(next - candidateMs) < 1000) {
-			candidateMs = next
-			break
-		}
-		candidateMs = next
-	}
-	const resolved = getZonedParts(candidateMs, timeZone)
-	if (
-		!resolved ||
-		resolved.year !== target.year ||
-		resolved.month !== target.month ||
-		resolved.day !== target.day ||
-		resolved.hour !== target.hour ||
-		resolved.minute !== target.minute
-	) {
-		return null
-	}
-	return Math.floor(candidateMs / 1000)
-}
-
 // --- read-side payload helpers (ported verbatim) --------------------------
 
 async function getContentPayload(ctx: RouteContext, type: string, id: string) {
@@ -1293,6 +1221,15 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 	 * — identical guard pattern to dispatchTakeaways / logActivity.
 	 * When no hook is injected this is a no-op (no 501, no error).
 	 */
+	/**
+	 * Only a context the HMAC-verified Foundry route marked is the machine
+	 * (routes/machine-context.ts); a subject or userId string never decides it,
+	 * so no person can act as the machine. Any other actor is a person.
+	 */
+	async function isFoundryActor(ctx: RouteContext): Promise<boolean> {
+		return isFoundryMachineContext(ctx)
+	}
+
 	async function fireWebhook(
 		ctx: RouteContext,
 		eventType: string,
@@ -1536,12 +1473,14 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (op === 'topic') {
 				const { topic } = parsed.data
 				for (const id of ids) {
-					await ctx.db
-						.prepare(
-							'UPDATE content_items SET primary_topic = ?, updated_at = unixepoch() WHERE id = ? AND deleted_at IS NULL',
-						)
-						.bind(topic, id)
-						.run()
+					// Through the editor's own save path, so it is a canonical edit; the
+					// existing category is passed through so the save changes nothing else.
+					const existing = await getContentItem(ctx.db, id)
+					if (!existing || (existing as { deleted_at?: number | null }).deleted_at != null) continue
+					await updateContentItem(ctx.db, id, {
+						primaryTopic: topic,
+						primaryCategory: existing.channel,
+					})
 				}
 				return json({ updated: ids })
 			}
@@ -1643,6 +1582,8 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				created = await createContent(ctx.db, parsed.data)
 			} catch (error) {
 				if (error instanceof TagInputError) return tagInputErrorResponse(error)
+				const notIngestable = videoSourceNotIngestableResponse(error)
+				if (notIngestable) return notIngestable
 				const conflict = verifiedMediaDurationConflictResponse(error)
 				if (conflict) return conflict
 				throw error
@@ -1889,6 +1830,8 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				})
 			} catch (error) {
 				if (error instanceof TagInputError) return tagInputErrorResponse(error)
+				const notIngestable = videoSourceNotIngestableResponse(error)
+				if (notIngestable) return notIngestable
 				const conflict = verifiedMediaDurationConflictResponse(error)
 				if (conflict) return conflict
 				throw error
@@ -2145,8 +2088,12 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 					throw error
 				}
 				try {
-					await publishContent(ctx.db, id, publishedAt, now)
-					await createRevision(ctx.db, id, ctx.userId || null)
+					if (config.publishCommit) {
+						await config.publishCommit(ctx, { contentId: id, now })
+					} else {
+						await publishContent(ctx.db, id, publishedAt, now)
+						await createRevision(ctx.db, id, ctx.userId || null)
+					}
 				} catch (error) {
 					if (error instanceof TagInputError) return tagInputErrorResponse(error)
 					throw error
@@ -2238,7 +2185,10 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			}
 
 			if (action === 'unpublish') {
-				await unpublishContent(ctx.db, id)
+				// A person's unpublish sticks: it is a canonical edit, so a machine
+				// publisher cannot put the item back without a new write. The
+				// machine's own unpublish is not, so it can republish its item.
+				await unpublishContent(ctx.db, id, { canonicalEdit: !(await isFoundryActor(ctx)) })
 
 				// Fire content.unpublished webhook.
 				await fireWebhook(ctx, 'content.unpublished', {
@@ -2274,9 +2224,11 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 			if (action === 'unschedule') {
 				// publish_tz is NOT NULL (DEFAULT 'Europe/Paris'); reset it to the
 				// default rather than nulling it (a NULL violates the constraint).
+				// A person pulling a scheduled item is a canonical edit (see unpublish).
+				const pulledByPerson = !(await isFoundryActor(ctx))
 				await ctx.db
 					.prepare(
-						"UPDATE content_items SET status = 'draft', publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch() WHERE id = ?",
+						`UPDATE content_items SET status = 'draft', publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch()${pulledByPerson ? ', canonical_version = canonical_version + 1' : ''} WHERE id = ?`,
 					)
 					.bind(id)
 					.run()
@@ -2315,9 +2267,12 @@ export function createContentRoutes(config: ContentRouteConfig): ContentRouteHan
 				// publish_at so a de-scheduled item doesn't carry a phantom publish time.
 				// publish_tz is NOT NULL (DEFAULT 'Europe/Paris'), so it is reset to the
 				// default rather than nulled.
+				// A person moving the item back to draft or review is a canonical
+				// edit (see unpublish); the machine never calls set-status.
+				const movedByPerson = !(await isFoundryActor(ctx))
 				await ctx.db
 					.prepare(
-						"UPDATE content_items SET status = ?, publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch() WHERE id = ?",
+						`UPDATE content_items SET status = ?, publish_at = NULL, publish_tz = 'Europe/Paris', updated_at = unixepoch()${movedByPerson ? ', canonical_version = canonical_version + 1' : ''} WHERE id = ?`,
 					)
 					.bind(status, id)
 					.run()