@byline/core 2.1.3 → 2.2.0

package/dist/@types/db-types.d.ts

@@ -164,12 +164,55 @@ export interface IDbAdapter {
     commands: {
         collections: ICollectionCommands;
         documents: IDocumentCommands;
+        counters: ICounterCommands;
     };
     queries: {
         collections: ICollectionQueries;
         documents: IDocumentQueries;
     };
 }
+/**
+ * Adapter capability for the shared-pool counter mechanism backing the
+ * `counter` field type. See `packages/core/src/@types/field-types.ts`
+ * (CounterField) for the field-level contract and `docs/COLLECTIONS.md`
+ * (Counter fields) for the conceptual overview.
+ *
+ * Both methods are keyed by the developer-facing `groupName` (the value
+ * of `CounterField.group`). The adapter is responsible for translating
+ * that into whatever backing primitive it uses (a Postgres SEQUENCE for
+ * the Postgres adapter) and for keeping the `byline_counter_groups`
+ * registry table in sync.
+ */
+export interface ICounterCommands {
+    /**
+     * Idempotently register a counter group and ensure its backing
+     * sequence exists. Called once per discovered group at boot by the
+     * collection-bootstrap layer (`@byline/core`). Safe to call
+     * concurrently across multiple booting processes — implementations
+     * must use `IF NOT EXISTS` / `ON CONFLICT DO NOTHING` semantics so
+     * two processes racing on the same group leave the system with
+     * exactly one sequence and one registry row.
+     *
+     * Returns the resolved sequence name so callers (tests, doctor
+     * tooling) can inspect what was created without re-deriving it.
+     */
+    ensureCounterGroup(groupName: string): Promise<{
+        groupName: string;
+        sequenceName: string;
+    }>;
+    /**
+     * Atomically allocate the next value from the named group's
+     * sequence. Called on every document create that includes one or
+     * more `counter` fields (see assignCounterValues in
+     * document-lifecycle). Throws if the group has not been registered
+     * via `ensureCounterGroup` — the lifecycle layer is expected to
+     * surface that as a configuration error, not silently retry.
+     *
+     * Gaps are expected: sequences leak on rolled-back transactions
+     * and deletes. The facet-URL use case does not require gapless IDs.
+     */
+    nextCounterValue(groupName: string): Promise<number>;
+}
 export interface ICollectionCommands {
     /**
      * Insert a new collection row. `opts.version` and `opts.schemaHash` are

package/dist/@types/field-data-types.d.ts

@@ -18,6 +18,7 @@ type BaseFieldDataTypes = {
     float: number;
     group: never;
     integer: number;
+    counter: number;
     json: unknown;
     object: unknown;
     richText: unknown;

package/dist/@types/field-types.d.ts

@@ -155,6 +155,24 @@ interface BaseField {
      * document to be considered valid.
      */
     optional?: boolean;
+    /**
+     * When `true`, the field's input widget renders in a read-only state.
+     * The editor can see the value but cannot change it through the form UI.
+     *
+     * This is a **rendering hint only** — it does not enforce immutability
+     * on the server. A determined caller can still send a value via the
+     * API. Server-side immutability is a separate concern; for fields
+     * whose values must be locked at the storage layer (e.g. allocator-
+     * assigned counters), the lifecycle layer enforces that independently
+     * of this flag. Use this flag for editor UX (locking computed fields,
+     * externally-assigned IDs like DOIs, fields that should only be set
+     * by a workflow transition), not as a security boundary.
+     *
+     * Whether a given widget honours this flag is per-widget — most ui-kit
+     * input components support a native readOnly state, and widgets are
+     * being progressively updated to forward this prop through.
+     */
+    readOnly?: boolean;
     /**
      * Optional field-level hooks that run on the client during editing.
      * @see FieldHooks
@@ -336,6 +354,37 @@ export interface DecimalField extends NonlocalizableField {
     type: 'decimal';
     defaultValue?: DefaultValue<string>;
 }
+/**
+ * An allocator-assigned integer field whose value is drawn from a shared,
+ * monotonically-increasing pool identified by `group`. Multiple counter
+ * fields — across the same collection or different collections — that
+ * declare the same `group` share a single ID sequence. The first document
+ * created with a counter field gets `1`, the next `2`, and so on, regardless
+ * of which collection the create originated in.
+ *
+ * The use case is faceted filtering across small "term" collections (e.g.
+ * Topic, Format, Geography) with URLs like `/library?t=1&t=4&t=9`, where
+ * each numeric ID resolves to a term in one of the collections via the
+ * shared pool.
+ *
+ * Values are assigned at create time and immutable thereafter — the field
+ * has no `defaultValue`, no `validation` slot, and updates that touch the
+ * counter field are ignored by the lifecycle layer. Duplicates of a
+ * document receive a fresh counter value, not the source's.
+ *
+ * Backed by a Postgres `SEQUENCE` per group; gaps may occur on rolled-back
+ * transactions and deletes, which is fine for the facet-URL use case.
+ */
+export interface CounterField extends NonlocalizableField {
+    type: 'counter';
+    /**
+     * Counter group name. Shared across all counter fields — in any
+     * collection — that declare the same string. Pick something descriptive
+     * and stable (e.g. `'library-facets'`); renaming a group later means
+     * creating a new sequence and starting over at 1.
+     */
+    group: string;
+}
 export interface JsonField extends LocalizableField {
     type: 'json';
     defaultValue?: DefaultValue<unknown>;
@@ -384,7 +433,7 @@ export interface ImageField extends NonlocalizableField {
     upload?: UploadConfig;
 }
 export type StructureField = GroupField | ArrayField | BlocksField;
-export type ValueField = TextField | TextAreaField | CheckboxField | BooleanField | SelectField | RichTextField | TimeField | DateField | DateTimeField | FloatField | IntegerField | DecimalField | JsonField | ObjectField | RelationField | FileField | ImageField;
+export type ValueField = TextField | TextAreaField | CheckboxField | BooleanField | SelectField | RichTextField | TimeField | DateField | DateTimeField | FloatField | IntegerField | DecimalField | CounterField | JsonField | ObjectField | RelationField | FileField | ImageField;
 export type Field = StructureField | ValueField;
 export type FieldSet = readonly Field[];
 export type ValueFieldType = ValueField['type'];

package/dist/core.js

@@ -11,6 +11,7 @@ import { defineBylineCore, defineServerConfig, getBylineCoreUnsafe } from './con
 import { createBylineLogger, defineLogger } from './lib/logger.js';
 import { Registry } from './lib/registry.js';
 import { ensureCollections } from './services/collection-bootstrap.js';
+import { discoverCounterGroups } from './services/discover-counter-groups.js';
 import { validateRichTextFieldFlags } from './services/richtext-populate.js';
 /**
  * Initialize Byline CMS core services via the typed registry.
@@ -52,6 +53,17 @@ export const initBylineCore = async (config, pinoLogger) => {
         db: composed.db,
         logger: composed.logger,
     });
+    // Discover every distinct counter `group` across the registered
+    // collections and ensure each one has a backing sequence in the
+    // database. Runs after ensureCollections (collection-shape errors
+    // surface first) and throws on any structural ban (counter inside
+    // array/blocks) or adapter failure — both are fatal config issues
+    // that should fail boot rather than show up at request time.
+    await discoverCounterGroups({
+        definitions: composed.collections,
+        db: composed.db,
+        logger: composed.logger,
+    });
     const getCollectionRecord = (path) => {
         const record = collectionRecords.get(path);
         if (!record) {

package/dist/schemas/zod/builder.js

@@ -112,6 +112,11 @@ export const fieldToZodSchema = (field, strict = true) => {
         case 'integer':
             schema = z.number().int();
             break;
+        case 'counter':
+            // Counter values are allocator-assigned; the wrapping below forces
+            // the schema to allow undefined regardless of `field.optional`.
+            schema = z.number().int();
+            break;
         case 'float':
         case 'decimal':
             schema = z.number();
@@ -172,9 +177,13 @@ export const fieldToZodSchema = (field, strict = true) => {
         default:
             schema = z.string();
     }
+    // Counter fields are implicitly populated by the lifecycle layer (see
+    // assignCounterValues in document-lifecycle), so callers must be able to
+    // omit them on create. Treat them as always-optional in input schemas.
+    const implicitlySet = field.type === 'counter';
     // In strict mode respect field.optional; in lenient mode always allow null/undefined so reads
     // never fail on schema-evolved documents.
-    return strict && !field.optional ? schema : schema.nullable().optional();
+    return strict && !field.optional && !implicitlySet ? schema : schema.nullable().optional();
 };
 // Create the base schema that all collections share.
 // When a collection defines a workflow, status is constrained to its status names;

package/dist/services/assign-counter-values.d.ts

@@ -0,0 +1,61 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type FieldSet } from '../@types/index.js';
+import type { ICounterCommands } from '../@types/db-types.js';
+export interface AssignCounterValuesInput {
+    fields: FieldSet;
+    /**
+     * The document data being written. Mutated in place — counter sites
+     * are overwritten with allocator-assigned values (on create / when
+     * no previous value exists) or with the previous version's value
+     * (on update). Caller-supplied counter values are NOT trusted, even
+     * on create: they are always replaced by `nextCounterValue` or by
+     * the previous version's value.
+     */
+    data: Record<string, any>;
+    /**
+     * Reconstructed fields from the previous version (update path only).
+     *
+     * When provided, counter values are copied forward from here rather
+     * than re-allocated — counter fields are immutable across versions
+     * of the same document. If the previous version is missing a value
+     * for a counter (e.g. the field was added to the collection after
+     * the document was created), a new value is allocated lazily so
+     * subsequent updates always see a populated counter.
+     *
+     * When omitted (create / duplicate / restore-as-new), every counter
+     * site is freshly allocated.
+     */
+    previousData?: Record<string, any>;
+    counters: ICounterCommands;
+}
+/**
+ * Populate every counter field in `data` with its canonical value
+ * before the document is flattened and persisted. Called by the
+ * lifecycle layer immediately before `db.commands.documents
+ * .createDocumentVersion` so the values land in `store_numeric` on
+ * the same write.
+ *
+ * Behaviour by lifecycle path:
+ *
+ *   - create:   `previousData` is undefined → every counter field is
+ *               freshly allocated, any caller-supplied value is
+ *               overwritten.
+ *
+ *   - update:   `previousData` is the prior version's reconstructed
+ *               fields → counter values are copied forward. Lazy
+ *               backfill fires for any counter the prior version is
+ *               missing (e.g. field added post-hoc).
+ *
+ *   - duplicate: caller strips counter values from the cloned source
+ *               before invoking the create path → fresh allocation
+ *               applies. (The strip itself is enforced by passing
+ *               `previousData: undefined`; even if the clone retains
+ *               the source's value, the create path overwrites it.)
+ */
+export declare function assignCounterValues({ fields, data, previousData, counters, }: AssignCounterValuesInput): Promise<void>;

package/dist/services/assign-counter-values.js

@@ -0,0 +1,110 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/index.js';
+/**
+ * Walk a `(fields, data)` pair and yield every counter-field site,
+ * descending into groups but never into arrays or blocks (which are
+ * banned for counters at discovery time, see discoverCounterGroups).
+ *
+ * Unlike `walkFieldTree`, this walker yields counter sites *even when
+ * the value is null or undefined* — that's the exact case where we
+ * need to allocate a fresh value.
+ *
+ * A missing or non-object container for a group field is treated as
+ * empty: the group is created on demand so the assigned value has
+ * somewhere to land.
+ */
+function* walkCounterSites(fields, data, pathPrefix = '') {
+    for (const field of fields) {
+        const path = pathPrefix === '' ? field.name : `${pathPrefix}.${field.name}`;
+        if (field.type === 'counter') {
+            yield { field, parent: data, key: field.name, path };
+            continue;
+        }
+        if (isGroupField(field)) {
+            let container = data[field.name];
+            if (container == null || typeof container !== 'object' || Array.isArray(container)) {
+                // Materialise the group container so the counter site has a
+                // parent to mutate. Counter fields nested in groups on
+                // freshly-minted documents arrive with no group object at all.
+                container = {};
+                data[field.name] = container;
+            }
+            yield* walkCounterSites(field.fields, container, path);
+            continue;
+        }
+        // arrays / blocks are banned at discovery time — they can't contain
+        // counters, so we don't descend. All other value field types are
+        // not our concern.
+        if (isArrayField(field) || isBlocksField(field))
+            continue;
+    }
+}
+/**
+ * Resolve a counter value already present in `previousData` at the
+ * same dotted path as the site. Returns `undefined` if the value is
+ * missing or not a finite number.
+ */
+function readPreviousValue(previousData, path) {
+    const segments = path.split('.');
+    let cursor = previousData;
+    for (const segment of segments) {
+        if (cursor == null || typeof cursor !== 'object' || Array.isArray(cursor))
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return typeof cursor === 'number' && Number.isFinite(cursor) ? cursor : undefined;
+}
+/**
+ * Populate every counter field in `data` with its canonical value
+ * before the document is flattened and persisted. Called by the
+ * lifecycle layer immediately before `db.commands.documents
+ * .createDocumentVersion` so the values land in `store_numeric` on
+ * the same write.
+ *
+ * Behaviour by lifecycle path:
+ *
+ *   - create:   `previousData` is undefined → every counter field is
+ *               freshly allocated, any caller-supplied value is
+ *               overwritten.
+ *
+ *   - update:   `previousData` is the prior version's reconstructed
+ *               fields → counter values are copied forward. Lazy
+ *               backfill fires for any counter the prior version is
+ *               missing (e.g. field added post-hoc).
+ *
+ *   - duplicate: caller strips counter values from the cloned source
+ *               before invoking the create path → fresh allocation
+ *               applies. (The strip itself is enforced by passing
+ *               `previousData: undefined`; even if the clone retains
+ *               the source's value, the create path overwrites it.)
+ */
+export async function assignCounterValues({ fields, data, previousData, counters, }) {
+    const sites = Array.from(walkCounterSites(fields, data));
+    if (sites.length === 0)
+        return;
+    // For each site, decide what value to write and resolve any sequence
+    // allocations in parallel. nextCounterValue is independent across
+    // groups, so there's no ordering constraint.
+    await Promise.all(sites.map(async (site) => {
+        // Update path: try to carry forward.
+        if (previousData !== undefined) {
+            const carried = readPreviousValue(previousData, site.path);
+            if (carried !== undefined) {
+                site.parent[site.key] = carried;
+                return;
+            }
+            // Lazy backfill — previous version had no value, but the
+            // field is declared. Fall through to allocation so the
+            // document is never left with a missing counter after an
+            // update touches it.
+        }
+        const value = await counters.nextCounterValue(site.field.group);
+        site.parent[site.key] = value;
+    }));
+}

package/dist/services/assign-counter-values.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/assign-counter-values.test.node.js

@@ -0,0 +1,163 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { assignCounterValues } from './assign-counter-values.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+function makeCounters(start = 1) {
+    let next = start;
+    const calls = [];
+    return {
+        counters: {
+            ensureCounterGroup: vi.fn(),
+            nextCounterValue: vi.fn(async (group) => {
+                calls.push(group);
+                return next++;
+            }),
+        },
+        calls,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('assignCounterValues', () => {
+    it('is a no-op when no counter fields are declared', async () => {
+        const { counters, calls } = makeCounters();
+        const fields = [{ name: 'title', type: 'text' }];
+        const data = { title: 'hello' };
+        await assignCounterValues({ fields, data, counters });
+        expect(calls).toEqual([]);
+        expect(data).toEqual({ title: 'hello' });
+    });
+    it('allocates a value for a single counter at root on create', async () => {
+        const { counters, calls } = makeCounters(42);
+        const fields = [
+            { name: 'label', type: 'text' },
+            { name: 'facetId', type: 'counter', group: 'library-facets' },
+        ];
+        const data = { label: 'Forestry' };
+        await assignCounterValues({ fields, data, counters });
+        expect(data.facetId).toBe(42);
+        expect(calls).toEqual(['library-facets']);
+    });
+    it('overwrites a caller-supplied counter value on create', async () => {
+        const { counters, calls } = makeCounters(7);
+        const fields = [{ name: 'facetId', type: 'counter', group: 'library-facets' }];
+        const data = { facetId: 999 };
+        await assignCounterValues({ fields, data, counters });
+        expect(data.facetId).toBe(7);
+        expect(calls).toEqual(['library-facets']);
+    });
+    it('allocates separate values for multiple counters across groups', async () => {
+        const { counters, calls } = makeCounters(1);
+        const fields = [
+            { name: 'facetId', type: 'counter', group: 'library-facets' },
+            { name: 'regionId', type: 'counter', group: 'region-codes' },
+        ];
+        const data = {};
+        await assignCounterValues({ fields, data, counters });
+        expect(data.facetId).toBeTypeOf('number');
+        expect(data.regionId).toBeTypeOf('number');
+        expect(data.facetId).not.toBe(data.regionId);
+        expect(calls.sort()).toEqual(['library-facets', 'region-codes']);
+    });
+    it('descends into group fields and materialises missing group containers', async () => {
+        const { counters, calls } = makeCounters(5);
+        const fields = [
+            {
+                name: 'meta',
+                type: 'group',
+                fields: [
+                    { name: 'label', type: 'text' },
+                    { name: 'facetId', type: 'counter', group: 'library-facets' },
+                ],
+            },
+        ];
+        const data = {};
+        await assignCounterValues({ fields, data, counters });
+        expect(data.meta).toBeTypeOf('object');
+        expect(data.meta.facetId).toBe(5);
+        expect(calls).toEqual(['library-facets']);
+    });
+    it('carries forward the previous version value on update', async () => {
+        const { counters, calls } = makeCounters(100);
+        const fields = [
+            { name: 'label', type: 'text' },
+            { name: 'facetId', type: 'counter', group: 'library-facets' },
+        ];
+        const data = { label: 'updated' };
+        const previousData = { label: 'previous', facetId: 7 };
+        await assignCounterValues({ fields, data, previousData, counters });
+        expect(data.facetId).toBe(7);
+        expect(calls).toEqual([]);
+    });
+    it('overwrites caller-sent value on update with the previous version value', async () => {
+        const { counters, calls } = makeCounters();
+        const fields = [{ name: 'facetId', type: 'counter', group: 'library-facets' }];
+        const data = { facetId: 999 };
+        const previousData = { facetId: 7 };
+        await assignCounterValues({ fields, data, previousData, counters });
+        expect(data.facetId).toBe(7);
+        expect(calls).toEqual([]);
+    });
+    it('lazy-allocates on update when the previous version is missing the counter', async () => {
+        const { counters, calls } = makeCounters(50);
+        const fields = [
+            { name: 'label', type: 'text' },
+            { name: 'facetId', type: 'counter', group: 'library-facets' },
+        ];
+        const data = { label: 'updated' };
+        const previousData = { label: 'previous' }; // counter added post-hoc
+        await assignCounterValues({ fields, data, previousData, counters });
+        expect(data.facetId).toBe(50);
+        expect(calls).toEqual(['library-facets']);
+    });
+    it('carries forward counter inside a group on update', async () => {
+        const { counters, calls } = makeCounters(99);
+        const fields = [
+            {
+                name: 'meta',
+                type: 'group',
+                fields: [{ name: 'facetId', type: 'counter', group: 'library-facets' }],
+            },
+        ];
+        const data = { meta: {} };
+        const previousData = { meta: { facetId: 12 } };
+        await assignCounterValues({ fields, data, previousData, counters });
+        expect(data.meta.facetId).toBe(12);
+        expect(calls).toEqual([]);
+    });
+    it('treats a non-finite previous value as missing and lazy-allocates', async () => {
+        const { counters, calls } = makeCounters(3);
+        const fields = [{ name: 'facetId', type: 'counter', group: 'library-facets' }];
+        const data = {};
+        const previousData = { facetId: 'not-a-number' };
+        await assignCounterValues({ fields, data, previousData, counters });
+        expect(data.facetId).toBe(3);
+        expect(calls).toEqual(['library-facets']);
+    });
+    it('does not descend into arrays or blocks (counters are banned there)', async () => {
+        // The walker should silently skip these — the structural ban is
+        // enforced separately in discoverCounterGroups at boot. Here we
+        // just verify the walker doesn't crash on an array/blocks sibling.
+        const { counters, calls } = makeCounters(1);
+        const fields = [
+            { name: 'facetId', type: 'counter', group: 'library-facets' },
+            { name: 'tags', type: 'array', fields: [{ name: 'label', type: 'text' }] },
+        ];
+        const data = {
+            tags: [{ label: 'a' }, { label: 'b' }],
+        };
+        await assignCounterValues({ fields, data, counters });
+        expect(data.facetId).toBe(1);
+        expect(data.tags).toEqual([{ label: 'a' }, { label: 'b' }]);
+        expect(calls).toEqual(['library-facets']);
+    });
+});

package/dist/services/collection-bootstrap.test.node.js

@@ -44,6 +44,10 @@ function createMockDb(options) {
                 softDeleteDocument: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
             },
+            counters: {
+                ensureCounterGroup: vi.fn(fail),
+                nextCounterValue: vi.fn(fail),
+            },
         },
         queries: {
             collections: {
@@ -181,6 +185,10 @@ describe('ensureCollections', () => {
                     softDeleteDocument: vi.fn(),
                     setOrderKey: vi.fn(),
                 },
+                counters: {
+                    ensureCounterGroup: vi.fn(),
+                    nextCounterValue: vi.fn(),
+                },
             },
             queries: {
                 collections: {

package/dist/services/discover-counter-groups.d.ts

@@ -0,0 +1,31 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { type CollectionDefinition } from '../@types/index.js';
+import type { IDbAdapter } from '../@types/db-types.js';
+import type { BylineLogger } from '../lib/logger.js';
+export interface DiscoverCounterGroupsInput {
+    definitions: CollectionDefinition[];
+    db: IDbAdapter;
+    logger?: BylineLogger;
+}
+/**
+ * Discover every distinct counter `group` declared across the provided
+ * collections and ensure each one is registered with the database
+ * adapter (creating its backing sequence as needed). Called once at
+ * startup from `initBylineCore()`, after `ensureCollections`.
+ *
+ * Returns a `Map<groupName, sequenceName>` of the registered groups,
+ * suitable for caching on the core instance if downstream callers ever
+ * need to inspect the resolved sequence names without round-tripping.
+ *
+ * Throws on:
+ *   - a counter field nested inside `array` or `blocks` (see
+ *     {@link findCounterFields} — structural ban)
+ *   - any `ensureCounterGroup` failure (treated as a fatal config error)
+ */
+export declare function discoverCounterGroups({ definitions, db, logger, }: DiscoverCounterGroupsInput): Promise<Map<string, string>>;

package/dist/services/discover-counter-groups.js

@@ -0,0 +1,105 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { isArrayField, isBlocksField, isGroupField, } from '../@types/index.js';
+/**
+ * Walk a collection's field tree and yield every `counter` field site.
+ *
+ * Banned locations are thrown immediately (not yielded): a `counter`
+ * inside an `array` or `blocks` structure would mean a single document
+ * carries multiple counter values, which collapses the "one ID per
+ * term" assumption that makes URLs like `?t=1&t=4&t=9` meaningful.
+ *
+ * Counters inside a `group` are allowed — groups don't repeat, so
+ * there's still exactly one counter value per document.
+ */
+function* findCounterFields(fields, collectionPath, pathPrefix = '', insideRepeating = null) {
+    for (const field of fields) {
+        const fieldPath = pathPrefix === '' ? field.name : `${pathPrefix}.${field.name}`;
+        if (field.type === 'counter') {
+            if (insideRepeating !== null) {
+                throw new Error(`discoverCounterGroups: counter field '${fieldPath}' in collection ` +
+                    `'${collectionPath}' is nested inside a ${insideRepeating.kind} field ` +
+                    `('${insideRepeating.fieldPath}'). Counter fields produce a single ` +
+                    `allocator-assigned value per document and cannot live inside ` +
+                    `repeating structure — move the field to the collection root or ` +
+                    `into a non-repeating group.`);
+            }
+            yield { collectionPath, fieldPath, field };
+            continue;
+        }
+        if (isGroupField(field)) {
+            yield* findCounterFields(field.fields, collectionPath, fieldPath, insideRepeating);
+            continue;
+        }
+        if (isArrayField(field)) {
+            yield* findCounterFields(field.fields, collectionPath, fieldPath, {
+                kind: 'array',
+                fieldPath,
+            });
+            continue;
+        }
+        if (isBlocksField(field)) {
+            for (const block of field.blocks) {
+                yield* findCounterFields(block.fields, collectionPath, `${fieldPath}.${block.blockType}`, {
+                    kind: 'blocks',
+                    fieldPath,
+                });
+            }
+            continue;
+        }
+        // Other value fields produce no counter sites; nothing to recurse into.
+        void field;
+    }
+}
+/**
+ * Discover every distinct counter `group` declared across the provided
+ * collections and ensure each one is registered with the database
+ * adapter (creating its backing sequence as needed). Called once at
+ * startup from `initBylineCore()`, after `ensureCollections`.
+ *
+ * Returns a `Map<groupName, sequenceName>` of the registered groups,
+ * suitable for caching on the core instance if downstream callers ever
+ * need to inspect the resolved sequence names without round-tripping.
+ *
+ * Throws on:
+ *   - a counter field nested inside `array` or `blocks` (see
+ *     {@link findCounterFields} — structural ban)
+ *   - any `ensureCounterGroup` failure (treated as a fatal config error)
+ */
+export async function discoverCounterGroups({ definitions, db, logger, }) {
+    // Aggregate distinct group names across all collections. We track the
+    // first site we saw each group at so the log line can point a human
+    // at where the group was declared.
+    const groupSites = new Map();
+    for (const definition of definitions) {
+        for (const site of findCounterFields(definition.fields, definition.path)) {
+            if (!groupSites.has(site.field.group)) {
+                groupSites.set(site.field.group, site);
+            }
+        }
+    }
+    if (groupSites.size === 0) {
+        return new Map();
+    }
+    // Reconcile each group concurrently — sequences are independent so
+    // there's no ordering constraint, and ensureCounterGroup is idempotent
+    // and safe under concurrent calls (CREATE SEQUENCE IF NOT EXISTS +
+    // ON CONFLICT DO NOTHING).
+    const results = await Promise.all(Array.from(groupSites.entries()).map(async ([groupName, site]) => {
+        const { sequenceName } = await db.commands.counters.ensureCounterGroup(groupName);
+        logger?.debug({
+            counterGroup: groupName,
+            sequenceName,
+            firstSeenIn: `${site.collectionPath}.${site.fieldPath}`,
+        }, 'counter group registered');
+        return [groupName, sequenceName];
+    }));
+    const registered = new Map(results);
+    logger?.info({ counterGroupCount: registered.size }, 'counter groups reconciled');
+    return registered;
+}

package/dist/services/discover-counter-groups.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/services/discover-counter-groups.test.node.js

@@ -0,0 +1,183 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { discoverCounterGroups } from './discover-counter-groups.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+function makeAdapter(options) {
+    const ensureCounterGroup = vi.fn(options?.ensure ??
+        (async (groupName) => ({
+            groupName,
+            sequenceName: `byline_cseq_${groupName.replace(/-/g, '_')}_abcd1234`,
+        })));
+    const fail = () => {
+        throw new Error('unexpected call');
+    };
+    const db = {
+        commands: {
+            collections: { create: vi.fn(fail), update: vi.fn(fail), delete: vi.fn(fail) },
+            documents: {
+                createDocumentVersion: vi.fn(fail),
+                setDocumentStatus: vi.fn(fail),
+                archivePublishedVersions: vi.fn(fail),
+                softDeleteDocument: vi.fn(fail),
+                setOrderKey: vi.fn(fail),
+            },
+            counters: {
+                ensureCounterGroup,
+                nextCounterValue: vi.fn(fail),
+            },
+        },
+        queries: {
+            collections: {
+                getAllCollections: vi.fn(fail),
+                getCollectionByPath: vi.fn(fail),
+                getCollectionById: vi.fn(fail),
+            },
+            documents: {
+                getDocumentById: vi.fn(fail),
+                getCurrentVersionMetadata: vi.fn(fail),
+                getDocumentByPath: vi.fn(fail),
+                getDocumentByVersion: vi.fn(fail),
+                getDocumentsByVersionIds: vi.fn(fail),
+                getDocumentsByDocumentIds: vi.fn(fail),
+                getDocumentHistory: vi.fn(fail),
+                getPublishedVersion: vi.fn(fail),
+                getPublishedDocumentIds: vi.fn(fail),
+                getDocumentCountsByStatus: vi.fn(fail),
+                findDocuments: vi.fn(fail),
+                getLastOrderKey: vi.fn(fail),
+                getNeighborOrderKeys: vi.fn(fail),
+                getCanonicalDocumentOrder: vi.fn(fail),
+            },
+        },
+    };
+    return { db, ensureCounterGroup };
+}
+function collection(path, fields) {
+    return {
+        path,
+        labels: { singular: path, plural: `${path}s` },
+        fields,
+        workflow: {
+            statuses: [{ name: 'draft' }, { name: 'published' }, { name: 'archived' }],
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('discoverCounterGroups', () => {
+    it('is a no-op when no collections declare any counter fields', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('news', [{ name: 'title', type: 'text' }]),
+            collection('pages', [{ name: 'body', type: 'textArea' }]),
+        ];
+        const result = await discoverCounterGroups({ definitions: collections, db });
+        expect(result.size).toBe(0);
+        expect(ensureCounterGroup).not.toHaveBeenCalled();
+    });
+    it('registers each distinct group exactly once across all collections', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('topics', [
+                { name: 'label', type: 'text' },
+                { name: 'facetId', type: 'counter', group: 'library-facets' },
+            ]),
+            collection('formats', [
+                { name: 'label', type: 'text' },
+                { name: 'facetId', type: 'counter', group: 'library-facets' },
+            ]),
+            collection('geography', [
+                { name: 'label', type: 'text' },
+                { name: 'facetId', type: 'counter', group: 'library-facets' },
+            ]),
+        ];
+        const result = await discoverCounterGroups({ definitions: collections, db });
+        expect(result.size).toBe(1);
+        expect(result.get('library-facets')).toMatch(/^byline_cseq_library_facets_/);
+        expect(ensureCounterGroup).toHaveBeenCalledTimes(1);
+        expect(ensureCounterGroup).toHaveBeenCalledWith('library-facets');
+    });
+    it('registers multiple distinct groups in a single pass', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('topics', [{ name: 'facetId', type: 'counter', group: 'library-facets' }]),
+            collection('regions', [{ name: 'regionId', type: 'counter', group: 'region-codes' }]),
+        ];
+        const result = await discoverCounterGroups({ definitions: collections, db });
+        expect(result.size).toBe(2);
+        expect(ensureCounterGroup).toHaveBeenCalledTimes(2);
+        expect(ensureCounterGroup).toHaveBeenCalledWith('library-facets');
+        expect(ensureCounterGroup).toHaveBeenCalledWith('region-codes');
+    });
+    it('descends into group fields — counter inside a non-repeating group is allowed', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('topics', [
+                {
+                    name: 'meta',
+                    type: 'group',
+                    fields: [
+                        { name: 'label', type: 'text' },
+                        { name: 'facetId', type: 'counter', group: 'library-facets' },
+                    ],
+                },
+            ]),
+        ];
+        const result = await discoverCounterGroups({ definitions: collections, db });
+        expect(result.size).toBe(1);
+        expect(ensureCounterGroup).toHaveBeenCalledWith('library-facets');
+    });
+    it('throws when a counter sits inside an array field', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('topics', [
+                {
+                    name: 'variants',
+                    type: 'array',
+                    fields: [{ name: 'facetId', type: 'counter', group: 'library-facets' }],
+                },
+            ]),
+        ];
+        await expect(discoverCounterGroups({ definitions: collections, db })).rejects.toThrow(/nested inside a array field/);
+        expect(ensureCounterGroup).not.toHaveBeenCalled();
+    });
+    it('throws when a counter sits inside a blocks field', async () => {
+        const { db, ensureCounterGroup } = makeAdapter();
+        const collections = [
+            collection('topics', [
+                {
+                    name: 'content',
+                    type: 'blocks',
+                    blocks: [
+                        {
+                            blockType: 'tagBlock',
+                            fields: [{ name: 'facetId', type: 'counter', group: 'library-facets' }],
+                        },
+                    ],
+                },
+            ]),
+        ];
+        await expect(discoverCounterGroups({ definitions: collections, db })).rejects.toThrow(/nested inside a blocks field/);
+        expect(ensureCounterGroup).not.toHaveBeenCalled();
+    });
+    it('surfaces the adapter error when ensureCounterGroup fails', async () => {
+        const { db } = makeAdapter({
+            ensure: async () => {
+                throw new Error('sequence ddl rejected');
+            },
+        });
+        const collections = [
+            collection('topics', [{ name: 'facetId', type: 'counter', group: 'library-facets' }]),
+        ];
+        await expect(discoverCounterGroups({ definitions: collections, db })).rejects.toThrow('sequence ddl rejected');
+    });
+});

package/dist/services/document-lifecycle.js

@@ -16,6 +16,7 @@ import { normaliseDateFields } from '../utils/normalise-dates.js';
 import { slugify } from '../utils/slugify.js';
 import { getUploadFields } from '../utils/storage-utils.js';
 import { getDefaultStatus, getWorkflow, validateStatusTransition } from '../workflow/workflow.js';
+import { assignCounterValues } from './assign-counter-values.js';
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -173,6 +174,16 @@ export async function createDocument(ctx, params) {
         }
         normaliseDateFields(data);
         await invokeHook(hooks?.beforeCreate, { data, collectionPath });
+        // Allocate counter-field values after beforeCreate so user-land hooks
+        // can run their own logic on the raw payload, but before the flatten/
+        // insert pass so the assigned values are persisted on the same write.
+        // Caller-supplied counter values are overwritten — counters are
+        // allocator-assigned, never user-set.
+        await assignCounterValues({
+            fields: definition.fields,
+            data,
+            counters: db.commands.counters,
+        });
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const resolvedPath = explicitPath ?? derivePath(definition, data, defaultLocale, slugifier);
         // Append-at-end order_key for `orderable: true` collections.
@@ -234,6 +245,18 @@ export async function updateDocument(ctx, params) {
         const originalData = latest ?? {};
         normaliseDateFields(data);
         await invokeHook(hooks?.beforeUpdate, { data, originalData, collectionPath });
+        // Counter fields are immutable: carry their values forward from the
+        // previous version rather than trusting whatever (or nothing) the
+        // caller sent. Lazy-allocates when a counter was added to the
+        // collection after this document was first created.
+        // originalData is the document envelope (with `.fields`, `.path`,
+        // `.document_version_id`); assignCounterValues expects field-shape.
+        await assignCounterValues({
+            fields: definition.fields,
+            data,
+            previousData: originalData.fields ?? originalData,
+            counters: db.commands.counters,
+        });
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
         const requestLocale = params.locale ?? defaultLocale;
@@ -329,6 +352,16 @@ export async function updateDocumentWithPatches(ctx, params) {
         normaliseDateFields(nextData);
         // 5. beforeUpdate hook.
         await invokeHook(hooks?.beforeUpdate, { data: nextData, originalData, collectionPath });
+        // 5b. Carry counter values forward from the previous version (or
+        // lazy-allocate if the previous version is missing a value). See
+        // updateDocument for the rationale — patch-based updates are
+        // subject to the same immutability contract.
+        await assignCounterValues({
+            fields: definition.fields,
+            data: nextData,
+            previousData: originalData.fields ?? {},
+            counters: db.commands.counters,
+        });
         // 6. Persist.
         const defaultStatus = getDefaultStatus(definition);
         const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
@@ -878,6 +911,15 @@ export async function duplicateDocument(ctx, params) {
             collectionPath,
             duplicate: duplicateMarker,
         });
+        // 6b. Reset counter fields to freshly-allocated values. The clone
+        // currently carries the source document's counter values; without
+        // this pass, the duplicate would alias the source's facet IDs and
+        // break the "one ID per term" contract.
+        await assignCounterValues({
+            fields: definition.fields,
+            data: clonedFields,
+            counters: db.commands.counters,
+        });
         // 7. Atomic write. Try the candidate path; on ERR_PATH_CONFLICT
         //    retry once with a 4-char UUID suffix.
         const defaultStatus = getDefaultStatus(definition);

package/dist/services/document-lifecycle.test.node.js

@@ -49,6 +49,10 @@ function createMockDb() {
                 softDeleteDocument,
                 setOrderKey: vi.fn(),
             },
+            counters: {
+                ensureCounterGroup: vi.fn(),
+                nextCounterValue: vi.fn(),
+            },
         },
         queries: {
             collections: {

package/dist/services/field-upload.test.node.js

@@ -58,6 +58,10 @@ function createMockDb() {
                 softDeleteDocument: vi.fn(),
                 setOrderKey: vi.fn(),
             },
+            counters: {
+                ensureCounterGroup: vi.fn(),
+                nextCounterValue: vi.fn(),
+            },
         },
         queries: {
             collections: {

package/dist/services/index.d.ts

@@ -1,6 +1,8 @@
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
+export { type AssignCounterValuesInput, assignCounterValues } from './assign-counter-values.js';
 export { type CollectionRecord, type EnsureCollectionsInput, ensureCollections, } from './collection-bootstrap.js';
+export { type DiscoverCounterGroupsInput, discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle.js';
 export * from './document-read.js';
 export * from './field-upload.js';

package/dist/services/index.js

@@ -1,7 +1,9 @@
 // packages/core/src/services/index.ts
 export { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '../lib/errors.js';
 export { normaliseDateFields } from '../utils/normalise-dates.js';
+export { assignCounterValues } from './assign-counter-values.js';
 export { ensureCollections, } from './collection-bootstrap.js';
+export { discoverCounterGroups, } from './discover-counter-groups.js';
 export * from './document-lifecycle.js';
 export * from './document-read.js';
 export * from './field-upload.js';

package/dist/services/populate.test.node.js

@@ -146,6 +146,10 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 softDeleteDocument: vi.fn(),
                 setOrderKey: vi.fn(),
             },
+            counters: {
+                ensureCounterGroup: vi.fn(),
+                nextCounterValue: vi.fn(),
+            },
         },
         queries: {
             collections: {

package/dist/storage/collection-fingerprint.js

@@ -38,6 +38,11 @@ function canonicalField(field) {
             if (field.mode !== undefined)
                 base.mode = field.mode;
             return base;
+        case 'counter':
+            // Group name is load-bearing — renaming it picks a different
+            // sequence and is a real schema change worth fingerprinting.
+            base.group = field.group;
+            return base;
         case 'image':
         case 'file':
             // Per-field upload config affects the read-back contract (mime

package/dist/storage/field-store-map.js

@@ -33,6 +33,7 @@ export const fieldTypeToStore = {
     integer: { storeType: 'numeric', valueColumn: 'value_integer' },
     float: { storeType: 'numeric', valueColumn: 'value_float' },
     decimal: { storeType: 'numeric', valueColumn: 'value_decimal' },
+    counter: { storeType: 'numeric', valueColumn: 'value_integer' },
     // Boolean store
     boolean: { storeType: 'boolean', valueColumn: 'value' },
     checkbox: { storeType: 'boolean', valueColumn: 'value' },

package/dist/storage/field-store-map.test.node.js

@@ -22,6 +22,7 @@ const VALUE_FIELD_TYPES = [
     'integer',
     'float',
     'decimal',
+    'counter',
     'boolean',
     'checkbox',
     'date',

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "2.1.3"
+    "@byline/auth": "2.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",