reploid 0.0.0-stage → 0.1.0

package/apps/poolday/pool/peer-pack-data-channel.js

@@ -0,0 +1,217 @@
+/** Bounded framing for a dedicated, reliable, ordered Pack-custody data channel.
+ * Signatures and authorized chunk commitments remain owned by peer-pack-custody.
+ * Counts describe application frames, not SCTP/IP bytes or relay charges.
+ */
+const SCHEMA = 'reploid.pool.pack-custody-channel/v1';
+const HEADER_BYTES = 24;
+const ID = /^[0-9a-f]{32}$/;
+const positive = (value) => Number.isSafeInteger(value) && value > 0;
+const assert = (condition, message) => { if (!condition) throw new Error(`Pack channel: ${message}`); };
+
+export function createPeerPackDataChannel({ channel, limits, serve = null }) {
+  assert(channel?.ordered === true && channel.maxRetransmits == null && channel.maxPacketLifeTime == null,
+    'a reliable ordered dedicated data channel is required');
+  assert(typeof channel.send === 'function' && typeof channel.addEventListener === 'function', 'data channel port required');
+  for (const name of ['maxFrameBytes', 'maxControlBytes', 'maxChunkBytes', 'maxBufferedBytes', 'maxPendingRequests', 'maxTransferBytes', 'timeoutMs']) {
+    assert(positive(limits?.[name]), `explicit ${name} required`);
+  }
+  assert(limits.maxFrameBytes > HEADER_BYTES && limits.maxFrameBytes <= limits.maxBufferedBytes
+    && limits.maxControlBytes <= limits.maxBufferedBytes && limits.maxChunkBytes <= 0xffffffff
+    && limits.timeoutMs <= 2147483647, 'invalid framing limits');
+  const policy = structuredClone(limits);
+  const fragmentBytes = policy.maxFrameBytes - HEADER_BYTES;
+  channel.binaryType = 'arraybuffer';
+  channel.bufferedAmountLowThreshold = 0;
+  const pending = new Map();
+  const inbound = new Map();
+  const lifecycle = new AbortController();
+  const counters = { sentFrameBytes: 0, receivedFrameBytes: 0, sentFrames: 0, receivedFrames: 0,
+    completedRequests: 0, cancelledRequests: 0, interruptedPayloadBytes: 0, discardedFrames: 0 };
+  let closed = false;
+
+  function finish(id, error, response) {
+    const entry = pending.get(id);
+    if (!entry) return;
+    pending.delete(id);
+    clearTimeout(entry.timer);
+    entry.signal?.removeEventListener('abort', entry.abort);
+    if (error) {
+      counters.interruptedPayloadBytes += entry.receivedBytes;
+      entry.reject(error);
+    } else {
+      counters.completedRequests += 1;
+      entry.resolve(response);
+    }
+  }
+
+  function close(reason = 'channel closed') {
+    if (closed) return;
+    closed = true;
+    lifecycle.abort();
+    for (const controller of inbound.values()) controller.abort();
+    inbound.clear();
+    for (const id of pending.keys()) finish(id, new Error(`Pack channel: ${reason}`));
+    channel.removeEventListener('message', onMessage);
+    channel.removeEventListener('close', onClose);
+    channel.removeEventListener('error', onClose);
+    channel.close();
+  }
+
+  async function send(data, signal = lifecycle.signal) {
+    const byteLength = typeof data === 'string' ? new TextEncoder().encode(data).byteLength : data.byteLength;
+    assert(!closed && channel.readyState === 'open' && !signal.aborted, 'channel unavailable');
+    assert(counters.sentFrameBytes + byteLength <= policy.maxTransferBytes, 'outgoing byte budget exhausted');
+    if (channel.bufferedAmount + byteLength > policy.maxBufferedBytes) {
+      await new Promise((resolve, reject) => {
+        const finish = (error) => {
+          clearTimeout(timer);
+          channel.removeEventListener('bufferedamountlow', low);
+          signal.removeEventListener('abort', abort);
+          lifecycle.signal.removeEventListener('abort', abort);
+          error ? reject(error) : resolve();
+        };
+        const low = () => finish();
+        const abort = () => finish(new Error('Pack channel: send cancelled'));
+        const timer = setTimeout(() => finish(new Error('Pack channel: backpressure timeout')), policy.timeoutMs);
+        channel.addEventListener('bufferedamountlow', low, { once: true });
+        signal.addEventListener('abort', abort, { once: true });
+        lifecycle.signal.addEventListener('abort', abort, { once: true });
+        if (closed || signal.aborted) abort();
+        else if (channel.bufferedAmount + byteLength <= policy.maxBufferedBytes) low();
+      });
+    }
+    assert(!closed && !signal.aborted && channel.readyState === 'open', 'channel unavailable');
+    assert(channel.bufferedAmount + byteLength <= policy.maxBufferedBytes, 'send buffer limit exceeded');
+    assert(counters.sentFrameBytes + byteLength <= policy.maxTransferBytes, 'outgoing byte budget exhausted');
+    channel.send(data);
+    counters.sentFrameBytes += byteLength;
+    counters.sentFrames += 1;
+  }
+
+  function control(value, signal) {
+    const text = JSON.stringify({ schema: SCHEMA, ...value });
+    assert(new TextEncoder().encode(text).byteLength <= policy.maxControlBytes, 'control frame too large');
+    return send(text, signal);
+  }
+
+  async function supply(frame) {
+    assert(typeof serve === 'function', 'serving is not enabled');
+    assert(!inbound.has(frame.id) && inbound.size < policy.maxPendingRequests, 'incoming request limit or duplicate');
+    assert(positive(frame.request?.sizeBytes) && frame.request.sizeBytes <= policy.maxChunkBytes, 'incoming chunk limit');
+    const controller = new AbortController();
+    inbound.set(frame.id, controller);
+    const timer = setTimeout(() => controller.abort(), policy.timeoutMs);
+    try {
+      const response = await serve(structuredClone(frame.request), { signal: controller.signal });
+      if (controller.signal.aborted || closed) return;
+      assert(response?.bytes instanceof Uint8Array && response.bytes.length === frame.request.sizeBytes, 'supplier response geometry');
+      await control({ type: 'response', id: frame.id, message: response.message, byteLength: response.bytes.length }, controller.signal);
+      for (let offset = 0; offset < response.bytes.length; offset += fragmentBytes) {
+        const part = response.bytes.subarray(offset, offset + fragmentBytes);
+        const bytes = new Uint8Array(HEADER_BYTES + part.length);
+        for (let index = 0; index < 16; index += 1) bytes[index] = parseInt(frame.id.slice(index * 2, index * 2 + 2), 16);
+        const view = new DataView(bytes.buffer);
+        view.setUint32(16, offset);
+        view.setUint32(20, part.length);
+        bytes.set(part, HEADER_BYTES);
+        await send(bytes.buffer, controller.signal);
+      }
+    } catch (error) {
+      if (!closed && !controller.signal.aborted) {
+        await control({ type: 'error', id: frame.id, error: String(error.message).slice(0, 256) }, controller.signal).catch(() => close('error delivery failed'));
+      }
+    } finally {
+      clearTimeout(timer);
+      inbound.delete(frame.id);
+    }
+  }
+
+  function receiveControl(text) {
+    const frame = JSON.parse(text);
+    assert(frame?.schema === SCHEMA && ID.test(frame.id), 'invalid control frame');
+    if (frame.type === 'request') {
+      supply(frame).catch((error) => close(error.message));
+      return;
+    }
+    if (frame.type === 'cancel') {
+      inbound.get(frame.id)?.abort();
+      return;
+    }
+    const entry = pending.get(frame.id);
+    if (!entry) { counters.discardedFrames += 1; return; }
+    if (frame.type === 'error') {
+      finish(frame.id, new Error(`Pack channel supplier: ${String(frame.error).slice(0, 256)}`));
+      return;
+    }
+    assert(frame.type === 'response' && !entry.bytes && frame.byteLength === entry.maxBytes, 'response binding or geometry');
+    assert(frame.message && typeof frame.message === 'object', 'signed response required');
+    entry.message = frame.message;
+    entry.bytes = new Uint8Array(frame.byteLength);
+  }
+
+  function receiveBinary(buffer) {
+    assert(buffer.byteLength > HEADER_BYTES, 'empty binary frame');
+    const bytes = new Uint8Array(buffer);
+    const id = Array.from(bytes.subarray(0, 16), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    const entry = pending.get(id);
+    if (!entry) { counters.discardedFrames += 1; return; }
+    assert(entry.bytes, 'binary frame before response');
+    const view = new DataView(buffer);
+    const offset = view.getUint32(16);
+    const length = view.getUint32(20);
+    assert(offset % fragmentBytes === 0 && offset < entry.maxBytes
+      && length === Math.min(fragmentBytes, entry.maxBytes - offset) && length === bytes.length - HEADER_BYTES, 'binary frame range');
+    if (entry.offsets.has(offset)) {
+      assert(bytes.subarray(HEADER_BYTES).every((byte, index) => entry.bytes[offset + index] === byte), 'conflicting duplicate fragment');
+      counters.discardedFrames += 1;
+      return;
+    }
+    entry.bytes.set(bytes.subarray(HEADER_BYTES), offset);
+    entry.offsets.add(offset);
+    entry.receivedBytes += length;
+    if (entry.receivedBytes === entry.maxBytes) finish(id, null, { message: entry.message, bytes: entry.bytes });
+  }
+
+  function onMessage(event) {
+    try {
+      const data = event.data;
+      const text = typeof data === 'string';
+      assert(text || data instanceof ArrayBuffer, 'unsupported frame type');
+      const size = text ? new TextEncoder().encode(data).byteLength : data.byteLength;
+      counters.receivedFrameBytes += size;
+      counters.receivedFrames += 1;
+      assert(size <= (text ? policy.maxControlBytes : policy.maxFrameBytes), 'frame limit exceeded');
+      assert(counters.receivedFrameBytes <= policy.maxTransferBytes, 'incoming byte budget exhausted');
+      text ? receiveControl(data) : receiveBinary(data);
+    } catch (error) { close(error.message); }
+  }
+
+  function onClose() { close('transport disconnected'); }
+  channel.addEventListener('message', onMessage);
+  channel.addEventListener('close', onClose);
+  channel.addEventListener('error', onClose);
+
+  return {
+    requestChunk(request, { signal, maxBytes }) {
+      assert(!closed && channel.readyState === 'open', 'channel unavailable');
+      assert(positive(maxBytes) && maxBytes === request?.sizeBytes && maxBytes <= policy.maxChunkBytes, 'requested chunk limit');
+      assert(pending.size < policy.maxPendingRequests && !signal?.aborted, 'request cancelled or pending limit exceeded');
+      const id = crypto.randomUUID().replaceAll('-', '');
+      return new Promise((resolve, reject) => {
+        const abort = () => {
+          counters.cancelledRequests += 1;
+          finish(id, new Error('Pack channel: request cancelled or timed out'));
+          control({ type: 'cancel', id }).catch(() => close('cancellation delivery failed'));
+        };
+        const entry = { resolve, reject, signal, abort, maxBytes, receivedBytes: 0, bytes: null, offsets: new Set(),
+          timer: setTimeout(abort, policy.timeoutMs) };
+        pending.set(id, entry);
+        signal?.addEventListener('abort', abort, { once: true });
+        control({ type: 'request', id, request }).catch((error) => finish(id, error));
+      });
+    },
+    close,
+    getReceipt() { return { schema: SCHEMA, ...counters, pendingRequests: pending.size, inboundRequests: inbound.size,
+      closed, wireBytes: null, relayBytes: null }; },
+  };
+}

package/apps/poolday/providers/work-adapter.js

@@ -0,0 +1,67 @@
+/** Resolve selections through the authorized catalog, never caller-supplied URLs. */
+export function selectWorkAdapters(model, selections = model.adapters || []) {
+  if (!Array.isArray(selections) || selections.length > 1) throw new Error('Select at most one adapter');
+  return selections.map(selection => {
+    const entry = model.availableAdapters?.find(adapter => adapter.identity === selection.identity
+      && adapter.baseModelIdentity === model.identity);
+    if (!entry) throw new Error('Adapter is not authorized for this exact base artifact');
+    return structuredClone(entry);
+  });
+}
+
+/** Acquire catalog-pinned adapter bytes; Doppler owns compatibility and tensor identity. */
+export function createWorkAdapterResolver({ models, acquire, fetchImpl = globalThis.fetch }) {
+  const catalog = structuredClone(models).flatMap(model => model.availableAdapters || []);
+  const cache = new Map();
+  return async (selection, { signal }) => {
+    signal.throwIfAborted();
+    const entry = catalog.find(item => item.identity === selection.identity
+      && item.baseModelIdentity === selection.baseModelIdentity);
+    if (!entry) throw new Error('Selected adapter is not in the authorized catalog');
+    let bytes = cache.get(entry.identity);
+    if (!bytes) {
+      if (acquire) bytes = new Uint8Array(await acquire(entry.artifact, { signal })).slice();
+      else {
+        bytes = await fetchAdapterFile(entry.artifact, { signal, fetchImpl });
+      }
+      signal.throwIfAborted();
+      const digest = [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))]
+        .map(value => value.toString(16).padStart(2, '0')).join('');
+      if (bytes.byteLength !== entry.artifact.sizeBytes || 'sha256:' + digest !== entry.artifact.hash) {
+        throw new Error('Adapter file identity mismatch');
+      }
+      signal.throwIfAborted(); cache.set(entry.identity, bytes.slice());
+    }
+    return { manifest: structuredClone(entry.manifest), options: {
+      weightsLayout: entry.weightsLayout, readOPFS: undefined, writeOPFS: undefined,
+      fetchUrl: async url => {
+        signal.throwIfAborted();
+        if (url !== entry.manifest.weightsPath) throw new Error('Adapter requested an undeclared file');
+        return bytes.slice().buffer;
+      }
+    } };
+  };
+}
+
+/** Bounded origin delivery; the resolver or custody owner verifies the resulting digest. */
+export async function fetchAdapterFile(artifact, { signal, fetchImpl = globalThis.fetch }) {
+  signal.throwIfAborted();
+  if (!Number.isSafeInteger(artifact.sizeBytes) || artifact.sizeBytes <= 0) throw new Error('Invalid adapter file size');
+  const response = await fetchImpl(artifact.url, { signal });
+  if (!response.ok) throw new Error(`Adapter acquisition HTTP ${response.status}`);
+  const chunks = []; let size = 0;
+  const reader = response.body.getReader();
+  try {
+    while (size <= artifact.sizeBytes) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value?.byteLength) throw new Error('Adapter stream made no progress');
+      signal.throwIfAborted(); size += value.byteLength;
+      if (size > artifact.sizeBytes) throw new Error('Adapter exceeds its declared file size');
+      chunks.push(value);
+    }
+  } finally { await reader.cancel(); reader.releaseLock(); }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return bytes;
+}

package/apps/poolday/providers/work-device.js

@@ -0,0 +1,33 @@
+/** Shared device admission. Running work owns its slot until cleanup settles. */
+// One borrowed GPU operation per runtime service, shared by threads and suppliers.
+// Cancellation removes a waiter; a running operation keeps its slot until settlement.
+const queues = new WeakMap();
+export async function withWorkDevice(service, signal, operation, onProgress = () => {}) {
+  signal.throwIfAborted();
+  let queue = queues.get(service);
+  if (!queue) { queue = { busy: false, waiting: [] }; queues.set(service, queue); }
+  await new Promise((resolve, reject) => {
+    const waiter = { enter() {
+      signal.removeEventListener('abort', abort);
+      queue.busy = true; resolve();
+    } };
+    const remove = error => {
+      queue.waiting = queue.waiting.filter(item => item !== waiter);
+      signal.removeEventListener('abort', abort);
+      reject(error);
+    };
+    const abort = () => remove(signal.reason);
+    if (!queue.busy) waiter.enter();
+    else {
+      queue.waiting.push(waiter);
+      signal.addEventListener('abort', abort, { once: true });
+      try { onProgress('Waiting for this device'); }
+      catch (error) { remove(error); }
+    }
+  });
+  try { signal.throwIfAborted(); return await operation(); }
+  finally {
+    queue.busy = false;
+    queue.waiting.shift()?.enter();
+  }
+}

package/apps/poolday/providers/work-generation-completion.js

@@ -0,0 +1,55 @@
+import { GENERATION_CONTRACT } from '../../../shared/config/doppler-generation-contract.js';
+
+/** Consume Doppler's public scoped stream: ordered text, then exactly one completion.
+ * A transport ending is not completion. Cancellation awaits iterator cleanup.
+ */
+export async function consumeWorkGenerationStream(events, { signal, onDelta, maxOutcomeCharacters }) {
+  let text = '', terminal = null;
+  for await (const event of events) {
+    signal.throwIfAborted();
+    if (terminal) throw new Error('Doppler stream emitted an event after completion');
+    if (event?.schema !== 'doppler.generation-event/v1'
+      || !['text-delta', 'complete'].includes(event.type)) throw new Error('Doppler stream emitted an unsupported event');
+    if (event.type === 'text-delta') {
+      if (typeof event.text !== 'string') throw new Error('Doppler stream emitted an invalid text delta');
+      text += event.text;
+      if (text.length > maxOutcomeCharacters) throw new Error('Model response exceeded the configured size limit');
+      await onDelta(event.text);
+      signal.throwIfAborted();
+    } else {
+      if (event.outputText !== text) throw new Error('Doppler completed text differs from its stream');
+      terminal = { content: text, completion: readWorkGenerationCompletion(event) };
+    }
+  }
+  signal.throwIfAborted();
+  if (!terminal) throw new Error('Doppler stream ended without completion');
+  return terminal;
+}
+
+/** Preserve Doppler's declared termination; missing legacy metadata stays unknown. */
+export function readWorkGenerationCompletion(result) {
+  const value = Object.hasOwn(result, 'completion') ? result.completion : result.evidence?.output?.completion;
+  if (value == null) return null;
+  if (value.schema !== GENERATION_CONTRACT.completionSchema
+    || !GENERATION_CONTRACT.stoppingReasons.includes(value.stopReason)
+    || !Number.isSafeInteger(value.promptTokenCount) || value.promptTokenCount < 0
+    || !Number.isSafeInteger(value.generatedTokenCount) || value.generatedTokenCount < 0) {
+    throw new Error('Doppler supplied invalid generation completion metadata');
+  }
+  return { schema: value.schema, stopReason: value.stopReason,
+    promptTokenCount: value.promptTokenCount, generatedTokenCount: value.generatedTokenCount };
+}
+
+/** Copy measurements while the generation still owns the session, before reset. */
+export function readWorkGenerationTiming(stats) {
+  if (!stats || !Number.isFinite(stats.totalTimeMs) || stats.totalTimeMs <= 0
+    || !Number.isSafeInteger(stats.tokensGenerated) || stats.tokensGenerated < 0) return null;
+  const duration = value => Number.isFinite(value) && value >= 0 ? value : null;
+  return { totalMs: stats.totalTimeMs, generatedTokenCount: stats.tokensGenerated,
+    prefillMs: duration(stats.prefillTimeMs), decodeMs: duration(stats.decodeTimeMs),
+    firstTokenMs: duration(stats.ttftMs),
+    ...(Number.isSafeInteger(stats.reusedPrefixTokens) && stats.reusedPrefixTokens >= 0
+      ? { reusedPrefixTokens: stats.reusedPrefixTokens } : {}),
+    ...(Number.isSafeInteger(stats.prefillComputedTokens) && stats.prefillComputedTokens >= 0
+      ? { prefillComputedTokens: stats.prefillComputedTokens } : {}) };
+}

package/apps/poolday/providers/work-provider.js

@@ -0,0 +1,209 @@
+/** Host-selected compatibility providers. Signed Pack providers remain separate. */
+import profile from '../config/work-profile.json' with { type: 'json' };
+import { createGenerationContextCache } from '../../../shared/vendor/reploid/mesh/generation-context-cache.js';
+import { publicProviderHardware } from '../../../shared/vendor/reploid/mesh/provider-hardware.js';
+import { consumeWorkGenerationStream, readWorkGenerationCompletion, readWorkGenerationTiming } from './work-generation-completion.js';
+const requireValue = (condition, message) => { if (!condition) throw new Error(message); };
+
+export function selectWorkModel({ models, modelId, defaultModelId }) {
+  const id = modelId === undefined || modelId === null || modelId === '' ? defaultModelId : modelId;
+  const model = models.find(item => item.id === id);
+  requireValue(model, `Unknown application model: ${String(id)}`);
+  requireValue(['doppler', 'gemini'].includes(model.provider), 'Model requires an explicit supported provider');
+  return Object.freeze({ ...model });
+}
+
+export async function openWorkProvider({ model, service, scope, signal, credentials,
+  fetchImpl = globalThis.fetch, generation, maxOutcomeCharacters, allowedFallbackModels = [], onProgress,
+  resolveAdapter, source = model.id, loadOptions = {} }) {
+  signal.throwIfAborted();
+  generation = { ...generation, ...model.generation };
+  const session = model.provider === 'doppler'
+    ? await service.open({ scope, source, options: { ...model.loadOptions, ...loadOptions, onProgress } }) : null;
+  signal.throwIfAborted();
+  if (session) requireValue(typeof session.stream === 'function', 'Configured Doppler session does not expose text streaming');
+  else requireValue(typeof credentials === 'function', 'Firebase Auth and App Check credentials are required');
+  let healthy = true;
+  const configuredBufferBudget = (loadOptions?.runtimeConfig ?? model.loadOptions?.runtimeConfig)?.shared?.bufferPool?.budget?.maxTotalBytes;
+  const contextCachePolicy = Number.isFinite(configuredBufferBudget) && configuredBufferBudget > 0
+    ? (() => {
+      const maxBytes = Math.min(profile.contextCache.maxBytes, Math.max(67108864, Math.floor(configuredBufferBudget * 0.25)));
+      return { ...profile.contextCache, maxBytes, maxEntryBytes: Math.min(profile.contextCache.maxEntryBytes, maxBytes) };
+    })()
+    : profile.contextCache;
+  const contexts = session?.supports?.('generationContext') === true
+    ? createGenerationContextCache({ policy: contextCachePolicy, create: options => session.createGenerationContext(options) }) : null;
+  const executionIdentity = () => {
+    if (!session) return null;
+    requireValue(healthy, 'Doppler session requires replacement after failed cleanup');
+    requireValue(session.loaded === true && typeof session.modelId === 'string', 'Doppler session is not ready');
+    const hash = String(session.manifestHash || '').replace(/^sha256:/, '');
+    requireValue(/^[a-f0-9]{64}$/.test(hash), 'Doppler session is missing its manifest identity');
+    requireValue(session.modelId === model.id, 'Doppler loaded a different model');
+    requireValue(!model.identity || model.identity === 'sha256:' + hash, 'Doppler loaded a different model artifact');
+    requireValue(!session.activeLoRA, 'Active adapter identity requires Doppler generation evidence');
+    return { model: session.modelId, modelIdentity: 'sha256:' + hash,
+      adapterIdentities: [] };
+  };
+  const evidencedIdentity = (result, adapters) => {
+    const actual = result?.evidence?.runtimeProfile?.model;
+    const hash = String(actual?.manifestHash || '').replace(/^sha256:/, '');
+    requireValue(actual?.modelId === model.id && 'sha256:' + hash === model.identity,
+      'Doppler generation evidence has a different model artifact');
+    const identities = actual.activeAdapterDigest ? [actual.activeAdapterDigest] : [];
+    requireValue(JSON.stringify(identities) === JSON.stringify(adapters.map(item => item.identity)),
+      'Doppler generation evidence has a different adapter artifact');
+    return { model: actual.modelId, modelIdentity: 'sha256:' + hash, adapterIdentities: identities };
+  };
+  if (session) executionIdentity();
+  const reset = async () => {
+    if (!session) return;
+    requireValue(typeof session.resetGenerationState === 'function', 'Doppler session cannot reset conversation state');
+    try { await session.resetGenerationState(); }
+    catch (error) { healthy = false; throw error; }
+  };
+  const setAdapters = async (adapters, attemptSignal = signal) => {
+    requireValue(Array.isArray(adapters) && adapters.length <= 1, 'This Doppler session supports one adapter at a time');
+    const selected = adapters[0];
+    if (selected) {
+      requireValue(selected.baseModelIdentity === model.identity, 'Adapter targets a different base model artifact');
+      requireValue(/^sha256:[a-f0-9]{64}$/.test(selected.identity), 'Exact adapter execution identity required');
+      requireValue(typeof resolveAdapter === 'function', 'Verified adapter acquisition is unavailable');
+    }
+    requireValue(session, 'Adapters require a Doppler session');
+    if (session.activeLoRA) await session.unloadLoRA();
+    requireValue(!session.activeLoRA, 'Doppler did not remove the previous adapter');
+    if (!selected) return;
+    attemptSignal.throwIfAborted();
+    const acquired = await resolveAdapter(structuredClone(selected), { signal: attemptSignal });
+    attemptSignal.throwIfAborted();
+    requireValue(acquired?.manifest?.baseModel === model.id, 'Adapter manifest targets a different model');
+    await session.loadLoRA(acquired.manifest, acquired.options);
+    attemptSignal.throwIfAborted();
+    requireValue(session.activeLoRA, 'Doppler did not apply the adapter');
+  };
+  return Object.freeze({
+    getIdentity: executionIdentity,
+    getHardware: () => publicProviderHardware(session?.deviceInfo),
+    getContextCacheStats: () => contexts?.getStats?.() ?? null,
+    isReady: () => healthy && session?.loaded === true,
+    reset,
+    close: () => contexts?.close(),
+    async prepareAdapters(adapters) {
+      try {
+        await setAdapters(adapters);
+        // The pinned scoped API reports tensor identity in execution evidence, not a session getter.
+        const result = await session.generate(profile.adapterQualification.messages,
+          { ...profile.adapterQualification.generation, signal });
+        signal.throwIfAborted();
+        return evidencedIdentity(result, adapters).adapterIdentities;
+      } finally {
+        try { await setAdapters([]); await reset(); }
+        catch (error) { healthy = false; throw error; }
+      }
+    },
+    async generate(messages, onUpdate = () => {}, { signal: attemptSignal, adapters = [], maxOutputTokens, contextOwner, contextId }) {
+      const combined = AbortSignal.any([signal, attemptSignal]);
+      combined.throwIfAborted();
+      requireValue(maxOutputTokens === undefined || Number.isSafeInteger(maxOutputTokens) && maxOutputTokens > 0,
+        'Request maxOutputTokens must be a positive integer');
+      let requestGeneration = maxOutputTokens === undefined ? generation
+        : { ...generation, maxTokens: Math.min(generation.maxTokens ?? maxOutputTokens, maxOutputTokens) };
+      let text = '', actualModel = model.id, actualIdentity = null, completion = null, timing = null;
+      const update = delta => {
+        combined.throwIfAborted();
+        requireValue(typeof delta === 'string', 'Provider emitted an invalid text delta');
+        text += delta;
+        requireValue(text.length <= maxOutcomeCharacters, 'Model response exceeded the configured size limit');
+        return onUpdate(delta);
+      };
+      if (session) {
+        const advanced = session.supports?.('advanced') === false ? null : session.advanced;
+        if (typeof advanced?.getGenerationGeometry === 'function' && typeof advanced?.tokenizePrompt === 'function') {
+          const maxSeqLen = advanced.getGenerationGeometry()?.maxSeqLen;
+          if (Number.isSafeInteger(maxSeqLen) && maxSeqLen > 0) {
+            const promptTokens = advanced.tokenizePrompt(messages, { useChatTemplate: requestGeneration.useChatTemplate !== false }).length;
+            const requiredOutputTokens = Number.isSafeInteger(requestGeneration.maxTokens) && requestGeneration.maxTokens > 0
+              ? requestGeneration.maxTokens : 1;
+            if (promptTokens + requiredOutputTokens > maxSeqLen) {
+              throw Object.assign(
+                new Error(`Conversation plus output budget exceeds model context limit (${promptTokens} + ${requiredOutputTokens} > ${maxSeqLen} tokens)`),
+                { code: 'CONTEXT_LENGTH_EXCEEDED', recoverableSession: true, status: 400 }
+              );
+            }
+          }
+        }
+        // Raw compatibility sessions cancel cooperatively; the host waits for settlement.
+        await reset();
+        let lease = null, complete = false;
+        try {
+          await setAdapters(adapters, combined);
+          const contextKey = typeof contextOwner === 'string' && contextOwner && typeof contextId === 'string' && contextId
+            ? JSON.stringify([contextOwner, contextId, model.identity, adapters.map(item => item.identity)]) : null;
+          lease = contexts?.acquire(contextKey);
+          const cachedGeneration = lease ? { ...requestGeneration, generationContext: lease.context } : requestGeneration;
+          if (adapters.length) {
+            const result = await session.generate(messages, { ...cachedGeneration, signal: combined,
+              onToken: (_token, delta) => { if (typeof delta === 'string') update(delta); } });
+            // Doppler owns visible output. Older callbacks supply only token IDs;
+            // those sessions deliver completion text without decoding IDs here.
+            requireValue(typeof result.outputText === 'string' && result.outputText.startsWith(text),
+              'Doppler streamed text differs from generation evidence');
+            await update(result.outputText.slice(text.length));
+            actualIdentity = evidencedIdentity(result, adapters);
+            completion = readWorkGenerationCompletion(result);
+            timing = readWorkGenerationTiming(result.evidence?.stats);
+            requireValue(text === result.outputText, 'Doppler streamed text differs from generation evidence');
+          } else {
+            actualIdentity = executionIdentity();
+            const result = await consumeWorkGenerationStream(session.stream(messages, { ...cachedGeneration, signal: combined }),
+              { signal: combined, onDelta: update, maxOutcomeCharacters });
+            completion = result.completion;
+            timing = readWorkGenerationTiming(session.supports?.('advanced') === false
+              ? null : session.advanced?.getStats?.());
+            requireValue(JSON.stringify(executionIdentity()) === JSON.stringify(actualIdentity),
+              'Doppler execution identity changed during generation');
+          }
+          combined.throwIfAborted();
+          complete = true;
+        } finally {
+          try { lease?.release({ discard: !complete }); await reset(); await setAdapters([]); }
+          catch (error) { healthy = false; throw error; }
+        }
+        actualModel = actualIdentity.model;
+      } else {
+        const headers = new Headers(await credentials({ signal: combined }));
+        requireValue(/^Bearer\s+\S+$/i.test(headers.get('Authorization') || '')
+          && !!headers.get('X-Firebase-AppCheck')?.trim(), 'Firebase Auth and App Check credentials are required');
+        headers.set('Content-Type', 'application/json');
+        combined.throwIfAborted();
+        const response = await fetchImpl('/zero/gemini', {
+          method: 'POST', headers,
+          body: JSON.stringify({ model: model.id, provider: model.provider, messages,
+            allowedFallbackModels, maxOutputTokens: requestGeneration.maxTokens }),
+          signal: combined
+        });
+        if (!response.ok) {
+          const data = await response.json().catch(() => ({}));
+          const error = new Error(`Gemini HTTP ${response.status}: ${data.error || response.statusText}`);
+          error.status = response.status;
+          error.retryAfter = response.headers.get('retry-after');
+          throw error;
+        }
+        const data = await response.json();
+        actualModel = data.model || data.effectiveModel;
+        requireValue(typeof actualModel === 'string' && actualModel,
+          'Provider response is missing execution model identity');
+        requireValue(actualModel === model.id || allowedFallbackModels.includes(actualModel),
+          'Provider substituted a model outside the declared fallback policy');
+        requireValue(!data.provider || data.provider === model.provider, 'Provider identity mismatch');
+        await update(data.content);
+      }
+      combined.throwIfAborted();
+      requireValue(text.trim() || completion?.stopReason === 'max-tokens', 'Provider returned no text');
+      return { content: text, raw: text, requestedModel: model.id, model: actualModel,
+        ...(session ? { ...actualIdentity, completion, timing, hardware: publicProviderHardware(session.deviceInfo) } : {}),
+        provider: model.provider, execution: session ? 'local-scoped-session' : 'cloud-proxy-session' };
+    }
+  });
+}