@mindpeeker/entropy 0.1.0

package/dist/internal/http.js

@@ -0,0 +1,76 @@
+import { EntropyError } from '../errors.js';
+function defaultErrorFor(status, body, response, provider) {
+    if (status === 429) {
+        const retryAfter = Number.parseFloat(response.headers.get('retry-after') ?? '');
+        return new EntropyError('rate_limited', `HTTP 429: ${body.slice(0, 200)}`, {
+            provider,
+            retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined,
+        });
+    }
+    if (status === 401 || status === 403) {
+        return new EntropyError('auth', `HTTP ${status}: ${body.slice(0, 200)}`, { provider });
+    }
+    return new EntropyError('network', `HTTP ${status}: ${body.slice(0, 200)}`, { provider });
+}
+function isAbort(error, signal) {
+    return signal?.aborted === true || (error instanceof DOMException && error.name === 'AbortError');
+}
+/** Shared transport + error taxonomy: resolve to an OK Response or throw EntropyError. */
+async function fetchOk(url, opts, accept) {
+    const { provider, signal } = opts;
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const headers = { accept, ...opts.headers };
+    const init = { method: opts.method ?? 'GET', headers, signal };
+    if (opts.body !== undefined) {
+        headers['content-type'] = 'application/json';
+        init.body = JSON.stringify(opts.body);
+    }
+    let response;
+    try {
+        response = await fetchImpl(url, init);
+    }
+    catch (error) {
+        if (isAbort(error, signal))
+            throw error;
+        throw new EntropyError('network', `request to ${url} failed: ${error.message}`, {
+            provider,
+            cause: error,
+        });
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw (opts.onErrorResponse?.(response.status, body) ??
+            defaultErrorFor(response.status, body, response, provider));
+    }
+    return response;
+}
+/**
+ * fetch + JSON parse with the library's uniform error taxonomy. Abort/timeout
+ * reasons pass through unwrapped so `defineProvider` can classify them.
+ */
+export async function fetchJson(url, opts) {
+    const response = await fetchOk(url, opts, 'application/json');
+    try {
+        return (await response.json());
+    }
+    catch (error) {
+        throw new EntropyError('bad_response', `invalid JSON from ${url}`, {
+            provider: opts.provider,
+            cause: error,
+        });
+    }
+}
+/** fetch returning the raw text body (e.g. Bitcoin tip-hash endpoints). */
+export async function fetchText(url, opts) {
+    const response = await fetchOk(url, opts, 'text/plain');
+    try {
+        return await response.text();
+    }
+    catch (error) {
+        throw new EntropyError('bad_response', `unreadable body from ${url}`, {
+            provider: opts.provider,
+            cause: error,
+        });
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/internal/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/internal/http.ts"],"names":[],"mappings":"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"}

package/dist/internal/nist-pulse.d.ts

@@ -0,0 +1,31 @@
+import type { EntropyProvider, EntropySourceInfo } from '../types.js';
+/** Caller-facing options every NIST-2.0-format beacon provider exposes. */
+export interface NistFamilyOptions {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    /** Stream poll cadence. Default: the beacon's pulse period. */
+    pollIntervalMs?: number;
+}
+export interface NistFamilySpec {
+    info: EntropySourceInfo;
+    defaultBaseUrl: string;
+    /**
+     * Appended to baseUrl for the newest pulse — may carry a query string
+     * (UChile) or rely on an HTTP redirect that fetch follows (NQSN's 303).
+     */
+    latestPath: string;
+    /** Historical pulse path. Default `/chain/{chain}/pulse/{i}`. */
+    pulsePath?: (chainIndex: number, pulseIndex: number) => string;
+    /** outputValue size in bytes. Default 64 (512-bit). */
+    pulseBytes?: number;
+    /** Pulse period, doubling as the default stream poll cadence. */
+    defaultPollIntervalMs: number;
+}
+/**
+ * Shared machinery for the NIST IR 8213 beacon family (NIST, NQSN Singapore,
+ * Random UChile, Inmetro Brazil): fetch latest pulse (wrapped or flat JSON),
+ * walk the chain backwards for larger requests, poll-dedupe streaming.
+ * All of these emit PUBLIC randomness — never use it as secret key material.
+ */
+export declare function nistPulseBeacon(spec: NistFamilySpec, opts?: NistFamilyOptions): EntropyProvider;
+//# sourceMappingURL=nist-pulse.d.ts.map

package/dist/internal/nist-pulse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nist-pulse.d.ts","sourceRoot":"","sources":["../../src/internal/nist-pulse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAOrE,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,iBAAiB,CAAA;IACvB,cAAc,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9D,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,qBAAqB,EAAE,MAAM,CAAA;CAC9B;AAQD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,iBAAsB,GAC3B,eAAe,CAiEjB"}

package/dist/internal/nist-pulse.js

@@ -0,0 +1,62 @@
+import { EntropyError } from '../errors.js';
+import { concatBytes } from './bytes.js';
+import { fetchJson } from './http.js';
+import { defineProvider } from './provider.js';
+import { beaconStream } from './stream.js';
+import { bytesFromHexField } from './validate.js';
+/**
+ * Shared machinery for the NIST IR 8213 beacon family (NIST, NQSN Singapore,
+ * Random UChile, Inmetro Brazil): fetch latest pulse (wrapped or flat JSON),
+ * walk the chain backwards for larger requests, poll-dedupe streaming.
+ * All of these emit PUBLIC randomness — never use it as secret key material.
+ */
+export function nistPulseBeacon(spec, opts = {}) {
+    const { info, pulseBytes = 64 } = spec;
+    const pulsePath = spec.pulsePath ?? ((chain, i) => `/chain/${chain}/pulse/${i}`);
+    const { baseUrl = spec.defaultBaseUrl, pollIntervalMs = spec.defaultPollIntervalMs, fetch: fetchImpl, } = opts;
+    async function fetchPulse(path, signal) {
+        const res = await fetchJson(`${baseUrl}${path}`, {
+            provider: info.name,
+            signal,
+            fetchImpl,
+        });
+        const pulse = res?.pulse ?? res;
+        const { chainIndex, pulseIndex } = pulse ?? {};
+        if (!Number.isInteger(chainIndex) || !Number.isInteger(pulseIndex)) {
+            throw new EntropyError('bad_response', 'malformed beacon pulse', { provider: info.name });
+        }
+        return {
+            chainIndex: chainIndex,
+            pulseIndex: pulseIndex,
+            bytes: bytesFromHexField(pulse?.outputValue, pulseBytes, info.name),
+        };
+    }
+    return defineProvider({
+        ...info,
+        defaultChunkBytes: pulseBytes,
+        async getBytes(length, reqOpts) {
+            const pulsesNeeded = Math.ceil(length / pulseBytes);
+            const latest = await fetchPulse(spec.latestPath, reqOpts?.signal);
+            const chunks = [latest.bytes];
+            // Past pulses are equally public — walk the chain backwards.
+            for (let i = 1; i < pulsesNeeded; i++) {
+                const pulseIndex = latest.pulseIndex - i;
+                if (pulseIndex < 1) {
+                    throw new EntropyError('insufficient_entropy', 'beacon chain too short for request', {
+                        provider: info.name,
+                    });
+                }
+                const prior = await fetchPulse(pulsePath(latest.chainIndex, pulseIndex), reqOpts?.signal);
+                chunks.push(prior.bytes);
+            }
+            return { bytes: concatBytes(chunks).slice(0, length), sources: [info] };
+        },
+        stream(streamOpts = {}) {
+            return beaconStream(async (signal) => {
+                const pulse = await fetchPulse(spec.latestPath, signal);
+                return { id: pulse.pulseIndex, bytes: pulse.bytes };
+            }, pollIntervalMs, pulseBytes, info.name, streamOpts);
+        },
+    });
+}
+//# sourceMappingURL=nist-pulse.js.map

package/dist/internal/nist-pulse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nist-pulse.js","sourceRoot":"","sources":["../../src/internal/nist-pulse.ts"],"names":[],"mappings":"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"}

package/dist/internal/provider.d.ts

@@ -0,0 +1,19 @@
+import type { EntropyProvider, EntropyRequestOptions, EntropyResult, EntropySourceInfo, EntropyStreamOptions } from '../types.js';
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export interface ProviderSpec extends EntropySourceInfo {
+    getBytes(length: number, opts?: EntropyRequestOptions): Promise<EntropyResult>;
+    stream?(opts?: EntropyStreamOptions): AsyncIterable<Uint8Array>;
+    /** Natural chunk size for the default poll-based stream. */
+    defaultChunkBytes?: number;
+    /** Whole-call timeout when the caller passes none (composites need more room). */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Wraps a provider implementation with the cross-cutting contract every
+ * provider must honor: length validation (`invalid_request`), abort handling
+ * (`aborted`), a whole-call timeout budget (`timeout`), and a default
+ * poll-based `stream()`. The impl receives a composite AbortSignal that fires
+ * on either caller abort or timeout expiry.
+ */
+export declare function defineProvider(spec: ProviderSpec): EntropyProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/internal/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/internal/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AAGpB,eAAO,MAAM,kBAAkB,QAAS,CAAA;AAExC,MAAM,WAAW,YAAa,SAAQ,iBAAiB;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC9E,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAA;IAC/D,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,CAyDlE"}

package/dist/internal/provider.js

@@ -0,0 +1,62 @@
+import { EntropyError } from '../errors.js';
+import { pollStream } from './stream.js';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * Wraps a provider implementation with the cross-cutting contract every
+ * provider must honor: length validation (`invalid_request`), abort handling
+ * (`aborted`), a whole-call timeout budget (`timeout`), and a default
+ * poll-based `stream()`. The impl receives a composite AbortSignal that fires
+ * on either caller abort or timeout expiry.
+ */
+export function defineProvider(spec) {
+    const { name, kind, privacy, defaultChunkBytes } = spec;
+    const provider = {
+        name,
+        kind,
+        privacy,
+        async getBytes(length, opts = {}) {
+            if (!Number.isInteger(length) || length < 1) {
+                throw new EntropyError('invalid_request', `requested length must be a positive integer, got ${length}`, {
+                    provider: name,
+                });
+            }
+            if (opts.signal?.aborted) {
+                throw new EntropyError('aborted', 'request aborted before start', { provider: name });
+            }
+            const timeoutMs = opts.timeoutMs ?? spec.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+            const timeoutSignal = AbortSignal.timeout(timeoutMs);
+            const signal = opts.signal ? AbortSignal.any([opts.signal, timeoutSignal]) : timeoutSignal;
+            try {
+                return await spec.getBytes(length, { ...opts, signal, timeoutMs });
+            }
+            catch (error) {
+                if (error instanceof EntropyError) {
+                    // A nested provider saw our composite signal abort and reported
+                    // 'aborted' — if that abort was our own timeout, reclassify.
+                    if (error.code === 'aborted' && !opts.signal?.aborted && timeoutSignal.aborted) {
+                        throw new EntropyError('timeout', `request exceeded ${timeoutMs}ms`, {
+                            provider: name,
+                            cause: error,
+                        });
+                    }
+                    throw error;
+                }
+                if (opts.signal?.aborted) {
+                    throw new EntropyError('aborted', 'request aborted', { provider: name, cause: error });
+                }
+                if (timeoutSignal.aborted) {
+                    throw new EntropyError('timeout', `request exceeded ${timeoutMs}ms`, {
+                        provider: name,
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        },
+        stream(opts = {}) {
+            return spec.stream ? spec.stream(opts) : pollStream(provider, opts, defaultChunkBytes);
+        },
+    };
+    return Object.freeze(provider);
+}
+//# sourceMappingURL=provider.js.map

package/dist/internal/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/internal/provider.ts"],"names":[],"mappings":"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"}

package/dist/internal/rate-limit.d.ts

@@ -0,0 +1,15 @@
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Client-side throttle: guarantees at least `intervalMs` between the moments
+ * consecutive `wait()` calls resolve. Callers reserve their slot at call time,
+ * so concurrent waiters are served FIFO, one interval apart. `defer(ms)`
+ * pushes the next free slot into the future — used for server-directed
+ * backoff like RANDOM.ORG's `advisoryDelay`.
+ */
+export declare class MinIntervalGate {
+    #private;
+    constructor(intervalMs: number);
+    wait(signal?: AbortSignal): Promise<void>;
+    defer(ms: number): void;
+}
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/internal/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/internal/rate-limit.ts"],"names":[],"mappings":"AAMA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAYrE;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;;gBAId,UAAU,EAAE,MAAM;IAIxB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAGxB"}

package/dist/internal/rate-limit.js

@@ -0,0 +1,47 @@
+function abortError(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    return new DOMException('The operation was aborted.', 'AbortError');
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal ? abortError(signal) : new DOMException('aborted', 'AbortError'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/**
+ * Client-side throttle: guarantees at least `intervalMs` between the moments
+ * consecutive `wait()` calls resolve. Callers reserve their slot at call time,
+ * so concurrent waiters are served FIFO, one interval apart. `defer(ms)`
+ * pushes the next free slot into the future — used for server-directed
+ * backoff like RANDOM.ORG's `advisoryDelay`.
+ */
+export class MinIntervalGate {
+    #nextAt = 0;
+    #intervalMs;
+    constructor(intervalMs) {
+        this.#intervalMs = intervalMs;
+    }
+    async wait(signal) {
+        if (signal?.aborted)
+            throw abortError(signal);
+        const now = Date.now();
+        const startAt = Math.max(now, this.#nextAt);
+        this.#nextAt = startAt + this.#intervalMs;
+        const delay = startAt - now;
+        if (delay > 0)
+            await sleep(delay, signal);
+    }
+    defer(ms) {
+        this.#nextAt = Math.max(this.#nextAt, Date.now() + ms);
+    }
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/internal/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/internal/rate-limit.ts"],"names":[],"mappings":"AAAA,SAAS,UAAU,CAAC,MAAmB;IACrC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;IAC5B,IAAI,MAAM,YAAY,KAAK;QAAE,OAAO,MAAM,CAAA;IAC1C,OAAO,IAAI,YAAY,CAAC,4BAA4B,EAAE,YAAY,CAAC,CAAA;AACrE,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC7C,OAAO,EAAE,CAAA;QACX,CAAC,EAAE,EAAE,CAAC,CAAA;QACN,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,YAAY,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAA;QACjF,CAAC,CAAA;QACD,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC5D,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IAC1B,OAAO,GAAG,CAAC,CAAA;IACF,WAAW,CAAQ;IAE5B,YAAY,UAAkB;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAoB;QAC7B,IAAI,MAAM,EAAE,OAAO;YAAE,MAAM,UAAU,CAAC,MAAM,CAAC,CAAA;QAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC,WAAW,CAAA;QACzC,MAAM,KAAK,GAAG,OAAO,GAAG,GAAG,CAAA;QAC3B,IAAI,KAAK,GAAG,CAAC;YAAE,MAAM,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;IAC3C,CAAC;IAED,KAAK,CAAC,EAAU;QACd,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAA;IACxD,CAAC;CACF"}

package/dist/internal/sampled.d.ts

@@ -0,0 +1,25 @@
+import type { EntropyProvider, EntropySourceInfo } from '../types.js';
+import { type ConditioningOptions } from './condition.js';
+export interface SampledSpec extends EntropySourceInfo {
+    /**
+     * Open a raw-sample session. The returned iterable must stop sampling and
+     * release the underlying hardware when the iterator is closed (return())
+     * or the signal aborts — put cleanup in the generator's finally block.
+     */
+    open(signal?: AbortSignal): AsyncIterable<Uint8Array>;
+    /** Conservative assessed min-entropy in bits per raw sample byte. */
+    defaultMinEntropyPerSample: number;
+    defaultSafetyFactor: number;
+    /** Stricter H for health-testing than for crediting (see ConditionerConfig). */
+    defaultHealthMinEntropyPerSample?: number;
+    defaultTimeoutMs?: number;
+    defaultChunkBytes?: number;
+}
+/**
+ * The convergence point for all local physical-noise providers: wires a raw
+ * sample session through health tests + conditioning (or raw passthrough)
+ * into the standard EntropyProvider contract. getBytes opens one session per
+ * call; stream() holds one lazy session for the iterator's lifetime.
+ */
+export declare function sampledProvider(spec: SampledSpec, opts?: ConditioningOptions): EntropyProvider;
+//# sourceMappingURL=sampled.d.ts.map

package/dist/internal/sampled.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampled.d.ts","sourceRoot":"","sources":["../../src/internal/sampled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAA;AAE3F,OAAO,EAEL,KAAK,mBAAmB,EAGzB,MAAM,gBAAgB,CAAA;AAIvB,MAAM,WAAW,WAAY,SAAQ,iBAAiB;IACpD;;;;OAIG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,CAAA;IACrD,qEAAqE;IACrE,0BAA0B,EAAE,MAAM,CAAA;IAClC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,gFAAgF;IAChF,gCAAgC,CAAC,EAAE,MAAM,CAAA;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,IAAI,GAAE,mBAAwB,GAC7B,eAAe,CAuCjB"}

package/dist/internal/sampled.js

@@ -0,0 +1,49 @@
+import { iterateBytes } from './byte-source.js';
+import { collectBytes, condition, } from './condition.js';
+import { defineProvider } from './provider.js';
+import { rechunk } from './stream.js';
+const CONDITIONED_BLOCK_BYTES = 32;
+/**
+ * The convergence point for all local physical-noise providers: wires a raw
+ * sample session through health tests + conditioning (or raw passthrough)
+ * into the standard EntropyProvider contract. getBytes opens one session per
+ * call; stream() holds one lazy session for the iterator's lifetime.
+ */
+export function sampledProvider(spec, opts = {}) {
+    const mode = opts.conditioning ?? 'conditioned';
+    // Raw mode is visible in the name — and therefore in attribution — so a
+    // result can always be traced to whitened vs unprocessed physical bits.
+    const name = mode === 'raw' ? `${spec.name}(raw)` : spec.name;
+    const info = Object.freeze({ name, kind: spec.kind, privacy: spec.privacy });
+    const config = {
+        provider: name,
+        minEntropyPerSample: opts.minEntropyPerSample ?? spec.defaultMinEntropyPerSample,
+        safetyFactor: opts.safetyFactor ?? spec.defaultSafetyFactor,
+        healthMinEntropyPerSample: spec.defaultHealthMinEntropyPerSample,
+        mode,
+    };
+    return defineProvider({
+        ...info,
+        defaultTimeoutMs: spec.defaultTimeoutMs,
+        defaultChunkBytes: spec.defaultChunkBytes ?? CONDITIONED_BLOCK_BYTES,
+        async getBytes(length, reqOpts) {
+            // iterateBytes races every pull against the composite signal so even a
+            // non-cooperative source honors abort/timeout; collectBytes returns
+            // early once satisfied and its close propagates through condition()
+            // into the source's finally block.
+            const raw = iterateBytes(spec.open(reqOpts?.signal), reqOpts?.signal);
+            const stream = condition(raw, config);
+            return { bytes: await collectBytes(stream, length, name), sources: [info] };
+        },
+        stream(streamOpts = {}) {
+            const chunkBytes = streamOpts.chunkBytes ?? spec.defaultChunkBytes ?? CONDITIONED_BLOCK_BYTES;
+            async function* session() {
+                yield* condition(iterateBytes(spec.open(streamOpts.signal), streamOpts.signal), config);
+            }
+            const natural = mode === 'conditioned' ? CONDITIONED_BLOCK_BYTES : -1;
+            const inner = session();
+            return chunkBytes === natural ? inner : rechunk(inner, chunkBytes);
+        },
+    });
+}
+//# sourceMappingURL=sampled.js.map

package/dist/internal/sampled.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampled.js","sourceRoot":"","sources":["../../src/internal/sampled.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC/C,OAAO,EAGL,YAAY,EACZ,SAAS,GACV,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAkBrC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AAElC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAiB,EACjB,OAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,IAAI,aAAa,CAAA;IAC/C,wEAAwE;IACxE,wEAAwE;IACxE,MAAM,IAAI,GAAG,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAA;IAC7D,MAAM,IAAI,GAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IAC/F,MAAM,MAAM,GAAsB;QAChC,QAAQ,EAAE,IAAI;QACd,mBAAmB,EAAE,IAAI,CAAC,mBAAmB,IAAI,IAAI,CAAC,0BAA0B;QAChF,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,mBAAmB;QAC3D,yBAAyB,EAAE,IAAI,CAAC,gCAAgC;QAChE,IAAI;KACL,CAAA;IAED,OAAO,cAAc,CAAC;QACpB,GAAG,IAAI;QACP,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,IAAI,uBAAuB;QAEpE,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO;YAC5B,uEAAuE;YACvE,oEAAoE;YACpE,oEAAoE;YACpE,mCAAmC;YACnC,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;YACrE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;YACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAA;QAC7E,CAAC;QAED,MAAM,CAAC,aAAmC,EAAE;YAC1C,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,IAAI,IAAI,CAAC,iBAAiB,IAAI,uBAAuB,CAAA;YAC7F,KAAK,SAAS,CAAC,CAAC,OAAO;gBACrB,KAAK,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;YACzF,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;YACrE,MAAM,KAAK,GAAG,OAAO,EAAE,CAAA;YACvB,OAAO,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QACpE,CAAC;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/internal/stream.d.ts

@@ -0,0 +1,29 @@
+import type { EntropyRequestOptions, EntropyResult, EntropyStreamOptions } from '../types.js';
+export declare const DEFAULT_CHUNK_BYTES = 32;
+interface ByteSource {
+    getBytes(length: number, opts?: EntropyRequestOptions): Promise<EntropyResult>;
+}
+/**
+ * Default stream implementation: one `getBytes` call per pull. Lazy (no I/O
+ * before the first `next()`), backpressured by construction, and it inherits
+ * whatever rate limiting the underlying `getBytes` applies.
+ */
+export declare function pollStream(source: ByteSource, opts?: EntropyStreamOptions, defaultChunkBytes?: number): AsyncIterable<Uint8Array>;
+/**
+ * Re-slice an inner stream into fixed-size chunks. When the source ends, any
+ * buffered tail is flushed as a final (short) chunk rather than discarded.
+ */
+export declare function rechunk(source: AsyncIterable<Uint8Array>, size: number): AsyncGenerator<Uint8Array>;
+export interface BeaconPoll {
+    /** Monotone identifier of the round/pulse, used for deduplication. */
+    id: number;
+    bytes: Uint8Array;
+}
+/**
+ * Round-aware beacon stream: polls `fetchLatest` on a fixed cadence and
+ * yields the payload only when the round/pulse id advances. Public beacons
+ * emit a small fixed payload per round, so `chunkBytes` is served via rechunk.
+ */
+export declare function beaconStream(fetchLatest: (signal?: AbortSignal) => Promise<BeaconPoll>, pollIntervalMs: number, naturalChunkBytes: number, provider: string, opts?: EntropyStreamOptions): AsyncIterable<Uint8Array>;
+export {};
+//# sourceMappingURL=stream.d.ts.map

package/dist/internal/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/internal/stream.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAI7F,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,UAAU,UAAU;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC/E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,oBAAyB,EAC/B,iBAAiB,GAAE,MAA4B,GAC9C,aAAa,CAAC,UAAU,CAAC,CAW3B;AAED;;;GAGG;AACH,wBAAuB,OAAO,CAC5B,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,IAAI,EAAE,MAAM,GACX,cAAc,CAAC,UAAU,CAAC,CAiB5B;AAED,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,UAAU,CAAA;CAClB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,EAC1D,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,oBAAyB,GAC9B,aAAa,CAAC,UAAU,CAAC,CA0B3B"}

package/dist/internal/stream.js

@@ -0,0 +1,78 @@
+import { EntropyError } from '../errors.js';
+import { concatBytes } from './bytes.js';
+import { sleep } from './rate-limit.js';
+export const DEFAULT_CHUNK_BYTES = 32;
+/**
+ * Default stream implementation: one `getBytes` call per pull. Lazy (no I/O
+ * before the first `next()`), backpressured by construction, and it inherits
+ * whatever rate limiting the underlying `getBytes` applies.
+ */
+export function pollStream(source, opts = {}, defaultChunkBytes = DEFAULT_CHUNK_BYTES) {
+    const chunkBytes = opts.chunkBytes ?? defaultChunkBytes;
+    const requestOpts = { signal: opts.signal, timeoutMs: opts.timeoutMs };
+    return {
+        async *[Symbol.asyncIterator]() {
+            while (true) {
+                const { bytes } = await source.getBytes(chunkBytes, requestOpts);
+                yield bytes;
+            }
+        },
+    };
+}
+/**
+ * Re-slice an inner stream into fixed-size chunks. When the source ends, any
+ * buffered tail is flushed as a final (short) chunk rather than discarded.
+ */
+export async function* rechunk(source, size) {
+    let buffer = [];
+    let buffered = 0;
+    for await (const chunk of source) {
+        buffer.push(chunk);
+        buffered += chunk.length;
+        if (buffered >= size) {
+            let all = concatBytes(buffer);
+            while (all.length >= size) {
+                yield all.slice(0, size);
+                all = all.slice(size);
+            }
+            buffer = all.length > 0 ? [all] : [];
+            buffered = all.length;
+        }
+    }
+    if (buffered > 0)
+        yield concatBytes(buffer);
+}
+/**
+ * Round-aware beacon stream: polls `fetchLatest` on a fixed cadence and
+ * yields the payload only when the round/pulse id advances. Public beacons
+ * emit a small fixed payload per round, so `chunkBytes` is served via rechunk.
+ */
+export function beaconStream(fetchLatest, pollIntervalMs, naturalChunkBytes, provider, opts = {}) {
+    async function* rounds() {
+        let lastId = Number.NEGATIVE_INFINITY;
+        try {
+            while (true) {
+                const timeoutMs = opts.timeoutMs ?? 10_000;
+                const timeoutSignal = AbortSignal.timeout(timeoutMs);
+                const signal = opts.signal ? AbortSignal.any([opts.signal, timeoutSignal]) : timeoutSignal;
+                const { id, bytes } = await fetchLatest(signal);
+                if (id > lastId) {
+                    lastId = id;
+                    yield bytes;
+                }
+                await sleep(pollIntervalMs, opts.signal);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof EntropyError) && opts.signal?.aborted) {
+                throw new EntropyError('aborted', 'stream aborted', { provider, cause: error });
+            }
+            throw error;
+        }
+    }
+    const inner = rounds();
+    return opts.chunkBytes && opts.chunkBytes !== naturalChunkBytes
+        ? rechunk(inner, opts.chunkBytes)
+        : inner;
+}
+//# sourceMappingURL=stream.js.map

package/dist/internal/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/internal/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAEvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAA;AAMrC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,MAAkB,EAClB,OAA6B,EAAE,EAC/B,oBAA4B,mBAAmB;IAE/C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,CAAA;IACvD,MAAM,WAAW,GAA0B,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAA;IAC7F,OAAO;QACL,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;YAC3B,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,CAAA;gBAChE,MAAM,KAAK,CAAA;YACb,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,CAC5B,MAAiC,EACjC,IAAY;IAEZ,IAAI,MAAM,GAAiB,EAAE,CAAA;IAC7B,IAAI,QAAQ,GAAG,CAAC,CAAA;IAChB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClB,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAA;QACxB,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;YACrB,IAAI,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,CAAA;YAC7B,OAAO,GAAG,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;gBAC1B,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;gBACxB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YACvB,CAAC;YACD,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;YACpC,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAA;QACvB,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC;QAAE,MAAM,WAAW,CAAC,MAAM,CAAC,CAAA;AAC7C,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,WAA0D,EAC1D,cAAsB,EACtB,iBAAyB,EACzB,QAAgB,EAChB,OAA6B,EAAE;IAE/B,KAAK,SAAS,CAAC,CAAC,MAAM;QACpB,IAAI,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAA;QACrC,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAA;gBAC1C,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;gBACpD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAA;gBAC1F,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAA;gBAC/C,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;oBAChB,MAAM,GAAG,EAAE,CAAA;oBACX,MAAM,KAAK,CAAA;gBACb,CAAC;gBACD,MAAM,KAAK,CAAC,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;YAC1C,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,YAAY,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;gBAC7D,MAAM,IAAI,YAAY,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;YACjF,CAAC;YACD,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAA;IACtB,OAAO,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,KAAK,iBAAiB;QAC7D,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC;QACjC,CAAC,CAAC,KAAK,CAAA;AACX,CAAC"}

package/dist/internal/validate.d.ts

@@ -0,0 +1,5 @@
+/** Validate a provider's JSON number array as exactly `expected` bytes. */
+export declare function byteArrayFrom(values: unknown, expected: number, provider: string): Uint8Array;
+/** Validate a provider's hex string field as exactly `expected` bytes. */
+export declare function bytesFromHexField(hex: unknown, expected: number, provider: string): Uint8Array;
+//# sourceMappingURL=validate.d.ts.map

package/dist/internal/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/internal/validate.ts"],"names":[],"mappings":"AAGA,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAmB7F;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAgB9F"}

package/dist/internal/validate.js

@@ -0,0 +1,39 @@
+import { EntropyError } from '../errors.js';
+import { hexToBytes } from './bytes.js';
+/** Validate a provider's JSON number array as exactly `expected` bytes. */
+export function byteArrayFrom(values, expected, provider) {
+    if (!Array.isArray(values) || values.length !== expected) {
+        throw new EntropyError('bad_response', `expected an array of ${expected} byte values, got ${Array.isArray(values) ? values.length : typeof values}`, { provider });
+    }
+    const out = new Uint8Array(expected);
+    for (let i = 0; i < expected; i++) {
+        const value = values[i];
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            throw new EntropyError('bad_response', `value at index ${i} is not a byte: ${value}`, {
+                provider,
+            });
+        }
+        out[i] = value;
+    }
+    return out;
+}
+/** Validate a provider's hex string field as exactly `expected` bytes. */
+export function bytesFromHexField(hex, expected, provider) {
+    if (typeof hex !== 'string') {
+        throw new EntropyError('bad_response', `expected a hex string, got ${typeof hex}`, { provider });
+    }
+    let bytes;
+    try {
+        bytes = hexToBytes(hex);
+    }
+    catch (error) {
+        throw new EntropyError('bad_response', `invalid hex in response`, { provider, cause: error });
+    }
+    if (bytes.length !== expected) {
+        throw new EntropyError('bad_response', `expected ${expected} bytes, got ${bytes.length}`, {
+            provider,
+        });
+    }
+    return bytes;
+}
+//# sourceMappingURL=validate.js.map

package/dist/internal/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/internal/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAEvC,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,MAAe,EAAE,QAAgB,EAAE,QAAgB;IAC/E,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzD,MAAM,IAAI,YAAY,CACpB,cAAc,EACd,wBAAwB,QAAQ,qBAAqB,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE,EAC5G,EAAE,QAAQ,EAAE,CACb,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAA;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,GAAG,CAAC,IAAK,KAAgB,GAAG,GAAG,EAAE,CAAC;YACjF,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,kBAAkB,CAAC,mBAAmB,KAAK,EAAE,EAAE;gBACpF,QAAQ;aACT,CAAC,CAAA;QACJ,CAAC;QACD,GAAG,CAAC,CAAC,CAAC,GAAG,KAAe,CAAA;IAC1B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,QAAgB,EAAE,QAAgB;IAChF,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,8BAA8B,OAAO,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;IAClG,CAAC;IACD,IAAI,KAAiB,CAAA;IACrB,IAAI,CAAC;QACH,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IACzB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,yBAAyB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;IAC/F,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,YAAY,QAAQ,eAAe,KAAK,CAAC,MAAM,EAAE,EAAE;YACxF,QAAQ;SACT,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}