cjm-context-graph-layer 0.0.2__py3-none-any.whl

cjm_context_graph_layer/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.2"

cjm_context_graph_layer/_modidx.py

@@ -0,0 +1,63 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/cjm-context-graph-layer',
+                'doc_host': 'https://cj-mills.github.io',
+                'git_url': 'https://github.com/cj-mills/cjm-context-graph-layer',
+                'lib_path': 'cjm_context_graph_layer'},
+  'syms': { 'cjm_context_graph_layer.declare': { 'cjm_context_graph_layer.declare.Derivation': ( 'declare.html#derivation',
+                                                                                                 'cjm_context_graph_layer/declare.py'),
+                                                 'cjm_context_graph_layer.declare.derivation_to_graph': ( 'declare.html#derivation_to_graph',
+                                                                                                          'cjm_context_graph_layer/declare.py')},
+            'cjm_context_graph_layer.edits': { 'cjm_context_graph_layer.edits.SpineEdit': ( 'edits.html#spineedit',
+                                                                                            'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.SpineEdit.__post_init__': ( 'edits.html#spineedit.__post_init__',
+                                                                                                          'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.SpineEdit.from_dict': ( 'edits.html#spineedit.from_dict',
+                                                                                                      'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.SpineEdit.to_dict': ( 'edits.html#spineedit.to_dict',
+                                                                                                    'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.SpineEditError': ( 'edits.html#spineediterror',
+                                                                                                 'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.SpineUnit': ( 'edits.html#spineunit',
+                                                                                            'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.project_effective_spine': ( 'edits.html#project_effective_spine',
+                                                                                                          'cjm_context_graph_layer/edits.py'),
+                                               'cjm_context_graph_layer.edits.resolve_active': ( 'edits.html#resolve_active',
+                                                                                                 'cjm_context_graph_layer/edits.py')},
+            'cjm_context_graph_layer.grammar': { 'cjm_context_graph_layer.grammar.OverlayRelations': ( 'grammar.html#overlayrelations',
+                                                                                                       'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.OverlayRelations.all': ( 'grammar.html#overlayrelations.all',
+                                                                                                           'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.SpineRelations': ( 'grammar.html#spinerelations',
+                                                                                                     'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.SpineRelations.all': ( 'grammar.html#spinerelations.all',
+                                                                                                         'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.attribution': ( 'grammar.html#attribution',
+                                                                                                  'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.grouped_spine_edges': ( 'grammar.html#grouped_spine_edges',
+                                                                                                          'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.make_edge': ( 'grammar.html#make_edge',
+                                                                                                'cjm_context_graph_layer/grammar.py'),
+                                                 'cjm_context_graph_layer.grammar.spine_edges': ( 'grammar.html#spine_edges',
+                                                                                                  'cjm_context_graph_layer/grammar.py')},
+            'cjm_context_graph_layer.identity': { 'cjm_context_graph_layer.identity.canonical_part': ( 'identity.html#canonical_part',
+                                                                                                       'cjm_context_graph_layer/identity.py'),
+                                                  'cjm_context_graph_layer.identity.derive_edge_id': ( 'identity.html#derive_edge_id',
+                                                                                                       'cjm_context_graph_layer/identity.py'),
+                                                  'cjm_context_graph_layer.identity.derive_node_id': ( 'identity.html#derive_node_id',
+                                                                                                       'cjm_context_graph_layer/identity.py')},
+            'cjm_context_graph_layer.ops': { 'cjm_context_graph_layer.ops.ExtendResult': ( 'ops.html#extendresult',
+                                                                                           'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops.GraphIntegrityError': ( 'ops.html#graphintegrityerror',
+                                                                                                  'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops._source_hashes': ( 'ops.html#_source_hashes',
+                                                                                             'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops.extend_graph': ( 'ops.html#extend_graph',
+                                                                                           'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops.graph_task': ( 'ops.html#graph_task',
+                                                                                         'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops.node_identity_mismatch': ( 'ops.html#node_identity_mismatch',
+                                                                                                     'cjm_context_graph_layer/ops.py'),
+                                             'cjm_context_graph_layer.ops.partition_by_presence': ( 'ops.html#partition_by_presence',
+                                                                                                    'cjm_context_graph_layer/ops.py')}}}

cjm_context_graph_layer/declare.py

@@ -0,0 +1,60 @@
+"""Provenance-by-declaration: host logic stays readable Python in the workflow core and DECLARES its provenance contributions as a `Derivation` event node (+ DERIVED_FROM input edges, PRODUCED output edges). This recovers audit completeness without the substrate executing host logic (pass-2 Thread 4's false-dichotomy resolution). The substrate stays untouched: declarations read composition/job ids from the outside.
+
+Docs: https://cj-mills.github.io/cjm-context-graph-layerdeclare.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/declare.ipynb.
+
+# %% auto #0
+__all__ = ['Derivation', 'derivation_to_graph']
+
+# %% ../nbs/declare.ipynb #97664d2b
+import time
+from uuid import uuid4
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Tuple
+
+from .grammar import OverlayRelations, attribution, make_edge
+
+# %% ../nbs/declare.ipynb #c11abbce
+@dataclass
+class Derivation:
+    """One host-logic transformation event, declared for the audit trail.
+
+    Coarse-grained by design: the adopter passes the ids that anchor the event
+    (e.g. the Transcript nodes consumed + the Source whose spine was produced),
+    not every fine-grained output (per-node provenance already rides each
+    node's SourceRefs — duplicating it here would re-create topology, the
+    Thread-2 no-derived_from rule).
+    """
+    actor: str                       # Who ran it (e.g. "host:cjm-transcript-decomp-core")
+    method: str                      # The transformation (e.g. "alignment-fold/v1")
+    input_ids: List[str] = field(default_factory=list)   # Graph node ids consumed
+    output_ids: List[str] = field(default_factory=list)  # Graph node ids produced (coarse anchors)
+    asserted_at: Optional[float] = None                  # Unix timestamp; None = now at to_graph time
+    composition_id: Optional[str] = None                 # Substrate composition run id, if any
+    job_ids: List[str] = field(default_factory=list)     # Member job ids, if any
+    properties: Dict[str, Any] = field(default_factory=dict)  # Extra event properties
+
+# %% ../nbs/declare.ipynb #7c77965e
+def derivation_to_graph(
+    d: Derivation,                       # The declared event
+    derivation_id: Optional[str] = None, # Explicit node id; None = generated (events are asserted, not re-derivable)
+) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:  # (event node wire dict, edges)
+    """Materialize a declaration as one event node + DERIVED_FROM / PRODUCED edges.
+
+    The event node gets a GENERATED id (asserted/decision class — the
+    FLIP-TRIGGER-protected kind); its edges are deterministic per
+    (event, anchor, relation)."""
+    node_id = derivation_id or str(uuid4())
+    props: Dict[str, Any] = attribution(d.actor, method=d.method, asserted_at=d.asserted_at)
+    if d.composition_id:
+        props["composition_id"] = d.composition_id
+    if d.job_ids:
+        props["job_ids"] = list(d.job_ids)
+    props.update(d.properties)
+    node = {"id": node_id, "label": "Derivation", "properties": props, "sources": []}
+    edges = (
+        [make_edge(node_id, i, OverlayRelations.DERIVED_FROM, {"role": "input"}) for i in d.input_ids]
+        + [make_edge(node_id, o, OverlayRelations.PRODUCED, {"role": "output"}) for o in d.output_ids]
+    )
+    return node, edges

cjm_context_graph_layer/edits.py

@@ -0,0 +1,132 @@
+"""The spine-edit operation vocabulary (`prune` / `replace_text` / `boundary_shift`) + supersession resolution + the effective-view projection. These are generic operations on any NEXT-chained text spine; correction workflows carry them in overlay-node payloads, and the projection interprets them at read time (migrates correction-core C11/C16 onto the layer).
+
+Docs: https://cj-mills.github.io/cjm-context-graph-layeredits.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/edits.ipynb.
+
+# %% auto #0
+__all__ = ['EDIT_OPS', 'SpineEditError', 'SpineUnit', 'SpineEdit', 'resolve_active', 'project_effective_spine']
+
+# %% ../nbs/edits.ipynb #68a6f6d3
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Set, Tuple
+
+# %% ../nbs/edits.ipynb #376d25b0
+# Reserved spine-edit operation vocabulary (reserve-enum-values-up-front):
+# boundary_shift is locked in NOW per the where-graph-begins resolution even
+# though no driver produces it yet — the persisted decision preserves the
+# alignment-error-vs-transcription-error distinction.
+EDIT_OPS = ("prune", "replace_text", "boundary_shift")
+
+# %% ../nbs/edits.ipynb #d771e0ec
+class SpineEditError(ValueError):
+    """A spine edit could not be validated or applied (loud, never silent)."""
+    pass
+
+# %% ../nbs/edits.ipynb #95ad3798
+@dataclass
+class SpineUnit:
+    """Minimal projection unit: one spine position with its effective text."""
+    id: str    # Layer-0 segment node id
+    text: str  # Effective text at this position
+
+# %% ../nbs/edits.ipynb #e6875de1
+@dataclass
+class SpineEdit:
+    """One spine-edit decision, as carried in an overlay node's payload.
+
+    `op` semantics:
+    - `prune`: drop `targets` from the effective view (payload unused).
+    - `replace_text`: payload `{"text": ...}` replaces each target's text.
+    - `boundary_shift`: payload `{"boundary_after": <left segment id>,
+      "text": <moved text>, "direction": "push"|"pull"}` moves text across the
+      boundary between two adjacent FIXED positions (push = from the end of the
+      left unit to the start of the right; pull = the mirror). 1:1 alignment is
+      maintained continuously — count and positions never change.
+    """
+    edit_id: str                                  # Carrying overlay node id (supersession anchor)
+    op: str                                       # One of EDIT_OPS
+    targets: List[str] = field(default_factory=list)   # Layer-0 segment node ids the edit applies to
+    payload: Dict[str, Any] = field(default_factory=dict)  # Op-specific payload (see above)
+    created_at: float = 0.0                       # Decision timestamp (application order + latest-wins tiebreak)
+
+    def __post_init__(self):
+        if self.op not in EDIT_OPS:
+            raise SpineEditError(f"unknown spine-edit op: {self.op!r} (known: {EDIT_OPS})")
+
+    def to_dict(self) -> Dict[str, Any]:  # Payload-ready dict
+        """Serialize for carriage in an overlay node payload."""
+        return {"edit_id": self.edit_id, "op": self.op, "targets": list(self.targets),
+                "payload": dict(self.payload), "created_at": self.created_at}
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "SpineEdit":  # Reconstructed edit
+        """Reconstruct from a payload dict."""
+        return cls(edit_id=d["edit_id"], op=d["op"], targets=list(d.get("targets") or []),
+                   payload=dict(d.get("payload") or {}), created_at=float(d.get("created_at") or 0.0))
+
+# %% ../nbs/edits.ipynb #d0b1d211
+def resolve_active(
+    edit_ids: Iterable[str],                      # Candidate overlay node ids
+    supersedes_pairs: Iterable[Tuple[str, str]],  # (superseder_id, superseded_id) SUPERSEDES edges
+) -> Set[str]:  # Active (non-superseded) ids
+    """Resolve the active set under append-only supersession.
+
+    An id is superseded iff it is the TARGET of any SUPERSEDES edge — chains
+    resolve naturally (C supersedes B supersedes A leaves only C active), and
+    nothing is ever mutated (the C16 semantics, now layer-owned).
+    """
+    superseded = {target for _, target in supersedes_pairs}
+    return {eid for eid in edit_ids if eid not in superseded}
+
+# %% ../nbs/edits.ipynb #0ced23b9
+def project_effective_spine(
+    units: List[SpineUnit],   # Ordered layer-0 spine (immutable input)
+    edits: List[SpineEdit],   # ACTIVE edits to apply (resolve supersession first)
+) -> List[SpineUnit]:  # New effective spine (input never mutated)
+    """Project the effective view: layer-0 + active edits, resolved at read time.
+
+    Edits apply in (created_at, edit_id) order over the evolving text state, so
+    later decisions see earlier ones' effects and replace_text latest-wins
+    emerges from ordering. Prunes drop positions at the end (a boundary_shift
+    or replace recorded before a later prune still applies cleanly).
+    boundary_shift is STRICT: if the current text no longer carries the moved
+    text verbatim at the boundary, the projection fails loudly rather than
+    guessing (SpineEditError).
+    """
+    order = {u.id: i for i, u in enumerate(units)}
+    texts = {u.id: u.text for u in units}
+    pruned: Set[str] = set()
+
+    for e in sorted(edits, key=lambda e: (e.created_at, e.edit_id)):
+        if e.op == "prune":
+            pruned.update(e.targets)
+        elif e.op == "replace_text":
+            new_text = e.payload.get("text", "")
+            for t in e.targets:
+                if t in texts:
+                    texts[t] = new_text
+        elif e.op == "boundary_shift":
+            left = e.payload.get("boundary_after")
+            moved = e.payload.get("text", "")
+            direction = e.payload.get("direction", "push")
+            if left not in order:
+                raise SpineEditError(f"boundary_shift: unknown boundary_after {left!r}")
+            idx = order[left]
+            if idx + 1 >= len(units):
+                raise SpineEditError("boundary_shift: no unit after the boundary")
+            right = units[idx + 1].id
+            if direction == "push":
+                if not texts[left].endswith(moved):
+                    raise SpineEditError(f"boundary_shift push: left text does not end with the moved text ({e.edit_id})")
+                texts[left] = texts[left][: len(texts[left]) - len(moved)]
+                texts[right] = moved + texts[right]
+            elif direction == "pull":
+                if not texts[right].startswith(moved):
+                    raise SpineEditError(f"boundary_shift pull: right text does not start with the moved text ({e.edit_id})")
+                texts[right] = texts[right][len(moved):]
+                texts[left] = texts[left] + moved
+            else:
+                raise SpineEditError(f"boundary_shift: unknown direction {direction!r}")
+
+    return [SpineUnit(u.id, texts[u.id]) for u in units if u.id not in pruned]

cjm_context_graph_layer/grammar.py

@@ -0,0 +1,117 @@
+"""The domain-neutral context-graph grammar: spine relations (NEXT / PART_OF / STARTS_WITH, recurring fractally at every layer), overlay relations (SUPERSEDES / DERIVED_FROM / PRODUCED), root kinds, and the standardized attribution fields.
+
+Docs: https://cj-mills.github.io/cjm-context-graph-layergrammar.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/grammar.ipynb.
+
+# %% auto #0
+__all__ = ['ROOT_KINDS', 'SpineRelations', 'OverlayRelations', 'attribution', 'make_edge', 'spine_edges', 'grouped_spine_edges']
+
+# %% ../nbs/grammar.ipynb #f66243ba
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+from .identity import derive_edge_id
+
+# %% ../nbs/grammar.ipynb #b4d7b6c7
+class SpineRelations:
+    """Structural spine relations, reused fractally at every layer
+    (Source -> AudioSegment -> Segment today; series -> episode tomorrow)."""
+    NEXT = "NEXT"               # Sequential order among siblings
+    PART_OF = "PART_OF"         # Containment (child -> parent)
+    STARTS_WITH = "STARTS_WITH" # Entry point (parent -> first child)
+
+    @classmethod
+    def all(cls) -> list:  # All spine relation types
+        """All spine relation types."""
+        return [cls.NEXT, cls.PART_OF, cls.STARTS_WITH]
+
+# %% ../nbs/grammar.ipynb #8945de1c
+class OverlayRelations:
+    """Overlay/derivation relations — the trust grammar shared by every
+    workflow's graph extensions."""
+    SUPERSEDES = "SUPERSEDES"     # Newer overlay node -> the prior one it replaces (append-only undo)
+    DERIVED_FROM = "DERIVED_FROM" # Derived/overlay node -> the node(s) it derives from / consumed
+    PRODUCED = "PRODUCED"         # Derivation event -> the node(s) it produced
+
+    @classmethod
+    def all(cls) -> list:  # All overlay relation types
+        """All overlay relation types."""
+        return [cls.SUPERSEDES, cls.DERIVED_FROM, cls.PRODUCED]
+
+# %% ../nbs/grammar.ipynb #8eab5d13
+# The three provenance-root kinds (where-graph-begins resolution): knowledge
+# enters the graph anchored one of these ways.
+ROOT_KINDS = ("ingested", "asserted", "derived")
+
+# %% ../nbs/grammar.ipynb #87da6c7e
+def attribution(
+    actor: str,                          # Who asserted/produced this (e.g. "human", "agent:claude", "capability:whisper")
+    method: Optional[str] = None,        # How (e.g. "transcribe", "alignment-fold/v1")
+    asserted_at: Optional[float] = None, # Unix timestamp; None = now
+) -> Dict[str, Any]:  # Standardized attribution property dict
+    """Standardized attribution fields for derived/asserted nodes.
+
+    Every derivation/assertion carries the same three fields, so audit reads
+    are uniform across workflows (P13's hand-rolled Connection attribution
+    graduated into the grammar).
+    """
+    out: Dict[str, Any] = {"actor": actor, "asserted_at": asserted_at if asserted_at is not None else time.time()}
+    if method is not None:
+        out["method"] = method
+    return out
+
+# %% ../nbs/grammar.ipynb #43ed17f3
+def make_edge(
+    source_id: str,                            # Edge source node id
+    target_id: str,                            # Edge target node id
+    relation_type: str,                        # Relation type (SpineRelations / OverlayRelations / domain)
+    properties: Optional[Dict[str, Any]] = None,  # Optional edge properties (e.g. {"role": "foreshadow"})
+    edge_id: Optional[str] = None,             # Explicit id; None = deterministic from the triple
+) -> Dict[str, Any]:  # Edge wire dict
+    """Build an edge wire dict with a deterministic id by default."""
+    return {
+        "id": edge_id or derive_edge_id(source_id, target_id, relation_type),
+        "source_id": source_id,
+        "target_id": target_id,
+        "relation_type": relation_type,
+        "properties": properties or {},
+    }
+
+# %% ../nbs/grammar.ipynb #047d3e7e
+def spine_edges(
+    parent_id: str,        # Parent node id
+    child_ids: List[str],  # Ordered child node ids
+) -> List[Dict[str, Any]]:  # Edge wire dicts
+    """The uniform spine pattern at any layer: PART_OF child->parent for each
+    child + NEXT chain among children + STARTS_WITH parent->first child."""
+    edges: List[Dict[str, Any]] = []
+    if child_ids:
+        edges.append(make_edge(parent_id, child_ids[0], SpineRelations.STARTS_WITH))
+    for i, cid in enumerate(child_ids):
+        edges.append(make_edge(cid, parent_id, SpineRelations.PART_OF))
+        if i < len(child_ids) - 1:
+            edges.append(make_edge(cid, child_ids[i + 1], SpineRelations.NEXT))
+    return edges
+
+# %% ../nbs/grammar.ipynb #71f01b78
+def grouped_spine_edges(
+    groups: List[Tuple[str, List[str]]],  # (parent id, ordered child ids) per group, groups in spine order
+) -> List[Dict[str, Any]]:  # Edge wire dicts
+    """Spine edges for a fine layer grouped under coarse parents.
+
+    PART_OF goes to the OWNING parent; STARTS_WITH per parent -> its first
+    child (the coarse-seam jump anchor); the NEXT chain is GLOBAL across group
+    boundaries — fine continuity crosses coarse boundaries (agent span reads).
+    """
+    edges: List[Dict[str, Any]] = []
+    flat: List[str] = []
+    for parent_id, child_ids in groups:
+        if child_ids:
+            edges.append(make_edge(parent_id, child_ids[0], SpineRelations.STARTS_WITH))
+        for cid in child_ids:
+            edges.append(make_edge(cid, parent_id, SpineRelations.PART_OF))
+            flat.append(cid)
+    for i in range(len(flat) - 1):
+        edges.append(make_edge(flat[i], flat[i + 1], SpineRelations.NEXT))
+    return edges

cjm_context_graph_layer/identity.py

@@ -0,0 +1,73 @@
+"""Deterministic node/edge identity: UUIDv5 over canonical identity tuples (stage-5 ratified rule: a node's id derives from what makes it THE same node across re-derivation, never from its correctable content).
+
+Docs: https://cj-mills.github.io/cjm-context-graph-layeridentity.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/identity.ipynb.
+
+# %% auto #0
+__all__ = ['LAYER_ID_NAMESPACE', 'IDENTITY_SEPARATOR', 'canonical_part', 'derive_node_id', 'derive_edge_id']
+
+# %% ../nbs/identity.ipynb #48c3ba87
+import uuid
+from typing import Union
+
+# %% ../nbs/identity.ipynb #8ae437f7
+# Fixed namespace for all context-graph layer ids. Derived once from the DNS
+# namespace so the value is stable and reproducible; every deterministic id in
+# the ecosystem hangs off this constant.
+LAYER_ID_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS, "context-graph.cj-mills.com")
+
+# Unit separator: cannot appear in paths/hashes/relation names, so joined
+# identity parts can never collide across part boundaries.
+IDENTITY_SEPARATOR = "\x1f"
+
+# %% ../nbs/identity.ipynb #2f674553
+def canonical_part(
+    value: Union[str, int, float],  # One identity-tuple part
+) -> str:  # Canonical string form used inside the UUIDv5 name
+    """Render one identity-tuple part canonically.
+
+    Floats use `repr` (shortest round-trip — identical floats from the same
+    deterministic computation render identically); ints use `str`; strings pass
+    through. Anything else (including bool, whose int-ness is ambiguous) is
+    rejected loudly: identity inputs must be deliberate.
+    """
+    if isinstance(value, bool):
+        raise TypeError("bool is not a valid identity part (ambiguous int)")
+    if isinstance(value, float):
+        return repr(value)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, str):
+        return value
+    raise TypeError(f"unsupported identity part type: {type(value).__name__}")
+
+# %% ../nbs/identity.ipynb #cc1d398c
+def derive_node_id(
+    kind: str,  # Node kind discriminator (e.g. "source", "audio-segment")
+    *parts: Union[str, int, float],  # The identity tuple (positional, order-significant)
+) -> str:  # Deterministic UUID string (UUIDv5)
+    """Derive a deterministic node id from a kind + identity tuple.
+
+    Same kind + same parts always yields the same id, across processes and
+    re-derivations — re-derived graphs reproduce their node ids, so cross-graph
+    references survive a rebuild (the G3a fix made structural). Content hashes
+    belong in SourceRefs, NOT here: identity is position/provenance, never the
+    correctable content.
+    """
+    name = IDENTITY_SEPARATOR.join([kind, *(canonical_part(p) for p in parts)])
+    return str(uuid.uuid5(LAYER_ID_NAMESPACE, name))
+
+# %% ../nbs/identity.ipynb #b603404f
+def derive_edge_id(
+    source_id: str,      # Edge source node id
+    target_id: str,      # Edge target node id
+    relation_type: str,  # Relation type (e.g. "NEXT")
+) -> str:  # Deterministic UUID string
+    """Derive a deterministic edge id from (source, target, relation).
+
+    Layer-0 structural edges are unique per (source, target, relation), so the
+    triple IS the identity — re-derivation reproduces edge ids the same way it
+    reproduces node ids.
+    """
+    return derive_node_id("edge", source_id, target_id, relation_type)

cjm_context_graph_layer/ops.py

@@ -0,0 +1,141 @@
+"""Queue-touching layer operations: the shared `graph_task` helper (task channel), idempotent emission (emit-if-absent + verify-if-present), and `extend_graph` — the one primitive every graph-extending workflow commits through. Deterministic ids (see `identity`) make idempotency a presence check instead of a search.
+
+Docs: https://cj-mills.github.io/cjm-context-graph-layerops.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/ops.ipynb.
+
+# %% auto #0
+__all__ = ['GRAPH_TASK', 'graph_task', 'GraphIntegrityError', 'node_identity_mismatch', 'partition_by_presence', 'ExtendResult',
+           'extend_graph']
+
+# %% ../nbs/ops.ipynb #189a5452
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from cjm_plugin_system.core.queue import JobQueue, JobStatus
+# Importing the typed query/result classes IS the host-side wire registration (F8).
+from cjm_context_graph_primitives.query import NodeQuery, EdgeQuery, NodeQueryResult, EdgeQueryResult
+
+# %% ../nbs/ops.ipynb #5756d771
+GRAPH_TASK = "graph-storage"  # The graph-storage adapter task (explicit task channel, stage 4)
+
+
+async def graph_task(
+    queue: JobQueue,  # Started job queue
+    graph_id: str,    # Graph-storage capability instance id
+    method: str,      # Adapter method (e.g. "query_nodes", "add_nodes")
+    **kwargs,         # Typed-method kwargs (wire dicts ok; the in-worker adapter normalizes)
+) -> Any:  # Typed task result (wire-decoded host-side)
+    """Invoke a graph-storage adapter method through the queue's task channel.
+
+    THE shared copy: decomp-core and correction-core's per-core helpers migrate
+    onto this one (graph ops stay on the queue path for telemetry/cancellation
+    per D7/Thread-5 lock 5).
+    """
+    jid = await queue.submit(graph_id, task=GRAPH_TASK, method=method, **kwargs)
+    job = await queue.wait_for_job(jid)
+    if job.status != JobStatus.completed:
+        raise RuntimeError(f"{graph_id} {method} {job.status}: {job.error}")
+    return job.result
+
+# %% ../nbs/ops.ipynb #77646074
+class GraphIntegrityError(RuntimeError):
+    """An emitted node collided with an existing node of different identity content.
+
+    Raised by verify-if-present: same deterministic id but mismatched label or
+    provenance content hashes means the identity tuple and the content have
+    diverged — never overwrite silently."""
+    pass
+
+# %% ../nbs/ops.ipynb #def7e7bb
+def _source_hashes(sources: Optional[List[Any]]) -> Set[str]:
+    """Content-hash set from a node's sources (typed SourceRefs or wire dicts)."""
+    out: Set[str] = set()
+    for s in sources or []:
+        h = s.get("content_hash") if isinstance(s, dict) else getattr(s, "content_hash", None)
+        if h:
+            out.add(h)
+    return out
+
+
+def node_identity_mismatch(
+    existing: Any,            # Existing node (typed GraphNode or wire dict)
+    new: Dict[str, Any],      # New node wire dict being emitted
+) -> Optional[str]:  # Mismatch description, or None when compatible
+    """Verify-if-present check: label + sources content-hash set must match."""
+    ex_label = existing.get("label") if isinstance(existing, dict) else getattr(existing, "label", None)
+    if ex_label != new.get("label"):
+        return f"label mismatch: existing {ex_label!r} != new {new.get('label')!r}"
+    ex_sources = existing.get("sources") if isinstance(existing, dict) else getattr(existing, "sources", None)
+    ex_hashes, new_hashes = _source_hashes(ex_sources), _source_hashes(new.get("sources"))
+    if ex_hashes != new_hashes:
+        return f"sources content-hash mismatch: existing {sorted(ex_hashes)} != new {sorted(new_hashes)}"
+    return None
+
+# %% ../nbs/ops.ipynb #96cab756
+def partition_by_presence(
+    items: List[Dict[str, Any]],  # Wire dicts carrying "id"
+    existing_ids: Set[str],       # Ids already present in the graph
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:  # (absent, present)
+    """Split wire dicts into absent (to add) and present (to verify)."""
+    absent = [it for it in items if it["id"] not in existing_ids]
+    present = [it for it in items if it["id"] in existing_ids]
+    return absent, present
+
+# %% ../nbs/ops.ipynb #c3d8d7da
+@dataclass
+class ExtendResult:
+    """Outcome of one idempotent extend_graph commit."""
+    nodes_added: int = 0      # Nodes newly created
+    nodes_verified: int = 0   # Nodes already present, identity-verified
+    edges_added: int = 0      # Edges newly created
+    edges_existing: int = 0   # Edges already present (skipped)
+    added_node_ids: List[str] = field(default_factory=list)  # Ids of created nodes
+    added_edge_ids: List[str] = field(default_factory=list)  # Ids of created edges
+
+# %% ../nbs/ops.ipynb #bcda5566
+async def extend_graph(
+    queue: JobQueue,              # Started job queue
+    graph_id: str,                # Graph-storage capability id
+    nodes: List[Dict[str, Any]],  # Node wire dicts (deterministic ids for layer-0; generated for decisions)
+    edges: List[Dict[str, Any]],  # Edge wire dicts
+) -> ExtendResult:  # Counts + created ids
+    """Idempotently extend the graph: emit-if-absent + verify-if-present.
+
+    Deterministic ids make idempotency a batched presence check (2 reads + at
+    most 2 writes per call — the C17 lesson applied to the write path): nodes
+    already present are verified against the new emission (label + provenance
+    content hashes) and a mismatch raises `GraphIntegrityError` LOUDLY; absent
+    nodes/edges are added. Cache-hit re-emission therefore collides into a
+    verified no-op (stress item 4), and a re-derived spine reproduces — never
+    duplicates — its layer-0 (stress item 1).
+    """
+    result = ExtendResult()
+
+    if nodes:
+        res = await graph_task(queue, graph_id, "query_nodes",
+                               query=NodeQuery(ids=[n["id"] for n in nodes]).to_dict())
+        existing = {gn.id: gn for gn in (res.nodes or [])}
+        absent, present = partition_by_presence(nodes, set(existing))
+        for n in present:
+            msg = node_identity_mismatch(existing[n["id"]], n)
+            if msg:
+                raise GraphIntegrityError(f"node {n['id']}: {msg}")
+        result.nodes_verified = len(present)
+        if absent:
+            added = await graph_task(queue, graph_id, "add_nodes", nodes=absent)
+            result.added_node_ids = list(added or [])
+            result.nodes_added = len(result.added_node_ids)
+
+    if edges:
+        eres = await graph_task(queue, graph_id, "query_edges",
+                                query=EdgeQuery(ids=[e["id"] for e in edges], project=["id"]).to_dict())
+        existing_eids = {r["id"] for r in (eres.rows or [])}
+        absent_edges = [e for e in edges if e["id"] not in existing_eids]
+        result.edges_existing = len(edges) - len(absent_edges)
+        if absent_edges:
+            added = await graph_task(queue, graph_id, "add_edges", edges=absent_edges)
+            result.added_edge_ids = list(added or [])
+            result.edges_added = len(result.added_edge_ids)
+
+    return result