@vauban-org/agent-sdk 0.16.0

package/dist/counterfactual/replay-with-alt.js

@@ -0,0 +1,191 @@
+/**
+ * OFFLINE TOOL. NOT a centerpiece. Use for ex-post analysis only —
+ * never wire into live runtime.
+ *
+ * replayCounterfactual — counterfactual replay primitive.
+ *
+ * Given an original runId, replays the same cycle with an alternative compute
+ * strategy (or verifier / temperature override). The original run's
+ * clock/random/cache are kept fixed — only the compute strategy is swapped.
+ *
+ * Purpose: offline "what-if" analysis. E.g. "what if this cycle had used
+ * best-of-n instead of single-shot?"
+ *
+ * Design invariants:
+ *   - Does NOT mutate the original trace or any live execution path.
+ *   - ReplayRunner.run() receives a ReplayContext augmented with strategyOverride
+ *     injected into the runner's compute config.
+ *   - "outputsCoherent" = same runtime type AND same top-level keys (for objects).
+ *   - "outputsIdentical" = deep structural equality via JSON serialisation.
+ *
+ * @module counterfactual/replay-with-alt
+ */
+import { RecordedClock } from "../replay/clock.js";
+import { RecordedRandom } from "../replay/random.js";
+/** All valid strategy names as a frozen set for runtime validation. */
+const VALID_STRATEGY_NAMES = new Set([
+    "single-shot",
+    "best-of-n",
+    "bon-mav",
+]);
+// ─── InvalidStrategyNameError ─────────────────────────────────────────────────
+/**
+ * Thrown when alt_strategy is not one of the known ComputeStrategyName values.
+ */
+export class InvalidStrategyNameError extends Error {
+    name;
+    constructor(name) {
+        super(`replayCounterfactual: unknown alt_strategy "${name}". ` +
+            `Valid values: ${[...VALID_STRATEGY_NAMES].join(", ")}.`);
+        this.name = name;
+        this.name = "InvalidStrategyNameError";
+    }
+}
+// ─── Coherence check ─────────────────────────────────────────────────────────
+/**
+ * Determine structural coherence between two outputs.
+ *
+ * Two outputs are "coherent" when:
+ *   1. Both have the same typeof (e.g. both "string", both "object").
+ *   2. If both are non-null plain objects: same set of top-level keys
+ *      (set equality, order-independent).
+ *   3. Special case: both null → coherent (typeof null === "object" in JS,
+ *      but we treat null explicitly).
+ */
+function areCoherent(a, b) {
+    // Handle null explicitly (typeof null === "object" would be misleading)
+    if (a === null && b === null)
+        return true;
+    if (a === null || b === null)
+        return false;
+    const ta = typeof a;
+    const tb = typeof b;
+    if (ta !== tb)
+        return false;
+    // Both non-null objects: compare top-level key sets
+    if (ta === "object") {
+        const keysA = Object.keys(a).sort();
+        const keysB = Object.keys(b).sort();
+        if (keysA.length !== keysB.length)
+            return false;
+        for (let i = 0; i < keysA.length; i++) {
+            if (keysA[i] !== keysB[i])
+                return false;
+        }
+        return true;
+    }
+    // Primitives (string, number, boolean, etc.) — same typeof is sufficient
+    return true;
+}
+// ─── replayCounterfactual ─────────────────────────────────────────────────────
+/**
+ * Replay the original cycle twice — once with its original config, once with
+ * the alt overrides — and compare outputs.
+ *
+ * Both runs use the SAME virtualized clock, random, and LLM cache derived from
+ * the original run's recorded artifacts. Only the compute strategy (and optional
+ * verifier / temperature) differs.
+ *
+ * OFFLINE TOOL. Do NOT call from any live execution path.
+ *
+ * @param originalRunId  runId of the run to analyse counterfactually.
+ * @param loader         Loader for the original trace + recorded artifacts.
+ * @param runner         Runner that accepts CounterfactualReplayContext.
+ *                       Contract: runner.run() MUST honour ctx.strategyOverride
+ *                       when present.
+ * @param opts           Counterfactual overrides (at least one should differ
+ *                       from the original to be meaningful).
+ */
+export async function replayCounterfactual(originalRunId, loader, runner, opts) {
+    // ── Validate alt_strategy early ────────────────────────────────────────────
+    if (opts.alt_strategy !== undefined && !VALID_STRATEGY_NAMES.has(opts.alt_strategy)) {
+        throw new InvalidStrategyNameError(opts.alt_strategy);
+    }
+    // ── Load original artifacts ─────────────────────────────────────────────────
+    const [originalTrace, artifacts] = await Promise.all([
+        loader.loadOriginalTrace(originalRunId),
+        loader.loadCacheEntries(originalRunId),
+    ]);
+    // ── Determine original strategy from trace metadata (best-effort) ──────────
+    // Runners may embed the strategy name in trace steps or config.
+    // We look for it in originalTrace.config as a convention.
+    const traceConfig = originalTrace.config;
+    const originalStrategyName = typeof traceConfig?.strategy === "string" ? traceConfig.strategy : "unknown";
+    // ── Build two independent virtualised contexts ──────────────────────────────
+    // Each gets a fresh RecordedClock/RecordedRandom so they don't share cursors.
+    const buildCtx = (replayRunId, overrides) => {
+        const clock = new RecordedClock([...artifacts.recordedTs]);
+        const random = new RecordedRandom([...artifacts.recordedNext], [...artifacts.recordedUuids], "strict");
+        return {
+            originalRunId,
+            replayRunId,
+            mode: "strict",
+            clock,
+            random,
+            cache: artifacts.cache,
+            ...overrides,
+        };
+    };
+    const originalReplayRunId = globalThis.crypto.randomUUID();
+    const counterfactualRunId = globalThis.crypto.randomUUID();
+    const originalCtx = buildCtx(originalReplayRunId, {
+    // No overrides — reproduce original behaviour
+    });
+    const counterfactualCtx = buildCtx(counterfactualRunId, {
+        strategyOverride: opts.alt_strategy,
+        verifierOverride: opts.alt_verifier,
+        temperatureOverride: opts.alt_temperature,
+    });
+    // ── Run both scenarios ──────────────────────────────────────────────────────
+    const t0Original = performance.now();
+    const originalReplayTrace = await runner.run(originalCtx, originalTrace);
+    const originalLatency = performance.now() - t0Original;
+    const t0Cf = performance.now();
+    const counterfactualTrace = await runner.run(counterfactualCtx, originalTrace);
+    const cfLatency = performance.now() - t0Cf;
+    // ── Extract outputs ─────────────────────────────────────────────────────────
+    const originalOutput = originalReplayTrace.output ?? originalReplayTrace;
+    const counterfactualOutput = counterfactualTrace.output ?? counterfactualTrace;
+    // ── Compute comparisons ─────────────────────────────────────────────────────
+    const outputsIdentical = JSON.stringify(originalOutput) === JSON.stringify(counterfactualOutput);
+    const outputsCoherent = outputsIdentical || areCoherent(originalOutput, counterfactualOutput);
+    // ── Build metadata ──────────────────────────────────────────────────────────
+    const strategySwapped = opts.alt_strategy !== undefined
+        ? { from: originalStrategyName, to: opts.alt_strategy }
+        : undefined;
+    const originalCostUsd = originalReplayTrace.cost_usd;
+    const cfCostUsd = counterfactualTrace.cost_usd;
+    const cost_delta_usd = typeof originalCostUsd === "number" && typeof cfCostUsd === "number"
+        ? cfCostUsd - originalCostUsd
+        : undefined;
+    // Use runner-reported latency when available, fall back to wall-clock
+    const origLatencyMs = typeof originalReplayTrace.latency_ms === "number"
+        ? originalReplayTrace.latency_ms
+        : originalLatency;
+    const cfLatencyMs = typeof counterfactualTrace.latency_ms === "number"
+        ? counterfactualTrace.latency_ms
+        : cfLatency;
+    const latency_delta_ms = cfLatencyMs - origLatencyMs;
+    const cacheHits = typeof counterfactualTrace.cacheHits === "number"
+        ? counterfactualTrace.cacheHits
+        : 0;
+    const cacheMisses = typeof counterfactualTrace.cacheMisses === "number"
+        ? counterfactualTrace.cacheMisses
+        : 0;
+    return {
+        originalRunId,
+        counterfactualRunId,
+        originalOutput,
+        counterfactualOutput,
+        outputsCoherent,
+        outputsIdentical,
+        metadata: {
+            strategySwapped,
+            cost_delta_usd,
+            latency_delta_ms,
+            cacheHits,
+            cacheMisses,
+        },
+    };
+}
+//# sourceMappingURL=replay-with-alt.js.map

package/dist/counterfactual/replay-with-alt.js.map

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

package/dist/dataops/index.d.ts

@@ -0,0 +1,5 @@
+export { VoyagerDataOps, VoyagerRpcError } from "./voyager.js";
+export type { VoyagerConfig, WalletEvent, HealthCheckResult } from "./voyager.js";
+export { StarkscanDataOps, StarkscanError } from "./starkscan.js";
+export type { StarkscanConfig } from "./starkscan.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dataops/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dataops/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/dataops/index.js

@@ -0,0 +1,3 @@
+export { VoyagerDataOps, VoyagerRpcError } from "./voyager.js";
+export { StarkscanDataOps, StarkscanError } from "./starkscan.js";
+//# sourceMappingURL=index.js.map

package/dist/dataops/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dataops/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/dataops/starkscan.d.ts

@@ -0,0 +1,13 @@
+/**
+ * StarkscanDataOps — minimal wrapper.
+ *
+ * Starkscan (starkscan.co) merged into Voyager (voyager.online) as of 2025-2026.
+ * This wrapper re-exports VoyagerDataOps with Starkscan-idiomatic naming.
+ * The underlying RPC endpoint is the same Nethermind free tier.
+ *
+ * If the Starkscan indexed REST API (starkscan.co/api-info) becomes separately
+ * available with a subscription key, replace the implementation below.
+ */
+export { VoyagerDataOps as StarkscanDataOps, VoyagerRpcError as StarkscanError } from "./voyager.js";
+export type { VoyagerConfig as StarkscanConfig, WalletEvent, HealthCheckResult } from "./voyager.js";
+//# sourceMappingURL=starkscan.d.ts.map

package/dist/dataops/starkscan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"starkscan.d.ts","sourceRoot":"","sources":["../../src/dataops/starkscan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,IAAI,gBAAgB,EAAE,eAAe,IAAI,cAAc,EAAE,MAAM,cAAc,CAAC;AACrG,YAAY,EAAE,aAAa,IAAI,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/dataops/starkscan.js

@@ -0,0 +1,12 @@
+/**
+ * StarkscanDataOps — minimal wrapper.
+ *
+ * Starkscan (starkscan.co) merged into Voyager (voyager.online) as of 2025-2026.
+ * This wrapper re-exports VoyagerDataOps with Starkscan-idiomatic naming.
+ * The underlying RPC endpoint is the same Nethermind free tier.
+ *
+ * If the Starkscan indexed REST API (starkscan.co/api-info) becomes separately
+ * available with a subscription key, replace the implementation below.
+ */
+export { VoyagerDataOps as StarkscanDataOps, VoyagerRpcError as StarkscanError } from "./voyager.js";
+//# sourceMappingURL=starkscan.js.map

package/dist/dataops/starkscan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starkscan.js","sourceRoot":"","sources":["../../src/dataops/starkscan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,IAAI,gBAAgB,EAAE,eAAe,IAAI,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/dataops/voyager.d.ts

@@ -0,0 +1,58 @@
+/**
+ * VoyagerDataOps — thin wrapper over Starknet JSON-RPC (free tier).
+ *
+ * Uses the Nethermind free RPC endpoint (no API key required).
+ * Rate-limited via configurable inter-call delay.
+ * No indexed REST API — pure JSON-RPC v0.7.
+ */
+export interface VoyagerConfig {
+    /** Starknet JSON-RPC endpoint URL. Defaults to Nethermind free tier. */
+    rpcUrl?: string;
+    /** Minimum ms between consecutive RPC calls. Default: 100ms. */
+    rateLimitMs?: number;
+    /** Max events per getEvents call. Default: 1000. */
+    chunkSize?: number;
+}
+export interface WalletEvent {
+    walletAddress: string;
+    txHash: string;
+    blockNumber: number;
+    eventData: string[];
+}
+export interface HealthCheckResult {
+    blockNumber: number;
+    latencyMs: number;
+}
+export declare class VoyagerDataOps {
+    private readonly rpcUrl;
+    private readonly rateLimitMs;
+    private readonly chunkSize;
+    private lastCallAt;
+    private requestId;
+    constructor(config?: VoyagerConfig);
+    /**
+     * Extract unique wallet addresses that interacted with a protocol contract.
+     * Uses starknet_getEvents; the first element of event.data is the caller.
+     *
+     * @param contractAddress - Protocol contract (e.g. zkLend main contract)
+     * @param eventSelector   - Event key selector (hex string, e.g. Deposit event)
+     * @param limit           - Max wallets to return. Default: 100.
+     */
+    getProtocolWallets(contractAddress: string, eventSelector: string, limit?: number): Promise<string[]>;
+    /**
+     * Get events emitted by a specific wallet address for a given contract.
+     */
+    getWalletEvents(walletAddress: string, contractAddress: string, eventSelector: string): Promise<WalletEvent[]>;
+    /**
+     * Verify RPC connectivity and return current block number + latency.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    private getEvents;
+    private rpcCall;
+    private throttle;
+}
+export declare class VoyagerRpcError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+//# sourceMappingURL=voyager.d.ts.map

package/dist/dataops/voyager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voyager.d.ts","sourceRoot":"","sources":["../../src/dataops/voyager.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AA2BD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAK;gBAEV,MAAM,GAAE,aAAkB;IAMtC;;;;;;;OAOG;IACG,kBAAkB,CACtB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,EACrB,KAAK,SAAM,GACV,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBpB;;OAEG;IACG,eAAe,CACnB,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC;IAiBzB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;YAQjC,SAAS;YAUT,OAAO;YA6BP,QAAQ;CAQvB;AAID,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B"}

package/dist/dataops/voyager.js

@@ -0,0 +1,146 @@
+/**
+ * VoyagerDataOps — thin wrapper over Starknet JSON-RPC (free tier).
+ *
+ * Uses the Nethermind free RPC endpoint (no API key required).
+ * Rate-limited via configurable inter-call delay.
+ * No indexed REST API — pure JSON-RPC v0.7.
+ */
+import { z } from "zod";
+const DEFAULT_RPC_URL = "https://free-rpc.nethermind.io/mainnet-juno/";
+const DEFAULT_RATE_LIMIT_MS = 100;
+const DEFAULT_CHUNK_SIZE = 1000;
+// ─── Zod schemas (strict boundary validation) ────────────────────────────────
+const RpcResponseSchema = z.object({
+    jsonrpc: z.literal("2.0"),
+    id: z.number(),
+    result: z.unknown().optional(),
+    error: z
+        .object({ code: z.number(), message: z.string() })
+        .optional(),
+});
+const EventSchema = z.object({
+    transaction_hash: z.string(),
+    block_number: z.number(),
+    keys: z.array(z.string()),
+    data: z.array(z.string()),
+});
+const GetEventsResultSchema = z.object({
+    events: z.array(EventSchema),
+    continuation_token: z.string().optional(),
+});
+// ─── VoyagerDataOps ──────────────────────────────────────────────────────────
+export class VoyagerDataOps {
+    rpcUrl;
+    rateLimitMs;
+    chunkSize;
+    lastCallAt = 0;
+    requestId = 0;
+    constructor(config = {}) {
+        this.rpcUrl = config.rpcUrl ?? DEFAULT_RPC_URL;
+        this.rateLimitMs = config.rateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+        this.chunkSize = config.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    }
+    /**
+     * Extract unique wallet addresses that interacted with a protocol contract.
+     * Uses starknet_getEvents; the first element of event.data is the caller.
+     *
+     * @param contractAddress - Protocol contract (e.g. zkLend main contract)
+     * @param eventSelector   - Event key selector (hex string, e.g. Deposit event)
+     * @param limit           - Max wallets to return. Default: 100.
+     */
+    async getProtocolWallets(contractAddress, eventSelector, limit = 100) {
+        const wallets = new Set();
+        let continuationToken;
+        while (wallets.size < limit) {
+            const result = await this.getEvents({
+                address: contractAddress,
+                keys: [[eventSelector]],
+                chunk_size: Math.min(this.chunkSize, limit * 2),
+                continuation_token: continuationToken,
+            });
+            for (const event of result.events) {
+                const caller = event.data[0];
+                if (caller)
+                    wallets.add(caller);
+                if (wallets.size >= limit)
+                    break;
+            }
+            continuationToken = result.continuation_token;
+            if (!continuationToken)
+                break;
+        }
+        return Array.from(wallets).slice(0, limit);
+    }
+    /**
+     * Get events emitted by a specific wallet address for a given contract.
+     */
+    async getWalletEvents(walletAddress, contractAddress, eventSelector) {
+        const result = await this.getEvents({
+            address: contractAddress,
+            keys: [[eventSelector]],
+            chunk_size: this.chunkSize,
+        });
+        return result.events
+            .filter((e) => e.data[0] === walletAddress)
+            .map((e) => ({
+            walletAddress,
+            txHash: e.transaction_hash,
+            blockNumber: e.block_number,
+            eventData: e.data,
+        }));
+    }
+    /**
+     * Verify RPC connectivity and return current block number + latency.
+     */
+    async healthCheck() {
+        const t0 = Date.now();
+        const res = await this.rpcCall("starknet_blockNumber", []);
+        return { blockNumber: res, latencyMs: Date.now() - t0 };
+    }
+    // ─── Private helpers ───────────────────────────────────────────────────────
+    async getEvents(params) {
+        const raw = await this.rpcCall("starknet_getEvents", [params]);
+        return GetEventsResultSchema.parse(raw);
+    }
+    async rpcCall(method, params) {
+        await this.throttle();
+        const id = ++this.requestId;
+        const body = JSON.stringify({ jsonrpc: "2.0", method, params, id });
+        const response = await fetch(this.rpcUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+        if (!response.ok) {
+            throw new VoyagerRpcError(`HTTP ${response.status} from ${this.rpcUrl}`, response.status);
+        }
+        const raw = await response.json();
+        const parsed = RpcResponseSchema.parse(raw);
+        if (parsed.error) {
+            throw new VoyagerRpcError(parsed.error.message, parsed.error.code);
+        }
+        return parsed.result;
+    }
+    async throttle() {
+        const now = Date.now();
+        const elapsed = now - this.lastCallAt;
+        if (elapsed < this.rateLimitMs) {
+            await sleep(this.rateLimitMs - elapsed);
+        }
+        this.lastCallAt = Date.now();
+    }
+}
+// ─── Error ────────────────────────────────────────────────────────────────────
+export class VoyagerRpcError extends Error {
+    code;
+    constructor(message, code) {
+        super(`VoyagerRpcError(${code}): ${message}`);
+        this.code = code;
+        this.name = "VoyagerRpcError";
+    }
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=voyager.js.map

package/dist/dataops/voyager.js.map

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

package/dist/deprecation.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Deprecation helpers.
+ *
+ * Usage:
+ *   export function oldApi() {
+ *     deprecated("oldApi", { since: "0.3.0", replacement: "newApi" });
+ *     // ... legacy behaviour
+ *   }
+ *
+ * Behaviour:
+ *   - First call from a given source-location emits one console.warn.
+ *   - Subsequent calls from the same location are silent (deduped by
+ *     stack-frame fingerprint).
+ *   - Calls from a different source-location warn again.
+ *   - Tests can reset state via `_resetDeprecationWarnings()`.
+ *
+ * Policy (per CONTRACT.md):
+ *   - An API marked `@deprecated` at version X.Y.Z is removed at earliest
+ *     X.(Y+2).0 (N-2 minor window). Major bumps MAY remove sooner if
+ *     explicitly listed in the release notes.
+ */
+export interface DeprecationOptions {
+    /** Version at which the API was marked deprecated, e.g. "0.3.0". */
+    since?: string;
+    /** Name of the replacement API to recommend. */
+    replacement?: string;
+    /** Version at which removal is scheduled, e.g. "0.5.0". */
+    removeIn?: string;
+    /** Free-form rationale appended to the warning. */
+    note?: string;
+    /**
+     * Optional logger override (defaults to `console.warn`). Pass
+     * `noopLogger.warn` in tests that want silence without resetting state.
+     */
+    emit?: (message: string) => void;
+}
+/**
+ * Emit a one-time-per-call-site deprecation warning.
+ *
+ * Dedup key is the top-most user frame of the stack; SDK-internal frames
+ * and node:internal frames are skipped so the fingerprint reflects where
+ * the deprecated API is *called from* in consumer code.
+ */
+export declare function deprecated(apiName: string, options?: DeprecationOptions): void;
+/** Test helper — clears the per-call-site dedup set. */
+export declare function _resetDeprecationWarnings(): void;
+/** Test helper — returns a snapshot of the warned call-sites. */
+export declare function _deprecationWarnedCallSites(): readonly string[];
+//# sourceMappingURL=deprecation.d.ts.map

package/dist/deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../src/deprecation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,kBAAuB,GAC/B,IAAI,CAiBN;AAED,wDAAwD;AACxD,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,iEAAiE;AACjE,wBAAgB,2BAA2B,IAAI,SAAS,MAAM,EAAE,CAE/D"}

package/dist/deprecation.js

@@ -0,0 +1,84 @@
+/**
+ * Deprecation helpers.
+ *
+ * Usage:
+ *   export function oldApi() {
+ *     deprecated("oldApi", { since: "0.3.0", replacement: "newApi" });
+ *     // ... legacy behaviour
+ *   }
+ *
+ * Behaviour:
+ *   - First call from a given source-location emits one console.warn.
+ *   - Subsequent calls from the same location are silent (deduped by
+ *     stack-frame fingerprint).
+ *   - Calls from a different source-location warn again.
+ *   - Tests can reset state via `_resetDeprecationWarnings()`.
+ *
+ * Policy (per CONTRACT.md):
+ *   - An API marked `@deprecated` at version X.Y.Z is removed at earliest
+ *     X.(Y+2).0 (N-2 minor window). Major bumps MAY remove sooner if
+ *     explicitly listed in the release notes.
+ */
+const warnedCallSites = new Set();
+/**
+ * Emit a one-time-per-call-site deprecation warning.
+ *
+ * Dedup key is the top-most user frame of the stack; SDK-internal frames
+ * and node:internal frames are skipped so the fingerprint reflects where
+ * the deprecated API is *called from* in consumer code.
+ */
+export function deprecated(apiName, options = {}) {
+    const callSite = captureCallSite();
+    const key = `${apiName}@${callSite}`;
+    if (warnedCallSites.has(key))
+        return;
+    warnedCallSites.add(key);
+    const parts = [`[deprecated] ${apiName}`];
+    if (options.since)
+        parts.push(`since ${options.since}`);
+    if (options.removeIn)
+        parts.push(`removing in ${options.removeIn}`);
+    if (options.replacement)
+        parts.push(`use ${options.replacement}`);
+    if (options.note)
+        parts.push(options.note);
+    parts.push(`call-site: ${callSite}`);
+    const message = parts.join(" — ");
+    const emit = options.emit ?? ((m) => console.warn(m));
+    emit(message);
+}
+/** Test helper — clears the per-call-site dedup set. */
+export function _resetDeprecationWarnings() {
+    warnedCallSites.clear();
+}
+/** Test helper — returns a snapshot of the warned call-sites. */
+export function _deprecationWarnedCallSites() {
+    return Array.from(warnedCallSites);
+}
+// ─── Internal ────────────────────────────────────────────────────────────
+/**
+ * Capture the top user-land stack frame. Skips frames inside this file
+ * (deprecation.ts) and node internals. Returns `"unknown"` if unavailable.
+ */
+function captureCallSite() {
+    const err = new Error("deprecation-trace");
+    const stack = err.stack ?? "";
+    const lines = stack.split("\n").slice(1); // drop the "Error: ..." header
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("at "))
+            continue;
+        if (trimmed.includes("deprecation.ts"))
+            continue;
+        if (trimmed.includes("deprecation.js"))
+            continue;
+        if (trimmed.includes("node:internal/"))
+            continue;
+        // Normalise to "file:line:col" form
+        const match = trimmed.match(/\(([^)]+)\)/) ?? trimmed.match(/at (.+)/);
+        if (match?.[1])
+            return match[1];
+    }
+    return "unknown";
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","sourceRoot":"","sources":["../src/deprecation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;AAkB1C;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,UAA8B,EAAE;IAEhC,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAC;IAErC,IAAI,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO;IACrC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAEzB,MAAM,KAAK,GAAa,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACxD,IAAI,OAAO,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAClE,IAAI,OAAO,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,KAAK,CAAC,IAAI,CAAC,cAAc,QAAQ,EAAE,CAAC,CAAC;IAErC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,OAAO,CAAC,CAAC;AAChB,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,yBAAyB;IACvC,eAAe,CAAC,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,2BAA2B;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;AACrC,CAAC;AAED,4EAA4E;AAE5E;;;GAGG;AACH,SAAS,eAAe;IACtB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,+BAA+B;IAEzE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,SAAS;QACzC,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAAE,SAAS;QACjD,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAAE,SAAS;QACjD,IAAI,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAAE,SAAS;QACjD,oCAAoC;QACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACvE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}