s3dgraphy 1.6.0.dev14__tar.gz → 1.6.0.dev16__tar.gz

{s3dgraphy-1.6.0.dev14/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev16}/PKG-INFO

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

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

s3dgraphy-1.6.0.dev16/src/s3dgraphy/JSON_config/acquisition_mappings/uri.json

@@ -0,0 +1,22 @@
+{
+  "mapping_version": "0",
+  "source": "uri",
+  "tier": 0,
+  "_comment": "Per-source acquisition mapping for a BARE URI — the asset nobody downloads. Somebody pastes a link (a IIIF manifest, a Zenodo record, a Sketchfab model, a colleague's WebDAV folder) and what enters the shelf is the URI plus the protocol you reach it through: asset.access = {mode: subscribe|open, endpoint?}. NO BYTES ARE COPIED and no object store is touched — that is the whole point of this mapping, and the difference from fs.json, which acquires a local file. Build the raw record with s3dgraphy.acquisition.uri_record(uri, protocol=..., access=...), then apply_mapping('uri', record). The acquisition method is uri_reference: the URI is what was acquired, not the object, and calling it 'download' would record a retrieval that never happened.",
+  "descriptor_defaults": {
+    "schema_version": "0",
+    "source": {"repo_id": "uri", "capabilities": []},
+    "acquisition": {"agent": "emtools-shelf@0", "method": "uri_reference"},
+    "rights": {"license": "unknown"}
+  },
+  "field_map": {
+    "asset.ref": "uri",
+    "asset.name": "name",
+    "asset.media_type": "media_type",
+    "asset.access": "access",
+    "asset.protocol": "protocol",
+    "source.repo_id": "repo_id",
+    "source.record_id": "record_id",
+    "source.record_url": "record_url"
+  }
+}

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/JSON_config/em_visual_rules.json

@@ -840,7 +840,8 @@
     "acquisition": {
       "download": { "label": "Download", "glyph": null, "description": "Retrieval of a digital object from a remote (opaque, Tier-0) repository." },
       "ingest": { "label": "Ingest", "glyph": null, "description": "Generic ingestion of a digital object into the study." },
-      "local_import": { "label": "Local import", "glyph": null, "description": "Acquisition from the local file system (project-folder search) — the local analog of remote acquisition." }
+      "local_import": { "label": "Local import", "glyph": null, "description": "Acquisition from the local file system (project-folder search) — the local analog of remote acquisition." },
+      "uri_reference": { "label": "URI reference", "glyph": null, "description": "The URI was acquired, not the object: the resource stays where it is and is reached through its own access protocol (an open link, or one you subscribe to). No bytes were copied — calling this a download would record a retrieval that never happened." }
     },
     "output": {
       "pointcloud": { "label": "Point cloud", "glyph": "02_pointcloud", "description": "Produced point cloud." },

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/JSON_config/s3Dgraphy_connections_datamodel.json

@@ -1,6 +1,6 @@
 {
-  "s3Dgraphy_connections_model_version": "1.6.10",
-  "description": "s3Dgraphy connections datamodel including edge types with CIDOC-CRM mappings. v1.6.8 (MIG1-A): graph-scope rights metadata become first-class nodes (DP-65). is_in_paradata_nodegroup.source += AuthorNode/LicenseNode/EmbargoNode and has_paradata_nodegroup.source += GraphNode, so the graph-self node (GraphNode) owns a graph-scope ParadataNodeGroup whose members are the AuthorNode/LicenseNode/EmbargoNode (+ the DP-65 GeoPositionNode shift), replacing the legacy graph.data['author_name'/'license'/'embargo'] fields. The Data Funnel canvas tier now reads these member nodes (one reader per scope); a one-shot load-time migration materialises the legacy fields into nodes. v1.6.7 (BUGFIX-CONN3): closes the two silent follow-ups of CONN2. has_documentation.source gains PropertyNode (judicious widening): the honest reading of a legacy yEd dashed PropertyNode→Document connector is P70i_is_documented_in ('the property is documented in this source'), NOT has_visual_reference (which CONN2 moved to PropertyNode→ResourceNode). The import heuristic (import_graphml.enhance_edge_type) now routes PropertyNode→Document to has_documentation and the rarer CombinerNode/ParadataNode→Document to generic_connection+warning (a combiner aggregates extractors and cites no document; the DTC chain is NOT synthesised at import). Shelf: hat_as_document no longer offers has_visual_reference (a Document attaches via has_documentation/extracted_from); a new hat_as_visual_resource attaches a ResourceNode image via has_visual_reference from a PropertyNode — the correct home after CONN2. No illegal edge is produced or expected. v1.6.6 (BUGFIX-CONN2): closes the two open domain questions on has_visual_reference (E.D. 2026-08-05). SOURCE narrowed to exactly [PropertyNode]: only a property (an asserted quale) is what a visual reference illustrates; the generic ParadataNode entry is dropped, which — because ExtractorNode, CombinerNode and DocumentNode are all subclasses of ParadataNode — now excludes them by class hierarchy (a PropertyNode is neither a sibling nor a parent of the others). The extractor/combiner denied_edges from v1.6.5 are therefore REDUNDANT for this edge but are KEPT as a defensive guard (they still bite if the source is ever broadened back to ParadataNode). TARGET changed from [DocumentNode] to [ResourceNode]: the oddity was that a visual reference pointed at a source-document (E31) rather than at a visual resource. It now points at the resource-layer image node (ResourceNode = E73 Information Object / ExternalResourceReference — the same P67 hinge RM/RMDoc use via has_linked_resource), keeping DocumentNode = fonte. CIDOC stays P138i_has_representation with the target co-typed E36 Visual Item: E36 is a subclass of E73, so co-typing a ResourceNode as E36 is range-consistent (it was NOT, strictly, for an E31 Document). FOLLOW-UPS flagged for E.D. (see end-of report): (a) import_graphml.enhance_edge_type still hardcodes PropertyNode/Combiner/Paradata→DocumentNode ⇒ has_visual_reference (legacy yEd heuristic, now produces an edge this datamodel refuses) — needs a domain decision on what legacy paradata→document edges become; (b) shelf.hat_as_document lists has_visual_reference among the Document-attach edges — it can no longer validate (target is ResourceNode), so a paradata attach silently no longer attaches; a hat_as_visual_resource(ResourceNode)+has_visual_reference path is the proper home. v1.6.5 (BUGFIX-CONN): has_visual_reference is no longer offered FROM an ExtractorNode or a CombinerNode. An extractor toward a document expresses ONLY extracted_from (its relation to the source is the extraction, not an illustration); a combiner aggregates extractors and illustrates nothing. Because ExtractorNode, CombinerNode and PropertyNode are all subclasses of ParadataNode, and has_visual_reference.source lists ParadataNode, simply dropping the two subtypes from the source list would not exclude them (they still match via the parent class). So this is expressed with node_type_restrictions (keyed by RUNTIME node_type, like USNt) using a new denied_edges blacklist (the mirror of allowed_edges): extractor/combiner deny has_visual_reference. PropertyNode and any other legitimate ParadataNode source keep it unchanged. OPEN domain question for E.D.: which paradata node-types may legitimately have a visual reference (today source = PropertyNode/ExtractorNode/CombinerNode/ParadataNode) — extractor/combiner removed; the rest left as-is, not invented. v1.6.1: has_paradata_nodegroup source extended to include EpochNode — an epoch can now own a ParadataNodeGroup holding its temporal-definition properties (e.g. absolute_time_start/end as PropertyNodes with paradata provenance), mirroring how a StratigraphicNode carries its paradata group. v1.6.0 (paired with node datamodel v1.6.0) introduces: bug fix on is_in_paradata_nodegroup (typo 'ProperrtyNOde' → 'PropertyNode'); semantic fix on has_documentation (P104_is_subject_to → P70i_is_documented_in — P104 means 'subject to a legal right', not 'has documentation'); deprecation of has_timebranch as duplicate of is_in_timebranch (the latter is the canonical one — used by import_graphml.py and graphml_patcher.py; the former exists only in config JSON); component list aligned with node datamodel (HDT-O, PROV-O added). HDT-O containment properties (hdto:contains_HDT, hdto:contains_SU, hdto:isPrimary) and physical-relation discriminator subproperties (em:abuts, em:cuts, em:fills, em:overlies, em:bonded_to, em:equals as rdfs:subPropertyOf crmarchaeo:AP11_has_physical_relation) to be added in v1.6.1. v1.5.3 introduced canonical/reverse directionality with verb-based labels for clear socket identification in node editors. v1.5.4 added 'has_visual_reference' edge type. v1.5.5 added 'is_in_location' edge type with context-sensitive CIDOC mapping (P53 for node→location, P89 for the recursive location→location hierarchy) and an optional 'is_primary' boolean attribute (s3d:isPrimary, proposed). v1.6.3: added node_type_restrictions — a per-node-type narrowing of the class-level edge rules (POL5): USN (the NEUTRAL stratigraphic unit, a risparmio) takes is_after/is_before and nothing else, because a void cannot cut, fill, abut or bond. v1.6.4 (POL6): the same restriction, moved to USNt — the tokens went back to their conventional meanings, USN = US negativa (all relations, it is a unit of the sequence) and USNt = US neutra (sequence only).",
+  "s3Dgraphy_connections_model_version": "1.6.11",
+  "description": "s3Dgraphy connections datamodel including edge types with CIDOC-CRM mappings. v1.6.11 (batch ingestion, 2026-08-17): two widenings for bulk assets. has_author.source DTCProcessNode -> DTCNode, so an ACQUISITION event (D12) can carry the author of a whole lot; dtc_had_input.target += DTCNode, so a DECLARED derivation can name a whole acquisition as its input (one input, not 500 edges) — that case projects as prov:wasInformedBy, not prov:used/L10, which range over digital objects and would be wrong for an event. v1.6.8 (MIG1-A): graph-scope rights metadata become first-class nodes (DP-65). is_in_paradata_nodegroup.source += AuthorNode/LicenseNode/EmbargoNode and has_paradata_nodegroup.source += GraphNode, so the graph-self node (GraphNode) owns a graph-scope ParadataNodeGroup whose members are the AuthorNode/LicenseNode/EmbargoNode (+ the DP-65 GeoPositionNode shift), replacing the legacy graph.data['author_name'/'license'/'embargo'] fields. The Data Funnel canvas tier now reads these member nodes (one reader per scope); a one-shot load-time migration materialises the legacy fields into nodes. v1.6.7 (BUGFIX-CONN3): closes the two silent follow-ups of CONN2. has_documentation.source gains PropertyNode (judicious widening): the honest reading of a legacy yEd dashed PropertyNode→Document connector is P70i_is_documented_in ('the property is documented in this source'), NOT has_visual_reference (which CONN2 moved to PropertyNode→ResourceNode). The import heuristic (import_graphml.enhance_edge_type) now routes PropertyNode→Document to has_documentation and the rarer CombinerNode/ParadataNode→Document to generic_connection+warning (a combiner aggregates extractors and cites no document; the DTC chain is NOT synthesised at import). Shelf: hat_as_document no longer offers has_visual_reference (a Document attaches via has_documentation/extracted_from); a new hat_as_visual_resource attaches a ResourceNode image via has_visual_reference from a PropertyNode — the correct home after CONN2. No illegal edge is produced or expected. v1.6.6 (BUGFIX-CONN2): closes the two open domain questions on has_visual_reference (E.D. 2026-08-05). SOURCE narrowed to exactly [PropertyNode]: only a property (an asserted quale) is what a visual reference illustrates; the generic ParadataNode entry is dropped, which — because ExtractorNode, CombinerNode and DocumentNode are all subclasses of ParadataNode — now excludes them by class hierarchy (a PropertyNode is neither a sibling nor a parent of the others). The extractor/combiner denied_edges from v1.6.5 are therefore REDUNDANT for this edge but are KEPT as a defensive guard (they still bite if the source is ever broadened back to ParadataNode). TARGET changed from [DocumentNode] to [ResourceNode]: the oddity was that a visual reference pointed at a source-document (E31) rather than at a visual resource. It now points at the resource-layer image node (ResourceNode = E73 Information Object / ExternalResourceReference — the same P67 hinge RM/RMDoc use via has_linked_resource), keeping DocumentNode = fonte. CIDOC stays P138i_has_representation with the target co-typed E36 Visual Item: E36 is a subclass of E73, so co-typing a ResourceNode as E36 is range-consistent (it was NOT, strictly, for an E31 Document). FOLLOW-UPS flagged for E.D. (see end-of report): (a) import_graphml.enhance_edge_type still hardcodes PropertyNode/Combiner/Paradata→DocumentNode ⇒ has_visual_reference (legacy yEd heuristic, now produces an edge this datamodel refuses) — needs a domain decision on what legacy paradata→document edges become; (b) shelf.hat_as_document lists has_visual_reference among the Document-attach edges — it can no longer validate (target is ResourceNode), so a paradata attach silently no longer attaches; a hat_as_visual_resource(ResourceNode)+has_visual_reference path is the proper home. v1.6.5 (BUGFIX-CONN): has_visual_reference is no longer offered FROM an ExtractorNode or a CombinerNode. An extractor toward a document expresses ONLY extracted_from (its relation to the source is the extraction, not an illustration); a combiner aggregates extractors and illustrates nothing. Because ExtractorNode, CombinerNode and PropertyNode are all subclasses of ParadataNode, and has_visual_reference.source lists ParadataNode, simply dropping the two subtypes from the source list would not exclude them (they still match via the parent class). So this is expressed with node_type_restrictions (keyed by RUNTIME node_type, like USNt) using a new denied_edges blacklist (the mirror of allowed_edges): extractor/combiner deny has_visual_reference. PropertyNode and any other legitimate ParadataNode source keep it unchanged. OPEN domain question for E.D.: which paradata node-types may legitimately have a visual reference (today source = PropertyNode/ExtractorNode/CombinerNode/ParadataNode) — extractor/combiner removed; the rest left as-is, not invented. v1.6.1: has_paradata_nodegroup source extended to include EpochNode — an epoch can now own a ParadataNodeGroup holding its temporal-definition properties (e.g. absolute_time_start/end as PropertyNodes with paradata provenance), mirroring how a StratigraphicNode carries its paradata group. v1.6.0 (paired with node datamodel v1.6.0) introduces: bug fix on is_in_paradata_nodegroup (typo 'ProperrtyNOde' → 'PropertyNode'); semantic fix on has_documentation (P104_is_subject_to → P70i_is_documented_in — P104 means 'subject to a legal right', not 'has documentation'); deprecation of has_timebranch as duplicate of is_in_timebranch (the latter is the canonical one — used by import_graphml.py and graphml_patcher.py; the former exists only in config JSON); component list aligned with node datamodel (HDT-O, PROV-O added). HDT-O containment properties (hdto:contains_HDT, hdto:contains_SU, hdto:isPrimary) and physical-relation discriminator subproperties (em:abuts, em:cuts, em:fills, em:overlies, em:bonded_to, em:equals as rdfs:subPropertyOf crmarchaeo:AP11_has_physical_relation) to be added in v1.6.1. v1.5.3 introduced canonical/reverse directionality with verb-based labels for clear socket identification in node editors. v1.5.4 added 'has_visual_reference' edge type. v1.5.5 added 'is_in_location' edge type with context-sensitive CIDOC mapping (P53 for node→location, P89 for the recursive location→location hierarchy) and an optional 'is_primary' boolean attribute (s3d:isPrimary, proposed). v1.6.3: added node_type_restrictions — a per-node-type narrowing of the class-level edge rules (POL5): USN (the NEUTRAL stratigraphic unit, a risparmio) takes is_after/is_before and nothing else, because a void cannot cut, fill, abut or bond. v1.6.4 (POL6): the same restriction, moved to USNt — the tokens went back to their conventional meanings, USN = US negativa (all relations, it is a unit of the sequence) and USNt = US neutra (sequence only).",
   "components": [
     "CIDOC-CRM",
     "CRMarchaeo",
@@ -682,7 +682,7 @@
     "has_author": {
       "name": "has_author",
       "label": "Has author",
-      "description": "Represents the connection of a node with its author. Target can be an AuthorNode (human) or AuthorAINode (AI-assisted authoring). Source covers the full range of EM node types so that the resolver can walk from any scope level down to the author.",
+      "description": "Represents the connection of a node with its author. Target can be an AuthorNode (human) or AuthorAINode (AI-assisted authoring). Source covers the full range of EM node types so that the resolver can walk from any scope level down to the author. SOURCE WIDENED 2026-08-16 (asset DTC protocol): ResourceNode joins the list. 'Who took this photograph' is exactly prov:wasAttributedTo on an information object, and the mapping is already domain-neutral — the omission was an oversight of scope, not a semantic boundary: the list exists so the resolver can walk from ANY scope down to the author, and a resource is a scope somebody attributes. It is also the shape the asset enrichment protocol needs, where the AUTHOR of the bytes (possibly absent, possibly dead) is declared by an ATTRIBUTOR who is somebody else (s3dgraphy.rights.enrich_asset_dtc, docs/asset-dtc-protocol.md).",
       "reverse": {
         "name": "is_author_of",
         "label": "Is author of"
@@ -705,13 +705,15 @@
           "CombinerNode",
           "PropertyNode",
           "EpochNode",
-          "DTCProcessNode",
-          "NarrativeNode"
+          "DTCNode",
+          "NarrativeNode",
+          "ResourceNode"
         ],
         "target": [
           "AuthorNode",
           "AuthorAINode"
-        ]
+        ],
+        "_note": "SOURCE WIDENED 2026-08-17 (batch ingestion): DTCProcessNode -> DTCNode, the DTC event BASE class, so an ACQUISITION (DTCAcquisitionNode, D12) can carry an author too — the same fix already applied to dtc_had_input/dtc_had_output for the same reason. A campaign of four hundred photographs is attributed ONCE, on the event that brought them in, and the reader (s3dgraphy.rights) already walks the chain to find it; without this the batch attribution silently degraded to generic_connection and the licence became unreadable."
       }
     },
     "has_geoposition": {
@@ -1320,15 +1322,16 @@
         "cidoc_extension": "CRMdig",
         "extension_mapping": "prov:used",
         "extension_name": "PROV-O",
-        "rationale": "crmdig:L10_had_input (D7 Digital Machine Event -> input digital object). Dual-emitted with prov:used (Activity used Entity) — same direction (Process -> input Resource) — so CRMdig and PROV-O readers both see the acquisition consumption. Target is the Resource (ResourceNode); the input is a resource, symmetric to the output."
+        "rationale": "crmdig:L10_had_input (D7 Digital Machine Event -> input digital object). Dual-emitted with prov:used (Activity used Entity) — same direction (Process -> input Resource) — so CRMdig and PROV-O readers both see the acquisition consumption. Target is the Resource (ResourceNode); the input is a resource, symmetric to the output. TARGET WIDENED 2026-08-17: when the target is a DTC EVENT (an acquisition consumed as a whole lot) neither L10_had_input nor prov:used holds — both range over digital OBJECTS, and an event is not one. That case projects as prov:wasInformedBy (activity -> activity), applied in the RDF exporter (_serialize_edge); the property-graph edge stays the one edge type, because 'this output came from that input' is one sentence whether the input is a file or a campaign."
       },
       "allowed_connections": {
-        "_note": "Source is the DTC event BASE class: both chunk types link to their Resources — DTCProcessNode (genesis, D7) and DTCAcquisitionNode (acquisition/ingestion, D12), per the dtc_nodes section note. Listing only DTCProcessNode used to pass by accident, because the old validator could not resolve the name and fell back to accepting anything.",
+        "_note": "Source is the DTC event BASE class: both chunk types link to their Resources — DTCProcessNode (genesis, D7) and DTCAcquisitionNode (acquisition/ingestion, D12), per the dtc_nodes section note. Listing only DTCProcessNode used to pass by accident, because the old validator could not resolve the name and fell back to accepting anything. TARGET 2026-08-17: DTCNode joins ResourceNode so a DECLARED derivation can name a whole ACQUISITION as its input — the serial node exists precisely so a campaign of 500 photographs is one input and not 500 edges. The RDF projection distinguishes the two cases (see mapping.rationale); dtc_derived_from stays resource -> resource, because a shortcut between files cannot be written to an event, and that is reported rather than faked.",
         "source": [
           "DTCNode"
         ],
         "target": [
-          "ResourceNode"
+          "ResourceNode",
+          "DTCNode"
         ]
       }
     },
@@ -1402,4 +1405,4 @@
       }
     }
   }
-}
+}

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/__init__.py

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

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/acquisition/__init__.py

@@ -16,7 +16,8 @@ from .descriptor import (
     AcquisitionError,
     schema,
 )
-from .mapping import apply_mapping, available_mappings, fs_record, load_mapping
+from .mapping import (ACCESS_MODES, apply_mapping, available_mappings,
+                      fs_record, load_mapping, uri_record)
 from .acquire import acquire_from_descriptor
 
 __all__ = [
@@ -28,5 +29,8 @@ __all__ = [
     "apply_mapping",
     "available_mappings",
     "fs_record",
+    # the asset nobody downloads: a URI plus how you reach it
+    "uri_record",
+    "ACCESS_MODES",
     "acquire_from_descriptor",
 ]

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/acquisition/acquire.py

@@ -92,9 +92,19 @@ def acquire_from_descriptor(descriptor: Any, shelf: Any = None
     name = desc.asset.get("name") or (ref.rstrip("/").rsplit("/", 1)[-1] if ref else rid[:8])
     origin = desc.origin()
 
-    # 1) Resource on the shelf (reuse-not-duplicate; origin preserved)
+    # 1) Resource on the shelf (reuse-not-duplicate; origin preserved).
+    #
+    # `media_type` / `size` / `access` are written only when the descriptor
+    # carried them — the fs mapping knows a file's size, a bare URI does not, and
+    # a resource that never said its size must not start claiming zero. They are
+    # here because they are what the shelf TABLE shows: without them the column
+    # would be empty for every entry and a reader would think the shelf lost it.
     entry = add_to_shelf(shelf, ref, resource_id=rid, name=name,
-                         resource_type=_resource_type(desc), origin=origin)
+                         resource_type=_resource_type(desc), origin=origin,
+                         media_type=desc.asset.get("media_type") or None,
+                         size=desc.asset.get("size") or None,
+                         access=origin.get("access"),
+                         role=desc.asset.get("role") or None)
 
     # 2) acquisition event — a distinct DTC event type (crmdig:D12), literals for
     #    the opaque upstream source (Tier 0: no genesis sub-graph)

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/acquisition/descriptor.py

@@ -97,9 +97,27 @@ class AcquisitionDescriptor:
 
     def origin(self) -> Dict[str, Any]:
         """The capability/origin envelope carried onto the shelf entry (for
-        downstream tier badges): repo + capabilities + scope."""
-        return {
+        downstream tier badges): repo + capabilities + scope, and — when the
+        asset says so — how it is REACHED.
+
+        ``access`` rides in the origin rather than in a channel of its own
+        because that is exactly what it is: a fact about where this resource came
+        from and how to get back to it. A URI-only entry has no bytes here, so
+        its origin is the only place that can answer "and how do I open it?".
+        """
+        out: Dict[str, Any] = {
             "repo": self.source.get("repo_id"),
             "capabilities": self.capabilities(),
             "scope": (self.payload_graph or {}).get("scope"),  # None in Tier 0
         }
+        access = self.asset.get("access")
+        if access:
+            out["access"] = (dict(access) if isinstance(access, dict)
+                             else {"mode": str(access)})
+        if self.asset.get("protocol"):
+            out["protocol"] = self.asset.get("protocol")
+        return out
+
+    def access(self) -> Optional[Dict[str, Any]]:
+        """``{mode, endpoint?}`` when the asset declared how it is reached."""
+        return self.origin().get("access")

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev16}/src/s3dgraphy/acquisition/mapping.py

@@ -25,7 +25,7 @@ from __future__ import annotations
 import copy
 import json
 from pathlib import Path
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 _MAPPINGS_DIR = (Path(__file__).resolve().parent.parent
                  / "JSON_config" / "acquisition_mappings")
@@ -83,6 +83,77 @@ _FS_MEDIA_TYPES = {
 }
 
 
+#: How you get to a resource you did not copy. TWO modes, because the practical
+#: question a colleague asks is binary: can I click this, or do I have to ask
+#: for access?
+#:
+#: * ``open`` — the link is freely reachable;
+#: * ``subscribe`` — you subscribe/register/are granted access first (an
+#:   institutional repository, a shared drive, a IIIF endpoint behind a login).
+#:
+#: This is deliberately NOT a rights statement: `rights.license` says what you
+#: may do with the object, `access.mode` says whether you can reach it at all.
+#: A CC-BY image behind a login is both, and conflating them would make one of
+#: the two unaskable.
+ACCESS_MODES = ("open", "subscribe")
+
+
+def uri_record(uri: str, *, protocol: Optional[str] = None,
+               access: Optional[Any] = None, name: Optional[str] = None,
+               media_type: Optional[str] = None,
+               repo_id: Optional[str] = None) -> Dict[str, Any]:
+    """Build a raw record for the ``uri`` mapping from a bare **URI**.
+
+    The asset nobody downloads: somebody pastes a link and what enters the shelf
+    is the URI plus the protocol it is reached through. **No bytes are copied**
+    and no object store is touched — that is the point, and the difference from
+    :func:`fs_record`.
+
+    ``access`` is ``{"mode": "open"|"subscribe", "endpoint": …}``, or just the
+    mode as a string (the common case). ``record_id`` is the URI itself, so
+    re-acquiring the same link lands on the same stable Resource id and the shelf
+    does not grow a second entry — the idempotence the fs record gets from the
+    absolute path.
+
+    Returns ``{uri, name, protocol, media_type, access, repo_id, record_id,
+    record_url}``.
+    """
+    import mimetypes
+    from urllib.parse import urlsplit
+
+    text = (uri or "").strip()
+    if not text:
+        raise ValueError("a URI-only entry needs a URI")
+    parts = urlsplit(text)
+    scheme = (protocol or parts.scheme or "").lower() or "http"
+    if isinstance(access, str):
+        access = {"mode": access}
+    access = dict(access or {})
+    mode = str(access.get("mode") or "open").lower()
+    if mode not in ACCESS_MODES:
+        raise ValueError(f"access.mode must be one of {list(ACCESS_MODES)}, "
+                         f"got {access.get('mode')!r}")
+    access["mode"] = mode
+    tail = parts.path.rstrip("/").rsplit("/", 1)[-1]
+    guessed = media_type or (_FS_MEDIA_TYPES.get(tail.rsplit(".", 1)[-1].lower())
+                             if "." in tail else None) \
+        or (mimetypes.guess_type(tail)[0] if "." in tail else None) or ""
+    return {
+        "uri": text,
+        # The host is the honest name when the tail is not a filename: a record
+        # page ends in an id, and "12345" is not what anybody is looking for.
+        "name": name or (tail if "." in tail else (parts.netloc or text)),
+        "protocol": scheme,
+        "media_type": guessed,
+        "access": access,
+        # …and the repo is the HOST unless told otherwise, so two links from the
+        # same institution group together without anybody configuring a repo.
+        "repo_id": repo_id or (parts.netloc or "uri"),
+        "record_id": text,
+        "record_url": text,
+    }
+
+
 def fs_record(path: str) -> Dict[str, Any]:
     """Build a raw FILE-SYSTEM record for the ``fs`` mapping from a local ``path``:
     ``{filename, path, record_id, record_url, size, ext, media_type}``. The local