@lsdsoftware/ordered-record-store 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LSD Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# ordered-record-store
+
+A small TypeScript ESM module for appending and retrieving opaque records in order.
+
+The package is deliberately domain-neutral. It knows about streams, records, and storage lifecycle; it does not know about users, buddies, messages, conversations, or any host application.
+
+## Design status
+
+The durable design is a **working design, not a frozen contract**. The package now
+includes both the memory adapter used by fast tests and the segmented local/S3
+adapter described below. Memory-store records disappear when the process exits;
+do not deploy that adapter as production persistence.
+
+The durable adapter uses local working segments as a write-back cache over one S3 segment namespace:
+
+```text
+append opaque record
+  -> append complete framed record to local working segment
+  -> durably flush local file
+  -> acknowledge caller
+  -> overwrite that segment's S3 object after at most about five minutes
+  -> rotate near 256 KiB; after 14 idle days evict a clean local copy
+```
+
+S3 is never on the synchronous append path. The design accepts up to roughly five minutes of loss only when the local durable volume itself is catastrophically lost.
+
+## Public API
+
+The current interface provides:
+
+- `append({ streamId, data })`
+- `read({ streamId, beforeId?, afterId?, limit })`
+- `getLatest(streamIds)`
+- `compareRecordIds(left, right)` and explicit async `close()`
+- opaque string stream IDs, record IDs, and record data
+
+The old caller-supplied idempotency key, duplicate result, and stream-deletion API
+have been removed. The store does not permanently deduplicate caller requests. A
+consuming application may perform cheap, domain-aware best-effort duplicate
+suppression at the stream head.
+
+The durable design uses per-record UUIDv7 values internally. Its public 43-character base64url cursor contains both the record UUID and its segment UUID, allowing exact segment lookup without a manifest. Both adapters use this format. Consumers treat it as opaque and call `compareRecordIds()` only when record ordering is actually required. The async durable factory reconstructs local files only and performs no S3 availability check at startup.
+
+## Segment lifecycle summary
+
+- The newest segment is mutable; older segments become immutable when rotation creates a newer segment.
+- Before appending, rotate when the current segment is approximately 256 KiB or larger; overshoot by one complete record is fine.
+- The first append that makes a clean local segment dirty sets a five-minute checkpoint deadline. Later appends do not move it.
+- A durable per-file clean/dirty bit lets startup recover unsynced-to-S3 local bytes without a persisted catalog or remote active namespace.
+- If no local file exists, locate the newest S3 segment with one newest-first listing. Download it when it is below the rotation target; otherwise create a new segment.
+- After 14 days without a successful append, evict the normally clean local copy. A dirty-and-idle file is an exceptional long-outage recovery case and must upload successfully before eviction. This is cache eviction, not sealing.
+- Startup validates local files, reconstructs only the local working set, and queues dirty uploads. It performs no S3 probe, listing, or download.
+- Nonlocal segments are fetched as complete objects and retained in a disposable 64-segment in-memory LRU, avoiding repeat `GetObject` calls during continued pagination.
+- The MVP assumes exactly one store/service instance.
+- The bucket has versioning disabled and never transitions segment objects to Glacier or another restore-required storage class.
+- Version 1 uses a small custom big-endian binary frame with leading/trailing lengths and CRC32C, plus SHA-256 for each S3 upload; it does not use Protobuf.
+
+See [docs/DESIGN.md](docs/DESIGN.md) for the complete recovery cases, decisions, open questions, and implementation sequence.
+
+## Usage
+
+The memory adapter is created with:
+
+```ts
+import { createMemoryOrderedRecordStore } from '@lsdsoftware/ordered-record-store'
+
+const store = createMemoryOrderedRecordStore()
+```
+
+The durable adapter is opened asynchronously with an explicit persistent local
+directory and an injected object-store boundary:
+
+```ts
+import {
+  createS3SegmentObjectStore,
+  openSegmentedOrderedRecordStore,
+} from '@lsdsoftware/ordered-record-store'
+import { S3Client } from '@aws-sdk/client-s3'
+
+const objectStore = createS3SegmentObjectStore({
+  client: new S3Client({ region: 'ap-southeast-1' }),
+  bucket: 'example-ordered-records',
+  keyPrefix: 'messenger',
+})
+
+const store = await openSegmentedOrderedRecordStore({
+  dataDirectory: '/var/lib/diepkhuc/ordered-record-store',
+  objectStore,
+})
+```
+
+Create one instance per consuming process and inject it into all handlers. The
+application owns AWS client configuration and credentials. Call `close()` during
+graceful shutdown; dirty local files are recovered and queued on the next start.
+
+## Commands
+
+Node.js 20 or newer is required.
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+The package is already consumed by `apsvc-diepkhuc-messenger` through a local `file:` dependency. Publishing or pinning a reproducible package version remains deployment work.

package/dist/crc32c.d.ts

@@ -0,0 +1,2 @@
+/** CRC-32C (Castagnoli), returned as an unsigned 32-bit integer. */
+export declare function crc32c(data: Uint8Array): number;

package/dist/crc32c.js

@@ -0,0 +1,22 @@
+const TABLE = createTable();
+/** CRC-32C (Castagnoli), returned as an unsigned 32-bit integer. */
+export function crc32c(data) {
+    let crc = 0xffffffff;
+    for (const byte of data) {
+        crc = TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function createTable() {
+    const table = new Uint32Array(256);
+    for (let index = 0; index < table.length; index++) {
+        let value = index;
+        for (let bit = 0; bit < 8; bit++) {
+            value = (value & 1) === 1
+                ? 0x82f63b78 ^ (value >>> 1)
+                : value >>> 1;
+        }
+        table[index] = value >>> 0;
+    }
+    return table;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { MAX_DATA_BYTES, MAX_IDENTIFIER_BYTES, MAX_READ_LIMIT, OrderedRecordStoreError, type AppendRequest, type OrderedRecordStore, type OrderedRecordStoreErrorCode, type ReadRequest, type RecordId, type SegmentObject, type SegmentObjectStore, type SegmentedOrderedRecordStoreOptions, type StoredRecord, type StreamId, } from './types.js';
+export { compareRecordIds } from './record-id.js';
+export { createMemoryOrderedRecordStore } from './memory-store.js';
+export { openSegmentedOrderedRecordStore } from './segmented-store.js';
+export { createS3SegmentObjectStore, type S3SegmentObjectStoreOptions, } from './s3-object-store.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { MAX_DATA_BYTES, MAX_IDENTIFIER_BYTES, MAX_READ_LIMIT, OrderedRecordStoreError, } from './types.js';
+export { compareRecordIds } from './record-id.js';
+export { createMemoryOrderedRecordStore } from './memory-store.js';
+export { openSegmentedOrderedRecordStore } from './segmented-store.js';
+export { createS3SegmentObjectStore, } from './s3-object-store.js';

package/dist/memory-store.d.ts

@@ -0,0 +1,2 @@
+import { type OrderedRecordStore } from './types.js';
+export declare function createMemoryOrderedRecordStore(): OrderedRecordStore;

package/dist/memory-store.js

@@ -0,0 +1,65 @@
+import { generateRecordIdentity, parseRecordId } from './record-id.js';
+import { OrderedRecordStoreError, } from './types.js';
+import { assertData, assertIdentifier, assertLimit, invalidArgument } from './validation.js';
+export function createMemoryOrderedRecordStore() {
+    const streams = new Map();
+    const segmentIds = new Map();
+    let closed = false;
+    return {
+        async append({ streamId, data }) {
+            assertOpen(closed);
+            assertIdentifier(streamId, 'streamId');
+            assertData(data);
+            const identity = generateRecordIdentity(segmentIds.get(streamId));
+            segmentIds.set(streamId, identity.segmentBytes);
+            const record = {
+                id: identity.id,
+                streamId,
+                data,
+                createdAt: new Date(identity.createdAtMilliseconds).toISOString(),
+            };
+            const records = streams.get(streamId) ?? [];
+            records.push(record);
+            streams.set(streamId, records);
+            return record;
+        },
+        async read({ streamId, beforeId, afterId, limit }) {
+            assertOpen(closed);
+            assertIdentifier(streamId, 'streamId');
+            assertLimit(limit);
+            if (beforeId !== undefined && afterId !== undefined) {
+                throw invalidArgument('beforeId and afterId are mutually exclusive');
+            }
+            const records = streams.get(streamId) ?? [];
+            if (beforeId === undefined && afterId === undefined) {
+                return records.slice(Math.max(0, records.length - limit));
+            }
+            const boundary = beforeId ?? afterId;
+            parseRecordId(boundary);
+            const index = records.findIndex(record => record.id === boundary);
+            if (index < 0) {
+                throw invalidArgument('pagination boundary must be a record from the requested stream');
+            }
+            return beforeId !== undefined
+                ? records.slice(Math.max(0, index - limit), index)
+                : records.slice(index + 1, index + 1 + limit);
+        },
+        async getLatest(streamIds) {
+            assertOpen(closed);
+            const result = new Map();
+            for (const streamId of streamIds) {
+                assertIdentifier(streamId, 'streamId');
+                result.set(streamId, streams.get(streamId)?.at(-1) ?? null);
+            }
+            return result;
+        },
+        async close() {
+            closed = true;
+        },
+    };
+}
+function assertOpen(closed) {
+    if (closed) {
+        throw new OrderedRecordStoreError('CLOSED', 'ordered record store is closed');
+    }
+}

package/dist/record-id.d.ts

@@ -0,0 +1,17 @@
+export interface ParsedRecordId {
+    readonly recordBytes: Buffer;
+    readonly segmentBytes: Buffer;
+    readonly recordHex: string;
+    readonly segmentHex: string;
+}
+export interface GeneratedRecordIdentity extends ParsedRecordId {
+    readonly id: string;
+    readonly createdAtMilliseconds: number;
+}
+export declare function generateRecordIdentity(segmentBytes?: Uint8Array): GeneratedRecordIdentity;
+export declare function parseRecordId(value: string, name?: string): ParsedRecordId;
+export declare function compareRecordIds(left: string, right: string): -1 | 0 | 1;
+export declare function makeRecordId(recordBytes: Uint8Array, segmentBytes: Uint8Array): string;
+export declare function uuidV7Timestamp(bytes: Uint8Array): number;
+export declare function invertUuidHex(bytes: Uint8Array): string;
+export declare function segmentBytesFromHex(value: string): Buffer;

package/dist/record-id.js

@@ -0,0 +1,82 @@
+import { parse as parseUuid, v7 as uuidv7 } from 'uuid';
+import { invalidArgument } from './validation.js';
+const UUID_BYTES = 16;
+const CURSOR_BYTES = UUID_BYTES * 2;
+const CURSOR_LENGTH = 43;
+export function generateRecordIdentity(segmentBytes) {
+    const recordBytes = Buffer.from(parseUuid(uuidv7()));
+    const actualSegmentBytes = segmentBytes === undefined
+        ? recordBytes
+        : Buffer.from(segmentBytes);
+    assertUuidV7(actualSegmentBytes, 'segment UUID');
+    const id = Buffer.concat([recordBytes, actualSegmentBytes]).toString('base64url');
+    const parsed = parseRecordId(id);
+    return {
+        ...parsed,
+        id,
+        createdAtMilliseconds: uuidV7Timestamp(recordBytes),
+    };
+}
+export function parseRecordId(value, name = 'recordId') {
+    if (typeof value !== 'string'
+        || value.length !== CURSOR_LENGTH
+        || !/^[A-Za-z0-9_-]+$/.test(value)) {
+        throw invalidArgument(`${name} must be a canonical ordered-record cursor`);
+    }
+    const bytes = Buffer.from(value, 'base64url');
+    if (bytes.length !== CURSOR_BYTES || bytes.toString('base64url') !== value) {
+        throw invalidArgument(`${name} must be a canonical ordered-record cursor`);
+    }
+    const recordBytes = bytes.subarray(0, UUID_BYTES);
+    const segmentBytes = bytes.subarray(UUID_BYTES);
+    assertUuidV7(recordBytes, `${name} record UUID`);
+    assertUuidV7(segmentBytes, `${name} segment UUID`);
+    return {
+        recordBytes,
+        segmentBytes,
+        recordHex: recordBytes.toString('hex'),
+        segmentHex: segmentBytes.toString('hex'),
+    };
+}
+export function compareRecordIds(left, right) {
+    const comparison = Buffer.compare(parseRecordId(left, 'left').recordBytes, parseRecordId(right, 'right').recordBytes);
+    return comparison < 0 ? -1 : comparison > 0 ? 1 : 0;
+}
+export function makeRecordId(recordBytes, segmentBytes) {
+    const record = Buffer.from(recordBytes);
+    const segment = Buffer.from(segmentBytes);
+    assertUuidV7(record, 'record UUID');
+    assertUuidV7(segment, 'segment UUID');
+    return Buffer.concat([record, segment]).toString('base64url');
+}
+export function uuidV7Timestamp(bytes) {
+    assertUuidV7(bytes, 'UUID');
+    let value = 0;
+    for (let index = 0; index < 6; index++) {
+        value = value * 256 + bytes[index];
+    }
+    return value;
+}
+export function invertUuidHex(bytes) {
+    assertUuidV7(bytes, 'segment UUID');
+    const inverted = Buffer.alloc(bytes.length);
+    for (let index = 0; index < bytes.length; index++) {
+        inverted[index] = 0xff ^ bytes[index];
+    }
+    return inverted.toString('hex');
+}
+export function segmentBytesFromHex(value) {
+    if (!/^[0-9a-f]{32}$/.test(value)) {
+        throw invalidArgument('segment ID must be lowercase UUID hex');
+    }
+    const bytes = Buffer.from(value, 'hex');
+    assertUuidV7(bytes, 'segment UUID');
+    return bytes;
+}
+function assertUuidV7(bytes, name) {
+    if (bytes.length !== UUID_BYTES
+        || (bytes[6] >>> 4) !== 7
+        || (bytes[8] & 0xc0) !== 0x80) {
+        throw invalidArgument(`${name} must be a UUIDv7`);
+    }
+}

package/dist/s3-object-store.d.ts

@@ -0,0 +1,8 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import type { SegmentObjectStore } from './types.js';
+export interface S3SegmentObjectStoreOptions {
+    readonly client: S3Client;
+    readonly bucket: string;
+    readonly keyPrefix?: string;
+}
+export declare function createS3SegmentObjectStore(options: S3SegmentObjectStoreOptions): SegmentObjectStore;

package/dist/s3-object-store.js

@@ -0,0 +1,51 @@
+import { GetObjectCommand, ListObjectsV2Command, NoSuchKey, PutObjectCommand, } from '@aws-sdk/client-s3';
+export function createS3SegmentObjectStore(options) {
+    const keyPrefix = normalizePrefix(options.keyPrefix ?? '');
+    return {
+        async list({ prefix, startAfter, limit }) {
+            const response = await options.client.send(new ListObjectsV2Command({
+                Bucket: options.bucket,
+                Prefix: `${keyPrefix}${prefix}`,
+                StartAfter: startAfter === undefined ? undefined : `${keyPrefix}${startAfter}`,
+                MaxKeys: limit,
+            }));
+            return (response.Contents ?? []).flatMap(object => {
+                if (object.Key === undefined || object.Size === undefined)
+                    return [];
+                return [{ key: object.Key.slice(keyPrefix.length), size: object.Size }];
+            });
+        },
+        async get(key) {
+            try {
+                const response = await options.client.send(new GetObjectCommand({
+                    Bucket: options.bucket,
+                    Key: `${keyPrefix}${key}`,
+                }));
+                if (response.Body === undefined)
+                    return new Uint8Array();
+                return await response.Body.transformToByteArray();
+            }
+            catch (error) {
+                if (error instanceof NoSuchKey
+                    || (typeof error === 'object' && error !== null && '$metadata' in error
+                        && error.$metadata?.httpStatusCode === 404)) {
+                    return null;
+                }
+                throw error;
+            }
+        },
+        async put({ key, data, checksumSha256 }) {
+            await options.client.send(new PutObjectCommand({
+                Bucket: options.bucket,
+                Key: `${keyPrefix}${key}`,
+                Body: data,
+                ChecksumSHA256: checksumSha256,
+            }));
+        },
+    };
+}
+function normalizePrefix(value) {
+    if (value === '')
+        return '';
+    return value.endsWith('/') ? value : `${value}/`;
+}

package/dist/segment-codec.d.ts

@@ -0,0 +1,18 @@
+import { type GeneratedRecordIdentity } from './record-id.js';
+import { type StoredRecord } from './types.js';
+export interface DecodedSegment {
+    readonly streamId: string;
+    readonly segmentHex: string;
+    readonly segmentBytes: Buffer;
+    readonly createdAtMilliseconds: number;
+    readonly headerLength: number;
+    readonly validLength: number;
+    readonly incompleteTail: boolean;
+    readonly records: readonly StoredRecord[];
+}
+export declare function encodeSegmentHeader(streamId: string, segmentBytes: Uint8Array, createdAtMilliseconds: number): Buffer;
+export declare function encodeRecordFrame(identity: GeneratedRecordIdentity, data: string): Buffer;
+export declare function decodeSegment(bytes: Uint8Array, expected?: {
+    readonly streamId?: string;
+    readonly segmentHex?: string;
+}): DecodedSegment;

package/dist/segment-codec.js

@@ -0,0 +1,172 @@
+import { TextDecoder } from 'node:util';
+import { crc32c } from './crc32c.js';
+import { makeRecordId, segmentBytesFromHex, uuidV7Timestamp, } from './record-id.js';
+import { MAX_DATA_BYTES, OrderedRecordStoreError, } from './types.js';
+const MAGIC = Buffer.from('ORSSEG01', 'ascii');
+const FIXED_HEADER_BYTES = 46;
+const MIN_RECORD_BODY_BYTES = 32;
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+export function encodeSegmentHeader(streamId, segmentBytes, createdAtMilliseconds) {
+    const stream = Buffer.from(streamId, 'utf8');
+    const totalLength = FIXED_HEADER_BYTES + stream.length;
+    const header = Buffer.alloc(totalLength);
+    MAGIC.copy(header, 0);
+    header.writeUInt32BE(totalLength, 8);
+    header.writeUInt16BE(1, 12);
+    header.writeUInt8(0, 14);
+    header.writeUInt8(0, 15);
+    Buffer.from(segmentBytes).copy(header, 16);
+    header.writeBigUInt64BE(BigInt(createdAtMilliseconds), 32);
+    header.writeUInt16BE(stream.length, 40);
+    stream.copy(header, 42);
+    header.writeUInt32BE(crc32c(header.subarray(8, totalLength - 4)), totalLength - 4);
+    return header;
+}
+export function encodeRecordFrame(identity, data) {
+    const payload = Buffer.from(data, 'utf8');
+    const bodyLength = MIN_RECORD_BODY_BYTES + payload.length;
+    const frame = Buffer.alloc(bodyLength + 8);
+    frame.writeUInt32BE(bodyLength, 0);
+    identity.recordBytes.copy(frame, 4);
+    frame.writeBigUInt64BE(BigInt(identity.createdAtMilliseconds), 20);
+    frame.writeUInt32BE(payload.length, 28);
+    payload.copy(frame, 32);
+    const crcOffset = 32 + payload.length;
+    frame.writeUInt32BE(crc32c(frame.subarray(4, crcOffset)), crcOffset);
+    frame.writeUInt32BE(bodyLength, crcOffset + 4);
+    return frame;
+}
+export function decodeSegment(bytes, expected) {
+    const buffer = Buffer.from(bytes);
+    if (buffer.length < FIXED_HEADER_BYTES || !buffer.subarray(0, 8).equals(MAGIC)) {
+        throw corrupt('invalid or incomplete segment header');
+    }
+    const headerLength = buffer.readUInt32BE(8);
+    const streamLength = buffer.readUInt16BE(40);
+    if (headerLength !== FIXED_HEADER_BYTES + streamLength
+        || headerLength > buffer.length
+        || buffer.readUInt16BE(12) !== 1
+        || buffer.readUInt8(14) !== 0
+        || buffer.readUInt8(15) !== 0) {
+        throw corrupt('unsupported or malformed segment header');
+    }
+    if (buffer.readUInt32BE(headerLength - 4)
+        !== crc32c(buffer.subarray(8, headerLength - 4))) {
+        throw corrupt('segment header checksum mismatch');
+    }
+    const segmentBytes = Buffer.from(buffer.subarray(16, 32));
+    const segmentHex = segmentBytes.toString('hex');
+    try {
+        segmentBytesFromHex(segmentHex);
+    }
+    catch {
+        throw corrupt('segment header contains an invalid UUIDv7');
+    }
+    const createdAtMilliseconds = numberFromUInt64(buffer.readBigUInt64BE(32), 'segment timestamp');
+    if (createdAtMilliseconds !== uuidV7Timestamp(segmentBytes)) {
+        throw corrupt('segment UUID and timestamp disagree');
+    }
+    let streamId;
+    try {
+        streamId = utf8.decode(buffer.subarray(42, 42 + streamLength));
+    }
+    catch {
+        throw corrupt('segment stream ID is not valid UTF-8');
+    }
+    if (expected?.streamId !== undefined && expected.streamId !== streamId) {
+        throw corrupt('segment stream ID does not match its requested stream');
+    }
+    if (expected?.segmentHex !== undefined && expected.segmentHex !== segmentHex) {
+        throw corrupt('segment ID does not match its path or object key');
+    }
+    const records = [];
+    let offset = headerLength;
+    let incompleteTail = false;
+    while (offset < buffer.length) {
+        if (buffer.length - offset < 4) {
+            incompleteTail = true;
+            break;
+        }
+        const bodyLength = buffer.readUInt32BE(offset);
+        if (bodyLength < MIN_RECORD_BODY_BYTES || bodyLength > MIN_RECORD_BODY_BYTES + MAX_DATA_BYTES) {
+            throw corrupt(`invalid record length at byte ${offset}`);
+        }
+        const frameLength = bodyLength + 8;
+        if (offset + frameLength > buffer.length) {
+            incompleteTail = true;
+            break;
+        }
+        const record = decodeFrame(buffer.subarray(offset, offset + frameLength), streamId, segmentBytes);
+        if (records.length > 0 && Buffer.compare(Buffer.from(records.at(-1).id, 'base64url').subarray(0, 16), Buffer.from(record.id, 'base64url').subarray(0, 16)) >= 0) {
+            throw corrupt('record IDs are not strictly increasing');
+        }
+        records.push(record);
+        offset += frameLength;
+    }
+    if (records.length === 0) {
+        throw corrupt('segment contains no complete records');
+    }
+    const firstRecordBytes = Buffer.from(records[0].id, 'base64url').subarray(0, 16);
+    if (!firstRecordBytes.equals(segmentBytes)) {
+        throw corrupt('first record UUID is not the segment UUID');
+    }
+    return {
+        streamId,
+        segmentHex,
+        segmentBytes,
+        createdAtMilliseconds,
+        headerLength,
+        validLength: offset,
+        incompleteTail,
+        records,
+    };
+}
+function decodeFrame(frame, streamId, segmentBytes) {
+    const bodyLength = frame.readUInt32BE(0);
+    const payloadLength = frame.readUInt32BE(28);
+    if (bodyLength !== MIN_RECORD_BODY_BYTES + payloadLength
+        || frame.length !== bodyLength + 8
+        || frame.readUInt32BE(frame.length - 4) !== bodyLength) {
+        throw corrupt('record framing is inconsistent');
+    }
+    const crcOffset = 32 + payloadLength;
+    if (frame.readUInt32BE(crcOffset) !== crc32c(frame.subarray(4, crcOffset))) {
+        throw corrupt('record checksum mismatch');
+    }
+    const recordBytes = frame.subarray(4, 20);
+    let timestamp;
+    try {
+        timestamp = numberFromUInt64(frame.readBigUInt64BE(20), 'record timestamp');
+        if (timestamp !== uuidV7Timestamp(recordBytes)) {
+            throw corrupt('record UUID and timestamp disagree');
+        }
+    }
+    catch (error) {
+        if (error instanceof OrderedRecordStoreError)
+            throw error;
+        throw corrupt('record contains an invalid UUIDv7');
+    }
+    let data;
+    try {
+        data = utf8.decode(frame.subarray(32, crcOffset));
+    }
+    catch {
+        throw corrupt('record payload is not valid UTF-8');
+    }
+    return {
+        id: makeRecordId(recordBytes, segmentBytes),
+        streamId,
+        data,
+        createdAt: new Date(timestamp).toISOString(),
+    };
+}
+function numberFromUInt64(value, name) {
+    const number = Number(value);
+    if (!Number.isSafeInteger(number)) {
+        throw corrupt(`${name} is outside JavaScript's safe integer range`);
+    }
+    return number;
+}
+function corrupt(message) {
+    return new OrderedRecordStoreError('CORRUPT_DATA', message);
+}

package/dist/segmented-store.d.ts

@@ -0,0 +1,2 @@
+import { type OrderedRecordStore, type SegmentedOrderedRecordStoreOptions } from './types.js';
+export declare function openSegmentedOrderedRecordStore(options: SegmentedOrderedRecordStoreOptions): Promise<OrderedRecordStore>;