@agent-native/core-corpus 0.216.0 → 0.217.0

package/corpus/templates/content/actions/_builder-cms-read-client.ts

@@ -1,4 +1,6 @@
+import { fail, isActionContractError } from "@agent-native/core/action";
 import {
+  BUILDER_CONTENT_READ_SCOPE,
   BUILDER_PUBLISH_MCP_RESOURCE,
   resolveBuilderCredential,
   resolveBuilderRequestAuthorization,
@@ -35,10 +37,14 @@ export interface BuilderCmsReadProgress {
   pageSize: number;
   startOffset: number;
   nextOffset: number;
+  nextCursor?: string;
   fetchedEntryCount: number;
   hasMore: boolean;
   partial: boolean;
   readMode: "builder-api" | "mcp" | "none";
+  sourceSpacePublicKey?: string;
+  sourceConnectionId?: string;
+  observedCollectionCount?: number;
 }
 
 export interface BuilderCmsEntryLiveState {
@@ -167,6 +173,7 @@ export type BuilderCmsContentEntryReadResult =
       entry: null;
       providerStatus:
         | "http_404"
+        | "http_200_not_found"
         | "http_200_unexpected_entry"
         | "mcp_not_found";
     };
@@ -177,6 +184,7 @@ export class BuilderCmsContentEntryReadError extends Error {
     readonly reason:
       | "auth_failed"
       | "access_denied"
+      | "not_found"
       | "transient_read_failure"
       | "malformed_body",
     readonly providerStatus: string,
@@ -196,6 +204,15 @@ type BuilderMcpToolResult = {
   content?: BuilderMcpContentPart[];
 };
 
+export const RETRYABLE_BUILDER_SOURCE_BINDING_ERRORS = new Set([
+  "builder_connection_required",
+  "builder_oauth_reauthorization_required",
+  "builder_source_binding_invalid",
+  "builder_source_binding_required",
+  "builder_source_connection_mismatch",
+  "builder_source_space_mismatch",
+]);
+
 const BUILDER_CMS_DEFAULT_READ_LIMIT = 500;
 const BUILDER_CMS_MAX_READ_LIMIT = 10_000;
 const BUILDER_CMS_PAGE_SIZE = 100;
@@ -322,6 +339,12 @@ function builderContentApiHost() {
   ).replace(/\/+$/, "");
 }
 
+// The general read routes (/api/v1/models, /api/v1/query-data) carry the
+// user's OAuth bearer, and Builder serves them on this host (api.builder.io
+// answers them with 404). It is a constant on purpose: no host override may
+// redirect the bearer.
+const BUILDER_OAUTH_READ_HOST = "https://cdn.builder.io";
+
 function entryArrayFromResponse(value: unknown) {
   if (Array.isArray(value)) return value;
   if (!value || typeof value !== "object") return [];
@@ -329,6 +352,33 @@ function entryArrayFromResponse(value: unknown) {
   return Array.isArray(record.results) ? record.results : [];
 }
 
+function parseBuilderGeneralQueryDataResponse(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    fail("Builder query-data returned a malformed response.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
+    });
+  }
+  const record = value as Record<string, unknown>;
+  if (!Array.isArray(record.results)) {
+    fail("Builder query-data did not return a results array.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
+    });
+  }
+  if (
+    typeof record.totalCount !== "number" ||
+    !Number.isInteger(record.totalCount) ||
+    record.totalCount < 0
+  ) {
+    fail("Builder query-data read did not return a valid totalCount.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
+    });
+  }
+  return { results: record.results, totalCount: record.totalCount };
+}
+
 function stringFromUnknown(value: unknown) {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
@@ -436,13 +486,22 @@ async function fetchBuilderContentPage(args: {
   fetchImpl: FetchLike;
   url: URL;
   privateKey?: string;
+  signal?: AbortSignal;
 }): Promise<Response> {
   let lastError: unknown = null;
   for (let attempt = 0; attempt <= BUILDER_CMS_READ_RETRIES; attempt += 1) {
+    if (args.signal?.aborted) {
+      throw args.signal.reason instanceof Error
+        ? args.signal.reason
+        : new Error("Builder request was aborted.");
+    }
     try {
       const headers: Record<string, string> = { accept: "application/json" };
       if (args.privateKey) headers.authorization = `Bearer ${args.privateKey}`;
-      const response = await args.fetchImpl(args.url, { headers });
+      const response = await args.fetchImpl(args.url, {
+        headers,
+        ...(args.signal ? { signal: args.signal } : {}),
+      });
       if (
         !retryableBuilderReadStatus(response.status) ||
         attempt === BUILDER_CMS_READ_RETRIES
@@ -451,7 +510,7 @@ async function fetchBuilderContentPage(args: {
       }
     } catch (error) {
       lastError = error;
-      if (attempt === BUILDER_CMS_READ_RETRIES) {
+      if (args.signal?.aborted || attempt === BUILDER_CMS_READ_RETRIES) {
         throw error;
       }
     }
@@ -486,11 +545,221 @@ function builderMcpEndpoint(
   ).replace(/\/+$/, "");
 }
 
-async function readBuilderCmsAuthorization() {
-  return resolveBuilderRequestAuthorization({
-    oauthResource: "publish",
-    legacyCredentialKeys: ["BUILDER_PRIVATE_KEY", "BUILDER_CMS_PRIVATE_KEY"],
+function isBuilderOAuthReauthorizationRequired(error: unknown) {
+  return (
+    isActionContractError(error) &&
+    error.errorCode === "builder_oauth_reauthorization_required"
+  );
+}
+
+function isBuilderReadSourceBound(
+  expectedSourceSpace?: string | null,
+  expectedSourceConnectionId?: string | null,
+) {
+  const hasSourceSpace = Boolean(expectedSourceSpace?.trim());
+  const hasSourceConnectionId = Boolean(expectedSourceConnectionId?.trim());
+  if (hasSourceSpace !== hasSourceConnectionId) {
+    fail(
+      "Builder source binding must include both its space and connection. Reconnect the source before reading.",
+      { errorCode: "builder_source_binding_invalid", statusCode: 412 },
+    );
+  }
+  return hasSourceSpace;
+}
+
+async function readGeneralBuilderContentAuthorization(sourceBound: boolean) {
+  try {
+    return {
+      authorization: await resolveBuilderRequestAuthorization({
+        oauthResource: "general",
+        requiredScope: BUILDER_CONTENT_READ_SCOPE,
+        legacyCredentialKeys: [],
+      }),
+      reauthorization: null,
+    };
+  } catch (error) {
+    // The shared resolver throws instead of returning null when a grant
+    // predates builder:content:read. Only an unbound source may keep its
+    // previous read path until the user re-authorizes.
+    if (sourceBound || !isBuilderOAuthReauthorizationRequired(error)) {
+      throw error;
+    }
+    return { authorization: null, reauthorization: error };
+  }
+}
+
+async function readBuilderCmsAuthorization(sourceBound = false) {
+  const general = await readGeneralBuilderContentAuthorization(sourceBound);
+  if (general.authorization) return general.authorization;
+  try {
+    const publish = await resolveBuilderRequestAuthorization({
+      oauthResource: "publish",
+      legacyCredentialKeys: ["BUILDER_PRIVATE_KEY", "BUILDER_CMS_PRIVATE_KEY"],
+    });
+    if (publish || !general.reauthorization) return publish;
+  } catch (error) {
+    if (!general.reauthorization) throw error;
+  }
+  throw general.reauthorization;
+}
+
+function isGeneralBuilderOAuth(
+  authorization: BuilderRequestAuthorization | null,
+): authorization is BuilderRequestAuthorization & {
+  source: "oauth";
+  oauthResource: "general";
+} {
+  return (
+    authorization?.source === "oauth" &&
+    authorization.oauthResource === "general"
+  );
+}
+
+function assertBuilderReadSourceAuthorization(
+  authorization: BuilderRequestAuthorization | null,
+  expectedSourceSpace?: string | null,
+  expectedSourceConnectionId?: string | null,
+) {
+  if (
+    isBuilderReadSourceBound(expectedSourceSpace, expectedSourceConnectionId) &&
+    !isGeneralBuilderOAuth(authorization)
+  ) {
+    fail(
+      "This Builder source's OAuth connection is unavailable. Reconnect the source before reading.",
+      { errorCode: "builder_connection_required", statusCode: 412 },
+    );
+  }
+}
+
+function requireBuilderOAuthPublicKey(
+  authorization: BuilderRequestAuthorization,
+  expectedSourceSpace?: string | null,
+  expectedSourceConnectionId?: string | null,
+) {
+  const selected = authorization.oauthSelectedPublicKey;
+  if (!selected) {
+    fail(
+      "Builder OAuth access did not identify its selected space. Reconnect Builder.io in Settings.",
+      { errorCode: "builder_connection_required", statusCode: 412 },
+    );
+  }
+  if (expectedSourceSpace && selected !== expectedSourceSpace) {
+    fail(
+      "The connected Builder space does not match this Content source. Reconnect the source's Builder space before continuing.",
+      { errorCode: "builder_source_space_mismatch", statusCode: 409 },
+    );
+  }
+  if (
+    expectedSourceConnectionId &&
+    authorization.oauthConnectionId !== expectedSourceConnectionId
+  ) {
+    fail(
+      "The connected Builder credential does not match this Content source. Reconnect the source before continuing.",
+      { errorCode: "builder_source_connection_mismatch", statusCode: 409 },
+    );
+  }
+  return selected;
+}
+
+async function readBuilderCmsGeneralModels(args: {
+  authorization: BuilderRequestAuthorization;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  fetchImpl: FetchLike;
+  signal?: AbortSignal;
+}) {
+  const publicKey = requireBuilderOAuthPublicKey(
+    args.authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  const url = new URL("/api/v1/models", BUILDER_OAUTH_READ_HOST);
+  url.searchParams.set("apiKey", publicKey);
+  const response = await fetchBuilderContentPage({
+    fetchImpl: args.fetchImpl,
+    url,
+    privateKey: args.authorization.token,
+    signal: args.signal,
+  });
+  if (response.status === 401) {
+    fail(
+      "Builder rejected this Builder.io connection. Reconnect Builder.io in Settings.",
+      { errorCode: "builder_connection_required", statusCode: 412 },
+    );
+  }
+  if (!response.ok) {
+    fail(`Builder model discovery failed with HTTP ${response.status}.`, {
+      errorCode: "builder_upstream_failed",
+      statusCode: 424,
+      details: { httpStatus: response.status },
+    });
+  }
+  return builderMcpModelsFromToolResponse((await response.json()) as unknown);
+}
+
+// Body hydration reads entries one at a time and each read needs the model id.
+// Rediscovering it per entry costs a request per row, so a large source floods
+// Builder.
+const BUILDER_MODEL_ID_TTL_MS = 60_000;
+const builderModelIdCache = new WeakMap<
+  FetchLike,
+  Map<string, { expiresAt: number; modelId: string }>
+>();
+
+async function resolveBuilderCmsGeneralModelId(args: {
+  model: string;
+  authorization: BuilderRequestAuthorization;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  fetchImpl: FetchLike;
+  signal?: AbortSignal;
+}) {
+  const publicKey = requireBuilderOAuthPublicKey(
+    args.authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  const key = [
+    publicKey,
+    args.authorization.oauthConnectionId ?? "",
+    args.model.trim().toLowerCase(),
+  ].join("\u0000");
+  const entries = builderModelIdCache.get(args.fetchImpl) ?? new Map();
+  builderModelIdCache.set(args.fetchImpl, entries);
+  const cached = entries.get(key);
+  if (cached && cached.expiresAt > Date.now()) return cached.modelId;
+  const modelId = await discoverBuilderCmsGeneralModelId(args);
+  entries.set(key, {
+    expiresAt: Date.now() + BUILDER_MODEL_ID_TTL_MS,
+    modelId,
   });
+  return modelId;
+}
+
+async function discoverBuilderCmsGeneralModelId(args: {
+  model: string;
+  authorization: BuilderRequestAuthorization;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  fetchImpl: FetchLike;
+  signal?: AbortSignal;
+}) {
+  const requestedModel = args.model.trim().toLowerCase();
+  const models = await readBuilderCmsGeneralModels(args);
+  const idMatch = models.find(
+    (candidate) => candidate.id.trim().toLowerCase() === requestedModel,
+  );
+  const nameMatches = models.filter(
+    (candidate) => candidate.name.trim().toLowerCase() === requestedModel,
+  );
+  const model = nameMatches.length === 1 ? nameMatches[0] : idMatch;
+  if (!model) {
+    fail(`Builder model ${args.model} was not found.`, {
+      errorCode: "builder_model_not_found",
+      statusCode: 404,
+    });
+  }
+  return model.id;
 }
 
 function parseBuilderMcpToolJson(value: unknown) {
@@ -760,17 +1029,40 @@ function stringOptionsFromUnknown(value: unknown): string[] | undefined {
 function builderMcpModelsFromToolResponse(
   response: unknown,
 ): BuilderCmsModelSummary[] {
-  if (!response || typeof response !== "object") return [];
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    fail("Builder model discovery returned a malformed response.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
+    });
+  }
   const record = response as Record<string, unknown>;
-  const models = Array.isArray(record.models) ? record.models : [];
-  return models
-    .map((model) => normalizeBuilderCmsModel(model))
-    .filter((model): model is BuilderCmsModelSummary => Boolean(model))
-    .sort((a, b) => {
-      if (a.name === "agent-native-blog-article-test") return -1;
-      if (b.name === "agent-native-blog-article-test") return 1;
-      return a.displayName.localeCompare(b.displayName);
+  if (!Array.isArray(record.models)) {
+    fail("Builder model discovery did not return a models array.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
     });
+  }
+  // /api/v1/models also lists archived models, which Builder's own model list
+  // hides; without this the source picker offers them.
+  const models = record.models
+    .filter(
+      (model) =>
+        !model ||
+        typeof model !== "object" ||
+        (model as Record<string, unknown>).archived !== true,
+    )
+    .map((model) => normalizeBuilderCmsModel(model));
+  if (models.some((model) => !model)) {
+    fail("Builder model discovery returned a malformed model.", {
+      errorCode: "builder_response_invalid",
+      statusCode: 424,
+    });
+  }
+  return (models as BuilderCmsModelSummary[]).sort((a, b) => {
+    if (a.name === "agent-native-blog-article-test") return -1;
+    if (b.name === "agent-native-blog-article-test") return 1;
+    return a.displayName.localeCompare(b.displayName);
+  });
 }
 
 async function initializeBuilderMcp(args: {
@@ -882,6 +1174,8 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
   limit?: number;
   maxPages?: number;
   offset?: number;
+  startingFetchedEntryCount?: number;
+  expectedCollectionCount?: number;
   fetchImpl: FetchLike;
   privateKey: string;
   endpoint: string;
@@ -894,6 +1188,8 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
     typeof args.offset === "number" && Number.isFinite(args.offset)
       ? Math.max(0, Math.floor(args.offset))
       : 0;
+  const startingFetchedEntryCount =
+    args.startingFetchedEntryCount ?? startOffset;
   const connection = await initializeBuilderMcp({
     endpoint,
     privateKey: args.privateKey,
@@ -909,6 +1205,7 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
   let pagesRead = 0;
   let hasMore = false;
   let offset = startOffset;
+  let observedCollectionCount: number | null = null;
   while (contentEntries.length < requestedLimit) {
     const pageLimit = Math.min(
       BUILDER_CMS_PAGE_SIZE,
@@ -955,8 +1252,35 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       pageEntries,
     );
     pagesRead += 1;
-    offset += pageLimit;
+    offset += providerEntryCount;
     const totalCount = builderMcpTotalCount(contentJson);
+    if (observedCollectionCount === null && totalCount !== null) {
+      observedCollectionCount = totalCount;
+      if (
+        args.expectedCollectionCount !== undefined &&
+        totalCount !== args.expectedCollectionCount
+      ) {
+        fail(
+          "Builder MCP collection changed between refresh pages; restart the source refresh before mutating the snapshot.",
+          { errorCode: "builder_source_changed", statusCode: 409 },
+        );
+      }
+    } else if (
+      totalCount !== null &&
+      observedCollectionCount !== null &&
+      totalCount !== observedCollectionCount
+    ) {
+      fail(
+        "Builder MCP collection changed during pagination; refresh the source to restart the observed collection read.",
+        { errorCode: "builder_source_changed", statusCode: 409 },
+      );
+    }
+    if (startOffset > 0 && observedCollectionCount === null) {
+      fail(
+        "Builder MCP continuation has no saved collection count. Start a full refresh before continuing.",
+        { errorCode: "builder_source_continuation_mismatch", statusCode: 409 },
+      );
+    }
     hasMore =
       totalCount !== null
         ? offset < totalCount
@@ -979,10 +1303,11 @@ async function readBuilderCmsContentEntriesViaMcp(args: {
       pageSize: BUILDER_CMS_PAGE_SIZE,
       startOffset,
       nextOffset: offset,
-      fetchedEntryCount: startOffset + contentEntries.length,
+      fetchedEntryCount: startingFetchedEntryCount + contentEntries.length,
       hasMore,
       partial: hasMore,
       readMode: "mcp",
+      observedCollectionCount: observedCollectionCount ?? undefined,
     },
   };
 }
@@ -1150,11 +1475,334 @@ async function readBuilderCmsContentEntriesViaContentApi(args: {
   };
 }
 
+async function readBuilderCmsContentEntriesViaGeneralApi(args: {
+  model: string;
+  limit?: number;
+  maxPages?: number;
+  offset?: number;
+  afterId?: string;
+  fetchImpl: FetchLike;
+  authorization: BuilderRequestAuthorization;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  expectedCollectionCount?: number;
+}): Promise<BuilderCmsReadResult> {
+  const fetchedAt = new Date().toISOString();
+  const requestedLimit = readLimit(args.limit);
+  const startOffset =
+    typeof args.offset === "number" && Number.isFinite(args.offset)
+      ? Math.max(0, Math.floor(args.offset))
+      : 0;
+  const startAfterId = args.afterId?.trim() || null;
+  if (startOffset > 0 && !startAfterId) {
+    fail(
+      "Builder query-data continuation needs a stable entry cursor. Restart the source refresh to establish one.",
+      { errorCode: "builder_source_continuation_mismatch", statusCode: 409 },
+    );
+  }
+  const publicKey = requireBuilderOAuthPublicKey(
+    args.authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  const modelId = await resolveBuilderCmsGeneralModelId(args);
+  const entries: BuilderCmsSourceEntry[] = [];
+  const seenIds = new Set<string>();
+  let offset = startOffset;
+  let cursor = startAfterId;
+  let pagesRead = 0;
+  let observedCollectionCount: number | null = null;
+  let hasMore = false;
+
+  while (entries.length < requestedLimit) {
+    if (args.maxPages && pagesRead >= args.maxPages) break;
+    const pageLimit = readPageLimit(requestedLimit - entries.length);
+    // Each page re-reads the previous page's last entry so a count-preserving
+    // edit before the offset (delete + append) cannot silently skip a row.
+    const anchored = offset > 0 && Boolean(cursor);
+    const url = new URL("/api/v1/query-data", BUILDER_OAUTH_READ_HOST);
+    url.searchParams.set("apiKey", publicKey);
+    url.searchParams.set("query.modelId", modelId);
+    url.searchParams.set("sort.id", "1");
+    url.searchParams.set("offset", String(anchored ? offset - 1 : offset));
+    url.searchParams.set("limit", String(anchored ? pageLimit + 1 : pageLimit));
+    url.searchParams.set("fetchTotalCount", "true");
+    url.searchParams.set("noCache", "true");
+    url.searchParams.set("cachebust", String(Date.now() + pagesRead));
+    const response = await fetchBuilderContentPage({
+      fetchImpl: args.fetchImpl,
+      url,
+      privateKey: args.authorization.token,
+    });
+    if (!response.ok) {
+      return {
+        state: "error",
+        entries: [],
+        fetchedAt,
+        message: `Builder CMS read failed with HTTP ${response.status}.`,
+        progress: {
+          requestedLimit,
+          pageSize: BUILDER_CMS_PAGE_SIZE,
+          startOffset,
+          nextOffset: offset,
+          nextCursor: cursor ?? undefined,
+          fetchedEntryCount: startOffset + entries.length,
+          hasMore: false,
+          partial: entries.length > 0,
+          readMode: "builder-api",
+        },
+      };
+    }
+    const json = (await response.json()) as unknown;
+    const { results: rawPageEntries, totalCount } =
+      parseBuilderGeneralQueryDataResponse(json);
+    const pageCollectionCount = totalCount;
+    if (observedCollectionCount === null) {
+      observedCollectionCount = pageCollectionCount;
+      if (startOffset > 0 && args.expectedCollectionCount === undefined) {
+        fail(
+          "Builder source continuation has no saved collection count. Start a full refresh before continuing.",
+          {
+            errorCode: "builder_source_continuation_mismatch",
+            statusCode: 409,
+          },
+        );
+      }
+      if (
+        args.expectedCollectionCount !== undefined &&
+        pageCollectionCount !== args.expectedCollectionCount
+      ) {
+        fail(
+          "Builder query-data collection changed between refresh pages; restart the source refresh before mutating the snapshot.",
+          { errorCode: "builder_source_changed", statusCode: 409 },
+        );
+      }
+    }
+    if (
+      observedCollectionCount !== null &&
+      pageCollectionCount !== observedCollectionCount
+    ) {
+      fail(
+        "Builder query-data collection changed during cursor pagination; refresh the source to restart the observed collection read.",
+        { errorCode: "builder_source_changed", statusCode: 409 },
+      );
+    }
+    const normalizedEntries = rawPageEntries
+      .map((entry) => normalizeBuilderCmsApiEntry(entry, args.model))
+      .filter((entry): entry is BuilderCmsSourceEntry => Boolean(entry));
+    if (normalizedEntries.length !== rawPageEntries.length) {
+      fail(
+        "Builder query-data returned a malformed entry before the observed collection was complete.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    if (anchored && normalizedEntries[0]?.id !== cursor) {
+      fail(
+        "Builder query-data collection changed before the saved cursor; restart the source refresh.",
+        { errorCode: "builder_source_changed", statusCode: 409 },
+      );
+    }
+    const pageEntries = anchored
+      ? normalizedEntries.slice(1)
+      : normalizedEntries;
+    const priorCursor = cursor;
+    if (priorCursor && pageEntries.some((entry) => entry.id <= priorCursor)) {
+      fail(
+        "Builder query-data cursor pagination repeated or reordered an entry.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    const appended = appendUniqueBuilderEntries(entries, seenIds, pageEntries);
+    if (appended !== pageEntries.length) {
+      fail(
+        "Builder query-data returned duplicate entries before the observed collection was complete.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    if (offset + pageEntries.length > totalCount) {
+      fail(
+        "Builder query-data returned more entries than its reported totalCount.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    pagesRead += 1;
+    offset += pageEntries.length;
+    cursor = pageEntries[pageEntries.length - 1]?.id ?? cursor;
+    hasMore = offset < totalCount;
+    if (hasMore && (pageEntries.length === 0 || appended === 0)) {
+      fail(
+        "Builder query-data pagination returned no new entries before the observed collection was complete.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    if (!hasMore) break;
+  }
+
+  return {
+    state: "live",
+    entries,
+    fetchedAt,
+    message: null,
+    progress: {
+      requestedLimit,
+      pageSize: BUILDER_CMS_PAGE_SIZE,
+      startOffset,
+      nextOffset: offset,
+      nextCursor: cursor ?? undefined,
+      fetchedEntryCount: offset,
+      hasMore,
+      partial: hasMore,
+      readMode: "builder-api",
+      sourceSpacePublicKey: publicKey,
+      sourceConnectionId: args.authorization.oauthConnectionId,
+      observedCollectionCount: observedCollectionCount ?? undefined,
+    },
+  };
+}
+
+async function readBuilderCmsGeneralApiEntry(args: {
+  model: string;
+  entryId: string;
+  authorization: BuilderRequestAuthorization;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  fetchImpl: FetchLike;
+  signal?: AbortSignal;
+}) {
+  const publicKey = requireBuilderOAuthPublicKey(
+    args.authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  const modelId = await resolveBuilderCmsGeneralModelId(args);
+  const url = new URL("/api/v1/query-data", BUILDER_OAUTH_READ_HOST);
+  url.searchParams.set("apiKey", publicKey);
+  url.searchParams.set("query.modelId", modelId);
+  url.searchParams.set("query.id", args.entryId);
+  url.searchParams.set("sort.id", "1");
+  url.searchParams.set("offset", "0");
+  url.searchParams.set("limit", "1");
+  url.searchParams.set("fetchTotalCount", "true");
+  // This read decides whether a write may overwrite the entry, and the host is
+  // a CDN that may serve a cached copy (including stale-if-error), so each
+  // request gets its own cache key.
+  url.searchParams.set("noCache", "true");
+  url.searchParams.set("cachebust", String(Date.now()));
+  return fetchBuilderContentPage({
+    fetchImpl: args.fetchImpl,
+    url,
+    privateKey: args.authorization.token,
+    signal: args.signal,
+  });
+}
+
+function builderGeneralEntryHttpFailure(message: string, status: number) {
+  const reason =
+    status === 401
+      ? "auth_failed"
+      : status === 403
+        ? "access_denied"
+        : status === 429 || status >= 500
+          ? "transient_read_failure"
+          : "malformed_body";
+  return new BuilderCmsContentEntryReadError(
+    message,
+    reason,
+    `http_${status}`,
+    reason === "transient_read_failure",
+  );
+}
+
+function builderGeneralEntryRequestFailure(error: unknown) {
+  if (!isActionContractError(error)) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new BuilderCmsContentEntryReadError(
+      `Builder CMS entry read failed before a response was received: ${message}`,
+      "transient_read_failure",
+      "network_error",
+      true,
+    );
+  }
+  const httpStatus = error.details?.httpStatus;
+  if (typeof httpStatus === "number") {
+    return builderGeneralEntryHttpFailure(error.message, httpStatus);
+  }
+  const reason =
+    error.statusCode === 404
+      ? "not_found"
+      : error.statusCode === 424
+        ? "malformed_body"
+        : "access_denied";
+  return new BuilderCmsContentEntryReadError(
+    error.message,
+    reason,
+    error.errorCode,
+    RETRYABLE_BUILDER_SOURCE_BINDING_ERRORS.has(error.errorCode),
+  );
+}
+
 export async function readBuilderCmsEntryLiveState(args: {
   model: string;
   entryId: string;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  requireBoundOAuth?: boolean;
   fetchImpl?: FetchLike;
+  signal?: AbortSignal;
 }): Promise<BuilderCmsEntryLiveState> {
+  const { authorization: generalAuthorization } =
+    await readGeneralBuilderContentAuthorization(
+      isBuilderReadSourceBound(
+        args.expectedSourceSpace,
+        args.expectedSourceConnectionId,
+      ),
+    );
+  assertBuilderReadSourceAuthorization(
+    generalAuthorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  if (
+    args.requireBoundOAuth === true &&
+    isGeneralBuilderOAuth(generalAuthorization) &&
+    !isBuilderReadSourceBound(
+      args.expectedSourceSpace,
+      args.expectedSourceConnectionId,
+    )
+  ) {
+    fail(
+      "Builder OAuth reads require a saved space and connection binding. Reattach the source with mode replace to bind the current Builder connection before reading.",
+      { errorCode: "builder_source_binding_required", statusCode: 409 },
+    );
+  }
+  if (isGeneralBuilderOAuth(generalAuthorization)) {
+    const response = await readBuilderCmsGeneralApiEntry({
+      model: args.model,
+      entryId: args.entryId,
+      authorization: generalAuthorization,
+      expectedSourceSpace: args.expectedSourceSpace,
+      expectedSourceConnectionId: args.expectedSourceConnectionId,
+      fetchImpl: args.fetchImpl ?? fetch,
+      signal: args.signal,
+    });
+    if (!response.ok) {
+      fail(`Builder CMS live entry read failed with HTTP ${response.status}.`, {
+        errorCode: "builder_upstream_failed",
+        statusCode: 424,
+      });
+    }
+    const json = (await response.json()) as unknown;
+    const { results } = parseBuilderGeneralQueryDataResponse(json);
+    if (results.length === 0) return liveStateFromBuilderEntry([]);
+    const entry = normalizeBuilderCmsApiEntry(results[0], args.model);
+    if (!entry || entry.id !== args.entryId) {
+      fail(
+        "Builder CMS live entry read returned an unexpected entry payload.",
+        { errorCode: "builder_response_invalid", statusCode: 424 },
+      );
+    }
+    return liveStateFromBuilderEntry(entry.rawEntry);
+  }
   const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
   if (!publicKey) {
     throw new Error(
@@ -1173,6 +1821,7 @@ export async function readBuilderCmsEntryLiveState(args: {
   const response = await fetchBuilderContentPage({
     fetchImpl: args.fetchImpl ?? fetch,
     url,
+    signal: args.signal,
   });
   if (response.status === 404) {
     return {
@@ -1196,6 +1845,9 @@ export async function readBuilderCmsEntryLiveState(args: {
 export async function readBuilderCmsContentEntry(args: {
   model: string;
   entryId: string;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  requireBoundOAuth?: boolean;
   fetchImpl?: FetchLike;
 }): Promise<BuilderCmsSourceEntry | null> {
   const result = await readBuilderCmsContentEntryResult({
@@ -1208,10 +1860,36 @@ export async function readBuilderCmsContentEntry(args: {
 export async function readBuilderCmsContentEntryResult(args: {
   model: string;
   entryId: string;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
+  requireBoundOAuth?: boolean;
   fetchImpl?: FetchLike;
   strictEntryIdentity?: boolean;
 }): Promise<BuilderCmsContentEntryReadResult> {
-  const authorization = await readBuilderCmsAuthorization();
+  const authorization = await readBuilderCmsAuthorization(
+    isBuilderReadSourceBound(
+      args.expectedSourceSpace,
+      args.expectedSourceConnectionId,
+    ),
+  );
+  assertBuilderReadSourceAuthorization(
+    authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
+  if (
+    args.requireBoundOAuth === true &&
+    isGeneralBuilderOAuth(authorization) &&
+    !isBuilderReadSourceBound(
+      args.expectedSourceSpace,
+      args.expectedSourceConnectionId,
+    )
+  ) {
+    fail(
+      "Builder OAuth reads require a saved space and connection binding. Reattach the source with mode replace to bind the current Builder connection before reading.",
+      { errorCode: "builder_source_binding_required", statusCode: 409 },
+    );
+  }
   const privateKey = authorization?.token ?? null;
   const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
   if (!publicKey && !privateKey) {
@@ -1223,6 +1901,85 @@ export async function readBuilderCmsContentEntryResult(args: {
     );
   }
 
+  if (isGeneralBuilderOAuth(authorization)) {
+    let response: Response;
+    try {
+      response = await readBuilderCmsGeneralApiEntry({
+        model: args.model,
+        entryId: args.entryId,
+        authorization,
+        expectedSourceSpace: args.expectedSourceSpace,
+        expectedSourceConnectionId: args.expectedSourceConnectionId,
+        fetchImpl: args.fetchImpl ?? fetch,
+      });
+    } catch (error) {
+      throw builderGeneralEntryRequestFailure(error);
+    }
+    if (!response.ok) {
+      throw builderGeneralEntryHttpFailure(
+        `Builder CMS entry read failed with HTTP ${response.status}.`,
+        response.status,
+      );
+    }
+    let json: unknown;
+    try {
+      json = (await response.json()) as unknown;
+    } catch {
+      throw new BuilderCmsContentEntryReadError(
+        "Builder CMS entry read returned malformed JSON.",
+        "malformed_body",
+        "http_200_invalid_json",
+        false,
+      );
+    }
+    let entries: unknown[];
+    try {
+      entries = parseBuilderGeneralQueryDataResponse(json).results;
+    } catch (error) {
+      throw new BuilderCmsContentEntryReadError(
+        error instanceof Error
+          ? error.message
+          : "Builder query-data returned a malformed response.",
+        "malformed_body",
+        "http_200_malformed_body",
+        false,
+      );
+    }
+    if (entries.length === 0) {
+      return {
+        state: "not_found",
+        entry: null,
+        providerStatus: "http_200_not_found",
+      };
+    }
+    const rawEntry = entries[0];
+    const entry = normalizeBuilderCmsApiEntry(rawEntry, args.model);
+    if (!entry) {
+      throw new BuilderCmsContentEntryReadError(
+        "Builder CMS entry read returned a malformed entry payload.",
+        "malformed_body",
+        "http_200_invalid_entry",
+        false,
+      );
+    }
+    if (entry.id !== args.entryId) {
+      if (args.strictEntryIdentity === false) {
+        return {
+          state: "not_found",
+          entry: null,
+          providerStatus: "http_200_unexpected_entry",
+        };
+      }
+      throw new BuilderCmsContentEntryReadError(
+        "Builder CMS entry read returned an unexpected entry payload.",
+        "malformed_body",
+        "http_200_unexpected_entry",
+        false,
+      );
+    }
+    return { state: "found", entry, providerStatus: "http_200" };
+  }
+
   if (privateKey && (authorization?.source === "oauth" || !publicKey)) {
     const endpoint = builderMcpEndpoint(authorization?.source);
     try {
@@ -1396,13 +2153,20 @@ export async function readBuilderCmsContentEntryResult(args: {
 export async function listBuilderCmsModels(
   args: {
     fetchImpl?: FetchLike;
+    expectedSourceSpace?: string | null;
+    expectedSourceConnectionId?: string | null;
   } = {},
 ): Promise<BuilderCmsModelsResponse> {
   const fetchedAt = new Date().toISOString();
   const fetchImpl = args.fetchImpl ?? fetch;
   let authorization: BuilderRequestAuthorization | null;
   try {
-    authorization = await readBuilderCmsAuthorization();
+    authorization = await readBuilderCmsAuthorization(
+      isBuilderReadSourceBound(
+        args.expectedSourceSpace,
+        args.expectedSourceConnectionId,
+      ),
+    );
   } catch (error) {
     return {
       state: "error",
@@ -1415,6 +2179,11 @@ export async function listBuilderCmsModels(
     };
   }
   const privateKey = authorization?.token ?? null;
+  assertBuilderReadSourceAuthorization(
+    authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
   if (!privateKey) {
     return {
       state: "unconfigured",
@@ -1426,6 +2195,20 @@ export async function listBuilderCmsModels(
   }
 
   try {
+    if (isGeneralBuilderOAuth(authorization)) {
+      const models = await readBuilderCmsGeneralModels({
+        authorization,
+        fetchImpl,
+        expectedSourceSpace: args.expectedSourceSpace,
+        expectedSourceConnectionId: args.expectedSourceConnectionId,
+      });
+      return {
+        state: "live",
+        models,
+        fetchedAt,
+        message: null,
+      };
+    }
     const endpoint = builderMcpEndpoint(authorization?.source);
     const connection = await initializeBuilderMcp({
       endpoint,
@@ -1475,8 +2258,14 @@ export async function listBuilderCmsModels(
 export async function readBuilderCmsModelFields(args: {
   model: string;
   fetchImpl?: FetchLike;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
 }): Promise<BuilderCmsModelFieldSummary[]> {
-  const models = await listBuilderCmsModels({ fetchImpl: args.fetchImpl });
+  const models = await listBuilderCmsModels({
+    fetchImpl: args.fetchImpl,
+    expectedSourceSpace: args.expectedSourceSpace,
+    expectedSourceConnectionId: args.expectedSourceConnectionId,
+  });
   if (models.state === "unconfigured") return [];
   if (models.state === "error") {
     throw new Error(models.message ?? "Builder CMS model discovery failed.");
@@ -1495,6 +2284,8 @@ export async function readBuilderCmsModelFields(args: {
 
 export async function readBuilderCmsContentEntries(args: {
   model: string;
+  expectedSourceSpace?: string | null;
+  expectedSourceConnectionId?: string | null;
   fieldPaths?: readonly string[];
   includeBodies?: boolean;
   allowCached?: boolean;
@@ -1503,13 +2294,22 @@ export async function readBuilderCmsContentEntries(args: {
   limit?: number;
   maxPages?: number;
   offset?: number;
+  afterId?: string;
+  startingFetchedEntryCount?: number;
+  expectedCollectionCount?: number;
+  requireBoundOAuth?: boolean;
   fetchImpl?: FetchLike;
 }): Promise<BuilderCmsReadResult> {
   const fetchedAt = new Date().toISOString();
   const fetchImpl = args.fetchImpl ?? fetch;
   let authorization: BuilderRequestAuthorization | null;
   try {
-    authorization = await readBuilderCmsAuthorization();
+    authorization = await readBuilderCmsAuthorization(
+      isBuilderReadSourceBound(
+        args.expectedSourceSpace,
+        args.expectedSourceConnectionId,
+      ),
+    );
   } catch (error) {
     return {
       state: "error",
@@ -1531,6 +2331,11 @@ export async function readBuilderCmsContentEntries(args: {
       },
     };
   }
+  assertBuilderReadSourceAuthorization(
+    authorization,
+    args.expectedSourceSpace,
+    args.expectedSourceConnectionId,
+  );
   const privateKey = authorization?.token ?? null;
   const publicKey = await resolveBuilderCredential("BUILDER_PUBLIC_KEY");
   if (args.requirePrivateKey === true && !privateKey) {
@@ -1552,6 +2357,59 @@ export async function readBuilderCmsContentEntries(args: {
       },
     };
   }
+  if (isGeneralBuilderOAuth(authorization)) {
+    try {
+      if (
+        args.requireBoundOAuth === true &&
+        !isBuilderReadSourceBound(
+          args.expectedSourceSpace,
+          args.expectedSourceConnectionId,
+        )
+      ) {
+        fail(
+          "Builder OAuth refresh requires a saved space and connection binding. Reattach this source with mode replace to bind the current Builder connection before refreshing.",
+          { errorCode: "builder_source_binding_required", statusCode: 409 },
+        );
+      }
+      return preserveProjectedBuilderFieldAbsence(
+        await readBuilderCmsContentEntriesViaGeneralApi({
+          model: args.model,
+          limit: args.limit,
+          maxPages: args.maxPages,
+          offset: args.offset,
+          afterId: args.afterId,
+          expectedCollectionCount: args.expectedCollectionCount,
+          fetchImpl,
+          authorization,
+          expectedSourceSpace: args.expectedSourceSpace,
+          expectedSourceConnectionId: args.expectedSourceConnectionId,
+        }),
+        args.fieldPaths,
+        args.rawData,
+      );
+    } catch (error) {
+      return {
+        state: "error",
+        entries: [],
+        fetchedAt,
+        message:
+          error instanceof Error
+            ? error.message
+            : "Builder CMS authenticated read failed.",
+        progress: {
+          requestedLimit: readLimit(args.limit),
+          pageSize: BUILDER_CMS_PAGE_SIZE,
+          startOffset: args.offset ?? 0,
+          nextOffset: args.offset ?? 0,
+          nextCursor: args.afterId,
+          fetchedEntryCount: args.offset ?? 0,
+          hasMore: false,
+          partial: false,
+          readMode: "builder-api",
+        },
+      };
+    }
+  }
   if (publicKey && authorization?.source !== "oauth") {
     const contentApiRead = await readBuilderCmsContentEntriesViaContentApi({
       model: args.model,
@@ -1587,6 +2445,8 @@ export async function readBuilderCmsContentEntries(args: {
           limit: args.limit,
           maxPages: args.maxPages,
           offset: args.offset,
+          startingFetchedEntryCount: args.startingFetchedEntryCount,
+          expectedCollectionCount: args.expectedCollectionCount,
           fetchImpl,
           privateKey,
           endpoint: builderMcpEndpoint(authorization?.source),