Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

sequential_numbering

/sequential_numbering

Przydziela bezluków i niepowtarzalne numery faktur, zamówień i zgłoszeń w RavenDB, z bezpieczną współbieżnością i ponawianiem zapisu.

Repozytorium
claude-plugins ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Przydziela bezluków i niepowtarzalne numery faktur, zamówień i zgłoszeń w RavenDB, z bezpieczną współbieżnością i ponawianiem zapisu.

Oryginalny opis (EN)

Allocate gapless, never-duplicated human-facing numbers (invoice/order/ticket): a sequence document per prefix+period (`INV/25`), allocation on finalize behind a `??=` guard, RavenDB arbitrating via `UseOptimisticConcurrency` + retry on `ConcurrencyException`; alternatives: `CounterBatchOperation`, a `ClusterWide` compare-exchange. PROACTIVE: invoke when the user needs a sequence or per-year number, concurrency-safe numbering, or mentions optimistic concurrency, RavenDB counters, IncrementAndGet, a sequence document. Not for the document id itself (see /vidyano:lifecycle_hooks).

Jak działa

  1. When to use
  2. Why the document id won't do
  3. A counter per prefix and period
  4. Allocate on finalize, reuse on resend
  5. The core tension: gaps, duplicates, and contention
  6. Option A — sequence document with optimistic concurrency (recommended)
  7. The duplicate trap: increment-then-get in one session
  8. Option B — immediate atomic increment (when gaps are acceptable)
  9. Option C — deferred-delta scope (single-threaded batches)
  10. Option D — cluster-wide transaction with compare-exchange (strictest)
Sekcje z nagłówków SKILL.md, w oryginale · 261 linii, 1 882 słów
Podgląd SKILL.md
---
name: sequential_numbering
description: "Allocate gapless, never-duplicated human-facing numbers (invoice/order/ticket): a sequence document per prefix+period (`INV/25`), allocation on finalize behind a `??=` guard, RavenDB arbitrating via `UseOptimisticConcurrency` + retry on `ConcurrencyException`; alternatives: `CounterBatchOperation`, a `ClusterWide` compare-exchange. PROACTIVE: invoke when the user needs a sequence or per-year number, concurrency-safe numbering, or mentions optimistic concurrency, RavenDB counters, IncrementAndGet, a sequence document. Not for the document id itself (see /vidyano:lifecycle_hooks)."
user-invocable: true
---

# Sequential Numbering & Counters

Many aggregates need a **human-facing sequence number** distinct from their storage id: an invoice number `INV/25/0042`, an order number, a ticket number. It must be gapless or near-gapless, reset per year, and — above all — **never duplicate**, because two invoices sharing a number is a real accounting problem.

This is harder than it looks: the obvious "load a counter, increment it, save it" races under concurrency — *unless* you let the database arbitrate the race. The counter, operation, and optimistic-concurrency APIs here are stock RavenDB; the one CronosCore add-on (`IncrementAndGet`) is the trap to avoid.

Not for: the document id itself — deterministic or natural ids are assigned in `AddToContext` (`/vidyano:lifecycle_hooks`) — or the save hook the allocation runs from (`/vidyano:lifecycle_hooks`, `OnSave`).

## When to use

The user needs an invoice/order/ticket/sequence number, a per-year counter, concurrency-safe numbering with no duplicates, or mentions optimistic concurrency / `UseOptimisticConcurrency` / `ConcurrencyException` / RavenDB counters / `CounterBatchOperation` / `IncrementAndGet` / a sequence document.

## Why the document id won't do

A natural id or a server-generated id is fine for *addressing* a document, but it's a poor human-facing number: opaque, doesn't reset per year, and you often want the number assigned only when the document is **finalized** (sent), not when the draft is created. So the sequence number is a **separate, allocated value** stored on the aggregate. (This is the human-facing number — distinct from a derived document id, which is a different concern.)

## A counter per prefix and period

Whatever stores the running number, **key it by prefix and period** — a separate counter for each `prefix/yy` — so a new year is just a new key starting at 0, with no reset job:

```
INV/25  → 42
INV/26  → 7
SBI/25  → 13
```

Either way, the same helper turns the value into the final string:

```csharp
private static string FormatReference(string prefix, DateTime period, long count) =>
    $"{prefix}/{period:yy}/{count:D4}";   // INV/25/0042
```

## Allocate on finalize, reuse on resend

Assign the number when the aggregate is **finalized** (saved/sent), guarded so it only allocates if a number isn't already set:

```csharp
invoice.Reference ??= AllocateReference(prefix, invoice.Date);
```

The `??=` makes allocation happen **once**: an abandoned draft never burns a number, and a resend sees a non-null `Reference` and reuses it instead of allocating again.

## The core tension: gaps, duplicates, and contention

Three failure modes pull against each other:

- **Gaps** — a number is allocated, the surrounding save fails, the number is burned. Harmless for accounting, ugly in an audit.
- **Duplicates** — two writers read the same value and both claim the next number. Never acceptable.
- **Contention** — serializing allocation so neither happens, paid for in retries or waiting.

You can't zero all three — but you don't have to treat "gaps or duplicates" as the only choice. For normal volumes, eliminate *both* and absorb the cost as **occasional retries**: that's Option A, and it's what to reach for first. The fallback judgement, when you genuinely must trade: **gaps are harmless; duplicates are not.**

## Option A — sequence document with optimistic concurrency (recommended)

Store the running number as a plain property on a small **sequence document**, one per prefix+period, and let RavenDB's **optimistic concurrency** arbitrate. The number is allocated, stamped onto the entity, and the incremented counter saved **in the same `SaveChanges` batch** — they commit together or not at all. A concurrent bump throws `ConcurrencyException`; reload, take the next number, retry. A failed attempt commits nothing, so there's neither a gap nor a duplicate.

```csharp
public class NumberSequence
{
    public string Id { get; set; } = null!;   // "sequences/INV/25"
    public long Last { get; set; }
}
```

```csharp
private Invoice CreateNumberedInvoice(string prefix, DateTime period)
{
    // Make the save fail if the sequence document changed under us.
    Context.Session.Advanced.UseOptimisticConcurrency = true;
    var seqId = $"sequences/{prefix}/{period:yy}";

    for (var attempt = 0; attempt < 5; attempt++)   // bounded: a pathological hotspot errors instead of spinning
    {
        var seq = Context.Session.Load<NumberSequence>(seqId);
        if (seq is null)
        {
            seq = new NumberSequence { Id = seqId };
            Context.Session.Store(seq);   // a null change vector enforces "must not already exist"
        }

        seq.Last++;
        var invoice = new Invoice { Reference = FormatReference(prefix, period, seq.Last) };
        Context.Session.Store(invoice);

        try
        {
            Context.SaveChanges();        // counter + invoice committed atomically
            return invoice;
        }
        catch (ConcurrencyException)
        {
            // Someone took a number first — nothing was committed (no gap).
            // Evict only the stale pair (not Clear(), so other pending work survives) and retry.
            Context.Session.Advanced.Evict(seq);
            Context.Session.Advanced.Evict(invoice);
        }
    }

    throw new InvalidOperationException($"Could not allocate a number for {seqId} after 5 attempts.");
}
```

Why reach for it first: **gapless** (increment shares the transaction with the document that uses it), **concurrency-safe** (the loser retries), **multi-threaded** (the retry, not a lock, serializes the race), **no special primitive** (a plain `long` + `try`/`catch`). The cost is **contention** — the sequence document is a write hotspot — but for invoice/order/ticket volumes that's negligible.

## The duplicate trap: increment-then-get in one session

If you use RavenDB counters (Options B/C), there's a tempting wrong turn that ships duplicates — incrementing and then reading back in the same session:

```csharp
// LOOKS fine, IS a trap when allocating several numbers in one session.
session.CountersFor(docId).Increment(counterName);          // deferred until SaveChanges
var count = session.CountersFor(docId).Get(counterName);    // reads the last PERSISTED value
```

`Increment` is **deferred to `SaveChanges`**, but `Get` reads the last *persisted* value. Allocate three numbers before one `SaveChanges` and all three read the same base — `42, 42, 42`. This is exactly how a batch produces duplicate references. (CronosCore wraps this pair as an `IncrementAndGet` extension — same trap.) Don't allocate multiple numbers per session this way.

## Option B — immediate atomic increment (when gaps are acceptable)

Increment the counter on the server *immediately*, via a store operation outside the session transaction, and use what it returns:

```csharp
private string AllocateReference(string prefix, DateTime period)
{
    var counterName = $"{prefix}/{period:yy}";
    var result = Context.Session.Advanced.DocumentStore.Operations.Send(
        new CounterBatchOperation(new CounterBatch
        {
            Documents =
            [
                new DocumentCountersOperation
                {
                    DocumentId = "Settings/InvoiceNumbers",
                    Operations = [ new CounterOperation
                    {
                        CounterName = counterName,
                        Delta = 1,
                        Type = CounterOperationType.Increment,
                    } ],
                }
            ],
        }));

    var count = result.Counters[0].CounterValues.First().Value;
    return FormatReference(prefix, period, count);
}
```

Because the increment is server-side and atomic, two concurrent callers always get distinct numbers. The cost: if `SaveChanges()` later throws, that number is gone — a gap. Choose this over Option A only when you specifically want to avoid the optimistic-concurrency retry (very high contention) and gaps are fine.

## Option C — deferred-delta scope (single-threaded batches)

When you must avoid gaps in a **single-threaded batch** that allocates many numbers, read each counter's base once, accumulate deltas in memory, and flush them as part of the unit of work:

```csharp
internal sealed class CounterScope(IDocumentSession session) : IDisposable
{
    private readonly Dictionary<(string counter, string doc), (long baseValue, long delta)> _counters = [];

    public long Next(string counterName, string documentId)
    {
        var key = (counterName, documentId);
        if (!_counters.TryGetValue(key, out var c))
            c = (session.CountersFor(documentId).Get(counterName) ?? 0, 0);   // read persisted base once
        c.delta++;
        _counters[key] = c;
        return c.baseValue + c.delta;                                        // base + running local delta
    }

    public void Dispose()
    {
        foreach (var ((counter, doc), (_, delta)) in _counters)
            session.CountersFor(doc).Increment(counter, delta);              // queue the real increment
    }
}
```

The `using` block **must close before `SaveChanges()`**, so the deferred increments are queued into that save:

```csharp
private void NumberBatch(IEnumerable<Invoice> batch, string prefix)
{
    using (var scope = new CounterScope(Context.Session))
    {
        foreach (var invoice in batch)
            invoice.Reference = FormatReference(prefix, invoice.Date,
                scope.Next($"{prefix}/{invoice.Date:yy}", "Settings/InvoiceNumbers"));
    }                       // Dispose() queues the increments...
    Context.SaveChanges();  // ...and this persists invoices + counter deltas atomically.
}
```

Gapless because nothing commits until `SaveChanges`. **Only safe single-threaded** — two concurrent batches read the same base and collide. Reserve it for a high-volume single-threaded batch where per-number retries would be wasteful.

## Option D — cluster-wide transaction with compare-exchange (strictest)

Option A's optimistic concurrency is arbitrated by the node that owns the document; in a multi-node cluster with failover a rare split-second duplicate is theoretically possible. When a gap *and* a duplicate are both unacceptable, hold the running number in a **compare-exchange** key and commit inside a **cluster-wide** session — its `SaveChanges` is a Raft consensus, so the key and the invoice commit together on every node or not at all:

```csharp
using Raven.Client.Documents.Session;
using Raven.Client.Exceptions;

private Invoice CreateNumberedInvoiceClusterWide(string prefix, DateTime period)
{
    var store = Context.Session.Advanced.DocumentStore;
    var key = $"sequences/{prefix}/{period:yy}";

    for (var attempt = 0; attempt < 5; attempt++)
    {
        // A separate session: cluster-wide mode cannot be switched on for the request's own session.
        using var session = store.OpenSession(new SessionOptions { TransactionMode = TransactionMode.ClusterWide });

        var seq = session.Advanced.ClusterTransaction.GetCompareExchangeValue<long>(key);
        var next = (seq?.Value ?? 0) + 1;
        if (seq is null)
            session.Advanced.ClusterTransaction.CreateCompareExchangeValue(key, next);
        else
            seq.Value = next;                                   // tracked: SaveChanges sends it with its index

        var invoice = new Invoice { Reference = FormatReference(prefix, period, next) };
        session.Store(invoice);

        try
        {
            session.SaveChanges();                              // key + invoice commit together, cluster-wide
            return invoice;
        }
        catch (ConcurrencyException)
        {
            // another writer moved the key first — the whole transaction was rejected; retry
        }
    }

    throw new InvalidOperationException($"Could not allocate a number for {key} after 5 attempts.");
}
```

The invoice lives in that separate session, not in `Context` — return its id and `Context.Session.Load` it if the request keeps working on it. Heavier than Option A (every allocation is a cluster round-trip), so reserve it for the case where the strict guarantee is a requirement, not a preference.

## Checklist

- [ ] Number keyed by **prefix + period** (`INV/25`) so year rollover is free — period is part of the key/name, never a reset job.
- [ ] Allocated on **finalize** (save/send) with a `??=` guard — drafts don't burn numbers, resends reuse.
- [ ] **Option A** preferred: sequence document, `UseOptimisticConcurrency = true`, increment + stamp + save in one batch, retry on `ConcurrencyException`, **bounded** loop, `Evict` (not `Clear`) on retry.
- [ ] **Never** `IncrementAndGet` (or unguarded load-increment-save) for several numbers in one session — deferred increment + stale `Get` yields duplicates.
- [ ] Option B (immediate `CounterBatchOperation`) only when gaps are acceptable; Option C (deferred `CounterScope`, dispose **before** `SaveChanges`) only single-threaded.
- [ ] Cluster-strict need: Option D (`TransactionMode.ClusterWide` + compare-exchange) — heavier; only when a gap *and* a rare duplicate are both unacceptable.

## Verify

1. Build; finalize one invoice: its `Reference` reads `INV/25/0001` and RavenDB Studio shows `sequences/INV/25` with `Last: 1` (Option D: the compare-exchange key under Documents → Compare Exchange).
2. Finalize a second invoice and resend the first: the second is `0002`, the first still `0001`, `Last` is 2.
3. Concurrency: finalize two invoices at the same moment (two browser sessions, or a small parallel test): both numbers are distinct, `Last` equals the count of numbered invoices, and the log shows a retry rather than an error.
4. Roll the period: finalize an invoice dated next year and a new `sequences/INV/26` document appears at `Last: 1` with no reset job.
5. Negative: make the save fail after allocation (trip a rule): with Option A or D no sequence changed; with Option B the counter advanced — the accepted gap.

## Related skills

- `/vidyano:lifecycle_hooks` — allocation usually runs in `OnSave` (or the action that sends). The human-facing sequence number is separate from any derived document id.

Wersje

W bazie nie ma innych skilli o nazwie sequential_numbering.

Migawka bazy z 13.11.2026 · wersja paczki 7965d1b001f0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95query_models
    Buduje model zapytań Vidyano na indeksie RavenDB, z denormalizacją danych, kolumnami i przekierowaniem do edycji rekordu.
  • 95map_reduce_indexes
    Pisze ręcznie indeksy RavenDB z mapowaniem i redukcją, indeksy wielokolekcyjne i liczniki, których generator nie tworzy.
  • 100tenant-document-numbering
    Projektuje ciągłe, nigdy nieresetowane numery dokumentów, np. faktur i zamówień, osobno dla każdego najemcy w systemie.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.