@tinycloud/operations 0.7.11-beta.2 → 0.8.0-beta.3

package/dist/cli-runtime.d.cts

@@ -1,4 +1,4 @@
-import { I as InvocationTarget, a as OperationResult } from './contract-DrtFhVsg.cjs';
+import { I as InvocationTarget, a as OperationResult } from './contract-BGJGxuGr.cjs';
 
 /**
  * The only published CLI acquisition helper. Its fixed operation identity is

package/dist/cli-runtime.d.ts

@@ -1,4 +1,4 @@
-import { I as InvocationTarget, a as OperationResult } from './contract-DrtFhVsg.js';
+import { I as InvocationTarget, a as OperationResult } from './contract-BGJGxuGr.js';
 
 /**
  * The only published CLI acquisition helper. Its fixed operation identity is

package/dist/cli-runtime.js

@@ -342,6 +342,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",
@@ -7820,10 +7822,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: {
@@ -7831,7 +7843,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) {
@@ -8245,14 +8258,16 @@ var init_exploration = __esm({
     KvListInputSchema = z7.object({
       space: SpaceSchema2,
       prefix: PrefixSchema2.optional(),
-      limit: LimitSchema.optional()
+      limit: LimitSchema.optional(),
+      cursor: z7.string().optional()
     }).strict();
     KvListOutputSchema = z7.object({
       space: z7.string().min(1),
       prefix: z7.string(),
       keys: z7.array(z7.string()),
       count: z7.number().int().nonnegative(),
-      truncated: z7.boolean()
+      truncated: z7.boolean(),
+      nextCursor: z7.string().nullable()
     }).strict();
     KvGetInputSchema = z7.object({
       space: SpaceSchema2,
@@ -8394,7 +8409,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"],
@@ -8409,7 +8424,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"],
@@ -8967,6 +8982,320 @@ var init_knowledge = __esm({
   }
 });
 
+// src/operations/read.ts
+import { isUtf8 } from "buffer";
+import { createHash } from "crypto";
+import { parseSpaceUri as parseSpaceUri2 } from "@tinycloud/node-sdk";
+import { z as z9 } from "zod";
+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 = parseSpaceUri2(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 = 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 : 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: 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 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";
+    init_jcs();
+    init_errors2();
+    init_exploration();
+    init_sql();
+    MAX_PAGE_BYTES = 12 * 1024;
+    MAX_PAGE_OUTPUT_BYTES = 8e4;
+    Sha256Schema = z9.string().regex(/^[0-9a-f]{64}$/);
+    ByteOffsetSchema = z9.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+    EncodingSchema = z9.enum(["utf8", "base64"]);
+    PageBytesSchema = z9.number().int().min(1).max(MAX_PAGE_BYTES);
+    ResourceSchema = z9.discriminatedUnion("kind", [
+      KvGetInputSchema.omit({ representation: true }).extend({ kind: z9.literal("kv") }),
+      SqlQueryInputSchema.extend({ kind: z9.literal("sql") })
+    ]);
+    ResourceIdentitySchema = z9.discriminatedUnion("kind", [
+      z9.object({
+        kind: z9.literal("kv"),
+        space: z9.string().min(1),
+        key: z9.string().min(1)
+      }).strict(),
+      z9.object({
+        kind: z9.literal("sql"),
+        space: z9.string().min(1),
+        database: z9.string().min(1),
+        querySha256: Sha256Schema
+      }).strict()
+    ]);
+    ReadBindingSchema = z9.object({
+      host: z9.string().min(1),
+      ownerDid: z9.string().min(1),
+      resource: ResourceIdentitySchema,
+      sha256: Sha256Schema,
+      totalBytes: ByteOffsetSchema
+    }).strict();
+    ContinuationSchema = z9.object({
+      offset: ByteOffsetSchema,
+      pageBytes: PageBytesSchema,
+      encoding: EncodingSchema,
+      expected: ReadBindingSchema
+    }).strict();
+    ReadInputSchema2 = z9.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: z9.ZodIssueCode.custom,
+          path: ["expected"],
+          message: "A nonzero byte offset requires the previous page's expected binding."
+        });
+      }
+    });
+    ReadOutputSchema2 = z9.object({
+      value: z9.string(),
+      encoding: EncodingSchema,
+      range: z9.object({
+        unit: z9.literal("bytes"),
+        start: ByteOffsetSchema,
+        end: ByteOffsetSchema
+      }).strict(),
+      binding: ReadBindingSchema,
+      provenance: z9.object({
+        digestAlgorithm: z9.literal("sha256"),
+        representation: z9.enum(["original-bytes", "normalized-sql-result-json"]),
+        acquiredAt: z9.string().datetime(),
+        etag: z9.string().nullable()
+      }).strict(),
+      complete: z9.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
+import { z as z10 } from "zod";
+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 InputSchema, OutputSchema, readScopeOperationDefinitions;
+var init_read_scope = __esm({
+  "src/operations/read-scope.ts"() {
+    "use strict";
+    init_artifacts();
+    init_authority();
+    init_errors2();
+    init_exploration();
+    init_sql();
+    InputSchema = z10.object({
+      space: KvGetInputSchema.shape.space,
+      kvPrefixes: z10.array(z10.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: z10.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: z10.ZodIssueCode.custom, message: "Select at least one KV prefix or exact database." });
+      }
+    });
+    OutputSchema = z10.object({
+      space: z10.string().min(1),
+      permissions: z10.array(PermissionEntrySchema).min(1),
+      access: z10.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
 import * as nodeSdk3 from "@tinycloud/node-sdk";
 function canonicalSecretRequestOwner(did) {
@@ -9154,7 +9483,7 @@ var init_secret_request = __esm({
 });
 
 // src/operations/secrets-get.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 async function planSecretGet(context, input) {
   const reference = resolveSecretReferenceForOperation(
     input,
@@ -9342,19 +9671,19 @@ var init_secrets_get = __esm({
     init_errors2();
     init_secret_request();
     init_secrets();
-    SecretsGetInputSchema = z9.object({
-      name: z9.string(),
-      scope: z9.string().optional(),
-      space: z9.string().optional()
+    SecretsGetInputSchema = z11.object({
+      name: z11.string(),
+      scope: z11.string().optional(),
+      space: z11.string().optional()
     }).strict().superRefine((input, context) => {
       try {
         resolveSecretReference(input);
       } catch {
-        context.addIssue({ code: z9.ZodIssueCode.custom, message: "Invalid secret reference." });
+        context.addIssue({ code: z11.ZodIssueCode.custom, message: "Invalid secret reference." });
       }
     }).transform(normalizeSecretsGetInput);
-    SecretsGetOutputSchema = z9.object({
-      value: z9.string()
+    SecretsGetOutputSchema = z11.object({
+      value: z11.string()
     }).strict();
     SECRETS_GET_POSTURES = [
       "owner-openkey",
@@ -9393,7 +9722,7 @@ var init_secrets_get = __esm({
 });
 
 // src/operations/secrets-status.ts
-import { z as z10 } from "zod";
+import { z as z12 } from "zod";
 import * as nodeSdk4 from "@tinycloud/node-sdk";
 async function executeSecretsStatus(context, input) {
   const runtime = context.runtime;
@@ -9492,27 +9821,27 @@ var init_secrets_status = __esm({
     init_secrets();
     PROBE_TIMEOUT_MS = 15e3;
     SECRETS_STATUS_DEADLINE_MS = 18e3;
-    SecretsStatusInputSchema = z10.object({
-      names: z10.array(z10.string()),
-      scope: z10.string().optional(),
-      owner: z10.string().optional()
+    SecretsStatusInputSchema = z12.object({
+      names: z12.array(z12.string()),
+      scope: z12.string().optional(),
+      owner: z12.string().optional()
     }).strict().superRefine((input, context) => {
       try {
         validSecretNames(input.names);
       } catch {
-        context.addIssue({ code: z10.ZodIssueCode.custom, path: ["names"], message: "Invalid secret names." });
+        context.addIssue({ code: z12.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: z10.ZodIssueCode.custom, path: ["scope"], message: "Invalid secret scope." });
+        context.addIssue({ code: z12.ZodIssueCode.custom, path: ["scope"], message: "Invalid secret scope." });
       }
       if (input.owner !== void 0) {
         try {
           canonicalSecretRequestOwner(input.owner);
         } catch {
-          context.addIssue({ code: z10.ZodIssueCode.custom, path: ["owner"], message: "Invalid owner." });
+          context.addIssue({ code: z12.ZodIssueCode.custom, path: ["owner"], message: "Invalid owner." });
         }
       }
     }).transform((input) => {
@@ -9523,23 +9852,23 @@ var init_secrets_status = __esm({
         ...input.owner === void 0 ? {} : { owner: canonicalSecretRequestOwner(input.owner) }
       };
     });
-    SecretSetupSchema = z10.object({
-      url: z10.string().url(),
-      names: z10.array(z10.string()).min(1),
-      scope: z10.string().optional(),
-      owner: z10.string(),
-      action: z10.literal("add_secret")
+    SecretSetupSchema = z12.object({
+      url: z12.string().url(),
+      names: z12.array(z12.string()).min(1),
+      scope: z12.string().optional(),
+      owner: z12.string(),
+      action: z12.literal("add_secret")
     }).strict();
-    SecretsStatusOutputSchema = z10.object({
-      status: z10.enum(["ready", "pending", "consent_required"]),
-      owner: z10.string(),
-      names: z10.array(z10.string()).min(1),
-      scope: z10.string().optional(),
-      present: z10.array(z10.string()),
-      pending: z10.array(z10.string()),
-      denied: z10.array(z10.string()),
+    SecretsStatusOutputSchema = z12.object({
+      status: z12.enum(["ready", "pending", "consent_required"]),
+      owner: z12.string(),
+      names: z12.array(z12.string()).min(1),
+      scope: z12.string().optional(),
+      present: z12.array(z12.string()),
+      pending: z12.array(z12.string()),
+      denied: z12.array(z12.string()),
       setup: SecretSetupSchema.optional(),
-      hint: z10.string().optional()
+      hint: z12.string().optional()
     }).strict();
     SECRETS_STATUS_POSTURES = [
       "owner-openkey",
@@ -9867,7 +10196,7 @@ var init_delegation_binding = __esm({
 });
 
 // src/operations/status.ts
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 function createStatusDefinition(params) {
   return {
     id: params.id,
@@ -9992,27 +10321,27 @@ var init_status = __esm({
     init_delegation_binding();
     init_errors2();
     init_state();
-    StatusInputSchema = z11.object({}).strict();
-    StatusOutputSchema = z11.object({
-      profile: z11.string().min(1),
-      host: z11.string().min(1),
-      posture: z11.enum([
+    StatusInputSchema = z13.object({}).strict();
+    StatusOutputSchema = z13.object({
+      profile: z13.string().min(1),
+      host: z13.string().min(1),
+      posture: z13.enum([
         "owner-openkey",
         "delegate-session",
         "local-owner-key",
         "unauthenticated"
       ]),
-      operatorType: z11.enum(["human", "agent"]).optional(),
-      principalDid: z11.string().min(1).optional(),
-      sessionDid: z11.string().min(1).optional(),
-      ownerDid: z11.string().min(1).optional(),
-      space: z11.string().min(1).optional(),
-      session: z11.object({
-        present: z11.boolean(),
-        expired: z11.boolean().nullable(),
-        expiresAt: z11.string().datetime({ offset: true }).nullable()
+      operatorType: z13.enum(["human", "agent"]).optional(),
+      principalDid: z13.string().min(1).optional(),
+      sessionDid: z13.string().min(1).optional(),
+      ownerDid: z13.string().min(1).optional(),
+      space: z13.string().min(1).optional(),
+      session: z13.object({
+        present: z13.boolean(),
+        expired: z13.boolean().nullable(),
+        expiresAt: z13.string().datetime({ offset: true }).nullable()
       }).strict(),
-      liveAdditionalDelegationCount: z11.number().int().nonnegative().describe(
+      liveAdditionalDelegationCount: z13.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();
@@ -10054,6 +10383,8 @@ function registeredOperationDefinitions() {
   operationDefinitions ?? (operationDefinitions = [
     ...statusOperationDefinitions,
     ...authOperationDefinitions,
+    ...readScopeOperationDefinitions,
+    ...readOperationDefinitions,
     ...explorationOperationDefinitions,
     ...appsOperationDefinitions,
     ...sqlOperationDefinitions,
@@ -10092,6 +10423,8 @@ var init_registry = __esm({
     init_auth();
     init_exploration();
     init_knowledge();
+    init_read();
+    init_read_scope();
     init_secrets_get();
     init_secrets_status();
     init_sql();
@@ -10534,12 +10867,12 @@ init_jcs();
 init_errors2();
 init_authority();
 init_artifacts();
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { isAbsolute as isAbsolute2 } from "path";
 import {
   makePkhSpaceId as makePkhSpaceId4,
   parsePkhDid as parsePkhDid4,
-  parseSpaceUri as parseSpaceUri2
+  parseSpaceUri as parseSpaceUri3
 } from "@tinycloud/node-sdk";
 
 // src/redaction.ts
@@ -11261,7 +11594,7 @@ function operationRetryDescriptor(operation, input, requiresCallerInput = false)
   return {
     operationId: operation.operationId,
     operationVersion: operation.operationVersion,
-    inputDigest: createHash("sha256").update(jcsCanonicalize(input), "utf8").digest("hex"),
+    inputDigest: createHash2("sha256").update(jcsCanonicalize(input), "utf8").digest("hex"),
     requiresCallerInput
   };
 }
@@ -11361,11 +11694,11 @@ function requirementsBelongToAuthenticatedOwner(requirements, authenticatedSpace
 }
 function canonicalPkhOwner(space) {
   if (typeof space !== "string") return void 0;
-  const parsedSpace = parseSpaceUri2(space);
+  const parsedSpace = parseSpaceUri3(space);
   if (parsedSpace === null) return void 0;
   try {
     const pkh = parsePkhDid4(parsedSpace.owner);
-    return pkh === null ? void 0 : parseSpaceUri2(makePkhSpaceId4(pkh.address, pkh.chainId, parsedSpace.name))?.owner;
+    return pkh === null ? void 0 : parseSpaceUri3(makePkhSpaceId4(pkh.address, pkh.chainId, parsedSpace.name))?.owner;
   } catch {
     return void 0;
   }