fix(scenario): prevent sink feedback from ratcheting goals

Author: ApocDev

app/src/server/factorio.ts

@@ -404,6 +404,13 @@ export const applyFactoryRebalanceFn = createServerFn({ method: "POST" })
     let passes = 0;
     let residual = 0;
     const failedBlocks = new Map<number, string>();
+    const sinkBaselines = new Map(
+      base.flatMap((block) =>
+        [...block.startGoals]
+          .filter(([, rate]) => rate < 0)
+          .map(([good, rate]) => [`${block.id}\u0000${good}`, rate] as const),
+      ),
+    );
     for (; passes < REBALANCE_MAX_PASSES; passes++) {
       // Pass one uses SQLite's persisted boundary flows. On later passes, only
       // re-solve docs whose rate changed; unchanged blocks keep their latest
@@ -452,7 +459,7 @@ export const applyFactoryRebalanceFn = createServerFn({ method: "POST" })
         status = "Infeasible";
         break;
       }
-      const result = factoryBalanceStep(withFlows, overrides);
+      const result = factoryBalanceStep(withFlows, overrides, sinkBaselines);
       status = result.status;
       // Goal changes are the only actionable controls. A scale on a utility or
       // goal-less block cannot be applied and must not keep the iteration alive.

app/src/server/factory-balance-step.server.ts

@@ -25,6 +25,7 @@ type GoalChange = {
 export function factoryBalanceStep(
   blocks: BlockWithFlows[],
   demandOverrides: Record<string, number> = {},
+  sinkBaselines: Map<string, number> = new Map(),
 ) {
   const kindOf = new Map<string, string>();
   const produced = new Map<string, number>();
@@ -157,11 +158,18 @@ export function factoryBalanceStep(
   for (const [good, entries] of sinks) {
     if (producers.has(good)) continue;
     const available = incidental.get(good) ?? 0;
-    if (available <= EPS) continue;
-    const current = entries.reduce((sum, entry) => sum + entry.rate, 0);
+    const baseline = entries.map((entry) =>
+      Math.abs(sinkBaselines.get(`${entry.block.id}\u0000${good}`) ?? -entry.rate),
+    );
+    const baselineTotal = baseline.reduce((sum, rate) => sum + rate, 0);
+    const required = Math.max(available, baselineTotal);
     entries.forEach((entry, index) => {
       const allocation =
-        current > EPS ? available * (entry.rate / current) : index === 0 ? available : 0;
+        baselineTotal > EPS
+          ? required * (baseline[index]! / baselineTotal)
+          : index === 0
+            ? required
+            : 0;
       addChange(entry.block, good, -allocation);
     });
   }

app/src/server/factory-balance-step.test.ts

@@ -89,6 +89,19 @@ describe("factoryBalanceStep", () => {
     );
   });
 
+  it("returns an enlarged sink to its starting baseline when surplus disappears", () => {
+    const sink = block(2, "Sink", { name: "waste", rate: -10 }, [
+      { item: "waste", kind: "fluid", role: "import", rate: 10 },
+    ]);
+    const baselines = new Map([[`${sink.id}\u0000waste`, -2]]);
+
+    const result = factoryBalanceStep([sink], {}, baselines);
+
+    expect(result.goalChanges).toContainEqual(
+      expect.objectContaining({ good: "waste", currentRate: -10, requiredRate: -2 }),
+    );
+  });
+
   it("leaves a good with no configured producer as a raw import", () => {
     const gears = block(1, "Gears", { name: "gear", rate: 1 }, [
       { item: "gear", kind: "item", role: "primary", rate: 1 },

app/src/server/factory-balance.server.ts

@@ -85,7 +85,14 @@ export async function previewFactoryBalance(demandOverrides: Record<string, numb
     );
 
   const initialModels = await models();
-  const initial = factoryBalanceStep(initialModels, demandOverrides);
+  const sinkBaselines = new Map(
+    base.flatMap((entry) =>
+      [...entry.startGoals]
+        .filter(([, rate]) => rate < 0)
+        .map(([good, rate]) => [`${entry.block.id}\u0000${good}`, rate] as const),
+    ),
+  );
+  const initial = factoryBalanceStep(initialModels, demandOverrides, sinkBaselines);
   let currentModels = initialModels;
   let settled = initial;
   let failed = false;
@@ -133,7 +140,7 @@ export async function previewFactoryBalance(demandOverrides: Record<string, numb
       break;
     }
     currentModels = await models();
-    settled = factoryBalanceStep(currentModels, demandOverrides);
+    settled = factoryBalanceStep(currentModels, demandOverrides, sinkBaselines);
   }
   const hitPassLimit = passes >= 15 && settled.goalChanges.length > 0;
 

app/src/server/factory-rebalance.test.ts

@@ -367,23 +367,34 @@ describe("applyFactoryRebalanceFn solve reuse", () => {
     };
     vi.mocked(blockCompute.computeBlock).mockResolvedValue(solved as never);
     vi.mocked(factoryBalance.factoryBalanceStep)
-      .mockImplementationOnce((blocks) => ({
-        ...factoryResult(blocks, { 1: 1 }),
-        goalChanges: [
-          {
-            id: 1,
-            name: "Tar",
-            good: "scrude",
-            kind: "fluid",
-            currentRate: -20,
-            requiredRate: -61.88,
-            scale: 3.094,
-            delta: -41.88,
-            goal: true,
-          },
-        ],
-      }))
-      .mockImplementationOnce((blocks) => factoryResult(blocks, { 1: 1 }));
+      .mockImplementationOnce((blocks, _overrides, sinkBaselines) => {
+        expect(sinkBaselines).toEqual(
+          new Map([
+            [`1\u0000tar`, -9.575],
+            [`1\u0000scrude`, -20],
+          ]),
+        );
+        return {
+          ...factoryResult(blocks, { 1: 1 }),
+          goalChanges: [
+            {
+              id: 1,
+              name: "Tar",
+              good: "scrude",
+              kind: "fluid",
+              currentRate: -20,
+              requiredRate: -61.88,
+              scale: 3.094,
+              delta: -41.88,
+              goal: true,
+            },
+          ],
+        };
+      })
+      .mockImplementationOnce((blocks, _overrides, sinkBaselines) => {
+        expect(sinkBaselines?.get(`1\u0000scrude`)).toBe(-20);
+        return factoryResult(blocks, { 1: 1 });
+      });
 
     const result = await applyFactoryRebalanceFn({ data: {} });
 

docs/development/solver.md

@@ -328,7 +328,10 @@ Factory Scenario balances enabled blocks through repeated goal-and-solve passes,
 YAFC's factory balancing. Each pass reads the persisted boundary flows, keeps terminal positive
 goals fixed, and computes the current mismatch for every good. Intermediate positive goals move
 to downstream demand after incidental byproducts are credited; negative goals move to absorb
-byproduct-only surplus.
+byproduct-only surplus. The negative rates present when balancing starts are retained as sink
+baselines: a pass may enlarge them to absorb real surplus, but a later pass returns them toward
+those baselines when the surplus disappears. This prevents transient byproducts from ratcheting
+consumer blocks upward across the iteration loop.
 
 The actionable output is one change per throughput goal—it never collapses a multi-goal block
 back to its first goal. **Balance factory** updates those goals, re-solves each affected block,

docs/guide/balance.md

@@ -70,7 +70,9 @@ if a Tar block consumes Shale oil as its second goal, surplus Shale oil produces
 Terminal goals—goods nothing else in the factory consumes—anchor the balance. Intermediate
 production goals move to cover downstream demand, while negative goals can move to absorb
 surplus. After each change PyOps re-solves the affected block and repeats until its boundary
-flows settle. A valid producer currently set to `0/s` is probed at a normalized rate, so
+flows settle. A consume goal can temporarily grow to handle that surplus, but it will not be
+left above the rate it had when balancing started after the surplus disappears. A valid producer
+currently set to `0/s` is probed at a normalized rate, so
 **Balance factory** can start it instead of reporting an infeasible zero-times-scale row.
 
 If no enabled block can supply a required ingredient, Scenario keeps the solve usable and