Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

docs(sequences): explain how a saved number moves the counter and drop the stale token warning

aashu7245049fa9e7
diff --git a/docs/content/docs/reference/sequences.mdx b/docs/content/docs/reference/sequences.mdx
index dffa5a477c..4f3fb0a416 100644
--- a/docs/content/docs/reference/sequences.mdx
+++ b/docs/content/docs/reference/sequences.mdx
@@ -21,19 +21,15 @@ Once created, a document's number never changes. Retuning a sequence only affect
<FieldTable>
<Field name="Prefix" type="text">Text prepended to the number. Optional; supports date tokens, so `PAY-%{yyyy}-%{mm}-` renders as `PAY-2026-07-`.</Field>
- <Field name="Current" type="integer">The last value handed out; the next document gets `Current + Step`. Set it to restart or fast-forward numbering. Must be `≥ 0`.</Field>
- <Field name="Size" type="integer">Zero-padding width: size `6` gives `000001`. Accepted range `1`–`20`; most sequences ship at `6`.</Field>
+ <Field name="Current" type="integer">The last value handed out; the next document gets `Current + Step`. Set it to restart or fast-forward numbering. Must be `≥ 0`. When a document is saved with a higher number in this sequence's format (typed as a custom ID, or sent through the API or an AI agent), Current moves up to it, so that number is never handed out again.</Field>
+ <Field name="Size" type="integer">Zero-padding width: size `6` gives `000001`. Accepted range `1`–`20`; most sequences ship at `6`. A counter that outgrows the size is issued in full, so size `6` at `1000000` gives `1000000`.</Field>
<Field name="Step" type="integer">How much the counter climbs each time. Almost always `1`; must be `≥ 1`.</Field>
<Field name="Suffix" type="text">Text appended after the number. Optional; same date tokens as the prefix.</Field>
</FieldTable>
### Date tokens
-Prefix and suffix can embed the current date — how payments and journal entries get their year/month partitioning. Tokens are interpolated when the number is generated, not when you save: `%{yyyy}` (2026), `%{yy}` (26), `%{mm}` (01–12), `%{dd}` (01–31), plus `%{hh}` and `%{ss}` for hour and second.
-
-<Callout type="warn" title="Hour and second tokens don't work for every document type">
-Customers, suppliers, and quotes are numbered by a database trigger that only understands the four **date** tokens; putting `%{hh}` or `%{ss}` in those sequences leaves the literal token in the number. Stick to date tokens unless you know the document type is generated by a server function.
-</Callout>
+Prefix and suffix can embed the current date — how payments and journal entries get their year/month partitioning. Tokens are interpolated when the number is generated, not when you save: `%{yyyy}` (2026), `%{yy}` (26), `%{mm}` (01–12), `%{ww}` (ISO week, 01–53), `%{dd}` (01–31), plus `%{hh}` and `%{ss}` for hour and second.
## Seed defaults
@@ -79,11 +75,16 @@ Accounting posts are the heaviest user of this machinery: every GL post pulls a
A sequence is a row in the `sequence` table keyed by `("table", "companyId")` (`20230525025310_sequences.sql`, PK moved in `20240704105128_rfq.sql:120`). The counter advances in the same operation that reads it (`packages/database/src/sequence.ts:76`). The form's live preview is `SequenceForm.tsx:38`; seed defaults are `packages/database/src/seed-data.ts:233`. Payments pick the right sequence by memo direction — credit memos draw `CR-`, debit memos `DR-` (`20260630093809_ar-ap-payments.sql:567`).
+A document saved with a number it was given moves its sequence past that number: the `sync_advance_document_sequence` interceptor (`packages/database/src/event-system/handlers/`) runs after every insert and number change on the numbered tables, reads the number with `util.document_sequence_pattern`, and raises `next` to it when it is higher. It never lowers `next`. The `document-sequence-synced` conformance check (`packages/checks`) fails CI when a new sequence is neither covered by it nor exempt.
+
### A sequence field won't save (Current, Step, or Size)
`sequenceValidator` bounds them (`settings.models.ts:285-292`): Current `≥ 0`, Step `≥ 1`, Size `1`–`20`. Values outside those ranges are rejected.
-### My `%{hh}` or `%{ss}` token shows up literally in the number
-Customers, suppliers, and quotes are numbered by a database trigger through the `get_next_sequence` RPC, which interpolates only `%{yyyy}`, `%{yy}`, `%{mm}`, `%{dd}` (`20241115101526_rpc-get-next-sequence.sql:42-51`). Server-function-generated documents support all six tokens. Use date tokens only for customer/supplier/quote prefixes.
+### Current jumped ahead on its own
+A document was saved with a higher number in the sequence's format, by a custom ID, the API, or an AI agent through MCP. Current moved up to it so the next automatic number does not collide. If the jump came from a typo, set Current back under Settings → Sequences, but not below the highest number already used.
+
+### "Failed to insert …" because the number is already taken
+Before `20261009171423_advance-document-sequence.sql`, a number chosen by the caller never moved the counter, so the counter later issued a number that already existed. `20261009171437_backfill-document-sequences.sql` moved every counter that was behind past the highest existing number. On the sales order form, typing a number that already exists shows "Sales order … already exists" on the field.
### Editing a sequence didn't renumber existing documents
By design: numbers are written at creation and never recomputed.