@gentbajko/slopify 0.1.0 → 0.2.0

package/dist/slices/images/run.js

@@ -7,13 +7,13 @@ import { projectById, setStageProgress } from "../admission/repo.js";
 import { outputFileName, outputPath } from "../storage/layout.js";
 import { insertOutput, outputsOf } from "../storage/repo.js";
 // What an image piece carries between runs: what was asked for, and the file it came back
-// as once the provider answered. That is the whole of the resume of §Q73.
+// as once the provider answered. That is the whole of the resume.
 const imagePayload = z.object({
     promptName: z.string(),
     prompt: z.string(),
     // Which ticked prompt this send belongs to, and which send of that prompt it is. Both
-    // are stored rather than derived, because §Q75 lets the user delete an image and the
-    // pieces that are left must still say where each one came from.
+    // are stored rather than derived, because the user can delete an image and the pieces
+    // that are left must still say where each one came from.
     promptIndex: z.number(),
     indexInPrompt: z.number(),
     file: z.string().optional(),
@@ -26,27 +26,25 @@ export async function runImages(deps, context, providers) {
     }
     const choice = project.config.images;
     if (choice === undefined) {
-        // Admission refuses a run whose images are Generate without a provider and a model
-        // (`logic/04` step 2), so reaching here is a bug in admission rather than the user's.
+        // Admission refuses a run whose images are Generate without a provider and a model, so
+        // reaching here is a bug in admission rather than the user's.
         throw new Error("the run has no image provider or model");
     }
     const pieces = plan(deps, context, project.config);
     if (pieces.length === 0) {
-        // `logic/04` §Q31 makes an image source mandatory and step 3 puts the Number at one
-        // or more, so an empty plan is a bug upstream rather than a run with no pictures.
+        // Admission makes an image source mandatory and puts the Number at one or more, so an
+        // empty plan is a bug upstream rather than a run with no pictures.
         throw new Error("the run ticked no image prompt");
     }
-    // Step 1: the run's own frame. The adapter turns it into whatever its provider spells
-    // the closest supported size, and `logic/11` step 4 crops whatever is left over.
+    // The run's own frame. The adapter turns it into whatever its provider spells the
+    // closest supported size, and the render crops whatever is left over.
     const made = await sendAll(deps, context, providers, choice, pieces, project.format);
-    // logic/16 step 3: "images made (stored images)". Only the ones this run stored, so a
-    // resume does not count an image the previous run made (§Q73) and a single regenerated
-    // image counts as one (§Q103, scenario 12: "regenerations count again").
+    // Images made means images stored, and only the ones this run stored: a resume does not
+    // count an image the previous run made, and a regenerated image counts again.
     //
     // ceiling: a run that fails partway records nothing, so the images it did store are
-    // counted by no event and the resume counts only its own. logic/16 step 2 puts one
-    // event on the stage completing; the upgrade, if the drift ever matters, is an event
-    // per image.
+    // counted by no event and the resume counts only its own. One event is written when the
+    // stage completes; the upgrade, if the drift ever matters, is an event per image.
     deps.count("stage.completed", {
         stage: "images",
         provider: choice.provider,
@@ -59,12 +57,12 @@ export async function runImages(deps, context, providers) {
         detail: `${String(pieces.length)} images from ${String(project.config.imagePrompts.length)} prompts`,
     });
 }
-// Step 2 with `logic/04` §Q30: "for each ticked image prompt, send its rendered text
-// Number times as independent parallel calls". The plan is made once and kept, so a retry
-// finds the rows the first run wrote and sends only what did not land (§Q73).
+// For each ticked image prompt, its rendered text is sent Number times as independent
+// parallel calls. The plan is made once and kept, so a retry finds the rows the first run
+// wrote and sends only what did not land.
 //
-// `idx` is the slideshow order of §Q72 - prompts in selection order, then the index within
-// each prompt - so the order is fixed here and never depends on which image arrives first.
+// `idx` is the slideshow order - prompts in selection order, then the index within each
+// prompt - so the order is fixed here and never depends on which image arrives first.
 function plan(deps, context, config) {
     const existing = piecesOf(deps.db, context.stage.id, "image");
     if (existing.length > 0) {
@@ -73,7 +71,7 @@ function plan(deps, context, config) {
     const planned = [];
     for (const [at, picked] of config.imagePrompts.entries()) {
         // `slices/library/slots.ts` names the rendered body after the draft field that picked
-        // it, so the run carries the substituted text under this key (`logic/03`).
+        // it, so the run carries the substituted text under this key.
         const prompt = config.rendered[`imagePrompts.${String(at)}`];
         if (prompt === undefined) {
             throw new Error(`the run has no rendered text for the image prompt ${picked.name}`);
@@ -101,9 +99,9 @@ function plan(deps, context, config) {
     });
     return planned;
 }
-// §Q73: an image a previous run stored is not made again, and one that fails fails the
+// An image a previous run stored is not made again, and one that fails takes down the
 // whole stage while its siblings finish and keep their images for the next resume. A
-// refusal is the wrapper's to make terminal (§Q74); nothing here counts attempts.
+// refusal is the wrapper's to make terminal; nothing here counts attempts.
 async function sendAll(deps, context, providers, choice, pieces, format) {
     const { projectId } = context.stage;
     // Read once, before anything is written: a piece counts as landed only when its row and
@@ -126,21 +124,21 @@ async function sendAll(deps, context, providers, choice, pieces, format) {
                 aspect: format,
             });
             const file = keep(deps, projectId, piece.idx, made);
-            // §Q76: the prompt text, the prompt name, the index within the prompt, the
+            // The prompt text, the prompt name, the index within the prompt, the
             // provider and the model travel with the image.
             const output = record(deps, projectId, piece, asked, file, made, choice);
             // The row and the file are both there before the piece says so: a crash between
             // them leaves a piece that is not `done`, which the next run simply sends again.
             setPiece(deps.db, piece.id, "done", JSON.stringify({ ...asked, file }));
             done += 1;
-            // Step 3: the project page fills in as each one arrives.
+            // The project page fills in as each one arrives.
             context.emit({ type: "image.landed", projectId, outputId: output.id, index: piece.idx });
             report(deps, context, done, total);
             return { ok: true, made: true };
         }
         catch (error) {
-            // A cancel is not this image failing: `logic/13` §Q112 counts an aborted call as
-            // nothing, and the resume runs a `pending` image exactly as a failed one.
+            // A cancel is not this image failing: an aborted call counts as nothing, and the
+            // resume runs a `pending` image exactly as a failed one.
             setPiece(deps.db, piece.id, context.signal.aborted ? "pending" : "failed", piece.payload);
             return { ok: false, error };
         }
@@ -156,8 +154,8 @@ async function sendAll(deps, context, providers, choice, pieces, format) {
 }
 // An image counts as landed only when its row and its file are both still there: they are
 // written one after the other, the boot reconcile can remove a file whose row survived,
-// and §Q75 lets the user delete one on purpose. Answering "done" for a missing file would
-// hand the render a path to nothing.
+// and the user can delete one on purpose. Answering "done" for a missing file would hand
+// the render a path to nothing.
 function landed(deps, projectId, piece, stored) {
     const file = payloadOf(piece).file;
     if (file === undefined) {
@@ -169,7 +167,7 @@ function landed(deps, projectId, piece, stored) {
     return existsSync(outputPath(deps.paths, projectId, file));
 }
 function keep(deps, projectId, idx, made) {
-    // Step 3: "stored as received (png or jpg)". The adapter read the mime off the bytes,
+    // Stored as received, png or jpg. The adapter read the mime off the bytes,
     // so the extension is what the file actually is rather than what a header claimed.
     const name = outputFileName("image", idx, made.mime === "image/png" ? ".png" : ".jpg", "images");
     const target = outputPath(deps.paths, projectId, name);
@@ -187,8 +185,8 @@ function record(deps, projectId, piece, asked, file, made, choice) {
         originalFilename: null,
         bytes: made.bytes.byteLength,
         durationMs: null,
-        // `index` is the slideshow place `logic/11` sorts on, and it is the piece's own `idx`
-        // rather than the order the images came back in (§Q72).
+        // `index` is the slideshow place the render sorts on, and it is the piece's own `idx`
+        // rather than the order the images came back in.
         meta: {
             index: piece.idx,
             promptName: asked.promptName,
@@ -201,8 +199,8 @@ function record(deps, projectId, piece, asked, file, made, choice) {
     insertOutput(deps.db, output);
     return output;
 }
-// `logic/01` §Q6: "k of N images made". Written as well as emitted, so a page opened
-// mid-stage reads the count off the row rather than waiting for the next image.
+// K of N images made. Written as well as emitted, so a page opened mid-stage reads the count
+// off the row rather than waiting for the next image.
 function report(deps, context, done, total) {
     setStageProgress(deps.db, context.stage.id, done, total);
     context.emit({

package/dist/slices/library/lint.js

@@ -1,6 +1,6 @@
-// What `logic/15` step 2 asks of a save: a name, a body, and no lint error. The slot
-// grammar is not restated here - it is admission/substitute.ts's, imported so the editor
-// and the run see the same parse of the same body.
+// What a save has to carry: a name, a body and no lint error. The slot grammar is not
+// restated here - it is admission/substitute.ts's, imported so the editor and the run see
+// the same parse of the same body.
 import { detectSlots } from "../admission/substitute.js";
 import { bodyMax, nameMax } from "./model.js";
 export function lintPrompt(draft) {

package/dist/slices/library/model.js

@@ -1,13 +1,13 @@
-// The two template libraries `logic/15` governs: prompts of three kinds, and the
-// intro/outro entries. §Q121 puts one rule set over both, which is why the drafts, the
-// lint and the save path below are shared rather than mirrored.
+// The two template libraries: prompts of three kinds, and the intro/outro entries. One rule
+// set covers both, which is why the drafts, the lint and the save path below are shared
+// rather than mirrored.
 export { entryModes } from "../admission/model.js";
-// mockup §Q6 and §Q13; the CHECK constraint on `prompts.kind` holds the same three.
+// The CHECK constraint on `prompts.kind` holds the same three.
 export const promptKinds = ["article", "image", "thumbnail"];
 export const entryCategories = ["intro", "outro"];
 // The name is what the Play pickers show, so it shares admission's title bound.
 export const nameMax = 200;
-// ceiling: `logic/15` sets no length for a body, and the §Q6 sample article prompt is
-// already a page long. This is a sanity bound on a trust boundary, not a product rule;
-// raising it is a one-line change with no schema consequence.
+// ceiling: nothing sets a length for a body, and the sample article prompt is already a
+// page long. This is a sanity bound on a trust boundary, not a product rule; raising it is
+// a one-line change with no schema consequence.
 export const bodyMax = 100_000;

package/dist/slices/library/repo.js

@@ -23,12 +23,12 @@ const slotsColumn = z.array(z.string());
 // `lower(name)` and not `name COLLATE NOCASE`: it is the expression the unique indexes
 // are built on, so a lookup by name reads the index instead of the table.
 const byName = "lower(name) = lower(?)";
-// `logic/15` step 5: the lists on 04 Prompts and the pickers on Play sort by name.
+// The lists on 04 Prompts and the pickers on Play sort by name.
 const byNameOrder = "ORDER BY lower(name)";
 export function insertPrompt(db, prompt) {
     db.prepare("INSERT INTO prompts (id, kind, name, body, slots, updated_at) VALUES (?, ?, ?, ?, ?, ?)").run(prompt.id, prompt.kind, prompt.name, prompt.body, JSON.stringify(prompt.slots), prompt.updatedAt);
 }
-// §Q122: the kind may change after creation, so the update writes it like any other
+// The kind may change after creation, so the update writes it like any other
 // column. Returns false when no row has that id.
 export function replacePrompt(db, prompt) {
     const result = db
@@ -36,7 +36,7 @@ export function replacePrompt(db, prompt) {
         .run(prompt.kind, prompt.name, prompt.body, JSON.stringify(prompt.slots), prompt.updatedAt, prompt.id);
     return Number(result.changes) > 0;
 }
-// §Q123: no foreign key points at this row, so a project that used the template keeps
+// No foreign key points at this row, so a project that used the template keeps
 // its own rendered text and nothing cascades.
 export function deletePrompt(db, id) {
     return Number(db.prepare("DELETE FROM prompts WHERE id = ?").run(id).changes) > 0;

package/dist/slices/library/save.js

@@ -1,5 +1,5 @@
-// Creating, editing and deleting a template (`logic/15`). One rule set covers prompts
-// and entries (§Q121), so both go through the same three outcomes.
+// Creating, editing and deleting a template. One rule set covers prompts
+// and entries, so both go through the same three outcomes.
 import { isUniqueConstraint } from "../../kernel/db/index.js";
 import { detectSlots } from "../admission/substitute.js";
 import { lintEntry, lintPrompt } from "./lint.js";
@@ -15,7 +15,7 @@ export function createPrompt(deps, draft) {
         return true;
     }, prompt);
 }
-// §Q125: a save overwrites; there is no version history, so the row is replaced whole.
+// A save overwrites; there is no version history, so the row is replaced whole.
 export function updatePrompt(deps, id, draft) {
     const fields = lintPrompt(draft);
     if (fields.length > 0) {
@@ -70,10 +70,10 @@ function entryOf(deps, draft) {
         updatedAt: deps.clock.now().toISOString(),
     };
 }
-// §Q122's uniqueness is the schema's: `prompts(kind, lower(name))` and
-// `entries(category, lower(name))`. A read-then-write check would answer from a row a
-// second writer could delete between the two statements, so the index decides and the
-// raw SQLite error never leaves this module.
+// Uniqueness is the schema's: `prompts(kind, lower(name))` and `entries(category,
+// lower(name))`. A read-then-write check would answer from a row a second writer could
+// delete between the two statements, so the index decides and the raw SQLite error never
+// leaves this module.
 function written(write, value) {
     try {
         return write() ? { ok: true, value } : { ok: false, reason: "not-found" };

package/dist/slices/library/slots.js

@@ -1,13 +1,13 @@
 // What a run needs from the library at the moment Play is pressed: the saved bodies of
 // the picked templates, the slot names they ask for, and the rendered text stored on the
-// project. `logic/04` §Q34 fixes the timing - the bodies are read at the click, not at
-// selection, so an edit made in between is the one that runs.
+// project. The bodies are read at the click, not at selection, so an edit made in between
+// is the one that runs.
 import { collectFields, render } from "../admission/substitute.js";
 import { entryByName, promptByName } from "./repo.js";
 export function pickTemplates(db, draft) {
     const { sources } = draft;
     const missing = [];
-    // `logic/03` step 3: only the prompts of stages set to Generate, plus the picked
+    // Only the prompts of stages set to Generate, plus the picked
     // entries. A prompt left selected on a stage set to Provide asks for no field.
     const text = [];
     const image = [];
@@ -25,7 +25,7 @@ export function pickTemplates(db, draft) {
         }
     }
     // Both Generate modes read the same thumbnail template; Prompt by LLM sends it as the
-    // instruction rather than to the image provider (`logic/10` step 1).
+    // instruction rather than to the image provider.
     if (sources.thumbnail === "from_prompt" || sources.thumbnail === "prompt_by_llm") {
         body(db, "thumbnail", draft.thumbnailPrompt, "thumbnailPrompt", missing, image, "thumbnailPrompt");
     }
@@ -37,7 +37,7 @@ export function pickTemplates(db, draft) {
         missing,
     };
 }
-// `logic/03` step 5 and step 6: every picked body rendered once, with the trimmed values
+// Every picked body rendered once, with the trimmed values
 // admission has already accepted, and stored on the project.
 export function renderPicked(picked, values) {
     const rendered = {};

package/dist/slices/narration/chunk.js

@@ -1,14 +1,14 @@
-// `logic/08` step 2, the run's chunking choice: "Whole text = one request; Per paragraph
-// = one request per paragraph; Every ~N words = consecutive chunks, each ending at the
-// last sentence boundary at or before N words, default N = 500 (§Q69)."
+// The run's chunking choice: whole text is one request, per paragraph is one request per
+// paragraph, and every ~N words is consecutive chunks each ending at the last sentence
+// boundary at or before N words, N defaulting to 500.
 //
-// Pure, and the only place the rule lives: 03-conventions puts chunking with substitution
-// and the render plan in the functional core, so it is testable with no I/O at all and
-// `run.ts` does nothing but call it.
+// Pure, and the only place the rule lives. Chunking sits in the functional core beside
+// substitution and the render plan, so it is testable with no I/O and `run.ts` does nothing
+// but call it.
 export const chunkModes = ["whole", "paragraph", "words"];
 export const defaultChunkWords = 500;
 // A run created before Play carried the control sends the whole text as one request,
-// which is step 2's first case and the one that adds nothing the user did not ask for.
+// which is the first case and the one that adds nothing the user did not ask for.
 export const defaultChunking = { mode: "whole" };
 // A run of blank lines is one paragraph break, not several, and a line of nothing but
 // spaces between two paragraphs is still a break: strip-markdown output is full of both.
@@ -37,8 +37,8 @@ function wordRuns(text, budget) {
     let count = 0;
     for (const sentence of sentences(text)) {
         const words = wordsIn(sentence);
-        // "the last sentence boundary at or before N words": the sentence that would push the
-        // count past the budget starts the next chunk instead of being split.
+        // The last sentence boundary at or before N words: the sentence that would push the count
+        // past the budget starts the next chunk instead of being split.
         if (count > 0 && count + words > limit) {
             chunks.push(current);
             current = "";
@@ -48,9 +48,9 @@ function wordRuns(text, budget) {
         count += words;
     }
     chunks.push(current);
-    // A single sentence longer than the budget lands here whole, on its own: §Q69 caps
-    // nothing, and a cut inside a clause would be an audible pause the writer never wrote.
-    // The provider's own per-request limit is what refuses it, as an error on the stage.
+    // A single sentence longer than the budget lands here whole, on its own: a cut inside a
+    // clause would be an audible pause the writer never wrote. The provider's own per-request
+    // limit is what refuses it, as an error on the stage.
     return nonEmpty(chunks);
 }
 // ceiling: segmented as English. `Intl.Segmenter` is the platform's own sentence breaker

package/dist/slices/narration/concat.js

@@ -26,14 +26,13 @@ export function concatArgs(listPath, output) {
         // video stream in the narration.
         "-map",
         "0:a:0",
-        // Re-encoded rather than stream-copied. A copy joins frame runs that each carry their
-        // own encoder delay and padding, which is the click and the drift at every join:
-        // three chunks of 1200, 700 and 450 ms copy to 2409 ms and decode to 2350 ms through
-        // here, exactly the sum. §Q68 hands that number to the video timeline, so it has to
-        // be the real one. No `-ar`: §Q65 keeps the provider's own sample rate.
-        // ceiling: one re-encode at the bitrate the adapters ask the providers for. Storing
-        // the chunks as wav and encoding once at the end would avoid even that generation,
-        // and costs about ten times the disk while a stage is running.
+        // Re-encoded rather than stream-copied. A copy joins frame runs that each carry their own
+        // encoder delay and padding, which is the click and the drift at every join: three chunks
+        // of 1200, 700 and 450 ms copy to 2409 ms and decode to 2350 ms through here, exactly the
+        // sum. That number goes to the video timeline, so it has to be the real one. No `-ar`: the
+        // provider's own sample rate is kept. ceiling: one re-encode at the bitrate the adapters
+        // ask the providers for. Storing the chunks as wav and encoding once at the end would avoid
+        // even that generation, and costs about ten times the disk while a stage is running.
         "-c:a",
         "libmp3lame",
         "-b:a",
@@ -41,12 +40,12 @@ export function concatArgs(listPath, output) {
         output,
     ];
 }
-// The body audio and its measured duration. §Q68: the duration is measured, never
-// estimated, because `logic/11` builds the video timeline out of it.
+// The body audio and its measured duration - measured, never estimated, because the video
+// timeline is built out of it.
 export async function joinNarration(deps, input) {
     const first = input.files[0];
     if (first === undefined) {
-        // The stage refuses an empty narration before it gets here (§Q67), so this is a bug.
+        // The stage refuses an empty narration before it gets here, so this is a bug.
         throw new Error("there are no audio chunks to join");
     }
     mkdirSync(dirname(input.output), { recursive: true, mode: 0o700 });
@@ -73,7 +72,7 @@ export async function joinNarration(deps, input) {
         }
     }
     // Measured off a full decode of the file that was written, not off the parts: a
-    // container header can carry an estimate, and `logic/11` step 1 adds this number to the
-    // gaps to get the length of the video.
+    // container header can carry an estimate, and the render adds this number to the gaps to
+    // get the length of the video.
     return probeDurationMs(deps.bin, input.output, input.signal, deps.log);
 }

package/dist/slices/narration/run.js

@@ -11,24 +11,23 @@ import { insertOutput, outputsOf } from "../storage/repo.js";
 import { probeDurationMs } from "../video/ffmpeg.js";
 import { chunkNarration, defaultChunking } from "./chunk.js";
 import { joinNarration } from "./concat.js";
-// §Q67, verbatim: an empty narration source is an "immediate stage failure 'nothing to
-// narrate', no retries". Thrown from the slice rather than from a provider call, so the
-// attempt wrapper never sees it and nothing is retried.
+// An empty narration source fails the stage immediately with no retries. Thrown from the
+// slice rather than from a provider call, so the attempt wrapper never sees it.
 export const nothingToNarrate = "nothing to narrate";
 // What a chunk piece carries between runs: the text that was sent, and the file it came
-// back as once the provider answered. That is the whole of the resume of §Q66.
+// back as once the provider answered. That is the whole of the resume.
 const chunkPayload = z.object({ text: z.string(), file: z.string().optional() });
-// What the article stage left on its `segment` pieces (`logic/07` step 5).
+// What the article stage left on its `segment` pieces.
 const segmentPayload = z.object({
     category: z.enum(entryCategories),
     name: z.string(),
     mode: z.enum(entryModes),
     text: z.string(),
 });
-// The chunk audio sits in a folder of its own under the project. It is not an output:
-// §Q65's invariant makes the concatenated body plus the picked intro and outro "the
-// project's only audio outputs", so the pieces name these files and the boot reconcile
-// keeps them by that name (`slices/storage/reconcile.ts`).
+// The chunk audio sits in a folder of its own under the project. It is not an output: the
+// concatenated body plus the picked intro and outro are the project's only audio outputs,
+// so the pieces name these files and the boot reconcile keeps them by that name
+// (`slices/storage/reconcile.ts`).
 const chunkDir = "audio-chunks";
 export async function runNarration(deps, context, providers) {
     const { projectId } = context.stage;
@@ -38,16 +37,15 @@ export async function runNarration(deps, context, providers) {
     }
     const choice = project.config.audio;
     if (choice === undefined) {
-        // Admission refuses a run whose audio is Generate without a provider and a voice
-        // (`logic/04`), so reaching here is a bug in admission rather than something the user
-        // did.
+        // Admission refuses a run whose audio is Generate without a provider and a voice, so
+        // reaching here is a bug in admission rather than something the user did.
         throw new Error("the run has no TTS provider or voice");
     }
     // Read once, before anything is written: the segment steps below ask it what a previous
     // run already stored, and the body step is the only thing that adds to it.
     const outputs = outputsOf(deps.db, projectId);
-    // Step 2. The end matter is already out of this text: the article stage cut it into
-    // files of its own (§Q63, `logic/07` step 4), so nothing here can narrate a sources list.
+    // The end matter is already out of this text: the article stage cut it into
+    // files of its own, so nothing here can narrate a sources list.
     const chunking = project.config.chunking ?? defaultChunking;
     const texts = chunkNarration(narrationSource(deps, outputs, projectId), chunking);
     if (texts.length === 0) {
@@ -62,8 +60,8 @@ export async function runNarration(deps, context, providers) {
         detail: `${String(texts.length)} chunks in ${chunking.mode} mode`,
     });
 }
-// The narration source of §Q37 and `logic/07` step 4: the plain-text article, written by
-// the article stage or pasted in by a user whose article stage was set to Provide.
+// The narration source: the plain-text article, written by the article stage or pasted in
+// by a user whose article stage was set to Provide.
 function narrationSource(deps, outputs, projectId) {
     const article = outputs.find((output) => output.role === "article_txt");
     if (article === undefined) {
@@ -72,7 +70,7 @@ function narrationSource(deps, outputs, projectId) {
     return readFileSync(outputPath(deps.paths, projectId, article.path), "utf8");
 }
 // The chunk list, planned once and kept. A retry after a failure finds the rows the first
-// run wrote and narrates only the ones that did not finish (§Q66).
+// run wrote and narrates only the ones that did not finish.
 function plan(deps, context, texts) {
     const existing = piecesOf(deps.db, context.stage.id, "chunk");
     if (existing.length > 0) {
@@ -93,9 +91,9 @@ function plan(deps, context, texts) {
     });
     return planned;
 }
-// Step 3: "Synthesize every chunk in parallel". §Q66: a chunk a previous run finished is
-// not spoken again, and one that fails fails the whole stage while its siblings finish
-// and keep their audio for the next resume.
+// Every chunk is synthesized in parallel. A chunk a previous run finished is not spoken
+// again, and one that fails takes down the whole stage while its siblings finish and keep their
+// audio for the next resume.
 async function speakChunks(deps, context, providers, choice, pieces) {
     const { projectId } = context.stage;
     const total = pieces.length;
@@ -125,8 +123,8 @@ async function speakChunks(deps, context, providers, choice, pieces) {
             return { ok: true, file };
         }
         catch (error) {
-            // A cancel is not this chunk failing: `logic/13` §Q112 counts an aborted call as
-            // nothing, and the resume runs a `pending` chunk exactly as a failed one.
+            // A cancel is not this chunk failing: an aborted call counts as nothing, and the
+            // resume runs a `pending` chunk exactly as a failed one.
             setPiece(deps.db, piece.id, context.signal.aborted ? "pending" : "failed", piece.payload);
             return { ok: false, error };
         }
@@ -140,7 +138,7 @@ async function speakChunks(deps, context, providers, choice, pieces) {
     }
     return files;
 }
-// Steps 4 and 6: one body file, in chunk order, with its measured duration on the row.
+// One body file, in chunk order, with its measured duration on the row.
 async function storeBody(deps, context, choice, files, outputs) {
     const { projectId } = context.stage;
     if (outputs.some((output) => output.role === "audio_body")) {
@@ -155,29 +153,29 @@ async function storeBody(deps, context, choice, files, outputs) {
         output: outputPath(deps.paths, projectId, name),
         signal: context.signal,
     });
-    // `logic/13` §Q113 protects an output already stored, not one about to be: a cancel
-    // landing between ffmpeg exiting and the row below leaves nothing recorded.
+    // A cancel protects an output already stored, not one about to be: one landing between
+    // ffmpeg exiting and the row below leaves nothing recorded.
     context.signal.throwIfAborted();
     store(deps, projectId, "audio_body", name, durationMs, choice);
     counted(deps, "body", durationMs, choice);
 }
-// Step 5: "each picked segment's text is one TTS request with the same provider and
-// voice, stored as its own audio file with its duration; body chunking does not apply to
-// them" (§Q93). The text is whatever the article stage wrote onto the segment piece: an
-// LLM-mode entry's answer, or a text-mode entry's rendered body, spoken verbatim.
+// Each picked segment's text is one TTS request with the same provider and voice, stored as
+// its own audio file with its duration; body chunking does not apply to them. The text is
+// whatever the article stage wrote onto the segment piece: an LLM-mode entry's answer, or a
+// text-mode entry's rendered body, spoken verbatim.
 async function speakSegments(deps, context, providers, choice, outputs) {
     const { projectId } = context.stage;
     for (const piece of segmentPieces(deps, projectId)) {
         const segment = segmentOf(piece);
         const role = segment.category === "intro" ? "audio_intro" : "audio_outro";
         if (outputs.some((output) => output.role === role)) {
-            // Spoken by a previous run of this stage; §Q66's resume keeps it.
+            // Spoken by a previous run of this stage; the resume keeps it.
             continue;
         }
         const text = segment.text.trim();
         if (text === "") {
-            // §Q67's rule, applied to a segment: there is nothing to say, and silently dropping
-            // an intro the user picked would lose it without telling anyone.
+            // The same rule, applied to a segment: there is nothing to say, and silently
+            // dropping an intro the user picked would lose it without telling anyone.
             throw new Error(`the ${segment.category} segment has ${nothingToNarrate}`);
         }
         const spoken = await providers.forPiece(piece.id).tts({
@@ -187,33 +185,32 @@ async function speakSegments(deps, context, providers, choice, outputs) {
         });
         const name = outputFileName(role, 1, ".mp3", "audio");
         write(deps, projectId, name, spoken.bytes);
-        // Measured the same way the body is, because `logic/11` step 1 adds all three and the
-        // gaps to get the length of the video (§Q68).
+        // Measured the same way the body is, because the render adds all three and the gaps to
+        // get the length of the video.
         const durationMs = await probeDurationMs(deps.ffmpeg, outputPath(deps.paths, projectId, name), context.signal, deps.log);
         context.signal.throwIfAborted();
         store(deps, projectId, role, name, durationMs, choice);
         counted(deps, segment.category, durationMs, choice);
     }
 }
-// The segment pieces belong to the *article* stage, which is where `logic/07` step 5
-// writes them, so they are read under its id and never under this stage's own. They stay
-// there because `logic/12` is what depends on it: a Re-run audio (step 2) and the audio
-// re-run an article edit cascades into (step 1) both clear the audio stage's pieces, and
-// only the article stage ever writes an entry text - so an intro kept on this stage's row
-// would be thrown away by the first re-narration and never written again.
+// The segment pieces belong to the *article* stage, which is where they are written, so
+// they are read under its id and never under this stage's own. They stay there because the
+// re-run rules depend on it: a Re-run audio, and the audio re-run an article edit cascades
+// into, both clear the audio stage's pieces, and only the article stage ever writes an
+// entry text - so an intro kept on this stage's row would be thrown away by the first
+// re-narration and never written again.
 function segmentPieces(deps, projectId) {
     const article = stagesOf(deps.db, projectId).find((stage) => stage.kind === "article");
     if (article === undefined) {
-        // Admission writes all six stage rows with the project (`logic/04` step 6), so a
-        // project without an article stage is a bug rather than a run the user configured.
+        // Admission writes all six stage rows with the project, so a project without an article
+        // stage is a bug rather than a run the user configured.
         throw new Error(`project ${projectId} has no article stage`);
     }
     return piecesOf(deps.db, article.id, "segment");
 }
-// logic/16 step 3: "audio seconds from the measured duration per segment". The measured
-// one, not the text's length: `logic/08` §Q68 puts the real duration on the row and
-// `logic/11` builds the timeline from it. No model is named because the TTS port carries
-// none - the same reason `store` above leaves it off the output row.
+// Audio seconds come from the measured duration per segment, never from the text's length:
+// the real duration goes on the row and the video timeline is built from it. No model is
+// named because the TTS port carries none - the same reason `store` above leaves it off.
 function counted(deps, segment, durationMs, choice) {
     deps.count("stage.completed", {
         stage: "audio",
@@ -222,8 +219,8 @@ function counted(deps, segment, durationMs, choice) {
         audioSeconds: durationMs / 1000,
     });
 }
-// Step 5: "k of N chunks narrated". Written as well as emitted, so a page opened mid-stage
-// reads the count off the row rather than waiting for the next chunk.
+// K of N chunks narrated, written as well as emitted, so a page opened mid-stage reads the
+// count off the row rather than waiting for the next chunk.
 function report(deps, context, done, total) {
     setStageProgress(deps.db, context.stage.id, done, total);
     context.emit({
@@ -249,7 +246,7 @@ function write(deps, projectId, path, bytes) {
     mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
     writeFileSync(target, bytes, { mode: 0o600 });
 }
-// §Q68: the provider and the voice are stored with the audio they made. The model is not:
+// The provider and the voice are stored with the audio they made. The model is not:
 // the TTS port carries no model, so every request went to the adapter's own, and writing
 // the run's dropdown value here would record something that was never sent.
 function store(deps, projectId, role, path, durationMs, choice) {