s3dgraphy 1.6.0.dev9__tar.gz → 1.6.0.dev10__tar.gz

{s3dgraphy-1.6.0.dev9/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev9
+Version: 1.6.0.dev10
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev9 → s3dgraphy-1.6.0.dev10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev9"
+version = "1.6.0.dev10"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev9 → s3dgraphy-1.6.0.dev10}/src/s3dgraphy/JSON_config/em_qualia_types.json

@@ -1,10 +1,10 @@
 {
     "metadata": {
-      "version": "4.0",
-      "last_updated": "2026-05-23",
+      "version": "4.1",
+      "last_updated": "2026-06-18",
       "maintainers": ["Emanuel Demetrescu"],
       "license": "CC-BY-4.0",
-      "changelog": "v4.0: verified all v3.0 CIDOC-CRM mappings (correct). Expanded with: volume, area, circumference in dimensional; color, texture, finish, patina, hardness, porosity in material; damage_type, fragility, completeness in state; tool_marks, joining_technique in technical; bounding_box, footprint_area in spatial; duration, terminus_post_quem, terminus_ante_quem, relative_chronology in temporal; ceremonial_function, ritual_function, defensive_function, domestic_function, symbolic_function in telic; school, workshop, period_attribution in stylistic. NEW subcategories: iconographic + semantic under cultural_interpretive (iconographic_subject, narrative_content, iconographic_program, aesthetic_value, religious_significance, monumental_status, attribution). Added provenance_history, exhibition_history, publication_history under administrative; NEW ownership subcategory (current_custodian, ownership_chain). NEW CATEGORY epistemic — meta-qualia central to EM paradata model (confidence_level, certainty_level, uncertainty_factors, methodology_used, validation_method, source_quality, primary_contributor, review_status, last_modified)."
+      "changelog": "v4.1: expanded spatial elevation qualia for pyArchInit us_table quote (all E54_Dimension): elevation_relative, elevation_min_absolute, elevation_max_absolute, elevation_min_relative, elevation_max_relative, elevation_min_usm, elevation_max_usm (the generic 'elevation' = absolute MASL, used by quota_abs). Each pyArchInit quota column maps to its own qualia id so they don't collide on the single-PropertyNode-per-property_name rule. v4.0: verified all v3.0 CIDOC-CRM mappings (correct). Expanded with: volume, area, circumference in dimensional; color, texture, finish, patina, hardness, porosity in material; damage_type, fragility, completeness in state; tool_marks, joining_technique in technical; bounding_box, footprint_area in spatial; duration, terminus_post_quem, terminus_ante_quem, relative_chronology in temporal; ceremonial_function, ritual_function, defensive_function, domestic_function, symbolic_function in telic; school, workshop, period_attribution in stylistic. NEW subcategories: iconographic + semantic under cultural_interpretive (iconographic_subject, narrative_content, iconographic_program, aesthetic_value, religious_significance, monumental_status, attribution). Added provenance_history, exhibition_history, publication_history under administrative; NEW ownership subcategory (current_custodian, ownership_chain). NEW CATEGORY epistemic — meta-qualia central to EM paradata model (confidence_level, certainty_level, uncertainty_factors, methodology_used, validation_method, source_quality, primary_contributor, review_status, last_modified)."
     },
     "qualia_categories": [
       {
@@ -421,7 +421,7 @@
               {
                 "id": "elevation",
                 "name": "Elevation",
-                "description": "Height above sea level",
+                "description": "Height above sea level (absolute / MASL). pyArchInit us_table.quota_abs maps here — it is the absolute single-point elevation.",
                 "mappings": {
                   "getty_aat": "300447457",
                   "cidoc_crm": "E54_Dimension"
@@ -430,6 +430,90 @@
                 "units": ["m", "ft"],
                 "expected_extractors": ["gps_survey", "total_station_survey", "leveling"]
               },
+              {
+                "id": "elevation_relative",
+                "name": "Relative Elevation",
+                "description": "Elevation measured relative to a local site datum (not sea level). pyArchInit us_table.quota_relativa. Distinct from 'elevation' (absolute MASL).",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m", "cm"],
+                "expected_extractors": ["total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_min_absolute",
+                "name": "Minimum Absolute Elevation",
+                "description": "Lowest absolute elevation (height above sea level) of the element's vertical extent. pyArchInit us_table.quota_min_abs.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m"],
+                "expected_extractors": ["gps_survey", "total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_max_absolute",
+                "name": "Maximum Absolute Elevation",
+                "description": "Highest absolute elevation (height above sea level) of the element's vertical extent. pyArchInit us_table.quota_max_abs.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m"],
+                "expected_extractors": ["gps_survey", "total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_min_relative",
+                "name": "Minimum Relative Elevation",
+                "description": "Lowest elevation relative to the local site datum. pyArchInit us_table.quota_min_rel.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m", "cm"],
+                "expected_extractors": ["total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_max_relative",
+                "name": "Maximum Relative Elevation",
+                "description": "Highest elevation relative to the local site datum. pyArchInit us_table.quota_max_rel.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m", "cm"],
+                "expected_extractors": ["total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_min_usm",
+                "name": "Minimum Elevation (USM)",
+                "description": "Lowest recorded elevation of a masonry unit (USM). pyArchInit us_table.quota_min_usm.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m", "cm"],
+                "expected_extractors": ["total_station_survey", "leveling"]
+              },
+              {
+                "id": "elevation_max_usm",
+                "name": "Maximum Elevation (USM)",
+                "description": "Highest recorded elevation of a masonry unit (USM). pyArchInit us_table.quota_max_usm.",
+                "mappings": {
+                  "getty_aat": "300447457",
+                  "cidoc_crm": "E54_Dimension"
+                },
+                "data_type": "float",
+                "units": ["m", "cm"],
+                "expected_extractors": ["total_station_survey", "leveling"]
+              },
               {
                 "id": "arrangement",
                 "name": "Arrangement",

{s3dgraphy-1.6.0.dev9 → s3dgraphy-1.6.0.dev10}/src/s3dgraphy/JSON_config/s3Dgraphy_connections_datamodel.json

@@ -586,7 +586,7 @@
     "is_in_paradata_nodegroup": {
       "name": "is_in_paradata_nodegroup",
       "label": "Is in paradata nodegroup",
-      "description": "Indicates that a node is included into a paradata node group.",
+      "description": "Indicates that a node is included into a paradata node group. Standard members are the paradata-chain nodes (PropertyNode/DocumentNode/ExtractorNode/CombinerNode/ParadataNode); GeoPositionNode is additionally admitted so the per-graph georeferencing shift can be a member of the graph-scope ParadataNodeGroup (DP-65) — semantically valid only at graph scope.",
       "reverse": {
         "name": "contains_paradata_node",
         "label": "Contains paradata node"
@@ -598,7 +598,7 @@
         "extension_name": "CIDOC-S3D"
       },
       "allowed_connections": {
-        "source": ["PropertyNode", "DocumentNode", "ExtractorNode", "CombinerNode", "ParadataNode"],
+        "source": ["PropertyNode", "DocumentNode", "ExtractorNode", "CombinerNode", "ParadataNode", "GeoPositionNode"],
         "target": ["ParadataNodeGroup"]
       }
     },

{s3dgraphy-1.6.0.dev9 → s3dgraphy-1.6.0.dev10}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev9"
+__version__ = "1.6.0.dev10"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev9 → s3dgraphy-1.6.0.dev10}/src/s3dgraphy/importer/pyarchinit_importer.py

@@ -1,5 +1,6 @@
 # s3Dgraphy/importer/pyarchinit_importer.py
 
+import ast
 import re
 from typing import Dict, Any, List, Optional, Tuple
 from .base_importer import BaseImporter
@@ -271,8 +272,13 @@ class PyArchInitImporter(BaseImporter):
                 if self.overwrite and description:
                     existing_node.description = str(description)
                 
-                # Process properties for existing node
+                # Process properties for existing node, then enrich it with
+                # the row's spatial / temporal / documentary / authorship
+                # context. Enriching mode (EM_ADVANCED) attaches pyArchInit
+                # memberships onto the matched host EM node, not just flat
+                # properties.
                 self._process_pyarchinit_properties(row_dict, existing_node)
+                self._process_memberships(row_dict, existing_node)
                 return existing_node
                 
             elif is_enriching_existing:
@@ -304,10 +310,18 @@ class PyArchInitImporter(BaseImporter):
                 strat_type = id_col_config.get('node_type', 'US')
                 node_class = get_stratigraphic_node_class(strat_type)
                 
-                # Create new node with UUID
+                # Create new node. Identity: if a column is flagged
+                # ``is_passthrough`` (e.g. node_uuid / EMid, UUID v7), carry its
+                # value into node_id so export->edit->re-import is idempotent;
+                # otherwise mint a fresh UUID (legacy behaviour).
                 import uuid
+                pt_col = self._get_passthrough_column()
+                pt_val = row_dict.get(pt_col) if pt_col else None
+                node_id = (str(pt_val).strip()
+                           if pt_val is not None and str(pt_val).strip()
+                           else str(uuid.uuid4()))
                 new_node = node_class(
-                    node_id=str(uuid.uuid4()),
+                    node_id=node_id,
                     name=node_name,
                     description=str(description)
                 )
@@ -315,8 +329,11 @@ class PyArchInitImporter(BaseImporter):
                 self.graph.add_node(new_node)
                 # print(f"  → Node created with ID: {new_node.node_id}")
 
-                # Process properties for new node
+                # Process properties for new node, then attach all
+                # non-property memberships (location / epoch / document /
+                # author).
                 self._process_pyarchinit_properties(row_dict, new_node)
+                self._process_memberships(row_dict, new_node)
                 return new_node
 
         except KeyError as e:
@@ -377,6 +394,416 @@ class PyArchInitImporter(BaseImporter):
                     # Valore vuoto o mancante - non creare proprietà
                     # print(f"    ⊘ Skipped property: {col_config['property_name']} (empty value)")
 
+    def _get_passthrough_column(self) -> Optional[str]:
+        """Column whose value becomes the node_id (identity passthrough).
+
+        A mapping column flagged ``"is_passthrough": true`` carries a stable
+        external id (pyArchInit ``node_uuid`` == s3dgraphy ``EMid``, UUID v7)
+        straight into ``node_id`` so export -> edit -> re-import is idempotent
+        instead of minting a fresh uuid4 each run.
+        """
+        for col_name, col_config in self.mapping.get('column_mappings', {}).items():
+            if col_config.get('is_passthrough', False):
+                return col_name
+        return None
+
+    def _process_location_memberships(self, row_dict: Dict[str, Any], strat_node: Node):
+        """Columns flagged ``node_type == 'LocationNodeGroup'`` become ONE shared
+        :class:`LocationNodeGroup` each (deduped by kind+value across rows), linked
+        from ``strat_node`` via an ``is_in_location`` edge.
+
+        A sector/area is an identitary place (CIDOC E53 Place), not a per-row
+        string property: N US in 'Sector 1' point at a single LocationNodeGroup,
+        not N copies. See mappings/pyarchinit/pyarchinit_us_mapping.json.
+        """
+        from ..nodes.group_node import LocationNodeGroup
+
+        valid_kinds = getattr(
+            LocationNodeGroup, "VALID_KINDS", ("toponym", "study", "functional"))
+        for col_name, col_config in self.mapping.get('column_mappings', {}).items():
+            if col_config.get('node_type') != 'LocationNodeGroup':
+                continue
+            value = row_dict.get(col_name, '')
+            if not (value and str(value).strip()):
+                continue
+            kind = col_config.get('location_kind', 'study')
+            if kind not in valid_kinds:
+                self.warnings.append(
+                    f"location_kind '{kind}' for column '{col_name}' not in "
+                    f"{valid_kinds}; falling back to 'study'.")
+                kind = 'study'
+            loc_name = str(value).strip()
+            # Dedup across rows, but keep distinct location dimensions: area "1"
+            # and settore "1" are different places that merely share a label, so
+            # the source column is part of the identity (not just kind+value).
+            loc_id = f"loc::{col_name}::{kind}::{loc_name}"
+            if self.graph.find_node_by_id(loc_id) is None:
+                self.graph.add_node(LocationNodeGroup(
+                    node_id=loc_id, name=loc_name, kind=kind,
+                    description=col_config.get('description', '')))
+            edge_id = f"{strat_node.node_id}_is_in_location_{loc_id}"
+            if not self.graph.find_edge_by_id(edge_id):
+                self.graph.add_edge(
+                    edge_id=edge_id, edge_source=strat_node.node_id,
+                    edge_target=loc_id, edge_type="is_in_location")
+
+    # ------------------------------------------------------------------
+    # Tier-2 memberships (epoch / document / author) — mirror the
+    # location handler above. Each is independent, deduplicates its shared
+    # targets across rows, and links them from the stratigraphic node with
+    # the appropriate semantic edge. See _tier2_pending_handlers in
+    # mappings/pyarchinit/pyarchinit_us_mapping.json and issue #26.
+    # ------------------------------------------------------------------
+
+    # Affirmative tokens for the pyArchInit 'documentazione' checklist
+    # (['Fotografie', 'Si'] -> photographic documentation is present).
+    # Italian 'Si'/'Sì' plus a few common variants so the same handler
+    # survives a localized DB.
+    _AFFIRMATIVE = {"si", "sì", "yes", "y", "true", "1", "x", "ja", "oui"}
+
+    @staticmethod
+    def _slug(text: Any) -> str:
+        """Id-safe slug: lowercase alphanumeric runs joined by '_'.
+
+        Used to fold a person name or documentation label into a stable,
+        readable node-id fragment (``Luca Mandolesi`` -> ``luca_mandolesi``).
+        """
+        return re.sub(r'[^a-z0-9]+', '_', str(text).strip().lower()).strip('_')
+
+    @staticmethod
+    def _norm_code(value: Any) -> str:
+        """Canonicalize a period/phase code so the values SQLite returns
+        from the periodizzazione table compare equal to those in us_table.
+
+        pyArchInit's ``fase`` column has NUMERIC affinity, so SQLite hands
+        back ``int 2`` for ``'2'`` and ``float 2.1`` for the sub-phase
+        ``'2.1'``, while us_table (TEXT affinity) keeps ``'2'`` / ``'2.1'``
+        as strings. Both sides are folded to one canonical token:
+
+          - ``2`` / ``'2'`` / ``2.0`` / ``'02'``  -> ``'2'``   (integer-valued)
+          - ``2.1`` / ``'2.1'`` / ``'2.10'``       -> ``'2.1'`` (genuine sub-phase)
+          - ``'A'`` / ``'II'``                      -> ``'A'`` / ``'II'`` (non-numeric)
+
+        Integer-valued forms collapse together, but a real sub-phase must
+        NOT collapse onto its integer period: ``'2.1'`` and ``'2'`` are
+        different phases of period 2 with different time spans.
+        """
+        if value is None:
+            return ""
+        s = str(value).strip()
+        if not s:
+            return ""
+        try:
+            f = float(s)
+        except (TypeError, ValueError):
+            return s  # non-numeric code (e.g. 'A') — keep as-is
+        # repr() gives the shortest round-trip float text, so the float
+        # SQLite returns and the string us_table stores map identically
+        # ('2.10' and 2.1 both -> '2.1').
+        return str(int(f)) if f.is_integer() else repr(f)
+
+    @staticmethod
+    def _coerce_time(value: Any) -> Optional[int]:
+        """Coerce a chronology value to an integer year, or None.
+
+        Negative values (BC years) are preserved; empty / non-numeric
+        values return None so the caller can skip an EpochNode that lacks a
+        usable time span.
+        """
+        if value is None:
+            return None
+        s = str(value).strip()
+        if not s:
+            return None
+        try:
+            return int(float(s))
+        except (ValueError, TypeError):
+            return None
+
+    def _process_memberships(self, row_dict: Dict[str, Any], strat_node: Node):
+        """Attach every non-property membership to ``strat_node``.
+
+        Centralizes the wiring so the new-node and the enriching
+        (node-found) branches of :meth:`process_row` stay in lock-step:
+        a pyArchInit row contributes its spatial, temporal, documentary
+        and authorship context in both modes, not only when minting a new
+        node.
+        """
+        self._process_location_memberships(row_dict, strat_node)
+        self._process_epoch_memberships(row_dict, strat_node)
+        self._process_document_memberships(row_dict, strat_node)
+        self._process_author_memberships(row_dict, strat_node)
+
+    def _get_periodization_index(
+            self, join_cfg: Dict[str, Any]) -> Dict[Tuple[str, str, str],
+                                                     Tuple[Any, Any, Any]]:
+        """Lazy, per-table cache mapping ``(site, period, phase)`` to
+        ``(start_time, end_time, name)`` read from the pyArchInit
+        periodizzazione table.
+
+        EpochNode requires a concrete start/end span, but us_table only
+        carries period/phase *codes*. This index resolves those codes with
+        a single cheap full scan of the periodizzazione table (cached on
+        the instance), so :meth:`_process_epoch_memberships` does one dict
+        lookup per row instead of N SQL joins.
+
+        A missing / unreadable table degrades gracefully to an empty index
+        (epochs are then skipped, each with a warning) rather than aborting
+        the whole import. Identifier names are whitelisted before
+        interpolation, consistent with the rest of this importer.
+        """
+        table = join_cfg.get('table')
+        if not table:
+            return {}
+        if not hasattr(self, '_period_index_cache'):
+            self._period_index_cache: Dict[str, Dict] = {}
+        if table in self._period_index_cache:
+            return self._period_index_cache[table]
+
+        index: Dict[Tuple[str, str, str], Tuple[Any, Any, Any]] = {}
+        site_col = join_cfg.get('site_column', 'sito')
+        per_col = join_cfg.get('period_column', 'periodo')
+        pha_col = join_cfg.get('phase_column', 'fase')
+        start_col = join_cfg.get('start_column', 'cron_iniziale')
+        end_col = join_cfg.get('end_column', 'cron_finale')
+        name_col = join_cfg.get('name_column', 'descrizione')
+
+        for ident in (table, site_col, per_col, pha_col,
+                      start_col, end_col, name_col):
+            if not self._is_safe_identifier(ident):
+                self.warnings.append(
+                    f"Unsafe periodization identifier {ident!r}; "
+                    f"epoch memberships skipped.")
+                self._period_index_cache[table] = index
+                return index
+
+        conn = None
+        try:
+            conn = self._connect()
+            cursor = conn.cursor()
+            cursor.execute(
+                f"SELECT {site_col}, {per_col}, {pha_col}, "
+                f"{start_col}, {end_col}, {name_col} FROM {table}")
+            for site, period, phase, start, end, name in cursor.fetchall():
+                key = (str(site).strip() if site is not None else "",
+                       self._norm_code(period), self._norm_code(phase))
+                index[key] = (start, end, name)
+        except Exception as e:  # missing table, bad schema, etc.
+            self.warnings.append(
+                f"Could not read periodization table '{table}': {e}. "
+                f"Epoch memberships skipped.")
+        finally:
+            if conn is not None:
+                conn.close()
+
+        self._period_index_cache[table] = index
+        return index
+
+    def _process_epoch_memberships(self, row_dict: Dict[str, Any],
+                                   strat_node: Node):
+        """Resolve the row's period/phase codes into shared
+        :class:`EpochNode`\\ s and link them from ``strat_node``.
+
+        Driven by the mapping's top-level ``epoch_mappings`` list. Each
+        entry names a ``period_column`` / ``phase_column`` pair, the
+        ``edge_type`` to use (``has_first_epoch`` for the initial period,
+        ``survive_in_epoch`` for the final one), and a ``join`` block
+        describing the periodizzazione lookup. An epoch is shared across
+        all rows that resolve to the same ``(site, period, phase)`` —
+        exactly as a sector is shared in
+        :meth:`_process_location_memberships`.
+        """
+        epoch_mappings = self.mapping.get('epoch_mappings', [])
+        if not epoch_mappings:
+            return
+        from ..nodes.epoch_node import EpochNode
+
+        for em in epoch_mappings:
+            per_col = em.get('period_column')
+            pha_col = em.get('phase_column')
+            join_cfg = em.get('join', {})
+            if not (per_col and pha_col and join_cfg):
+                continue
+            edge_type = em.get('edge_type', 'has_first_epoch')
+            site_col = em.get('site_column', 'sito')
+
+            per_val = row_dict.get(per_col)
+            if not (per_val and str(per_val).strip()):
+                continue  # no period code on this row -> no epoch
+            site_val = row_dict.get(site_col, '')
+            site_n = str(site_val).strip() if site_val is not None else ""
+            per_n = self._norm_code(per_val)
+            pha_n = self._norm_code(row_dict.get(pha_col))
+
+            span = self._get_periodization_index(join_cfg).get(
+                (site_n, per_n, pha_n))
+            if span is None:
+                self.warnings.append(
+                    f"No periodization row for site={site_n!r} "
+                    f"period={per_n!r} phase={pha_n!r} "
+                    f"(US '{strat_node.name}'); skipping {edge_type} edge.")
+                continue
+            start_raw, end_raw, name_raw = span
+            start = self._coerce_time(start_raw)
+            end = self._coerce_time(end_raw)
+            if start is None or end is None:
+                self.warnings.append(
+                    f"Periodization row site={site_n!r} period={per_n!r} "
+                    f"phase={pha_n!r} lacks a start/end time; EpochNode "
+                    f"requires both — skipping (US '{strat_node.name}').")
+                continue
+
+            epoch_name = (str(name_raw).strip() if name_raw
+                          else f"P{per_n}F{pha_n}")
+            epoch_id = f"epoch::{site_n}::{per_n}::{pha_n}"
+            if self.graph.find_node_by_id(epoch_id) is None:
+                self.graph.add_node(EpochNode(
+                    node_id=epoch_id, name=epoch_name,
+                    start_time=start, end_time=end))
+            edge_id = f"{strat_node.node_id}_{edge_type}_{epoch_id}"
+            if not self.graph.find_edge_by_id(edge_id):
+                self.graph.add_edge(
+                    edge_id=edge_id, edge_source=strat_node.node_id,
+                    edge_target=epoch_id, edge_type=edge_type)
+
+    def _process_author_memberships(self, row_dict: Dict[str, Any],
+                                    strat_node: Node):
+        """Columns flagged ``node_type == 'AuthorNode'`` become ONE shared
+        :class:`AuthorNode` each (deduped by person name across rows),
+        linked from ``strat_node`` via a ``has_author`` edge.
+
+        ``schedatore`` / ``direttore_us`` / ``responsabile_us`` all name a
+        *person*; the same person fills different roles on different US, so
+        identity is the person (shared node), not the (US, role) pair. The
+        ``has_author`` edge is deduped per (US, person): if one person is
+        both compiler and director of the same US, the two columns collapse
+        to a single edge. Role is recorded only as provenance in the
+        author's description on first creation (a richer role-on-edge model
+        is a future enhancement).
+        """
+        from ..nodes.author_node import AuthorNode
+
+        for col_name, col_config in self.mapping.get(
+                'column_mappings', {}).items():
+            if col_config.get('node_type') != 'AuthorNode':
+                continue
+            value = row_dict.get(col_name, '')
+            if not (value and str(value).strip()):
+                continue
+            person = str(value).strip()
+            author_id = f"author::{self._slug(person)}"
+            if self.graph.find_node_by_id(author_id) is None:
+                role = col_config.get('author_role')
+                desc = (f"pyArchInit {role}: {person}" if role
+                        else f"pyArchInit author: {person}")
+                self.graph.add_node(AuthorNode(
+                    node_id=author_id, name=person, description=desc))
+            edge_id = f"{strat_node.node_id}_has_author_{author_id}"
+            if not self.graph.find_edge_by_id(edge_id):
+                self.graph.add_edge(
+                    edge_id=edge_id, edge_source=strat_node.node_id,
+                    edge_target=author_id, edge_type="has_author")
+
+    def _process_document_memberships(self, row_dict: Dict[str, Any],
+                                      strat_node: Node):
+        """Columns flagged ``node_type == 'DocumentNode'`` become
+        :class:`DocumentNode`\\ s linked via ``has_documentation`` (CRMdig).
+        The ``doc_format`` key selects how the column value is interpreted:
+
+        - ``pyarchinit_checklist`` — value is a Python-literal list of
+          ``[label, flag]`` pairs (the pyArchInit ``documentazione``
+          field). Each pair whose flag is affirmative (``'Si'``) yields one
+          *per-US* DocumentNode named after the documentation type. These
+          are presence assertions ("photographic documentation exists for
+          this US"), so identity is (US, type) — node-scoped, not shared.
+        - ``path`` — value is a single file reference (``doc_usv``). The
+          file is a real, shareable document, so it is deduped by path
+          across rows and carries the path as its ``url``.
+        """
+        for col_name, col_config in self.mapping.get(
+                'column_mappings', {}).items():
+            if col_config.get('node_type') != 'DocumentNode':
+                continue
+            value = row_dict.get(col_name, '')
+            if not (value and str(value).strip()):
+                continue
+            doc_format = col_config.get('doc_format', 'path')
+            if doc_format == 'pyarchinit_checklist':
+                self._add_checklist_documents(value, col_config, strat_node)
+            elif doc_format == 'path':
+                self._add_path_document(value, col_config, strat_node)
+            else:
+                self.warnings.append(
+                    f"Unknown doc_format '{doc_format}' for column "
+                    f"'{col_name}'; skipping.")
+
+    def _link_document(self, doc_node: Node, strat_node: Node):
+        """Add ``doc_node`` if new and link it from ``strat_node`` with a
+        deduplicated ``has_documentation`` edge."""
+        if self.graph.find_node_by_id(doc_node.node_id) is None:
+            self.graph.add_node(doc_node)
+        edge_id = f"{strat_node.node_id}_has_documentation_{doc_node.node_id}"
+        if not self.graph.find_edge_by_id(edge_id):
+            self.graph.add_edge(
+                edge_id=edge_id, edge_source=strat_node.node_id,
+                edge_target=doc_node.node_id, edge_type="has_documentation")
+
+    def _add_checklist_documents(self, value: Any,
+                                 col_config: Dict[str, Any],
+                                 strat_node: Node):
+        """Parse a pyArchInit ``documentazione`` checklist and create one
+        per-US DocumentNode per affirmative entry."""
+        from ..nodes.document_node import (
+            DocumentNode, DOCUMENT_CONTENT_NATURES)
+        try:
+            entries = ast.literal_eval(str(value))
+        except (ValueError, SyntaxError):
+            self.warnings.append(
+                f"Could not parse documentation checklist {value!r} "
+                f"(US '{strat_node.name}'); skipping.")
+            return
+        if not isinstance(entries, (list, tuple)):
+            return
+
+        content_nature = col_config.get('doc_content_nature_default')
+        if (content_nature is not None
+                and content_nature not in DOCUMENT_CONTENT_NATURES):
+            self.warnings.append(
+                f"doc_content_nature_default '{content_nature}' not in "
+                f"{DOCUMENT_CONTENT_NATURES}; ignoring.")
+            content_nature = None
+
+        for entry in entries:
+            if not (isinstance(entry, (list, tuple)) and len(entry) >= 2):
+                continue
+            label = str(entry[0]).strip()
+            flag = str(entry[1]).strip().lower()
+            if not label or flag not in self._AFFIRMATIVE:
+                continue
+            doc_id = f"{strat_node.node_id}_doc_{self._slug(label)}"
+            self._link_document(
+                DocumentNode(
+                    node_id=doc_id, name=label,
+                    description=f"pyArchInit documentation present: {label}",
+                    content_nature=content_nature),
+                strat_node)
+
+    def _add_path_document(self, value: Any, col_config: Dict[str, Any],
+                           strat_node: Node):
+        """Create / reuse a shared DocumentNode for a single file reference
+        (deduped by path; basename used as the human label)."""
+        from ..nodes.document_node import DocumentNode
+        path = str(value).strip()
+        # pyArchInit stores Windows-style 'DosCo\\file.ext'; split on either
+        # separator so the label is the bare filename on any platform.
+        base = re.split(r'[\\/]', path)[-1] or path
+        self._link_document(
+            DocumentNode(
+                node_id=f"doc::path::{path}", name=base,
+                description=f"pyArchInit document reference: {path}",
+                url=path),
+            strat_node)
+
     def _get_description_column(self) -> Optional[str]:
         """Get description column from mapping"""
         for col_name, col_config in self.mapping.get('column_mappings', {}).items():