@meuecommerce/frete-adapter-node 0.3.1 → 0.4.1

package/dist/correiosLabelHttpClient.js

@@ -17,6 +17,16 @@
  */
 import { correiosApiUrl, } from "@meuecommerce/frete";
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Some Correios label messages are transient: the pré-postagem is fine and the
+ * PDF is still being produced, so a later poll succeeds (e.g. PPN-291 "O rótulo
+ * ainda não foi gerado. Por favor, consulte novamente."). Distinguish those from
+ * terminal ones — notably PPN-288 "status Pendente" — which won't clear by
+ * polling and must be surfaced. Retryable → keep polling; terminal → `message`.
+ */
+function isRetryableLabelMessage(msg) {
+    return /consulte novamente|ainda n[ãa]o foi gerado|n[ãa]o (foi )?gerado|PPN-291/i.test(msg);
+}
 export function createCorreiosLabelHttpClient(options = {}) {
     const { fetch = globalThis.fetch, baseUrl = correiosApiUrl, timeoutMs = 20000, retries = 2, retryDelayMs = 500, tipoRotulo = "P", downloadPath = "/prepostagem/v1/prepostagens/rotulo/download/assincrono/{idRecibo}", logger = console, } = options;
     if (typeof fetch !== "function") {
@@ -66,6 +76,12 @@ export function createCorreiosLabelHttpClient(options = {}) {
             }
             return json;
         },
+        async getPrepostagemStatus(id, token) {
+            const response = await fetchWithRetry(`${baseUrl}/prepostagem/v2/prepostagens?id=${encodeURIComponent(id)}&page=0&size=1`, { method: "GET", headers: authHeaders(token) });
+            const json = (await response.json().catch(() => ({})));
+            const item = Array.isArray(json.itens) ? json.itens[0] : undefined;
+            return item ?? null;
+        },
         async requestLabelPdf(ids, token) {
             const response = await fetchWithRetry(`${baseUrl}/prepostagem/v1/prepostagens/rotulo/assincrono/pdf`, {
                 method: "POST",
@@ -92,6 +108,9 @@ export function createCorreiosLabelHttpClient(options = {}) {
                 return { ready: false };
             if (response.status !== 200) {
                 const body = await response.text().catch(() => "");
+                // A retryable business message can arrive with a non-2xx status too.
+                if (isRetryableLabelMessage(body))
+                    return { ready: false };
                 return { ready: false, message: `http_${response.status}: ${body.slice(0, 200)}` };
             }
             // Correios may return the PDF as raw bytes (application/pdf) or wrapped in
@@ -104,8 +123,11 @@ export function createCorreiosLabelHttpClient(options = {}) {
             const pdfBase64 = (json.dados ?? json.pdf ?? json.base64 ?? json.arquivo);
             if (pdfBase64)
                 return { ready: true, pdfBase64 };
-            // 200 without a PDF carries a business message (e.g. "status Pendente").
+            // 200 without a PDF carries a business message (e.g. "status Pendente" or
+            // "ainda não foi gerado, consulte novamente"). Retryable ones → keep polling.
             const message = typeof json.mensagem === "string" ? json.mensagem : undefined;
+            if (message && isRetryableLabelMessage(message))
+                return { ready: false };
             return message ? { ready: false, message } : { ready: false };
         },
     };

package/dist/inMemoryDimensionMemory.d.ts

@@ -0,0 +1,10 @@
+import type { DimensionMemory, DimensionMemoryEntry, DimensionRecord, ProductIdentity } from "@meuecommerce/frete";
+export declare class InMemoryDimensionMemory implements DimensionMemory {
+    private readonly records;
+    constructor(seed?: DimensionMemoryEntry[]);
+    /** How many products the memory holds. For tests and local inspection. */
+    get size(): number;
+    get(identities: ProductIdentity[]): Promise<Map<string, DimensionRecord>>;
+    set(entries: DimensionMemoryEntry[]): Promise<void>;
+    invalidate(identities: ProductIdentity[]): Promise<void>;
+}

package/dist/inMemoryDimensionMemory.js

@@ -0,0 +1,55 @@
+/**
+ * In-memory `DimensionMemory` — local dev, the MCP server's local mode, and
+ * tests. Production swaps it for the Postgres-backed one; the core does not
+ * change.
+ *
+ * It enforces the layer rule rather than just storing what it is given: an
+ * agent guess (`L3`) must never overwrite what the merchant declared (`L0`).
+ * Putting that here as well as in the Postgres implementation is deliberate —
+ * it is a property of the memory, not of one backend, and the tests that pin it
+ * run against this one.
+ */
+import { canOverwrite, productKey } from "@meuecommerce/frete";
+export class InMemoryDimensionMemory {
+    records = new Map();
+    constructor(seed = []) {
+        // O seed passa pela mesma regra de camada que uma escrita normal.
+        void this.set(seed);
+    }
+    /** How many products the memory holds. For tests and local inspection. */
+    get size() {
+        return this.records.size;
+    }
+    async get(identities) {
+        const found = new Map();
+        for (const identity of identities) {
+            const key = productKey(identity);
+            if (!key)
+                continue;
+            const record = this.records.get(key.value);
+            if (record)
+                found.set(key.value, record);
+        }
+        return found;
+    }
+    async set(entries) {
+        for (const { identity, record } of entries) {
+            const key = productKey(identity);
+            // Sem chave derivável não há o que gravar: inventar uma faria produtos
+            // sem relação compartilharem entrada.
+            if (!key)
+                continue;
+            const existing = this.records.get(key.value);
+            if (existing && !canOverwrite(existing.source, record.source))
+                continue;
+            this.records.set(key.value, record);
+        }
+    }
+    async invalidate(identities) {
+        for (const identity of identities) {
+            const key = productKey(identity);
+            if (key)
+                this.records.delete(key.value);
+        }
+    }
+}

package/dist/index.d.ts

@@ -6,11 +6,18 @@
  */
 export { createCorreiosHttpClient } from "./correiosHttpClient.js";
 export type { CorreiosHttpClientOptions } from "./correiosHttpClient.js";
+export { createCorreiosLabelHttpClient } from "./correiosLabelHttpClient.js";
+export type { CorreiosLabelHttpClientOptions } from "./correiosLabelHttpClient.js";
 export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
 export type { InMemorySettingsStoreOptions } from "./inMemorySettingsStore.js";
+export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
 export type { EnvSecretStoreOptions } from "./envSecretStore.js";
-export { createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+export { DIMENSION_MEMORY_SCHEMA_SQL, PgDimensionMemory } from "./pgDimensionMemory.js";
+export type { PgDimensionMemoryOptions, SqlClient } from "./pgDimensionMemory.js";
+export type { OpenAIResponsesAgentRunnerOptions } from "./openAIResponsesAgentRunner.js";
 export type { OpenAIDimensionEstimatorOptions } from "./openAIDimensionEstimator.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";
 export type { OpenAIBoxDistributorOptions } from "./openAIBoxDistributor.js";

package/dist/index.js

@@ -5,7 +5,11 @@
  * Shopify/Fly deployment today, and the MCP server next.
  */
 export { createCorreiosHttpClient } from "./correiosHttpClient.js";
+export { createCorreiosLabelHttpClient } from "./correiosLabelHttpClient.js";
 export { InMemorySettingsStore } from "./inMemorySettingsStore.js";
+export { InMemoryDimensionMemory } from "./inMemoryDimensionMemory.js";
 export { EnvSecretStore } from "./envSecretStore.js";
-export { createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { DIMENSION_PROMPT_VERSION, createOpenAIDimensionEstimator } from "./openAIDimensionEstimator.js";
+export { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+export { DIMENSION_MEMORY_SCHEMA_SQL, PgDimensionMemory } from "./pgDimensionMemory.js";
 export { createOpenAIBoxDistributor } from "./openAIBoxDistributor.js";

package/dist/openAIDimensionEstimator.d.ts

@@ -1,24 +1,44 @@
 /**
- * `ProductDimensionEstimator` implemented with the OpenAI chat-completions API.
+ * `ProductDimensionEstimator` implemented with the OpenAI Responses API and a
+ * strict structured output.
  *
  * Ports the dimension-estimation path from the Velo `openAI/` modules:
- * - `ai-tools.js`      -> the `estimate_dimensions` tool + request/response handling
+ * - `ai-tools.js`      -> request/response handling (was a forced tool call)
  * - `prompt-methods.js`-> `createDimensionEstimationPrompt`
  * - `box-methods.js`   -> `validateAndOptimizeDimensions` (post-process AI output)
  *
+ * Why the move off chat-completions with a forced tool call: a tool call is a
+ * request for a shape, not a guarantee of one — the arguments still arrive as a
+ * string that can be truncated or malformed, which is why the old code had to
+ * `JSON.parse` and hope. `text.format` with `strict: true` makes the schema a
+ * constraint on decoding instead, so a missing field or an extra one cannot
+ * come back at all.
+ *
  * `fetch` is injectable (defaults to global fetch) so this also runs under Velo
  * with `wix-fetch` passed in. The API key is passed in — the caller resolves it
  * (e.g. via a `SecretStore`), keeping secret handling out of this module.
  */
-import type { ProductDimensionEstimator } from "@meuecommerce/frete";
+import type { LlmAgentRunner, ProductDimensionEstimator } from "@meuecommerce/frete";
 type FetchLike = typeof globalThis.fetch;
+/**
+ * Bump whenever the prompt or the schema changes. It is written next to every
+ * `L3` record so a prompt change can invalidate stale estimates in background
+ * instead of at checkout.
+ */
+export declare const DIMENSION_PROMPT_VERSION = "2026-09-04.responses.v1";
 export interface OpenAIDimensionEstimatorOptions {
-    apiKey: string;
+    apiKey?: string;
     fetch?: FetchLike;
     model?: string;
     temperature?: number;
     apiUrl?: string;
     timeoutMs?: number;
+    /**
+     * Run the call through an existing {@link LlmAgentRunner} instead of building
+     * one. Pass it to share a runner across use cases, or to substitute the
+     * transport in tests; omit it and one is created from `apiKey`.
+     */
+    runner?: LlmAgentRunner;
 }
 export declare function createOpenAIDimensionEstimator(options: OpenAIDimensionEstimatorOptions): ProductDimensionEstimator;
 export {};

package/dist/openAIDimensionEstimator.js

@@ -1,28 +1,38 @@
-const ESTIMATE_DIMENSIONS_TOOL = {
-    type: "function",
-    function: {
-        name: "estimate_dimensions",
-        description: "Estima dimensões de produtos PRESERVANDO os nomes exatos fornecidos",
-        parameters: {
-            type: "object",
-            properties: {
-                products: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            name: { type: "string" },
-                            length: { type: "number", description: "Comprimento em cm" },
-                            width: { type: "number", description: "Largura em cm" },
-                            height: { type: "number", description: "Altura em cm" },
-                        },
-                        required: ["name", "length", "width", "height"],
-                    },
+import { createOpenAIResponsesAgentRunner } from "./openAIResponsesAgentRunner.js";
+/**
+ * Bump whenever the prompt or the schema changes. It is written next to every
+ * `L3` record so a prompt change can invalidate stale estimates in background
+ * instead of at checkout.
+ */
+export const DIMENSION_PROMPT_VERSION = "2026-09-04.responses.v1";
+/**
+ * Strict JSON schema for the response.
+ *
+ * `strict: true` has two requirements that are easy to miss and reject the
+ * whole request when absent: every object needs `additionalProperties: false`,
+ * and `required` has to list every property — optional fields are not allowed.
+ */
+const DIMENSIONS_SCHEMA = {
+    type: "object",
+    properties: {
+        products: {
+            type: "array",
+            description: "Uma entrada por produto pedido, na mesma ordem.",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "O nome EXATO recebido, sem reescrever" },
+                    length: { type: "number", description: "Comprimento em cm" },
+                    width: { type: "number", description: "Largura em cm" },
+                    height: { type: "number", description: "Altura em cm" },
                 },
+                required: ["name", "length", "width", "height"],
+                additionalProperties: false,
             },
-            required: ["products"],
         },
     },
+    required: ["products"],
+    additionalProperties: false,
 };
 function largestBox(boxes) {
     return boxes.reduce((largest, current) => current.width * current.height * current.length > largest.width * largest.height * largest.length ? current : largest);
@@ -40,8 +50,7 @@ function createPrompt(products, boxes, samples) {
         `🚨 LIMITES FÍSICOS OBRIGATÓRIOS:\n- Largura máxima: ${maxWidth}cm\n- Altura máxima: ${maxHeight}cm\n- Comprimento máximo: ${maxLength}cm\n(Maior caixa: ${box.name ?? "—"})\n\n` +
         `📦 PRODUTOS PARA ESTIMAR:\n${products.map((p, i) => `${i + 1}. ${p.name} - ${p.quantity}x (${p.weight}kg cada)`).join("\n")}\n` +
         samplesSection +
-        `\n⚠️ REGRAS: respeite os limites; preserve os nomes EXATOS; retorne length×width×height em cm.\n` +
-        `Responda usando a função 'estimate_dimensions'.`);
+        `\n⚠️ REGRAS: respeite os limites; preserve os nomes EXATOS; retorne length×width×height em cm.`);
 }
 /** Apply the largest-box physical limits + a minimum-volume floor to AI output. */
 function validateAndOptimize(aiResult, products, boxes) {
@@ -76,52 +85,32 @@ function validateAndOptimize(aiResult, products, boxes) {
     return { products: optimized };
 }
 export function createOpenAIDimensionEstimator(options) {
-    const { apiKey, fetch = globalThis.fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl = "https://api.openai.com/v1/chat/completions", timeoutMs = 20000, } = options;
-    if (!apiKey)
-        throw new Error("createOpenAIDimensionEstimator: apiKey is required");
-    if (typeof fetch !== "function")
-        throw new Error("createOpenAIDimensionEstimator: no fetch available");
+    const { apiKey, fetch, model = "gpt-4o-mini", temperature = 0.1, apiUrl, timeoutMs, runner } = options;
+    const agent = runner ??
+        createOpenAIResponsesAgentRunner({
+            apiKey: apiKey ?? "",
+            ...(fetch ? { fetch } : {}),
+            model,
+            ...(apiUrl ? { apiUrl } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
     return {
         async estimate(products, boxes, productSamples = []) {
             if (!boxes.length)
                 throw new Error("estimate: no boxes provided");
-            const body = {
-                model,
-                messages: [
-                    {
-                        role: "system",
-                        content: "Você é um especialista em dimensões de produtos. Use os exemplos personalizados como prioridade máxima quando o nome bater.",
-                    },
-                    { role: "user", content: createPrompt(products, boxes, productSamples) },
-                ],
-                tools: [ESTIMATE_DIMENSIONS_TOOL],
-                tool_choice: { type: "function", function: { name: "estimate_dimensions" } },
+            const result = await agent.run({
+                task: "estimate-dimensions",
+                promptVersion: DIMENSION_PROMPT_VERSION,
+                system: "Você é um especialista em dimensões de produtos. Use os exemplos personalizados como prioridade máxima quando o nome bater.",
+                user: createPrompt(products, boxes, productSamples),
+                schema: { name: "product_dimensions", schema: DIMENSIONS_SCHEMA },
                 temperature,
-            };
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), timeoutMs);
-            let response;
-            try {
-                response = await fetch(apiUrl, {
-                    method: "POST",
-                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
-                    body: JSON.stringify(body),
-                    signal: controller.signal,
-                });
+            });
+            if (!Array.isArray(result.output?.products)) {
+                throw new Error("Resposta da IA sem a lista de produtos");
             }
-            finally {
-                clearTimeout(timer);
-            }
-            if (!response.ok)
-                throw new Error(`OpenAI API Error: ${response.status} ${response.statusText}`);
-            const json = (await response.json());
-            if (json.error)
-                throw new Error(`OpenAI Error: ${json.error.message}`);
-            const args = json.choices?.[0]?.message?.tool_calls?.[0]?.function?.arguments;
-            if (!args)
-                throw new Error("IA não conseguiu estimar dimensões dos produtos");
-            const parsed = JSON.parse(args);
-            return validateAndOptimize(parsed, products, boxes);
+            const validated = validateAndOptimize(result.output, products, boxes);
+            return result.usage ? { ...validated, usage: result.usage } : validated;
         },
     };
 }

package/dist/openAIResponsesAgentRunner.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `LlmAgentRunner` on the OpenAI Responses API.
+ *
+ * One call, one strict schema, no re-ask. It owns everything provider-shaped —
+ * the endpoint, the structured-output envelope, reading the answer out of the
+ * two shapes the API returns it in, refusals, and token accounting — so each
+ * use case is left with only its prompt, its schema and its own validation.
+ *
+ * `fetch` is injectable (defaults to global fetch) so this also runs under Velo
+ * with `wix-fetch` passed in. The API key is passed in — the caller resolves it,
+ * keeping secret handling out of this module.
+ */
+import type { LlmAgentRunner } from "@meuecommerce/frete";
+type FetchLike = typeof globalThis.fetch;
+export interface OpenAIResponsesAgentRunnerOptions {
+    apiKey: string;
+    fetch?: FetchLike;
+    model?: string;
+    apiUrl?: string;
+    timeoutMs?: number;
+}
+interface ResponsesPayload {
+    error?: {
+        message?: string;
+    };
+    model?: string;
+    /** Convenience field with the text already concatenated. */
+    output_text?: string;
+    output?: Array<{
+        content?: Array<{
+            type?: string;
+            text?: string;
+            refusal?: string;
+        }>;
+    }>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+/** The model's text, accepting both shapes the Responses API delivers it in. */
+export declare function extractOutputText(json: ResponsesPayload): string;
+/**
+ * A refusal is a *successful* response in which the model declined to fill the
+ * schema. Without this check it would read as empty text and be reported as
+ * "the model could not answer", hiding the real reason.
+ */
+export declare function findRefusal(json: ResponsesPayload): string | null;
+export declare function createOpenAIResponsesAgentRunner(options: OpenAIResponsesAgentRunnerOptions): LlmAgentRunner;
+export {};

package/dist/openAIResponsesAgentRunner.js

@@ -0,0 +1,114 @@
+/** The model's text, accepting both shapes the Responses API delivers it in. */
+export function extractOutputText(json) {
+    if (typeof json.output_text === "string" && json.output_text.trim())
+        return json.output_text;
+    const parts = [];
+    for (const item of json.output ?? []) {
+        for (const content of item.content ?? []) {
+            if (typeof content.text === "string")
+                parts.push(content.text);
+        }
+    }
+    return parts.join("").trim();
+}
+/**
+ * A refusal is a *successful* response in which the model declined to fill the
+ * schema. Without this check it would read as empty text and be reported as
+ * "the model could not answer", hiding the real reason.
+ */
+export function findRefusal(json) {
+    for (const item of json.output ?? []) {
+        for (const content of item.content ?? []) {
+            if (typeof content.refusal === "string" && content.refusal)
+                return content.refusal;
+        }
+    }
+    return null;
+}
+export function createOpenAIResponsesAgentRunner(options) {
+    const { apiKey, fetch = globalThis.fetch, model: defaultModel = "gpt-4o-mini", apiUrl = "https://api.openai.com/v1/responses", timeoutMs = 20000, } = options;
+    if (!apiKey)
+        throw new Error("createOpenAIResponsesAgentRunner: apiKey is required");
+    if (typeof fetch !== "function")
+        throw new Error("createOpenAIResponsesAgentRunner: no fetch available");
+    return {
+        async run(request) {
+            const input = [];
+            if (request.system)
+                input.push({ role: "system", content: request.system });
+            // `images` ainda não é usado pelo estimador; quando a fase 2 ligar, o
+            // conteúdo do turno do usuário vira lista em vez de string.
+            if (request.images?.length) {
+                input.push({
+                    role: "user",
+                    content: [
+                        { type: "input_text", text: request.user },
+                        ...request.images.map((url) => ({ type: "input_image", image_url: url })),
+                    ],
+                });
+            }
+            else {
+                input.push({ role: "user", content: request.user });
+            }
+            const body = {
+                model: defaultModel,
+                input,
+                text: {
+                    format: {
+                        type: "json_schema",
+                        name: request.schema.name,
+                        strict: true,
+                        schema: request.schema.schema,
+                    },
+                },
+            };
+            if (request.temperature !== undefined)
+                body.temperature = request.temperature;
+            if (request.maxOutputTokens !== undefined)
+                body.max_output_tokens = request.maxOutputTokens;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            try {
+                response = await fetch(apiUrl, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!response.ok)
+                throw new Error(`OpenAI API Error: ${response.status} ${response.statusText}`);
+            const json = (await response.json());
+            if (json.error)
+                throw new Error(`OpenAI Error: ${json.error.message}`);
+            const refusal = findRefusal(json);
+            if (refusal)
+                throw new Error(`OpenAI recusou a resposta de ${request.task}: ${refusal}`);
+            const text = extractOutputText(json);
+            if (!text)
+                throw new Error(`Resposta vazia da IA para ${request.task}`);
+            let output;
+            try {
+                output = JSON.parse(text);
+            }
+            catch {
+                throw new Error(`Resposta da IA para ${request.task} não é JSON válido`);
+            }
+            const model = json.model ?? defaultModel;
+            const usage = json.usage
+                ? {
+                    model,
+                    ...(typeof json.usage.input_tokens === "number" ? { inputTokens: json.usage.input_tokens } : {}),
+                    ...(typeof json.usage.output_tokens === "number" ? { outputTokens: json.usage.output_tokens } : {}),
+                }
+                : undefined;
+            // Sempre 1 nesta fase: a repescagem por falha de validação é o próximo
+            // passo, e é ela que vai fazer este número variar.
+            return usage ? { output, usage, model, attempts: 1 } : { output, model, attempts: 1 };
+        },
+    };
+}

package/dist/pgDimensionMemory.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Postgres-backed `DimensionMemory` — the production counterpart of
+ * {@link InMemoryDimensionMemory}.
+ *
+ * Two rules from the port are enforced here in SQL rather than in application
+ * code, because the memory is written from more than one place (the quote path,
+ * the label feedback, the dashboard) and a check that lives in one caller is a
+ * check that the next caller forgets:
+ *
+ * - **A weaker layer never overwrites a stronger one.** The upsert carries the
+ *   layer's rank and only updates when the incoming rank is at least as strong,
+ *   so an agent estimate racing with a merchant's correction loses regardless of
+ *   which arrives last.
+ * - **One round trip per cart.** `get` takes every product at once, because a
+ *   query per line item is exactly what makes a hot path slow.
+ *
+ * The client is the structural {@link SqlClient} rather than a `pg` import, so
+ * this package gains no runtime dependency and the tests can run real SQL
+ * against pg-mem with no network.
+ *
+ * Lookups expand to `IN ($1, $2, …)` instead of the more idiomatic
+ * `= ANY($1)`. Real Postgres accepts both, but pg-mem silently returns zero
+ * rows for the array form, and running the tests against real SQL is worth more
+ * than the tidier query — a cart is a handful of line items, so the parameter
+ * count is not a concern. Revisit if this is ever used for bulk reads.
+ */
+import { canOverwrite } from "@meuecommerce/frete";
+import type { DimensionMemory, DimensionMemoryEntry, DimensionRecord, ProductIdentity } from "@meuecommerce/frete";
+/**
+ * Minimal query surface — satisfied structurally by a node-postgres
+ * `Pool`/`Client` and by pg-mem's adapter.
+ */
+export interface SqlClient {
+    query<R extends Record<string, unknown> = Record<string, unknown>>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+export declare const DIMENSION_MEMORY_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS dimension_memory (\n  key             TEXT PRIMARY KEY,\n  instance_id     TEXT NOT NULL,\n  length_cm       DOUBLE PRECISION NOT NULL,\n  width_cm        DOUBLE PRECISION NOT NULL,\n  height_cm       DOUBLE PRECISION NOT NULL,\n  attrs           JSONB,\n  confidence      DOUBLE PRECISION NOT NULL,\n  source          TEXT NOT NULL,\n  layer_rank      INTEGER NOT NULL,\n  prompt_version  TEXT,\n  model           TEXT,\n  updated_at      TIMESTAMPTZ NOT NULL\n);\nCREATE INDEX IF NOT EXISTS dimension_memory_instance_idx ON dimension_memory (instance_id);\n";
+export interface PgDimensionMemoryOptions {
+    sql: SqlClient;
+}
+export declare class PgDimensionMemory implements DimensionMemory {
+    private readonly sql;
+    constructor(options: PgDimensionMemoryOptions);
+    /** Idempotent — safe to call on every boot. */
+    migrate(): Promise<void>;
+    get(identities: ProductIdentity[]): Promise<Map<string, DimensionRecord>>;
+    set(entries: DimensionMemoryEntry[]): Promise<void>;
+    invalidate(identities: ProductIdentity[]): Promise<void>;
+    /**
+     * Drop agent estimates produced by an older prompt.
+     *
+     * Only touches `L3`: what the merchant declared and what a real label proved
+     * do not go stale because we changed a prompt. Meant to run in background
+     * after a prompt bump — never on the quote path.
+     */
+    invalidateStaleEstimates(currentPromptVersion: string): Promise<number>;
+    /** Forget everything for one merchant — uninstall, or a support reset. */
+    forgetInstance(instanceId: string): Promise<number>;
+}
+/** Re-exported so callers can reason about precedence without importing core. */
+export { canOverwrite };