@gobing-ai/knowledge-kit 0.1.10 → 0.1.11

package/plugins/publishings/surfdash-pub/src/index.ts

@@ -1,3 +1,28 @@
+/**
+ * surfdash-pub plugin — publishing transport for the Surfdash site.
+ *
+ * Listen-link backfill:
+ * Runs `bun run sd seo listen-link --backfill --write` before the site gate and commit
+ * in both the main publish path (when auto-push is on) and the patch path. Any modified
+ * files under `content/posts` are included in the scoped commit pathspec.
+ *
+ * Site gate:
+ * Before committing and pushing post content to surfdash `main` (both in the main publish
+ * path and the patch path), `runSiteGate` executes `bun run sd check digest` and
+ * `bun run check:content` in the surfdash checkout. The surfdash site gate is the authoritative
+ * validation suite before deployment.
+ *
+ * Environment variables:
+ * - `SURFDASH_LISTEN_BACKFILL`:
+ *   - `off`: skips the listen-link backfill command.
+ * - `SURFDASH_DIGEST_CHECK`:
+ *   - unset / default: fail-loud on gate failure; commit and push are blocked.
+ *   - `warn`: echoes gate failures via `echoError` prefixed with `site gate (warn):` and continues to push.
+ *   - `off`: bypasses the gate check.
+ * - `SURFDASH_AUTO_PUSH`:
+ *   - '0': disables auto-commit and push (used in tests and offline runs).
+ */
+import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { copyFile, cp, writeFile } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
@@ -16,12 +41,21 @@ export { checkDigestFrontmatter, DIGEST_TAG, type DigestLocale } from './digest-
 const TARGET = 'surfdash';
 
 /** Management operations routed via `options.operation` (L1 R7; pattern from podcast-pub). */
-const OPERATIONS = ['publish', 'scaffold-locale', 'sync', 'patch'] as const;
+const OPERATIONS = [
+    'publish',
+    'prepare',
+    'refine-prepared',
+    'publish-prepared',
+    'scaffold-locale',
+    'sync',
+    'patch',
+] as const;
 type Operation = (typeof OPERATIONS)[number];
 
 /** Locales `scaffold-locale` can scaffold; LLM translation stays in the workflow's agent step. */
 const SCAFFOLD_LOCALES = ['en', 'ja'] as const;
 type ScaffoldLocale = (typeof SCAFFOLD_LOCALES)[number];
+type SupportedLocale = 'zh' | 'en' | 'ja';
 
 /** Cover-image extensions accepted from `metadata.coverImage` (R4): anything else is rejected, not copied. */
 const COVER_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
@@ -33,6 +67,16 @@ interface SurfdashPubOptions {
     postPath?: unknown;
     /** Draft locale to scaffold; required for `scaffold-locale`. */
     target?: unknown;
+    /** Rebuild an existing locale draft after the zh source fingerprint changes. */
+    force?: unknown;
+    /** `publish-prepared`: YYYYMMDD run identity bound to the validated locale files. */
+    runDate?: unknown;
+    /** `refine-prepared`: ask the site-owned orchestrator to refine all three local locale files. */
+    // The plugin never writes `refined: true` itself; the site command owns all managed fields.
+    /** `publish-prepared`: SHA-256 of the prepared zh post, checked before postsurfing runs. */
+    expectedPostSha256?: unknown;
+    /** `publish-prepared`: fingerprint of the prepared zh/en/ja files, checked before postsurfing runs. */
+    expectedLocaleFingerprint?: unknown;
     /** `patch`: podcast-hosted cover URL for `image`/`og_image` (empty → the local cover fallback). */
     coverUrl?: unknown;
     /** `patch`: podcast episode URL appended as the cross-link (empty → none). */
@@ -160,6 +204,21 @@ function fail(error: string): Result {
     return ResultSchema.parse({ ok: false, target: TARGET, error });
 }
 
+type DeliveryState = 'not-sent' | 'uncertain';
+
+/** A failed publish is replay-safe only when it was rejected before postsurfing was invoked. */
+function failWithDeliveryState(error: string, deliveryState: DeliveryState): Result {
+    return ResultSchema.parse({ ok: false, target: TARGET, error, metadata: { deliveryState } });
+}
+
+function failNotSent(error: string): Result {
+    return failWithDeliveryState(error, 'not-sent');
+}
+
+function failUncertain(error: string): Result {
+    return failWithDeliveryState(error, 'uncertain');
+}
+
 /**
  * Writes a Result JSON to `outputPath`, creating the directory as needed. Shared by the success
  * path and the invalid-input path so a malformed payload still produces the spec §2.5 `ok:false`
@@ -333,6 +392,7 @@ export function requireRefined(filePath: string): string | undefined {
  * undefined when ok / downgraded. `SURFDASH_DIGEST_CHECK=warn` echoes each problem and continues.
  */
 export function digestCheckGate(filePath: string, locale: DigestLocale): string | undefined {
+    if (process.env.SURFDASH_DIGEST_CHECK === 'off') return undefined;
     const problems = checkDigestFrontmatter(readFileSync(filePath, 'utf-8'), locale);
     if (problems.length === 0) return undefined;
     if (process.env.SURFDASH_DIGEST_CHECK === 'warn') {
@@ -342,6 +402,109 @@ export function digestCheckGate(filePath: string, locale: DigestLocale): string
     return `digest frontmatter check failed: ${problems.join('; ')}`;
 }
 
+/**
+ * Helper to parse file paths from `git status --porcelain` output.
+ */
+function parsePorcelainPaths(stdout: string): string[] {
+    return stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 3)
+        .map((line) => {
+            const raw = line.slice(3).trim();
+            const arrowIdx = raw.indexOf(' -> ');
+            const target = arrowIdx >= 0 ? raw.slice(arrowIdx + 4).trim() : raw;
+            if (target.startsWith('"') && target.endsWith('"')) {
+                return target.slice(1, -1);
+            }
+            return target;
+        })
+        .filter((p) => p.length > 0);
+}
+
+/**
+ * Runs the surfdash listen-link backfill command (`bun run sd seo listen-link --backfill --write`)
+ * with cwd = `surfdashRoot` via `spawnCli`.
+ *
+ * Scans recent non-draft digest posts and links the podcast episode URL when live.
+ * Best-effort: non-zero exit is reported via `echoError` prefixed with `listen-link backfill:`
+ * and never throws or fails publish/patch.
+ *
+ * Returns relative paths under `content/posts` modified by the backfill, by diffing
+ * `git status --porcelain -- content/posts` before and after the run.
+ * Skipped when `SURFDASH_LISTEN_BACKFILL=off`.
+ */
+export async function runListenLinkBackfill(surfdashRoot: string): Promise<string[]> {
+    if (process.env.SURFDASH_LISTEN_BACKFILL === 'off') {
+        return [];
+    }
+
+    const before = await spawnCli(['git', 'status', '--porcelain', '--', 'content/posts'], surfdashRoot);
+    const beforePaths = new Set(parsePorcelainPaths(before.stdout));
+
+    const spawned = await spawnCli(['bun', 'run', 'sd', 'seo', 'listen-link', '--backfill', '--write'], surfdashRoot);
+    if (spawned.exitCode !== 0) {
+        echoError(`listen-link backfill: ${cliErrorText(spawned)}`);
+    }
+
+    const after = await spawnCli(['git', 'status', '--porcelain', '--', 'content/posts'], surfdashRoot);
+    const afterPaths = parsePorcelainPaths(after.stdout);
+
+    return [...new Set(afterPaths.filter((p) => !beforePaths.has(p)))];
+}
+
+/** Outcome of {@link runSiteGate}. */
+export type SiteGateOutcome = { ok: true } | { ok: false; error: string };
+
+/** Commands executed by the surfdash site gate before commit and push to main. */
+const SITE_GATE_COMMANDS: readonly (readonly string[])[] = [
+    ['bun', 'run', 'sd', 'check', 'digest'],
+    ['bun', 'run', 'check:content'],
+];
+
+/**
+ * Extracts a failing post hint (path or identifier) from CLI error output if detectable.
+ */
+export function extractFailingPostHint(text: string): string | undefined {
+    const match = text.match(/(?:content[\\/])?posts[\\/][^\s:)]+/);
+    if (!match) return undefined;
+    return match[0].replace(/[.,;]+$/, '');
+}
+
+/**
+ * Runs the surfdash site gates (`bun run sd check digest` then `bun run check:content`)
+ * with cwd = `surfdashRoot` via `spawnCli`.
+ *
+ * If either command exits non-zero:
+ * - With `SURFDASH_DIGEST_CHECK=warn`: echoes each line of the failure via `echoError`
+ *   prefixed with `site gate (warn):` and continues.
+ * - With `SURFDASH_DIGEST_CHECK=off`: skips the gate completely.
+ * - Default (unset or any other value): fails loud with command, trimmed output, and post hint.
+ */
+export async function runSiteGate(surfdashRoot: string): Promise<SiteGateOutcome> {
+    if (process.env.SURFDASH_DIGEST_CHECK === 'off') {
+        return { ok: true };
+    }
+
+    for (const cmd of SITE_GATE_COMMANDS) {
+        const spawned = await spawnCli([...cmd], surfdashRoot);
+        if (spawned.exitCode !== 0) {
+            const output = cliErrorText(spawned);
+            const postHint = extractFailingPostHint(output);
+            const hint = postHint ? ` [failing post: ${postHint}]` : '';
+            const error = `site gate failed: ${cmd.join(' ')} (exit ${spawned.exitCode})${hint}: ${output}`;
+            if (process.env.SURFDASH_DIGEST_CHECK === 'warn') {
+                for (const line of error.split('\n')) {
+                    echoError(`site gate (warn): ${line}`);
+                }
+                continue;
+            }
+            return { ok: false, error };
+        }
+    }
+    return { ok: true };
+}
+
 /** Outcome of {@link pushPostGit} — the union keeps fail-loud errors typed at the call site. */
 export type GitPushOutcome = { ok: true; hash: string } | { ok: false; error: string };
 
@@ -352,8 +515,15 @@ export type GitPushOutcome = { ok: true; hash: string } | { ok: false; error: st
  * Committing with a pathspec (`git commit -- <path>`) keeps unrelated staged files
  * out of the publish commit. Fails loud on branch/commit/push errors.
  */
-export async function pushPostGit(surfdashRoot: string, relPostDir: string, message: string): Promise<GitPushOutcome> {
-    return commitPostPaths(surfdashRoot, [relPostDir], message);
+export async function pushPostGit(
+    surfdashRoot: string,
+    relPostDir: string | string[],
+    message: string,
+    extraPaths: string[] = [],
+): Promise<GitPushOutcome> {
+    const rawPaths = Array.isArray(relPostDir) ? [...relPostDir, ...extraPaths] : [relPostDir, ...extraPaths];
+    const paths = [...new Set(rawPaths)];
+    return commitPostPaths(surfdashRoot, paths, message);
 }
 /** Refuse a checkout that cannot deploy before anything is written (`deploy.yml` builds `main` only). */
 async function assertMainBranch(surfdashRoot: string): Promise<{ ok: true } | { ok: false; error: string }> {
@@ -504,8 +674,20 @@ async function scaffoldLocale(options: SurfdashPubOptions): Promise<Result> {
     }
 
     try {
+        const force = options.force === true;
         const spawned = await spawnCli(
-            ['bun', 'run', 'sd', 'translate', postPath.postPath, '--source', 'zh', '--target', target.locale],
+            [
+                'bun',
+                'run',
+                'sd',
+                'translate',
+                postPath.postPath,
+                '--source',
+                'zh',
+                '--target',
+                target.locale,
+                ...(force ? ['--force'] : []),
+            ],
             surfdashRoot,
         );
         if (spawned.exitCode !== 0) {
@@ -659,6 +841,12 @@ async function patchPost(options: SurfdashPubOptions): Promise<Result> {
             commitPaths.add(relative(surfdashRoot, assetsDir));
         }
     }
+    if (process.env.SURFDASH_AUTO_PUSH !== '0') {
+        const backfilled = await runListenLinkBackfill(surfdashRoot);
+        for (const p of backfilled) commitPaths.add(p);
+        const gate = await runSiteGate(surfdashRoot);
+        if (!gate.ok) return fail(gate.error);
+    }
     const commit = await commitPostPaths(
         surfdashRoot,
         [...commitPaths],
@@ -693,95 +881,336 @@ async function patchPost(options: SurfdashPubOptions): Promise<Result> {
     });
 }
 
+interface PreparedPost {
+    surfdashRoot: string;
+    locale: SupportedLocale;
+    dateStamp: string;
+    slug: string;
+    filePath: string;
+    relPostDir: string;
+    /** Prepared daily publishes carry all translated sibling directories into the deploy commit. */
+    relPostDirs?: string[];
+    articleUrl: string;
+}
+
+interface PreparedLocaleIdentity {
+    runDate: string;
+    postPath: string;
+    localePaths: Record<SupportedLocale, string>;
+    localeDigests: Record<SupportedLocale, string>;
+    fingerprint: string;
+}
+
+function fileSha256(filePath: string): string {
+    return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+
 /**
- * Publish path (behavior unchanged since E3): maps Content into surfdash markdown under
- * `content/posts/<collection>/<locale>/<slug>/index.md` and invokes the postsurfing CLI.
+ * Computes the exact identity used by the daily locale gate. This is intentionally derived from
+ * bytes on disk immediately before the remote publishing FSM starts; a cached result must never
+ * satisfy a different slug, payload, or translated-locale set.
  */
-async function publishPost(payload: PublishTransportPayload): Promise<Result> {
-    const postsurfingBin = process.env.POSTSURFING_BIN ?? 'postsurfing';
+function preparedLocaleIdentity(
+    postPath: string,
+    runDate: string,
+): { ok: true; value: PreparedLocaleIdentity } | { ok: false; error: string } {
+    const enPath = deriveLocaleDraftPath(postPath, 'en');
+    const jaPath = deriveLocaleDraftPath(postPath, 'ja');
+    if (enPath === undefined || jaPath === undefined) {
+        return { ok: false, error: `prepared zh post path must contain a "/zh/" locale segment: ${postPath}` };
+    }
+    const localePaths: Record<SupportedLocale, string> = { zh: postPath, en: enPath, ja: jaPath };
+    const localeDigests = {} as Record<SupportedLocale, string>;
+    for (const locale of ['zh', 'en', 'ja'] as const) {
+        const path = localePaths[locale];
+        if (!existsSync(path)) return { ok: false, error: `${locale} locale file is missing: ${path}` };
+        try {
+            localeDigests[locale] = fileSha256(path);
+        } catch (error: unknown) {
+            return {
+                ok: false,
+                error: `${locale} locale file cannot be fingerprinted: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    const identity = { runDate, postPath, localePaths, localeDigests };
+    return {
+        ok: true,
+        value: { ...identity, fingerprint: createHash('sha256').update(JSON.stringify(identity)).digest('hex') },
+    };
+}
+
+interface PreparedLocaleSet {
+    surfdashRoot: string;
+    runDate: string;
+    postPath: string;
+    slug: string;
+    localePaths: Record<SupportedLocale, string>;
+}
 
-    // The publishing FSM requires the markdown at
-    // content/posts/<collection>/<locale>/<slug>/index.md inside the surfdash site tree
-    // (its refine step rejects other layouts); the root resolution lives in resolveSurfdashRoot().
+/**
+ * Resolves the exact three-file daily post set without writing anything. Both the local refine
+ * phase and the final prepared publish use this guard so they cannot drift to different slugs or
+ * locale siblings between validation and dispatch.
+ */
+function resolvePreparedLocaleSet(
+    options: SurfdashPubOptions,
+): { ok: true; value: PreparedLocaleSet } | { ok: false; result: Result } {
+    const postPath = resolvePostPath(options);
+    if ('error' in postPath) return { ok: false, result: failNotSent(postPath.error) };
     const surfdashRoot = resolveSurfdashRoot();
     if (!surfdashRoot) {
-        return fail('SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout');
+        return {
+            ok: false,
+            result: failNotSent(
+                'SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout',
+            ),
+        };
+    }
+    const outsideRoot = postPathOutsideRoot(postPath.postPath, surfdashRoot);
+    if (outsideRoot) return { ok: false, result: failNotSent(outsideRoot) };
+    if (!existsSync(postPath.postPath))
+        return { ok: false, result: failNotSent(`prepared post does not exist: ${postPath.postPath}`) };
+    const runDate = options.runDate;
+    if (typeof runDate !== 'string' || !/^\d{8}$/.test(runDate)) {
+        return { ok: false, result: failNotSent(`options.runDate must be YYYYMMDD, got '${String(runDate)}'`) };
+    }
+    const articlesRoot = resolve(surfdashRoot, 'content', 'posts', 'articles');
+    const relativePost = relative(articlesRoot, postPath.postPath);
+    const parts = relativePost.split(sep);
+    const slug = parts[1];
+    if (parts.length !== 3 || parts[0] !== 'zh' || parts[2] !== 'index.md' || slug === undefined || slug === '') {
+        return {
+            ok: false,
+            result: failNotSent(
+                `options.postPath must be content/posts/articles/zh/<slug>/index.md: ${postPath.postPath}`,
+            ),
+        };
+    }
+    const enPath = deriveLocaleDraftPath(postPath.postPath, 'en');
+    const jaPath = deriveLocaleDraftPath(postPath.postPath, 'ja');
+    if (enPath === undefined || jaPath === undefined) {
+        return {
+            ok: false,
+            result: failNotSent(`prepared zh post path must contain a "/zh/" locale segment: ${postPath.postPath}`),
+        };
+    }
+    const localePaths: Record<SupportedLocale, string> = { zh: postPath.postPath, en: enPath, ja: jaPath };
+    for (const locale of ['zh', 'en', 'ja'] as const) {
+        if (!existsSync(localePaths[locale])) {
+            return { ok: false, result: failNotSent(`${locale} locale file is missing: ${localePaths[locale]}`) };
+        }
+    }
+    return { ok: true, value: { surfdashRoot, runDate, postPath: postPath.postPath, slug, localePaths } };
+}
+
+function resolvePreparedPost(
+    options: SurfdashPubOptions,
+): { ok: true; prepared: PreparedPost; identity: PreparedLocaleIdentity } | { ok: false; result: Result } {
+    const resolved = resolvePreparedLocaleSet(options);
+    if (!resolved.ok) return resolved;
+    const { surfdashRoot, runDate, postPath: preparedPath, slug } = resolved.value;
+    const expectedPostSha256 = options.expectedPostSha256;
+    if (typeof expectedPostSha256 !== 'string' || !/^[0-9a-f]{64}$/.test(expectedPostSha256)) {
+        return { ok: false, result: failNotSent('options.expectedPostSha256 must be a lowercase SHA-256 digest') };
+    }
+    const expectedLocaleFingerprint = options.expectedLocaleFingerprint;
+    if (typeof expectedLocaleFingerprint !== 'string' || !/^[0-9a-f]{64}$/.test(expectedLocaleFingerprint)) {
+        return {
+            ok: false,
+            result: failNotSent('options.expectedLocaleFingerprint must be a lowercase SHA-256 digest'),
+        };
+    }
+    const identity = preparedLocaleIdentity(preparedPath, runDate);
+    if (!identity.ok) return { ok: false, result: failNotSent(identity.error) };
+    if (identity.value.localeDigests.zh !== expectedPostSha256) {
+        return {
+            ok: false,
+            result: failNotSent(`prepared zh post bytes changed after validation: ${preparedPath}`),
+        };
+    }
+    if (identity.value.fingerprint !== expectedLocaleFingerprint) {
+        return {
+            ok: false,
+            result: failNotSent(
+                'prepared locale files changed after validation; refresh the locale gate before publishing',
+            ),
+        };
+    }
+    const baseUrl = (process.env.SURFDASH_URL ?? 'https://surfing.salty.vip').replace(/\/$/, '');
+    return {
+        ok: true,
+        prepared: {
+            surfdashRoot,
+            locale: 'zh',
+            dateStamp: runDate,
+            slug,
+            filePath: preparedPath,
+            relPostDir: join('content', 'posts', 'articles', 'zh', slug),
+            relPostDirs: ['zh', 'en', 'ja'].map((locale) => join('content', 'posts', 'articles', locale, slug)),
+            articleUrl: `${baseUrl}/zh/posts/${slug}`,
+        },
+        identity: identity.value,
+    };
+}
+
+type PrepareOutcome = { ok: true; prepared: PreparedPost } | { ok: false; result: Result };
+
+/**
+ * Materializes the local post without invoking the external publishing FSM.
+ *
+ * Locale scaffolding and translation must happen before Surfdash's strict sync gate runs. The
+ * normal `publish` operation uses the same preparation path before refine, CMS sync and deploy.
+ */
+async function preparePost(payload: PublishTransportPayload): Promise<PrepareOutcome> {
+    const surfdashRoot = resolveSurfdashRoot();
+    if (!surfdashRoot) {
+        return {
+            ok: false,
+            result: failNotSent(
+                'SURFDASH_ROOT is required when POSTSURFING_BIN is not a path inside the surfdash checkout',
+            ),
+        };
     }
 
-    const locale = process.env.SURFDASH_LOCALE ?? 'zh';
-    // Fail loud on legacy locale codes ('cn' is the pre-migration name for zh) —
-    // they'd write a content dir no route serves.
-    if (!['zh', 'en', 'ja'].includes(locale)) {
-        return fail(`SURFDASH_LOCALE must be one of zh/en/ja, got '${locale}'`);
+    const rawLocale = process.env.SURFDASH_LOCALE ?? 'zh';
+    if (!['zh', 'en', 'ja'].includes(rawLocale)) {
+        return { ok: false, result: failNotSent(`SURFDASH_LOCALE must be one of zh/en/ja, got '${rawLocale}'`) };
     }
-    // Date-stamped slug (metadata.runDate, e.g. 20260904) keeps same-title daily posts
-    // from colliding; Chinese titles slugify to '' and fall back to the bare date.
+    const locale = rawLocale as SupportedLocale;
     const runDate = typeof payload.content.metadata?.runDate === 'string' ? payload.content.metadata.runDate : '';
     const today = new Date().toISOString().slice(0, 10).replaceAll('-', '');
     const dateStamp = runDate || today;
     const titleSlug = slugify(payload.content.title ?? '');
     const slug = titleSlug ? `${dateStamp}-${titleSlug}` : `${dateStamp}-post`;
-    // Validate before touching disk (R4): a `metadata.runDate` or slug that escapes the articles
-    // tree would write a post outside it, and a non-image `coverImage` would be copied into a post
-    // that pushPostGit then publishes to a public repo.
     if (runDate !== '' && !/^\d{8}$/.test(runDate)) {
-        return fail(`metadata.runDate must be YYYYMMDD, got '${runDate}'`);
+        return { ok: false, result: failNotSent(`metadata.runDate must be YYYYMMDD, got '${runDate}'`) };
     }
     const articlesRoot = resolve(surfdashRoot, 'content', 'posts', 'articles');
     const localeRoot = resolve(articlesRoot, locale);
     const postDir = resolve(localeRoot, slug);
     if (dirname(localeRoot) !== articlesRoot || dirname(postDir) !== localeRoot) {
-        return fail(`post path escapes ${articlesRoot}`);
+        return { ok: false, result: failNotSent(`post path escapes ${articlesRoot}`) };
     }
+
     const coverPath = payload.content.metadata?.coverImage;
-    // R4 + 2026-10-24: a coverImage that does not exist must fail before anything is written —
-    // the old silent skip published a coverless post while the run believed it had one.
     if (typeof coverPath === 'string' && !existsSync(coverPath)) {
-        return fail(`metadata.coverImage not found: ${coverPath}`);
+        return { ok: false, result: failNotSent(`metadata.coverImage not found: ${coverPath}`) };
     }
     if (typeof coverPath === 'string' && !COVER_EXTS.has(extname(coverPath).toLowerCase())) {
-        return fail(`metadata.coverImage must be one of ${[...COVER_EXTS].join(', ')}`);
+        return {
+            ok: false,
+            result: failNotSent(`metadata.coverImage must be one of ${[...COVER_EXTS].join(', ')}`),
+        };
     }
-    // Daily digest posts are the series' public face: a missing cover ships a blank OG card.
-    // The check uses the same tag sources as mapContentToSurfingMarkdown (contentTags).
     if (isDigestContent(payload.content) && typeof coverPath !== 'string') {
-        return fail('digest post has no cover image (metadata.coverImage)');
+        return { ok: false, result: failNotSent('digest post has no cover image (metadata.coverImage)') };
     }
 
-    await createNodeFileSystem().ensureDir(postDir);
-
-    // Cover image: metadata.coverImage (absolute local path) is copied into the post's
-    // assets dir and referenced relatively — the surfdash PostSchema accepts ./assets/<file>.
-    let imageFrontmatter: string | undefined;
-    if (typeof coverPath === 'string') {
-        const assetsDir = join(postDir, 'assets');
-        await createNodeFileSystem().ensureDir(assetsDir);
-        const coverName = `cover${extname(coverPath).toLowerCase()}`;
-        await copyFile(coverPath, join(assetsDir, coverName));
-        imageFrontmatter = `./assets/${coverName}`;
+    const filePath = join(postDir, 'index.md');
+    try {
+        await createNodeFileSystem().ensureDir(postDir);
+        let imageFrontmatter: string | undefined;
+        if (typeof coverPath === 'string') {
+            const assetsDir = join(postDir, 'assets');
+            await createNodeFileSystem().ensureDir(assetsDir);
+            const coverName = `cover${extname(coverPath).toLowerCase()}`;
+            await copyFile(coverPath, join(assetsDir, coverName));
+            imageFrontmatter = `./assets/${coverName}`;
+        }
+        const markdown = mapContentToSurfingMarkdown(payload.content, {
+            image: imageFrontmatter,
+            publishDate: runDate ? `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` : undefined,
+        });
+        await createNodeFileSystem().writeFile(filePath, markdown);
+    } catch (err: unknown) {
+        return {
+            ok: false,
+            result: failNotSent(
+                `Surfdash post preparation failed: ${err instanceof Error ? err.message : String(err)}`,
+            ),
+        };
     }
-    const markdown = mapContentToSurfingMarkdown(payload.content, {
-        image: imageFrontmatter,
-        publishDate: runDate ? `${runDate.slice(0, 4)}-${runDate.slice(4, 6)}-${runDate.slice(6, 8)}` : undefined,
+
+    const baseUrl = (process.env.SURFDASH_URL ?? 'https://surfing.salty.vip').replace(/\/$/, '');
+    const articleUrl = `${baseUrl}${locale === 'en' ? '' : `/${locale}`}/posts/${slug}`;
+    return {
+        ok: true,
+        prepared: {
+            surfdashRoot,
+            locale,
+            dateStamp,
+            slug,
+            filePath,
+            relPostDir: join('content', 'posts', 'articles', locale, slug),
+            articleUrl,
+        },
+    };
+}
+
+/** `prepare` operation: write the local post and return its path for locale scaffolding. */
+async function preparePostResult(payload: PublishTransportPayload): Promise<Result> {
+    const outcome = await preparePost(payload);
+    if (!outcome.ok) return outcome.result;
+    return ResultSchema.parse({
+        ok: true,
+        target: TARGET,
+        message: `Prepared ${outcome.prepared.locale} post at ${outcome.prepared.filePath}`,
+        metadata: {
+            postPath: outcome.prepared.filePath,
+            articleUrl: outcome.prepared.articleUrl,
+            dateStamp: outcome.prepared.dateStamp,
+            slug: outcome.prepared.slug,
+        },
     });
-    const filePath = join(postDir, 'index.md');
+}
+
+/** Invokes the remote publishing FSM for an already-materialized post path. */
+async function publishPreparedFile(
+    prepared: PreparedPost,
+    identity?: Pick<PreparedLocaleIdentity, 'runDate' | 'fingerprint'> & { postSha256?: string },
+): Promise<Result> {
+    const postsurfingBin = process.env.POSTSURFING_BIN ?? 'postsurfing';
+    const { surfdashRoot, locale, dateStamp, filePath, relPostDir, relPostDirs, articleUrl } = prepared;
+    const identityMetadata = identity
+        ? {
+              runDate: identity.runDate,
+              localeFingerprint: identity.fingerprint,
+              ...(identity.postSha256 ? { postSha256: identity.postSha256 } : {}),
+          }
+        : {};
 
     try {
-        await createNodeFileSystem().writeFile(filePath, markdown);
         const spawned = await spawnCli([postsurfingBin, 'publish', filePath], surfdashRoot);
 
         if (spawned.exitCode !== 0) {
-            return fail(
+            return failUncertain(
                 `postsurfing CLI failed (exit ${spawned.exitCode}): ${withEmdashTokenHint(cliErrorText(spawned))}`,
             );
         }
 
+        // The real Surfdash FSM runs its own refine step before CMS sync. The daily workflow runs
+        // site-owned refine locally first, so this must be idempotent; otherwise the remote phase
+        // would silently mutate the bytes whose fingerprint admitted this publish. Treat any
+        // mutation as uncertain because CMS/git may already have side effects.
+        if (identity !== undefined) {
+            const afterRemote = preparedLocaleIdentity(filePath, identity.runDate);
+            if (!afterRemote.ok)
+                return failUncertain(`prepared locale files changed after remote publish: ${afterRemote.error}`);
+            if (
+                afterRemote.value.fingerprint !== identity.fingerprint ||
+                (identity.postSha256 !== undefined && afterRemote.value.localeDigests.zh !== identity.postSha256)
+            ) {
+                return failUncertain('prepared locale files changed after remote publish; reconcile before retrying');
+            }
+        }
+
         // Contract check (ADR-008): the site, not this plugin, owns SEO metadata.
         const notRefined = requireRefined(filePath);
-        if (notRefined) return fail(notRefined);
+        if (notRefined) return failUncertain(notRefined);
         // Digest contract (2026-10-24): the refined values themselves must hold, before any push.
-        const digestProblem = digestCheckGate(filePath, locale as DigestLocale);
-        if (digestProblem) return fail(digestProblem);
+        const digestProblem = digestCheckGate(filePath, locale);
+        if (digestProblem) return failUncertain(digestProblem);
         const refined = readRefinedSnapshot(filePath);
 
         // Deploy seam: commit + push the post so deploy.yml builds it, then wait for
@@ -790,8 +1219,6 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
         // URL shape mirrors surfdash's localePathPrefix (surfdash/src/lib/seo.ts):
         // en is served at the site root, zh/ja carry a /<locale> prefix. Composing
         // /<locale>/posts/<slug> unconditionally 404s en posts.
-        const baseUrl = (process.env.SURFDASH_URL ?? 'https://surfing.salty.vip').replace(/\/$/, '');
-        const articleUrl = `${baseUrl}${locale === 'en' ? '' : `/${locale}`}/posts/${slug}`;
         if (process.env.SURFDASH_AUTO_PUSH === '0') {
             return ResultSchema.parse({
                 ok: true,
@@ -800,12 +1227,26 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
                 message: 'Published via postsurfing CLI (auto-push disabled)',
                 // Absolute post path lets downstream steps (locale translation + CMS sync)
                 // derive the surfdash checkout root without extra configuration.
-                metadata: { postPath: filePath, refinedTitle: refined?.title, refinedCanonical: refined?.canonical },
+                metadata: {
+                    postPath: filePath,
+                    ...identityMetadata,
+                    refinedTitle: refined?.title,
+                    refinedCanonical: refined?.canonical,
+                },
             });
         }
-        const relPostDir = join('content', 'posts', 'articles', locale, slug);
-        const pushed = await pushPostGit(surfdashRoot, relPostDir, `content: daily AI news ${dateStamp} (zh)`);
-        if (!pushed.ok) return fail(pushed.error);
+        const backfilled = await runListenLinkBackfill(surfdashRoot);
+        const gate = await runSiteGate(surfdashRoot);
+        if (!gate.ok) return failUncertain(gate.error);
+        const commitPaths = relPostDirs ?? [relPostDir];
+        const commitLocales: SupportedLocale[] = relPostDirs === undefined ? [locale] : ['zh', 'en', 'ja'];
+        const pushed = await pushPostGit(
+            surfdashRoot,
+            commitPaths,
+            `content: daily AI news ${dateStamp} (${commitLocales.join(', ')})`,
+            backfilled,
+        );
+        if (!pushed.ok) return failUncertain(pushed.error);
         const live = await awaitArticleLive(articleUrl);
 
         return ResultSchema.parse({
@@ -815,16 +1256,95 @@ async function publishPost(payload: PublishTransportPayload): Promise<Result> {
             message: live
                 ? 'Published, committed, pushed, and live on the site'
                 : 'Published and pushed; URL not live within the verify window — check the surfdash deploy workflow',
-            metadata: { postPath: filePath, gitCommit: pushed.hash, live, refinedTitle: refined?.title },
+            metadata: {
+                postPath: filePath,
+                ...identityMetadata,
+                gitCommit: pushed.hash,
+                live,
+                refinedTitle: refined?.title,
+            },
         });
     } catch (err: unknown) {
-        return fail(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);
+        return failUncertain(`Postsurfing transport error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+
+/**
+ * Publish path (behavior unchanged since E3): maps Content into surfdash markdown under
+ * `content/posts/<collection>/<locale>/<slug>/index.md` and invokes the postsurfing CLI.
+ */
+async function publishPost(payload: PublishTransportPayload): Promise<Result> {
+    const outcome = await preparePost(payload);
+    if (!outcome.ok) return outcome.result;
+    return publishPreparedFile(outcome.prepared);
+}
+
+/**
+ * Runs the site-owned refine command over zh/en/ja without CMS, git, or remote effects. The daily
+ * workflow fingerprints only after this operation; the real publish FSM can then revisit refine
+ * idempotently instead of rewriting a validated locale set during its remote phase.
+ */
+async function refinePreparedPost(options: SurfdashPubOptions): Promise<Result> {
+    const resolved = resolvePreparedLocaleSet(options);
+    if (!resolved.ok) return resolved.result;
+    const orchestrator = join(resolved.value.surfdashRoot, 'scripts', 'publish-orchestrator.ts');
+    if (!existsSync(orchestrator)) return failNotSent(`Surfdash refine orchestrator is missing: ${orchestrator}`);
+    try {
+        for (const locale of ['zh', 'en', 'ja'] as const) {
+            const filePath = resolved.value.localePaths[locale];
+            const spawned = await spawnCli(
+                [process.execPath, orchestrator, 'refine', filePath],
+                resolved.value.surfdashRoot,
+            );
+            if (spawned.exitCode !== 0) {
+                return failNotSent(
+                    `Surfdash refine failed for ${locale} (exit ${spawned.exitCode}): ${cliErrorText(spawned)}`,
+                );
+            }
+            const notRefined = requireRefined(filePath);
+            if (notRefined) return failNotSent(notRefined);
+            const digestProblem = digestCheckGate(filePath, locale);
+            if (digestProblem) return failNotSent(digestProblem);
+        }
+    } catch (error: unknown) {
+        return failNotSent(
+            `Surfdash refine transport error: ${error instanceof Error ? error.message : String(error)}`,
+        );
     }
+    const identity = preparedLocaleIdentity(resolved.value.postPath, resolved.value.runDate);
+    if (!identity.ok) return failNotSent(identity.error);
+    return ResultSchema.parse({
+        ok: true,
+        target: TARGET,
+        message: 'Refined zh/en/ja via the Surfdash-owned orchestrator',
+        metadata: {
+            postPath: resolved.value.postPath,
+            runDate: resolved.value.runDate,
+            localePaths: identity.value.localePaths,
+            localeDigests: identity.value.localeDigests,
+            localeFingerprint: identity.value.fingerprint,
+        },
+    });
+}
+
+/**
+ * Final daily voice2 operation. Unlike `publish`, this never maps Content or rewrites the prepared
+ * zh post. It verifies the exact validated bytes and locale fingerprint immediately before invoking
+ * postsurfing, so a regenerated same-day payload cannot silently replace the validated material.
+ */
+async function publishPreparedPost(options: SurfdashPubOptions): Promise<Result> {
+    const outcome = resolvePreparedPost(options);
+    if (!outcome.ok) return outcome.result;
+    return publishPreparedFile(outcome.prepared, {
+        runDate: outcome.identity.runDate,
+        fingerprint: outcome.identity.fingerprint,
+        postSha256: outcome.identity.localeDigests.zh,
+    });
 }
 
 /**
  * FileCli transport invoking postsurfing CLI for `publish` (default) and the
- * `scaffold-locale` / `sync` surfdash mechanics via `options.operation` (L1 R7).
+ * prepared-path / `scaffold-locale` / `sync` surfdash mechanics via `options.operation` (L1 R7).
  */
 export class PostsurfingFileCliTransport implements PublishTransport {
     public readonly kind = 'file-cli';
@@ -839,6 +1359,12 @@ export class PostsurfingFileCliTransport implements PublishTransport {
         if ('error' in routed) return fail(routed.error);
 
         switch (routed.operation) {
+            case 'prepare':
+                return preparePostResult(payload);
+            case 'refine-prepared':
+                return refinePreparedPost(options);
+            case 'publish-prepared':
+                return publishPreparedPost(options);
             case 'scaffold-locale':
                 return scaffoldLocale(options);
             case 'sync':
@@ -865,10 +1391,9 @@ export function getPublishTransport(): PublishTransport {
 /**
  * Processes input Content and writes output Result via transport.
  *
- * The input JSON may carry a top-level `options` object (`operation`, `postPath`,
- * `target`) alongside the Content fields; it is forwarded to the transport so
- * `kk executor run` callers can select scaffold-locale/sync without extra flags
- * (podcast-pub pattern, 0096).
+ * The input JSON may carry a top-level `options` object (`operation`, `postPath`, `target`, and
+ * prepared-path identity fields) alongside the Content fields; it is forwarded to the transport so
+ * `kk executor run` callers can select locale/publish mechanics without extra flags (0096).
  */
 export async function processPublishIO(
     inputPath: string,