@eliware/snowflake 12.0.0 → 14.0.0

package/AGENTS.md

@@ -2,53 +2,45 @@
 
 ## Project
 
-Build a Snowflake ID library with Node.js 26. Use native ESM.
+Maintain `@eliware/snowflake`, a Snowflake ID library owned by Eliware.
 
 ## Scope and boundaries
 
-Keep this package focused on Snowflake ID generation.
-Do not use validation to publish, deploy, or change external systems.
+Limit this package to Snowflake ID generation.
 
 ## Layout
 
-Keep implementation modules under `src/` and matching tests under `tests/`.
-Keep user guides under `docs/`, examples under `examples/`, and rules under `specs/`.
+Use `README.md` and `specs/README.md` to find repository paths.
 
 ## Development
 
-Keep each module focused on one purpose.
-Keep TypeScript declarations beside their matching ESM modules.
+Use Node.js 26 and native ESM for maintained JavaScript.
 
 ## Validation
 
-Use Node.js 26 and native ESM.
-Run `npm test` for aggregate validation.
-Run `npm run lint` for lint checks.
-Run `npm run audit` for dependency checks.
-Run `npm run format` to format files.
-Run `npm run format:check` to check file format.
-Run `npm run typecheck` to check TypeScript declarations.
-Run `npm run pack` to check package contents.
+Run `npm test`.
+Run `npm run lint`.
+Run `npm run audit`.
+Run `npm run format`.
+Run `npm run format:check`.
 
 ## Security
 
-Protect credentials, tokens, secrets, private data, and machine-specific values.
-Treat Snowflake IDs as identifiers, not secrets.
+Keep credentials, private data, and runtime state out of Git.
 
 ## Changes
 
-Keep docs current and direct.
-Follow the Eliware Operations approval process for release changes.
-Do not treat validation as release approval.
+Update the nearest index when you add a document.
 
 ## Library
 
-Export the public generator API from `src/index.mjs`.
-Return each generated ID as a decimal string.
-Keep declarations in `src/` beside their matching ESM modules.
+Run focused tests first during development.
+Run one test file with `npm test -- tests/path/to/example.test.mjs`.
+Run multiple test files with `npm test -- tests/path/to/first.test.mjs tests/path/to/second.test.mjs`.
+Prevent repeated full-suite runs during development.
+Run the full `npm test` suite for final validation before a commit, milestone, or release.
 
 ## npm publication
 
-Publish the `@eliware/snowflake` package only after release approval.
-Use `package.json.version` as the package version.
-Run package validation before publication review.
+Run `npm run pack` to check package contents.
+Follow the approved release procedure.

package/README.md

@@ -23,19 +23,17 @@ A Node.js Snowflake ID generator with BigInt support and a configurable epoch.
 
 ## Features
 
-Create time-ordered IDs with a custom epoch and unique worker and process IDs.
-The IDs use the Discord Snowflake bit layout.
-Receive decimal strings that preserve every ID bit in JavaScript and JSON.
-The generator handles clock rollback and reports sequence overflow.
+Create time-ordered Snowflake IDs as decimal strings.
+Set a custom epoch, worker ID, process ID, clock, or logger.
 
 ## Requirements
 
 Use Node.js 26 or later.
-Assign a unique worker and process ID pair to each active generator.
+Use native ECMAScript modules (ESM).
 
 ## Setup
 
-Install the package:
+Install the package from npm:
 
 ```text
 npm install @eliware/snowflake
@@ -43,7 +41,7 @@ npm install @eliware/snowflake
 
 ## Usage
 
-Create a generator with a unique identity:
+Create a generator with a unique worker and process ID pair:
 
 ```js
 import { createSnowflakeGenerator } from "@eliware/snowflake";
@@ -52,43 +50,54 @@ const generate = createSnowflakeGenerator({ workerId: 3, processId: 7 });
 console.log(generate());
 ```
 
-See [release notes](RELEASE_NOTES.md) for changes by version.
-See the [usage guide](docs/usage.md) for options, ID fields, and limits.
+Each call returns one decimal string.
+Read the [usage guide](docs/usage.md) for generator options and ID fields.
+Read the [release notes](RELEASE_NOTES.md) for changes by version.
+Read the [specifications index](specs/README.md) for repository requirements.
 
 ## Development
 
-Read [user documentation](docs/README.md), [examples](examples/README.md), and [specifications](specs/README.md).
+Read the [documentation index](docs/README.md) for maintained guides.
 
 ## Testing
 
-Run `npm test` for all required checks.
-Run `npm run lint`, `npm run format:check`, `npm run audit`, `npm run typecheck`, or `npm run pack` for focused checks.
+Run `npm test` from a repository clone for aggregate validation.
 
 ## Troubleshooting
 
-See [troubleshooting](docs/troubleshooting.md) for error causes and recovery steps.
+Read the [troubleshooting guide](docs/troubleshooting.md) for error causes and actions.
 
 ## Security
 
-Treat IDs as identifiers, not secrets.
-IDs reveal timestamp and deployment data.
-Do not use IDs as authentication tokens.
+Each ID contains its generation time and identity fields.
+Do not use IDs as secrets or authentication tokens.
 
 ## API
 
-`createSnowflakeGenerator(options)` returns a function that creates decimal-string IDs.
-Options set the epoch, worker ID, process ID, and clock.
-The default generator is `generate`, `snowflake`, and the default export.
-The `constants` export provides the default epoch and bit sizes.
+Import `createSnowflakeGenerator` to create a generator with custom options.
+Import `generate`, `snowflake`, or the default export to use the default generator.
+Import `constants` to read the default epoch and field sizes.
+Read the [usage guide](docs/usage.md) for API details and TypeScript declarations.
 
 ## Packaging
 
-The package provides native ESM code and TypeScript declarations.
-It has no runtime dependencies.
+The package uses native ESM, includes TypeScript declarations, and depends on `@eliware/log`.
+Its root entrypoint is `src/index.mjs` and its declaration file is `src/index.d.ts`.
+The npm package includes these paths from `package.json`:
+
+- `src/`
+- `docs/`
+- `README.md`, `AGENTS.md`, `LICENSE`, and `RELEASE_NOTES.md`
+- `examples/` and `specs/`
+
+Use numeric `MAJOR.MINOR.PATCH` versions.
+Push a matching `v<version>` tag to start validation and npm publication.
+Follow the approved release procedure before you create a release tag.
 
 ## Examples
 
-Run the [native ESM example](examples/example.mjs) with Node.js 26 or later.
+Run `node examples/example.mjs` to create sample IDs.
+Read [examples/README.md](examples/README.md) for the example index.
 
 ## Support
 

package/RELEASE_NOTES.md

@@ -1,5 +1,43 @@
 # Release Notes
 
+## 14.0.0 — 2026-10-21
+
+### Added
+
+- Added optional structured logging through `@eliware/log` with a custom logger option.
+- Added tests for logger records and the full elapsed timestamp range with the maximum epoch.
+
+### Changed
+
+- Updated the package to version 14.0.0 and aligned its specifications with Eliware Test 14.
+- Clarified the authoritative rule for first timestamps and later pre-epoch rollbacks.
+- Updated npm dependencies and added `@eliware/log` as a direct dependency.
+- Expanded the user guides with logging, API, decoding, timestamp limits, identity, and storage details.
+- Reduced `README.md` and `AGENTS.md` to convention-required content.
+
+### Fixed
+
+- Kept the full elapsed timestamp range available when the configured epoch is at its maximum.
+- Kept IDs increasing when the clock returns a time before the epoch after the first valid ID.
+
+## 13.0.0 — 2026-10-19
+
+### Added
+
+- Added the canonical npm publication workflow.
+- Added full Git history to CI.
+
+### Changed
+
+- Updated the package to version 13.0.0 and upgraded `@eliware/test` and npm dependencies.
+- Aligned CI and npm publication workflows with the current templates and checkout action.
+- Updated Knit deployment commands and the repository path.
+- Updated specifications and repository guidance for Convention 13.
+- Expanded user guides with API details, ID limits, timestamp decoding, and storage guidance.
+- Documented the custom epoch for Discord timestamp decoding. It does not create official Discord IDs.
+- Changed the invalid clock source and sequence overflow error messages.
+- Reduced the root README and contributor guidance to convention-required content.
+
 ## 12.0.0 — 2026-10-12
 
 ### Changed
@@ -32,34 +70,3 @@
 ### Breaking changes
 
 - Changed the `test` and `lint` scripts to use `@eliware/test`.
-
-## 1.1.5 — 2026-08-07
-
-### Changed
-
-- Aligned the repository layout, scripts, documentation, and package contents.
-- Added TypeScript declaration checks and package validation.
-- Moved tests under `tests/` and added a runnable native ESM example.
-- Removed the legacy CommonJS package entry point.
-
-## 1.1.4 — 2026-08-07
-
-### Changed
-
-- Removed the unused `@eliware/common` runtime dependency.
-- Added manual GitHub Actions workflow dispatch support.
-
-## 1.1.2 — 2026-08-06
-
-### Added
-
-- Added a configurable BigInt-safe Snowflake ID generator.
-- Added the Eliware epoch, worker IDs, and process IDs.
-- Added clock rollback protection and sequence overflow handling.
-- Added injectable clocks, range checks, and timestamp capacity checks.
-- Added TypeScript declarations for public options and exports.
-
-### Changed
-
-- Removed CommonJS entry points and tests. The package now uses native ESM.
-- Expanded deployment and bit layout guidance.

package/docs/README.md

@@ -1,4 +1,13 @@
 # Documentation
 
-- [Usage](usage.md)
-- [Troubleshooting](troubleshooting.md)
+Use these guides to install the package, create IDs, and resolve common errors.
+
+## Guides
+
+- [Usage](usage.md) explains installation, generator options, ID fields, decoding, logging, and storage.
+- [Troubleshooting](troubleshooting.md) explains validation errors, sequence limits, and duplicate IDs.
+
+## Requirements
+
+Use Node.js 26 or later.
+Use native ECMAScript modules (ESM).

package/docs/troubleshooting.md

@@ -2,44 +2,57 @@
 
 ## Error reference
 
-| Error                                         | Cause                                                | Action                                                          |
-| --------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
-| `RangeError` for `workerId` or `processId`    | The value is outside `0` through `31`.               | Set an integer from `0` through `31`.                           |
-| `TypeError` for `now`                         | The option is not a function.                        | Pass a function that returns Unix time in milliseconds.         |
-| `RangeError` for `epoch`                      | The epoch is outside the supported range.            | Set the epoch from zero through the timestamp limit.            |
-| `RangeError` for invalid clock number         | The clock returned a fractional or unsafe number.    | Return a safe integer number or a bigint.                       |
-| `RangeError` for time before epoch            | The clock value is lower than `epoch`.               | Set the correct epoch or fix the clock source.                  |
-| `RangeError` for timestamp capacity           | Elapsed time is greater than the 42-bit limit.       | Use a valid epoch for the required date range.                  |
-| `RangeError` for sequence overflow            | The generator created 4096 IDs at one timestamp.     | Wait until the clock moves past the last timestamp, then retry. |
-| `TypeError` or `RangeError` during conversion | An option or clock value cannot convert to `BigInt`. | Pass an integer number or bigint value.                         |
+| Error                                         | Cause                                                | Action                                                           |
+| --------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| `RangeError` for `workerId` or `processId`    | The value is outside `0` through `31`.               | Set an integer from `0` through `31`.                            |
+| `TypeError` for `now`                         | The option is not a function.                        | Pass a function that returns Unix time in milliseconds.          |
+| `TypeError` for `logger`                      | The logger lacks a required level method.            | Pass a logger with `error`, `warn`, `info`, and `debug` methods. |
+| `RangeError` for `epoch`                      | The epoch is outside the supported range.            | Set the epoch from zero through the timestamp limit.             |
+| `RangeError` for invalid clock number         | The clock returned a fractional or unsafe number.    | Return a safe integer number or a bigint.                        |
+| `RangeError` for first time before epoch      | The first clock value is lower than `epoch`.         | Set the correct epoch or set the clock source.                   |
+| `RangeError` for timestamp capacity           | Elapsed time is greater than the 42-bit limit.       | Use a valid epoch for the required date range.                   |
+| `RangeError` for sequence overflow            | The generator created 4096 IDs at one timestamp.     | Retry when the clock returns a greater timestamp.                |
+| `TypeError` or `RangeError` during conversion | An option or clock value cannot convert to `BigInt`. | Pass an integer number or bigint value.                          |
 
 ## Sequence overflow
 
 The generator does not wait for the clock.
 It fails when one timestamp reaches the 4096-ID limit.
-Wait until the clock moves past the last timestamp before you retry.
+Retry when the clock returns a timestamp greater than the last timestamp.
 If the clock stalls, check the system clock or the `now` function.
 
 ## Duplicate IDs
 
-Assign a unique worker and process ID pair to each active generator.
+Give each active generator a unique worker and process ID pair.
 Use the same epoch for each generator in one application.
 The default worker ID is `0`.
 The default process ID is `process.pid % 32` and can repeat across hosts.
-Set both IDs through deployment configuration when several hosts create IDs.
+Set both IDs in deployment configuration when some hosts create IDs.
+
+Do not create multiple generators with the same pair while their IDs can overlap in time.
+Each generator starts its sequence at zero.
+Use one generator instance for each pair in a process.
+
+## Clock rollback
+
+The generator keeps IDs in increasing order when its clock returns an earlier time.
+It uses the last valid timestamp and advances the sequence.
+It logs a warning when you provide a logger.
+The first clock value must be at or after the configured epoch.
+After the first ID, a clock value lower than the epoch uses rollback handling.
 
 ## Invalid timestamps
 
 The clock must return a safe integer number or a bigint.
 The value must be Unix time in milliseconds.
-The timestamp must be at or after the configured epoch.
-The elapsed time must fit in 42 bits.
+The first timestamp must be at or after the configured epoch.
+The elapsed time must be 42 bits or less.
 Check the clock and epoch values when timestamp validation fails.
 
 ## Large ID values
 
-IDs are decimal strings because JavaScript numbers cannot represent every ID exactly.
-Keep the string in JSON and in database fields that preserve exact decimal values.
+IDs are decimal strings because JavaScript numbers cannot store every ID exactly.
+Keep the string in JSON and in database fields that store exact decimal values.
 Use `BigInt(id)` for exact integer operations.
 
 ## Node.js version

package/docs/usage.md

@@ -3,7 +3,8 @@
 ## Requirements
 
 Use Node.js 26 or later.
-Use one package instance in each Node.js process.
+Use native ECMAScript modules (ESM).
+Give each active generator a unique worker and process ID pair.
 
 ## Install
 
@@ -25,7 +26,11 @@ const id = generate();
 console.log(id);
 ```
 
-The program prints one decimal string. The value changes on each call.
+The command prints one decimal string. The value changes on each call.
+
+The package exports `createSnowflakeGenerator`, `generate`, `snowflake`, `constants`, and a default generator.
+The `generate`, `snowflake`, and default exports use the same generator instance.
+Use `createSnowflakeGenerator()` to set an epoch, identity, clock, or logger.
 
 ## Set generator options
 
@@ -37,21 +42,40 @@ Pass an options object to `createSnowflakeGenerator`.
 | `workerId`  | number or bigint | `0`                | Worker value from `0` through `31`.              |
 | `processId` | number or bigint | `process.pid % 32` | Process value from `0` through `31`.             |
 | `now`       | function         | `Date.now`         | Function that returns Unix time in milliseconds. |
+| `logger`    | logger           | none               | Optional structured logger for generator events. |
+
+`createSnowflakeGenerator(options)` returns a function that creates IDs.
+Each call returns one decimal string.
+Set `epoch` as a safe integer number or a bigint from zero through `(1n << 42n) - 1n`.
+Set `workerId` and `processId` to integer values from `0` through `31`.
+Use the same epoch for all generators in one application.
+
+Give each active generator a unique pair of `workerId` and `processId` values.
+Keep each pair unique while IDs from that pair remain in use.
+The fields allow 32 worker values and 32 process values, for 1,024 pairs.
+The default process ID is `process.pid % 32` and can repeat across hosts.
+Set both values in deployment configuration when different hosts can create IDs at the same time.
 
-Use the same epoch for all generators that create IDs for one application.
-Set the epoch from zero through the timestamp limit.
-Pass it as a safe integer number or a bigint.
-Set `epoch` to `1420070400000n` to decode timestamps with Discord's epoch.
-Assign a unique worker and process ID pair to each active generator.
-Set `processId` when several hosts or processes share worker IDs.
-The default process ID can repeat across hosts.
+To align timestamp decoding with Discord, set `epoch` to `1420070400000n`.
+This epoch matches Discord's timestamp epoch.
+It does not create an official Discord resource ID.
+
+```js
+const createDiscordTimeGenerator = createSnowflakeGenerator({
+  epoch: 1420070400000n,
+  workerId: 3,
+  processId: 7,
+});
+```
 
 ## Understand the ID fields
 
 Each ID has a 42-bit timestamp, a 5-bit worker ID, a 5-bit process ID, and a 12-bit sequence.
 The timestamp stores milliseconds since the configured epoch.
-The sequence starts at zero when the timestamp advances.
+The sequence starts at zero when the timestamp changes.
 The default epoch is `365662380000n`, or `1981-08-03T04:53:00Z`.
+The timestamp field sorts before the worker, process, and sequence fields.
+The complete ID has 64 bits.
 
 The generator combines the fields as follows:
 
@@ -59,15 +83,50 @@ The generator combines the fields as follows:
 ((time - epoch) << 22) | (workerId << 17) | (processId << 12) | sequence
 ```
 
-The maximum elapsed timestamp is `(1n << 42n) - 1n` milliseconds.
-IDs can exceed JavaScript's safe integer range.
+The epoch option accepts values through `(1n << 42n) - 1n` milliseconds.
+The timestamp field separately stores a maximum of `(1n << 42n) - 1n` elapsed milliseconds.
+The epoch limit applies to the configured epoch, not the final Unix time.
+The maximum supported Unix time equals the epoch plus the maximum elapsed timestamp.
+IDs can be greater than JavaScript's safe integer limit.
 
 ## Use the default generator
 
 Use `generate`, `snowflake`, or the default export to create IDs.
 These exports refer to the same generator instance.
 The default generator uses worker ID `0` and process ID `process.pid % 32`.
-Create a custom generator when you need a different identity, epoch, or clock.
+Create a custom generator to set a different identity, epoch, or clock.
+
+The `constants` export has `epoch`, `sequenceBits`, `processBits`, and `workerBits` fields.
+Each field has a `bigint` value.
+The sequence, process, and worker fields use 12, 5, and 5 bits.
+The `constants` object is frozen.
+
+## Decode an ID timestamp
+
+Convert the ID string to a `bigint` before you read its timestamp field.
+Move the value right by 22 bits to read elapsed milliseconds.
+Add the configured epoch to get Unix time in milliseconds.
+Convert that value to a JavaScript `Date` to get its ISO 8601 value.
+
+```js
+const epoch = 365662380000n;
+const timestamp = new Date(Number((BigInt(id) >> 22n) + epoch));
+console.log(timestamp.toISOString());
+```
+
+Use the same epoch that the generator used to create the ID.
+
+Read the worker, process, and sequence fields with bit shifts and masks:
+
+```js
+const value = BigInt(id);
+const workerId = (value >> 17n) & 31n;
+const processId = (value >> 12n) & 31n;
+const sequence = value & 4095n;
+```
+
+The package does not export a decoder.
+Use the same field layout and epoch that the generator used to create the ID.
 
 ## Use a custom clock
 
@@ -76,29 +135,80 @@ Return a safe integer number or a bigint from that function.
 The value must be Unix time in milliseconds.
 Use this option for deterministic tests or a controlled clock source.
 
-## Handle time and sequence limits
+The first clock value must be at or after the configured epoch.
+After the first ID, an earlier clock value uses the last valid timestamp.
+The generator increments the sequence during that rollback.
 
-The generator uses the last timestamp when the clock moves backward.
-It increments the sequence while that timestamp remains active.
-Each generator can create up to 4096 IDs for one millisecond.
-The next call throws `RangeError` until the clock advances past the last timestamp.
-Wait for the clock to advance before retry.
-The generator throws `RangeError` for a timestamp before the epoch or beyond its 42-bit limit.
+## Add structured logging
 
-## Store and transfer IDs
+Install `@eliware/log` to create a logger. Pass the logger to the generator with the `logger` option.
+The generator writes records only when you provide a logger.
+
+```js
+import { createLogger } from "@eliware/log";
+import { createSnowflakeGenerator } from "@eliware/snowflake";
+
+const logger = createLogger({ level: "debug", format: "json" });
+const generate = createSnowflakeGenerator({ logger });
+const id = generate();
+```
+
+The generator writes `info` when it starts, `debug` when it creates an ID, and `warn` when its clock returns an earlier time.
+It writes `error` when ID generation fails.
+Records do not include generated IDs, credentials, tokens, or error messages.
+
+Records include the operation, component, and related timestamp or identity fields.
+The logger supports the `error`, `warn`, `info`, `http`, `verbose`, `debug`, and `silly` levels.
+The generator uses only levels that apply to its operations.
+Set the logger level to control which records it writes.
+The `logger` option requires `error`, `warn`, `info`, and `debug` methods.
+The `LoggerWithConfiguredLevels` TypeScript type describes the supported logger interface.
+
+## Time and sequence limits
+
+The generator uses the last timestamp when the clock returns a lower value.
+The generator sets the sequence to zero when the timestamp changes.
+The generator increments the sequence while the timestamp stays the same.
+
+Each generator can create 4096 IDs in one millisecond.
+The generator throws `RangeError` after that limit.
+Retry when the clock returns a timestamp greater than the last timestamp.
+The generator throws `RangeError` for a timestamp before the epoch or greater than its 42-bit limit.
+
+## Store and share IDs
 
 Keep each ID as a decimal string in JavaScript and JSON.
 Do not convert an ID to `number`.
+JSON cannot encode a `bigint` value without custom code.
 Use a text field or an unsigned 64-bit field in a database.
-Use `BigInt(id)` when you need exact integer math in JavaScript.
+Use `BigInt(id)` for exact integer math in JavaScript.
+
+Each ID contains its generation time, worker ID, process ID, and sequence.
+Do not use an ID as a password, credential, or authentication token.
+
+## Use TypeScript
+
+The package includes TypeScript declarations for its public API.
+Import `SnowflakeGeneratorOptions`, `SnowflakeConstants`, and `LoggerWithConfiguredLevels` as types.
+
+```ts
+import { createSnowflakeGenerator, constants } from "@eliware/snowflake";
+import type { SnowflakeGeneratorOptions } from "@eliware/snowflake";
+
+const options: SnowflakeGeneratorOptions = { workerId: 3, processId: 7 };
+const generate = createSnowflakeGenerator(options);
+const id: string = generate();
+const epoch: bigint = constants.epoch;
+```
 
 ## Run the example
 
-Use Node.js 26 or later. Run this command from the repository root:
+Use Node.js 26 or later.
+Run this command from the repository root:
 
 ```text
 node examples/example.mjs
 ```
 
 The command prints two decimal strings. The values depend on the current time and process ID.
-You do not need cleanup.
+The example writes no files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eliware/snowflake",
-  "version": "12.0.0",
+  "version": "14.0.0",
   "type": "module",
   "description": "A Node.js Snowflake ID generator with BigInt support and a configurable epoch.",
   "keywords": [
@@ -41,8 +41,11 @@
   "engines": {
     "node": ">=26"
   },
+  "dependencies": {
+    "@eliware/log": "^14.0.0"
+  },
   "devDependencies": {
-    "@eliware/test": "^12.0.0",
+    "@eliware/test": "^14.0.0",
     "typescript": "^7.0.2"
   },
   "jest": {

package/specs/directives.yaml

@@ -1,25 +1,26 @@
-version: "12.0"
+version: "14.0"
 description: Defines behavior and limits for the Snowflake ID generator.
-requires: []
-conflicts: []
 directives:
   - id: E-106.0
     dos:
-      - Generate time-ordered Snowflake IDs.
+      - Create time-ordered Snowflake IDs.
       - Return each ID as a decimal string.
       - Use configurable epoch and identity values.
     donts:
-      - Do not present generated IDs as secrets.
+      - Do not show generated IDs as secrets.
     children:
       - id: E-106.0.0
         dos:
           - Validate worker and process IDs before generation.
-          - Reject timestamps before the configured epoch.
+          - Reject the first clock value when it is before the configured epoch.
+          - Apply rollback handling to a later clock value before the configured epoch.
+          - Use the last valid timestamp after a rollback.
         donts:
-          - Do not permit identity values outside the supported bit range.
+          - Do not create an ID from a timestamp before the configured epoch.
+          - Do not use identity values outside the supported bit range.
       - id: E-106.0.1
         dos:
-          - Protect generation from clock rollback.
+          - Keep IDs unique when the clock returns a lower value.
           - Report sequence overflow before an ID can repeat.
         donts:
           - Do not return an ID when the sequence overflows.

package/specs/out-of-scope.yaml

@@ -1,7 +1,5 @@
-version: "12.0"
+version: "14.0"
 description: Defines work outside the Snowflake ID library scope.
-requires: []
-conflicts: []
 directives:
   - id: E-106.2
     dos:

package/specs/requirements.yaml

@@ -1,13 +1,11 @@
-version: "12.0"
+version: "14.0"
 description: Defines repository requirements for the Snowflake ID library.
-requires: []
-conflicts: []
 directives:
   - id: E-106.1
     dos:
       - Preserve the documented Snowflake ID behavior.
       - Return IDs as decimal strings.
-      - Protect credentials and private data.
-      - Pass the repository validation commands before review.
+      - Keep credentials and private data private.
+      - Pass repository validation before inspection.
     donts:
       - Do not use IDs as secrets or authentication tokens.

package/src/generator-options.mjs

@@ -8,6 +8,7 @@ export function validateGeneratorOptions({
   workerId = 0,
   processId = process.pid % 32,
   now = defaultNow,
+  logger,
 } = {}) {
   if (typeof epoch === "number" && !Number.isSafeInteger(epoch))
     throw new RangeError("epoch must be between 0 and the timestamp limit");
@@ -15,7 +16,13 @@ export function validateGeneratorOptions({
   if (baseEpoch < 0n || baseEpoch > MAX_TIMESTAMP)
     throw new RangeError("epoch must be between 0 and the timestamp limit");
   const identity = validateIdentity(workerId, processId);
-  if (typeof now !== "function") throw new TypeError("now must be a function");
+  if (typeof now !== "function") throw new TypeError("clock source must be a function");
+  if (
+    logger !== undefined &&
+    (!logger ||
+      ["error", "warn", "info", "debug"].some((level) => typeof logger[level] !== "function"))
+  )
+    throw new TypeError("logger must provide error, warn, info, and debug methods");
 
-  return { baseEpoch, ...identity, now };
+  return { baseEpoch, ...identity, now, logger };
 }

package/src/generator.mjs

@@ -8,40 +8,76 @@ import {
 import { validateGeneratorOptions } from "./generator-options.mjs";
 
 export function createGenerator(options = {}) {
-  const { baseEpoch, worker, processNumber, now } = validateGeneratorOptions(options);
+  const { baseEpoch, worker, processNumber, now, logger } = validateGeneratorOptions(options);
 
   let lastTimestamp = -1n;
   let sequence = 0n;
 
+  logger?.info("Snowflake generator created", {
+    component: "snowflake",
+    operation: "create-generator",
+    epoch: baseEpoch.toString(),
+    workerId: worker.toString(),
+    processId: processNumber.toString(),
+  });
+
   function readTime() {
     const clockValue = now();
     if (typeof clockValue === "number" && !Number.isSafeInteger(clockValue))
       throw new RangeError("current time must be a safe integer or bigint");
     const timestamp = BigInt(clockValue);
-    if (timestamp < baseEpoch) throw new RangeError("current time must not be before epoch");
+    if (timestamp < baseEpoch && lastTimestamp < baseEpoch)
+      throw new RangeError("current time must not be before epoch");
     return timestamp;
   }
 
   return function generate() {
-    let timestamp = readTime();
-    if (timestamp < lastTimestamp) timestamp = lastTimestamp;
-    let nextSequence;
-    if (timestamp === lastTimestamp) {
-      if (sequence === SEQUENCE_MASK)
-        throw new RangeError("sequence overflow; clock must advance before retrying");
-      nextSequence = sequence + 1n;
-    } else {
-      nextSequence = 0n;
+    try {
+      let timestamp = readTime();
+      if (timestamp < lastTimestamp) {
+        logger?.warn("Snowflake clock moved backward", {
+          component: "snowflake",
+          operation: "generate",
+          event: "clock-rollback",
+          timestamp: timestamp.toString(),
+          lastTimestamp: lastTimestamp.toString(),
+        });
+        timestamp = lastTimestamp;
+      }
+      let nextSequence;
+      if (timestamp === lastTimestamp) {
+        if (sequence === SEQUENCE_MASK)
+          throw new RangeError(
+            "sequence overflow. Retry when the clock returns a greater timestamp.",
+          );
+        nextSequence = sequence + 1n;
+      } else {
+        nextSequence = 0n;
+      }
+      const elapsed = timestamp - baseEpoch;
+      if (elapsed > MAX_TIMESTAMP) throw new RangeError("timestamp exceeds Snowflake capacity");
+      lastTimestamp = timestamp;
+      sequence = nextSequence;
+      const id = (
+        (elapsed << (WORKER_BITS + PROCESS_BITS + SEQUENCE_BITS)) |
+        (worker << (PROCESS_BITS + SEQUENCE_BITS)) |
+        (processNumber << SEQUENCE_BITS) |
+        nextSequence
+      ).toString();
+      logger?.debug("Snowflake ID generated", {
+        component: "snowflake",
+        operation: "generate",
+        timestamp: timestamp.toString(),
+        sequence: nextSequence.toString(),
+      });
+      return id;
+    } catch (error) {
+      logger?.error("Snowflake ID generation failed", {
+        component: "snowflake",
+        operation: "generate",
+        errorType: error.name,
+      });
+      throw error;
     }
-    const elapsed = timestamp - baseEpoch;
-    if (elapsed > MAX_TIMESTAMP) throw new RangeError("timestamp exceeds Snowflake capacity");
-    lastTimestamp = timestamp;
-    sequence = nextSequence;
-    return (
-      (elapsed << (WORKER_BITS + PROCESS_BITS + SEQUENCE_BITS)) |
-      (worker << (PROCESS_BITS + SEQUENCE_BITS)) |
-      (processNumber << SEQUENCE_BITS) |
-      nextSequence
-    ).toString();
   };
 }

package/src/index.d.ts

@@ -1,10 +1,15 @@
+import type { LoggerWithConfiguredLevels } from "@eliware/log";
+
 export interface SnowflakeGeneratorOptions {
   epoch?: number | bigint;
   workerId?: number | bigint;
   processId?: number | bigint;
   now?: () => number | bigint;
+  logger?: LoggerWithConfiguredLevels;
 }
 
+export type { LoggerWithConfiguredLevels } from "@eliware/log";
+
 export interface SnowflakeConstants {
   readonly epoch: bigint;
   readonly sequenceBits: bigint;