Graph Namespace Utils

Graph node ID namespacing utilities.

`build_cypher_chunk_id_match(chunk_id, index_name, use_namespaced_id=True)`

Build the Cypher Chunk-id match clause and its bind parameters for one chunk id.

Parameters:

Name	Type	Description	Default
`chunk_id`	`str`	Raw (un-namespaced) chunk identifier.	required
`index_name`	`str`	Namespace scoping the lookup.	required
`use_namespaced_id`	`bool`	Whether the predicate also matches the namespaced (`{index_name}:{chunk_id}`) form. Defaults to True.	`True`

Returns:

Type	Description
`tuple[str, dict[str, Any]]`	tuple[str, dict[str, Any]]: The parenthesized Cypher predicate matching the chunk's `id` (the `Chunk` node must be bound as `c`), and the bind parameters it references.

`build_namespaced_edge_dict(edge_dict, index_name)`

Return a copy of a generator edge dict with its endpoints namespaced.

Parameters:

Name	Type	Description	Default
`edge_dict`	`dict[str, Any]`	Raw edge dict from generator output, with `source` and `target`.	required
`index_name`	`str \| None`	Namespace prefix to apply, or `None` to return an unchanged (shallow-copied) dict.	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: A copy of `edge_dict` with `source` and `target` namespaced.

`build_namespaced_id(raw_id, index_name)`

Return a namespaced node identifier.

When index_name is provided, the returned id takes the form "{index_name}:{raw_id}", scoping the node to a single pipeline's namespace. When index_name is None the raw id is returned unchanged, preserving backwards compatibility with deployments that predate namespacing. Idempotent when raw_id already carries the current index_name prefix (e.g. an in-flight element produced by a generator version that namespaced ids itself), so callers can't double-prefix an id into "{index_name}:{index_name}:...".

Parameters:

Name	Type	Description	Default
`raw_id`	`str`	Raw, un-namespaced node identifier.	required
`index_name`	`str \| None`	Namespace prefix to prepend, or `None` to return `raw_id` unchanged.	required

Returns:

Name	Type	Description
`str`	`str`	The namespaced id `"{index_name}:{raw_id}"`, `raw_id` unchanged when `index_name` is `None`, or `raw_id` unchanged when it is already prefixed with `index_name`.

`build_namespaced_node_dict(node_dict, index_name)`

Return a copy of a generator node dict with its id (and id references) namespaced.

Prefixes the top-level id and, when present, every property in _ID_REFERENCE_PROPERTIES — the mirrored properties["id"] copy several node builders carry (Chapter, Part, Paragraph, Article, ArticleVersion, Clause, Concept, Obligation, Explanation, Chunk), and properties["article_id"] (ArticleVersion's reference to its parent Article's id). Never touches properties["chunk_id"], which the deleter/reader match on in its raw (un-namespaced) form.

Parameters:

Name	Type	Description	Default
`node_dict`	`dict[str, Any]`	Raw node dict from generator output, with `id` and optionally `properties`.	required
`index_name`	`str \| None`	Namespace prefix to apply, or `None` to return an unchanged (shallow-copied) dict.	required

Returns:

Type	Description
`dict[str, Any]`	dict[str, Any]: A copy of `node_dict` with `id` and any id-reference properties (see `_ID_REFERENCE_PROPERTIES`) namespaced.