> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varianz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Naming and routing

> How VPoint names canonicalize to org/pkg/scope/entity, how stage targets match by suffix, and how selector and environment filters scope delivery.

## Canonical names

Every VPoint has a canonical lookup name of the form:

```
{org}/{pkg}/{scope}/{entity}
```

All components are kebab-case. `entity` is the operation itself; `scope` is its class/module grouping; `pkg` a functional grouping; `org` the top-level domain. Example: `my-app/pricing/calculator/calculate-shipping`.

You rarely write all four. When an explicit name contains `/`, its segments parse **right-aligned**, and unset components derive from your code's package/class/function structure:

| Annotation name                                  | org         | pkg         | scope        | entity               |
| ------------------------------------------------ | ----------- | ----------- | ------------ | -------------------- |
| `"calculate-shipping"`                           | *(derived)* | *(derived)* | *(derived)*  | `calculate-shipping` |
| `"calculator/calculate-shipping"`                | *(derived)* | *(derived)* | `calculator` | `calculate-shipping` |
| `"pricing/calculator/calculate-shipping"`        | *(derived)* | `pricing`   | `calculator` | `calculate-shipping` |
| `"my-app/pricing/calculator/calculate-shipping"` | `my-app`    | `pricing`   | `calculator` | `calculate-shipping` |

So the two-segment names used throughout these docs (`payment/charge`) set `scope/entity` and inherit `org`/`pkg` from the code. Derivation examples:

| Language    | Source                                             | Canonical name                                      |
| ----------- | -------------------------------------------------- | --------------------------------------------------- |
| Java/Kotlin | `com.example.pricing.Calculator.calculateShipping` | `com-example/pricing/calculator/calculate-shipping` |
| Python      | `my_app.pricing.calculator.calculate_shipping`     | `my-app/pricing/calculator/calculate-shipping`      |

Structs named via `@struct` / `@Struct` follow the same right-aligned rules; CEL resolves a bare `PricingResult { ... }` literal by the last segment.

## Stage routing targets

When inserting a stage, the target string tells the registry which VPoint to attach to:

```
[app_name:]vpoint_target [key=value...]
```

Examples:

```
calculate-shipping                                  # suffix match
my-app:calculate-shipping                           # + application filter
my-app:pricing/calculator/calculate-shipping        # fully qualified
calculate-shipping region=us-east-1 cluster=prod    # + environment filters
calculate-shipping org=my-app pkg=pricing           # + name-component filters
```

### Suffix matching

`vpoint_target` matches registered canonical names by suffix **on `/` boundaries**:

* `calculate-shipping` matches `my-app/pricing/calculator/calculate-shipping`
* `calculator/calculate-shipping` matches it too
* `ulate-shipping` does **not** match (not on a boundary)

**Exactly one match is required.** Zero matches is an error; multiple matches is an ambiguity error — add segments or filters to disambiguate.

### Name-component filters

After suffix matching, `org=` / `pkg=` / `scope=` / `entity=` filters narrow candidates by canonical-name components; all set filters must match (AND). Useful when the same entity name exists across packages.

### Environment filters

Stages can be scoped to deployment environments. A stage with filters reaches only clients whose advertised environment matches:

| Field              | Behavior                                                          |
| ------------------ | ----------------------------------------------------------------- |
| `application_name` | Exact match; set via the `app_name:` prefix                       |
| `region`           | Exact match; `region=...`                                         |
| `cluster`          | Exact match; `cluster=...`                                        |
| `tags`             | All stage tags must be present on the client with matching values |

Empty fields are wildcards — a stage without a `region` filter reaches all regions. Clients advertise their environment via SDK options or `VARIANZ_APPLICATION_NAME` / `VARIANZ_REGION` / `VARIANZ_CLUSTER` ([configuration](/reference/configuration#environment-tags)).

```python theme={null}
# Reaches only checkout-service instances in us-east-1 prod:
session.insert(cel(
    "checkout-service:calculate-shipping region=us-east-1 cluster=prod",
    "ctx.applyTax(invoke(), 0.1)",
))
```

## Resolution timing

Routing resolves against the registry's catalog **at insert time**, and the result is sticky — a stage never migrates to a VPoint registered later with a "better" name. Targets that match nothing yet are stored unresolved and attach when a matching VPoint appears (convenient for lazily-registered VPoints, but see the [delivery-barrier caveats](/testing/overview#insertion-vs-delivery)).