Number Series

Several entities in Hantera carry a human-readable, auto-incrementing number — orders, invoices, deliveries, payments, assets and tickets. These numbers are produced by number series, and both the prefix and the start number of each series are configurable through the registry.

What a number series is

A number series is the pair (numbering entity, prefix). The growing counter belongs to the series, not to the channel or the actor type. This has an important consequence:

Two ticket types that resolve to the same prefix share a counter.

The counter is global per series. There is no per-channel or per-type counter — only a per-prefix one. This keeps numbering predictable and matches how the underlying counter is seeded (from the maximum existing number for that prefix).

Entities that get numbers

Entity	Default prefix	Notes
order	O
invoice	I	Sub-entity of the order actor
delivery	D	Sub-entity of the order actor
payment	P
asset	none	Typed — defined by asset type
ticket	none	Typed — defined by ticket type

Prefix and seed

Each series has two configurable aspects:

• Prefix — the text in front of the number (e.g. O in O1042).
• Seed — the start number for the series. The counter never produces a number below the seed. If existing data already has higher numbers, the counter continues from there. The default seed is 1000.

Both live under the owning actor in the registry, so an administrator can override the read-only defaults that an app's actor/type specs provide.

Configuring numbering

Base configuration is stored under the actor:

actors/{actor}/numbering/{...scope}

The value (NumberingConfig) carries a default prefix and a per-prefix seed map:

uri: /registry/actors/order/numbering/order
spec:
  value:
    defaultPrefix: O
    seeds:
      O: 1000

• defaultPrefix — default prefix for the scope. Only honored for typeless entities (order, invoice, delivery, payment). For typed entities (asset, ticket) the type spec supplies the prefix, so a defaultPrefix here is ignored and raises a warning signal.
• seeds — start numbers keyed by prefix. Seeds are global per series and are never channel-overridable.

See the actors/{actor}/numbering reference for the full value format.

Scope

The {...scope} segment identifies the series within the actor:

Actor	Scope	Example leaf
order	order	actors/order/numbering/order
order → invoice	invoice	actors/order/numbering/invoice
order → delivery	delivery	actors/order/numbering/delivery
payment	payment	actors/payment/numbering/payment
ticket (typed)	{typeKey}	actors/ticket/numbering/{typeKey}
asset (typed)	{typeKey}	actors/asset/numbering/{typeKey}

For typed actors the scope is the type key.

Channel overrides

Channels can override the prefix of a series (but never the seed, which is global):

actors/{actor}/channels/{channelKey}/numbering/{...scope}

uri: /registry/actors/order/channels/b2b/numbering/order
spec:
  value:
    defaultPrefix: B2B

Only defaultPrefix is honored here; a seeds map on a channel override raises a warning signal. Channel overrides are only effective for actors that carry a channelKey — today that is order and ticket.

See the actors/{actor}/channels/{channelKey}/numbering reference.

Resolution

When a number is generated, the prefix is resolved with this precedence:

explicit prefix on the command
  ?? channel override   actors/{actor}/channels/{ch}/numbering/{...scope}.defaultPrefix
  ?? base config        actors/{actor}/numbering/{...scope}.defaultPrefix
  ?? type spec          actors/{actor}/types/{typeKey}.DefaultNumberPrefix   (typed actors)
  ?? built-in fallback  (O / I / D / P / AS / T)

The seed is then read from actors/{actor}/numbering/{...scope}.seeds[prefix] (must be a positive number), falling back to 1000.

Generating numbers

Numbers are generated in two ways:

• Automatically on create. When an entity is created, the actor appends an internal command that resolves the prefix and seed and assigns the next number. If a number prefix is already set, this silently skips — re-running create is safe.
• Explicitly, by prefix. The public Generate{Entity}NumberByPrefix commands take a required prefix and generate a number with it. Unlike auto-generation, these fail if a number prefix is already set on the entity. They are intended for entities that were created without a number, or for deliberate, controlled assignment.

Live view

The current next number for each active series is exposed read-only under the system namespace:

system/actors/{entity}/numbering/{entity}/{prefix}

This reflects the in-memory counter and is useful for monitoring. It cannot be written.