@k2b/cloud 0.44.0 → 0.46.0

package/src/browser/shared-text-table-contract.ts

@@ -0,0 +1,150 @@
+import { encoding } from "@k2b/stdlib";
+import type { TableActionIntent, TableFocusWitness } from "../shared-text/table-actions";
+
+const { fromBase64, toBase64 } = encoding;
+
+import * as Y from "yjs";
+import { z } from "zod";
+
+/** Approved editor limit, measured in UTF-16 code units. Rejection must preserve the existing text. */
+export const TEXT_TABLE_ACTION_MAX_LENGTH = 2_097_152;
+
+// An item relative position is one tag, two safe-integer varuints (at most
+// ceil(53 / 7) bytes each), and the zero-association byte. No root-name/sentinel
+// positions are accepted. The base64 bound follows this Yjs wire format.
+const ITEM_ANCHOR_MAX_BYTES = 1 + 2 * Math.ceil(53 / 7) + 1;
+const ITEM_ANCHOR_MAX_BASE64_LENGTH = 4 * Math.ceil(ITEM_ANCHOR_MAX_BYTES / 3);
+const AnchorSchema = z
+  .string()
+  .min(1)
+  .max(ITEM_ANCHOR_MAX_BASE64_LENGTH)
+  .refine((encoded) => {
+    if (encoded.length > ITEM_ANCHOR_MAX_BASE64_LENGTH) return false;
+    try {
+      const bytes = fromBase64(encoded);
+      const position = Y.decodeRelativePosition(bytes);
+      return (
+        bytes.length <= ITEM_ANCHOR_MAX_BYTES &&
+        position.item !== null &&
+        position.assoc === 0 &&
+        Number.isSafeInteger(position.item.client) &&
+        position.item.client >= 0 &&
+        Number.isSafeInteger(position.item.clock) &&
+        position.item.clock >= 0 &&
+        toBase64(Y.encodeRelativePosition(position)) === encoded
+      );
+    } catch {
+      return false;
+    }
+  }, "Expected a canonical Yjs character anchor");
+
+const TableSchema = z.object({ headerBreak: AnchorSchema, separatorHyphen: AnchorSchema }).strict();
+const RowSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("header") }).strict(),
+  z.object({ kind: z.literal("body"), beforeBreak: AnchorSchema, inside: AnchorSchema, insideKind: z.enum(["pipe", "break"]) }).strict(),
+]);
+const ColumnSchema = z.object({ hyphen: AnchorSchema, left: AnchorSchema, right: AnchorSchema }).strict();
+
+export const TextTableFocusSchema = z.object({ table: TableSchema, row: RowSchema, column: ColumnSchema }).strict();
+export type EncodedTableFocus = z.infer<typeof TextTableFocusSchema>;
+export const encodeTableFocus = (focus: TableFocusWitness): EncodedTableFocus => ({
+  table: { headerBreak: toBase64(focus.table.headerBreak), separatorHyphen: toBase64(focus.table.separatorHyphen) },
+  row:
+    focus.row.kind === "header"
+      ? focus.row
+      : { ...focus.row, beforeBreak: toBase64(focus.row.beforeBreak), inside: toBase64(focus.row.inside) },
+  column: { hyphen: toBase64(focus.column.hyphen), left: toBase64(focus.column.left), right: toBase64(focus.column.right) },
+});
+export const decodeTableFocus = (focus: EncodedTableFocus): TableFocusWitness => ({
+  table: { headerBreak: fromBase64(focus.table.headerBreak), separatorHyphen: fromBase64(focus.table.separatorHyphen) },
+  row:
+    focus.row.kind === "header"
+      ? focus.row
+      : { ...focus.row, beforeBreak: fromBase64(focus.row.beforeBreak), inside: fromBase64(focus.row.inside) },
+  column: { hyphen: fromBase64(focus.column.hyphen), left: fromBase64(focus.column.left), right: fromBase64(focus.column.right) },
+});
+
+export const EncodedTableActionIntentSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.enum(["moveRowUp", "moveRowDown"]), table: TableSchema, row: RowSchema, neighbor: RowSchema }).strict(),
+  z.object({ action: z.enum(["moveColLeft", "moveColRight"]), table: TableSchema, column: ColumnSchema, neighbor: ColumnSchema }).strict(),
+  z.object({ action: z.enum(["undo", "redo"]), receiptCursor: z.string().min(1).max(256) }).strict(),
+  z
+    .object({
+      action: z.literal("replaceSource"),
+      table: TableSchema,
+      expected: z.string().max(TEXT_TABLE_ACTION_MAX_LENGTH),
+      source: z.string().max(TEXT_TABLE_ACTION_MAX_LENGTH),
+    })
+    .strict(),
+  z.object({ action: z.enum(["completeColumns", "toggleHeader", "deleteTable"]), table: TableSchema }).strict(),
+  z.object({ action: z.enum(["rowAbove", "rowBelow", "deleteRow"]), table: TableSchema, row: RowSchema }).strict(),
+  z
+    .object({
+      action: z.enum(["colLeft", "colRight", "deleteCol", "alignLeft", "alignCenter", "alignRight"]),
+      table: TableSchema,
+      column: ColumnSchema,
+    })
+    .strict(),
+]);
+
+export const TextTableActionRequestSchema = z
+  .object({
+    // The application stores this token in a nonnegative Postgres bigint.
+    restoreRevision: z
+      .string()
+      .min(1)
+      .max(19)
+      .regex(/^(0|[1-9]\d*)$/)
+      .refine((value) => value.length <= 19 && /^(0|[1-9]\d*)$/.test(value) && BigInt(value) <= 9_223_372_036_854_775_807n),
+    actionId: z.uuid(),
+    intent: EncodedTableActionIntentSchema,
+    focus: TextTableFocusSchema.optional(),
+    caret: z
+      .object({
+        row: z.number().int().nonnegative().max(TEXT_TABLE_ACTION_MAX_LENGTH),
+        column: z.number().int().nonnegative().max(TEXT_TABLE_ACTION_MAX_LENGTH),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export type EncodedTableActionIntent = z.infer<typeof EncodedTableActionIntentSchema>;
+export type TextTableActionRequest = z.infer<typeof TextTableActionRequestSchema>;
+
+/** Decode only schema-validated transport; planning still validates identity and current context. */
+export type TextTableIntent = TableActionIntent | { action: "undo" | "redo"; receiptCursor: string };
+export const decodeTableActionIntent = (intent: EncodedTableActionIntent): TextTableIntent => {
+  if ("receiptCursor" in intent) return intent;
+  const table = { headerBreak: fromBase64(intent.table.headerBreak), separatorHyphen: fromBase64(intent.table.separatorHyphen) };
+  if ("source" in intent) return { action: intent.action, table, expected: intent.expected, source: intent.source };
+  if (!("row" in intent) && !("column" in intent)) return { action: intent.action, table };
+  const decodeRow = (row: z.infer<typeof RowSchema>) =>
+    row.kind === "header"
+      ? row
+      : { kind: "body" as const, beforeBreak: fromBase64(row.beforeBreak), inside: fromBase64(row.inside), insideKind: row.insideKind };
+  const decodeColumn = (column: z.infer<typeof ColumnSchema>) => ({
+    hyphen: fromBase64(column.hyphen),
+    left: fromBase64(column.left),
+    right: fromBase64(column.right),
+  });
+  if ("row" in intent) {
+    const row = decodeRow(intent.row);
+    return "neighbor" in intent
+      ? { action: intent.action, table, row, neighbor: decodeRow(intent.neighbor) }
+      : { action: intent.action, table, row };
+  }
+  const column = decodeColumn(intent.column);
+  return "neighbor" in intent
+    ? { action: intent.action, table, column, neighbor: decodeColumn(intent.neighbor) }
+    : { action: intent.action, table, column };
+};
+
+export const TextTableActionReceiptSchema = z.object({ actionId: z.uuid(), update: z.string() });
+export const TextTableActionResponseSchema = z.object({
+  changed: z.boolean(),
+  focus: TextTableFocusSchema.nullable().optional(),
+  cursor: z.string().nullable(),
+  receipt: TextTableActionReceiptSchema.nullable(),
+});
+export type TextTableActionResponse = z.infer<typeof TextTableActionResponseSchema>;

package/src/browser/shared-text.ts

@@ -0,0 +1,19 @@
+/** Browser-safe identity helpers; no server log, storage, or process state. */
+export { captureTextAnchor, resolveTextAnchor } from "../shared-text/anchors";
+export {
+  captureTableAction,
+  captureTableFocus,
+  captureTableSource,
+  prepareTableActionFocus,
+  resolveTableFocus,
+  type TableActionIntent,
+  TableActionLimitError,
+  TableActionRejectedError,
+  type TableFocusWitness,
+} from "../shared-text/table-actions";
+export { createSharedTextActionHistory, type SharedTextInverseRequest } from "./shared-text-history";
+export * from "./shared-text-offline";
+export { openAuthorizedSharedTextOffline } from "./shared-text-offline-authorized";
+export * from "./shared-text-provider";
+
+export * from "./shared-text-table-contract";

package/src/capabilities/discussion-providers.ts

@@ -0,0 +1,99 @@
+import { discussionsIssues } from "../contracts/discussions";
+import { type CapabilityCaller, listCapabilityCatalog } from "./server-invoke";
+import type { CapabilityCatalogApp } from "./types";
+
+// Same interactive discovery budget as the calendar reader. Cursor pages are sequential (one in flight).
+const MAX_CALLS = 60;
+const MAX_BYTES = 4 * 1024 * 1024;
+export type DiscussionProvider = {
+  app: CapabilityCatalogApp;
+  itemType: string;
+  containerType: string;
+  containers: string;
+  activity?: string;
+};
+
+/** Request-local discovery. Failure, truncation, and cancellation throw; no partial success or retained authority. */
+export const discussionProviders = async (
+  caller: CapabilityCaller,
+  options: { deadline: number; signal?: AbortSignal },
+): Promise<DiscussionProvider[]> => {
+  if (!Number.isFinite(options.deadline)) throw new RangeError("Discussion deadline must be a finite epoch time in milliseconds");
+  const controller = new AbortController();
+  const signal = AbortSignal.any([
+    controller.signal,
+    ...[caller.signal, options.signal].filter((signal): signal is AbortSignal => !!signal),
+  ]);
+  const timer = setTimeout(() => controller.abort(new Error("DISCUSSION_DEADLINE")), Math.max(0, options.deadline - Date.now()));
+  let bytes = 0;
+  const addBytes = (size: number) => {
+    bytes += size;
+    if (bytes > MAX_BYTES) {
+      controller.abort(new Error("DISCUSSION_BYTE_BUDGET"));
+      signal.throwIfAborted();
+    }
+  };
+  const credentials: CapabilityCaller = {
+    ...caller,
+    signal,
+    ...(!caller.authority
+      ? {
+          transport: async (request: Request) => {
+            const response = await (caller.transport ?? ((request: Request) => fetch(request, { redirect: "error" })))(request);
+            if (!response.body) return response;
+            const body = response.body.pipeThrough(
+              new TransformStream<Uint8Array, Uint8Array>({
+                transform(chunk, stream) {
+                  addBytes(chunk.byteLength);
+                  stream.enqueue(chunk);
+                },
+              }),
+              { signal },
+            );
+            return new Response(body, { status: response.status, headers: response.headers });
+          },
+        }
+      : {}),
+  };
+  const providers: DiscussionProvider[] = [];
+  const seen = new Set<string>();
+  const appIds = new Set<string>();
+  let cursor: string | undefined;
+  let onAbort: (() => void) | undefined;
+  const cancelled = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    for (let calls = 0; calls < MAX_CALLS; calls++) {
+      if (options.deadline <= Date.now()) controller.abort(new Error("DISCUSSION_DEADLINE"));
+      signal.throwIfAborted();
+      const page = await Promise.race([listCapabilityCatalog({ caller: credentials, cursor, limit: 25 }), cancelled]);
+      signal.throwIfAborted();
+      if (!page.ok) throw new Error(`Discussion discovery unavailable: ${page.error.code}`);
+      if (caller.authority) addBytes(new TextEncoder().encode(JSON.stringify(page.data)).byteLength);
+      for (const app of page.data.apps) {
+        const role = app.manifest.discussions;
+        const model = app.manifest.resourceTypes?.find((model) => model.type === role?.item);
+        if (!role || !model?.container || discussionsIssues(app.manifest).length || appIds.has(app.appId)) continue;
+        appIds.add(app.appId);
+        providers.push({
+          app,
+          itemType: `${app.appId}.${role.item}`,
+          containerType: `${app.appId}.${model.container}`,
+          containers: role.containers,
+          ...(role.activity ? { activity: role.activity } : {}),
+        });
+      }
+      if (!page.data.page.hasMore) return providers;
+      cursor = page.data.page.nextCursor;
+      if (seen.has(cursor)) throw new Error("DISCUSSION_CURSOR_LOOP");
+      seen.add(cursor);
+    }
+    throw new Error("DISCUSSION_CALL_BUDGET");
+  } finally {
+    clearTimeout(timer);
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+    controller.abort();
+  }
+};

package/src/capabilities/executions.ts

@@ -63,7 +63,7 @@ export type CapabilityExecutionInput = {
   capability: string;
   kind: "query" | "action";
   destructive: boolean;
-  actorKind?: "user" | "service_account" | null;
+  actorKind?: "user" | "service_account" | "app" | null;
   actorId?: string | null;
   userId?: string | null;
   /** Recorded only when the access subject differs from the acting principal. */
@@ -90,7 +90,7 @@ export type CapabilityExecution = {
   capability: string;
   kind: "query" | "action";
   destructive: boolean;
-  actorKind: "user" | "service_account" | null;
+  actorKind: "user" | "service_account" | "app" | null;
   actorId: string | null;
   userId: string | null;
   accessSubjectType: "user" | "service_account" | null;

package/src/capabilities/migrate.ts

@@ -35,7 +35,7 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
       duration_ms INTEGER NOT NULL DEFAULT 0,
       CONSTRAINT capabilities_executions_origin_check CHECK (origin IN ('assistant', 'mcp', 'http', 'app')),
       CONSTRAINT capabilities_executions_kind_check CHECK (kind IN ('query', 'action')),
-      CONSTRAINT capabilities_executions_actor_kind_check CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account')),
+      CONSTRAINT capabilities_executions_actor_kind_check CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account', 'app')),
       CONSTRAINT capabilities_executions_subject_check CHECK (access_subject_type IS NULL OR access_subject_type IN ('user', 'service_account')),
       CONSTRAINT capabilities_executions_status_check CHECK (status IN ('succeeded', 'failed', 'denied', 'invalid_input', 'timed_out', 'rejected'))
     )
@@ -59,6 +59,15 @@ export const migrateCloudCapabilities = async (): Promise<void> => {
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS parent_invocation_id UUID`.simple();
   await sql`ALTER TABLE capabilities.executions ADD COLUMN IF NOT EXISTS via_app_id TEXT`.simple();
 
+  await sql`DO $$ BEGIN
+    IF EXISTS (SELECT 1 FROM pg_constraint WHERE conrelid = 'capabilities.executions'::regclass
+      AND conname = 'capabilities_executions_actor_kind_check' AND position('''app''' in pg_get_constraintdef(oid)) = 0) THEN
+      ALTER TABLE capabilities.executions DROP CONSTRAINT capabilities_executions_actor_kind_check;
+      ALTER TABLE capabilities.executions ADD CONSTRAINT capabilities_executions_actor_kind_check
+        CHECK (actor_kind IS NULL OR actor_kind IN ('user', 'service_account', 'app'));
+    END IF;
+  END $$`.simple();
+
   // Platform-owned idempotency claims. One row per
   // (app, capability, principal, key); the dispatcher claims before it
   // forwards and resolves the row once the outcome is known. Response bodies

package/src/capabilities/resource-readers.ts

@@ -0,0 +1,58 @@
+import { getProcessApplicationId } from "../_internal/process-identity";
+import { getCapability } from "../_internal/registry";
+import { env } from "../config/env";
+import {
+  CloudResourceRefSchema,
+  type ResourcePrincipal,
+  ResourceReadableDataSchema,
+  ResourceReadableInputSchema,
+} from "../contracts/capabilities";
+import { invokeCapabilityWithDataSchema } from "./server-invoke";
+
+export type ResourceReadersResult =
+  | { state: "checked"; readable: ResourcePrincipal[] }
+  | { state: "not_configured"; reason: "no_readable" | "no_credential" | "no_internal_origin" | "no_app_identity" | "not_admitted" };
+
+/** An empty checked subset means not readable; an unavailable check throws for the caller's retry. */
+export const readResourcePrincipals = async (options: {
+  ref: { type: string; id: string };
+  container?: { type: string; id: string };
+  principals: readonly ResourcePrincipal[];
+  signal?: AbortSignal;
+  locale?: string;
+  requestId?: string;
+}): Promise<ResourceReadersResult> => {
+  const ref = CloudResourceRefSchema.parse(options.ref);
+  if (!env.CLOUD_APP_CREDENTIAL) return { state: "not_configured", reason: "no_credential" };
+  if (!env.CLOUD_CORE_INTERNAL_ORIGIN) return { state: "not_configured", reason: "no_internal_origin" };
+  const callerAppId = getProcessApplicationId();
+  if (!callerAppId) return { state: "not_configured", reason: "no_app_identity" };
+  options.signal?.throwIfAborted();
+  const separator = ref.type.indexOf(".");
+  const appId = ref.type.slice(0, separator);
+  const localType = ref.type.slice(separator + 1);
+  const entry = await getCapability(appId);
+  if (!entry) throw new Error("Resource reader provider registry entry unavailable");
+  const model = entry.manifest.resourceTypes?.find((model) => model.type === localType);
+  if (!model?.readable || !entry.manifest.queries.some((query) => query.localId === `${localType}.readable` && query.appOnly))
+    return { state: "not_configured", reason: "no_readable" };
+  const input = ResourceReadableInputSchema.parse({ id: ref.id, container: options.container, principals: options.principals });
+  if (model.container && input.container?.type !== `${appId}.${model.container}`)
+    throw new Error("Reader check requires a reference to the declared container type");
+  const result = await invokeCapabilityWithDataSchema(
+    { appId, capabilityId: `${localType}.readable`, kind: "query", input },
+    ResourceReadableDataSchema,
+    {
+      workload: { appId: callerAppId },
+      authorization: `Bearer ${env.CLOUD_APP_CREDENTIAL}`,
+      signal: options.signal,
+      locale: options.locale,
+      requestId: options.requestId,
+    },
+  );
+  if (!result.ok) {
+    if (result.error.code === "APP_QUERY_NOT_ADMITTED") return { state: "not_configured", reason: "not_admitted" };
+    throw new Error(`Resource reader check unavailable: ${result.error.code}`);
+  }
+  return { state: "checked", readable: result.data.data.readable };
+};

package/src/capabilities/server-invoke.ts

@@ -35,6 +35,8 @@ export type CapabilityCaller = {
   /** BCP 47 locale of the originating request, forwarded as invocation metadata. */
   locale?: string | null;
   signal?: AbortSignal;
+  /** App-only query authority. The workload credential goes only to Core. */
+  workload?: { appId: string };
   /** Durable background authority. `authorization` must be the owning app's workload credential. */
   mandate?: { id: string; revision: number; callingAppId: string };
 };
@@ -49,7 +51,7 @@ export const callerRequest = async (
 ): Promise<Request> => {
   const headers = new Headers();
   if (caller.authorization) headers.set("authorization", caller.authorization);
-  if (!caller.mandate) {
+  if (!caller.mandate && !caller.workload) {
     if (caller.cookie) headers.set("cookie", caller.cookie);
     if (caller.requestId) headers.set("x-request-id", caller.requestId);
     if (caller.traceparent) headers.set("traceparent", caller.traceparent);
@@ -57,10 +59,14 @@ export const callerRequest = async (
     if (caller.locale) headers.set(LOCALE_HEADER, caller.locale);
     if (idempotencyKey) headers.set("idempotency-key", idempotencyKey);
   } else {
-    headers.set("x-cloud-app-id", caller.mandate.callingAppId);
+    headers.set("x-cloud-app-id", caller.mandate?.callingAppId ?? caller.workload!.appId);
   }
   const signal = combineCapabilitySignals(caller.signal, invocationSignal);
-  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined)), { method: "POST", headers, signal });
+  return new Request(new URL(path, await coreOrigin(caller.mandate !== undefined || caller.workload !== undefined)), {
+    method: "POST",
+    headers,
+    signal,
+  });
 };
 
 export const unavailable = (
@@ -96,12 +102,15 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
   caller: CapabilityCaller,
 ): Promise<CapabilityClientResult<z.output<TDataSchema>>> => {
   try {
-    const path = caller.mandate
-      ? "/api/_internal/identity/v1/invoke"
-      : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
+    if (caller.workload && (caller.mandate || caller.cookie || invocation.kind !== "query"))
+      throw new Error("Workload authority permits only queries without a mandate or cookie");
+    const path =
+      caller.mandate || caller.workload
+        ? "/api/_internal/identity/v1/invoke"
+        : `/api/capabilities/v1/${invocation.kind === "query" ? "queries" : "actions"}/${encodeURIComponent(invocation.appId)}/${encodeURIComponent(invocation.capabilityId)}`;
     const request = await callerRequest(caller, path, invocation.idempotencyKey, invocation.signal);
     if (caller.authority) {
-      if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
+      if (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport)
         throw new Error("Use exactly one capability authority source");
       const outcome = await dispatchCapability({
         request,
@@ -115,17 +124,18 @@ const invokeCapabilityWithResultSchema = async <TDataSchema extends z.ZodType, T
       });
       return readCapabilityResponse(outcome, capabilityResultSchema(dataSchema, { consumer: true }));
     }
-    const response = await (caller.transport ?? fetch)(
+    const response = await (
+      caller.transport ?? ((request: Request) => fetch(request, caller.workload ? { redirect: "error" } : undefined))
+    )(
       new Request(request, {
         body: JSON.stringify(
-          caller.mandate
+          caller.mandate || caller.workload
             ? {
                 kind: invocation.kind,
                 targetApp: invocation.appId,
                 capabilityId: invocation.capabilityId,
                 input: invocation.input,
-                mandateId: caller.mandate.id,
-                mandateRevision: caller.mandate.revision,
+                ...(caller.mandate ? { mandateId: caller.mandate.id, mandateRevision: caller.mandate.revision } : {}),
                 ...(invocation.idempotencyKey ? { idempotencyKey: invocation.idempotencyKey } : {}),
                 ...(caller.requestId || caller.traceparent || caller.tracestate || caller.locale
                   ? {
@@ -174,14 +184,14 @@ export const listCapabilityCatalog = async (
     if (options.caller) {
       const caller = options.caller;
       if (options.authority) throw new Error("Use one catalog authority source");
-      if (caller.authority && (caller.authorization || caller.cookie || caller.mandate || caller.transport))
+      if (caller.authority && (caller.authorization || caller.cookie || caller.mandate || caller.workload || caller.transport))
         throw new Error("Use exactly one capability authority source");
       if (caller.authority)
         return {
           ok: true,
           data: await loadCapabilityCatalogPage({ cursor: options.cursor, limit }, {}, caller.locale ?? options.locale, caller.authority),
         };
-      if (caller.mandate) throw new Error("Calendar discovery requires request credentials");
+      if (caller.mandate || caller.workload) throw new Error("Calendar discovery requires request credentials");
       const query = new URLSearchParams({ limit: String(limit) });
       if (options.cursor) query.set("cursor", options.cursor);
       const request = new Request(await callerRequest(caller, `/api/capabilities/v1/catalog?${query}`), { method: "GET" });

package/src/capabilities/server.ts

@@ -1,4 +1,8 @@
-import { resolveCapabilityActionWording, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import {
+  isPersonVisibleCapabilityQuery,
+  resolveCapabilityActionWording,
+  resolveCapabilityManifestPresentation,
+} from "../_internal/capabilities";
 import type { CapabilityActionWording } from "../_internal/capability-sentences";
 import { getApp, getCapability } from "../_internal/registry";
 import { dispatchCapability } from "../api/capabilities";
@@ -37,18 +41,22 @@ export const getCapabilityCatalogApp = async (
   try {
     const [capability, registeredApp] = await Promise.all([getCapability(appId), getApp(appId)]);
     const presentedApp = registeredApp && locale ? resolveAppPresentation(registeredApp, locale) : registeredApp;
+    const manifest =
+      capability &&
+      (locale ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale) : capability.manifest);
     return {
       ok: true,
       data:
-        capability && registeredApp && (await canUseApp(authority, registeredApp))
+        capability && registeredApp && manifest && (await canUseApp(authority, registeredApp))
           ? {
               appId: capability.appId,
               appName: presentedApp?.name ?? capability.appName,
               appIcon: capability.appIcon,
               appDescription: presentedApp?.description ?? capability.appDescription,
-              manifest: locale
-                ? resolveCapabilityManifestPresentation(capability.manifest, capability.presentation, locale)
-                : capability.manifest,
+              manifest: {
+                ...manifest,
+                queries: manifest.queries.filter(isPersonVisibleCapabilityQuery),
+              },
             }
           : null,
     };
@@ -81,6 +89,7 @@ export const reviewCapabilityAction = async <TInput = unknown>(
   caller: CapabilityCaller,
 ): Promise<CapabilityReviewClientResult> => {
   try {
+    if (caller.workload) throw new Error("App query authority cannot review Actions");
     if (caller.authority) {
       if (caller.authorization || caller.cookie || caller.mandate || caller.transport)
         throw new Error("Use exactly one capability authority source");
@@ -132,7 +141,7 @@ export async function transferCapabilityStream(
   caller: CapabilityCaller,
   body?: BodyInit,
 ): Promise<Response> {
-  if (caller.mandate) throw new Error("Capability streams do not support background mandates yet");
+  if (caller.mandate || caller.workload) throw new Error("Capability streams require request authority");
   const path = `/api/capabilities/v1/streams/${verb}`;
   const headers = new Headers();
   headers.set("x-cloud-stream-id", stream.id);
@@ -172,6 +181,8 @@ export {
   listCalendarSources,
   readCalendarEvents,
 } from "./calendar-sources";
+export { type DiscussionProvider, discussionProviders } from "./discussion-providers";
+export { type ResourceReadersResult, readResourcePrincipals } from "./resource-readers";
 export {
   actionReview,
   type CapabilityReviewForms,

package/src/capabilities/testing.ts

@@ -14,6 +14,8 @@ import {
   type CapabilityResult,
   CapabilitySemanticLinkSchema,
   type CapabilitySlot,
+  CloudResourceReaderViewSchema,
+  type CloudResourceRef,
 } from "../contracts/capabilities";
 
 /** Compile and validate the public manifest an app would register at startup. */
@@ -36,6 +38,17 @@ export const assertResourceOpenLink = (result: Pick<CapabilityResult<unknown>, "
   return CapabilitySemanticLinkSchema.parse(link);
 };
 
+/** Assert the canonical reader presentation and, for contained types, its exact container. */
+export const assertResourceView = (result: Pick<CapabilityResult<unknown>, "data">, container?: CloudResourceRef) => {
+  const data = result.data;
+  const view = CloudResourceReaderViewSchema.parse(
+    data !== null && typeof data === "object" ? Object.getOwnPropertyDescriptor(data, "view")?.value : undefined,
+  );
+  if (container && (view.container?.ref.type !== container.type || view.container.ref.id !== container.id))
+    throw new Error("Resource reader view must identify the expected container");
+  return view;
+};
+
 /** Validate each localized review in application tests, with optional declaration context. */
 export const assertCapabilityReview = (review: unknown, context?: CapabilityReviewContext): void => {
   const parsed = CapabilityActionReviewDataSchema.safeParse(review);