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 coordinator 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)
At most one match is required. Multiple matches is an ambiguity error — add segments or filters to disambiguate. Zero matches is not an error. Insertion is lazy by default: a target that matches nothing is stored unresolved and attaches if a matching VPoint appears later, so a typo’d target inserts cleanly, passes await_sync_or_fail(), and never applies:
The barrier confirms subscribers, not routing. See insertion vs. delivery for how to tell the two apart.
Duplicate canonical names are not detected. Two VPoints registered under one name are both accepted with no ambiguity error. The last one registered wins and the other becomes silently un-stageable; in Go, validation and execution can resolve to different registrants, so an expression that validates cleanly runs against the other VPoint’s schema.Keep VPoint names unique across every process that talks to one coordinator — there is no diagnostic to check, in any runtime.

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