Promote Ontology Relationship

promote-ontology-relationship

Cartography normalises cross-provider edges between two ontology-labelled nodes (semantic labels like UserAccount, PermissionRole, ServiceAccount, ComputePod, or abstract nodes like User, Device) under a single canonical relationship label. The canonical label is declared as a RelConstraint and enforced by a CI guard.

There are two cases. (A) A direct provider edge already exists between the two ontology-labelled nodes: promote it in place, following the WORKLOAD_PARENT precedent (PRs #2735 / #2738): add a parallel canonical edge, keep the old one deprecated for backward compatibility, and add a constraint. This promotion is NOT done with analysis/linking jobs. (B) No direct edge exists yet (the relationship only lives through a binding node, or in another sync's data, or not at all): you must create the canonical edge, choosing the cheapest mechanism that fits (see When no direct edge exists). In both cases the canonical label is still declared as a RelConstraint and enforced by the guard.

Mechanism (the WORKLOAD_PARENT pattern)

For each existing direct CartographyRelSchema edge that connects two ontology-labelled nodes:

1. Add a new parallel rel class with rel_label = "<CANONICAL>", same target_node_label / matcher / direction as the existing edge, and register it in the node schema's other_relationships (both edges MERGE on every sync).
2. Keep the old edge but mark it # DEPRECATED: replaced by <CANONICAL>, will be removed in v1.0.0, and add its rel class to LEGACY_REL_WHITELIST in constraints.py.
3. Add a RelConstraint(src, dst, label) to ONTOLOGY_REL_CONSTRAINTS so the guard enforces the canonical label + direction whenever both endpoints carry the listed ontology labels.
4. Whitelist any other existing edge that shares the same ontology-label pair but carries a distinct semantic (reverse direction, or a different concept).

If a provider already uses the chosen canonical label, that edge is already compliant: leave it untouched (no parallel, no deprecation).

When no direct edge exists (genuine gap)

Sometimes a constrained pair has no direct provider edge to promote: the relationship only exists through a binding node (AWSInstanceProfile, AzureRoleAssignment), or the two endpoints are created in different syncs, or the data simply is not modelled yet. The constraint still belongs in constraints.py (it never requires the edge to exist), but to actually populate the edge you create it. Pick the cheapest mechanism that fits, in this strict priority order:

1. Classic CartographyRelSchema (preferred). Use when the source node's own payload already carries the target's identifier (e.g. an AWS Lambda payload holds its execution-role arn, an API-key payload holds its owner id). Add a normal rel class on the source schema pointing at the target label, with the canonical rel_label. This is just Step 4 without a deprecated sibling. Use the add-relationship skill for the mechanics.

2. MatchLink — always prefer this over an analysis job. Use when the two endpoints are created in different syncs, or the relationship is only derivable by resolving a binding node, so neither schema's payload can express it directly (e.g. AWSEC2Instance -[:ASSUMES]-> AWSRole resolved through the instance profile in the IAM sync; AzureVirtualMachine -[:ASSUMES]-> AzureRoleDefinition joined on the managed-identity principalId via AzureRoleAssignment). Assemble the (source_key, target_key) pairs in the owning sync and load them with load_matchlinks / a MatchLink schema carrying the canonical rel_label. The guard reads a MatchLink's direction + label too, so the canonical name is enforced. Use the add-relationship skill for MatchLink mechanics.

3. Analysis job (last resort). Only when the edge is purely transitive and the join genuinely cannot be assembled inside a single sync, so it must be computed post-sync by traversing the whole graph (e.g. deriving GCPInstance -[:ASSUMES]-> GCPRole across RUNS_AS + HAS_ROLE, where the compute sync and the IAM-policy-binding sync each hold only half the path). Add a Cypher analysis job (see the analysis-jobs skill) that MERGEs the canonical edge. If you reach for this, first re-confirm a MatchLink really cannot assemble the pairs; an analysis job is harder to test and to keep idempotent.

Whichever you pick, the canonical label/direction must match the RelConstraint, and the edge gets the same docs + integration-test treatment as a promoted edge. Edges through binding nodes are still not "direct" for the purposes of Step 3 — they are gaps, handled here.

Critical rules

1. The guard reads labels from the node schema (label + declarative extra_node_labels, including labels with conditions), not from the runtime graph. An edge is only constrained when both endpoints carry an ontology label in their schema. Edges through intermediate binding nodes (e.g. GCPPolicyBinding, KubernetesRoleBinding, AzureRoleAssignment) are NOT direct and are not affected by a rename.
2. Pick the canonical verb to fit the abstraction, not one provider. The label applies to the abstract semantic pair (e.g. UserAccount -> PermissionRole), which spans many providers. Prefer a neutral verb (HAS_ROLE, not ASSUME_ROLE, when the target generalises IAM roles, permission sets, and SaaS roles). Reserve action verbs (ASSUMES) for workload-identity/runtime semantics.
3. Backward compatibility is mandatory. Never rename in place. The old edge keeps being created (whitelisted) until v1.0.0 so existing queries/rules keep working.
4. Run the guard test to discover collisions: do not assume you found every edge by reading code. test_ontology_rel_constraints.py will list every offending rel (wrong label or reverse direction). Decide per edge: migrate (parallel + deprecate) or whitelist (distinct semantic).
5. Docs are generated, do not hand-edit schema.md. Module and ontology schema pages are built from the data model. The canonical edge reaches the ontology page through constraints.py and the model. The generator has no deprecation marker, so a relationship still declared in the model is still rendered. Update model docstrings and descriptions that name the old label, then build the docs to check the result.
6. Decouple internal queries from the deprecated label. If any analysis job / intel query traverses the old label, switch it to the canonical one (both edges exist, so it is equivalent and survives the v1.0.0 removal).
7. One commit per canonical edge. --signoff. No internal ticket or client references in committed text.