@opendatalabs/vana-sdk 3.18.1 → 3.19.0

package/dist/index.node.cjs

@@ -1186,11 +1186,23 @@ __export(index_node_exports, {
   ContractNotFoundError: () => ContractNotFoundError,
   DATA_ACCESS_OP_TYPE: () => DATA_ACCESS_OP_TYPE,
   DATA_REGISTRY_STATUS_ABI: () => DATA_REGISTRY_STATUS_ABI,
+  DEFAULT_QUESTION_POLL_INTERVAL_MS: () => DEFAULT_QUESTION_POLL_INTERVAL_MS,
+  DEFAULT_QUESTION_TIMEOUT_MS: () => DEFAULT_QUESTION_TIMEOUT_MS,
+  DERIVATIVE_QUESTIONS_PATH: () => DERIVATIVE_QUESTIONS_PATH,
   DataFileEnvelopeSchema: () => DataFileEnvelopeSchema,
   DataPointDeletedError: () => DataPointDeletedError,
   DataPointNotFoundError: () => DataPointNotFoundError,
   DataPointStatus: () => DataPointStatus,
   DataPointVersionConflictError: () => DataPointVersionConflictError,
+  DerivativeComputeUnavailableError: () => DerivativeComputeUnavailableError,
+  DerivativeCycleError: () => DerivativeCycleError,
+  DerivativeQuestionFailedError: () => DerivativeQuestionFailedError,
+  DerivativeQuestionInvalidError: () => DerivativeQuestionInvalidError,
+  DerivativeQuestionNotFoundError: () => DerivativeQuestionNotFoundError,
+  DerivativeQuestionRejectedError: () => DerivativeQuestionRejectedError,
+  DerivativeQuestionSchema: () => DerivativeQuestionSchema,
+  DerivativeQuestionTimeoutError: () => DerivativeQuestionTimeoutError,
+  DerivativeSourceNotGrantedError: () => DerivativeSourceNotGrantedError,
   DropboxStorage: () => DropboxStorage,
   ECIESError: () => ECIESError,
   ESCROW_DEPOSIT_ABI: () => ESCROW_DEPOSIT_ABI2,
@@ -1215,6 +1227,9 @@ __export(index_node_exports, {
   LineageReadError: () => LineageReadError,
   MASTER_KEY_MESSAGE: () => MASTER_KEY_MESSAGE,
   MAX_LINEAGE_SOURCES: () => MAX_LINEAGE_SOURCES,
+  MAX_QUESTION_CHARS: () => MAX_QUESTION_CHARS,
+  MAX_QUESTION_MODEL_CHARS: () => MAX_QUESTION_MODEL_CHARS,
+  MAX_QUESTION_SOURCE_SCOPES: () => MAX_QUESTION_SOURCE_SCOPES,
   MissingAuthError: () => MissingAuthError,
   NATIVE_ASSET_ADDRESS: () => NATIVE_ASSET_ADDRESS,
   NATIVE_VANA_ASSET: () => NATIVE_VANA_ASSET,
@@ -1235,6 +1250,11 @@ __export(index_node_exports, {
   PersonalServerError: () => PersonalServerError,
   PersonalServerWriteError: () => PersonalServerWriteError,
   PinataStorage: () => PinataStorage,
+  QUESTION_STATUSES: () => QUESTION_STATUSES,
+  QuestionDeleteResultSchema: () => QuestionDeleteResultSchema,
+  QuestionRecomputeResultSchema: () => QuestionRecomputeResultSchema,
+  QuestionRegisteredBySchema: () => QuestionRegisteredBySchema,
+  QuestionStatusSchema: () => QuestionStatusSchema,
   R2Storage: () => R2Storage,
   RECORD_DATA_ACCESS_TYPES: () => RECORD_DATA_ACCESS_TYPES,
   REGISTRATION_KIND_FOR_OP: () => REGISTRATION_KIND_FOR_OP,
@@ -1273,6 +1293,7 @@ __export(index_node_exports, {
   WriteSessionExpiredError: () => WriteSessionExpiredError,
   WriteTransportError: () => WriteTransportError,
   WriteUnauthorizedError: () => WriteUnauthorizedError,
+  askPersonalServer: () => askPersonalServer,
   assertDerivedScopeNaming: () => assertDerivedScopeNaming,
   assertValidPkceVerifier: () => assertValidPkceVerifier,
   authorizeEscrowPayment: () => authorizeEscrowPayment,
@@ -1316,6 +1337,7 @@ __export(index_node_exports, {
   dataRegistryDomain: () => dataRegistryDomain,
   decryptWithPassword: () => decryptWithPassword,
   deleteDataPoint: () => deleteDataPoint,
+  deleteQuestion: () => deleteQuestion,
   deriveDataPointId: () => deriveDataPointId,
   deriveMasterKey: () => deriveMasterKey,
   deriveScopeKey: () => deriveScopeKey,
@@ -1345,6 +1367,7 @@ __export(index_node_exports, {
   getOpFee: () => getOpFee,
   getPersonalServerLineage: () => getPersonalServerLineage,
   getPlatformCapabilities: () => getPlatformCapabilities,
+  getQuestion: () => getQuestion,
   getServiceEndpoints: () => getServiceEndpoints,
   grantPermissions: () => grantPermissions,
   grantRegistrationDomain: () => grantRegistrationDomain,
@@ -1357,6 +1380,7 @@ __export(index_node_exports, {
   isPlatformSupported: () => isPlatformSupported,
   isRedactedLineageNode: () => isRedactedLineageNode,
   isTombstoneHashes: () => isTombstoneHashes,
+  listQuestions: () => listQuestions,
   mainnetServices: () => mainnetServices,
   moksha: () => moksha,
   mokshaServices: () => mokshaServices,
@@ -1376,8 +1400,10 @@ __export(index_node_exports, {
   personalServerLineagePath: () => personalServerLineagePath,
   personalServerRegistrationDomain: () => personalServerRegistrationDomain,
   readPersonalServerData: () => readPersonalServerData,
+  recomputeQuestion: () => recomputeQuestion,
   recoverServerOwner: () => recoverServerOwner,
   registerPersonalServerSignature: () => registerPersonalServerSignature,
+  registerQuestion: () => registerQuestion,
   resolveWriteSigner: () => resolveWriteSigner,
   scopeCoveredByGrant: () => scopeCoveredByGrant,
   scopeMatchesPattern: () => scopeMatchesPattern,
@@ -1397,6 +1423,7 @@ __export(index_node_exports, {
   verifyGrantRegistration: () => verifyGrantRegistration,
   verifyPkceChallenge: () => verifyPkceChallenge,
   verifyWeb3Signed: () => verifyWeb3Signed,
+  waitForQuestion: () => waitForQuestion,
   writeData: () => writeData,
   writePersonalServerData: () => writePersonalServerData
 });
@@ -1613,6 +1640,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");
@@ -34621,32 +34688,13 @@ function tryGrantPermissions(scopes) {
 }
 
 // src/protocol/personal-server-write.ts
+var import_sha26 = require("@noble/hashes/sha2");
+var import_viem24 = require("viem");
+var import_zod4 = require("zod");
+
+// src/protocol/write-request.ts
 var import_sha25 = require("@noble/hashes/sha2");
 var import_viem23 = require("viem");
-var import_zod4 = require("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: import_zod4.z.object({ sources: import_zod4.z.array(import_zod4.z.string()) }).optional()
-});
-var WriteSessionResponseSchema = import_zod4.z.object({
-  access_token: import_zod4.z.string().min(1),
-  token_type: import_zod4.z.string(),
-  expires_in: import_zod4.z.number().nonnegative(),
-  scope: import_zod4.z.string()
-});
 function normalizeBaseUrl2(url) {
   return url.replace(/\/+$/, "");
 }
@@ -34657,9 +34705,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);
 }
@@ -34747,6 +34792,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: import_zod4.z.object({ sources: import_zod4.z.array(import_zod4.z.string()) }).optional()
+});
+var WriteSessionResponseSchema = import_zod4.z.object({
+  access_token: import_zod4.z.string().min(1),
+  token_type: import_zod4.z.string(),
+  expires_in: import_zod4.z.number().nonnegative(),
+  scope: import_zod4.z.string()
+});
+function dataPath(scope) {
+  return `/v1/data/${encodeURIComponent(scope)}`;
+}
 async function openWriteSession(params) {
   const fetchFn = resolveFetch2(params.fetch);
   const personalServerUrl = normalizeBaseUrl2(params.personalServerUrl);
@@ -34878,7 +34951,7 @@ function binaryWriteSignedBytes(input) {
     mimeType: normalizeBinaryMimeType(input.contentType),
     ...input.filename ? { filename: input.filename } : {},
     sizeBytes: input.bytes.length,
-    contentHash: (0, import_viem23.bytesToHex)((0, import_sha25.sha256)(input.bytes)),
+    contentHash: (0, import_viem24.bytesToHex)((0, import_sha26.sha256)(input.bytes)),
     encoding: "base64",
     content: toBase64(input.bytes),
     ...metadata !== void 0 ? { metadata } : {}
@@ -34926,7 +34999,7 @@ function normalizeLineage(lineage, derivedScope) {
   for (const entry of lineage) {
     let id;
     if (isLineagePair(entry)) {
-      if (!(0, import_viem23.isAddress)(entry.ownerAddress, { strict: false })) {
+      if (!(0, import_viem24.isAddress)(entry.ownerAddress, { strict: false })) {
         throw new WriteRequestError(
           "lineage source ownerAddress must be an EVM address",
           { ownerAddress: entry.ownerAddress }
@@ -35175,6 +35248,437 @@ async function writePersonalServerData(params) {
   return { ...result, session };
 }
 
+// src/protocol/derivative-questions.ts
+var import_zod5 = require("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 = import_zod5.z.enum(QUESTION_STATUSES);
+var QuestionRegisteredBySchema = import_zod5.z.union([
+  import_zod5.z.object({ kind: import_zod5.z.literal("owner") }),
+  import_zod5.z.object({
+    kind: import_zod5.z.literal("builder"),
+    builder: import_zod5.z.string(),
+    grantId: import_zod5.z.string()
+  })
+]);
+var nullableString = import_zod5.z.string().nullish().transform((value) => value ?? null);
+var DerivativeQuestionSchema = import_zod5.z.object({
+  questionId: import_zod5.z.string().min(1),
+  derivedScope: import_zod5.z.string().min(1),
+  sourceScopes: import_zod5.z.array(import_zod5.z.string()),
+  question: import_zod5.z.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: import_zod5.z.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: import_zod5.z.number().nullish().transform((value) => value ?? null),
+  derivedCollectedAt: nullableString
+});
+var QuestionListSchema = import_zod5.z.object({
+  questions: import_zod5.z.array(DerivativeQuestionSchema)
+});
+var QuestionRecomputeResultSchema = import_zod5.z.object({
+  questionId: import_zod5.z.string().min(1),
+  derivedScope: import_zod5.z.string().min(1),
+  /** `pending` when the question was never computed, else `stale`. */
+  status: QuestionStatusSchema
+});
+var QuestionDeleteResultSchema = import_zod5.z.object({
+  questionId: import_zod5.z.string().min(1),
+  deleted: import_zod5.z.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 };
@@ -36256,11 +36760,23 @@ async function parsePSError(response) {
   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_ABI,
@@ -36285,6 +36801,9 @@ async function parsePSError(response) {
   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,
@@ -36305,6 +36824,11 @@ async function parsePSError(response) {
   PersonalServerError,
   PersonalServerWriteError,
   PinataStorage,
+  QUESTION_STATUSES,
+  QuestionDeleteResultSchema,
+  QuestionRecomputeResultSchema,
+  QuestionRegisteredBySchema,
+  QuestionStatusSchema,
   R2Storage,
   RECORD_DATA_ACCESS_TYPES,
   REGISTRATION_KIND_FOR_OP,
@@ -36343,6 +36867,7 @@ async function parsePSError(response) {
   WriteSessionExpiredError,
   WriteTransportError,
   WriteUnauthorizedError,
+  askPersonalServer,
   assertDerivedScopeNaming,
   assertValidPkceVerifier,
   authorizeEscrowPayment,
@@ -36386,6 +36911,7 @@ async function parsePSError(response) {
   dataRegistryDomain,
   decryptWithPassword,
   deleteDataPoint,
+  deleteQuestion,
   deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
@@ -36415,6 +36941,7 @@ async function parsePSError(response) {
   getOpFee,
   getPersonalServerLineage,
   getPlatformCapabilities,
+  getQuestion,
   getServiceEndpoints,
   grantPermissions,
   grantRegistrationDomain,
@@ -36427,6 +36954,7 @@ async function parsePSError(response) {
   isPlatformSupported,
   isRedactedLineageNode,
   isTombstoneHashes,
+  listQuestions,
   mainnetServices,
   moksha,
   mokshaServices,
@@ -36446,8 +36974,10 @@ async function parsePSError(response) {
   personalServerLineagePath,
   personalServerRegistrationDomain,
   readPersonalServerData,
+  recomputeQuestion,
   recoverServerOwner,
   registerPersonalServerSignature,
+  registerQuestion,
   resolveWriteSigner,
   scopeCoveredByGrant,
   scopeMatchesPattern,
@@ -36467,6 +36997,7 @@ async function parsePSError(response) {
   verifyGrantRegistration,
   verifyPkceChallenge,
   verifyWeb3Signed,
+  waitForQuestion,
   writeData,
   writePersonalServerData
 });