From ff7d4a32046613363db3cf3eb221e51dfe10019f Mon Sep 17 00:00:00 2001
From: Fredrik Karlsson <bjorn.fredrik.karlsson@gmail.com>
Date: Tue, 28 Jul 2026 11:18:00 +0200
Subject: [PATCH] usage: plumbing

---
 Examples/EmoWasmExample/browser.html      |  29 ++-
 Examples/EmoWasmExample/main.mjs          |  10 +-
 Examples/EmoWasmExample/node_modules      |   1 -
 Package.resolved                          |  42 ++--
 Package.swift                             |   3 +-
 Sources/Emo/ModelLoading.swift            |  16 +-
 Sources/EmoAndroid/CABI.swift             |  37 +++-
 Sources/EmoWeb/main.swift                 |  40 +++-
 Tests/EmoTests/UsageTests.swift           | 234 ++++++++++++++++++++++
 packages/emo-node/browser.js              |   6 +-
 packages/emo-node/index.d.ts              |   7 +
 packages/emo-node/node.js                 |  43 +++-
 packages/emo-node/package.json            |   4 +-
 packages/emo-node/test/callgroup.test.mjs |  76 +++++++
 14 files changed, 502 insertions(+), 46 deletions(-)
 delete mode 120000 Examples/EmoWasmExample/node_modules
 create mode 100644 Tests/EmoTests/UsageTests.swift
 create mode 100644 packages/emo-node/test/callgroup.test.mjs

diff --git a/Examples/EmoWasmExample/browser.html b/Examples/EmoWasmExample/browser.html
index 09aaef6..86d2176 100644
--- a/Examples/EmoWasmExample/browser.html
+++ b/Examples/EmoWasmExample/browser.html
@@ -7,14 +7,34 @@
     "imports": {
       "@bjorn3/browser_wasi_shim": "/packages/emo-node/node_modules/@bjorn3/browser_wasi_shim/dist/index.js",
       "@desert-ant-labs/emo": "/packages/emo-node/browser.js",
+      "#platform": "/packages/emo-node/platform-browser.js",
+      "@desert-ant-labs/core": "/packages/emo-node/node_modules/@desert-ant-labs/core/index.js",
       "@litertjs/core": "/packages/emo-node/node_modules/@litertjs/core/dist/index.js",
       "@litertjs/wasm-utils": "/packages/emo-node/node_modules/@litertjs/wasm-utils/dist/index.js"
     }
   }
 </script>
+<script>
+  // Enable DAL HTTP request logging (must run before modules load).
+  globalThis.__dalHttpDebug = true;
+  globalThis.__dalAppId = "ai.desertant.wasm.browser";
+</script>
 <script type="module">
   import * as litert from "@litertjs/core";
 
+  // A self-provided, stable per-device id. Multi-tenant WebAssembly hosts pass
+  // their own device id per call; the core binds it into the InferenceContext
+  // for that call, so usage is attributed to this device (safe under
+  // concurrency). Here we persist one in localStorage across reloads.
+  function selfProvidedDeviceId() {
+    let id = localStorage.getItem("emoDeviceId");
+    if (!id) {
+      id = crypto.randomUUID();
+      localStorage.setItem("emoDeviceId", id);
+    }
+    return id;
+  }
+
   async function run() {
     const { Emo } = await import("@desert-ant-labs/emo");
     // Emo downloads, verifies, and caches the model from the Hub; LiteRT.js
@@ -25,7 +45,14 @@
     });
 
     const start = performance.now();
-    const suggestions = await emo.suggestions("Pay my bills", { limit: 3 });
+    const suggestions = await emo.suggestions("Pay my bills", {
+      limit: 3,
+      deviceId: selfProvidedDeviceId,
+    });
+    // Force the usage telemetry POST out now and await it before continuing.
+    if (globalThis.__EmoExports?.flushTelemetry) {
+      await globalThis.__EmoExports.flushTelemetry();
+    }
     return { suggestions, ms: Math.round(performance.now() - start) };
   }
 
diff --git a/Examples/EmoWasmExample/main.mjs b/Examples/EmoWasmExample/main.mjs
index e8c890f..c287b1d 100644
--- a/Examples/EmoWasmExample/main.mjs
+++ b/Examples/EmoWasmExample/main.mjs
@@ -3,14 +3,20 @@
 // server-side - no browser, no LiteRT.js needed. (The browser example,
 // browser.html / `npm run browser-example`, exercises the WebAssembly +
 // LiteRT.js path instead.)
-import { Emo } from "@desert-ant-labs/emo";
+// Enable DAL HTTP request logging. Set before importing Emo: static imports
+// are hoisted, so we use a dynamic import below to guarantee ordering.
+globalThis.__dalHttpDebug = true;
+const { Emo } = await import("@desert-ant-labs/emo");
 
 // Emo downloads, verifies (SHA-256), and caches the model from the Hub, then
 // runs inference through the native core. First run fetches; later runs cache.
 const emo = await Emo.load({});
 
 const start = Date.now();
-const suggestions = await emo.suggestions("Pay my bills", { limit: 3 });
+// `deviceId` attributes usage to a specific end-user device on multi-tenant
+// hosts (a string, or a zero-arg function returning one). Omit for the host
+// device. Collected per call, so it is safe under concurrency.
+const suggestions = await emo.suggestions("Pay my bills", { limit: 3, deviceId: "user-42" });
 console.log("suggestions:", suggestions.map((s) => s.emoji).join(" "));
 console.log(JSON.stringify(suggestions, null, 2));
 console.log(`(${Date.now() - start} ms)`);
diff --git a/Examples/EmoWasmExample/node_modules b/Examples/EmoWasmExample/node_modules
deleted file mode 120000
index ffc6bcb..0000000
--- a/Examples/EmoWasmExample/node_modules
+++ /dev/null
@@ -1 +0,0 @@
-/tmp/pw/node_modules
\ No newline at end of file
diff --git a/Package.resolved b/Package.resolved
index 34c9f5a..43ddaf3 100644
--- a/Package.resolved
+++ b/Package.resolved
@@ -1,33 +1,33 @@
 {
-  "originHash": "d7822dc62dca9725217c2bfa62b70baab94c0e3502460f8ca8eb132f7c194347",
-  "pins": [
+  "originHash" : "4d3f09eb8643dd8ad73fc26db50f173f23b02e53ec0a8013e2b84414c23b244d",
+  "pins" : [
     {
-      "identity": "desert-ant-core",
-      "kind": "remoteSourceControl",
-      "location": "https://github.com/Desert-Ant-Labs/desert-ant-core.git",
-      "state": {
-        "revision": "134e85d725aab94f2f4a7bcf014af1688227bce0",
-        "version": "0.5.3"
+      "identity" : "desert-ant-core",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/Desert-Ant-Labs/desert-ant-core.git",
+      "state" : {
+        "branch" : "a967f68",
+        "revision" : "a967f6833e7f928a8e494a8cbc6f5a8d81e97e0f"
       }
     },
     {
-      "identity": "javascriptkit",
-      "kind": "remoteSourceControl",
-      "location": "https://github.com/swiftwasm/JavaScriptKit",
-      "state": {
-        "revision": "22905075f8b61834810babe5fb9a2f613f22f398",
-        "version": "0.56.1"
+      "identity" : "javascriptkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftwasm/JavaScriptKit",
+      "state" : {
+        "revision" : "22905075f8b61834810babe5fb9a2f613f22f398",
+        "version" : "0.56.1"
       }
     },
     {
-      "identity": "swift-syntax",
-      "kind": "remoteSourceControl",
-      "location": "https://github.com/swiftlang/swift-syntax",
-      "state": {
-        "revision": "79e4b74a295b6eb74a8b585e3a39d29e70c1dbd1",
-        "version": "603.0.2"
+      "identity" : "swift-syntax",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-syntax",
+      "state" : {
+        "revision" : "79e4b74a295b6eb74a8b585e3a39d29e70c1dbd1",
+        "version" : "603.0.2"
       }
     }
   ],
-  "version": 3
+  "version" : 3
 }
diff --git a/Package.swift b/Package.swift
index b97ea40..3ec3978 100644
--- a/Package.swift
+++ b/Package.swift
@@ -37,7 +37,7 @@ let jsDependencies: [Package.Dependency] = noJavaScriptKit ? [] : [
 let packageDependencies: [Package.Dependency] = [
     // Reusable cross-platform primitives (JSON, ModelStore, TextNormalization,
     // Inference, FFIBuffer, HostBridge, PlatformSupport, ModelResources).
-    .package(url: "https://github.com/Desert-Ant-Labs/desert-ant-core.git", from: "0.5.3"),
+    .package(url: "https://github.com/Desert-Ant-Labs/desert-ant-core.git", revision: "a967f68"),
 ] + jsDependencies
 
 let wasmProducts: [Product] = noJavaScriptKit ? [] : [
@@ -111,6 +111,7 @@ let androidTarget: Target = .target(
     dependencies: [
         "Emo",
         .product(name: "FFIBuffer", package: "desert-ant-core"),
+        .product(name: "Inference", package: "desert-ant-core"),
         .product(name: "HostBridge", package: "desert-ant-core", condition: .when(platforms: [.android])),
         .product(name: "ModelStore", package: "desert-ant-core", condition: .when(platforms: [.android])),
         .product(name: "PlatformSupport", package: "desert-ant-core"),
diff --git a/Sources/Emo/ModelLoading.swift b/Sources/Emo/ModelLoading.swift
index 0254eec..964eb06 100644
--- a/Sources/Emo/ModelLoading.swift
+++ b/Sources/Emo/ModelLoading.swift
@@ -12,6 +12,14 @@ import EmoCoreMLResources
 import EmoTFLiteResources
 #endif
 
+/// This SDK's usage identity, attached to every emitted telemetry body's `sdk`
+/// field so usage attributes to Emo (not the underlying desert-ant-core).
+let emoSDKInfo = SDKInfo(name: "Emo", version: emoSDKVersion)
+
+/// The Emo SDK version. Keep in sync with the package version (single-sourced
+/// from packages/emo-node/package.json; see `mise run set-version`).
+let emoSDKVersion = "0.7.0"
+
 /// The model's file names and per-platform artifacts, in one place.
 enum EmoModel {
     static let meta = "emo_meta.json"
@@ -45,7 +53,7 @@ public struct ModelAssets: Sendable {
         self.init(
             metaJSON: metaJSON,
             tokenizer: tokenizerBytes,
-            session: try inferenceSession(modelBytes: modelBytes))
+            session: try inferenceSession(modelBytes: modelBytes, sdk: emoSDKInfo))
     }
 
     /// Bindings entry point: load the artifact from a file path (the Node
@@ -58,7 +66,7 @@ public struct ModelAssets: Sendable {
         self.init(
             metaJSON: metaJSON,
             tokenizer: tokenizerBytes,
-            session: try inferenceSession(modelPath: modelPath))
+            session: try inferenceSession(modelPath: modelPath, sdk: emoSDKInfo))
     }
 
     /// Bindings entry point: build from an already-constructed session (e.g. the
@@ -76,7 +84,7 @@ public struct ModelAssets: Sendable {
         ModelAssets(
             metaJSON: try files.readString(EmoModel.meta),
             tokenizer: try files.read(EmoModel.tokenizer),
-            session: try await files.inferenceSession(model: EmoModel.artifact, hostGlobal: "__EmoHost"))
+            session: try await files.inferenceSession(model: EmoModel.artifact, hostGlobal: "__EmoHost", sdk: emoSDKInfo))
     }
 }
 
@@ -204,7 +212,7 @@ extension ModelAssets {
             return ModelAssets(
                 metaJSON: try resources.readString(EmoModel.meta),
                 tokenizer: try resources.read(EmoModel.tokenizer),
-                session: try inferenceSession(modelPath: try resources.path(EmoModel.artifact)))
+                session: try inferenceSession(modelPath: try resources.path(EmoModel.artifact), sdk: emoSDKInfo))
         } catch {
             throw EmoError.modelNotFound
         }
diff --git a/Sources/EmoAndroid/CABI.swift b/Sources/EmoAndroid/CABI.swift
index 3295ae5..261fe21 100644
--- a/Sources/EmoAndroid/CABI.swift
+++ b/Sources/EmoAndroid/CABI.swift
@@ -1,6 +1,7 @@
 #if !os(WASI)
 @_spi(EmoBindings) import Emo
 import FFIBuffer
+import Inference   // InferenceContext.withCallGroup(id:), for grouped runs
 import PlatformSupport
 
 // C ABI over the Emo core, called by the Swift JNI entry points in
@@ -14,6 +15,7 @@ import PlatformSupport
 //   emo_is_downloaded(handle)                                  -> 0/1
 //   emo_download(handle)                                       -> 0/-1  (blocks)
 //   emo_run(handle, textUTF8, limit, skinTone)                 -> buffer | NULL
+//   emo_run_grouped(handle, textUTF8, limit, skinTone, groupId)-> buffer | NULL
 //   emo_destroy(handle)
 //   emo_string_free(ptr)
 //
@@ -115,12 +117,45 @@ public func emo_download(_ handle: UnsafeMutableRawPointer?) -> Int32 {
 public func emo_run(
     _ handle: UnsafeMutableRawPointer?, _ text: UnsafePointer<CChar>?,
     _ limit: Int32, _ skinToneRaw: Int32
+) -> UnsafeMutablePointer<CChar>? {
+    runSuggestions(handle, text, limit, skinToneRaw, groupId: nil)
+}
+
+/// Like `emo_run`, but attributes usage to the shared call group named `groupId`
+/// (reused across SDKs, via desert-ant-core): every run sharing the id bills as
+/// one call, and to a specific end-user `deviceId` (multi-tenant hosts serving
+/// many users). Both are optional — pass NULL to omit either. Used by the Node
+/// build; each call binds its own device, safe under concurrency. Release the
+/// call group with `dal_call_group_end`. (Android calls plain `emo_run` and
+/// resolves its own device via the host bridge, so it needs no `deviceId` here.)
+@_cdecl("emo_run_grouped")
+public func emo_run_grouped(
+    _ handle: UnsafeMutableRawPointer?, _ text: UnsafePointer<CChar>?,
+    _ limit: Int32, _ skinToneRaw: Int32,
+    _ groupId: UnsafePointer<CChar>?, _ deviceId: UnsafePointer<CChar>?
+) -> UnsafeMutablePointer<CChar>? {
+    runSuggestions(
+        handle, text, limit, skinToneRaw,
+        groupId: groupId.map { String(cString: $0) },
+        deviceId: deviceId.map { String(cString: $0) })
+}
+
+/// Shared body for `emo_run`/`emo_run_grouped`: run and encode suggestions,
+/// binding the shared call group `groupId` and the end-user `deviceId` into the
+/// InferenceContext when set.
+private func runSuggestions(
+    _ handle: UnsafeMutableRawPointer?, _ text: UnsafePointer<CChar>?,
+    _ limit: Int32, _ skinToneRaw: Int32, groupId: String?, deviceId: String? = nil
 ) -> UnsafeMutablePointer<CChar>? {
     guard let emo = emo(handle), let text else { return nil }
     let phrase = String(cString: text)
     let tone = skinTone(skinToneRaw)
     let payload: [UInt8]? = blockingValue {
-        let suggestions = (try? await emo.suggestions(for: phrase, limit: Int(limit), skinTone: tone)) ?? []
+        let suggestions = await InferenceContext.$deviceId.withValue(deviceId) {
+            await InferenceContext.withCallGroup(id: groupId) {
+                (try? await emo.suggestions(for: phrase, limit: Int(limit), skinTone: tone)) ?? []
+            }
+        }
         var w = FFIWriter()
         w.u32(suggestions.count)
         for s in suggestions {
diff --git a/Sources/EmoWeb/main.swift b/Sources/EmoWeb/main.swift
index f170610..0fad1a1 100644
--- a/Sources/EmoWeb/main.swift
+++ b/Sources/EmoWeb/main.swift
@@ -2,6 +2,7 @@
 import Inference
 import JavaScriptEventLoop
 import JavaScriptKit
+import Usage
 @_spi(EmoBindings) import Emo
 
 // WebAssembly entry point. Mirrors the iOS/Swift SDK (suggestion only). The JS
@@ -10,11 +11,15 @@ import JavaScriptKit
 // start, the module exposes:
 //
 //     globalThis.__EmoExports = {
-//       load(cacheRoot, directory?, onProgress?)  -> Promise<boolean>,
-//       loadBundled(metaJSON, tokenizerBytes)     -> Promise<boolean>,
-//       suggest(text, limit?, skinTone?)          -> Promise<[{emoji, confidence}]>,
+//       load(cacheRoot, directory?, onProgress?)          -> Promise<boolean>,
+//       loadBundled(metaJSON, tokenizerBytes, modelBytes) -> Promise<boolean>,
+//       suggest(text, limit?, skinTone?, deviceId?)       -> Promise<[{emoji, confidence}]>,
 //     }
 //
+// `deviceId` may be a string or a zero-arg function returning one; it is
+// collected per call and bound to that call's task tree (safe for concurrent
+// multi-tenant hosts), attributing usage to a specific end-user device.
+//
 // `skinTone` is a number: 0 default, 1 light, 2 mediumLight, 3 medium,
 // 4 mediumDark, 5 dark. `packages/emo-node` wraps this in the public typed API;
 // nothing else should touch these globals.
@@ -48,14 +53,26 @@ private func encode(_ suggestions: [EmoSuggestion]) -> JSValue {
     return .object(arr)
 }
 
+private func collectDeviceId(_ value: JSValue?) -> String? {
+    guard let value else { return nil }
+    if let string = value.string, !string.isEmpty { return string }
+    if let getter = value.function, let string = getter().string, !string.isEmpty { return string }
+    return nil
+}
+
 let suggestFn = JSClosure { args in
     let text = args.first?.string ?? ""
     let limit = args.count > 1 ? Int(args[1].number ?? 3) : 3
     let tone = skinTone(args.count > 2 ? args[2].number : nil)
+    // Collect the per-call device id now (before any await), then bind it to
+    // this call's task tree so concurrent calls stay isolated.
+    let deviceId = collectDeviceId(args.count > 3 ? args[3] : nil)
     return JSPromise { resolve in
         Task {
             do {
-                let suggestions = try await instance().suggestions(for: text, limit: limit, skinTone: tone)
+                let suggestions = try await InferenceContext.$deviceId.withValue(deviceId) {
+                    try await instance().suggestions(for: text, limit: limit, skinTone: tone)
+                }
                 resolve(.success(encode(suggestions)))
             } catch {
                 resolve(.failure(.string(String(describing: error))))
@@ -108,7 +125,7 @@ let loadBundledFn = JSClosure { args in
                 guard let metaJSON, let tokenizer else { throw EmoError.modelNotFound }
                 let assets = try ModelAssets(
                     metaJSON: metaJSON, tokenizer: tokenizer,
-                    session: JSInferenceSession(hostGlobal: "__EmoHost"))
+                    session: inferenceSession(hostGlobal: "__EmoHost"))
                 let emo = Emo(assets: assets)
                 try await emo.waitUntilLoaded()
                 suggester = emo
@@ -120,9 +137,22 @@ let loadBundledFn = JSClosure { args in
     }.jsValue
 }
 
+// flushTelemetry(): force any tracked session to emit now (bypassing the 3s
+// debounce + re-emit window) and await the send, so the usage POST actually
+// goes out before the caller continues. Requires `globalThis.__dalHttpDebug`.
+let flushTelemetryFn = JSClosure { _ in
+    JSPromise { resolve in
+        Task {
+            await TelemetryDebug.shared.flushAndWait()
+            resolve(.success(.boolean(true)))
+        }
+    }.jsValue
+}
+
 let exports = JSObject.global.Object.function!.new()
 exports.load = .object(loadFn)
 exports.loadBundled = .object(loadBundledFn)
 exports.suggest = .object(suggestFn)
+exports.flushTelemetry = .object(flushTelemetryFn)
 JSObject.global.__EmoExports = .object(exports)
 #endif
diff --git a/Tests/EmoTests/UsageTests.swift b/Tests/EmoTests/UsageTests.swift
new file mode 100644
index 0000000..adf1563
--- /dev/null
+++ b/Tests/EmoTests/UsageTests.swift
@@ -0,0 +1,234 @@
+import Foundation
+import Testing
+@testable import Emo
+import Inference
+
+#if canImport(CoreML)
+import EmoCoreMLResources
+#elseif os(Linux) || os(Windows)
+import EmoTFLiteResources
+#endif
+
+#if canImport(Glibc)
+import Glibc
+#endif
+
+/// End-to-end check that running an Emo suggestion propagates a usage turnstile
+/// all the way through desert-ant-core: the tracked inference session opens a
+/// turnstile, records the call, and the `Usage` transport POSTs the wire body.
+///
+/// The `Usage` transport is fire-and-forget against a fixed ingest endpoint, so
+/// this test uses the two supported diagnostic hooks:
+///   - `DAL_INGEST_ENDPOINT` redirects the POST to a local capture server, and
+///   - `DAL_HTTP_DEBUG` installs the force-flush + await-send hooks so we can
+///     make the debounced send go out now and wait for it to land.
+///
+/// Only runs where the native URLSession transport exists (Apple/Linux).
+#if canImport(CoreML) || os(Linux)
+struct UsageTests {
+    private func makeEmo() -> Emo {
+        #if canImport(CoreML)
+        return Emo(bundle: EmoCoreMLResourcesBundle.bundle)
+        #elseif os(Linux) || os(Windows)
+        return Emo(bundle: EmoTFLiteResourcesBundle.bundle)
+        #else
+        fatalError("no bundled model for this platform")
+        #endif
+    }
+
+    @Test func suggestionEmitsUsageThroughCore() async throws {
+        let server = try CaptureServer()
+        defer { server.stop() }
+
+        setenv("DAL_INGEST_ENDPOINT", "http://127.0.0.1:\(server.port)/api/v1/ingest", 1)
+        setenv("DAL_HTTP_DEBUG", "1", 1)
+        defer {
+            unsetenv("DAL_INGEST_ENDPOINT")
+            unsetenv("DAL_HTTP_DEBUG")
+        }
+
+        let emo = makeEmo()
+        let results = try await emo.suggestions(for: "Pay my bills", limit: 3)
+        #expect(results.count == 3)
+
+        await TelemetryDebug.shared.flushAndWait()
+
+        let body = try await server.awaitBody(timeout: 5)
+        let ingest = try JSONDecoder().decode(IngestBody.self, from: body)
+
+        #expect(ingest.platform == defaultPlatform)
+        #expect(["com.apple.dt.xctest.tool", "swiftpm-testing-helper"].contains(ingest.app?.id))
+        #expect(ingest.sdk.name == "Emo")
+        #expect(ingest.sdk.version == emoSDKVersion)
+        #expect(!ingest.events.isEmpty)
+
+        let load = try #require(ingest.events.first)
+        #expect(load.name == "load")
+        #expect(!load.deviceId.isEmpty)
+        #expect((load.callCount ?? 0) >= 1)
+    }
+
+    /// Several runs wrapped in `InferenceContext.withCallGroup` bill as a single
+    /// usage call; the same runs without a group bill individually. Uses a fresh
+    /// app id (turnstile namespace) per case so the turnstile actually emits, and
+    /// lets the debounce flush send — no forced-flush debug path to skew counts.
+    @Test func callGroupCoalescesRunsIntoOneCall() async throws {
+        // Grouped: three suggestions inside one call group -> callCount == 1.
+        let grouped = try await capturedCallCount() { emo in
+            try await InferenceContext.withCallGroup {
+                for _ in 0..<3 { _ = try await emo.suggestions(for: "Pay my bills", limit: 1) }
+            }
+        }
+        #expect(grouped == 1)
+
+        // Control: the same three suggestions with no group -> callCount == 3.
+        let ungrouped = try await capturedCallCount() { emo in
+            for _ in 0..<3 { _ = try await emo.suggestions(for: "Pay my bills", limit: 1) }
+        }
+        #expect(ungrouped == 3)
+    }
+
+    /// Run `body` against a fresh Emo whose usage POST is captured locally, and
+    /// return the emitted `callCount`. A unique `appId` gives a fresh turnstile
+    /// namespace so the load actually emits; the ~3s debounce does the send.
+    private func capturedCallCount(
+        _ body: (Emo) async throws -> Void
+    ) async throws -> Int? {
+        let server = try CaptureServer()
+        defer { server.stop() }
+        setenv("DAL_INGEST_ENDPOINT", "http://127.0.0.1:\(server.port)/api/v1/ingest", 1)
+        defer { unsetenv("DAL_INGEST_ENDPOINT") }
+
+        let emo = makeEmo()
+        try await body(emo)
+
+        // Wait out the tracked session's debounce (default ~3s) + the send.
+        let data = try await server.awaitBody(timeout: 10)
+        withExtendedLifetime(emo) {}
+        let ingest = try JSONDecoder().decode(IngestBody.self, from: data)
+        return try #require(ingest.events.first).callCount
+    }
+}
+
+/// A minimal, single-request HTTP server over POSIX sockets. It accepts one
+/// connection, reads the full request (headers + body via Content-Length), and
+/// replies `200 OK`. Enough to capture the usage POST in a test.
+private final class CaptureServer: @unchecked Sendable {
+    let port: UInt16
+    private let listenFD: Int32
+    private let lock = NSLock()
+    private var captured: Data?
+    private var running = true
+
+    init() throws {
+        let fd = socket(AF_INET, SOCK_STREAM_VALUE, 0)
+        guard fd >= 0 else { throw ServerError.socket }
+
+        var yes: Int32 = 1
+        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &yes, socklen_t(MemoryLayout<Int32>.size))
+
+        var addr = sockaddr_in()
+        addr.sin_family = sa_family_t(AF_INET)
+        addr.sin_port = 0 // ask the OS for an ephemeral port
+        addr.sin_addr.s_addr = inet_addr("127.0.0.1")
+
+        let bindResult = withUnsafePointer(to: &addr) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                bind(fd, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+            }
+        }
+        guard bindResult == 0 else { close(fd); throw ServerError.bind }
+        guard listen(fd, 1) == 0 else { close(fd); throw ServerError.listen }
+
+        // Read back the assigned port.
+        var bound = sockaddr_in()
+        var len = socklen_t(MemoryLayout<sockaddr_in>.size)
+        _ = withUnsafeMutablePointer(to: &bound) {
+            $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                getsockname(fd, $0, &len)
+            }
+        }
+        port = UInt16(bigEndian: bound.sin_port)
+        listenFD = fd
+
+        Thread.detachNewThread { [fd] in self.serve(fd) }
+    }
+
+    private func serve(_ fd: Int32) {
+        let clientFD = accept(fd, nil, nil)
+        guard clientFD >= 0 else { return }
+        defer { close(clientFD) }
+
+        var request = Data()
+        var buffer = [UInt8](repeating: 0, count: 4096)
+        var headerEnd: Range<Data.Index>?
+
+        // Read until we have the header terminator, then the full body.
+        while running {
+            let n = read(clientFD, &buffer, buffer.count)
+            if n <= 0 { break }
+            request.append(contentsOf: buffer[0..<n])
+
+            if headerEnd == nil {
+                headerEnd = request.range(of: Data("\r\n\r\n".utf8))
+            }
+            if let he = headerEnd {
+                let header = String(decoding: request[request.startIndex..<he.lowerBound], as: UTF8.self)
+                let contentLength = Self.contentLength(header) ?? 0
+                let bodyStart = he.upperBound
+                if request.distance(from: bodyStart, to: request.endIndex) >= contentLength {
+                    let body = request[bodyStart..<request.index(bodyStart, offsetBy: contentLength)]
+                    setCaptured(Data(body))
+                    break
+                }
+            }
+        }
+
+        let response = "HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+        _ = response.utf8.withContiguousStorageIfAvailable { ptr in
+            write(clientFD, ptr.baseAddress, ptr.count)
+        }
+    }
+
+    private static func contentLength(_ header: String) -> Int? {
+        for line in header.split(separator: "\r\n") {
+            let parts = line.split(separator: ":", maxSplits: 1)
+            if parts.count == 2, parts[0].lowercased() == "content-length" {
+                return Int(parts[1].trimmingCharacters(in: .whitespaces))
+            }
+        }
+        return nil
+    }
+
+    private func setCaptured(_ data: Data) {
+        lock.lock(); captured = data; lock.unlock()
+    }
+
+    private func takeCaptured() -> Data? {
+        lock.lock(); defer { lock.unlock() }; return captured
+    }
+
+    func awaitBody(timeout: TimeInterval) async throws -> Data {
+        let deadline = Date().addingTimeInterval(timeout)
+        while Date() < deadline {
+            if let body = takeCaptured() { return body }
+            try await Task.sleep(nanoseconds: 50_000_000)
+        }
+        throw ServerError.timeout
+    }
+
+    func stop() {
+        running = false
+        close(listenFD)
+    }
+
+    enum ServerError: Error { case socket, bind, listen, timeout }
+}
+
+// SOCK_STREAM is an enum on Darwin and a raw Int32 on Glibc; normalize it.
+#if canImport(Glibc)
+private let SOCK_STREAM_VALUE = Int32(SOCK_STREAM.rawValue)
+#else
+private let SOCK_STREAM_VALUE = SOCK_STREAM
+#endif
+#endif
diff --git a/packages/emo-node/browser.js b/packages/emo-node/browser.js
index 81f029d..a28d104 100644
--- a/packages/emo-node/browser.js
+++ b/packages/emo-node/browser.js
@@ -96,11 +96,15 @@ export class Emo {
   /**
    * Suggest emojis for a phrase, most likely first. Returns up to `limit`
    * `{ emoji, confidence }` suggestions; empty input returns `[]`.
+   *
+   * `options.deviceId` (a string or a zero-arg function returning one)
+   * attributes usage to a specific end-user device. It is collected per call
+   * and bound to that call, so it is safe for concurrent multi-tenant hosts.
    */
   async suggestions(text, options = {}) {
     const limit = options.limit ?? 3;
     const skinTone = SKIN_TONES[options.skinTone ?? "default"] ?? 0;
-    return core.suggest(String(text ?? ""), limit, skinTone);
+    return core.suggest(String(text ?? ""), limit, skinTone, options.deviceId);
   }
 
   /**
diff --git a/packages/emo-node/index.d.ts b/packages/emo-node/index.d.ts
index 706b376..3375b10 100644
--- a/packages/emo-node/index.d.ts
+++ b/packages/emo-node/index.d.ts
@@ -21,6 +21,13 @@ export interface SuggestOptions {
   limit?: number;
   /** Preferred skin tone for skin-tone-capable emoji (default `"default"`). */
   skinTone?: EmojiSkinTone;
+  /**
+   * Attributes usage to a specific end-user device (multi-tenant hosts serving
+   * many users). A string, or a zero-arg function returning one, collected per
+   * call and bound to that call so it is safe under concurrency. Omit to use
+   * the default device. Honored by both the WebAssembly and native Node builds.
+   */
+  deviceId?: string | (() => string);
 }
 
 /**
diff --git a/packages/emo-node/node.js b/packages/emo-node/node.js
index 808d963..e888538 100644
--- a/packages/emo-node/node.js
+++ b/packages/emo-node/node.js
@@ -27,16 +27,17 @@ const core = loadNative({
     create: "void* emo_create(const char*, const char*)",
     isDownloaded: "int emo_is_downloaded(void*)",
     download: "int emo_download(void*)",
-    run: "void* emo_run(void*, const char*, int, int)",
+    runGrouped: "void* emo_run_grouped(void*, const char*, int, int, const char*, const char*)",
     destroy: "void emo_destroy(void*)",
     stringFree: "void emo_string_free(void*)",
   },
 });
-const { lib, callAsync, decodeResult } = core;
+const { lib, callAsync, decodeResult, withCallGroup } = core;
 
-/** Decode the FFI buffer the core returns: a u32 count, then per suggestion a
- *  u32-length UTF-8 emoji string and an IEEE-754 double confidence, read off the
- *  shared FfiReader. Mirrors `emo_run` in Sources/EmoAndroid/CABI.swift. */
+/** Decode the FFI buffer the core returns (via `decodeResult`, positioned at the
+ *  payload): a u32 count, then per suggestion a u32-length UTF-8 emoji string
+ *  and an IEEE-754 double confidence. Mirrors `emo_run` in
+ *  Sources/EmoAndroid/CABI.swift and the Kotlin FfiReader. */
 function decodeSuggestions(r) {
   const count = r.u32();
   const out = [];
@@ -99,6 +100,15 @@ export class Emo {
   /**
    * Suggest emojis for `text`, most likely first. Returns up to `limit`
    * `{ emoji, confidence }` suggestions; empty input returns `[]`.
+   *
+   * Usage is tracked automatically. By default each call is its own billed
+   * usage call. Pass `options.group` (an id from {@link withCallGroup}) to bill
+   * several calls as one — a logical operation made of multiple suggestions.
+   *
+   * Pass `options.deviceId` (a string, or a zero-arg function returning one) to
+   * attribute usage to a specific end-user device on multi-tenant hosts. It is
+   * collected per call and bound to that call, so it is safe under concurrency.
+   * Omit to attribute to the host device.
    */
   async suggestions(text, options = {}) {
     if (!this.#handle) throw new Error("@desert-ant-labs/emo: suggester disposed");
@@ -106,7 +116,10 @@ export class Emo {
     if (phrase.trim() === "") return [];
     const limit = options.limit ?? 3;
     const skinTone = SKIN_TONES[options.skinTone ?? "default"] ?? 0;
-    const ptr = await callAsync(lib.run, this.#handle, phrase, limit, skinTone);
+    const deviceId = typeof options.deviceId === "function" ? options.deviceId() : options.deviceId;
+    const group = options.group != null ? String(options.group) : null;
+    const ptr = await callAsync(
+      lib.runGrouped, this.#handle, phrase, limit, skinTone, group, deviceId != null ? String(deviceId) : null);
     if (!ptr) throw new Error("@desert-ant-labs/emo: suggestion failed");
     try {
       return decodeSuggestions(decodeResult(ptr));
@@ -115,6 +128,24 @@ export class Emo {
     }
   }
 
+  /**
+   * Run `body` with a call group, so every `suggestions({ group })` inside it
+   * bills as a single usage call (rather than one per suggestion). Use it for a
+   * logical operation that issues several suggestions but should count once:
+   *
+   * ```js
+   * await emo.withCallGroup(async (group) => {
+   *   await emo.suggestions("a", { group });
+   *   await emo.suggestions("b", { group });  // same group -> counted as one call
+   * });
+   * ```
+   *
+   * The group is released when `body` settles.
+   */
+  withCallGroup(body) {
+    return withCallGroup(body);
+  }
+
   /** Free the native handle. Call when you are done with the suggester. */
   dispose() {
     if (this.#handle) { lib.destroy(this.#handle); this.#handle = null; }
diff --git a/packages/emo-node/package.json b/packages/emo-node/package.json
index 369ba41..35195e0 100644
--- a/packages/emo-node/package.json
+++ b/packages/emo-node/package.json
@@ -63,9 +63,7 @@
   ],
   "dependencies": {
     "@bjorn3/browser_wasi_shim": "^0.3.0",
-    "@desert-ant-labs/core": "^0.3.0"
-  },
-  "optionalDependencies": {
+    "@desert-ant-labs/core": "^0.6.0",
     "koffi": "^2.9.0"
   },
   "peerDependencies": {
diff --git a/packages/emo-node/test/callgroup.test.mjs b/packages/emo-node/test/callgroup.test.mjs
new file mode 100644
index 0000000..50d38c3
--- /dev/null
+++ b/packages/emo-node/test/callgroup.test.mjs
@@ -0,0 +1,76 @@
+// Usage call-group tests for the native (server-side) Node core. They show the
+// two ways usage attributes to billed calls:
+//
+//   1. Default  — each suggestions() is its own billed call.
+//   2. Grouped  — emo.withCallGroup(async (group) => { ...({ group }) }) bills
+//                 every suggestion inside as a single call.
+//
+// The usage transport POSTs a `load` body fire-and-forget on a short debounce.
+// We redirect it to a local capture server (DAL_INGEST_ENDPOINT) and read back
+// the emitted callCount. A unique DAL_APP_ID per case gives a fresh turnstile
+// namespace so the load actually emits. Env is set before the first run, since
+// the native usage client reads it (getenv) when it is first built.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import http from "node:http";
+import { randomUUID } from "node:crypto";
+
+// A one-shot server that captures the first POSTed usage body and resolves it.
+function captureServer() {
+  let resolveBody;
+  const bodyPromise = new Promise((r) => (resolveBody = r));
+  const server = http.createServer((req, res) => {
+    let data = "";
+    req.on("data", (c) => (data += c));
+    req.on("end", () => {
+      res.writeHead(200).end();
+      resolveBody(JSON.parse(data));
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      resolve({ port: server.address().port, body: bodyPromise, close: () => server.close() });
+    });
+  });
+}
+
+// Load Emo fresh with the capture endpoint + a unique app id already in the env,
+// run `body(emo)`, and return the emitted callCount (waits out the ~3s debounce).
+async function capturedCallCount(body) {
+  const server = await captureServer();
+  process.env.DAL_INGEST_ENDPOINT = `http://127.0.0.1:${server.port}/api/v1/ingest`;
+  process.env.DAL_APP_ID = `ai.desertant.emo.callgroup.${randomUUID()}`;
+  try {
+    const { Emo } = await import(`../node.js?fresh=${randomUUID()}`);
+    const emo = await Emo.load();
+    await body(emo);
+    const ingest = await server.body;   // debounce (~3s) fires the POST
+    emo.dispose();
+    return ingest.events?.[0]?.callCount;
+  } finally {
+    server.close();
+    delete process.env.DAL_INGEST_ENDPOINT;
+    delete process.env.DAL_APP_ID;
+  }
+}
+
+let available = true;
+try { const { Emo } = await import("../node.js"); (await Emo.load()).dispose(); }
+catch { available = false; }
+const opts = available ? {} : { skip: "native core unavailable" };
+
+test("default: three suggestions bill as three usage calls", opts, async () => {
+  const count = await capturedCallCount(async (emo) => {
+    for (let i = 0; i < 3; i++) await emo.suggestions("Pay my bills", { limit: 1 });
+  });
+  assert.equal(count, 3);
+});
+
+test("grouped: three suggestions in a call group bill as one usage call", opts, async () => {
+  const count = await capturedCallCount(async (emo) => {
+    await emo.withCallGroup(async (group) => {
+      for (let i = 0; i < 3; i++) await emo.suggestions("Pay my bills", { limit: 1, group });
+    });
+  });
+  assert.equal(count, 1);
+});