@gentbajko/slopify 0.1.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ A prompt and a few keywords in. A narrated slideshow video out. Your keys, your
 npx @gentbajko/slopify@latest
 ```
 
-That opens a browser at `http://127.0.0.1:4242`. Nothing to configure first; add
+That opens a browser at `http://127.0.0.1:6969`. Nothing to configure first; add
 provider keys on the Settings screen when you want a stage to generate rather than
 take what you paste in.
 
@@ -18,7 +18,7 @@ video is a slideshow with alternating zoom over the narration, rendered with ffm
 
 | Flag | Environment variable | Default |
 |---|---|---|
-| `--port` | `SLOPIFY_PORT` | `4242` |
+| `--port` | `SLOPIFY_PORT` | `6969` |
 | `--host` | `SLOPIFY_HOST` | `127.0.0.1` |
 | `--data-dir` | `SLOPIFY_DATA_DIR` | `~/.slopify` |
 | `--no-open` | `SLOPIFY_NO_OPEN` | the browser opens |

package/dist/adapter-registry.js

@@ -10,31 +10,30 @@ import { openAiTts } from "./adapters/tts/openai.js";
 import { keyForAttempt } from "./slices/settings/keys.js";
 import { providerStatuses } from "./slices/settings/readiness.js";
 export function buildRegistry(deps) {
-    // `logic/02` §Q16: read per request, never held, so an attempt in flight finishes on
-    // the key it started with and the next one picks up a key saved since. The closure is
-    // handed to the one adapter that provider belongs to and to nothing else (§Q18).
+    // Read per request, never held, so an attempt in flight finishes on the key it started with
+    // and the next one picks up a key saved since. The closure is handed to the one adapter that
+    // provider belongs to and to nothing else.
     const keyOf = (provider) => () => {
         const found = keyForAttempt({ db: deps.db, clock: deps.clock }, provider);
         return found.ok ? found.key : undefined;
     };
     const llms = new Map([
         ["openrouter", openRouterLlm({ fetch: deps.fetch, key: keyOf("openrouter") })],
-        // No key: both CLIs authenticate with their own login (`logic/02` §Q135).
+        // No key: both CLIs authenticate with their own login.
         ["claude-code", claudeCodeLlm({ run: deps.spawn })],
         ["codex", codexLlm({ run: deps.spawn })],
     ]);
-    // One key per provider (`logic/02` invariant), so each adapter is handed the reader for
-    // its own row and no other. OpenAI keeps two rows because it ships an adapter in two
-    // families and a user may key one without the other (`slices/settings/model.ts`).
+    // One key per provider, so each adapter is handed the reader for its own row and no other.
+    // OpenAI keeps two rows because it ships an adapter in two families and a user may key one
+    // without the other (`slices/settings/model.ts`).
     const ttses = new Map([
         ["elevenlabs", elevenLabsTts({ fetch: deps.fetch, key: keyOf("elevenlabs") })],
         ["openai-tts", openAiTts({ fetch: deps.fetch, key: keyOf("openai-tts") })],
         ["cartesia", cartesiaTts({ fetch: deps.fetch, key: keyOf("cartesia") })],
     ]);
-    // `logic/09` and `logic/02` §Q15: three image providers behind one port, each handed
-    // the reader for its own key row. Replicate also takes the clock: `Prefer: wait` gives
-    // up after 60 s and the prediction has to be polled, and the wait is spent on the
-    // app's clock so a test never sits through one.
+    // Three image providers behind one port, each handed the reader for its own key row.
+    // Replicate also takes the clock: `Prefer: wait` gives up after 60 s and the prediction has
+    // to be polled, and the wait is spent on the app's clock so a test never sits through one.
     const images = new Map([
         ["fal", falImage({ fetch: deps.fetch, key: keyOf("fal") })],
         [
@@ -47,7 +46,7 @@ export function buildRegistry(deps) {
         llm: (id) => resolve(llms, "llm", id),
         tts: (id) => resolve(ttses, "tts", id),
         image: (id) => resolve(images, "image", id),
-        // `logic/02` step 5: every supported provider, keyed or not, found or not, so Play
+        // Every supported provider, keyed or not, found or not, so Play
         // can grey one out with a reason instead of hiding it.
         list: async () => (await providerStatuses({ db: deps.db, probe: deps.probe })).map((status) => ({
             family: status.family,

package/dist/adapters/image/bytes.js

@@ -14,7 +14,7 @@ const riff = [0x52, 0x49, 0x46, 0x46];
 const webp = [0x57, 0x45, 0x42, 0x50];
 // The bytes decide, never the Content-Type header. A CDN in front of an expired link
 // serves `image/png` over an HTML error page often enough to be worth not trusting, and
-// the mime is stored with the file and becomes its extension (`logic/09` step 3).
+// the mime is stored with the file and becomes its extension.
 export function sniffImage(bytes) {
     if (startsWith(bytes, png, 0)) {
         return "image/png";

package/dist/adapters/image/fal.js

@@ -3,40 +3,59 @@ import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
-// The HTTP gateway adapter for fal.ai (01-architecture Module boundaries). `fetch` and
-// the downloader beside this file, no SDK: `@fal-ai/client` exists and would buy the
-// queue polling this endpoint does not need, so 05-dependencies' rung 3 - the platform's
-// own `fetch` - already covers the whole call. The synchronous host runs the model on the
-// open connection, which is what the attempt wrapper's 300 s is measuring.
+// The HTTP gateway adapter for fal.ai: `fetch` and the downloader beside this file, no SDK.
+// `@fal-ai/client` would buy queue polling this endpoint does not need, so the platform's
+// own `fetch` covers the whole call. The synchronous host runs the model on the open
+// connection, which is what the wrapper's 300 s measures.
 export const falBase = "https://fal.run";
-// `logic/02` §Q15: the model dropdown is filled from what the provider offers, and fal has
-// no endpoint that lists only its text-to-image models, so the list is this adapter's own
-// data. Adding next month's model is a line here and no code change anywhere else.
-// Every entry takes the same input shape: `image_size` as an enum, `num_images`, and
-// `output_format`. ceiling: a fal model that spells its aspect `aspect_ratio` instead -
-// `xai/grok-imagine-image` does - cannot be added to this list without a per-model input
-// map, which is the upgrade when one is wanted.
+// fal has no endpoint listing only its text-to-image models, so the list is this adapter's own
+// data and adding one is a line here plus its aspect shape below.
 export const falModels = [
     { id: "fal-ai/flux-2", name: "FLUX.2" },
     { id: "fal-ai/flux/dev", name: "FLUX.1 [dev]" },
     { id: "fal-ai/flux/schnell", name: "FLUX.1 [schnell]" },
+    { id: "fal-ai/nano-banana", name: "Nano Banana" },
+    { id: "fal-ai/nano-banana-2", name: "Nano Banana 2" },
+    { id: "fal-ai/gemini-3.1-flash-image-preview", name: "Gemini 3.1 Flash Image" },
 ];
-// `logic/09` step 1: the closest supported size to the run's aspect. fal names the two
-// 16:9 frames from the orientation, so the portrait one is "portrait_16_9" and is 9:16.
+// fal spells the frame two ways and the difference is per model, not per family: the FLUX
+// endpoints take an `image_size` enum naming the orientation, the Google ones take a plain
+// `aspect_ratio` string. Both accept everything else identically, so the shape is the only
+// thing a model entry has to declare.
+const aspectFields = ["image_size", "aspect_ratio"];
+// The closest supported size, per shape. fal names both 16:9 `image_size` frames from the
+// orientation, so the portrait one is "portrait_16_9" and is 9:16; `aspect_ratio` takes the
+// run's own words.
 const sizes = {
-    "16:9": "landscape_16_9",
-    "9:16": "portrait_16_9",
+    image_size: { "16:9": "landscape_16_9", "9:16": "portrait_16_9" },
+    aspect_ratio: { "16:9": "16:9", "9:16": "9:16" },
 };
-// A wire payload is narrowed, never cast: everything unlisted is dropped at the seam so
-// no vendor shape can leak past this file (01-architecture §Q10, §Q33).
+const modelAspects = {
+    "fal-ai/flux-2": "image_size",
+    "fal-ai/flux/dev": "image_size",
+    "fal-ai/flux/schnell": "image_size",
+    "fal-ai/nano-banana": "aspect_ratio",
+    "fal-ai/nano-banana-2": "aspect_ratio",
+    "fal-ai/gemini-3.1-flash-image-preview": "aspect_ratio",
+};
+// A model the map does not know is one the user typed rather than picked, so it falls back to
+// `image_size` - the shape the FLUX endpoints use and the one this adapter shipped with.
+// `Object.hasOwn` because a model id is user input and a plain lookup would answer
+// "constructor" from Object's own prototype.
+function aspectOf(model, aspect) {
+    const field = Object.hasOwn(modelAspects, model) ? modelAspects[model] : undefined;
+    const shape = field ?? "image_size";
+    return { [shape]: sizes[shape][aspect] };
+}
+// A wire payload is narrowed, never cast: everything unlisted is dropped at the seam.
 const generated = z.object({
     images: z.array(z.object({ url: z.string() })),
-    // The safety checker's verdict, one flag per image. It is how fal says it declined:
-    // the request is a 200 and the image that comes back is blank.
+    // The safety checker's verdict, one flag per image - how fal declines: a 200 with a
+    // blank image.
     has_nsfw_concepts: z.array(z.boolean()).nullish(),
 });
-// fal answers a rejected request with FastAPI's own envelope: an object per failed field
-// for a validation error, a bare string for everything else.
+// FastAPI's envelope: an object per failed field for a validation error, a bare string
+// otherwise.
 const errorBody = z.object({
     detail: z.union([
         z.string(),
@@ -54,13 +73,11 @@ export function falImage(deps) {
                 headers: { Authorization: `Key ${keyOf(deps)}`, "Content-Type": "application/json" },
                 body: JSON.stringify({
                     prompt: req.prompt,
-                    image_size: sizes[req.aspect],
-                    // `logic/09` step 2 sends Number as that many independent calls, each its own
-                    // resumable piece, so one image per request is what the stage asks for.
+                    ...aspectOf(req.model, req.aspect),
+                    // The stage sends Number as that many independent calls, one piece each.
                     num_images: 1,
-                    // The port stores a PNG or a JPEG; fal's own default is WebP on some models and
-                    // the download would refuse it. Nothing else about quality or style is set:
-                    // step 2 asks for the provider's defaults.
+                    // The port stores PNG or JPEG; fal defaults to WebP on some models and the
+                    // download would refuse it. The stage asks for the provider's own quality.
                     output_format: "png",
                 }),
             });
@@ -73,8 +90,7 @@ export function falImage(deps) {
             if (first === undefined) {
                 throw providerError({ kind: "other", message: "fal answered with no image" });
             }
-            // The download is inside the attempt with the call that produced the link, so a
-            // link that 404s is a failed attempt rather than a broken file on the project.
+            // The download rides inside the attempt: a link that 404s is a failed attempt.
             return await downloadImage({
                 fetch: deps.fetch,
                 provider: "fal",
@@ -85,18 +101,16 @@ export function falImage(deps) {
     };
 }
 function keyOf(deps) {
-    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
-    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no fal key is stored" });
     }
     return key;
 }
-// `logic/09` §Q74: a content-policy refusal is the provider's final answer, so it is named
-// here and the wrapper makes it terminal. fal declines inside a 200: the safety checker
-// flags the image and hands back a blank one. There is no sentence to quote, so this is
-// the one refusal in the app whose words are the app's; fal's own verdict is the flag.
+// A content-policy refusal is final, named here and made terminal by the wrapper. fal declines
+// inside a 200 - the safety checker flags the image and hands back a blank one. With no
+// sentence to quote, this is the one refusal whose words are the app's.
 function refused(answer, prompt) {
     const flags = answer.has_nsfw_concepts ?? [];
     if (flags.length > 0 && flags.every((flagged) => flagged)) {
@@ -106,8 +120,7 @@ function refused(answer, prompt) {
         });
     }
 }
-// Only the adapter can read a vendor's status code, so only the adapter names the kind;
-// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+// Only the adapter sees the vendor's status code, so only the adapter names the kind.
 function kindOf(status) {
     if (status === 401 || status === 403) {
         return "auth";
@@ -115,16 +128,14 @@ function kindOf(status) {
     if (status === 429) {
         return "rate_limit";
     }
-    // ceiling: everything else is `other` and is retried, so a 422 naming an input this
-    // model does not take fails the same way four times over. A terminal kind for "this
-    // request will never work" would have to be added to the port's error contract first,
-    // which is not this adapter's to widen.
+    // ceiling: everything else is `other` and is retried, so a 422 naming an input this model
+    // does not take fails the same way four times over. A terminal "this will never work" kind
+    // has to reach the port's error contract first, which is not this adapter's to widen.
     return "other";
 }
 async function failure(response) {
     const text = await response.text().catch(() => "");
-    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
-    // error body is free to quote the key back and this is the first place it is held.
+    // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(detailOf(text) || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({

package/dist/adapters/image/openai.js

@@ -3,13 +3,12 @@ import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
 import { describeBytes, sniffImage } from "./bytes.js";
-// The HTTP gateway adapter for OpenAI's images endpoint (01-architecture Module
-// boundaries). `fetch` and nothing else: 05-dependencies records global `fetch` at rung 3
-// and the whole call is one request. Unlike fal and Replicate this one hands back the
-// image itself - a GPT image model always answers with base64 and never with a URL - so
-// there is no link to follow.
+// The HTTP gateway adapter for OpenAI's images endpoint: the platform's own `fetch` and
+// nothing else, because the whole call is one request. Unlike fal and Replicate this one
+// hands back the image itself - a GPT image model always answers with base64, never a URL -
+// so there is no link to follow.
 export const openAiImagesBase = "https://api.openai.com/v1";
-// `logic/02` §Q15: the dropdown is filled from what the provider offers, and `/v1/models`
+// The dropdown is filled from what the provider offers, and `/v1/models`
 // lists every model on the account, chat and embeddings among them, so the image
 // shortlist is this adapter's own data. These are the four GPT image models OpenAI
 // documents; adding the next one is a line here and no code change anywhere else.
@@ -19,9 +18,9 @@ export const openAiImageModels = [
     { id: "gpt-image-1", name: "GPT Image 1" },
     { id: "gpt-image-1-mini", name: "GPT Image 1 mini" },
 ];
-// `logic/09` step 1: "the provider's closest supported size to the run's aspect". The
-// standard GPT image sizes are 3:2 and 2:3, so 16:9 is asked for as 1536×1024 and the
-// remaining sliver is cropped by the render (`logic/11` step 4).
+// The provider's closest supported size to the run's aspect. The standard GPT image sizes are
+// 3:2 and 2:3, so 16:9 is asked for as 1536×1024 and the remaining sliver is cropped by the
+// render.
 const standard = {
     "16:9": "1536x1024",
     "9:16": "1024x1536",
@@ -34,7 +33,7 @@ const exact = {
     "9:16": "864x1536",
 };
 const arbitrarySizes = /^gpt-image-2/;
-// A wire payload is narrowed, never cast (01-architecture §Q10, §Q33).
+// A wire payload is narrowed, never cast.
 const generated = z.object({ data: z.array(z.object({ b64_json: z.string().nullish() })) });
 const errorBody = z.object({
     error: z.object({
@@ -43,7 +42,7 @@ const errorBody = z.object({
         code: z.string().nullish(),
     }),
 });
-// `logic/09` §Q74: a content-policy refusal is the provider's final answer and is never
+// A content-policy refusal is the provider's final answer and is never
 // retried. OpenAI names it in the body rather than in the status, so the code is what
 // tells a declined prompt from a malformed request that shares its 400.
 const refusalCodes = ["moderation_blocked", "content_policy_violation"];
@@ -62,11 +61,11 @@ export function openAiImage(deps) {
                 body: JSON.stringify({
                     model: req.model,
                     prompt: req.prompt,
-                    // `logic/09` step 2 sends Number as that many independent calls, each its own
-                    // resumable piece, so one image per request is what the stage asks for.
+                    // The stage sends Number as that many independent calls, one piece each, so one
+                    // image per request is what it asks for.
                     n: 1,
                     size: sizeFor(req.model, req.aspect),
-                    // No `quality` and no `background`: step 2 asks for the provider's default
+                    // No `quality` and no `background`: the stage asks for the provider's default
                     // quality and style, which is what leaving them off means.
                 }),
             });
@@ -96,16 +95,14 @@ function decode(b64) {
     return { bytes, mime };
 }
 function keyOf(deps) {
-    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
-    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no OpenAI image key is stored" });
     }
     return key;
 }
-// Only the adapter can read a vendor's status code, so only the adapter names the kind;
-// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+// Only the adapter sees the vendor's status code, so only the adapter names the kind.
 function kindOf(status, code) {
     if (code !== undefined && code !== null && refusalCodes.includes(code)) {
         return "refusal";
@@ -116,17 +113,15 @@ function kindOf(status, code) {
     if (status === 429) {
         return "rate_limit";
     }
-    // ceiling: everything else is `other` and is retried, so a prompt past the model's
-    // length limit fails the same way four times over. A terminal kind for "this request
-    // will never work" would have to be added to the port's error contract first, which is
-    // not this adapter's to widen.
+    // ceiling: everything else is `other` and is retried, so a prompt past the model's length
+    // limit fails the same way four times over. A terminal "this will never work" kind has to
+    // reach the port's error contract first, which is not this adapter's to widen.
     return "other";
 }
 async function failure(response) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
-    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
-    // error body is free to quote the key back and this is the first place it is held.
+    // The provider's own words, through the redactor - an error body may quote the key back.
     const message = redact(parsed.success ? parsed.data.error.message : text.trim() || response.statusText);
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));
     return providerError({

package/dist/adapters/image/replicate.js

@@ -3,30 +3,27 @@ import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { retryAfter } from "../retry-after.js";
 import { downloadImage } from "./bytes.js";
-// The HTTP gateway adapter for Replicate (01-architecture Module boundaries). `fetch`,
-// the injected clock, and the downloader beside this file; no SDK. `replicate` the package
-// exists and wraps exactly the two requests below, so 05-dependencies' rung 3 covers it.
+// The HTTP gateway adapter for Replicate: `fetch`, the injected clock and the downloader
+// beside this file, no SDK. The `replicate` package wraps exactly the two requests below, so
+// the platform's own `fetch` covers it.
 export const replicateBase = "https://api.replicate.com/v1";
-// `Prefer: wait` holds the connection open while the model runs, up to the 60 s ceiling
-// Replicate documents. A model slower than that answers `starting` instead, and the
-// prediction has to be polled - which is why this adapter takes a clock. The attempt
-// wrapper's 300 s (`logic/09` §Q77) is what ends the polling, through the request signal.
+// `Prefer: wait` holds the connection open while the model runs, up to the 60 s Replicate
+// documents. A slower model answers `starting` and has to be polled, which is why this
+// adapter takes a clock. The wrapper's 300 s ends the polling.
 export const replicateWaitSeconds = 60;
 export const replicatePollMs = 2000;
-// `logic/02` §Q15: the model dropdown is filled from what the provider offers. Replicate's
-// model index lists every model on the platform, text and video among them, so the
-// text-to-image shortlist is this adapter's own data and adding one is a line here.
-// ceiling: each entry has to take `prompt`, `aspect_ratio` and `output_format`, which is
-// the convention across Replicate's official image models but not a guarantee; a model
-// that spells its inputs differently needs a per-model input map first.
+// The model dropdown comes from what the provider offers, but Replicate's index lists every
+// model on the platform, so the text-to-image shortlist is this adapter's own data and adding
+// one is a line here. ceiling: each entry has to take `prompt`, `aspect_ratio` and
+// `output_format` - the convention across Replicate's official image models, not a guarantee. A
+// model spelling its inputs differently needs an input map.
 export const replicateModels = [
     { id: "black-forest-labs/flux-1.1-pro", name: "FLUX 1.1 [pro]" },
     { id: "black-forest-labs/flux-dev", name: "FLUX.1 [dev]" },
     { id: "black-forest-labs/flux-schnell", name: "FLUX.1 [schnell]" },
 ];
-// A wire payload is narrowed, never cast (01-architecture §Q10, §Q33). `output` is one
-// URL on the models that make a single image and an array on the ones that can make
-// several, so both shapes are read and the first is taken.
+// A wire payload is narrowed, never cast. `output` is one URL
+// on single-image models and an array on the rest, so both shapes are read.
 const prediction = z.object({
     status: z.string(),
     output: z.union([z.string(), z.array(z.string())]).nullish(),
@@ -34,8 +31,8 @@ const prediction = z.object({
     urls: z.object({ get: z.string().optional() }).nullish(),
 });
 const errorBody = z.object({ detail: z.string().optional(), title: z.string().optional() });
-// The two terminal states that are not success. `canceled` cannot happen here - nothing
-// cancels a prediction this app made - but reading it as terminal beats polling forever.
+// `canceled` cannot happen here - nothing cancels a prediction this app made - but reading
+// it as terminal beats polling forever.
 const settled = ["succeeded", "failed", "canceled"];
 export function replicateImage(deps) {
     return {
@@ -53,11 +50,10 @@ export function replicateImage(deps) {
                 body: JSON.stringify({
                     input: {
                         prompt: req.prompt,
-                        // `logic/09` step 1: Replicate takes the aspect itself, so the closest
-                        // supported size is the exact one.
+                        // Replicate takes the aspect, so the closest size is exact.
                         aspect_ratio: req.aspect,
-                        // The port stores a PNG or a JPEG and these models default to WebP.
-                        // Nothing else is set: step 2 asks for the provider's own quality and style.
+                        // The port stores PNG or JPEG and these models default to WebP. Nothing else
+                        // is set: the stage asks for the provider's own quality and style.
                         output_format: "png",
                     },
                 }),
@@ -66,8 +62,7 @@ export function replicateImage(deps) {
                 throw await failure(response);
             }
             const url = await settle(deps, parse(await response.text()), req.signal);
-            // The download is inside the attempt with the call that produced the link, so a
-            // link that 404s is a failed attempt rather than a broken file on the project.
+            // The download rides inside the attempt: a link that 404s is a failed attempt.
             return await downloadImage({
                 fetch: deps.fetch,
                 provider: "Replicate",
@@ -77,8 +72,8 @@ export function replicateImage(deps) {
         },
     };
 }
-// `Prefer: wait` answers `starting` when the model outlived its 60 s, and Replicate's own
-// guidance is to poll `urls.get` until the prediction settles.
+// `Prefer: wait` answers `starting` when the model outlived its 60 s; Replicate's guidance
+// is to poll `urls.get` until the prediction settles.
 async function settle(deps, first, signal) {
     let current = first;
     while (!settled.includes(current.status)) {
@@ -109,33 +104,30 @@ function outputOf(current) {
     }
     return url;
 }
-// `logic/09` §Q74: a content-policy refusal is the provider's final answer and is never
-// retried. Replicate reports one as a settled prediction whose `error` says so, with the
-// same 201 the successful call had, so the text is what tells them apart.
+// A content-policy refusal is final and never retried. Replicate reports one as a settled
+// prediction whose `error` says so, under the same 201 a success gets, so the text is all that
+// tells them apart.
 const refusalWords = /\b(nsfw|sensitive|safety|content polic|flagged|moderat)/i;
 function declined(current) {
     // The provider's own words, verbatim, through the same redactor the wrapper uses.
     const message = redact(current.error ?? `the prediction ended ${current.status}`);
-    // ceiling: read off the sentence, because Replicate carries no machine-readable reason
-    // on a failed prediction. A phrase the list does not know is retried three more times
-    // and costs the user three more images; a structured field would settle it, and the
-    // upgrade is to read one when Replicate ships it.
+    // ceiling: read off the sentence, because a failed prediction carries no machine-readable
+    // reason. A phrase the list does not know costs the user three more images; the upgrade
+    // is a structured field, when Replicate ships one.
     return providerError({
         kind: refusalWords.test(message) ? "refusal" : "other",
         message: `Replicate answered: ${message}`,
     });
 }
 function auth(deps) {
-    // `logic/02` §Q13: an attempt that finds no key fails rather than calling anonymously.
-    // `missing_key` rather than `auth` because the same rule makes it terminal.
+    // `missing_key`, not `auth`, because that rule makes it terminal.
     const key = deps.key();
     if (key === undefined || key === "") {
         throw providerError({ kind: "missing_key", message: "no Replicate key is stored" });
     }
     return { Authorization: `Bearer ${key}` };
 }
-// Only the adapter can read a vendor's status code, so only the adapter names the kind;
-// the attempt wrapper maps it and nothing downstream classifies again (03-conventions).
+// Only the adapter sees the vendor's status code, so only the adapter names the kind.
 function kindOf(status) {
     if (status === 401 || status === 403) {
         return "auth";
@@ -143,17 +135,15 @@ function kindOf(status) {
     if (status === 429) {
         return "rate_limit";
     }
-    // ceiling: everything else is `other` and is retried, so a 402 with no credit left
-    // fails the same way four times over. A terminal kind for "this request will never
-    // work" would have to be added to the port's error contract first, which is not this
-    // adapter's to widen.
+    // ceiling: everything else is `other` and is retried, so a 402 with no credit left fails the
+    // same way four times over. A terminal "this will never work" kind has to reach the port's
+    // error contract first, which is not this adapter's to widen.
     return "other";
 }
 async function failure(response) {
     const text = await response.text().catch(() => "");
     const parsed = errorBody.safeParse(safeJson(text));
-    // The provider's own words, verbatim, through the same redactor the wrapper uses: an
-    // error body is free to quote the key back and this is the first place it is held.
+    // The provider's own words, through the redactor - an error body may quote the key back.
     const detail = parsed.success ? (parsed.data.detail ?? parsed.data.title) : undefined;
     const message = redact(detail ?? text.trim());
     const retryAfterMs = retryAfter(response.headers.get("retry-after"));

package/dist/adapters/llm/claude-code.js

@@ -3,11 +3,10 @@ import { redact } from "../../kernel/log.js";
 import { providerError } from "../../kernel/ports/model.js";
 import { cliEvent, cliShaped, endedWithout, promptOf } from "./run-cli.js";
 import { lines } from "./sse-lines.js";
-// The local-agent adapter for Claude Code (01-architecture Module boundaries): spawned
-// non-interactively, authenticated by the CLI's own login, no key anywhere in this file.
-// Readiness is not computed here - `adapters/**` may not import `slices/**`, and
-// `slices/settings/cli-status.ts` already probes the binary per request (`logic/02`
-// §Q135). The registry `main.ts` builds is where this adapter and that probe meet.
+// The local-agent adapter for Claude Code: spawned non-interactively, authenticated by the
+// CLI's own login, no key anywhere in this file. Readiness is not computed here - `adapters/**`
+// may not import `slices/**`, and `slices/settings/cli-status.ts` already probes the binary per
+// request. The registry `main.ts` builds is where this adapter and that probe meet.
 export const claudeCodeBinary = "claude";
 // The CLI takes an alias for the latest model of a family (`claude --help`, 2.1.258).
 // ceiling: a fixed list, because the CLI has no offline command that prints the models an
@@ -19,13 +18,12 @@ export const claudeCodeModels = [
     { id: "sonnet", name: "Claude Sonnet (latest)" },
     { id: "haiku", name: "Claude Haiku (latest)" },
 ];
-// Measured on 2.1.258, not assumed: with the built-in tools left alone, a `-p` run of this
-// CLI still reached for ToolSearch and WebFetch, and the machine's MCP servers were loaded
-// into the session. Neither belongs in a content pipeline - the article stage must not
-// quietly ground itself on the web, since `logic/06` §Q47 makes grounding an explicit ask,
-// and no stage should be able to touch the disk. `--tools ""` empties the built-in set and
-// `--strict-mcp-config` drops the user's MCP servers; the init event of a run with both
-// reports `"tools":[]` and `"mcp_servers":[]`.
+// Measured on 2.1.258, not assumed: with the built-in tools left alone, a `-p` run of this CLI
+// still reached for ToolSearch and WebFetch, and the machine's MCP servers were loaded into the
+// session. Neither belongs in a content pipeline - grounding on the web is an explicit ask,
+// never something a stage does quietly, and no stage should touch the disk. `--tools ""`
+// empties the built-in set and `--strict-mcp-config` drops the user's MCP servers; the init
+// event of a run with both reports `"tools":[]` and `"mcp_servers":[]`.
 export function claudeCodeArgs(req) {
     return [
         "-p",
@@ -103,7 +101,7 @@ export function claudeCodeLlm(deps) {
         }
         catch (error) {
             // A cancelled stage killed the child; the reason the user's cancel carried is what
-            // the runner expects back, not whatever the half-closed pipe threw (`logic/13`).
+            // the runner expects back, not whatever the half-closed pipe threw.
             req.signal.throwIfAborted();
             throw error;
         }
@@ -113,8 +111,8 @@ export function claudeCodeLlm(deps) {
             run.kill();
         }
         // A cancelled run ends its stream the same way an exhausted one does: the child was
-        // killed, so stdout simply stopped. `logic/13` §Q112 says an aborted call counts
-        // nothing, so it must not be reported as the provider failing.
+        // killed, so stdout simply stopped. An aborted call counts as nothing, so it must not
+        // be reported as the provider failing.
         req.signal.throwIfAborted();
         // The stream ended with no result event at all.
         throw providerError({
@@ -124,10 +122,9 @@ export function claudeCodeLlm(deps) {
     }
     return {
         id: "claude-code",
-        // The CLI emits whole assistant turns rather than token deltas, which is still enough
-        // for the idle timeout of `logic/01` §Q62 to see life on the stream.
-        // ceiling: `--include-partial-messages` would give per-token deltas for the streamed
-        // article of `logic/07` step 2; it is the upgrade when the page needs finer text.
+        // Whole assistant turns rather than token deltas, still enough for the idle timeout to
+        // see life on the stream. ceiling: `--include-partial-messages` would give per-token
+        // deltas for the streamed article; it is the upgrade when the page needs finer text.
         capabilities: { streams: true, reportsUsage: true, webSearch: true },
         models: () => Promise.resolve(claudeCodeModels),
         complete,