@tinycloud/operations 0.7.11-beta.2 → 0.8.0

package/dist/artifacts.d.cts

@@ -2,7 +2,7 @@ import { PermissionEntry } from '@tinycloud/sdk-core';
 import { z } from 'zod';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.cjs';
 export { e as evaluateAuthority } from './authority-ofwbEqmj.cjs';
-import { T as TinyCloudPosture, O as OperationOperatorType } from './contract-DrtFhVsg.cjs';
+import { T as TinyCloudPosture, O as OperationOperatorType } from './contract-BGJGxuGr.cjs';
 
 /** The shared wire schema for SDK PermissionEntry values, including signed ReCap caveats. */
 declare const PermissionEntrySchema: z.ZodObject<{

package/dist/artifacts.d.ts

@@ -2,7 +2,7 @@ import { PermissionEntry } from '@tinycloud/sdk-core';
 import { z } from 'zod';
 import { O as OperationSpaceResolver } from './authority-ofwbEqmj.js';
 export { e as evaluateAuthority } from './authority-ofwbEqmj.js';
-import { T as TinyCloudPosture, O as OperationOperatorType } from './contract-DrtFhVsg.js';
+import { T as TinyCloudPosture, O as OperationOperatorType } from './contract-BGJGxuGr.js';
 
 /** The shared wire schema for SDK PermissionEntry values, including signed ReCap caveats. */
 declare const PermissionEntrySchema: z.ZodObject<{

package/dist/cli-runtime.cjs

@@ -344,6 +344,8 @@ var init_errors2 = __esm({
       "SQL_EXECUTION_FAILED",
       "SQL_RESULT_LIMIT_EXCEEDED",
       "SQL_VALUE_UNSAFE",
+      "READ_SOURCE_CHANGED",
+      "READ_CONTEXT_MISMATCH",
       "SECRET_READ_FAILED",
       "SECRET_DECRYPT_FAILED",
       "OUTPUT_INVALID",
@@ -7807,10 +7809,20 @@ async function executeKvList(context, input) {
     const space = resolveGenericKvSpace(runtime, input.space);
     const result = await genericKv(runtime, space).list({
       ...input.prefix === void 0 ? {} : { prefix: input.prefix },
+      ...input.cursor === void 0 ? {} : { cursor: input.cursor },
       limit: input.limit ?? DEFAULT_KV_LIST_LIMIT
     });
-    if (!result.ok) return kvFailure(result.error, "list KV keys");
+    if (!result.ok) {
+      if (input.cursor !== void 0 && result.error.meta?.status === 400) {
+        return {
+          status: "error",
+          error: operationError("INPUT_INVALID", "The node rejected the KV listing cursor. Restart the listing without a cursor and discard earlier pages rather than combining different listings.")
+        };
+      }
+      return kvFailure(result.error, "list KV keys");
+    }
     const keys = [...result.data.keys];
+    const nextCursor = result.data.nextCursor ?? null;
     return {
       status: "ok",
       output: {
@@ -7818,7 +7830,8 @@ async function executeKvList(context, input) {
         prefix: input.prefix ?? "",
         keys,
         count: keys.length,
-        truncated: result.data.truncated ?? false
+        truncated: result.data.truncated === true || nextCursor !== null,
+        nextCursor
       }
     };
   } catch (error) {
@@ -8233,14 +8246,16 @@ var init_exploration = __esm({
     KvListInputSchema = import_zod7.z.object({
       space: SpaceSchema2,
       prefix: PrefixSchema2.optional(),
-      limit: LimitSchema.optional()
+      limit: LimitSchema.optional(),
+      cursor: import_zod7.z.string().optional()
     }).strict();
     KvListOutputSchema = import_zod7.z.object({
       space: import_zod7.z.string().min(1),
       prefix: import_zod7.z.string(),
       keys: import_zod7.z.array(import_zod7.z.string()),
       count: import_zod7.z.number().int().nonnegative(),
-      truncated: import_zod7.z.boolean()
+      truncated: import_zod7.z.boolean(),
+      nextCursor: import_zod7.z.string().nullable()
     }).strict();
     KvGetInputSchema = import_zod7.z.object({
       space: SpaceSchema2,
@@ -8382,7 +8397,7 @@ var init_exploration = __esm({
         id: "tinycloud.kv.list",
         version: 1,
         title: "List TinyCloud KV keys",
-        description: "List keys at one exact prefix in a delegated TinyCloud space.",
+        description: "List a bounded page of keys at the supplied prefix in one delegated TinyCloud space. Continue with nextCursor as cursor and the same space and prefix; cursors are opaque and scope-bound. nextCursor is null when unavailable. If truncated is true without a cursor, coverage is incomplete: narrow the prefix rather than guessing offsets.",
         input: KvListInputSchema,
         output: KvListOutputSchema,
         effects: ["read"],
@@ -8397,7 +8412,7 @@ var init_exploration = __esm({
         id: "tinycloud.kv.get",
         version: 1,
         title: "Get a TinyCloud KV value",
-        description: "Read one exact key with a node-enforced one MiB response limit.",
+        description: "Read one exact key with a one MiB acquired-body limit in bytes. Hosted MCP separately caps the serialized response envelope at 100,000 UTF-16 code units; a value below one MiB can still exceed that cap. Use tinycloud_read for bounded, byte-preserving delivery within the acquisition limit.",
         input: KvGetInputSchema,
         output: KvGetOutputSchema,
         effects: ["read"],
@@ -8955,6 +8970,320 @@ var init_knowledge = __esm({
   }
 });
 
+// src/operations/read.ts
+async function planRead(context, input) {
+  return input.resource.kind === "kv" ? planKvGet(context, input.resource) : planSqlRead(context, input.resource);
+}
+async function executeRead2(context, input) {
+  try {
+    const runtime = runtimeContext2(context);
+    const requirements = await planRead(runtime, input);
+    const space = requirements[0]?.space;
+    if (typeof space !== "string") throw new TypeError("Read target space is unavailable.");
+    const ownerDid = (0, import_node_sdk2.parseSpaceUri)(space)?.owner;
+    if (ownerDid === void 0) return invalidInput2("The read target must resolve to an owner-scoped space.");
+    const resource = resourceIdentity(input.resource, space);
+    const expected = input.expected;
+    const offset = input.offset ?? 0;
+    if (offset > 0 && expected === void 0) {
+      return invalidInput2("A nonzero byte offset requires the previous page's expected binding.");
+    }
+    if (expected !== void 0 && (expected.host !== context.summary.host || expected.ownerDid !== ownerDid || jcsCanonicalize(expected.resource) !== jcsCanonicalize(resource))) {
+      return {
+        status: "error",
+        error: operationError("READ_CONTEXT_MISMATCH", "The expected read binding identifies a different host, owner, space, or resource.")
+      };
+    }
+    let bytes;
+    let etag = null;
+    if (input.resource.kind === "kv") {
+      const result = await genericKv(runtime, space).get(input.resource.key, {
+        binary: true,
+        maxResponseBytes: MAX_KV_VALUE_BYTES
+      });
+      if (!result.ok) return kvFailure(result.error, "read the KV value");
+      bytes = result.data.data;
+      if (bytes.byteLength > MAX_KV_VALUE_BYTES) {
+        return kvFailure({ code: "KV_RESPONSE_TOO_LARGE" }, "read the KV value");
+      }
+      etag = result.data.headers.etag ?? null;
+    } else {
+      const result = await executeSqlQuery(context, input.resource);
+      if (result.status !== "ok") return result;
+      bytes = Buffer.from(JSON.stringify(result.output), "utf8");
+    }
+    const acquiredAt = (/* @__PURE__ */ new Date()).toISOString();
+    const sha256 = (0, import_node_crypto3.createHash)("sha256").update(bytes).digest("hex");
+    if (expected !== void 0 && (expected.sha256 !== sha256 || expected.totalBytes !== bytes.byteLength)) {
+      return {
+        status: "error",
+        error: operationError("READ_SOURCE_CHANGED", "The acquired bytes no longer match the expected digest and byte length. Start a new read explicitly to accept a new source revision.")
+      };
+    }
+    if (offset > bytes.byteLength) return invalidInput2("The byte offset exceeds the acquired body length.");
+    const validUtf8 = input.encoding === "base64" ? false : (0, import_node_buffer.isUtf8)(bytes);
+    const encoding = input.encoding ?? (validUtf8 ? "utf8" : "base64");
+    if (encoding === "utf8" && !validUtf8) {
+      return invalidInput2("The acquired body is not valid UTF-8. Request base64 to preserve its original bytes.");
+    }
+    if (encoding === "utf8" && isContinuationByte(bytes[offset])) {
+      return invalidInput2("The byte offset is inside a UTF-8 character.");
+    }
+    const pageBytes = input.pageBytes ?? MAX_PAGE_BYTES;
+    const binding = {
+      host: context.summary.host,
+      ownerDid,
+      resource,
+      sha256,
+      totalBytes: bytes.byteLength
+    };
+    const provenance = {
+      digestAlgorithm: "sha256",
+      representation: input.resource.kind === "kv" ? "original-bytes" : "normalized-sql-result-json",
+      acquiredAt,
+      etag
+    };
+    let end = Math.min(offset + pageBytes, bytes.byteLength);
+    for (; ; ) {
+      if (encoding === "utf8") {
+        while (end > offset && isContinuationByte(bytes[end])) end--;
+      }
+      if (end === offset && offset < bytes.byteLength) {
+        return invalidInput2("The requested UTF-8 character or resource provenance cannot fit the bounded page. Use a larger pageBytes (at least 4 for UTF-8), base64, or a shorter locator.");
+      }
+      const value = Buffer.from(bytes.buffer, bytes.byteOffset + offset, end - offset).toString(
+        encoding === "utf8" ? "utf8" : "base64"
+      );
+      const complete = end === bytes.byteLength;
+      const output = {
+        value,
+        encoding,
+        range: { unit: "bytes", start: offset, end },
+        binding,
+        provenance,
+        complete,
+        continuation: complete ? null : { offset: end, pageBytes, encoding, expected: binding }
+      };
+      if (Buffer.byteLength(JSON.stringify(output), "utf8") < MAX_PAGE_OUTPUT_BYTES) {
+        return { status: "ok", output };
+      }
+      if (end === offset) {
+        return invalidInput2("The resource provenance cannot fit the bounded page; use a shorter locator.");
+      }
+      end = offset + Math.floor((end - offset) / 2);
+    }
+  } catch (error) {
+    if (error instanceof OperationInvocationError) return { status: "error", error: error.operationError };
+    return caughtKvFailure(error, "read the resource");
+  }
+}
+function resourceIdentity(resource, space) {
+  if (resource.kind === "kv") return { kind: "kv", space, key: resource.key };
+  const query = { database: resource.database, sql: resource.sql };
+  if (resource.params !== void 0) query.params = resource.params;
+  if (resource.maxRows !== void 0) query.maxRows = resource.maxRows;
+  if (resource.maxBytes !== void 0) query.maxBytes = resource.maxBytes;
+  return {
+    kind: "sql",
+    space,
+    database: resource.database,
+    querySha256: (0, import_node_crypto3.createHash)("sha256").update(jcsCanonicalize(query), "utf8").digest("hex")
+  };
+}
+function isContinuationByte(byte) {
+  return byte !== void 0 && (byte & 192) === 128;
+}
+function invalidInput2(message) {
+  return { status: "error", error: operationError("INPUT_INVALID", message) };
+}
+var import_node_buffer, import_node_crypto3, import_node_sdk2, import_zod9, MAX_PAGE_BYTES, MAX_PAGE_OUTPUT_BYTES, Sha256Schema, ByteOffsetSchema, EncodingSchema, PageBytesSchema, ResourceSchema, ResourceIdentitySchema, ReadBindingSchema, ContinuationSchema, ReadInputSchema2, ReadOutputSchema2, readOperationDefinitions;
+var init_read = __esm({
+  "src/operations/read.ts"() {
+    "use strict";
+    import_node_buffer = require("buffer");
+    import_node_crypto3 = require("crypto");
+    import_node_sdk2 = require("@tinycloud/node-sdk");
+    init_jcs();
+    import_zod9 = require("zod");
+    init_errors2();
+    init_exploration();
+    init_sql();
+    MAX_PAGE_BYTES = 12 * 1024;
+    MAX_PAGE_OUTPUT_BYTES = 8e4;
+    Sha256Schema = import_zod9.z.string().regex(/^[0-9a-f]{64}$/);
+    ByteOffsetSchema = import_zod9.z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+    EncodingSchema = import_zod9.z.enum(["utf8", "base64"]);
+    PageBytesSchema = import_zod9.z.number().int().min(1).max(MAX_PAGE_BYTES);
+    ResourceSchema = import_zod9.z.discriminatedUnion("kind", [
+      KvGetInputSchema.omit({ representation: true }).extend({ kind: import_zod9.z.literal("kv") }),
+      SqlQueryInputSchema.extend({ kind: import_zod9.z.literal("sql") })
+    ]);
+    ResourceIdentitySchema = import_zod9.z.discriminatedUnion("kind", [
+      import_zod9.z.object({
+        kind: import_zod9.z.literal("kv"),
+        space: import_zod9.z.string().min(1),
+        key: import_zod9.z.string().min(1)
+      }).strict(),
+      import_zod9.z.object({
+        kind: import_zod9.z.literal("sql"),
+        space: import_zod9.z.string().min(1),
+        database: import_zod9.z.string().min(1),
+        querySha256: Sha256Schema
+      }).strict()
+    ]);
+    ReadBindingSchema = import_zod9.z.object({
+      host: import_zod9.z.string().min(1),
+      ownerDid: import_zod9.z.string().min(1),
+      resource: ResourceIdentitySchema,
+      sha256: Sha256Schema,
+      totalBytes: ByteOffsetSchema
+    }).strict();
+    ContinuationSchema = import_zod9.z.object({
+      offset: ByteOffsetSchema,
+      pageBytes: PageBytesSchema,
+      encoding: EncodingSchema,
+      expected: ReadBindingSchema
+    }).strict();
+    ReadInputSchema2 = import_zod9.z.object({
+      resource: ResourceSchema,
+      offset: ByteOffsetSchema.optional(),
+      pageBytes: PageBytesSchema.optional(),
+      encoding: EncodingSchema.optional(),
+      expected: ReadBindingSchema.optional()
+    }).strict().superRefine((input, context) => {
+      if ((input.offset ?? 0) > 0 && input.expected === void 0) {
+        context.addIssue({
+          code: import_zod9.z.ZodIssueCode.custom,
+          path: ["expected"],
+          message: "A nonzero byte offset requires the previous page's expected binding."
+        });
+      }
+    });
+    ReadOutputSchema2 = import_zod9.z.object({
+      value: import_zod9.z.string(),
+      encoding: EncodingSchema,
+      range: import_zod9.z.object({
+        unit: import_zod9.z.literal("bytes"),
+        start: ByteOffsetSchema,
+        end: ByteOffsetSchema
+      }).strict(),
+      binding: ReadBindingSchema,
+      provenance: import_zod9.z.object({
+        digestAlgorithm: import_zod9.z.literal("sha256"),
+        representation: import_zod9.z.enum(["original-bytes", "normalized-sql-result-json"]),
+        acquiredAt: import_zod9.z.string().datetime(),
+        etag: import_zod9.z.string().nullable()
+      }).strict(),
+      complete: import_zod9.z.boolean(),
+      continuation: ContinuationSchema.nullable()
+    }).strict();
+    readOperationDefinitions = [{
+      id: "tinycloud.read",
+      version: 1,
+      title: "Read complete TinyCloud resource bytes in bounded pages",
+      description: "Read original KV bytes or normalized read-only SQL result JSON in digest-bound byte pages. Every call reacquires the resource with current authority. Replay the original resource with continuation fields; a recipient can validate the first page with expected: binding. SQL locators require retaining the original query and parameters. Paging does not increase acquisition limits.",
+      input: ReadInputSchema2,
+      output: ReadOutputSchema2,
+      effects: ["read"],
+      runtime: "authenticated",
+      postures: ["owner-openkey", "delegate-session", "local-owner-key"],
+      exposure: {
+        cli: { status: "excluded", reason: "Existing CLI KV and SQL reads remain the CLI surface." },
+        mcp: { status: "required" },
+        skill: { status: "required" },
+        docs: { status: "required" }
+      },
+      sensitivity: { input: ["/resource", "/expected"], output: ["/value", "/binding", "/continuation"] },
+      authority: planRead,
+      execute: executeRead2
+    }];
+  }
+});
+
+// src/operations/read-scope.ts
+function scopeSpace(context, input) {
+  const space = resolveGenericKvSpace(context, input.space);
+  const ownSpace = resolveGenericKvSpace(context, space.split(":").at(-1));
+  if (space !== ownSpace) {
+    throw new OperationInvocationError(operationError(
+      "INPUT_INVALID",
+      "Read-scope approval must target the selected owner's space."
+    ));
+  }
+  return space;
+}
+async function planReadScope(context, input) {
+  const space = scopeSpace(context, input);
+  const permissions = [];
+  for (const path of input.kvPrefixes ?? []) {
+    permissions.push({
+      service: "tinycloud.kv",
+      space,
+      path,
+      actions: ["tinycloud.kv/get", "tinycloud.kv/metadata", "tinycloud.kv/list"]
+    });
+  }
+  for (const path of input.databases ?? []) {
+    permissions.push({ service: "tinycloud.sql", space, path, actions: ["tinycloud.sql/read"] });
+  }
+  return canonicalizeCapabilities(permissions);
+}
+var import_zod10, InputSchema, OutputSchema, readScopeOperationDefinitions;
+var init_read_scope = __esm({
+  "src/operations/read-scope.ts"() {
+    "use strict";
+    import_zod10 = require("zod");
+    init_artifacts();
+    init_authority();
+    init_errors2();
+    init_exploration();
+    init_sql();
+    InputSchema = import_zod10.z.object({
+      space: KvGetInputSchema.shape.space,
+      kvPrefixes: import_zod10.z.array(import_zod10.z.string().max(2048).refine(
+        (prefix) => (prefix === "" || prefix.endsWith("/")) && prefix !== "/" && !prefix.includes("*") && !/[\u0000-\u001f\u007f]/.test(prefix),
+        "Select a recursive slash-ended KV prefix, or explicitly select the empty prefix for the whole space."
+      )).min(1).max(20).optional(),
+      databases: import_zod10.z.array(SqlQueryInputSchema.shape.database).min(1).max(20).optional()
+    }).strict().superRefine((input, issue) => {
+      if (input.kvPrefixes === void 0 && input.databases === void 0) {
+        issue.addIssue({ code: import_zod10.z.ZodIssueCode.custom, message: "Select at least one KV prefix or exact database." });
+      }
+    });
+    OutputSchema = import_zod10.z.object({
+      space: import_zod10.z.string().min(1),
+      permissions: import_zod10.z.array(PermissionEntrySchema).min(1),
+      access: import_zod10.z.literal("not-tested")
+    }).strict();
+    readScopeOperationDefinitions = [{
+      id: "tinycloud.auth.read_scope",
+      version: 1,
+      title: "Approve a reusable TinyCloud read scope",
+      description: "Explicitly select recursive KV prefixes and/or exact read-only databases in one existing owner space. Missing authority uses the normal request-bound approval flow. Empty KV prefix explicitly requests the whole space. No write authority is requested; ordinary GET/HEAD requests stay exact. Future children are covered only until grant expiry/revocation. Success reports capability coverage, not a storage read; then use KV/SQL discovery or tinycloud_read.",
+      input: InputSchema,
+      output: OutputSchema,
+      effects: ["read"],
+      runtime: "authenticated",
+      postures: ["owner-openkey", "delegate-session", "local-owner-key"],
+      exposure: {
+        cli: { status: "excluded", reason: "The CLI retains its explicit permission-manifest/request flow; SDK callers use invokeOperation." },
+        mcp: { status: "required" },
+        skill: { status: "required" },
+        docs: { status: "required" }
+      },
+      sensitivity: { input: ["/kvPrefixes", "/databases"], output: ["/permissions"] },
+      authority: planReadScope,
+      execute: async (context, input) => {
+        const runtime = runtimeContext2(context);
+        return {
+          status: "ok",
+          output: { space: scopeSpace(runtime, input), permissions: await planReadScope(runtime, input), access: "not-tested" }
+        };
+      }
+    }];
+  }
+});
+
 // src/secret-request.ts
 function canonicalSecretRequestOwner(did) {
   const match = typeof did === "string" ? OWNER_RE.exec(did) : null;
@@ -9321,28 +9650,28 @@ function resolveEncryptionNetworkId(node, space) {
     )
   );
 }
-var import_zod9, SecretsGetInputSchema, SecretsGetOutputSchema, SECRETS_GET_POSTURES, SECRETS_GET_EXPOSURE, SECRETS_GET_SENSITIVITY, secretsGetOperationDefinition, secretsGetOperationDefinitions;
+var import_zod11, SecretsGetInputSchema, SecretsGetOutputSchema, SECRETS_GET_POSTURES, SECRETS_GET_EXPOSURE, SECRETS_GET_SENSITIVITY, secretsGetOperationDefinition, secretsGetOperationDefinitions;
 var init_secrets_get = __esm({
   "src/operations/secrets-get.ts"() {
     "use strict";
-    import_zod9 = require("zod");
+    import_zod11 = require("zod");
     init_cli_name();
     init_errors2();
     init_secret_request();
     init_secrets();
-    SecretsGetInputSchema = import_zod9.z.object({
-      name: import_zod9.z.string(),
-      scope: import_zod9.z.string().optional(),
-      space: import_zod9.z.string().optional()
+    SecretsGetInputSchema = import_zod11.z.object({
+      name: import_zod11.z.string(),
+      scope: import_zod11.z.string().optional(),
+      space: import_zod11.z.string().optional()
     }).strict().superRefine((input, context) => {
       try {
         resolveSecretReference(input);
       } catch {
-        context.addIssue({ code: import_zod9.z.ZodIssueCode.custom, message: "Invalid secret reference." });
+        context.addIssue({ code: import_zod11.z.ZodIssueCode.custom, message: "Invalid secret reference." });
       }
     }).transform(normalizeSecretsGetInput);
-    SecretsGetOutputSchema = import_zod9.z.object({
-      value: import_zod9.z.string()
+    SecretsGetOutputSchema = import_zod11.z.object({
+      value: import_zod11.z.string()
     }).strict();
     SECRETS_GET_POSTURES = [
       "owner-openkey",
@@ -9467,11 +9796,11 @@ async function executeSecretsStatus(context, input) {
     }
   };
 }
-var import_zod10, nodeSdk4, PROBE_TIMEOUT_MS, SECRETS_STATUS_DEADLINE_MS, SecretsStatusInputSchema, SecretSetupSchema, SecretsStatusOutputSchema, SECRETS_STATUS_POSTURES, SECRETS_STATUS_EXPOSURE, SECRETS_STATUS_SENSITIVITY, secretsStatusOperationDefinition, secretsStatusOperationDefinitions;
+var import_zod12, nodeSdk4, PROBE_TIMEOUT_MS, SECRETS_STATUS_DEADLINE_MS, SecretsStatusInputSchema, SecretSetupSchema, SecretsStatusOutputSchema, SECRETS_STATUS_POSTURES, SECRETS_STATUS_EXPOSURE, SECRETS_STATUS_SENSITIVITY, secretsStatusOperationDefinition, secretsStatusOperationDefinitions;
 var init_secrets_status = __esm({
   "src/operations/secrets-status.ts"() {
     "use strict";
-    import_zod10 = require("zod");
+    import_zod12 = require("zod");
     nodeSdk4 = __toESM(require("@tinycloud/node-sdk"), 1);
     init_errors2();
     init_kv_failure();
@@ -9480,27 +9809,27 @@ var init_secrets_status = __esm({
     init_secrets();
     PROBE_TIMEOUT_MS = 15e3;
     SECRETS_STATUS_DEADLINE_MS = 18e3;
-    SecretsStatusInputSchema = import_zod10.z.object({
-      names: import_zod10.z.array(import_zod10.z.string()),
-      scope: import_zod10.z.string().optional(),
-      owner: import_zod10.z.string().optional()
+    SecretsStatusInputSchema = import_zod12.z.object({
+      names: import_zod12.z.array(import_zod12.z.string()),
+      scope: import_zod12.z.string().optional(),
+      owner: import_zod12.z.string().optional()
     }).strict().superRefine((input, context) => {
       try {
         validSecretNames(input.names);
       } catch {
-        context.addIssue({ code: import_zod10.z.ZodIssueCode.custom, path: ["names"], message: "Invalid secret names." });
+        context.addIssue({ code: import_zod12.z.ZodIssueCode.custom, path: ["names"], message: "Invalid secret names." });
       }
       try {
         const scope = canonicalizeSecretScope(input.scope);
         if (scope !== void 0 && !isValidSecretRequestScope(scope)) throw new Error("invalid scope");
       } catch {
-        context.addIssue({ code: import_zod10.z.ZodIssueCode.custom, path: ["scope"], message: "Invalid secret scope." });
+        context.addIssue({ code: import_zod12.z.ZodIssueCode.custom, path: ["scope"], message: "Invalid secret scope." });
       }
       if (input.owner !== void 0) {
         try {
           canonicalSecretRequestOwner(input.owner);
         } catch {
-          context.addIssue({ code: import_zod10.z.ZodIssueCode.custom, path: ["owner"], message: "Invalid owner." });
+          context.addIssue({ code: import_zod12.z.ZodIssueCode.custom, path: ["owner"], message: "Invalid owner." });
         }
       }
     }).transform((input) => {
@@ -9511,23 +9840,23 @@ var init_secrets_status = __esm({
         ...input.owner === void 0 ? {} : { owner: canonicalSecretRequestOwner(input.owner) }
       };
     });
-    SecretSetupSchema = import_zod10.z.object({
-      url: import_zod10.z.string().url(),
-      names: import_zod10.z.array(import_zod10.z.string()).min(1),
-      scope: import_zod10.z.string().optional(),
-      owner: import_zod10.z.string(),
-      action: import_zod10.z.literal("add_secret")
+    SecretSetupSchema = import_zod12.z.object({
+      url: import_zod12.z.string().url(),
+      names: import_zod12.z.array(import_zod12.z.string()).min(1),
+      scope: import_zod12.z.string().optional(),
+      owner: import_zod12.z.string(),
+      action: import_zod12.z.literal("add_secret")
     }).strict();
-    SecretsStatusOutputSchema = import_zod10.z.object({
-      status: import_zod10.z.enum(["ready", "pending", "consent_required"]),
-      owner: import_zod10.z.string(),
-      names: import_zod10.z.array(import_zod10.z.string()).min(1),
-      scope: import_zod10.z.string().optional(),
-      present: import_zod10.z.array(import_zod10.z.string()),
-      pending: import_zod10.z.array(import_zod10.z.string()),
-      denied: import_zod10.z.array(import_zod10.z.string()),
+    SecretsStatusOutputSchema = import_zod12.z.object({
+      status: import_zod12.z.enum(["ready", "pending", "consent_required"]),
+      owner: import_zod12.z.string(),
+      names: import_zod12.z.array(import_zod12.z.string()).min(1),
+      scope: import_zod12.z.string().optional(),
+      present: import_zod12.z.array(import_zod12.z.string()),
+      pending: import_zod12.z.array(import_zod12.z.string()),
+      denied: import_zod12.z.array(import_zod12.z.string()),
       setup: SecretSetupSchema.optional(),
-      hint: import_zod10.z.string().optional()
+      hint: import_zod12.z.string().optional()
     }).strict();
     SECRETS_STATUS_POSTURES = [
       "owner-openkey",
@@ -9972,35 +10301,35 @@ function profileNotFound(profile) {
 function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var import_zod11, StatusInputSchema, StatusOutputSchema, STATUS_POSTURES, STATUS_EXPOSURE, STATUS_SENSITIVITY, statusOperationDefinitions;
+var import_zod13, StatusInputSchema, StatusOutputSchema, STATUS_POSTURES, STATUS_EXPOSURE, STATUS_SENSITIVITY, statusOperationDefinitions;
 var init_status = __esm({
   "src/operations/status.ts"() {
     "use strict";
-    import_zod11 = require("zod");
+    import_zod13 = require("zod");
     init_delegation_binding();
     init_errors2();
     init_state();
-    StatusInputSchema = import_zod11.z.object({}).strict();
-    StatusOutputSchema = import_zod11.z.object({
-      profile: import_zod11.z.string().min(1),
-      host: import_zod11.z.string().min(1),
-      posture: import_zod11.z.enum([
+    StatusInputSchema = import_zod13.z.object({}).strict();
+    StatusOutputSchema = import_zod13.z.object({
+      profile: import_zod13.z.string().min(1),
+      host: import_zod13.z.string().min(1),
+      posture: import_zod13.z.enum([
         "owner-openkey",
         "delegate-session",
         "local-owner-key",
         "unauthenticated"
       ]),
-      operatorType: import_zod11.z.enum(["human", "agent"]).optional(),
-      principalDid: import_zod11.z.string().min(1).optional(),
-      sessionDid: import_zod11.z.string().min(1).optional(),
-      ownerDid: import_zod11.z.string().min(1).optional(),
-      space: import_zod11.z.string().min(1).optional(),
-      session: import_zod11.z.object({
-        present: import_zod11.z.boolean(),
-        expired: import_zod11.z.boolean().nullable(),
-        expiresAt: import_zod11.z.string().datetime({ offset: true }).nullable()
+      operatorType: import_zod13.z.enum(["human", "agent"]).optional(),
+      principalDid: import_zod13.z.string().min(1).optional(),
+      sessionDid: import_zod13.z.string().min(1).optional(),
+      ownerDid: import_zod13.z.string().min(1).optional(),
+      space: import_zod13.z.string().min(1).optional(),
+      session: import_zod13.z.object({
+        present: import_zod13.z.boolean(),
+        expired: import_zod13.z.boolean().nullable(),
+        expiresAt: import_zod13.z.string().datetime({ offset: true }).nullable()
       }).strict(),
-      liveAdditionalDelegationCount: import_zod11.z.number().int().nonnegative().describe(
+      liveAdditionalDelegationCount: import_zod13.z.number().int().nonnegative().describe(
         "Stored, unexpired compact-UCAN or signed-login delegations with a valid request binding. Each still requires local proof validation and node activation before it grants authority."
       )
     }).strict();
@@ -10042,6 +10371,8 @@ function registeredOperationDefinitions() {
   operationDefinitions ?? (operationDefinitions = [
     ...statusOperationDefinitions,
     ...authOperationDefinitions,
+    ...readScopeOperationDefinitions,
+    ...readOperationDefinitions,
     ...explorationOperationDefinitions,
     ...appsOperationDefinitions,
     ...sqlOperationDefinitions,
@@ -10080,6 +10411,8 @@ var init_registry = __esm({
     init_auth();
     init_exploration();
     init_knowledge();
+    init_read();
+    init_read_scope();
     init_secrets_get();
     init_secrets_status();
     init_sql();
@@ -10525,10 +10858,10 @@ __export(cli_runtime_exports, {
 module.exports = __toCommonJS(cli_runtime_exports);
 
 // src/invoke.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto4 = require("crypto");
 var import_node_path5 = require("path");
 init_cli_name();
-var import_node_sdk2 = require("@tinycloud/node-sdk");
+var import_node_sdk3 = require("@tinycloud/node-sdk");
 init_jcs();
 init_errors2();
 init_authority();
@@ -11253,7 +11586,7 @@ function operationRetryDescriptor(operation, input, requiresCallerInput = false)
   return {
     operationId: operation.operationId,
     operationVersion: operation.operationVersion,
-    inputDigest: (0, import_node_crypto3.createHash)("sha256").update(jcsCanonicalize(input), "utf8").digest("hex"),
+    inputDigest: (0, import_node_crypto4.createHash)("sha256").update(jcsCanonicalize(input), "utf8").digest("hex"),
     requiresCallerInput
   };
 }
@@ -11353,11 +11686,11 @@ function requirementsBelongToAuthenticatedOwner(requirements, authenticatedSpace
 }
 function canonicalPkhOwner(space) {
   if (typeof space !== "string") return void 0;
-  const parsedSpace = (0, import_node_sdk2.parseSpaceUri)(space);
+  const parsedSpace = (0, import_node_sdk3.parseSpaceUri)(space);
   if (parsedSpace === null) return void 0;
   try {
-    const pkh = (0, import_node_sdk2.parsePkhDid)(parsedSpace.owner);
-    return pkh === null ? void 0 : (0, import_node_sdk2.parseSpaceUri)((0, import_node_sdk2.makePkhSpaceId)(pkh.address, pkh.chainId, parsedSpace.name))?.owner;
+    const pkh = (0, import_node_sdk3.parsePkhDid)(parsedSpace.owner);
+    return pkh === null ? void 0 : (0, import_node_sdk3.parseSpaceUri)((0, import_node_sdk3.makePkhSpaceId)(pkh.address, pkh.chainId, parsedSpace.name))?.owner;
   } catch {
     return void 0;
   }