s3dgraphy 1.6.0.dev44__tar.gz → 1.6.0.dev46__tar.gz

{s3dgraphy-1.6.0.dev44/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev44
+Version: 1.6.0.dev46
 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.dev44 → s3dgraphy-1.6.0.dev46}/pyproject.toml

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

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/JSON_config/s3Dgraphy_node_datamodel.json

@@ -1,6 +1,6 @@
 {
-  "s3Dgraphy_data_model_version": "1.6.29",
-  "description": "v1.6.29 (giro dell'11 ottobre, decided by E.D. 2026-10-11): the code of a graph is the code of its STUDY — StudyNode.code replaces the graph-self node's retired «EM-ID» (GraphNode.data.em_id, never a field of this datamodel): a file that has one keeps it and s3dgraphy.hdto.migrate_em_id carries it to the study's code only when the study exists and has none. A saggio is a study AND a place: its LocationNodeGroup (kind study) is in the site (is_in_location), the study took place at it. Descriptions only, no field added. v1.6.28 (MICRO lo studio usabile, decided by E.D. 2026-10-10: the stratigraphic trench is a STUDY, the site is TOPOGRAPHY, HC1 is heritage only where recognised): StudyNode gains `study_kind` (stratigraphic_excavation | survey | documentation | other) — a stratigraphic_excavation is ALSO a crmarchaeo:A9_Archaeological_Excavation, declared per value in the field (`subclass_of_by_value`, the same subclass_of form the classes use) and emitted by the RDF exporter as a second rdf:type — and `code` (the short name of the study, e.g. GT16: what the source gives, or what the user writes; never derived; the label prefix reads it). HC9 Study is aligned to crm:E65_Creation (was crm:E7_Activity; E65 ⊑ E7), HC1 Heritage Entity to crm:E70_Thing (was crm:E1_CRM_Entity), as the official HDT-O RDFS says (HDT_v2.0.1.rdf, ECHOES D7.1). The study reaches its place with study_took_place_at (crm:P7_took_place_at, connections 1.6.39). v1.6.27 (MICRO le entità spaziotemporali, decided by E.D. 2026-10-10): DocumentNode and AuthorNode (with AuthorAINode) are SPATIOTEMPORAL ENTITIES like the stratigraphic units — the top-level block `spatiotemporal_entities` names the three classes and what they share: a start and an end (absolute_time_start / absolute_time_end, read with the label of their owner: a person is born and dies, a model is released and retired), the lane of the matrix where they begin (has_first_epoch) and the ones they last through (survive_in_epoch), their place in the sequence (is_after, has_same_time), an activity. The edges are widened in connections 1.6.38; the chronology dates the three with the same rules (Graph.CHRONOLOGY_TYPES). AuthorNode and DocumentNode gain a `spatiotemporal` element saying how their time reads; no field of theirs changes. v1.6.26 (H4, decided by E.D. 5 Oct 2026, «Heriverse legge l'em.json e sceglie la versione»): ResourceNode.use admits two more uses, heriverse and aton — a version made FOR a viewer, the package on disk that Heriverse or another ATON app opens offline (EM Tools makes it with «Prepare for a use…», as is: no optimisation of its own); a viewer asks heriverse, aton, web, realtime in that order (s3dgraphy.resources.versions.choose_version). v1.6.25 (D1, MICRO un solo vocabolario, decided by E.D. 4 Oct 2026): GeoPositionNode.rotation_reference = 'grid' (D2: the rotation is measured from the GRID north of the CRS). ResourceNode.lod_level (em:lodLevel, computed from the chain, written only on export and checked at load), ResourceNode.use (em:use, a list of analysis | realtime | web | mobile_ar | print | render | preview) and seven measures of a version (em:trisPerM2, em:texelDensityDD, em:textureCount, em:textureSidePx, em:uvRatio, em:reductionFromLod0, em:geometricErrorM). v1.6.24 (dev30, decided by E.D. 2026-10-02 on the dev29 report): DTCAcquisitionNode.retrieved_from — where a retrieved object came from, a DOI or a URL (em:retrievedFrom, D1; optional, validate warns «download without origin»). ResourceNode.members_digest names em:membersDigest, the digest of a file_set with a predicate of its own beside em:checksum + em:digestCovers (D4; not a second field). ResourceNode.packaging carries its vocabulary with values and labels, translated in datamodel_translations.json (packagings; A3). ResourceNode.content_digest also holds the digest of the data of a master inside another file — a Metashape model's mesh.ply — compared, never verified by downloading (D7). GCPSetNode gains data.control (ground_control_points | camera_positions) and data.accuracy_m: a chunk referenced only by its cameras' GPS is absolute with the control said for what it is, and validate warns «georeferenced only by camera GPS» (D7). Node.properties.lang states the one explicit exception to the AI marker: a recognised language confirmed by a person is data.lang only (U5). CRMem 1.6.14. v1.6.23 (dev29, 2026-10-02, measured on San Pietro): seven properties that the round trip em.json → TTL → em.json lost now leave and come back — ResourceNode packaging / tier / digest_covers / content_digest (em:packaging, em:tier, em:digestCovers, em:contentDigest) and the declared fields of a DTC step, technique / parameters / software (em:technique, em:parameters, em:software, the last two as rdf:JSON). digest_covers admits members (a file_set). The blend:// locator stays out of RDF on purpose: it is a private path. v1.6.22 (dev28, 2026-11-01, decided by E.D. 2026-10-01 on the dev27 report): the access mode of a signature (created_auth / modified_auth / validated_auth) admits a third mode, 'declared' — an iD typed in a tool's preferences and checked by nobody (EMStudio's declared identity, EM Tools' local identity), with no attested_by; through a relay the mode is the relay's, read from the token (crdt.stamp_auth), not the client's declaration. The language a node is born in travels in the add_node op (crdt.make_op requires it of the producer, 'und' when unknown); the study's language is read only for old ops, said and counted. CRMem 1.6.12. v1.6.21 (dev27, 2026-10-31, decided by E.D. 2026-10-01, «il testo, la risorsa e la selezione» and «l'accesso sul campo»): ResourceNode.properties gains lang — on a resource the language(s) of its CONTENT, one tag or a sorted list, leaving as dcterms:language and outside the cascade of the texts — addresses (several addresses of ONE resource, same digest: em:hasAddress with em:locator, em:residency, em:checkedAt, em:reachable) and checksum_at (a dated digest, em:checksumAt). Node.properties gains created_auth / modified_auth / validated_auth: how the hand of a signature had entered, {mode: orcid | node_password, attested_by} (em:createdVia / em:modifiedVia / em:validatedVia, em:authMode, em:attestedBy). data.lang is written at birth (s3dgraphy.language.stamp_birth_language), also when equal to the study's. v1.6.20 (MICRO le traduzioni, 2026-10-29, decided by E.D. 2026-10-01, «Le traduzioni»): NEW TranslationNode (TRANSL, crm:E33_Linguistic_Object) — ONE translation of one text field of one node. The original stays a string in its field (data.lang on the node, else the study's), never overwritten; each translation is a node reached by has_translation (crm:P73_has_translation, connections 1.6.34) with data.lang (arrival), data.from_lang (departure, written because the original can change), data.field (CRDT vocabulary: description | data.<key>; a PropertyNode's value is data.value; never name), data.text, data.method (manual | ai | edition), data.source_digest (sha256 of the original translated: a different digest = «da riallineare») and data.review_requested («da rivedere»). Who: has_author; AI: data.ai_assisted, unverified until validated_by; an edition: extracted_from → the DocumentNode. RDF (em.ttl 1.6.10): Node.properties.lang names em:originalLanguage — the node's own data.lang leaves as that literal whenever it is declared, equal to the study's too, so a reader tells the original literal from the translations that share its predicate and the round trip gives data.lang back exactly where it was (the D.1 limit of 1.6.19 is closed); the TranslationNode's fields name em:sourceLanguage, em:translatedField, em:translationMethod, em:sourceDigest, em:reviewRequested. v1.6.19 (MICRO la lingua dei dati, 2026-10-27, decided by E.D. 2026-09-28): Node.properties.description becomes an object {cidoc: P3_has_note, natural_language: true, note} — the MARKER that says the description is text in a natural language and leaves in RDF with its language tag; declared once on the base class and inherited by every node type. name is NOT marked: names are invariant identities. No field added, no node element, no graph change: the em.json is the same; only the RDF literal gains its tag. v1.6.18 (MICRO i termini di em.ttl nel datamodel, 2026-10-26, decided by E.D. 2026-10-01 — the datamodel JSON is the truth, so every em: term of em.ttl is cited by a datamodel or is a written exception): the em: predicates the RDF exporter already writes are now NAMED in properties, as plain-string mapping notes (no field added, no node element, no graph change). Node (inherited by every class): the last-hand stamps created_by em:createdBy / modified_by em:lastEditedBy / modified_at em:modifiedAt (created_at prov:generatedAtTime), the tombstone removed.ts em:removedAt / removed.by em:removedBy, the AI marker ai_assisted.by em:aiAssistedBy / .model em:aiModel / .prompt_ref em:aiPromptRef / .fields em:aiAssistedField and the verification validated_by em:validatedBy / validated_at em:validatedAt (properties_note). ResourceNode: checksum em:checksum, scope em:resourceScope, residency em:residency. SemanticShapeNode: convexshapes em:convexShape, spheres em:sphere. AnnotationRegionNode: crs em:crs, coords.frame_iri em:LocalSceneFrame. AuthorNode and AuthorAINode: verified em:orcidVerified (AuthorAINode also names orcid P48, which the exporter writes for both). LocationNodeGroup.propagation.mapping: uri em:propagation. THREE ENTRIES CORRECTED TO WHAT THE CODE WRITES (measured in rdf_exporter.py): PropertyNode.property_type was P2_has_type, is em:hasQualiaType; AuthorAINode model / prompt_reference were P3_has_note, are em:modelIdentifier / em:promptReference; ResourceFileNode.checksum was P1_is_identified_by, is em:checksum; and LocationNodeGroup.propagation said 'not serialized to triplestore' while the exporter has written the non-default value as em:propagation since c1a702c (2026-08-12). v1.6.17 (MICRO la risorsa e i suoi file, 2026-10-18, decided by E.D. 2026-09-30): NEW ResourceFileNode (FILE, crmdig:D1_Digital_Object) — the ResourceNode is the set, the ResourceFileNode is each file, reached by has_file (connections 1.6.30) with role and relative path on the edge. With one file the node is implicit (url and checksum stay on the ResourceNode, as today). ResourceNode.PACKAGINGS += file_set (a few files that call each other: obj → mtl → textures, gltf → bin, shp and companions) and datablock (one object inside a file, a blend:// locator). Representations of the same thing are sibling ResourceNodes tied by dtc_derived_from and chosen by tier and packaging. ADDITIVE: nothing narrowed, no graph changes. v1.6.16 (MICRO le annotazioni ATON sull'asset, 2026-10-15, decided by E.D.): AnnotationRegionNode gains geometry_kind 'volume' — an annotation that encloses a part of a 3D model (ATON / Hathor convex hulls and spheres) and is the proxy of no unit. The region carries no vertices: it reaches a SemanticShapeNode (convexshapes, spheres) with has_semantic_shape and the model with is_on_resource. geometry.aton.import_aton_scene makes one for every semantic id no EM node is named after (a stratigraphic unit only with an explicit create_type); api.promote_region_to_proxy turns it into the proxy of a unit later. RDF: P2_has_type 'volume', no selector, no WKT; the shape travels as itself. Additive. v1.6.15 (MICRO la geometria per origine, 2026-10-11, decided by E.D. 2026-09-30): AnnotationRegionNode's point / line / polyline keep their vertices IN THE NODE, data.coords [[x, y, z], ...] (scene-local, glTF Y-up, metres) with crs and, for a line or a polyline, length and unit — no .glb and no SemanticShape for a reading. New block coords (inline_max_vertices 500: above it the vertices go to a .glb resource via has_linked_resource, with a warning). RDF: geo:hasGeometry -> <region>/geometry geo:asWKT (POINT Z / LINESTRING Z, GeoSPARQL). The readings/<id>.glb of 2026-10-06 are migrated on opening. v1.6.14 (MICRO la cattura in RDF, 2026-09-30): DTCAcquisitionNode.mapping.by_kind — its D12 is the class of a retrieval; a capture takes the class its kind declares in em_visual_rules 1.6.24 (D2 / D11 / E65). Mapping text only, no field changed. v1.6.13 (MICRO i generi delle US, 2026-09-30, decided by E.D. the same day): stratigraphic_kind gains 'coating' — the USR (rivestimento) and its English translation USS (surface): plaster, floors, revetments — with `labels`, `codes` and `default_code` per kind; new node element `source_code` (data.source_code) keeps the code a unit came in with when it is not its kind's default, so the way back to pyArchInit gives the same code. A legacy node_type 'USR' / 'USS' opens as US + coating. v1.6.12 (MICRO la cattura nel DTC e le murature, 2026-09-30): StratigraphicUnit (US) gains the node element `stratigraphic_kind` (em.json data.stratigraphic_kind; today one value, 'masonry'): a USM is a US + masonry, and the legacy node_type 'USM' — never a type of this datamodel — opens as that. DTCAcquisitionNode's description names the two families of the acquisition axis (em_visual_rules 1.6.22: capture / retrieval). v1.6.11 (MICRO la misura in RDF, 2026-10-07): AnnotationRegionNode.properties says how the fields left unprojected by 1.6.10 now travel — the quote of a passage as oa:TextQuoteSelector, the length of a line/polyline as crm:E54_Dimension (P90 value, P91 QUDT unit, em:crs), vertex_count as em:vertexCount. CRMem (em.ttl) 1.6.5 -> 1.6.6. Mapping text only, no field changed. v1.6.10 (MICRO la geometria della lettura, 2026-10-06, decided by E.D. on 2026-09-29): AnnotationRegionNode becomes the node of THE PLACE A READING LOOKED AT, with a new field geometry_kind: region2d (default, every older region), passage (start, end, text), point, line, polyline. The three 3D kinds keep their coordinates in a .glb (glTF POINTS / LINES / LINE_STRIP) linked with has_semantic_shape exactly like a proxy's payload, never in the em.json; the node keeps vertex_count and, for line/polyline, length + unit + crs (api.measure). See the entry's geometry_kinds and glb_payload. Paired with connections 1.6.27 (is_on_resource.target += the representation models). Additive: a region without geometry_kind reads as region2d. v1.6.9 (MICRO la definizione dell'unita', 2026-10-20, decided by E.D. on 2026-09-27): StratigraphicNode.properties gains `definition`, the DEFINIZIONE of the US sheet, as an element of the node like name and description and NOT a qualia. Value = a controlled-vocabulary concept {concept, label}; em.json carries it as data.definition (CRDT field 'data.definition', no change to the frozen em.json v1 node shape); inherited by every stratigraphic subtype. The RDF projection is declared in the entry itself (`rdf`): crm:P2_has_type -> crm:E55_Type when a concept URI is present, nothing when only a label is (`label_only: null`). CRMem 1.6.4 -> 1.6.5 for the companion em:hasDefinition (subproperty of crm:P2_has_type, declared, not emitted by default). Additive only. v1.6.7 (CRMem WIRING, 2026-09-24): rimosso il campo legacy `cidoc_s3d` da tutte le mapping. Non era letto da nessuna parte del codice e portava quattro nomi di classe senza namespace, mai dichiarati e mai emessi: EpochNode = StratigraphicTimeframe; ActivityNodeGroup = StratigraphicActivity; ParadataNodeGroup = ParadataCollection; ResourceNode = ExternalResourceReference. Il prefisso CIDOC-S3D non esiste piu' in nessuno dei due datamodel. v1.6.6 (CIDOC REPAIR, 2026-09-21): classes that pointed at IRIs nobody declares. Checked by parsing the official releases, not from memory. crm:E78_Collection is gone from CIDOC CRM 7.1.3 — renamed E78_Curated_Holding — and E.D. decided NOT to follow the rename, because E78_Curated_Holding is a subclass of E24 Physical Human-Made Thing and a group of nodes is not a physical thing. The three classes that carried it therefore split, each to the class it actually is: GroupNode and RepresentationModelNodeGroup to crm:E73_Information_Object (a conceptual set, and an E90 Symbolic Object, which is what the P106i membership edge needs at both ends), ParadataNodeGroup to crm:E89_Propositional_Object — which is what a gathered body of reasoning IS and what the range of crm:P129i_is_subject_of demands, that being the predicate has_paradata_nodegroup takes in connections 1.6.17 the same day; it stays an E90 through em:NodeGroup, so the membership edge does not break. SemanticShapeNode leaves crmgeo:SP5_Geometric_Place_Expression for crm:E73_Information_Object, PROVVISORIAMENTE: SP5 is not declared at the crmgeo namespace this datamodel emits, crmgeo:SP6_Declarative_Place is the better candidate, and the decision is rinviata da E.D. — E73 commits to nothing meanwhile. crm:P131_is_identified_by, deprecated in CRM 7.x together with E82 Actor Appellation, becomes crm:P1_is_identified_by on AuthorNode (name, surname) and AuthorAINode (name). «CRMs3D» is renamed «CRMem», in components and in referenced_ontology_versions alike: the companion ontology is em.ttl and its namespace is em:, so the old name pointed at nothing anyone could look up. CRMsci moves 3.1 -> 3.2 (latest release). The eight em: terms this file and the connections datamodel cite but em.ttl never defined are now declared there (em:FunctionalUnit, em:GCPSet, em:Narrative, em:NeutralSU, em:RegistrationTransform, em:RepresentationModelNodeGroup, em:hasSubEpoch, em:validatedBy), with domain, range and superclass read off these datamodels and nothing invented. NOT TOUCHED: the `alternative` and legacy `cidoc_s3d` prose fields, which still discuss E78 as an option — prose, not a projection, and rewording them is modelling rather than repair. v1.6.5 (EM16-RMNG, 2026-09-10): adds RepresentationModelNodeGroup, the RM container as a first-class group of the graph — sixth subtype of GroupNode, keeping the parent's E78 Collection because a container IS a curatorial set. Paired with connections datamodel 1.6.14, which adds the is_in_representation_model_group membership edge and widens has_representation_model.target to accept the group. Additive only: no existing entry changed. s3Dgraphy nodes datamodel including node types with CIDOC-CRM mappings. v1.6.4 adds the ADDITIVE georeferencing_nodes section (GCPSetNode = em:GCPSet, RegistrationTransformNode = em:RegistrationTransform, both subclasses of crm:E73_Information_Object with their own extension URIs so the RDF projection stays bijective): the CONTROL and the SOLUTION that place a produced model in the world, introduced with the photogrammetry processing connector. The two modes of that connector are the SHAPE of the graph (a transform with a CRS that has_gcp_set points at = absolute; a transform with crs=null and no control set = a site-local frame; no transform at all = nobody placed it), never a flag. No existing family changed. v1.6.3 re-reads SemanticShapeNode as a PAYLOAD carrier: the proxy of a unit is now a PropertyNode of qualia type 'geometry' that points at the shape (has_semantic_shape), so the proxy inherits the paradata chain it never had. Breaking for consumers that read the proxy as a standalone SemanticShape. v1.6.2 adds AnnotationRegionNode (em:AnnotationRegion, subclass of crm:E36_Visual_Item): the geometry of a 2D annotation in NORMALISED image space, distinct from SemanticShapeNode (3D scene geometry, crmgeo:SP5) - the semantics of the 2D annotator, defined before any canvas exists. v1.6.0 inaugurates a systematic CIDOC-CRM mapping revision: complete audit of all node types against CIDOC-CRM, CRMarchaeo, CRMinf, CRMdig, CRMsci, CRMgeo; replacement of legacy 'cidoc_s3d' pseudo-class names (invented strings without IRI or superclass declaration) with formal em:/s3d: IRIs declared as proper subclasses of CRM classes; introduction of CRMinf as primary (not alternative) for the paradata chain (ParadataNode, PropertyNode interpretive case, ExtractorNode, CombinerNode); introduction of PROV-O for AuthorNode to cover both human and AI agents; alignment with the Heritage Digital Twin Ontology (HDT-O) for containment / granularity properties; LocationNodeGroup (v1.5.3) adopted as the reference pattern (CIDOC-native composition via P2_has_type → E55 Type instances, with explicit extension_status and rationale). Companion deliverables: em.ttl (formal EM extension ontology, dereferenceable via w3id.org/em/) and hdto_extension.ttl (HDT-O granularity properties: contains_HDT, contains_SU, isPrimary). v1.5.4 added RSF (Reused Special Find — spolia) as a stratigraphic subtype, octagon with red border, family=real, is_series=false. Originating DP: DP-26 (spolia project, last DP before the EM 1.5 cut). v1.5.3 added LocationNodeGroup (E53 Place + E55 Type) for spatial / locational membership orthogonal to ActivityNodeGroup (intention) and EpochNode (time). v1.5.2 added family + is_series classification metadata on stratigraphic subtypes.",
+  "s3Dgraphy_data_model_version": "1.6.30",
+  "description": "v1.6.30 (giro dell'11 ottobre (2), decided by E.D. 2026-10-11, «il codice di studio è stabile»): StudyNode.code is STABLE — once a study has one it never changes by itself (import, export, migration, projection): it is what Blender re-attaches the proxies by (GT16.1.USM100). Read: the study's code, else the GraphML header ID (graph_code), else the retired em_id (read only). A GraphML's header ID is written on the study at import. When there is none, s3dgraphy.hdto.propose_study_code writes ONE proposal (site initials + the year of the study's date, -2/-3 against the other codes of the container) and marks it with the new field `code_proposed` until the user confirms it. v1.6.29 (giro dell'11 ottobre, decided by E.D. 2026-10-11): the code of a graph is the code of its STUDY — StudyNode.code replaces the graph-self node's retired «EM-ID» (GraphNode.data.em_id, never a field of this datamodel): a file that has one keeps it and s3dgraphy.hdto.migrate_em_id carries it to the study's code only when the study exists and has none. A saggio is a study AND a place: its LocationNodeGroup (kind study) is in the site (is_in_location), the study took place at it. Descriptions only, no field added. v1.6.28 (MICRO lo studio usabile, decided by E.D. 2026-10-10: the stratigraphic trench is a STUDY, the site is TOPOGRAPHY, HC1 is heritage only where recognised): StudyNode gains `study_kind` (stratigraphic_excavation | survey | documentation | other) — a stratigraphic_excavation is ALSO a crmarchaeo:A9_Archaeological_Excavation, declared per value in the field (`subclass_of_by_value`, the same subclass_of form the classes use) and emitted by the RDF exporter as a second rdf:type — and `code` (the short name of the study, e.g. GT16: what the source gives, or what the user writes; never derived; the label prefix reads it). HC9 Study is aligned to crm:E65_Creation (was crm:E7_Activity; E65 ⊑ E7), HC1 Heritage Entity to crm:E70_Thing (was crm:E1_CRM_Entity), as the official HDT-O RDFS says (HDT_v2.0.1.rdf, ECHOES D7.1). The study reaches its place with study_took_place_at (crm:P7_took_place_at, connections 1.6.39). v1.6.27 (MICRO le entità spaziotemporali, decided by E.D. 2026-10-10): DocumentNode and AuthorNode (with AuthorAINode) are SPATIOTEMPORAL ENTITIES like the stratigraphic units — the top-level block `spatiotemporal_entities` names the three classes and what they share: a start and an end (absolute_time_start / absolute_time_end, read with the label of their owner: a person is born and dies, a model is released and retired), the lane of the matrix where they begin (has_first_epoch) and the ones they last through (survive_in_epoch), their place in the sequence (is_after, has_same_time), an activity. The edges are widened in connections 1.6.38; the chronology dates the three with the same rules (Graph.CHRONOLOGY_TYPES). AuthorNode and DocumentNode gain a `spatiotemporal` element saying how their time reads; no field of theirs changes. v1.6.26 (H4, decided by E.D. 5 Oct 2026, «Heriverse legge l'em.json e sceglie la versione»): ResourceNode.use admits two more uses, heriverse and aton — a version made FOR a viewer, the package on disk that Heriverse or another ATON app opens offline (EM Tools makes it with «Prepare for a use…», as is: no optimisation of its own); a viewer asks heriverse, aton, web, realtime in that order (s3dgraphy.resources.versions.choose_version). v1.6.25 (D1, MICRO un solo vocabolario, decided by E.D. 4 Oct 2026): GeoPositionNode.rotation_reference = 'grid' (D2: the rotation is measured from the GRID north of the CRS). ResourceNode.lod_level (em:lodLevel, computed from the chain, written only on export and checked at load), ResourceNode.use (em:use, a list of analysis | realtime | web | mobile_ar | print | render | preview) and seven measures of a version (em:trisPerM2, em:texelDensityDD, em:textureCount, em:textureSidePx, em:uvRatio, em:reductionFromLod0, em:geometricErrorM). v1.6.24 (dev30, decided by E.D. 2026-10-02 on the dev29 report): DTCAcquisitionNode.retrieved_from — where a retrieved object came from, a DOI or a URL (em:retrievedFrom, D1; optional, validate warns «download without origin»). ResourceNode.members_digest names em:membersDigest, the digest of a file_set with a predicate of its own beside em:checksum + em:digestCovers (D4; not a second field). ResourceNode.packaging carries its vocabulary with values and labels, translated in datamodel_translations.json (packagings; A3). ResourceNode.content_digest also holds the digest of the data of a master inside another file — a Metashape model's mesh.ply — compared, never verified by downloading (D7). GCPSetNode gains data.control (ground_control_points | camera_positions) and data.accuracy_m: a chunk referenced only by its cameras' GPS is absolute with the control said for what it is, and validate warns «georeferenced only by camera GPS» (D7). Node.properties.lang states the one explicit exception to the AI marker: a recognised language confirmed by a person is data.lang only (U5). CRMem 1.6.14. v1.6.23 (dev29, 2026-10-02, measured on San Pietro): seven properties that the round trip em.json → TTL → em.json lost now leave and come back — ResourceNode packaging / tier / digest_covers / content_digest (em:packaging, em:tier, em:digestCovers, em:contentDigest) and the declared fields of a DTC step, technique / parameters / software (em:technique, em:parameters, em:software, the last two as rdf:JSON). digest_covers admits members (a file_set). The blend:// locator stays out of RDF on purpose: it is a private path. v1.6.22 (dev28, 2026-11-01, decided by E.D. 2026-10-01 on the dev27 report): the access mode of a signature (created_auth / modified_auth / validated_auth) admits a third mode, 'declared' — an iD typed in a tool's preferences and checked by nobody (EMStudio's declared identity, EM Tools' local identity), with no attested_by; through a relay the mode is the relay's, read from the token (crdt.stamp_auth), not the client's declaration. The language a node is born in travels in the add_node op (crdt.make_op requires it of the producer, 'und' when unknown); the study's language is read only for old ops, said and counted. CRMem 1.6.12. v1.6.21 (dev27, 2026-10-31, decided by E.D. 2026-10-01, «il testo, la risorsa e la selezione» and «l'accesso sul campo»): ResourceNode.properties gains lang — on a resource the language(s) of its CONTENT, one tag or a sorted list, leaving as dcterms:language and outside the cascade of the texts — addresses (several addresses of ONE resource, same digest: em:hasAddress with em:locator, em:residency, em:checkedAt, em:reachable) and checksum_at (a dated digest, em:checksumAt). Node.properties gains created_auth / modified_auth / validated_auth: how the hand of a signature had entered, {mode: orcid | node_password, attested_by} (em:createdVia / em:modifiedVia / em:validatedVia, em:authMode, em:attestedBy). data.lang is written at birth (s3dgraphy.language.stamp_birth_language), also when equal to the study's. v1.6.20 (MICRO le traduzioni, 2026-10-29, decided by E.D. 2026-10-01, «Le traduzioni»): NEW TranslationNode (TRANSL, crm:E33_Linguistic_Object) — ONE translation of one text field of one node. The original stays a string in its field (data.lang on the node, else the study's), never overwritten; each translation is a node reached by has_translation (crm:P73_has_translation, connections 1.6.34) with data.lang (arrival), data.from_lang (departure, written because the original can change), data.field (CRDT vocabulary: description | data.<key>; a PropertyNode's value is data.value; never name), data.text, data.method (manual | ai | edition), data.source_digest (sha256 of the original translated: a different digest = «da riallineare») and data.review_requested («da rivedere»). Who: has_author; AI: data.ai_assisted, unverified until validated_by; an edition: extracted_from → the DocumentNode. RDF (em.ttl 1.6.10): Node.properties.lang names em:originalLanguage — the node's own data.lang leaves as that literal whenever it is declared, equal to the study's too, so a reader tells the original literal from the translations that share its predicate and the round trip gives data.lang back exactly where it was (the D.1 limit of 1.6.19 is closed); the TranslationNode's fields name em:sourceLanguage, em:translatedField, em:translationMethod, em:sourceDigest, em:reviewRequested. v1.6.19 (MICRO la lingua dei dati, 2026-10-27, decided by E.D. 2026-09-28): Node.properties.description becomes an object {cidoc: P3_has_note, natural_language: true, note} — the MARKER that says the description is text in a natural language and leaves in RDF with its language tag; declared once on the base class and inherited by every node type. name is NOT marked: names are invariant identities. No field added, no node element, no graph change: the em.json is the same; only the RDF literal gains its tag. v1.6.18 (MICRO i termini di em.ttl nel datamodel, 2026-10-26, decided by E.D. 2026-10-01 — the datamodel JSON is the truth, so every em: term of em.ttl is cited by a datamodel or is a written exception): the em: predicates the RDF exporter already writes are now NAMED in properties, as plain-string mapping notes (no field added, no node element, no graph change). Node (inherited by every class): the last-hand stamps created_by em:createdBy / modified_by em:lastEditedBy / modified_at em:modifiedAt (created_at prov:generatedAtTime), the tombstone removed.ts em:removedAt / removed.by em:removedBy, the AI marker ai_assisted.by em:aiAssistedBy / .model em:aiModel / .prompt_ref em:aiPromptRef / .fields em:aiAssistedField and the verification validated_by em:validatedBy / validated_at em:validatedAt (properties_note). ResourceNode: checksum em:checksum, scope em:resourceScope, residency em:residency. SemanticShapeNode: convexshapes em:convexShape, spheres em:sphere. AnnotationRegionNode: crs em:crs, coords.frame_iri em:LocalSceneFrame. AuthorNode and AuthorAINode: verified em:orcidVerified (AuthorAINode also names orcid P48, which the exporter writes for both). LocationNodeGroup.propagation.mapping: uri em:propagation. THREE ENTRIES CORRECTED TO WHAT THE CODE WRITES (measured in rdf_exporter.py): PropertyNode.property_type was P2_has_type, is em:hasQualiaType; AuthorAINode model / prompt_reference were P3_has_note, are em:modelIdentifier / em:promptReference; ResourceFileNode.checksum was P1_is_identified_by, is em:checksum; and LocationNodeGroup.propagation said 'not serialized to triplestore' while the exporter has written the non-default value as em:propagation since c1a702c (2026-08-12). v1.6.17 (MICRO la risorsa e i suoi file, 2026-10-18, decided by E.D. 2026-09-30): NEW ResourceFileNode (FILE, crmdig:D1_Digital_Object) — the ResourceNode is the set, the ResourceFileNode is each file, reached by has_file (connections 1.6.30) with role and relative path on the edge. With one file the node is implicit (url and checksum stay on the ResourceNode, as today). ResourceNode.PACKAGINGS += file_set (a few files that call each other: obj → mtl → textures, gltf → bin, shp and companions) and datablock (one object inside a file, a blend:// locator). Representations of the same thing are sibling ResourceNodes tied by dtc_derived_from and chosen by tier and packaging. ADDITIVE: nothing narrowed, no graph changes. v1.6.16 (MICRO le annotazioni ATON sull'asset, 2026-10-15, decided by E.D.): AnnotationRegionNode gains geometry_kind 'volume' — an annotation that encloses a part of a 3D model (ATON / Hathor convex hulls and spheres) and is the proxy of no unit. The region carries no vertices: it reaches a SemanticShapeNode (convexshapes, spheres) with has_semantic_shape and the model with is_on_resource. geometry.aton.import_aton_scene makes one for every semantic id no EM node is named after (a stratigraphic unit only with an explicit create_type); api.promote_region_to_proxy turns it into the proxy of a unit later. RDF: P2_has_type 'volume', no selector, no WKT; the shape travels as itself. Additive. v1.6.15 (MICRO la geometria per origine, 2026-10-11, decided by E.D. 2026-09-30): AnnotationRegionNode's point / line / polyline keep their vertices IN THE NODE, data.coords [[x, y, z], ...] (scene-local, glTF Y-up, metres) with crs and, for a line or a polyline, length and unit — no .glb and no SemanticShape for a reading. New block coords (inline_max_vertices 500: above it the vertices go to a .glb resource via has_linked_resource, with a warning). RDF: geo:hasGeometry -> <region>/geometry geo:asWKT (POINT Z / LINESTRING Z, GeoSPARQL). The readings/<id>.glb of 2026-10-06 are migrated on opening. v1.6.14 (MICRO la cattura in RDF, 2026-09-30): DTCAcquisitionNode.mapping.by_kind — its D12 is the class of a retrieval; a capture takes the class its kind declares in em_visual_rules 1.6.24 (D2 / D11 / E65). Mapping text only, no field changed. v1.6.13 (MICRO i generi delle US, 2026-09-30, decided by E.D. the same day): stratigraphic_kind gains 'coating' — the USR (rivestimento) and its English translation USS (surface): plaster, floors, revetments — with `labels`, `codes` and `default_code` per kind; new node element `source_code` (data.source_code) keeps the code a unit came in with when it is not its kind's default, so the way back to pyArchInit gives the same code. A legacy node_type 'USR' / 'USS' opens as US + coating. v1.6.12 (MICRO la cattura nel DTC e le murature, 2026-09-30): StratigraphicUnit (US) gains the node element `stratigraphic_kind` (em.json data.stratigraphic_kind; today one value, 'masonry'): a USM is a US + masonry, and the legacy node_type 'USM' — never a type of this datamodel — opens as that. DTCAcquisitionNode's description names the two families of the acquisition axis (em_visual_rules 1.6.22: capture / retrieval). v1.6.11 (MICRO la misura in RDF, 2026-10-07): AnnotationRegionNode.properties says how the fields left unprojected by 1.6.10 now travel — the quote of a passage as oa:TextQuoteSelector, the length of a line/polyline as crm:E54_Dimension (P90 value, P91 QUDT unit, em:crs), vertex_count as em:vertexCount. CRMem (em.ttl) 1.6.5 -> 1.6.6. Mapping text only, no field changed. v1.6.10 (MICRO la geometria della lettura, 2026-10-06, decided by E.D. on 2026-09-29): AnnotationRegionNode becomes the node of THE PLACE A READING LOOKED AT, with a new field geometry_kind: region2d (default, every older region), passage (start, end, text), point, line, polyline. The three 3D kinds keep their coordinates in a .glb (glTF POINTS / LINES / LINE_STRIP) linked with has_semantic_shape exactly like a proxy's payload, never in the em.json; the node keeps vertex_count and, for line/polyline, length + unit + crs (api.measure). See the entry's geometry_kinds and glb_payload. Paired with connections 1.6.27 (is_on_resource.target += the representation models). Additive: a region without geometry_kind reads as region2d. v1.6.9 (MICRO la definizione dell'unita', 2026-10-20, decided by E.D. on 2026-09-27): StratigraphicNode.properties gains `definition`, the DEFINIZIONE of the US sheet, as an element of the node like name and description and NOT a qualia. Value = a controlled-vocabulary concept {concept, label}; em.json carries it as data.definition (CRDT field 'data.definition', no change to the frozen em.json v1 node shape); inherited by every stratigraphic subtype. The RDF projection is declared in the entry itself (`rdf`): crm:P2_has_type -> crm:E55_Type when a concept URI is present, nothing when only a label is (`label_only: null`). CRMem 1.6.4 -> 1.6.5 for the companion em:hasDefinition (subproperty of crm:P2_has_type, declared, not emitted by default). Additive only. v1.6.7 (CRMem WIRING, 2026-09-24): rimosso il campo legacy `cidoc_s3d` da tutte le mapping. Non era letto da nessuna parte del codice e portava quattro nomi di classe senza namespace, mai dichiarati e mai emessi: EpochNode = StratigraphicTimeframe; ActivityNodeGroup = StratigraphicActivity; ParadataNodeGroup = ParadataCollection; ResourceNode = ExternalResourceReference. Il prefisso CIDOC-S3D non esiste piu' in nessuno dei due datamodel. v1.6.6 (CIDOC REPAIR, 2026-09-21): classes that pointed at IRIs nobody declares. Checked by parsing the official releases, not from memory. crm:E78_Collection is gone from CIDOC CRM 7.1.3 — renamed E78_Curated_Holding — and E.D. decided NOT to follow the rename, because E78_Curated_Holding is a subclass of E24 Physical Human-Made Thing and a group of nodes is not a physical thing. The three classes that carried it therefore split, each to the class it actually is: GroupNode and RepresentationModelNodeGroup to crm:E73_Information_Object (a conceptual set, and an E90 Symbolic Object, which is what the P106i membership edge needs at both ends), ParadataNodeGroup to crm:E89_Propositional_Object — which is what a gathered body of reasoning IS and what the range of crm:P129i_is_subject_of demands, that being the predicate has_paradata_nodegroup takes in connections 1.6.17 the same day; it stays an E90 through em:NodeGroup, so the membership edge does not break. SemanticShapeNode leaves crmgeo:SP5_Geometric_Place_Expression for crm:E73_Information_Object, PROVVISORIAMENTE: SP5 is not declared at the crmgeo namespace this datamodel emits, crmgeo:SP6_Declarative_Place is the better candidate, and the decision is rinviata da E.D. — E73 commits to nothing meanwhile. crm:P131_is_identified_by, deprecated in CRM 7.x together with E82 Actor Appellation, becomes crm:P1_is_identified_by on AuthorNode (name, surname) and AuthorAINode (name). «CRMs3D» is renamed «CRMem», in components and in referenced_ontology_versions alike: the companion ontology is em.ttl and its namespace is em:, so the old name pointed at nothing anyone could look up. CRMsci moves 3.1 -> 3.2 (latest release). The eight em: terms this file and the connections datamodel cite but em.ttl never defined are now declared there (em:FunctionalUnit, em:GCPSet, em:Narrative, em:NeutralSU, em:RegistrationTransform, em:RepresentationModelNodeGroup, em:hasSubEpoch, em:validatedBy), with domain, range and superclass read off these datamodels and nothing invented. NOT TOUCHED: the `alternative` and legacy `cidoc_s3d` prose fields, which still discuss E78 as an option — prose, not a projection, and rewording them is modelling rather than repair. v1.6.5 (EM16-RMNG, 2026-09-10): adds RepresentationModelNodeGroup, the RM container as a first-class group of the graph — sixth subtype of GroupNode, keeping the parent's E78 Collection because a container IS a curatorial set. Paired with connections datamodel 1.6.14, which adds the is_in_representation_model_group membership edge and widens has_representation_model.target to accept the group. Additive only: no existing entry changed. s3Dgraphy nodes datamodel including node types with CIDOC-CRM mappings. v1.6.4 adds the ADDITIVE georeferencing_nodes section (GCPSetNode = em:GCPSet, RegistrationTransformNode = em:RegistrationTransform, both subclasses of crm:E73_Information_Object with their own extension URIs so the RDF projection stays bijective): the CONTROL and the SOLUTION that place a produced model in the world, introduced with the photogrammetry processing connector. The two modes of that connector are the SHAPE of the graph (a transform with a CRS that has_gcp_set points at = absolute; a transform with crs=null and no control set = a site-local frame; no transform at all = nobody placed it), never a flag. No existing family changed. v1.6.3 re-reads SemanticShapeNode as a PAYLOAD carrier: the proxy of a unit is now a PropertyNode of qualia type 'geometry' that points at the shape (has_semantic_shape), so the proxy inherits the paradata chain it never had. Breaking for consumers that read the proxy as a standalone SemanticShape. v1.6.2 adds AnnotationRegionNode (em:AnnotationRegion, subclass of crm:E36_Visual_Item): the geometry of a 2D annotation in NORMALISED image space, distinct from SemanticShapeNode (3D scene geometry, crmgeo:SP5) - the semantics of the 2D annotator, defined before any canvas exists. v1.6.0 inaugurates a systematic CIDOC-CRM mapping revision: complete audit of all node types against CIDOC-CRM, CRMarchaeo, CRMinf, CRMdig, CRMsci, CRMgeo; replacement of legacy 'cidoc_s3d' pseudo-class names (invented strings without IRI or superclass declaration) with formal em:/s3d: IRIs declared as proper subclasses of CRM classes; introduction of CRMinf as primary (not alternative) for the paradata chain (ParadataNode, PropertyNode interpretive case, ExtractorNode, CombinerNode); introduction of PROV-O for AuthorNode to cover both human and AI agents; alignment with the Heritage Digital Twin Ontology (HDT-O) for containment / granularity properties; LocationNodeGroup (v1.5.3) adopted as the reference pattern (CIDOC-native composition via P2_has_type → E55 Type instances, with explicit extension_status and rationale). Companion deliverables: em.ttl (formal EM extension ontology, dereferenceable via w3id.org/em/) and hdto_extension.ttl (HDT-O granularity properties: contains_HDT, contains_SU, isPrimary). v1.5.4 added RSF (Reused Special Find — spolia) as a stratigraphic subtype, octagon with red border, family=real, is_series=false. Originating DP: DP-26 (spolia project, last DP before the EM 1.5 cut). v1.5.3 added LocationNodeGroup (E53 Place + E55 Type) for spatial / locational membership orthogonal to ActivityNodeGroup (intention) and EpochNode (time). v1.5.2 added family + is_series classification metadata on stratigraphic subtypes.",
   "components": [
     "CIDOC-CRM",
     "CRMarchaeo",
@@ -1713,11 +1713,19 @@
         "code": {
           "type": "string",
           "required": false,
-          "description": "The short name of the study (GT16, TM16): the one the source gives (pyArchInit), or the one the user writes in EM — never derived. The code of the graph is this one (E.D., 11 Oct 2026): it replaces the graph-self node's retired «EM-ID» (GraphNode.data.em_id), which a file keeps and s3dgraphy.hdto.migrate_em_id carries here only when the study has no code. The label prefix of the units reads it (s3dgraphy.hdto.study_code); graph.attributes['graph_code'] of a GraphML is read only when no study says one, the em_id never.",
+          "description": "The short name of the study (GT16, TM16), STABLE (E.D., 11 Oct 2026): the prefix Blender re-attaches the proxies by (GT16.1.USM100), so once written it never changes by itself — import, export, migration, projection. Sources, in order: the code the source gives (pyArchInit); the GraphML header ID, reused as it is (written here at import, and still kept in graph.attributes['graph_code'] and GraphNode.data.em_id); a file's retired em_id (s3dgraphy.hdto.migrate_em_id; s3dgraphy.hdto.study_code reads it as a fallback without writing). When none exists, a proposal is written ONCE (s3dgraphy.hdto.propose_study_code) and marked with code_proposed until the user confirms it.",
           "mapping": {
             "cidoc": "P1_is_identified_by"
           }
         },
+        "code_proposed": {
+          "type": "boolean",
+          "required": false,
+          "description": "True while the study's code is a PROPOSAL of the system (E.D., 11 Oct 2026: Blender needs unique proxy names, so a study without a code gets one — the site's initials and the year, unique in the container). Written once with the code and never recomputed; it goes away when the user confirms the code (s3dgraphy.hdto.confirm_study_code), who may then also replace the proposal. Absent = the code was given, not proposed.",
+          "mapping": {
+            "cidoc": null
+          }
+        },
         "disciplinary_focus": {
           "type": "string",
           "required": false,

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/__init__.py

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

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/api.py

@@ -322,6 +322,15 @@ def is_spatiotemporal(node) -> bool:
     return _is(node)
 
 
+def entity_epoch(graph: Graph, node_id: str) -> Optional[str]:
+    """The epoch an entity stands in: the narrowest holding its own date (start,
+    else end), else its ``has_first_epoch``, else the nearest to its date
+    (MICRO autori nel tempo, 11 Oct 2026). See
+    :func:`s3dgraphy.spatiotemporal.entity_epoch`."""
+    from .spatiotemporal import entity_epoch as _epoch
+    return _epoch(graph, node_id)
+
+
 def view_instances(graph: Graph, group_id: str) -> List[Dict[str, Any]]:
     """The instances a client draws inside the paradata group ``group_id``:
     every master (document or property) outside the group that a reader of the
@@ -673,12 +682,35 @@ def graphs_about(container, entity) -> List[str]:
 
 
 def study_code(graph: Graph) -> Optional[str]:
-    """The study's short name (GT16): ``StudyNode.data.code``, else the
-    GraphML's header ID, never invented."""
+    """The study's short name (GT16), stable: ``StudyNode.data.code``, else the
+    GraphML's header ID, else the retired em_id (read only). Never writes,
+    never proposes. See :func:`s3dgraphy.hdto.study_code`."""
     from .hdto import study_code as _code
     return _code(graph)
 
 
+def propose_study_code(graph: Graph, container=None) -> Dict[str, Any]:
+    """Give the study a code when it has none — once, marked
+    ``data.code_proposed`` until :func:`confirm_study_code`; never recomputed.
+    ``container`` avoids the codes of its other graphs. See
+    :func:`s3dgraphy.hdto.propose_study_code`."""
+    from .hdto import propose_study_code as _propose
+    return _propose(graph, container)
+
+
+def is_code_proposed(graph: Graph) -> bool:
+    """Whether the study's code is a proposal not yet confirmed."""
+    from .hdto import is_code_proposed as _is
+    return _is(graph)
+
+
+def confirm_study_code(graph: Graph, code: Optional[str] = None) -> Optional[str]:
+    """The user confirms the proposed code (or replaces the PROPOSAL with
+    ``code``); a confirmed code is not changed by confirming."""
+    from .hdto import confirm_study_code as _confirm
+    return _confirm(graph, code)
+
+
 def migrate_em_id(graph: Graph) -> Dict[str, Any]:
     """The retired ``GraphNode.data.em_id`` → ``StudyNode.data.code``, only
     when the study exists and has no code; the em_id is kept, nothing is
@@ -687,11 +719,38 @@ def migrate_em_id(graph: Graph) -> Dict[str, Any]:
     return _migrate(graph)
 
 
-def unit_label(graph: Graph, name: str, separator: str = ".") -> str:
-    """A unit's name with the study's code as prefix, or as it is when the
-    study has none."""
+def unit_label(graph: Graph, name: str, separator: str = ".", *,
+               container=None, propose: bool = True) -> str:
+    """A unit's name with the study's code as prefix (GT16.US001). Without a
+    code, one is proposed and written first (once); ``propose=False`` gives
+    the name as it is."""
     from .hdto import unit_label as _label
-    return _label(graph, name, separator)
+    return _label(graph, name, separator, container=container, propose=propose)
+
+
+# ── rapporti between the graphs of one em.json (11 Oct 2026) ─────────────────
+def add_link(container, source, target, edge_type: str, *,
+             link_id: Optional[str] = None,
+             attributes: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """A rapporto from ``(graph_id, node_id)`` to ``(graph_id, node_id)`` of
+    another graph of ``container``. See :mod:`s3dgraphy.links`."""
+    from .links import add_link as _add
+    return _add(container, source, target, edge_type, link_id=link_id,
+                attributes=attributes)
+
+
+def links_of(container, graph_id: str,
+             node_id: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Every rapporto touching a graph (or one of its nodes), both ways, with
+    the address of the other end to navigate to."""
+    from .links import links_of as _of
+    return _of(container, graph_id, node_id)
+
+
+def linked_graphs(container, graph_id: str) -> List[str]:
+    """The other graphs ``graph_id`` has rapporti with."""
+    from .links import linked_graphs as _linked
+    return _linked(container, graph_id)
 
 
 # ── editorial stamps (last hand) ──────────────────────────────────────────────

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/crdt.py

@@ -1010,7 +1010,8 @@ def edge_outside_graph(has_node, source: Any, target: Any,
 
     **The rule: an end that is a node of ANOTHER graph of the study refuses the
     edge.** An edge lives in the section of one graph and joins two nodes of it;
-    a link between graphs of one study (I-4, graph + UUID) does not exist yet.
+    a rapporto between graphs of one study (I-4, graph + UUID) is a LINK of
+    the graph of its source, not an edge — :mod:`s3dgraphy.links`.
     Until 5 Oct 2026 the CRDT took such an edge and the reader then dropped it:
     a room accepted what its own file threw away.
 
@@ -1032,7 +1033,8 @@ def edge_outside_graph(has_node, source: Any, target: Any,
         if other:
             return (f"the node '{node_id}' is in the graph '{other}', not in "
                     f"this one: an edge joins two nodes of the same graph, and "
-                    f"a link between graphs does not exist yet")
+                    f"a rapporto between graphs is a link (graph + node), "
+                    f"not an edge")
     return None
 
 

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/exporter/emjson_exporter.py

@@ -240,6 +240,24 @@ def build_emjson(graph: Graph, layout: Optional[Dict[str, Any]] = None) -> Dict[
         "nodes": nodes,
         "edges": edges,
     }
+    # the HEADER of the graph (E.D., 11 Oct 2026): its stable id and the
+    # study's code side by side, readable without walking the nodes. The code
+    # is a MIRROR of StudyNode.data.code — written here, checked on import,
+    # and the study wins — or, when the study has none, what study_code reads
+    # (the GraphML header's ID, the retired em_id), so an old file's code is
+    # no longer lost at its first em.json. Written only when there is a code.
+    from ..hdto import is_code_proposed, study_code
+    code = study_code(graph)
+    if code:
+        graph_section["code"] = code
+        if is_code_proposed(graph):
+            graph_section["code_proposed"] = True
+    # the rapporti towards other graphs of the container (s3dgraphy.links):
+    # written only when there are some, so a graph without stays as it was
+    links = [dict(l) for l in (getattr(graph, "links", None) or [])
+             if isinstance(l, dict)]
+    if links:
+        graph_section["links"] = links
     gname = _to_text(getattr(graph, "name", None))
     if gname:
         graph_section["name"] = gname

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/graph.py

@@ -64,6 +64,9 @@ class Graph:
         #: ``warnings`` alone, because nothing here knows what it points at.
         self.warning_records = []
         self.attributes = {}
+        #: the rapporti towards nodes of OTHER graphs of the container — see
+        #: :mod:`s3dgraphy.links` (E.D., 11 Oct 2026)
+        self.links = []
 
         # Initialize graph indices
         self._indices = None

{s3dgraphy-1.6.0.dev44 → s3dgraphy-1.6.0.dev46}/src/s3dgraphy/hdto.py

@@ -21,8 +21,16 @@ Giro dell'11 ottobre (E.D., 11 Oct 2026):
   export with several saggi is one graph per saggio in a Container
   (``GraphProjector.populate_container``);
 * **the code is the study's**: the graph's «EM-ID» (``GraphNode.data.em_id``)
-  is retired; :func:`study_code` never reads it and :func:`migrate_em_id`
-  carries it to ``StudyNode.data.code`` only when the study has none.
+  is retired; :func:`migrate_em_id` carries it to ``StudyNode.data.code`` only
+  when the study has none.
+
+Giro dell'11 ottobre (2) (E.D., 11 Oct 2026):
+
+* **the code is stable**: it is what Blender re-attaches the proxies by
+  (``GT16.1.USM100``), so once written it never changes by itself.
+  :func:`study_code` reads the study's code, then the GraphML header ID, then
+  the em_id (read only); :func:`propose_study_code` writes ONE proposal when
+  there is none, marked ``code_proposed`` until :func:`confirm_study_code`.
 
 The writer follows EMStudio's ``applyHdto`` (frontend/src/model.ts) for every
 role EMStudio already writes — the same roles in ``data.hdto_role``, one node
@@ -300,7 +308,10 @@ def declare_hdto(graph, *, study=None, place=None, about=None, parent=None,
             if study_s.get(key) is not None:
                 d[key] = study_s[key]
         if _text(study_s.get("code")):
+            # a code GIVEN is a person's (or the source's): it is no longer a
+            # proposal, whatever was written before (E.D., 11 Oct 2026)
             d["code"] = _text(study_s["code"])
+            d.pop("code_proposed", None)
         _ensure_edge(graph, study_node, proposition_set,
                      "study_produced_proposition_set")
     if study_node is not None and hc1 is not None and has_about:
@@ -411,21 +422,216 @@ def read_hdto(graph) -> Dict[str, Any]:
 # ── the code of the study ───────────────────────────────────────────────────
 
 def study_code(graph) -> Optional[str]:
-    """The short name of the study (GT16), or ``None``.
-
-    ONE source: ``StudyNode.data.code``. A GraphML's header ID
-    (``graph.attributes['graph_code']``) is read only when no study says a
-    code — it is what the source gave — and never its ``MISSINGCODE``
-    placeholder. Nothing is derived (E.D., 10 Oct 2026). The retired
-    ``GraphNode.data.em_id`` is NEVER read here (E.D., 11 Oct 2026): it
-    becomes the study's code through :func:`migrate_em_id`, explicitly.
+    """The short name of the study (GT16), or ``None``. It is the name Blender
+    re-attaches the proxies by (``GT16.1.USM100``), so once a study has a code
+    it never changes by itself (E.D., 11 Oct 2026, «il codice di studio è
+    stabile»). Read, in order:
+
+    1. ``StudyNode.data.code`` — the code the source gave, the GraphML header's
+       ID carried on import, a migrated em_id, or a proposal already written
+       (:func:`propose_study_code`, ``data.code_proposed``);
+    2. the GraphML header ID (``graph.attributes['graph_code']``), never its
+       ``MISSINGCODE`` placeholder — a graph read by an older importer;
+    3. the retired ``GraphNode.data.em_id``, read only, as a fallback: the
+       file is not changed (:func:`migrate_em_id` writes it to the study).
+
+    Nothing is proposed here: reading never writes. :func:`unit_label` and
+    :func:`ensure_study_code` propose, once, when all three are missing.
     """
     study = _role_node(graph, "study")
     code = _text(_get(study, "code")) if study is not None else ""
     if code:
         return code
     legacy = _text((getattr(graph, "attributes", None) or {}).get("graph_code"))
-    return legacy if legacy not in _NO_CODE else None
+    if legacy not in _NO_CODE:
+        return legacy
+    return legacy_em_id(graph)
+
+
+def is_code_proposed(graph) -> bool:
+    """Whether the study's code is a proposal nobody confirmed yet."""
+    study = _role_node(graph, "study")
+    return bool(study is not None and _text(_get(study, "code"))
+                and _get(study, "code_proposed") is True)
+
+
+def confirm_study_code(graph, code: Optional[str] = None) -> Optional[str]:
+    """The user confirms the study's code: ``data.code_proposed`` goes away.
+
+    ``code`` given and different from the proposal: the user's code replaces
+    the PROPOSAL — the one case a written code changes, and only by a person.
+    A confirmed code is never replaced here: changing it is the user's edit
+    of ``StudyNode.data.code``, not a confirmation. Returns the code."""
+    study = _role_node(graph, "study")
+    if study is None:
+        return None
+    d = _data(study)
+    current = _text(d.get("code"))
+    wanted = _text(code)
+    if wanted and wanted != current:
+        if current and d.get("code_proposed") is not True:
+            raise ValueError(f"the study's code is {current!r}, confirmed: "
+                             f"confirming does not change it")
+        d["code"] = wanted
+    d.pop("code_proposed", None)
+    return _text(d.get("code")) or None
+
+
+#: words that are not initials (Grotta di Tiberio → GT)
+_NOT_INITIALS = {"di", "de", "del", "della", "dei", "delle", "degli", "da",
+                 "la", "le", "il", "lo", "gli", "i", "l", "d", "e", "ed",
+                 "of", "the", "and", "a", "an", "von", "der", "des", "du"}
+
+
+def _site_name_of(graph) -> str:
+    """The name of the site the study took place at: the place itself when it
+    is a site, else the first site up its ``is_in_location`` chain, else the
+    place (a saggio not under a site)."""
+    study = _role_node(graph, "study")
+    for place in _out(graph, study, "study_took_place_at"):
+        chain = _place_chain(graph, place)
+        for p in chain:
+            if _get(p, "level") == "sito" and _text(p.name):
+                return _text(p.name)
+        if _text(place.name):
+            return _text(place.name)
+    return ""
+
+
+#: a name nobody gave (EMStudio's and EM-tools' defaults): no initials
+_PLACEHOLDER_WORDS = {"untitled", "graph", "grafo", "new", "nuovo", "senza",
+                      "titolo", "empty", "slot", "proposition", "set"}
+
+
+def _initials(name: str) -> str:
+    import re
+    import unicodedata
+    plain = unicodedata.normalize("NFKD", name)
+    plain = "".join(c for c in plain if not unicodedata.combining(c))
+    words = [w for w in re.split(r"[^A-Za-z0-9]+", plain) if w]
+    if words and all(w.lower() in _PLACEHOLDER_WORDS for w in words):
+        return ""
+    words = [w for w in words if w.lower() not in _NOT_INITIALS] or words
+    if not words:
+        return ""
+    if len(words) == 1:
+        return words[0][:2].upper()
+    return "".join(w[0] for w in words[:4]).upper()
+
+
+def _year_of(value: Any) -> str:
+    import re
+    found = re.search(r"(1[89]|20)(\d\d)", _text(value))
+    return found.group(2) if found else ""
+
+
+def _codes_in(container, besides=None) -> set:
+    taken = set()
+    if container is None:
+        return taken
+    for _gid, other in _member_graphs(container):
+        if other is besides:
+            continue
+        code = study_code(other)
+        if code:
+            taken.add(code.upper())
+    return taken
+
+
+def proposal_for(graph, container=None) -> str:
+    """The code the system would propose for ``graph`` — computed, not
+    written. The rule (E.D., 11 Oct 2026, measured and written in the referto
+    of the giro):
+
+    * the letters: the initials of the site the study took place at (words of
+      two or more: ``Grotta di Tiberio`` → ``GT``, the particles left out;
+      one word: its first two letters, ``Volterra`` → ``VO``); without a site,
+      of the study's name; without that, of the graph's name; else ``ST``;
+    * the year: the last two digits of the first year in the study's
+      ``date`` (``2016`` → ``16``), when there is one;
+    * a collision with a code of another graph of the container (case
+      insensitive) takes ``-2``, ``-3``…: never a ``.``, which is the
+      separator of the proxies' names.
+    """
+    study = _role_node(graph, "study")
+    letters = (_initials(_site_name_of(graph))
+               or _initials(_text(getattr(study, "name", "")) if study is not None else "")
+               or _initials(_text(_to_name(getattr(graph, "name", None))))
+               or "ST")
+    year = _year_of(_get(study, "date")) if study is not None else ""
+    base = f"{letters}{year}"
+    taken = _codes_in(container, besides=graph)
+    code, n = base, 1
+    while code.upper() in taken:
+        n += 1
+        code = f"{base}-{n}"
+    return code
+
+
+def _to_name(value: Any) -> str:
+    if isinstance(value, dict):
+        return _text(value.get("default") or next(iter(value.values()), ""))
+    return _text(value)
+
+
+def propose_study_code(graph, container=None) -> Dict[str, Any]:
+    """Give the study a code when it has none — ONCE: written on
+    ``StudyNode.data.code`` with ``data.code_proposed = True`` until the user
+    confirms it (:func:`confirm_study_code`), and from then on read like any
+    code, never recomputed (E.D., 11 Oct 2026).
+
+    * the study already has a code (proposed or not): nothing changes;
+    * a code without a study — the GraphML header ID, the retired em_id —
+      goes to the study as it is (not a proposal: the source gave it);
+    * nothing at all: :func:`proposal_for`, avoiding the other codes of
+      ``container``.
+
+    A graph without a study gets one (the code has to live somewhere, and the
+    code is the study's): named like the graph, no kind, no place.
+
+    Returns ``{"code", "proposed", "written", "source"}``; ``source`` is
+    ``"study"``, ``"graph_code"``, ``"em_id"`` or ``"proposal"``.
+    """
+    from .nodes.study_node import StudyNode
+    from .nodes.graph_node import GraphNode
+    study = _role_node(graph, "study")
+    code = _text(_get(study, "code")) if study is not None else ""
+    if code:
+        return {"code": code, "proposed": _get(study, "code_proposed") is True,
+                "written": False, "source": "study"}
+    legacy = _text((getattr(graph, "attributes", None) or {}).get("graph_code"))
+    if legacy not in _NO_CODE:
+        code, source = legacy, "graph_code"
+    elif legacy_em_id(graph):
+        code, source = legacy_em_id(graph), "em_id"
+    else:
+        code, source = proposal_for(graph, container), "proposal"
+    if study is None:
+        name = _to_name(getattr(graph, "name", None)) or code
+        if _role_node(graph, "proposition_set") is None:
+            pset = GraphNode(_derived_id(graph, "proposition_set"), name=name)
+            _data(pset)["hdto_role"] = "proposition_set"
+            graph.add_node(pset)
+        study = StudyNode(_derived_id(graph, "study"), name=name)
+        _data(study)["hdto_role"] = "study"
+        graph.add_node(study)
+        declare_hdto(graph, study={"name": name})
+    d = _data(study)
+    d["code"] = code
+    if source == "proposal":
+        d["code_proposed"] = True
+    return {"code": code, "proposed": source == "proposal", "written": True,
+            "source": source}
+
+
+def _derived_id(graph, role: str) -> str:
+    """A deterministic id for a node :func:`propose_study_code` has to make:
+    the same graph gives the same id (a re-import does not move it)."""
+    return str(uuid.uuid5(uuid.NAMESPACE_URL,
+                          f"s3dgraphy:{getattr(graph, 'graph_id', '')}:{role}"))
+
+
+ensure_study_code = propose_study_code
 
 
 def legacy_em_id(graph) -> Optional[str]:
@@ -469,11 +675,18 @@ def migrate_em_id(graph) -> Dict[str, Any]:
             "migrated": reason == "migrated", "reason": reason}
 
 
-def unit_label(graph, name: str, separator: str = ".") -> str:
-    """``name`` with the study's code as prefix (GT16.US001), or ``name`` as it
-    is when the study has no code — never an invented one."""
+def unit_label(graph, name: str, separator: str = ".", *, container=None,
+               propose: bool = True) -> str:
+    """``name`` with the study's code as prefix (GT16.US001).
+
+    The code is :func:`study_code`'s; when there is none and ``propose`` is
+    true, :func:`propose_study_code` writes one first (Blender needs unique
+    proxy names) — once: the next call reads it. ``propose=False``: ``name``
+    as it is."""
     from .utils.utils import manage_id_prefix
     code = study_code(graph)
+    if not code and propose:
+        code = propose_study_code(graph, container)["code"]
     return manage_id_prefix(name, code, "add", separator) if code else name