@growth-labs/cms 0.8.20 → 0.8.24

package/docs/foundry-publish.md

@@ -64,6 +64,214 @@ GET returns HTTP 404 with `{ "error": "not_found" }` when the external id is abs
 
 POST has no request body. It moves an item back to `draft` through the native CMS lifecycle handler and returns the same four-field receipt shape. Repeating the request while already draft is idempotent.
 
+## v2 body, `POST /publish` and adoption (opt-in, per publication)
+
+Draft-only is the default and stays byte-identical to the v1 contract above. A
+publication opts in through the route's config, which the Astro adapter reads
+from `locals.cmsHooks.foundryPublish`:
+
+```ts
+locals.cmsHooks = {
+  ...locals.cmsHooks,
+  foundryPublish: {
+    autoPublish: true, // only the literal `true` opts in
+    canonicalHost: 'warfronts.pub', // REQUIRED when opted in: lowercase, no scheme, no port
+    surfaces: (ctx) => [sitemapSurface, feedSurface, markdownTwinSurface], // the LIVE surfaces
+    requiredSurfaceNames: ['seo-discovery'], // optional, forwarded to publishOne
+    bridgeSourceNamespace: 'warfronts', // the archive bridge's source_id namespace (adoption)
+    scheduling: 'publishOne', // only if the site's scheduler projects through publishOne
+  },
+}
+```
+
+With the flag off (omitted, `false`, or anything but `true`):
+
+- every existing request takes the v1 path, byte-for-byte;
+- a body carrying `schemaVersion: 2` is refused as today (`400 invalid_request`);
+- `POST .../publish` returns `409 published_requires_approval` (404 for an unknown id).
+
+With the flag on, v1 bodies still take the v1 path unchanged. Only a body
+declaring `"schemaVersion": 2` takes the v2 path.
+
+### Host-bound signatures on opted-in publications
+
+The Foundry HMAC secret is one value shared by every site. An opted-in
+publication therefore verifies every `/api/cms/foundry/*` verb (PUT, GET,
+publish, unpublish) against a host-bound string, newline-joined, with no
+trailing newline:
+
+```text
+foundry-cms-v2
+METHOD
+HOST
+PATH
+TIMESTAMP
+sha256hex(raw_body)
+```
+
+- `HOST` is the configured `foundryPublish.canonicalHost`, never the request's
+  Host header. A request signed for another site, the legacy dot form, or a
+  dot-joined host-bound string is `401`.
+- An opted-in publication without a valid `canonicalHost` answers
+  `503 GL_CMS_FOUNDRY_HOST_UNCONFIGURED` on every verb; it never falls back to
+  the unbound form.
+- Publications that do not opt in keep the legacy `method.path.timestamp.sha256`
+  string described above, byte-for-byte.
+- Foundry's signer is `SignPublishRequestV2` (fulcrum-labs/foundry
+  `articlechain`). This route verifies with `@growth-labs/foundry-signing`, the
+  one shared implementation, whose golden vectors (`/fixtures`) the route tests
+  import.
+
+### v2 PUT
+
+```json
+{
+  "schemaVersion": 2,
+  "slug": "exact-canonical-slug",
+  "title": "Article title",
+  "body_html": "<p>Complete article HTML.</p>",
+  "hero_image_key": "articles/<id>/hero.jpg",
+  "publishAt": "2026-10-01T09:00:00Z",
+  "author": "Byline",
+  "desk": "analysis",
+  "tags": ["drones"],
+  "description": "The dek.",
+  "visibility": "free",
+  "adoptSourceId": "warfronts:articles/military/<file>.md"
+}
+```
+
+The schema is strict and exported as `FoundryArticleV2Schema` from
+`@growth-labs/cms/foundry-emit`.
+
+- `slug`, `title` and `body_html` are required.
+- `slug` is used verbatim and must already be canonical (`slugify(slug) === slug`,
+  3–512 characters). It is never derived and never suffixed: a slug held by
+  another item is `409 slug_conflict`.
+- `hero_image_key` (a relative object key, stored as `hero_image_id` exactly as the
+  bridge import stores it) and `hero_image_url` (https) are mutually exclusive.
+- `description` fills `description` and `excerpt`, `author` fills `byline`, and
+  `desk` fills the primary category.
+- `publishAt` is carried on the draft (`publish_at`) for `POST /publish` to act on.
+
+A v2 PUT never publishes. It writes a draft, or, on an opted-in publication, edits
+a **published** item in place. That write is a CAS on `status = 'published'`, and
+the live revision does not move until `POST /publish` resyncs it. Scheduled,
+review and archived items stay human-owned: a changed PUT is
+`409 published_requires_approval`.
+
+Every v2 PUT, publish and GET response is the four-field receipt plus
+`request_sha256`: the lowercase hex SHA-256 of the exact bytes of the last
+accepted v2 PUT body, the value the route stores. An identical repeat PUT returns
+the existing receipt.
+
+### `POST /api/cms/foundry/articles/:external_id/publish`
+
+HMAC-signed like the others, with an empty body. It returns the receipt (plus
+`request_sha256`).
+
+- **Draft** with `publish_at` in the future: scheduled through the native schedule
+  action (`state: "scheduled"`), but only when the publication declares
+  `foundryPublish.scheduling: 'publishOne'`, meaning its scheduler publishes
+  scheduled items through `publishOne` with the live surfaces. Otherwise the
+  request is refused with `409 scheduling_requires_surface_scheduler`: the legacy
+  scheduled sweep (`engine/cron.ts` `runScheduledPublish`) publishes with no
+  surfaces, and that gap must surface at the request, not after the fact.
+- **Draft**, otherwise: published through `publishOne` with the publication's live
+  surfaces, so the `.md` twin, sitemap and feed are projected. The publication
+  time is the draft's `publishAt`, else now.
+- **Every** publish, schedule or resync acts on the working copy only while it is
+  still exactly what Foundry's last v2 PUT wrote; this applies to drafts and to
+  published items alike.
+- **Published** item whose working copy changed since its live revision: re-runs
+  `publishOne` (the resync), keeping the original publication time. The guard:
+  every v2 PUT records a History revision (`created_by: foundry`, tag
+  `foundry.put:<request_sha256>`), and the item's `canonical_version` must still
+  equal that revision's. A human edit since then is `409 human_edit_pending`,
+  with nothing written, until Foundry sends a new PUT or a human publishes.
+  Human-initiated writes outside the editor form (editor-triggered AI meta
+  description, dek, takeaways and OG image, the bulk topic op, and a topic rename)
+  advance `canonical_version` as an editor save does. The automatic enrichment a
+  publish triggers (the pre-commit dek, takeaways, FAQ and host enrichment) does
+  not. A person pulling an item (native unpublish, unschedule, or set-status to
+  draft or review) is a canonical edit too, so Foundry never republishes an
+  article a person pulled until it sends a new PUT. Foundry's own `/unpublish`
+  is not, so Foundry can unpublish and republish its own item. "Foundry's own" is
+  decided by an internal marker the HMAC-verified route sets on the contexts it
+  builds, never by a subject or user id. Tag rename and delete are canonical
+  edits to every tagged item too.
+- `POST /publish` takes no body: any body bytes, or a non-zero `Content-Length`,
+  is `400 invalid_request`.
+- Idempotent: a published item whose live revision is current, or a scheduled
+  item, returns its existing receipt.
+- The route never passes `allowNoSurfaces`. Absent, empty or failing surfaces
+  refuse with `503 GL_CMS_FOUNDRY_PUBLISH_UNCONFIGURED` before anything is written.
+- The publish runs the **native publish action itself**. Only its commit step is
+  swapped, from `publishContent` + `createRevision` to `publishOne` with the live
+  surfaces, through the internal `publishCommit` seam. So the readiness hook, the
+  body guard, dek generation (or the dek-failure notification), the tag check, the
+  activity log, takeaways and FAQ dispatch (first publish only), and the
+  `content.published` webhook run exactly as for an editor's publish, and its
+  refusals keep the native shapes.
+- An exception thrown inside the publication is `502 publish_failed` (or `422
+  publish_validation_failed` from the kernel's own guard). It leaves the item and
+  its receipt unchanged, so a retry re-runs it.
+- `unpublish` remains the undo.
+
+### One-time adoption of bridge-imported items
+
+When no item is bound to `foundry:<external_id>` yet, a v2 PUT first looks for an
+existing item:
+
+- by exact `source_id` when the body carries `adoptSourceId`;
+- otherwise by the verbatim slug.
+
+Only a bridge-imported article that no external id owns can be adopted, and
+only under the publication's declared bridge namespace
+(`foundryPublish.bridgeSourceNamespace`, so `source_id` = `<namespace>:<relpath>`,
+as a channel repo's `scripts/archive-import/compiler.mjs` `buildSourceId` writes
+it). Any other source is `409 adoption_source_not_bridge`; with no namespace
+declared, nothing is adoptable. Exactly one match is bound to `foundry:<external_id>` in one
+D1 transaction together with a `foundry.adopted` row in `cms_activity_log`, and
+the receipt carries an `adoption` object (`content_id`, `from_source_id`,
+`matched_by`). A draft or published match is then written as above. A scheduled,
+review or archived match is bound and answered with
+`409 published_requires_approval` plus the `adoption` object.
+
+| Response | When |
+| --- | --- |
+| `409 adoption_ambiguous` | `adoptSourceId` and the slug name two different items |
+| `409 adoption_conflict` | the match is deleted, not an article, already bound to another external id, not bridge-imported, or the bind lost a race |
+| `409 slug_conflict` | the slug is held by an item the request did not identify |
+
+### content-emit.json (`foundry-emit` bin)
+
+`foundry-emit --app <id> --source-sha <sha> --out <file> [--in <archive.json>]`
+reads an app compiler's ContentArchiveInput (`{ items }`, or compileArchive's
+`{ archive, receipt }`) from `--in` or stdin. It writes:
+
+```json
+{ "schemaVersion": 1, "app": "warfronts", "sourceSha": "<sha>",
+  "items": [
+    { "path": "articles/x.md", "videoId": "abc", "retire": false,
+      "requestSha256": "<hex>", "request": "{\"schemaVersion\":2,...}" },
+    { "path": "articles/old.md", "videoId": "def", "retire": true }
+  ] }
+```
+
+- It covers the whole archive; any item that cannot be emitted fails the run.
+- `retire` is the compiler's carry of frontmatter `status: archived`. A retire item
+  omits `request` and `requestSha256`.
+- `request` is a JSON **string**, the exact PUT body, so re-indenting the envelope
+  never changes its bytes.
+- `requestSha256` is the SHA-256 of its UTF-8 bytes. When foundryd PUTs exactly
+  those bytes, the route stores and echoes the same value as `request_sha256`.
+
+The mapper is exported as `toFoundryArticleV2(item)`, and the envelope builder as
+`buildContentEmit(archive, { app, sourceSha })`.
+
+No migration is needed for v2.
+
 ## Cloudflare binding
 
 ```toml

package/migrations/0033_survey_answer_labels.sql

@@ -0,0 +1,15 @@
+-- Owner-side classification of written survey answers (2026-10-02). Only the
+-- CMS owner ever sees an answer that is not labeled 'general': technical and
+-- unlabeled comments are withheld from every other role by the survey routes.
+-- No FK to a survey table: surveys live in the reporting upstream, so the key
+-- references provider-issued ids only.
+CREATE TABLE survey_answer_labels (
+  survey_id TEXT NOT NULL,
+  response_id TEXT NOT NULL,
+  question_id TEXT NOT NULL,
+  label TEXT NOT NULL CHECK (label IN ('technical','general')),
+  source TEXT NOT NULL CHECK (source IN ('owner','auto','import')),
+  labeled_by TEXT,
+  labeled_at INTEGER NOT NULL,
+  PRIMARY KEY (survey_id, response_id, question_id)
+);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@growth-labs/cms",
-  "version": "0.8.20",
+  "version": "0.8.24",
   "type": "module",
   "bin": {
-    "growth-labs-cms-migrations": "./dist/cli/migrations.js"
+    "growth-labs-cms-migrations": "./dist/cli/migrations.js",
+    "foundry-emit": "./dist/cli/foundry-emit.js"
   },
   "types": "./dist/index.d.ts",
   "exports": {
@@ -31,6 +32,10 @@
       "types": "./dist/integration/index.d.ts",
       "import": "./dist/integration/index.js"
     },
+    "./foundry-emit": {
+      "types": "./dist/foundry-emit.d.ts",
+      "import": "./dist/foundry-emit.js"
+    },
     "./migration-vendor": {
       "types": "./dist/migration-vendor.d.ts",
       "import": "./dist/migration-vendor.js"
@@ -128,7 +133,8 @@
     "@tiptap/suggestion": "3.30.5",
     "@tiptap/y-tiptap": "^3.0.9",
     "yjs": "^13.6.32",
-    "zod": "^3.24.0"
+    "zod": "^3.24.0",
+    "@growth-labs/foundry-signing": "^0.1.0"
   },
   "devDependencies": {
     "@puckeditor/core": "0.23.0",

package/src/cli/foundry-emit.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// foundry-emit --app <id> --source-sha <sha> --out <file> [--in <archive.json>]
+//
+// Reads an app compiler's ContentArchiveInput (`{ items }`, or compileArchive's
+// `{ archive, receipt }`) from --in or stdin and writes content-emit.json: the
+// whole archive as the exact v2 PUT bodies foundryd sends (see
+// buildContentEmit in ../foundry-emit.ts).
+import { readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import type { ContentArchiveInput } from '../engine/publication.js'
+import { buildContentEmit, type ContentEmit } from '../foundry-emit.js'
+
+const USAGE = 'Usage: foundry-emit --app <id> --source-sha <sha> --out <file> [--in <archive.json>]'
+
+interface EmitArgs {
+	app: string
+	sourceSha: string
+	out: string
+	in?: string
+}
+
+export function parseEmitArgs(argv: string[]): EmitArgs {
+	const values: Record<string, string> = {}
+	for (let index = 0; index < argv.length; index += 2) {
+		const flag = argv[index]
+		const value = argv[index + 1]
+		if (!['--app', '--source-sha', '--out', '--in'].includes(flag ?? '')) {
+			throw new Error(`unknown argument ${flag}\n${USAGE}`)
+		}
+		if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value\n${USAGE}`)
+		values[(flag as string).slice(2)] = value
+	}
+	for (const required of ['app', 'source-sha', 'out']) {
+		if (!values[required]) throw new Error(`--${required} is required\n${USAGE}`)
+	}
+	return {
+		app: values.app as string,
+		sourceSha: values['source-sha'] as string,
+		out: values.out as string,
+		...(values.in ? { in: values.in } : {}),
+	}
+}
+
+function archiveFrom(raw: string): ContentArchiveInput {
+	const parsed = JSON.parse(raw) as { items?: unknown; archive?: { items?: unknown } }
+	if (Array.isArray(parsed.items)) return parsed as ContentArchiveInput
+	if (parsed.archive && Array.isArray(parsed.archive.items)) {
+		return parsed.archive as ContentArchiveInput
+	}
+	throw new Error('input is not a ContentArchiveInput: no items array')
+}
+
+export async function runFoundryEmit(
+	argv: string[],
+	io: { readStdin: () => string } = { readStdin: () => readFileSync(0, 'utf8') },
+): Promise<ContentEmit> {
+	const args = parseEmitArgs(argv)
+	const raw = args.in ? readFileSync(args.in, 'utf8') : io.readStdin()
+	const emit = await buildContentEmit(archiveFrom(raw), {
+		app: args.app,
+		sourceSha: args.sourceSha,
+	})
+	// Written whole or not at all: a reader never sees a truncated emit.
+	const temporary = `${args.out}.tmp-${process.pid}`
+	writeFileSync(temporary, `${JSON.stringify(emit, null, 2)}\n`)
+	renameSync(temporary, args.out)
+	return emit
+}
+
+// An installed bin runs through a node_modules/.bin symlink, so compare real paths.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+	runFoundryEmit(process.argv.slice(2))
+		.then((emit) => {
+			const retired = emit.items.filter((item) => item.retire).length
+			console.log(
+				`foundry-emit: wrote ${emit.items.length} items (${retired} retire) for ${emit.app}@${emit.sourceSha}`,
+			)
+		})
+		.catch((error: unknown) => {
+			process.stderr.write(
+				`foundry-emit: ${error instanceof Error ? error.message : String(error)}\n`,
+			)
+			process.exitCode = 1
+		})
+}

package/src/engine/foundry-dispatch.ts

@@ -65,7 +65,7 @@ export interface CallbackInput {
 	excerpt?: string | null
 }
 
-async function sha256Hex(value: string): Promise<string> {
+export async function sha256Hex(value: string): Promise<string> {
 	const bytes = new TextEncoder().encode(value)
 	const digest = await crypto.subtle.digest('SHA-256', bytes)
 	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('')

package/src/engine/fronts-publish-intent.ts

@@ -47,7 +47,11 @@ import {
 	podcastPublishBlocker,
 	validPodcastSourceUrl,
 } from './podcast-source.js'
-import { frontsVideoSourceGeneration, videoSourceIngestableOverHttps } from './video-source.js'
+import {
+	frontsVideoSourceGeneration,
+	videoSourceIngestableOverHttps,
+	videoSourceUrlIngestableOverHttps,
+} from './video-source.js'
 
 /** The CMS's own name for the record this intent describes. */
 export const FRONTS_PUBLISH_INTENT_SOURCE = 'masthead'
@@ -71,6 +75,7 @@ export type FrontsPublishIntentErrorCode =
 	| 'missing_article_body'
 	| 'video_media_not_ready'
 	| 'video_source_duration_unavailable'
+	| 'video_source_not_ingestable'
 	| 'missing_podcast_audio'
 	| PodcastPublishBlockerCode
 
@@ -779,6 +784,23 @@ async function videoSourceRef(
 		!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(correlation)
 	)
 		return null
+	// A URL with a query, fragment, userinfo or non-https scheme passes
+	// validPodcastSourceUrl above but is refused by Foundry's media probe
+	// ("artifact ingest probe source URL is invalid"), which fails without
+	// telling the CMS — the HomeFronts 2026-10-01T18:05Z incident, where the
+	// video sat scheduled-but-never-prepared with no incomplete entry. Raise
+	// it loudly here instead of handing the URL to Foundry; consumers catch
+	// this per item, so the feed's other items are unaffected.
+	if (
+		found.processing_source_kind === 'http_url' &&
+		!videoSourceUrlIngestableOverHttps(found.processing_source_url)
+	) {
+		throw new FrontsPublishIntentError(
+			'video_source_not_ingestable',
+			row.id,
+			'Video source URL is not a plain HTTPS URL Foundry can ingest (no query string or fragment); re-capture the source with its direct /download link.',
+		)
+	}
 	if (
 		typeof found.duration_seconds !== 'number' ||
 		!Number.isFinite(found.duration_seconds) ||

package/src/engine/index.ts

@@ -213,6 +213,11 @@ export {
 	isRetiredItem,
 	payloadDrift,
 } from './publication-continuity.js'
+// Trusted media producers use the same capture proof as the CMS dispatch path.
+export {
+	MEDIA_PUBLICATION_ITEM_FIELDS,
+	mediaPublicationCaptureGuard,
+} from './publication-current-guard.js'
 export {
 	CanonicalJsonError,
 	canonicalJson,

package/src/engine/publisher.ts

@@ -30,6 +30,7 @@ import {
 	validateDeclaredTagList,
 	validateStoredTaxonomyRows,
 } from './taxonomy.js'
+import { VideoSourceNotIngestableError, videoSourceUrlIngestableOverHttps } from './video-source.js'
 
 export {
 	MAX_ITEM_TAG_COUNT,
@@ -625,6 +626,20 @@ export async function createContent(
 	db: D1Database,
 	input: CreateContentInput,
 ): Promise<{ id: string; slug: string }> {
+	// Refuse before the provider probe or any row write: an http_url source
+	// with a query, fragment, userinfo or non-https scheme can never pass
+	// Foundry's media probe, so storing it strands a scheduled video (the
+	// HomeFronts 2026-10-01T18:05Z incident). Dropbox links legitimately
+	// carry `?dl=1` and stay out of this check.
+	if (
+		input.type === 'video' &&
+		input.content.processingSourceUrl !== undefined &&
+		input.content.processingSourceUrl !== null &&
+		(input.content.processingSourceKind ?? 'http_url') === 'http_url' &&
+		!videoSourceUrlIngestableOverHttps(input.content.processingSourceUrl)
+	) {
+		throw new VideoSourceNotIngestableError()
+	}
 	const resolvedMediaDuration =
 		input.type === 'video'
 			? await resolveMediaDuration(
@@ -775,6 +790,21 @@ export async function getContentItem(
 		.first<ContentItemRecord>()
 }
 
+/**
+ * A human-initiated canonical change written outside updateContentItem (an
+ * editor-triggered AI write-back to a field updateContentItem does not carry):
+ * advances canonical_version exactly as updateContentItem's own UPDATE does.
+ * canonical_version is how the Foundry machine route knows the working copy is
+ * no longer only what its last PUT wrote (M3-18 resync guard).
+ */
+export function canonicalEditStatement(db: D1Database, contentId: string) {
+	return db
+		.prepare(
+			'UPDATE content_items SET canonical_version = canonical_version + 1, updated_at = unixepoch() WHERE id = ?',
+		)
+		.bind(contentId)
+}
+
 export async function updateContentItem(
 	db: D1Database,
 	id: string,
@@ -823,6 +853,16 @@ export async function updateContentItem(
 			const sourceKind = hasOwn(videoContent, 'processingSourceKind')
 				? (videoContent.processingSourceKind ?? null)
 				: current.processing_source_kind
+			// Same refusal as createContent, against the merged (input-or-stored)
+			// source: a row that already holds a query-bearing link is corrected
+			// at the next save, while the editor is still there to re-capture it.
+			if (
+				sourceUrl !== null &&
+				(sourceKind ?? 'http_url') === 'http_url' &&
+				!videoSourceUrlIngestableOverHttps(sourceUrl)
+			) {
+				throw new VideoSourceNotIngestableError()
+			}
 			const sourceChanged =
 				sourceUrl !== current.processing_source_url || sourceKind !== current.processing_source_kind
 			const durationProvided = hasOwn(videoContent, 'durationSeconds')
@@ -997,8 +1037,8 @@ export async function updateContentItem(
 		: existing.metadata_json
 
 	if (options.requiredStatus) {
-		if (input.tags !== undefined || input.relations !== undefined) {
-			throw new TypeError('Status-constrained updates do not support tags or relations')
+		if (input.relations !== undefined) {
+			throw new TypeError('Status-constrained updates do not support relations')
 		}
 		if (!isBodyBackedContentType(existing.type)) {
 			throw new TypeError('Status-constrained updates require body-backed content')
@@ -1131,6 +1171,31 @@ export async function updateContentItem(
 			)
 		}
 
+		if (tagPairs) {
+			// Tag links join the same transaction under the same status predicate,
+			// so a refused (non-matching status) update leaves the links untouched.
+			// Tag dictionary rows are shared and idempotent, so they may be ensured
+			// up front even when the guarded write below is refused.
+			const tagRows = tagPairs.length > 0 ? await ensureTags(db, tagPairs) : []
+			const statusGuard = `EXISTS (SELECT 1 FROM content_items
+			   WHERE id = ? AND status = ? AND deleted_at IS NULL)`
+			statements.push(
+				db
+					.prepare(`DELETE FROM content_tag_links WHERE content_id = ? AND ${statusGuard}`)
+					.bind(id, id, options.requiredStatus),
+			)
+			for (const tag of tagRows) {
+				statements.push(
+					db
+						.prepare(
+							`INSERT INTO content_tag_links (content_id, tag_id, label)
+							 SELECT ?, ?, ? WHERE ${statusGuard}`,
+						)
+						.bind(id, tag.id, tag.label, id, options.requiredStatus),
+				)
+			}
+		}
+
 		const statusResultIndex = statements.length
 		statements.push(
 			db
@@ -1677,14 +1742,25 @@ export async function claimScheduledForPublish(
 	return changes > 0
 }
 
-export async function unpublishContent(db: D1Database, id: string): Promise<void> {
+export async function unpublishContent(
+	db: D1Database,
+	id: string,
+	options: {
+		/**
+		 * A person pulled the item: advance canonical_version in the same UPDATE,
+		 * so a machine publisher can never put it back without a new write of its
+		 * own (the Foundry machine route's human-edit guard, M3-18).
+		 */
+		canonicalEdit?: boolean
+	} = {},
+): Promise<void> {
 	await db
 		.prepare(
 			`UPDATE content_items
        SET status = 'draft',
            published_at = NULL,
            publish_at = NULL,
-           updated_at = unixepoch()
+           updated_at = unixepoch()${options.canonicalEdit ? ', canonical_version = canonical_version + 1' : ''}
        WHERE id = ?`,
 		)
 		.bind(id)

package/src/engine/tags.ts

@@ -106,12 +106,32 @@ export async function renameTag(db: D1Database, tagId: string, label: string): P
 			.prepare('UPDATE content_tags SET label = ?, slug = ? WHERE id = ?')
 			.bind(tag.label, tag.slug, tagId),
 		db.prepare('UPDATE content_tag_links SET label = ? WHERE tag_id = ?').bind(tag.label, tagId),
+		// A rename is a human-initiated canonical change to every item carrying
+		// the tag, exactly as topic rename is (engine/topics.ts).
+		bumpTaggedItems(db, tagId),
 	])
 	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
 }
 
 export async function deleteTag(db: D1Database, tagId: string): Promise<boolean> {
 	// content_tag_links has ON DELETE CASCADE on tag_id (0001), so links go too.
-	const res = await db.prepare('DELETE FROM content_tags WHERE id = ?').bind(tagId).run()
+	// The tagged items are bumped first, in the same batch, while the links that
+	// name them still exist.
+	const [, res] = await db.batch([
+		bumpTaggedItems(db, tagId),
+		db.prepare('DELETE FROM content_tags WHERE id = ?').bind(tagId),
+	])
 	return Boolean(res.meta && (res.meta as { changes?: number }).changes)
 }
+
+/** canonical_version + 1 for every live item linked to the tag. */
+function bumpTaggedItems(db: D1Database, tagId: string) {
+	return db
+		.prepare(
+			`UPDATE content_items
+			 SET canonical_version = canonical_version + 1, updated_at = unixepoch()
+			 WHERE deleted_at IS NULL
+			   AND id IN (SELECT content_id FROM content_tag_links WHERE tag_id = ?)`,
+		)
+		.bind(tagId)
+}

package/src/engine/topics.ts

@@ -133,7 +133,10 @@ export async function renameTopic(
 	const res = await db
 		.prepare(
 			`UPDATE content_items
-			 SET primary_topic = ?, updated_at = unixepoch()
+			 SET primary_topic = ?, updated_at = unixepoch(),
+			     -- A rename is a human-initiated canonical change to every item it
+			     -- touches, exactly as an editor's per-item topic change is.
+			     canonical_version = canonical_version + 1
 			 WHERE deleted_at IS NULL AND primary_topic = ?`,
 		)
 		.bind(nextSlug, currentSlug)

package/src/engine/video-source.ts

@@ -46,3 +46,47 @@ export async function frontsVideoSourceGeneration(
 export function videoSourceIngestableOverHttps(kind: string | null | undefined): boolean {
 	return kind === 'http_url' || kind === 'dropbox'
 }
+
+/**
+ * The URL shape Foundry's ingest accepts (capabilityplane/ingest.go
+ * `validHTTPSIngestURL`): https, a host, and no userinfo, query or
+ * fragment. A URL outside this shape is refused at the Go media probe with
+ * "artifact ingest probe source URL is invalid" — the failure that blocked
+ * a scheduled HomeFronts video on 2026-10-01T18:05Z. The IP-range checks
+ * (`PublicHTTPSIngestHost`) stay Foundry's: the CMS only refuses what no
+ * host would accept.
+ */
+export function videoSourceUrlIngestableOverHttps(rawUrl: string | null | undefined): boolean {
+	if (!rawUrl) return false
+	let url: URL
+	try {
+		url = new URL(rawUrl)
+	} catch {
+		return false
+	}
+	return (
+		url.protocol === 'https:' &&
+		url.hostname !== '' &&
+		!url.username &&
+		!url.password &&
+		url.search === '' &&
+		url.hash === ''
+	)
+}
+
+/**
+ * A video source whose URL `videoSourceUrlIngestableOverHttps` refuses (a
+ * query string, fragment, userinfo or non-https scheme). Thrown by the
+ * publisher's video write so the save fails before a row can strand a
+ * scheduled video at the Go media probe. The message is the whole
+ * editor-facing error and deliberately echoes no part of the URL — a share
+ * link's path or query can carry its token.
+ */
+export class VideoSourceNotIngestableError extends Error {
+	constructor() {
+		super(
+			'Video source URL must be a direct HTTPS link with no query string or fragment — Foundry refuses to ingest it. A Fulcrum Drive share link must be pasted in its direct /download form.',
+		)
+		this.name = 'VideoSourceNotIngestableError'
+	}
+}