Cable core allocation: the layer #934 deferred, and the one decision it needs

[ispyisail]

The specification for the layer discussion #934
deferred — a cable that owns its cores, and a way to allocate those cores to
individual conductors on the drawing.

Status: proposed, nothing built. Every code reference below was checked
against master ef1fbd79b; every element-collection fact against the shipped
collection; forum and issue evidence gathered 2026-09-20.

Read #934 first. It covers levels 1 and 2 — the
cable string made searchable and reportable — and its phases 1 and 2 remain
the right first work. This document is its level 3, and it exists because
level 3 was left as "needs a decision" without ever being specified.

---

1. The ask, and an honest correction

The request that prompted this: select a marker symbol, drop it on a wire, get
a dialog offering cable types from a database with a known core count, then keep
placing that marker on other wires until the cores are used up — with the spare
cores visible.

Nobody on the forum has asked for that. Eleven years of requests split three
ways, and none of them is this:

What is actually asked for	Where	Times
A cable drawn across several conductors at once (EPLAN style)	forum 2807, 2461, 1342, 3143, 2775	5
Per-core identification at both ends of a multi-core run	forum 804, 825, 1207, 2500	4
A cable list / schedule report	forum 2930, 2938, 2289, 2798, 1254, 1496; issue #405	7

Spare-core tracking appears in zero threads. Three separate people have
written external Python tools to get the report alone.

That is not an argument against the marker. The marker is
AutoCAD Electrical's cable marker,
shipping for twenty years: a parent marker carries the cable's identity and part
number, and each child marker inherits the tag and is offered the next unused
core. SEE Electrical ships the marker and the draw-across-wires gesture as
two entry points to the same data.

So the gesture is not the decision. Both gestures write the same rows. The
decision is whether a cable becomes an object. Build the object, ship the report
that has been asked for seven times, and the marker is one of two ways to fill
it in.

---

2. What already exists — more than anyone assumed

The symbol is already shipped

10_allpole/120_cables_wiring/filerie.elmt — "Filerie", "Wiring",
"Verdrahtung", named in 11 languages:

<line x1="5" y1="-5" x2="-5" y2="5"/>      <!-- the slash -->
<line x1="0" y1="-5" x2="0" y2="5"/>       <!-- the wire through it -->
<dynamic_text text_from="ElementInfo"><info_name>label</info_name></dynamic_text>
<terminal x="0" y="-5" orientation="n"/>
<terminal x="0" y="5" orientation="s"/>

That folder holds 57 cable elements: cable…cable6, kabel3g/4g/7g/8g,
ecran_3p, m_cable_designation, fil_de_cable, and a whole
m_cable_02p…10p_mux/demux family with numbered cores.

Across all 57, the only machine-readable fields are label (16), designation
(1) and description (1). No core count, no cable type, no core index. The
drawing vocabulary is rich and complete; nothing behind it can be queried,
counted or reported. That is the entire gap in one sentence.

The UI slot was built and never filled

The terminal strip editor has CABLE_CELL = 9 and CABLE_WIRE_CELL = 10,
headed "Câble" and "Couleur / numéro de fil câble"
(TerminalStrip/ui/terminalstripmodel.cpp:44-45, 292-293), fed by
RealTerminal::cable() and cableWire() — both stubs returning
QString() (TerminalStrip/realterminal.cpp:162-172). Someone designed the
display and the data never arrived.

The field exists and cannot even be typed into

ConductorProperties::m_cable and m_bus are plain QString
(conductorproperties.h:97-98), persisted as attributes on <conductor>
(conductorproperties.cpp:286, read :345). Their QLineEdits are disabled:

#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

TODO_LIST is commented out in cmake/developer_options.cmake:32, so the
disabling arm is live in every normal build. The one field a cable feature
would build on cannot be typed into today.

sources/dataBase/ contains zero occurrences of "cable".

The catalogue exists as an open PR

#936
(restoring @Gokulakannan750's #529) gives WireSpec — numCores, per-core
colours, per-core sections, shield — backed by a working SQLite store with CRUD,
search, CSV and tests, plus a per-core selector UI with IEC 60757 swatches.

Two limits decide how it is used here:

• It models a cable type, never an instance. Its key is wireId, so
  three separate 4-core W63 runs in one project are one row.
• assignSelectedWire() bakes the chosen core into a display string
  ("W31:3 0.5mm² Brown") in the label field; only wireId reaches
  m_cable. The core index is not stored machine-readably anywhere.

---

3. Why the last two attempts died

Both stopped at the same place, and it was not the drawing.

Attempt	What shipped	Where it stopped
Joshua's prototype, 2015 (forum 706, Cable.webm)	a demo video	"le code n'a pas bougé depuis la vidéo"
achim's cable_assist, 2026 (forum 3144)	a drawing assistant	the author: each conductor gets its own symbol, no cable editing, no cable list, no management
#936, open	the type catalogue	assignment copies values onto one conductor; the core index is lost

Every one built the drawing. None built the object. That is why the
current state reads as underwhelming: it is a catalogue nothing consumes, on top
of 57 symbols nothing can query.

Joshua's own condition for doing this properly — stated in forum 1382, that
cable management needs terminal blocks and element terminals first — is now
satisfied. Both exist.

---

4. The model

Three layers. Every professional tool has all three; QET has one and a half.

Layer	Example elsewhere	QET today
Cable type library	ACE _W0_CBLWIRES, SOLIDWORKS Cable References Manager, EPLAN part templates	#936, open
Cable instance in the project	EPLAN cable definition DT, ACE parent marker	missing
Core → conductor allocation	ACE child markers, SOLIDWORKS "Associate cable cores"	missing

The one rule that makes the model work

Store the core count on the instance. Derive the allocation from the
conductors.

This resolves the contradiction #934 identified. A cable's core count cannot
be derived — a 7-core cable with 4 used has 3 cores no conductor hangs on. But
once the instance carries the count, "which cores are spare" is simply
count − (conductors referencing this cable), computed by one SQL query. No
back-reference list, no orphan bookkeeping.

Persisted shape — additive only

Two optional attributes beside the existing cable on <conductor>:

<conductor ... cable="W2" cable_uuid="{…}" cable_core="3"/>

One new project-level block, the same shape as the existing <terminal_strips>
and <newdiagrams> blocks that the maintainer already accepts:

<cables>
  <cable uuid="{…}" designation="W2" type_ref="W63" cores="7">
    <core index="1" colour="Brown"      section="0.5"/>
    <core index="2" colour="Blue"       section="0.5"/>
    <core index="3" colour="Black"      section="0.5" state="reserved"/>
    …
  </cable>
</cables>

The instance snapshots its cores from the catalogue at creation. It does not
chase the catalogue afterwards. This is what EPLAN does (fixed function
templates) and what ACE does (copying the conductor list onto the marker), and
it is non-negotiable here for a specific reason: #936's catalogue lives at
<AppDataLocation>/wirecatalogue.sqlite — per-user and global, not in the
.qet. Without snapshotting, a project opened on another machine loses every
core count, colour and spare report.

ConductorProperties::fromXml reads by e.attribute(...), and unknown child
elements are ignored on load, so an older QET opening the file keeps working and
still shows the human-readable cable string. Nothing existing changes meaning.

Database

Per the repository's own data-direction rules — never add persisted state the
database does not know about, populate it from the document rather than from
constructed scenes, and do not add another scene-walker — two new tables, cable and cable_core,
populated from the document, not from constructed scenes; cable and
cable_core columns added to the existing conductor table. The database is
derived and rebuilt every load, so this costs no migration and no versioning.
Every report is then a query, and no thirty-eighth scene-walker is added.

---

5. The three hazards, and what to do about them

These decide whether the feature is buildable. A design that ducks them is
worthless.

H1 — core identity fights the potential model (the real blocker)

Conductor::setPropertyToPotential() (conductor.cpp:1630) has two branches,
and they differ in exactly the way that matters:

if (only_text) {                       // copies a NAMED SUBSET
    other_properties.m_formula           = m_properties.m_formula;
    other_properties.text                = m_properties.text;
    other_properties.m_function          = m_properties.m_function;
    other_properties.m_tension_protocol  = m_properties.m_tension_protocol;
    other_properties.m_wire_color        = m_properties.m_wire_color;
    other_properties.m_wire_section      = m_properties.m_wire_section;
    other_conductor->setProperties(other_properties);
} else {
    other_conductor->setProperties(property);   // copies EVERYTHING, m_cable included
}

Conductor labels are potential-scoped by design and per-segment labelling has
been rejected before. A core allocation is inherently per-segment: core 3 runs
from A to B, and the conductor on the far side of a terminal is a different core
or no core at all. The else branch therefore smears one core's identity across
a whole potential.

Resolution, and it is smaller than it looks. The if branch is already a
selective copy of a named subset — the precedent exists six lines above the
problem. Cable identity (m_cable, cable_uuid, cable_core) is excluded from
the else branch the same way. #936 already depends on this rule: its
assignment path unticks "apply to all" precisely because different conductors of
one potential carry different cores.

This is the decision to settle before any code. It is a genuine, if narrow,
departure from "properties belong to the potential", and the maintainer has
declined that direction before in a different context. If the answer is no, the
feature cannot be built as specified and the honest response is to stop at
#934's phases 1 and 2.

H2 — an element marker cuts the wire

autoBreakConductors() runs on every element placement when the project setting
is on. filerie.elmt has two terminals, so dropping it does split the
conductor in two — and then neither half is obviously "the" conductor carrying
core 3.

Resolution. The marker is not an element. It is a graphics item anchored
to the conductor, following the one existing precedent for exactly that:
ConductorTextItem is a QGraphicsItem child of the Conductor
(conductor.cpp:128), positioned by posForText() / middleSegment() /
calculateTextItemPosition() (:1348, :1324, :1411), with
moved_by_user_ / rotate_by_user_ flags so it survives path changes.

filerie.elmt keeps its existing job as a hand-drawn annotation. The allocation
marker is a new, lighter thing that never splits a wire.

H3 — lifecycle

Delete a conductor, split one, merge a potential, copy a folio.

Resolution follows from the one rule. Because the conductor points at the
cable and never the reverse, deleting a conductor frees its core with no
bookkeeping — the next SELECT simply returns one fewer allocation. Copying a
folio duplicates the attributes, which is the one case needing explicit
handling: a pasted conductor must either keep the allocation (same cable
continues onto the new folio) or drop it. Recommend: drop it, matching
paste's existing treatment of PLC slave data, and surface it in the report.

---

6. Over- and under-allocation: report, never block

EPLAN validates both directions as check-run messages — P003011 "too many
cable connections" and P003028 "cable does not use all the cable connections
of the part". It does not refuse the edit.

Do the same. Offer only unused cores in the picker so over-allocation is hard to
reach by accident, but if a user exceeds the count, allow it and flag it. A
cautious maintainer will accept a new report far more readily than a new way for
the application to refuse an edit, and a design-rule-check report is the natural
home for them.

---

7. Phases

Each ships something visible. Phase 1 needs no new persisted state at all.

Phase 0 — unblock the field. The cable and bus line edits sit in the
#else arm of a #if TODO_LIST block (ui/conductorpropertieswidget.cpp:245-250),
and TODO_LIST is commented out in cmake/developer_options.cmake:32 — so the
disabling arm is live in every normal build and the fields have never been
usable. Removing the guard makes #934's phase 1 meaningful,
because there is otherwise no way to put a value in the field it proposes to
search, export and report on.

Phase 1 — the report everyone actually asked for. #934's phases 1 and 2,
unchanged: search & replace, database columns, a cable column
on --export-cables, select-all-by-cable, and the cable schedule as CSV and as
an on-diagram table. Closes seven citable requests, and fills the terminal
strip's two blank columns. No format change.

Phase 2 — the cable instance. The <cables> block, the cable and
cable_core tables, and a cable manager dialog to create instances from a
catalogue type. Spare cores become real and reportable. Additive format change.

Phase 3 — allocation. cable_uuid / cable_core on <conductor>, the
H1 propagation exclusion, and the conductor-anchored marker with its
next-unused-core picker. This is the requested feature, and it is last because
everything above it has to exist first.

Phase 4 — the second gesture. The draw-a-line-across-wires entry point,
which the forum has asked for five times. It inserts N allocations; the data
model is untouched.

First PR

Phase 0 plus the Search & Replace half of phase 1: add m_cable/m_bus to
applyChange() and replaceAdvanced() in
SearchAndReplace/searchandreplaceworker.cpp:420-440, two fields in the
Search & Replace UI, and delete the setDisabled pair. Small, self-contained,
no format change, and it turns a write-only field into a maintainable one.

---

8. Decisions needed

1. H1: may cable identity be excluded from potential propagation? Everything
   downstream of phase 2 depends on this.
2. Is a cable an object at all, or is the tag-plus-reporting ceiling of phases
   0–1 the right answer for QET?
3. Project-level cable list, or folio-level? (Project assumed.)
4. Does the instance snapshot its cores, or reference the catalogue live?
   (Snapshot assumed, for the per-user-database reason in §4.)
5. Is Wire/cable catalogue (#529 restored): French UI, search and green/yellow fixes #936 landed as the type library first, or folded into this?
6. Does bus follow cable throughout?

---

9. Non-goals

• No cable routing or length calculation. Discussion Feature idea: structured conductor data (DB table + folio cross-reference links) to support FreeCAD/3D wire-length tools #601 wants lengths from
  a 3D tool; different feature.
• No automatic cable assignment. A conductor joins a cable because someone said so.
• No change to how potentials work, beyond the narrow exclusion in H1.
• No migration of existing free-text cable values. They stay, and a project
  that never creates an instance behaves exactly as today.

---

10. On abandoning the current work

#897 is not cable work. It is the IEC 81346 designation-letter PR — open,
mergeable, with live review. Abandoning it buys this nothing.

#936 should not be abandoned either. It is the type library, which every
tool surveyed has as a distinct layer, and it is sound. Its problem is that it
was presented as the feature when it is the foundation. Land it as the
catalogue, fix the per-user scoping by snapshotting at instance creation, and
build the instance and allocation on top.

Restarting would discard a working catalogue, colour picker and IEC 60757
implementation to rebuild the one layer that already exists.

[ispyisail]

Correction: §5's "real blocker" names dead code.

This document says the feature hinges on Conductor::setPropertyToPotential() smearing m_cable across a potential. That function has no callers — a declaration at conductor.h:118 and a definition at conductor.cpp:1630, and nothing else in sources/ or tests/. Implementing the fix as written would have been a no-op, and §8 decision 1 asked @scorpio810 to rule on a non-problem. My apologies.

The whole-ConductorProperties copies that do happen are elsewhere: elementsmover.cpp:236,239 (one of which writes the application default onto a conductor), diagramcommands.cpp:187, conductorautonumerotation.cpp:189,214,249, elementspanelwidget.cpp:796, conductorcreator.cpp:61, deleteqgraphicsitemcommand.cpp:230.

Three further corrections, all from @arummler's review on #936, and he is right on each:

1. §4's flat core list cannot express real cables. One hasShield flag does not describe CAT7 S/FTP — four individually foil-shielded pairs inside an overall braid — or triax, or foil-inside-braid. That needs a nested tree.
2. Writing colour and section onto the conductor is wrong. The catalogue and the drawing then fight for one field. The link should carry a reference; the values are read through it.
3. cable_core as an integer index is wrong. An index breaks the moment a core is inserted or reordered, and cannot address a nested structure. It needs a stable id.

Keeping the allocation out of ConductorProperties entirely — which is what @arummler's point 5 buys — avoids all seven copy sites at once, rather than patching one function.

§1–§3 and §6 stand, and phases 0–1 are unaffected: switching on a field that has been disabled since 2020 and reporting over it remains the highest-value work here.

Superseded by #956, which rebuilds the plan around a fact I had not found when writing this: the cable data layer was committed complete on 2020-09-24 and its UI disabled the same day, and 34 language files have since translated a string whose visible value is wouldn't this be nice?.