@struktoai/mirage-core/dist/utils/ids.d.ts

A Unified Virtual Filesystem For AI Agents

import { type Clock } from './clock.ts';
/**
 * Mint an RFC 9562 UUIDv7 in canonical lowercase hyphenated form.
 *
 * The first 48 bits are a unix-millisecond timestamp, so ids sort by
 * creation time and stay index-friendly as database primary keys; the
 * next 12 bits order ids minted inside one millisecond, and the last 62
 * bits are random. Stamped by the process's own `SystemIdSource`.
 */
export declare function uuid7(): string;
/** Mint a fresh workspace id (UUIDv7). */
export declare function newWorkspaceId(): string;
/** Mint a fresh session id (UUIDv7). */
export declare function newSessionId(): string;
/** Where a workspace's generated ids and random draws come from. */
export interface IdSource {
    /** A fresh RFC 9562 UUIDv7 in canonical lowercase form. */
    uuid7(): string;
    /** A uniform integer in `[0, 2**32)`. */
    randomU32(): number;
    /**
     * At least `count` of the words `randomU32` would answer next, each as four
     * little-endian bytes. A source that replays answers exactly `count`, so its
     * next word follows the last one taken.
     */
    randomWords(count: number): Uint8Array;
}
/**
 * Platform randomness used when no source is supplied. A UUIDv7 is stamped
 * from `clock` and ordered inside one millisecond by a counter, as
 * `SeededIdSource` orders its ids. Every source on the system clock shares the
 * process's floor, so ids minted anywhere in the process sort by when they
 * were made. A source on another clock keeps a floor of its own, so a manual
 * clock never shares one with the system clock.
 */
export declare class SystemIdSource implements IdSource {
    private readonly clock;
    private readonly floor;
    /** @param clock the clock ids are stamped from; omitted means the system clock. */
    constructor(clock?: Clock);
    /** A fresh UUIDv7 stamped from the source's clock. */
    uuid7(): string;
    /** A uniform 32-bit integer from the platform generator. */
    randomU32(): number;
    /**
     * Twice `count` platform words, and at least `WORDS_AHEAD`, each as four
     * little-endian bytes: a caller drawing below a limit, which redraws up to
     * half its words, seldom has to ask again.
     */
    randomWords(count: number): Uint8Array;
}
/**
 * Ids and draws replayed exactly from a seed.
 *
 * Draws come from xoshiro128** (Blackman and Vigna) seeded through
 * SplitMix64, so one seed yields one sequence on every host and in both
 * languages. A UUIDv7 is stamped from `clock`, ordered inside one
 * millisecond by a counter, and borrows the next millisecond rather than
 * waiting when that counter runs out.
 */
export declare class SeededIdSource implements IdSource {
    readonly seed: number;
    private readonly clock;
    private readonly state;
    private lastMs;
    private counter;
    /**
     * @param seed the sequence to replay, from 0 to `2**53 - 1`.
     * @param clock the clock ids are stamped from; omitted means a
     *   `ManualClock` at zero, so ids depend on the seed alone.
     */
    constructor(seed: number, clock?: Clock);
    /** The next 32-bit draw of the seeded sequence. */
    randomU32(): number;
    /** The next `count` draws of the seeded sequence, each as four little-endian bytes. */
    randomWords(count: number): Uint8Array;
    /** The next UUIDv7 of the seeded sequence, stamped from the clock. */
    uuid7(): string;
}
/**
 * A uniform bigint in `[0, limit)` drawn from `ids`.
 *
 * Whole 32-bit words are drawn, most significant first, the top bits of the
 * limit's own bit length kept, and a value past the limit drawn again, which
 * discards at most half the draws. `random_below` in ids.py is the twin and
 * draws the same words for the same limit.
 */
export declare function randomBelowBig(ids: IdSource, limit: bigint): bigint;
/**
 * A uniform integer in `[0, limit)` drawn from `ids`, as `randomBelowBig`
 * draws it; a limit within one word skips the bigint arithmetic.
 */
export declare function randomBelow(ids: IdSource, limit: number): number;
//# sourceMappingURL=ids.d.ts.map