tan-cli 0.7.0__py3-none-any.whl

tan/planner/partition.py

@@ -0,0 +1,1160 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Storage-partition resolver -- board.yaml `storage:` entries -> resolved partitions.
+
+Resolves each StorageEntry to a ResolvedPartition: picks the flash device (the
+SoM memory_map region names + on_module.ospi_memories keys), computes base/size
+with page alignment, and flags overlaps. An entry that can't resolve (unknown
+device / no size) becomes a blocked ResolvedPartition. Extracted from
+alp_orchestrate as the #285 partition seam.
+
+Depends only downward -- models (which carries the metadata root the project
+was resolved against, tan-cli#573), memregion (_PAGE /
+_region_size_bytes), and som_metadata.resolve_memory_map; nothing calls back into
+the package __init__.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from .aperture import is_partition_inside_aperture, resolve_aperture
+from .memregion import _PAGE, _region_size_bytes
+from .models import BoardProject, ResolvedPartition, StorageEntry
+from .som_metadata import resolve_memory_map
+
+# Sentinel distinguishing "caller has no hoisted aperture yet, resolve it"
+# from a genuinely-resolved `aperture is None` ("this SoC declares none").
+# `resolve_storage_partitions()` resolves the aperture ONCE and threads it
+# through every helper below (the way `carveout.py` hoists it once per
+# `resolve_carve_outs()` call) instead of each helper -- and each region a
+# helper loops over -- re-parsing the SoC JSON and re-resolving the silicon
+# variant on its own. Callers outside this module (`loader.py`'s eager
+# cross-check, and the direct-call pytest suite) don't pass `aperture` at
+# all, so they keep resolving it themselves via this sentinel's default --
+# unchanged behaviour, just no longer redundant inside one resolve.
+_APERTURE_UNSET: Any = object()
+
+# `write_authority` value that means "writable by the application at
+# runtime" -- the ONLY value a `memory_map` row may itself claim for a
+# runtime mount (#2088). Same value, same rationale, as
+# `check_atoc_reservation._RUNTIME_WRITABLE_AUTHORITY` (#2086); duplicated
+# rather than imported since the two live in separate top-level scripts.
+_RUNTIME_WRITABLE_AUTHORITY = "customer_runtime"
+
+# `write_authority` value meaning "whole-device alias spanning contained
+# rows of DIFFERENT authority -- consult the contained rows instead" (the
+# schema's own words for `memory_region.write_authority`, `mram_main`'s tag
+# on every AEN preset today). A composite row does NOT claim
+# customer-runtime-writable for itself, but it is also not an unconditional
+# pass: `_composite_alias_coverage_gap()` below is what actually "consults
+# the contained rows" this value promises -- refusing the alias outright
+# whenever a contained row can't be verified (unresolved base/size, absent
+# write_authority, or a gap none of them cover). Treating `composite` the
+# same as `customer_image`/`vendor_image`/`secure_enclave`/`none` --
+# refusing it unconditionally -- would refuse `mram_main` on every AEN
+# preset, the only whole-device alias any of them declares, even though it
+# is the intended `flash_device:` target
+# (docs/adr/0027-storage-regions-are-declared-by-role.md); this value
+# exists so that shape can still be verified rather than rubber-stamped.
+_DEFERRING_ALIAS_AUTHORITY = "composite"
+
+
+def _is_ospi_key_unassembled(som_preset: dict[str, Any], key: str) -> bool:
+    """Does `som_preset.on_module.ospi_memories[key]` carry `assembled:
+    false` -- the schema's tag for an on-module OSPI part this SKU's PCB
+    doesn't actually populate (e.g. E1M-AEN801's `ospi0`/`ospi1`, #2311)?
+
+    Shared by every caller that must refuse an unfitted OSPI part rather
+    than treat its `capacity_mbit` (a property of the shared PCB footprint,
+    not evidence of assembly) as usable: `_known_flash_devices()` and
+    `_resolve_flash_device()` below, and `loader.py`'s
+    `storage[].flash_device` cross-field check and its
+    `security.psa.{its,ps}_storage` cross-check. Line-for-line port of
+    alp-sdk's `scripts/alp_orchestrate/partition.py::_is_ospi_key_unassembled`;
+    both sides move together (#2311).
+    """
+    om = som_preset.get("on_module") or {}
+    ospi = om.get("ospi_memories") or {}
+    if not isinstance(ospi, dict) or key not in ospi:
+        return False
+    entry = ospi[key] or {}
+    return isinstance(entry, dict) and entry.get("assembled") is False
+
+
+def _resolve_aperture_arg(
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Any,
+) -> Optional[tuple[int, int]]:
+    """Return `aperture` verbatim when a caller already hoisted it;
+    resolve it fresh only when `aperture` is the `_APERTURE_UNSET`
+    sentinel (no caller has resolved it yet for this call)."""
+    if aperture is _APERTURE_UNSET:
+        return resolve_aperture(som_preset, metadata_root)
+    return aperture
+
+
+def _is_flash_sub_partition(
+    region: dict[str, Any],
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Any = _APERTURE_UNSET,
+) -> bool:
+    """alp-sdk#1365 split B (P2): is `region` a partition INSIDE a flash
+    device, not a device of its own?
+
+    Derives the verdict against the SoC's declared on-die MRAM aperture
+    (`aperture.is_partition_inside_aperture`) instead of trusting the
+    legacy `carveout:` flag outright. Falls back to the legacy flag
+    verbatim whenever the derivation can't resolve a definite verdict --
+    no aperture declared for this SoC (every non-Alif SoM), this region's
+    own `base` still unresolved (e.g. AEN's `mram_main`), OR this region's
+    resolved extent lying OUTSIDE the declared aperture (containment is
+    one-sided: outside proves nothing, so it does not by itself mean
+    "this is a device", alp-sdk#1365 split B review MAJOR 3): this is what
+    keeps split B a no-op everywhere it can't prove a better answer.
+
+    `aperture` defaults to the `_APERTURE_UNSET` sentinel, resolving it
+    fresh per call; pass an already-resolved aperture to avoid re-parsing
+    the SoC JSON when a caller is looping over many regions/devices in one
+    resolve.
+    """
+    aperture = _resolve_aperture_arg(som_preset, metadata_root, aperture)
+    inside = is_partition_inside_aperture(region, aperture)
+    if inside is None:
+        return region.get("carveout") is False
+    return inside
+
+
+def _known_flash_devices(
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Any = _APERTURE_UNSET,
+) -> list[str]:
+    """Enumerate every flash-device name a `storage[].flash_device:` may
+    reference for the given SoM preset.
+
+    Today this is the union of:
+      - `memory_map:` region names (explicit override or derived from
+        the SoC variant), excluding any region `_is_flash_sub_partition()`
+        calls a partition INSIDE a flash-class node rather than a device
+        of its own (#1484) -- derived against the SoC's declared on-die
+        MRAM aperture, falling back to the legacy `carveout: false` flag
+        wherever containment can't prove a verdict (alp-sdk#1365 split B),
+        AND
+      - `on_module.ospi_memories:` keys (when declared on the SoM).
+
+    Kept as a list so the loader's "did you mean..." message can sort
+    it deterministically.
+
+    `aperture` defaults to `_APERTURE_UNSET`, resolving it once for this
+    call (rather than once per region, as a call embedded in the loop
+    used to); pass an already-resolved aperture to share it across many
+    calls in one resolve (see `_APERTURE_UNSET`'s module comment).
+    """
+    aperture = _resolve_aperture_arg(som_preset, metadata_root, aperture)
+    names: set[str] = set()
+    for region in resolve_memory_map(som_preset, metadata_root):
+        n = region.get("name")
+        if not isinstance(n, str):
+            continue
+        if _is_flash_sub_partition(region, som_preset, metadata_root, aperture):
+            # A flash-class SUB-region -- an MRAM partition living inside a
+            # `mram_storage`-class flash node, not a flash device of its own
+            # (see the schema's `memory_region.carveout` description). On
+            # AEN this is `mcuboot` / `he_slot0` / `hp_slot0` / `reserved` /
+            # `storage` / `atoc`: none of them carries a Devicetree label,
+            # and decorating one with a `partitions { }` child targets a
+            # node the board tree never defines (#1484). Keep it out of the
+            # advertised set and out of `_resolve_flash_device()` below.
+            # alp-sdk#1365 split B: derived against the SoC's declared
+            # on-die MRAM aperture (containment), not the legacy
+            # `carveout:` flag -- see `_is_flash_sub_partition()`.
+            continue
+        names.add(n)
+    om = som_preset.get("on_module") or {}
+    ospi = om.get("ospi_memories") or {}
+    if isinstance(ospi, dict):
+        for k in ospi:
+            if not isinstance(k, str):
+                continue
+            if _is_ospi_key_unassembled(som_preset, k):
+                # Not fitted on this SKU (e.g. E1M-AEN801's ospi0/ospi1) --
+                # don't advertise a device `_resolve_flash_device()` below
+                # will refuse anyway (alp-sdk#2311).
+                continue
+            names.add(k)
+    return sorted(names)
+
+
+def _reserved_spans(
+    device_name: str,
+    capacity_bytes: int,
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+) -> "tuple[list[tuple[int, int, str]], Optional[str]]":
+    """Return the SoM's own regions as DEVICE-RELATIVE [lo, hi) spans.
+
+    Returns `(spans, None)` on success, `([], reason)` when the spans can't
+    be computed safely -- the caller then falls back to sibling-only overlap
+    checking rather than trusting a guessed conversion (alp-sdk#1331).
+
+    Why this is needed at all: `storage[].offset_kib:` (and the bump
+    allocator) work in offsets WITHIN a flash device, while `memory_map:`
+    regions declare ABSOLUTE bases. Nothing previously bridged the two, so
+    every check was blind to the SoM's own layout -- on E1M-AEN801 that let a
+    littlefs mount resolve to offset 0 of `mram_main`, which is MCUboot, with
+    no `offset_kib:` involved and no `status: blocked`.
+
+    The device base is DERIVED, then VERIFIED, never assumed:
+
+      - If the device is itself a `memory_map:` region with an integer
+        `base`, that base is the origin -- authoritative, no further check
+        needed. On every AEN preset today this is the branch `mram_main`
+        takes: #2053 resolved its `base` to `0x80000000`, an ordinary
+        integer like any other region's.
+      - Otherwise (a device with no `base` of its own, e.g. a whole-window
+        alias whose `base:` is still an unresolved `"TBD"` placeholder --
+        no shipped AEN preset has this shape today; `mram_main` was the
+        standing example before #2053) take the lowest integer base among
+        the sibling regions and require `lowest + capacity == highest
+        region top`. That identity is what proves the alias really spans
+        the same window the fine-grained regions tile; if it does not
+        hold, refuse to convert. This is the ONLY leg that ever ran the
+        identity check -- it exists to substitute for a missing origin,
+        so it is unreachable (and its absence is safe, not a gap) once
+        the device carries a real `base` and takes the branch above
+        instead.
+
+    `_resolve_flash_device`'s descriptor deliberately carries no physical
+    base (Zephyr's flash-mapping layer derives it from the DT controller
+    node), which is why the origin is reconstructed here instead of being
+    read off the descriptor.
+    """
+    regions = [r for r in resolve_memory_map(som_preset, metadata_root)
+               if isinstance(r, dict)]
+    sized = [(r["base"], r["base"] + (_region_size_bytes(r) or 0), str(r.get("name")))
+             for r in regions
+             if isinstance(r.get("base"), int) and _region_size_bytes(r)]
+    if not sized:
+        return [], (f"SoM declares no addressed memory_map region, so "
+                    f"'{device_name}' offsets cannot be checked against it")
+
+    self_region = next((r for r in regions if r.get("name") == device_name), None)
+    if self_region is not None and isinstance(self_region.get("base"), int):
+        origin = self_region["base"]
+    else:
+        origin = min(lo for lo, _, _ in sized)
+        window_top = max(hi for _, hi, _ in sized)
+        if origin + capacity_bytes != window_top:
+            return [], (
+                f"flash device '{device_name}' has no declared base and its "
+                f"capacity ({capacity_bytes} B) does not span the addressed "
+                f"memory_map window (0x{origin:x}..0x{window_top:x}), so its "
+                f"offsets cannot be mapped onto the SoM's regions")
+
+    spans: "list[tuple[int, int, str]]" = []
+    for lo, hi, name in sized:
+        # The device itself is not an obstacle inside itself; nor is a region
+        # that spans the whole window (a coarse alias) -- otherwise every
+        # partition would "overlap" it and nothing could ever be placed.
+        if name == device_name or (lo <= origin and hi - lo >= capacity_bytes):
+            continue
+        rel_lo, rel_hi = lo - origin, hi - origin
+        # Clip to the device; a region outside it is simply not our problem.
+        rel_lo, rel_hi = max(rel_lo, 0), min(rel_hi, capacity_bytes)
+        if rel_hi > rel_lo:
+            spans.append((rel_lo, rel_hi, name))
+    return sorted(spans), None
+
+
+def _first_free(
+    base_bytes: int,
+    size_aligned: int,
+    allocated: "list[tuple[int, int, str]]",
+    capacity_bytes: int,
+) -> int:
+    """Advance `base_bytes` past any span it collides with, page-aligned.
+
+    The bump allocator must allocate AROUND the SoM's reserved regions, not
+    merely notice a collision: refusing instead of skipping would break the
+    ordinary case (a project that names no addresses at all) rather than fix
+    it. Returns the first non-colliding page-aligned base, or a value past
+    `capacity_bytes` when the device has no room left -- the caller reports
+    that as a blocked entry.
+    """
+    moved = True
+    while moved:
+        moved = False
+        for lo, hi, _ in sorted(allocated):
+            if base_bytes < hi and lo < base_bytes + size_aligned:
+                base_bytes = ((hi + _PAGE - 1) // _PAGE) * _PAGE
+                moved = True
+        if base_bytes >= capacity_bytes:
+            return base_bytes
+    return base_bytes
+
+
+def _composite_alias_coverage_gap(
+    alias_name: str,
+    alias_base: Any,
+    capacity_bytes: int,
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Optional[tuple[int, int]],
+) -> Optional[str]:
+    """#2088: what "`write_authority: composite` means consult the
+    contained rows" actually has to DO, not just claim.
+
+    Returns `None` when the `memory_map:` rows CONTAINED in
+    `alias_name`'s own `[origin, origin+capacity_bytes)` window --
+    resolved, `write_authority`-bearing, non-overlapping -- CONTIGUOUSLY
+    tile that window with no gap (review round 2, Major 1: an earlier
+    version of this function summed sizes rather than walking spans, so
+    an overlap of N bytes plus a hole of N bytes passed the sum check
+    while the hole itself stayed unprotected -- reproduced by deleting
+    `atoc` and widening `he_slot0` by exactly `atoc`'s size). Returns a
+    refusal reason otherwise, naming the gap or the overlapping pair.
+
+    A row whose resolved extent lies OUTSIDE the window (a genuinely
+    unrelated device that merely happens to share this SoM's
+    `memory_map:` list) is ignored -- containment, not mere co-listing,
+    is what makes a row this alias's business.
+
+    A row whose base or size DOESN'T resolve is not immediately fatal on
+    its own (review round 2, Major 3: an earlier version refused for
+    ANY such row unconditionally, which also refused a genuinely
+    unrelated device parked at a TBD-but-clearly-different address
+    purely because its address wasn't resolved yet -- indistinguishable
+    from `atoc`'s real pre-HW-mapped shape without more information).
+    Instead: walk only the rows that DO resolve; if they alone already
+    tile the window with no gap, an unresolved-base sibling can only be
+    something else entirely (resolving it into an overlap would be a
+    SEPARATE metadata bug for a different gate to catch, not evidence
+    this alias is unsafe today) -- but if a gap remains, an unresolved
+    sibling is named as a candidate that might explain it (never ruled
+    out, per ADR-0034 clause 4), while an alias with NO unresolved
+    sibling AND a gap has nothing left to blame but a genuinely missing
+    row.
+
+    `origin` is `alias_base` when the alias's own base has resolved;
+    else `aperture[0]` when an aperture resolves for this SoM (`mram_main`
+    itself carries `base: "TBD"` on every AEN preset today, so this is
+    the common case, not the exception -- using the SoC's own declared
+    aperture start here, rather than the lowest resolved sibling base,
+    avoids anchoring the window at a fabricated address when a resolved
+    but genuinely-unrelated sibling happens to sit below every real
+    contained row, review round 2 Minor); else the lowest resolved base
+    among sibling rows, for a non-Alif SoM with no aperture to anchor to.
+
+    Without this whole function, a sibling with an unresolved `base` or
+    a sibling missing from `memory_map:` altogether contributes NO span
+    to `_reserved_spans()`, which reserves only what it can see -- so
+    the bump allocator treats the unaccounted band as free. On
+    `mram_main`, that band can be the Secure-Enclave-owned `atoc` window
+    (bench-observed live at 0x80578000..0x80580000, `carveout.py:100-104`).
+    `aperture` gates the same absent-write_authority leniency
+    `_resolve_flash_device()`'s own guard applies just above this call --
+    a non-Alif sibling with no `write_authority` at all is not itself
+    the hazard.
+    """
+    siblings = [r for r in resolve_memory_map(som_preset, metadata_root)
+                if isinstance(r, dict) and r.get("name") != alias_name]
+
+    def _resolved_int(value: Any) -> bool:
+        return isinstance(value, int) and not isinstance(value, bool)
+
+    if _resolved_int(alias_base):
+        origin = alias_base
+    elif aperture is not None:
+        origin = aperture[0]
+    else:
+        resolved_bases = [r["base"] for r in siblings if _resolved_int(r.get("base"))]
+        if not resolved_bases:
+            return (
+                f"flash device '{alias_name}' declares "
+                f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, which defers "
+                f"eligibility to its contained memory_map rows -- but "
+                f"neither '{alias_name}' itself nor any sibling row has a "
+                f"resolved base, and no SoC aperture resolves either, so "
+                f"its window cannot be anchored to verify anything inside "
+                f"it. Resolve at least one memory_map row's base before "
+                f"targeting '{alias_name}' with a storage[].flash_device: "
+                f"(#2088)")
+        origin = min(resolved_bases)
+    top = origin + capacity_bytes
+
+    contained: "list[tuple[int, int, str]]" = []
+    ambiguous_names: "list[str]" = []
+    for region in siblings:
+        name = region.get("name")
+        base = region.get("base")
+        if not _resolved_int(base):
+            ambiguous_names.append(str(name))
+            continue
+        size_bytes = _region_size_bytes(region)
+        if size_bytes is None:
+            ambiguous_names.append(str(name))
+            continue
+        hi = base + size_bytes
+        if base >= top or hi <= origin:
+            continue  # Disjoint -- a different device, not this alias's business.
+        if not (base >= origin and hi <= top):
+            # Partial overlap with the WINDOW boundary -- neither cleanly
+            # inside nor cleanly outside. Rare/malformed; refuse rather
+            # than guess which side of the boundary the bytes belong to.
+            return (
+                f"flash device '{alias_name}' declares "
+                f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, which defers "
+                f"eligibility to its contained memory_map rows -- but "
+                f"region {name!r} [0x{base:x}, 0x{hi:x}) only partially "
+                f"overlaps '{alias_name}'s 0x{origin:x}..0x{top:x} "
+                f"window, so it can't be cleanly attributed as contained "
+                f"or disjoint. Fix the addresses before targeting "
+                f"'{alias_name}' with a storage[].flash_device: (#2088)")
+        wa = region.get("write_authority")
+        if wa is None and aperture is not None:
+            return (
+                f"flash device '{alias_name}' declares "
+                f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, which defers "
+                f"eligibility to its contained memory_map rows -- but "
+                f"region {name!r}, contained in '{alias_name}'s window, "
+                f"carries no write_authority, so whether it may host a "
+                f"runtime mount cannot be verified. Author "
+                f"write_authority: on {name!r} before targeting "
+                f"'{alias_name}' with a storage[].flash_device: (#2088)")
+        contained.append((base, hi, str(name)))
+
+    # Walk the CONTAINED, resolved spans in address order and require
+    # exact contiguity -- an overlap of N bytes plus a hole of N bytes
+    # must not cancel out in a sum (review round 2, Major 1).
+    contained.sort()
+    cursor = origin
+    prev_name = None
+    for lo, hi, name in contained:
+        if lo < cursor:
+            return (
+                f"flash device '{alias_name}' declares "
+                f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, which defers "
+                f"eligibility to its contained memory_map rows -- but "
+                f"region {name!r} [0x{lo:x}, 0x{hi:x}) overlaps "
+                f"{prev_name!r}, which ends at 0x{cursor:x}, by "
+                f"{(cursor - lo) // 1024} KiB. Two rows claiming the same "
+                f"bytes means at most one of their `write_authority` "
+                f"values actually applies there; fix the addresses before "
+                f"targeting '{alias_name}' with a storage[].flash_device: "
+                f"(#2088)")
+        if lo > cursor:
+            break  # Gap -- reported below, naming any candidate that might fill it.
+        cursor = hi
+        prev_name = name
+
+    if cursor < top:
+        gap_lo, gap_hi = cursor, top
+        candidate_note = (
+            f" -- {', '.join(sorted(ambiguous_names))} carries an "
+            f"unresolved base or size and cannot be ruled out as the "
+            f"row that belongs there"
+            if ambiguous_names else
+            f" and no memory_map row with an unresolved base or size "
+            f"exists either, so this is a genuinely undeclared row")
+        return (
+            f"flash device '{alias_name}' declares "
+            f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on SoM "
+            f"{som_preset.get('sku', '<unknown>')} "
+            f"({capacity_bytes // 1024} KiB, window 0x{origin:x}.."
+            f"0x{top:x}), but its contained memory_map rows leave a gap "
+            f"at 0x{gap_lo:x}..0x{gap_hi:x} ({(gap_hi - gap_lo) // 1024} "
+            f"KiB) unaccounted for{candidate_note}. Declare the missing "
+            f"row(s) before targeting '{alias_name}' with a "
+            f"storage[].flash_device: (#2088)")
+    return None
+
+
+def _resolve_flash_device(
+    flash_device: str,
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Any = _APERTURE_UNSET,
+) -> tuple[Optional[dict[str, Any]], Optional[str]]:
+    """Resolve a board.yaml `flash_device:` reference to a device descriptor.
+
+    Returns `(descriptor, None)` on success; `(None, reason)` when the
+    device is known but cannot be allocated against (TBD capacity).
+    The descriptor carries:
+        name        -- the SDK device name (verbatim from board.yaml)
+        dt_label    -- the Zephyr DT label to decorate
+        size_bytes  -- capacity in bytes (None when unresolvable)
+
+    Address allocation is offset-within-device; the descriptor does
+    NOT carry a physical base because Zephyr's flash-mapping layer
+    derives that from the DT controller node.  The emitted overlay
+    references `&<dt_label>` and lets Zephyr handle the physical mapping.
+
+    `aperture` defaults to `_APERTURE_UNSET` (resolve fresh); pass an
+    already-resolved aperture to share it across many calls in one
+    resolve (see `_APERTURE_UNSET`'s module comment).
+    """
+    aperture = _resolve_aperture_arg(som_preset, metadata_root, aperture)
+    # memory_map: region match first (covers the auto-derived MRAM /
+    # SRAM region table from resolve_memory_map()).
+    for region in resolve_memory_map(som_preset, metadata_root):
+        if region.get("name") != flash_device:
+            continue
+        if _is_flash_sub_partition(region, som_preset, metadata_root, aperture):
+            # Defense in depth for a hand-built project that skips the
+            # loader's `_known_flash_devices()` check: refuse rather than
+            # fabricate a `dt_label` from the region name.  This region is
+            # a partition INSIDE a flash-class node (e.g. AEN's
+            # `mram_storage`), not a flash device -- it has no Devicetree
+            # label of its own and a `partitions { }` child on it targets
+            # a node the board tree never defines (#1484). alp-sdk#1365
+            # split B: derived against the declared MRAM aperture, not the
+            # legacy `carveout:` flag -- see `_is_flash_sub_partition()`.
+            return None, (
+                f"flash device '{flash_device}' is a partition inside a "
+                f"flash-class region on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, not a flash device "
+                f"of its own -- it has no Devicetree label and cannot take "
+                f"a `partitions {{ }}` child")
+        # #2088: a resolved memory_map region is not automatically
+        # customer-writable at runtime -- that includes a whole-device
+        # alias (e.g. `mram_main`), which `_is_flash_sub_partition()`
+        # above correctly does NOT treat as a sub-partition, so it would
+        # otherwise fall straight through to a resolved descriptor. Per
+        # the schema (`memory_region.write_authority`), a row may take a
+        # runtime mount only when it claims `customer_runtime` directly,
+        # OR defers as a `composite` alias (see `_DEFERRING_ALIAS_AUTHORITY`
+        # above) AND every contained row it defers to is independently
+        # verified safe below -- every other AUTHORED value
+        # (customer_image/vendor_image/secure_enclave/none) means
+        # something else owns writes to this region and refuses outright.
+        wa = region.get("write_authority")
+        if wa is not None and wa not in (
+                _RUNTIME_WRITABLE_AUTHORITY, _DEFERRING_ALIAS_AUTHORITY):
+            return None, (
+                f"flash device '{flash_device}' declares "
+                f"write_authority: {wa!r} on SoM "
+                f"{som_preset.get('sku', '<unknown>')}, which is not "
+                f"customer-writable at runtime -- only a region declaring "
+                f"write_authority: {_RUNTIME_WRITABLE_AUTHORITY!r} (or "
+                f"{_DEFERRING_ALIAS_AUTHORITY!r} for a whole-device alias "
+                f"that defers to contained rows) may take a runtime mount "
+                f"(storage[].flash_device:). Either give '{flash_device}' "
+                f"write_authority: {_RUNTIME_WRITABLE_AUTHORITY!r} if it "
+                f"truly is the customer's runtime storage, or point "
+                f"flash_device: at the region that is (#2088)")
+        # An ABSENT value is different: the schema and ADR-0034 clause 4
+        # both say absent means UNRESOLVED, never `customer_runtime` -- "a
+        # consumer must treat an authored region carrying no
+        # write_authority as ineligible for ... runtime write ... rather
+        # than defaulting permissively" (`docs/porting-new-som.md`
+        # repeats this verbatim). `carveout.py`'s equivalent guard
+        # (`_region_ipc_eligibility`'s "unclassified"/"unresolved" legs)
+        # enforces this the same way -- refuse -- but ONLY once an
+        # on-die MRAM aperture actually resolves for this SoM (every
+        # non-Alif SoM, and any Alif SoC/variant that hasn't declared
+        # one, short-circuits before this rule even runs -- see
+        # `_candidate_regions()`). Mirrored here: refusing
+        # unconditionally would fire on every V2N/V2M preset's
+        # `memory_map:` rows, none of which author `write_authority` at
+        # all and none of which a customer can fix by authoring a field
+        # this guard doesn't even apply to.
+        if wa is None and aperture is not None:
+            return None, (
+                f"flash device '{flash_device}' on SoM "
+                f"{som_preset.get('sku', '<unknown>')} carries no "
+                f"write_authority -- ADR-0034 clause 4 and the schema "
+                f"both say an absent value means unresolved, not "
+                f"'customer_runtime': treat it as ineligible for a "
+                f"runtime write rather than defaulting permissively. "
+                f"Author write_authority: {_RUNTIME_WRITABLE_AUTHORITY!r} "
+                f"on '{flash_device}' if it is meant to take a runtime "
+                f"mount, or point flash_device: at a region that already "
+                f"declares it (#2088)")
+        size_bytes = _region_size_bytes(region)
+        if size_bytes is None:
+            return None, (
+                f"flash device '{flash_device}' resolves to memory_map "
+                f"region but size_mib / size_kib is unset or TBD on "
+                f"SoM {som_preset.get('sku', '<unknown>')}; the SoM "
+                f"hasn't been HW-mapped yet")
+        if wa == _DEFERRING_ALIAS_AUTHORITY:
+            # `composite` means "consult the contained rows instead" --
+            # so actually consult them, rather than trusting the alias's
+            # own tag as a pass. Every OTHER row in this SoM's memory_map
+            # must resolve to a concrete [base, base+size) span AND
+            # declare its own write_authority, and together they must
+            # fully tile this alias's capacity, before the alias can be
+            # called safe: a row this can't account for (unresolved base
+            # or size, absent authority, or a gap none of them cover) is
+            # exactly the #2088 hazard (a storage[] entry silently
+            # landing in the unaccounted-for band, e.g. the SE-owned
+            # `atoc` window when its base is still TBD) -- refuse the
+            # whole alias rather than resolve permissively around a hole
+            # this function can't see the shape of.
+            gap_reason = _composite_alias_coverage_gap(
+                flash_device, region.get("base"), size_bytes, som_preset,
+                metadata_root, aperture)
+            if gap_reason is not None:
+                return None, gap_reason
+            # #2088 review round 2, Major 2: the coverage-gap walk above
+            # proves the CONTAINED rows are individually sound, but
+            # placement itself runs through `_reserved_spans()` --  a
+            # SEPARATE, older function with its own (weaker) origin/
+            # window derivation. An out-of-window sibling (correctly
+            # ignored as disjoint above) can still push
+            # `_reserved_spans()`'s own `window_top = max(hi for sized)`
+            # past this alias's real top, failing its
+            # `origin + capacity == window_top` identity check and
+            # degrading it to `([], reason)` -- silently reserving
+            # NOTHING, including `mcuboot`, for any caller that placed a
+            # storage[] entry here. An alias whose contained rows can't
+            # actually be RESERVED is exactly as unconsultable as one
+            # whose rows can't be VERIFIED (the same principle already
+            # applied to an unresolved base above) -- refuse rather than
+            # let a caller believe the window this function just proved
+            # safe stays protected at placement time.
+            _reserved_probe, reserved_degraded_reason = _reserved_spans(
+                flash_device, size_bytes, som_preset, metadata_root)
+            if reserved_degraded_reason is not None:
+                return None, (
+                    f"flash device '{flash_device}' declares "
+                    f"write_authority: {_DEFERRING_ALIAS_AUTHORITY!r} on "
+                    f"SoM {som_preset.get('sku', '<unknown>')} -- its "
+                    f"contained memory_map rows verify safe, but "
+                    f"{reserved_degraded_reason}, so placement cannot "
+                    f"actually reserve them: an alias whose contained "
+                    f"rows can't be reserved can't be consulted either "
+                    f"(#2088)")
+        dt_label = (region.get("dt_label")
+                    if isinstance(region.get("dt_label"), str)
+                    else flash_device)
+        return {
+            "name":       flash_device,
+            "dt_label":   dt_label,
+            "size_bytes": size_bytes,
+        }, None
+
+    # on_module.ospi_memories: key match.
+    #
+    # alp-sdk#2311: refuse a device this SKU's preset declares
+    # `assembled: false` (e.g. `E1M-AEN801`'s `ospi0`/`ospi1`) BEFORE
+    # looking at `capacity_mbit` -- `capacity_mbit` is the DESIGNED-IN
+    # part's capacity (present on the shared PCB footprint), not evidence
+    # the module actually carries the part. `_known_flash_devices()` above
+    # already keeps an unassembled device out of the advertised set; this
+    # is the same guard applied where a hand-built project (or a stale
+    # caller) skips that check and calls this resolver directly (defense
+    # in depth). `optional` and an absent key (schema default: true) both
+    # still resolve -- `assembled` must be the literal `False` the schema
+    # uses for "not fitted".
+    #
+    # Ported line-for-line from alp-sdk's
+    # scripts/alp_orchestrate/partition.py::_resolve_flash_device; both
+    # sides move together (alp-sdk#2311).
+    om = som_preset.get("on_module") or {}
+    ospi = om.get("ospi_memories") or {}
+    if isinstance(ospi, dict) and flash_device in ospi:
+        entry = ospi[flash_device] or {}
+        if _is_ospi_key_unassembled(som_preset, flash_device):
+            sku = som_preset.get("sku")
+            where = f"SoM {sku}" if sku else "this SoM"
+            yaml_ref = (f"metadata/e1m_modules/{sku}.yaml" if sku
+                        else "its SoM preset YAML")
+            return None, (
+                f"flash device '{flash_device}' is not assembled on "
+                f"{where} (assembled: false in {yaml_ref}); it cannot "
+                f"take a runtime storage mount")
+        cap = entry.get("capacity_mbit")
+        if isinstance(cap, str) and cap.strip().upper() == "TBD":
+            return None, (
+                f"on_module.ospi_memories.{flash_device}.capacity_mbit "
+                f"is TBD on SoM {som_preset.get('sku', '<unknown>')}; "
+                f"fill the value or move the storage entry to a sized "
+                f"flash device")
+        if not isinstance(cap, int):
+            return None, (
+                f"on_module.ospi_memories.{flash_device}.capacity_mbit "
+                f"is missing on SoM {som_preset.get('sku', '<unknown>')}; "
+                f"the storage allocator needs an authoritative capacity")
+        dt_label = (entry.get("dt_label")
+                    if isinstance(entry.get("dt_label"), str)
+                    else flash_device)
+        # capacity_mbit is megabits; convert to bytes.
+        size_bytes = int(cap) * 1024 * 1024 // 8
+        return {
+            "name":       flash_device,
+            "dt_label":   dt_label,
+            "size_bytes": size_bytes,
+        }, None
+
+    # Unknown device — the loader catches this earlier, but defend
+    # in depth in case a resolver is called with a hand-built project.
+    return None, (
+        f"flash device '{flash_device}' is neither a memory_map region "
+        f"nor an on_module.ospi_memories key on SoM "
+        f"{som_preset.get('sku', '<unknown>')}")
+
+
+def _has_real_dt_label(
+    flash_device: str,
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+) -> bool:
+    """True when `flash_device`'s Devicetree label is KNOWN, not fabricated.
+
+    `_resolve_flash_device()` succeeding is NOT enough to recommend a device
+    to a customer: its `dt_label` DEFAULTS to the device name whenever the
+    metadata omits an explicit override, and that default is unverified
+    against the board `.dts` (see the schema's `memory_region.dt_label`
+    description -- AEN's `mram_main` region, for example, names its flash
+    node `mram_storage`, not `mram_main`). Emitting `&<name>` for one of
+    those is the exact defect #1484 closes.
+
+    An `on_module.ospi_memories:` key does NOT qualify, despite its name
+    matching a controller node's label 1:1 on paper. Measured against the
+    generated Zephyr board trees (#1484 re-review): `ospi0` is the ONLY
+    `ospi<n>` label that exists anywhere under `zephyr/`
+    (`zephyr/dts/alif/ensemble_e8_peripherals.dtsi:688`), it is included by
+    only the two E1M-AEN801 board `.dts` files, and there it is the OSPI
+    CONTROLLER node (`compatible = "snps,designware-ospi"`,
+    `status = "disabled"`) -- neither AEN801 board tree enables it or gives
+    it a flash-chip child, so a `fixed-partitions` overlay under `&ospi0`
+    would not be a working flash area even on the one SKU where the label
+    exists. E1M-AEN401/601 have a board tree with no `ospi0` node at all;
+    E1M-AEN301/501/701 have no board tree in `zephyr/boards/alp/` at all.
+    `scripts/gen_zephyr_board.py` never generates an `ospi<n>` node either.
+    So until a real per-instance DT label is wired up and verified against
+    an ENABLED node, no `ospi_memories:` key is trustworthy here.
+
+    Only trust a `memory_map:` region that carries an EXPLICIT `dt_label:`
+    override -- nothing does yet, so this currently returns `False` for
+    every device on every SoM. That is the correct interim answer: it means
+    `alt_devices` never recommends a target this resolver cannot verify,
+    rather than recommending one that merely LOOKS verified.
+
+    alp-sdk#1556: `resolve_storage_partitions()` now gates the PRIMARY
+    resolution on this same predicate for a `memory_map:`-sourced device
+    (not just the alt-device remedy) -- naming `flash_device: mram_main`
+    (or any other unverified `memory_map:` region) can no longer reach
+    `status: ok`; it blocks with a reason instead of fabricating a DT
+    label the board tree never defines. `on_module.ospi_memories:`
+    devices are NOT gated by that change (`is_ospi_device` in the
+    resolver still short-circuits this predicate to `True` for them) --
+    this function already returns `False` for every `ospi_memories:` key
+    (the loop below only ever matches a `memory_map:` region name), so
+    gating the primary path on it unconditionally would also block every
+    `ospi0`-targeting entry, including the ones the existing storage test
+    suite (`tests/scripts/test_orchestrate_storage*.py`) deliberately uses
+    as its "device-independent allocator mechanics" fixture. Verifying
+    `ospi_memories:` against its own real, per-instance DT label is a
+    separate gap this issue's repro does not cover (see this function's
+    own paragraph above) -- left as tracked follow-up, not silently
+    widened here.
+    """
+    for region in resolve_memory_map(som_preset, metadata_root):
+        if region.get("name") == flash_device:
+            return isinstance(region.get("dt_label"), str)
+    return False
+
+
+def _verified_alt_devices(
+    exclude: str,
+    som_preset: dict[str, Any],
+    metadata_root: Path,
+    aperture: Any = _APERTURE_UNSET,
+) -> list[str]:
+    """Every known flash device other than `exclude` that both resolves
+    (`_resolve_flash_device()`) and carries a verified Devicetree label
+    (`_has_real_dt_label()`) -- the only kind of device safe to name back
+    to a customer as a `flash_device:` alternative (#1484 / #1556: naming
+    one that merely LOOKS verified reproduces the exact defect either
+    issue closes). Used by `resolve_storage_partitions()`'s #1556
+    unverified-dt_label block; kept separate from the near-identical
+    filter already inlined in the overlap-block remedy below (that one
+    also excludes the SoM's own reserved region names, which don't apply
+    here) rather than risk a shared-helper refactor rippling into that
+    already-reviewed code path.
+
+    `aperture` defaults to `_APERTURE_UNSET` (resolve fresh); pass an
+    already-resolved aperture to share it across many calls in one
+    resolve (see `_APERTURE_UNSET`'s module comment).
+    """
+    aperture = _resolve_aperture_arg(som_preset, metadata_root, aperture)
+    return sorted(
+        d for d in _known_flash_devices(som_preset, metadata_root, aperture)
+        if d != exclude
+        and _has_real_dt_label(d, som_preset, metadata_root)
+        and _resolve_flash_device(d, som_preset, metadata_root, aperture)[0] is not None)
+
+
+def _blocked_partition(
+    entry: StorageEntry,
+    reason: str,
+) -> ResolvedPartition:
+    """Project a StorageEntry into a blocked ResolvedPartition."""
+    return ResolvedPartition(
+        name=entry.name,
+        fs=entry.fs,
+        flash_device=entry.flash_device or "",
+        dt_label="",
+        base_kib=0,
+        size_kib=entry.size_kib,
+        mount=entry.mount,
+        status="blocked",
+        reason=reason,
+    )
+
+
+def resolve_storage_partitions(
+    project: BoardProject,
+) -> list[ResolvedPartition]:
+    """Allocate physical offsets for every storage[] entry.
+
+    Algorithm (mirrors `resolve_carve_outs()`):
+      1. Group entries by `flash_device:` (entries without one block
+         immediately; the loader normally catches that, but this is
+         the resolver's failure mode for hand-built projects).
+      2. Within each group, sort by name for determinism (an explicit
+         `offset_kib:` doesn't change sort order — it's an override
+         the allocator simply respects).
+      3. Place every `offset_kib:`-pinned entry FIRST (page-aligned
+         check; overlap check against the SoM's own regions and prior
+         pins), then bump-allocate the rest bottom-up from the current
+         high-water mark, stepping over the pins.  Pinning first is
+         what keeps a pin that sorts LATE alphabetically from being
+         dropped by a sibling the allocator had already placed on top
+         of it (#554).
+      4. Block on capacity overflow, TBD device, page-misaligned
+         offset, or sibling overlap.  Blocked entries land in the
+         manifest with `status: blocked` + `reason:` so reviewers see
+         the gap; the slice build trips when the DTS overlay is
+         consumed.
+
+    Spec note: byte-stable OTA images require the orchestrator to pin
+    addresses (resolved in design Q1 for v0.6 -- option "Pin in
+    orchestrator").  Customers get reproducible per-rebuild addresses
+    by declaring stable `name:` slugs; partitions stay at the same
+    offset across rebuilds as long as their relative order doesn't
+    change.  Explicit `offset_kib:` is the escape hatch.
+    """
+    if not project.storage:
+        return []
+
+    # Group by flash device, preserving original order for the
+    # downstream resolver (we re-sort for allocation determinism below).
+    by_device: dict[str, list[StorageEntry]] = {}
+    no_device: list[StorageEntry] = []
+    for entry in project.storage:
+        if not entry.flash_device:
+            no_device.append(entry)
+        else:
+            by_device.setdefault(entry.flash_device, []).append(entry)
+
+    resolved: list[ResolvedPartition] = []
+
+    for entry in no_device:
+        resolved.append(_blocked_partition(entry, (
+            f"storage entry '{entry.name}' has no flash_device: "
+            f"declared; add one referencing a SoM memory_map region "
+            f"or an on_module.ospi_memories key")))
+
+    # alp-sdk#1365 split B (Also fix): hoist the aperture ONCE for this
+    # whole resolve, the way `carveout.py` hoists it once per
+    # `resolve_carve_outs()` call -- every downstream helper below
+    # (`_resolve_flash_device`, `_known_flash_devices` via
+    # `_verified_alt_devices`, the alt-device scan inlined in `_place()`)
+    # otherwise re-parses the SoC JSON and re-resolves the silicon variant
+    # once per region AND once per storage entry / alt-device enumeration.
+    aperture = resolve_aperture(
+        project.som_preset, project.effective_metadata_root())
+
+    # Iterate flash devices in alphabetical order; within each device,
+    # entries are name-sorted for byte-stable allocation.
+    for device_name in sorted(by_device.keys()):
+        descriptor, block_reason = _resolve_flash_device(
+            device_name, project.som_preset,
+            project.effective_metadata_root(), aperture)
+        if descriptor is None:
+            for entry in by_device[device_name]:
+                resolved.append(_blocked_partition(
+                    entry, block_reason or "flash device unresolvable"))
+            continue
+
+        dt_label = descriptor["dt_label"]
+        capacity_bytes = descriptor["size_bytes"]
+        # True when `device_name` is an `on_module.ospi_memories:` key --
+        # an off-chip OSPI part that legitimately has no `memory_map:`
+        # presence at all, vs. an on-chip `memory_map:` device (`ddr_main`
+        # etc.) where the SoM's own regions really do live on the same
+        # address window.  Used below to keep the reserved-spans warning
+        # for the case it exists to catch.
+        is_ospi_device = device_name in (
+            (project.som_preset.get("on_module") or {}).get(
+                "ospi_memories") or {})
+        # #1556: `descriptor["dt_label"]` DEFAULTS to the device name
+        # whenever the SoM preset sets no explicit `dt_label:` override,
+        # and that default was never checked against the generated
+        # Zephyr board tree -- `flash_device: mram_main` resolved
+        # `status: ok` with a fabricated `dt_label` of `mram_main` even
+        # though the generated tree only defines `mram_storage`. Gate on
+        # the exact predicate #1484 already built for this
+        # (`_has_real_dt_label()`) so an entry can never reach
+        # `status: ok` on a `memory_map:` device whose label is
+        # unverified -- applied in `_place()` below, AFTER the
+        # overlap/overflow checks, so an entry that was already going to
+        # block for one of THOSE reasons keeps that reason (the SoM's
+        # own regions are the more actionable fact to report).
+        # `on_module.ospi_memories:` devices are deliberately exempted
+        # (see `_has_real_dt_label()`'s docstring) -- that key's
+        # verification gap is separate follow-up.
+        verified_dt_label = is_ospi_device or _has_real_dt_label(
+            device_name, project.som_preset,
+            project.effective_metadata_root())
+        # Page-aligned high-water mark; sibling partitions allocate
+        # bottom-up from offset 0.  Page = 4 KiB matches the IPC
+        # carve-out allocator; storage erase blocks on every silicon
+        # the SDK targets are 4 KiB-or-larger multiples.
+        high_water_bytes = 0
+        # Track allocated [lo, hi) ranges so explicit `offset_kib:`
+        # overrides can be checked against sibling allocations even
+        # when the bump allocator would have placed them differently.
+        allocated: list[tuple[int, int, str]] = []   # (lo, hi, name)
+
+        # Seed with the SoM's OWN regions (alp-sdk#1331).  Without this the
+        # checks below only ever saw sibling storage[] entries, so mcuboot, a
+        # core's slot0 and the SE-owned atoc band were all invisible: on
+        # E1M-AEN801 a littlefs mount resolved to offset 0 of `mram_main` --
+        # MCUboot -- with no offset_kib: declared and no status: blocked.
+        reserved_spans, reserved_reason = _reserved_spans(
+            device_name, capacity_bytes, project.som_preset,
+            project.effective_metadata_root())
+        reserved_names = {name for _, _, name in reserved_spans}
+        allocated.extend(reserved_spans)
+        if reserved_reason is not None and not is_ospi_device:
+            # Degrading to sibling-only checking is exactly the silent
+            # false-PASS this fix exists to remove, so SAY so rather than
+            # letting the caller believe the SoM's regions were honoured.
+            # Suppressed for an `ospi_memories:` device: an off-chip OSPI
+            # part has no `memory_map:` presence to begin with, so sibling-
+            # only checking isn't a degradation there -- warning on it
+            # would fire on every AEN storage build using `ospi0` (#1484
+            # review).
+            print(f"alp_orchestrate.partition: WARNING: {reserved_reason}; "
+                  f"storage offsets on '{device_name}' are checked against "
+                  f"sibling partitions only", file=sys.stderr)
+
+        entries_sorted = sorted(
+            by_device[device_name], key=lambda e: e.name)
+
+        # (base_bytes, size_aligned, reason) per entry INDEX.  Placement runs
+        # in TWO passes over the name-sorted list -- every `offset_kib:` pin
+        # first, then the bump allocator around them (#554).  In one pass a
+        # pin only ever became an obstacle for the siblings that happened to
+        # sort BEFORE it, so `pinned_low` (offset_kib: 0, the shape
+        # docs/board-config-features.md itself documents) collided with an
+        # already-auto-allocated `app_data` and was silently dropped from
+        # dts-partitions.dtsi -- a validate-clean layout the allocator could
+        # have satisfied.  Emission below still walks `entries_sorted`.
+        # Keyed by index rather than name because board.schema.json does not
+        # require `storage[].name` to be unique.
+        placement: dict[int, tuple[int, int, Optional[str]]] = {}
+
+        def _place(entry: StorageEntry) -> tuple[int, int, Optional[str]]:
+            size_bytes = entry.size_kib * 1024
+            size_aligned = ((size_bytes + _PAGE - 1) // _PAGE) * _PAGE
+
+            if entry.offset_kib is not None:
+                base_bytes = entry.offset_kib * 1024
+                if base_bytes % _PAGE != 0:
+                    return 0, size_aligned, (
+                        f"storage entry '{entry.name}' explicit "
+                        f"offset_kib={entry.offset_kib} is not page-"
+                        f"aligned (4 KiB)")
+            else:
+                # Allocate AROUND the reserved regions and the pins, not
+                # merely detect a collision with them (alp-sdk#1331 / #554):
+                # refusing here instead of skipping would break every
+                # project that names no addresses -- which is the common
+                # case -- rather than fix it.
+                base_bytes = _first_free(
+                    high_water_bytes, size_aligned, allocated, capacity_bytes)
+
+            top_bytes = base_bytes + size_aligned
+            if top_bytes > capacity_bytes:
+                free_note = ""
+                if entry.offset_kib is None and reserved_spans:
+                    free_note = (
+                        f"; the SoM's own regions ("
+                        f"{', '.join(sorted(reserved_names))}) already occupy "
+                        f"{sum(hi - lo for lo, hi, _ in reserved_spans) // 1024} "
+                        f"KiB of it")
+                return 0, size_aligned, (
+                    f"storage entry '{entry.name}' ({entry.size_kib} "
+                    f"KiB at offset {base_bytes // 1024} KiB) overruns "
+                    f"flash device '{device_name}' "
+                    f"(capacity {capacity_bytes // 1024} KiB){free_note}")
+
+            # Overlap check -- against sibling partitions AND the SoM's own
+            # regions seeded above.
+            overlap_with: Optional[str] = None
+            for lo, hi, peer_name in allocated:
+                if not (top_bytes <= lo or base_bytes >= hi):
+                    overlap_with = peer_name
+                    break
+            if overlap_with is not None:
+                where = (f"offset_kib={entry.offset_kib}"
+                         if entry.offset_kib is not None
+                         else f"auto-allocated offset {base_bytes // 1024} KiB")
+                if overlap_with in reserved_names:
+                    # `overlap_with` is one of the SoM's OWN regions (any
+                    # `memory_map:` region with an addressed `base:` is
+                    # seeded into `reserved_spans` regardless of its
+                    # `carveout:` value -- see `_reserved_spans()`) -- it
+                    # must NOT be named here as something to target
+                    # directly (#1484), and neither may any other reserved
+                    # region: they are exactly what this entry just failed
+                    # to overlap.  A name in `_known_flash_devices()` is
+                    # not enough either -- e.g. an `ospi_memories:` entry
+                    # with a TBD capacity (E1M-AEN801's `ospi1`) is known
+                    # but does not actually resolve, and a device that DOES
+                    # resolve may still be recommending an undefined DT
+                    # node (`_resolve_flash_device()` defaults `dt_label`
+                    # to the device name when unset -- see
+                    # `_has_real_dt_label()`).  Only recommend a device
+                    # that both resolves AND has a verified DT label.
+                    alt_devices = [
+                        d for d in _known_flash_devices(
+                            project.som_preset,
+                            project.effective_metadata_root(), aperture)
+                        if d != device_name
+                        and d not in reserved_names
+                        and _has_real_dt_label(
+                            d, project.som_preset,
+                            project.effective_metadata_root())
+                        and _resolve_flash_device(
+                            d, project.som_preset,
+                            project.effective_metadata_root(), aperture)[0]
+                        is not None]
+                    # Only lead with "pick an offset on <device>" when the
+                    # device actually has free room outside its reserved
+                    # spans.  Reserved spans come from ANY addressed
+                    # memory_map region, `carveout: false` or not; AEN's
+                    # `mram_main` is the fully-tiled case (0 KiB free,
+                    # tiled exactly by its `carveout: false` sub-regions),
+                    # not the only case this branch can fire for.
+                    reserved_bytes = sum(
+                        hi - lo for lo, hi, _ in reserved_spans)
+                    if reserved_bytes < capacity_bytes:
+                        remedy = (
+                            f"pick an offset on '{device_name}' outside "
+                            f"the SoM's declared regions")
+                        if alt_devices:
+                            remedy += (
+                                f", or use a different flash_device: "
+                                f"({', '.join(alt_devices)})")
+                    elif alt_devices:
+                        remedy = (
+                            f"'{device_name}' is fully tiled by the SoM's "
+                            f"own regions ({capacity_bytes // 1024} KiB, "
+                            f"no free room) -- use a different "
+                            f"flash_device: ({', '.join(alt_devices)})")
+                    else:
+                        # NOT "no other flash_device: resolves" -- on an
+                        # AEN SoM, ospi0 typically DOES resolve
+                        # (`_resolve_flash_device()`), it just has no
+                        # verified Devicetree label yet (see
+                        # `_has_real_dt_label()`). Naming it here would
+                        # recommend the very label #1484 exists to stop
+                        # fabricating, so the message must stay true for
+                        # BOTH cases (nothing resolves / something
+                        # resolves but is unverified) without naming a
+                        # device either way.
+                        remedy = (
+                            f"'{device_name}' is fully tiled by the SoM's "
+                            f"own regions ({capacity_bytes // 1024} KiB, "
+                            f"no free room) and no other flash_device: on "
+                            f"this SoM both resolves and has a verified "
+                            f"Devicetree label (alp-sdk#1556)")
+                    return 0, size_aligned, (
+                        f"storage entry '{entry.name}' {where} overlaps SoM "
+                        f"region '{overlap_with}' on device '{device_name}' "
+                        f"-- that region is not customer-writable. "
+                        f"{remedy}.")
+                return 0, size_aligned, (
+                    f"storage entry '{entry.name}' {where} overlaps "
+                    f"sibling partition '{overlap_with}' on device "
+                    f"'{device_name}'")
+
+            if not verified_dt_label:
+                # #1556: this entry cleared every other check (page
+                # alignment, capacity, sibling/reserved overlap) and was
+                # about to resolve `status: ok` -- but `dt_label` is the
+                # device NAME, defaulted because no SoM preset declares
+                # an explicit `dt_label:` override for '{device_name}',
+                # and that default has never been checked against the
+                # generated board tree. Refuse rather than emit a
+                # `partitions { }` overlay under a label the board `.dts`
+                # may not define (`grep -rn '{dt_label}' zephyr/` is the
+                # check to run). Checked HERE, not earlier, so an entry
+                # that would ALSO overlap a reserved/sibling region still
+                # gets that more actionable reason instead.
+                alt = _verified_alt_devices(
+                    device_name, project.som_preset,
+                    project.effective_metadata_root(), aperture)
+                remedy = (
+                    f"use a different flash_device: ({', '.join(alt)})"
+                    if alt else
+                    "no other flash_device: on this SoM both resolves "
+                    "and has a verified Devicetree label")
+                return 0, size_aligned, (
+                    f"storage entry '{entry.name}' would resolve on "
+                    f"flash device '{device_name}', but its Devicetree "
+                    f"label defaults to '{dt_label}' (the device name) "
+                    f"-- no SoM preset declares an explicit dt_label: "
+                    f"override for '{device_name}', so this default is "
+                    f"unverified against the generated board tree and "
+                    f"may decorate a `partitions {{ }}` child under a "
+                    f"node the board `.dts` never defines; {remedy}.")
+
+            allocated.append((base_bytes, top_bytes, entry.name))
+            return base_bytes, size_aligned, None
+
+        for index, entry in enumerate(entries_sorted):
+            if entry.offset_kib is not None:
+                placement[index] = _place(entry)
+        for index, entry in enumerate(entries_sorted):
+            if entry.offset_kib is None:
+                base_bytes, size_aligned, reason = _place(entry)
+                placement[index] = (base_bytes, size_aligned, reason)
+                if reason is None:
+                    # Only bump the allocator when we used it; explicit
+                    # offsets don't shift the high-water mark (they may be
+                    # below it deliberately, e.g. to reserve a low slot) --
+                    # `allocated` is what makes the allocator step over them.
+                    high_water_bytes = base_bytes + size_aligned
+
+        for index, entry in enumerate(entries_sorted):
+            base_bytes, size_aligned, reason = placement[index]
+            if reason is not None:
+                resolved.append(_blocked_partition(entry, reason))
+                continue
+            resolved.append(ResolvedPartition(
+                name=entry.name,
+                fs=entry.fs,
+                flash_device=device_name,
+                dt_label=dt_label,
+                base_kib=base_bytes // 1024,
+                size_kib=size_aligned // 1024,
+                mount=entry.mount,
+            ))
+
+    return resolved