Module model 

Core graph data model and JGF (JSON Graph Format) serialization.

drft’s substrate is a set of independent graphs (the raw view); a composition step merges them by path into one graph (the composed view). Both views share the same node/edge shape and both serialize to valid JGF:

• Composed — a single graph: {"graph": {...}} (GraphDocument).
• Raw — the unmerged set: {"graphs": [...]} (GraphSet), JGF’s multi-graph form.

A node or edge carries a JSON object of Metadata. The keys differ by view:

• In a raw per-graph fragment, keys are bare — whatever the builder emits (e.g. {"type": "file", "hash": "b3:…"}).
• In the composed graph, keys are namespaced: an @<graph> object per contributing graph, plus the reserved _graphs provenance list.

@ and _ are reserved, compose-only sigils. A graph label must not contain @ (it builds the @<label> namespace) or start with _ (reserved for keys like _graphs); interior _ is fine. validate_label, validate_raw_metadata, and validate_composed_metadata enforce these invariants.

Structs

Edge

A directed edge from source to target (both node-identity paths).

Graph

A single JGF graph. Used for both a raw per-graph fragment (with label set to the graph name) and the composed graph (with label absent).

GraphDocument

JGF single-graph document: {"graph": {...}}. The composed view drft emits by default.

GraphSet

JGF multi-graph document: {"graphs": [...]}. The raw view drft emits under --raw — the unmerged set of per-graph fragments.

Node

A node in a graph. Its identity is its key in Graph::nodes (a path); the node body carries only metadata.

Enums

ValidationError

An invariant violation in graph labels or metadata keys.

Constants

FS_NAMESPACE

The fs namespace key on a composed node — the base graph that carries content type and hash. The single place the @fs literal lives.

PROVENANCE_KEY

The reserved provenance key stamped on composed nodes and edges.

Functions

namespace

The @<label> namespace key under which a graph’s contribution nests in a composed node or edge. The single place the @ prefix rule lives; FS_NAMESPACE is namespace("fs").

validate_composed_metadata

Validate that a composed metadata object’s top-level keys are each either an @<graph> namespace (naming a bare graph) or the reserved _graphs key.

validate_label

Validate that a graph label is non-empty and free of the reserved sigils: no @ anywhere (it builds the @<label> namespace) and no leading _ (reserved for keys like _graphs). Interior _ is allowed.

validate_raw_metadata

Validate that a raw fragment’s metadata keys are all bare — no key may begin with the reserved @ or _ sigils. Builders emit bare keys; the sigils are introduced only at compose.

Type Aliases

Metadata

A JSON object of metadata attached to a node or edge.