@opendatalabs/vana-sdk 3.18.1 → 3.19.0

package/dist/index.node.d.ts

@@ -51,6 +51,7 @@ export { ScopeSchema, parseScope, scopeToPathSegments, scopeMatchesPattern, scop
 export { SCOPE_ACTIONS, InvalidScopeEntryError, parseScopeEntry, formatScopeEntry, grantPermissions, permissionsToScopes, tryGrantPermissions, hasAction, type ScopeAction, type ParsedScopeEntry, type GrantPermission, } from "./protocol/scope-actions.js";
 export { WRITE_SESSION_PATH, WRITE_SIGNATURE_HEADER, WRITE_METADATA_HEADER, WRITE_FILENAME_HEADER, WRITE_CONTENT_DISPOSITION_HEADER, WRITER_ATTRIBUTION_KEY, LINEAGE_KEY, LINEAGE_FIELD, MAX_LINEAGE_SOURCES, RESERVED_WRITE_KEYS, openWriteSession, writeData, writePersonalServerData, sessionCoversScope, binaryWriteSignedBytes, normalizeBinaryMimeType, parseWriteMetadataHeader, encodeWriteMetadataHeader, type WriteTransportRetryOptions, type WriteSession, type OpenWriteSessionParams, type WriteBinaryPayload, type LineageSource, type WriteJsonDataParams, type WriteBinaryDataParams, type WriteDataParams, type WriteDataResult, type WritePersonalServerDataParams, type WritePersonalServerDataResult, type BinaryWriteSignedBytesInput, } from "./protocol/personal-server-write.js";
 export { resolveWriteSigner, type WriteSigner, type WriteSignerSource, type ViemWriteAccount, type ViemWriteWalletClient, type ResolveWriteSignerOptions, } from "./protocol/write-signer.js";
+export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
 export { deriveDataPointId, isDataPointId, scopeNamespace, derivedScopeViolatesNaming, assertDerivedScopeNaming, isRedactedLineageNode, personalServerLineagePath, gatewayLineagePath, getLineage, getPersonalServerLineage, getGatewayLineage, LineageNodeSchema, RedactedLineageNodeSchema, LineageEntrySchema, LineageGraphSchema, type LineageNode, type RedactedLineageNode, type LineageEntry, type LineageGraph, type LineageReadResult, type PersonalServerLineageParams, type GatewayLineageParams, type GetLineageParams, } from "./protocol/lineage.js";
 export { DataFileEnvelopeSchema, createDataFileEnvelope, IngestResponseSchema, type DataFileEnvelope, type IngestResponse, } from "./protocol/data-file.js";
 export { createGatewayClient, type GatewayEnvelope, type GatewayProof, type Builder, type Schema, type ServerInfo, type OwnerServerRecord, type OwnerServersResult, type GatewayGrantFee, type GatewayGrantStatus, type GatewayGrantResponse, type GrantListItem, type DataPointRecord, type DataPointListResult, type ListDataPointsOptions, type RegisterServerParams, type RegisterServerResult, type RegisterBuilderParams, type RegisterBuilderResult, type RegisterDataPointParams, type RegisterDataPointResult, type GetDataPointOptions, type DeleteDataPointParams, type DeleteDataPointResult, type CreateGrantParams, type RevokeGrantParams, type AccessRecord, type PayForOperationParams, type PayForOperationResult, type SettleOpType, type SettleItem, type SettlePromoteResult, type SettleReconcileItem, type SettleParams, type SettleResult, type GatewayClient, } from "./protocol/gateway.js";

package/dist/index.node.js

@@ -1358,6 +1358,46 @@ var LineageReadError = class extends VanaError {
   errorCode;
   details;
 };
+var DerivativeQuestionRejectedError = class extends PersonalServerWriteError {
+  constructor(message, status, errorCode = null, details) {
+    super(message, "DERIVATIVE_QUESTION_REJECTED", status, errorCode, details);
+  }
+};
+var DerivativeQuestionInvalidError = class extends PersonalServerWriteError {
+  constructor(message, status = 400, errorCode = null, details) {
+    super(message, "DERIVATIVE_QUESTION_INVALID", status, errorCode, details);
+  }
+};
+var DerivativeQuestionNotFoundError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "DERIVATIVE_QUESTION_NOT_FOUND", 404, errorCode, details);
+  }
+};
+var DerivativeSourceNotGrantedError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "DERIVATIVE_SOURCE_NOT_GRANTED", 403, errorCode, details);
+  }
+};
+var DerivativeCycleError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "DERIVATIVE_CYCLE", 409, errorCode, details);
+  }
+};
+var DerivativeComputeUnavailableError = class extends PersonalServerWriteError {
+  constructor(message, errorCode = null, details) {
+    super(message, "DERIVATIVE_COMPUTE_UNAVAILABLE", 503, errorCode, details);
+  }
+};
+var DerivativeQuestionTimeoutError = class extends PersonalServerWriteError {
+  constructor(message, details) {
+    super(message, "DERIVATIVE_QUESTION_TIMEOUT", void 0, null, details);
+  }
+};
+var DerivativeQuestionFailedError = class extends PersonalServerWriteError {
+  constructor(message, details) {
+    super(message, "DERIVATIVE_QUESTION_FAILED", void 0, null, details);
+  }
+};
 var DataPointDeletedError = class extends VanaError {
   constructor(message, details = {}) {
     super(message, "DATA_POINT_DELETED");
@@ -34391,32 +34431,13 @@ function tryGrantPermissions(scopes) {
 }
 
 // src/protocol/personal-server-write.ts
-import { sha256 as sha2565 } from "@noble/hashes/sha2";
-import { bytesToHex as bytesToHex2, isAddress as isAddress6 } from "viem";
+import { sha256 as sha2566 } from "@noble/hashes/sha2";
+import { bytesToHex as bytesToHex3, isAddress as isAddress6 } from "viem";
 import { z as z4 } from "zod";
-var WRITE_SESSION_PATH = "/v1/write/session";
-var WRITE_SIGNATURE_HEADER = "X-Vana-Write-Signature";
-var WRITE_METADATA_HEADER = "X-Vana-Metadata";
-var LINEAGE_FIELD = "lineage";
-var MAX_LINEAGE_SOURCES = 256;
-var WRITE_FILENAME_HEADER = "X-Filename";
-var WRITE_CONTENT_DISPOSITION_HEADER = "Content-Disposition";
-var WRITER_ATTRIBUTION_KEY = "$writtenBy";
-var LINEAGE_KEY = "$lineage";
-var RESERVED_WRITE_KEYS = [
-  WRITER_ATTRIBUTION_KEY,
-  LINEAGE_KEY
-];
-var WriteDataResultSchema = IngestResponseSchema.extend({
-  // Present when the write carried lineage: the validated, lowercased ids.
-  lineage: z4.object({ sources: z4.array(z4.string()) }).optional()
-});
-var WriteSessionResponseSchema = z4.object({
-  access_token: z4.string().min(1),
-  token_type: z4.string(),
-  expires_in: z4.number().nonnegative(),
-  scope: z4.string()
-});
+
+// src/protocol/write-request.ts
+import { sha256 as sha2565 } from "@noble/hashes/sha2";
+import { bytesToHex as bytesToHex2 } from "viem";
 function normalizeBaseUrl2(url) {
   return url.replace(/\/+$/, "");
 }
@@ -34427,9 +34448,6 @@ function resolveFetch2(fetchFn) {
   }
   return resolved;
 }
-function dataPath(scope) {
-  return `/v1/data/${encodeURIComponent(scope)}`;
-}
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -34517,6 +34535,34 @@ async function sendWithFreshProof(label, fetchFn, options, proofKey, build) {
     lastError
   );
 }
+
+// src/protocol/personal-server-write.ts
+var WRITE_SESSION_PATH = "/v1/write/session";
+var WRITE_SIGNATURE_HEADER = "X-Vana-Write-Signature";
+var WRITE_METADATA_HEADER = "X-Vana-Metadata";
+var LINEAGE_FIELD = "lineage";
+var MAX_LINEAGE_SOURCES = 256;
+var WRITE_FILENAME_HEADER = "X-Filename";
+var WRITE_CONTENT_DISPOSITION_HEADER = "Content-Disposition";
+var WRITER_ATTRIBUTION_KEY = "$writtenBy";
+var LINEAGE_KEY = "$lineage";
+var RESERVED_WRITE_KEYS = [
+  WRITER_ATTRIBUTION_KEY,
+  LINEAGE_KEY
+];
+var WriteDataResultSchema = IngestResponseSchema.extend({
+  // Present when the write carried lineage: the validated, lowercased ids.
+  lineage: z4.object({ sources: z4.array(z4.string()) }).optional()
+});
+var WriteSessionResponseSchema = z4.object({
+  access_token: z4.string().min(1),
+  token_type: z4.string(),
+  expires_in: z4.number().nonnegative(),
+  scope: z4.string()
+});
+function dataPath(scope) {
+  return `/v1/data/${encodeURIComponent(scope)}`;
+}
 async function openWriteSession(params) {
   const fetchFn = resolveFetch2(params.fetch);
   const personalServerUrl = normalizeBaseUrl2(params.personalServerUrl);
@@ -34648,7 +34694,7 @@ function binaryWriteSignedBytes(input) {
     mimeType: normalizeBinaryMimeType(input.contentType),
     ...input.filename ? { filename: input.filename } : {},
     sizeBytes: input.bytes.length,
-    contentHash: bytesToHex2(sha2565(input.bytes)),
+    contentHash: bytesToHex3(sha2566(input.bytes)),
     encoding: "base64",
     content: toBase64(input.bytes),
     ...metadata !== void 0 ? { metadata } : {}
@@ -34945,6 +34991,437 @@ async function writePersonalServerData(params) {
   return { ...result, session };
 }
 
+// src/protocol/derivative-questions.ts
+import { z as z5 } from "zod";
+var DERIVATIVE_QUESTIONS_PATH = "/v1/derivatives/questions";
+var MAX_QUESTION_SOURCE_SCOPES = 16;
+var MAX_QUESTION_CHARS = 8e3;
+var MAX_QUESTION_MODEL_CHARS = 128;
+var MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/-]*$/;
+var DEFAULT_QUESTION_TIMEOUT_MS = 12e4;
+var DEFAULT_QUESTION_POLL_INTERVAL_MS = 2e3;
+var SESSION_REFRESH_SKEW_MS = 3e4;
+var QUESTION_STATUSES = [
+  "pending",
+  "ready",
+  "failed",
+  "stale"
+];
+var QuestionStatusSchema = z5.enum(QUESTION_STATUSES);
+var QuestionRegisteredBySchema = z5.union([
+  z5.object({ kind: z5.literal("owner") }),
+  z5.object({
+    kind: z5.literal("builder"),
+    builder: z5.string(),
+    grantId: z5.string()
+  })
+]);
+var nullableString = z5.string().nullish().transform((value) => value ?? null);
+var DerivativeQuestionSchema = z5.object({
+  questionId: z5.string().min(1),
+  derivedScope: z5.string().min(1),
+  sourceScopes: z5.array(z5.string()),
+  question: z5.string(),
+  /** The model override, or `null` for the server's default. */
+  model: nullableString,
+  registeredBy: QuestionRegisteredBySchema,
+  status: QuestionStatusSchema,
+  /** A short reason, set only while `status` is `failed`. */
+  error: nullableString,
+  createdAt: z5.string(),
+  updatedAt: nullableString,
+  /** When the last compute finished, or `null` while `pending`. */
+  lastComputedAt: nullableString,
+  /** Local version of the derived record the last compute wrote. */
+  derivedVersion: z5.number().nullish().transform((value) => value ?? null),
+  derivedCollectedAt: nullableString
+});
+var QuestionListSchema = z5.object({
+  questions: z5.array(DerivativeQuestionSchema)
+});
+var QuestionRecomputeResultSchema = z5.object({
+  questionId: z5.string().min(1),
+  derivedScope: z5.string().min(1),
+  /** `pending` when the question was never computed, else `stale`. */
+  status: QuestionStatusSchema
+});
+var QuestionDeleteResultSchema = z5.object({
+  questionId: z5.string().min(1),
+  deleted: z5.literal(true)
+});
+var sessionsBySigner = /* @__PURE__ */ new WeakMap();
+function sessionCacheKey(personalServerUrl, audience, grantId, fetchFn) {
+  return JSON.stringify([personalServerUrl, audience, grantId]) + fetchIdOf(fetchFn);
+}
+var fetchIds = /* @__PURE__ */ new WeakMap();
+var nextFetchId = 0;
+function fetchIdOf(fetchFn) {
+  let id = fetchIds.get(fetchFn);
+  if (id === void 0) {
+    id = ++nextFetchId;
+    fetchIds.set(fetchFn, id);
+  }
+  return `#${id}`;
+}
+function resolveRequest(params) {
+  if (typeof params.personalServerUrl !== "string" || params.personalServerUrl.length === 0) {
+    throw new WriteRequestError("personalServerUrl is required");
+  }
+  if (typeof params.grantId !== "string" || params.grantId.length === 0) {
+    throw new WriteRequestError(
+      "grantId is required; a question call runs under the grant carrying write:<derivedScope>"
+    );
+  }
+  if (params.signer === null || typeof params.signer !== "object") {
+    throw new WriteRequestError(
+      "signer must be a viem LocalAccount, a viem WalletClient, or a { signMessage } object"
+    );
+  }
+  const fetchFn = resolveFetch2(params.fetch);
+  const baseUrl = normalizeBaseUrl2(params.personalServerUrl);
+  const audience = params.audience ?? baseUrl;
+  return {
+    baseUrl,
+    audience,
+    fetchFn,
+    cacheKey: sessionCacheKey(baseUrl, audience, params.grantId, fetchFn),
+    signerKey: params.signer
+  };
+}
+async function resolveSession(params, resolved, force) {
+  let cache = sessionsBySigner.get(resolved.signerKey);
+  if (cache === void 0) {
+    cache = /* @__PURE__ */ new Map();
+    sessionsBySigner.set(resolved.signerKey, cache);
+  }
+  const cached = cache.get(resolved.cacheKey);
+  if (!force && cached !== void 0 && cached.expiresAt > Date.now() + SESSION_REFRESH_SKEW_MS) {
+    return cached;
+  }
+  if (force) cache.delete(resolved.cacheKey);
+  const session = await openWriteSession({
+    personalServerUrl: resolved.baseUrl,
+    signer: params.signer,
+    grantId: params.grantId,
+    account: params.account,
+    audience: resolved.audience,
+    fetch: resolved.fetchFn,
+    headers: params.headers,
+    retry: params.retry
+  });
+  cache.set(resolved.cacheKey, session);
+  return session;
+}
+async function questionErrorFromResponse(response) {
+  const { errorCode, message, details } = await readPersonalServerErrorBody(response);
+  const text = message ?? `Derivative question request failed: ${response.status} ${response.statusText}`;
+  switch (errorCode) {
+    case "DERIVATIVE_SOURCE_NOT_GRANTED":
+      return new DerivativeSourceNotGrantedError(text, errorCode, details);
+    case "DERIVATIVE_CYCLE":
+      return new DerivativeCycleError(text, errorCode, details);
+    case "DERIVATIVE_COMPUTE_UNAVAILABLE":
+      return new DerivativeComputeUnavailableError(text, errorCode, details);
+    case "DERIVATIVE_QUESTION_INVALID":
+    case "LINEAGE_SCOPE_UNDER_SOURCE_PREFIX":
+      return new DerivativeQuestionInvalidError(
+        text,
+        response.status,
+        errorCode,
+        details
+      );
+    case "DERIVATIVE_QUESTION_NOT_FOUND":
+      return new DerivativeQuestionNotFoundError(text, errorCode, details);
+    default:
+      break;
+  }
+  switch (response.status) {
+    case 401:
+      return new WriteUnauthorizedError(text, errorCode, details);
+    case 403:
+      return new WriteForbiddenError(text, errorCode, details);
+    case 404:
+      return new DerivativeQuestionNotFoundError(text, errorCode, details);
+    case 409:
+      return new WriteConflictError(text, errorCode, details);
+    default:
+      return new DerivativeQuestionRejectedError(
+        text,
+        response.status,
+        errorCode,
+        details
+      );
+  }
+}
+async function sendOnce(params, resolved, session, spec, bodyBytes) {
+  return sendWithFreshProof(
+    spec.label,
+    resolved.fetchFn,
+    params.retry,
+    proofKeyFor({
+      aud: session.audience,
+      method: spec.method,
+      uri: spec.path,
+      grantId: session.grantId,
+      signedBytes: bodyBytes
+    }),
+    async (iat) => {
+      const headers = new Headers(params.headers);
+      headers.set("Accept", "application/json");
+      headers.set("Authorization", `Bearer ${session.accessToken}`);
+      if (bodyBytes !== void 0) {
+        headers.set("Content-Type", "application/json");
+      }
+      headers.set(
+        WRITE_SIGNATURE_HEADER,
+        await buildWeb3SignedHeader({
+          signMessage: session.signer.signMessage,
+          aud: session.audience,
+          // The Personal Server verifies the proof against the request's
+          // path only, so the signed `uri` must not carry the query string.
+          uri: spec.path,
+          method: spec.method,
+          body: bodyBytes,
+          grantId: session.grantId,
+          iat
+        })
+      );
+      return {
+        url: `${resolved.baseUrl}${spec.path}${spec.query ?? ""}`,
+        init: {
+          method: spec.method,
+          headers,
+          ...bodyBytes === void 0 ? {} : { body: bodyBytes },
+          ...params.signal ? { signal: params.signal } : {}
+        }
+      };
+    }
+  );
+}
+async function sendQuestionRequest(params, spec, schema) {
+  const resolved = resolveRequest(params);
+  const bodyBytes = spec.body === void 0 ? void 0 : new TextEncoder().encode(JSON.stringify(spec.body));
+  let session = await resolveSession(params, resolved, false);
+  let response = await sendOnce(params, resolved, session, spec, bodyBytes);
+  if (response.status === 401) {
+    session = await resolveSession(params, resolved, true);
+    response = await sendOnce(params, resolved, session, spec, bodyBytes);
+  }
+  if (!response.ok) {
+    throw await questionErrorFromResponse(response);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new DerivativeQuestionRejectedError(
+      `${spec.label} response is not JSON`,
+      response.status,
+      null,
+      { cause: errorMessage(err) }
+    );
+  }
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    throw new DerivativeQuestionRejectedError(
+      `${spec.label} response is not a derivative question answer`,
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+function assertQuestionId(questionId) {
+  if (typeof questionId !== "string" || questionId.length === 0) {
+    throw new WriteRequestError("questionId is required");
+  }
+  return `${DERIVATIVE_QUESTIONS_PATH}/${encodeURIComponent(questionId)}`;
+}
+function registrationBody(params) {
+  const { derivedScope, question } = params;
+  if (typeof derivedScope !== "string" || derivedScope.length === 0) {
+    throw new WriteRequestError("derivedScope is required");
+  }
+  if (!Array.isArray(params.sourceScopes) || params.sourceScopes.length === 0) {
+    throw new WriteRequestError(
+      "sourceScopes must be a non-empty array of scopes"
+    );
+  }
+  if (params.sourceScopes.length > MAX_QUESTION_SOURCE_SCOPES) {
+    throw new WriteRequestError(
+      `sourceScopes lists ${params.sourceScopes.length} scopes; the maximum is ${MAX_QUESTION_SOURCE_SCOPES}`,
+      { max: MAX_QUESTION_SOURCE_SCOPES, count: params.sourceScopes.length }
+    );
+  }
+  const sourceScopes = [];
+  for (const scope of params.sourceScopes) {
+    if (typeof scope !== "string" || scope.length === 0) {
+      throw new WriteRequestError("sourceScopes entries must be scope strings");
+    }
+    if (sourceScopes.includes(scope)) {
+      throw new WriteRequestError("sourceScopes must not repeat a scope", {
+        duplicate: scope
+      });
+    }
+    if (scope === derivedScope) {
+      throw new WriteRequestError(
+        "derivedScope cannot be one of its own sources",
+        { scope }
+      );
+    }
+    sourceScopes.push(scope);
+  }
+  if (typeof question !== "string" || question.trim() === "") {
+    throw new WriteRequestError("question must be a non-empty string");
+  }
+  if (question.length > MAX_QUESTION_CHARS) {
+    throw new WriteRequestError(
+      `question is ${question.length} characters; the maximum is ${MAX_QUESTION_CHARS}`,
+      { max: MAX_QUESTION_CHARS, length: question.length }
+    );
+  }
+  if (params.model !== void 0) {
+    if (typeof params.model !== "string" || params.model.length > MAX_QUESTION_MODEL_CHARS || !MODEL_ID_PATTERN.test(params.model)) {
+      throw new WriteRequestError("model must be a provider model id", {
+        model: params.model
+      });
+    }
+  }
+  assertDerivedScopeNaming(derivedScope, sourceScopes);
+  return {
+    derivedScope,
+    sourceScopes,
+    question,
+    ...params.model === void 0 ? {} : { model: params.model }
+  };
+}
+async function registerQuestion(params) {
+  const body = registrationBody(params);
+  return sendQuestionRequest(
+    params,
+    {
+      method: "POST",
+      path: DERIVATIVE_QUESTIONS_PATH,
+      body,
+      label: "Register derivative question"
+    },
+    DerivativeQuestionSchema
+  );
+}
+async function getQuestion(params) {
+  const path = assertQuestionId(params.questionId);
+  return sendQuestionRequest(
+    params,
+    { method: "GET", path, label: "Read derivative question" },
+    DerivativeQuestionSchema
+  );
+}
+async function listQuestions(params) {
+  if (typeof params.derivedScope !== "string" || params.derivedScope.length === 0) {
+    throw new WriteRequestError(
+      "derivedScope is required; a builder may only list its own questions on a scope it may write"
+    );
+  }
+  const { questions } = await sendQuestionRequest(
+    params,
+    {
+      method: "GET",
+      path: DERIVATIVE_QUESTIONS_PATH,
+      query: `?derivedScope=${encodeURIComponent(params.derivedScope)}`,
+      label: "List derivative questions"
+    },
+    QuestionListSchema
+  );
+  return questions;
+}
+async function recomputeQuestion(params) {
+  const path = `${assertQuestionId(params.questionId)}/recompute`;
+  return sendQuestionRequest(
+    params,
+    { method: "POST", path, label: "Recompute derivative question" },
+    QuestionRecomputeResultSchema
+  );
+}
+async function deleteQuestion(params) {
+  const path = assertQuestionId(params.questionId);
+  return sendQuestionRequest(
+    params,
+    { method: "DELETE", path, label: "Delete derivative question" },
+    QuestionDeleteResultSchema
+  );
+}
+function isSettled(status) {
+  return status === "ready" || status === "failed";
+}
+function abortError(signal) {
+  const reason = signal.reason;
+  if (reason instanceof Error) return reason;
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+async function waitForQuestion(params) {
+  const timeoutMs = Math.max(
+    0,
+    params.timeoutMs ?? DEFAULT_QUESTION_TIMEOUT_MS
+  );
+  const pollIntervalMs = Math.max(
+    0,
+    params.pollIntervalMs ?? DEFAULT_QUESTION_POLL_INTERVAL_MS
+  );
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (params.signal?.aborted) throw abortError(params.signal);
+    const latest = await getQuestion(params);
+    if (isSettled(latest.status)) return latest;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      throw new DerivativeQuestionTimeoutError(
+        `Derivative question ${latest.questionId} was still ${latest.status} after ${timeoutMs}ms`,
+        {
+          questionId: latest.questionId,
+          derivedScope: latest.derivedScope,
+          status: latest.status,
+          timeoutMs
+        }
+      );
+    }
+    await sleep2(Math.min(pollIntervalMs, remaining));
+  }
+}
+async function askPersonalServer(params) {
+  const registered = await registerQuestion(params);
+  const registration = await waitForQuestion({
+    ...params,
+    questionId: registered.questionId
+  });
+  if (registration.status !== "ready") {
+    throw new DerivativeQuestionFailedError(
+      `Derivative question ${registration.questionId} failed: ${registration.error ?? "no reason given"}`,
+      {
+        questionId: registration.questionId,
+        derivedScope: registration.derivedScope,
+        error: registration.error
+      }
+    );
+  }
+  const signer = resolveWriteSigner(params.signer, {
+    account: params.account
+  });
+  const readParams = {
+    personalServerUrl: normalizeBaseUrl2(params.personalServerUrl),
+    scope: params.derivedScope,
+    grantId: params.grantId,
+    signMessage: signer.signMessage,
+    ...params.audience === void 0 ? {} : { audience: params.audience },
+    ...params.headers === void 0 ? {} : { headers: params.headers },
+    ...params.fetch === void 0 ? {} : { fetch: params.fetch }
+  };
+  const record = await readPersonalServerData(readParams);
+  return { registration, record };
+}
+
 // src/protocol/gateway.ts
 function withGrantPermissions(grant) {
   const stripped = { ...grant };
@@ -36025,11 +36502,23 @@ export {
   ContractNotFoundError,
   DATA_ACCESS_OP_TYPE,
   DATA_REGISTRY_STATUS_ABI,
+  DEFAULT_QUESTION_POLL_INTERVAL_MS,
+  DEFAULT_QUESTION_TIMEOUT_MS,
+  DERIVATIVE_QUESTIONS_PATH,
   DataFileEnvelopeSchema,
   DataPointDeletedError,
   DataPointNotFoundError,
   DataPointStatus,
   DataPointVersionConflictError,
+  DerivativeComputeUnavailableError,
+  DerivativeCycleError,
+  DerivativeQuestionFailedError,
+  DerivativeQuestionInvalidError,
+  DerivativeQuestionNotFoundError,
+  DerivativeQuestionRejectedError,
+  DerivativeQuestionSchema,
+  DerivativeQuestionTimeoutError,
+  DerivativeSourceNotGrantedError,
   DropboxStorage,
   ECIESError,
   ESCROW_DEPOSIT_ABI2 as ESCROW_DEPOSIT_ABI,
@@ -36054,6 +36543,9 @@ export {
   LineageReadError,
   MASTER_KEY_MESSAGE,
   MAX_LINEAGE_SOURCES,
+  MAX_QUESTION_CHARS,
+  MAX_QUESTION_MODEL_CHARS,
+  MAX_QUESTION_SOURCE_SCOPES,
   MissingAuthError,
   NATIVE_ASSET_ADDRESS,
   NATIVE_VANA_ASSET,
@@ -36074,6 +36566,11 @@ export {
   PersonalServerError,
   PersonalServerWriteError,
   PinataStorage,
+  QUESTION_STATUSES,
+  QuestionDeleteResultSchema,
+  QuestionRecomputeResultSchema,
+  QuestionRegisteredBySchema,
+  QuestionStatusSchema,
   R2Storage,
   RECORD_DATA_ACCESS_TYPES,
   REGISTRATION_KIND_FOR_OP,
@@ -36112,6 +36609,7 @@ export {
   WriteSessionExpiredError,
   WriteTransportError,
   WriteUnauthorizedError,
+  askPersonalServer,
   assertDerivedScopeNaming,
   assertValidPkceVerifier,
   authorizeEscrowPayment,
@@ -36155,6 +36653,7 @@ export {
   dataRegistryDomain,
   decryptWithPassword,
   deleteDataPoint,
+  deleteQuestion,
   deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
@@ -36184,6 +36683,7 @@ export {
   getOpFee,
   getPersonalServerLineage,
   getPlatformCapabilities,
+  getQuestion,
   getServiceEndpoints,
   grantPermissions,
   grantRegistrationDomain,
@@ -36196,6 +36696,7 @@ export {
   isPlatformSupported,
   isRedactedLineageNode,
   isTombstoneHashes,
+  listQuestions,
   mainnetServices,
   moksha,
   mokshaServices,
@@ -36215,8 +36716,10 @@ export {
   personalServerLineagePath,
   personalServerRegistrationDomain,
   readPersonalServerData,
+  recomputeQuestion,
   recoverServerOwner,
   registerPersonalServerSignature,
+  registerQuestion,
   resolveWriteSigner,
   scopeCoveredByGrant,
   scopeMatchesPattern,
@@ -36236,6 +36739,7 @@ export {
   verifyGrantRegistration,
   verifyPkceChallenge,
   verifyWeb3Signed,
+  waitForQuestion,
   writeData,
   writePersonalServerData
 };