@rex0220/kintone-sql-tools 3.0.0 → 3.1.0

package/dist-cli/ksql.js

@@ -5643,7 +5643,7 @@ var KORDER_NATIVE_FIELD_TYPES = /* @__PURE__ */ new Set([
   "CREATOR",
   "MODIFIER"
 ]);
-function planKorderNative(input) {
+function planKorder(input) {
   const { stmt } = input;
   const reasons = [];
   if (stmt.orderMode !== "KINTONE_NATIVE") reasons.push("KORDER_MODE_REQUIRED");
@@ -5673,29 +5673,120 @@ function planKorderNative(input) {
       reasons.push(`KORDER_TYPE_UNSUPPORTED(field=${name}, type=${semantics.fieldType})`);
     }
   }
-  if (stmt.limit === null || stmt.limit < 0 || stmt.limit > 500) {
+  if (stmt.limit === null || !Number.isSafeInteger(stmt.limit) || stmt.limit < 0) {
     reasons.push(`KORDER_LIMIT_INVALID(limit=${String(stmt.limit)})`);
   }
-  if (stmt.limit !== null && stmt.limit > input.maxRecords) {
-    reasons.push(`KORDER_LIMIT_EXCEEDS_MAX_RECORDS(limit=${stmt.limit}, maxRecords=${input.maxRecords})`);
-  }
   const offset = stmt.offset ?? 0;
-  if (offset < 0 || offset > 1e4) reasons.push(`KORDER_OFFSET_INVALID(offset=${offset})`);
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    reasons.push(`KORDER_OFFSET_INVALID(offset=${offset})`);
+  }
+  const scanRows = stmt.limit === null ? Number.NaN : offset + stmt.limit;
+  if (stmt.limit !== null && !Number.isSafeInteger(scanRows)) {
+    reasons.push(`KORDER_SCAN_ROWS_INVALID(offset=${offset}, limit=${stmt.limit})`);
+  }
   const unique = [...new Set(reasons)];
   if (unique.length > 0) {
     throw new Error(
       `ArgumentError: KORDER BY cannot be executed (mode=KINTONE_NATIVE; ${unique.join(", ")}). Use ORDER BY for canonical local ordering or simplify the query.`
     );
   }
+  const native = stmt.limit <= 500 && offset <= 1e4 && stmt.limit <= input.maxRecords;
+  if (!native && scanRows > input.maxRecords) {
+    throw new Error(
+      `ArgumentError: KORDER BY cannot be executed (mode=KINTONE_NATIVE; KORDER_SCAN_ROWS_EXCEEDS_MAX_RECORDS(scanRows=${scanRows}, maxRecords=${input.maxRecords})). Use ORDER BY for canonical local ordering, raise maxRecords, or reduce LIMIT/OFFSET.`
+    );
+  }
   return {
-    kind: "KORDER_NATIVE",
+    kind: native ? "KORDER_NATIVE" : "KORDER_CURSOR",
     requiresCompleteInput: false,
     localOrderBy: false,
     applyLocalOffsetLimit: false,
-    reasonCodes: []
+    reasonCodes: [],
+    scanRows
   };
 }
 
+// src/core/errors/cursorErrors.ts
+var CursorCapacityError = class extends Error {
+  constructor(host, limit, waitMs) {
+    super(`CursorCapacityError: host=${host} \u306E active cursor \u4E0A\u9650 ${limit} \u306B ${waitMs}ms \u4EE5\u5185\u3067\u7A7A\u304D\u304C\u3067\u304D\u307E\u305B\u3093\u3067\u3057\u305F\u3002`);
+    this.name = "CursorCapacityError";
+  }
+};
+var CursorCreateOutcomeUnknownError = class extends Error {
+  constructor(cause) {
+    super("CursorCreateOutcomeUnknownError: Create Cursor \u306E\u6210\u5426\u3092\u78BA\u8A8D\u3067\u304D\u307E\u305B\u3093\u3002\u81EA\u52D5\u518D\u8A66\u884C\u305B\u305A\u3001\u6700\u592710\u5206+\u5B89\u5168\u4F59\u88D5\u306E\u9593\u306F\u67A0\u3092\u9694\u96E2\u3057\u307E\u3059\u3002");
+    this.name = "CursorCreateOutcomeUnknownError";
+    this.cause = cause;
+  }
+};
+var CursorCleanupWarning = class extends Error {
+  constructor(cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`CursorCleanupWarning: Cursor \u306E\u89E3\u653E\u3092\u78BA\u8A8D\u3067\u304D\u307E\u305B\u3093\u3002\u7D50\u679C\u306F\u6709\u52B9\u3067\u3059\u304C\u3001\u6700\u592710\u5206+\u5B89\u5168\u4F59\u88D5\u306E\u9593\u306F\u67A0\u3092\u9694\u96E2\u3057\u307E\u3059\u3002\u8A73\u7D30: ${detail}`);
+    this.name = "CursorCleanupWarning";
+    this.cause = cause;
+  }
+};
+
+// src/core/optimization/korderCursorExecutor.ts
+async function executeKorderCursor(input) {
+  const handle = await input.client.openCursor({
+    app: input.app,
+    fields: input.fields.length > 0 ? input.fields : void 0,
+    query: input.query,
+    size: 500
+  });
+  const records = [];
+  let seen = 0;
+  let primaryError;
+  let cleanupWarning;
+  try {
+    if (handle.totalCount > input.offset) {
+      while (records.length < input.limit) {
+        const page = await handle.nextPage();
+        for (const record of page.records) {
+          if (seen < input.offset) seen += 1;
+          else if (records.length < input.limit) records.push(record);
+          else break;
+        }
+        if (!page.next) break;
+      }
+    }
+  } catch (error) {
+    primaryError = error;
+    throw error;
+  } finally {
+    try {
+      await handle.close();
+    } catch (cleanupError) {
+      if (primaryError && primaryError instanceof Error) {
+        Object.defineProperty(primaryError, "cursorCleanupError", {
+          value: cleanupError,
+          configurable: true
+        });
+      } else {
+        cleanupWarning = new CursorCleanupWarning(cleanupError).message;
+      }
+    }
+  }
+  return { records, cleanupWarning };
+}
+
+// src/converter/korderCursorQuery.ts
+function buildKorderCursorQuery(stmt) {
+  const parts = [];
+  if (stmt.where) parts.push(whereToKintone(stmt.where));
+  const order = stmt.orderBy.map((item) => {
+    if (item.key.type !== "FIELD_NAME") {
+      throw new Error("ArgumentError: KORDER cursor key must be a direct field.");
+    }
+    return `${item.key.name} ${item.direction === "ASC" ? "asc" : "desc"}`;
+  });
+  parts.push(`order by ${order.join(", ")}`);
+  return parts.join(" ");
+}
+
 // src/engine/process.ts
 function flatten(record, alias) {
   const row = {};
@@ -6836,6 +6927,15 @@ function createEmptyMetrics() {
     fieldCalls: 0,
     appsCalls: 0,
     processStatusCalls: 0,
+    cursorCreateCalls: 0,
+    cursorGetCalls: 0,
+    cursorDeleteCalls: 0,
+    cursorRecordsScanned: 0,
+    cursorActiveCurrent: 0,
+    cursorActivePeak: 0,
+    cursorCleanupFailures: 0,
+    cursorCreateOutcomeUnknown: 0,
+    cursorQuarantinedCurrent: 0,
     fetchedRows: 0,
     elapsedMs: 0
   };
@@ -6848,6 +6948,48 @@ function wrapClientWithMetrics(client, metrics) {
       metrics.fetchedRows += res.records.length;
       return res;
     },
+    openCursor: async (params) => {
+      metrics.cursorCreateCalls += 1;
+      let handle;
+      try {
+        handle = await client.openCursor(params);
+      } catch (error) {
+        if (error instanceof Error && error.name === "CursorCreateOutcomeUnknownError") {
+          metrics.cursorCreateOutcomeUnknown += 1;
+          metrics.cursorQuarantinedCurrent += 1;
+        }
+        throw error;
+      }
+      metrics.cursorActiveCurrent += 1;
+      metrics.cursorActivePeak = Math.max(metrics.cursorActivePeak, metrics.cursorActiveCurrent);
+      let released = false;
+      const markReleased = () => {
+        if (released) return;
+        released = true;
+        metrics.cursorActiveCurrent -= 1;
+      };
+      return {
+        totalCount: handle.totalCount,
+        nextPage: async () => {
+          metrics.cursorGetCalls += 1;
+          const page = await handle.nextPage();
+          metrics.cursorRecordsScanned += page.records.length;
+          if (!page.next) markReleased();
+          return page;
+        },
+        close: async () => {
+          if (!released) metrics.cursorDeleteCalls += 1;
+          try {
+            await handle.close();
+            markReleased();
+          } catch (error) {
+            metrics.cursorCleanupFailures += 1;
+            metrics.cursorQuarantinedCurrent += 1;
+            throw error;
+          }
+        }
+      };
+    },
     postRecords: (params) => {
       metrics.postCalls += 1;
       return client.postRecords(params);
@@ -6887,6 +7029,37 @@ function wrapClientWithSearchAbort(client, collector, failClosed) {
     }
   };
 }
+function wrapClientWithCursorScope(client) {
+  const active = /* @__PURE__ */ new Set();
+  return {
+    client: {
+      ...client,
+      openCursor: async (params) => {
+        const handle = await client.openCursor(params);
+        active.add(handle);
+        const remove = () => active.delete(handle);
+        return {
+          totalCount: handle.totalCount,
+          async nextPage() {
+            const page = await handle.nextPage();
+            if (!page.next) remove();
+            return page;
+          },
+          async close() {
+            try {
+              await handle.close();
+            } finally {
+              remove();
+            }
+          }
+        };
+      }
+    },
+    closeActive: async () => {
+      await Promise.all([...active].map((handle) => handle.close().catch(() => void 0)));
+    }
+  };
+}
 function isSelectLikeStatement(stmt) {
   return stmt.type === "SELECT" || stmt.type === "UNION" || stmt.type === "WITH";
 }
@@ -6937,7 +7110,13 @@ async function executeParsedStatement(stmt, client, options, cacheContext) {
     case "DESCRIBE":
       return executeDescribe(stmt, client, cacheContext);
     case "EXPLAIN":
-      return executeExplain(stmt, client, cacheContext, options.maxRecords ?? 1e4);
+      return executeExplain(
+        stmt,
+        client,
+        cacheContext,
+        options.maxRecords ?? 1e4,
+        options.cursorMaxActive ?? 2
+      );
     // 一時テーブルはバッチスコープのため単文実行では拒否する（executeBatch を使う）
     case "CREATE_TEMP_TABLE":
       throw new Error("ArgumentError: CREATE TEMP TABLE requires a batch (temp tables are batch-scoped).");
@@ -7044,9 +7223,11 @@ async function executeBatch(sql, client, options = {}) {
         searchAbortCollector,
         info.statementType !== "SELECT" && info.statementType !== "UNION" && info.statementType !== "WITH"
       );
+      const cursorScope = wrapClientWithCursorScope(statementClient);
       const outcome = await runWithDeadline(
-        executeBatchStatement(statements[i], info, statementClient, stmtOptions, cacheContext, tempTables, variables),
-        remaining
+        executeBatchStatement(statements[i], info, cursorScope.client, stmtOptions, cacheContext, tempTables, variables),
+        remaining,
+        cursorScope.closeActive
       );
       if (outcome.result) {
         outcome.result = attachSearchAbortWarning(outcome.result, searchAbortCollector);
@@ -7204,19 +7385,47 @@ async function runSelectLike(query, client, options, cacheContext, tempTables) {
   }
   return executeQueryWithCte(query, client, options, tempTables, cacheContext, true);
 }
-async function runWithDeadline(work, remainingMs) {
+async function runWithDeadline(work, remainingMs, onTimeout) {
   if (remainingMs === null) return work;
   if (remainingMs <= 0) {
+    if (onTimeout) await onTimeout();
     void work.catch(() => {
     });
     throw new BatchTimeoutError();
   }
   let timer;
+  let timedOut = false;
+  const guardedWork = work.then(
+    (value) => timedOut ? new Promise(() => void 0) : value,
+    (error) => {
+      if (timedOut) return new Promise(() => void 0);
+      throw error;
+    }
+  );
   try {
     return await Promise.race([
-      work,
+      guardedWork,
       new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new BatchTimeoutError()), remainingMs);
+        timer = setTimeout(() => {
+          timedOut = true;
+          void (async () => {
+            if (onTimeout) {
+              let cleanupTimer;
+              try {
+                await Promise.race([
+                  onTimeout(),
+                  new Promise((resolve2) => {
+                    cleanupTimer = setTimeout(resolve2, 5e3);
+                    cleanupTimer.unref?.();
+                  })
+                ]);
+              } finally {
+                if (cleanupTimer) clearTimeout(cleanupTimer);
+              }
+            }
+            reject(new BatchTimeoutError());
+          })();
+        }, remainingMs);
       })
     ]);
   } catch (e) {
@@ -7576,7 +7785,7 @@ async function executeSelect(stmt, client, options, cacheContext, cteCache, capt
   const staticMode = resolveSelectMode(stmt);
   const mode = whereCapability.capability === "EXACT_PUSHDOWN" ? staticMode : "FULL_SCAN";
   const orderMeta = await buildOrderByMetaForSelect(stmt, client, cacheContext, cteCache);
-  const orderPlan = hasCanonicalOrder(stmt) ? (stmt.orderMode === "KINTONE_NATIVE" ? planKorderNative : planCanonicalOrder)({
+  const orderPlan = hasCanonicalOrder(stmt) ? (stmt.orderMode === "KINTONE_NATIVE" ? planKorder : planCanonicalOrder)({
     stmt,
     staticMode: mode,
     whereCapability: whereCapability.capability,
@@ -7590,7 +7799,7 @@ async function executeSelect(stmt, client, options, cacheContext, cteCache, capt
     client,
     cacheContext
   );
-  const completeInputRequired = orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" ? requiresCompleteInput({ ...stmt, orderBy: [] }) : requiresCompleteInput(stmt);
+  const completeInputRequired = orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" || orderPlan?.kind === "KORDER_CURSOR" ? requiresCompleteInput({ ...stmt, orderBy: [] }) : requiresCompleteInput(stmt);
   const truncateWasDisabled = completeInputRequired && options.onLimitReached === "truncate";
   const effectiveOptions = truncateWasDisabled ? { ...options, onLimitReached: "error" } : options;
   try {
@@ -7691,12 +7900,23 @@ async function executeSimpleSelect(stmt, client, options, cacheContext, orderPla
   const warnings = /* @__PURE__ */ new Set();
   const onLimit = options.onLimitReached ?? "error";
   const parallel = options.fetchParallel ?? 1;
-  const useRestWindow = stmt.orderBy.length > 0 ? orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" : stmt.limit !== null && stmt.limit <= 500;
+  const useRestWindow = stmt.orderBy.length > 0 ? orderPlan?.kind === "CANONICAL_REST_TOP_N" || orderPlan?.kind === "KORDER_NATIVE" || orderPlan?.kind === "KORDER_CURSOR" : stmt.limit !== null && stmt.limit <= 500;
   const needed = stmt.limit === null ? null : (stmt.offset ?? 0) + stmt.limit;
   const stopAfter = stmt.orderBy.length === 0 && needed !== null && needed <= maxRecords && !whereHasKlike(stmt.where) ? needed : void 0;
   let records;
-  if (orderPlan?.kind === "KORDER_NATIVE" && stmt.limit === 0) {
+  if ((orderPlan?.kind === "KORDER_NATIVE" || orderPlan?.kind === "KORDER_CURSOR") && stmt.limit === 0) {
     records = [];
+  } else if (orderPlan?.kind === "KORDER_CURSOR") {
+    const cursorResult = await executeKorderCursor({
+      client,
+      app: params.app,
+      fields: params.fields,
+      query: buildKorderCursorQuery(stmt),
+      offset: stmt.offset ?? 0,
+      limit: stmt.limit
+    });
+    records = cursorResult.records;
+    if (cursorResult.cleanupWarning) warnings.add(cursorResult.cleanupWarning);
   } else if (useRestWindow) {
     const res = await client.getRecords({
       app: params.app,
@@ -8488,7 +8708,7 @@ async function executeFullScanWithCte(stmt, client, options, cteCache, cacheCont
   }
   const orderMeta = await buildOrderByMetaForSelect(stmt, client, cacheContext, cteCache);
   if (hasCanonicalOrder(stmt)) {
-    (stmt.orderMode === "KINTONE_NATIVE" ? planKorderNative : planCanonicalOrder)({
+    (stmt.orderMode === "KINTONE_NATIVE" ? planKorder : planCanonicalOrder)({
       stmt,
       staticMode: "FULL_SCAN",
       whereCapability: whereCapability.capability,
@@ -10265,7 +10485,7 @@ async function buildExplainWhereAnalysis(query, client, cacheContext, maxRecords
         const hasUnmaterializedSource = [select.from, ...select.joins.map((join2) => join2.table)].some((table) => table.cteName !== null);
         if (hasCanonicalOrder(select) && !hasUnmaterializedSource) {
           const mode = capability.capability === "EXACT_PUSHDOWN" ? resolveSelectMode(select) : "FULL_SCAN";
-          orderPlans.set(select, (select.orderMode === "KINTONE_NATIVE" ? planKorderNative : planCanonicalOrder)({
+          orderPlans.set(select, (select.orderMode === "KINTONE_NATIVE" ? planKorder : planCanonicalOrder)({
             stmt: select,
             staticMode: mode,
             whereCapability: capability.capability,
@@ -10295,7 +10515,7 @@ async function buildExplainWhereAnalysis(query, client, cacheContext, maxRecords
     capabilities.set(inlined, capability);
     if (hasCanonicalOrder(inlined)) {
       const meta = await buildOrderByMetaForSelect(inlined, tracedClient, cacheContext);
-      orderPlans.set(inlined, (inlined.orderMode === "KINTONE_NATIVE" ? planKorderNative : planCanonicalOrder)({
+      orderPlans.set(inlined, (inlined.orderMode === "KINTONE_NATIVE" ? planKorder : planCanonicalOrder)({
         stmt: inlined,
         staticMode: capability.capability === "EXACT_PUSHDOWN" ? resolveSelectMode(inlined) : "FULL_SCAN",
         whereCapability: capability.capability,
@@ -10313,7 +10533,7 @@ function explainMetadataLines(analysis) {
     ...[...analysis.processStatusApps].sort((a, b) => a - b).map((appId) => `  metadata API: process status APP${appId}`)
   ];
 }
-async function buildBatchExplainPlans(sql, client, injectedVariables, cacheContext = "batch-explain", maxRecords = 1e4) {
+async function buildBatchExplainPlans(sql, client, injectedVariables, cacheContext = "batch-explain", maxRecords = 1e4, cursorMaxActive = 2) {
   const statements = parseSqlBatch(sql);
   const analysis = analyzeBatch(statements);
   validateDeclaredBatchVariables(statements, injectedVariables);
@@ -10324,12 +10544,12 @@ async function buildBatchExplainPlans(sql, client, injectedVariables, cacheConte
     const planStmt = stmt.type === "SET_VARIABLE" ? stmt.expr.type === "SCALAR_SUBQUERY" ? { ...stmt, expr: resolveVariableRefs(stmt.expr, variables) } : stmt : resolveVariableRefs(stmt, variables);
     validateKlikeStatement(planStmt);
     const whereAnalysis = await buildExplainWhereAnalysis(planStmt, client, cacheContext, maxRecords);
-    const statementPlan = buildBatchStatementPlan(
+    const statementPlan = addCursorConcurrency(buildBatchStatementPlan(
       planStmt,
       analysis.statements[i],
       whereAnalysis.capabilities,
       whereAnalysis.orderPlans
-    );
+    ), cursorMaxActive);
     const metadataPlan = explainMetadataLines(whereAnalysis);
     plans.push({
       index: i,
@@ -10435,11 +10655,14 @@ function buildPlanForBatchQuery(query, info, capabilities, orderPlans) {
   lines.push("  note:          \u4E00\u6642\u30C6\u30FC\u30D6\u30EB\u3078\u306E WHERE \u30D7\u30C3\u30B7\u30E5\u30C0\u30A6\u30F3\u306F\u884C\u308F\u308C\u306A\u3044");
   return lines;
 }
-async function executeExplain(stmt, client, cacheContext, maxRecords) {
+async function executeExplain(stmt, client, cacheContext, maxRecords, cursorMaxActive) {
   const analysis = await buildExplainWhereAnalysis(stmt.query, client, cacheContext, maxRecords);
   const lines = [
     ...explainMetadataLines(analysis),
-    ...buildExplainPlan(stmt.query, void 0, analysis.capabilities, analysis.orderPlans)
+    ...addCursorConcurrency(
+      buildExplainPlan(stmt.query, void 0, analysis.capabilities, analysis.orderPlans),
+      cursorMaxActive
+    )
   ];
   return {
     type: "SELECT",
@@ -10448,6 +10671,17 @@ async function executeExplain(stmt, client, cacheContext, maxRecords) {
     rowCount: lines.length
   };
 }
+function addCursorConcurrency(lines, cursorMaxActive) {
+  const result = [];
+  for (const line of lines) {
+    result.push(line);
+    if (line.trim() === "cursor page size: 500") {
+      const indent = line.match(/^\s*/)?.[0] ?? "";
+      result.push(`${indent}cursor concurrency: ${cursorMaxActive} per domain (process-local)`);
+    }
+  }
+  return result;
+}
 function buildExplainPlan(query, label, capabilities, orderPlans) {
   if (query.type === "UNION") return buildUnionPlan(query, capabilities, orderPlans);
   if (query.type === "WITH") return buildWithPlan(query, capabilities, orderPlans);
@@ -10477,6 +10711,11 @@ function buildSelectPlan(stmt, label, capabilities, orderPlans) {
     if (orderPlan.kind === "KORDER_NATIVE") {
       lines.push("  order semantics: kintone native (not kSQL canonical)");
       lines.push("  REST execution: single GET");
+    } else if (orderPlan.kind === "KORDER_CURSOR") {
+      lines.push("  order semantics: kintone native (not kSQL canonical)");
+      lines.push("  fetch API: POST/GET/DELETE records/cursor.json");
+      lines.push("  cursor page size: 500");
+      lines.push(`  scan rows:     ${orderPlan.scanRows}`);
     }
   }
   if (orderPlan?.requiresCompleteInput ?? requiresCompleteInput(stmt)) {
@@ -10488,7 +10727,8 @@ function buildSelectPlan(stmt, label, capabilities, orderPlans) {
   if (mode === "SIMPLE") {
     const params = selectToKintoneParams(orderPlan?.kind === "CANONICAL_REST_TOP_N" ? withCanonicalRestTie(stmt) : stmt);
     lines.push(`  app:           APP${stmt.from.appId} (${stmt.from.appId})`);
-    lines.push(`  kintone query: ${params.query || "(\u306A\u3057)"}`);
+    const displayedQuery = orderPlan?.kind === "KORDER_CURSOR" ? buildKorderCursorQuery(stmt) : params.query;
+    lines.push(`  kintone query: ${displayedQuery || "(\u306A\u3057)"}`);
     lines.push(`  fields:        ${params.fields.length === 0 ? "(\u5168\u30D5\u30A3\u30FC\u30EB\u30C9)" : params.fields.join(", ")}`);
   } else {
     const pushdownPlan = buildKlikePushdownPlan(stmt);
@@ -11056,6 +11296,12 @@ function validateKsqlConfig(config) {
     }
     const logicalApps = normalizeLogicalApps(profileName, profile.logicalApps);
     if (logicalApps !== void 0) profile.logicalApps = logicalApps;
+    if (profile.query?.cursorMaxActive !== void 0) {
+      const value = profile.query.cursorMaxActive;
+      if (!Number.isSafeInteger(value) || value < 1 || value > 5) {
+        throw argumentError(`query.cursorMaxActive for profile "${profileName}" must be an integer from 1 to 5.`);
+      }
+    }
   }
   return config;
 }
@@ -11200,6 +11446,10 @@ var RequestGate = class {
   async runMutation(fn) {
     return this.withSlot(fn);
   }
+  /** Cursor Create/Get/Delete: セマフォのみ。GETでも位置を進めるため再試行しない。 */
+  async runCursorStep(fn) {
+    return this.withSlot(fn);
+  }
   async withSlot(fn) {
     await this.acquire();
     try {
@@ -11231,6 +11481,14 @@ var RequestGate = class {
 function withRequestGate(client, gate) {
   return {
     getRecords: (params) => gate.runReadOnly(() => client.getRecords(params)),
+    openCursor: async (params) => {
+      const handle = await gate.runCursorStep(() => client.openCursor(params));
+      return {
+        totalCount: handle.totalCount,
+        nextPage: () => gate.runCursorStep(() => handle.nextPage()),
+        close: () => gate.runCursorStep(() => handle.close())
+      };
+    },
     getApps: () => gate.runReadOnly(() => client.getApps()),
     getFields: (appId) => gate.runReadOnly(() => client.getFields(appId)),
     getProcessStatuses: (appId) => gate.runReadOnly(() => client.getProcessStatuses(appId)),
@@ -11345,7 +11603,218 @@ function normalizeProcessStatusStates(states) {
   });
 }
 
+// src/api/kintoneCursor.ts
+function isAlreadyReleasedCursorError(error) {
+  const shaped = error;
+  return shaped?.status === 404 && shaped.code === "GAIA_CN01";
+}
+async function deleteCursorWithConfirmation(deleteCursor, sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)), isAlreadyReleased = isAlreadyReleasedCursorError) {
+  try {
+    await deleteCursor();
+    return;
+  } catch (firstError) {
+    if (isAlreadyReleased(firstError)) return;
+  }
+  await sleep(250);
+  try {
+    await deleteCursor();
+  } catch (confirmationError) {
+    if (isAlreadyReleased(confirmationError)) return;
+    throw confirmationError;
+  }
+}
+async function withTimeout(promise, timeoutMs) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`CursorCleanupTimeoutError: cleanup exceeded ${timeoutMs}ms.`)), timeoutMs);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+function createKintoneCursorHandle(totalCount, operations) {
+  let released = false;
+  let closing = false;
+  let pageTail = Promise.resolve();
+  let closePromise = null;
+  const nextPage = () => {
+    if (closing || released) return Promise.resolve({ records: [], next: false });
+    const result = pageTail.then(async () => {
+      if (closing || released) return { records: [], next: false };
+      const page = await operations.get();
+      if (!page.next) {
+        released = true;
+        operations.onReleased?.();
+      }
+      return page;
+    });
+    pageTail = result.then(() => void 0, () => void 0);
+    return result;
+  };
+  const close = () => {
+    if (released) return Promise.resolve();
+    if (closePromise) return closePromise;
+    closing = true;
+    closePromise = pageTail.then(async () => {
+      if (released) return;
+      try {
+        await withTimeout(
+          deleteCursorWithConfirmation(
+            operations.delete,
+            operations.sleep,
+            operations.isAlreadyReleasedError
+          ),
+          operations.cleanupTimeoutMs ?? 5e3
+        );
+        released = true;
+        operations.onReleased?.();
+      } catch (error) {
+        operations.onReleaseUnknown?.();
+        throw error;
+      }
+    });
+    return closePromise;
+  };
+  return { totalCount, nextPage, close };
+}
+
+// src/api/cursorLeaseManager.ts
+var DEFAULT_MAX_ACTIVE = 2;
+var MAX_ACTIVE = 5;
+var DEFAULT_WAIT_MS = 3e4;
+var DEFAULT_QUARANTINE_MS = 10 * 6e4 + 3e4;
+var CursorLeaseManager = class {
+  constructor(host, options = {}) {
+    this.host = host;
+    this.active = 0;
+    this.peak = 0;
+    this.quarantined = 0;
+    this.waiters = [];
+    this.createTail = Promise.resolve();
+    const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
+    if (!Number.isSafeInteger(maxActive) || maxActive < 1 || maxActive > MAX_ACTIVE) {
+      throw new Error(`ArgumentError: cursorMaxActive must be an integer from 1 to ${MAX_ACTIVE}.`);
+    }
+    this.maxActive = maxActive;
+    this.waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_MS;
+    this.quarantineMs = options.quarantineMs ?? DEFAULT_QUARANTINE_MS;
+  }
+  acquire() {
+    if (this.active < this.maxActive) {
+      this.active += 1;
+      this.peak = Math.max(this.peak, this.active);
+      return Promise.resolve(this.makeLease());
+    }
+    return new Promise((resolve2, reject) => {
+      const waiter = {};
+      waiter.resolve = resolve2;
+      waiter.reject = reject;
+      waiter.timer = setTimeout(() => {
+        const index = this.waiters.indexOf(waiter);
+        if (index >= 0) this.waiters.splice(index, 1);
+        reject(new CursorCapacityError(this.host, this.maxActive, this.waitTimeoutMs));
+      }, this.waitTimeoutMs);
+      waiter.timer.unref?.();
+      this.waiters.push(waiter);
+    });
+  }
+  /**
+   * 同一hostを共有する後続surfaceの設定を反映する。
+   * 縮小時は既存leaseを強制終了せず、activeが新上限を下回るまで新規取得だけを止める。
+   */
+  setMaxActive(maxActive) {
+    this.validateMaxActive(maxActive);
+    if (this.maxActive === maxActive) return;
+    this.maxActive = maxActive;
+    this.dispatchWaiters();
+  }
+  async runCreate(fn) {
+    const previous = this.createTail;
+    let unlock;
+    this.createTail = new Promise((resolve2) => {
+      unlock = resolve2;
+    });
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      unlock();
+    }
+  }
+  snapshot() {
+    return {
+      active: this.active,
+      peak: this.peak,
+      quarantined: this.quarantined,
+      waiting: this.waiters.length,
+      limit: this.maxActive
+    };
+  }
+  makeLease() {
+    let done = false;
+    return {
+      release: () => {
+        if (done) return;
+        done = true;
+        this.returnPermit();
+      },
+      quarantine: (durationMs = this.quarantineMs) => {
+        if (done) return;
+        done = true;
+        this.quarantined += 1;
+        const timer = setTimeout(() => {
+          this.quarantined -= 1;
+          this.returnPermit();
+        }, durationMs);
+        timer.unref?.();
+      }
+    };
+  }
+  returnPermit() {
+    this.active -= 1;
+    this.dispatchWaiters();
+  }
+  dispatchWaiters() {
+    while (this.active < this.maxActive) {
+      const waiter = this.waiters.shift();
+      if (!waiter) return;
+      clearTimeout(waiter.timer);
+      this.active += 1;
+      this.peak = Math.max(this.peak, this.active);
+      waiter.resolve(this.makeLease());
+    }
+  }
+  validateMaxActive(maxActive) {
+    if (!Number.isSafeInteger(maxActive) || maxActive < 1 || maxActive > MAX_ACTIVE) {
+      throw new Error(`ArgumentError: cursorMaxActive must be an integer from 1 to ${MAX_ACTIVE}.`);
+    }
+  }
+};
+var managers = /* @__PURE__ */ new Map();
+function getCursorLeaseManager(host, maxActive = DEFAULT_MAX_ACTIVE) {
+  const key = host.toLowerCase();
+  let manager = managers.get(key);
+  if (!manager) {
+    manager = new CursorLeaseManager(key, { maxActive });
+    managers.set(key, manager);
+  } else {
+    manager.setMaxActive(maxActive);
+  }
+  return manager;
+}
+
 // src/cli/nodeKintoneClient.ts
+var KintoneApiError = class extends Error {
+  constructor(status, code, bodyText) {
+    super(`kintone API error ${status}: ${bodyText}`);
+    this.status = status;
+    this.code = code;
+    this.name = "KintoneApiError";
+  }
+};
 var SEARCH_ABORTED_HEADER_VALUE = "Filter aborted because of too many search results";
 function createNodeKintoneClient(baseUrl, tokenResolver) {
   const normalizedBaseUrl = baseUrl.replace(/\/+$/, "");
@@ -11393,7 +11862,13 @@ function createNodeKintoneClient(baseUrl, tokenResolver) {
       if (tokenResolver.debug) {
         tokenResolver.log?.(`[debug] response status=${res.status} body=${bodyText}`);
       }
-      throw new Error(`kintone API error ${res.status}: ${bodyText}`);
+      let code;
+      try {
+        const body = JSON.parse(bodyText);
+        if (typeof body.code === "string") code = body.code;
+      } catch {
+      }
+      throw new KintoneApiError(res.status, code, bodyText);
     }
     if (tokenResolver.debug) {
       tokenResolver.log?.(`[debug] response status=${res.status}`);
@@ -11460,6 +11935,48 @@ function createNodeKintoneClient(baseUrl, tokenResolver) {
         return response.searchAborted ? { ...response.body, searchAborted: true } : response.body;
       }
     },
+    async openCursor(params) {
+      const manager = getCursorLeaseManager(new URL(normalizedBaseUrl).host, tokenResolver.cursorMaxActive);
+      const lease = await manager.acquire();
+      let created;
+      try {
+        created = await manager.runCreate(() => requestJson(
+          `${apiBasePath}/records/cursor.json`,
+          {
+            method: "POST",
+            body: JSON.stringify({
+              app: params.app,
+              query: params.query,
+              size: params.size,
+              fields: params.fields && params.fields.length > 0 ? params.fields : void 0
+            })
+          },
+          params.app
+        ));
+      } catch (error) {
+        if (error instanceof KintoneApiError) {
+          lease.release();
+          throw error;
+        }
+        lease.quarantine();
+        throw new CursorCreateOutcomeUnknownError(error);
+      }
+      const cursorId = created.id;
+      return createKintoneCursorHandle(Number(created.totalCount), {
+        get: () => requestJson(
+          `${apiBasePath}/records/cursor.json?id=${encodeURIComponent(cursorId)}`,
+          { method: "GET" },
+          params.app
+        ),
+        delete: () => requestJson(
+          `${apiBasePath}/records/cursor.json`,
+          { method: "DELETE", body: JSON.stringify({ id: cursorId }) },
+          params.app
+        ),
+        onReleased: () => lease.release(),
+        onReleaseUnknown: () => lease.quarantine()
+      });
+    },
     async postRecords(_params) {
       const res = await requestJson(
         `${apiBasePath}/records.json`,
@@ -12017,6 +12534,7 @@ Options:
   --timeout <ms>             Request timeout in milliseconds (default: 30000)
   --max-concurrent <n>       Max concurrent kintone requests: 1-50 (default: 10)
                              (process-wide; fixed at first resolution; KSQL_MAX_CONCURRENT wins)
+  --cursor-max-active <n>    Max active cursors per host: 1-5 (default: 2; KSQL_CURSOR_MAX_ACTIVE wins)
   --retry <n>                GET retry count: 0-10, 0 disables (default: 3; KSQL_RETRY wins)
   --retry-base-delay <ms>    GET retry backoff base delay (default: 500)
   --retry-max-delay <ms>     GET retry backoff max delay (default: 8000)
@@ -12097,6 +12615,7 @@ function parseArgs(argv) {
     continueOnError: false,
     dmlMaxRows: null,
     maxConcurrent: null,
+    cursorMaxActive: null,
     retry: null,
     retryBaseDelay: null,
     retryMaxDelay: null,
@@ -12353,6 +12872,13 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (a === "--cursor-max-active") {
+      const n = Number(v);
+      if (!Number.isInteger(n) || n < 1 || n > 5) throw new Error("ArgumentError: --cursor-max-active must be an integer between 1 and 5.");
+      out.cursorMaxActive = n;
+      i++;
+      continue;
+    }
     if (a === "--retry") {
       const n = Number(v);
       if (!Number.isInteger(n) || n < 0 || n > 10) throw new Error("ArgumentError: --retry must be an integer between 0 and 10 (0 disables retry).");
@@ -12648,6 +13174,7 @@ function createDryRunClient() {
   };
   return {
     getRecords: notUsed,
+    openCursor: notUsed,
     postRecords: notUsed,
     putRecords: notUsed,
     deleteRecords: notUsed,
@@ -12790,6 +13317,7 @@ function buildReplExecArgv(base, sql, dryRun, format) {
   pushOpt(argv, "--attachment-format", base.attachmentFormat);
   pushOpt(argv, "--dml-max-rows", base.dmlMaxRows);
   pushOpt(argv, "--max-concurrent", base.maxConcurrent);
+  pushOpt(argv, "--cursor-max-active", base.cursorMaxActive);
   pushOpt(argv, "--retry", base.retry);
   pushOpt(argv, "--retry-base-delay", base.retryBaseDelay);
   pushOpt(argv, "--retry-max-delay", base.retryMaxDelay);
@@ -13357,6 +13885,11 @@ async function run() {
   const onLimit = args.onLimit ?? envOnLimit2("KSQL_ON_LIMIT") ?? profile.query?.onLimit ?? "error";
   const timeout = args.timeout ?? envInt2("KSQL_TIMEOUT") ?? profile.query?.timeout ?? 3e4;
   const tempTableMaxRows = args.tempTableMaxRows ?? envInt2("KSQL_TEMP_TABLE_MAX_ROWS") ?? profile.query?.tempTableMaxRows ?? void 0;
+  const cursorMaxActive = args.cursorMaxActive ?? envInt2("KSQL_CURSOR_MAX_ACTIVE") ?? profile.query?.cursorMaxActive ?? 2;
+  if (!Number.isSafeInteger(cursorMaxActive) || cursorMaxActive < 1 || cursorMaxActive > 5) {
+    process.stderr.write("ArgumentError: cursorMaxActive must be an integer from 1 to 5.\n");
+    return 2;
+  }
   if (!Number.isInteger(fetchParallel) || fetchParallel < 1 || fetchParallel > 10) {
     process.stderr.write("ArgumentError: fetch-parallel must be an integer between 1 and 10.\n");
     return 2;
@@ -13487,6 +14020,7 @@ async function run() {
         }
         profileClientMap.set(pName, createNodeKintoneClient(baseUrl, {
           guestSpaceId,
+          cursorMaxActive,
           timeoutMs: timeout,
           debug,
           debugHeaders,
@@ -13519,6 +14053,7 @@ async function run() {
       missingAppProfiles.push(...resolvedTokens.missing);
       profileClientMap.set(pName, createNodeKintoneClient(baseUrl, {
         guestSpaceId,
+        cursorMaxActive,
         timeoutMs: timeout,
         debug,
         debugHeaders,
@@ -13630,6 +14165,12 @@ async function run() {
         if (!routed) throw new Error(`AuthError: profile "${pName}" is not resolved for APP${params.app}.`);
         return routed.getRecords({ ...params, app: binding.appId });
       },
+      openCursor: (params) => {
+        const binding = appBindingByMappedApp.get(params.app) ?? { appId: params.app, profile: profileName.toLowerCase() };
+        const routed = profileClientMap.get(binding.profile);
+        if (!routed) throw new Error(`AuthError: profile "${binding.profile}" is not resolved for APP${params.app}.`);
+        return routed.openCursor({ ...params, app: binding.appId });
+      },
       postRecords: (params) => {
         const binding = appBindingByMappedApp.get(params.app) ?? { appId: params.app, profile: profileName.toLowerCase() };
         const pName = binding.profile;
@@ -13678,7 +14219,14 @@ async function run() {
   }
   if (isBatchSql && args.dryRun) {
     try {
-      const plans = await buildBatchExplainPlans(sql, client, args.variables, cacheContext, maxRecords);
+      const plans = await buildBatchExplainPlans(
+        sql,
+        client,
+        args.variables,
+        cacheContext,
+        maxRecords,
+        cursorMaxActive
+      );
       const out = [];
       const restoredStatements = sqlDiagnosticContext ? restoreSqlDiagnosticValue(plans.statements, sqlDiagnosticContext.appBindingByMappedApp) : plans.statements;
       restoredStatements.forEach((p) => {
@@ -13742,6 +14290,7 @@ query=${label}`);
         continueOnError: args.continueOnError,
         tempTableMaxRows,
         timeoutMs: timeout,
+        cursorMaxActive,
         variables: args.variables,
         confirm: batchContainsDml ? async (count, operation) => {
           if (count > dmlMaxRows) {
@@ -13752,12 +14301,18 @@ query=${label}`);
       });
       return writeBatchOutput(batchResult, { format, noHeader, pretty, displayOptions, outputPath, quiet });
     }
-    let result = args.dryRun ? await execute(`EXPLAIN ${sql}`, client, { maxRecords, onLimitReached: onLimit, cacheContext }) : await execute(sql, client, {
+    let result = args.dryRun ? await execute(`EXPLAIN ${sql}`, client, {
+      maxRecords,
+      onLimitReached: onLimit,
+      cacheContext,
+      cursorMaxActive
+    }) : await execute(sql, client, {
       maxRecords,
       fetchParallel,
       onLimitReached: effectiveOnLimit,
       confirm: isDmlStatement ? confirm : void 0,
-      cacheContext
+      cacheContext,
+      cursorMaxActive
     });
     if (args.dryRun && sqlDiagnosticContext) {
       result = restoreSqlDiagnosticValue(result, sqlDiagnosticContext.appBindingByMappedApp);