@gentbajko/slopify 0.1.0 → 0.2.0

package/dist/main.js

@@ -81,7 +81,7 @@ export async function boot(config) {
             probe: nodeCliProbe,
         });
         const server = await listen(app, config, log);
-        // logic/16 step 5: whatever last run left queued goes out at start. Nothing waits for
+        // Whatever last run left queued goes out at start. Nothing waits for
         // it, and an unreachable collector costs one refused socket.
         flusher.soon();
         const open = db;
@@ -101,7 +101,7 @@ export async function boot(config) {
                     // The pending timer is cancelled rather than awaited: a shutdown must not wait
                     // on the collector. A flush already in flight may land after the database
                     // closes and fail to mark its batch delivered, which costs one re-send that
-                    // the collector deduplicates by event id (logic/16 §Q134).
+                    // the collector deduplicates by event id.
                     flusher.stop();
                     log.write("info", "shutdown");
                     open.close();
@@ -120,9 +120,9 @@ function wire({ db, paths, clock, ids, log, hub, telemetry, flusher, registry })
     // Resolved once at boot rather than per render, so a machine with no usable binary
     // fails at start with one message instead of on every project's last stage.
     const ffmpeg = resolveFfmpeg(process.env, ffmpegStatic);
-    // logic/16 steps 2 and 5: a stage counts what it did and the queue is flushed after
-    // each new event. `record` swallows its own failures, so this can neither fail a stage
-    // nor widen what leaves the machine - the payload allow-list is checked inside it.
+    // A stage counts what it did and the queue is flushed after each new event. `record`
+    // swallows its own failures, so this can neither fail a stage nor widen what leaves the
+    // machine - the payload allow-list is checked inside it.
     const count = (type, counters) => {
         record(telemetry, type, counters);
         flusher.soon();
@@ -152,11 +152,10 @@ function wire({ db, paths, clock, ids, log, hub, telemetry, flusher, registry })
             thumbnail: (context) => runThumbnail(writing, context, stageProviders(providers, context)),
             video: (context) => renderVideo(video, context),
         },
-        // logic/16 step 2 counts finer than a stage reaching `done` - each intro and outro
-        // text, each narrated segment - and its counters are the provider names, the token
-        // usage and the durations only the stage slice ever sees. Each slice therefore
-        // records its own units through `count` above, and the runner is left counting
-        // nothing: the kernel may not import a slice (03-conventions).
+        // Counting is finer than a stage reaching `done` - each intro and outro text, each
+        // narrated segment - and the counters are provider names, token usage and durations
+        // only the stage slice ever sees. Each slice records its own units through `count`
+        // above, and the runner counts nothing: the kernel may not import a slice.
         emit: (projectId, event) => {
             hub.emit(projectId, event);
         },
@@ -203,7 +202,7 @@ export function urlOf(host, port) {
     return `http://${host.includes(":") ? `[${host}]` : host}:${port}`;
 }
 // A stage can only be `running` at boot if the previous process died mid-run;
-// nothing auto-resumes, the user retries by hand (logic/01 §Q7).
+// nothing auto-resumes, the user retries by hand.
 export function markInterruptedStages(db, clock) {
     const result = db
         .prepare("UPDATE stages SET state = 'failed', failure_reason = 'interrupted', finished_at = ? WHERE state = 'running'")

package/dist/slices/admission/model.js

@@ -1,6 +1,6 @@
 // The format is the kernel's: the image port asks for the same two aspects.
 export { formats } from "../../kernel/pipeline.js";
-// mockup §Q28 and logic/10 §Q78: Generate / Provide / Off for most stages, and the
-// thumbnail's two Generate modes. Video is always `generate` (logic/01 step 5).
+// Generate, Provide or Off for most stages, plus the thumbnail's two Generate modes. Video
+// is always `generate`.
 export const stageSources = ["generate", "provide", "off", "from_prompt", "prompt_by_llm"];
 export const entryModes = ["text", "llm"];

package/dist/slices/admission/repo.js

@@ -5,7 +5,7 @@ import { entryModes, formats, stageSources } from "./model.js";
 const providerChoice = z.object({ provider: z.string(), model: z.string() });
 const entryChoice = z.object({ name: z.string(), mode: z.enum(entryModes) });
 // The shape Play posts and the shape `projects.config` holds, in one place: the second
-// is the first plus the rendered prompt texts (logic/03 §Q25).
+// is the first plus the rendered prompt texts.
 export const runDraftSchema = z.object({
     title: z.string(),
     format: z.enum(formats),
@@ -35,8 +35,8 @@ export const runDraftSchema = z.object({
         images: z.array(z.string()).optional(),
         thumbnail: z.string().optional(),
     }),
-    // logic/08 §Q65. Optional until Play carries the control; unknown keys are stripped by
-    // this schema, so a mode that is not listed here would never reach the audio stage.
+    // Optional until Play carries the control; unknown keys are stripped by this schema, so
+    // a mode not listed here would never reach the audio stage.
     chunking: z.object({ mode: z.enum(chunkModes), words: z.number().optional() }).optional(),
     silenceGapSeconds: z.number(),
 });
@@ -87,7 +87,7 @@ export function projectById(db, id) {
 export function projectExists(db, id) {
     return db.prepare("SELECT 1 FROM projects WHERE id = ?").get(id) !== undefined;
 }
-// mockup/07: newest first.
+// Newest first.
 export function listProjects(db) {
     return db
         .prepare("SELECT * FROM projects ORDER BY created_at DESC, id DESC")
@@ -137,9 +137,8 @@ export function claimStage(db, stageId, at) {
 export function finishStage(db, stageId, state, failureReason, at) {
     db.prepare("UPDATE stages SET state = ?, failure_reason = ?, finished_at = ? WHERE id = ?").run(state, failureReason, at, stageId);
 }
-// `logic/12` step 9 and `logic/13` step 5: a stage put back to `pending` by a re-run, a
-// cascade or a retry starts again from a clean row - no error text, no progress from the
-// run before it, and the fresh attempt budget of `logic/01` §Q5.
+// A stage put back to `pending` by a re-run, a cascade or a retry starts again from a clean row
+// - no error text, no progress from the run before it, and a fresh attempt budget.
 export function resetStage(db, stageId) {
     db.prepare("UPDATE stages SET state = 'pending', failure_reason = NULL, attempt_count = 0, progress_current = NULL, progress_total = NULL, started_at = NULL, finished_at = NULL WHERE id = ?").run(stageId);
 }

package/dist/slices/admission/rules.js

@@ -3,15 +3,14 @@ export const titleMax = 200;
 export const valueMax = 200;
 export const numberPerPromptMax = 20;
 export const imagesPerRunMax = 60;
-// ceiling: logic/11 §Q99 and logic/02 fix the default at 3 s but name no bounds, so the
-// range is this module's. A wider gap is a settings change, not a schema change.
+// ceiling: the default gap is 3 s and nothing fixes an upper or lower bound, so the range
+// is this module's. A wider gap is a settings change, not a schema change.
 export const silenceGapSecondsMax = 30;
-// mockup §Q28, logic/04 §Q31, logic/10 §Q78. Video is always generated (logic/01 step 5).
-// Exported because Play's source switches offer exactly these and nothing else: the
-// segmented control and the refusal below it are then the same list, and a stage whose
-// legal set changes cannot leave a switch behind offering something the server refuses.
-// The order is the order the segments are drawn in on the reference sheet; the rule
-// itself only asks whether a source is on its stage's list.
+// The legal source for each stage; video is always generated. Exported because Play's
+// source switches offer exactly these and nothing else, so the segmented control and the
+// refusal below it are the same list and a stage whose legal set changes cannot leave a
+// switch offering something the server refuses. The order is the order the segments are
+// drawn in; the rule itself only asks whether a source is on its stage's list.
 export const allowedSources = {
     research: ["off", "generate", "provide"],
     article: ["generate", "provide"],
@@ -38,8 +37,7 @@ export function admit(input) {
             });
         }
     }
-    // logic/04 §Q28 with logic/10 §Q81 and §Q97: the LLM row is required only when
-    // something in the run actually asks an LLM for text.
+    // The LLM row is required only when something in the run actually asks an LLM for text.
     const needsLlm = sources.research === "generate" ||
         sources.article === "generate" ||
         sources.thumbnail === "prompt_by_llm" ||
@@ -82,8 +80,8 @@ export function admit(input) {
     }
     return fields.length === 0 ? { ok: true, draft } : { ok: false, fields };
 }
-// logic/05 §Q41: research only feeds article writing, so a provided article hides it.
-// logic/01 step 5: video is generated whatever the form said.
+// Research only feeds article writing, so a provided article hides it.
+// Video is generated whatever the form said.
 function normalise(draft) {
     const sources = { ...draft.sources, video: "generate" };
     if (sources.article === "provide") {
@@ -100,7 +98,7 @@ function normalise(draft) {
 }
 function checkImagePrompts(draft, fields) {
     if (draft.imagePrompts.length === 0) {
-        // logic/04 §Q31: a run always has an image source.
+        // A run always has an image source.
         fields.push({ field: "imagePrompts", message: "Tick at least one image prompt." });
         return;
     }
@@ -159,7 +157,7 @@ function checkProvided(draft, staged, fields) {
         }
     }
 }
-// logic/05 §Q44: a run never starts with provided content that is missing or still copying.
+// A run never starts with provided content that is missing or still copying.
 function checkFile(staged, id, kind, field, missing, fields) {
     if (id === undefined || id === "") {
         fields.push({ field, message: missing });
@@ -174,7 +172,6 @@ function checkFile(staged, id, kind, field, missing, fields) {
         fields.push({ field, message: "This upload is still copying." });
     }
 }
-// logic/03 step 4 and §Q26.
 function checkValues(draft, requiredSlots, fields) {
     for (const name of requiredSlots) {
         const value = Object.hasOwn(draft.values, name) ? draft.values[name] : undefined;

package/dist/slices/admission/start.js

@@ -3,7 +3,7 @@ import { stageKinds } from "../../kernel/pipeline.js";
 import { storeArticleText } from "../article/store.js";
 import { attachStagedFile, dropStagedSource, storeText } from "../storage/staging.js";
 import { insertProject, insertStage } from "./repo.js";
-// logic/01 step 1: Provide → `provided` with its output attached; Off → `skipped`;
+// Provide → `provided` with its output attached; Off → `skipped`;
 // everything else → `pending`.
 export function initialState(source) {
     if (source === "provide") {
@@ -11,9 +11,8 @@ export function initialState(source) {
     }
     return source === "off" ? "skipped" : "pending";
 }
-// logic/04 step 6 with 04-data-flow Run step 2: the project row, its six stages, and the
-// provided content all land together or not at all. The caller ticks the runner after
-// this returns, never inside it.
+// The project row, its six stages and the provided content all land together or not at
+// all. The caller ticks the runner after this returns, never inside it.
 export function startRun(deps, draft, rendered) {
     const id = deps.ids.next();
     const at = deps.clock.now().toISOString();
@@ -66,9 +65,9 @@ function attachProvided(deps, projectId, draft, collected) {
         });
     }
     if (sources.article === "provide" && provided.article !== undefined) {
-        // logic/08 step 1: the end-matter split runs when the article becomes done *or
-        // provided*, so a pasted Sources Consulted list is cut into its own file here exactly
-        // as the article stage cuts a written one, and never reaches the narration.
+        // The end-matter split runs when the article becomes done *or provided*, so a pasted
+        // Sources Consulted list is cut into its own file here exactly as the article stage cuts a
+        // written one, and never reaches the narration.
         storeArticleText(deps, { projectId, markdown: provided.article.trim() });
     }
     if (sources.audio === "provide") {
@@ -78,7 +77,7 @@ function attachProvided(deps, projectId, draft, collected) {
         attach(deps, projectId, "thumbnail", provided.thumbnail, "thumbnail", collected);
     }
     if (sources.images === "provide") {
-        // logic/05 §Q39: slideshow order is the order the user left the list in.
+        // Slideshow order is the order the user left the list in.
         for (const [index, stagedFileId] of (provided.images ?? []).entries()) {
             attach(deps, projectId, "images", stagedFileId, "image", collected, index + 1);
         }

package/dist/slices/admission/substitute.js

@@ -1,7 +1,7 @@
-// logic/03 §Q19-§Q21 fix the grammar: `{{` … `}}`, whitespace immediately inside the
-// braces stripped, the name case-sensitive and free to hold anything but `{`, `}` and a
-// newline (so `{{Middle of Words}}` is one name). There is no escape syntax. Hand-rolled
-// on purpose (standards §Q2): a template library would bring its own grammar.
+// The slot grammar: `{{` … `}}`, whitespace immediately inside the braces stripped, the
+// name case-sensitive and free to hold anything but `{`, `}` and a newline (so
+// `{{Middle of Words}}` is one name). There is no escape syntax. Hand-rolled on purpose: a
+// template library would bring its own grammar.
 export const slotLintKinds = ["unclosed", "empty", "nested"];
 export const fieldGroups = ["common", "text", "image"];
 // A well-formed slot: no brace and no newline between the delimiters.
@@ -37,9 +37,9 @@ export function detectSlots(body) {
     }
     return { names, errors };
 }
-// logic/03 step 3: one field per distinct name; Common when a name is used on both
-// sides, otherwise Text or Image. §Q24 fixes the order as first appearance, which is why
-// both sides arrive as ordered lists of bodies rather than as sets.
+// One field per distinct name; Common when a name is used on both sides, otherwise Text or
+// Image. The order is first appearance, which is why both sides arrive as ordered lists of
+// bodies rather than as sets.
 export function collectFields(textBodies, imageBodies) {
     const text = namesOf(textBodies);
     const image = namesOf(imageBodies);
@@ -54,12 +54,12 @@ export function collectFields(textBodies, imageBodies) {
     }
     return fields;
 }
-// logic/03 step 5 and §Q21: one pass, so a value that itself contains `{{x}}` lands in
-// the output verbatim and is never looked at again. A name with no value is left as it
-// was written; scenario 04 refuses the run before this can reach a provider.
+// One pass, so a value that itself contains `{{x}}` lands in the output verbatim and is never
+// looked at again. A name with no value is left as it was written; admission refuses the run
+// before this can reach a provider.
 export function render(body, values) {
     return body.replace(slot, (whole, inside) => {
-        // A slot name may be anything but a brace or a newline (§Q19), so "constructor" and
+        // A slot name may be anything but a brace or a newline, so "constructor" and
         // "toString" are ordinary names; a plain lookup would answer them from Object's
         // prototype and splice a function's source into a prompt bound for a provider.
         const name = inside.trim();

package/dist/slices/article/continuation.js

@@ -1,12 +1,12 @@
 import { noTokens, plusUsage } from "../telemetry/model.js";
-// §Q59: "at most 3 continuations; still unfinished after the third is a failed attempt".
+// At most 3 continuations; still unfinished after the third is a failed attempt.
 export const continuationLimit = 3;
 // The provider's own word for "I stopped because I ran out of room", which is what every
 // adapter maps its finish reason to (`kernel/ports/llm.ts`).
 const truncatedReason = "length";
-// §Q56: "a fixed 'Research notes' header followed by the notes, then the rendered article
-// prompt; without research, the rendered prompt alone". One user message, and no
-// parameters of the app's own: the provider's defaults are used (§Q61).
+// A fixed 'Research notes' header followed by the notes, then the rendered article prompt;
+// without research, the rendered prompt alone. One user message, and no parameters of the app's
+// own: the provider's defaults are used.
 export function articleMessages(brief) {
     const notes = brief.notes?.trim();
     const content = notes === undefined || notes === ""
@@ -16,9 +16,9 @@ export function articleMessages(brief) {
 }
 // The article so far goes back as the assistant turn it was, so the model continues its
 // own answer rather than being asked to write a second article. Nothing is inserted at
-// the seam - the pieces are concatenated exactly as they arrived (§Q57: the stored text
-// is the model's, never edited by the app) - so the instruction has to carry the whole
-// of the rule that keeps the seam invisible.
+// the seam - the pieces are concatenated exactly as they arrived, and the stored text is
+// the model's, never edited by the app - so the instruction has to carry the whole of the
+// rule that keeps the seam invisible.
 export function continuationMessages(base, soFar) {
     return [
         ...base,
@@ -54,7 +54,7 @@ export async function writeArticle(providers, choice, brief, onDelta) {
             model: choice.model,
             messages,
             // The last continuation allowed is the one that has to end the article: a fourth
-            // truncation is a failed attempt, which is the wrapper's to retry (§Q59). The
+            // truncation is a failed attempt, which is the wrapper's to retry. The
             // loop therefore never sees a truncated answer with its budget spent.
             check: n === continuationLimit ? finished : written,
         }, stream);
@@ -66,7 +66,7 @@ export async function writeArticle(providers, choice, brief, onDelta) {
 function truncated(answer) {
     return answer.finishReason === truncatedReason;
 }
-// §Q61: "Empty response → failed attempt".
+// Empty response → failed attempt.
 function written(answer) {
     return answer.text.trim() === "" ? "the article answered with nothing" : undefined;
 }

package/dist/slices/article/plain.js

@@ -1,11 +1,11 @@
 import { remark } from "remark";
 import remarkGfm from "remark-gfm";
 import stripMarkdown from "strip-markdown";
-// `logic/05` §Q37 and `logic/07` step 4: 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.
+// 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.

package/dist/slices/article/run.js

@@ -17,29 +17,29 @@ export async function runArticle(deps, context, providers) {
     const choice = project.config.llm;
     const articlePrompt = project.config.rendered.article;
     if (choice === undefined || articlePrompt === undefined) {
-        // Admission refuses a run whose article is Generate without both (`logic/04`), so
+        // Admission refuses a run whose article is Generate without both, so
         // reaching here is a bug in admission rather than something the user did.
         throw new Error("the run has no LLM provider or no rendered article prompt");
     }
     const notes = researchNotes(deps, projectId);
     const brief = { articlePrompt, ...(notes === undefined ? {} : { notes }) };
     const written = await writeArticle(providers, choice, brief, (text) => {
-        // Step 2 and `logic/01` §Q6: the page shows the article as it is written. The idle
-        // timeout is restarted by the wrapper on the same events, not here.
-        // ceiling: §Q60 discards the partial text of a failed attempt, but the deltas already
-        // sent cannot be unsent, so a retry mid-stream leaves the page appending the second
-        // telling under the first. What the project keeps is still the successful attempt's
-        // text alone; the upgrade is an event telling the page to start the article again.
+        // The page shows the article as it is written. The idle timeout is restarted by the wrapper
+        // on the same events, not here. ceiling: the partial text of a failed attempt is discarded,
+        // but the deltas already sent cannot be unsent, so a retry mid-stream leaves the page
+        // appending the second telling under the first. What the project keeps is still the
+        // successful attempt's text alone; the upgrade is an event telling the page to start the
+        // article again.
         context.emit({ type: "article.delta", projectId, text });
     });
-    // Step 4: the markdown exactly as the model produced it, and the plain-text narration
-    // source. §Q63 keeps the end matter out of the narration and beside the article instead.
+    // The markdown exactly as the model produced it, and the plain-text narration source.
+    // The end matter is kept out of the narration and stored beside the article instead.
     const store = { projectId, stageKind: "article" };
     storeText(deps, { ...store, role: "article_md", text: written.markdown });
     const narration = storeArticleText(deps, { projectId, markdown: written.markdown });
-    // logic/16 step 2 counts the article and each entry text as units of their own, so the
-    // article's own event goes out as soon as its text is stored, carrying the tokens of
-    // the first call and its continuations (logic/07 step 3).
+    // The article and each entry text are counted as units of their own, so the article's
+    // event goes out as soon as its text is stored, carrying the tokens of the first call
+    // and its continuations.
     deps.count("stage.completed", {
         stage: "article",
         provider: choice.provider,
@@ -51,9 +51,9 @@ export async function runArticle(deps, context, providers) {
         const segment = await writeSegment(providers, choice, project.config, category, narration, sent);
         if (segment !== undefined) {
             keepSegment(deps, context, segment, index + 1);
-            // "each intro/outro text" of logic/16 step 2, named by its segment. A text-mode
-            // entry is rendered rather than written (§Q98), so it made no call and names no
-            // provider; its tokens are the zero step 3 asks for rather than an estimate.
+            // One event per intro/outro text, named by its segment. A text-mode entry is
+            // rendered rather than written, so it made no call, names no provider and reports
+            // zero tokens rather than an estimate.
             deps.count("stage.completed", {
                 stage: "article",
                 segment: category,
@@ -62,7 +62,7 @@ export async function runArticle(deps, context, providers) {
             });
         }
     }
-    // §Q57: the exact messages sent, the continuations and the entry calls among them.
+    // The exact messages sent, the continuations and the entry calls among them.
     storeText(deps, { ...store, role: "instructions", text: instructionsText(sent) });
     deps.log.write("info", "article.done", {
         projectId,
@@ -70,9 +70,9 @@ export async function runArticle(deps, context, providers) {
         detail: `${String(written.sent.length - 1)} continuations, ${String(narration.length)} characters to narrate`,
     });
 }
-// Step 5: "for each picked entry in LLM mode, one call with the filled entry as
-// instruction plus the title, keyword values, and the plain-text article ... Text-mode
-// entries are stored as rendered per scenario 03 with no call" (§Q97, §Q98).
+// For each picked entry in LLM mode, one call with the filled entry as instruction plus the
+// title, keyword values, and the plain-text article ... Text-mode entries are stored as
+// rendered, with no call.
 async function writeSegment(providers, choice, config, category, article, sent) {
     const picked = config[category];
     if (picked === undefined) {
@@ -92,7 +92,7 @@ async function writeSegment(providers, choice, config, category, article, sent)
         provider: choice.provider,
         model: choice.model,
         messages,
-        // §Q96 and §Q61: an entry that answers with nothing is a failed attempt like any
+        // An entry that answers with nothing is a failed attempt like any
         // other, and the wrapper is what retries it.
         check: (given) => given.text.trim() === "" ? `the ${category} answered with nothing` : undefined,
     });
@@ -125,8 +125,8 @@ function segmentMessages(body, config, article) {
 // a failure replaces what it wrote rather than colliding with it.
 function keepSegment(deps, context, segment, idx) {
     // Written out rather than stringified whole: the caller hands in what the call cost as
-    // well, and the piece is `logic/08`'s to read - it carries the text to narrate, nothing
-    // about the model that wrote it.
+    // well, and the narration stage is what reads the piece - it carries the text to speak,
+    // nothing about the model that wrote it.
     const payload = JSON.stringify({
         category: segment.category,
         name: segment.name,
@@ -147,9 +147,9 @@ function keepSegment(deps, context, segment, idx) {
     }
     setPiece(deps.db, existing.id, "done", payload);
 }
-// Research writes its notes as an output of its own (`logic/06` step 4), and a provided
-// research stage stores the pasted text the same way, so one lookup covers both. No row
-// means research was Off or skipped, and the article is written from the prompt alone.
+// Research writes its notes as an output of its own, and a provided research stage stores the
+// pasted text the same way, so one lookup covers both. No row means research was Off or
+// skipped, and the article is written from the prompt alone.
 function researchNotes(deps, projectId) {
     const notes = outputsOf(deps.db, projectId).find((output) => output.role === "notes");
     if (notes === undefined) {

package/dist/slices/article/split.js

@@ -1,7 +1,7 @@
 import { remark } from "remark";
 import remarkGfm from "remark-gfm";
 import { plainText } from "./plain.js";
-// §Q63 names the two sections. The comparison is on the heading's own text, so "## Sources
+// The two end-matter sections. The comparison is on the heading's own text, so "## Sources
 // Consulted", "# SOURCES CONSULTED" and "**Sources Consulted:**" are one heading and
 // "## Sources Consulted and Further Reading" is not.
 const endHeadings = {

package/dist/slices/article/store.js

@@ -1,16 +1,16 @@
 import { storeText } from "../storage/staging.js";
 import { plainText } from "./plain.js";
 import { splitEndMatter } from "./split.js";
-// The narration source it stored, so a caller that needs the article as it will be spoken
-// - `logic/07` step 5 writes the intro and outro from it - does not read the file back.
+// The narration source it stored, so a caller that needs the article as it will be spoken -
+// the intro and outro are written from it - does not read the file back.
 export function storeArticleText(deps, input) {
     const end = splitEndMatter(input.markdown);
     const store = { projectId: input.projectId, stageKind: "article" };
-    // `logic/05` §Q37's invariant: "the narration source of an article is always plain
-    // text", so no voice ever says a hash or a bracket, whoever wrote the markdown.
+    // The narration source of an article is always plain text, so no voice ever says a hash or a
+    // bracket, whoever wrote the markdown.
     const narration = plainText(end.body);
     storeText(deps, { ...store, role: "article_txt", text: narration });
-    // §Q63: no such heading means no file, not an empty one.
+    // No such heading means no file, not an empty one.
     if (end.sources.trim() !== "") {
         storeText(deps, { ...store, role: "sources", text: end.sources });
     }

package/dist/slices/cancel/index.js

@@ -1,9 +1,9 @@
 import { derive } from "../../kernel/runner/graph.js";
 import { finishStage, projectExists, stagesOf } from "../admission/repo.js";
-// `logic/13`: Cancel on the project header. Every in-flight call of this project is
-// aborted at once, every `done` output and every finished piece is kept for the resume,
-// and the project sits `canceled` until the user retries a stage.
-// §Q111 and `logic/01`'s transition table, in the words the stage row carries.
+// Cancel on the project header. Every in-flight call of this project is aborted at once, every
+// `done` output and every finished piece is kept for the resume, and the project sits
+// `canceled` until the user retries a stage.
+// The cancel rules and the stage transition table, in the words the stage row carries.
 export const canceledByUser = "canceled by user";
 export async function cancelProject(deps, projectId) {
     if (!projectExists(deps.db, projectId)) {
@@ -12,14 +12,14 @@ export async function cancelProject(deps, projectId) {
     const before = stagesOf(deps.db, projectId);
     const running = before.filter((stage) => stage.state === "running").map((stage) => stage.kind);
     if (running.length === 0) {
-        // Step 4: "a second click is a no-op". Nothing is aborted and no state changes, so
+        // A second click is a no-op. Nothing is aborted and no state changes, so
         // the page is simply told what the project already reads.
         return { ok: true, canceled: [], state: derive(before) };
     }
-    // Step 1: nothing waits for a response. The runner holds the controllers and its own
+    // Nothing waits for a response. The runner holds the controllers and its own
     // barrier, so a stage that finishes during this does not release its dependents.
     await deps.abort(projectId);
-    // Step 3's invariant: "after cancel completes no stage of the project is `running`".
+    // The invariant: after cancel completes no stage of the project is `running`.
     // The runner writes that row as each aborted stage unwinds; this is the path where it
     // could not - a failed write is logged there and the run is left mid-flight otherwise.
     const after = stagesOf(deps.db, projectId);
@@ -51,7 +51,7 @@ export async function cancelProject(deps, projectId) {
     }
     return {
         ok: true,
-        // §Q113: a stage whose output was stored in the same instant as the cancel stays
+        // A stage whose output was stored in the same instant as the cancel stays
         // `done`, so what was stopped is read back rather than assumed from what was running.
         canceled: settled
             .filter((stage) => stage.state === "canceled" && running.includes(stage.kind))