s3dgraphy 1.6.0.dev14__tar.gz → 1.6.0.dev15__tar.gz

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

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

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

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev15}/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.dev15}/src/s3dgraphy/__init__.py

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

{s3dgraphy-1.6.0.dev14 → s3dgraphy-1.6.0.dev15}/src/s3dgraphy/api.py

@@ -445,9 +445,19 @@ def promote_resource(graph: Graph, resource_id: str, *, url: str, sha256: str,
                      author: Optional[str] = None, at: Optional[str] = None,
                      source_id: Optional[str] = None,
                      link_to: Optional[str] = None,
-                     name: Optional[str] = None) -> Dict[str, Any]:
-    """Publish a resource: `residency="reference"` + url + checksum, and record
-    the genesis as a DTC transformation (crmdig:D7), attributed and dated.
+                     name: Optional[str] = None,
+                     residency: str = "reference",
+                     corpus: Optional[Graph] = None) -> Dict[str, Any]:
+    """Publish a resource: url + checksum + a residency, and record the genesis
+    as a DTC transformation (crmdig:D7), attributed and dated.
+
+    `residency` says which true sentence this is — `reference` (a store the study
+    points at, the default and the original DP-76 one) or `resident` (the ROOM's
+    store: em-server is in the bytes' path, so the gate and the licence travel
+    with them). `corpus` is the offline→online moment: hand it the container's
+    DOCUMENTATION member and the D7 event is recorded THERE, with the asset
+    mirrored into it under its own id — the shared leaf between the study and its
+    provenance.
 
     The inverse of `import_geometry` and the activation of DP-76: the model stops
     living inside a .blend and becomes an asset the study POINTS AT. Returns the
@@ -457,7 +467,87 @@ def promote_resource(graph: Graph, resource_id: str, *, url: str, sha256: str,
     from .publication import promote_resource as _promote
     return _promote(graph, resource_id, url=url, sha256=sha256,
                     media_type=media_type, author=author, at=at,
-                    source_id=source_id, link_to=link_to, name=name).as_dict()
+                    source_id=source_id, link_to=link_to, name=name,
+                    residency=residency, corpus=corpus).as_dict()
+
+
+# ── the DOCUMENTATION member: the DTC corpus ─────────────────────────────────
+#
+# A study's provenance is a graph of a different KIND — acquisitions,
+# transformations and the files they are about, a forest that shares its leaves.
+# It travels as a container member of its own (`em_collection: "DTCCorpus"`), the
+# way the shelf does. On the api surface because the tools author it: EMStudio's
+# Documentation tab, EMtools at promotion, an ingest.
+
+def dtc_corpus(container: Any, *, create: bool = True) -> Optional[Graph]:
+    """The container's documentation member — found by its marker, or made.
+
+    `create=False` answers "is there one?" without making one: a panel that
+    showed an empty corpus it had just invented would be reporting its own side
+    effect. See :mod:`s3dgraphy.dtc.corpus`.
+    """
+    from .dtc.corpus import corpus_of
+    return corpus_of(container, create=create)
+
+
+def merge_corpus(resident: Any, incoming: Any) -> Dict[str, Any]:
+    """Fold one DTC corpus into another, per UUID. Returns the report as a dict.
+
+    On the api surface because another PROCESS performs it: em-server merges a
+    project's **file** corpus into the instance's **resident** one when a study is
+    promoted or joins a room, and it must not invent a second answer to "who
+    wins". Same merge the container uses. See :mod:`s3dgraphy.dtc.corpus`.
+    """
+    from .dtc.corpus import merge_corpus as _merge
+    return _merge(resident, incoming)
+
+
+def is_dtc_corpus(graph: Any) -> bool:
+    """Is this graph (or raw member section) a DTC corpus?"""
+    from .dtc.corpus import is_dtc_corpus as _is
+    return _is(graph)
+
+
+def new_dtc_corpus(graph_id: Optional[str] = None,
+                   name: Optional[str] = None) -> Graph:
+    """An empty corpus, tagged as one — for a caller building a container."""
+    from .dtc.corpus import DTC_CORPUS_MEMBER_ID, new_corpus
+    return new_corpus(graph_id or DTC_CORPUS_MEMBER_ID, name)
+
+
+def dtc_corpus_summary(corpus: Any) -> Dict[str, Any]:
+    """What is in the corpus, in its own terms: roots (acquisitions),
+    transformations, resources, outputs, **shared leaves** (a file more than one
+    event consumed — what a matrix could not draw), orphans, and anything
+    FOREIGN that does not belong in a corpus at all."""
+    from .dtc.corpus import dtc_corpus_summary as _summary
+    return _summary(corpus)
+
+
+def store_backed_geometry(graph: Graph) -> List[Dict[str, Any]]:
+    """The geometry this graph describes that LIVES in the store — resident only.
+
+    The consuming half of DP-76, and the answer a 3D tool needs before it can
+    materialise anything: one record per (facet, resource), each with the digest
+    to fetch by and the epochs/units to bind to. On the api surface because the
+    caller is another PROCESS (EMtools in Blender, a headless publisher), and
+    because the walk belongs to the library — a consumer that re-derived
+    `has_linked_resource` would drift the day a facet is added.
+
+    `reference` resources are deliberately absent: their bytes are outside the
+    store (and outside em-server's gate), so a digest cannot fetch them and a
+    path is meaningful on one machine only. See
+    :mod:`s3dgraphy.geometry.store_backed`.
+    """
+    from .geometry.store_backed import store_backed_geometry as _geometry
+    return _geometry(graph)
+
+
+def geometry_summary(graph: Graph) -> Dict[str, Any]:
+    """What is fetchable, and what the graph describes that is NOT — so a panel
+    can show the whole truth rather than the smaller half of it."""
+    from .geometry.store_backed import geometry_summary as _summary
+    return _summary(graph)
 
 
 def promotion_delta(graph: Graph, result: Dict[str, Any]) -> Dict[str, Any]:
@@ -472,6 +562,61 @@ def promotion_delta(graph: Graph, result: Dict[str, Any]) -> Dict[str, Any]:
     ))
 
 
+# ── narrative queries (DP-79 P4) ──────────────────────────────────────────────
+#
+# The point of authoring a study ON the graph: the interpretation and the
+# evidence are one dataset, so questions that cross them have answers. These
+# read the em.json in memory — the same content the RDF projection restates as
+# `P67_refers_to` — so there is no index to rebuild and no answer that can be
+# stale. See :mod:`s3dgraphy.narrative.query`.
+
+def narrative_citations(graph: Graph) -> List[Dict[str, Any]]:
+    """Every embed in every narrative, flattened, with its chapter/block position."""
+    from .narrative.query import citations
+    return citations(graph)
+
+
+def narratives_citing(graph: Graph, node_id: str) -> List[Dict[str, Any]]:
+    """Where a node is cited, **in reading order**.
+
+    SPARQL over the projection answers the set version of this; only the
+    property graph can answer the ordered one, because the chapters are
+    deliberately not reified in RDF.
+    """
+    from .narrative.query import narratives_citing as _q
+    return _q(graph, node_id)
+
+
+def narratives_on_retracted_sources(graph: Graph) -> List[Dict[str, Any]]:
+    """Citations that no longer stand — a withdrawn source, or a reference that
+    does not resolve at all. Reported together, separated by `reason`: they need
+    different work."""
+    from .narrative.query import narratives_on_retracted_sources as _q
+    return _q(graph)
+
+
+def interpretive_coverage(graph: Graph, *, kind: str = "epoch"
+                          ) -> List[Dict[str, Any]]:
+    """How much has been WRITTEN about each epoch (or activity), counting a
+    citation of a member as covering the whole. `narratives: 0` is the row
+    people are actually looking for."""
+    from .narrative.query import interpretive_coverage as _q
+    return _q(graph, kind=kind)
+
+
+def unexplained_reconstructions(graph: Graph) -> List[Dict[str, Any]]:
+    """3D somebody built and nobody explained: a model with a scene that no
+    narrative cites, directly or through the unit it represents."""
+    from .narrative.query import unexplained_reconstructions as _q
+    return _q(graph)
+
+
+def narrative_report(graph: Graph) -> Dict[str, Any]:
+    """All four answers in one deterministic dict."""
+    from .narrative.query import narrative_report as _q
+    return _q(graph)
+
+
 # ── the study, as a catalogue sees it ─────────────────────────────────────────
 def study_metadata(container: Any, *, study_id: Optional[str] = None
                    ) -> Dict[str, Any]:
@@ -492,20 +637,166 @@ def study_metadata(container: Any, *, study_id: Optional[str] = None
     return _card(container, study_id=study_id)
 
 
+# ── one asset's rights, read off the graph ────────────────────────────────────
+def asset_rights(document: Any, digest: str, *, today: Any = None
+                 ) -> Optional[Dict[str, Any]]:
+    """What the graph says about the asset with this digest — licence, embargo,
+    authors — or `None` when it has never heard of it.
+
+    On the api surface for the same reason `study_metadata` is: another PROCESS
+    asks it. An asset store must decide whether to serve bytes, and the decision
+    belongs to the graph — em-server CONSULTS this rather than keeping a second
+    copy of an embargo that lives in a document people edit.
+
+    See :mod:`s3dgraphy.rights` for how the walk works and why the rights are
+    read both directly off the resource and through its DTC chain.
+    """
+    from .rights import rights_for_digest
+    return rights_for_digest(document, digest, today=today)
+
+
+def enrich_asset_dtc(graph: Any, checksum: str, *, attributor: Optional[str],
+                     author: Any = None, license: Any = None, embargo: Any = None,
+                     at: Optional[str] = None, author_name: Optional[str] = None,
+                     reason: Optional[str] = None) -> Dict[str, Any]:
+    """Declare an asset's rights — as an ACT, signed by whoever declares it.
+
+    The writing half of `asset_rights`. On the api surface because it is a
+    PROTOCOL other tools perform: EMStudio at upload, EMtools, the field
+    chatbot, an ECHOES/ECCCH ingest. The contract is written down once, in
+    `docs/asset-dtc-protocol.md`, so those tools do not each invent their own.
+
+    The distinction it exists for: the **author** is who made the data, the
+    **attributor** is who says so, and they are frequently not the same person —
+    attribution happens later, sometimes posthumously, usually by a cataloguer.
+    See :mod:`s3dgraphy.rights`.
+    """
+    from .rights import enrich_asset_dtc as _enrich
+    return _enrich(graph, checksum, attributor=attributor, author=author,
+                   license=license, embargo=embargo, at=at,
+                   author_name=author_name, reason=reason)
+
+
+# ── ingestion in bulk: a lot, a declared chain, and who uses a file ──────────
+#
+# The plural of the act above. On the api surface for the same reason: several
+# tools ingest (EMStudio's Assets tab, EMtools, a field ingest), and a rule that
+# lived in one of them would be re-invented differently by the next.
+# See :mod:`s3dgraphy.dtc.ingest`.
+
+def bucket_acquisition(graph: Graph, resources: Any, *,
+                       acquisition_id: Optional[str] = None,
+                       name: Optional[str] = None,
+                       dtc_kind: Optional[str] = None,
+                       metadata: Optional[Dict[str, Any]] = None,
+                       author: Optional[str] = None,
+                       at: Optional[str] = None) -> Dict[str, Any]:
+    """Group N resources (ids or digests) under ONE acquisition event (D12).
+
+    The serial node: a campaign of four hundred photographs is one thing in the
+    graph, not four hundred top-level entries. The membership is the
+    `dtc_had_output` edges; `data.member_count` is a cache of their number.
+    """
+    from .dtc.ingest import DEFAULT_ACQUISITION_KIND, bucket_acquisition as _bucket
+    return _bucket(graph, list(resources or ()), acquisition_id=acquisition_id,
+                   name=name, dtc_kind=dtc_kind or DEFAULT_ACQUISITION_KIND,
+                   metadata=metadata, author=author, at=at)
+
+
+def acquisition_members(graph: Graph, acquisition_id: str) -> List[str]:
+    """The resources an acquisition brought in — live, read off the edges."""
+    from .dtc.ingest import acquisition_members as _members
+    return _members(graph, acquisition_id)
+
+
+def declare_derivation(graph: Graph, output: str, inputs: Any, *,
+                       tool: Optional[str] = None,
+                       process_id: Optional[str] = None,
+                       name: Optional[str] = None,
+                       author: Optional[str] = None,
+                       at: Optional[str] = None) -> Dict[str, Any]:
+    """Declare that `output` came out of `inputs`, with `tool` named.
+
+    DECLARED, never inferred: nobody guesses that an orthophoto came from that
+    flight because the dates line up. An input may be a resource or a whole
+    acquisition.
+    """
+    from .dtc.ingest import declare_derivation as _declare
+    return _declare(graph, output, list(inputs or ()), tool=tool,
+                    process_id=process_id, name=name, author=author, at=at)
+
+
+def derivation_chain(graph: Graph, resource: str) -> Dict[str, Any]:
+    """What made this file and what consumed it — one hop each way."""
+    from .dtc.ingest import derivation_chain as _chain
+    return _chain(graph, resource)
+
+
+def attribute_batch(graph: Graph, acquisition_id: str, *,
+                    attributor: Optional[str], author: Any = None,
+                    author_name: Optional[str] = None, license: Any = None,
+                    embargo: Any = None, reason: Optional[str] = None,
+                    at: Optional[str] = None,
+                    propagate: bool = False) -> Dict[str, Any]:
+    """Licence / author / embargo for a whole lot, signed by its attributor.
+
+    The batch twin of `enrich_asset_dtc`, hung on the acquisition — which is how
+    `asset_rights` already reads it. `propagate=True` also stamps each member,
+    which is a copy and can therefore disagree: off by default.
+    """
+    from .dtc.ingest import attribute_batch as _attribute
+    return _attribute(graph, acquisition_id, attributor=attributor,
+                      author=author, author_name=author_name, license=license,
+                      embargo=embargo, reason=reason, at=at,
+                      propagate=propagate)
+
+
+def resource_usages(graph: Graph, resource: str) -> List[Dict[str, Any]]:
+    """Every live node that refers to this asset, classified by HOW.
+
+    The question to answer before replacing a file — and the inspector's
+    "used by…". Roles: reference / annotation / chain / rights / other.
+    """
+    from .dtc.ingest import resource_usages as _usages
+    return _usages(graph, resource)
+
+
+def unused_resources(graph: Graph) -> List[Dict[str, Any]]:
+    """Files nothing points at. Not a fault — a list somebody may want."""
+    from .dtc.ingest import unused_resources as _unused
+    return _unused(graph)
+
+
+def batch_summary(graph: Graph, acquisition_id: str) -> Dict[str, Any]:
+    """One acquisition as a panel shows it: the event, its members, their
+    rights (inherited or their own). Read-only."""
+    from .dtc.ingest import batch_summary as _summary
+    return _summary(graph, acquisition_id)
+
+
 # ── IIIF: the image layer, as a projection ────────────────────────────────────
 def iiif_manifest(graph: Graph, target_id: str, *, image_base: str,
                   manifest_id: Optional[str] = None,
                   sizes: Optional[Dict[str, Any]] = None,
-                  label: Optional[str] = None) -> Dict[str, Any]:
+                  label: Optional[str] = None,
+                  document: Any = None,
+                  withhold_embargoed: bool = True) -> Dict[str, Any]:
     """A IIIF **Presentation 3** manifest for a resource or a document.
 
     One canvas per image, with the graph's annotation regions projected onto it
     as W3C Web Annotations. The graph is the source; the manifest is a view, and
     nothing about it is written back. See :mod:`s3dgraphy.iiif`.
+
+    `document` (the container this graph came from) turns on the RIGHTS half:
+    each image's licence travels in the manifest, and an image under a running
+    embargo is left out with the fact recorded. Without it the manifest is
+    exactly what it was before — a caller that knows nothing about rights is not
+    made to care.
     """
     from .iiif import iiif_manifest as _manifest
     return _manifest(graph, target_id, image_base=image_base,
-                     manifest_id=manifest_id, sizes=sizes, label=label)
+                     manifest_id=manifest_id, sizes=sizes, label=label,
+                     document=document, withhold_embargoed=withhold_embargoed)
 
 
 def iiif_image_service(resource, base: str) -> Optional[Dict[str, Any]]:
@@ -862,13 +1153,20 @@ def write_ai_draft(graph: Graph, target: str, text: str, *, model: str,
 
 
 # ── EM Narrative — print projection (L1) ──────────────────────────────────────
-def export_narrative_latex(graph: Graph, narrative_id: str) -> Dict[str, str]:
+def export_narrative_latex(graph: Graph, narrative_id: str, *,
+                           fragment: bool = False,
+                           figures: Optional[Dict[str, Any]] = None,
+                           figure_suffix: str = ".pdf") -> Dict[str, str]:
     """Project a NarrativeNode to LaTeX + BibTeX: ``{"tex": …, "bib": …}``.
 
     An **exporter, not a renderer**: it returns two strings and needs no LaTeX
-    engine. ``tex`` is a body to ``\\input{}`` into your own preamble (chapters →
-    ``\\section``/``\\subsection``, prose → prose, embeds → figures or
-    ``\\cite``), ``bib`` one entry per cited source with keys derived
+    engine. ``tex`` is a **complete, compilable document** — a minimal preamble
+    (inputenc/fontenc/babel/graphicx/hyperref), the chapters as ``\\section``s,
+    and the cited sources as an inline ``thebibliography`` so one file yields one
+    PDF. ``fragment=True`` returns the old BODY instead, to ``\\input{}`` into
+    your own preamble (chapters become ``\\subsection``s under your title).
+
+    ``bib`` is one entry per cited source with keys derived
     deterministically from the node ids (:func:`bib_key`), so citations and
     entries cannot drift and a re-export is stable.
 
@@ -879,7 +1177,8 @@ def export_narrative_latex(graph: Graph, narrative_id: str) -> Dict[str, str]:
 
     Raises ``KeyError`` if ``narrative_id`` names no narrative in the graph."""
     from .exporter.latex_exporter import export_narrative_latex as _e
-    return _e(graph, narrative_id)
+    return _e(graph, narrative_id, fragment=fragment, figures=figures,
+              figure_suffix=figure_suffix)
 
 
 def bib_key(node_id: str) -> str:
@@ -890,7 +1189,9 @@ def bib_key(node_id: str) -> str:
 
 
 def bake_narrative(graph: Graph, narrative_id: str, *,
-                   base_dir: Optional[str] = None) -> Any:
+                   base_dir: Optional[str] = None,
+                   figures: Optional[Dict[str, bytes]] = None,
+                   figure_suffix: str = ".png") -> Any:
     """Resolve a live narrative into a **static snapshot** (``BakedNarrative``).
 
     A narrative's embeds mean "whatever this node says now" — which is what makes
@@ -911,13 +1212,86 @@ def bake_narrative(graph: Graph, narrative_id: str, *,
     ``base_dir`` is what relative image locators resolve against (normally the
     folder holding the em.json). Raises ``KeyError`` if ``narrative_id`` names no
     narrative.
+
+    ``figures`` are images a CLIENT rendered, keyed by
+    :func:`s3dgraphy.narrative.bake.figure_key` — see there for why a matrix
+    arrives from outside instead of being drawn here.
+
     """
     from .narrative.bake import bake_narrative as _b
-    return _b(graph, narrative_id, base_dir=base_dir)
+    return _b(graph, narrative_id, base_dir=base_dir, figures=figures,
+              figure_suffix=figure_suffix)
+
+
+def export_narrative_html(graph: Graph, narrative_id: str, *,
+                          base_dir: Optional[str] = None,
+                          generated_at: str = "",
+                          figures: Optional[Dict[str, bytes]] = None,
+                          figure_suffix: str = ".png") -> str:
+    """Render a narrative to **one self-contained HTML file** — the format for
+    the reader who is simply handed a link or an attachment.
+
+    The third rendering of the same bake (:func:`bake_narrative`), which is why
+    it cannot disagree with the DocX or the LaTeX about what the narrative said.
+    Images are inlined as data URIs and the CSS travels in the file: a folder of
+    loose assets is a document that arrives broken the first time it is emailed.
+
+    Needs nothing beyond the standard library — unlike DocX, it cannot be
+    unavailable. `generated_at` is stamped into the footer when given; it is a
+    parameter rather than a call to the clock so the same bake renders to the
+    same bytes twice.
+    
+    ``figures``/``figure_suffix`` carry images a CLIENT rendered (keyed by
+    :func:`s3dgraphy.narrative.bake.figure_key`, e.g. ``"matrix:EP1"``): a matrix
+    is drawn by the layout engine, the layout engine lives in the client, and this
+    library does not grow a browser. Without them the visual embeds stay
+    placeholders — the export never breaks, it just says less.
+
+    """
+    from .exporter.html_exporter import render_html
+    return render_html(bake_narrative(graph, narrative_id, base_dir=base_dir,
+                                      figures=figures,
+                                      figure_suffix=figure_suffix),
+                       generated_at=generated_at)
+
+
+def export_narrative_ipynb(graph: Graph, narrative_id: str, *,
+                           emjson_url: Optional[str] = None,
+                           figures: Optional[Dict[str, bytes]] = None,
+                           figure_suffix: str = ".png") -> str:
+    """Render a narrative to a **Jupyter notebook** — the fourth output, and the
+    only LIVE one.
+
+    The other three (DocX, LaTeX, HTML) are snapshots: they resolve the embeds
+    once and freeze them. This one does the opposite — the prose becomes
+    markdown and every embed becomes a **code cell that queries the graph**, so
+    the notebook contains the questions and the reader runs them. Re-run it in a
+    year and it says what the study says then.
+
+    `emjson_url` is written into the loader cell (the Catalog's `/emjson` route,
+    typically). Without it the cell names a local file and the reader edits one
+    line. The notebook deliberately carries **no copy of the graph**: a copy is
+    what would make it a snapshot again.
+
+    Needs nothing beyond the standard library — the notebook is a dict and
+    `json` is the whole serialiser.
+    
+    ``figures``/``figure_suffix`` carry images a CLIENT rendered (keyed by
+    :func:`s3dgraphy.narrative.bake.figure_key`, e.g. ``"matrix:EP1"``): a matrix
+    is drawn by the layout engine, the layout engine lives in the client, and this
+    library does not grow a browser. Without them the visual embeds stay
+    placeholders — the export never breaks, it just says less.
+
+    """
+    from .exporter.ipynb_exporter import export_narrative_ipynb as _e
+    return _e(graph, narrative_id, emjson_url=emjson_url, figures=figures,
+              figure_suffix=figure_suffix)
 
 
 def export_narrative_docx(graph: Graph, narrative_id: str, *,
-                          base_dir: Optional[str] = None) -> bytes:
+                          base_dir: Optional[str] = None,
+                          figures: Optional[Dict[str, bytes]] = None,
+                          figure_suffix: str = ".png") -> bytes:
     """Render a narrative to **.docx** bytes — the format for the normal reader.
 
     Bakes first (:func:`bake_narrative`), then places the result: chapter
@@ -933,9 +1307,18 @@ def export_narrative_docx(graph: Graph, narrative_id: str, *,
     Raises :class:`MissingDependency` if python-docx is not installed — the bake
     itself does not need it, so ``bake_narrative`` keeps working and only the
     rendering is unavailable.
+    
+    ``figures``/``figure_suffix`` carry images a CLIENT rendered (keyed by
+    :func:`s3dgraphy.narrative.bake.figure_key`, e.g. ``"matrix:EP1"``): a matrix
+    is drawn by the layout engine, the layout engine lives in the client, and this
+    library does not grow a browser. Without them the visual embeds stay
+    placeholders — the export never breaks, it just says less.
+
     """
     from .exporter.docx_exporter import render_docx
-    return render_docx(bake_narrative(graph, narrative_id, base_dir=base_dir))
+    return render_docx(bake_narrative(graph, narrative_id, base_dir=base_dir,
+                                      figures=figures,
+                                      figure_suffix=figure_suffix))
 
 
 # ── XLSX mapping ──────────────────────────────────────────────────────────────