cartethyia 2.7.2 → 2.7.4

package/src/providers/integrations/perplexity.ts

@@ -69,11 +69,11 @@ export function createPerplexityAdapter(fetchImpl?: typeof fetch): ProviderAdapt
       void _candidate;
       const query = extractSearchQuery(request);
       if (!query) {
-        throw new GatewayError("invalid_request", 400, "Search query is required.");
+        throw new GatewayError("invalid_request", 400, "Search query is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
       }
       const token = tokenFromContext(context);
       if (!token) {
-        throw new GatewayError("authentication_failed", 401, "Missing Perplexity API key");
+        throw new GatewayError("authentication_failed", 401, "Missing Perplexity API key (request {requestId}). Wrong key, right door — check the key 🔑");
       }
 
       const fetchFn = (context.outbound_fetch as unknown as typeof fetch | undefined) ?? fetchImpl ?? globalThis.fetch;

package/src/providers/integrations/qoder/qoder-catalog.ts

@@ -133,13 +133,15 @@ export const QODER_INTL_MODEL_CONFIGS: Readonly<Record<string, QoderModelConfig>
   qfmodel: { id: "qfmodel", display_name: "Qwen3.8-Flash", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: true, is_reasoning: true },
   qmodel_latest: { id: "qmodel_latest", display_name: "Qwen3.7-Max", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: false },
   qmodel: { id: "qmodel", display_name: "Qwen3.7-Plus", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: false },
-  kmodel_latest: { id: "kmodel_latest", display_name: "Kimi-K3", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: false, is_reasoning: false },
+  kmodel_latest: { id: "kmodel_latest", display_name: "Kimi-K3.1-Pro", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: false, is_reasoning: false },
   kmodel: { id: "kmodel", display_name: "Kimi-K2.8-Preview", max_input_tokens: 1000000, max_output_tokens: 65_536, is_vl: true, is_free: false, is_reasoning: false },
   gmodel: { id: "gmodel", display_name: "GLM-5.3", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_free: false, is_reasoning: true },
   gfmodel: { id: "gfmodel", display_name: "GLM-5.3-Flash", max_input_tokens: 1000000, max_output_tokens: 131_072, is_vl: true, is_reasoning: true },
   dmodel: { id: "dmodel", display_name: "DeepSeek-V4-Pro", max_input_tokens: 1000000, max_output_tokens: 384_000, is_vl: true, is_free: false, is_reasoning: true },
-  dfmodel: { id: "dfmodel", display_name: "DeepSeek-Flash", max_input_tokens: 1000000, max_output_tokens: 384_000, is_vl: true, is_free: true, is_reasoning: true },
-  mmodel: { id: "mmodel", display_name: "MiniMax-M3", max_input_tokens: 1000000, max_output_tokens: 512_000, is_vl: true, is_free: false, is_reasoning: false },
+  // Live roster (2026-11-01) reports dfmodel as billed (is_free false); it was
+  // previously marked free. Display names are corrected from the same capture.
+  dfmodel: { id: "dfmodel", display_name: "DeepSeek-Flash", max_input_tokens: 1000000, max_output_tokens: 384_000, is_vl: true, is_free: false, is_reasoning: true },
+  mmodel: { id: "mmodel", display_name: "MiniMax-M3.1-Flash", max_input_tokens: 1000000, max_output_tokens: 512_000, is_vl: true, is_free: false, is_reasoning: false },
 };
 
 /**
@@ -353,6 +355,14 @@ interface CachedRoster {
 /** Per-realm live-list cache; keyed by realm, not by account. */
 const discoveryCache = new Map<QoderRealm, CachedRoster>();
 
+/**
+ * Per-realm max-context window per roster key, taken from the live list's
+ * `context_config` (the widest selectable window). This is what dispatch reads
+ * to send `model_config.max_input_tokens`; without it the request would use the
+ * static roster's *currently active* window (often 180k) instead of the max.
+ */
+const discoveryMaxContextByKey = new Map<QoderRealm, Map<string, number>>();
+
 /**
  * Drops one realm's cached list.
  *
@@ -361,8 +371,21 @@ const discoveryCache = new Map<QoderRealm, CachedRoster>();
  * previous assertion left behind.
  */
 export function resetQoderDiscoveryCache(realm?: QoderRealm): void {
-  if (realm === undefined) discoveryCache.clear();
-  else discoveryCache.delete(realm);
+  if (realm === undefined) {
+    discoveryCache.clear();
+    discoveryMaxContextByKey.clear();
+  } else {
+    discoveryCache.delete(realm);
+    discoveryMaxContextByKey.delete(realm);
+  }
+}
+
+/**
+ * The widest selectable context window per roster key for one realm, from the
+ * live model list. Empty when discovery has not succeeded for that realm yet.
+ */
+export function qoderDiscoveredMaxContexts(realm: QoderRealm): ReadonlyMap<string, number> {
+  return discoveryMaxContextByKey.get(realm) ?? new Map();
 }
 
 export async function discoverQoderModels(input: {
@@ -389,7 +412,7 @@ export async function discoverQoderModels(input: {
     throw new GatewayError(
       "authentication_failed",
       401,
-      "Qoder model discovery requires an account credential.",
+      "Qoder model discovery requires an account credential (request {requestId}). Wrong key, right door — check the credential 🔑",
       { providerId, realm: input.realm },
     );
   }
@@ -398,7 +421,7 @@ export async function discoverQoderModels(input: {
     throw new GatewayError(
       "invalid_request",
       400,
-      "Qoder model discovery requires a validated outbound fetch",
+      "Qoder model discovery requires a validated outbound fetch (request {requestId}). No bridge to cross — configure a pool first 🏗️",
       { providerId, realm: input.realm },
     );
   }
@@ -409,6 +432,11 @@ export async function discoverQoderModels(input: {
     const url = `${host}${QODER_MODELS_PATH}`;
     try {
       const headers = await input.headers(url, signedBody);
+      // GET, not POST: upstream refuses POST on the model-list surface (400
+      // "Request method 'POST' not supported"). The signature covers the body,
+      // so the body must accompany the GET. The gateway's validated egress
+      // dials GET+body through the Node http(s) client (the runtime fetch
+      // rejects GET bodies), which is exactly the shape the donor client sends.
       const response = await fetcher(url, {
         method: "GET",
         headers: headers as unknown as HeadersInit,
@@ -430,9 +458,19 @@ export async function discoverQoderModels(input: {
         continue;
       }
       const models = enabled.map((entry) => qoderCatalogModel(entry, providerId));
+      // Index the widest selectable window per key (from `context_config`,
+      // already computed into `maxInputTokens` by `mapQoderCatalogResponse`) so
+      // dispatch can send the maximum rather than the currently active one.
+      const maxCtx = new Map<string, number>();
+      for (const entry of enabled) {
+        if (entry.maxInputTokens !== undefined && entry.key.length > 0) {
+          maxCtx.set(entry.key, entry.maxInputTokens);
+        }
+      }
       // Cached only after a host actually answered: a failure must stay
       // retryable on the next call rather than being frozen for five minutes.
       discoveryCache.set(input.realm, { at: Date.now(), models });
+      discoveryMaxContextByKey.set(input.realm, maxCtx);
       return models;
     } catch (error) {
       lastError = error;
@@ -441,9 +479,9 @@ export async function discoverQoderModels(input: {
   throw new GatewayError(
     "transport_unavailable",
     502,
-    `Qoder model discovery failed for ${input.realm}: ${
+    `Qoder model discovery failed for ${input.realm} (request {requestId}): ${
       lastError instanceof Error ? lastError.message : "unknown error"
-    }`,
+    }. The connection ghosted us — come back in a moment 👻`,
     { providerId, realm: input.realm },
     "upstream",
   );

package/src/providers/integrations/qoder/qoder-checkin.ts

@@ -17,6 +17,18 @@
  * the console surface treat Qoder like any other daily-grant provider.
  */
 import { QODER_REALMS, qoderRealmForProvider } from "./qoder-realm";
+import { getQoderVersion } from "../../operations/client-versions";
+import {
+  qoderMachineHeaders,
+  type QoderNativeIdentity,
+} from "./qoder-umid";
+import {
+  allocateQoderNativeIdentity,
+  ensureQoderNativeIdentity,
+  type QoderNativeIdentityStore,
+} from "./qoder-native-identity-store";
+import type { NativeIdentityRecord } from "../../../persistence/schema";
+import { log } from "../../../observability/logger";
 
 /** Structural fetch bound; Bun's own fetch type carries extra host props. */
 type Fetcher = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
@@ -37,6 +49,36 @@ const CHECKIN_CLAIM_PATH = "/sash/api/v1/me/daily-check-in/claim";
 const CAMPAIGNS_PATH = "/sash/api/v1/me/campaigns";
 const CAMPAIGN_CLAIM_PATH = "/sash/api/v1/me/campaigns/%s/claim";
 
+/**
+ * Headers the official desktop client sends to the `/sash` campaign surface.
+ * Without these — notably `cosy-clienttype`, `cosy-version`, and the `Qoder`
+ * user agent — the upstream hides the campaign list entirely
+ * (`showCampaign:false`), so the daily grant never appears. Verified live:
+ * the bare Authorization+Accept request returns an empty list, the desktop
+ * header set returns `showCampaign:true` with the campaigns populated.
+ *
+ * `native` optionally carries the UMID machine headers (see `qoder-umid`);
+ * when present they unlock the daily 100-credit campaign, which the server
+ * otherwise silently filters out.
+ */
+export function buildCampaignHeaders(
+  credential: string,
+  native?: Record<string, string>,
+): Record<string, string> {
+  return {
+    Authorization: `Bearer ${credential}`,
+    Accept: "application/json",
+    "User-Agent": "Qoder",
+    "Cosy-ClientType": "10",
+    "Cosy-Version": getQoderVersion(),
+    ...(native ?? {}),
+  };
+}
+
+function campaignHeaders(credential: string): Record<string, string> {
+  return buildCampaignHeaders(credential);
+}
+
 function asRecord(value: unknown): Record<string, unknown> | null {
   if (typeof value !== "object" || value === null) return null;
   return value as Record<string, unknown>;
@@ -80,19 +122,32 @@ function asState(state: string, today: string, lastClaimedAt: unknown): { active
   return { active, todayCheckedIn: claimedToday };
 }
 
-/** GET campaign list; returns `null` when the surface is unreachable/unauthorized. */
-async function fetchCampaigns(
+/**
+ * Normalizes one upstream campaign row to the snake_case shape the claim loop
+ * consumes. The API returns camelCase keys (`campaignId`, `actionType`,
+ * `claimStatus`); the fixtures and the donor hub use snake_case — accept both.
+ */
+function normalizeCampaign(raw: Record<string, unknown>): Record<string, unknown> {
+  const benefit = asRecord(raw["benefit"]);
+  return {
+    campaign_id: String(raw["campaignId"] ?? raw["campaign_id"] ?? ""),
+    campaign_key: String(raw["campaignKey"] ?? raw["campaign_key"] ?? ""),
+    action_type: String(raw["actionType"] ?? raw["action_type"] ?? ""),
+    claim_status: String(raw["claimStatus"] ?? raw["claim_status"] ?? ""),
+    ...(benefit !== null ? { benefit } : {}),
+  };
+}
+
+/** GET campaign list once with given headers; `null` when unreachable/unauthorized. */
+async function getCampaigns(
   base: string,
-  credential: string,
+  headers: Record<string, string>,
   fetcher: Fetcher,
 ): Promise<Record<string, unknown>[] | null> {
   try {
     const response = await fetcher(`${base}${CAMPAIGNS_PATH}`, {
       method: "GET",
-      headers: {
-        Authorization: `Bearer ${credential}`,
-        Accept: "application/json",
-      },
+      headers,
       signal: AbortSignal.timeout(TIMEOUT_MS),
     });
     if (response.status === 401 || response.status === 403) return null;
@@ -100,12 +155,112 @@ async function fetchCampaigns(
     const payload: unknown = await response.json().catch(() => null);
     const rec = asRecord(payload);
     const list = Array.isArray(rec?.["campaigns"]) ? rec!["campaigns"] : Array.isArray(payload) ? payload : null;
-    return Array.isArray(list) ? (list as Record<string, unknown>[]) : null;
+    if (!Array.isArray(list)) return null;
+    return (list as Record<string, unknown>[]).map(normalizeCampaign);
   } catch {
     return null;
   }
 }
 
+/**
+ * One attempted claim across a header set, returning the same result shape as
+ * `claimCampaign` (already-claimed grants resolve to `already_claimed`).
+ */
+async function tryClaimDaily(
+  base: string,
+  headers: Record<string, string>,
+  fetcher: Fetcher,
+): Promise<{ state: DailyCheckinState; amount: number; error: string | null }> {
+  const campaigns = await getCampaigns(base, headers, fetcher);
+  if (campaigns === null) {
+    return { state: "error", amount: 0, error: "Campaign list unavailable." };
+  }
+  // Claim a `CLAIMABLE` CREDITS-kind campaign. Promo rows (`VIEW_DETAILS`,
+  // no benefit) are not credit grants and must not be claimed — claiming one
+  // spends the account's daily slot for nothing and makes the sweep report a
+  // misleading `claimed` with 0 credits.
+  const claimable = campaigns.filter((c) => {
+    if (String(c["claim_status"] ?? "").toUpperCase() !== "CLAIMABLE") return false;
+    const kind = String(asRecord(c["benefit"])?.["kind"] ?? "").toUpperCase();
+    const action = String(c["action_type"] ?? "").toUpperCase();
+    return kind === "CREDITS" || action === "CLAIM_BENEFIT";
+  });
+  for (const campaign of claimable) {
+    const benefit = asRecord(campaign["benefit"]);
+    const campaignId = String(campaign["campaign_id"] ?? "");
+    if (!campaignId) continue;
+    const claim = await claimWithHeaders(base, campaignId, headers, fetcher);
+    if (claim.state === "claimed") {
+      const amount = asNumber(benefit?.["amount"]) ?? claim.amount;
+      return { state: "claimed", amount, error: null };
+    }
+    if (claim.state === "already_claimed") return { state: "already_claimed", amount: 0, error: null };
+    if (claim.state === "not_eligible") return { state: "not_eligible", amount: 0, error: null };
+    return { state: "error", amount: 0, error: "Campaign claim failed." };
+  }
+  // Nothing claimable. Only a CREDITS-kind campaign that is `CLAIMED` proves
+  // today's credit was already taken; a claimed promo (`VIEW_DETAILS`, no
+  // benefit) says nothing about the daily grant, so it must not be reported
+  // as already_claimed. When the CREDITS campaign is absent entirely, the
+  // daily grant is simply not present (or hidden) for this account.
+  const anyCreditsClaimed = campaigns.some((c) => {
+    if (String(c["claim_status"] ?? "").toUpperCase() !== "CLAIMED") return false;
+    const kind = String(asRecord(c["benefit"])?.["kind"] ?? "").toUpperCase();
+    const action = String(c["action_type"] ?? "").toUpperCase();
+    return kind === "CREDITS" || action === "CLAIM_BENEFIT";
+  });
+  if (anyCreditsClaimed) return { state: "already_claimed", amount: 0, error: null };
+  return { state: "unavailable", amount: 0, error: "No daily CREDITS campaign claimable." };
+}
+
+/**
+ * Probes the daily CREDITS grant under a native device identity.
+ *
+ * The server binds the grant to the device identity and hides it once a
+ * device claimed today, so an account claims under its own persisted device
+ * (minted seed). A bound identity that resolves to `claimed`/`already_claimed`
+ * is terminal; one that resolves to `unavailable`/`not_eligible` is honest
+ * (the device is spent for the day or the person is blocked) and is also
+ * terminal — the account must not move to a different device, because that is
+ * how devices are re-spun. Only an *error* (stored identity stopped working)
+ * falls back to a freshly minted identity.
+ *
+ * Returns `{ result, identity }` where `identity` is the device that produced
+ * a terminal `claimed`/`already_claimed` outcome (or `null`).
+ */
+async function probeDailyClaim(
+  base: string,
+  credential: string,
+  fetcher: Fetcher,
+  options: {
+    readonly bound?: QoderNativeIdentity | null;
+    readonly alt?: QoderNativeIdentity | null;
+  } = {},
+): Promise<{ result: { state: DailyCheckinState; amount: number; error: string | null }; identity: QoderNativeIdentity | null }> {
+  const basic = await tryClaimDaily(base, campaignHeaders(credential), fetcher);
+  if (basic.state === "claimed" || basic.state === "already_claimed") {
+    // `tryClaimDaily` only claims CREDITS-kind campaigns, so a `claimed` or
+    // `already_claimed` basic result is already about the daily credit grant —
+    // terminal, no identity probe needed.
+    return { result: basic, identity: null };
+  }
+  if (basic.state === "unavailable") {
+    const identities = [options.bound, options.alt].filter((i): i is QoderNativeIdentity => i !== null && i !== undefined);
+    for (const identity of identities) {
+      const headers = { ...campaignHeaders(credential), ...qoderMachineHeaders(identity) };
+      const result = await tryClaimDaily(base, headers, fetcher);
+      if (result.state === "claimed" || result.state === "already_claimed") {
+        return { result, identity };
+      }
+      // Only an error falls through to the next identity (e.g. the bound one
+      // stopped working). Any honest outcome (unavailable/not_eligible) is
+      // terminal.
+      if (result.state !== "error") return { result, identity };
+    }
+  }
+  return { result: basic, identity: null };
+}
+
 /**
  * Claims one campaign and returns the resulting state. Mirrors the donor's
  * `claim_campaign` idempotence handling: a 409 or `ALREADY_CLAIMED` body is
@@ -113,10 +268,10 @@ async function fetchCampaigns(
  * same-person block (not a failure of this account's day), and anything else
  * is an error.
  */
-async function claimCampaign(
+async function claimWithHeaders(
   base: string,
   campaignId: string,
-  credential: string,
+  headers: Record<string, string>,
   fetcher: Fetcher,
 ): Promise<{ state: DailyCheckinState; amount: number }> {
   const url = base + CAMPAIGN_CLAIM_PATH.replace("%s", encodeURIComponent(campaignId));
@@ -124,11 +279,7 @@ async function claimCampaign(
   try {
     response = await fetcher(url, {
       method: "POST",
-      headers: {
-        Authorization: `Bearer ${credential}`,
-        "Content-Type": "application/json",
-        Accept: "application/json",
-      },
+      headers: { ...headers, "Content-Type": "application/json" },
       body: "{}",
       signal: AbortSignal.timeout(TIMEOUT_MS),
     });
@@ -233,6 +384,16 @@ export async function fetchQoderDailyCheckin(args: {
   readonly credential: string;
   readonly fetcher: Fetcher;
   readonly now?: () => Date;
+  /**
+   * The account's persisted native device identity. When absent and
+   * `nativeIdentityStore` is provided, the first check-in mints one and
+   * persists it (see `allocateQoderNativeIdentity`). When the store is absent
+   * too (tests), `identities` supplies the identities to probe.
+   */
+  readonly nativeIdentity?: NativeIdentityRecord | null;
+  readonly nativeIdentityStore?: QoderNativeIdentityStore;
+  /** Test-only: override the identity list (defaults to bridge-minted). */
+  readonly identities?: readonly QoderNativeIdentity[];
 }): Promise<DailyCheckinResult> {
   const { providerId, accountId, credential, fetcher } = args;
   const baseResult = baseOutcome(providerId, accountId);
@@ -258,46 +419,76 @@ export async function fetchQoderDailyCheckin(args: {
     };
   }
 
-  // Legacy surface absent: campaign fallback.
-  const campaigns = await fetchCampaigns(base, credential, fetcher);
-  if (campaigns === null) {
-    return { ...baseResult, state: "error", error: "Check-in surface unavailable (legacy 404 and campaign list failed)." };
+  // Legacy surface absent: campaign fallback. Prefer the account's persisted
+  // device (loaded from the store); on first check-in with no stored device,
+  // mint one before probing so the account claims under the same identity
+  // every day.
+  const store = args.nativeIdentityStore;
+  let bound: QoderNativeIdentity | null = null;
+  let boundRecord: NativeIdentityRecord | null = args.nativeIdentity ?? null;
+  if (store) {
+    boundRecord = (await store.get(providerId, accountId)) ?? boundRecord;
   }
-  let alreadySeen = false;
-  for (const campaign of campaigns) {
-    const rec = asRecord(campaign);
-    if (!rec) continue;
-    const benefit = asRecord(rec["benefit"]);
-    const kind = String(benefit?.["kind"] ?? "").toUpperCase();
-    if (kind !== "CREDITS" && kind !== "") continue;
-    const actionType = String(rec["action_type"] ?? "");
-    if (actionType !== "" && actionType !== "CLAIM_BENEFIT") continue;
-    const claimStatus = String(rec["claim_status"] ?? "").toUpperCase();
-    if (claimStatus === "CLAIMED") {
-      alreadySeen = true;
-      continue;
-    }
-    if (claimStatus !== "CLAIMABLE") continue;
-    const campaignId = String(rec["campaign_id"] ?? "");
-    if (!campaignId) continue;
-    const result = await claimCampaign(base, campaignId, credential, fetcher);
-    if (result.state === "claimed") {
-      const amount = asNumber(benefit?.["amount"]) ?? result.amount;
-      return { ...baseResult, state: "claimed", credit: amount, streakDays: null };
+  if (boundRecord) {
+    // Ensure the stored device is active on this host (replay its seed).
+    const active = store ? await ensureQoderNativeIdentity(store, providerId, accountId) : true;
+    if (active) {
+      bound = {
+        machineToken: boundRecord.machineToken,
+        machineType: boundRecord.machineType,
+        machineCode: boundRecord.machineCode,
+        isVm: false,
+        source: "runtime-info",
+      };
     }
-    if (result.state === "already_claimed") {
-      alreadySeen = true;
-      continue;
+  }
+  if (!bound && store) {
+    const minted = await allocateQoderNativeIdentity(store, providerId, accountId);
+    if (minted) {
+      boundRecord = minted;
+      bound = {
+        machineToken: minted.machineToken,
+        machineType: minted.machineType,
+        machineCode: minted.machineCode,
+        isVm: false,
+        source: "runtime-info",
+      };
     }
-    if (result.state === "error") {
-      return { ...baseResult, state: "error", error: "Campaign claim failed." };
+  }
+
+  const alt = args.identities?.[0] ?? null;
+  const probe = await probeDailyClaim(base, credential, fetcher, {
+    bound,
+    alt,
+  });
+  const probed = probe.result;
+
+  // If a non-bound identity won (the bound one errored), persist it as the
+  // account's device — but only when its token is actually free, so the
+  // one-device-per-account invariant holds.
+  if (store && probe.identity !== null && probe.identity.machineToken !== bound?.machineToken) {
+    const occupied = await store.occupied(accountId);
+    if (!occupied.has(probe.identity.machineToken)) {
+      try {
+        await store.bind(providerId, accountId, {
+          machineToken: probe.identity.machineToken,
+          machineType: probe.identity.machineType,
+          machineCode: probe.identity.machineCode,
+        });
+      } catch (error) {
+        log.warn(`[qoder] could not bind native identity for account=${accountId}`, error as Error);
+      }
     }
-    // not_eligible (same-person block): stop trying further campaigns.
+  }
+
+  if (probed.state === "claimed") {
+    return { ...baseResult, state: "claimed", credit: probed.amount, streakDays: null };
+  }
+  if (probed.state === "already_claimed") {
+    return { ...baseResult, state: "already_claimed", streakDays: null };
+  }
+  if (probed.state === "not_eligible") {
     return { ...baseResult, state: "not_eligible", error: "Same-person claim already used today." };
   }
-  return {
-    ...baseResult,
-    state: alreadySeen ? "already_claimed" : "unavailable",
-    error: alreadySeen ? null : "No daily CREDITS campaign claimable.",
-  };
+  return { ...baseResult, state: probed.state, error: probed.error };
 }

package/src/providers/integrations/qoder/qoder-native-identity-store.ts

@@ -0,0 +1,157 @@
+/**
+ * Persistence for the Qoder native machine identity (UMID) bound to an
+ * account.
+ *
+ * Same-account probes found that daily 100-credit grant visibility does not
+ * depend on machine headers. This store preserves native identities and seeds
+ * for deterministic replay and other surfaces that may use device identity.
+ * A native identity is a deterministic function of a seed file
+ * (`~/.config/.locale_cfg`). The bound record lives in
+ * `provider_accounts.native_identity` (plain JSON, not a secret).
+ *
+ * Uniqueness of the device is enforced by the partial unique index on the
+ * extracted `machineToken`; this store keeps the JS side of that internal
+ * identity-allocation invariant and surfaces the DB constraint as the backstop.
+ */
+import { and, eq, isNotNull, ne } from "drizzle-orm";
+import type { CartethyiaDatabase } from "../../../persistence/db-handle";
+import { providerAccounts, type NativeIdentityRecord } from "../../../persistence/schema";
+import {
+  mintQoderNativeIdentity,
+  replayQoderNativeIdentity,
+  type QoderNativeIdentity,
+} from "./qoder-umid";
+
+/** Stateful read/write boundary for bound native identities. */
+export interface QoderNativeIdentityStore {
+  /**
+   * The identity bound to one account, or `undefined` when the account has
+   * no identity yet.
+   */
+  get(providerId: string, accountId: string): Promise<NativeIdentityRecord | undefined>;
+  /**
+   * Machine tokens already bound to **other** accounts, so a caller can mint
+   * a fresh identity without colliding. A bound token represents a device identity, and
+   * the unique index that backs this spans all `provider_accounts` rows. The
+   * account's own bound token is not "occupied" — reusing one's own device is
+   * the point.
+   */
+  occupied(accountId: string): Promise<ReadonlySet<string>>;
+  /** Binds an identity to an account (upsert). Throws on a device collision. */
+  bind(providerId: string, accountId: string, record: NativeIdentityRecord): Promise<void>;
+}
+
+export class DrizzleQoderNativeIdentityStore implements QoderNativeIdentityStore {
+  constructor(private readonly db: CartethyiaDatabase) {}
+
+  async get(providerId: string, accountId: string): Promise<NativeIdentityRecord | undefined> {
+    const rows = await this.db
+      .select({ nativeIdentity: providerAccounts.nativeIdentity })
+      .from(providerAccounts)
+      .where(and(eq(providerAccounts.id, accountId), eq(providerAccounts.providerId, providerId)))
+      .limit(1);
+    const row = rows[0];
+    return row?.nativeIdentity ?? undefined;
+  }
+
+  async occupied(accountId: string): Promise<ReadonlySet<string>> {
+    const rows = await this.db
+      .select({ nativeIdentity: providerAccounts.nativeIdentity })
+      .from(providerAccounts)
+      .where(
+        accountId
+          ? and(isNotNull(providerAccounts.nativeIdentity), ne(providerAccounts.id, accountId))
+          : isNotNull(providerAccounts.nativeIdentity),
+      );
+    const occupied = new Set<string>();
+    for (const row of rows) {
+      const token = row.nativeIdentity?.machineToken;
+      if (token !== undefined && token !== "") occupied.add(token);
+    }
+    return occupied;
+  }
+
+  async bind(providerId: string, accountId: string, record: NativeIdentityRecord): Promise<void> {
+    await this.db
+      .update(providerAccounts)
+      .set({ nativeIdentity: record })
+      .where(and(eq(providerAccounts.id, accountId), eq(providerAccounts.providerId, providerId)));
+  }
+}
+
+/**
+ * Serializes identity minting across accounts in this process, so two
+ * concurrent allocations cannot interleave seed swaps.
+ */
+let allocationQueue: Promise<unknown> = Promise.resolve();
+function withAllocationLock<T>(work: () => Promise<T>): Promise<T> {
+  const next = allocationQueue.then(work, work);
+  allocationQueue = next.catch(() => undefined);
+  return next;
+}
+
+/** Identity minting injected for tests; defaults to the real bridge. */
+export type NativeIdentityMinter = (accountId: string) => { identity: QoderNativeIdentity; seed: string } | null;
+export type NativeIdentityReplayer = (seed: string, accountId: string) => QoderNativeIdentity | null;
+
+const defaultMinter: NativeIdentityMinter = (accountId) => mintQoderNativeIdentity(accountId);
+const defaultReplayer: NativeIdentityReplayer = (seed, accountId) => replayQoderNativeIdentity(seed, accountId);
+
+/**
+ * Mints and binds a fresh device identity for an account: runs the bridge
+ * with a cleared seed, captures the new seed, and persists both. Returns the
+ * bound record, or `null` when the bridge fails.
+ *
+ * `avoidToken` optionally excludes the account's own current token so a
+ * regenerate moves to a *different* device.
+ */
+export function allocateQoderNativeIdentity(
+  store: QoderNativeIdentityStore,
+  providerId: string,
+  accountId: string,
+  options: {
+    readonly avoidToken?: string;
+    readonly mint?: NativeIdentityMinter;
+    readonly replayer?: NativeIdentityReplayer;
+  } = {},
+): Promise<NativeIdentityRecord | null> {
+  const mint = options.mint ?? defaultMinter;
+  return withAllocationLock(async () => {
+    const occupied = await store.occupied(accountId);
+    for (let i = 0; i < 6; i += 1) {
+      const minted = mint(accountId);
+      if (!minted) return null;
+      const token = minted.identity.machineToken;
+      if (occupied.has(token)) continue; // collision (rare) → mint again
+      if (token === options.avoidToken) continue;
+      const record: NativeIdentityRecord = {
+        machineToken: token,
+        machineType: minted.identity.machineType,
+        machineCode: minted.identity.machineCode,
+        ...(minted.seed ? { seed: minted.seed } : {}),
+        source: minted.identity.source,
+      };
+      await store.bind(providerId, accountId, record);
+      return record;
+    }
+    return null;
+  });
+}
+
+/**
+ * Ensures the bound identity is currently active on this host: replays the
+ * stored seed so the bridge yields the same token. Returns `false` when the
+ * account has no bound identity or replay failed.
+ */
+export async function ensureQoderNativeIdentity(
+  store: QoderNativeIdentityStore,
+  providerId: string,
+  accountId: string,
+  replayer: NativeIdentityReplayer = defaultReplayer,
+): Promise<boolean> {
+  const record = await store.get(providerId, accountId);
+  if (!record) return false;
+  if (!record.seed) return true; // no seed captured → assume already active
+  const identity = replayer(record.seed, accountId);
+  return identity !== null && identity.machineToken === record.machineToken;
+}