modelrig 0.0.1 → 0.1.0

package/dist/telemetry/ingest-protocol.d.ts

@@ -0,0 +1,161 @@
+/**
+ * The telemetry wire contract — Phase 6 WS2.
+ *
+ * ONE definition of what a batch of telemetry looks like, and ONE function
+ * that turns a batch plus a tenant into the exact database writes it becomes.
+ * Both transports use them:
+ *
+ *   direct mode  exporter → stampBatch(batch, ownTenancy)  → PostgREST
+ *   api mode     exporter → POST /v1/ingest → server → stampBatch(batch, keyTenancy) → PostgREST
+ *
+ * telemetry-ingestion-boundary.md §4 requires that "the SDK must treat api
+ * mode and direct mode identically … one exporter interface, two transports —
+ * enforced by a shared conformance test". This module is what makes that
+ * enforceable rather than aspirational: the conformance test does not compare
+ * two hand-written mappers for similarity, it asserts that both paths run the
+ * SAME mapper. A drift bug has nowhere to live.
+ *
+ * ── WHY THE WIRE ROWS DO NOT CARRY A TENANT ──────────────────────────────
+ * T3: tenancy is derived from the principal, never trusted from the caller. A
+ * client that could put `org_id` on a row could put someone else's `org_id` on
+ * a row. So the wire carries the telemetry and nothing else, and the tenant is
+ * stamped by whoever holds the principal — the exporter's config in direct
+ * mode, the resolved key in api mode.
+ *
+ * The single exception is `feedback.org_id`, and it is the reason WS2 exists.
+ * A verdict recorded on OUR hosted server belongs to the org of the person who
+ * recorded it, not to the org the server runs as, and one SQLite store holds
+ * verdicts for many orgs. So a feedback row may name its own org — and the
+ * ingest endpoint VERIFIES that name against the key rather than trusting it
+ * (see `foreignOrgFeedback`). A service-role exporter needs no such check: it
+ * already holds a credential that can write any row in the database.
+ */
+import type { FailureClass } from "../types/failures";
+/** The path the api sink posts to. Spelled once. */
+export declare const INGEST_PATH = "/v1/ingest";
+/** Bumped only for a breaking change to the shapes below. A server that does
+ * not recognise the version refuses the batch rather than guessing. */
+export declare const INGEST_PROTOCOL_VERSION = 1;
+/** Default ingest host — telemetry-ingestion-boundary.md §2.1. */
+export declare const DEFAULT_INGEST_URL = "https://api.modelrig.ai";
+/** The tenant stamped onto every row. Resolved from the principal, never from
+ * the payload. */
+export interface Tenancy {
+    readonly org_id: string;
+    readonly project_id: string | null;
+    readonly source_id: string;
+}
+export interface WireInference {
+    readonly id: string;
+    readonly ts: string;
+    readonly route: string;
+    readonly route_version: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly requested_tier: string;
+    readonly served_tier: string;
+    readonly tokens_in: number;
+    readonly tokens_out: number;
+    readonly tokens_cached: number;
+    readonly cost_estimate_usd: number;
+    readonly latency_ms: number;
+    readonly ttfb_ms: number | null;
+    readonly failure_class: FailureClass | null;
+    readonly attempts: unknown;
+    readonly tags: unknown;
+    readonly fingerprint_cell: string | null;
+    readonly served_variant: string | null;
+    readonly repaired_by: string | null;
+    readonly pricing_missing: boolean;
+}
+export interface WireFeedback {
+    readonly id: string;
+    readonly ts: string;
+    readonly inference_id: string | null;
+    readonly episode_key: string | null;
+    readonly verdict: "up" | "down";
+    readonly score: number | null;
+    readonly note: string | null;
+    /** WHO judged — "sdk", "console", a review-agent name. Not a tenant. */
+    readonly source: string;
+    /** Authenticated user who recorded it (00017), or null. */
+    readonly created_by: string | null;
+    /** The verdict's OWN org, when it differs from the exporter's. See the
+     * module header — this is the one field the ingest endpoint must verify. */
+    readonly org_id?: string;
+}
+export interface WireEnvelope {
+    readonly envelope_key: string;
+    readonly budget_usd: number;
+    readonly spent_usd: number;
+    readonly status: "open" | "exhausted";
+}
+export interface WireRoute {
+    readonly route: string;
+    readonly version: number;
+    readonly candidates: ReadonlyArray<{
+        readonly provider: string;
+        readonly model: string;
+    }>;
+    readonly capture: boolean;
+}
+export interface WireManifest {
+    readonly name: string;
+    readonly dimensions: unknown;
+    readonly contribution: boolean;
+    readonly serveability: readonly unknown[];
+}
+/** One flush's worth of telemetry. Every collection is optional — a flush that
+ * has only inferences sends only inferences. */
+export interface IngestBatch {
+    readonly v: number;
+    /** The rig instance this came from. Half of an inference's identity under
+     * multi-tenancy (00013), and customer-chosen, so it is validated but not
+     * trusted to be unique across tenants. */
+    readonly source: string;
+    readonly inferences?: readonly WireInference[];
+    readonly feedback?: readonly WireFeedback[];
+    readonly envelopes?: readonly WireEnvelope[];
+    readonly routes?: readonly WireRoute[];
+    readonly manifest?: WireManifest;
+    /** Present when this batch advanced the exporter's inference watermark. */
+    readonly watermarkAt?: string;
+}
+/** One PostgREST write. `onConflict` is mandatory where `merge` is true —
+ * S5: a single-argument upsert targets the PK and 23505s later. */
+export interface TableWrite {
+    readonly table: string;
+    readonly rows: readonly Record<string, unknown>[];
+    /** Real unique constraint the upsert resolves against. */
+    readonly onConflict: string;
+    /** true = merge-duplicates (mutable projection), false = ignore-duplicates
+     * (immutable fact; a retry must never rewrite what already landed). */
+    readonly merge: boolean;
+}
+/**
+ * Turn a batch plus a tenant into the writes it becomes.
+ *
+ * THE conformance seam. Both transports call this; nothing else builds a
+ * telemetry row. If you are about to add a table to the export, add it here
+ * and both modes gain it at once — which is the point.
+ */
+export declare function stampBatch(batch: IngestBatch, tenancy: Tenancy): TableWrite[];
+/**
+ * Feedback rows naming an org other than the presented key's.
+ *
+ * Exists as its own exported function because the ingest endpoint must drop
+ * these and COUNT them, and a check that lives inline in a request handler is
+ * a check nobody can test in isolation. Returns the offending ids.
+ */
+export declare function foreignOrgFeedback(rows: readonly WireFeedback[], keyOrgId: string): readonly string[];
+/** What `/v1/ingest` answers. Counts only — a per-row error list on a
+ * fire-and-forget telemetry path is a payload nobody reads and a leak surface
+ * nobody audits. */
+export interface IngestOutcome {
+    readonly accepted: Readonly<Record<string, number>>;
+    readonly dropped: Readonly<Record<string, number>>;
+    /** reason → count. The teaching half: "clock_skew_future: 12" is actionable
+     * where "dropped: 12" is not. */
+    readonly reasons: Readonly<Record<string, number>>;
+}
+//# sourceMappingURL=ingest-protocol.d.ts.map

package/dist/telemetry/ingest-protocol.d.ts.map

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

package/dist/telemetry/ingest-protocol.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * The telemetry wire contract — Phase 6 WS2.
+ *
+ * ONE definition of what a batch of telemetry looks like, and ONE function
+ * that turns a batch plus a tenant into the exact database writes it becomes.
+ * Both transports use them:
+ *
+ *   direct mode  exporter → stampBatch(batch, ownTenancy)  → PostgREST
+ *   api mode     exporter → POST /v1/ingest → server → stampBatch(batch, keyTenancy) → PostgREST
+ *
+ * telemetry-ingestion-boundary.md §4 requires that "the SDK must treat api
+ * mode and direct mode identically … one exporter interface, two transports —
+ * enforced by a shared conformance test". This module is what makes that
+ * enforceable rather than aspirational: the conformance test does not compare
+ * two hand-written mappers for similarity, it asserts that both paths run the
+ * SAME mapper. A drift bug has nowhere to live.
+ *
+ * ── WHY THE WIRE ROWS DO NOT CARRY A TENANT ──────────────────────────────
+ * T3: tenancy is derived from the principal, never trusted from the caller. A
+ * client that could put `org_id` on a row could put someone else's `org_id` on
+ * a row. So the wire carries the telemetry and nothing else, and the tenant is
+ * stamped by whoever holds the principal — the exporter's config in direct
+ * mode, the resolved key in api mode.
+ *
+ * The single exception is `feedback.org_id`, and it is the reason WS2 exists.
+ * A verdict recorded on OUR hosted server belongs to the org of the person who
+ * recorded it, not to the org the server runs as, and one SQLite store holds
+ * verdicts for many orgs. So a feedback row may name its own org — and the
+ * ingest endpoint VERIFIES that name against the key rather than trusting it
+ * (see `foreignOrgFeedback`). A service-role exporter needs no such check: it
+ * already holds a credential that can write any row in the database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INGEST_URL = exports.INGEST_PROTOCOL_VERSION = exports.INGEST_PATH = void 0;
+exports.stampBatch = stampBatch;
+exports.foreignOrgFeedback = foreignOrgFeedback;
+/** The path the api sink posts to. Spelled once. */
+exports.INGEST_PATH = "/v1/ingest";
+/** Bumped only for a breaking change to the shapes below. A server that does
+ * not recognise the version refuses the batch rather than guessing. */
+exports.INGEST_PROTOCOL_VERSION = 1;
+/** Default ingest host — telemetry-ingestion-boundary.md §2.1. */
+exports.DEFAULT_INGEST_URL = "https://api.modelrig.ai";
+/**
+ * Turn a batch plus a tenant into the writes it becomes.
+ *
+ * THE conformance seam. Both transports call this; nothing else builds a
+ * telemetry row. If you are about to add a table to the export, add it here
+ * and both modes gain it at once — which is the point.
+ */
+function stampBatch(batch, tenancy) {
+    const writes = [];
+    const now = new Date().toISOString();
+    if (batch.routes !== undefined && batch.routes.length > 0) {
+        writes.push({
+            table: "routes",
+            onConflict: "org_id,route,version",
+            merge: true,
+            rows: batch.routes.map((r) => ({
+                org_id: tenancy.org_id,
+                route: r.route,
+                version: r.version,
+                candidates: r.candidates,
+                capture: r.capture,
+                updated_at: now,
+            })),
+        });
+    }
+    if (batch.manifest !== undefined) {
+        writes.push({
+            table: "rig_manifests",
+            onConflict: "org_id,source_id",
+            merge: true,
+            rows: [
+                {
+                    org_id: tenancy.org_id,
+                    source_id: tenancy.source_id,
+                    name: batch.manifest.name,
+                    dimensions: batch.manifest.dimensions,
+                    contribution: batch.manifest.contribution,
+                    serveability: batch.manifest.serveability,
+                    updated_at: now,
+                },
+            ],
+        });
+    }
+    if (batch.inferences !== undefined && batch.inferences.length > 0) {
+        writes.push({
+            table: "inferences",
+            // 00013's tenant-first primary key. Named explicitly so a retry lands on
+            // the row it already wrote rather than on the old single-column pk.
+            onConflict: "org_id,source_id,id",
+            // An inference is a fact that happened. A retry must not be able to
+            // rewrite it — idempotent by doing nothing, not by overwriting.
+            merge: false,
+            rows: batch.inferences.map((row) => ({
+                org_id: tenancy.org_id,
+                project_id: tenancy.project_id,
+                source_id: tenancy.source_id,
+                ...row,
+            })),
+        });
+    }
+    if (batch.watermarkAt !== undefined) {
+        writes.push({
+            table: "export_watermarks",
+            onConflict: "org_id,source_id",
+            merge: true,
+            rows: [
+                {
+                    org_id: tenancy.org_id,
+                    source_id: tenancy.source_id,
+                    last_exported_ts: batch.watermarkAt,
+                },
+            ],
+        });
+    }
+    if (batch.feedback !== undefined && batch.feedback.length > 0) {
+        writes.push({
+            table: "feedback",
+            onConflict: "id",
+            merge: false,
+            rows: batch.feedback.map(({ org_id, ...row }) => ({
+                // The verdict's own org wins when it has one — that is the whole of
+                // QA-P6-010's fix. Note that `source_id` is deliberately absent:
+                // `feedback.source` already means "who judged", and two columns a
+                // letter apart meaning different things is N2's cautionary tale.
+                org_id: org_id ?? tenancy.org_id,
+                project_id: tenancy.project_id,
+                ...row,
+            })),
+        });
+    }
+    if (batch.envelopes !== undefined && batch.envelopes.length > 0) {
+        writes.push({
+            table: "envelopes",
+            onConflict: "org_id,envelope_key",
+            merge: true,
+            rows: batch.envelopes.map((e) => ({
+                org_id: tenancy.org_id,
+                envelope_key: e.envelope_key,
+                budget_usd: e.budget_usd,
+                spent_usd: e.spent_usd,
+                status: e.status,
+                exported_at: now,
+            })),
+        });
+    }
+    return writes;
+}
+/**
+ * Feedback rows naming an org other than the presented key's.
+ *
+ * Exists as its own exported function because the ingest endpoint must drop
+ * these and COUNT them, and a check that lives inline in a request handler is
+ * a check nobody can test in isolation. Returns the offending ids.
+ */
+function foreignOrgFeedback(rows, keyOrgId) {
+    return rows
+        .filter((r) => r.org_id !== undefined && r.org_id !== keyOrgId)
+        .map((r) => r.id);
+}

package/dist/telemetry/sinks.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The two telemetry transports — Phase 6 WS2.
+ *
+ * telemetry-ingestion-boundary.md §2.4 names three modes. Two of them are
+ * sinks and live here; the third (local-only) is the absence of a sink.
+ *
+ *   direct   self-host + our own single-tenant deployments · their database
+ *   api      every hosted customer · their `rig_sk_` key only
+ *
+ * Both implement `TelemetrySink`, both are driven by the SAME exporter loop,
+ * and both produce their database rows through `stampBatch` — so the promise
+ * that "self-host ↔ hosted migration is a config change, not a data model
+ * change" is enforced by construction rather than by review.
+ *
+ * ── WHY THE API SINK GZIPS AND THE DIRECT ONE DOES NOT ───────────────────
+ * The api sink crosses the public internet with one batch per flush, and a
+ * batch is highly repetitive JSON. The direct sink talks to PostgREST, which
+ * would have to decompress it again on the way into the same database the
+ * caller already holds a service-role key for. Compression there would be
+ * cost with no payer.
+ */
+import type { IngestBatch, IngestOutcome, Tenancy } from "./ingest-protocol";
+export interface TelemetrySink {
+    /** Named so a boot banner and `/status` can say which lane is live without
+     * inspecting config — the "which mode am I in?" question got asked enough
+     * during WS1 to be worth answering in the object. */
+    readonly mode: "direct" | "api";
+    /** Deliver one batch. Throws on failure; the exporter owns retry/backoff. */
+    send(batch: IngestBatch): Promise<void>;
+}
+export interface DirectSinkConfig {
+    readonly supabaseUrl: string;
+    /** Service-role key — server-side only; never reaches a browser. */
+    readonly serviceRoleKey: string;
+    /** The tenant this deployment stamps. Every row it writes lands here. */
+    readonly tenancy: Tenancy;
+    readonly fetchFn?: typeof fetch;
+}
+export declare function createDirectSink(config: DirectSinkConfig): TelemetrySink;
+export interface ApiSinkConfig {
+    /** Base URL of the ingest service, e.g. https://api.modelrig.ai */
+    readonly ingestUrl: string;
+    /** `rig_sk_…` with the `ingest` scope. The ONLY credential a hosted
+     * customer holds — no database URL, no service role (§2's one rule). */
+    readonly apiKey: string;
+    readonly fetchFn?: typeof fetch;
+    /** Called with each batch's outcome. The exporter logs dropped rows through
+     * this: a batch the server partly refused is a 200, and a customer whose
+     * rows are being dropped must hear about it from their own process rather
+     * than by noticing a gap in a chart weeks later. */
+    readonly onOutcome?: (outcome: IngestOutcome) => void;
+}
+export declare function createApiSink(config: ApiSinkConfig): TelemetrySink;
+//# sourceMappingURL=sinks.d.ts.map

package/dist/telemetry/sinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sinks.d.ts","sourceRoot":"","sources":["../../src/telemetry/sinks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B;;yDAEqD;IACrD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,KAAK,CAAC;IAChC,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAMD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAiCxE;AAMD,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;4EACwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IAChC;;;wDAGoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;CACvD;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAgClE"}

package/dist/telemetry/sinks.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * The two telemetry transports — Phase 6 WS2.
+ *
+ * telemetry-ingestion-boundary.md §2.4 names three modes. Two of them are
+ * sinks and live here; the third (local-only) is the absence of a sink.
+ *
+ *   direct   self-host + our own single-tenant deployments · their database
+ *   api      every hosted customer · their `rig_sk_` key only
+ *
+ * Both implement `TelemetrySink`, both are driven by the SAME exporter loop,
+ * and both produce their database rows through `stampBatch` — so the promise
+ * that "self-host ↔ hosted migration is a config change, not a data model
+ * change" is enforced by construction rather than by review.
+ *
+ * ── WHY THE API SINK GZIPS AND THE DIRECT ONE DOES NOT ───────────────────
+ * The api sink crosses the public internet with one batch per flush, and a
+ * batch is highly repetitive JSON. The direct sink talks to PostgREST, which
+ * would have to decompress it again on the way into the same database the
+ * caller already holds a service-role key for. Compression there would be
+ * cost with no payer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDirectSink = createDirectSink;
+exports.createApiSink = createApiSink;
+const node_zlib_1 = require("node:zlib");
+const ingest_protocol_1 = require("./ingest-protocol");
+function createDirectSink(config) {
+    const base = config.supabaseUrl.replace(/\/$/, "");
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        mode: "direct",
+        async send(batch) {
+            for (const write of (0, ingest_protocol_1.stampBatch)(batch, config.tenancy)) {
+                const response = await fetchFn(
+                // S5: the upsert names a real unique constraint. A single-argument
+                // upsert targets the primary key and 23505s later.
+                `${base}/rest/v1/${write.table}?on_conflict=${encodeURIComponent(write.onConflict)}`, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        apikey: config.serviceRoleKey,
+                        authorization: `Bearer ${config.serviceRoleKey}`,
+                        prefer: write.merge
+                            ? "resolution=merge-duplicates,return=minimal"
+                            : "resolution=ignore-duplicates,return=minimal",
+                    },
+                    body: JSON.stringify(write.rows),
+                });
+                if (!response.ok) {
+                    throw new Error(`sink POST ${write.table} → ${response.status} ${await response.text().catch(() => "")}`);
+                }
+            }
+        },
+    };
+}
+/** Below this, gzip costs more than it saves. */
+const GZIP_MIN_BYTES = 1024;
+function createApiSink(config) {
+    const url = config.ingestUrl.replace(/\/$/, "") + ingest_protocol_1.INGEST_PATH;
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        mode: "api",
+        async send(batch) {
+            const json = JSON.stringify({ ...batch, v: ingest_protocol_1.INGEST_PROTOCOL_VERSION });
+            const compress = Buffer.byteLength(json) >= GZIP_MIN_BYTES;
+            const response = await fetchFn(url, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${config.apiKey}`,
+                    ...(compress ? { "content-encoding": "gzip" } : {}),
+                },
+                body: compress ? (0, node_zlib_1.gzipSync)(json) : json,
+            });
+            if (!response.ok) {
+                // The key itself never appears in the message — C2's leak gate covers
+                // failure text, and an exporter's warnings are the likeliest place for
+                // a secret to reach someone else's log aggregator.
+                throw new Error(`ingest POST → ${response.status} ${await response.text().catch(() => "")}`);
+            }
+            if (config.onOutcome !== undefined) {
+                const outcome = (await response.json().catch(() => null));
+                if (outcome !== null)
+                    config.onOutcome(outcome);
+            }
+        },
+    };
+}

package/dist/telemetry/store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SQLite telemetry store — spec §5, plan §2. Package-owned storage; zero
+ * InferWealth Supabase involvement. Schema created idempotently on open;
+ * PRAGMA user_version tracks migrations (v2: fingerprint_cell, Phase 2;
+ * v3: captures table + served_variant/repaired_by, Phase 3).
+ *
+ * PRIVACY (Phase 3 WS4): the `captures` table is created here but NEVER read
+ * here — capture access lives exclusively behind telemetry/capture.ts's
+ * separate handle. ExportableTelemetryStore MUST NOT gain capture accessors;
+ * the export-isolation tests are the tripwire.
+ */
+import type { EnvelopeRow, FeedbackRow, TelemetryRow, TelemetryStore } from "../types/telemetry";
+/**
+ * Superset of the TelemetryStore contract with the enumeration hooks the
+ * Supabase exporter needs (rowid-watermarked reads + local export state).
+ * Kept out of types/telemetry.ts on purpose: the public contract stays
+ * minimal; the exporter is wired against the concrete store.
+ */
+export interface ExportableTelemetryStore extends TelemetryStore {
+    /** Rows with rowid > afterRowid, oldest first, with their rowids. */
+    readInferencesAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: TelemetryRow;
+    }>;
+    /** Feedback rows past the watermark, oldest first (Phase 4 mirror). */
+    readFeedbackAfter(afterRowid: number, limit: number): Array<{
+        rowid: number;
+        row: FeedbackRow;
+    }>;
+    /** Newest-first local feedback read (console/dev inspection). */
+    listFeedback(limit: number): FeedbackRow[];
+    listEnvelopes(): EnvelopeRow[];
+    /** Local exporter watermark (per source instance), 0 when unset. */
+    getExportWatermark(sourceId: string): number;
+    setExportWatermark(sourceId: string, lastRowid: number): void;
+}
+export declare function openTelemetryStore(dbPath: string): ExportableTelemetryStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/telemetry/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/telemetry/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGjG;;;;;GAKG;AACH,MAAM,WAAW,wBAAyB,SAAQ,cAAc;IAC9D,qEAAqE;IACrE,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,YAAY,CAAA;KAAE,CAAC,CAAC;IACpG,uEAAuE;IACvE,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACjG,iEAAiE;IACjE,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAC3C,aAAa,IAAI,WAAW,EAAE,CAAC;IAC/B,oEAAoE;IACpE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7C,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/D;AAyKD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAkN3E"}