@evomap/evolver-adapter-public 2.0.0-beta.0

package/dist/hubReuse.d.ts

@@ -0,0 +1,112 @@
+import { hub } from '@evomap/evolver-core';
+import type { algo } from '@evomap/evolver-core';
+type HubMetadata = hub.HubMetadata;
+type ReuseDecision = hub.ReuseDecision;
+type GeneCandidateInput = algo.GeneCandidateInput;
+export declare const SEARCH_CACHE_TTL_MS: number;
+export declare const SEARCH_CACHE_MAX = 200;
+export declare const PAYLOAD_CACHE_MAX = 100;
+/** Default reuse mode (ported from v1): 'reference' injects the asset as a strong hint; 'direct' applies it. */
+export type ReuseMode = 'direct' | 'reference';
+export declare const DEFAULT_REUSE_MODE: ReuseMode;
+/** Reads EVOLVER_MIN_REUSE_SCORE here (env is an ADAPTER concern — core never reads it). */
+export declare function getMinReuseScore(env?: NodeJS.ProcessEnv): number;
+/** Reads EVOLVER_REUSE_MODE here (adapter concern). */
+export declare function getReuseMode(env?: NodeJS.ProcessEnv): ReuseMode;
+/** Stable signal fingerprint (ported from v1 _cacheKey: sort + join). */
+export declare function signalFingerprint(signals: readonly string[]): string;
+/**
+ * The two-layer reuse cache. Bounded + TTL'd, per-process. A search-cache hit means phase 1 makes ZERO hub
+ * calls; a payload-cache hit means phase 3 makes ZERO hub calls. The clock is injected for deterministic tests.
+ */
+export declare class ReuseCache {
+    private readonly now;
+    private readonly searchTtlMs;
+    private readonly searchMax;
+    private readonly payloadMax;
+    private readonly search;
+    private readonly payload;
+    constructor(now?: () => number, searchTtlMs?: number, searchMax?: number, payloadMax?: number);
+    getSearch(key: string): HubMetadata[] | null;
+    setSearch(key: string, value: HubMetadata[]): void;
+    getPayload(assetId: string): hub.AssetRecord | null;
+    setPayload(assetId: string, payload: hub.AssetRecord): void;
+    clear(): void;
+}
+/**
+ * Map a hub search row (AssetRecord with arbitrary quality fields) → the core's price-free HubMetadata.
+ * Accepts both camelCase and the hub's snake_case (gdi_score / success_rate / reuse_count / ...). Drops any
+ * price/credit field by simply not reading it — the core HubMetadata has no slot for cost.
+ */
+export declare function toHubMetadata(rec: hub.AssetRecord): HubMetadata;
+/** Map a fetched hub asset (full payload) → a selection candidate so it competes in candidateAssembly. */
+export declare function toGeneCandidate(rec: hub.AssetRecord): GeneCandidateInput;
+/** A receipt the adapter SURFACES but never interprets (mirrors core's PublishReceipt.economic handling). */
+export interface ReuseReceipt {
+    /** The hub's credit_cost block, passed through verbatim for observability/UI. Never gated on. */
+    creditCost?: unknown;
+    fromCache: boolean;
+}
+export interface ReuseBeforeSolveOptions {
+    /** Reuse threshold; default from EVOLVER_MIN_REUSE_SCORE (read in the adapter, never in core). */
+    threshold?: number;
+    /** Injected clock for recency scoring (passed to core scoreSearchResults). */
+    now?: number;
+    /** Cap on how many candidates the free search pulls. */
+    searchLimit?: number;
+    /** Reuse mode label carried into the result (direct/reference). */
+    mode?: ReuseMode;
+    /** Observability sink (asset-call log). Receives structured records; never throws. */
+    log?: {
+        append(entry: Record<string, unknown>): void;
+    };
+    runId?: string | null;
+    /**
+     * Value-ledger emission seam (#112). Fired exactly once on a reuse HIT (action === 'fetch') with the audit
+     * anchors the ledger needs to derive a source=reuse entry: the reused assetId, the cycleId it feeds, the
+     * signal fingerprint, and the tokens the fetch actually consumed (≈0 — payload/cache pull, no fresh solve).
+     * The composition layer wires this to a `value.reuse_hit` root_event. Optional + must never throw (reuse is
+     * an optimization, and observability emission can never be allowed to break it).
+     */
+    onReuseHit?: (hit: ReuseHitInfo) => void;
+    /** The cycle this resolution feeds — carried into onReuseHit so the event refs the SAME cycleId as the cycle. */
+    cycleId?: string;
+}
+/** What onReuseHit reports on a reuse hit — the value-ledger audit anchors (#112). */
+export interface ReuseHitInfo {
+    assetId: string;
+    cycleId: string;
+    signalFingerprint: string;
+    /** Tokens the fetch actually consumed (cache/payload pull — typically 0). */
+    fetchTokens: number;
+}
+export interface ReuseBeforeSolveResult {
+    /** 'fetch' = a winner was fetched and is ready to compete; 'solve-fresh' = nothing worth reusing. */
+    action: ReuseDecision['action'];
+    /** The fetched winner as a selection candidate (only when action === 'fetch'). */
+    candidate?: GeneCandidateInput;
+    /** The raw fetched payload (only when action === 'fetch'), for ingest/reference injection. */
+    asset?: hub.AssetRecord;
+    /** The reuse mode applied. */
+    mode: ReuseMode;
+    /** Decision score of the winner (rounded), for logging. */
+    score?: number;
+    /** Economic receipt read-through (read-only; the adapter never interprets credits). */
+    receipt?: ReuseReceipt;
+    /** True when the whole flow made ZERO hub calls (both layers hit). */
+    zeroHubCalls: boolean;
+    /** Why we didn't reuse, when action === 'solve-fresh' (no_signals / no_results / below_threshold). */
+    reason?: string;
+}
+/**
+ * The reuse-before-solve flow. Returns the single winner (already fetched) as a selection candidate, or a
+ * solve-fresh verdict. Never throws on a hub error — reuse is an optimization, not a hard dependency:
+ * a failed search/fetch degrades to solve-fresh.
+ *
+ * @param cap   the HubCapability (free search + paid fetch).
+ * @param cache the two-layer cache (caller owns it across cycles so it actually warms).
+ * @param signals the local problem signals.
+ */
+export declare function reuseBeforeSolve(cap: hub.HubCapability, cache: ReuseCache, signals: readonly string[], opts?: ReuseBeforeSolveOptions): Promise<ReuseBeforeSolveResult>;
+export declare function assetMatchesId(asset: hub.AssetRecord | null | undefined, assetId: string): asset is hub.AssetRecord;
+export {};

package/dist/hubReuse.js

@@ -0,0 +1,292 @@
+// Reuse-before-solve ORCHESTRATION + BILLING + CACHE (#110) — the adapter half of the cost lever.
+// Ported from v1 hubSearch.js (the two-phase flow + the two-layer cache). The PURE decision lives in core
+// (evolver-core/src/hub/reuseDecision.ts) — this file owns everything core must NOT know about: the paid
+// fetch, the economic receipt read-through, and the cache that turns repeat lookups into ZERO hub calls.
+//
+// Two-phase flow (the #69 lesson: search != fetch — search is free metadata, fetch is the paid content pull):
+//   Phase 1 (free):  cap.search(query)            → candidate metadata only
+//   Phase 2 (decide): core scoreSearchResults + decideReuse → AT MOST ONE winner
+//   Phase 3 (paid):  cap.fetch(winner)            → full payload for the single winner (and only then)
+//
+// Two-layer cache (ported from v1):
+//   - search cache: signal-fingerprint → phase-1 metadata (short TTL). Repeat signal set → ZERO hub calls.
+//   - payload cache: assetId → phase-3 payload (content-addressed, long/permanent, bounded LRU). A cached
+//     payload → ZERO fetch. Both clocks are injected so TTL/eviction is deterministic and testable.
+import { hub } from '@evomap/evolver-core';
+const { scoreSearchResults, decideReuse, DEFAULT_MIN_REUSE_SCORE, } = hub;
+const GENE_WIRE_KEYS = new Set([
+    'type',
+    'schema_version',
+    'id',
+    'category',
+    'signals_match',
+    'preconditions',
+    'strategy',
+    'constraints',
+    'validation',
+    'summary',
+    'epigenetic_marks',
+    'learning_history',
+    'anti_patterns',
+    'routing_hint',
+    'tool_policy',
+    'asset_id',
+]);
+// ── Cache config (ported from v1 hubSearch.js) ───────────────────────────────
+export const SEARCH_CACHE_TTL_MS = 5 * 60 * 1000; // metadata is hot but staleable — short TTL
+export const SEARCH_CACHE_MAX = 200;
+export const PAYLOAD_CACHE_MAX = 100;
+export const DEFAULT_REUSE_MODE = 'reference';
+/** Reads EVOLVER_MIN_REUSE_SCORE here (env is an ADAPTER concern — core never reads it). */
+export function getMinReuseScore(env = process.env) {
+    const n = Number(env['EVOLVER_MIN_REUSE_SCORE']);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_MIN_REUSE_SCORE;
+}
+/** Reads EVOLVER_REUSE_MODE here (adapter concern). */
+export function getReuseMode(env = process.env) {
+    return String(env['EVOLVER_REUSE_MODE'] ?? DEFAULT_REUSE_MODE).toLowerCase() === 'direct' ? 'direct' : 'reference';
+}
+/** Stable signal fingerprint (ported from v1 _cacheKey: sort + join). */
+export function signalFingerprint(signals) {
+    return [...signals].map((s) => String(s).trim()).filter(Boolean).sort().join('|');
+}
+/**
+ * The two-layer reuse cache. Bounded + TTL'd, per-process. A search-cache hit means phase 1 makes ZERO hub
+ * calls; a payload-cache hit means phase 3 makes ZERO hub calls. The clock is injected for deterministic tests.
+ */
+export class ReuseCache {
+    now;
+    searchTtlMs;
+    searchMax;
+    payloadMax;
+    search = new Map();
+    payload = new Map();
+    constructor(now = () => Date.now(), searchTtlMs = SEARCH_CACHE_TTL_MS, searchMax = SEARCH_CACHE_MAX, payloadMax = PAYLOAD_CACHE_MAX) {
+        this.now = now;
+        this.searchTtlMs = searchTtlMs;
+        this.searchMax = searchMax;
+        this.payloadMax = payloadMax;
+    }
+    getSearch(key) {
+        const e = this.search.get(key);
+        if (!e)
+            return null;
+        if (this.now() - e.ts > this.searchTtlMs) {
+            this.search.delete(key);
+            return null;
+        }
+        return e.value;
+    }
+    setSearch(key, value) {
+        if (this.search.size >= this.searchMax) {
+            const oldest = this.search.keys().next().value;
+            if (oldest !== undefined)
+                this.search.delete(oldest);
+        }
+        this.search.set(key, { ts: this.now(), value });
+    }
+    getPayload(assetId) {
+        const asset = this.payload.get(assetId) ?? null;
+        if (!asset)
+            return null;
+        if (assetMatchesId(asset, assetId))
+            return asset;
+        this.payload.delete(assetId);
+        return null;
+    }
+    setPayload(assetId, payload) {
+        if (!assetMatchesId(payload, assetId))
+            return;
+        if (this.payload.size >= this.payloadMax) {
+            const oldest = this.payload.keys().next().value;
+            if (oldest !== undefined)
+                this.payload.delete(oldest);
+        }
+        this.payload.set(assetId, payload);
+    }
+    clear() { this.search.clear(); this.payload.clear(); }
+}
+// ── metadata mapping (hub wire → core HubMetadata, NO price) ──────────────────
+function num(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+function strArr(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+}
+function ts(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isFinite(t) ? t : undefined;
+    }
+    return undefined;
+}
+function stripHubPayloadMetadata(rec) {
+    const out = {};
+    for (const [key, value] of Object.entries(rec)) {
+        if (GENE_WIRE_KEYS.has(key))
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * Map a hub search row (AssetRecord with arbitrary quality fields) → the core's price-free HubMetadata.
+ * Accepts both camelCase and the hub's snake_case (gdi_score / success_rate / reuse_count / ...). Drops any
+ * price/credit field by simply not reading it — the core HubMetadata has no slot for cost.
+ */
+export function toHubMetadata(rec) {
+    const r = rec;
+    const assetId = String(r['asset_id'] ?? r['assetId'] ?? '');
+    const updatedAt = ts(r['updated_at'] ?? r['updatedAt'] ?? r['created_at'] ?? r['createdAt']);
+    return {
+        assetId,
+        ...(strArr(r['signals_match'] ?? r['signalsMatch']) ? { signalsMatch: strArr(r['signals_match'] ?? r['signalsMatch']) } : {}),
+        ...(typeof r['category'] === 'string' ? { category: r['category'] } : {}),
+        ...(typeof r['summary'] === 'string' ? { summary: r['summary'] } : {}),
+        ...(typeof r['status'] === 'string' ? { status: r['status'] } : {}),
+        ...(num(r['confidence']) !== undefined ? { confidence: num(r['confidence']) } : {}),
+        ...(num(r['success_streak'] ?? r['successStreak']) !== undefined ? { successStreak: num(r['success_streak'] ?? r['successStreak']) } : {}),
+        ...(num(r['reputation_score'] ?? r['reputationScore']) !== undefined ? { reputationScore: num(r['reputation_score'] ?? r['reputationScore']) } : {}),
+        ...(num(r['gdi_score'] ?? r['gdiScore']) !== undefined ? { gdiScore: num(r['gdi_score'] ?? r['gdiScore']) } : {}),
+        ...(num(r['success_rate'] ?? r['successRate']) !== undefined ? { successRate: num(r['success_rate'] ?? r['successRate']) } : {}),
+        ...(num(r['reuse_count'] ?? r['reuseCount']) !== undefined ? { reuseCount: num(r['reuse_count'] ?? r['reuseCount']) } : {}),
+        ...(num(r['similarity'] ?? r['semanticSimilarity']) !== undefined ? { semanticSimilarity: num(r['similarity'] ?? r['semanticSimilarity']) } : {}),
+        ...(updatedAt !== undefined ? { updatedAt } : {}),
+    };
+}
+/** Map a fetched hub asset (full payload) → a selection candidate so it competes in candidateAssembly. */
+export function toGeneCandidate(rec) {
+    const r = rec;
+    const assetId = String(r['asset_id'] ?? r['assetId'] ?? '');
+    const geneId = typeof r['id'] === 'string' ? r['id'] : assetId;
+    const signalsMatch = strArr(r['signals_match'] ?? r['signalsMatch']) ?? [];
+    const reuseCount = num(r['reuse_count'] ?? r['reuseCount']) ?? 0;
+    return {
+        geneId,
+        assetId,
+        signalsMatch,
+        // A freshly-fetched hub gene has no LOCAL learning history yet; selection scores it on signal-match +
+        // reuse popularity. The local learning view stays empty (it earns history once it's actually applied).
+        view: { geneId, total: 0, success: 0, failed: 0, successRate: 0, avgScore: 0, recentCapsuleIds: [] },
+        reuseCount,
+        ...(typeof r['category'] === 'string' ? { category: r['category'] } : {}),
+        ...(typeof r['summary'] === 'string' ? { summary: r['summary'] } : {}),
+        hubAsset: stripHubPayloadMetadata(rec),
+    };
+}
+/**
+ * The reuse-before-solve flow. Returns the single winner (already fetched) as a selection candidate, or a
+ * solve-fresh verdict. Never throws on a hub error — reuse is an optimization, not a hard dependency:
+ * a failed search/fetch degrades to solve-fresh.
+ *
+ * @param cap   the HubCapability (free search + paid fetch).
+ * @param cache the two-layer cache (caller owns it across cycles so it actually warms).
+ * @param signals the local problem signals.
+ */
+export async function reuseBeforeSolve(cap, cache, signals, opts = {}) {
+    const mode = opts.mode ?? getReuseMode();
+    const threshold = opts.threshold ?? getMinReuseScore();
+    const runId = opts.runId ?? null;
+    const log = opts.log;
+    const signalList = signals.map((s) => String(s).trim()).filter(Boolean);
+    if (signalList.length === 0) {
+        return { action: 'solve-fresh', mode, zeroHubCalls: true, reason: 'no_signals' };
+    }
+    // ── Phase 1: free search (signal fingerprint cache → ZERO hub calls on hit) ──
+    const key = signalFingerprint(signalList);
+    let metadata = cache.getSearch(key);
+    const searchCached = metadata !== null;
+    if (metadata === null) {
+        let rows = [];
+        try {
+            rows = await cap.search({ signalsAny: signalList, ...(opts.searchLimit ? { limit: opts.searchLimit } : {}) });
+        }
+        catch (e) {
+            log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'search_error', error: errMsg(e) });
+            return { action: 'solve-fresh', mode, zeroHubCalls: false, reason: 'search_error' };
+        }
+        metadata = rows.map(toHubMetadata).filter((m) => m.assetId.length > 0);
+        cache.setSearch(key, metadata);
+    }
+    if (metadata.length === 0) {
+        log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'no_results', via: searchCached ? 'search_cached' : 'search' });
+        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'no_results' };
+    }
+    // ── Phase 2: PURE decision (core — no price) ──
+    const ranked = scoreSearchResults(signalList, metadata, opts.now !== undefined ? { now: opts.now } : {});
+    const decision = decideReuse(ranked, { threshold });
+    if (decision.action === 'solve-fresh' || !decision.candidate) {
+        log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'below_threshold', candidates: metadata.length, threshold });
+        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'below_threshold' };
+    }
+    // ── Phase 3: paid fetch for the ONE winner (payload cache → ZERO hub calls on hit) ──
+    const winner = decision.candidate;
+    const winnerId = winner.assetId;
+    let asset = cache.getPayload(winnerId);
+    let payloadCached = asset !== null;
+    let creditCost;
+    if (asset === null) {
+        try {
+            if (isAssetByIdFetcher(cap)) {
+                asset = await cap.fetchAssetById(winnerId);
+                creditCost = asset?.['credit_cost'];
+            }
+            else {
+                const results = await cap.fetch({ signalsAny: signalList, limit: metadata.length });
+                // The paid fetch returns full payloads; select the winner by id (content-addressed match).
+                asset = results.find((a) => String(a['asset_id'] ?? '') === winnerId)
+                    ?? null;
+                // Economic receipt read-through (read-only): surface credit_cost if the hub attached one, never gate.
+                const carrier = results.credit_cost
+                    ?? asset?.['credit_cost'];
+                creditCost = carrier;
+            }
+        }
+        catch (e) {
+            log?.append({ run_id: runId, action: 'hub_search_miss', signals: signalList, reason: 'fetch_error', error: errMsg(e) });
+            return { action: 'solve-fresh', mode, zeroHubCalls: false, reason: 'fetch_error' };
+        }
+        if (assetMatchesId(asset, winnerId))
+            cache.setPayload(winnerId, asset);
+        else
+            asset = null;
+        payloadCached = false;
+    }
+    if (!asset) {
+        return { action: 'solve-fresh', mode, zeroHubCalls: searchCached, reason: 'fetch_empty' };
+    }
+    const zeroHubCalls = searchCached && payloadCached;
+    log?.append({
+        run_id: runId, action: 'hub_search_hit', asset_id: winnerId, score: winner.score, mode,
+        signals: signalList, via: zeroHubCalls ? 'cache' : (searchCached ? 'search_cached' : 'search_then_fetch'),
+    });
+    // Value-ledger emission (#112): a reuse HIT lands a replayable record so the ledger can derive a
+    // source=reuse entry anchored on the real assetId + cycleId. fetchTokens is the actual fetch cost — a
+    // payload/cache pull rather than a fresh LLM solve, so ≈0 here. Never lets an emission error break reuse.
+    if (opts.onReuseHit) {
+        try {
+            opts.onReuseHit({ assetId: winnerId, cycleId: opts.cycleId ?? '', signalFingerprint: key, fetchTokens: 0 });
+        }
+        catch { /* emission must never break the reuse path */ }
+    }
+    return {
+        action: 'fetch',
+        candidate: toGeneCandidate(asset),
+        asset,
+        mode,
+        score: winner.score,
+        receipt: { fromCache: payloadCached, ...(creditCost !== undefined ? { creditCost } : {}) },
+        zeroHubCalls,
+    };
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+function isAssetByIdFetcher(value) {
+    return typeof value.fetchAssetById === 'function';
+}
+export function assetMatchesId(asset, assetId) {
+    return Boolean(asset && asset.asset_id === assetId);
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export declare const PACKAGE = "@evomap/evolver-adapter-public";
+export * from './auth/machineId.js';
+export * from './auth/credentialStore.js';
+export * from './auth/keypair.js';
+export * from './auth/legacyShim.js';
+export * from './auth/oauthDeviceToken.js';
+export * from './auth/oauthHttpTransport.js';
+export * from './hubFetch.js';
+export * from './wireMap.js';
+export * from './hubCapability.js';
+export * from './antiAbuseTelemetry.js';
+export * from './offlinePermit.js';
+export * from './hubReuse.js';
+export * from './atp.js';
+export * from './pricing/modelPrices.js';
+export * from './connect.js';

package/dist/index.js

@@ -0,0 +1,16 @@
+export const PACKAGE = '@evomap/evolver-adapter-public';
+export * from './auth/machineId.js';
+export * from './auth/credentialStore.js';
+export * from './auth/keypair.js';
+export * from './auth/legacyShim.js';
+export * from './auth/oauthDeviceToken.js';
+export * from './auth/oauthHttpTransport.js';
+export * from './hubFetch.js';
+export * from './wireMap.js';
+export * from './hubCapability.js';
+export * from './antiAbuseTelemetry.js';
+export * from './offlinePermit.js';
+export * from './hubReuse.js';
+export * from './atp.js';
+export * from './pricing/modelPrices.js';
+export * from './connect.js';

package/dist/offlinePermit.d.ts

@@ -0,0 +1,74 @@
+import { type algo, type hub } from '@evomap/evolver-core';
+import { type FetchLike } from './hubFetch.js';
+export declare const DEFAULT_MAX_OFFLINE_SOLIDIFIES = 10;
+export declare const DEFAULT_MAX_OFFLINE_DURATION_MS: number;
+export declare const DEFAULT_MAX_CLOCK_DRIFT_MS: number;
+export interface OfflinePermitToken {
+    usedCount?: number;
+    maxOfflineSolidifies?: number;
+    expiresAt?: number;
+    [key: string]: unknown;
+}
+export type OfflinePermitFailure = 'no_offline_token' | 'clock_drift_detected' | 'offline_token_expired' | 'offline_duration_exceeded' | 'offline_quota_exhausted' | 'offline_permit_busy' | 'offline_lock_failed';
+export type OfflinePermitResult = {
+    ok: true;
+    offline: true;
+    remaining: number;
+} | {
+    ok: false;
+    offline: true;
+    error: OfflinePermitFailure;
+    detail?: string;
+};
+export interface OfflinePermitStoreOptions {
+    dir: string;
+    nodeSecret: string | (() => string | null | undefined) | null | undefined;
+    now?: () => number;
+    maxOfflineSolidifies?: number;
+    maxOfflineDurationMs?: number;
+    maxClockDriftMs?: number;
+    lock?: OfflinePermitLockOptions;
+}
+export interface OfflinePermitLockOptions {
+    maxTries?: number;
+    waitMs?: number;
+}
+export interface SolidifyPermitCheckOptions {
+    hubUrl: string;
+    auth: hub.AuthProvider;
+    senderId: () => string | undefined;
+    dir: string;
+    nodeSecret?: string | (() => string | null | undefined) | null | undefined;
+    fetchFn?: FetchLike;
+    now?: () => number;
+    store?: OfflinePermitStore;
+}
+/**
+ * HMAC-backed local offline permit counter.
+ *
+ * This ports v1 PR #157's concurrency fix into v2: the full
+ * load -> cap-check -> increment -> write pipeline is serialized with the
+ * shared PID-liveness file lock, so daemon and CLI processes cannot both
+ * consume the same local offline quota slot.
+ */
+export declare class OfflinePermitStore {
+    private readonly opts;
+    private readonly now;
+    private readonly maxOfflineSolidifies;
+    private readonly maxOfflineDurationMs;
+    private readonly maxClockDriftMs;
+    constructor(opts: OfflinePermitStoreOptions);
+    offlineTokenPath(): string;
+    lastVerifyPath(): string;
+    lockPath(): string;
+    cacheOfflineToken(token: OfflinePermitToken): boolean;
+    loadOfflineToken(): OfflinePermitToken | null;
+    recordLastOnlineVerify(ts?: number): boolean;
+    getLastOnlineVerifyTs(): number;
+    consumeOfflinePermit(): OfflinePermitResult;
+    private consumeLocked;
+    private nodeSecret;
+    private errorDetail;
+}
+export declare function createSolidifyPermitCheck(opts: SolidifyPermitCheckOptions): algo.SolidifyPermitGate;
+export declare function hmacSha256(key: string, data: string): string;