@tinycloud/operations 0.1.0 → 0.2.0-beta.0

package/dist/cli-runtime.js

@@ -86,6 +86,14 @@ var init_errors = __esm({
       "ENCRYPTION_NETWORK_UNRESOLVED",
       "NODE_UNREACHABLE",
       "NODE_ERROR",
+      "KV_NOT_FOUND",
+      "KV_PRECONDITION_FAILED",
+      "KV_CONFLICT",
+      "KV_RESPONSE_TOO_LARGE",
+      "SQL_QUERY_INVALID",
+      "SQL_EXECUTION_FAILED",
+      "SQL_RESULT_LIMIT_EXCEEDED",
+      "SQL_VALUE_UNSAFE",
       "SECRET_READ_FAILED",
       "SECRET_DECRYPT_FAILED",
       "OUTPUT_INVALID",
@@ -1134,6 +1142,11 @@ function validateMigrationOptions(options) {
   }
   return null;
 }
+function serializeSqlValues(values) {
+  return values.map(
+    (value) => value instanceof Uint8Array ? Array.from(value) : value
+  );
+}
 function migrationKey(namespace, id) {
   return `${encodeURIComponent(namespace)}:${encodeURIComponent(id)}`;
 }
@@ -2406,6 +2419,9 @@ var init_dist2 = __esm({
       // KV-specific errors
       KV_NOT_FOUND: "KV_NOT_FOUND",
       KV_WRITE_FAILED: "KV_WRITE_FAILED",
+      KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
+      KV_CONFLICT: "KV_CONFLICT",
+      KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
       // SQL-specific errors
       SQL_ERROR: "SQL_ERROR",
       SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -3083,7 +3099,7 @@ var init_dist2 = __esm({
        * @param signal - Optional abort signal
        * @returns Fetch response
        */
-      async invokeOperation(path, action, body, signal) {
+      async invokeOperation(path, action, body, signal, extraHeaders) {
         const session = this.context.session;
         const headers = this.context.invoke(
           session,
@@ -3091,9 +3107,10 @@ var init_dist2 = __esm({
           path,
           action
         );
+        const requestHeaders = Array.isArray(headers) ? [...headers, ...Object.entries(extraHeaders ?? {})] : { ...headers, ...extraHeaders };
         return this.context.fetch(`${this.host}/invoke`, {
           method: "POST",
-          headers,
+          headers: requestHeaders,
           body,
           signal: this.combineSignals(signal)
         });
@@ -3275,13 +3292,21 @@ var init_dist2 = __esm({
           if (!this.requireAuth()) {
             return err(authRequiredError("kv"));
           }
+          if (options?.maxResponseBytes !== void 0 && (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0)) {
+            return err(serviceError(
+              ErrorCodes.INVALID_INPUT,
+              "KV maxResponseBytes must be a positive safe integer",
+              "kv"
+            ));
+          }
           const path = this.getFullPath(key, options?.prefix);
           try {
             const response = await this.invokeOperation(
               path,
               KVAction.GET,
               void 0,
-              options?.signal
+              options?.signal,
+              options?.maxResponseBytes === void 0 ? void 0 : { "x-tinycloud-max-response-bytes": String(options.maxResponseBytes) }
             );
             if (!response.ok) {
               if (response.status === 401 || response.status === 403) {
@@ -3299,6 +3324,14 @@ var init_dist2 = __esm({
                 return this.classifyNotFound(response, key);
               }
               const errorText = await response.text();
+              if (response.status === 413) {
+                return err(serviceError(
+                  ErrorCodes.KV_RESPONSE_TOO_LARGE,
+                  `KV value at key "${key}" exceeds the requested response limit`,
+                  "kv",
+                  { meta: { status: response.status, statusText: response.statusText } }
+                ));
+              }
               return err(
                 serviceError(
                   ErrorCodes.NETWORK_ERROR,
@@ -3330,6 +3363,13 @@ var init_dist2 = __esm({
           if (!this.requireAuth()) {
             return err(authRequiredError("kv"));
           }
+          if (options?.ifMatch !== void 0 && options.ifNoneMatch !== void 0) {
+            return err(serviceError(
+              ErrorCodes.INVALID_INPUT,
+              "KV put cannot combine ifMatch and ifNoneMatch",
+              "kv"
+            ));
+          }
           const path = this.getFullPath(key, options?.prefix);
           const body = this.serializePutValue(value, options?.contentType);
           try {
@@ -3337,7 +3377,11 @@ var init_dist2 = __esm({
               path,
               KVAction.PUT,
               body,
-              options?.signal
+              options?.signal,
+              {
+                ...options?.ifMatch === void 0 ? {} : { "if-match": options.ifMatch },
+                ...options?.ifNoneMatch === void 0 ? {} : { "if-none-match": options.ifNoneMatch }
+              }
             );
             if (!response.ok) {
               if (response.status === 401) {
@@ -3350,6 +3394,22 @@ var init_dist2 = __esm({
                 }));
               }
               const errorText = await response.text();
+              if (response.status === 412) {
+                return err(serviceError(
+                  ErrorCodes.KV_PRECONDITION_FAILED,
+                  `KV precondition failed for key "${key}"`,
+                  "kv",
+                  { meta: { status: response.status, statusText: response.statusText } }
+                ));
+              }
+              if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
+                return err(serviceError(
+                  ErrorCodes.KV_CONFLICT,
+                  `Concurrent KV update conflicted for key "${key}"`,
+                  "kv",
+                  { meta: { status: response.status, statusText: response.statusText } }
+                ));
+              }
               const quotaError = this.handleQuotaErrorResponse(
                 response,
                 errorText,
@@ -3485,6 +3545,13 @@ var init_dist2 = __esm({
           if (!this.requireAuth()) {
             return err(authRequiredError("kv"));
           }
+          if (options?.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1e3)) {
+            return err(serviceError(
+              ErrorCodes.INVALID_INPUT,
+              "KV list limit must be an integer from 1 through 1000",
+              "kv"
+            ));
+          }
           let listPath = options?.prefix ?? this._config.prefix ?? "";
           if (options?.path) {
             listPath = listPath ? `${listPath}/${options.path}` : options.path;
@@ -3494,7 +3561,8 @@ var init_dist2 = __esm({
               listPath,
               KVAction.LIST,
               void 0,
-              options?.signal
+              options?.signal,
+              options?.limit === void 0 ? void 0 : { "x-tinycloud-limit": String(options.limit) }
             );
             if (!response.ok) {
               if (response.status === 401) {
@@ -3524,7 +3592,10 @@ var init_dist2 = __esm({
                 (key) => key.startsWith(prefixWithSlash) ? key.slice(prefixWithSlash.length) : key
               );
             }
-            return ok({ keys });
+            return ok({
+              keys,
+              ...response.headers.get("x-tinycloud-truncated") === null ? {} : { truncated: response.headers.get("x-tinycloud-truncated") === "true" }
+            });
           } catch (error) {
             return err(wrapError("kv", error));
           }
@@ -3544,7 +3615,8 @@ var init_dist2 = __esm({
               path,
               KVAction.DELETE,
               void 0,
-              options?.signal
+              options?.signal,
+              options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
             );
             if (!response.ok) {
               if (response.status === 401) {
@@ -3560,6 +3632,22 @@ var init_dist2 = __esm({
                 return this.classifyNotFound(response, key);
               }
               const errorText = await response.text();
+              if (response.status === 412) {
+                return err(serviceError(
+                  ErrorCodes.KV_PRECONDITION_FAILED,
+                  `KV precondition failed for key "${key}"`,
+                  "kv",
+                  { meta: { status: response.status, statusText: response.statusText } }
+                ));
+              }
+              if (response.status === 503 && options?.ifMatch !== void 0) {
+                return err(serviceError(
+                  ErrorCodes.KV_CONFLICT,
+                  `Concurrent KV delete conflicted for key "${key}"`,
+                  "kv",
+                  { meta: { status: response.status, statusText: response.statusText } }
+                ));
+              }
               return err(
                 serviceError(
                   ErrorCodes.NETWORK_ERROR,
@@ -3569,7 +3657,10 @@ var init_dist2 = __esm({
                 )
               );
             }
-            return ok(void 0);
+            return ok({
+              data: void 0,
+              headers: this.createResponseHeaders(response.headers)
+            });
           } catch (error) {
             return err(wrapError("kv", error));
           }
@@ -3841,10 +3932,17 @@ var init_dist2 = __esm({
             return err(authRequiredError("sql"));
           }
           try {
+            const body = {
+              action: "query",
+              sql,
+              params: serializeSqlValues(params ?? [])
+            };
+            if (options?.maxRows !== void 0) body.maxRows = options.maxRows;
+            if (options?.maxBytes !== void 0) body.maxBytes = options.maxBytes;
             const response = await this.invokeSQL(
               dbName,
               this.actionForSql(sql, SQLAction.READ),
-              { action: "query", sql, params: params ?? [] },
+              body,
               options?.signal
             );
             if (!response.ok) {
@@ -3866,7 +3964,7 @@ var init_dist2 = __esm({
             const body = {
               action: "execute",
               sql,
-              params: params ?? []
+              params: serializeSqlValues(params ?? [])
             };
             if (options?.schema) {
               body.schema = options.schema;
@@ -7831,7 +7929,7 @@ async function planAccountRegistryRead(context, path) {
   }];
 }
 async function planKvList(context, input) {
-  const space = resolveNonSecretSpace(context, input.space);
+  const space = resolveGenericKvSpace(context, input.space);
   return [{
     service: "tinycloud.kv",
     space,
@@ -7840,7 +7938,7 @@ async function planKvList(context, input) {
   }];
 }
 async function planKvGet(context, input) {
-  const space = resolveNonSecretSpace(context, input.space);
+  const space = resolveGenericKvSpace(context, input.space);
   return [{
     service: "tinycloud.kv",
     space,
@@ -7848,12 +7946,21 @@ async function planKvGet(context, input) {
     actions: ["tinycloud.kv/get"]
   }];
 }
+async function planExactKv(context, requestedSpace, key, action) {
+  return [{
+    service: "tinycloud.kv",
+    space: resolveGenericKvSpace(context, requestedSpace),
+    path: key,
+    actions: [action]
+  }];
+}
 async function executeAccountSpacesList(context, _input) {
   try {
     const entries = await readAccountRegistry(context, "spaces/");
-    if (!entries.ok) return nodeFailure("list account spaces");
+    if (!entries.ok) return entries.outcome;
     const spaces = entries.records.map(({ key, value }) => projectAccountSpace(key, value)).sort((left, right) => left.name.localeCompare(right.name) || left.spaceId.localeCompare(right.spaceId));
-    return { status: "ok", output: { spaces, count: spaces.length } };
+    const output = { spaces, count: spaces.length };
+    return accountRegistryOutput(output);
   } catch {
     return nodeFailure("list account spaces");
   }
@@ -7861,9 +7968,10 @@ async function executeAccountSpacesList(context, _input) {
 async function executeAccountApplicationsList(context, _input) {
   try {
     const entries = await readAccountRegistry(context, "applications/");
-    if (!entries.ok) return nodeFailure("list account applications");
+    if (!entries.ok) return entries.outcome;
     const applications = entries.records.map(({ key, value }) => projectAccountApplication(key, value)).sort((left, right) => left.appId.localeCompare(right.appId));
-    return { status: "ok", output: { applications, count: applications.length } };
+    const output = { applications, count: applications.length };
+    return accountRegistryOutput(output);
   } catch {
     return nodeFailure("list account applications");
   }
@@ -7871,15 +7979,22 @@ async function executeAccountApplicationsList(context, _input) {
 async function executeKvList(context, input) {
   try {
     const runtime = runtimeContext(context);
-    const space = resolveNonSecretSpace(runtime, input.space);
-    const result = await runtimeNode(runtime).kvForSpace(space).list(
-      input.prefix === void 0 ? void 0 : { prefix: input.prefix }
-    );
+    const space = resolveGenericKvSpace(runtime, input.space);
+    const result = await genericKv(runtime, space).list({
+      ...input.prefix === void 0 ? {} : { prefix: input.prefix },
+      limit: input.limit ?? DEFAULT_KV_LIST_LIMIT
+    });
     if (!result.ok) return nodeFailure("list KV keys");
     const keys = [...result.data.keys];
     return {
       status: "ok",
-      output: { space, prefix: input.prefix ?? "", keys, count: keys.length }
+      output: {
+        space,
+        prefix: input.prefix ?? "",
+        keys,
+        count: keys.length,
+        truncated: result.data.truncated ?? false
+      }
     };
   } catch (error) {
     if (error instanceof OperationInvocationError) {
@@ -7891,10 +8006,18 @@ async function executeKvList(context, input) {
 async function executeKvGet(context, input) {
   try {
     const runtime = runtimeContext(context);
-    const space = resolveNonSecretSpace(runtime, input.space);
-    const result = await runtimeNode(runtime).kvForSpace(space).get(input.key);
-    if (!result.ok) return nodeFailure("read the KV value");
-    const encoded = encodeKvValue(result.data.data);
+    const space = resolveGenericKvSpace(runtime, input.space);
+    const result = await genericKv(runtime, space).get(input.key, {
+      binary: true,
+      maxResponseBytes: MAX_KV_VALUE_BYTES
+    });
+    if (!result.ok) return kvFailure(result.error, "read the KV value");
+    const bytes = result.data.data;
+    if (bytes.byteLength > MAX_KV_VALUE_BYTES) {
+      return kvFailure({ code: "KV_RESPONSE_TOO_LARGE" }, "read the KV value");
+    }
+    const encoded = encodeKvValue(bytes, input.representation ?? "base64");
+    if (!encoded.ok) return encoded.outcome;
     return {
       status: "ok",
       output: {
@@ -7902,12 +8025,8 @@ async function executeKvGet(context, input) {
         key: input.key,
         value: encoded.value,
         encoding: encoded.encoding,
-        metadata: {
-          ...result.data.headers.etag === void 0 ? {} : { etag: result.data.headers.etag },
-          ...result.data.headers.contentType === void 0 ? {} : { contentType: result.data.headers.contentType },
-          ...result.data.headers.lastModified === void 0 ? {} : { lastModified: result.data.headers.lastModified },
-          ...result.data.headers.contentLength === void 0 ? {} : { contentLength: result.data.headers.contentLength }
-        }
+        metadata: projectKvMetadata(result.data.headers),
+        byteLength: bytes.byteLength
       }
     };
   } catch (error) {
@@ -7917,6 +8036,66 @@ async function executeKvGet(context, input) {
     return nodeFailure("read the KV value");
   }
 }
+async function executeKvHead(context, input) {
+  try {
+    const runtime = runtimeContext(context);
+    const space = resolveGenericKvSpace(runtime, input.space);
+    const result = await genericKv(runtime, space).head(input.key);
+    if (!result.ok) return kvFailure(result.error, "read KV metadata");
+    return { status: "ok", output: { space, key: input.key, metadata: projectKvMetadata(result.data.headers) } };
+  } catch (error) {
+    return caughtKvFailure(error, "read KV metadata");
+  }
+}
+async function executeKvPut(context, input) {
+  try {
+    const runtime = runtimeContext(context);
+    const space = resolveGenericKvSpace(runtime, input.space);
+    const decoded = decodeKvPutContent(input.content);
+    if (decoded === void 0 || decoded.byteLength > MAX_KV_VALUE_BYTES) {
+      return { status: "error", error: operationError("INPUT_INVALID", "The KV content is invalid or too large.") };
+    }
+    const result = await genericKv(runtime, space).put(input.key, decoded.bytes, {
+      contentType: input.contentType ?? decoded.contentType,
+      ...input.mode === "create" ? { ifNoneMatch: "*" } : {},
+      ...input.mode === "replace" ? { ifMatch: input.etag } : {}
+    });
+    if (!result.ok) return kvFailure(result.error, "write the KV value");
+    return {
+      status: "ok",
+      output: {
+        space,
+        key: input.key,
+        mode: input.mode,
+        byteLength: decoded.byteLength,
+        metadata: projectKvMetadata(result.data.headers)
+      }
+    };
+  } catch (error) {
+    return caughtKvFailure(error, "write the KV value");
+  }
+}
+async function executeKvDelete(context, input) {
+  try {
+    const runtime = runtimeContext(context);
+    const space = resolveGenericKvSpace(runtime, input.space);
+    const result = await genericKv(runtime, space).delete(input.key, {
+      ...input.etag === void 0 ? {} : { ifMatch: input.etag }
+    });
+    if (!result.ok) return kvFailure(result.error, "delete the KV value");
+    return {
+      status: "ok",
+      output: {
+        space,
+        key: input.key,
+        deleted: true,
+        ...result.data.headers.etag === void 0 ? {} : { etag: result.data.headers.etag }
+      }
+    };
+  } catch (error) {
+    return caughtKvFailure(error, "delete the KV value");
+  }
+}
 function runtimeContext(context) {
   if (context.runtime === void 0) {
     throw new TypeError("Authenticated operation runtime is unavailable.");
@@ -7926,15 +8105,19 @@ function runtimeContext(context) {
 function runtimeNode(context) {
   return runtimeContext(context).runtime.node;
 }
+function genericKv(context, space) {
+  return runtimeNode(context).kvForSpace(space);
+}
 function resolveSpace(context, space) {
   return operationSpaceResolver(context.runtime.node, context.summary.space)(space);
 }
-function resolveNonSecretSpace(context, space) {
+function resolveGenericKvSpace(context, space) {
   const resolved = resolveSpace(context, space);
-  if (resolved.split(":").at(-1)?.toLowerCase() === "secrets") {
+  const protectedName = resolved.split(":").at(-1)?.toLowerCase();
+  if (protectedName === "secrets" || protectedName === "account") {
     throw new OperationInvocationError(operationError(
       "INPUT_INVALID",
-      "Generic KV operations cannot access the TinyCloud secrets space; use tinycloud.secrets.get."
+      "Generic KV operations cannot access TinyCloud account or secrets spaces."
     ));
   }
   return resolved;
@@ -7943,13 +8126,57 @@ async function readAccountRegistry(context, prefix) {
   const runtime = runtimeContext(context);
   const accountSpace = resolveSpace(runtime, "account");
   const kv = runtimeNode(runtime).kvForSpace(accountSpace);
-  const listed = await kv.list({ prefix });
-  if (!listed.ok) return { ok: false };
+  const listed = await kv.list({ prefix, limit: MAX_ACCOUNT_REGISTRY_RECORDS });
+  if (!listed.ok) return { ok: false, outcome: nodeFailure("list the account registry") };
+  if (listed.data.truncated === true) {
+    return {
+      ok: false,
+      outcome: {
+        status: "error",
+        error: operationError(
+          "OUTPUT_INVALID",
+          `The TinyCloud account registry exceeds the ${MAX_ACCOUNT_REGISTRY_RECORDS}-record exploration limit.`
+        )
+      }
+    };
+  }
   const records = [];
+  let totalBytes = 0;
   for (const key of listed.data.keys) {
-    const loaded = await kv.get(key);
-    if (!loaded.ok || !isRecord2(loaded.data.data)) return { ok: false };
-    records.push({ key, value: loaded.data.data });
+    const loaded = await kv.get(key, {
+      binary: true,
+      maxResponseBytes: MAX_KV_VALUE_BYTES
+    });
+    if (!loaded.ok) {
+      return { ok: false, outcome: kvFailure(loaded.error, "read the account registry") };
+    }
+    const bytes = loaded.data.data;
+    totalBytes += bytes.byteLength;
+    if (bytes.byteLength > MAX_KV_VALUE_BYTES || totalBytes > MAX_ACCOUNT_REGISTRY_BYTES) {
+      return {
+        ok: false,
+        outcome: {
+          status: "error",
+          error: operationError(
+            "KV_RESPONSE_TOO_LARGE",
+            `The TinyCloud account registry exceeds the ${MAX_ACCOUNT_REGISTRY_BYTES}-byte exploration limit.`
+          )
+        }
+      };
+    }
+    try {
+      const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+      if (!isRecord2(value)) throw new TypeError("Account registry values must be JSON objects.");
+      records.push({ key, value });
+    } catch {
+      return {
+        ok: false,
+        outcome: {
+          status: "error",
+          error: operationError("OUTPUT_INVALID", "The TinyCloud account registry contains an invalid record.")
+        }
+      };
+    }
   }
   return { ok: true, records };
 }
@@ -7995,15 +8222,110 @@ function stringField2(record, ...keys) {
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function encodeKvValue(value) {
-  if (value instanceof Uint8Array) {
-    return { value: Buffer.from(value).toString("base64"), encoding: "base64" };
+function encodeKvValue(value, representation) {
+  if (representation === "base64") {
+    return { ok: true, value: Buffer.from(value).toString("base64"), encoding: "base64" };
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(value);
+  } catch {
+    return {
+      ok: false,
+      outcome: { status: "error", error: operationError("OUTPUT_INVALID", "The KV value is not valid UTF-8.") }
+    };
+  }
+  if (representation === "text") return { ok: true, value: text, encoding: "text" };
+  try {
+    const parsed = JsonValueSchema.safeParse(JSON.parse(text));
+    if (!parsed.success) {
+      return {
+        ok: false,
+        outcome: {
+          status: "error",
+          error: operationError(
+            "OUTPUT_INVALID",
+            "The KV JSON contains a number that cannot be represented safely."
+          )
+        }
+      };
+    }
+    return { ok: true, value: parsed.data, encoding: "json" };
+  } catch {
+    return {
+      ok: false,
+      outcome: { status: "error", error: operationError("OUTPUT_INVALID", "The KV value is not valid JSON.") }
+    };
+  }
+}
+function decodeKvPutContent(content) {
+  let bytes;
+  let contentType;
+  if (content.encoding === "utf8") {
+    bytes = new TextEncoder().encode(content.value);
+    contentType = "text/plain;charset=UTF-8";
+  } else if (content.encoding === "json") {
+    bytes = new TextEncoder().encode(JSON.stringify(content.value));
+    contentType = "application/json";
+  } else {
+    if (!isCanonicalBase64(content.value)) return void 0;
+    bytes = new Uint8Array(Buffer.from(content.value, "base64"));
+    contentType = "application/octet-stream";
+  }
+  return { bytes, byteLength: bytes.byteLength, contentType };
+}
+function isCanonicalBase64(value) {
+  if (value.length % 4 !== 0 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return false;
   }
+  return Buffer.from(value, "base64").toString("base64") === value;
+}
+function projectKvMetadata(headers) {
   return {
-    value,
-    encoding: typeof value === "string" ? "text" : "json"
+    ...headers.etag === void 0 ? {} : { etag: headers.etag },
+    ...headers.contentType === void 0 ? {} : { contentType: headers.contentType },
+    ...headers.lastModified === void 0 ? {} : { lastModified: headers.lastModified },
+    ...headers.contentLength === void 0 ? {} : { contentLength: headers.contentLength }
   };
 }
+function caughtKvFailure(error, action) {
+  if (error instanceof OperationInvocationError) return { status: "error", error: error.operationError };
+  return nodeFailure(action);
+}
+function accountRegistryOutput(output) {
+  if (Buffer.byteLength(JSON.stringify(output), "utf8") > MAX_ACCOUNT_REGISTRY_BYTES) {
+    return {
+      status: "error",
+      error: operationError(
+        "KV_RESPONSE_TOO_LARGE",
+        `The TinyCloud account registry exceeds the ${MAX_ACCOUNT_REGISTRY_BYTES}-byte exploration limit.`
+      )
+    };
+  }
+  return { status: "ok", output };
+}
+function kvFailure(error, action) {
+  if (error.code === "KV_NOT_FOUND") {
+    return { status: "error", error: operationError("KV_NOT_FOUND", "The TinyCloud KV key was not found.") };
+  }
+  if (error.code === "KV_PRECONDITION_FAILED") {
+    return { status: "error", error: operationError("KV_PRECONDITION_FAILED", "The TinyCloud KV object changed or already exists.") };
+  }
+  if (error.code === "KV_CONFLICT") {
+    return {
+      status: "error",
+      error: operationError(
+        "KV_CONFLICT",
+        "A database serialization conflict prevented the conditional KV mutation; re-read the key state, which may still be absent, before deciding whether to retry.",
+        { retryable: true }
+      )
+    };
+  }
+  if (error.code === "KV_RESPONSE_TOO_LARGE") {
+    return { status: "error", error: operationError("KV_RESPONSE_TOO_LARGE", `The TinyCloud KV value exceeds ${MAX_KV_VALUE_BYTES} bytes.`) };
+  }
+  return nodeFailure(action);
+}
 function nodeFailure(action) {
   return {
     status: "error",
@@ -8014,12 +8336,16 @@ function nodeFailure(action) {
     )
   };
 }
-var EmptyInputSchema2, SpaceSchema, PrefixSchema, KeySchema, AccountSpaceSchema, AccountSpacesOutputSchema, AccountApplicationSchema, AccountApplicationsOutputSchema, KvListInputSchema, KvListOutputSchema, KvGetInputSchema, KvGetOutputSchema, AUTHENTICATED_POSTURES, EXPLORATION_EXPOSURE, ACCOUNT_SPACES_SENSITIVITY, ACCOUNT_APPLICATIONS_SENSITIVITY, KV_LIST_SENSITIVITY, KV_GET_SENSITIVITY, explorationOperationDefinitions;
+var MAX_KV_VALUE_BYTES, DEFAULT_KV_LIST_LIMIT, MAX_ACCOUNT_REGISTRY_RECORDS, MAX_ACCOUNT_REGISTRY_BYTES, EmptyInputSchema2, SpaceSchema, PrefixSchema, KeySchema, LimitSchema, StrongEtagSchema, ContentTypeSchema, JsonNumberSchema, JsonValueSchema, KvMetadataSchema, AccountSpaceSchema, AccountSpacesOutputSchema, AccountApplicationSchema, AccountApplicationsOutputSchema, KvListInputSchema, KvListOutputSchema, KvGetInputSchema, KvGetOutputSchema, KvPutContentSchema, KvPutCommonSchema, KvPutInputSchema, KvPutOutputSchema, KvHeadInputSchema, KvHeadOutputSchema, KvDeleteInputSchema, KvDeleteOutputSchema, AUTHENTICATED_POSTURES, EXPLORATION_EXPOSURE, ACCOUNT_SPACES_SENSITIVITY, ACCOUNT_APPLICATIONS_SENSITIVITY, KV_LIST_SENSITIVITY, KV_GET_SENSITIVITY, KV_PUT_SENSITIVITY, KV_KEY_SENSITIVITY, explorationOperationDefinitions;
 var init_exploration = __esm({
   "src/operations/exploration.ts"() {
     "use strict";
     init_errors();
     init_secrets();
+    MAX_KV_VALUE_BYTES = 1024 * 1024;
+    DEFAULT_KV_LIST_LIMIT = 100;
+    MAX_ACCOUNT_REGISTRY_RECORDS = 1e3;
+    MAX_ACCOUNT_REGISTRY_BYTES = 4 * 1024 * 1024;
     EmptyInputSchema2 = z4.object({}).strict();
     SpaceSchema = z4.string().min(1).refine(
       (space) => (/^[A-Za-z0-9_-]+$/.test(space) || space.startsWith("tinycloud:")) && !space.includes("*"),
@@ -8033,6 +8359,33 @@ var init_exploration = __esm({
       (key) => key !== "/" && !key.endsWith("/") && !key.includes("*"),
       "Invalid KV key."
     );
+    LimitSchema = z4.number().int().min(1).max(1e3);
+    StrongEtagSchema = z4.string().regex(
+      /^"blake3-[0-9a-f]{64}"$/,
+      "A strong TinyCloud BLAKE3 ETag is required."
+    );
+    ContentTypeSchema = z4.string().min(1).max(128).refine(
+      (value) => !/[\x00-\x1f\x7f]/.test(value),
+      "Invalid content type."
+    );
+    JsonNumberSchema = z4.number().finite().refine(
+      (value) => !Number.isInteger(value) || Number.isSafeInteger(value),
+      "JSON integer values must be JavaScript safe integers."
+    );
+    JsonValueSchema = z4.lazy(() => z4.union([
+      z4.null(),
+      z4.boolean(),
+      JsonNumberSchema,
+      z4.string(),
+      z4.array(JsonValueSchema),
+      z4.record(JsonValueSchema)
+    ]));
+    KvMetadataSchema = z4.object({
+      etag: z4.string().optional(),
+      contentType: z4.string().optional(),
+      lastModified: z4.string().optional(),
+      contentLength: z4.number().int().nonnegative().optional()
+    }).strict();
     AccountSpaceSchema = z4.object({
       spaceId: z4.string().min(1),
       name: z4.string().min(1),
@@ -8062,17 +8415,20 @@ var init_exploration = __esm({
     }).strict();
     KvListInputSchema = z4.object({
       space: SpaceSchema,
-      prefix: PrefixSchema.optional()
+      prefix: PrefixSchema.optional(),
+      limit: LimitSchema.optional()
     }).strict();
     KvListOutputSchema = z4.object({
       space: z4.string().min(1),
       prefix: z4.string(),
       keys: z4.array(z4.string()),
-      count: z4.number().int().nonnegative()
+      count: z4.number().int().nonnegative(),
+      truncated: z4.boolean()
     }).strict();
     KvGetInputSchema = z4.object({
       space: SpaceSchema,
-      key: KeySchema
+      key: KeySchema,
+      representation: z4.enum(["base64", "text", "json"]).optional()
     }).strict();
     KvGetOutputSchema = z4.object({
       space: z4.string().min(1),
@@ -8086,12 +8442,61 @@ var init_exploration = __esm({
         z4.record(z4.unknown())
       ]),
       encoding: z4.enum(["json", "text", "base64"]),
-      metadata: z4.object({
-        etag: z4.string().optional(),
-        contentType: z4.string().optional(),
-        lastModified: z4.string().optional(),
-        contentLength: z4.number().int().nonnegative().optional()
-      }).strict()
+      metadata: KvMetadataSchema,
+      byteLength: z4.number().int().nonnegative()
+    }).strict();
+    KvPutContentSchema = z4.discriminatedUnion("encoding", [
+      z4.object({ encoding: z4.literal("utf8"), value: z4.string() }).strict(),
+      z4.object({ encoding: z4.literal("json"), value: JsonValueSchema }).strict(),
+      z4.object({ encoding: z4.literal("base64"), value: z4.string() }).strict()
+    ]).superRefine((content, context) => {
+      const decoded = decodeKvPutContent(content);
+      if (decoded === void 0) {
+        context.addIssue({ code: z4.ZodIssueCode.custom, message: "Invalid canonical base64 content." });
+      } else if (decoded.byteLength > MAX_KV_VALUE_BYTES) {
+        context.addIssue({
+          code: z4.ZodIssueCode.too_big,
+          type: "array",
+          maximum: MAX_KV_VALUE_BYTES,
+          inclusive: true,
+          message: `KV content must not exceed ${MAX_KV_VALUE_BYTES} bytes.`
+        });
+      }
+    });
+    KvPutCommonSchema = {
+      space: SpaceSchema,
+      key: KeySchema,
+      content: KvPutContentSchema,
+      contentType: ContentTypeSchema.optional()
+    };
+    KvPutInputSchema = z4.discriminatedUnion("mode", [
+      z4.object({ ...KvPutCommonSchema, mode: z4.literal("create") }).strict(),
+      z4.object({ ...KvPutCommonSchema, mode: z4.literal("upsert") }).strict(),
+      z4.object({ ...KvPutCommonSchema, mode: z4.literal("replace"), etag: StrongEtagSchema }).strict()
+    ]);
+    KvPutOutputSchema = z4.object({
+      space: z4.string().min(1),
+      key: z4.string().min(1),
+      mode: z4.enum(["create", "replace", "upsert"]),
+      byteLength: z4.number().int().nonnegative(),
+      metadata: KvMetadataSchema
+    }).strict();
+    KvHeadInputSchema = z4.object({ space: SpaceSchema, key: KeySchema }).strict();
+    KvHeadOutputSchema = z4.object({
+      space: z4.string().min(1),
+      key: z4.string().min(1),
+      metadata: KvMetadataSchema
+    }).strict();
+    KvDeleteInputSchema = z4.object({
+      space: SpaceSchema,
+      key: KeySchema,
+      etag: StrongEtagSchema.optional()
+    }).strict();
+    KvDeleteOutputSchema = z4.object({
+      space: z4.string().min(1),
+      key: z4.string().min(1),
+      deleted: z4.literal(true),
+      etag: z4.string().optional()
     }).strict();
     AUTHENTICATED_POSTURES = [
       "owner-openkey",
@@ -8123,6 +8528,8 @@ var init_exploration = __esm({
       input: ["/key"],
       output: ["/value"]
     };
+    KV_PUT_SENSITIVITY = { input: ["/key", "/content"], output: [] };
+    KV_KEY_SENSITIVITY = { input: ["/key"], output: [] };
     explorationOperationDefinitions = [
       {
         id: "tinycloud.account.spaces.list",
@@ -8173,7 +8580,7 @@ var init_exploration = __esm({
         id: "tinycloud.kv.get",
         version: 1,
         title: "Get a TinyCloud KV value",
-        description: "Read one exact key from a delegated non-secrets TinyCloud space.",
+        description: "Read one exact key with a node-enforced one MiB response limit.",
         input: KvGetInputSchema,
         output: KvGetOutputSchema,
         effects: ["read"],
@@ -8183,6 +8590,51 @@ var init_exploration = __esm({
         sensitivity: KV_GET_SENSITIVITY,
         authority: planKvGet,
         execute: executeKvGet
+      },
+      {
+        id: "tinycloud.kv.head",
+        version: 1,
+        title: "Inspect TinyCloud KV metadata",
+        description: "Read metadata for one exact key without downloading its value.",
+        input: KvHeadInputSchema,
+        output: KvHeadOutputSchema,
+        effects: ["read"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES,
+        exposure: EXPLORATION_EXPOSURE,
+        sensitivity: KV_KEY_SENSITIVITY,
+        authority: (context, input) => planExactKv(context, input.space, input.key, "tinycloud.kv/metadata"),
+        execute: executeKvHead
+      },
+      {
+        id: "tinycloud.kv.put",
+        version: 1,
+        title: "Write a TinyCloud KV value",
+        description: "Create, conditionally replace, or explicitly upsert one exact KV key.",
+        input: KvPutInputSchema,
+        output: KvPutOutputSchema,
+        effects: ["write"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES,
+        exposure: EXPLORATION_EXPOSURE,
+        sensitivity: KV_PUT_SENSITIVITY,
+        authority: (context, input) => planExactKv(context, input.space, input.key, "tinycloud.kv/put"),
+        execute: executeKvPut
+      },
+      {
+        id: "tinycloud.kv.delete",
+        version: 1,
+        title: "Delete a TinyCloud KV value",
+        description: "Delete one exact KV key, optionally only when its ETag still matches.",
+        input: KvDeleteInputSchema,
+        output: KvDeleteOutputSchema,
+        effects: ["destructive"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES,
+        exposure: EXPLORATION_EXPOSURE,
+        sensitivity: KV_KEY_SENSITIVITY,
+        authority: (context, input) => planExactKv(context, input.space, input.key, "tinycloud.kv/del"),
+        execute: executeKvDelete
       }
     ];
   }
@@ -8397,8 +8849,543 @@ var init_secrets_get = __esm({
   }
 });
 
-// src/operations/status.ts
+// src/operations/sql.ts
+import nodeSqlParser from "node-sql-parser";
 import { z as z6 } from "zod";
+async function planSqlRead(context, input) {
+  const space = resolveSqlSpace(context, input.space);
+  return [{
+    service: "tinycloud.sql",
+    space,
+    path: input.database,
+    actions: ["tinycloud.sql/read"]
+  }];
+}
+async function planSqlWrite(context, input) {
+  const space = resolveSqlSpace(context, input.space);
+  return [{
+    service: "tinycloud.sql",
+    space,
+    path: input.database,
+    actions: ["tinycloud.sql/write"],
+    description: SQL_WRITE_AUTHORITY_NOTICE
+  }];
+}
+async function executeSqlSchemaInspect(context, input) {
+  try {
+    const runtime = runtimeContext2(context);
+    const space = resolveSqlSpace(runtime, input.space);
+    const result = await runtimeNode2(runtime).sqlForSpace(space).db(input.database).query(SCHEMA_QUERY, [], { maxRows: SCHEMA_MAX_ROWS, maxBytes: SCHEMA_MAX_BYTES });
+    if (!result.ok) return sqlServiceFailure(result.error, "inspect the SQLite schema");
+    const normalized = normalizeQueryResult(result.data, SCHEMA_MAX_ROWS, SCHEMA_MAX_BYTES);
+    const objects = normalized.rows.map((row) => schemaObject(row));
+    return {
+      status: "ok",
+      output: {
+        space,
+        database: input.database,
+        objects,
+        count: objects.length,
+        limits: limitsOutput(SCHEMA_MAX_ROWS, SCHEMA_MAX_BYTES)
+      }
+    };
+  } catch (error) {
+    return sqlFailure(error, "inspect the SQLite schema");
+  }
+}
+async function executeSqlQuery(context, input) {
+  try {
+    if (!isSingleReadQuery(input.sql)) {
+      return {
+        status: "error",
+        error: operationError(
+          "SQL_QUERY_INVALID",
+          "SQL must parse as exactly one SQLite SELECT statement."
+        )
+      };
+    }
+    const runtime = runtimeContext2(context);
+    const space = resolveSqlSpace(runtime, input.space);
+    const maxRows = input.maxRows ?? DEFAULT_MAX_ROWS;
+    const maxBytes = input.maxBytes ?? DEFAULT_MAX_BYTES;
+    const params = (input.params ?? []).map(decodeSqlInputValue);
+    const result = await runtimeNode2(runtime).sqlForSpace(space).db(input.database).query(input.sql, params, { maxRows, maxBytes });
+    if (!result.ok) return sqlServiceFailure(result.error, "run the SQLite query");
+    const normalized = normalizeQueryResult(result.data, maxRows, maxBytes);
+    return {
+      status: "ok",
+      output: {
+        space,
+        database: input.database,
+        columns: normalized.columns,
+        rows: normalized.rows,
+        rowCount: normalized.rows.length,
+        limits: limitsOutput(maxRows, maxBytes)
+      }
+    };
+  } catch (error) {
+    return sqlFailure(error, "run the SQLite query");
+  }
+}
+async function executeSqlDml(context, input) {
+  try {
+    const statementType = parseSingleDmlStatement(input.sql, input.params.length);
+    if (statementType === void 0) {
+      return {
+        status: "error",
+        error: operationError(
+          "SQL_QUERY_INVALID",
+          "SQL must parse as exactly one parameterized INSERT, UPDATE, or DELETE with one value per positional placeholder."
+        )
+      };
+    }
+    const runtime = runtimeContext2(context);
+    const space = resolveSqlSpace(runtime, input.space);
+    const result = await runtimeNode2(runtime).sqlForSpace(space).db(input.database).execute(input.sql, input.params.map(decodeSqlInputValue));
+    if (!result.ok) return sqlMutationFailure();
+    const normalized = normalizeExecuteResult(result.data);
+    return {
+      status: "ok",
+      output: {
+        space,
+        database: input.database,
+        statementType,
+        ...normalized,
+        authorityNotice: SQL_WRITE_AUTHORITY_NOTICE
+      }
+    };
+  } catch (error) {
+    return sqlFailure(error, "execute the SQLite statement");
+  }
+}
+function isSingleReadQuery(sql) {
+  const ast = parseSingleStatement(sql);
+  return ast !== void 0 && ast.type === "select";
+}
+function parseSingleDmlStatement(sql, parameterCount) {
+  const ast = parseSingleStatement(sql);
+  if (ast === void 0 || ast.type !== "insert" && ast.type !== "update" && ast.type !== "delete" || ast.with !== void 0 && ast.with !== null) {
+    return void 0;
+  }
+  const placeholders = countPositionalParameters(ast);
+  return placeholders > 0 && placeholders === parameterCount ? ast.type : void 0;
+}
+function parseSingleStatement(sql) {
+  try {
+    const ast = sqlParser.astify(sql, { database: "sqlite" });
+    return !Array.isArray(ast) && isRecord3(ast) ? ast : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function countPositionalParameters(value) {
+  if (Array.isArray(value)) {
+    return value.reduce((count, entry) => count + countPositionalParameters(entry), 0);
+  }
+  if (!isRecord3(value)) return 0;
+  const current = value.type === "origin" && value.value === "?" ? 1 : 0;
+  return Object.values(value).reduce(
+    (count, entry) => count + countPositionalParameters(entry),
+    current
+  );
+}
+function decodeSqlInputValue(value) {
+  if (isRecord3(value) && value.type === "blob") {
+    return new Uint8Array(Buffer.from(value.base64, "base64"));
+  }
+  return value;
+}
+function normalizeQueryResult(value, maxRows, maxBytes) {
+  if (!isRecord3(value) || !Array.isArray(value.columns) || !Array.isArray(value.rows)) {
+    throw unsafeSqlValue("The node returned an invalid SQLite query result.");
+  }
+  const columns = value.columns.map((column) => {
+    if (typeof column !== "string") {
+      throw unsafeSqlValue("The node returned an invalid SQLite column name.");
+    }
+    return column;
+  });
+  const rows = value.rows.map((row) => {
+    if (!Array.isArray(row) || row.length !== columns.length) {
+      throw unsafeSqlValue("The node returned an invalid SQLite row.");
+    }
+    return row.map(normalizeSqlOutputValue);
+  });
+  const serializedBytes = Buffer.byteLength(JSON.stringify({ columns, rows }), "utf8");
+  if (rows.length > maxRows || serializedBytes > maxBytes) {
+    throw new OperationInvocationError(operationError(
+      "SQL_RESULT_LIMIT_EXCEEDED",
+      "The SQLite query result exceeded the requested result limits.",
+      {
+        details: {
+          maxRows,
+          maxBytes,
+          returnedRows: rows.length,
+          returnedBytes: serializedBytes
+        }
+      }
+    ));
+  }
+  return { columns, rows };
+}
+function normalizeSqlOutputValue(value) {
+  if (value === null || typeof value === "string") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw unsafeSqlValue("The node returned an integer that cannot be represented safely in JavaScript.");
+    }
+    return value;
+  }
+  if (value instanceof Uint8Array) return encodeBlob(value);
+  if (Array.isArray(value) && value.every(isByte)) {
+    return encodeBlob(Uint8Array.from(value));
+  }
+  if (isRecord3(value) && value.type === "Buffer" && Array.isArray(value.data) && value.data.every(isByte)) {
+    return encodeBlob(Uint8Array.from(value.data));
+  }
+  throw unsafeSqlValue("The node returned an unsupported SQLite value.");
+}
+function normalizeExecuteResult(value) {
+  if (!isRecord3(value) || !Number.isSafeInteger(value.changes) || value.changes < 0 || value.lastInsertRowId !== null && !Number.isSafeInteger(value.lastInsertRowId)) {
+    throw unsafeSqlValue("The node returned SQLite mutation metadata that cannot be represented safely in JavaScript.");
+  }
+  return {
+    changes: value.changes,
+    lastInsertRowId: value.lastInsertRowId
+  };
+}
+function schemaObject(row) {
+  const [type, name, tableName, sql] = row;
+  if (type !== "table" && type !== "view" && type !== "index" && type !== "trigger" || typeof name !== "string" || typeof tableName !== "string" || sql !== null && typeof sql !== "string") {
+    throw unsafeSqlValue("The node returned an invalid SQLite schema record.");
+  }
+  return {
+    type,
+    name,
+    tableName,
+    ...sql === null ? {} : { sql }
+  };
+}
+function limitsOutput(maxRows, maxBytes) {
+  return { maxRows, maxBytes, enforcement: "node-requested-client-verified" };
+}
+function runtimeContext2(context) {
+  if (context.runtime === void 0) {
+    throw new TypeError("Authenticated operation runtime is unavailable.");
+  }
+  return context;
+}
+function runtimeNode2(context) {
+  return context.runtime.node;
+}
+function resolveSqlSpace(context, space) {
+  const resolved = operationSpaceResolver(
+    context.runtime.node,
+    context.summary.space
+  )(space);
+  const name = resolved.split(":").at(-1)?.toLowerCase();
+  if (name === "secrets" || name === "account") {
+    throw new OperationInvocationError(operationError(
+      "INPUT_INVALID",
+      "Generic SQL operations cannot access protected TinyCloud account or secrets spaces."
+    ));
+  }
+  return resolved;
+}
+function encodeBlob(value) {
+  return {
+    type: "blob",
+    base64: Buffer.from(value).toString("base64"),
+    byteLength: value.byteLength
+  };
+}
+function unsafeSqlValue(message) {
+  return new OperationInvocationError(operationError("SQL_VALUE_UNSAFE", message));
+}
+function sqlFailure(error, action) {
+  if (error instanceof OperationInvocationError) {
+    return { status: "error", error: error.operationError };
+  }
+  return nodeFailure2(action);
+}
+function nodeFailure2(action) {
+  return {
+    status: "error",
+    error: operationError(
+      "NODE_ERROR",
+      `The TinyCloud node could not ${action}.`,
+      { retryable: true }
+    )
+  };
+}
+function sqlServiceFailure(error, action) {
+  if (isRecord3(error) && error.code === "SQL_RESPONSE_TOO_LARGE") {
+    return {
+      status: "error",
+      error: operationError(
+        "SQL_RESULT_LIMIT_EXCEEDED",
+        "The SQLite query result exceeded the requested result limits."
+      )
+    };
+  }
+  return nodeFailure2(action);
+}
+function sqlMutationFailure() {
+  return {
+    status: "error",
+    error: operationError(
+      "SQL_EXECUTION_FAILED",
+      "The SQLite statement outcome is unknown; inspect database state before considering another write.",
+      { retryable: false }
+    )
+  };
+}
+function isCanonicalBase642(value) {
+  if (value === "") return true;
+  if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) return false;
+  return Buffer.from(value, "base64").toString("base64") === value;
+}
+function sqlInputValueBytes(value) {
+  if (typeof value === "string") return Buffer.byteLength(value, "utf8");
+  if (isRecord3(value) && value.type === "blob") {
+    return Buffer.from(value.base64, "base64").byteLength;
+  }
+  return 8;
+}
+function isByte(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 255;
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var DEFAULT_MAX_ROWS, MAX_MAX_ROWS, DEFAULT_MAX_BYTES, MAX_MAX_BYTES, SCHEMA_MAX_ROWS, SCHEMA_MAX_BYTES, MAX_PARAMETERS, MAX_SQL_LENGTH, SQL_WRITE_AUTHORITY_NOTICE, SCHEMA_QUERY, sqlParser, SpaceSchema2, DatabaseSchema, SafeNumberSchema, Base64Schema, SqlInputValueSchema, SqlParamsSchema, RequiredSqlParamsSchema, SqlOutputValueSchema, SqlTargetInputSchema, SqlQueryInputSchema, SqlExecuteInputSchema, SqlLimitsOutputSchema, SqlSchemaInspectOutputSchema, SqlQueryOutputSchema, SqlExecuteOutputSchema, AUTHENTICATED_POSTURES2, SQL_EXPOSURE, SQL_SCHEMA_SENSITIVITY, SQL_QUERY_SENSITIVITY, SQL_EXECUTE_SENSITIVITY, sqlOperationDefinitions;
+var init_sql = __esm({
+  "src/operations/sql.ts"() {
+    "use strict";
+    init_errors();
+    init_secrets();
+    DEFAULT_MAX_ROWS = 100;
+    MAX_MAX_ROWS = 1e3;
+    DEFAULT_MAX_BYTES = 1024 * 1024;
+    MAX_MAX_BYTES = 4 * 1024 * 1024;
+    SCHEMA_MAX_ROWS = 500;
+    SCHEMA_MAX_BYTES = 1024 * 1024;
+    MAX_PARAMETERS = 100;
+    MAX_SQL_LENGTH = 64 * 1024;
+    SQL_WRITE_AUTHORITY_NOTICE = "Approving tinycloud.sql/write grants full read/write/schema mutation authority over this exact database; the MCP tool itself accepts only one parameterized INSERT, UPDATE, or DELETE.";
+    SCHEMA_QUERY = `SELECT type, name, tbl_name, sql
+FROM sqlite_schema
+WHERE type IN ('table', 'view', 'index', 'trigger')
+  AND name NOT LIKE 'sqlite_%'
+ORDER BY type, name`;
+    sqlParser = new nodeSqlParser.Parser();
+    SpaceSchema2 = z6.string().min(1).refine(
+      (space) => (/^[A-Za-z0-9_-]+$/.test(space) || space.startsWith("tinycloud:")) && !space.includes("*"),
+      "Invalid TinyCloud space."
+    );
+    DatabaseSchema = z6.string().min(1).max(256).refine(
+      (database) => database !== "/" && !database.endsWith("/") && !database.includes("*") && !/[\u0000-\u001f\u007f]/.test(database),
+      "Invalid SQLite database name."
+    );
+    SafeNumberSchema = z6.number().finite().refine(
+      (value) => !Number.isInteger(value) || Number.isSafeInteger(value),
+      "SQLite integer parameters must be JavaScript safe integers."
+    );
+    Base64Schema = z6.string().max(Math.ceil(MAX_MAX_BYTES / 3) * 4).refine(
+      isCanonicalBase642,
+      "Invalid base64 BLOB value."
+    );
+    SqlInputValueSchema = z6.union([
+      z6.null(),
+      SafeNumberSchema,
+      z6.string().max(MAX_MAX_BYTES),
+      z6.object({ type: z6.literal("blob"), base64: Base64Schema }).strict()
+    ]);
+    SqlParamsSchema = z6.array(SqlInputValueSchema).max(MAX_PARAMETERS).superRefine(
+      (params, context) => {
+        const totalBytes = params.reduce(
+          (total, value) => total + sqlInputValueBytes(value),
+          0
+        );
+        if (totalBytes > MAX_MAX_BYTES) {
+          context.addIssue({
+            code: z6.ZodIssueCode.custom,
+            message: "SQLite query parameters exceed the 4 MiB input limit."
+          });
+        }
+      }
+    );
+    RequiredSqlParamsSchema = z6.array(SqlInputValueSchema).min(1).max(MAX_PARAMETERS).superRefine(
+      (params, context) => {
+        const totalBytes = params.reduce(
+          (total, value) => total + sqlInputValueBytes(value),
+          0
+        );
+        if (totalBytes > MAX_MAX_BYTES) {
+          context.addIssue({
+            code: z6.ZodIssueCode.custom,
+            message: "SQLite query parameters exceed the 4 MiB input limit."
+          });
+        }
+      }
+    );
+    SqlOutputValueSchema = z6.union([
+      z6.null(),
+      SafeNumberSchema,
+      z6.string(),
+      z6.object({
+        type: z6.literal("blob"),
+        base64: z6.string(),
+        byteLength: z6.number().int().nonnegative()
+      }).strict()
+    ]);
+    SqlTargetInputSchema = z6.object({
+      space: SpaceSchema2,
+      database: DatabaseSchema
+    }).strict();
+    SqlQueryInputSchema = z6.object({
+      space: SpaceSchema2,
+      database: DatabaseSchema,
+      sql: z6.string().min(1).max(MAX_SQL_LENGTH).superRefine((sql, context) => {
+        if (!isSingleReadQuery(sql)) {
+          context.addIssue({
+            code: z6.ZodIssueCode.custom,
+            message: "SQL must parse as exactly one SQLite SELECT statement."
+          });
+        }
+      }),
+      params: SqlParamsSchema.optional(),
+      maxRows: z6.number().int().positive().max(MAX_MAX_ROWS).optional(),
+      maxBytes: z6.number().int().positive().max(MAX_MAX_BYTES).optional()
+    }).strict();
+    SqlExecuteInputSchema = z6.object({
+      space: SpaceSchema2,
+      database: DatabaseSchema,
+      sql: z6.string().min(1).max(MAX_SQL_LENGTH),
+      params: RequiredSqlParamsSchema,
+      acknowledgeDatabaseWideAuthority: z6.literal(true).describe(SQL_WRITE_AUTHORITY_NOTICE)
+    }).strict().superRefine((input, context) => {
+      if (parseSingleDmlStatement(input.sql, input.params.length) === void 0) {
+        context.addIssue({
+          code: z6.ZodIssueCode.custom,
+          path: ["sql"],
+          message: "SQL must parse as exactly one parameterized INSERT, UPDATE, or DELETE with one value per positional placeholder."
+        });
+      }
+    });
+    SqlLimitsOutputSchema = z6.object({
+      maxRows: z6.number().int().positive(),
+      maxBytes: z6.number().int().positive(),
+      enforcement: z6.literal("node-requested-client-verified")
+    }).strict();
+    SqlSchemaInspectOutputSchema = z6.object({
+      space: z6.string().min(1),
+      database: z6.string().min(1),
+      objects: z6.array(z6.object({
+        type: z6.enum(["table", "view", "index", "trigger"]),
+        name: z6.string().min(1),
+        tableName: z6.string().min(1),
+        sql: z6.string().optional()
+      }).strict()),
+      count: z6.number().int().nonnegative(),
+      limits: SqlLimitsOutputSchema
+    }).strict();
+    SqlQueryOutputSchema = z6.object({
+      space: z6.string().min(1),
+      database: z6.string().min(1),
+      columns: z6.array(z6.string()),
+      rows: z6.array(z6.array(SqlOutputValueSchema)),
+      rowCount: z6.number().int().nonnegative(),
+      limits: SqlLimitsOutputSchema
+    }).strict();
+    SqlExecuteOutputSchema = z6.object({
+      space: z6.string().min(1),
+      database: z6.string().min(1),
+      statementType: z6.enum(["insert", "update", "delete"]),
+      changes: z6.number().int().nonnegative(),
+      lastInsertRowId: z6.number().int().nullable(),
+      authorityNotice: z6.literal(SQL_WRITE_AUTHORITY_NOTICE)
+    }).strict();
+    AUTHENTICATED_POSTURES2 = [
+      "owner-openkey",
+      "delegate-session",
+      "local-owner-key"
+    ];
+    SQL_EXPOSURE = {
+      cli: {
+        status: "excluded",
+        reason: "Existing SQL Commander commands remain the CLI surface."
+      },
+      mcp: { status: "required" },
+      skill: { status: "required" },
+      docs: { status: "required" }
+    };
+    SQL_SCHEMA_SENSITIVITY = {
+      input: ["/database"],
+      output: ["/objects"]
+    };
+    SQL_QUERY_SENSITIVITY = {
+      input: ["/database", "/sql", "/params"],
+      output: ["/columns", "/rows"]
+    };
+    SQL_EXECUTE_SENSITIVITY = {
+      input: ["/database", "/sql", "/params"],
+      output: ["/lastInsertRowId"]
+    };
+    sqlOperationDefinitions = [
+      {
+        id: "tinycloud.sql.schema.inspect",
+        version: 1,
+        title: "Inspect a TinyCloud SQLite schema",
+        description: "List user tables, views, indexes, and triggers in one exact TinyCloud SQLite database using a fixed read-only query.",
+        input: SqlTargetInputSchema,
+        output: SqlSchemaInspectOutputSchema,
+        effects: ["read"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES2,
+        exposure: SQL_EXPOSURE,
+        sensitivity: SQL_SCHEMA_SENSITIVITY,
+        authority: planSqlRead,
+        execute: executeSqlSchemaInspect
+      },
+      {
+        id: "tinycloud.sql.query",
+        version: 1,
+        title: "Query a TinyCloud SQLite database",
+        description: "Run exactly one parser-approved SELECT against one exact TinyCloud SQLite database. Result limits are requested from the node and verified locally without silent truncation.",
+        input: SqlQueryInputSchema,
+        output: SqlQueryOutputSchema,
+        effects: ["read"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES2,
+        exposure: SQL_EXPOSURE,
+        sensitivity: SQL_QUERY_SENSITIVITY,
+        invalidInputErrorCode: "SQL_QUERY_INVALID",
+        authority: planSqlRead,
+        execute: executeSqlQuery
+      },
+      {
+        id: "tinycloud.sql.execute",
+        version: 1,
+        title: "Execute a TinyCloud SQLite DML statement",
+        description: `Run exactly one parameterized INSERT, UPDATE, or DELETE against one exact TinyCloud SQLite database. ${SQL_WRITE_AUTHORITY_NOTICE}`,
+        input: SqlExecuteInputSchema,
+        output: SqlExecuteOutputSchema,
+        effects: ["write", "destructive"],
+        runtime: "authenticated",
+        postures: AUTHENTICATED_POSTURES2,
+        exposure: SQL_EXPOSURE,
+        sensitivity: SQL_EXECUTE_SENSITIVITY,
+        invalidInputErrorCode: "SQL_QUERY_INVALID",
+        authority: planSqlWrite,
+        execute: executeSqlDml
+      }
+    ];
+  }
+});
+
+// src/operations/status.ts
+import { z as z7 } from "zod";
 function createStatusDefinition(params) {
   return {
     id: params.id,
@@ -8453,7 +9440,7 @@ async function inspectPinnedProfileStatus(context, _input) {
 async function pinnedProfileExists(profile) {
   try {
     const storedProfile = await readProfile(profile);
-    return isRecord3(storedProfile);
+    return isRecord4(storedProfile);
   } catch {
     return false;
   }
@@ -8473,7 +9460,7 @@ async function countLiveAdditionalDelegations(profile) {
 }
 function summarizeSession(session) {
   if (session === null) return { present: false, expired: null, expiresAt: null };
-  if (!isRecord3(session)) throw new TypeError("Invalid session store.");
+  if (!isRecord4(session)) throw new TypeError("Invalid session store.");
   const expiry = extractSessionExpiry(session);
   if (expiry === null) return { present: true, expired: null, expiresAt: null };
   return {
@@ -8483,7 +9470,7 @@ function summarizeSession(session) {
   };
 }
 function storedDelegationExpiry(entry) {
-  if (!isRecord3(entry) || !isRecord3(entry.delegation) || !("expiry" in entry.delegation)) {
+  if (!isRecord4(entry) || !isRecord4(entry.delegation) || !("expiry" in entry.delegation)) {
     throw new TypeError("Invalid stored delegation.");
   }
   return parseExpiry(entry.delegation.expiry);
@@ -8512,7 +9499,7 @@ function profileNotFound(profile) {
     )
   };
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var StatusInputSchema, StatusOutputSchema, STATUS_POSTURES, STATUS_EXPOSURE, STATUS_SENSITIVITY, statusOperationDefinitions;
@@ -8521,27 +9508,27 @@ var init_status = __esm({
     "use strict";
     init_errors();
     init_state();
-    StatusInputSchema = z6.object({}).strict();
-    StatusOutputSchema = z6.object({
-      profile: z6.string().min(1),
-      host: z6.string().min(1),
-      posture: z6.enum([
+    StatusInputSchema = z7.object({}).strict();
+    StatusOutputSchema = z7.object({
+      profile: z7.string().min(1),
+      host: z7.string().min(1),
+      posture: z7.enum([
         "owner-openkey",
         "delegate-session",
         "local-owner-key",
         "unauthenticated"
       ]),
-      operatorType: z6.enum(["human", "agent"]).optional(),
-      principalDid: z6.string().min(1).optional(),
-      sessionDid: z6.string().min(1).optional(),
-      ownerDid: z6.string().min(1).optional(),
-      space: z6.string().min(1).optional(),
-      session: z6.object({
-        present: z6.boolean(),
-        expired: z6.boolean().nullable(),
-        expiresAt: z6.string().datetime({ offset: true }).nullable()
+      operatorType: z7.enum(["human", "agent"]).optional(),
+      principalDid: z7.string().min(1).optional(),
+      sessionDid: z7.string().min(1).optional(),
+      ownerDid: z7.string().min(1).optional(),
+      space: z7.string().min(1).optional(),
+      session: z7.object({
+        present: z7.boolean(),
+        expired: z7.boolean().nullable(),
+        expiresAt: z7.string().datetime({ offset: true }).nullable()
       }).strict(),
-      liveAdditionalDelegationCount: z6.number().int().nonnegative()
+      liveAdditionalDelegationCount: z7.number().int().nonnegative()
     }).strict();
     STATUS_POSTURES = [
       "owner-openkey",
@@ -8582,6 +9569,7 @@ function registeredOperationDefinitions() {
     ...statusOperationDefinitions,
     ...authOperationDefinitions,
     ...explorationOperationDefinitions,
+    ...sqlOperationDefinitions,
     ...secretsGetOperationDefinitions
   ]);
   return operationDefinitions;
@@ -8614,6 +9602,7 @@ var init_registry = __esm({
     init_auth();
     init_exploration();
     init_secrets_get();
+    init_sql();
     init_status();
   }
 });
@@ -8693,9 +9682,9 @@ function isOperatorType(value) {
   return value === "human" || value === "agent";
 }
 function isStoredProfile(value) {
-  return isRecord4(value) && isNonEmptyString(value.name) && isNonEmptyString(value.host) && typeof value.chainId === "number" && Number.isFinite(value.chainId) && isNonEmptyString(value.spaceName) && isNonEmptyString(value.did) && isNonEmptyString(value.createdAt) && isOptionalNonEmptyString(value.sessionDid) && isOptionalNonEmptyString(value.ownerDid) && isOptionalNonEmptyString(value.spaceId) && isOptionalPosture(value.posture) && isOptionalOperatorType(value.operatorType) && isOptionalAuthMethod(value.authMethod) && isOptionalNonEmptyString(value.defaultSpace) && isOptionalNonEmptyString(value.privateKey) && isOptionalNonEmptyString(value.address) && isOptionalNonEmptyString(value.openkeyHost);
+  return isRecord5(value) && isNonEmptyString(value.name) && isNonEmptyString(value.host) && typeof value.chainId === "number" && Number.isFinite(value.chainId) && isNonEmptyString(value.spaceName) && isNonEmptyString(value.did) && isNonEmptyString(value.createdAt) && isOptionalNonEmptyString(value.sessionDid) && isOptionalNonEmptyString(value.ownerDid) && isOptionalNonEmptyString(value.spaceId) && isOptionalPosture(value.posture) && isOptionalOperatorType(value.operatorType) && isOptionalAuthMethod(value.authMethod) && isOptionalNonEmptyString(value.defaultSpace) && isOptionalNonEmptyString(value.privateKey) && isOptionalNonEmptyString(value.address) && isOptionalNonEmptyString(value.openkeyHost);
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isNonEmptyString(value) {
@@ -8860,7 +9849,7 @@ function spaceForAuthenticatedPrincipal(principal2) {
 function normalizeSession(session, key) {
   const header = session.delegationHeader;
   const jwk = hasPrivateParameter(session.jwk) ? session.jwk : key;
-  if (!isRecord5(header) || typeof header.Authorization !== "string" || typeof session.delegationCid !== "string" || typeof session.spaceId !== "string" || !hasPrivateParameter(jwk) || typeof session.verificationMethod !== "string") {
+  if (!isRecord6(header) || typeof header.Authorization !== "string" || typeof session.delegationCid !== "string" || typeof session.spaceId !== "string" || !hasPrivateParameter(jwk) || typeof session.verificationMethod !== "string") {
     return void 0;
   }
   return {
@@ -8878,7 +9867,7 @@ function normalizeSession(session, key) {
 }
 function normalizeStoredDelegation(entry) {
   const raw = entry.delegation;
-  if (!isRecord5(raw) || !isRecord5(raw.delegationHeader)) return void 0;
+  if (!isRecord6(raw) || !isRecord6(raw.delegationHeader)) return void 0;
   const expiry = parseExpiry2(raw.expiry);
   if (expiry === void 0 || typeof raw.cid !== "string" || typeof raw.spaceId !== "string" || typeof raw.path !== "string" || !Array.isArray(raw.actions) || !raw.actions.every((action) => typeof action === "string") || typeof raw.delegateDID !== "string" || typeof raw.ownerAddress !== "string" || typeof raw.chainId !== "number" || typeof raw.delegationHeader.Authorization !== "string") {
     return void 0;
@@ -8890,13 +9879,13 @@ function parseExpiry2(value) {
   return expiry !== void 0 && !Number.isNaN(expiry.getTime()) ? expiry : void 0;
 }
 function hasPrivateParameter(value) {
-  return isRecord5(value) && typeof value.d === "string" && value.d.length > 0;
+  return isRecord6(value) && typeof value.d === "string" && value.d.length > 0;
 }
 function normalizeDid(value) {
   if (typeof value !== "string" || value.length === 0) return void 0;
   return value.split("#", 1)[0];
 }
-function isRecord5(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function failed(context, error) {
@@ -9301,9 +10290,9 @@ async function invokeOperationWithLocalAuthorityRetry(operationId, operationVers
       )
     );
   }
-  const runtimeContext2 = prepared.runtimeResolution.context;
-  if (runtimeContext2.runtime === void 0) return internalOperationErrorResult(prepared);
-  const operationContext = runtimeContext2;
+  const runtimeContext3 = prepared.runtimeResolution.context;
+  if (runtimeContext3.runtime === void 0) return internalOperationErrorResult(prepared);
+  const operationContext = runtimeContext3;
   let planned;
   try {
     planned = exactCapabilities2(await prepared.definition.authority(
@@ -9508,14 +10497,14 @@ async function prepareInvocation(operationId, operationVersion, invocationTarget
 }
 async function executePreparedInvocation(prepared, options = {}) {
   const { operation, definition, parsedInput, runtimeResolution } = prepared;
-  const runtimeContext2 = runtimeResolution.context.runtime === void 0 ? void 0 : runtimeResolution.context;
-  const resolveSpace2 = runtimeContext2 === void 0 ? void 0 : operationSpaceResolver(
-    runtimeContext2.runtime.node,
-    runtimeContext2.summary.space
+  const runtimeContext3 = runtimeResolution.context.runtime === void 0 ? void 0 : runtimeResolution.context;
+  const resolveSpace2 = runtimeContext3 === void 0 ? void 0 : operationSpaceResolver(
+    runtimeContext3.runtime.node,
+    runtimeContext3.summary.space
   );
   try {
     const planned = await definition.authority(
-      runtimeContext2 ?? runtimeResolution.context,
+      runtimeContext3 ?? runtimeResolution.context,
       parsedInput.data
     );
     const required = exactCapabilities2(planned);
@@ -9530,12 +10519,12 @@ async function executePreparedInvocation(prepared, options = {}) {
       );
     }
     const evaluation = evaluateOperationAuthority(
-      runtimeContext2?.runtime.granted ?? [],
+      runtimeContext3?.runtime.granted ?? [],
       required,
       resolveSpace2
     );
     if (!evaluation.satisfied) {
-      if (runtimeContext2 === void 0) {
+      if (runtimeContext3 === void 0) {
         return errorResult(
           operation,
           runtimeResolution.context.summary,
@@ -9545,13 +10534,13 @@ async function executePreparedInvocation(prepared, options = {}) {
       if (options.deferAuthorityRequest) {
         try {
           const request = buildPermissionRequestArtifact({
-            profile: runtimeContext2.summary.profile,
-            host: runtimeContext2.summary.host,
-            sessionDid: runtimeContext2.summary.sessionDid,
-            posture: runtimeContext2.summary.posture,
-            operatorType: runtimeContext2.summary.operatorType ?? "human",
-            ...runtimeContext2.summary.ownerDid === void 0 ? {} : { ownerDid: runtimeContext2.summary.ownerDid },
-            ...runtimeContext2.summary.space === void 0 ? {} : { spaceId: runtimeContext2.summary.space },
+            profile: runtimeContext3.summary.profile,
+            host: runtimeContext3.summary.host,
+            sessionDid: runtimeContext3.summary.sessionDid,
+            posture: runtimeContext3.summary.posture,
+            operatorType: runtimeContext3.summary.operatorType ?? "human",
+            ...runtimeContext3.summary.ownerDid === void 0 ? {} : { ownerDid: runtimeContext3.summary.ownerDid },
+            ...runtimeContext3.summary.space === void 0 ? {} : { spaceId: runtimeContext3.summary.space },
             missing: evaluation.missing
           });
           return authorityRequiredResult(
@@ -9560,7 +10549,7 @@ async function executePreparedInvocation(prepared, options = {}) {
             parsedInput.data,
             request,
             evaluation.missing,
-            runtimeContext2.runtime.node
+            runtimeContext3.runtime.node
           );
         } catch {
           return errorResult(
@@ -9571,7 +10560,7 @@ async function executePreparedInvocation(prepared, options = {}) {
         }
       }
       const authority = await persistAuthorityRequest(
-        runtimeContext2,
+        runtimeContext3,
         evaluation.missing
       );
       if (authority.status === "error") {
@@ -9587,7 +10576,7 @@ async function executePreparedInvocation(prepared, options = {}) {
         parsedInput.data,
         authority.request,
         authority.missing,
-        runtimeContext2.runtime.node
+        runtimeContext3.runtime.node
       );
     }
     const outcome = await definition.execute(
@@ -9630,7 +10619,7 @@ async function executePreparedInvocation(prepared, options = {}) {
             )
           );
         }
-        if (runtimeContext2 === void 0) {
+        if (runtimeContext3 === void 0) {
           return errorResult(
             operation,
             runtimeResolution.context.summary,
@@ -9640,13 +10629,13 @@ async function executePreparedInvocation(prepared, options = {}) {
         if (options.deferAuthorityRequest) {
           try {
             const request = buildPermissionRequestArtifact({
-              profile: runtimeContext2.summary.profile,
-              host: runtimeContext2.summary.host,
-              sessionDid: runtimeContext2.summary.sessionDid,
-              posture: runtimeContext2.summary.posture,
-              operatorType: runtimeContext2.summary.operatorType ?? "human",
-              ...runtimeContext2.summary.ownerDid === void 0 ? {} : { ownerDid: runtimeContext2.summary.ownerDid },
-              ...runtimeContext2.summary.space === void 0 ? {} : { spaceId: runtimeContext2.summary.space },
+              profile: runtimeContext3.summary.profile,
+              host: runtimeContext3.summary.host,
+              sessionDid: runtimeContext3.summary.sessionDid,
+              posture: runtimeContext3.summary.posture,
+              operatorType: runtimeContext3.summary.operatorType ?? "human",
+              ...runtimeContext3.summary.ownerDid === void 0 ? {} : { ownerDid: runtimeContext3.summary.ownerDid },
+              ...runtimeContext3.summary.space === void 0 ? {} : { spaceId: runtimeContext3.summary.space },
               missing: hinted
             });
             return authorityRequiredResult(
@@ -9655,7 +10644,7 @@ async function executePreparedInvocation(prepared, options = {}) {
               parsedInput.data,
               request,
               hinted,
-              runtimeContext2.runtime.node,
+              runtimeContext3.runtime.node,
               outcome.requiresCallerInput ?? false
             );
           } catch {
@@ -9667,7 +10656,7 @@ async function executePreparedInvocation(prepared, options = {}) {
           }
         }
         const authority = await persistAuthorityRequest(
-          runtimeContext2,
+          runtimeContext3,
           hinted,
           true
         );
@@ -9684,7 +10673,7 @@ async function executePreparedInvocation(prepared, options = {}) {
           parsedInput.data,
           authority.request,
           authority.missing,
-          runtimeContext2.runtime.node,
+          runtimeContext3.runtime.node,
           outcome.requiresCallerInput ?? false
         );
       }