@selvajs/server 0.2.1 → 1.0.0-beta.1

package/dist/compute/client-cache.js

@@ -1,176 +0,0 @@
-import { GrasshopperClient, enableDebugLogging } from '@selvajs/compute';
-/** Derive the opaque cache identity from a resolved server. Identity is the `id`. */
-export function serverIdentity(server) {
-    return server.id;
-}
-const DEFAULT_MAX_CACHED_CLIENTS = 16;
-/**
- * Build a per-server warm-client cache. Each cache owns its own LRU `Map` keyed
- * on server `id`.
- */
-export function createClientCache(config) {
-    const maxCachedClients = config.maxCachedClients ?? DEFAULT_MAX_CACHED_CLIENTS;
-    const cache = new Map();
-    if (config.debugVerbose)
-        enableDebugLogging();
-    const debugLog = (message) => {
-        if (config.debug)
-            config.onDebugLog?.(message);
-    };
-    async function build(server, definitionGuid) {
-        // Holders for per-request results from the client/scheduler callbacks; the
-        // caller reads them right after each solve resolves to build Server-Timing,
-        // using the seq counters to detect (and drop) ambiguous concurrent writes.
-        const rhinoTiming = { last: null, seq: 0 };
-        const solveMeta = { last: null, seq: 0 };
-        const clientConfig = {
-            serverUrl: server.serverUrl,
-            apiKey: server.apiKey,
-            // Lib-level debug is the verbose one (full payload logs); keep it on the
-            // verbose flag so the concise cache logs can run without the noise.
-            debug: config.debugVerbose,
-            // Ask Rhino.Compute to cache solve results and return them on identical
-            // repeats (same definition + inputs), skipping the solve.
-            cachesolve: config.cachesolve,
-            // Opt-in: also cache solves that reported GH errors.
-            cacheerroredsolves: config.cacheerroredsolves,
-            // DEBUG: the server's per-request timing breakdown, which exposes the two
-            // SERVER-side caches at once — definition cache (pointer reuse) via
-            // `decode`, solve cache (cachesolve) via `solve`. Flagged below so the
-            // contrast is obvious in the logs.
-            onServerTiming: (t) => {
-                const decode = t.decode ?? 0;
-                const solve = t.solve ?? 0;
-                const encode = t.encode ?? 0;
-                // Always recorded (cheap): the caller reads this after scheduler.solve.
-                rhinoTiming.seq += 1;
-                rhinoTiming.last = { decode, solve, encode };
-                if (!config.debug)
-                    return;
-                // Heuristic thresholds: a genuine parse/solve is many ms; a cache hit
-                // is sub-millisecond. Only meaningful relative to the first (cold) solve.
-                const defCache = decode <= 1 ? 'HIT (definition reused, no re-upload/parse)' : 'miss (full parse)';
-                const solveCache = config.cachesolve && solve <= 1
-                    ? 'HIT (cached result, solve skipped)'
-                    : config.cachesolve
-                        ? 'miss (solved fresh)'
-                        : 'off';
-                debugLog(`[Compute/rhino-cache] decode=${decode}ms solve=${solve}ms encode=${encode}ms ` +
-                    `| definition-cache: ${defCache} | solve-cache (cachesolve): ${solveCache}`);
-            }
-        };
-        // `X-Selva-Definition` on the wire (ADR 0004 D2). Baked at client-create
-        // time because the scheduler has no per-request header hook — inert for a
-        // single-member "pool", useful in compute-side access logs immediately.
-        if (definitionGuid) {
-            clientConfig.headers = { 'X-Selva-Definition': definitionGuid };
-        }
-        const client = await GrasshopperClient.create(clientConfig);
-        const scheduler = client.createScheduler({
-            mode: 'queue',
-            // Queue mode defaults maxConcurrent to 1, which would serialize every
-            // solve on this server through a single slot while the compute VM's
-            // other compute.geometry children idle (audit B6) — always pass it.
-            maxConcurrent: config.maxConcurrentSolves,
-            // Backpressure (audit B7). The scheduler treats undefined as
-            // unbounded/no-deadline, so map our `0`-means-off convention to undefined
-            // rather than passing 0 (which would shed EVERY queued solve).
-            maxQueueDepth: config.maxQueueDepth || undefined,
-            queueWaitMs: config.queueWaitMs || undefined,
-            timeoutMs: config.maxSolveDurationMs,
-            // L1 response cache: count-capped AND byte-budgeted (audit C2) — entries
-            // can be as large as the response cap allows, so the count alone would
-            // let 20 × max-response-size pin gigabytes per warm client. `0` = off.
-            cache: config.responseCacheMaxBytes > 0
-                ? { maxEntries: 20, ttlMs: 5 * 60_000, maxBytes: config.responseCacheMaxBytes }
-                : false,
-            // Solve large definitions by server cache-key (pointer) instead of
-            // re-uploading the full binary every solve. On a stale-pointer miss the
-            // client transparently re-uploads.
-            reuseServerDefinitionCache: config.reuseServerDefinitionCache,
-            // DEBUG: observe the in-process response cache. `fromCache === true` means
-            // this solve was served from the app's own cache — Rhino.Compute was never
-            // called. `false` means it went to the compute server.
-            onSettle: (_ctx, result) => {
-                // Count EVERY settle (success or error) so the caller's attribution
-                // guard sees all concurrent activity, not just successful writes.
-                solveMeta.seq += 1;
-                if (result.status !== 'success')
-                    return;
-                // Always recorded (cheap): the caller surfaces these on Server-Timing.
-                solveMeta.last = {
-                    fromCache: result.fromCache === true,
-                    definitionReuploaded: result.definitionReuploaded
-                };
-                if (!config.debug)
-                    return;
-                debugLog(`[Compute/selva-cache] ${result.fromCache ? 'HIT  — served from cache (no compute call)' : 'miss — went to Rhino.Compute'} (${Math.round(result.durationMs)}ms)`);
-                // Definition-cache verdict for a real compute call (not a cache HIT).
-                if (!result.fromCache) {
-                    debugLog(result.definitionReuploaded === true
-                        ? '[Compute/def-cache] miss — definition RE-UPLOADED (pointer was cold/stale)'
-                        : result.definitionReuploaded === false
-                            ? '[Compute/def-cache] HIT  — definition reused from server cache (no upload)'
-                            : '[Compute/def-cache] n/a — reuse disabled or non-reusable definition');
-                }
-                // Surface real GH errors when present. Whether an errored solve is cached is
-                // config-gated by `cacheerroredsolves` (default false → errored solves are
-                // re-run each time; true → the error result is cached like any other, per R2).
-                if (!result.fromCache) {
-                    const errs = result.response?.errors;
-                    const errCount = Array.isArray(errs) ? errs.length : 0;
-                    if (errCount > 0) {
-                        const cacheNote = config.cacheerroredsolves
-                            ? 'cached (cacheerroredsolves on)'
-                            : 'not cached (cacheerroredsolves off) — re-run until fixed';
-                        debugLog(`[Compute/rhino-cache] ${errCount} GH error(s); ${cacheNote}. First: ${JSON.stringify(errs[0])}`);
-                    }
-                }
-            }
-        });
-        return { client, scheduler, rhinoTiming, solveMeta };
-    }
-    return {
-        async getClient(server, opts) {
-            const key = server.id;
-            const existing = cache.get(key);
-            if (existing) {
-                // Refresh LRU position.
-                cache.delete(key);
-                cache.set(key, existing);
-                return existing;
-            }
-            // A build is a Rhino.Compute handshake — expensive, and repeated builds for
-            // the same id mean churn (LRU thrash or config-rotation evictions).
-            debugLog(`[Compute/client-cache] miss — building warm client for server ${key}`);
-            const entry = await build(server, opts?.definitionGuid);
-            // Evict the least-recently-used entry before inserting when at capacity.
-            if (cache.size >= maxCachedClients) {
-                const oldestKey = cache.keys().next().value;
-                if (oldestKey !== undefined) {
-                    debugLog(`[Compute/client-cache] LRU evicted warm client for server ${oldestKey} (cap ${maxCachedClients})`);
-                    cache.get(oldestKey)?.scheduler.dispose();
-                    cache.delete(oldestKey);
-                }
-            }
-            cache.set(key, entry);
-            return entry;
-        },
-        evict(id) {
-            const key = id;
-            const entry = cache.get(key);
-            if (entry) {
-                debugLog(`[Compute/client-cache] evicted warm client for server ${key} (config change)`);
-                entry.scheduler.dispose();
-                cache.delete(key);
-            }
-        },
-        disposeAll() {
-            debugLog(`[Compute/client-cache] disposing all ${cache.size} warm client(s)`);
-            for (const entry of cache.values())
-                entry.scheduler.dispose();
-            cache.clear();
-        }
-    };
-}
-//# sourceMappingURL=client-cache.js.map

package/dist/compute/client-cache.js.map

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

package/dist/compute/definition-byte-cache.d.ts

@@ -1,85 +0,0 @@
-/**
- * In-process cache of `.gh` definition bytes, keyed by immutable **version id**.
- *
- * The solve path used to eagerly `storage.get(fileKey)` on every request — moving
- * multi-MB definition bytes off disk/S3 into memory before the scheduler could
- * decide it didn't need them (the compute server already holds the definition via
- * the pointer/`reuseServerDefinitionCache` fast path). This cache turns that eager
- * read into a lazy `DefinitionRef.load()`: the scheduler calls `load()` ONLY when
- * an upload is unavoidable, and even then a warm entry serves the bytes without
- * touching storage. A pointer-known re-solve therefore moves ZERO definition bytes.
- *
- * Keying discipline (the whole reason this module exists):
- *   - The key is the **version id**, an immutable UUID — never a `fileKey`, which
- *     a delete-latest-then-reupload can REUSE for different content (see the
- *     monotonic-version-number fix). A reused key would serve one version's bytes
- *     for another: silent cache poisoning with no diagnostic. Callers pass
- *     `version.id`, and the returned `DefinitionRef.key` is that same id, so the
- *     scheduler's own result/pointer cache keys on the same immutable identity.
- *
- * Eviction:
- *   - LRU by **total byte budget**, not entry count — definitions range from tens
- *     of KB to hundreds of MB, so an entry-count cap would either pin gigabytes or
- *     evict uselessly. `COMPUTE_DEFINITION_BYTE_CACHE_MB` sets the budget; `0`
- *     disables the cache (every `getOrLoad` calls `load` and caches nothing).
- *   - No TTL: version ids are immutable, so a cached entry can never go stale.
- *   - An entry larger than the whole budget is served but never retained (caching
- *     it would immediately evict everything including itself).
- */
-/**
- * Per-`getOrLoad` outcome, observable AFTER the scheduler has (or hasn't) called
- * `load()`. Lets the solve pipeline emit a `def_bytes` Server-Timing verdict:
- *   - `load` never invoked  → the scheduler served a pointer-known solve without
- *     bytes (`skipped`);
- *   - `load` invoked, `fromCache` true  → warm byte-cache entry (`hit`);
- *   - `load` invoked, `fromCache` false → fell through to the loader (`miss`).
- */
-export interface ByteRefOutcome {
-    /** True once `load()` has been called at least once on this ref. */
-    loaded: boolean;
-    /** When `loaded`, whether the bytes came from a warm cache entry. */
-    fromCache: boolean;
-}
-/** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
-export interface ByteCacheRef {
-    /** Immutable identity (a version UUID). Keys the scheduler's caches too. */
-    key: string;
-    /** Materialize the bytes — served from cache when warm, else via the loader. */
-    load: () => Promise<Uint8Array>;
-    /** Mutable outcome of this ref's `load()` (see {@link ByteRefOutcome}). */
-    outcome: ByteRefOutcome;
-}
-/** Hit/miss/eviction counters for observability (Server-Timing, admin debug). */
-export interface ByteCacheStats {
-    /** `load()` served from a warm entry (no loader call). */
-    hits: number;
-    /** `load()` fell through to the loader (cold key, or caching disabled). */
-    misses: number;
-    /** Entries dropped by the byte-budget LRU. */
-    evictions: number;
-    /** Current retained entry count. */
-    entries: number;
-    /** Current retained bytes. */
-    bytes: number;
-}
-export interface DefinitionByteCache {
-    /**
-     * Return a `DefinitionRef` whose `load()` serves `versionId`'s bytes from the
-     * cache when warm, otherwise calls `load` (and caches the result). The
-     * `DefinitionRef` is cheap to build and moves no bytes until `load()` runs —
-     * so handing it to the scheduler for a pointer-known solve costs nothing.
-     */
-    getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
-    /** Snapshot of the counters (see {@link ByteCacheStats}). */
-    stats(): ByteCacheStats;
-    /** Drop everything (test seam / eviction on definition delete if ever needed). */
-    clear(): void;
-}
-/**
- * Build a definition-byte cache with a total-byte LRU budget.
- *
- * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
- *   entirely — every `load()` calls the loader and nothing is retained.
- */
-export declare function createDefinitionByteCache(maxBytes: number): DefinitionByteCache;
-//# sourceMappingURL=definition-byte-cache.d.ts.map

package/dist/compute/definition-byte-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"definition-byte-cache.d.ts","sourceRoot":"","sources":["../../src/compute/definition-byte-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC9B,oEAAoE;IACpE,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC5B,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,2EAA2E;IAC3E,OAAO,EAAE,cAAc,CAAC;CACxB;AAED,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC9B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GAAG,YAAY,CAAC;IAC5E,6DAA6D;IAC7D,KAAK,IAAI,cAAc,CAAC;IACxB,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;CACd;AAMD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CA2E/E"}

package/dist/compute/definition-byte-cache.js

@@ -1,110 +0,0 @@
-/**
- * In-process cache of `.gh` definition bytes, keyed by immutable **version id**.
- *
- * The solve path used to eagerly `storage.get(fileKey)` on every request — moving
- * multi-MB definition bytes off disk/S3 into memory before the scheduler could
- * decide it didn't need them (the compute server already holds the definition via
- * the pointer/`reuseServerDefinitionCache` fast path). This cache turns that eager
- * read into a lazy `DefinitionRef.load()`: the scheduler calls `load()` ONLY when
- * an upload is unavoidable, and even then a warm entry serves the bytes without
- * touching storage. A pointer-known re-solve therefore moves ZERO definition bytes.
- *
- * Keying discipline (the whole reason this module exists):
- *   - The key is the **version id**, an immutable UUID — never a `fileKey`, which
- *     a delete-latest-then-reupload can REUSE for different content (see the
- *     monotonic-version-number fix). A reused key would serve one version's bytes
- *     for another: silent cache poisoning with no diagnostic. Callers pass
- *     `version.id`, and the returned `DefinitionRef.key` is that same id, so the
- *     scheduler's own result/pointer cache keys on the same immutable identity.
- *
- * Eviction:
- *   - LRU by **total byte budget**, not entry count — definitions range from tens
- *     of KB to hundreds of MB, so an entry-count cap would either pin gigabytes or
- *     evict uselessly. `COMPUTE_DEFINITION_BYTE_CACHE_MB` sets the budget; `0`
- *     disables the cache (every `getOrLoad` calls `load` and caches nothing).
- *   - No TTL: version ids are immutable, so a cached entry can never go stale.
- *   - An entry larger than the whole budget is served but never retained (caching
- *     it would immediately evict everything including itself).
- */
-/**
- * Build a definition-byte cache with a total-byte LRU budget.
- *
- * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
- *   entirely — every `load()` calls the loader and nothing is retained.
- */
-export function createDefinitionByteCache(maxBytes) {
-    const budget = Math.max(0, Math.floor(maxBytes));
-    // Map preserves insertion order → iteration order IS LRU order; re-inserting
-    // on access moves an entry to the most-recently-used (last) position.
-    const cache = new Map();
-    let retainedBytes = 0;
-    const stats = { hits: 0, misses: 0, evictions: 0 };
-    function touch(key, entry) {
-        cache.delete(key);
-        cache.set(key, entry);
-    }
-    function evictToFit() {
-        // Evict least-recently-used (first in insertion order) until within budget.
-        while (retainedBytes > budget && cache.size > 0) {
-            const oldestKey = cache.keys().next().value;
-            const oldest = cache.get(oldestKey);
-            cache.delete(oldestKey);
-            retainedBytes -= oldest.bytes.byteLength;
-            stats.evictions += 1;
-        }
-    }
-    function store(key, bytes) {
-        if (budget === 0)
-            return;
-        // An entry bigger than the whole budget is never retained — caching it would
-        // evict everything (including itself) on the next `evictToFit`. Serve it
-        // through, cache nothing.
-        if (bytes.byteLength > budget)
-            return;
-        const existing = cache.get(key);
-        if (existing)
-            retainedBytes -= existing.bytes.byteLength;
-        cache.set(key, { bytes });
-        retainedBytes += bytes.byteLength;
-        evictToFit();
-    }
-    return {
-        getOrLoad(versionId, load) {
-            const outcome = { loaded: false, fromCache: false };
-            return {
-                key: versionId,
-                outcome,
-                load: async () => {
-                    const hit = cache.get(versionId);
-                    if (hit) {
-                        touch(versionId, hit);
-                        stats.hits += 1;
-                        outcome.loaded = true;
-                        outcome.fromCache = true;
-                        return hit.bytes;
-                    }
-                    stats.misses += 1;
-                    outcome.loaded = true;
-                    outcome.fromCache = false;
-                    const bytes = await load();
-                    store(versionId, bytes);
-                    return bytes;
-                }
-            };
-        },
-        stats() {
-            return {
-                hits: stats.hits,
-                misses: stats.misses,
-                evictions: stats.evictions,
-                entries: cache.size,
-                bytes: retainedBytes
-            };
-        },
-        clear() {
-            cache.clear();
-            retainedBytes = 0;
-        }
-    };
-}
-//# sourceMappingURL=definition-byte-cache.js.map

package/dist/compute/definition-byte-cache.js.map

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

package/dist/compute/memory-solve-cache.d.ts

@@ -1,58 +0,0 @@
-/**
- * In-memory `ISolveResultCache` — the first durable L2 backend (H1).
- *
- * Two eviction dimensions, both required (see CACHING.md H1):
- *
- *   1. **Per-definition count quota, LRU-within-definition.** Each definition
- *      gets its own budget of remembered solves (`maxEntriesForDefinition`,
- *      passed at write time). A slider-heavy definition churns ONLY its own
- *      entries — it can never evict another definition's. This is what makes a
- *      wide-input-space definition harmless structurally instead of via an
- *      off-switch.
- *   2. **Global byte backstop, global-LRU.** Entries range KB→100s of MB, so a
- *      count quota can't bound heap. `maxTotalBytes` evicts the globally
- *      least-recently-used entry across every definition until total retained
- *      bytes fit. Authors think in counts; operators think in bytes; both hold.
- *
- * The key is `(orgId, definitionId, versionId, inputKey)`. `definitionId` scopes
- * the count quota; the full tuple addresses the entry. Version keying means a
- * publish is a fresh keyspace and there is nothing to invalidate — entries just
- * age out under the two budgets.
- *
- * Best-effort contract: this never throws. A `get` miss and a `set` drop are both
- * normal. Correctness never depends on a hit.
- */
-import type { ISolveResultCache } from '@selvajs/platform';
-/** Observability counters for the admin/debug surface (parallels ByteCacheStats). */
-export interface SolveCacheStats {
-    /** `get` served a live entry. */
-    hits: number;
-    /** `get` found nothing. */
-    misses: number;
-    /** `set` stored a new (or replaced) entry. */
-    writes: number;
-    /** Entries dropped by the per-definition count quota. */
-    quotaEvictions: number;
-    /** Entries dropped by the global byte backstop. */
-    byteEvictions: number;
-    /** Current retained entry count across all definitions. */
-    entries: number;
-    /** Current retained bytes across all definitions. */
-    bytes: number;
-}
-/** A memory backend with its own stats, for wiring + observability. */
-export interface MemorySolveResultCache extends ISolveResultCache {
-    stats(): SolveCacheStats;
-    /** Drop everything (test seam). */
-    clear(): void;
-}
-/**
- * Build an in-memory L2 solve cache.
- *
- * @param maxTotalBytes global retained-byte backstop; `0` (or negative) disables
- *   the backstop (per-definition counts are then the only bound — not recommended
- *   in-process). An entry larger than the whole backstop is stored-then-immediately
- *   evicted (served through, never retained) — same rule as the byte cache.
- */
-export declare function createMemorySolveResultCache(maxTotalBytes: number): MemorySolveResultCache;
-//# sourceMappingURL=memory-solve-cache.d.ts.map

package/dist/compute/memory-solve-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory-solve-cache.d.ts","sourceRoot":"","sources":["../../src/compute/memory-solve-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACX,iBAAiB,EAIjB,MAAM,mBAAmB,CAAC;AAE3B,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC/B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,cAAc,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAChE,KAAK,IAAI,eAAe,CAAC;IACzB,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACd;AAOD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,sBAAsB,CAoI1F"}

package/dist/compute/memory-solve-cache.js.map

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

package/dist/compute/solve-cache-envelope.d.ts

@@ -1,53 +0,0 @@
-/**
- * L2 cache entry format (R6). An entry is the gzipped response body plus a tiny
- * metadata header, so a hit is near-CPU-free: no `JSON.stringify`, no re-solve —
- * gzip clients get the stored bytes verbatim, and the header carries just enough
- * to rebuild the `ok` outcome (error/warning counts for the metric, uncompressed
- * length for the `Content-Length` on a gunzip fallback).
- *
- * Wire layout (opaque to the `ISolveResultCache` backend, which sees only bytes):
- *
- *   [ 4 bytes: header length N, big-endian uint32 ]
- *   [ N bytes: UTF-8 JSON EnvelopeHeader ]
- *   [ rest:    gzipped JSON response body ]
- *
- * The `algo` echo (M3) is already stripped at the source in the package's
- * `runSolve`, so the body never carries the base64 definition — entries stay
- * small without a strip step here.
- */
-/** Metadata stored beside the gzipped body. Small; parsed on every hit. */
-export interface EnvelopeHeader {
-    /** Grasshopper runtime error count, for the solve metric. */
-    errorCount: number;
-    /** Grasshopper runtime warning count, for the solve metric. */
-    warningCount: number;
-    /** Uncompressed JSON body length in bytes (Content-Length for a gunzip fallback). */
-    serializedBytes: number;
-    /**
-     * SHA-256 hex of the canonical input preimage (H2 defense-in-depth). A hit
-     * verifies this equals the requesting key's hash before serving — a wide-hash
-     * collision that produced the same storage key still can't serve the wrong
-     * geometry.
-     */
-    inputHash: string;
-}
-/**
- * Encode a cache entry from the gzipped body + header. The body MUST already be
- * gzipped (the pipeline gzips before storing so every hit serves compressed
- * bytes; a rare non-gzip client gunzips on read).
- */
-export declare function encodeSolveCacheEntry(header: EnvelopeHeader, gzippedBody: Uint8Array): Uint8Array;
-/** A decoded entry: the parsed header + the still-gzipped body slice. */
-export interface DecodedSolveCacheEntry {
-    header: EnvelopeHeader;
-    gzippedBody: Uint8Array;
-}
-/**
- * Decode a cache entry. Returns `null` on any malformed input (truncated, bad
- * length prefix, non-JSON header) — a corrupt entry is treated as a miss, never
- * an error, matching the best-effort cache contract.
- */
-export declare function decodeSolveCacheEntry(bytes: Uint8Array): DecodedSolveCacheEntry | null;
-/** Gunzip a stored body back to the JSON string, for a non-gzip client (rare). */
-export declare function gunzipEntryBody(gzippedBody: Uint8Array): string;
-//# sourceMappingURL=solve-cache-envelope.d.ts.map

package/dist/compute/solve-cache-envelope.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"solve-cache-envelope.d.ts","sourceRoot":"","sources":["../../src/compute/solve-cache-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC9B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,GAAG,UAAU,CAUjG;AAED,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,EAAE,UAAU,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,GAAG,sBAAsB,GAAG,IAAI,CA2BtF;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,WAAW,EAAE,UAAU,GAAG,MAAM,CAE/D"}

package/dist/compute/solve-cache-envelope.js

@@ -1,66 +0,0 @@
-/**
- * L2 cache entry format (R6). An entry is the gzipped response body plus a tiny
- * metadata header, so a hit is near-CPU-free: no `JSON.stringify`, no re-solve —
- * gzip clients get the stored bytes verbatim, and the header carries just enough
- * to rebuild the `ok` outcome (error/warning counts for the metric, uncompressed
- * length for the `Content-Length` on a gunzip fallback).
- *
- * Wire layout (opaque to the `ISolveResultCache` backend, which sees only bytes):
- *
- *   [ 4 bytes: header length N, big-endian uint32 ]
- *   [ N bytes: UTF-8 JSON EnvelopeHeader ]
- *   [ rest:    gzipped JSON response body ]
- *
- * The `algo` echo (M3) is already stripped at the source in the package's
- * `runSolve`, so the body never carries the base64 definition — entries stay
- * small without a strip step here.
- */
-import { gunzipSync } from 'node:zlib';
-/**
- * Encode a cache entry from the gzipped body + header. The body MUST already be
- * gzipped (the pipeline gzips before storing so every hit serves compressed
- * bytes; a rare non-gzip client gunzips on read).
- */
-export function encodeSolveCacheEntry(header, gzippedBody) {
-    const headerJson = Buffer.from(JSON.stringify(header), 'utf8');
-    const out = Buffer.allocUnsafe(4 + headerJson.byteLength + gzippedBody.byteLength);
-    out.writeUInt32BE(headerJson.byteLength, 0);
-    headerJson.copy(out, 4);
-    Buffer.from(gzippedBody.buffer, gzippedBody.byteOffset, gzippedBody.byteLength).copy(out, 4 + headerJson.byteLength);
-    return out;
-}
-/**
- * Decode a cache entry. Returns `null` on any malformed input (truncated, bad
- * length prefix, non-JSON header) — a corrupt entry is treated as a miss, never
- * an error, matching the best-effort cache contract.
- */
-export function decodeSolveCacheEntry(bytes) {
-    if (bytes.byteLength < 4)
-        return null;
-    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-    const headerLen = buf.readUInt32BE(0);
-    const headerEnd = 4 + headerLen;
-    if (headerEnd > buf.byteLength)
-        return null;
-    let header;
-    try {
-        header = JSON.parse(buf.toString('utf8', 4, headerEnd));
-    }
-    catch {
-        return null;
-    }
-    if (typeof header?.errorCount !== 'number' ||
-        typeof header?.warningCount !== 'number' ||
-        typeof header?.serializedBytes !== 'number' ||
-        typeof header?.inputHash !== 'string') {
-        return null;
-    }
-    // Slice (view, no copy) of the gzipped remainder.
-    const gzippedBody = new Uint8Array(bytes.buffer, bytes.byteOffset + headerEnd, bytes.byteLength - headerEnd);
-    return { header, gzippedBody };
-}
-/** Gunzip a stored body back to the JSON string, for a non-gzip client (rare). */
-export function gunzipEntryBody(gzippedBody) {
-    return gunzipSync(gzippedBody).toString('utf8');
-}
-//# sourceMappingURL=solve-cache-envelope.js.map

package/dist/compute/solve-cache-envelope.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"solve-cache-envelope.js","sourceRoot":"","sources":["../../src/compute/solve-cache-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAmBvC;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAsB,EAAE,WAAuB;IACpF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,GAAG,UAAU,CAAC,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACnF,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACxB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC,IAAI,CACnF,GAAG,EACH,CAAC,GAAG,UAAU,CAAC,UAAU,CACzB,CAAC;IACF,OAAO,GAAG,CAAC;AACZ,CAAC;AAQD;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiB;IACtD,IAAI,KAAK,CAAC,UAAU,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,IAAI,SAAS,GAAG,GAAG,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,MAAsB,CAAC;IAC3B,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,SAAS,CAAC,CAAmB,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAC;IACb,CAAC;IACD,IACC,OAAO,MAAM,EAAE,UAAU,KAAK,QAAQ;QACtC,OAAO,MAAM,EAAE,YAAY,KAAK,QAAQ;QACxC,OAAO,MAAM,EAAE,eAAe,KAAK,QAAQ;QAC3C,OAAO,MAAM,EAAE,SAAS,KAAK,QAAQ,EACpC,CAAC;QACF,OAAO,IAAI,CAAC;IACb,CAAC;IACD,kDAAkD;IAClD,MAAM,WAAW,GAAG,IAAI,UAAU,CACjC,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,GAAG,SAAS,EAC5B,KAAK,CAAC,UAAU,GAAG,SAAS,CAC5B,CAAC;IACF,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAChC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,WAAuB;IACtD,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACjD,CAAC"}