fix(planner): drain a byproduct when its consumer is a terminal sink

Adding a consumer through a byproduct's surplus chip marked the good made
but only drained it (net = 0, forcing the sink to run) for the literal
pure-void shape — no products, or only returning less of the same good. A
Py hard-mode disposal recipe like coal-gas-void (50 coal-gas -> 1 ash)
makes ash, so it failed that test: the good stayed merely made, its
surplus vented as a free export, and the void idled at 0 next to it — the
gesture looked like it did nothing.

Generalize the test to TERMINAL sinks: net-consumes the good AND none of
its other products feeds anything else in the block (everything it makes
leaves). That is the actual line between 'consume my surplus' and
'restructure production' — coal-gas -> ash (nothing here uses ash) drains
and runs; block 27's grade-2 -> grade-3, whose output re-enters the
chain, is still only made, never drained, so forcing it can't cascade.
Extracted to lib/sink-classify.ts (drainsOnConsume) with unit tests for
both shapes; the block's consumed-goods set comes from the current solve.

Verified on the live carbolic-oil block: coal-gas-void goes 0 -> 2.34
machines and the 117/s coal-gas export drops to zero, chain unchanged.

Refs #91

Author: ApocDev

app/src/lib/sink-classify.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vite-plus/test";
+import { drainsOnConsume } from "./sink-classify.ts";
+
+const good = (name: string, amount: number) => ({ name, amount });
+
+describe("drainsOnConsume", () => {
+  it("drains a pure void whose output leaves the block (coal-gas → ash)", () => {
+    // coal-gas-void: 50 coal-gas in, 1 ash out; nothing in the block uses ash
+    expect(
+      drainsOnConsume({
+        good: "coal-gas",
+        ingredients: [good("coal-gas", 50)],
+        products: [good("ash", 1)],
+        consumedInBlock: new Set(["coal", "raw-coal", "tar", "steam", "water"]),
+      }),
+    ).toBe(true);
+  });
+
+  it("does NOT drain a reprocessor whose output re-enters the chain (block 27)", () => {
+    // grade-2-crush: consumes grade-2-iron, makes grade-3-iron which the chain uses
+    expect(
+      drainsOnConsume({
+        good: "grade-2-iron",
+        ingredients: [good("grade-2-iron", 4)],
+        products: [good("grade-3-iron", 2), good("iron-slime", 1)],
+        consumedInBlock: new Set(["grade-2-iron", "grade-3-iron", "iron-slime"]),
+      }),
+    ).toBe(false);
+  });
+
+  it("drains a product-less void", () => {
+    expect(
+      drainsOnConsume({
+        good: "pollution",
+        ingredients: [good("pollution", 10)],
+        products: [],
+        consumedInBlock: new Set(["iron-plate"]),
+      }),
+    ).toBe(true);
+  });
+
+  it("drains when it returns LESS of the same good (net reducer)", () => {
+    expect(
+      drainsOnConsume({
+        good: "sludge",
+        ingredients: [good("sludge", 10)],
+        products: [good("sludge", 3)],
+        consumedInBlock: new Set(),
+      }),
+    ).toBe(true);
+  });
+
+  it("does NOT drain a net PRODUCER of the good", () => {
+    // consumes 10, makes 20 of the same good — not a sink
+    expect(
+      drainsOnConsume({
+        good: "steam",
+        ingredients: [good("steam", 10)],
+        products: [good("steam", 20)],
+        consumedInBlock: new Set(),
+      }),
+    ).toBe(false);
+  });
+
+  it("drains a multi-output void when every other product leaves the block", () => {
+    expect(
+      drainsOnConsume({
+        good: "waste-water",
+        ingredients: [good("waste-water", 100)],
+        products: [good("mineral-sludge", 1), good("stone", 1)],
+        consumedInBlock: new Set(["waste-water"]), // neither product used elsewhere
+      }),
+    ).toBe(true);
+  });
+
+  it("does NOT drain when ANY other product feeds the block", () => {
+    expect(
+      drainsOnConsume({
+        good: "waste-water",
+        ingredients: [good("waste-water", 100)],
+        products: [good("stone", 1), good("iron-ore", 1)],
+        consumedInBlock: new Set(["iron-ore"]), // iron-ore re-enters the chain
+      }),
+    ).toBe(false);
+  });
+});

app/src/lib/sink-classify.ts

@@ -0,0 +1,32 @@
+/** When you add a recipe to consume a byproduct (clicking its surplus chip),
+ * should the block DRAIN that good — pin it to net = 0 so the surplus MUST be
+ * consumed in-block rather than vented — or only mark it made?
+ *
+ * Marking made alone forbids importing the good (the block-27 import-and-
+ * restructure trap) but still lets any surplus leave as an export, so a pure
+ * disposal recipe idles at 0 next to an untouched export. Draining forces it to
+ * run. The catch: draining a consumer whose output RE-ENTERS the chain
+ * restructures production (block 27's grade-2 → grade-3, which the chain then
+ * consumes), which is not what "deal with my surplus" means.
+ *
+ * The line is TERMINALITY: drain only when the consumer net-consumes the good
+ * AND none of its other products feeds anything else in the block — everything
+ * it makes leaves. A void (coal-gas → ash, nothing here uses ash) qualifies; a
+ * reprocessor does not. `consumedInBlock` is the set of goods the block's other
+ * recipes consume, read from the current solve (the block before this add), so
+ * a terminal product that only starts leaving after the add still reads right. */
+export function drainsOnConsume(opts: {
+  good: string;
+  ingredients: readonly { name: string; amount?: number | null }[];
+  products: readonly { name: string; amount?: number | null }[];
+  consumedInBlock: ReadonlySet<string>;
+}): boolean {
+  const { good, ingredients, products, consumedInBlock } = opts;
+  const sum = (arr: readonly { name: string; amount?: number | null }[], name: string) =>
+    arr.filter((c) => c.name === name).reduce((s, c) => s + (c.amount ?? 0), 0);
+  // a net producer of the good isn't a sink for it
+  const netConsumes = sum(products, good) < sum(ingredients, good);
+  // every other product leaves the block (nothing else consumes it)
+  const terminal = products.every((c) => c.name === good || !consumedInBlock.has(c.name));
+  return netConsumes && terminal;
+}

app/src/routes/block.$id.tsx

@@ -18,6 +18,7 @@ import {
 } from "../server/factorio";
 import { exportBlockFn } from "../server/export-fns";
 import { registerBlockEditor } from "../lib/block-editors";
+import { drainsOnConsume } from "../lib/sink-classify";
 import { downloadJson } from "../lib/download";
 import { exportFileName } from "../lib/plan-export";
 import { toast } from "../lib/toast-store";
@@ -466,26 +467,36 @@ function Block({ blockId }: { blockId: number }) {
     // Adding a CONSUMER via a byproduct's chip means "deal with MY surplus":
     // mark the good made — without this, a reprocessing recipe lets the plan
     // IMPORT the byproduct and shut down the real producers (the block-27
-    // failure). A reprocessor then absorbs surplus on its own (recycling is
-    // cheaper than making more). A pure SINK (void: no products, or only
-    // returning less of the same good) makes nothing the objective wants, so
-    // it also gets a drain pin — "this good's surplus must be consumed here"
-    // (net = 0) — or it would idle at 0 with the export untouched.
+    // failure). Then, when the consumer is a TERMINAL sink, also DRAIN the good
+    // (net = 0 → the surplus must be consumed in-block, not vented) so the sink
+    // actually runs instead of idling at 0 next to an untouched export.
+    //
+    // Terminal = the consumer net-consumes the good AND none of its OTHER
+    // products feeds anything else in this block (they all leave). That's the
+    // line between "consume the surplus" and "restructure production": a pure
+    // void (coal-gas → ash, and nothing here uses ash) drains cleanly; a
+    // reprocessor whose output re-enters the chain (block 27's grade-2 →
+    // grade-3, which the chain consumes) is only marked made, never drained,
+    // so forcing it can't cascade. Read from the CURRENT solve (the block
+    // before this add), so newly-added terminal products still read as leaving.
     if (pickFor?.mode === "consume") {
       const good = pickFor.name;
       if (!goals.some((g) => g.name === good)) doc.markMade(good);
       const cand = picker.data?.find((c) => c.name === name);
-      const intake = cand?.ingredients
-        .filter((c) => c.name === good)
-        .reduce((s, c) => s + (c.amount ?? 0), 0);
-      const sameGoodOut = cand?.products
-        .filter((c) => c.name === good)
-        .reduce((s, c) => s + (c.amount ?? 0), 0);
-      const isSink =
-        cand != null &&
-        (cand.products.length === 0 ||
-          (cand.products.every((c) => c.name === good) && (sameGoodOut ?? 0) < (intake ?? 0)));
-      if (isSink) doc.setPin({ kind: "drain", recipe: name, item: good });
+      if (cand) {
+        const consumedInBlock = new Set(
+          (res?.rows ?? []).flatMap((row) => row.ingredients.map((i) => i.name)),
+        );
+        if (
+          drainsOnConsume({
+            good,
+            ingredients: cand.ingredients,
+            products: cand.products,
+            consumedInBlock,
+          })
+        )
+          doc.setPin({ kind: "drain", recipe: name, item: good });
+      }
     }
     // label the save for the undo stack — the picker rows carry the display name
     const display = picker.data?.find((c) => c.name === name)?.display;

docs/solver.md

@@ -40,16 +40,23 @@ single-`target` shape. The item rules:
   incidental byproduct just offsets the import — a 0.02/s side-product of
   something else is never scaled up to cover a 10/s demand.
 - **Draining a byproduct**: adding a consumer through a byproduct's chip marks
-  the good made AND — when the chosen recipe is a pure sink (a void: no
-  products, or only returning less of the same good) — records a **drain**
-  (`net = 0`): the surplus must be consumed in-block, which is what forces a
-  void to run at all (it produces nothing the objective wants). A reprocessing
-  consumer needs no drain — once the good is made (import forbidden), recycling
-  the surplus is cheaper than making more, so the optimizer uses it; without
-  the made mark it would instead IMPORT the byproduct and idle the real
-  producers. The solve also reports `importedProducible` — imports of goods an
-  enabled in-block recipe produces, the tell-tale of that trap — and the import
-  chip offers one click to claim the good in-block.
+  the good made AND — when the chosen recipe is a **terminal sink** — records a
+  **drain** (`net = 0`): the surplus must be consumed in-block, which is what
+  forces a void to run at all (it produces nothing the objective wants).
+  Terminal means the recipe net-consumes the good and none of its *other*
+  products feeds anything else in the block — everything it makes leaves
+  (`lib/sink-classify.ts`, `drainsOnConsume`, tested). That single test is the
+  line between "consume my surplus" and "restructure production": a void like
+  coal-gas → ash (nothing here uses ash) drains and runs; a reprocessor whose
+  output re-enters the chain (block 27's grade-2 → grade-3, which the chain
+  consumes) is only marked made, never drained, so forcing it can't cascade.
+  A reprocessing consumer needs no drain — once the good is made (import
+  forbidden), recycling the surplus is cheaper than making more, so the
+  optimizer uses it; without the made mark it would instead IMPORT the
+  byproduct and idle the real producers. The solve also reports
+  `importedProducible` — imports of goods an enabled in-block recipe produces,
+  the tell-tale of that trap — and the import chip offers one click to claim
+  the good in-block.
 - **Pins** (`pins` in the doc, in building counts) constrain single rows:
   `count` = always run exactly N buildings (supply-push — this is how byproducts
   route into in-block consumers), `cap` = at most N (a built-capacity ceiling;