first commit

docs/foundation/bitpacker/bitpacker-schema/src/registry/defaults/default-clock.md

@@ -0,0 +1,56 @@
+# defaultClock (schema-registry)
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`defaultClock` is the single point in `@suaveplan/bitpacker-schema/registry` where the wall clock is read. The `SchemaRegistry` class accepts an injectable `Clock` for stamping `createdAt`/`updatedAt` on registered entries; when no clock is provided, it falls back to this default.
+
+Centralising the `Date.now()` call this way matches the pattern used by `@suaveplan/bitpacker-streaming` and `@suaveplan/bitpacker-network`. suaveplan enforces a "no module-scope `Date.now()`/`Math.random()`" rule outside allow-listed defaults — this file is one of those defaults.
+
+## Features
+
+- Single named export `defaultClock: Clock` typed via `@suaveplan/types`.
+- Pure function — no side effects beyond reading the wall clock.
+- Idiomatic Suaveplan convention for clock injection.
+
+## Usage: Basic Example
+
+```ts
+import { defaultClock } from "@suaveplan/bitpacker-schema";
+
+const now = defaultClock();
+```
+
+## Usage: Advanced Example
+
+```ts
+import type { Clock } from "@suaveplan/types";
+import { SchemaRegistry } from "@suaveplan/bitpacker-schema";
+
+// Inject a deterministic clock for reproducible test timestamps.
+let t = 0;
+const fakeClock: Clock = () => {
+    t += 1000;
+    return t;
+};
+
+const registry = new SchemaRegistry(undefined, { clock: fakeClock });
+await registry.registerSchema(
+    { id: "uuid" },
+    { namespace: "events", name: "user-created" }
+);
+```
+
+## API Reference
+
+### `defaultClock: Clock`
+
+Returns `Date.now()` — the current wall-clock time in milliseconds.
+
+## Implementation Notes
+
+The `Clock` type is `() => number`. suaveplan prefers function types over class instances for monotonic primitives because they are trivially serialisable, comparable, and substitutable in tests without dependency-injection frameworks.
+
+The reason this lives in `registry/defaults/` rather than as a static class member is the lint rule that bans module-scope `Date.now()` calls in production code. By scoping the call to a single named, lint-allow-listed module, we keep the rest of the package free of static analysis exceptions.