@optimystic/db-core 0.22.0 → 0.24.0

package/src/cohort-topic/registration/sharding.ts

@@ -1,61 +1,61 @@
-/**
- * Cohort-topic substrate — deterministic primary/backup sharding.
- *
- * Transcribed from `docs/cohort-topic.md` §Primary and backup sharding:
- *
- * ```
- * order(cohortMembers) = sort(cohortMembers, by PeerId ascending)
- * slot(participantId, cohortEpoch) = H(participantId ‖ cohortEpoch) mod k
- * primary  = order[slot]
- * backups  = order[slot+1 .. slot+2  (mod k)]
- * ```
- *
- * Deterministic given `(participantId, cohortEpoch, members)`; shards delivery load roughly evenly
- * across the `~k` members. `H` is the injected {@link IRingHash} (db-core's own SHA-256 — **not** a
- * FRET import), reused so coords stay byte-compatible with the rest of the substrate.
- */
-
-import type { IRingHash } from "../ports.js";
-import { compareBytes, concatBytes } from "./bytes.js";
-
-/** Deterministic slot assignment over a fixed cohort snapshot. */
-export interface SlotAssigner {
-	/**
-	 * `(primary, backups)` for `participantId` under `cohortEpoch` and `cohortMembers`.
-	 * Backups are the 1..2 members following the primary in ascending order, wrapping mod `k`.
-	 */
-	assignSlots(participantId: Uint8Array, cohortEpoch: Uint8Array, cohortMembers: readonly Uint8Array[]): { primary: Uint8Array; backups: Uint8Array[] };
-}
-
-/** Number of warm-failover backups (capped by available members). */
-const MAX_BACKUPS = 2;
-
-/** `coord mod k` over the full digest, MSB-first, without bigint allocation. */
-function modK(coord: Uint8Array, k: number): number {
-	let acc = 0;
-	for (let i = 0; i < coord.length; i++) {
-		acc = (acc * 256 + coord[i]!) % k;
-	}
-	return acc;
-}
-
-/** Build a {@link SlotAssigner} bound to a hash. */
-export function createSlotAssigner(hash: IRingHash): SlotAssigner {
-	return {
-		assignSlots(participantId: Uint8Array, cohortEpoch: Uint8Array, cohortMembers: readonly Uint8Array[]): { primary: Uint8Array; backups: Uint8Array[] } {
-			const k = cohortMembers.length;
-			if (k === 0) {
-				throw new RangeError("assignSlots requires a non-empty cohort");
-			}
-			const order = [...cohortMembers].sort(compareBytes);
-			const slot = modK(hash.H(concatBytes(participantId, cohortEpoch)), k);
-			const primary = order[slot]!;
-			const backups: Uint8Array[] = [];
-			const nBackups = Math.min(MAX_BACKUPS, k - 1);
-			for (let i = 1; i <= nBackups; i++) {
-				backups.push(order[(slot + i) % k]!);
-			}
-			return { primary, backups };
-		},
-	};
-}
+/**
+ * Cohort-topic substrate — deterministic primary/backup sharding.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Primary and backup sharding:
+ *
+ * ```
+ * order(cohortMembers) = sort(cohortMembers, by PeerId ascending)
+ * slot(participantId, cohortEpoch) = H(participantId ‖ cohortEpoch) mod k
+ * primary  = order[slot]
+ * backups  = order[slot+1 .. slot+2  (mod k)]
+ * ```
+ *
+ * Deterministic given `(participantId, cohortEpoch, members)`; shards delivery load roughly evenly
+ * across the `~k` members. `H` is the injected {@link IRingHash} (db-core's own SHA-256 — **not** a
+ * FRET import), reused so coords stay byte-compatible with the rest of the substrate.
+ */
+
+import type { IRingHash } from "../ports.js";
+import { compareBytes, concatBytes } from "./bytes.js";
+
+/** Deterministic slot assignment over a fixed cohort snapshot. */
+export interface SlotAssigner {
+	/**
+	 * `(primary, backups)` for `participantId` under `cohortEpoch` and `cohortMembers`.
+	 * Backups are the 1..2 members following the primary in ascending order, wrapping mod `k`.
+	 */
+	assignSlots(participantId: Uint8Array, cohortEpoch: Uint8Array, cohortMembers: readonly Uint8Array[]): { primary: Uint8Array; backups: Uint8Array[] };
+}
+
+/** Number of warm-failover backups (capped by available members). */
+const MAX_BACKUPS = 2;
+
+/** `coord mod k` over the full digest, MSB-first, without bigint allocation. */
+function modK(coord: Uint8Array, k: number): number {
+	let acc = 0;
+	for (let i = 0; i < coord.length; i++) {
+		acc = (acc * 256 + coord[i]!) % k;
+	}
+	return acc;
+}
+
+/** Build a {@link SlotAssigner} bound to a hash. */
+export function createSlotAssigner(hash: IRingHash): SlotAssigner {
+	return {
+		assignSlots(participantId: Uint8Array, cohortEpoch: Uint8Array, cohortMembers: readonly Uint8Array[]): { primary: Uint8Array; backups: Uint8Array[] } {
+			const k = cohortMembers.length;
+			if (k === 0) {
+				throw new RangeError("assignSlots requires a non-empty cohort");
+			}
+			const order = [...cohortMembers].sort(compareBytes);
+			const slot = modK(hash.H(concatBytes(participantId, cohortEpoch)), k);
+			const primary = order[slot]!;
+			const backups: Uint8Array[] = [];
+			const nBackups = Math.min(MAX_BACKUPS, k - 1);
+			for (let i = 1; i <= nBackups; i++) {
+				backups.push(order[(slot + i) % k]!);
+			}
+			return { primary, backups };
+		},
+	};
+}

package/src/cohort-topic/registration/store.ts

@@ -1,81 +1,81 @@
-/**
- * Cohort-topic substrate — in-memory registration store.
- *
- * Per `docs/cohort-topic.md` §Registration mechanics. Records are doubly indexed: an outer map
- * keyed by topic, each holding an inner map keyed by participant. This gives O(1)
- * {@link RegistrationStore.getByParticipant} / {@link RegistrationStore.delete} and O(participants)
- * {@link RegistrationStore.listByTopic} without a secondary index to keep in sync. The store is
- * local soft state; cross-member replication runs over cohort gossip in a later ticket.
- */
-
-import { bytesKey } from "./bytes.js";
-import type { RegistrationRecord, RegistrationStore } from "./types.js";
-
-class InMemoryRegistrationStore implements RegistrationStore {
-	/** topicKey → (participantKey → record). Inner maps are pruned when they empty. */
-	private readonly byTopic = new Map<string, Map<string, RegistrationRecord>>();
-
-	put(rec: RegistrationRecord): void {
-		const tk = bytesKey(rec.topicId);
-		let inner = this.byTopic.get(tk);
-		if (inner === undefined) {
-			inner = new Map<string, RegistrationRecord>();
-			this.byTopic.set(tk, inner);
-		}
-		inner.set(bytesKey(rec.participantId), rec);
-	}
-
-	getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined {
-		return this.byTopic.get(bytesKey(topicId))?.get(bytesKey(participantId));
-	}
-
-	listByTopic(topicId: Uint8Array): readonly RegistrationRecord[] {
-		const inner = this.byTopic.get(bytesKey(topicId));
-		return inner === undefined ? [] : [...inner.values()];
-	}
-
-	listAll(): readonly RegistrationRecord[] {
-		const out: RegistrationRecord[] = [];
-		for (const inner of this.byTopic.values()) {
-			for (const rec of inner.values()) {
-				out.push(rec);
-			}
-		}
-		return out;
-	}
-
-	delete(topicId: Uint8Array, participantId: Uint8Array): void {
-		const tk = bytesKey(topicId);
-		const inner = this.byTopic.get(tk);
-		if (inner === undefined) return;
-		inner.delete(bytesKey(participantId));
-		if (inner.size === 0) {
-			this.byTopic.delete(tk);
-		}
-	}
-
-	directParticipants(topicId: Uint8Array): number {
-		return this.byTopic.get(bytesKey(topicId))?.size ?? 0;
-	}
-
-	evictStale(now: number): readonly RegistrationRecord[] {
-		const evicted: RegistrationRecord[] = [];
-		for (const [tk, inner] of this.byTopic) {
-			for (const [pk, rec] of inner) {
-				if (now - rec.lastPing > rec.ttl) {
-					evicted.push(rec);
-					inner.delete(pk);
-				}
-			}
-			if (inner.size === 0) {
-				this.byTopic.delete(tk);
-			}
-		}
-		return evicted;
-	}
-}
-
-/** Construct an empty {@link RegistrationStore}. */
-export function createRegistrationStore(): RegistrationStore {
-	return new InMemoryRegistrationStore();
-}
+/**
+ * Cohort-topic substrate — in-memory registration store.
+ *
+ * Per `docs/cohort-topic.md` §Registration mechanics. Records are doubly indexed: an outer map
+ * keyed by topic, each holding an inner map keyed by participant. This gives O(1)
+ * {@link RegistrationStore.getByParticipant} / {@link RegistrationStore.delete} and O(participants)
+ * {@link RegistrationStore.listByTopic} without a secondary index to keep in sync. The store is
+ * local soft state; cross-member replication runs over cohort gossip in a later ticket.
+ */
+
+import { bytesKey } from "./bytes.js";
+import type { RegistrationRecord, RegistrationStore } from "./types.js";
+
+class InMemoryRegistrationStore implements RegistrationStore {
+	/** topicKey → (participantKey → record). Inner maps are pruned when they empty. */
+	private readonly byTopic = new Map<string, Map<string, RegistrationRecord>>();
+
+	put(rec: RegistrationRecord): void {
+		const tk = bytesKey(rec.topicId);
+		let inner = this.byTopic.get(tk);
+		if (inner === undefined) {
+			inner = new Map<string, RegistrationRecord>();
+			this.byTopic.set(tk, inner);
+		}
+		inner.set(bytesKey(rec.participantId), rec);
+	}
+
+	getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined {
+		return this.byTopic.get(bytesKey(topicId))?.get(bytesKey(participantId));
+	}
+
+	listByTopic(topicId: Uint8Array): readonly RegistrationRecord[] {
+		const inner = this.byTopic.get(bytesKey(topicId));
+		return inner === undefined ? [] : [...inner.values()];
+	}
+
+	listAll(): readonly RegistrationRecord[] {
+		const out: RegistrationRecord[] = [];
+		for (const inner of this.byTopic.values()) {
+			for (const rec of inner.values()) {
+				out.push(rec);
+			}
+		}
+		return out;
+	}
+
+	delete(topicId: Uint8Array, participantId: Uint8Array): void {
+		const tk = bytesKey(topicId);
+		const inner = this.byTopic.get(tk);
+		if (inner === undefined) return;
+		inner.delete(bytesKey(participantId));
+		if (inner.size === 0) {
+			this.byTopic.delete(tk);
+		}
+	}
+
+	directParticipants(topicId: Uint8Array): number {
+		return this.byTopic.get(bytesKey(topicId))?.size ?? 0;
+	}
+
+	evictStale(now: number): readonly RegistrationRecord[] {
+		const evicted: RegistrationRecord[] = [];
+		for (const [tk, inner] of this.byTopic) {
+			for (const [pk, rec] of inner) {
+				if (now - rec.lastPing > rec.ttl) {
+					evicted.push(rec);
+					inner.delete(pk);
+				}
+			}
+			if (inner.size === 0) {
+				this.byTopic.delete(tk);
+			}
+		}
+		return evicted;
+	}
+}
+
+/** Construct an empty {@link RegistrationStore}. */
+export function createRegistrationStore(): RegistrationStore {
+	return new InMemoryRegistrationStore();
+}

package/src/cohort-topic/registration/types.ts

@@ -1,91 +1,91 @@
-/**
- * Cohort-topic substrate — registration record store, types and constants.
- *
- * Transcribed from `docs/cohort-topic.md` §Registration mechanics and §Primary and backup
- * sharding. This module owns the **local**, transport-agnostic shapes: the soft-state record a
- * cohort member holds per participant, the in-memory store interface over those records, and the
- * TTL constants. Cross-member replication (cohort gossip) is layered on top by db-p2p and the
- * bridge ticket; db-core never imports FRET or libp2p here.
- *
- * Peer ids are the opaque byte-array references the cohort-topic substrate uses throughout — the
- * same representation as {@link import("../ports.js").PeerRef}`.id` and
- * {@link import("../ports.js").RingCoord} (raw `Uint8Array`, not the structural
- * {@link import("../../network/types.js").PeerId}). The wire layer carries them as base64url
- * strings; this store works in raw bytes and the renewal/handoff bridges translate at the wire
- * boundary.
- */
-
-/**
- * Soft-state registration a cohort member holds per participant. Replicated across the `~k`
- * members by cohort gossip; only {@link RegistrationRecord.primary} serves, with
- * {@link RegistrationRecord.backups} watching for warm failover.
- */
-export interface RegistrationRecord {
-	/** Topic id, 32 bytes. */
-	topicId: Uint8Array;
-	/** Registering participant. */
-	participantId: Uint8Array;
-	/** Tier this registration sits at (0..3). */
-	tier: number;
-	/** Cohort member assigned to serve this participant. */
-	primary: Uint8Array;
-	/** 1..2 warm-failover cohort members. */
-	backups: Uint8Array[];
-	/** Unix ms the registration first attached. */
-	attachedAt: number;
-	/** Unix ms of the most recent successful ping/touch. */
-	lastPing: number;
-	/** Lifetime in ms; record is stale once `now − lastPing > ttl`. */
-	ttl: number;
-	/** Opaque application-defined per-registration state; the layer never interprets it. */
-	appState?: Uint8Array;
-}
-
-/**
- * In-memory registration store, indexed for both per-participant lookup and per-topic listing.
- * This ticket owns the **local** store and its indexes; the gossip layer and TTL loop call the
- * deterministic functions over it.
- */
-export interface RegistrationStore {
-	/** Insert or replace the record for `(topicId, participantId)`. */
-	put(rec: RegistrationRecord): void;
-	/** Record for `(topicId, participantId)`, or `undefined`. */
-	getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined;
-	/** All records held for `topicId` (empty if none). */
-	listByTopic(topicId: Uint8Array): readonly RegistrationRecord[];
-	/** Every record across all topics — used by the rotation handoff inventory pass. */
-	listAll(): readonly RegistrationRecord[];
-	/** Remove the record for `(topicId, participantId)`. */
-	delete(topicId: Uint8Array, participantId: Uint8Array): void;
-	/** Stock count of direct participants for `topicId` (drives promotion). */
-	directParticipants(topicId: Uint8Array): number;
-	/** Remove and return every record where `now − lastPing > ttl`. */
-	evictStale(now: number): readonly RegistrationRecord[];
-}
-
-/** Core-tier default registration TTL (ms). */
-export const DEFAULT_TTL_MS = 90_000;
-/** Edge-tier default registration TTL (ms). */
-export const EDGE_TTL_MS = 60_000;
-/** Minimum accepted registration TTL (ms). Requests below this are clamped up. */
-export const MIN_TTL_MS = 10_000;
-/** Maximum accepted registration TTL (ms). Requests above this are clamped down.
- *  10 × DEFAULT_TTL_MS keeps the window predictable; prevents a wedged budget slot from a poison TTL. */
-export const MAX_TTL_MS = 10 * DEFAULT_TTL_MS;
-/** Consecutive ping failures before a participant promotes `backups[0]`. */
-export const MAX_PING_FAILURES = 3;
-
-/**
- * Clamp a requested or replicated TTL into the accepted `[MIN_TTL_MS, MAX_TTL_MS]` window.
- * Non-positive input falls to {@link DEFAULT_TTL_MS} first. This is the single TTL policy gate:
- * both local admission (`accept()`) and gossip replication (`mergeRecords`) run every TTL through
- * it, so no store — local or replica — can ever hold a record whose lifetime dodges the cap.
- */
-export function clampTtl(ttl: number): number {
-	return Math.min(Math.max(ttl > 0 ? ttl : DEFAULT_TTL_MS, MIN_TTL_MS), MAX_TTL_MS);
-}
-
-/** `ping_interval = ttl / 3` (default 30s Core, 20s Edge), floored to whole ms. */
-export function pingIntervalMs(ttl: number): number {
-	return Math.floor(ttl / 3);
-}
+/**
+ * Cohort-topic substrate — registration record store, types and constants.
+ *
+ * Transcribed from `docs/cohort-topic.md` §Registration mechanics and §Primary and backup
+ * sharding. This module owns the **local**, transport-agnostic shapes: the soft-state record a
+ * cohort member holds per participant, the in-memory store interface over those records, and the
+ * TTL constants. Cross-member replication (cohort gossip) is layered on top by db-p2p and the
+ * bridge ticket; db-core never imports FRET or libp2p here.
+ *
+ * Peer ids are the opaque byte-array references the cohort-topic substrate uses throughout — the
+ * same representation as {@link import("../ports.js").PeerRef}`.id` and
+ * {@link import("../ports.js").RingCoord} (raw `Uint8Array`, not the structural
+ * {@link import("../../network/types.js").PeerId}). The wire layer carries them as base64url
+ * strings; this store works in raw bytes and the renewal/handoff bridges translate at the wire
+ * boundary.
+ */
+
+/**
+ * Soft-state registration a cohort member holds per participant. Replicated across the `~k`
+ * members by cohort gossip; only {@link RegistrationRecord.primary} serves, with
+ * {@link RegistrationRecord.backups} watching for warm failover.
+ */
+export interface RegistrationRecord {
+	/** Topic id, 32 bytes. */
+	topicId: Uint8Array;
+	/** Registering participant. */
+	participantId: Uint8Array;
+	/** Tier this registration sits at (0..3). */
+	tier: number;
+	/** Cohort member assigned to serve this participant. */
+	primary: Uint8Array;
+	/** 1..2 warm-failover cohort members. */
+	backups: Uint8Array[];
+	/** Unix ms the registration first attached. */
+	attachedAt: number;
+	/** Unix ms of the most recent successful ping/touch. */
+	lastPing: number;
+	/** Lifetime in ms; record is stale once `now − lastPing > ttl`. */
+	ttl: number;
+	/** Opaque application-defined per-registration state; the layer never interprets it. */
+	appState?: Uint8Array;
+}
+
+/**
+ * In-memory registration store, indexed for both per-participant lookup and per-topic listing.
+ * This ticket owns the **local** store and its indexes; the gossip layer and TTL loop call the
+ * deterministic functions over it.
+ */
+export interface RegistrationStore {
+	/** Insert or replace the record for `(topicId, participantId)`. */
+	put(rec: RegistrationRecord): void;
+	/** Record for `(topicId, participantId)`, or `undefined`. */
+	getByParticipant(topicId: Uint8Array, participantId: Uint8Array): RegistrationRecord | undefined;
+	/** All records held for `topicId` (empty if none). */
+	listByTopic(topicId: Uint8Array): readonly RegistrationRecord[];
+	/** Every record across all topics — used by the rotation handoff inventory pass. */
+	listAll(): readonly RegistrationRecord[];
+	/** Remove the record for `(topicId, participantId)`. */
+	delete(topicId: Uint8Array, participantId: Uint8Array): void;
+	/** Stock count of direct participants for `topicId` (drives promotion). */
+	directParticipants(topicId: Uint8Array): number;
+	/** Remove and return every record where `now − lastPing > ttl`. */
+	evictStale(now: number): readonly RegistrationRecord[];
+}
+
+/** Core-tier default registration TTL (ms). */
+export const DEFAULT_TTL_MS = 90_000;
+/** Edge-tier default registration TTL (ms). */
+export const EDGE_TTL_MS = 60_000;
+/** Minimum accepted registration TTL (ms). Requests below this are clamped up. */
+export const MIN_TTL_MS = 10_000;
+/** Maximum accepted registration TTL (ms). Requests above this are clamped down.
+ *  10 × DEFAULT_TTL_MS keeps the window predictable; prevents a wedged budget slot from a poison TTL. */
+export const MAX_TTL_MS = 10 * DEFAULT_TTL_MS;
+/** Consecutive ping failures before a participant promotes `backups[0]`. */
+export const MAX_PING_FAILURES = 3;
+
+/**
+ * Clamp a requested or replicated TTL into the accepted `[MIN_TTL_MS, MAX_TTL_MS]` window.
+ * Non-positive input falls to {@link DEFAULT_TTL_MS} first. This is the single TTL policy gate:
+ * both local admission (`accept()`) and gossip replication (`mergeRecords`) run every TTL through
+ * it, so no store — local or replica — can ever hold a record whose lifetime dodges the cap.
+ */
+export function clampTtl(ttl: number): number {
+	return Math.min(Math.max(ttl > 0 ? ttl : DEFAULT_TTL_MS, MIN_TTL_MS), MAX_TTL_MS);
+}
+
+/** `ping_interval = ttl / 3` (default 30s Core, 20s Edge), floored to whole ms. */
+export function pingIntervalMs(ttl: number): number {
+	return Math.floor(ttl / 3);
+}

package/src/cohort-topic/ring-hash.ts

@@ -1,50 +1,50 @@
-import { sha256 } from '@noble/hashes/sha2.js';
-import type { IRingHash, RingCoord } from './ports.js';
-
-/**
- * Default ring width in bits. 256 = the full SHA-256 digest, which lines up byte-for-byte with
- * FRET's coordinate type (FRET hashes ring keys with SHA-256). Override only when targeting a
- * DHT with a narrower ring.
- */
-export const RING_BITS = 256;
-
-/**
- * db-core's {@link IRingHash}, backed by its own SHA-256 (the same digest db-core already uses
- * for logs and block ids) — **not** an import of any FRET hash module. This keeps db-core
- * FRET-free while guaranteeing on-the-wire coord compatibility: at the default `ringBits = 256`,
- * `H(bytes)` is the full SHA-256 digest, identical to what FRET produces for the same input.
- *
- * For ring widths that are not a whole number of bytes, the digest is truncated to
- * `ceil(ringBits / 8)` bytes and the trailing partial byte's unused low bits are zeroed, so two
- * inputs whose digests share the first `ringBits` bits yield byte-identical coords.
- */
-export class RingHash implements IRingHash {
-	public readonly ringBits: number;
-	private readonly nBytes: number;
-	private readonly tailMask: number;
-
-	constructor(ringBits: number = RING_BITS) {
-		if (!Number.isInteger(ringBits) || ringBits <= 0 || ringBits > 256) {
-			throw new RangeError(`ringBits must be an integer in [1, 256], got ${ringBits}`);
-		}
-		this.ringBits = ringBits;
-		this.nBytes = Math.ceil(ringBits / 8);
-		const remBits = ringBits - (this.nBytes - 1) * 8;
-		this.tailMask = remBits === 8 ? 0xff : (0xff << (8 - remBits)) & 0xff;
-	}
-
-	H(bytes: Uint8Array): RingCoord {
-		const digest = sha256(bytes);
-		if (this.nBytes === digest.length && this.tailMask === 0xff) {
-			return digest;
-		}
-		const coord = digest.slice(0, this.nBytes);
-		coord[this.nBytes - 1] = coord[this.nBytes - 1]! & this.tailMask;
-		return coord;
-	}
-}
-
-/** Convenience factory mirroring the db-p2p adapter construction style. */
-export function createRingHash(ringBits: number = RING_BITS): IRingHash {
-	return new RingHash(ringBits);
-}
+import { sha256 } from '@noble/hashes/sha2.js';
+import type { IRingHash, RingCoord } from './ports.js';
+
+/**
+ * Default ring width in bits. 256 = the full SHA-256 digest, which lines up byte-for-byte with
+ * FRET's coordinate type (FRET hashes ring keys with SHA-256). Override only when targeting a
+ * DHT with a narrower ring.
+ */
+export const RING_BITS = 256;
+
+/**
+ * db-core's {@link IRingHash}, backed by its own SHA-256 (the same digest db-core already uses
+ * for logs and block ids) — **not** an import of any FRET hash module. This keeps db-core
+ * FRET-free while guaranteeing on-the-wire coord compatibility: at the default `ringBits = 256`,
+ * `H(bytes)` is the full SHA-256 digest, identical to what FRET produces for the same input.
+ *
+ * For ring widths that are not a whole number of bytes, the digest is truncated to
+ * `ceil(ringBits / 8)` bytes and the trailing partial byte's unused low bits are zeroed, so two
+ * inputs whose digests share the first `ringBits` bits yield byte-identical coords.
+ */
+export class RingHash implements IRingHash {
+	public readonly ringBits: number;
+	private readonly nBytes: number;
+	private readonly tailMask: number;
+
+	constructor(ringBits: number = RING_BITS) {
+		if (!Number.isInteger(ringBits) || ringBits <= 0 || ringBits > 256) {
+			throw new RangeError(`ringBits must be an integer in [1, 256], got ${ringBits}`);
+		}
+		this.ringBits = ringBits;
+		this.nBytes = Math.ceil(ringBits / 8);
+		const remBits = ringBits - (this.nBytes - 1) * 8;
+		this.tailMask = remBits === 8 ? 0xff : (0xff << (8 - remBits)) & 0xff;
+	}
+
+	H(bytes: Uint8Array): RingCoord {
+		const digest = sha256(bytes);
+		if (this.nBytes === digest.length && this.tailMask === 0xff) {
+			return digest;
+		}
+		const coord = digest.slice(0, this.nBytes);
+		coord[this.nBytes - 1] = coord[this.nBytes - 1]! & this.tailMask;
+		return coord;
+	}
+}
+
+/** Convenience factory mirroring the db-p2p adapter construction style. */
+export function createRingHash(ringBits: number = RING_BITS): IRingHash {
+	return new RingHash(ringBits);
+}