The cable model, and why the last one was never switched on

[ispyisail]

Supersedes #951,
which was written before @arummler's architectural review on
PR #936
and which got four things wrong. Those corrections are §8.

Status: proposed, nothing built. Code checked against master ef1fbd79b.

---

1. The fact that should decide this

On 2020-09-24, Simon De Backer committed 3b9ba6a26 — "WIP: Add Kabel to
qet" — and, the same day, 36dbe6545, "Add TODO compile var". The cable data
layer landed complete: the field, its XML persistence, its settings defaults,
its copy semantics. The user interface was disabled behind a compile switch that
was never turned on.

Six years later, on master:

// sources/ui/conductorpropertieswidget.cpp:245-250
#if TODO_LIST
#pragma message("@TODO Add Kabel and Bus to qet")
#else
	ui->m_cable_le->setDisabled(true);
	ui->m_bus_le->setDisabled(true);
#endif

// sources/ui/potentialselectordialog.cpp:358-369
QRadioButton *rbk = new QRadioButton(tr("Ajouter au câble: %1")
				.arg("wouldn't this be nice?"), this);
QRadioButton *rbb = new QRadioButton(tr("Ajouter au bus: %1")
				.arg("wouldn't this be nice?"), this);
#if TODO_LIST
	…
#else
	rbk->setDisabled(true);
	rbb->setDisabled(true);
#endif

TODO_LIST is commented out in cmake/developer_options.cmake:32, so the
#else arm is live in every build ever shipped.

34 language files contain "Ajouter au câble". Translators in thirty-four
languages have translated a sentence whose visible value is the English string
wouldn't this be nice?, attached to a radio button nobody can click.

And the consequence, measured across the 25 shipped example projects: 3,190
conductors, zero cable values. Not because users do not want cables — because
for six years there has been nowhere to type one.

The question this scope has to answer is therefore not "what should a
cable model look like". It is "why was the last one never switched on, and
what stops that happening again".

---

2. What @arummler actually said, and what it costs

His review of #936 is the best architectural criticism this feature has had.
Summarised, with what each point does to the earlier scope:

#	His point	Effect
2	The catalogue writes straight into conductor properties, so logical and physical values fight for one field	Kills #951's "allocation writes colour/section/label onto the conductor"
5	Put a link object between the conductor and the catalogue — "conductor UUID points at core X of cable instance XYZ, not the spec"	Replaces #951's direct attributes
6	One hasShield flag cannot describe CAT7 S/FTP, triax, or foil-inside-braid — use a nested tree	Kills #951's flat <core index colour section> list
7	Fixed description fields are wrong — RoHS, EN 50200, radiation hardness. Common fields plus user-defined ones	Adds a requirement #951 did not have
8	Connectors and harnesses are out of scope, but leave hooks	Reserve the vocabulary, build nothing

He is right on all five. The disagreement in this document is not with the
model — it is with when to build it, and that disagreement is settled by §1.

---

3. The vocabulary, settled first

@arummler asked for this explicitly: "One just has to be careful with the
vocabulary … better to get it right before the confusion starts."

PhysicalWire is the wrong name, and the reason is checkable rather than
aesthetic. QET already uses wire / fil as a synonym for conductor /
conducteur:

• ConductorProperties::m_wire_color persists as the XML attribute
  conductor_color and is labelled "Couleur du fil" / "Wire color"
• "Numéro de conducteur" is translated "Number wire"
• --export-wires emits conductor numbers

So Conductor / PhysicalWire reads in French as conducteur / fil physique —
the same word twice. The distinction that works is not logical-versus-physical
but line versus core:

French (UI)	English (UI)	Code	Definition
Conducteur	Conductor	Conductor	the line drawn between two terminals. Exists today, unchanged
Brin	Core	CableCore	one continuous piece of copper installed end to end, belonging to exactly one cable
Câble	Cable	Cable	one cable installed between two places; an instance of a type; holds 1..n cores
Type de câble	Cable type	CableType	the catalogue record. @arummler's own word — adopt it verbatim
Écran	Shield	CableScreen	a screen over the cable or over a core group
Repère	End marking	endMarking	the ferrule text at each end of a core (his point 4)

Brin already ships with exactly this meaning: cable_3wires.elmt is French
"Cable 3 brins". core, Cable and CableType are unused as identifiers
today. Reserved and deliberately unspent: faisceau / harness, connecteur /
connector — that reservation is the hook his point 8 asks for.

A loose wire is a cable whose type has one core, exactly as #936's WireSpec
already does with isCable() { return numCores > 1; }.

---

4. The plan: a ceiling first, a model only on evidence

Each release ships on its own and is independently abandonable. Nothing before
release 3 changes the file format.

Release 1 — switch on what has been finished since 2020

No new state, no format change, and it is filmable in ninety seconds — which is
what @scorpio810 actually asked for on #936.

• Delete the setDisabled pair at conductorpropertieswidget.cpp:248-249 and
  the pair at potentialselectordialog.cpp:367-368; replace
  "wouldn't this be nice?" with the real value.
• Implement RealTerminal::cable() and cableWire()
  (TerminalStrip/realterminal.cpp:162-172) from the conductor's existing
  m_cable and wire number. Two terminal-strip columns, blank since they were
  written, become populated.
• Add m_cable / m_bus to Search & Replace
  (searchandreplaceworker.cpp:420-440) so the field is mass-editable.

Release 2 — the report, still no format change

• cable and bus columns on the project database's conductor table
  (projectdatabase.cpp:667-679), populated from the document. Free: the
  database is derived and rebuilt on every load.
• A cable schedule as a SQL-backed report — conductors grouped by cable,
  with from/to element, terminal, folio, colour and section — surfaced through
  --export-cable-schedule and the existing on-diagram table machinery.

This closes issue #405 and the seven forum requests for a cable list, and it is
a query rather than a forty-third scene-walker. Three people have written
external Python tools to get this report. It needs none of the architecture
below.

Then stop, and measure

The honest number today is 0 cable values across 3,190 conductors, and it is
uninformative because the field was unusable. Re-measure real projects six
months after release 1.

If people are not tagging cables when tagging is finally possible, the instance
model has no user. If they are, the next question arrives on its own — which
core? — and releases 3 and 4 answer it with evidence behind them instead of
ahead of them.

Release 3 — the smallest instance that is still correct

Only on that evidence.

• A project-level <cables> block, modelled on the existing <terminal_strips>
  block (qetproject.cpp:1144-1152), holding cable instances with a
  designation, an optional catalogue reference, a core list and a
  DiagramContext bag for @arummler's point 7.

• The allocation link as its own Conductor member, outside
  ConductorProperties, serialised as a child element:

  <conductor …>
    <cable_allocation core="{uuid}"/>
  </conductor>

  The pattern already ships: m_autoNum_seq is exactly this — a separate
  Q_PROPERTY, a separate XML child, copied only where an author deliberately
  wrote the copy (conductor.h:50, conductor.cpp:1099, :1178-1179).

• The core is addressed by a stable id, never an index. An index breaks the
  moment a core is inserted or reordered, and cannot address a nested structure
  at all. This corrects both Cable core allocation: the layer #934 deferred, and the one decision it needs #951 and Wire/cable catalogue (#529 restored): French UI, search and green/yellow fixes #936, which bakes W31:3 into a display
  string.

• Only the core id is stored. The cable is the core's parent and is therefore
  derivable; storing both invites them to disagree.

Release 4 — the nested tree

@arummler's point 6, as a pure addition. One recursive node type — a node's
children are exactly what it physically encloses — expressed as <bundle>,
<shield>, <core>, <fibre>. A shield is a node that both contains and is
terminable, its terminable body being its drain wire, which is why coax braid
and the shipped ecran_3p.elmt fall out of the model instead of needing an
exception.

Release 3 emits only depth-1 trees, which are a special case of the same
grammar, so CAT7 and triax arrive later with no format break.

---

5. Why this order, and not the model first

Because the model-first order is the one that has already failed three times.

Attempt	What shipped	What did not
De Backer, 2020	the whole cable data layer	the UI — disabled six years and counting
Joshua, 2015	a demo video	"le code n'a pas bougé depuis la vidéo"
achim, 2026 (cable_assist)	a drawing assistant	author: no cable editing, no list, no management
#936	the type catalogue	an instance for it to describe

There is a fourth failure mode available, and it is the mirror image: build a
large object model and never ship a drawing. Releases 1 and 2 are chosen
specifically because they cannot fail that way — they are visible on the day
they merge.

One concrete risk makes shipping format before consumers worse than merely
wasteful. QETProject::toXml() rebuilds the project file from a fixed list, so
if a format feature is merged and later reverted — and this repository has
several same-day reverts on record — the next save silently discards the
data users entered under it. Release 3 is the first release that carries that
risk, which is another reason it comes after evidence rather than before.

---

6. What #936 needs before it lands

It should land. It is the type catalogue, and every comparable tool has one as a
distinct layer. But it should land as something that cannot be built on,
which is precisely @arummler's condition:

"if it is merged now then I would propose with the understanding that no one
builds their workflow on top of it and that it can be completely changed /
broken in the future"

• Drop lang/qet_en.ts. @scorpio810 has now asked twice; translation work
  belongs on its own track.
• Trim "Affecter un fil" to appearance only. Keep "apply this type's colour
  and section to this conductor". Remove the core selector and the write of a
  W31:3 core reference into the label field — that is the exact mechanism
  release 3 replaces, and leaving it in is what invites a workflow to grow on
  it.
• De-vendor: sources/custom/wirecatalogue/ → sources/wirecatalogue/, and
  the twenty "Copyright 2026 Trovo Tech Solutions" headers normalised to QET's
  standard GPL header.
• Make the dock lazy. It opens and seeds a SQLite file in every user's
  application-data directory during the editor's constructor.

---

7. Decisions needed

1. Release 1 — any objection to switching on a field finished in 2020? This is
   the only decision needed to start.
2. Is the cable schedule of release 2 a CSV export, an on-diagram table, or both?
3. Vocabulary: brin / core, or something else? Settle before code, per
   @arummler.
4. Does the measurement gate before release 3 have agreement, or is the instance
   model wanted regardless?
5. Should bus follow cable throughout?

---

8. Corrections to discussion #951

Four, and they are load-bearing.

1. "H1 — the real blocker" named dead code. Cable core allocation: the layer #934 deferred, and the one decision it needs #951 said
   Conductor::setPropertyToPotential() smears m_cable across a potential and
   that the feature hinges on changing it. That function has zero callers —
   only a declaration (conductor.h:118) and a definition
   (conductor.cpp:1630). Implementing the fix as written would have been a
   no-op. The real copies of a whole ConductorProperties onto other conductors
   are elsewhere: elementsmover.cpp:236,239, diagramcommands.cpp:187,
   conductorautonumerotation.cpp:189,214,249, elementspanelwidget.cpp:796,
   conductorcreator.cpp:61, deleteqgraphicsitemcommand.cpp:230. Keeping the
   allocation out of ConductorProperties entirely — §4, release 3 — avoids all
   of them at once, which is what @arummler's point 5 buys.
2. The flat core list is wrong (his point 6) — replaced by the tree in
   release 4.
3. Writing colour and section onto the conductor is wrong (his point 2) —
   the link carries the reference; the values are read through it.
4. cable_uuid + cable_core index is wrong — one stable core id, the
   cable derived from it.

#951 §1–§3 and §6 stand, and its phases 0–1 are releases 1 and 2 here, which
remain the highest-value work in the whole programme.

---

9. Non-goals

• Connectors and harnesses. Vocabulary reserved, nothing built.
• Cable routing and physical length calculation.
• PLM or inventory integration as a bespoke importer. The headless
  --run script.js scripting API is the write path if one is wanted.
• Any change to how potentials work.
• Migration of existing free-text cable values. They stay and keep working.

[ispyisail]

This is my proposed build scope