python-materialsdb 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

materialsdb/__init__.py

@@ -1 +1,3 @@
-from materialsdb import ifc, cache, config, classes, serialiser
+from materialsdb import cache, classes, config, ifc, serialiser
+
+__all__ = ["cache", "classes", "config", "ifc", "serialiser"]

materialsdb/cache.py

@@ -2,7 +2,7 @@ import os
 import pathlib
 import urllib.request
 from collections import namedtuple
-from typing import Optional
+
 from lxml import etree
 
 MATERIALSDBINDEXURLLIST = [
@@ -13,9 +13,7 @@ MATERIALSDBINDEXURLLIST = [
 
 def get_cache_folder():
     cache_dir = pathlib.Path(
-        os.environ.get("APPDATA")
-        or os.environ.get("XDG_CACHE_HOME")
-        or pathlib.Path.home() / ".cache"
+        os.environ.get("APPDATA") or os.environ.get("XDG_CACHE_HOME") or pathlib.Path.home() / ".cache"
     ).joinpath(
         "materialsdb",
     )
@@ -35,7 +33,7 @@ def parse_cached_index(index) -> etree._ElementTree:
     return etree.ElementTree(root)
 
 
-def get_by_id(root: etree._Element, id: str) -> Optional[etree._Element]:
+def get_by_id(root: etree._Element, id: str) -> etree._Element | None:
     for company in root:
         if company.get("id") == id:
             return company
@@ -60,47 +58,75 @@ def get_producers_dir() -> pathlib.Path:
 Report = namedtuple("Report", ["existing", "updated", "deleted"])
 
 
-def update_producers_data(url_list=MATERIALSDBINDEXURLLIST):
-    existing = []
-    updated = []
-    deleted = []
-    for index in url_list:
-        report = update_producers_from_index(index)
-        existing.extend(report.existing)
-        updated.extend(report.updated)
-        deleted.extend(report.deleted)
-    return Report(existing, updated, deleted)
+class _IndexPlan:
+    def __init__(self, index, new_index, unchanged, todos):
+        self.index = index
+        self.new_index = new_index
+        self.unchanged = unchanged
+        self.todos = todos  # list[(company, cached_producer|None, producer_path)]
 
 
-def update_producers_from_index(index):
+def _plan_index(index):
     cached_index = parse_cached_index(index)
     cached_root = cached_index.getroot()
     with urllib.request.urlopen(index) as response:
         new_index = etree.parse(response)
     new_root = new_index.getroot()
     producers_dir = get_producers_dir()
-    has_index_update = False
-    existing = []
-    updated = []
-    deleted = []
+    unchanged = []
+    todos = []
     for company in new_root:
         cached_producer = get_by_id(cached_root, company.get("id"))
         producer_path = producers_dir / pathlib.Path(company.get("href")).name
         if not require_update(cached_producer, company) and producer_path.exists():
-            existing.append(producer_path)
+            unchanged.append(producer_path)
             continue
-        if cached_producer:
-            cached_path = producers_dir / pathlib.Path(cached_producer.get("href")).name
-            deleted.append(cached_path)
-            cached_path.unlink(True)
-        has_index_update = True
-        urllib.request.urlretrieve(company.get("href"), producer_path)
-        updated.append(producer_path)
-    if has_index_update:
-        new_index.write(str(get_cached_index_path(index)))
+        todos.append((company, cached_producer, producer_path))
+    return _IndexPlan(index, new_index, unchanged, todos)
+
+
+def update_producers_data(url_list=MATERIALSDBINDEXURLLIST, on_progress=None):
+    """on_progress(done, total, name) is called after each producer download
+    with a global running total; returning a truthy value stops the update
+    between two downloads (the partial Report is returned as-is)."""
+    plans = [_plan_index(index) for index in url_list]
+    total = sum(len(plan.todos) for plan in plans)
+    existing, updated, deleted = [], [], []
+    done = 0
+    for plan in plans:
+        for company, cached_producer, producer_path in plan.todos:
+            if cached_producer is not None:
+                cached_path = get_producers_dir() / pathlib.Path(cached_producer.get("href")).name
+                deleted.append(cached_path)
+                cached_path.unlink(True)
+            urllib.request.urlretrieve(company.get("href"), producer_path)
+            updated.append(producer_path)
+            done += 1
+            if on_progress is not None and on_progress(done, total, pathlib.Path(company.get("href")).name):
+                return Report(existing, updated, deleted)
+        if plan.todos:
+            plan.new_index.write(str(get_cached_index_path(plan.index)))
+        existing.extend(plan.unchanged)
     return Report(existing, updated, deleted)
 
 
+def update_producers_from_index(index):
+    """Legacy single-index entry point (no progress callback)."""
+    return update_producers_data([index])
+
+
+def updates_available(url_list=MATERIALSDBINDEXURLLIST) -> bool:
+    """True when any remote company differs from the cached index."""
+    for index in url_list:
+        cached_root = parse_cached_index(index).getroot()
+        with urllib.request.urlopen(index) as response:
+            new_root = etree.parse(response).getroot()
+        for company in new_root:
+            if require_update(get_by_id(cached_root, company.get("id")), company):
+                return True
+    return False
+
+
 def producers():
     for producer in get_producers_dir().iterdir():
         if producer.suffix.lower() == ".xml":

materialsdb/classes.py

@@ -14,6 +14,12 @@ from dataclasses import dataclass
 from typing import Tuple, Optional, List
 
 
+class TDesignUsage(str):
+    xs_type: str = "simpleType"
+    xml_enum: Tuple[str, ...] = ('consDesignForWall', 'consDesignForRoof', 'consDesignForFloor')
+    xml_name: str = "TDesignUsage"
+
+
 class TLCADB(str):
     xs_type: str = "simpleType"
     xml_enum: Tuple[str, ...] = ('dbKBOB', 'dbOkobauDat', 'dbLux')
@@ -58,7 +64,7 @@ class T2Lowercase(str):
 
 class Groupkind(str):
     xs_type: str = "simpleType"
-    xml_enum: Tuple[str, ...] = ('Others', 'Water_Proof', 'Vapour_Proof', 'Concrete', 'Wood_Timberproducts', 'Insulation', 'Masonry', 'Metal', 'Mortar', 'Plastics', 'Stone', 'Composite', 'Films', 'Render', 'Covering', 'Glas', 'Soil', 'air')
+    xml_enum: Tuple[str, ...] = ('Others', 'Water_Proof', 'Vapour_Proof', 'Concrete', 'Wood_Timberproducts', 'Insulation', 'Masonry', 'Metal', 'Mortar', 'Plastics', 'Stone', 'Composite', 'Films', 'Render', 'Covering', 'Glas', 'Soil', 'Air')
     xml_name: str = "groupkind"
 
 
@@ -408,9 +414,10 @@ class Lcia:
 @dataclass
 class Lcaversion:
     id: str
-    code: Brackguid
     xs_type: str = "element"
-    xml_attributes: Tuple[str, ...] = ('id', 'code')
+    code: Optional[Brackguid] = None
+    disabled: Optional[Boolean] = None
+    xml_attributes: Tuple[str, ...] = ('id', 'code', 'disabled')
     xml_name = "lcaversion"
     xml_elements: Tuple[str, ...] = ()
 
@@ -555,11 +562,11 @@ class Vlca:
 @dataclass
 class Variation:
     id: Guid
-    vgeometry: List[Vgeometry]
-    vthermal: List[Vthermal]
     xs_type: str = "element"
     displayorder: Optional[int] = None
     xml_attributes: Tuple[str, ...] = ('id', 'displayorder')
+    vgeometry: Optional[List[Vgeometry]] = None
+    vthermal: Optional[List[Vthermal]] = None
     vacoustic: Optional[List[Vacoustic]] = None
     vother: Optional[List[Vother]] = None
     vlcia: Optional[List[Vlcia]] = None
@@ -582,7 +589,8 @@ class Construction:
     xs_type: str = "element"
     source: Optional[str] = None
     consref: Optional[str] = None
-    xml_attributes: Tuple[str, ...] = ('source', 'consref')
+    designusage: Optional[TDesignUsage] = None
+    xml_attributes: Tuple[str, ...] = ('source', 'consref', 'designusage')
     xml_name = "construction"
     xml_elements: Tuple[str, ...] = ()
 

materialsdb/config.py

@@ -1,14 +1,11 @@
+import json
 import os
 import pathlib
-import json
-from typing import Dict
 
 
 def get_config_dir():
     config_dir = pathlib.Path(
-        os.environ.get("APPDATA")
-        or os.environ.get("XDG_CACHE_HOME")
-        or pathlib.Path.home() / ".config"
+        os.environ.get("APPDATA") or os.environ.get("XDG_CACHE_HOME") or pathlib.Path.home() / ".config"
     ).joinpath(
         "materialsdb",
     )
@@ -20,7 +17,7 @@ def get_base_config_path() -> pathlib.Path:
     return get_config_dir() / "config.json"
 
 
-def get_base_config() -> Dict[str, str]:
+def get_base_config() -> dict[str, str]:
     base_config_path = get_base_config_path()
     if base_config_path.exists():
         return json.loads(get_base_config_path().read_text("utf-8"))

materialsdb/construction.py

@@ -0,0 +1,464 @@
+"""Thermal construction composition: stack model, U-value math, IFC emission."""
+
+import json
+import math
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from materialsdb import cache, config, utils
+
+
+def finite_or_none(value) -> float | None:
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if math.isfinite(number) else None
+
+
+# Surface resistances (m2K/W): interior/exterior by heat-flow direction.
+# ISO 6946 table values; SIA 180 references the same table for these boundary
+# cases (verified against secondary literature 2026-08). Kept as separate
+# entries so standard-specific corrections have an explicit home.
+RESISTANCE_PRESETS = {
+    "ISO6946": {
+        "wall": (0.13, 0.04),
+        "roof": (0.10, 0.04),
+        "floor": (0.17, 0.04),
+        "generic": (0.13, 0.04),
+    },
+    "SIA180": {
+        "wall": (0.13, 0.04),
+        "roof": (0.10, 0.04),
+        "floor": (0.17, 0.04),
+        "generic": (0.13, 0.04),
+    },
+}
+
+_DESIGN_USAGE_TO_DIRECTION = {
+    "consDesignForWall": "wall",
+    "consDesignForRoof": "roof",
+    "consDesignForFloor": "floor",
+}
+
+
+@dataclass
+class ConstructionLayer:
+    material_id: str | None
+    thickness_m: float
+    # {"name": str, "lambda_value": float | None} for model materials without
+    # a materialsdb identity (round-tripped from Bonsai, re-attached by name)
+    placeholder: dict | None = None
+
+
+@dataclass
+class Construction:
+    name: str
+    design_usage: str | None
+    layers: list[ConstructionLayer] = field(default_factory=list)
+
+
+@dataclass
+class UResult:
+    u: float | None
+    rsi: float
+    rse: float
+    contributions: list[dict]
+    missing_lambda_ids: list[str | None]
+
+
+def resolve_lambda(store_, material_id: str | None, country: str | None = None) -> float | None:
+    """First country-resolved lambda_value across the material's layers."""
+    material = store_.get(material_id)
+    if material is None:
+        return None
+    country = country or config.get_country()
+    for layer in getattr(getattr(material, "layers", None), "layer", ()) or ():
+        thermal = utils.get_by_country(layer.thermal or (), country)
+        if thermal is not None and thermal.lambda_value is not None:
+            return thermal.lambda_value
+    return None
+
+
+def _direction(design_usage: str | None) -> str:
+    return _DESIGN_USAGE_TO_DIRECTION.get(design_usage or "", "generic")
+
+
+def u_value(construction: Construction, store_, preset: str = "ISO6946") -> UResult:
+    if preset not in RESISTANCE_PRESETS:
+        raise ValueError(f"unknown preset: {preset} (available: {sorted(RESISTANCE_PRESETS)})")
+    return _u_for_direction(construction, store_, _direction(construction.design_usage), preset)
+
+
+def _u_for_direction(construction: Construction, store_, direction: str, preset: str = "ISO6946") -> UResult:
+    if direction not in RESISTANCE_PRESETS[preset]:
+        raise ValueError(f"unknown direction: {direction}")
+    rsi, rse = RESISTANCE_PRESETS[preset][direction]
+    country = config.get_country()
+
+    contributions = []
+    missing = []
+    r_sum = 0.0
+    for index, layer in enumerate(construction.layers):
+        if layer.placeholder is not None:
+            name = layer.placeholder.get("name") or ""
+            lambda_value = finite_or_none(layer.placeholder.get("lambda_value"))
+        else:
+            summary = store_.get_summary(layer.material_id)
+            if summary is not None:
+                name = summary.names.get(config.get_lang()) or summary.names.get("") or ""
+            lambda_value = resolve_lambda(store_, layer.material_id, country)
+        if lambda_value is None or lambda_value <= 0 or not layer.thickness_m or layer.thickness_m <= 0:
+            missing.append(layer.material_id)
+            continue
+        r_layer = layer.thickness_m / lambda_value
+        r_sum += r_layer
+        contributions.append(
+            {
+                "material_id": layer.material_id,
+                "name": name,
+                "d_m": layer.thickness_m,
+                "lambda_value": lambda_value,
+                "r": r_layer,
+                "layer_index": index,
+            }
+        )
+
+    if missing or not contributions or math.isclose(r_sum, 0):
+        return UResult(u=None, rsi=rsi, rse=rse, contributions=contributions, missing_lambda_ids=missing)
+
+    u = 1 / (rsi + r_sum + rse)
+    return UResult(u=u, rsi=rsi, rse=rse, contributions=contributions, missing_lambda_ids=missing)
+
+
+_TYPE_TO_DIRECTION = {
+    "IfcWallType": "wall",
+    "IfcSlabType": "floor",
+    "IfcRoofType": "roof",
+}
+
+
+def u_values_by_type(construction: Construction, store_, types, preset: str = "ISO6946") -> dict[str, float | None]:
+    """U per element class, each with its own heat-flow direction
+    (wall / floor / roof Rsi-Rse). Unresolvable λ → None for that type."""
+    if preset not in RESISTANCE_PRESETS:
+        raise ValueError(f"unknown preset: {preset} (available: {sorted(RESISTANCE_PRESETS)})")
+    for cls in types:
+        if cls not in _TYPE_TO_DIRECTION:
+            raise ValueError(f"unknown element type: {cls}")
+    return {cls: _u_for_direction(construction, store_, _TYPE_TO_DIRECTION[cls], preset).u for cls in types}
+
+
+def _has_identity_pset(file, material) -> bool:
+    from materialsdb.ifc.material_builder import MATERIALSDB_PSET, _materials_of
+
+    for pset in file.by_type("IfcMaterialProperties"):
+        if pset.Name != MATERIALSDB_PSET:
+            continue
+        if any(m.id() == material.id() for m in _materials_of(pset)):
+            return True
+    return False
+
+
+def _purge_prior_layer_sets(file, name: str) -> None:
+    """Remove prior IfcMaterialLayerSets called `name` before a re-append.
+
+    Layers whose material carries a materialsdb identity pset are ours: their
+    materials are purged outright. Foreign materials (no identity pset) are
+    kept and merely detached from their layer references; emptied set shells
+    are dropped so the replacement set stays unique."""
+    from materialsdb.ifc.material_builder import purge_material
+
+    stale = []
+    for old_set in [s for s in file.by_type("IfcMaterialLayerSet") if s.LayerSetName == name]:
+        for layer in list(old_set.MaterialLayers or ()):
+            material = getattr(layer, "Material", None)
+            if material is not None and _has_identity_pset(file, material):
+                stale.append(material.id())
+    for guid in dict.fromkeys(stale):
+        purge_material(file, guid)
+    # re-fetch: purge may already have removed some or all of the old sets
+    for leftover in [s for s in file.by_type("IfcMaterialLayerSet") if s.LayerSetName == name]:
+        for layer in list(leftover.MaterialLayers or ()):
+            file.remove(layer)
+        if not leftover.MaterialLayers:
+            file.remove(leftover)
+
+
+def to_ifc_layer_set(construction: Construction, store_, file=None):
+    """Emit a wrapper IFC library containing the construction as an
+    IfcMaterialLayerSet. Referenced materials are built through
+    MaterialBuilder (single representative variant) so their identity psets
+    ride along; IfcMaterialLayer.Description carries the source material guid.
+
+    Appending into an existing session file replaces any prior layer set with
+    the same name (materials matched by their materialsdb identity)."""
+    if any(layer.placeholder is not None for layer in construction.layers):
+        raise ValueError("cannot export placeholder layers; assign materialsdb materials first")
+    import uuid
+
+    from materialsdb.ifc.material_builder import MaterialBuilder
+    from materialsdb.ifc.project_library import ProjectLibrary
+
+    missing = [layer.material_id for layer in construction.layers if store_.get(layer.material_id) is None]
+    if missing:
+        raise ValueError(f"unknown material ids: {', '.join(str(m) for m in missing)}")
+
+    if file is None:
+        library = ProjectLibrary()
+        library.create_project_library(
+            company="MaterialsDB Constructions",
+            companyid=str(uuid.uuid4()),
+            ver=1,
+            crd=utils.new_tdatetime(),
+        )
+        target_file = library.file
+    else:
+        library = None
+        target_file = file
+        # purge before building: a later find_existing must not re-attach to
+        # materials that are about to be removed with the superseded set
+        _purge_prior_layer_sets(target_file, construction.name)
+
+    builder = MaterialBuilder(target_file)
+    material_layers = []
+    for layer in construction.layers:
+        summary = store_.get_summary(layer.material_id)
+        material = store_.get(layer.material_id)
+        created = builder.build(
+            material,
+            company_id=str(summary.company_id),
+            company=summary.company,
+            with_layers=False,
+        )
+        assert len(created) == 1, "with_layers=False must yield exactly one IfcMaterial"
+        name = summary.names.get(config.get_lang()) or ""
+        element_name = f"{name} | {round(layer.thickness_m * 1000)} mm"
+        ifc_layer = target_file.create_entity(
+            "IfcMaterialLayer",
+            Material=created[0],
+            LayerThickness=layer.thickness_m,
+            Description=layer.material_id,
+            Name=element_name,
+        )
+        material_layers.append(ifc_layer)
+
+    target_file.create_entity(
+        "IfcMaterialLayerSet",
+        MaterialLayers=material_layers,
+        LayerSetName=construction.name,
+    )
+    return target_file if library is None else library.file
+
+
+def constructions_dir() -> Path:
+    directory = cache.get_cache_folder() / "constructions"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def slugify(name: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+    return slug or "construction"
+
+
+def _unique_path(directory: Path, base: str) -> Path:
+    candidate = directory / f"{base}.json"
+    index = 2
+    while candidate.exists():
+        candidate = directory / f"{base}-{index}.json"
+        index += 1
+    return candidate
+
+
+def _find_stored_name_file(directory: Path, name: str) -> Path | None:
+    for file in directory.glob("*.json"):
+        data = json.loads(file.read_text(encoding="utf-8"))
+        if data.get("name") == name:
+            return file
+    return None
+
+
+def validate_construction(body: dict, store_) -> tuple[Construction, list[str]]:
+    problems: list[str] = []
+    name = str(body.get("name") or "").strip()
+    if not name:
+        problems.append("name required")
+    layers_body = body.get("layers")
+    if not isinstance(layers_body, list) or not layers_body:
+        problems.append("at least one layer required")
+        layers_body = []
+    layers = []
+    for index, entry in enumerate(layers_body):
+        if not isinstance(entry, dict):
+            problems.append(f"layer {index}: invalid entry")
+            continue
+        try:
+            thickness = float(entry.get("thickness_m"))
+        except (TypeError, ValueError):
+            problems.append(f"layer {index}: thickness must be a number")
+            continue
+        if not math.isfinite(thickness) or thickness <= 0:
+            problems.append(f"layer {index}: thickness must be > 0")
+            continue
+        material_id = entry.get("material_id")
+        placeholder = entry.get("placeholder") if isinstance(entry.get("placeholder"), dict) else None
+        if material_id:
+            if store_.get(str(material_id)) is None:
+                problems.append(f"unknown material id: {material_id}")
+                continue
+            layers.append(ConstructionLayer(material_id=str(material_id), thickness_m=thickness))
+        elif placeholder is not None:
+            layers.append(
+                ConstructionLayer(
+                    material_id=None,
+                    thickness_m=thickness,
+                    placeholder={
+                        "name": str(placeholder.get("name") or ""),
+                        "lambda_value": finite_or_none(placeholder.get("lambda_value")),
+                    },
+                )
+            )
+        else:
+            problems.append(f"layer {index}: material_id or placeholder required")
+    design_usage = body.get("design_usage") or None
+    if design_usage not in (None, *_DESIGN_USAGE_TO_DIRECTION):
+        problems.append(f"invalid design_usage: {design_usage}")
+    return Construction(name=name, design_usage=design_usage, layers=layers), problems
+
+
+def _to_body(construction: Construction) -> dict:
+    return {
+        "name": construction.name,
+        "design_usage": construction.design_usage,
+        "layers": [
+            {
+                "material_id": layer.material_id,
+                "thickness_m": layer.thickness_m,
+                **({"placeholder": layer.placeholder} if layer.placeholder else {}),
+            }
+            for layer in construction.layers
+        ],
+    }
+
+
+def save_construction(construction: Construction, store_) -> Path:
+    _, problems = validate_construction(_to_body(construction), store_)
+    if problems:
+        raise ValueError("; ".join(problems))
+    directory = constructions_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    existing = _find_stored_name_file(directory, construction.name)
+    path = existing if existing is not None else _unique_path(directory, slugify(construction.name))
+    payload = {
+        "name": construction.name,
+        "design_usage": construction.design_usage,
+        "layers": [
+            {
+                "material_id": layer.material_id,
+                "thickness_m": layer.thickness_m,
+                **({"placeholder": layer.placeholder} if layer.placeholder else {}),
+            }
+            for layer in construction.layers
+        ],
+        "created": time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    path.write_text(json.dumps(payload, indent=1), encoding="utf-8")
+    return path
+
+
+def load_construction(name_or_slug: str, store_) -> Construction | None:
+    directory = constructions_dir()
+    candidates = [directory / f"{slugify(name_or_slug)}.json"]
+    for file in directory.glob("*.json"):
+        data = json.loads(file.read_text(encoding="utf-8"))
+        if data.get("name") == name_or_slug:
+            candidates.insert(0, file)
+            break
+    for file in candidates:
+        if file.exists():
+            data = json.loads(file.read_text(encoding="utf-8"))
+            layers = []
+            for entry in data.get("layers", []):
+                placeholder = entry.get("placeholder") if isinstance(entry.get("placeholder"), dict) else None
+                layers.append(
+                    ConstructionLayer(
+                        material_id=entry.get("material_id"),
+                        thickness_m=float(entry["thickness_m"]),
+                        placeholder=(
+                            {
+                                "name": str(placeholder.get("name") or ""),
+                                "lambda_value": finite_or_none(placeholder.get("lambda_value")),
+                            }
+                            if placeholder
+                            else None
+                        ),
+                    )
+                )
+            return Construction(name=data["name"], design_usage=data.get("design_usage"), layers=layers)
+    return None
+
+
+def list_constructions() -> list[str]:
+    names = []
+    for file in constructions_dir().glob("*.json"):
+        try:
+            names.append(json.loads(file.read_text(encoding="utf-8"))["name"])
+        except (json.JSONDecodeError, KeyError):
+            continue
+    return sorted(names)
+
+
+def delete_construction(name_or_slug: str) -> bool:
+    directory = constructions_dir()
+    named = _find_stored_name_file(directory, name_or_slug)
+    file = named if named is not None else directory / f"{slugify(name_or_slug)}.json"
+    if file.exists():
+        file.unlink()
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# NON-SPEC vendor content: some producer tools encode a layer stack inside the
+# <construction> string body (format observed as:
+#   001[HEADER;][PREFIX$]THICK@GUID(FLAGS);...
+# ). This is NOT part of materialsdb103.xsd (which defines a plain string).
+# The decoder below is best-effort and read-only: unknown tokens are preserved
+# verbatim, unresolvable guids are flagged by the caller, never fatal.
+# ---------------------------------------------------------------------------
+
+_LEGACY_LAYER_RE = re.compile(r"(?:\d+:\d+\$)?([0-9.]+)@([0-9a-fA-F-]{36})(?:\(([^)]*)\))?")
+
+
+def parse_legacy_stack(body: str) -> dict:
+    """Best-effort decode of a vendor-specific construction stack string.
+
+    Returns {"version": str, "variants": [{"header_raw": str,
+    "layers": [{"guid", "thickness_m", "flags_raw"}]}], "raw": body}.
+    Semantics of header numbers / flag letters are UNKNOWN and preserved
+    verbatim."""
+    body = body.strip()
+    version = body[:3]
+    variants = []
+    for group in re.findall(r"\[([^\]]*)\]", body):
+        header_raw = ""
+        layers = []
+        for segment in (s for s in group.split(";") if s.strip()):
+            match = _LEGACY_LAYER_RE.search(segment)
+            if match is None:
+                # not a layer -> opaque header token (only valid before layers)
+                if not layers:
+                    header_raw = segment
+                continue
+            layers.append(
+                {
+                    "guid": match.group(2),
+                    "thickness_m": float(match.group(1)),
+                    "flags_raw": match.group(3) or "",
+                }
+            )
+        variants.append({"header_raw": header_raw, "layers": layers})
+    return {"version": version, "variants": variants, "raw": body}