@gentbajko/slopify 0.1.0 → 0.2.0

package/dist/edge/http/telemetry.js

@@ -11,14 +11,13 @@ export function telemetryRoutes(deps) {
         appVersion: deps.version,
     };
     return (new Hono()
-        // What the SPA asks before it shows the first-run notice
-        // (mockup/02-first-run-notice.md). The app version comes with it because the notice
-        // names the version that goes out in every report, and the promise has to be made
-        // with the number it is true of.
+        // What the SPA asks before it shows the first-run notice. The app version comes with it
+        // because the notice names the version that goes out in every report, and the promise has
+        // to be made with the number it is true of.
         .get("/notice", (c) => c.json({ seen: noticeSeen(deps.db), appVersion: deps.version }))
-        // "Got it" is the only control on that modal, and pressing it is what creates the
-        // machine id (logic/16 step 1). Idempotent: a second press, a reload or a second tab
-        // finds the machine already there and mints nothing.
+        // "Got it" is the only control on that modal, and pressing it is what creates the machine
+        // id. Idempotent: a second press, a reload or a second tab finds the machine already
+        // there and mints nothing.
         .post("/notice", (c) => {
         dismissNotice(telemetry);
         deps.flushSoon();

package/dist/edge/http/usage.js

@@ -1,10 +1,10 @@
 import { Hono } from "hono";
 import { allTelemetryEvents, machineOf } from "../../slices/telemetry/repo.js";
 import { usageOf } from "../../slices/telemetry/usage.js";
-// The data behind `uiux/screens/10-usage.md`: the five counters, the "Tokens by stage"
-// table, and the machine id with the app version. logic/16 step 6 computes all of it from
-// the local event log, "independent of delivery", so this route never touches the
-// collector and answers just as well offline.
+// The data behind the Usage screen: the five counters, the "Tokens by stage" table, and the
+// machine id with the app version. All of it is computed from the local event log,
+// independent of delivery, so this route never touches the collector and answers just as
+// well offline.
 // The return type is inferred so Hono keeps the route types the SPA's client is
 // generated from; see stagingRoutes.
 export function usageRoutes(deps) {
@@ -12,7 +12,7 @@ export function usageRoutes(deps) {
         events: allTelemetryEvents(deps.db),
         // The machine id is shown on this page and goes no further: the server is bound to
         // loopback and the SPA reading it is this machine's own. Nothing puts it in a
-        // payload - the collector is told it once, in the envelope (logic/16 §Q129).
+        // payload - the collector is told it once, in the envelope.
         machineId: machineOf(deps.db)?.machineId ?? null,
         appVersion: deps.version,
     })));

package/dist/kernel/config/index.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-const defaultPort = 4242;
+const defaultPort = 6969;
 const defaultHost = "127.0.0.1";
 export function configFrom(flags, env) {
     const port = flags.port ?? env.SLOPIFY_PORT;

package/dist/kernel/db/tx.js

@@ -1,25 +1,22 @@
 // SQLite starts a transaction for a SAVEPOINT issued outside one and nests it inside one
-// that is already open, so a slice can wrap its own writes without knowing whether its
-// caller wrapped them too. The name is a constant rather than a parameter: SQLite matches
-// RELEASE and ROLLBACK TO against the most recent savepoint of that name, which is
-// exactly the nesting we want, and nothing a caller passes reaches the statement.
+// already open, so a slice can wrap its own writes without knowing whether its caller did
+// too. The name is a constant, not a parameter: SQLite matches RELEASE and ROLLBACK TO
+// against the most recent savepoint of that name, and nothing a caller passes reaches SQL.
 const savepoint = "slopify";
 export function transact(db, run) {
     db.exec(`SAVEPOINT ${savepoint}`);
     try {
         const result = run();
         // node:sqlite is synchronous, so an async block would release this frame while its
-        // awaited writes were still to come - and they would then land outside any
-        // transaction. The frame is unwound below, which is the only safe answer.
+        // awaited writes were still to come, and they would land outside any transaction.
         if (isThenable(result)) {
-            // Refusing the block orphans the promise it already started. Node treats an
-            // unhandled rejection as fatal, so it would take the process down and bury the
-            // error thrown here, which is the one that names the mistake.
+            // Refusing the block orphans the promise it already started, and Node treats an
+            // unhandled rejection as fatal - it would bury the error thrown here.
             void Promise.resolve(result).catch(() => { });
             throw new Error("transact runs synchronous work only: an awaited write would land after the savepoint is released");
         }
         // Inside the try: a RELEASE that fails leaves the frame open with the block's writes
-        // uncommitted, which is a rollback, not a success to return a value from.
+        // uncommitted, which is a rollback, not a value to return.
         db.exec(`RELEASE ${savepoint}`);
         return result;
     }
@@ -29,8 +26,8 @@ export function transact(db, run) {
     }
 }
 // An unguarded ROLLBACK TO would leave the frame open on failure, and the enclosing
-// transact - which names the same savepoint - would then aim its own rollback at the
-// leaked frame and commit part of what it meant to undo.
+// transact - same savepoint name - would aim its rollback at the leaked frame and commit
+// part of what it meant to undo.
 function unwind(db, error) {
     try {
         db.exec(`ROLLBACK TO ${savepoint}`);

package/dist/kernel/log.js

@@ -1,9 +1,9 @@
 import { appendFileSync } from "node:fs";
 import { join } from "node:path";
 // ceiling: prefix matching, not a secret scanner. The prefixes cover the providers in
-// `slices/settings/model.ts`; fal.ai's `<uuid>:<hex>` form has no prefix to match on and
-// is the known gap. That is why LogFields is a closed set of three strings: no caller
-// can hand this module an arbitrary payload to serialise.
+// `slices/settings/model.ts`; fal.ai's `<uuid>:<hex>` form has no prefix and is the known
+// gap. Hence LogFields is a closed set of three strings - no caller can hand this module
+// an arbitrary payload to serialise.
 const keyLike = /\b(?:sk|rk|pk|hf|gsk|xai|nvapi|r8)[-_][A-Za-z0-9_-]{16,}|\bAIza[A-Za-z0-9_-]{16,}/g;
 const bearerLike = /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi;
 export function openLog(logsDir, clock) {
@@ -27,8 +27,8 @@ export function openLog(logsDir, clock) {
         },
     };
 }
-// Exported for the attempt wrapper: a provider's verbatim error is shown on the project
-// page and stored on the attempt, so it goes through the same filter as a log line.
+// Exported for the attempt wrapper: a provider's verbatim error reaches the project page
+// and the attempt row, so it goes through the same filter as a log line.
 export function redact(text) {
     return text.replace(bearerLike, "Bearer [redacted]").replace(keyLike, "[redacted]");
 }

package/dist/kernel/pipeline.js

@@ -1,8 +1,7 @@
 // The pipeline's vocabulary. It sits in the kernel because the runner, the slices that
-// implement a stage, and the edge that reports one all name the same finite sets, and
-// the runner may not import a slice to learn them (03-conventions Dependency injection).
-// The frame a run is made in, and the aspect an image is asked for: one set, named once
-// (`logic/04`, `logic/09` step 1).
+// implement a stage and the edge that reports one all name the same finite sets, and the
+// runner may not import a slice to learn them.
+// The frame a run is made in, and the aspect an image is asked for: one set, named once.
 export const formats = ["16:9", "9:16"];
 export const stageKinds = ["research", "article", "audio", "images", "thumbnail", "video"];
 export const stageStates = [
@@ -14,9 +13,8 @@ export const stageStates = [
     "provided",
     "skipped",
 ];
-// logic/01 §Q9 names four project states and derives them in order: running if any
-// stage is running, else canceled, else failed, else done when video is done. A project
-// whose stages are all still pending matches none of them, and that window is real
-// between creating the project and the runner starting the first stage, so `pending` is
-// the fallback the derivation returns. Nothing stores it: status is always derived.
+// Four project states, derived in order: running if any stage is running, else canceled,
+// else failed, else done when video is done. A project whose stages are all pending matches
+// none of them - the real window between creating it and the runner starting the first
+// stage - so `pending` is the fallback. Nothing stores it.
 export const projectStates = ["running", "canceled", "failed", "done", "pending"];

package/dist/kernel/ports/model.js

@@ -1,11 +1,10 @@
 // The vocabulary that crosses the provider seam. Domain types only: a vendor's payload
-// shape never leaves its adapter (01-architecture §Q10, §Q33).
+// shape never leaves its adapter.
 export const providerFamilies = ["llm", "tts", "image"];
 export const providerErrorKinds = [
     "auth",
-    // Distinct from `auth`, which is a key the provider rejected. `logic/02` §Q13 splits
-    // them: a bad key runs the whole retry policy (§Q11) and an absent one "fails
-    // immediately, without retries", so the wrapper needs two kinds to tell apart.
+    // Distinct from `auth`, a key the provider rejected: a bad key runs the whole retry
+    // policy, an absent one fails immediately.
     "missing_key",
     "rate_limit",
     "refusal",

package/dist/kernel/runner/attempt-repo.js

@@ -1,9 +1,8 @@
 import { z } from "zod";
 import { providerErrorKinds } from "../ports/model.js";
-// One row per provider call attempt (02-models, `logic/01` §Q4). The project page reads
-// the last error text off these rows and the Usage page counts them, so an attempt is
-// written when it opens rather than when it ends: a process that dies mid-call leaves
-// the evidence behind (`logic/01` §Q7).
+// One row per provider call attempt. The project page reads the last error text off these rows
+// and Usage counts them, so an attempt is written when it opens rather than when it ends: a
+// process that dies mid-call leaves the evidence behind.
 export const attemptOutcomes = ["ok", "canceled", ...providerErrorKinds];
 const attemptRow = z.object({
     id: z.string(),
@@ -20,8 +19,8 @@ export function sqliteAttempts(db, ids) {
         start: (attempt) => {
             const id = ids.next();
             db.prepare("INSERT INTO attempts (id, stage_id, piece_id, n, started_at) VALUES (?, ?, ?, ?, ?)").run(id, attempt.stageId, attempt.pieceId, attempt.n, attempt.startedAt);
-            // `logic/01` §Q3: the stage shows the attempt count beside the error. A stage with
-            // pieces (twenty images) shows the count of the call being attempted, not a sum.
+            // The stage shows the attempt count beside the error. A stage with pieces (twenty images)
+            // shows the count of the call being attempted, not a sum.
             db.prepare("UPDATE stages SET attempt_count = ? WHERE id = ?").run(attempt.n, attempt.stageId);
             return id;
         },

package/dist/kernel/runner/attempt.js

@@ -1,24 +1,20 @@
 import { redact } from "../log.js";
 import { isProviderError, providerError } from "../ports/model.js";
-// The retry policy of `logic/01` step 6, in one place. Every provider call in the app
-// goes through here: a stage slice is handed the wrapped calls of `providers.ts` and
-// never an adapter, so there is no way round it.
-// "attempted up to 4 times: the first attempt plus 3 retries, waiting 2 s, 8 s, 30 s
-// between attempts" (`logic/01` step 6, §Q4).
+// The retry policy, in one place. A stage slice is handed the wrapped calls of
+// `providers.ts` and never an adapter, so there is no way round it.
+// Four attempts - the first plus 3 retries - waiting 2 s, 8 s, 30 s.
 export const attemptLimit = 4;
 export const backoffMs = [2000, 8000, 30_000];
-// "each attempt times out at 120 s ... except image-generation calls, which time out at
-// 300 s" (`logic/01` step 6, §Q62; `logic/09` §Q77).
+// Each attempt times out at 120 s, image calls at 300 s.
 export const timeoutMs = {
     llm: 120_000,
     tts: 120_000,
     image: 300_000,
 };
-// `logic/09` §Q74 and `logic/06` §Q47: a refusal and an unsupported capability are the
-// provider's final answer. Retrying either would only spend the user's money again.
-// `logic/02` §Q13 adds the third: a key removed mid-run leaves nothing to call with, so
-// "the next attempt finds no key, fails immediately without retries" - unlike a key the
-// provider rejected, which is an `auth` failure and is retried like any other (§Q11).
+// A refusal and an unsupported capability are the provider's final answer; retrying only
+// spends the user's money again. The third is a key removed mid-run, which leaves nothing
+// to call with. A key the provider rejected is different: that is an `auth` failure,
+// retried like any other.
 const terminalKinds = ["refusal", "unsupported", "missing_key"];
 export async function attempt(ctx, call, opts) {
     ctx.signal.throwIfAborted();
@@ -49,9 +45,8 @@ export async function attempt(ctx, call, opts) {
             return result.value;
         }
         if (ctx.signal.aborted) {
-            // `logic/13` §Q112: an aborted call counts nothing. The row is closed so the page
-            // is not left with an attempt that never ended, and it carries no error text: the
-            // user stopped it, the provider did not fail.
+            // An aborted call counts nothing. The row is closed so the page is
+            // not left with an attempt that never ended, and carries no error text.
             ctx.attempts.end(id, {
                 outcome: "canceled",
                 endedAt: ctx.clock.now().toISOString(),
@@ -73,12 +68,11 @@ export async function attempt(ctx, call, opts) {
         if (terminalKinds.includes(failure.fault.kind) || n >= attemptLimit) {
             throw failure;
         }
-        // §Q4: a 429 that names a Retry-After replaces the fixed wait with the provider's.
+        // A 429 that names a Retry-After replaces the fixed wait with the provider's.
         await ctx.clock.sleep(failure.fault.retryAfterMs ?? backoffMs[n - 1] ?? 0, ctx.signal);
     }
 }
-// The wrapper is the only place a provider failure is named (03-standards). Everything
-// downstream reads `fault.kind` and shows `message`.
+// The wrapper is the only place a provider failure is named.
 function classify(error, expired, opts, limit) {
     if (expired) {
         const seconds = Math.round(limit / 1000);
@@ -90,8 +84,8 @@ function classify(error, expired, opts, limit) {
         });
     }
     if (isProviderError(error)) {
-        // Rebuilt rather than rethrown so the text that reaches the stage row, the page and
-        // the log has been through the redactor: a provider is free to quote the key back.
+        // Rebuilt rather than rethrown so the text reaching the stage row, the page and the
+        // log has been through the redactor: a provider is free to quote the key back.
         return providerError({
             kind: error.fault.kind,
             message: redact(error.message),
@@ -103,9 +97,8 @@ function classify(error, expired, opts, limit) {
         message: redact(error instanceof Error ? error.message : String(error)),
     });
 }
-// `logic/01` §Q62: the same number of milliseconds, measured two ways. `idle` restarts
-// the count on every chunk, so a long answer that keeps arriving is never cut off, and a
-// stream that stalls is. Composed with AbortSignal.any so the stage's cancel still wins.
+// The same milliseconds, measured two ways. `idle` restarts the count on every chunk, so a
+// stalled stream is cut off and a long answer is not. Cancel still wins.
 function deadline(clock, parent, ms, idle) {
     const timer = new AbortController();
     const signal = AbortSignal.any([parent, timer.signal]);

package/dist/kernel/runner/graph.js

@@ -1,4 +1,4 @@
-// logic/01 steps 2-5: research → article → {audio ∥ images ∥ thumbnail} → video.
+// Research → article → {audio ∥ images ∥ thumbnail} → video.
 export const deps = {
     research: [],
     article: ["research"],
@@ -7,11 +7,11 @@ export const deps = {
     thumbnail: ["article"],
     video: ["audio", "images", "thumbnail"],
 };
-// logic/01 §Q2: a dependency is released by `provided` and `skipped` exactly as by `done`.
+// `provided` and `skipped` release a dependency exactly as `done` does.
 export function satisfied(state) {
     return state === "done" || state === "provided" || state === "skipped";
 }
-// logic/01 §Q9, in its order. Derived on every read, never stored.
+// The four states, in their order. Derived on every read, never stored.
 export function derive(stages) {
     if (stages.some((stage) => stage.state === "running")) {
         return "running";
@@ -25,39 +25,28 @@ export function derive(stages) {
     if (stages.some((stage) => stage.kind === "video" && stage.state === "done")) {
         return "done";
     }
-    // Extended rule, not one of §Q9's four. §Q9 offers no answer for a project that matches
-    // none of them, and `pending` was chosen for the window between creating a project and
-    // the runner claiming its first stage. `logic/13` §Q113 makes a second case reachable:
-    // when the only running stage stores its output in the same instant as the cancel it
-    // stays `done`, so nothing is `canceled` and a run the user stopped would read as one
-    // about to start. `logic/13` step 3 is unconditional - "the project reads `canceled`" -
-    // so that is what a run which started and stopped reads here.
-    //
-    // A stage in a terminal state is what tells the two apart: at creation every stage is
-    // `pending`, `provided` or `skipped`, and only a stage the runner carried to the end is
-    // `done`. Nothing restarts such a project by itself (§Q111), so `pending` is the one
-    // answer that is certainly wrong.
+    // Extended rule, beyond the four above. `pending` covers the window between creating a
+    // project and the runner claiming its first stage. A second case is reachable: a stage
+    // that stores its output in the same instant as the cancel stays `done`, so nothing is
+    // `canceled` and a stopped run would read as about to start. A stage in a terminal state
+    // tells the two apart - at creation none is `done`.
     //
     // ceiling: a process killed between a stage finishing and its dependent being claimed
-    // leaves the same rows and reads `canceled` too - `logic/01` §Q7 only reaches a stage
-    // found `running`. Telling that apart needs the cancel recorded on the project, which is
-    // the upgrade if it ever matters; §Q9 keeps status derived and stores nothing.
+    // reads `canceled` too. Separating those needs the cancel stored on the project, and
+    // nothing about the status is stored.
     if (stages.some((stage) => stage.state === "done")) {
         return "canceled";
     }
     return "pending";
 }
-// The thin meter under a running row on 07 Projects, "averaging stage progress"
-// (uiux/screens/07-projects.md). Every stage the run actually asks for counts once: a
-// finished one whole, a running one by its own progress, a waiting, failed or canceled
-// one not at all.
-//
-// `provided` and `skipped` are left out of the average rather than counted as finished.
-// Nothing was asked of them, and counting them would put a run with research off and a
-// supplied article at a third of the way along before the first call was made.
+// The thin meter under a running row on Projects, averaging stage progress. Every stage
+// the run asks for counts once: a finished one whole, a running one by its own progress, a
+// waiting, failed or canceled one not at all. `provided` and `skipped` are left out rather
+// than counted as finished, which would put a run with a supplied article a third of the
+// way along before the first call was made.
 export function progressOf(stages) {
     const asked = stages.filter((stage) => stage.state !== "provided" && stage.state !== "skipped");
-    // A run made entirely of supplied files has nothing outstanding, and a division by zero
+    // A run made entirely of supplied files has nothing outstanding; dividing by zero
     // would answer NaN.
     if (asked.length === 0) {
         return 1;
@@ -74,8 +63,8 @@ function shareOf(stage) {
     }
     const total = stage.progressTotal ?? 0;
     if (total <= 0) {
-        // A stage that has not yet said how many chapters or chunks there are. Guessing would
-        // be a meter that moves backwards when the count arrives.
+        // The stage has not said how many chapters or chunks there are yet. Guessing gives a
+        // meter that moves backwards when the count arrives.
         return 0;
     }
     return Math.min(1, Math.max(0, (stage.progressCurrent ?? 0) / total));

package/dist/kernel/runner/index.js

@@ -1,16 +1,14 @@
 import { derive, deps as graph, satisfied } from "./graph.js";
 export function createRunner(deps) {
     const inflight = new Map();
-    // ceiling: one entry per project ticked since boot, never evicted, so it costs a few
-    // dozen bytes per project of a single user's local app and is emptied by any restart.
-    // Evicting on a terminal state would re-announce that state on the next tick of the
-    // same project, so the upgrade is to drop the entry when the project is deleted.
+    // ceiling: one entry per project ticked since boot, never evicted - a few dozen bytes
+    // each, emptied by any restart. Evicting on a terminal state would re-announce it on the
+    // next tick, so the upgrade is to drop the entry when the project is deleted.
     const announced = new Map();
-    // The projects a cancel is walking through. It is a set rather than a flag because
-    // `logic/13` D14 leaves every other project untouched, and it is held for the whole of
-    // abortProject rather than for the abort call alone: a stage of this project that
-    // stores its output in the same instant as the cancel stays `done` (§Q113), and its
-    // hand-over to the next stage is exactly what must not happen.
+    // The projects a cancel is walking through. A set, not a flag, because a cancel leaves
+    // every other project untouched. Held for the whole of abortProject: a stage that stores
+    // its output in the same instant as the cancel stays `done`, and its hand-over to the
+    // next stage is what must not happen.
     const stopped = new Set();
     let count = 0;
     let shuttingDown = false;
@@ -23,8 +21,8 @@ export function createRunner(deps) {
             ...(reason === null ? {} : { failureReason: reason }),
         });
     };
-    // The global tally is the number of projects with a stage in flight, so it is read off
-    // the in-flight set rather than counted in the database (04-data-flow, Run step 5).
+    // The global tally counts projects with a stage in flight, read off the in-flight set
+    // rather than the database.
     const retally = () => {
         const projects = new Set();
         for (const entry of inflight.values()) {
@@ -48,8 +46,8 @@ export function createRunner(deps) {
             deps.stages.finish(stage.id, state, reason);
         }
         catch (error) {
-            // The page would otherwise sit on a stage that never leaves `running`; the event
-            // still goes out, and the next boot marks the row interrupted (logic/01 §Q7).
+            // The row stays `running` when the write fails. The event still goes out, and the
+            // next boot marks the row interrupted.
             deps.log.write("error", "stage.finish", {
                 projectId: stage.projectId,
                 stage: stage.kind,
@@ -75,8 +73,8 @@ export function createRunner(deps) {
         }
         catch (error) {
             if (controller.signal.aborted) {
-                // logic/13 step 3 fixes the wording; a late rejection from the aborted call is
-                // the expected way a stage learns it was canceled, so it is not logged as a fault.
+                // A late rejection from the aborted call is how a stage learns it was canceled, so
+                // it is not logged as a fault.
                 conclude(stage, "canceled", "canceled by user");
                 return;
             }
@@ -98,8 +96,7 @@ export function createRunner(deps) {
                 release = resolve;
             }),
         };
-        // Registered before the stage body is invoked: a tick arriving while this stage is
-        // starting has to see it in flight.
+        // Registered before the body runs: a tick arriving mid-start has to see it in flight.
         inflight.set(stage.id, entry);
         retally();
         emitStage(stage, "running", null);
@@ -108,13 +105,13 @@ export function createRunner(deps) {
             inflight.delete(stage.id);
             release();
             try {
-                // The next stage is claimed before the tally is read, so a fan-out handing over
-                // to the video stage never reports the project as briefly not running.
+                // Claim the next stage before reading the tally, so a hand-over never reports
+                // the project as briefly not running.
                 tick(stage.projectId);
             }
             finally {
-                // stagesOf parses rows and can throw. The tally is replayed to every page that
-                // opens afterwards, so it is read whether or not the tick got that far.
+                // stagesOf can throw. The tally is replayed to every page that opens later, so
+                // it is read whether or not the tick got that far.
                 retally();
             }
         })
@@ -127,10 +124,9 @@ export function createRunner(deps) {
         });
     }
     function tick(projectId) {
-        // A stage that finished in the same instant as the shutdown or a cancel would
-        // otherwise release its dependent, and the abort would then be waiting on a render
-        // nobody asked for - or, worse, leaving one running under a controller nobody
-        // aborted. The project's state still goes out, so an open page sees the run stop.
+        // A stage finishing in the same instant as a shutdown or cancel would otherwise release
+        // its dependent, leaving the abort waiting on a render nobody asked for - or one running
+        // under a controller nobody aborted. The state still goes out, so an open page sees it.
         if (!shuttingDown && !stopped.has(projectId)) {
             startEligible(projectId);
         }
@@ -146,8 +142,7 @@ export function createRunner(deps) {
             if (!graph[stage.kind].every((kind) => satisfied(stateOf(kind)))) {
                 continue;
             }
-            // Nothing is awaited in this loop, so the fan-out after the article starts audio,
-            // images and thumbnail together rather than one after another.
+            // Nothing is awaited here: the fan-out starts audio, images and thumbnail together.
             if (deps.stages.claim(stage.id)) {
                 start({ ...stage, state: "running" });
             }
@@ -171,8 +166,8 @@ export function createRunner(deps) {
         tick,
         settled,
         abortProject: async (projectId) => {
-            // Up before the first abort and down only once every stage of the project has
-            // stopped: in between, the tick each finishing stage fires starts nothing.
+            // Up before the first abort, down only once every stage has stopped. In between, the
+            // tick each finishing stage fires starts nothing.
             stopped.add(projectId);
             try {
                 for (const entry of inflight.values()) {
@@ -180,15 +175,14 @@ export function createRunner(deps) {
                         entry.controller.abort();
                     }
                 }
-                // §Q109's invariant: "no provider call of the project continues after cancel
-                // returns". Waiting here is what makes that true rather than hoped for.
+                // No provider call continues after cancel returns. The wait makes it true.
                 await settledOf(projectId);
             }
             finally {
                 stopped.delete(projectId);
             }
-            // The last stage's own tick announced the project while the barrier was up and the
-            // rows may not all have been written yet; this is the state the user asked for.
+            // The last stage's tick announced the project while the barrier was up, before every
+            // row was written. This is the state the user asked for.
             announce(projectId);
         },
         abortAll: async () => {

package/dist/kernel/runner/piece-repo.js

@@ -1,9 +1,8 @@
 import { z } from "zod";
-// One row per resumable sub-unit of a stage (02-models, `stage_pieces`): a research
-// chapter, an audio chunk, an image index. It sits beside the attempt store because the
-// attempt wrapper stamps `piece_id` on every row it writes and the kernel may not import
-// the slices that fill these in. The payload is carried as the JSON text it is stored
-// as: its shape belongs to whichever stage owns the kind, and nothing here reads inside.
+// One `stage_pieces` row per resumable sub-unit of a stage: a research chapter, an audio
+// chunk, an image index. It sits beside the attempt store because the wrapper stamps
+// `piece_id` on every row it writes. The payload stays the JSON text it was stored as - its
+// shape belongs to whichever stage owns the kind, and nothing here reads inside it.
 export const pieceKinds = ["chapter", "chunk", "segment", "image", "prompt_written"];
 export const pieceStates = ["pending", "running", "done", "failed"];
 const pieceRow = z.object({
@@ -17,9 +16,8 @@ const pieceRow = z.object({
 export function insertPiece(db, piece) {
     db.prepare("INSERT INTO stage_pieces (id, stage_id, kind, idx, state, payload) VALUES (?, ?, ?, ?, ?, ?)").run(piece.id, piece.stageId, piece.kind, piece.idx, piece.state, piece.payload);
 }
-// In `idx` order: the resume of `logic/06` §Q54 re-runs the pieces a previous attempt did
-// not finish and keeps the rest, and the order they were planned in is the order the
-// stage's output is assembled in.
+// In `idx` order: a resume re-runs only the unfinished pieces, and planning order is
+// assembly order.
 export function piecesOf(db, stageId, kind) {
     return db
         .prepare("SELECT * FROM stage_pieces WHERE stage_id = ? AND kind = ? ORDER BY idx")
@@ -28,7 +26,7 @@ export function piecesOf(db, stageId, kind) {
 }
 // Every piece of a stage whatever its kind, for the one caller that does not care: a
 // re-run throws the whole plan away, because the text a chunk was cut from and the prompt
-// an image was sent with are what changed (`logic/12` §Q101, §Q104).
+// an image was sent with are what changed.
 export function allPiecesOf(db, stageId) {
     return db
         .prepare("SELECT * FROM stage_pieces WHERE stage_id = ? ORDER BY kind, idx")
@@ -38,8 +36,8 @@ export function allPiecesOf(db, stageId) {
 export function deletePieces(db, stageId) {
     db.prepare("DELETE FROM stage_pieces WHERE stage_id = ?").run(stageId);
 }
-// One piece, for `logic/09` §Q75: an image the user deleted leaves no row behind, or the
-// next run of the stage would look at the plan and make it again.
+// One piece: an image the user deleted leaves no row behind, or the next run would look at
+// the plan and make it again.
 export function deletePiece(db, id) {
     db.prepare("DELETE FROM stage_pieces WHERE id = ?").run(id);
 }

package/dist/kernel/runner/providers.js

@@ -12,8 +12,8 @@ export function stageProviders(deps, context, pieceId) {
     };
     return {
         llm: (call, onEvent) => {
-            // Resolved once: an adapter reads the stored key when it builds each request, so a
-            // key replaced mid-run still reaches the next attempt (`logic/02` §Q16).
+            // Resolved once; the adapter reads the stored key per request, so a key replaced
+            // mid-run still reaches the next attempt.
             const port = deps.registry.llm(call.provider);
             return attempt(ctx, async (signal, progress) => {
                 let text = "";
@@ -25,8 +25,7 @@ export function stageProviders(deps, context, pieceId) {
                     ...(call.webSearch === undefined ? {} : { webSearch: call.webSearch }),
                     signal,
                 })) {
-                    // Every event is a sign of life, so the idle clock restarts here rather than
-                    // in each slice that consumes one.
+                    // Every event is a sign of life, so the idle clock restarts here.
                     progress();
                     if (event.type === "delta") {
                         text += event.text;
@@ -40,8 +39,7 @@ export function stageProviders(deps, context, pieceId) {
                 const answer = { text, usage, finishReason };
                 const unusable = call.check?.(answer);
                 if (unusable !== undefined) {
-                    // Thrown bare: the wrapper is the one place a failure is named, and it names
-                    // this `other`, which is retried like any other bad answer.
+                    // Thrown bare: the wrapper names it `other` and retries it like any bad answer.
                     throw new Error(unusable);
                 }
                 return answer;
@@ -84,7 +82,7 @@ export function stageProviders(deps, context, pieceId) {
                 aspect: call.aspect,
                 signal,
             }), 
-            // One request, one answer: the 300 s runs over the whole call (`logic/09` §Q77).
+            // One request, one answer: the 300 s runs over the whole call.
             { kind: "image" });
         },
         forPiece: (piece) => stageProviders(deps, context, piece),

package/dist/kernel/version.js

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
-// package.json sits two directories above this module both in src/ and in dist/,
-// because the build mirrors the source tree (src/kernel/version.ts -> dist/kernel/
-// version.js). Reading it through import.meta.url survives `npx slopify` from any cwd.
+// package.json sits two directories above this module in both src/ and dist/, because the
+// build mirrors the source tree. Reading it through import.meta.url survives `npx` from
+// any working directory.
 export function readVersion() {
     const parsed = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     if (typeof parsed !== "object" ||