Add proposed cable-sizing module

Isolated module (mirrors src/external-model/ dependency direction) that
adds an on-demand, DIN VDE 0298-4 referenced cable cross-section
calculator: a click-on-a-circuit input mask for laying method,
insulation, ambient temperature, grouping and voltage-drop limit that
suggests a cross-section for the circuit cableCrossSection/cableLength
fields. Applying a suggestion goes through the existing circuit.update
command (expectedRevision, undo/redo) unchanged - nothing here writes
to circuits directly or touches the revision/command system. See
docs/cable-sizing-module.md for the full rationale, API contract,
verification status and maintenance plan. Proposal, not yet reviewed
by the project owner - see the docs file.

423 existing + 11 new tests pass, build:api/build:web/typecheck:scripts
clean.

tests/cable-sizing-calculation.repository.test.ts

@@ -0,0 +1,152 @@
+import path from "node:path";
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { eq } from "drizzle-orm";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import { createDatabaseContext, type DatabaseContext } from "../src/db/database-context.js";
+import { CableSizingCalculationRepository } from "../src/db/repositories/cable-sizing-calculation.repository.js";
+import { circuitLists } from "../src/db/schema/circuit-lists.js";
+import { circuitSections } from "../src/db/schema/circuit-sections.js";
+import { circuits } from "../src/db/schema/circuits.js";
+import { projects } from "../src/db/schema/projects.js";
+import { DistributionBoardFixtureRepository } from "./support/distribution-board-fixture.js";
+
+function createRepository() {
+  const context = createDatabaseContext(":memory:");
+  migrate(context.db, { migrationsFolder: path.resolve("src", "db", "migrations") });
+  return new CableSizingCalculationRepository(context.db);
+}
+
+function createRepositoryWithCircuits(): {
+  repository: CableSizingCalculationRepository;
+  context: DatabaseContext;
+  circuitOneId: string;
+  circuitTwoId: string;
+} {
+  const context = createDatabaseContext(":memory:");
+  migrate(context.db, { migrationsFolder: path.resolve("src", "db", "migrations") });
+  context.db.insert(projects).values({ id: "project-1", name: "Test project" }).run();
+  const board = new DistributionBoardFixtureRepository(context.db).createWithCircuitListAndDefaultSections(
+    "project-1",
+    "UV-01"
+  );
+  const circuitList = context.db
+    .select()
+    .from(circuitLists)
+    .where(eq(circuitLists.distributionBoardId, board.id))
+    .get();
+  if (!circuitList) {
+    throw new Error("fixture did not create a circuit list");
+  }
+  const section = context.db
+    .select()
+    .from(circuitSections)
+    .where(eq(circuitSections.circuitListId, circuitList.id))
+    .get();
+  if (!section) {
+    throw new Error("fixture did not create a section");
+  }
+  const circuitOneId = "circuit-1";
+  const circuitTwoId = "circuit-2";
+  context.db
+    .insert(circuits)
+    .values([
+      {
+        id: circuitOneId,
+        circuitListId: section.circuitListId,
+        sectionId: section.id,
+        equipmentIdentifier: "-1F1.1",
+      },
+      {
+        id: circuitTwoId,
+        circuitListId: section.circuitListId,
+        sectionId: section.id,
+        equipmentIdentifier: "-1F1.2",
+      },
+    ])
+    .run();
+  return {
+    repository: new CableSizingCalculationRepository(context.db),
+    context,
+    circuitOneId,
+    circuitTwoId,
+  };
+}
+
+describe("CableSizingCalculationRepository", () => {
+  it("creates an entry with input/result JSON and defaults appliedToCircuit to false", () => {
+    const repository = createRepository();
+    const entry = repository.create({
+      id: "calc-1",
+      projectId: null,
+      circuitId: null,
+      equipmentIdentifier: "-1F1.1",
+      input: { layingMethod: "C" },
+      result: { recommendedCrossSectionMm2: 4 },
+      appliedToCircuit: 0,
+    });
+    assert.equal(entry.id, "calc-1");
+    assert.equal(entry.appliedToCircuit, 0);
+    assert.deepEqual(entry.input, { layingMethod: "C" });
+    assert.deepEqual(entry.result, { recommendedCrossSectionMm2: 4 });
+  });
+
+  it("lists entries by circuitId, most recent first", () => {
+    // createdAt defaults to SQLite's unixepoch() (second resolution), so two
+    // inserts in the same test can tie - pass explicit, distinct timestamps
+    // instead of racing the clock. circuitId has a real foreign key into
+    // circuits (foreign_keys = ON), so this needs actual circuit rows, not
+    // arbitrary strings.
+    const { repository, circuitOneId, circuitTwoId } = createRepositoryWithCircuits();
+    repository.create({
+      id: "calc-a",
+      projectId: null,
+      circuitId: circuitOneId,
+      equipmentIdentifier: null,
+      input: {},
+      result: {},
+      appliedToCircuit: 0,
+      createdAt: new Date(1000),
+    });
+    repository.create({
+      id: "calc-b",
+      projectId: null,
+      circuitId: circuitOneId,
+      equipmentIdentifier: null,
+      input: {},
+      result: {},
+      appliedToCircuit: 0,
+      createdAt: new Date(2000),
+    });
+    repository.create({
+      id: "calc-other-circuit",
+      projectId: null,
+      circuitId: circuitTwoId,
+      equipmentIdentifier: null,
+      input: {},
+      result: {},
+      appliedToCircuit: 0,
+      createdAt: new Date(3000),
+    });
+
+    const rows = repository.listByCircuit(circuitOneId);
+    assert.equal(rows.length, 2);
+    assert.equal(rows[0].id, "calc-b");
+    assert.equal(rows[1].id, "calc-a");
+  });
+
+  it("marks an entry as applied", () => {
+    const repository = createRepository();
+    repository.create({
+      id: "calc-1",
+      projectId: null,
+      circuitId: null,
+      equipmentIdentifier: null,
+      input: {},
+      result: {},
+      appliedToCircuit: 0,
+    });
+    const updated = repository.markApplied("calc-1");
+    assert.equal(updated?.appliedToCircuit, 1);
+  });
+});

tests/cable-sizing-calculation.test.ts

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  buildCableSizingAlerts,
+  calculateCableSizing,
+  isCableSizingDataVerified,
+  type CableSizingInput,
+} from "../src/cable-sizing/domain/cable-sizing-calculation.js";
+
+const BASE_INPUT: CableSizingInput = {
+  phase: 1,
+  mode: "power",
+  powerKw: 5,
+  cosPhi: 1,
+  voltage: 230,
+  lengthM: 30,
+  layingMethod: "C",
+  conductorMaterial: "copper",
+  insulation: "pvc",
+  ambientTemperatureC: 30,
+  groupingCircuits: 1,
+  maxVoltageDropPercent: 3,
+  harmonicNeutralLoad: "none",
+};
+
+describe("calculateCableSizing", () => {
+  it("matches the verified reference case (1~, 5 kW, 230 V, 30 m, method C, copper)", () => {
+    const result = calculateCableSizing(BASE_INPUT);
+    assert.equal(result.dataVerified, true);
+    assert.ok(Math.abs(result.operatingCurrentA - 21.739) < 0.01);
+    assert.equal(result.crossSectionByCapacityMm2, 2.5);
+    assert.equal(result.crossSectionByVoltageDropMm2, 4);
+    assert.equal(result.recommendedCrossSectionMm2, 4);
+  });
+
+  it("returns dataVerified: false and no numeric result for an unverified laying method", () => {
+    const result = calculateCableSizing({ ...BASE_INPUT, layingMethod: "A2" });
+    assert.equal(result.dataVerified, false);
+    assert.equal(result.recommendedCrossSectionMm2, null);
+    assert.equal(result.rows.length, 0);
+    // The operating current itself does not depend on the capacity table
+    // and is still reported so the UI can show at least that much.
+    assert.ok(Math.abs(result.operatingCurrentA - 21.739) < 0.01);
+  });
+
+  it("returns dataVerified: false for xlpe regardless of method", () => {
+    const result = calculateCableSizing({ ...BASE_INPUT, insulation: "xlpe" });
+    assert.equal(result.dataVerified, false);
+  });
+
+  it("isCableSizingDataVerified matches the six ported, verified methods only", () => {
+    for (const method of ["A1", "B2", "C", "E", "D1", "D2"] as const) {
+      assert.equal(isCableSizingDataVerified(method, "pvc"), true, method);
+    }
+    for (const method of ["A2", "B1", "F", "G"] as const) {
+      assert.equal(isCableSizingDataVerified(method, "pvc"), false, method);
+    }
+  });
+
+  it("applies the 0.86 harmonic reduction factor only for three-phase + 15to33Percent", () => {
+    const threePhase: CableSizingInput = {
+      ...BASE_INPUT,
+      phase: 3,
+      mode: "current",
+      currentA: 10,
+      powerKw: undefined,
+      voltage: 400,
+    };
+    const base = calculateCableSizing({ ...threePhase, harmonicNeutralLoad: "none" });
+    const derated = calculateCableSizing({
+      ...threePhase,
+      harmonicNeutralLoad: "15to33Percent",
+    });
+    assert.equal(base.harmonicReductionApplied, false);
+    assert.equal(derated.harmonicReductionApplied, true);
+    assert.ok(
+      Math.abs(derated.combinedDerationFactor - base.combinedDerationFactor * 0.86) < 1e-9
+    );
+
+    const singlePhaseWithHarmonics = calculateCableSizing({
+      ...BASE_INPUT,
+      harmonicNeutralLoad: "15to33Percent",
+    });
+    assert.equal(singlePhaseWithHarmonics.harmonicReductionApplied, false);
+  });
+
+  it("flags a simplified protection coordination mismatch", () => {
+    const result = calculateCableSizing({
+      ...BASE_INPUT,
+      existingProtectionRatedCurrentA: 1000,
+    });
+    assert.ok(result.protectionCoordination);
+    assert.equal(result.protectionCoordination?.coordinated, false);
+
+    const alerts = buildCableSizingAlerts(
+      { ...BASE_INPUT, existingProtectionRatedCurrentA: 1000 },
+      result
+    );
+    assert.ok(alerts.some((alert) => alert.text.includes("Koordination prüfen")));
+  });
+});
+
+describe("buildCableSizingAlerts", () => {
+  it("returns a single critical alert for an unverified combination, no numeric claims", () => {
+    const input: CableSizingInput = { ...BASE_INPUT, layingMethod: "G" };
+    const result = calculateCableSizing(input);
+    const alerts = buildCableSizingAlerts(input, result);
+    assert.equal(alerts.length, 1);
+    assert.equal(alerts[0].kind, "critical");
+    assert.ok(alerts[0].text.includes("keine geprüften"));
+  });
+
+  it("returns a single ok alert for a clean, unremarkable case", () => {
+    const input: CableSizingInput = {
+      ...BASE_INPUT,
+      mode: "current",
+      currentA: 15,
+      powerKw: undefined,
+      lengthM: 3,
+    };
+    const result = calculateCableSizing(input);
+    const alerts = buildCableSizingAlerts(input, result);
+    assert.equal(alerts.length, 1);
+    assert.equal(alerts[0].kind, "ok");
+  });
+});