@gentbajko/slopify 1.5.1 → 2.0.1

package/dist/edge/http/actions.js

@@ -8,6 +8,9 @@ import { cancelProject } from "../../slices/cancel/index.js";
 import { settleReleasedCheckpoints } from "../../slices/checkpoints/recovery.js";
 import { pauseProject } from "../../slices/control/index.js";
 import { revisionControlSchema, } from "../../slices/control/revision-control-schema.js";
+import { recoverProject } from "../../slices/rebuild/recovery.js";
+import { recoveryResultSchema } from "../../slices/rebuild/recovery-model.js";
+import { resumable } from "../../slices/rebuild/recovery-repo.js";
 import { adoptBaseline } from "../../slices/revisions/adopt.js";
 import { currentRevisionId } from "../../slices/revisions/repo.js";
 import { allowsCustomModel } from "../../slices/settings/models.js";
@@ -64,6 +67,7 @@ export function actionRoutes(deps) {
         const stages = stagesOf(deps.db, projectId);
         return {
             revisionId: currentRevisionId(deps.db, projectId) ?? null,
+            resumable: resumable(deps.db, projectId),
             project: {
                 ...projectById(deps.db, projectId),
                 status: derive(stages, projectPaused(deps.db, projectId)),
@@ -108,6 +112,57 @@ export function actionRoutes(deps) {
             },
         });
     };
+    const recovery = async (c, id, input, action) => {
+        if (deps.rebuild === undefined)
+            return problem(c, {
+                status: 503,
+                title: titleOf(503),
+                detail: "Recovery is unavailable. Try again after restart.",
+            });
+        const result = recoveryResultSchema.parse(await recoverProject(deps.rebuild, id, { ...input, action }));
+        if (result.ok)
+            return c.json(result, 202);
+        const status = result.reason === "no-project" || result.reason === "no-revision"
+            ? 404
+            : result.reason === "invalid-selection" || result.reason === "invalid-edit"
+                ? 400
+                : 409;
+        const messages = {
+            "no-project": "This project no longer exists.",
+            "no-revision": "This revision no longer exists. Reload the project.",
+            conflict: "The saved project changed. Reload it and try Resume.",
+            "idempotency-conflict": "This request ID belongs to another action. Reload the project.",
+            "invalid-edit": "This section needs attention in Edit project before rerunning.",
+            "stale-preview": "The required work changed. Try Resume to check it again.",
+            "invalid-selection": "This section has no generated work to rerun. Use Edit project to change its source.",
+            "review-required": "Changed supplied content or manual captions need Edit project or optional Advanced rebuild review.",
+            "cost-ack-required": "Use optional Advanced rebuild review for this request.",
+            readiness: "Check the provider, model, voice or source files, then try Resume.",
+            running: "Wait for this section to finish, or Pause the project before rerunning it.",
+            "accepted-job": "This section cannot be rerun yet.",
+            "control-changed": "A newer control action took precedence. Check the project before using Resume.",
+        };
+        const detail = [
+            messages[result.reason],
+            ...(result.fields ?? []).map((row) => row.message),
+            ...(result.intentRevisionId === undefined
+                ? []
+                : ["The rerun revision was saved. Use Resume to continue it; do not rerun again."]),
+        ].join(" ");
+        return problem(c, {
+            status,
+            title: titleOf(status),
+            detail,
+            extensions: {
+                reason: result.reason,
+                fields: result.fields ?? [],
+                currentRevisionId: currentRevisionId(deps.db, id) ?? null,
+                ...(result.intentRevisionId === undefined
+                    ? {}
+                    : { intentRevisionId: result.intentRevisionId }),
+            },
+        });
+    };
     const controlInput = async (c, id) => {
         if (deps.catalogue !== undefined)
             adoptBaseline(deps, id);
@@ -135,13 +190,7 @@ export function actionRoutes(deps) {
             ? input
             : controlled(c, id, await pauseProject(control, id, input));
     })
-        .post("/:id/resume", zValidator("param", idParam, onInvalid), (c) => {
-        const { id } = c.req.valid("param");
-        return controlled(c, id, {
-            ok: false,
-            reason: projectById(deps.db, id) === undefined ? "no-project" : "rebuild-required",
-        });
-    })
+        .post("/:id/resume", zValidator("param", idParam, onInvalid), zValidator("json", revisionControlSchema, onInvalid), (c) => recovery(c, c.req.valid("param").id, c.req.valid("json"), { kind: "resume" }))
         .patch("/:id/providers", zValidator("param", idParam, onInvalid), revisionRequired)
         .post("/:id/cancel", zValidator("param", idParam, onInvalid), async (c) => {
         const { id } = c.req.valid("param");
@@ -153,14 +202,14 @@ export function actionRoutes(deps) {
             return controlled(c, id, result);
         return c.json({ ...view(id), canceled: result.canceled });
     })
-        .post("/:id/stages/:kind/retry", zValidator("param", stageParam, onInvalid), (c) => {
-        const { id } = c.req.valid("param");
-        return controlled(c, id, {
-            ok: false,
-            reason: projectById(deps.db, id) === undefined ? "no-project" : "rebuild-required",
-        });
-    })
-        .post("/:id/stages/:kind/rerun", zValidator("param", stageParam, onInvalid), revisionRequired)
+        .post("/:id/stages/:kind/retry", zValidator("param", stageParam, onInvalid), zValidator("json", revisionControlSchema, onInvalid), (c) => recovery(c, c.req.valid("param").id, c.req.valid("json"), {
+        kind: "retry",
+        stage: c.req.valid("param").kind,
+    }))
+        .post("/:id/stages/:kind/rerun", zValidator("param", stageParam, onInvalid), zValidator("json", revisionControlSchema, onInvalid), (c) => recovery(c, c.req.valid("param").id, c.req.valid("json"), {
+        kind: "rerun",
+        stage: c.req.valid("param").kind,
+    }))
         .put("/:id/article", zValidator("param", idParam, onInvalid), revisionRequired)
         .delete("/:id/images/:outputId", zValidator("param", imageParam, onInvalid), revisionRequired)
         .post("/:id/images/:outputId/regenerate", zValidator("param", imageParam, onInvalid), revisionRequired);

package/dist/edge/http/app.js

@@ -76,6 +76,12 @@ export function createApp(deps) {
         .use("/api/*", async (c, next) => {
         if (["GET", "HEAD", "OPTIONS"].includes(c.req.method))
             return next();
+        if (deps.installationPending?.() && new URL(c.req.url).pathname !== "/api/update/activate")
+            return problem(c, {
+                status: 503,
+                title: titleOf(503),
+                detail: "Docker installation is being verified. Wait for the launcher to finish.",
+            });
         const releaseRequest = deps.mutations?.begin();
         if (deps.mutations !== undefined && releaseRequest === undefined)
             return problem(c, {

package/dist/edge/http/folder-location-schema.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const folderReplySchema = z.discriminatedUnion("opened", [
+    z.object({ opened: z.literal(true) }).strict(),
+    z
+        .object({
+        opened: z.literal(false),
+        location: z.literal("docker-host"),
+        path: z.string().min(1),
+    })
+        .strict(),
+]);

package/dist/edge/http/folder-location.js

@@ -0,0 +1,65 @@
+import { lstat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { folderReplySchema } from "./folder-location-schema.js";
+import { problem, titleOf } from "./problem.js";
+export async function replyForFolder(c, deps, projectId, file) {
+    c.header("Cache-Control", "no-store");
+    if (deps.folderLocation?.container) {
+        const host = deps.folderLocation.hostProjects;
+        if (!host)
+            return problem(c, {
+                status: 503,
+                title: titleOf(503),
+                detail: "This Docker installation has no verified host project folder. Downloads remain available. Rerun the managed Docker launcher to set up host files.",
+            });
+        try {
+            const r = relative(deps.paths.projects, file);
+            if (!r || r === ".." || r.startsWith(`..${sep}`) || isAbsolute(r))
+                throw new Error("Outside projects");
+            let path = deps.paths.projects;
+            const root = await lstat(path);
+            if (!root.isDirectory() || root.isSymbolicLink())
+                throw new Error("Invalid project root");
+            const parts = r.split(sep);
+            for (const [i, part] of parts.entries()) {
+                path = join(path, part);
+                const s = await lstat(path);
+                if (s.isSymbolicLink() || (i === parts.length - 1 ? !s.isFile() : !s.isDirectory()))
+                    throw new Error("Unavailable output");
+            }
+            return c.json(folderReplySchema.parse({
+                opened: false,
+                location: "docker-host",
+                path: join(host, dirname(r)),
+            }));
+        }
+        catch {
+            deps.log.write("warn", "project.locate-folder", {
+                projectId,
+                detail: "The verified output folder is no longer available.",
+            });
+            return problem(c, {
+                status: 404,
+                title: titleOf(404),
+                detail: "This saved output folder is no longer available.",
+            });
+        }
+    }
+    try {
+        if (!deps.openFolder)
+            throw new Error("No folder opener configured");
+        await deps.openFolder(dirname(file));
+        return c.json(folderReplySchema.parse({ opened: true }));
+    }
+    catch {
+        deps.log.write("warn", "project.open-folder", {
+            projectId,
+            detail: "The file manager could not be opened for a saved file.",
+        });
+        return problem(c, {
+            status: 503,
+            title: titleOf(503),
+            detail: "Could not open the file manager on the machine running Slopify. Make sure a desktop session is available.",
+        });
+    }
+}

package/dist/edge/http/open-folder.js

@@ -1,9 +1,9 @@
-import { dirname } from "node:path";
 import { zValidator } from "@hono/zod-validator";
 import { Hono } from "hono";
 import { z } from "zod";
 import { assetOf, findDownload } from "../../slices/storage/downloads.js";
 import { outputsOf } from "../../slices/storage/repo.js";
+import { replyForFolder } from "./folder-location.js";
 import { onInvalid, problem, titleOf } from "./problem.js";
 export function openFolderRoutes(deps) {
     return new Hono().post("/:id/open-folder", zValidator("param", z.object({
@@ -44,18 +44,6 @@ export function openFolderRoutes(deps) {
                 detail: "No saved file was found for this output. Re-run the stage if the file was removed.",
             });
         }
-        try {
-            if (deps.openFolder === undefined)
-                throw new Error("No folder opener configured");
-            await deps.openFolder(dirname(download.download.path));
-            return c.json({ opened: true });
-        }
-        catch {
-            return problem(c, {
-                status: 503,
-                title: titleOf(503),
-                detail: "Could not open the file manager on the machine running Slopify. Make sure a desktop session is available.",
-            });
-        }
+        return replyForFolder(c, deps, id, download.download.path);
     });
 }

package/dist/edge/http/projects.js

@@ -9,6 +9,7 @@ import { startRun } from "../../slices/admission/start.js";
 import { withProjectControl } from "../../slices/control/lock.js";
 import { resolveFont } from "../../slices/fonts/index.js";
 import { pickTemplates, renderPicked } from "../../slices/library/slots.js";
+import { resumable } from "../../slices/rebuild/recovery-repo.js";
 import { adoptBaseline } from "../../slices/revisions/adopt.js";
 import { currentRevisionId } from "../../slices/revisions/repo.js";
 import { deleteProject } from "../../slices/storage/delete-project.js";
@@ -142,6 +143,7 @@ export function projectRoutes(deps) {
             adoptBaseline(deps, project.id);
         return c.json({
             revisionId: currentRevisionId(deps.db, project.id) ?? null,
+            resumable: resumable(deps.db, project.id),
             project: summarise(project),
             stages: stagesOf(deps.db, project.id),
             outputs: outputsOf(deps.db, project.id),

package/dist/edge/http/revision-files.js

@@ -1,10 +1,10 @@
 import { createReadStream } from "node:fs";
-import { dirname } from "node:path";
 import { Readable } from "node:stream";
 import { zValidator } from "@hono/zod-validator";
 import { Hono } from "hono";
 import { z } from "zod";
 import { findRevisionDownload, revisionImagesZip } from "../../slices/revisions/downloads.js";
+import { replyForFolder } from "./folder-location.js";
 import { onInvalid, problem, titleOf } from "./problem.js";
 const id = z
     .string()
@@ -53,23 +53,7 @@ export function revisionFolderRoutes(deps) {
         const result = findRevisionDownload(deps, projectId, revisionId, recordId);
         if (!result.ok)
             return unavailable(c, result.reason);
-        try {
-            if (deps.openFolder === undefined)
-                throw new Error("No folder opener configured");
-            await deps.openFolder(dirname(result.download.path));
-            return c.json({ opened: true });
-        }
-        catch {
-            deps.log.write("warn", "project.open-folder", {
-                projectId,
-                detail: "The file manager could not be opened for a retained file.",
-            });
-            return problem(c, {
-                status: 503,
-                title: titleOf(503),
-                detail: "Could not open the file manager on the machine running Slopify. Make sure a desktop session is available.",
-            });
-        }
+        return replyForFolder(c, deps, projectId, result.download.path);
     });
 }
 function unavailable(c, reason) {

package/dist/kernel/db/migrations/0012-project-recovery.sql

@@ -0,0 +1,17 @@
+ALTER TABLE provider_keys ADD COLUMN credential_generation TEXT NOT NULL DEFAULT 'legacy';
+
+CREATE TABLE project_recovery_requests (
+ project_id TEXT NOT NULL,
+ idempotency_key TEXT NOT NULL,
+ request_hash TEXT NOT NULL,
+ base_revision_id TEXT NOT NULL,
+ authority_stamp TEXT NOT NULL,
+ edit_json TEXT CHECK(edit_json IS NULL OR json_valid(edit_json)),
+ intent_revision_id TEXT,
+ response_json TEXT CHECK(response_json IS NULL OR json_valid(response_json)),
+ PRIMARY KEY(project_id,idempotency_key),
+ FOREIGN KEY(project_id,base_revision_id)
+   REFERENCES project_revisions(project_id,id) ON DELETE CASCADE,
+ FOREIGN KEY(project_id,intent_revision_id)
+   REFERENCES project_revisions(project_id,id) ON DELETE CASCADE
+);

package/dist/kernel/lock.js

@@ -1,10 +1,12 @@
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+// Seconds since the epoch at which this process started, stable for its whole life.
+const startedAt = Math.round(Date.now() / 1000 - process.uptime());
 export function acquireInstanceLock(lockPath) {
     const pid = process.pid;
     if (!claim(lockPath, pid)) {
         const holder = holderOf(lockPath);
-        if (holder !== undefined && isAlive(holder)) {
-            throw new Error(`another Slopify instance is already running on this data directory (pid ${holder}). ` +
+        if (holder !== undefined && holds(holder, pid)) {
+            throw new Error(`another Slopify instance is already running on this data directory (pid ${holder.pid}). ` +
                 `Stop it, or delete ${lockPath} if it is stale.`);
         }
         // The recorded process is gone, or the file says nothing usable. Reclaiming it here
@@ -16,7 +18,8 @@ export function acquireInstanceLock(lockPath) {
     }
     return {
         release: () => {
-            if (holderOf(lockPath) === pid) {
+            const holder = holderOf(lockPath);
+            if (holder?.pid === pid && holder.startedAt === startedAt) {
                 discard(lockPath);
             }
         },
@@ -24,7 +27,7 @@ export function acquireInstanceLock(lockPath) {
 }
 function claim(lockPath, pid) {
     try {
-        writeFileSync(lockPath, `${pid}\n`, { flag: "wx", mode: 0o600 });
+        writeFileSync(lockPath, `${pid} ${startedAt}\n`, { flag: "wx", mode: 0o600 });
         return true;
     }
     catch (error) {
@@ -42,8 +45,19 @@ function holderOf(lockPath) {
     catch {
         return undefined;
     }
-    const pid = Number(contents.trim());
-    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    const [pidText = "", startText] = contents.trim().split(/\s+/);
+    const pid = Number(pidText);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    const started = startText === undefined ? undefined : Number(startText);
+    return { pid, startedAt: Number.isInteger(started) ? started : undefined };
+}
+// A lock naming this very pid is live only if this process wrote it; one from an earlier
+// process that reused the pid (a restarted container) is stale.
+function holds(holder, pid) {
+    if (holder.pid === pid)
+        return holder.startedAt === startedAt;
+    return isAlive(holder.pid);
 }
 function discard(lockPath) {
     try {

package/dist/main.js

@@ -10,6 +10,7 @@ import { createHostCliClient } from "./adapters/host-cli/index.js";
 import { nodeRunCli } from "./adapters/llm/run-cli.js";
 import { curateRegistry } from "./catalog/registry.js";
 import { createCatalogueStore } from "./catalog/store.js";
+import { dockerActivationCommitted, dockerFolderConfiguration, } from "./edge/docker-projects/activation.js";
 import { createHub } from "./edge/events/hub.js";
 import { currentProjectEvent } from "./edge/events/visibility.js";
 import { createApp } from "./edge/http/app.js";
@@ -112,6 +113,11 @@ export async function boot(config) {
     const clock = systemClock;
     const ids = ulidIds;
     const paths = layout(config.dataDir);
+    const dockerState = process.env.SLOPIFY_DOCKER_INSTALL_STATE;
+    if (dockerState !== undefined &&
+        (process.env.SLOPIFY_CONTAINER !== "1" ||
+            dockerState !== "/opt/slopify-install/activation.json"))
+        throw new Error("Invalid managed Docker activation configuration.");
     const candidateToken = process.env.SLOPIFY_UPDATE_TOKEN ?? "";
     const pendingActivation = isUpdateToken(candidateToken) && process.env.SLOPIFY_UPDATE_PENDING === "1";
     ensureDirs(paths, { mode: 0o700 });
@@ -203,7 +209,9 @@ export async function boot(config) {
                     candidate: {
                         token: candidateToken,
                         pending: pendingActivation,
-                        committed: () => updateCommitted(paths.dataDir, version, candidateToken),
+                        committed: () => dockerState === undefined
+                            ? updateCommitted(paths.dataDir, version, candidateToken)
+                            : dockerActivationCommitted(dockerState, candidateToken),
                         settle: () => {
                             try {
                                 const settled = reconcileStorage(updateDb, paths);
@@ -313,6 +321,8 @@ export async function boot(config) {
             schedules: scheduleDeps,
             ...(rebuild.measureAudio === undefined ? {} : { measureAudio: rebuild.measureAudio }),
             openFolder,
+            folderLocation: await dockerFolderConfiguration(process.env, paths.projects),
+            ...(dockerState === undefined ? {} : { installationPending: () => updater.locked() }),
             db,
             paths,
             hub,

package/dist/slices/admission/rules.js

@@ -232,3 +232,9 @@ export function narrationPreparationFields(draft) {
 function chosen(choice) {
     return choice !== undefined && choice.provider.trim() !== "" && choice.model.trim() !== "";
 }
+export function usesPronunciationGlossary(draft) {
+    return (draft.sources.audio === "generate" &&
+        draft.audio?.usePronunciationGlossary === true &&
+        draft.audio.provider === "inworld" &&
+        (draft.audio.model === "inworld-tts-2" || draft.audio.model === "inworld-tts-2-flash"));
+}

package/dist/slices/admission/schema.js

@@ -32,7 +32,9 @@ export const runDraftSchema = z.object({
         video: z.enum(stageSources),
     }),
     llm: providerChoice.optional(),
-    audio: providerChoice.extend({ voice: z.string() }).optional(),
+    audio: providerChoice
+        .extend({ voice: z.string(), usePronunciationGlossary: z.boolean().optional() })
+        .optional(),
     images: providerChoice.optional(),
     articlePrompt: z.string().optional(),
     narrationPrompt: z.string().optional(),

package/dist/slices/article/plain.js

@@ -1,14 +1,21 @@
 import { remark } from "remark";
 import remarkGfm from "remark-gfm";
 import stripMarkdown from "strip-markdown";
-// The article is stored twice, as the markdown the model wrote and as the plain text the
-// narration is read from, so no TTS voice ever says a hash or a bracket. remark parses and
-// strip-markdown drops the formatting; the GFM extension is what makes a table a table rather
-// than a paragraph full of pipes, and what takes a footnote marker out of the middle of a
-// sentence.
 export function plainText(markdown) {
-    // Built per call: a shared processor would be a module-level singleton, and building
-    // one costs a few microseconds against a call that just parsed an article.
-    const stripped = remark().use(remarkGfm).use(stripMarkdown).processSync(markdown);
-    return String(stripped);
+    const processor = remark().use(remarkGfm).use(stripMarkdown);
+    const tree = processor.runSync(processor.parse(markdown));
+    const paragraphs = tree.children
+        .map((node) => {
+        if (node.type !== "paragraph")
+            throw new Error("Expected stripped prose paragraphs.");
+        return node.children
+            .map((child) => {
+            if (child.type !== "text")
+                throw new Error("Expected stripped prose text.");
+            return child.value;
+        })
+            .join("");
+    })
+        .filter((text) => text.trim() !== "");
+    return paragraphs.length === 0 ? "" : paragraphs.join("\n\n") + "\n";
 }

package/dist/slices/control/revision-control.js

@@ -39,8 +39,8 @@ export function checkRevisionControl(deps, projectId, operation, input, response
             return { ok: true, identity: null, response: responseSchema.parse(response) };
         }
         if (db
-            .prepare("SELECT 1 FROM revision_mutations WHERE project_id=? AND idempotency_key=? UNION ALL SELECT 1 FROM rebuild_admissions WHERE project_id=? AND idempotency_key=?")
-            .get(projectId, identity.idempotencyKey, projectId, identity.idempotencyKey) !== undefined)
+            .prepare("SELECT 1 FROM revision_mutations WHERE project_id=? AND idempotency_key=? UNION ALL SELECT 1 FROM rebuild_admissions WHERE project_id=? AND idempotency_key=? UNION ALL SELECT 1 FROM project_recovery_requests WHERE project_id=? AND idempotency_key=?")
+            .get(projectId, identity.idempotencyKey, projectId, identity.idempotencyKey, projectId, identity.idempotencyKey) !== undefined)
             return { ok: false, reason: "idempotency-conflict" };
         if (head !== identity.baseRevisionId)
             return { ok: false, reason: "conflict" };

package/dist/slices/narration/pronunciation-chunks.js

@@ -0,0 +1,105 @@
+import { fingerprint } from "../../kernel/runner/work.js";
+import { chunkNarration, defaultChunkCharacters, defaultChunkWords, } from "./chunk.js";
+import { pronunciationMatches } from "./pronunciation.js";
+export function pronunciationChunks(source, chunking, entries, overriddenKeys = new Set(), sources = {}) {
+    const occurrences = new Map();
+    const usedKeys = new Set();
+    const nextKey = (text) => {
+        const hash = fingerprint(text).slice(0, 20);
+        let occurrence = (occurrences.get(hash) ?? 0) + 1;
+        while (usedKeys.has(`audio:body:${hash}-${occurrence}`))
+            occurrence++;
+        occurrences.set(hash, occurrence);
+        const key = `audio:body:${hash}-${occurrence}`;
+        usedKeys.add(key);
+        return key;
+    };
+    let offset = 0;
+    const chunks = chunkNarration(source, chunking).map((text) => {
+        const start = source.indexOf(text, offset);
+        if (start < 0)
+            throw new Error("Narration chunk is missing from its source.");
+        offset = start + text.length;
+        return { key: nextKey(text), text, start, end: offset };
+    });
+    const bodyFingerprint = fingerprint(source);
+    const chunkingFingerprint = fingerprint([
+        chunking.mode,
+        chunking.mode === "words"
+            ? (chunking.words ?? defaultChunkWords)
+            : chunking.mode === "characters"
+                ? (chunking.characters ?? defaultChunkCharacters)
+                : null,
+    ]);
+    const starts = new Map(chunks.map((chunk, index) => [chunk.start, index]));
+    const ends = new Map(chunks.map((chunk, index) => [chunk.end, index]));
+    const pinned = new Map();
+    let lastPinned = -1;
+    for (const [key, saved] of Object.entries(sources).sort((a, b) => a[1].start - b[1].start)) {
+        const first = starts.get(saved.start);
+        const last = ends.get(saved.start + saved.text.length);
+        if (saved.bodyFingerprint !== bodyFingerprint ||
+            saved.chunkingFingerprint !== chunkingFingerprint ||
+            source.slice(saved.start, saved.start + saved.text.length) !== saved.text ||
+            !new RegExp(`^audio:body:${fingerprint(saved.text).slice(0, 20)}-[1-9][0-9]*$`, "u").test(key) ||
+            first === undefined ||
+            last === undefined ||
+            first <= lastPinned ||
+            last <= first ||
+            chunks.slice(first, last + 1).some((chunk) => overriddenKeys.has(chunk.key)))
+            continue;
+        pinned.set(first, { key, source: saved, last });
+        usedKeys.add(key);
+        lastPinned = last;
+    }
+    const blocked = [
+        ...chunks.filter((chunk) => overriddenKeys.has(chunk.key)),
+        ...[...pinned.values()].map((row) => ({
+            start: row.source.start,
+            end: row.source.start + row.source.text.length,
+        })),
+    ].sort((a, b) => a.start - b.start);
+    let blockedIndex = 0;
+    const matches = pronunciationMatches(source, entries).filter((match) => {
+        while ((blocked[blockedIndex]?.end ?? Infinity) <= match.start)
+            blockedIndex++;
+        return (blocked[blockedIndex]?.start ?? Infinity) >= match.end;
+    });
+    const result = [];
+    let from = 0;
+    let matchIndex = 0;
+    for (let index = 0; index < chunks.length; index++) {
+        const sticky = pinned.get(index);
+        if (sticky !== undefined) {
+            result.push({ key: sticky.key, text: sticky.source.text, source: sticky.source });
+            index = sticky.last;
+            from = index + 1;
+            continue;
+        }
+        const chunk = chunks[index];
+        if (chunk === undefined)
+            throw new Error("Narration chunk disappeared.");
+        while ((matches[matchIndex]?.end ?? Infinity) <= chunk.end)
+            matchIndex++;
+        const match = matches[matchIndex];
+        const next = chunks[index + 1];
+        if (next !== undefined &&
+            match !== undefined &&
+            match.start < chunk.end &&
+            next.start < match.end)
+            continue;
+        const first = chunks[from];
+        if (first === undefined)
+            throw new Error("Narration group has no first chunk.");
+        const text = source.slice(first.start, chunk.end);
+        result.push(from === index
+            ? { key: chunk.key, text }
+            : {
+                key: nextKey(text),
+                text,
+                source: { text, start: first.start, bodyFingerprint, chunkingFingerprint },
+            });
+        from = index + 1;
+    }
+    return result;
+}