add assigned vertices (#323)

Author: alexander-belikov

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.8.15]
+
+### Added
+
+- **`FieldType.UUID`** — logical scalar (incl. `LIST` `item_type`); TigerGraph / Nebula / Postgres DDL store as `STRING` / `TEXT`.
+- **`Vertex.assigned`** / **`identity_mode == "assigned"`** — intentional UUID primary key, distinct from `blank`. Empty identity is minted with `uuid4()` at assemble time (before edge projection); writer keeps an idempotent safety net. Assigned vertices do **not** participate in blank-edge resolution.
+- **`VertexConfig.assigned_vertices`**; helpers in **`graflo.db.identity_uuid`** (`ensure_assigned_uuid`, `validate_uuid_value`, …).
+- Docs: four identity modes and blank vs assigned in [vertex identity](docs/concepts/schema/vertex_identity.md); UUID moved to supported field types.
+
 ## [1.8.14]
 
 ### Added

docs/concepts/architecture/core_components.md

@@ -91,15 +91,17 @@ A `Vertex` describes vertices and their logical identity. It supports:
   - **LIST-typed properties cannot be identity / hash-identity sources**
 - Filtering conditions
 - **`blank: true`** — placeholder vertex with no natural key; identity defaults to **`id`** when omitted
+- **`assigned: true`** — intentional UUID primary key; identity defaults to **`id`**; mint at assemble (not blank-edge resolution)
 - **`hash_identity_properties`** — when non-empty, SHA256 hash of these source fields produces a deterministic synthetic **`id`** (see [Vertex identity modes](../schema/vertex_identity.md))
-- **`Vertex.identity_mode`** — derived runtime mode: **`natural`** (upsert on `identity`), **`hash`**, or **`blank`**
+- **`Vertex.identity_mode`** — derived runtime mode: **`natural`**, **`hash`**, **`blank`**, or **`assigned`**
 
 #### Supported field types
 
 | `FieldType` | Shape | Notes |
 |-------------|-------|-------|
 | `INT` `UINT` `FLOAT` `DOUBLE` `BOOL` `STRING` `DATETIME` | scalar | Existing scalar types |
-| `LIST` | + required `item_type` (scalar above) | Homogeneous, **one level** only — no `LIST[LIST[…]]`, no object schemas |
+| `UUID` | scalar | Logical UUID; TigerGraph / Nebula / Postgres DDL store as `STRING` / `TEXT` |
+| `LIST` | + required `item_type` (scalar above, including `UUID`) | Homogeneous, **one level** only — no `LIST[LIST[…]]`, no object schemas |
 
 Declare types on each property as a mapping (`name` / `type` / optional `item_type`).
 String shorthand (`properties: [id, name]`) still works and leaves types unset.
@@ -197,16 +199,15 @@ Not in `FieldType` yet — do not author these in manifests:
 
 | Type | Status | Sketch |
 |------|--------|--------|
-| `UUID` | PR2 | Logical scalar; TigerGraph/Nebula still store as `STRING` |
 | `MAP` | follow-up | `key_type` + `value_type` (scalar); native TG/Arango; Cypher targets raise (maps are not storable node/rel properties) |
 | `SET` | follow-up (low) | TigerGraph-oriented; prefer `LIST` elsewhere |
 
 Identity defaults at schema level (`VertexConfig`):
 
 - **`identity_from_all_properties: true`** (default) — vertices without explicit **`identity`** use all **`properties`** names as the logical key.
-- **`identity_from_all_properties: false`** — each non-blank vertex must declare **`identity`** explicitly; blank vertices still default to **`id`**.
+- **`identity_from_all_properties: false`** — each non-blank / non-assigned vertex must declare **`identity`** explicitly; blank and assigned vertices still default to **`id`**.
 
-**Blank vertices:** set **`blank: true`** on the vertex entry under **`schema.graph.vertex_config.vertices`**. **`VertexConfig.blank_vertices`** is a derived list of names (not a separate YAML field). **`VertexConfig.hash_identity_vertices`** lists vertices with hash-derived identity. At runtime, **`ResourceRuntime`** keeps only vertex types referenced by that resource’s pipeline (and edge-inference selectors); blank types that are declared in the schema but not used by the resource are not injected automatically—include a **`vertex`** (or edge) step when the placeholder must be populated.
+**Blank vertices:** set **`blank: true`** on the vertex entry under **`schema.graph.vertex_config.vertices`**. **`VertexConfig.blank_vertices`** is a derived list of names (not a separate YAML field). **`VertexConfig.hash_identity_vertices`** lists vertices with hash-derived identity; **`VertexConfig.assigned_vertices`** lists intentional UUID-PK vertices. At runtime, **`ResourceRuntime`** keeps only vertex types referenced by that resource’s pipeline (and edge-inference selectors); blank types that are declared in the schema but not used by the resource are not injected automatically—include a **`vertex`** (or edge) step when the placeholder must be populated.
 
 Algorithmic identity inference from record samples: **`graflo.db.identity_inference`** (`IdentityInferencer`, `apply_identity_inference_to_vertices`). See [Vertex identity modes](../schema/vertex_identity.md) and [Example 15](../../examples/example-15.md).
 

docs/concepts/schema/vertex_identity.md

@@ -2,23 +2,35 @@
 
 GraFlo vertices declare how records are matched during upserts through fields on the logical **`Vertex`** model in `schema.graph.vertex_config`. Identity semantics are **not** configured in `DatabaseProfile` or `IngestionModel`.
 
-## Three runtime modes
+## Four runtime modes
 
-Each vertex resolves to one of three modes via the derived property **`Vertex.identity_mode`**:
+Each vertex resolves to one of four modes via the derived property **`Vertex.identity_mode`**. Modes describe **how the upsert key is obtained** (not string encoding). They are mutually exclusive.
 
-| `identity_mode` | `blank` | `hash_identity_properties` | `identity` | Write-time behavior |
-|---|---|---|---|---|
-| **`natural`** | `false` | `[]` | `[f]` or `[f1, f2, ...]` | Upsert on declared fields (same code path for one or many fields) |
-| **`hash`** | `false` | `[f1, f2, ...]` | `["id"]` | SHA256 of hash sources → synthetic `id`, then upsert |
-| **`blank`** | `true` | `[]` | `["id"]` | Random UUID → synthetic `id`, then upsert |
+| `identity_mode` | Authored signal | `identity` | Key behavior |
+|---|---|---|---|
+| **`natural`** | default | `[f]` or `[f1, f2, …]` | Upsert on declared fields. If a field is typed **`UUID`**, validate shape when present — **do not invent**. |
+| **`hash`** | non-empty `hash_identity_properties` | `["id"]` | SHA256 of hash sources → synthetic `id`, then upsert |
+| **`assigned`** | `assigned: true` | `["id"]` | Intentional UUID PK: empty → `uuid4()` at **assemble** (before edge projection); writer is an idempotent safety net. **Not** blank-edge resolution. |
+| **`blank`** | `blank: true` | `["id"]` | Placeholder: random UUID at write time; listed in `blank_vertices`; **does** blank-edge resolution |
 
 Unary and composite natural keys are the **same runtime mode**. The upsert path passes `Vertex.identity` to the database as `match_keys`; width does not change the write branch.
 
+### Blank vs assigned
+
+Both may mint a random UUID when the synthetic `id` is empty, but they are not interchangeable:
+
+| | `blank` | `assigned` |
+|---|---|---|
+| Meaning | No business identity / placeholder | Intentional UUID primary key |
+| Mint timing | Writer (`_assign_blank_vertex_ids`) | Assemble (before `assemble_edges`); writer net is idempotent |
+| Blank-edge resolution | Yes (`_resolve_blank_edges`) | **No** |
+| Typical use | Mentions, ephemeral join stubs | Events / entities whose PK is a UUID |
+
 ## Schema fields
 
 ### `identity`
 
-Logical field name(s) used for upsert matching. For `hash` and `blank` modes the normalizer sets `identity` to `["id"]` (GraFlo canonical synthetic key; ArangoDB maps to `_key` at write time).
+Logical field name(s) used for upsert matching. For `hash`, `blank`, and `assigned` modes the normalizer sets `identity` to `["id"]` (GraFlo canonical synthetic key; ArangoDB maps to `_key` at write time).
 
 ### `hash_identity_properties`
 
@@ -35,7 +47,30 @@ Example:
 
 ### `blank`
 
-Placeholder vertices with no stable natural key; each record gets a random UUID at ingest time.
+Placeholder vertices with no stable natural key; each record gets a random UUID at ingest time and may participate in blank-edge expansion.
+
+### `assigned`
+
+Intentional UUID primary key. Empty identity is filled with `uuid4()` so cast-time edge projections see the key. Present valid UUIDs are preserved; invalid non-empty values raise.
+
+```yaml
+- name: event
+  properties:
+    - { name: id, type: UUID }
+    - { name: payload, type: STRING }
+  identity: [id]
+  assigned: true
+```
+
+Natural key that happens to be a UUID (no new mode):
+
+```yaml
+- name: user
+  properties:
+    - { name: external_id, type: UUID }
+    - { name: email, type: STRING }
+  identity: [external_id]
+```
 
 ## Inference vs runtime
 
@@ -64,4 +99,4 @@ See [Example 15](../../examples/example-15.md) for a CSV → manifest → ingest
 | **`DatabaseProfile`** | Physical indexes and storage names only |
 | **`IngestionModel`** | Pipeline and connectors only; no identity semantics |
 
-`VertexConfig.hash_identity_vertices` and `VertexConfig.vertices_by_identity_mode()` are derived lists for runtime introspection and `db_writer` branching.
+`VertexConfig.hash_identity_vertices`, `VertexConfig.blank_vertices`, `VertexConfig.assigned_vertices`, and `VertexConfig.vertices_by_identity_mode()` are derived lists for runtime introspection and `db_writer` / assemble branching.

graflo/architecture/pipeline/runtime/actor/wrapper.py

@@ -138,6 +138,10 @@ def assemble(
             assembly_ctx = ctx
         else:
             assembly_ctx = AssemblyContext.from_extraction(ctx)
+        # Lazy import: graflo.db pulls architecture via ConnectionManager.
+        from graflo.db.identity_uuid import ensure_assigned_uuids_in_acc_vertex
+
+        ensure_assigned_uuids_in_acc_vertex(assembly_ctx.acc_vertex, self.vertex_config)
         assemble_edges(
             ctx=assembly_ctx,
             vertex_config=self.vertex_config,

graflo/architecture/schema/db_aware.py

@@ -88,6 +88,10 @@ def vertex_set(self):
     def blank_vertices(self):
         return self.logical.blank_vertices
 
+    @property
+    def assigned_vertices(self):
+        return self.logical.assigned_vertices
+
     @property
     def hash_identity_vertices(self):
         return self.logical.hash_identity_vertices

graflo/architecture/schema/vertex.py

@@ -39,7 +39,7 @@
 # Type accepted for vertex properties before normalization (for use by Edge/WeightConfig)
 PropertiesInputType = list[str] | list["Field"] | list[dict[str, Any]]
 VertexName: TypeAlias = str
-IdentityMode: TypeAlias = Literal["natural", "hash", "blank"]
+IdentityMode: TypeAlias = Literal["natural", "hash", "blank", "assigned"]
 
 
 class FieldType(BaseEnum):
@@ -56,6 +56,7 @@ class FieldType(BaseEnum):
         BOOL: Boolean type
         STRING: String type
         DATETIME: DateTime type
+        UUID: Logical UUID scalar (backends store as STRING/TEXT)
         LIST: Homogeneous list of scalars (requires ``Field.item_type``)
     """
 
@@ -66,6 +67,7 @@ class FieldType(BaseEnum):
     BOOL = "BOOL"
     STRING = "STRING"
     DATETIME = "DATETIME"
+    UUID = "UUID"
     LIST = "LIST"
 
 
@@ -79,6 +81,7 @@ class FieldType(BaseEnum):
         FieldType.BOOL,
         FieldType.STRING,
         FieldType.DATETIME,
+        FieldType.UUID,
     }
 )
 SCALAR_FIELD_TYPE_VALUES: frozenset[str] = frozenset(
@@ -161,7 +164,7 @@ class Field(ConfigBaseModel):
         default=None,
         description=(
             "Element type when ``type`` is LIST. Must be a scalar "
-            "(INT, UINT, FLOAT, DOUBLE, BOOL, STRING, DATETIME)."
+            "(INT, UINT, FLOAT, DOUBLE, BOOL, STRING, DATETIME, UUID)."
         ),
     )
     description: str | None = PydanticField(
@@ -416,6 +419,13 @@ class Vertex(ConfigBaseModel):
             "True when this vertex has no natural identity and gets an auto-generated ID."
         ),
     )
+    assigned: bool = PydanticField(
+        default=False,
+        description=(
+            "True when this vertex uses an intentional UUID primary key: empty identity "
+            "is filled with uuid4 at assemble time; not a blank-node placeholder."
+        ),
+    )
     hash_identity_properties: list[str] = PydanticField(
         default_factory=list,
         description=(
@@ -475,6 +485,15 @@ def convert_hash_identity_properties(cls, v: Any) -> Any:
 
     @model_validator(mode="after")
     def set_identity(self) -> "Vertex":
+        if self.blank and self.assigned:
+            raise ValueError(
+                f"Vertex '{self.name}': blank and assigned are mutually exclusive"
+            )
+        if self.assigned and self.hash_identity_properties:
+            raise ValueError(
+                f"Vertex '{self.name}': assigned and hash_identity_properties "
+                "are mutually exclusive"
+            )
         merged_properties = _merge_duplicate_fields(self.name, list(self.properties))
         identity_names = _dedupe_ordered(list(self.identity))
         hash_identity_names = _dedupe_ordered(list(self.hash_identity_properties))
@@ -497,7 +516,8 @@ def set_identity(self) -> "Vertex":
         augmented = list(merged_properties)
         for name in identity_names + hash_identity_names:
             if name not in seen_names:
-                augmented.append(Field(name=name, type=None))
+                synth_type = FieldType.UUID if self.assigned and name == "id" else None
+                augmented.append(Field(name=name, type=synth_type))
                 seen_names.add(name)
         object.__setattr__(self, "identity", identity_names)
         object.__setattr__(self, "hash_identity_properties", hash_identity_names)
@@ -511,9 +531,11 @@ def property_names(self) -> list[str]:
 
     @property
     def identity_mode(self) -> IdentityMode:
-        """Runtime identity mode: natural upsert, hash-derived id, or blank uuid."""
+        """Runtime identity mode: natural, hash, blank, or assigned UUID PK."""
         if self.blank:
             return "blank"
+        if self.assigned:
+            return "assigned"
         if self.hash_identity_properties:
             return "hash"
         return "natural"
@@ -552,7 +574,7 @@ class VertexConfig(ConfigBaseModel):
         default=True,
         description=(
             "When true, vertices without explicit identity fall back to all property names. "
-            "When false, explicit identity is required except for blank vertices."
+            "When false, explicit identity is required except for blank or assigned vertices."
         ),
     )
     _vertices_map: dict[VertexName, Vertex] | None = PrivateAttr(default=None)
@@ -576,6 +598,11 @@ def blank_vertices(self) -> list[str]:
         """Vertex names marked blank (no natural identity; auto-generated ID)."""
         return [v.name for v in self.vertices if v.blank]
 
+    @property
+    def assigned_vertices(self) -> list[str]:
+        """Vertex names with intentional UUID primary keys (``assigned: true``)."""
+        return [v.name for v in self.vertices if v.assigned]
+
     @property
     def hash_identity_vertices(self) -> list[str]:
         """Vertex names using hash-derived synthetic identity fields."""
@@ -593,7 +620,7 @@ def _normalize_vertex_identities(
             if not vertex.identity:
                 if vertex.hash_identity_properties:
                     vertex.identity = [blank_id_field]
-                elif vertex.blank:
+                elif vertex.blank or vertex.assigned:
                     vertex.identity = [blank_id_field]
                 elif self.identity_from_all_properties:
                     vertex.identity = list(vertex.property_names)
@@ -611,7 +638,12 @@ def _normalize_vertex_identities(
                 if field_name not in vertex.property_names
             ]
             for field_name in missing:
-                vertex.properties.append(Field(name=field_name, type=None))
+                synth_type = (
+                    FieldType.UUID
+                    if vertex.assigned and field_name == blank_id_field
+                    else None
+                )
+                vertex.properties.append(Field(name=field_name, type=synth_type))
 
     def _get_vertices_map(self) -> dict[VertexName, Vertex]:
         """Return the vertices map (set by model validator)."""

graflo/db/field_type_support.py

@@ -69,14 +69,24 @@ def assert_schema_field_types_supported(db_type: DBType, schema: Schema) -> None
 
 
 def tigergraph_type_for_field(field: Field) -> str:
-    """Return a TigerGraph attribute type string (e.g. ``LIST<STRING>``, ``INT``)."""
+    """Return a TigerGraph attribute type string (e.g. ``LIST<STRING>``, ``INT``).
+
+    Logical ``UUID`` is stored as ``STRING`` (TigerGraph has no native UUID type).
+    """
     assert_field_type_supported(DBType.TIGERGRAPH, field)
     if field.type is None:
         return FieldType.STRING.value
     if is_list_field_type(field.type):
         item = field.item_type
         item_val = item.value if isinstance(item, FieldType) else str(item).upper()
+        if item_val == FieldType.UUID.value:
+            item_val = FieldType.STRING.value
         return f"LIST<{item_val}>"
     if isinstance(field.type, FieldType):
+        if field.type == FieldType.UUID:
+            return FieldType.STRING.value
         return field.type.value
-    return str(field.type).upper()
+    type_upper = str(field.type).upper()
+    if type_upper == FieldType.UUID.value:
+        return FieldType.STRING.value
+    return type_upper

graflo/db/identity_inference.py

@@ -17,15 +17,13 @@
 from graflo.architecture.schema.graflo_output import GraFloOutput
 from graflo.architecture.schema.vertex import Vertex, VertexConfig
 from graflo.db.graph_introspection import strip_internal_properties
+from graflo.db.identity_uuid import UUID_PATTERN
 
 logger = logging.getLogger(__name__)
 
 _SYNTHETIC_ID_FIELD = "id"
 _SEMANTIC_PATTERN = re.compile(r"(?i)(id|uuid|key|code|pk)$")
-_UUID_PATTERN = re.compile(
-    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
-    re.IGNORECASE,
-)
+_UUID_PATTERN = UUID_PATTERN
 _ISO_DATETIME_PATTERN = re.compile(
     r"^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$"
 )