Skip to main content

​
Canonical names

Every VPoint has a canonical lookup name of the form:
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: So the two-segment names used throughout these docs (payment/charge) set scope/entity and inherit org/pkg from the code. Derivation examples: 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:
Examples:

​
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: 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).

​
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).