diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index a1b7db6f..a90340c5 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -4,6 +4,12 @@
   "description": "JavaScript SDK for Base44 API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "imports": {
+    "#build-commit-source": {
+      "module": "./dist/utils/build-commit-source.js",
+      "default": "./dist/utils/build-commit-source.fallback.js"
+    }
+  },
   "type": "module",
   "files": [
     "dist"
@@ -16,6 +22,7 @@
     "test:e2e": "vitest run tests/e2e",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:build-commit": "scripts/verify-build-commit.sh",
     "docs": "typedoc",
     "prepublishOnly": "npm run build",
     "create-docs": "npm run create-docs:generate && npm run create-docs:process",
diff --git a/packages/sdk/scripts/verify-build-commit.sh b/packages/sdk/scripts/verify-build-commit.sh
new file mode 100755
index 00000000..18b7ace9
--- /dev/null
+++ b/packages/sdk/scripts/verify-build-commit.sh
@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# Proves the X-Base44-Build value really reaches a bundled app, using the SDK as
+# it ships: packed and installed into node_modules, not linked.
+#
+#   scripts/verify-build-commit.sh          # Vite 6 and 7: build + dev server
+#   scripts/verify-build-commit.sh --expo   # also Expo 54: Android (Hermes) and web
+#
+# Checks that `vite build` bakes VITE_BASE44_BUILD_COMMIT into the bundle and
+# leaves no `import.meta` behind, that the dev server's prebundled SDK carries
+# it, and that Metro bundles the SDK without the reader on native and web.
+set -euo pipefail
+
+SDK_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+WORK="$(mktemp -d)"
+COMMIT=0123456789abcdef0123456789abcdef01234567
+PORT=5391
+trap 'kill $(jobs -p) 2>/dev/null || true; rm -rf "$WORK"' EXIT
+
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+(cd "$SDK_DIR" && npm run build >/dev/null && npm pack --pack-destination "$WORK" >/dev/null 2>&1)
+TARBALL="$(ls "$WORK"/base44-sdk-*.tgz)"
+
+make_vite_app() { # dir vite-version plugin-react-version
+  mkdir -p "$1/src"
+  cat >"$1/package.json" <<EOF
+{ "name": "verify-app", "private": true, "type": "module",
+  "dependencies": { "@base44/sdk": "file:$TARBALL", "react": "^18.2.0", "react-dom": "^18.2.0" },
+  "devDependencies": { "vite": "$2", "@vitejs/plugin-react": "$3" } }
+EOF
+  cat >"$1/vite.config.js" <<'EOF'
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+export default defineConfig({ plugins: [react()] });
+EOF
+  echo '<!doctype html><div id="root"></div><script type="module" src="/src/main.jsx"></script>' >"$1/index.html"
+  cat >"$1/src/main.jsx" <<'EOF'
+import { createClient } from "@base44/sdk";
+const base44 = createClient({ appId: import.meta.env.VITE_BASE44_APP_ID });
+base44.entities.Todo.list().catch(() => {});
+EOF
+  (cd "$1" && npm install --silent >/dev/null 2>&1)
+}
+
+check_vite() { # dir label
+  local app="$1" label="$2"
+  cd "$app"
+  # Output is captured before grepping: under pipefail, `grep -q` exiting
+  # early would fail the pipeline with SIGPIPE.
+  local out
+  VITE_BASE44_BUILD_COMMIT=$COMMIT npx vite build --logLevel silent >/dev/null
+  out=$(cat dist/assets/*.js)
+  grep -q "$COMMIT" <<<"$out" || fail "$label build: commit not in bundle"
+  ! grep -q 'import\.meta' <<<"$out" || fail "$label build: import.meta left in bundle"
+  echo "ok  $label build bakes in the commit"
+
+  npx vite build --logLevel silent >/dev/null
+  out=$(cat dist/assets/*.js)
+  ! grep -q "$COMMIT" <<<"$out" || fail "$label build without the var still has a commit"
+  echo "ok  $label build without the var has none"
+
+  rm -rf node_modules/.vite
+  VITE_BASE44_BUILD_COMMIT=$COMMIT npx vite --port $PORT --strictPort >/dev/null 2>&1 &
+  local server=$!
+  for _ in $(seq 1 60); do curl -sf "localhost:$PORT" >/dev/null && break; sleep 0.5; done
+  local dep
+  dep=$(curl -s "localhost:$PORT/src/main.jsx" | grep -o '/node_modules/.vite/deps/@base44_sdk.js[^"]*')
+  out=$(curl -s "localhost:$PORT$dep")
+  grep -q "$COMMIT" <<<"$out" || fail "$label dev: prebundled SDK lacks the commit"
+  kill $server; wait $server 2>/dev/null || true
+  echo "ok  $label dev server's prebundled SDK carries the commit"
+}
+
+make_vite_app "$WORK/vite6" "^6.1.0" "^4.3.4" && check_vite "$WORK/vite6" "vite 6"
+make_vite_app "$WORK/vite7" "^7.0.0" "^5.0.0" && check_vite "$WORK/vite7" "vite 7"
+
+if [ "${1:-}" = "--expo" ]; then
+  cd "$WORK"
+  npx --yes create-expo-app@latest expo-app --template blank@sdk-54 --no-install >/dev/null 2>&1
+  cd expo-app && npm install --silent >/dev/null 2>&1 && npm install --silent "$TARBALL" >/dev/null 2>&1
+  npx expo install react-dom react-native-web @expo/metro-runtime >/dev/null 2>&1
+  printf '%s\n' "import { createClient } from '@base44/sdk';" \
+    "export const base44 = createClient({ appId: 'x' });" | cat - App.js >App.tmp && mv App.tmp App.js
+  npx expo export --platform android --output-dir out-hbc >/dev/null 2>&1 \
+    || fail "expo 54: Hermes build failed"
+  npx expo export --platform android --no-bytecode --output-dir out-js >/dev/null 2>&1
+  bundle=$(cat out-js/_expo/static/js/android/*.js)
+  grep -q "X-Base44-Build" <<<"$bundle" || fail "expo 54: SDK not in bundle"
+  ! grep -q "VITE_BASE44_BUILD_COMMIT" <<<"$bundle" || fail "expo 54: picked the browser reader"
+  echo "ok  expo 54 Hermes build bundles the SDK without the import.meta reader"
+
+  # Metro's web build ships a classic <script>, where `import.meta` is a
+  # SyntaxError that blanks the page: parse the bundle the way a browser would.
+  npx expo export --platform web --output-dir out-web >/dev/null 2>&1 \
+    || fail "expo 54 web: build failed"
+  web=$(cat out-web/_expo/static/js/web/*.js)
+  grep -q "X-App-Id" <<<"$web" || fail "expo 54 web: SDK not in bundle"
+  ! grep -q "VITE_BASE44_BUILD_COMMIT" <<<"$web" || fail "expo 54 web: picked the import.meta reader"
+  for f in out-web/_expo/static/js/web/*.js; do
+    node -e 'new (require("vm").Script)(require("fs").readFileSync(process.argv[1], "utf8"))' "$f" \
+      || fail "expo 54 web: $f doesn't parse as a classic script"
+  done
+  echo "ok  expo 54 web bundle has no import.meta reader and parses as a classic script"
+fi
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 9e357dfa..910b9c44 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -9,6 +9,10 @@ import {
 } from "./modules/connectors.js";
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFetchWithAuth } from "./utils/fetch-with-auth.js";
+import {
+  BUILD_COMMIT_HEADER,
+  getBuildCommitHeaders,
+} from "./utils/build-commit.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
@@ -75,6 +79,13 @@ export type {
  * ```
  */
 export function createClient(config: CreateClientConfig): Base44Client {
+  return buildClient(config, { sendBuildCommit: true });
+}
+
+function buildClient(
+  config: CreateClientConfig,
+  { sendBuildCommit }: { sendBuildCommit: boolean }
+): Base44Client {
   const {
     serverUrl = "https://base44.app",
     appId,
@@ -110,7 +121,21 @@ export function createClient(config: CreateClientConfig): Base44Client {
     return socket;
   };
 
+  // The build commit goes on every API call, so the backend can tell which
+  // frontend bundle a request came from. One set by the caller, in any
+  // casing, replaces it; resolving that once here keeps every call path,
+  // functions.fetch() included, reporting the same build.
+  const callerBuildCommit = Object.entries(optionalHeaders ?? {}).find(
+    ([name]) => name.toLowerCase() === BUILD_COMMIT_HEADER.toLowerCase()
+  );
+  const buildCommitHeaders: Record<string, string> = callerBuildCommit
+    ? { [BUILD_COMMIT_HEADER]: callerBuildCommit[1] }
+    : sendBuildCommit
+      ? getBuildCommitHeaders()
+      : {};
+
   const headers = {
+    ...(callerBuildCommit ? {} : buildCommitHeaders),
     ...optionalHeaders,
     "X-App-Id": String(appId),
   };
@@ -237,7 +262,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
     auth: userAuthModule,
     functions: createFunctionsModule(functionsAxiosClient, appId, {
       getAuthHeaders: () => {
-        const headers: Record<string, string> = {};
+        const headers: Record<string, string> = { ...buildCommitHeaders };
         // Get current token from storage or initial config
         const currentToken = token || getAccessToken();
         if (currentToken) {
@@ -538,12 +563,14 @@ export function createClientFromRequest(request: Request): Base44Client {
     additionalHeaders["X-Data-Env"] = dataEnvHeader;
   }
 
-  return createClient({
+  // A backend function isn't the browser bundle, so it never reports a build
+  // commit, whatever its runtime looks like.
+  return buildClient({
     serverUrl: serverUrlHeader || "https://base44.app",
     appId,
     token: userToken,
     serviceToken: serviceRoleToken,
     functionsVersion: functionsVersion ?? undefined,
     headers: additionalHeaders,
-  });
+  }, { sendBuildCommit: false });
 }
diff --git a/packages/sdk/src/import-meta-env.d.ts b/packages/sdk/src/import-meta-env.d.ts
new file mode 100644
index 00000000..eed58037
--- /dev/null
+++ b/packages/sdk/src/import-meta-env.d.ts
@@ -0,0 +1,7 @@
+// Vite statically replaces `import.meta.env.*` when it bundles the SDK; see
+// utils/build-commit-source.ts. Elsewhere `import.meta.env` is undefined.
+interface ImportMeta {
+  readonly env: {
+    readonly VITE_BASE44_BUILD_COMMIT?: string;
+  };
+}
diff --git a/packages/sdk/src/utils/build-commit-source.fallback.ts b/packages/sdk/src/utils/build-commit-source.fallback.ts
new file mode 100644
index 00000000..a6510b2d
--- /dev/null
+++ b/packages/sdk/src/utils/build-commit-source.fallback.ts
@@ -0,0 +1,16 @@
+/**
+ * What `#build-commit-source` resolves to without the `module` condition: no
+ * build commit.
+ *
+ * The package's `imports` field gives the `import.meta` reader
+ * (`build-commit-source.ts`) only to bundlers that match `module`: Vite,
+ * webpack and esbuild. Everything else gets this file, so `import.meta` never
+ * reaches a runtime or bundler that can't take it. That includes Node, Deno,
+ * and Metro on every platform: Hermes rejects `import.meta` outright, and
+ * Metro's web build ships a classic script, where it is a SyntaxError.
+ *
+ * @internal
+ */
+export function readBuildCommitSource(): unknown {
+  return undefined;
+}
diff --git a/packages/sdk/src/utils/build-commit-source.ts b/packages/sdk/src/utils/build-commit-source.ts
new file mode 100644
index 00000000..a82f9b02
--- /dev/null
+++ b/packages/sdk/src/utils/build-commit-source.ts
@@ -0,0 +1,25 @@
+/**
+ * Reads the commit the app's frontend bundle was built from.
+ *
+ * Base44's publish pipeline sets `VITE_BASE44_BUILD_COMMIT` for the build, and
+ * Vite replaces the expression below with that literal string when it bundles
+ * this file out of `node_modules`, in `vite build` and in the dev server's
+ * prebundled deps alike. The expression must stay spelled out exactly like
+ * this: Vite matches it statically, and any indirection leaves a runtime lookup
+ * that is always undefined.
+ *
+ * A bundler that isn't Vite leaves `import.meta.env` undefined, so the lookup
+ * throws, and that means "no build commit".
+ *
+ * Only reached as `#build-commit-source` under the `module` condition; see
+ * `build-commit-source.fallback.ts`.
+ *
+ * @internal
+ */
+export function readBuildCommitSource(): unknown {
+  try {
+    return import.meta.env.VITE_BASE44_BUILD_COMMIT;
+  } catch {
+    return undefined;
+  }
+}
diff --git a/packages/sdk/src/utils/build-commit.ts b/packages/sdk/src/utils/build-commit.ts
new file mode 100644
index 00000000..40ba65ac
--- /dev/null
+++ b/packages/sdk/src/utils/build-commit.ts
@@ -0,0 +1,26 @@
+import { isNode, isReactNative } from "./common.js";
+import { readBuildCommitSource } from "#build-commit-source";
+
+/** Header the backend reads to tell which frontend build sent a request. */
+export const BUILD_COMMIT_HEADER = "X-Base44-Build";
+
+// The backend accepts exactly this shape and ignores anything else, so a value
+// that doesn't match is never sent.
+const BUILD_COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+
+/**
+ * The build-commit header to send from this client, if any.
+ *
+ * Only a browser sends it: the value names the browser bundle, so a server
+ * (Node, Deno, a backend function) or React Native would report a commit that
+ * isn't the one running.
+ *
+ * @internal
+ */
+export function getBuildCommitHeaders(): Record<string, string> {
+  if (isNode || isReactNative) return {};
+  const commit = readBuildCommitSource();
+  return typeof commit === "string" && BUILD_COMMIT_PATTERN.test(commit)
+    ? { [BUILD_COMMIT_HEADER]: commit }
+    : {};
+}
diff --git a/packages/sdk/tests/unit/build-commit-header.test.ts b/packages/sdk/tests/unit/build-commit-header.test.ts
new file mode 100644
index 00000000..3d0fee27
--- /dev/null
+++ b/packages/sdk/tests/unit/build-commit-header.test.ts
@@ -0,0 +1,275 @@
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import nock from "nock";
+
+// What the bundler would have baked in for VITE_BASE44_BUILD_COMMIT. The
+// reader is replaced here so each test picks its value; it is tested on its
+// own below.
+const source = vi.hoisted(() => ({ value: undefined as unknown }));
+vi.mock("../../src/utils/build-commit-source.ts", () => ({
+  readBuildCommitSource: () => source.value,
+}));
+
+const COMMIT = "0123456789abcdef0123456789abcdef01234567";
+const serverUrl = "https://api.base44.com";
+const appId = "test-app-id";
+
+function makeLocalStorage() {
+  const store = new Map<string, string>();
+  return {
+    getItem: (k: string) => (store.has(k) ? store.get(k)! : null),
+    setItem: (k: string, v: string) => void store.set(k, v),
+    removeItem: (k: string) => void store.delete(k),
+    clear: () => store.clear(),
+  };
+}
+
+function stubBrowserGlobals() {
+  const localStorage = makeLocalStorage();
+  vi.stubGlobal("window", {
+    location: { href: "https://my-app.base44.app/", origin: "https://my-app.base44.app" },
+    localStorage,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+  });
+  vi.stubGlobal("document", {});
+  vi.stubGlobal("localStorage", localStorage);
+}
+
+function stubReactNativeGlobals() {
+  vi.stubGlobal("window", {});
+  vi.stubGlobal("document", undefined);
+  vi.stubGlobal("localStorage", undefined);
+}
+
+// Environment flags are read once at module load, so each test re-imports the
+// SDK after stubbing the globals it runs under.
+async function loadSdk() {
+  vi.resetModules();
+  return await import("../../src/index.ts");
+}
+
+// The X-Base44-Build value the next entity call sends, or undefined.
+async function entityCallBuildHeader(client: {
+  entities: Record<string, any>;
+}): Promise<string | undefined> {
+  let sent: string | undefined;
+  nock(serverUrl)
+    .get(`/api/apps/${appId}/entities/Todo`)
+    .query(true)
+    .reply(function () {
+      const value = this.req.headers["x-base44-build"];
+      sent = Array.isArray(value) ? value[0] : value;
+      return [200, []];
+    });
+  await client.entities.Todo.list();
+  return sent;
+}
+
+beforeEach(() => {
+  nock.disableNetConnect();
+  source.value = undefined;
+});
+
+afterEach(() => {
+  nock.cleanAll();
+  nock.enableNetConnect();
+  vi.unstubAllGlobals();
+  vi.resetModules();
+});
+
+describe("X-Base44-Build header", () => {
+  test("a browser client sends the build commit on entity calls", async () => {
+    stubBrowserGlobals();
+    source.value = COMMIT;
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId, analytics: { enabled: false } });
+
+    expect(await entityCallBuildHeader(client)).toBe(COMMIT);
+  });
+
+  test("a browser client sends it on function invocations and functions.fetch", async () => {
+    stubBrowserGlobals();
+    source.value = COMMIT;
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId, analytics: { enabled: false } });
+
+    let invoked: string | undefined;
+    nock(serverUrl)
+      .post(`/api/apps/${appId}/functions/hello`)
+      .reply(function () {
+        invoked = this.req.headers["x-base44-build"] as string;
+        return [200, {}];
+      });
+    await client.functions.invoke("hello", {});
+    expect(invoked).toBe(COMMIT);
+
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    await client.functions.fetch("/hello");
+    const init = fetchMock.mock.calls[0][1] as RequestInit;
+    expect(new Headers(init.headers).get("X-Base44-Build")).toBe(COMMIT);
+  });
+
+  test("omits the header when no build commit was baked in", async () => {
+    stubBrowserGlobals();
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId, analytics: { enabled: false } });
+
+    expect(await entityCallBuildHeader(client)).toBeUndefined();
+  });
+
+  test.each([
+    ["empty", ""],
+    ["uppercase", COMMIT.toUpperCase()],
+    ["short", COMMIT.slice(0, 39)],
+    ["long", COMMIT + "0"],
+    ["padded", ` ${COMMIT}`],
+    ["trailing newline", `${COMMIT}\n`],
+    ["not hex", "g".repeat(40)],
+    ["not a string", 123],
+  ])("omits the header for a malformed value (%s)", async (_label, value) => {
+    stubBrowserGlobals();
+    source.value = value;
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId, analytics: { enabled: false } });
+
+    expect(await entityCallBuildHeader(client)).toBeUndefined();
+  });
+
+  test("createClientFromRequest never sends it, even where a browser bundle would", async () => {
+    stubBrowserGlobals();
+    source.value = COMMIT;
+    const { createClientFromRequest } = await loadSdk();
+    const client = createClientFromRequest(
+      new Request("https://fn.example/", {
+        headers: { "Base44-App-Id": appId, "Base44-Api-Url": serverUrl },
+      })
+    );
+
+    expect(await entityCallBuildHeader(client)).toBeUndefined();
+  });
+
+  test("a server-side client (no window) never sends it", async () => {
+    source.value = COMMIT;
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId });
+
+    expect(await entityCallBuildHeader(client)).toBeUndefined();
+  });
+
+  test("a React Native client never sends it", async () => {
+    stubReactNativeGlobals();
+    source.value = COMMIT;
+    const { createClient } = await loadSdk();
+    const client = createClient({ serverUrl, appId });
+
+    expect(await entityCallBuildHeader(client)).toBeUndefined();
+  });
+
+  // Every call path must report the same build, or one client's requests get
+  // attributed to two different bundles.
+  test.each([
+    ["exact casing, over a baked-in commit", "X-Base44-Build", COMMIT],
+    ["lowercase, over a baked-in commit", "x-base44-build", COMMIT],
+    ["uppercase, over a baked-in commit", "X-BASE44-BUILD", COMMIT],
+    ["exact casing, with no baked-in commit", "X-Base44-Build", undefined],
+  ])("a caller-supplied header wins on every call path (%s)", async (_label, name, baked) => {
+    stubBrowserGlobals();
+    source.value = baked;
+    const override = "f".repeat(40);
+    const { createClient } = await loadSdk();
+    const client = createClient({
+      serverUrl,
+      appId,
+      analytics: { enabled: false },
+      headers: { [name]: override },
+    });
+
+    expect(await entityCallBuildHeader(client)).toBe(override);
+
+    let invoked: string | string[] | undefined;
+    nock(serverUrl)
+      .post(`/api/apps/${appId}/functions/hello`)
+      .reply(function () {
+        invoked = this.req.headers["x-base44-build"];
+        return [200, {}];
+      });
+    await client.functions.invoke("hello", {});
+    expect(invoked).toBe(override);
+
+    const fetchMock = vi.fn(async () => new Response("ok"));
+    vi.stubGlobal("fetch", fetchMock);
+    await client.functions.fetch("/hello");
+    const init = fetchMock.mock.calls[0][1] as RequestInit;
+    expect(new Headers(init.headers).get("X-Base44-Build")).toBe(override);
+  });
+});
+
+describe("build commit source", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  test("the reader returns VITE_BASE44_BUILD_COMMIT from import.meta.env", async () => {
+    const { readBuildCommitSource } = await vi.importActual<
+      typeof import("../../src/utils/build-commit-source.ts")
+    >("../../src/utils/build-commit-source.ts");
+
+    vi.stubEnv("VITE_BASE44_BUILD_COMMIT", COMMIT);
+    expect(readBuildCommitSource()).toBe(COMMIT);
+  });
+
+  test("the reader keeps the exact expression Vite replaces", () => {
+    // Vite substitutes the value by matching this expression statically; a
+    // refactor that reaches it any other way silently stops the header.
+    const file = fileURLToPath(
+      new URL("../../src/utils/build-commit-source.ts", import.meta.url)
+    );
+    expect(readFileSync(file, "utf8")).toContain(
+      "import.meta.env.VITE_BASE44_BUILD_COMMIT"
+    );
+  });
+
+  test("only the reader uses import.meta, and the fallback returns nothing", async () => {
+    // Anything else with `import.meta` would reach Metro, which can't take it.
+    const sources = import.meta.glob("../../src/**/*.ts", {
+      query: "?raw",
+      import: "default",
+      eager: true,
+    });
+    const usesImportMeta = Object.entries(sources)
+      .filter(([, code]) =>
+        (code as string).replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, "").includes("import.meta")
+      )
+      .map(([file]) => file);
+    expect(usesImportMeta).toEqual(["../../src/utils/build-commit-source.ts"]);
+
+    const { readBuildCommitSource } = await vi.importActual<
+      typeof import("../../src/utils/build-commit-source.fallback.ts")
+    >("../../src/utils/build-commit-source.fallback.ts");
+    vi.stubEnv("VITE_BASE44_BUILD_COMMIT", COMMIT);
+    expect(readBuildCommitSource()).toBeUndefined();
+  });
+
+  test("package.json gives the reader only to the module condition", () => {
+    const pkgPath = fileURLToPath(new URL("../../package.json", import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const map = pkg.imports["#build-commit-source"];
+
+    // Metro matches neither `module` nor `browser` here, so it takes the
+    // fallback on native and web alike. Order matters: the first match wins.
+    expect(map).toEqual({
+      module: "./dist/utils/build-commit-source.js",
+      default: "./dist/utils/build-commit-source.fallback.js",
+    });
+    expect(Object.keys(map)).toEqual(["module", "default"]);
+
+    // Each mapped dist file comes from a src file of the same name.
+    for (const target of Object.values(map) as string[]) {
+      const src = target.replace("./dist/", "../../src/").replace(/\.js$/, ".ts");
+      expect(existsSync(fileURLToPath(new URL(src, import.meta.url)))).toBe(true);
+    }
+  });
+});
diff --git a/packages/sdk/tsconfig.json b/packages/sdk/tsconfig.json
index 01385596..c0a224c5 100644
--- a/packages/sdk/tsconfig.json
+++ b/packages/sdk/tsconfig.json
@@ -1,7 +1,12 @@
 {
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-    "outDir": "./dist"
+    "outDir": "./dist",
+    "paths": {
+      "#build-commit-source": [
+        "./src/utils/build-commit-source.ts"
+      ]
+    }
   },
   "include": [
     "src/**/*",
diff --git a/packages/sdk/vitest.config.ts b/packages/sdk/vitest.config.ts
index d3a67f43..a28a8f8a 100644
--- a/packages/sdk/vitest.config.ts
+++ b/packages/sdk/vitest.config.ts
@@ -1,6 +1,16 @@
+import { fileURLToPath } from "node:url";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
+  resolve: {
+    // Vitest's Node conditions would resolve the package's own
+    // `#build-commit-source` import to the dist fallback; tests run the source.
+    alias: {
+      "#build-commit-source": fileURLToPath(
+        new URL("./src/utils/build-commit-source.ts", import.meta.url)
+      ),
+    },
+  },
   test: {
     environment: "node",
     globals: true,